⚡

规范格式检查器 canonical-format-checker

规范格式检查器是一个用于防止软件开发中格式漂移的智能工具。它通过验证教学内容是否遵循权威的规范源格式，确保技能、子代理、ADR、PHR和规范等平台模式的一致性。该工具提供自动触发检查、格式对比清单和漂移检测报告，帮助开发团队维护代码规范、文档标准化和格式一致性。关键词：格式检查、规范验证、格式漂移预防、代码规范、文档标准化、一致性检查、开发工具、格式审计、规范源比对、格式合规性。

DevOps 0 次安装 0 次浏览 更新于 2/28/2026

name: canonical-format-checker description: 当内容教授在其他地方有规范来源的模式（技能、子代理、ADR、PHR、规范）时，应使用此技能。通过确保内容引用并遵循规范来源的权威格式来防止格式漂移。在实施教授平台模式的课程之前，或在审查内容格式一致性时使用。

规范格式检查器

概述

通过验证内容是否遵循权威的规范来源来防止格式漂移。当教授平台中其他地方存在的模式（技能、子代理、ADR等）时，此技能确保所教授的格式与规范源匹配。

为什么这很重要：第14章的格式漂移失败是因为课程教授的技能格式与第5章（规范源）不同。学生学习了与早期章节相矛盾的错误模式。

何时使用此技能

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

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

手动触发（用户请求）：

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

规范源查找表

正在教授的模式 规范源位置 关键格式元素
技能 .claude/skills/<名称>/SKILL.md 目录结构，包含 name、description 的YAML前言
子代理 .claude/agents/<名称>.md 包含 name、description、model、skills 的YAML前言
ADR specs/<功能>/adrs/adr-*.md 编号文件，标准ADR结构
PHR history/prompts/<阶段>/ 来自 .specify/templates/phr-template.prompt.md 的模板
规范 specs/<功能>/spec.md 章节：概述、用户故事、功能需求、成功标准、评估
命令 .claude/commands/*.md YAML前言，分步阶段

工作流程

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

问自己：

  • 这节课是否教授如何创建任何平台模式？
  • 这个模式是否有现有的规范源？
触发示例：
- "课程教学生编写自己的技能" → 技能模式
- "章节涵盖自定义命令" → 命令模式
- "模块解释代理创建" → 子代理模式

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

强制要求：在编写或审查内容之前阅读规范源。

# 对于技能 - 读取实际技能结构
ls .claude/skills/*/
cat .claude/skills/session-intelligence-harvester/SKILL.md

# 对于代理 - 读取实际代理结构
ls .claude/agents/
cat .claude/agents/content-implementer.md

# 对于命令 - 读取实际命令结构
ls .claude/commands/
head -50 .claude/commands/sp.specify.md

步骤3：提取格式要求

从规范源记录所需的格式元素：

## 规范格式：技能

**目录结构**：

.claude/skills/ └── <技能名称>/ # 目录，不是平面文件 └── SKILL.md # SKILL.md 文件（大写）


**YAML前言**（必需）：
```yaml
---
name: "<技能名称>"
description: "此技能应在...时使用。当...时使用"
---

内容结构：

  1. H1标题匹配技能名称
  2. 概述部分解释目的
  3. 何时使用部分包含触发条件
  4. 工作流程部分包含步骤

### 步骤4：与规范源比较内容

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

```markdown
## 格式比较检查清单

**技能格式检查**：
- [ ] 显示目录结构（不是平面文件）
- [ ] 使用SKILL.md文件名（不是skill.md或index.md）
- [ ] 包含带有 `name` 和 `description` 的YAML前言
- [ ] `description` 以"此技能应在...时使用"开头

**代理格式检查**：
- [ ] 显示代理目录中的单个.md文件
- [ ] 包含带有 `name`、`description`、`model` 的YAML前言
- [ ] 包含 `skills` 数组（可以为空）
- [ ] 描述解释何时调用

**命令格式检查**：
- [ ] 显示命令目录中的.md文件
- [ ] 具有带明确关卡的编号阶段
- [ ] 包含强制执行检查

步骤5：报告漂移或确认合规性

如果检测到格式漂移：

## 检测到格式漂移

**模式**：技能
**位置**：第7课，"创建你的第一个技能"部分

**问题**：显示平面文件 `.claude/skills/my-skill.md`
**规范**：目录结构 `.claude/skills/my-skill/SKILL.md`

**需要的具体修复**：
1. 第45行：将 `.claude/skills/my-skill.md` 改为 `.claude/skills/my-skill/SKILL.md`
2. 第52行：更新示例以显示使用 `mkdir` 创建目录
3. 第60行：添加带有必需字段的YAML前言示例

**交叉引用**：第5章，第7课（agent-skills.md）是规范源

如果格式合规：

## 格式已验证

**模式**：技能
**规范源**：`.claude/skills/session-intelligence-harvester/SKILL.md`
**内容位置**：第14章，第5课

**验证**：
- [x] 目录结构与规范匹配
- [x] YAML前言格式正确
- [x] 必需字段存在（名称，描述）
- [x] 描述遵循"此技能应在...时使用"模式

**状态**：合规 - 未检测到漂移

常见格式漂移模式

漂移模式1：平面文件 vs 目录

错误：.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 都有（描述以"此技能应在…时使用"开头）

漂移模式5：发明新格式

错误：创建与规范不匹配的自定义格式 正确：遵循规范源的精确结构

集成点

与以下一起使用：

  • chapter-planner - 在课程规划阶段检查
  • content-implementer - 实施前验证
  • validation-auditor - 包含在验证检查清单中

何时调用：

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

自我监控

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

  • [ ] 识别正在教授的模式
  • [ ] 定位并阅读规范源
  • [ ] 从规范源提取格式要求
  • [ ] 将内容与规范要求进行比较
  • [ ] 检测漂移或确认合规性
  • [ ] 如果发现漂移，提供具体的修复说明

成功标准

成功时：

  • 在发布前检测到格式漂移
  • 识别并引用了具体的规范源
  • 记录了精确的格式要求
  • 内容与规范源完全匹配

失败时：

  • 内容教授与规范相矛盾的错误格式
  • 实施前未检查规范源
  • 模糊的反馈（“修复格式”）而不是具体的更正
  • 发明新模式而不是遵循规范