Canonical Format Checker

Overview

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.

When to Use This Skill

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?"

Canonical Source Lookup Table

Pattern Being Taught Canonical Source Location Key Format Elements

Skills .claude/skills/<name>/SKILL.md

Directory structure, YAML frontmatter with name , description

Subagents .claude/agents/<name>.md

YAML frontmatter with name , description , model , skills

ADRs specs/<feature>/adrs/adr-*.md

Numbered files, standard ADR structure

PHRs history/prompts/<stage>/

Template from .specify/templates/phr-template.prompt.md

Specifications specs/<feature>/spec.md

Sections: Overview, User Stories, FRs, SCs, Evals

Commands .claude/commands/*.md

YAML frontmatter, step-by-step phases

Workflow

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.

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:

Canonical Format: Skills

Directory Structure:

.claude/skills/ └── / # Directory, NOT flat file └── SKILL.md # SKILL.md file (uppercase)

YAML Frontmatter (REQUIRED):

---
name: "<skill-name>"
description: "This skill should be used when... Use when..."
---

Content Structure:

- H1 title matching skill name

- Overview section explaining purpose

- When to Use section with triggers

- Workflow section with steps

### Step 4: Compare Content Against Canonical

Check the lesson/content for format consistency:

```markdown
## Format Comparison Checklist

**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:

## Format Drift Detected

**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:

## Format Verified

**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

Common Format Drift Patterns

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

Integration Points

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

Self-Monitoring

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

Success Criteria

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