Document Skills

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/<name>/). 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").

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

For injecting shell output before the skill runs, see Inject dynamic context.

3. Checklist when writing or updating

1. Frontmatter: description follows [What it does] + [When to use it] + [Key capabilities] and is specific (include phrases users might say, e.g. "Use when user says save, /save"). name matches the skill. Task or side-effect skills: disable-model-invocation: true per official docs.
2. Sections: Inputs, Output, Process, then optionally Examples and Troubleshooting, then Reference. Same order as other skills.
3. Length: Under 500 lines; long reference in other files, linked from SKILL.md.
4. Supporting files: If used, say so in SKILL.md and when to load them. Keep SKILL.md focused; put long or detailed docs in references/ and link (progressive disclosure).
5. Arguments: Use $ARGUMENTS or $N and optionally argument-hint if the skill takes input.
6. Invocation: Use disable-model-invocation and/or user-invocable so the skill runs when intended (see Control who invokes a skill).

4. Steps to run

1. Read the target skill path and any source.
2. Apply the checklist and structure above. Don't change behavior unless the user asked.
3. Write or update SKILL.md (and supporting files if needed). Only document what the skill does; don't add capabilities that aren't there.

Examples

User says: "Create a skill for validating CSV uploads."

Actions: Create folder skills/validate-csv/ (or the project's skill path; kebab-case). Add SKILL.md with required frontmatter (name: validate-csv, description using [What it does] + [When to use it] + [Key capabilities], e.g. "Validate CSV uploads. Use when user says validate CSV, check upload, /validate-csv. Key capabilities: schema check, encoding detection."). Add Inputs, Output, Process, optional Reference. If the skill runs a script, add scripts/validate.sh and reference it in Process.

Result: New skill that triggers on the stated phrases; coordinator and flows updated if it is part of a flow.

User says: "Update the save skill to mention update-gitignore."

Actions: Open the save skill's SKILL.md (e.g. skills/save/SKILL.md). Add the new step or reference in Process. Update description if trigger phrases change. Sync coordinator and references/coordinator-flows.md if the Save flow changes.

Troubleshooting

Invalid frontmatter / upload error.
Cause: YAML formatting (missing --- delimiters, unclosed quotes, or colons in a value read as a new key).
Solution: Ensure frontmatter is between two --- lines. Avoid colons in description text; use "Use when" not "When:". No < or > in frontmatter.

Skill doesn't trigger.
Cause: Description too vague or missing the full formula (what it does, when to use it, key capabilities) or trigger phrases.
Solution: Use [What it does] + [When to use it] + [Key capabilities] and add specific "Use when user says X, Y, /skill-name". Same phrases should appear in coordinator flow table if the skill is part of a flow. Debug: Ask the assistant "When would you use the [skill name] skill?" and adjust the description from what’s missing.

Skill triggers too often.
Cause: Description too broad or overlapping with other skills.
Solution: Add negative triggers (e.g. "Do NOT use for simple data exploration; use data-viz skill instead"). Narrow scope (e.g. "PDF legal documents for contract review" instead of "Processes documents"). Clarify when not to use (e.g. "Use specifically for online payment workflows, not general financial queries").

Wrong folder name.
Cause: Folder has spaces, underscores, or capitals.
Solution: Rename to kebab-case. Update name in SKILL.md to match. Update all references (coordinator, agents, README, package.json, checklist script, agents/references/).

After writing

• Coordinator sync: If you changed the description (e.g. "when to use" or key capabilities that match user requests), update the coordinator agent and the flow steps in references/coordinator-flows.md if the skill is part of a flow, so the flow table and agent descriptions stay in sync.
• Rename/move: If a skill was renamed or moved (e.g. generate-figma → designer-figma), update all references: coordinator, agents, README, package.json, other skills that link to it, verify-task checklist script, agents/references/ (e.g. coordinator-flows.md if the skill appears in a flow), and .gitignore.

Reference

Official skills reference – frontmatter, control who invokes a skill, run in subagent, substitutions. Coordinator – Flow table and agent descriptions should follow [What it does] + [When to use it] + [Key capabilities] and match the phrases users say.

Complete guide to building skills – progressive disclosure, description formula, good/bad examples, optional frontmatter, triggering and troubleshooting, instructions best practices.