---
name: skill-engineering
description: Meta-skill for creating, refactoring, vetting, and maintaining Claude Code skills. Treats skills as production software. Source: Alja (20+ yrs enterprise arch) + Sam/Francis (AI workflow expert).
version: 1.0.0
metadata:
  filePattern: "**/skills/**"
priority: 92
---

# Skill Engineering

## Skills Are Production Code

| Code Principle | Skill Equivalent |
|---------------|-----------------|
| Refactor when quality drifts | Refactor skill when outputs become inconsistent |
| Version control | `version: X.Y.Z` in frontmatter, increment on changes |
| Single responsibility | One skill = one concern. Split if > 1 page. |
| DRY | Don't repeat context across skills. Reference shared files. |
| Test coverage | Define expected output shape. Validate before deploying. |
| Code review | Vet externally-sourced skills before adopting. |

## SKILL.md Frontmatter Template

```yaml
---
name: skill-name
description: One sentence — what this teaches and when it applies. Be specific.
version: 1.0.0
metadata:
  filePattern: "**/*.ext"     # Glob: triggers on file path match
  # OR
  bashPattern: "pattern"      # Regex: triggers on bash command match
priority: 80                  # 1-100. Higher = injected first. Max 3 skills per tool call.
---
```

## Skill Structure Template

```markdown
# Skill Name

## Core Principle
[One paragraph — the "why" behind this skill]

## Rules
[Numbered, actionable. Not philosophy — specific instructions.]

## Decision Matrix
[Table: situation → what to do]

## Anti-Patterns
[❌ list of what NOT to do]

## Examples
[Concrete before/after or command examples]
```

## Skill Size Rules

- **Max 1 page** per skill
- If a skill covers more than one topic → split into two skills
- Chain split skills sequentially (trigger one → outputs feed into next)
- AI misses instructions in the second half of long prompts — this is a hard limit

## Skill Refactoring Triggers

Refactor a skill when:
- Output quality drifts (same task → inconsistent results)
- Token cost for a task is unreasonably high
- Skill is being ignored (check: does it trigger? is the pattern right?)
- Skill has grown beyond one page
- Two skills are doing overlapping things

## Vetting External Skills

Never adopt a skill from the internet without review:
1. Generate the skill from its source material (book, blog, framework)
2. Read it critically — does it match your team's context?
3. Remove anything conflicting with your ADRs or architectural decisions
4. Test it on a real task before committing to the skills directory
5. Version it as `1.0.0-external` until validated

**Good skill sources**: Guru, design pattern libraries, Code Smiths, engineering best practice repos.
Ask AI: "Generate a Claude Code skill from this source: [paste content]. Then I'll review it."

## Organizational Skill Strategy

| Layer | Owns It | Changes |
|-------|---------|---------|
| Base skills (10 Commandments) | Team/org | Rarely — shared best practices |
| Domain skills | Team | Occasionally — patterns for your domain |
| Personal skills | Individual | Frequently — personal workflow preferences |

Base skills — the "10 Commandments":
1. Make it work (correctness first)
2. Make it clean (code quality)
3. Make it tested (tests before merging)
4. Make it reviewed (human reviews output)
5. Make it secure (security scan embedded)

## Priority Guide

| Priority Range | Use For |
|---------------|---------|
| 90-100 | Meta-skills, orchestration rules, universal guidelines |
| 80-89 | Domain-specific patterns, core architectural rules |
| 70-79 | Framework-specific conventions |
| 60-69 | Optional enhancements, style guides |

## Anti-Patterns
- ❌ Skills longer than one page
- ❌ No `filePattern` or `bashPattern` (skill never triggers)
- ❌ Skills that cover too many topics (split them)
- ❌ Adopting external skills without vetting
- ❌ Skills that duplicate each other (consolidate)
- ❌ Not versioning skills (you won't know when they changed)