# 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):

Source | Path | Scope
--- | --- | ---
Bundled | Ships with Clew | All users
User | `~/.claude/skills/<name>/SKILL.md` | Personal
Project | `.claude/skills/<name>/SKILL.md` | Team (in-repo)
Plugin | Inside plugin directories | Plugin users

## 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.

Skills vs. Plugins Skills are instruction-only (markdown), no code required. Plugins provide executable JavaScript — commands, hooks, agents, MCP servers. Use skills to standardize AI behavior; use plugins for custom tooling.