Claude Skills + CONTENT_GUIDELINES の組み合わせ

Skills とは何か

Claude Skills は、特定タスクの実行手順を 定義ファイル + 補助ドキュメント で構成された再利用可能な「型」。スラッシュコマンドで呼び出すと、Claude が型に沿って動く。

私のサイトでは 4 つの Skills を運用している:

• /post-outline — テーマから h2/h3 構成案を作る
• /post-draft — 構成案から Markdown 本文を作る
• /post-image — __IMAGE_N__ プレースホルダを実 URL に置換
• /post-publish — Bot API に POST して draft で投稿

これらが守るルールは doc/CONTENT_GUIDELINES.md に集約されている。Skills はガイドラインに従う、ガイドラインは Skills を制約する。

Skill 定義の基本構造

# .claude/skills/post-outline/SKILL.md
---
name: post-outline
description: AetherEchoes のブログ記事の構成案を CONTENT_GUIDELINES に準拠した形で生成する
---

# /post-outline — 記事構成案ジェネレータ

## 必読ファイル

1. doc/CONTENT_GUIDELINES.md — 4.1 章（見出し階層）/ 7 章（LLMO チェックリスト）
2. doc/DATA_MODEL.md — 3.5 章（フィールド上限）

## 出力フォーマット

YAML 風のチェックリストで返す。slug / title / excerpt / tag_slugs / 章立て / FAQ 候補 / 出典候補。

ポイント:

• 必読ファイルを明示する。Claude はその記述を見て、毎回読みに行く
• 出力フォーマットを厳密に決める。次の Skill が消費できる形を強制
• 入力の解釈方法を書く。テーマだけ / 構造化、両方を受ける

CONTENT_GUIDELINES.md が SSoT

Skill が守るべきルールは Skill 定義の中ではなく、CONTENT_GUIDELINES.md に書く。Skill は「ガイドラインを読んで従う」だけ。

なぜか:

1. Skill が複数になっても 同じガイドラインを参照 できる
2. 人間（編集者）も同じ書類を読む — Bot と人間で ルールがずれない
3. ガイドラインの更新が即 Skill にも反映される（Skill は毎回読み直す）

ガイドラインに書くべき内容

• 見出し階層（h1 禁止、最初は h2、レベル飛ばし禁止）
• 段落の長さ目安
• callout の type 名（note / tip / warning / summary / danger）
• 画像の embed 規約
• アフィ表記の付け方
• SEO/OG 推奨文字数

これらが文書化されていれば、Skill は 最終出力が valid かどうかを自分で検査 できる。

# backend/app/services/post/markdown_structure_validator.rb
class Post::MarkdownStructureValidator
  def validate
    raise 'h1 is forbidden' if @md.match?(/^# /m)
    raise 'must start with h2' unless @md.lstrip.start_with?('## ')
    # ... レベル飛ばし禁止 等
  end
end

これを Bot API + Admin API の両方で走らせる。ガイドライン違反は upsert ごと拒否 される。