Agent Skills

Agents use progressive disclosure to manage context. At startup, they only load the name and description from your SKILL.md frontmatter to decide if a skill is relevant. If a match is found, the agent then reads the full SKILL.md to follow its instructions.

Key Nuance: Agents typically only consult skills for tasks requiring specialized knowledge (unfamiliar APIs, domain-specific workflows, or uncommon formats) that go beyond their native capabilities. A simple request like "read this PDF" might not trigger a PDF skill if the agent can already handle it with its basic tools.

The Markdown body following the YAML frontmatter in SKILL.md contains the actual instructions for the agent. There are no strict format restrictions, but for effective agent performance, it is recommended to include:

• Step-by-step instructions
• Examples of inputs and outputs
• Common edge cases

Best Practices for Performance (Progressive Disclosure): Agents load skills in stages to manage context window usage:

1. Metadata: name and description are loaded at startup.
2. Instructions: The full SKILL.md body is loaded when the skill is activated. Keep this under 500 lines.
3. Resources: Files in scripts/, references/, or assets/ are loaded only when explicitly required by the instructions.

To keep the main instruction set concise, move detailed technical documentation into the references/ directory and link to them using relative paths.

Agent Skills use a progressive disclosure mechanism to manage context window usage. Instead of loading all information at once, agents interact with skills in three distinct stages:

1. Discovery: At startup, the agent only loads the name and description of each skill. This allows the agent to identify relevant skills without consuming significant context.
2. Activation: When a user task matches a skill's description, the agent reads the full content of the SKILL.md file into its context.
3. Execution: The agent follows the instructions provided in SKILL.md, which may involve executing code from the scripts/ directory or loading files from references/ or assets/.

Agent Skills are a lightweight, open format used to extend AI agent capabilities with specialized knowledge and workflows. A skill is represented as a directory containing a mandatory SKILL.md file, which provides the metadata and instructions necessary for an agent to perform a task. Skills can also bundle optional resources like scripts, reference materials, and assets.

Skill Directory Structure:

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

To keep context windows efficient, Agent Skills implementations should follow a three-tier progressive disclosure strategy. This ensures the model only consumes tokens for specialized knowledge when it is actually needed.

Workflow:

1. The model starts with the Catalog to understand available capabilities.
2. When a skill is relevant, the agent loads the full Instructions.
3. If the instructions require external files, the agent loads those Resources individually.

Match the level of prescriptiveness to the fragility of the task:

• Give the agent freedom for flexible tasks where multiple approaches work. Explain the why to help the agent make better context-dependent decisions.
• Be prescriptive for fragile operations or required sequences. Use exact commands and explicitly forbid modifications.
• Provide defaults, not menus: When multiple tools exist, pick a default and mention alternatives briefly as an escape hatch rather than presenting them as equal options.
• Favor procedures over declarations: Teach the agent how to approach a class of problems (a reusable method) rather than telling it exactly what to produce for one specific instance.

To maintain a small context footprint, agents use a progressive disclosure model to load skills in three distinct stages:

1. Discovery: At startup, the agent only loads the name and description of each skill to determine relevance.
2. Activation: When a task matches a skill's description, the agent reads the full content of SKILL.md into its context.
3. Execution: The agent follows the instructions, executing bundled code in scripts/ or loading files from references/ or assets/ as required.

This approach allows agents to have access to a vast library of skills without overwhelming their context window.

Agent Skills are a lightweight, open format for extending AI agent capabilities. A skill is represented as a directory containing a mandatory SKILL.md file, which provides the metadata and instructions necessary for an agent to perform a task. Skills can optionally include supporting files like scripts, documentation, or assets.

A typical skill directory structure looks like this:

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

Agent Skills operate using a pattern called progressive disclosure. This allows an agent to manage a large number of skills without overwhelming its context window. The lifecycle of a skill usage is:

1. Discovery: The agent scans default skill directories (like .agents/skills/) and reads only the name and description of each skill.
2. Activation: When a user's prompt matches a skill's description, the agent loads the full content of the SKILL.md body into its context.
3. Execution: The agent follows the instructions provided in the body (e.g., running a specific terminal command with substituted parameters) to complete the task.

To improve reliability, instruct the agent to validate its own work before proceeding. The recommended pattern is: perform the task, run a validator (such as a script, a reference checklist, or a self-check), fix any identified issues, and repeat until validation passes. You can also use a reference document as the validator by instructing the agent to check its work against it.

## Editing workflow

1. Make your edits
2. Run validation: `python scripts/validate.py output/`
3. If validation fails:
   - Review the error message
   - Fix the issues
   - Run validation again
4. Only proceed when validation passes