canonical-format-checker

正規フォーマットチェッカー

概要

コンテンツが権威ある正規のソースに従っていることを確認し、フォーマットのずれを防ぎます。プラットフォーム内の別の場所（スキル、サブエージェント、ADR など）に存在するパターンを教える際、このスキルによって、教えるフォーマットが正規のソースと一致していることを確認します。

これが重要な理由：第 14 章でフォーマットのずれが発生したのは、レッスンでスキルのフォーマットを第 5 章（正規のソース）とは異なる形で教えたためです。学習者は、それ以前の章と矛盾する誤ったパターンを学んでしまいました。

このスキルを使用する場面

自動トリガー（実装前に確認）：

• レッスンでスキルの作成方法を教える → .claude/skills/ の構造を確認
• レッスンでサブエージェントの記述方法を教える → .claude/agents/ の構造を確認
• レッスンで ADR のフォーマットを教える → specs/*/adrs/ の構造を確認
• レッスンで PHR のフォーマットを教える → history/prompts/ の構造を確認
• レッスンで仕様書のフォーマットを教える → specs/*/spec.md の構造を確認

手動トリガー（ユーザーからの依頼）：

• 「スキルの正規フォーマットを確認してください」
• 「フォーマットの一貫性を確認してください」
• 「これは正規のソースと一致していますか？」

正規のソース参照表

教えるパターン	正規のソースの場所	主なフォーマット要素
スキル	.claude/skills/<name>/SKILL.md	ディレクトリ構造、name と description を含む YAML フロントマター
サブエージェント	.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、評価
コマンド	.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 の機能に関するドキュメントを検証するとき

セルフモニタリング

パターンを教えるコンテンツを承認する前に、次の項目を確認してください。

• 教えているパターンを特定した
• 正式な情報源を見つけて読み込んだ
• 正式な情報源からフォーマット要件を抽出した
• コンテンツを正式な要件と照合した
• 逸脱を検出した、または準拠していることを確認した
• 逸脱が見つかった場合、具体的な修正指示を提示した

成功基準

次の場合に成功です。

• 公開前にフォーマットの逸脱を検出する
• 具体的な正式な情報源を特定し、参照する
• 正確なフォーマット要件を記録する
• コンテンツが正式な情報源に完全に準拠している

次の場合に失敗です。

• 正式な情報源に反する誤ったフォーマットをコンテンツで教える
• 実装前に正式な情報源を確認しない
• 具体的な修正ではなく、「フォーマットを修正してください」のような曖昧なフィードバックをする
• 正式な情報源に従わず、新たなパターンを考案する