Reference Files

Advanced skill discovery and optimization guidance:

• trigger-analysis.md - Description analysis methodology and keyword extraction
• progressive-disclosure.md - SKILL.md size guidelines and reference organization
• discovery-testing.md - Test query generation and scoring methodology
• examples.md - Good vs poor skill examples with before/after fixes

---

Skill Audit

Audits skills for discoverability and triggering effectiveness by analyzing description quality, trigger phrase coverage, progressive disclosure, and metadata completeness.

Focus Areas

• Description Completeness - What the skill does AND when to use it
• Trigger Phrase Coverage - Keywords and patterns that should activate the skill
• Metadata Quality - Frontmatter completeness and accuracy
• Progressive Disclosure - SKILL.md size vs reference file organization
• Reference Organization - File structure, linking, navigation
• Tool Appropriateness - allowed-tools matches actual needs

Audit Framework

Discovery Analysis

Critical Question: Would this skill be discovered and triggered when needed?

Key Components:

1. Description Triggers - Does frontmatter description contain:

   • What the skill does (capability statement)
   • When to use it (triggering scenarios)
   • Key features (differentiators)
   • User query keywords (how users would ask for it)

2. Anti-Patterns - Common discovery killers:

   • "When to Use" section in SKILL.md body (loaded AFTER triggering)
   • Description <50 chars (too vague)
   • Generic description ("helps with tasks")
   • Missing use cases in description
   • Technical jargon without plain language equivalents

3. Progressive Disclosure Compliance:

   • SKILL.md lean (<500 lines target)
   • Details in separate reference files
   • References clearly linked from SKILL.md
   • One level deep (no nested subdirectories)

4. Tool Permission Analysis:

   • allowed-tools field present and accurate
   • Tools match actual usage in SKILL.md
   • Not overly restrictive or permissive
   • Security implications considered

Audit Process

Step 1: Read SKILL.md Frontmatter

Extract and analyze frontmatter:

---
name: skill-name
description: Comprehensive description...
allowed-tools: [Tool1, Tool2, Tool3]
---

Check for:

• Required fields (name, description)
• Description length (>50 chars minimum)
• allowed-tools presence and accuracy

Step 2: Analyze Description for Trigger Clarity

Test the description against these questions:

1. Capability: What does this skill do? (explicitly stated?)
2. Triggers: When should it be used? (scenarios mentioned?)
3. Keywords: Would user queries match? (natural language?)
4. Features: What makes it unique? (differentiators listed?)

Score Calculation (1-10):

• 10: Comprehensive description with all elements
• 7-9: Good description, minor improvements possible
• 4-6: Adequate but missing key triggers
• 1-3: Poor, would rarely be discovered

For detailed trigger analysis methodology, see trigger-analysis.md.

Step 3: Check for Body Boundary Violations

Search SKILL.md body for anti-patterns:

• "When to Use" section (should be in description)
• "Triggers" section (should be in description)
• Use case lists not in description
• Extensive scenario descriptions

Why This Matters: Body content is only loaded AFTER the skill is triggered. Information needed for triggering MUST be in the frontmatter description.

Step 4: Verify Progressive Disclosure

Assess information architecture:

1. SKILL.md Size: Count lines (target <500)
2. Reference Files: Check for separate reference files alongside SKILL.md
3. Navigation: Verify links from SKILL.md to reference files
4. Flat Structure: Ensure all files are at skill root, no subdirectories
5. Orphans: Find references not linked from SKILL.md

Scoring:

• GOOD: SKILL.md <500 lines, clear navigation, proper structure
• NEEDS IMPROVEMENT: SKILL.md >500 lines or poor organization
• N/A: Skill is simple enough to not need references

For progressive disclosure guidelines, see progressive-disclosure.md.

Step 5: Assess allowed-tools Appropriateness

Compare allowed-tools to actual usage:

1. Extract tools mentioned in SKILL.md body
2. Compare to allowed-tools list
3. Identify missing or excessive permissions
4. Check for security implications

Common Issues:

• Missing allowed-tools (overly permissive)
• allowed-tools too restrictive (skill can't work)
• Security concerns (excessive permissions)

Step 6: Generate Discovery Score and Report

Create comprehensive audit report following output format.

Output Format

Provide audit reports in this standardized structure:

# Skill Audit Report: {name}

**Skill**: {name}
**File**: {path t

...