creating-skills

Creating Skills

When to Create a Skill

Create a skill when:

• A workflow is repeated across multiple sessions
• Complex multi-step processes need documentation
• Team needs standardized approach to a task
• Errors occur that a documented procedure would prevent

Skill Directory Structure

.claude/skills/{skill-name}/
├── SKILL.md          # Required: Main skill document
├── reference/        # Optional: Supporting documents
└── scripts/          # Optional: Automation scripts

SKILL.md Template

---
name: skill-name
description: Third-person description of what the skill does. Under 1024 chars.
---

# Skill Title

## When to Use

Describe trigger conditions.

## Steps

1. First step
2. Second step
3. Third step

## Commands

command1 command2

## Examples

Show usage examples.

Frontmatter Rules

Required fields (only these two allowed):

| Field | Rules | |-------|-------| | name | Lowercase, hyphenated, gerund form (e.g., creating-skills) | | description | Under 1024 chars, 3rd-person voice, no "you" |

Not allowed: Any other fields (version, author, tags, etc.)

Naming Conventions

| Rule | Good | Bad | |------|------|-----| | Lowercase | reviewing-code | Reviewing-Code | | Hyphens, not underscores | creating-skills | creating_skills | | Gerund form (-ing) | implementing-with-tdd | implement-tdd | | Match directory name | name: foo in foo/ | name: bar in foo/ |

Gerund Suggestions

| Instead of | Use | |------------|-----| | code-review | reviewing-code | | plan | planning | | implement | implementing | | design | designing | | finish | finishing |

Description Guidelines

Good (3rd person):

Manages task lifecycle transitions and coordinates Trello sync.

Bad (2nd person):

Use when you need to manage task lifecycle.

File Size Limits

• SKILL.md: Under 500 lines
• Description: Under 1024 characters

Validation Checklist

Before finalizing a skill:

• [ ] Frontmatter has only name and description
• [ ] Name is lowercase-hyphenated gerund
• [ ] Name matches directory name
• [ ] Description under 1024 characters
• [ ] Description uses 3rd-person voice
• [ ] SKILL.md under 500 lines
• [ ] No "Claude already knows this" content
• [ ] Includes actionable steps or commands

CLI Commands

# List all skills
bpsai-pair skill list

# Validate all skills
bpsai-pair skill validate

# Validate specific skill
bpsai-pair skill validate creating-skills

# Auto-fix simple issues
bpsai-pair skill validate --fix

Common Validation Errors

| Error | Fix | |-------|-----| | Extra frontmatter fields | Remove all fields except name/description | | Name mismatch | Make frontmatter name match directory name | | Description too long | Shorten to under 1024 characters | | File too long | Split into SKILL.md + reference docs |

Creating a New Skill

1. Create directory: mkdir -p .claude/skills/{skill-name}
2. Create SKILL.md with template above
3. Add content: Steps, commands, examples
4. Validate: bpsai-pair skill validate {skill-name}
5. Fix issues: Address any errors or warnings
6. Test: Verify skill works in practice

Anti-patterns to Avoid

• Generic knowledge: Don't document things Claude already knows
• Excessive length: Keep focused, link to reference docs
• 2nd person voice: Use "Performs X" not "Use when you need X"
• Extra metadata: No version, author, tags in frontmatter
• Underscores: Use hyphens for multi-word names