claude-code:skill

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

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.
• 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.
• 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)