writing-skills

writing-skills スキルの概要

writing-skills ができること

writing-skills スキルは、テスト駆動のワークフローで agent skills を作成・編集・検証するための Skill Authoring ガイドです。発想の核はシンプルですが、かなり明確です。つまり、スキル作成を「プロセス文書のための TDD」として扱うこと。最初に助言を書いてうまく機能することを期待するのではなく、まずプレッシャーがかかる状況を作り、スキルがない状態でどう失敗するかを観察し、その挙動を実際に変える guidance だけを書く、という進め方です。

writing-skills が向いている人

特に相性がいいのは、Claude Code、Codex 系の agent 環境、または同種のローカル skill directory 向けにスキルを作る人です。とくに、規律の徹底、検証ステップ、時間に追われると agent が飛ばしがちなワークフローを守らせたい場合に役立ちます。

本当に解決したい仕事

多くの人が必要としているのは、単なる「markdown の書き方の支援」ではありません。必要なのは、agent が実際に見つけ、従い、しかもスピード重視・過信・サンクコストによってプロセスを無視したくなる場面でも従い続ける SKILL.md を、再現性をもって作る方法です。writing-skills はその課題に向けて作られています。

generic prompt と何が違うのか

generic prompt でも、スキルのたたき台を作ることはできます。ですが writing-skills は、そのスキルが本当に挙動を変えるかを検証するための方法を提供します。

• プレッシャーがかかるシナリオを定義する
• スキルなしでベースラインのテストを行う
• 観測された失敗パターンに対応する形で文書を書く
• 再テストして抜け道をふさぐようにリファクタする

そのため、単発の「スキルを書いて」という指示より、Skill Authoring ではずっと実用的です。

重要な前提条件とトレードオフ

導入時の最大のハードルは、writing-skills がこのリポジトリの TDD 的な考え方をすでに理解している前提で作られていることです。スキル内でも superpowers:test-driven-development の背景知識が明示的に必要とされています。この土台を飛ばすと、書き方の助言が必要以上に厳しく感じられたり、なぜここまでテスト寄りなのか分かりにくくなったりします。

トレードオフも明確です。このワークフローは、直感でドラフトを書くより遅いです。ただし、失敗コストが高い場面や、agent がもっともらしい理由をつけてスキルを飛ばしがちな場面では、はるかに有効です。

writing-skills スキルの使い方

writing-skills のインストール先と前提

このリポジトリでは、個人用スキルは agent ごとのディレクトリに置く前提です。たとえば Claude Code なら ~/.claude/skills、Codex なら ~/.agents/skills/ です。obra/superpowers リポジトリから skill manager を使って導入する場合は、最終的にそのスキルが、実際に agent がスキャンするディレクトリに入っているか確認してください。

インストール前に手動で内容を確認するなら、まず次を読むのが近道です。

• skills/writing-skills/SKILL.md
• skills/writing-skills/testing-skills-with-subagents.md
• skills/writing-skills/anthropic-best-practices.md
• skills/writing-skills/examples/CLAUDE_MD_TESTING.md

最初に読むべきファイル

短時間で評価したいなら、次の順番で読むのがおすすめです。

1. メインのワークフローと位置づけを把握するための SKILL.md
2. スキルに対して RED/GREEN/REFACTOR をどう回すかを見る testing-skills-with-subagents.md
3. 端的な authoring guidance を得る anthropic-best-practices.md
4. 現実的なプレッシャーシナリオの例がある examples/CLAUDE_MD_TESTING.md
5. スキルが合理化に負けてはいけない場合の persuasion-principles.md
6. 図が必要なときだけ graphviz-conventions.dot と render-graphs.js

SKILL.md の冒頭だけを流し読みするより、この順番のほうが情報量と判断材料が増えます。

writing-skills に渡すべき入力

writing-skills は、テーマだけでなく具体的な証拠を渡したときに最も強く機能します。良い入力の例は次のとおりです。

• 作成または改訂したいスキルそのもの
• 変えたい agent の挙動
• スキルがない状態で起きた失敗例
• agent がプロセスを飛ばしたくなる状況
• スキルを置く対象ディレクトリとプラットフォーム

弱い入力:
“Help me write a testing skill.”

強い入力:
“Create a skill that forces pre-deployment verification for database migrations. Agents currently skip rollback checks when fixes seem obvious.”

ざっくりした目的を使える prompt に変える

writing-skills usage の使い方として有効なのは、最初から次の 4 点をまとめて要求することです。

1. プレッシャーシナリオ
2. スキルなしで起きる失敗のベースライン想定
3. スキル構成
4. 検証プラン

例:

Use writing-skills for Skill Authoring.

