skill-development

What this skill does

# Skill Development for Claude Code Plugins

This skill provides guidance for creating effective skills for Claude Code plugins.

## About Skills

Skills are modular, self-contained packages that extend Claude's capabilities by providing
specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific
domains or tasks—they transform Claude from a general-purpose agent into a specialized agent
equipped with procedural knowledge that no model can fully possess.

### Skill Precedence

When multiple skills share the same name, precedence determines which loads:

1. Enterprise (managed settings) — highest priority
2. Personal (`~/.claude/skills/`)
3. Project (`.claude/skills/`)
4. Plugin skills — lowest priority

Plugin developers should use distinctive, ideally namespaced names (the plugin system auto-namespaces as `plugin-name:skill-name`) to avoid collisions with user or project skills.

### Skills and Commands: Unified Mechanism

Skills and commands share the same underlying mechanism (Skill tool). The choice depends on complexity needs:

- **Use commands** (`commands/foo.md`): Simple prompts without bundled resources
- **Use skills** (`skills/foo/SKILL.md`): Complex workflows needing scripts, references, or examples

Both support `$ARGUMENTS`, `[BANG]` bash execution, and frontmatter fields. Skills add bundled resources and progressive disclosure.

### What Skills Provide

1. Specialized workflows - Multi-step procedures for specific domains
2. Tool integrations - Instructions for working with specific file formats or APIs
3. Domain expertise - Company-specific knowledge, schemas, business logic
4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks
5. Visual output generation - Scripts that produce HTML/interactive visualizations

### Anatomy of a Skill

Every skill consists of a required SKILL.md file and optional bundled resources:

```
skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)
```

#### SKILL.md (required)

**Metadata Quality:** The `name` and `description` in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. "This skill should be used when..." instead of "Use this skill when...").

#### Optional Frontmatter Fields

##### allowed-tools

Optionally restrict which tools Claude can use when the skill is active:

```yaml
---
name: code-reviewer
description: Review code for best practices...
allowed-tools: Read, Grep, Glob
---
```

Use `allowed-tools` for:

- Read-only skills that shouldn't modify files
- Security-sensitive workflows
- Skills with limited scope

When specified, Claude can only use the listed tools without needing permission. If omitted, Claude follows the standard permission model.

##### context

Control how the skill's context is loaded:

```yaml
---
name: analysis-skill
description: Perform deep code analysis...
context: fork
---
```

**Values:**

- `fork` - Run skill in a subagent (separate context), preserving main agent's context
- Not specified - Run in main agent's context (default)

Use `context: fork` for:

- Skills that load large reference files
- Skills that might pollute the main context
- Expensive operations you want isolated

##### agent

Specify which agent type handles the skill when `context: fork` is set:

```yaml
---
name: exploration-skill
description: Explore codebase patterns...
context: fork
agent: Explore
---
```

**Values:**

- `Explore` - Fast agent for codebase exploration
- `Plan` - Architect agent for implementation planning
- `general` - General-purpose agent (default if `context: fork`)

Requires `context: fork` to be set.

##### skills

Load other skills into the forked agent's context:

```yaml
---
name: comprehensive-review
description: Full code review with testing...
context: fork
agent: general
skills:
  - testing-patterns
  - security-audit
---
```

Requires `context: fork` to be set. Only skills from the same plugin can be loaded.

##### user-invocable

Control whether the skill appears in the slash command menu:

```yaml
---
name: internal-review-standards
description: Apply internal code review standards...
user-invocable: false
---
```

**Default:** `true` (skills are visible in the `/` menu)

**Important:** This field only controls slash menu visibility. It does NOT affect:

- **Skill tool access** - Claude can still invoke the skill programmatically
- **Auto-discovery** - Claude still discovers and uses the skill based on context

Use `user-invocable: false` for skills that Claude should use automatically but users shouldn't invoke directly.

##### disable-model-invocation

Prevent Claude from programmatically invoking the skill via the Skill tool:

```yaml
---
name: dangerous-operation
description: Perform dangerous operation...
disable-model-invocation: true
---
```

**Default:** `false` (programmatic invocation allowed)

Use for skills that should only be manually invoked by users, such as:

- Destructive operations requiring human judgment
- Interactive workflows needing user input
- Approval processes

**Visibility comparison:**

| Setting                          | Slash Menu | Skill Tool | Auto-Discovery |
| -------------------------------- | ---------- | ---------- | -------------- |
| `user-invocable: true` (default) | Visible    | Allowed    | Yes            |
| `user-invocable: false`          | Hidden     | Allowed    | Yes            |
| `disable-model-invocation: true` | Visible    | Blocked    | Yes            |

##### model

Override which model handles the skill:

```yaml
---
name: quick-lint
description: Fast code linting checks...
model: haiku
---
```

**Values:** `sonnet`, `opus`, `haiku`, `inherit` (default), or a full model ID (e.g., `claude-sonnet-4-5-20250929`)

Use `haiku` for fast/cheap skills, `opus` for complex reasoning requiring maximum capability. Default behavior (`inherit`) uses the conversation's current model.

See `references/advanced-frontmatter.md` for detailed guidance on model selection.

##### hooks

Define scoped hooks that activate only when this skill is in use:

```yaml
---
name: secure-writer
description: Write files with validation...
hooks:
  PreToolUse:
    - matcher: Write
      hooks:
        - type: command
          command: "${CLAUDE_PLUGIN_ROOT}/scripts/validate-write.sh"
---
```

Scoped hooks follow the same event/matcher/hook structure as `hooks.json` but are lifecycle-bound to the skill. Supported events: `PreToolUse`, `PostToolUse`, `Stop`.

See `references/advanced-frontmatter.md` for full syntax and comparison with `hooks.json`.

##### argument-hint

Provides autocomplete hint text shown in the `/` menu for the skill's expected arguments:

```yaml
---
argument-hint: "<file-path> [--verbose]"
---
```

Purely cosmetic — helps users understand what arguments the skill expects. Does not affect argument parsing.

#### Bundled Resources (optional)

##### Scripts (`scripts/`)

Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.

- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed
- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks
- **Benefits**: Token efficient, deterministic, may be executed without loading into context

##### References (`references/`)

Documentation and reference material intended to be loaded as needed into context.

- **When to include**: For documentation that Claude should reference while working
- **Examples**: `references/s