aiskillstore 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
```bash
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
```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
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
- Create directory:
mkdir -p .claude/skills/{skill-name} - Create SKILL.md with template above
- Add content: Steps, commands, examples
- Validate:
bpsai-pair skill validate {skill-name} - Fix issues: Address any errors or warnings
- 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