Skip to content

Auditing Skills

This guide provides a formal checklist for auditing existing skills to ensure they meet quality standards.

Quick Audit Commands

Run these from repository root:

# Count all skills
find plugins -name "SKILL.md" | wc -l

# Check frontmatter compliance
for f in $(find plugins -name "SKILL.md"); do
  echo "=== $f ==="
  head -10 "$f"
done

# Find skills missing activation rules
for skill in $(find plugins -name "SKILL.md" -exec dirname {} \;); do
  [ -f "$skill/skill-rules-fragment.json" ] || echo "Missing: $skill"
done

# Check description lengths (Claude.ai = 200 max)
for f in $(find plugins -name "SKILL.md"); do
  desc=$(grep "^description:" "$f" | cut -d: -f2-)
  len=${#desc}
  if [ $len -gt 200 ]; then
    echo "TOO LONG ($len): $f"
  fi
done

Audit Checklist

Frontmatter Compliance

Requirement Check Fix
Has name field grep "^name:" SKILL.md Add field
Name ≤64 chars Count characters Shorten
Name is kebab-case No spaces, uppercase Rename
Has description field grep "^description:" SKILL.md Add field
Description ≤200 chars (Claude.ai) Count characters Shorten
Description ≤1024 chars (general) Count characters Shorten
Has type: skill grep "^type:" SKILL.md Add field
Has version grep "^version:" SKILL.md Add field
Has auto-load grep "^auto-load:" SKILL.md Add field

Structure Compliance

Requirement Check Fix
SKILL.md < 500 lines wc -l SKILL.md Move to resources/
Has skill-rules-fragment.json ls skill-rules-fragment.json Create file
Resources in resources/ folder ls resources/ Move files
Resource files have parent-skill grep "parent-skill:" resources/*.md Add frontmatter

Content Quality

Requirement Check Fix
Description explains WHAT Read description Rewrite
Description explains WHEN Contains trigger words Add triggers
Quick Reference section exists grep "## Quick Reference" SKILL.md Add section
Components/Resources listed grep "## Components\|## Resources" SKILL.md Add section
Usage examples present grep "## Usage\|## Examples" SKILL.md Add section

Activation Quality

Requirement Check Fix
Has keywords array jq '.*.promptTriggers.keywords' *.json Add keywords
Has intent patterns jq '.*.promptTriggers.intentPatterns' *.json Add patterns
Priority set jq '.*.priority' *.json Add priority
Type is domain or workflow jq '.*.type' *.json Set type

Documentation Quality

Requirement Check Fix
User stories documented Check references/by-division/ Document
Golden examples available Check references/by-division/{div}/examples/ Collect
Linked from skill-reference.md grep "skill-name" docs/wiki/reference/skill-reference.md Add entry
Requirements Stack complete Check Requirements Stack checklist Gather missing inputs

Audit Report Template

Use this template for audit reports:

# Skill Audit Report

**Date:** YYYY-MM-DD
**Auditor:** [Name]
**Scope:** [All skills / Division / Specific skill]

## Summary

| Metric | Count |
|--------|-------|
| Total skills | X |
| Passing | X |
| Needs fix | X |
| Critical issues | X |

## Issues Found

| Skill | Issue | Severity | Fix |
|-------|-------|----------|-----|
| skill-name | Missing frontmatter | Critical | Add YAML |
| skill-name | Description too long | Medium | Shorten to <200 |

## Recommendations

1. [Recommendation 1]
2. [Recommendation 2]

Common Issues & Fixes

Missing YAML Frontmatter

Symptom: File starts with # instead of ---

Fix: Add frontmatter at TOP of file:

---
name: skill-name
description: "What it does. Use when [triggers]."
type: skill
version: 1.0.0
auto-load: true
---

Description Too Long

Symptom: Description > 200 characters

Fix: Shorten to essential info:

  • WHAT it does (primary function)
  • WHEN to use (trigger phrases)
  • Remove marketing fluff

Example:

# Before (247 chars):
description: Assists in writing high-quality content by conducting research, adding citations, improving hooks, iterating on outlines, and providing real-time feedback on each section. Transforms your writing process from solo effort to collaborative partnership.

# After (118 chars):
description: Writing partner for research, citations, outlines, and section-by-section feedback. Transforms writing into collaboration.

Missing Activation Rules

Symptom: No skill-rules-fragment.json file

Fix: Create with minimal triggers:

{
  "skill-name": {
    "type": "domain",
    "enforcement": "suggest",
    "priority": "medium",
    "promptTriggers": {
      "keywords": ["keyword1", "keyword2"],
      "intentPatterns": ["(action).*(noun)"]
    }
  }
}