Goal: Create a skill for release-checklist enforcement in ~/.claude/skills/release-checks.
Observed failures: agents skip smoke tests when changes look small; they rationalize that CI is enough.
Need:
- 3 pressure scenarios that trigger those shortcuts
- baseline RED expectations without the skill
- a concise SKILL.md outline
- refactor ideas to close loopholes after first test run
Keep it concise and optimized for discoverability.

これは単に “a polished skill doc” を求めるよりはるかに強力です。なぜなら、そのスキルが何を修正すべきかという failure model が最初から入っているからです。

writing-skills の推奨ワークフロー

実務的には、次の流れが扱いやすいです。

1. 強制したい挙動を定義する
2. 2〜5 個のプレッシャーシナリオを書く
3. スキルなしで agent をテストする
4. 実際に出た合理化や近道を記録する
5. その失敗に対応する形でのみ SKILL.md を書く
6. スキルを読み込んだ状態で再テストする
7. まだ agent がすり抜ける箇所の文言を締める
8. 遵守率の改善に寄与しなかった説明を削る

最後のステップが重要です。同梱の best-practices では、トークン効率と簡潔な指示が重視されています。

テスト駆動の方法が特に効く場面

次のように、スキルに従うコストが発生するなら writing-skills for Skill Authoring を使う価値があります。

• 追加テストが必要
• 検証に時間がかかる
• ドキュメント確認が必要
• 再起動や手戻りが必要
• スピード優先のインセンティブと衝突するルールがある

逆に、API 構文のチートシートのような純粋な参照用スキルでは、agent が内容を意図的に回避する理由が少ないため、この方法の重要度は下がります。

subagent テスト資料の使いどころ

testing-skills-with-subagents.md は実務向けの補助資料です。平時に読むと正しそうに見えるだけのスキルではなく、実際のプレッシャー下でも機能するかを検証するのに役立ちます。必要になるのはたとえば次のようなときです。

• シナリオの書式が欲しい
• RED/GREEN/REFACTOR の対応づけを知りたい
• 合理化の記録方法を見たい
• プレッシャー起因の非遵守例を見たい

初稿が一見問題なさそうでも定着しないなら、このファイルが改善への最短ルートになりやすいです。

例のシナリオは参考にしつつ、そのまま写さない

examples/CLAUDE_MD_TESTING.md が useful なのは、実際のプレッシャーシナリオがどういう形になるのかを具体的に見せてくれるからです。時間圧、サンクコスト、権威、慣れによるバイアスなどが含まれます。ありがちな失敗は、関係のないスキルにそのままコピペしてしまうことです。

そうではなく、自分のワークフローに合わせてプレッシャーの種類を変換してください。たとえば:

• deployment skill → 緊急性と rollback への不安
• review skill → 過信とスピードバイアス
• security skill → 「今回だけは」という合理化
• style skill → 導入コストが低いので、テストも軽めでよい

persuasion guidance をどう組み込むか

persuasion-principles.md は飾りではありません。プロセス自体は明確でも、守られないスキルがあるから置かれています。agent がよく抵抗する行動を強制したいなら、より強い言い回しが効く場合があります。このファイルでは、authority、commitment、明示的な宣言など、具体的なパターンが示されています。

ただし使い方には注意が必要です。目的はスキルを大げさにすることではなく、必要な行動を「まあ今回は省いてもいい」と合理化しにくくすることです。

簡潔さのルールが出力品質を左右する

このリポジトリで特に価値が高いポイントのひとつが、skills はコンテキスト予算を共有する、という前提です。writing-skills が求めているのは「もっと書くこと」ではなく、「挙動を変える部分だけを書くこと」です。

良い兆候:

• 具体的なトリガー
• 明快で必須のアクション
• 現実の失敗に結びついた短い例
• 最小限の背景説明

悪い兆候:

• 長い動機づけの文章
• 定義の繰り返し
• プロセスの経緯説明
• Claude がすでに知っている generic な “best practices”

任意の graph ツール

skill directory には render-graphs.js が含まれており、SKILL.md から dot ブロックを抽出して、graphviz が入っていれば SVG 図を生成できます。これは任意機能で、主に分岐のある状態遷移や review gate を人が視覚的に確認したい場合に役立ちます。writing-skills skill を使うだけなら必須ではありませんが、プロセスの複雑さを maintainers が把握・調整する助けになります。

writing-skills スキル FAQ

prompt が書けるなら、writing-skills を入れる価値はある？

あります。課題が「速くドラフトを書くこと」ではなく「信頼性」にあるなら特に有効です。普通の prompt でも見た目の整ったスキルはすぐ作れます。writing-skills が効くのは、プレッシャー下でも最終的なスキルが agent の挙動を変えると確信したいときです。

writing-skills は初心者向け？

部分的には向いています。書き方そのものは読みやすいですが、方法論は TDD 的な考え方に慣れている前提があります。Skill Authoring に不慣れな人は、先にこのリポジトリの TDD 関連資料を読んだほうがよく、そうしないとワークフローを「不要に儀式的なもの」と誤解しがちです。

