---
description: Standards and quality gates for the skill library. Audits existing skills (descriptions, dependencies, dead skills, eval coverage), proposes improvements, governs how new skills are created. Runs on demand or quarterly. Triggered by 'audit skills', 'skill health check', '/skill-maint'.
---

# personal-skill-maintenance

Keeps the skill library sharp. Skills decay (descriptions go stale, dependencies break, patterns drift); this skill is the maintenance layer.

## Trigger phrases

- "Audit my skills"
- "Skill health check"
- "Are any skills stale?"
- `/skill-maint`

## Audit checks

### Check 1 — Description quality (description-triggering effectiveness)

For each skill:

- Does the description start with a concise capability statement?
- Does it list trigger phrases?
- Is it >50 words and <250 words (sweet spot for triggering without bloat)?
- Are there ambiguous overlaps with other skills' descriptions?

### Check 2 — File staleness

- When was the SKILL.md last modified?
- Does it reference paths that exist?
- Does it reference tools/MCPs that are still installed?

### Check 3 — Eval coverage (if evals/ folder exists)

- Does the skill have an evals/ folder?
- Are evals current (last run within 30 days)?
- Do evals pass?

### Check 4 — Dead-skill detection

- Has the skill been invoked in the last 60 days? (Check OpenCode session DB for invocations.)
- If not invoked in >180 days, propose archiving.

### Check 5 — Cross-skill consistency

- Do skills with similar purpose use consistent file structure (same section names, same output formats)?
- Are voice rules applied consistently across skills that produce future-employer-content?

### Check 6 — AGENTS.md alignment

- Does each skill's behavior match the rules in AGENTS.md?
- E.g., does every skill that produces future-employer-content explicitly state Tier 4 main session?
- Does every skill that delegates respect the GATE rules?

### Check 7 — Trigger collision

- If two skills could both reasonably fire on the same prompt, surface the collision.
- Example: "personal-resume-tailor" and "personal-cover-letter" both fire on application work — but they should fire in sequence, not in conflict. Make sure the description language disambiguates.

## Output

```markdown
# Skill Library Audit — YYYY-MM-DD

**Total skills:** [N]
**Active (invoked in last 60d):** [N]
**Stale (>180d, candidates for archive):** [N]

## Per-skill summary

| Skill | Last invoked | Eval status | Description quality | Findings |
|---|---|---|---|---|
| personal-jd-analyzer | 3d ago | passing | green | 0 |
| personal-resume-tailor | 5d ago | passing | green | 1 nit |
| ... | | | | |

## Findings by severity

### BLOCKING

- [skill]: [finding]

### WARNING

- [skill]: [finding]

### NIT

- [skill]: [finding]

## Recommended actions

1. **Archive:** [skill] (180+ days dormant, no clear use case)
2. **Update description:** [skill] (collides with [other skill])
3. **Add evals:** [skill] (no evals folder, recently modified)

## Library health score

[X]/10 — [1 sentence rationale]
```

## Skill creation governance

When creating a new skill:

1. **Capture intent.** What's the one-line capability?
2. **Draft description.** 50-250 words. Start with capability, end with trigger phrases.
3. **Test prompts.** Try 5-10 prompts that should trigger this skill. Confirm they do.
4. **Test prompts that should NOT trigger.** Confirm they don't.
5. **Ship with at least one eval** so future drift is caught by regression check.
6. **Add to AGENTS.md project registry** if the skill is project-specific (e.g., career-* skills).

## Discipline

- Don't keep skills "just in case." Stale skills bloat description-loading and reduce trigger precision for the active skills.
- Every skill should produce something concrete. Skills that just "think about" something without output are vapor.
- Skills that overlap in trigger space should either be merged or have descriptions sharpened to disambiguate.