---

description: "Best practices for authoring Agent Skill SKILL.md files" paths: ["**/SKILL.md"]

<!-- Generated by SharedVSCode .ai/tools/Render-AIAdapters.ps1. Do not edit this adapter directly; edit the canonical source or record an overlay in the manifest. SourceId: ai.instruction.skill.v1 Source: .ai/instructions/skill.instructions.md SourceSha256: 66b24503fed6b2c7d92f731741a1d94353b4e5768809f64a7d9a7d263c8f0cd5 Materialization: generated-wrapper -->

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:

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:

---
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:

[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:

# 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 — 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 — authoritative capture of Anthropic's Skill authoring best practices docs page (the parseable cross-check).
• 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 https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf; docs reference https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices. 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.