Quick Start

Create a basic Agent Skill structure:

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── examples/         # Optional: sample inputs/outputs

SKILL.md template:

YAML
---
name: skill-name-in-kebab-case
description: Third-person description of what it does and when to use it.
---

# Quick Start
[Immediate actionable example]

# Workflow
1. Step one with specific action
2. Step two with expected output
3. Step three with validation

# Examples
**Example 1:**
Input: [specific input]
Output: [specific output]

# Best Practices
- Key guideline 1
- Key guideline 2

# Common Pitfalls
- What to avoid and why

Workflow

• Identify the specific expertise or workflow to capture
• Define clear trigger conditions (when to use this skill)
• Determine required inputs and expected outputs

• Create skill directory with kebab-case name
• Write SKILL.md with proper YAML frontmatter
• Add supporting files (scripts, references, assets) as needed
• Include concrete examples with input/output pairs

• Validate that instructions are clear and actionable
• Test with sample inputs to ensure expected outputs
• Remove unnecessary complexity and explanations
• Optimize for ~500 lines or split into multiple skills

• Ensure all file paths are relative and portable
• Add README.md for human users if needed
• Version control the skill directory
• Make available to compatible agent systems

Examples

Example 1: Data Analysis Skill Input: "I need to analyze sales data trends" Output: Agent loads analyzing-sales-data skill with pandas scripts, visualization templates, and step-by-step analysis workflow.

Example 2: Code Review Skill Input: "Please review this pull request" Output: Agent loads reviewing-code skill with checklists, style guides, and security scanning procedures.

Example 3: Legal Document Skill Input: "Draft a service agreement" Output: Agent loads drafting-contracts skill with templates, clause libraries, and compliance requirements.

Best Practices

• Name skills with gerund verbs: analyzing-data, writing-reports, debugging-code
• Progressive disclosure: Only essential metadata loads initially, full instructions load when triggered
• Concrete over abstract: Include specific examples rather than general descriptions
• Portable design: Use relative file paths, avoid hardcoded dependencies
• Focused scope: One skill per distinct workflow or expertise area
• Actionable instructions: Each step should produce a measurable output
• Include validation: How to verify the task was completed correctly

Common Pitfalls

• Overly broad scope: Don't create "general purpose" skills - be specific
• Missing trigger conditions: Description must clearly indicate when to use the skill
• Verbose explanations: Assume the agent understands basic concepts
• Hardcoded paths: Skills must be portable across different environments
• No examples: Abstract instructions without concrete input/output samples
• Kitchen sink approach: Including every possible option instead of recommended defaults
• First-person instructions: Use third-person or imperative voice, not "I will..."
• Circular dependencies: Skills referencing other skills create loading complexity

The Agent Skills format enables building libraries of specialized knowledge that agents can discover, load, and execute on-demand, creating more capable and reliable AI assistants.