Claude Codeでoutput styleを自作する実践パターン集

自作のoutput styleは、frontmatterと本文だけのMarkdownファイル1つです。組み込みのDefaultやExplanatoryで足りない役割(ドキュメント執筆・データ分析・レビュー専任など)を、既存のスタイルに近い型から作れます。切り替え手順や組み込みスタイルの詳細はoutput styleの基本ガイドに譲ります。本稿は自作、用途別のテンプレート、配布時の落とし穴を扱います。手元のClaude Code v2.1.287でclaude plugin initを実行した結果も載せます。

自作が必要になるタイミング

組み込みのProactive・Concise・Explanatory・Learningでカバーできない役割が欲しくなったら自作の出番です。毎回同じ前置きを打ち込んでいる、Claudeに特定の職能(レビュアー・アナリスト・教育係)を演じさせたい、といった状況が該当します。

たとえば、ドキュメントだけを書かせたいのに毎回コードを提案してくる。分析結果が長文で返ってきて表にまとめてほしい。実装前に設計方針を確認してほしいのに黙って書き始める。プロンプトを書き直せば解消しますが、セッションが変わるたびに同じ指示を繰り返すことになります。自作のoutput styleにしておけば、その職能を選ぶだけで再現できます。

前提として、/configから組み込みスタイルを切り替えたことがあり、.claude/settings.local.jsonに保存されることを知っている状態を想定します。切り替え自体が初めてなら、先に基本ガイドを読んでから戻ってください。

frontmatterに書けるキーはname・description・keep-coding-instructions・force-for-pluginの4つで、すべて省略できます。設計判断が要るのはkeep-coding-instructionsだけです。force-for-pluginはプラグイン配布のときにだけ意味を持ちます。

用途を1つに絞って設計する

自作スタイルの設計は、keep-coding-instructionsをtrueにするかfalseにするかの二択にほぼ集約されます。ここを最初に決めると、本文に何を書くかが自然に決まります。

判断に迷ったら、「このスタイルを選んだ状態でコードを書かせるか」を自問します。書かせないならfalse、書かせるならtrueが出発点です。

本文の書き方にも原則があります。CLAUDE.mdについて公式が述べる「後から守れたか確認できるほど具体的に書く」という原則は、output styleの本文にも使えます。「丁寧に対応する」より、後から守れたか判定できる指示のほうが再現性が上がります。「結論を1文で先頭に置く」「表以外の形式を使わない」「1回答は3段落まで」といった粒度です。

本文は有効なあいだ毎回のリクエストに乗るので、長く書くほど入力トークンが増えます。公式は、プロンプトキャッシュが効くので最初のリクエスト以降はその負担が軽くなると説明しています。

目的別テンプレート5パターン

ここからは実際に使える5パターンです。ファイル名がそのままスタイル名になるのでnameは省略できますが、区別のため明記しています。

最初の1つはkeep-coding-instructions: falseの代表例、ドキュメント執筆アシスタントです。

---
name: Docs Writer
description: 実装せず、ドキュメント執筆のみを行うスタイル
keep-coding-instructions: false
---
 
あなたはテクニカルライターです。コードの変更は提案のみに留め、ファイルの編集は行いません。
既存のREADMEやガイドの文体に合わせ、見出し構成を先に提示してから本文を書いてください。
専門用語には初出で簡潔な補足を添えます。

---
name: Data Analyst
description: 分析結果を表形式で返すスタイル
keep-coding-instructions: false
---
 
あなたはデータアナリストです。実装は行わず、渡されたデータや出力の傾向を分析して返してください。
結論を先頭に1文で示し、根拠となる数値はMarkdownの表にまとめます。
不確かな推測には「〜と考えられます」と明記し、断定しないでください。

---
name: Socratic Mentor
description: 実装前に設計判断を質問で確認するスタイル
keep-coding-instructions: true
---
 
実装に取りかかる前に、設計上の分岐点(データ構造・エラー処理方針・命名)を1つずつ質問してください。
回答を得てから実装に進みます。質問は一度に1つまでとし、矢継ぎ早に聞かないでください。

---
name: Commit Writer
description: 実装後に詳細なコミットメッセージ案を添えるスタイル
keep-coding-instructions: true
---
 
実装が終わったら、変更内容を要約したコミットメッセージ案を提示してください。
1行目は50字以内の要約、2行目以降に変更理由と影響範囲を箇条書きで示します。

---
name: JSON Only
description: 説明文を含めずJSONのみを返すスタイル
keep-coding-instructions: false
---
 
すべての応答をJSONのみで返してください。説明文・前置き・コードフェンスは付けません。
出力できない場合は {"error": "理由"} の形式で理由を返してください。

保存先と切り替え、反映のタイミング

ファイルの置き場所は3段階あります。

保存したら/output-style <スタイル名>か、/configのOutput styleメニューで選びます。反映の仕方は、ファイルを選ぶ操作と編集する操作で違います。

