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

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): ```yaml

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