writing-skills が向かないケースは？

次のような場合は writing-skills を使わないほうがよいです。

• 単純な参照専用スキル
• 再利用前提ではない一回限りのメモ
• guidance に違反したくなる現実的な誘惑がないテーマ
• before/after のテストをまったく回せない状況

こうしたケースでは、より軽い authoring ワークフローで十分なことが多いです。

Anthropic の skill best practices とどう違う？

同梱の anthropic-best-practices.md は、簡潔で、見つけやすく、コンテキスト効率のよい skill writing に重点があります。writing-skills はそこに、より強い「行動変容」の視点を足します。まず失敗を観察し、それを修正する部分だけを書く、という考え方です。両者は競合ではなく補完関係にあります。

writing-skills を使うのに追加ツールは必要？

この方法の恩恵を受けるうえで、大きなツール要件はありません。重要なのは testing guidance と examples です。graph の描画は任意で、コアの authoring ワークフローに必須の補助スクリプトもありません。

既存スキルの編集にも writing-skills は使える？

使えます。むしろ有力な用途のひとつです。すでにスキルがあるのに agent が無視したり誤用したりするなら、writing-skills は実際の failure mode を特定し、不要な内容を削り、本当に効く指示へ書き直すのに役立ちます。

writing-skills スキルを改善する方法

理想の文書ではなく、観測された失敗から始める

writing-skills の結果を最短で良くする方法は、失敗の証拠を持ち込むことです。理想のプロセスだけを説明すると、出力は generic になりがちです。実際に agent が取った近道を示せば、できあがるスキルはより鋭く、短くなります。

より強いプレッシャーシナリオを用意する

良いシナリオは、agent がそのスキルを飛ばしたくなる本物の誘惑を作ります。次の要素を入れてください。

• 時間圧
• 過去の経験から来る自信
• サンクコスト
• 人間からの authority pressure
• 「修正内容は明らか」という framing

こうした条件があると、指示のどこが弱いか、どこが曖昧かが見えやすくなります。

agent の合理化をそのまま記録する

失敗を「スキルを無視した」と要約して済ませないでください。agent が実際に何と言ったか、あるいはどういう含みを持たせたかを残します。

• “This is a small change”
• “CI will catch it”
• “I already know this pattern”
• “Reading the skill would take too long”

こうした合理化が分かると、改訂後の writing-skills usage prompt と最終的なスキル文言で、何を正面から潰すべきかが見えてきます。

遵守が重要な箇所は文言を締める

スキルが「任意ではない行動」を徹底させるものなら、曖昧な言い回しは不利です。弱い提案表現を、明確なトリガーと必須アクションに置き換えてください。persuasion guide も役立ちますが、改善の主因は具体性です。

• いつスキルを読み込むのか
• 最初に何をするのか
• 何が省略不可なのか
• 何を成功とみなすのか

挙動を変えない内容は削る

writing-skills skill の出力でよくある失敗は、説明のしすぎです。ある段落が discovery、compliance、testing のいずれにも効いていないなら削ってください。このルールが repository の best-practices で中心に置かれているのには理由があります。

最初の pass で終わらせず、もう一段回す

最初に “GREEN” が出ても、簡単な条件でしか機能しないなら十分ではありません。もっと厳しい prompt や別の言い回しで再テストしてください。agent が急いでいるとき、確信しているとき、すでに終えた作業を守ろうとするときでも、そのスキルが効くかを確認します。

repository 固有の例と組み合わせる

チームに繰り返し出てくるワークフローがあるなら、対象スキルのドメインで短い worked example を 1 つ入れてください。抽象的なルールを増やすより、こちらのほうが adoption を改善することがよくあります。百科事典的に増やすのではなく、短く、プレッシャー下で試した例にするのがポイントです。

polish ではなく構造を要求して prompt を改善する

writing-skills を呼び出すときは、次を求めるのが有効です。

• scenario list
• failure analysis
• concise skill outline
• loophole-closing edits

最初から “make it polished” や “make it comprehensive” と言わないでください。たいていは長くなるだけで、compliance は改善しません。

そもそもそのスキルが必要かを確認する

writing-skills guide の資料から得られる有益な結論のひとつは、「そのテーマにはスキル自体が不要」という判断です。プロセスが明白で、低リスクで、繰り返しも少ないなら、スキルは行動上のメリットに対して保守コストだけ増やすかもしれません。それは妥当な結論であり、repository の質も上がります。

作成だけでなく、リファクタ用途で writing-skills を使う

writing-skills の価値がもっとも出やすいのは、既存スキルが失敗するのを見たあとにリファクタする場面です。そうすると、この方法は単なる文書ドラフトではなく、行動設計の手法になります。そこにこそ、この repository の実務的な価値があります。