--- name: document-skills description: Write or update a skill (SKILL.md and supporting files) to match host structure and best practices. Use when user says create skill, write skill, update SKILL.md, /document-skills. disable-model-invocation: true argument-hint: "[skill-path] [source]" context: fork agent: general-purpose ---

Document Skills

Write or update a skill to fit the host's expected structure. Use the structure and checklist below.

Inputs

1. Target skill – Path to the skill folder (e.g. the project skills directory skills/example/) or the skill name.
2. Source – Draft, user instructions, or notes to turn into the skill or merge in.

If you don't give either: Use the current or given context (e.g. the skill or path already under discussion).

Output

SKILL.md updated (and supporting files if needed).

Process

1. Skill layout

• One folder per skill. The main file is always SKILL.md (exact name, case-sensitive).
• Folder name: Must be kebab-case (lowercase, hyphens; no spaces, underscores, or capitals). The frontmatter name must match the folder name.
• Where skills live: In a project, typically a dedicated skills directory (e.g. skills//). The host discovers skills from this location even when it's nested (e.g. inside a package).
• Optional subfolders only: Use scripts/ (executable code), references/ (documentation loaded as needed), and assets/ (templates, icons, etc.). Do not put README.md inside the skill folder; all documentation goes in SKILL.md or references/. Long reference material goes in references/ and is linked from SKILL.md (progressive disclosure).
• Length: Keep SKILL.md under ~5,000 words. Long reference in references/, linked from SKILL.md.
• Progressive disclosure: Skills use three levels — (1) YAML frontmatter is always loaded so the assistant knows when to use the skill; (2) SKILL.md body is loaded when the skill is relevant; (3) files in references/ or assets/ are opened only as needed. This keeps token use down while keeping expertise available.
• Composability: Skills can load together. Write the skill so it works alongside others; don't assume it's the only one active.

2. SKILL.md format

Frontmatter (the YAML block between the first --- lines)

Frontmatter configures when and how the skill runs. The table below follows the official skills reference.

name and description are required. name must match the folder name (kebab-case). description should follow: [What it does] + [When to use it] + [Key capabilities] — under 1024 characters; no XML angle brackets (< >). Avoid vague lines like "Helps with projects"; include specific trigger phrases and, if relevant, file types (e.g. ".fig files", "PDF contract review").

| Field | Required | Description | | :------------------------- | :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- | | name | Yes | kebab-case only; must match skill folder name. Lowercase letters, numbers, and hyphens (max 64 characters). | | description | Yes | [What it does] + [When to use it] + [Key capabilities]. Include trigger phrases (e.g. "Use when user says save, /save"). Mention file types if relevant. Under 1024 characters. No < or >. | | argument-hint | No | Hint shown during autocomplete to indicate expected arguments. Example: [issue-number] or [filename] [format]. | | disable-model-invocation | No | Set to true to disable automatic loading; use for workflows you want to trigger manually with /name. Default: false. | | user-invocable | No | Set to false to hide from the / menu. Use for background knowledge users shouldn't invoke directly. Default: true. | | allowed-tools | No | Tools the assistant can use without asking permission when this skill is active. | | model | No | Model to use when this skill is active. | | context | No | Set to fork to run in a forked subagent context. | | agent | No | Which subagent type to use when context: fork is set. | | hooks | No | Hooks scoped to this skill's lifecycle. See Hooks in skills and agents for configuration format. |

Optional: license (e.g. MIT for open source), compatibility (1–500 chars: product, system deps, network), metadata (e.g. author, version, mcp-server). See complete skills guide.

Security: No XML angle brackets in frontmatter. Avoid reserved names in the skill name (e.g. host or vendor names).

YAML gotcha: Avoid colons inside a value. They can be read as a new key. Use something like "Scope is" instead of "Scope:" in the text.

Content type

• Reference content – Conventions, patterns, style. The assistant applies it inline to your current work. No invocation control needed.
• Task content – Step-by-step instructions for a specific action (deploy, commit, code generation). Often invoked directly with /skill-name. Use disable-model-invocation: true so the skill is not auto-loaded.

Body sections (same order for every skill)

Use the same section order so skills are easy to scan:

1. # Title – Skill name as H1, then one short intro (what it does).
2. ## Inputs – What the skill needs (user input, paths, options). Number the items. Use "None" or "Optional" when nothing is required.
3. ## Output – What you get (a file, a behavior, a handoff). One short block.
4. ## Process – How to do it. Numbered steps or subsections (e.g. "### 1. Step name"). Put all how-to and rules here. Be specific and actionable (e.g. "Run python scripts/validate.py --input {filename}" not "Validate the data"). Include error handling for common failures; reference bundled files (e.g. "Before queries, consult references/api-patterns.md") when relevant.
5. ## Examples – Optional but recommended. Common scenarios: "User says X → Actions → Result."
6. ## Troubleshooting – Optional but recommended. Error or symptom → Cause → Solution.
7. ## Reference – Optional. Links to related skills or docs.

Skip a section only if it really doesn't apply. When unsure, include Inputs, Output, Process, and Reference; add Examples and Troubleshooting where they help. Match the layout of other skills in the repo.

Substitutions (in the body text)

From the official docs:

• $ARGUMENTS – All arguments passed when invoking the skill. If not present in the content, arguments are appended as ARGUMENTS: .
• $ARGUMENTS[N] or $N – The Nth argument (0-based index).
• ${CLAUDE_SESSION_ID} – The current session ID (host-defined).
• ${CLAUDE_SKILL_DIR} – The directory containing the skill's SKILL.md file (host-defined).

...