Agent Skill Creation

Agent Skill Creation Guide

This skill teaches you how to create Agent Skills following Anthropic's open standard (agentskills.io).

What is an Agent Skill?

An Agent Skill is a folder containing a SKILL.md file with:

• YAML frontmatter (name and description)
• Markdown instructions that give agents specialized knowledge and workflows
• Optional supporting files (scripts, reference docs, templates)

SKILL.md Format

---
name: skill-name-in-kebab-case
description: "Concise description of what this skill enables. Include trigger phrases like 'When the user asks to...'"
---

# Skill Title

## Overview
Brief explanation of what this skill does and when to use it.

## Workflows
Step-by-step instructions for completing tasks.

## Best Practices
Guidelines and tips for using this skill effectively.

## Dependencies (optional)
Required tools or packages.

Design Principles

1. Progressive Disclosure

• Load only what's needed: name/description first, then full instructions
• Split large skills into multiple files referenced from SKILL.md
• Use separate files for detailed reference material

2. Clear Trigger Conditions

• The description should clearly indicate WHEN to use this skill
• Include example phrases: "When the user asks to...", "For tasks involving..."

3. Actionable Instructions

• Write step-by-step workflows, not just explanations
• Include code examples, commands, and templates
• Be specific about tools and parameters to use

4. Think from Claude's Perspective

• What context does the agent need to succeed?
• What mistakes might it make? Include warnings
• What's the decision tree for different scenarios?

Creating a New Skill

Step 1: Plan the Skill

Answer these questions:

1. What specific capability does this skill provide?
2. What triggers should activate this skill?
3. What steps/workflows are involved?
4. What could go wrong? What guardrails are needed?

Step 2: Create the Skill Folder

# Use the absolute skills installation path
# The path varies by OS - use the path shown in the skills system prompt
mkdir -p "<SKILLS_FOLDER>/my-skill-name"

Step 3: Write SKILL.md

Create the SKILL.md file with:

• Frontmatter with name and description
• Overview section
• Workflow sections with step-by-step instructions
• Examples and code snippets

Step 4: Add Supporting Files (Optional)

For complex skills, create additional files:

• reference.md - Detailed documentation
• templates/ - Template files for common tasks
• scripts/ - Helper scripts the agent can execute

Step 5: Test the Skill

• Enable the skill in Settings > Skills
• Ask questions that should trigger it
• Iterate based on what works and what doesn't

Example Skills Ideas

• Code Review: Guidelines for reviewing code in a specific language or framework
• API Integration: Instructions for working with a specific API
• Testing Patterns: Best practices for writing tests in your stack
• Documentation: Standards for writing technical documentation
• Git Workflows: Team-specific branching and commit conventions
• Data Processing: Workflows for handling specific data formats

Best Practices for Skill Authors

1. Start with evaluation: Identify where your agent struggles before writing a skill
2. Structure for scale: Keep SKILL.md lean, use linked files for detailed content
3. Iterate with Claude: Ask the agent to help refine the skill based on real usage
4. Version control: Put skills in git for team sharing and history
5. Security: Only install skills from trusted sources; audit third-party skills

File Organization

skill-name/
├── SKILL.md           # Required: Main skill instructions
├── reference.md       # Optional: Detailed reference material
├── examples/          # Optional: Example files
│   ├── example1.md
│   └── example2.md
├── scripts/           # Optional: Helper scripts
│   └── helper.py
└── templates/         # Optional: Templates for common tasks
    └── template.md

Common Mistakes to Avoid

1. Too broad: Skills work best when focused on specific tasks
2. Too much context: Don't load everything upfront; use progressive disclosure
3. Missing examples: Always include concrete examples and code
4. Vague triggers: Make it clear exactly when to use the skill
5. No error handling: Include guidance for common failure modes