• スタイルの切り替えは、v2.1.251以降なら/clearなしで次のメッセージから反映される
• ターミナルでは、スタイルのファイルをClaude Codeの起動時に読み込む。セッション中に作成・編集したファイルは、Claude Codeを再起動して初めて拾われる

/output-styleは、v2.1.269以降は、ヘッドレス実行とAgent SDKでも使えます。Remote Control(モバイル・Web)から選べるのは組み込みスタイルだけです。VS Code拡張では、v2.1.257以降でOutput stylesメニューから選べます。v2.1.261以降はメニューから作成もできます。

v2.1.251より前は、切り替えが/clearか新セッションまで効きませんでした(公式のprompt-cachingのページ)。古い解説の/clear手順は今のバージョンに当てはまりません。

outputStyleを設定ファイルに直接書く場合、値は大文字小文字を区別します。explanatoryのように名前と一致しない値はDefaultスタイルになります。自作スタイルならname(省略時はファイル名)と同じ綴りで書きます。

plugin initの雛形をそのまま使うと何が起きるか

プラグインで配るなら、プラグインルートのoutput-styles/に置くか、plugin.jsonのoutputStylesキーで別のパスを指定します。このキーを書くと、既定のoutput-styles/の走査は置き換わり、併用されません。ゼロから作るならclaude plugin init <name> --with output-styleが最短です。

claude plugin init my-styles --with output-style

v2.1.287で空のホームディレクトリを使って実行すると、次の出力でした。

⚠ Found 1 warning:
 
  ❯ author: No author information provided. Consider adding author details for plugin attribution
 
✔ Created plugin "my-styles" at ~/.claude/skills/my-styles
  It will auto-load next session as my-styles@skills-dir. Run /reload-plugins to load it now.
  Disable: claude plugin disable my-styles@skills-dir. Remove: delete the directory.

生成物は、SKILL.md、.claude-plugin/plugin.json、output-styles/my-styles.mdの3つです。保存先はプロジェクトではなく~/.claude/skills/my-styles/で、プラグインとして次回起動時に自動で読み込まれます。plugin.jsonにはskills: ["./"]が入り、outputStylesキーは入りません。

注意したいのは、生成されるoutput-styles/my-styles.mdのfrontmatterです。

---
name: my-styles
description: TODO — one line shown in the Output style picker in /config
force-for-plugin: true
keep-coding-instructions: true
---

雛形はforce-for-pluginとkeep-coding-instructionsの両方がtrueで出てきます。force-for-plugin: trueは、プラグインが有効なあいだスタイルを自動で適用し、利用者のoutputStyle設定を上書きします。複数のプラグインが指定した場合に使われるのは最初に読み込まれた1つです。

ここまでを手順にすると次の流れです。

~/.claude/skills/配下に置いたプラグインでは、SKILL.mdの変更はセッション中に検出されます。output-styles/・hooks/・agents/・.mcp.jsonの変更は/reload-pluginsが要ります(公式のskillsページ)。チームメンバーに「更新したのに古いスタイルのまま」と言われたら、まずここを疑います。

配布方法の目安は単純です。1つのリポジトリで完結するなら、.claude/output-styles/にコミットするだけで足ります。複数のプロジェクトをまたいで配りたい、あるいはフックやコマンドと一緒に配りたいなら、プラグイン化すると管理が一箇所に集まります。作り方と公開手順はプラグイン完全ガイドにまとめています。

よくあるつまずき

個人スコープに置いてチームに配布されていない

~/.claude/output-styles/はホームディレクトリなのでgit管理下になく、チームメンバーの環境には存在しません。全員が使うスタイルは、.claude/output-styles/に置いてリポジトリにコミットします。

keep-coding-instructionsを役割と合わせ忘れる

自作の本文が「コードを書くな」という趣旨なのにkeep-coding-instructions: trueにすると、Claude Codeの組み込み指示を残す設定と、コードを書かせない本文が並びます。コーディングを含まない役割ならfalseに戻します。

frontmatterのキーを書き間違える

スペルを間違えたキーは、エラーなしで無視されます。たとえばハイフンをアンダースコアにしたkeep_coding_instructionsは効かず、既定のfalseのまま動きます。YAML自体が壊れていると、スタイルはファイル名だけで読み込まれ、frontmatterのキーはすべて空になります。原因が分からないときはclaude --debugでパースエラーを確認できます。

切り替えたのに本文の指示が守られない

output styleはClaudeに渡す指示であって、強制ではありません。公式も、毎回必ず起きてほしい処理(編集後の整形、コマンドのブロックなど)はhooksの領域だと整理しています。CLAUDE.mdやSkillsとの使い分けは3つの拡張機構の違いで比べています。

output styleが効く範囲にも限りがあります。メインの会話とフォークには適用されますが、他のサブエージェントは自分のシステムプロンプトで動くため、スタイルは反映されません。

まとめ

1人で使う職能は個人スコープで試し、チームで同じ出力が要る段階でプロジェクトの.claude/output-styles/へ移す進め方があります。複数のリポジトリへ配る段階になって初めて、プラグイン化の手間に見合います。