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

---
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

```bash
command1
command2

## 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

```bash
# 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