canonical-format-checker

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

通过验证内容是否遵循权威规范来源，防止格式偏差。当教授平台中已存在的模式（技能、子代理、ADR等）时，此技能可确保所教授的格式与规范来源保持一致。

重要性：第14章曾出现格式偏差问题，原因是课程教授的技能格式与第5章（规范来源）不一致，导致学生学习到与先前章节矛盾的错误模式。

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

自动触发（实施前检查）：

课程教授如何创建技能 → 检查
```
.claude/skills/
```
结构
课程教授如何编写子代理 → 检查
```
.claude/agents/
```
结构
课程教授ADR格式 → 检查
```
specs/*/adrs/
```
结构
课程教授PHR格式 → 检查
```
history/prompts/
```
结构
课程教授规范格式 → 检查
```
specs/*/spec.md
```
结构

手动触发（用户请求）：

"检查技能的规范格式"
"验证格式一致性"
"这是否与规范来源匹配？"

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

教授的模式	规范来源位置	关键格式要素
技能	`.claude/skills/<name>/SKILL.md`	目录结构、包含 `name` 和 `description` 的YAML frontmatter
子代理	`.claude/agents/<name>.md`	包含 `name` 、 `description` 、 `model` 、 `skills` 的YAML frontmatter
ADR	`specs/<feature>/adrs/adr-*.md`	编号文件、标准ADR结构
PHR	`history/prompts/<stage>/`	来自 `.specify/templates/phr-template.prompt.md` 的模板
规范文档	`specs/<feature>/spec.md`	章节：概述、用户故事、功能需求（FRs）、场景（SCs）、评估（Evals）
命令	`.claude/commands/*.md`	YAML frontmatter、分步阶段

Workflow

工作流程

Step 1: Identify What Pattern Is Being Taught

步骤1：确定教授的模式类型

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

步骤2：定位并阅读规范来源

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

bash

undefined

强制要求：在编写或审核内容前，必须阅读规范来源。

bash

undefined

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

undefined

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

undefined

Step 3: Extract Format Requirements

步骤3：提取格式要求

Document the required format elements from canonical source:

markdown

undefined

记录从规范来源中获取的必填格式要素：

markdown

undefined

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:

H1 title matching skill name
Overview section explaining purpose
When to Use section with triggers
Workflow section with steps

undefined

目录结构:

.claude/skills/
└── <skill-name>/          # 目录，而非扁平文件
    └── SKILL.md           # SKILL.md文件（大写）

YAML Frontmatter（必填）:

yaml

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

内容结构:

与技能名称匹配的H1标题
说明用途的概述章节
包含触发条件的使用场景章节
包含步骤的工作流程章节

undefined

Step 4: Compare Content Against Canonical

步骤4：对比内容与规范要求

Check the lesson/content for format consistency:

markdown

undefined

检查课程/内容的格式一致性：

markdown

undefined

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

undefined

技能格式检查:

展示目录结构（而非扁平文件）
使用SKILL.md文件名（而非skill.md或index.md）
包含带有
```
name
```
和
```
description
```
的YAML frontmatter
```
description
```
以"This skill should be used when..."开头

代理格式检查:

展示agents目录中的单个.md文件
包含带有
```
name
```
、
```
description
```
、
```
model
```
的YAML frontmatter
包含
```
skills
```
数组（可空）
描述说明调用时机

命令格式检查:

展示commands目录中的.md文件
包含带明确节点的编号阶段
包含合规性检查

undefined

Step 5: Report Drift or Confirm Compliance

步骤5：报告偏差或确认合规

If Format Drift Detected:

markdown

undefined

若检测到格式偏差:

markdown

undefined

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:

Line 45: Change

.claude/skills/my-skill.md

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

Line 52: Update example to show directory creation with
```
mkdir
```
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

模式: 技能位置: 第7课，"创建你的第一个技能"小节

问题: 展示扁平文件

.claude/skills/my-skill.md

规范: 目录结构

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

需修改的具体内容:

第45行：将

.claude/skills/my-skill.md

改为

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

第52行：更新示例以展示使用
```
mkdir
```
创建目录
第60行：添加包含必填字段的YAML frontmatter示例

交叉引用: 第5章第7课（agent-skills.md）为规范来源


**若格式合规**:
```markdown

Format Verified

格式验证通过

Pattern: Skills Canonical Source:

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

Content Location: Chapter 14, Lesson 5

Verification:

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

Status: COMPLIANT - No drift detected

undefined

模式: 技能 规范来源:

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

内容位置: 第14章第5课

验证结果:

目录结构与规范匹配
YAML frontmatter格式正确
必填字段齐全（name、description）
描述遵循"This skill should be used when..."格式

状态: 合规 - 未检测到偏差

undefined

Common Format Drift Patterns

常见格式偏差模式

Drift Pattern 1: Flat Files vs Directories

偏差模式1：扁平文件vs目录

Wrong:

.claude/skills/my-skill.md

Right:

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

错误:

.claude/skills/my-skill.md

正确:

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

Drift Pattern 2: Missing YAML Frontmatter

偏差模式2：缺少YAML Frontmatter

Wrong: Markdown file with no frontmatter Right: YAML frontmatter with required fields

错误: 无frontmatter的Markdown文件正确: 包含必填字段的YAML frontmatter

Drift Pattern 3: Wrong Filename

偏差模式3：错误的文件名

Wrong:

skill.md

index.md

README.md

Right:

SKILL.md

(uppercase)

错误:

skill.md

、

index.md

、

README.md

正确:

SKILL.md

（大写）

Drift Pattern 4: Missing Required Fields

偏差模式4：缺少必填字段

Wrong: Only

name

in frontmatter Right: Both

name

and

description

(description starts with "This skill should be used when...")

错误: frontmatter中仅包含

name

正确: 同时包含

name

和

description

（描述以"This skill should be used when..."开头）

Drift Pattern 5: Inventing New Format

偏差模式5：自定义新格式

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

搭配使用:

```
chapter-planner
```
- 课程规划阶段检查
```
content-implementer
```
- 实施前验证
```
validation-auditor
```
- 纳入验证检查表

调用时机:

规划教授平台模式的课程时
审核描述文件结构的内容时
验证关于Claude Code功能的文档时

Self-Monitoring

自我监控

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

成功场景:

格式偏差在发布前被检测到
已明确标识并引用具体规范来源
已记录精确的格式要求
内容与规范来源完全匹配

失败场景:

内容教授与规范矛盾的错误格式
实施前未检查规范来源
给出模糊反馈（如"修改格式"）而非具体修正建议
未遵循规范而是创建新模式