agent-skills-authoring

Agent Skills Authoring Guide

This is your authoritative reference for producing high-quality SKILL.md files. When a user asks you to create, edit, or improve a skill, follow these instructions to produce the best possible result — one that any consuming agent can discover, activate, and apply effectively.

1. Core Principles

These principles come from Anthropic's official best practices. Apply them to every skill.

Claude is already very smart. Only add context Claude doesn't already have. Challenge each piece of content: "Does Claude really need this explanation?" "Can I assume Claude knows this?" "Does this paragraph justify its token cost?" Concise skills perform better because the context window is shared with conversation history, system prompts, and other skills' metadata.

Explain WHY, not just WHAT. Anthropic's guidance: "Explain to the model why things are important in lieu of heavy-handed musty MUSTs." When agents understand reasoning, they generalize correctly across novel situations. Rigid imperative-only rules cause brittle, over-literal behavior.

Match specificity to fragility. Use high freedom (general text guidance) when multiple approaches are valid. Use medium freedom (pseudocode/parameterized scripts) when a preferred pattern exists. Use low freedom (exact scripts, no modifications) when operations are fragile and consistency is critical. Think of it as: narrow bridge (one safe path, give exact steps) vs. open field (many valid routes, give direction and trust the agent).

Use consistent terminology. Pick one term and use it throughout. Don't mix "API endpoint" / "URL" / "path" or "extract" / "pull" / "get" / "retrieve" in the same skill.

2. Directory Structure

skill-name/
├── SKILL.md          # REQUIRED — frontmatter + instructions
├── scripts/          # Optional — executable code (runs without loading into context)
│   └── validate.py
├── references/       # Optional — docs loaded on demand
│   ├── REFERENCE.md
│   └── domain.md
└── assets/           # Optional — templates, data files, schemas
    └── template.json

• Directory name must match the name field in frontmatter exactly
• scripts/ — self-contained executables. Handle errors explicitly ("solve, don't punt").

Scripts execute via bash and only their output enters context, not their code

• references/ — additional docs loaded on demand. Keep files focused. Add a table of

contents at the top of any reference file over 100 lines

• assets/ — static resources: templates, configuration files, schemas, lookup tables
• Use forward slashes in all paths, even on Windows: scripts/validate.py not scripts\validate.py

Domain organization: For skills supporting multiple variants, split into references:

cloud-deploy/
├── SKILL.md           # Overview + variant selection
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

The agent loads only the relevant reference, saving context.

3. YAML Frontmatter — Complete Field Reference

Base Spec Fields (agentskills.io)

The open standard defines exactly six fields:

name (REQUIRED)

Unique identifier. 1–64 chars. Lowercase alphanumeric + hyphens only. No leading/trailing/consecutive hyphens. No XML tags. Cannot contain reserved words "anthropic" or "claude". Must match the parent directory name.

Prefer gerund naming (verb + -ing): processing-pdfs, analyzing-spreadsheets, testing-code. Also acceptable: noun phrases (pdf-processing) or action-oriented (process-pdfs). Avoid vague names (helper, utils, tools).

name: processing-pdfs

description (REQUIRED)

Natural-language summary. 1–1,024 chars. Plain text only. No XML tags. This is the primary triggering mechanism — agents use it to decide which skills to load.

Always write in third person. "Processes Excel files..." not "I can help you..." or "You can use this..." (inconsistent POV causes discovery problems).

Make descriptions slightly "pushy." Claude tends to undertrigger skills. Include both what the skill does AND specific trigger contexts. List keywords users would say. Add "even if they don't explicitly ask for X" where appropriate.

description: >-
  Extracts text and tables from PDF files, fills forms, and merges documents.
  Use when working with PDF files or when the user mentions PDFs, forms, or
  document extraction, even if they don't explicitly ask for "PDF processing."

license (OPTIONAL)

SPDX identifier or bundled file reference. Omit if unknown.

compatibility (OPTIONAL)

Environment requirements. 1–500 chars. Plain text. Only include if the skill has genuine requirements — most skills don't need this field.

metadata (OPTIONAL)

String key-value map. Use reasonably unique key names to avoid collisions.

metadata:
  author: "your-org"
  version: "1.0"
  category: "document-processing"

allowed-tools (OPTIONAL, EXPERIMENTAL)

Space-delimited list. Use scoped format where the platform supports it.

allowed-tools: Bash(git:*) Bash(jq:*) Read Write

Claude Code Extended Fields

Claude Code extends the open standard with additional fields. These are platform-specific and not part of the base agentskills.io spec:

| Field | Purpose | | -------------------------- | ------------------------------------------------------------ | | argument-hint | Autocomplete hint: [issue-number] or [filename] [format] | | disable-model-invocation | true to prevent auto-loading (manual /name only) | | user-invocable | false to hide from / menu (background knowledge skills) | | model | Model override when this skill is active | | context | fork to run in a forked subagent context | | agent | Subagent type to use when context: fork is set | | hooks | Hooks scoped to this skill's lifecycle |

In Claude Code, name falls back to directory name if omitted, and description falls back to the first paragraph of the markdown body.

4. Body Content

Everything after the closing --- is free-form Markdown. Keep the body under 500 lines. If approaching this limit, move detail into references/ and add clear pointers.

Recommended Structure

# [Skill Name]

[1-3 sentence overview]

## When to use this skill

[Trigger conditions — what user requests or contexts activate this]

## How to [primary action]

[Step-by-step instructions]

## Examples

[Input/output pairs]

## Common edge cases

[Boundary conditions and handling]

## Guidelines

[Key principles with reasoning]

Progressive Disclosure

| Level | Content | Budget | When Loaded | | ----- | -------------------------------- | ------------------------- | -------------------------- | | 1 | Frontmatter (name + description) | ~100 tokens | Always — at agent startup | | 2 | SKILL.md body | < 500 lines / < 5K tokens | When skill activates | | 3 | scripts/, references/, assets/ | Unlimited | On demand during execution |

Level 3 scripts execute without loading into context — only their output enters the context window. Reference files are read on demand. This means you can bundle comprehensive resources with no context penalty until they're accessed.

File References

Use standard Markdown links with relative paths:

See [the reference guide](references/REFERENCE.md) for detailed API documentation.
Run the extraction script: `python scripts/extract.py`
For TypeScript specifics, see [TypeScript patterns](references/typescript.md).

Keep references one level deep from SKILL.md