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 = 1024 chars max, per Agent Skills Spec)
for f in $(find plugins -name "SKILL.md"); do
  desc=$(grep "^description:" "$f" | cut -d: -f2-)
  len=${#desc}
  if [ $len -gt 1024 ]; then
    echo "DESCRIPTION TOO LONG ($len chars): $f"
  fi
done

# Check SKILL.md body line count (Anthropic recommends < 500 lines for progressive disclosure)
for f in $(find plugins -name "SKILL.md"); do
  # Count body lines (skip frontmatter between first two --- markers)
  body_lines=$(awk '/^---$/{c++; next} c>=2{n++} END{print n+0}' "$f")
  if [ "$body_lines" -gt 500 ]; then
    echo "BODY TOO LONG ($body_lines lines): $f — move detail to resources/"
  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 ≤1024 chars (Agent Skills Spec) Count characters Shorten
SKILL.md body ≤500 lines (progressive disclosure) Count body lines (after frontmatter) Move detail to resources/*.md
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 <1024 chars |
| skill-name | SKILL.md body too long | Medium | Split detail into `resources/*.md`, keep body <500 lines |

## 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 > 1024 characters (Agent Skills Spec hard limit)

Fix: Shorten to essential info:

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

SKILL.md Body Too Long

Symptom: SKILL.md body > 500 lines (Anthropic progressive disclosure guidance)

Fix: Split detail into resources/*.md files. Keep SKILL.md as the discoverable summary; load resource files on-demand:

  • Workflow steps → resources/workflow.md
  • Schema/field references → resources/schemas.md (or per-table .md files)
  • Templates → resources/templates/*.md
  • Detailed examples → resources/examples.md

The SKILL.md body should fit in ≤5000 tokens (~500 lines) so it loads quickly when the skill activates. Resource files only load when explicitly read.

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)"]
    }
  }
}