Agent Skills

Product summary

Agent Skills is a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows. Skills are directories containing a SKILL.md file (YAML frontmatter + Markdown instructions) plus optional supporting files (scripts, references, assets). Use the skills-ref CLI to validate skills and generate prompt XML for agent integration. Primary documentation: https://agentskills.io

When to use

Reach for this skill when:

• Creating a new skill: You need to package domain expertise, repeatable workflows, or new agent capabilities into a reusable format
• Validating skills: You're checking that a skill's SKILL.md file meets format requirements before deployment
• Integrating skills into agents: You're setting up skill discovery, loading metadata, or injecting skills into agent system prompts
• Authoring instructions: You're writing the Markdown body of a skill to guide agent behavior
• Managing skill resources: You're organizing scripts, templates, reference files, or assets alongside skill instructions

Quick reference

SKILL.md frontmatter (required fields)

SKILL.md optional frontmatter fields

Directory structure

skill-name/
├── SKILL.md              # Required: frontmatter + instructions
├── scripts/              # Optional: executable code
├── references/           # Optional: detailed reference material
└── assets/               # Optional: templates, images, data files

skills-ref CLI commands

# Validate a skill directory
skills-ref validate ./my-skill

# Generate <available_skills> XML for agent prompts
skills-ref to-prompt /path/to/skill1 /path/to/skill2

File references in SKILL.md

Use relative paths from skill root:

See [the guide](references/REFERENCE.md) for details.
Run the script: `scripts/extract.py`

Decision guidance

When to use filesystem-based vs tool-based agent integration

When to include optional frontmatter fields

When to move content to separate files

Workflow

Creating a new skill

1. Create the directory structure: Make a folder named skill-name (lowercase, hyphens only)
2. Write the SKILL.md file:
   • Start with YAML frontmatter: name and description (required)
   • Write the Markdown body with clear instructions
   • Keep the main file under 500 lines
   • Use relative paths for file references: scripts/extract.py, references/GUIDE.md
3. Organize supporting files:
   • scripts/: Executable code (Python, Bash, etc.)
   • references/: Detailed documentation, lookup tables, schemas
   • assets/: Templates, images, data files
4. Validate the skill:

   skills-ref validate ./skill-name

   Fix any frontmatter errors (name format, description length, etc.)
5. Test the skill: Read the SKILL.md file to verify instructions are clear and complete

Integrating skills into an agent

1. Discover skills: Scan configured directories for folders containing SKILL.md files
2. Load metadata at startup: Parse only the YAML frontmatter from each skill:

   name: pdf-processing
   description: Extract text and tables from PDFs...

   This keeps initial context usage low (~100 tokens per skill)
3. Generate prompt XML:

   skills-ref to-prompt /path/to/skills/*

   Output includes name, description, and location for each skill
4. Inject into system prompt: Add the XML to your agent's system prompt so it knows available skills:

   <available_skills>
     <skill>
       <name>pdf-processing</name>
       <description>Extract text and tables from PDFs...</description>
       <location>/path/to/skills/pdf-processing/SKILL.md</location>
     </skill>
   </available_skills>

5. Activate on demand: When a user task matches a skill's description, load the full SKILL.md into context (~5000 tokens max)
6. Execute resources: Load referenced files or run scripts only when the skill instructions require them

Common gotchas

• Name format violations: Names must be lowercase with hyphens only, no leading/trailing hyphens. my-skill ✓, MySkill ✗, -my-skill ✗
• Description too long: Max 1024 characters. Descriptions longer than this will fail validation. Be concise about what the skill does and when to use it.
• Forgetting YAML delimiters: Frontmatter must start and end with --- on its own line. Missing delimiters break parsing.
• Absolute paths in file references: Always use relative paths from skill root (scripts/extract.py), never absolute paths (/home/user/scripts/extract.py)
• Bloated SKILL.md: Keeping the main file under 500 lines is a guideline, not a hard limit, but large files waste context. Move detailed reference material to references/ subdirectory.
• Missing location field for filesystem agents: When injecting skills into filesystem-based agent prompts, include the absolute path to SKILL.md. Tool-based agents can omit this.
• Not validating before deployment: Always run skills-ref validate before sharing or deploying a skill. Frontmatter errors are silent until validation.
• Unclear "when to use" description: The description field is critical for agent matching. Write it as a clear trigger: "Use when the user needs to extract text from PDFs" not "PDF processing skill".

Verification checklist

Before submitting a skill:

• SKILL.md frontmatter has name (max 64 chars, lowercase + hyphens) and description (max 1024 chars)
• Frontmatter is wrapped in --- delimiters on separate lines
• All file references use relative paths from skill root (e.g., scripts/extract.py)
• Main SKILL.md is under 500 lines; detailed material moved to references/ or assets/
• Skill passes validation: skills-ref validate ./skill-name
• Instructions are clear and actionable (imperative voice, step-by-step)
• Optional fields (license, compatibility, metadata) are accurate if included
• Skill description clearly states when an agent should use it (not just what it does)

Resources

• Comprehensive navigation: https://agentskills.io/llms.txt
• Full specification: https://agentskills.io/specification
• Integration guide: https://agentskills.io/integrate-skills
• Example skills: GitHub repository (linked from agentskills.io)

For additional documentation and navigation, see: https://agentskills.io/llms.txt