name: create-agent-skill
description: Creates new AI agent skills following the standard guidelines. Use when you need to create a new skill, scaffold skill structure, or ensure skills follow best practices.

Create AI Skill

This skill helps you create new AI agent skills that follow the standard folder structure and formatting guidelines.

When to Use This Skill

• Creating a new skill from scratch
• Scaffolding the correct folder structure for a skill
• Ensuring a skill follows best practices
• Converting existing documentation into a skill format

Skill Structure

Every skill MUST follow this folder structure:

.agent/skills/<skill-name>/
├── SKILL.md          # Main instructions (REQUIRED)
├── scripts/          # Helper scripts (optional)
├── examples/         # Reference implementations (optional)
└── resources/        # Templates and other assets (optional)

How to Create a Skill

Step 1: Create the Skill Folder

mkdir -p .agent/skills/<skill-name>

Use lowercase with hyphens for the folder name:
- ✅ code-review, unit-testing, api-design
- ❌ CodeReview, unit_testing, apiDesign

Step 2: Create SKILL.md with Frontmatter

Every SKILL.md MUST start with YAML frontmatter:

---
name: skill-name
description: Clear description of what this skill does. Use when you need to do X or Y.
---

[!IMPORTANT]
The description field is REQUIRED. The agent uses this to decide whether to use the skill.

[!CAUTION]
All skills MUST be written in English. This ensures consistency and accessibility across all users and AI agents.

Step 3: Add Required Sections

Include these sections in order:

1. Title - # Skill Name
2. Overview - 1-2 sentence description
3. When to Use This Skill - Bullet points of use cases
4. How to Use - Step-by-step instructions
5. Examples - Real, runnable examples

Step 4: Add Optional Folders (If Needed)

Create optional folders when your skill needs them:

# For helper scripts
mkdir -p .agent/skills/<skill-name>/scripts

# For code examples
mkdir -p .agent/skills/<skill-name>/examples

# For templates and assets
mkdir -p .agent/skills/<skill-name>/resources

Managing Long Skills

[!WARNING]
SKILL.md MUST NOT exceed 500 lines. If your skill is getting too long, you MUST split content into external files.

File Length Rules

How to Split Long Skills

1. Move examples to examples/ folder
   bash mkdir -p .agent/skills/<skill-name>/examples

2. Move reference docs to resources/ folder
   bash mkdir -p .agent/skills/<skill-name>/resources

3. Keep SKILL.md focused on:

4. Overview and when to use
5. Quick start / essential commands
6. Links to detailed examples

7. Best practices summary

8. Link external files in SKILL.md:
   ```markdown
   ## Examples & Resources

### Examples
- Basic Usage - Getting started example
- Advanced Patterns - Complex use cases

### Resources
- Commands Reference - Full command list
- Configuration Guide - All config options
```

What Goes Where

Links Requirement

[!IMPORTANT]
Every file in examples/, scripts/, and resources/ folders MUST be linked in SKILL.md. Unlinked files will not be discovered by the agent.

SKILL.md Template

Use this template for new skills:

---
name: my-skill-name
description: [Clear, specific description. Include keywords for discovery.]
---

# [Skill Name]

[1-2 sentence overview of what this skill does]

## When to Use This Skill

- Use when [specific situation 1]
- Use when [specific situation 2]
- NOT for [exclusion case]

## Prerequisites

- [Required tool/setup 1]
- [Required tool/setup 2]

## How to Use

### Step 1: [First Action]

[Detailed instructions]

### Step 2: [Second Action]

[Detailed instructions]

## Examples

### [Example Scenario]

\`\`\`bash
# Example commands or code
\`\`\`

## Best Practices

- [Practice 1]
- [Practice 2]

## Troubleshooting

| Issue | Solution |
|-------|----------|
| [Problem 1] | [Fix 1] |
| [Problem 2] | [Fix 2] |

Validation Checklist

Before finalizing a skill, verify:

Structure

• [ ] Folder name is lowercase with hyphens
• [ ] Has SKILL.md file (uppercase)
• [ ] YAML frontmatter has description
• [ ] All content written in English

Content

• [ ] Description is clear and specific
• [ ] Has "When to Use This Skill" section
• [ ] Has "How to Use" section with steps
• [ ] Examples are realistic and runnable

Links Validation

• [ ] All examples/ files are linked in SKILL.md
• [ ] All scripts/ files are linked in SKILL.md
• [ ] All resources/ files are linked in SKILL.md
• [ ] Links use relative paths (e.g., ./examples/file.js)
• [ ] All linked files exist

Best Practices

• [ ] Skill focuses on ONE specific task
• [ ] No overlap with existing skills
• [ ] Scripts have --help option
• [ ] Decision tree for complex logic

Decision Tree

What are you creating?
├── New skill from scratch
│   └── Use full template above
├── Converting existing docs to skill
│   └── Extract key instructions, add frontmatter
└── Adding examples to existing skill
    └── Create examples/ folder, link from SKILL.md

Common Mistakes to Avoid

Related Skills

• See SKILL_GUIDELINES.md for the full specification