Skill SKILL.md Consistency Audit Report

Audit date: 2026-02-02 Audited by: Claude Opus 4.5 Sample size: 10 skills out of 65 total Reference standard: CLAUDE.md project instructions (Skill Authorship Standards)

---

1. Consistency Matrix

The table below tracks whether each sampled skill conforms to the documented standard for each dimension.

Legend: PASS = conforms, FAIL = deviates, WARN = uses value outside documented enum but value is reasonable, -- = not applicable

---

2. Common Quality Issues Across Skills

2.1 Phantom Related Skills References (CRITICAL)

The most significant cross-cutting issue. Multiple skills reference Related Skills that do not exist in the repository. Across the 10 sampled skills, 4 contain broken references. A broader search reveals this is a systemic problem across the full skill set (30+ phantom references found).

Phantom names found in sampled skills:

Broader systemic phantoms found across all skills (not just sample):

• "Backend Developer" (referenced by 6 skills) -- does not exist
• "Performance Engineer" (referenced by 8 skills) -- does not exist
• "Data Engineer" (referenced by 3 skills) -- does not exist
• "TypeScript Expert" (referenced in javascript-pro) -- actual name is typescript-pro
• "React Developer" (referenced in javascript-pro, typescript-pro) -- actual name is react-expert
• "Azure Specialist" (referenced in csharp-developer) -- does not exist
• "IoT Engineer" (referenced in embedded-systems) -- does not exist
• "Cloud Architect" (referenced by 7 skills) -- actually exists as cloud-architect
• "Security Engineer" (referenced by 2 skills) -- does not exist

Root cause: Related Skills use human-readable display names (e.g., "Backend Developer") that are not validated against the actual skill inventory. Some are aspirational references to skills that were never created. Others use slightly different display names than the actual skill's H1 title.

2.2 All Skills Fall Below Target Line Count

CLAUDE.md specifies Tier 1 SKILL.md files should be "~80-100 lines." Every sampled skill falls below the target range:

When blank lines are included, most files are close to the lower end of the 80-100 range. This is acceptable but means there is no headroom -- no skill invests its "line budget" on skill-specific nuances that would differentiate it from a template fill.

2.3 Core Workflow Step Count Inconsistency

CLAUDE.md specifies "Core workflow (5 high-level steps)." Two sampled skills use 6 steps:

• debugging-wizard: 6 steps (Reproduce, Isolate, Hypothesize, Test, Fix, Prevent)
• security-reviewer: 6 steps (Scope, Automated scan, Manual review, Active testing, Categorize, Report)

Both 6-step workflows are domain-justified and arguably better for it. This suggests the "5 steps" guidance may be too rigid, or these skills should be brought into compliance.

2.4 Frontmatter Enum Drift

The CLAUDE.md documents these enums:

• scope: implementation | review | design | system-design
• output-format: code | document | report | architecture

Actual values found across the full 65-skill set that fall outside these enums:

These are all reasonable values. The issue is that CLAUDE.md's enum list is incomplete, not that the skills are wrong. The documented enums need to be expanded, or a note added that custom values are permitted.

2.5 Non-Standard Frontmatter Fields

Two fields appear in some skills but are not documented in CLAUDE.md's Frontmatter Requirements:

• allowed-tools: Used by code-reviewer, spec-miner, security-reviewer (3 skills)

This field is meaningful (restricts which tools the skill can use) but is undocumented. It should either be added to the frontmatter spec or removed from the skills.

2.6 "When to Use" Format Inconsistency

9 of 10 sampled skills use a bullet list under "When to Use This Skill." The exception is security-reviewer, which uses a comma-separated prose paragraph:

Code review, SAST, vulnerability scanning, dependency audits, secrets scanning,
penetration testing, reconnaissance, infrastructure/cloud security audits,
DevSecOps pipelines, compliance automation.

This is the only format deviation in the sample but should be standardized for docs site generation.

2.7 Output Templates Format Inconsistency

Most skills use a numbered list under "Output Templates." Two deviate:

• security-reviewer: Uses inline prose with numbered parentheticals: "Provide: (1) Executive summary... (2) Findings table..."
• debugging-wizard: Uses bold labels in a numbered list (a richer format than others)

Neither is wrong, but for docs site rendering consistency, a single format should be chosen.

2.8 Attribution Comments in Routing Tables

