--- description: "Best practices for authoring Agent Skill SKILL.md files" paths: ["**/SKILL.md"] --- # AI instructions for authoring SKILL.md files Apply these rules whenever creating or editing a `SKILL.md` file (a Claude/Codex/Copilot/ Antigravity Agent Skill). They distill Anthropic's *The Complete Guide to Building Skills for Claude* and the official *Skill authoring best practices*. Full source material and reasoning are preserved in `skill-references/` (see the end of this file). --- ## Skill anatomy A skill is a folder, not a single file: ```text your-skill-name/ ├── SKILL.md # REQUIRED — Markdown body + YAML frontmatter ├── scripts/ # optional — executable code; executed, not loaded into context ├── references/ # optional — docs loaded only when needed └── assets/ # optional — templates, fonts, icons used in output ``` - The main file must be named **exactly `SKILL.md`** (case-sensitive). - **No `README.md` inside the skill folder** — all docs live in `SKILL.md` or `references/`. A repo-level README for humans is separate and fine. - Folder name uses **kebab-case** (no spaces, underscores, or capitals) and **should match the `name` field**. --- ## Progressive disclosure — the three-level model 1. **Level 1 — YAML frontmatter (`name` + `description`):** always pre-loaded into the system prompt for every skill. Just enough for Claude to decide whether to load the skill. Keep it tight — it always competes for context. 2. **Level 2 — SKILL.md body:** loaded only when Claude judges the skill relevant. Contains the full instructions. 3. **Level 3 — linked files (`references/`, `scripts/`, `assets/`):** read or executed only as needed. No context cost until accessed. Practical limits: - Keep the **SKILL.md body under 500 lines** (the PDF phrases this as under 5,000 words). Split into `references/` when approaching the limit. - **Keep references one level deep** from SKILL.md. Claude may only partially read (`head -100`) files reached through chains of references. - For any reference file **longer than 100 lines, add a table of contents** at the top. - Make execution intent explicit: *"Run `analyze.py` ..."* (execute) vs. *"See `analyze.py` for the algorithm"* (read as reference). Prefer execution for deterministic work. --- ## YAML frontmatter rules | Field | Required | Rules | | --- | --- | --- | | `name` | Yes | kebab-case; lowercase letters/numbers/hyphens only; **max 64 characters**; no XML tags; must not contain reserved words `anthropic` or `claude`; should match the folder name. | | `description` | Yes | Non-empty; **max 1024 characters**; **must state BOTH what the skill does AND when to use it**; third person; no XML tags; include specific trigger phrases and relevant file types. | | `license` | Optional | For open-source skills (e.g. `MIT`, `Apache-2.0`). | | `compatibility` | Optional | 1–500 chars; environment requirements (intended product, packages, network needs). | | `allowed-tools` | Optional | **Restricts tool access (least privilege).** Example: `allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch"`. | | `metadata` | Optional | Custom key/value. Suggested: `author`, `version`, `mcp-server`, `category`, `tags`, `documentation`, `support`. | Security: frontmatter is injected into the system prompt — **never use XML angle brackets (`<` `>`) anywhere in it**, and never name a skill with `claude`/`anthropic`. Use safe YAML only (no executable content). Minimal valid frontmatter: ```yaml --- name: your-skill-name description: What it does. Use when the user asks to [specific phrases]. --- ``` --- ## Writing the `description` (highest-leverage field) This is the only Level-1 cue Claude uses to pick the skill from 100+ candidates. Structure: ```text [What it does] + [When to use it] + [Key capabilities / trigger phrases] ``` - Write in **third person** ("Processes Excel files...", not "I can help you..."). - Include the **specific phrases users would actually type** and relevant **file types**. - Add **negative triggers** when a skill over-fires (e.g. *"Do NOT use for simple data exploration; use the data-viz skill instead."*). Good vs. bad: ```yaml # Good — specific, includes triggers description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files. # Bad — vague, no triggers description: Helps with documents ``` Debugging tip: ask Claude *"When would you use the [skill] skill?"* — it quotes the description back, exposing what is missing. --- ## Writing the instructions (SKILL.md body) - **Be specific and actionable.** Good: *"Run `python scripts/validate.py --input {filename}` to check format."* Bad: *"Validate the data before proceeding."* - **Match degrees of freedom to fragility:** prose steps when many approaches work; parameterized scripts when a preferred pattern exists; exact, do-not-modify commands when consistency is critical. - **Put critical instructions at the top**; use `## Important` / `## Critical` headers; repeat key points if needed. - **Use consistent terminology** — choose one term and keep it. - **Avoid time-sensitive info**; move deprecated guidance to a collapsed "Old patterns" section. - Provide **workflows as checklists** for multi-step tasks, and **feedback loops** (validate → fix → repeat) for quality-critical work. - **Avoid offering too many options** — give one default with an escape hatch. - For bundled scripts: **solve, don't punt** (handle errors), **no voodoo constants** (justify magic numbers), **forward slashes only** (no Windows paths), and use **fully-qualified MCP tool names** `ServerName:tool_name`. --- ## Tool-surface minimization (least privilege) Use the optional **`allowed-tools`** frontmatter field as a whitelist restricting which tools the skill may use. For each skill, ask: - Which tools does the skill actually invoke in its instructions/scripts? - Does it need write access? To which paths? - Does it need network access? (Usually no.) Drop every grant the skill does not exercise, and document the rationale. Granularity includes scoped Bash patterns (e.g. `Bash(python:*)` permits Python but not arbitrary shell). Reconcile with this repo's `SolutionDocumentation/AI-Agent-Tool-Surface-Audit.md` and `Agent-Permission-Model.md` for how the workspace enforces grants. --- ## Testing and iteration - **Build evaluations first** (≥ 3 scenarios): baseline Claude without the skill, then write the minimum instructions to pass. - Test three areas: **triggering** (fires on obvious + paraphrased tasks; does NOT fire on unrelated topics — aspirational target: triggers on 90% of relevant queries), **functional** (correct outputs, error handling, edge cases), and **performance** (fewer tool calls/tokens vs. a no-skill baseline). - **Test with Haiku, Sonnet, and Opus.** - Iterate with two Claudes: one authors/refines, a fresh instance uses it; feed observed gaps back. Under-triggering → enrich the description with keywords; over-triggering → add negative triggers and tighten scope. --- ## Anti-patterns (audit failure signals) - Vague description ("Helps with projects") → skill never loads. - Frontmatter errors: missing `---` delimiters, unclosed quotes, spaces/capitals in `name`, any `<`/`>` characters. - Overstuffed or buried instructions → instructions ignored. - Deeply nested references (links to links) → incomplete reads. - Windows-style backslash paths. - Too many tool grants / scope creep. - A `README.md` inside the skill folder. - More than ~20–50 skills enabled at once (context risk). --- ## Condensed checklist (apply per skill) - [ ] Folder is kebab-case and matches `name`; `SKILL.md` exact spelling; no in-folder `README.md`. - [ ] Frontmatter has `---` delimiters; no `<`/`>`; `name` ≤ 64 chars, no reserved words. - [ ] `description` ≤ 1024 chars, third person, states what + when, includes trigger phrases and file types. - [ ] SKILL.md body < 500 lines / 5,000 words; detail pushed to `references/`. - [ ] References one level deep; reference files > 100 lines have a TOC. - [ ] Instructions specific/actionable; critical steps first; consistent terminology. - [ ] Workflows have steps; quality-critical paths have validate → fix loops. - [ ] Scripts handle errors, justify constants, use forward slashes, fully-qualified MCP names. - [ ] `allowed-tools` restricted to the minimum the skill uses; rationale documented. - [ ] Triggering / functional / performance checks pass; ≥ 3 evaluations exist. --- ## Source material and preserved reasoning These bundled references hold the full reasoning behind this rule so it is not lost and is available to future agents. They are kept one level deep, per the guide's own rule: - [`skill-references/skill-building-guide-summary.md`](skill-references/skill-building-guide-summary.md) — the full rubric/summary head-start (mirrors `SolutionDocumentation/SC-0215-Skill-Authoring-Best-Practices-Summary.md`), with the SC-0215 work-unit mapping. - [`skill-references/anthropic-skill-best-practices-doc.md`](skill-references/anthropic-skill-best-practices-doc.md) — authoritative capture of Anthropic's *Skill authoring best practices* docs page (the parseable cross-check). - [`skill-references/anthropic-skill-guide-extracted-text.txt`](skill-references/anthropic-skill-guide-extracted-text.txt) — raw `pdftotext` extraction of the original PDF *The Complete Guide to Building Skills for Claude* (primary source). > Provenance: PDF reference > ; > docs reference > . > Captured 2026-06-23 for scope-creep item SC-0215. > Pending activation (tracked by SC-0217): this canonical source is registered in > `manifests/instruction-map.json` as a pre-render record (kind ToolInstruction, four > pending targets) but is not yet rendered through `Render-AIAdapters` to the four callers > (Claude `.claude/Rules`, Copilot, Codex, Antigravity). Until rendered, agents should read > this `.ai` source directly. Render must go through the governed pipeline with > `-UpdateManifest` (do not hand-edit rendered hashes). > Closure marker: the next planned step is a SprintEnd -> SprintStart cycle that > re-materializes all adapter files. Once the `skill` record is registered in the > instruction map (the gating prerequisite — the renderer is manifest-driven), this > instruction is considered CLOSED when, after that cycle, it is present in its caller > adapters (e.g. `.claude/Rules/skill.md`) and `Test-AIAdapterDrift -Domain instructions` > reports zero drift and zero missing for it.