概要
writing-skills スキルでできること
writing-skills は、Claude のようなエージェント向けのスキルを作成・改訂・テストする人のためのメタスキルです。クラシックな Test-Driven Development (TDD) の考え方をドキュメント作成に応用し、スキルを次のような状態にします。
- 実際のプレッシャーシナリオに基づいている
- 実在するエージェントの失敗事例で検証されている
- 抜け道を塞ぎ、自己正当化に強い形に磨かれている
writing-skills を使うことで、時間的プレッシャーやサンクコストバイアス、相反するインセンティブがあっても、エージェントがスキルを見つけ、従い続けられるような設計ができます。
writing-skills の対象ユーザー
writing-skills スキルは、次のような方に向いています。
- Claude などのエージェント向けスキルを作る 開発者
~/.claude/skillsや~/.agents/skills/のワークフローを標準化したい チームリード- 「読むだけでなく、実際に守られなければならない」スキルの責任を持つ ドキュメントオーナー
- ロールアウト前に、スキルが本当にエージェントの行動を変えているか検証する テスター
一般的な文章の書き方スタイルに特化したものではありません。効果的でテスト可能なエージェントスキルを書くことに特化しています。
このスキルが役立つ課題
writing-skills は、次のような状況を想定して設計されています。
- プレッシャー下でエージェントがスキルを無視したり、一部しか守らなかったりする
- 新しいスキルが本当に行動を変えているのか確信が持てない
- デプロイ前に subagents を使ってスキルを反復テスト できる仕組みがほしい
- 手探りではなく、Anthropic のスキル作成ベストプラクティス に沿いたい
- Graphviz を使って複雑なスキルのワークフローを可視化し、共有したい
一度きりのストーリーやメモのように機能しているスキルがあるなら、writing-skills を使うことでそれらを 再利用可能でテスト可能なリファレンスガイド に再構成できます。
writing-skills が向いているケース／向いていないケース
向いているケース:
- 規律を強制するスキル（TDD、検証、レビューのチェックリストなど）
- 実際に コンプライアンスコスト（時間、手戻り、出荷遅延）が発生するスキル
- エージェントが「今回だけ」とバイパスしがちなスキル
- 準拠率の改善を定量的に測りたいスキル
向いていないケース:
- 単なるリファレンススキル（例: API シンタックス、言語チートシート）
- そもそも違反できるルールが意図的に存在しないスキル
- TDD 形式のテストやプレッシャーシナリオを必要としない軽量なメモ
1 回限りの会話用に軽くメモを残したいだけなら、writing-skills は不要かもしれません。本番運用のプレッシャーを生き残るスキルにしたいなら、writing-skills が役に立ちます。
使い方
インストールと基本セットアップ
skills 対応環境に writing-skills スキルをインストールするには、次を実行します。
npx skills add https://github.com/obra/superpowers --skill writing-skills
このコマンドは obra/superpowers リポジトリから writing-skills スキルを取得し、他のスキルと並んで登録します。
個人用スキルは、通常はエージェントごとのディレクトリに配置します。例:
- Claude Code 用:
~/.claude/skills/ - Codex 等のエージェント用:
~/.agents/skills/
対象のスキルルート配下に writing-skills ディレクトリがあることを確認し、必要に応じて配置してください。これにより、必要なときにエージェントが SKILL.md と関連ファイルを読み込めます。
writing-skills の主要ファイルとフォルダ
インストール後、ワークフローを理解し実践するために最初に読むべきファイルは次のとおりです。
SKILL.md– writing-skills の中核となるスキル定義と概要。スキルに対する TDD の対応関係を含みます。anthropic-best-practices.md– Claude 向けの、簡潔で発見しやすく効果的なスキルを書くための公式スタイルのガイドライン。testing-skills-with-subagents.md– プレッシャーシナリオやテストキャンペーンの設計・実行方法を解説する実践ガイド。persuasion-principles.md– エージェントのスキル遵守を高めるための、エビデンスベースの説得パターン集。graphviz-conventions.dot– スキルのワークフローやプロセスを Graphviz 図として表現する際の慣例。render-graphs.js–SKILL.md内の ```dot ブロックを抽出し、SVG ダイアグラムとしてレンダリングするヘルパースクリプト。examples/CLAUDE_MD_TESTING.md– 複数のCLAUDE.mdバリアントを対象としたテストキャンペーンの完全な作業例。
これらを組み合わせることで、スキルの 作成 + テスト + 可視化 まで一気通貫で回せるワークフローが構築できます。
コアワークフロー: スキルに対する TDD
writing-skills は、TDD の考え方をそのままスキル作成に適用します。高レベルなループは次のとおりです。
-
テストケース（プレッシャーシナリオ）を書く
- エージェントが、意図したプロセスを省略・ゆがめて自己正当化しそうな現実的な状況を設計します。
- subagents を使ってこれらのシナリオを実行し、その行動を記録します。
-
ベースラインテストを実行して、失敗を観察する
- 新規または改訂中のスキルを ロードせずに シナリオを実行します。
- どこで失敗するか（何を省略し、どのように正当化し、どこを誤解したか）を具体的に記録します。
-
スキルを書く／改訂する
- 観察した失敗を解消するように
SKILL.mdと関連ファイルを作成・更新します。 - コンテキストウィンドウの制約を意識しつつ、簡潔で命令的な文体 を用います。
- 観察した失敗を解消するように
-
スキルをロードした状態でテストを再実行する
- 同じシナリオを、今度はスキルを有効にした状態で再度実行します。
- エージェントがスキルを発見・告知し、その指示に従うようになっているか検証します。
-
抜け道を塞ぐようにリファクタリングする
- 依然として残っている自己正当化や部分的な遵守を洗い出します。
- 説得の原則（権威、コミットメントなど）を適用し、遵守を強化します。
- 不要なトークンを削減し、スキルをより簡潔に保ちます。
このループは、クラシックな TDD における RED → GREEN → REFACTOR を、コードではなくドキュメントとプロセス遵守に適用したものです。
anthropic-best-practices.md を使ってスキルの質を高める
anthropic-best-practices.md には、Claude エコシステムに特化したガイダンスが含まれます。例えば:
- なぜスキルを 簡潔に することがコンテキスト利用効率やモデル性能の向上につながるのか
- Claude がどのように、いつ
SKILL.mdやその他のファイルをコンテキストウィンドウに読み込むのか - 各スキルセクションがトークンコストに見合う価値を持つように書く方法
このファイルは、自分のスキルをレビューするときのチェックリストとして活用できます。
- Claude が既に知っている説明は削る
- 実行可能なパターン・ルール・ワークフロー に焦点を当てる
- 最重要の指示が冒頭で明確に伝わるように構造を整える
writing-skills の TDD ループとこれらのプラクティスを組み合わせることで、スキルが 発見されやすく、効率的 な状態を維持できます。
subagents を使ったスキルのテスト
testing-skills-with-subagents.md は、TDD のアプローチをさらに踏み込み、具体的なテスト手法として整理しています。
- 本番で想定されるプレッシャー（時間、サンクコスト、スピード vs 品質）に近いシナリオを設計する
- メインエージェントの振る舞いを模した subagents でシナリオを実行する
- 失敗や自己正当化を構造化された形式で記録する
これは特に次のようなスキルに有用です。
- テスト先行開発など、時間のかかるベストプラクティスを強制するスキル
- 「早く出荷する」などの短期目標と競合するスキル（例: 十分な検証 vs スピード）
- 人間から明示的な「近道」のリクエストがあっても耐えなければならないスキル
このファイルのテストパターンに従うことで、エンドユーザーに届く前に、プレッシャー下でスキルが機能するか を検証できます。
説得の原則をスキル設計に取り入れる
persuasion-principles.md は、LLM の振る舞いにも影響する心理学的原則をまとめています。例:
- Authority（権威） – 安全に関わるルールには、明確で譲歩のない表現を使う
- Commitment（コミットメント） – スキル利用時に宣言させ、選んだプロセスを最後まで守らせる
- Scarcity（希少性） など – 重要なプラクティスに優先度を付けるために慎重に活用する
実務上は、次のように応用できます。
- 選択の余地がないステップには、より強い命令形を使う
- スキル利用時にエージェントに「I am using [Skill Name] now」と明言させる
- 流し読みではなく、必ず完了させることを前提としたチェックリストを設計する
目的は操作することではなく、重要なプラクティスが一貫して守られるようにすること です。
Graphviz でスキルフローを可視化する
複雑なスキルは、ビジュアルで表現したほうが理解しやすい場合があります。writing-skills には次が含まれます。
graphviz-conventions.dot– 図の構造やスタイルに関する推奨ルールrender-graphs.js–SKILL.md内の ```dot ブロックを抽出し、SVG ファイルに変換する Node.js スクリプト
レンダラーの基本的な使い方:
./render-graphs.js path/to/your/skill
# or
./render-graphs.js path/to/your/skill --combine
これにより、次のようなことが可能になります。
- スキルのフローを人間のコラボレーターと共有しやすくする
- プロセス設計の抜けや無限ループを視覚的に発見する
SKILL.mdに ```dot コードブロックとして図を埋め込み、ドキュメントとビジュアルを同期させる
writing-skills を自分の環境に合わせてカスタマイズする
このリポジトリで説明されているのは、そのままコピーするのではなく、環境に合わせてアダプトすべきパターン です。自分のワークフローに writing-skills を組み込む際は、次の点を意識してください。
- TDD ループは維持しつつ、シナリオのフォーマットは自分のツールに合わせて調整する
- ディレクトリ構造は独自のものでも構わないが、スキルの境界は明確に保つ
- 既存の CI・レビュー・リリースプロセスの中にテストキャンペーンを組み込む
目的は、チームとインフラにフィットした 再現性のあるテスト駆動のスキル作成ワークフロー を確立することです。
FAQ
writing-skills スキルはいつロードすればよいですか？
次のような場面では、writing-skills をロードして使うことをおすすめします。
~/.claude/skillsなどのディレクトリ配下に新しいスキルを作成するとき- 既存スキルが形骸化したり、無視され始めていると感じるとき
- チームメンバーや本番環境へのデプロイを控えたスキルを仕上げるとき
- subagents を使ったスキルのテストキャンペーンを設計・実行するとき
一時的な単発セッションで軽く試すだけなら、writing-skills のフルワークフローは必須ではありません。
writing-skills を使う前に TDD を理解しておく必要はありますか？
はい。writing-skills は superpowers:test-driven-development の理解を前提としています。RED → GREEN → REFACTOR のサイクルを知っていることを期待しており、それをドキュメントに適用します。
- RED: スキルなしでシナリオを実行し、失敗を記録する
- GREEN: そのシナリオが通るようにスキルを追加・改訂する
- REFACTOR: 明確さを高め、抜け道を塞ぎ、トークンコストを削減する
TDD が初めての場合は、先に TDD 関連のスキルをロードして学習してください。
writing-skills は Claude 固有の挙動にどう役立ちますか？
writing-skills は Claude のような環境を念頭に設計されており、リポジトリには Anthropic のドキュメントに沿ったガイダンスをまとめた anthropic-best-practices.md が含まれています。両者を組み合わせることで、次のようなことができます。
- Claude がスキルを確実に discover できるように書く
- context window とトークン予算を尊重した設計にする
- Claude が SKILL ファイルを適切にロードし活用できるような構造にする
Claude 向けのスキルライブラリを整備している場合、writing-skills は特に有用です。
非技術的・非コード系のスキルにも writing-skills は使えますか？
はい、そのスキルがシナリオを通じてテスト可能な 再現性のあるプロセス を扱っている限り、利用できます。例:
- インシデントレスポンスのチェックリスト
- コードレビューのワークフロー
- ドキュメントレビューや承認プロセス
重要なのは、そのプロセスに次のような特徴があることです。
- エージェントが守ることも破ることもできる明確なルールが存在する
- ステップを飛ばしたときに現実的な影響やコストがある
- 準拠状況をシナリオで有意味にテストできる
単なる説明文やストーリーのみのコンテンツは、writing-skills とは相性がよくありません。
examples/CLAUDE_MD_TESTING.md ファイルの役割は何ですか？
examples/CLAUDE_MD_TESTING.md は、次のような一連の流れをフルに示した作業例です。
- 時間的プレッシャーやサンクコスト、権威 vs スピードといった現実的なシナリオを設計する
- それらを複数の
CLAUDE.mdドキュメントバリアントに対して実行する - どのバリアントがスキルの発見・活用につながるかを比較する
自分のスキルテストキャンペーンを設計する際のテンプレートとして利用してください。
スキルはストーリーやケーススタディとどう違うのですか？
writing-skills のモデルでは、次のように考えます。
- スキル: 実績あるパターン・ツール・ワークフローを再利用可能なリファレンスガイドとしてコード化したもの
- ストーリー／ケーススタディ: 特定の問題を一度だけどう解決したかを記述したもの
writing-skills は、単発のストーリーを、将来のエージェントが新しい状況で見つけて適用できる 一般化されたテスト可能なスキル に変換する手助けをします。
スキルが長くなってしまいました。問題になりますか？
コンテキストウィンドウの制約があるため、長さは重要です。anthropic-best-practices.md では、簡潔なスキルがなぜ有利かを説明しています。
- 最初にロードされるのはメタデータだけですが、一度
SKILL.mdが読まれると、そのすべてのトークンが会話履歴とコンテキストを奪い合います。 - 各セクションが「本当にここにあるべきか」を常に問い直す必要があります。
writing-skills は次のような改善を促します。
- 冗長な説明を削る
- 必要に応じて、詳細な例は補助ファイルに分離する
- テストを通すうえで本質的な コアプロセスとルール を
SKILL.mdに集中させる
writing-skills が機能しているかどうかはどう判断できますか？
次のような変化が見られれば、writing-skills が効果を発揮していると判断できます。
- 以前はプレッシャー下で無視されがちだったスキルが、今は守られるようになった
- 新しいスキルが、単なるテキストではなく 明示的なシナリオとテスト を伴ってリリースされるようになった
- 特定のシナリオにおいて、スキルの有無でエージェントの振る舞いがどう変わったかを示せる
もしスキルの有無で行動の違いを示せない場合は、writing-skills が提供する TDD ループや説得／テストガイドに立ち返って見直してください。