canonical-format-checker

规范格式检查器

概述

通过验证内容是否遵循权威规范来源，防止格式漂移。当教学内容涉及平台其他位置已有的模式（技能、子 Agent、ADR 等）时，此技能可确保教授的格式与规范来源一致。

为何重要：第 14 章发生的格式漂移问题，是因为课程教授的技能格式与第 5 章（规范来源）不同。学生学到了与前面章节相矛盾的错误模式。

何时使用此技能

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

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

手动触发（用户请求）：

• “检查技能的规范格式”
• “验证格式是否一致”
• “这是否符合规范来源？”

规范来源查找表

教授的模式	规范来源位置	关键格式要素
技能	.claude/skills/<name>/SKILL.md	目录结构，包含 name、description 的 YAML 前置内容
子 Agent	.claude/agents/<name>.md	包含 name、description、model、skills 的 YAML 前置内容
ADR	specs/<feature>/adrs/adr-*.md	编号文件，标准 ADR 结构
PHR	history/prompts/<stage>/	.specify/templates/phr-template.prompt.md 中的模板
规格说明	specs/<feature>/spec.md	各章节：概述、用户故事、FR、SC、Evals
命令	.claude/commands/*.md	YAML 前置内容，分步骤的阶段

工作流

步骤 1：识别正在教授的模式

问问自己：

• 本课程是否教授如何创建任何平台模式？
• 此模式是否已有规范来源？

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

步骤 2：查找并阅读规范来源

必须：在编写或审查内容之前，先阅读规范来源。

# 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

步骤 3：提取格式要求

记录规范来源中的必需格式要素：

## Canonical Format: Skills

**Directory Structure**:

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

**YAML Frontmatter** (REQUIRED):
```yaml
---
name: "<skill-name>"
description: "This skill should be used when... Use when..."
---

内容结构：

1. H1 标题与技能名称一致
2. 概述部分，说明用途
3. 使用时机部分，列出触发条件
4. 工作流部分，列出步骤

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

步骤 5：报告格式漂移或确认符合要求

如果检测到格式漂移：

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

如果格式符合要求：

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

常见格式漂移模式

漂移模式 1：扁平文件与目录

错误：.claude/skills/my-skill.md 正确：.claude/skills/my-skill/SKILL.md

漂移模式 2：缺少 YAML 前置内容

错误：没有前置内容的 Markdown 文件 正确：包含必需字段的 YAML 前置内容

漂移模式 3：文件名错误

错误：skill.md、index.md、README.md 正确：SKILL.md（大写）

漂移模式 4：缺少必需字段

错误：前置内容中只有 name 正确：同时包含 name 和 description（description 以“This skill should be used when...”开头）

漂移模式 5：另创格式

错误：创建与规范格式不一致的自定义格式 正确：严格遵循规范来源中的结构

集成点

配合使用：

• chapter-planner - 在课程规划阶段检查
• content-implementer - 实现前验证
• validation-auditor - 纳入验证清单

在以下情况下调用：

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

自我监控

在批准教授模式的内容之前：

• 确定所教授的模式
• 找到并阅读规范来源
• 从规范来源中提取格式要求
• 对照规范要求检查内容
• 检测偏差，或确认符合要求
• 如果发现偏差，提供具体的修正说明

成功标准

满足以下条件即为成功：

• 在发布前检测到格式偏差
• 明确指出并引用具体的规范来源
• 记录精确的格式要求
• 内容与规范来源完全一致

出现以下情况即为失败：

• 内容教授了与规范相矛盾的错误格式
• 实施前未核查规范来源
• 反馈含糊不清（如“修正格式”），而非提供具体的修改建议
• 未遵循规范来源，而是另行发明模式