Skills

Skills are reusable prompt-type commands — markdown files that provide structured instructions to the AI model. They are loaded from bundled, user, project, and plugin directories.

Overview

Skills are commands of type prompt — they expand to text that is sent to the model. Unlike plugins (which provide JavaScript code), skills are purely instructional. They bridge the gap between ad-hoc prompts and full plugin development.

Skill Locations

Skills are loaded from four sources (order: bundled user project plugin):

Skill Structure

my-skill/
  SKILL.md              # Skill instructions (required)
  assets/               # Optional: scripts, references, examples

The SKILL.md file uses frontmatter for metadata and markdown for instructions. Skills are registered as prompt-type commands and can be invoked by the model via the SkillTool.

Managing Skills

/skill            # List available skills or show skill details
/skills           # List available skills
/skill-name       # Invoke a specific skill directly

Skill Frontmatter

Skills support YAML frontmatter for metadata and configuration:

---
name: my-skill
description: Does focused text work
allowed-tools:
  - Read
  - Grep
disallowed-tools:
  - Bash
  - Edit
hooks:
  PreToolUse:
    - matcher: Bash
      hooks:
        - type: command
          command: echo "About to run bash"
model: claude-sonnet-4-6
effort: high
user-invocable: true
context: fork
---

Key frontmatter fields:

• allowed-tools — Restrict which tools the model can use while this skill is active
• disallowed-tools — Explicitly block tools (e.g., Bash, Edit) for read-only skills
• hooks — Register PreToolUse, PostToolUse, or MessageDisplay hooks for the skill
• model — Override the model used when this skill runs
• effort — Set effort level (low, medium, high, xhigh, max)
• context — inline (default) expands into current conversation; fork runs as sub-agent

Creating a Skill

mkdir -p ~/.claude/skills/my-skill
touch ~/.claude/skills/my-skill/SKILL.md
# Edit SKILL.md with frontmatter and instructions

Or use the skillify plugin to create a skill from an existing workflow.

Project-Level Skills

Place skills in .claude/skills/ inside your repository to share with your team:

.claude/
  skills/
    code-review/
      SKILL.md
    migration-workflow/
      SKILL.md

Project skills are automatically available to everyone working in the repository.

Dynamic Skills

Skills can be discovered dynamically during file operations. When a skill file is created or modified, it's automatically added to the available command list without restarting. Use clearCommandMemoizationCaches() to refresh the skill index.