/skill

name: claude-code:skill
description: Creating and optimizing Claude Code Skills including activation patterns, content structure, and development workflows. Use when creating new skills, converting memory files to skills, debugging skill activation, or understanding skill architecture and best practices.
argument-hint: "[--validate] [--structure]"
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash
  - WebFetch(domain:docs.claude.com)
hooks:
  PostToolUse:
    - matcher: "Write|Edit"
      hooks:
        - type: command
          command: "bun ${CLAUDE_PLUGIN_ROOT}/skills/skill/scripts/check-namespace.ts"
        - type: command
          command: "bun ${CLAUDE_PLUGIN_ROOT}/skills/skill/scripts/check-structure.ts"
        - type: command
          command: "bun ${CLAUDE_PLUGIN_ROOT}/skills/skill/scripts/check-lint.ts"

Claude Code Skills Development

Reference for developing effective skills.

Arguments

Run a check against a skill path in `$ARGUMENTS`, defaulting to the skill you just edited:

• `--validate`: run `skill-lint` (see [Validation](#validation)) for frontmatter, naming, and reference-depth validation.
• `--structure`: run the directory-structure check (`${CLAUDE_SKILL_DIR}/scripts/check-structure.ts`) for the SKILL.md, `scripts/`, `references/`, `assets/` layout.

With neither flag, use the skill as an authoring reference. See [Validation](#validation).

Skill Structure

---
name: plugin-name:skill-name
description: Third-person capability description with trigger terms
argument-hint: "[--flag] [<positional>]"
allowed-tools: [Read, Grep, Glob]
model: sonnet
effort: low
context: fork
agent: Explore
background: false
user-invocable: false
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate.sh"
          once: true
---

Required Fields

• `name`: Lowercase letters, numbers, hyphens only (max 64 chars). See [Naming](#naming).
• `description`: Third-person, includes trigger terms and use cases (max 1024 chars).

Optional Fields

• `argument-hint`: Arguments the skill accepts, shown in the slash menu after the skill name. See [Argument Hints](#argument-hints).
• `allowed-tools`: Tools Claude can use without permission when skill is active
• `model`: Override the conversation's model. Prefer a tier alias (`haiku`, `sonnet`, `opus`, `fable`) or `inherit` over a dated model ID.
• `effort`: Reasoning effort while the skill is active. Pin `low` on mechanical skills such as monitoring, execution, and formatting. Defaults to the conversation's effort.
• `context`: Set to `fork` to run in isolated subagent context
• `agent`: Agent type when `context: fork` (`Explore`, `Plan`, `general-purpose`, or custom)
• `background`: Only with `context: fork`. `false` waits for the fork's result in the invoking turn instead of backgrounding it. Default `true`.
• `user-invocable`: Hide from slash menu when `false` (default: `true`)
• `disable-model-invocation`: Block model (Skill-tool) invocation and drop the skill's name and description from the always-on catalog (zero recurring context cost); still slash-invocable. Opposite of `user-invocable: false`, which hides the slash menu but keeps the description loaded for the model.
• `hooks`: Skill-scoped hooks (`PreToolUse`, `PostToolUse`, `Stop`)

Naming

Plugin skills use `plugin-name:skill-name` with a colon namespace (e.g., `gitlab:ci`, `things:url`). The part after the colon should not repeat the plugin name. Skip the prefix when name equals plugin name. For standalone skills, use gerund form (verb + -ing): `processing-pdfs`, `analyzing-data`. Avoid vague names like `helper`, `utils`.

Storage

`~/.claude/skills/` (personal), `.claude/skills/` (project), plugins (bundled)

Skill Authoring Best Practices

Descriptions

The description field is a trigger, not a summary. It's what Claude scans to decide whether to activate the skill. Write it for the model: trigger terms, use cases, and "Use when..." phrasing. Make it slightly pushy to combat under-triggering.

Skip the Obvious

The context window is a public good. Don't restate what Claude already knows. Spend tokens on what pushes Claude out of its defaults: gotchas, internal conventions, non-obvious constraints. The highest-signal content in any skill is a `## Gotchas` section documenting failure modes hit in practice; grow it as edge cases surface.

Progressive Disclosure

A skill is a folder, not just a markdown file. Keep `SKILL.md` a concise hub and push details into `references/`, `scripts/`, and `assets/`. Tell Claude what files exist and when to read them. Organize references by domain and gate conditional detail behind a pointer, so a question about one domain loads only that file.

Don't Railroad Claude

State the goal and constraints, then leave room to adapt. Prefer outcome-oriented instructions over step-by-step scripts.

First-Run Setup

Skills that depend on user-specific context should check for a `config.json` in `${CLAUDE_SKILL_DIR}` or `${CLAUDE_PLUGIN_DATA}`. If missing, prompt the user for setup and store answers for future runs.

Store Persistent Data in `${CLAUDE_PLUGIN_DATA}`

Skills can maintain state across runs: append-only logs, JSON records, SQLite databases. Use `${CLAUDE_PLUGIN_DATA}` for storage that survives plugin upgrades.

Give Claude Code to Compose

Include helper scripts and libraries that Claude can import and compose on the fly. Document scripts with `"Run script.py"` (execute) vs `"See script.py"` (reference).

On-Demand Hooks

Skill-scoped hooks activate only when the skill is invoked and last for the session. Use these for guardrails that would be annoying globally but valuable in specific contexts (e.g., blocking destructive commands during prod operations).

Content Features

String Substitutions

| Variable | Description