aiskillstore/canonical-format-checker

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/ └── <skill-name>/ # Directory, NOT flat file └── SKILL.md # SKILL.md file (uppercase)

**YAML Frontmatter** (REQUIRED):
```yaml
---
name: "<skill-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
## 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