Claude Codeのoutput styleとCLAUDE.md・Skillsは何が違うか
output styleは毎回送られる指示の差し替え、CLAUDE.mdは常時読み込まれる事実、Skillsは呼ばれたときだけ読み込まれる手順です。反映のタイミングまで含めて比較します。
output style・CLAUDE.md・Skillsはどれも「Claudeの振る舞いを変える」機構ですが、効く範囲と、編集してから効き始めるまでの時間が違います。output styleは毎回のリクエストに乗る応答の流儀、CLAUDE.mdはプロジェクトの事実、Skillsは呼ばれたときだけ読み込まれる手順書です。
迷ったら、全応答の口調や役割ならoutput style、毎回知っておいてほしい事実ならCLAUDE.md、ときどき使う手順ならSkillsです。output styleの切り替え手順そのものは基本ガイドと自作テンプレート集にあり、ここでは3つの選び分けと組み合わせ方を扱います。
3つの機構は何を変えるのか
Claude Codeの3機構は、Claudeに届く指示の種類が違います。
3つの機構が担うもの
Output style
応答の役割・口調・形式を全リクエストに適用します。組み込みはProactive・Concise・Explanatory・Learningの4種で、
/output-styleで切り替えます。何も選ばないDefaultは、ソフトウェア開発向けの標準の指示のままです。CLAUDE.md
プロジェクトの規約やビルドコマンドのような事実です。システムプロンプトの後ろにユーザーメッセージとして読み込まれ、Claudeの基本的な振る舞いは変えません。
Skills
デプロイ手順やAPI仕様書のように、ときどき必要でまとまった分量になる手順・参考資料です。Claudeが関連作業で自動的に選ぶか、
/名前で呼んだときだけ本文が会話に入ります。
カスタムのoutput styleは、既定ではClaude Code組み込みのソフトウェア開発向け指示を外します。コードを書く作業を続けたいなら、frontmatterに keep-coding-instructions: true を足します。Roo Codeの roleDefinition をoutput styleへ移す対応はRoo CodeからClaude Codeへの移行で扱っています。
| 機構 | 内容を書くのは | 毎リクエストのコスト | 強制力 |
|---|---|---|---|
| Output style | 内容を書くのはあなた(組み込みも選べる) | 毎リクエストのコスト選んだスタイルの本文が常に乗る | 強制力なし |
| CLAUDE.md | 内容を書くのはあなた(自動メモリはClaude) | 毎リクエストのコスト読み込まれた全内容が乗る | 強制力なし |
| Skills | 内容を書くのはあなた | 毎リクエストのコスト説明文だけ常駐、本文は呼ばれたときだけ | 強制力なし |
「強制力」の列が3つとも「なし」なのは意図的です。どれもClaudeへの指示であって、実行を保証する仕組みではありません。編集後のフォーマット整形やコマンドのブロックのように毎回必ず起きてほしい処理は、Claude Codeが自分で実行するhookの領分です。
編集したら、いつ効き始めるか
設定を直したのに反映されない、という場面の大半は、機構ごとに反映のタイミングが違うことが原因です。
編集してから効くまで
次のメッセージから
output styleの切り替え(/output-style、/config、outputStyle 設定)と、Skillsの追加・編集です。Skillsは ~/.claude/skills/ やプロジェクトの .claude/skills/ の変更を、セッション中に検知します。
次の /clear か再起動から
ルート直下とユーザーレベルのCLAUDE.mdの編集です。output styleのファイル(.claude/output-styles/ の中身)をターミナルで編集した場合は、再起動が要ります。
output styleの切り替えは、v2.1.251より前は /clear か新しいセッションまで反映されませんでした。今は切り替えた次のメッセージから効きます。新しいスタイルの指示は会話の中のメッセージとして届くので、システムプロンプトと過去の会話はキャッシュから読まれたままです。なお、Proactiveは定型の判断で止まらずに作業を進めるスタイルですが、権限モードは変わりません。データの削除や本番・共有環境の変更の前だけは、会話で確認する指示が入っています。
CLAUDE.mdのほうは、プロジェクトルートとユーザーレベルのファイルがセッション開始時に一度だけ読まれ、メモリ上に保持されます。編集してもキャッシュは無効化されませんが、編集は反映されません。新しい内容が入るのは次の /clear・/compact・再起動です。サブディレクトリのCLAUDE.mdと paths: を付けたルールは、Claudeが該当ファイルを読んだときに読み込まれます。
Skillsは、呼び出された時点でユーザーメッセージとして会話に注入されます。それ以前の会話は変わらないため、キャッシュも崩れません。新規に作ったトップレベルのskillsディレクトリだけは、検知対象になっていないので /reload-skills を実行します。
機構ごとの強みと弱み
output styleの強みと弱み: 口調と役割をまとめて変えられる
強みは、トーン・出力形式・役割を1回の選択でまとめて切り替えられることです。Conciseは結論から始めて前置きと要約を省き(v2.1.237以降が必要)、Explanatoryは Insight ブロックで判断の理由を添えます。Learningは小さなコードを利用者に書かせます。
弱みは3つあります。
- カスタムスタイルは
keep-coding-instructionsを付けないと開発向けの指示を失う outputStyleは1つの名前を取る設定で、複数のスタイルを並べる指定にはなっていない- frontmatterの項目名を綴り違いしても、エラーなしで無視される
outputStyle の値は大文字小文字を区別します。explanatory と書くとDefaultに戻り、組み込みなら Explanatory と書きます。/output-style コマンドのほうは大文字小文字を無視します。
CLAUDE.mdの強みと弱み: 肥大化すると効きが落ちる
強みは、規約やビルドコマンドのように常に知っておいてほしい事実を、どのスタイルでも保ったまま確実に読み込ませられることです。/compact の後もプロジェクトルートのCLAUDE.mdはディスクから再読み込みされ、会話に戻ります。
弱みは、全内容が毎回コンテキストに乗ることです。1ファイル200行以内が目安で、超えるとコンテキストを消費するうえ、指示の守られ方も落ちます。@path による分割は整理には役立ちますが、読み込み量は減りません。インポートしたファイルも起動時に読み込まれるためです。
200行を超えたファイルには、起動時と /status で警告が出ます。4 MiBを超えるファイルは読み込まれません。ブロックレベルのHTMLコメント(<!-- 保守メモ -->)はコンテキストに入る前に取り除かれるので、人間向けのメモはコメントに書けばトークンを使いません。あふれた参考資料は、Skillsやパス限定のルールへ逃がします。
Skillsの強みと弱み: 呼ばれないと発動しない
強みは、使われるまでの費用がほぼ説明文だけで済むことです。description と when_to_use を合わせた1,536文字を超える部分は、一覧に載る時点で切り捨てられます。主な用途を先頭に書くのがコツです。
弱みは、自動選択に任せると、説明文が曖昧なときに狙ったSkillが選ばれないことです。確実に使いたい手順は /名前 で呼びます。デプロイや送信のように副作用がある手順には、disable-model-invocation: true を付けて自動起動を止めます。
もう1つの癖は自動コンパクションです。会話が要約されると、呼び出し済みのSkillは各5,000トークンまで、合計25,000トークンの予算で要約の後ろに再添付されます。最近使ったものから詰めるため、1セッションで多数を呼ぶと古いSkillは落ちることがあります。
状況別の使い分け早見表
| 状況 | 選ぶ機構 | 理由 |
|---|---|---|
| 規約・ビルドコマンドを毎回知っておいてほしい | 選ぶ機構CLAUDE.md | 理由常時読み込まれ、スタイルを変えても保たれる |
| 全応答の口調・役割・形式を変えたい | 選ぶ機構Output style | 理由全リクエストに適用される |
| 起動時に渡す追加指示が欲しい(スクリプト向け) | 選ぶ機構--append-system-prompt | 理由システムプロンプトの末尾に追記し、既存の内容は消さない |
| リリース手順のような、ときどき使う手順書 | 選ぶ機構Skills | 理由呼ばれるまで本文を読み込まない |
| 編集のたびに必ず整形したい | 選ぶ機構hook | 理由Claude Codeが実行するので、指示への従い方に依存しない |
| 外部サービスへ接続したい | 選ぶ機構MCP | 理由3機構とも接続手段を持たない |
外部接続やサブエージェント・hooksとの境界はSkills・MCP・サブエージェント・hooksの4機構比較で扱っています。CLAUDE.mdの階層はCLAUDE.mdの三層構造にあります。
3つを同時に使う設定例
3つは同時に使えます。output styleの公式ページでも、CLAUDE.mdが知識、output styleが応答の仕方、hookが保証を担う組み合わせが例に挙がっています。ここではhookの代わりにSkillsを加えた構成を作ります。
三層構成の作り方
- 1
CLAUDE.mdに常時ルールを置く
「pnpmを使う」「コミット前にテストを実行する」のような、毎回の前提だけを書きます。
- 2
output styleでコミットの書式だけ変える
開発の進め方は変えたくないので
keep-coding-instructions: trueを付けます。.claude/output-styles/に置きます。 - 3
リリース手順はSkillにする
/releaseで呼ぶ手順書にし、勝手に走らないよう自動起動を止めます。
output styleのファイルは次の形です。
---
name: Commit voice
description: コミットメッセージを日本語の1行要約で書く
keep-coding-instructions: true
---
コミットメッセージは日本語で、50字以内の1行要約にしてください。Skillは .claude/skills/release/SKILL.md に置きます。
---
description: リリース手順を実行する。タグ付けと変更履歴の更新を含む
disable-model-invocation: true
---
1. 変更履歴を更新する
2. バージョンタグを付ける文書執筆やデータ分析のようにコードを書かない役割では、keep-coding-instructions を付けず、開発向けの指示を外したままにします。
指示が効かないとき、どの機構を疑うか
3つの機構が重なるほど、どれが効いていないのかが分かりにくくなります。切り分けの手がかりは次のとおりです。
claude --safe-modev2.1.287の claude --help では、--safe-mode をこう説明しています。CLAUDE.md、skills、プラグイン、hooks、MCPサーバー、output stylesなどの設定をすべて無効にして起動する、という指定です。ここで症状が消えるなら、原因はこれらの設定のどこかにあります。3つに加えてhookやプラグインも、1つずつ戻して調べます。
- output style: 値の綴りを見直します。
outputStyleは大文字小文字を区別し、frontmatterのYAMLが壊れていてもスタイルはファイル名で読み込まれるため、claude --debugでパースエラーを確かめます - CLAUDE.md: 読み込まれたファイルは
InstructionsLoadedhookで記録できます。長すぎる場合は/statusの警告に出ます - Skills: 自動起動を止めたSkillは、説明文もコンテキストに入りません。呼んでも走らないなら、
user-invocable: falseになっていないかを見ます
--bare は別の方向の絞り込みです。同じ --help の説明では、フックやCLAUDE.mdの自動探索などを省く最小構成で起動します。必要な文脈は --append-system-prompt や --add-dir で明示的に渡します。Skillsも自動では探索されず、--add-dir で渡したディレクトリの .claude/skills/ だけが読み込まれます。文体の指示が崩れる事例はClaudeの文章の癖が抜けない問題で扱っています。
まとめ
口調の指示をCLAUDE.mdに書くと、スタイルを切り替えたときに上書きされます。事実をoutput styleに書くと、スタイルを変えた瞬間に消えます。置き場所は、内容が事実か応答の流儀かで決まります。
効かないときに先に疑うのは、反映のタイミングです。次に outputStyle の綴りと大文字小文字、最後にSkillsの自動選択を見ます。必ず起きてほしい処理だけは、3つのどれでもなくhookに任せます。
よくある質問
サブエージェントは呼び出し元のoutput styleを引き継ぎますか
メインの会話とforkには適用されますが、それ以外のサブエージェントは自分のシステムプロンプトで動くので、スタイルは効きません。forkは親の会話とシステムプロンプトをそのまま引き継ぎます。
組織で3つを配布できますか
できます。output styleとSkillsは、管理設定ディレクトリの .claude/output-styles/ と .claude/skills/ に置きます。CLAUDE.mdは管理ポリシーの場所です。同名のSkillが複数の場所にあるときは、エンタープライズ、個人、プロジェクトの順で優先されます。
Skillsの context: fork は、会話のforkと同じですか
別物です。context: fork はskillの本文を新しいサブエージェントに渡して実行する指定で、サブエージェントはそれまでの会話履歴を見ません。会話の履歴が要る作業では、context: fork ではなく会話そのものをforkします。