Three skills contain HTML comments for attribution in their Reference Guide tables:

• code-reviewer: ``
• debugging-wizard: Same pattern
• test-master: Same pattern

These are invisible in rendered markdown but would appear in raw source. For a docs site generator that processes SKILL.md files, these should either be preserved (if attribution is required) or moved to a separate attribution section.

---

3. Section Order Analysis

The expected section order (derived from CLAUDE.md's Progressive Disclosure Architecture and the majority pattern) is:

1. YAML Frontmatter
2. # Title
3. One-line subtitle/description
4. ## Role Definition
5. ## When to Use This Skill
6. ## Core Workflow
7. ## Reference Guide (table)
8. ## Constraints (### MUST DO, ### MUST NOT DO)
9. ## Output Templates
10. ## Knowledge Reference
11. ## Related Skills

All 10 sampled skills follow this exact order, with one exception:

• feature-forge adds a non-standard ## Pre-Discovery with Subagents section between "Core Workflow" and "Reference Guide." This is the only skill in the sample with an extra section.

This is a strong positive finding: section order is highly consistent.

---

4. Per-Skill Deviations (Only Where Notable)

4.1 feature-forge

• Extra section: ## Pre-Discovery with Subagents is a non-standard section not found in other skills. It describes a multi-agent workflow pattern.
• Tool-specific constraints: References AskUserQuestions tool explicitly in both Core Workflow and Constraints. This is unique among sampled skills and raises a question: should skills reference specific tools by name, or keep tool usage implicit?
• File output path: Specifies Save as: specs/{feature_name}.spec.md in Output Templates -- the only skill to prescribe a file path.

4.2 security-reviewer

• "When to Use" is prose, not bullets (see section 2.6 above).
• Core Workflow has 6 steps instead of 5.
• Output Templates is prose instead of numbered list.
• Has allowed-tools field not in the documented frontmatter spec.
• Overall, this skill deviates more from the template than any other in the sample.

4.3 debugging-wizard

• Core Workflow has 6 steps instead of 5.
• scope: analysis and output-format: analysis are outside documented enums.
• Output Templates uses bold labels (e.g., **Root Cause**:, **Evidence**:) -- richer format than others.

4.4 code-reviewer

• Has allowed-tools field (undocumented in spec).
• Attribution HTML comment in Reference Guide table.

4.5 python-pro

• Phantom Related Skill: References "Data Science Pro" which does not exist.

4.6 terraform-engineer

• Phantom Related Skill: References "Security Engineer" which does not exist.
• References "Cloud Architect" which does exist.

4.7 pandas-pro

• Phantom Related Skill: References "Data Scientist" which does not exist.
• Only 2 Related Skills listed (fewest in sample; others have 3-4).

4.8 architecture-designer

• Lowest line count in sample (69 non-blank lines).
• Related Skills reference names ("Secure Code Guardian") that use different casing/display than the H1 title in the actual skill.

4.9 react-expert, nestjs-expert

No notable deviations. These are the most template-conformant skills in the sample.

---

5. Docs Site Readiness Assessment

What Works Well for Standalone Pages

1. Consistent section structure -- The 11-section order is machine-parseable and could directly map to page sections.
2. YAML frontmatter -- Provides structured metadata for page generation (title, category via scope, output type).
3. Reference Guide table -- Could generate "See Also" or "Deep Dive" link sections.
4. Constraints -- MUST DO / MUST NOT DO sections are visually distinctive and could be rendered as callout boxes.
5. Related Skills -- Natural cross-linking between pages (once phantom references are fixed).

What Is Missing for Standalone Pages

---

6. Template Recommendation

Based on this audit, the ideal SKILL.md structure for docs site generation would be:

---
name: skill-name-with-hyphens
description: Use when [triggering conditions]. Invoke for [specific keywords].
summary: One-sentence human-readable summary for docs site cards.
category: frontend|backend|language|quality|architecture|design|workflow|infrastructure|security|data|devops|testing
triggers: [keyword1, keyword2, keyword3]
role: specialist|expert|architect
scope: implementation|review|design|system-design|analysis|testing|infrastructure|optimization
output-format: code|document|report|architecture|analysis|specification
version: "1.0"
---

# Skill Display Name

One-line role statement: "Senior [role] specializing in [domain]."

## Role Definition

2-3 sentences establishing persona, years of experience