canonical-format-checker

Prevent format drift by verifying content follows authoritative canonical sources. When teaching a pattern that exists elsewhere in the platform (skills, subagents, ADRs, etc.), this skill ensures the taught format matches the canonical source.

Why this matters: The Chapter 14 format drift failure occurred because the lesson taught skill format differently from Chapter 5 (canonical source). Students learned incorrect patterns that contradicted earlier chapters.

Automatic Triggers (check before implementation):

• Lesson teaches how to create skills → Check .claude/skills/ structure
• Lesson teaches how to write subagents → Check .claude/agents/ structure
• Lesson teaches ADR format → Check specs/*/adrs/ structure
• Lesson teaches PHR format → Check history/prompts/ structure
• Lesson teaches specification format → Check specs/*/spec.md structure

Manual Triggers (user requests):

• "Check canonical format for skills"
• "Verify format consistency"
• "Does this match the canonical source?"

| Pattern Being Taught | Canonical Source Location | Key Format Elements |

|---------------------|--------------------------|---------------------|

| Skills | .claude/skills//SKILL.md | Directory structure, YAML frontmatter with name, description |

| Subagents | .claude/agents/.md | YAML frontmatter with name, description, model, skills |

| ADRs | specs//adrs/adr-*.md | Numbered files, standard ADR structure |

| PHRs | history/prompts// | Template from .specify/templates/phr-template.prompt.md |

| Specifications | specs//spec.md | Sections: Overview, User Stories, FRs, SCs, Evals |

| Commands | .claude/commands/*.md | YAML frontmatter, step-by-step phases |

Step 1: Identify What Pattern Is Being Taught

Ask yourself:

• Does this lesson teach how to CREATE any platform pattern?
• Is there an existing canonical source for this pattern?

```

Trigger Examples:

• "Lesson teaches students to write their own skills" → Skills pattern
• "Chapter covers custom commands" → Commands pattern
• "Module explains agent creation" → Subagents pattern

```

Step 2: Locate and Read Canonical Source

MANDATORY: Read the canonical source BEFORE writing or reviewing content.

```bash

# For Skills - read actual skill structure

ls .claude/skills/*/

cat .claude/skills/session-intelligence-harvester/SKILL.md

# For Agents - read actual agent structure

ls .claude/agents/

cat .claude/agents/content-implementer.md

# For Commands - read actual command structure

ls .claude/commands/

head -50 .claude/commands/sp.specify.md

```

Step 3: Extract Format Requirements

Document the required format elements from canonical source:

```markdown

Directory Structure:

```

.claude/skills/

└── / # Directory, NOT flat file

└── SKILL.md # SKILL.md file (uppercase)

```

YAML Frontmatter (REQUIRED):

```yaml

---

name: ""

description: "This skill should be used when... Use when..."

---

```

Content Structure:

1. H1 title matching skill name
2. Overview section explaining purpose
3. When to Use section with triggers
4. Workflow section with steps

```

Step 4: Compare Content Against Canonical

Check the lesson/content for format consistency:

```markdown

Skill Format Check:

• [ ] Shows directory structure (not flat file)
• [ ] Uses SKILL.md filename (not skill.md or index.md)
• [ ] Includes YAML frontmatter with name and description
• [ ] description starts with "This skill should be used when..."

Agent Format Check:

• [ ] Shows single .md file in agents directory
• [ ] Includes YAML frontmatter with name, description, model
• [ ] Includes skills array (can be empty)
• [ ] Description explains when to invoke

Command Format Check:

• [ ] Shows .md file in commands directory
• [ ] Has numbered phases with clear gates
• [ ] Includes enforcement checks

```

Step 5: Report Drift or Confirm Compliance

If Format Drift Detected:

```markdown

Pattern: Skills

Location: Lesson 7, Section "Creating Your First Skill"

Issue: Shows flat file .claude/skills/my-skill.md

Canonical: Directory structure .claude/skills/my-skill/SKILL.md

Specific Fixes Required:

1. Line 45: Change .claude/skills/my-skill.md to .claude/skills/my-skill/SKILL.md
2. Line 52: Update example to show directory creation with mkdir
3. Line 60: Add YAML frontmatter example with required fields

Cross-Reference: Chapter 5, Lesson 7 (agent-skills.md) is canonical source

```

If Format Compliant:

```markdown

Pattern: Skills

Canonical Source: .claude/skills/session-intelligence-harvester/SKILL.md

Content Location: Chapter 14, Lesson 5

Verification:

• [x] Directory structure matches canonical
• [x] YAML frontmatter format correct
• [x] Required fields present (name, description)
• [x] Description follows "This skill should be used when..." pattern

Status: COMPLIANT - No drift detected

```

Drift Pattern 1: Flat Files vs Directories

Wrong: .claude/skills/my-skill.md

Right: .claude/skills/my-skill/SKILL.md

Drift Pattern 2: Missing YAML Frontmatter

Wrong: Markdown file with no frontmatter

Right: YAML frontmatter with required fields

Drift Pattern 3: Wrong Filename

Wrong: skill.md, index.md, README.md

Right: SKILL.md (uppercase)

Drift Pattern 4: Missing Required Fields

Wrong: Only name in frontmatter

Right: Both name and description (description starts with "This skill should be used when...")

Drift Pattern 5: Inventing New Format

Wrong: Creating custom format not matching canonical

Right: Following exact structure from canonical source

Use With:

• chapter-planner - Check during lesson planning phase
• content-implementer - Verify before implementation
• validation-auditor - Include in validation checklist

Invoke When:

• Planning lessons that teach platform patterns
• Reviewing content that describes file structures
• Validating documentation about Claude Code features

Before approving content that teaches patterns:

• [ ] Identified what pattern is being taught
• [ ] Located and READ the canonical source
• [ ] Extracted format requirements from canonical
• [ ] Compared content against canonical requirements
• [ ] Detected drift OR confirmed compliance
• [ ] Provided specific fix instructions if drift found

You succeed when:

• Format drift detected BEFORE publication
• Specific canonical source identified and referenced
• Exact format requirements documented
• Content matches canonical source exactly

You fail when:

• Content teaches incorrect format that contradicts canonical
• Canonical source not checked before implementation
• Vague feedback ("fix the format") instead of specific corrections
• New patterns invented instead of following canonical