skill-stocktake

Skill Stocktake

Audit the .github/skills/ and vscode-omg/resources/templates/skills/ directories to produce a quality and coverage report.

When to Use

• Before adding new skills (to avoid duplication)
• After a large change batch (to verify templates are in sync)
• Periodically to prune stale or incomplete skills

Audit Protocol

Step 1: Inventory

# List all skill directories
ls -1d .github/skills/*/

# Count total
ls -1d .github/skills/*/ | wc -l

# Check each has a SKILL.md
for dir in .github/skills/*/; do
  [ -f "${dir}SKILL.md" ] || echo "MISSING SKILL.md: $dir"
done

Step 2: Frontmatter Validation (v1.0.5+)

Each SKILL.md MUST have valid frontmatter:

---
name: skill-name           # required, kebab-case, matches directory name
description: >             # required, multi-line description with trigger keywords
  ...
argument-hint: "..."       # optional, describes argument
---

v1.0.5 breaking changes to check:

• ❌ hint: field → ✅ argument-hint:
• ❌ allowed-tools: field → ✅ remove (not supported)
• Skill name autopilot → must be omg-autopilot (naming collision)

Validate with:

# Find skills using old 'hint:' field
grep -rn "^hint:" .github/skills/

# Find skills using unsupported 'allowed-tools:'
grep -rn "^allowed-tools:" .github/skills/

# Check for old 'autopilot' directory
ls .github/skills/ | grep "^autopilot$"

Step 3: Template Sync Check

# Skills in .github but not in templates
diff <(ls .github/skills/) <(ls vscode-omg/resources/templates/skills/)

# Skills in templates but not in .github (orphan templates)
diff <(ls vscode-omg/resources/templates/skills/) <(ls .github/skills/)

Step 4: Quality Checks

For each skill, check:

• name: matches directory name exactly
• description: includes trigger keywords ("Activate when: X, Y, Z")
• Has a clear "When to Use" or "Steps" section
• Has an "Output Format" or "See Also" section
• No broken cross-references to renamed skills (/autopilot → /omg-autopilot)
• File is not empty stub (< 20 lines = likely incomplete)