mcpField
S
skill-writing

skill-writing

github.com/millioncoエージェントワークフロー3.6k84 回インストール29 週間前に更新
リポジトリ

skill-writing について

skill-writingは、エージェントスキルの作成とテストを支援する指示モジュールです。エージェントの失敗を記録し、新しい指示で動作が変わるか確かめる、テスト駆動の方法を示します。

主な機能

  1. 01作成前にスキル案をテスト
  2. 02RED・GREEN・REFACTORの手順
  3. 03起動条件の説明文に関する指針
  4. 04指示とチェックリストの構成パターン
  5. 05公開前の確認リスト

活用シーン

  1. 01繰り返し起きるエージェントの失敗に対応するスキルの作成
  2. 02スキルの起動条件の説明文の改善
  3. 03公開前のスキル確認

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/millionco/expect --skill skill-writing

インストール後、Claude Code で/skill-writingを入力して読み込まれたか確認します。

詳細

スキルの作成

スキルは、有効化されたときにエージェントのコンテキストに読み込まれる、指示をまとめたモジュールです。関連性の高いタイミングで焦点を絞った指示を提示できるため、エージェントの動作を制御するうえで最も効果の高い仕組みです。

鉄則

失敗するテストを先に実施せずに、スキルを作成してはいけません。 スキルを書く前に、対象タスクをスキルなしでサブエージェントに実行させます。そこで何を間違えるのか、具体的な正当化、近道、手順の省略を記録します。そのうえで、そうした失敗に対処するスキルを書きます。これはドキュメントに適用する TDD です。

TDD のステップスキルでの対応
REDスキルなしでシナリオを実行します。エージェントの誤りを記録します。
GREEN具体的な失敗に対処する最小限のスキルを書きます。エージェントが指示に従うようになったか確認します。
REFACTORエージェントが新たに考え出す正当化を見つけます。抜け穴を塞ぎ、再テストします。

スキルを作成するタイミング

作成する場合： 手法が自明でない場合、複数のプロジェクトで参照する場合、ほかの人にも役立つ場合、またはエージェントがスキルなしでは繰り返し失敗する場合です。

作成しない場合： 一度限りの解決策、ほかで文書化されている標準的な慣行、プロジェクト固有の規約（CLAUDE.md を使用してください）、またはリンターやフックで強制できる機械的な制約の場合です。

基本原則

指示に使える予算には限りがあります。 モデルが確実に従える指示は約150件です。システムプロンプトですでに約50件を使っています。指示を追加するたびに、すべての指示に対する遵守率が下がります。指示の枠を割く価値があるものだけを厳選してください。

周辺にある内容ほど注目されます。 最初と最後のセクションは、ほかの部分よりも大きな注意を引きます。重要なルールを途中に埋めると、見落とされます。

具体性が遵守につながります。 「監査の実行を検討してください」は無視されます。「RUN_COMPLETED を出力する前に accessibility_audit を呼び出してください」は守られます。

無条件の指示は条件付きの指示に勝ります。 「X を必ず呼び出してください」は有効です。「必要に応じて X を検討してください」は有効ではありません。

説明の最適化

description フィールドは、スキルをいつ有効化するかを制御します。エージェントはこれを読んで、「今、読み込むべきか」を判断します。ワークフローではなく、有効化する条件を説明してください。

悪い例： description: TDD のためのスキル — 最初にテストを書き、失敗を確認してからコードを書く 良い例： description: テストに競合状態、タイミングへの依存、または不安定な合否がある場合に使用します。不安定なテスト、停止するテスト、ゾンビプロセスを扱います。

説明のチェックリスト：

  • 有効化する条件に焦点を当て、「Use when...」で始めます
  • ユーザーが挙げる具体的な症状やエラーメッセージを含めます
  • 類義語を含めます（timeout/hang/freeze、cleanup/teardown/afterEach）
  • 関連性を示すツール、コマンド、ファイル形式を明記します
  • 500文字以内にします。頻繁に読み込むスキルは200文字以内にします
  • スキルの手順を要約してはいけません。要約すると、エージェントはスキル本体を読み込まず、説明に従ってしまいます

スキルの構成

.agents/skills/<skill-name>/
  SKILL.md          # Required. Under 200 lines.
  references/       # Optional. Heavy reference docs (100+ lines).
フロントマター
---
name: kebab-case-name
description: Use when [triggering conditions]. Covers [symptoms, tools, keywords].
---

動詞から始まる能動的な名前を使います。skill-creation ではなく creating-skills、async-helpers ではなく condition-based-waiting とします。

実行される指示を書く

まず役割を示し、次に制約を示す

役割を1行で示し、その直後に厳守すべき制約を置きます。前置きを重ねてから制約を示してはいけません。

# Browser Test Executor

You are executing adversarial browser tests against code changes.

REQUIRED for every test run:
1. Call accessibility_audit before completing
2. Call performance_metrics before completing
3. Call close to flush the session
完了条件を設けた番号付きチェックリストを使う

番号付きリストは、手順と網羅性を示します。タスクの「完了」を示す基準と結び付けてください。

Before marking the task complete, you MUST:
1. Run the linter
2. Run the type checker
3. Run the test suite
Do not skip any step. A skipped step is a failed task.

最後にある「省略してはいけません」は冗長ではありません。抜け道を塞ぐ役割があります。

ツールとコマンドは正確な名前を使う

「適切なチェックを実行してください」とは書かないでください。必ず call accessibility_audit や run pnpm typecheck と書きます。

必須の振る舞いは最後に置く

最後のセクションは、行動に移る直前に読まれる最後の内容です。譲れないチェックリストをそこに置いてください。

良い例を1つ、悪い例を1つ

説明を重ねるより、例を示すほうが効果的です。

**Bad:** `test the login page`
**Good:** `Submit login with empty fields, invalid email, wrong password, valid credentials. Verify errors and redirect.`

合理化への徹底的な防御

エージェントはルールを回避する理由をでっち上げます。あらゆる抜け穴を予測し、明示的に塞ぎましょう。

逃げ道を塞ぐ: すべての必須ルールの後に、次のように追加します:「『今回だけ』『十分に単純だから』『次回やる』といった例外は認めません。」

合理化テーブルを作成する — RED フェーズのテストから作成します。エージェントが行ったあらゆる言い訳が、スキルにおける明示的な反論になります:

エージェントの言い分スキルの応答
「この変更はテストするには小さすぎる」すべての変更はテストされます。サイズは免除の理由になりません。
「すでに手動で検証した」手動検証は代用になりません。ツールを実行してください。
「ユーザーはこれを求めていない」スキルが要求しています。ユーザーの沈黙はオプトアウトではありません。

レッドフラグリストを作成する:「これらのいずれかを考えている自分に気づいたら、止まってチェックリストに従ってください。」

アンチパターン

パターン失敗する理由
「適切なときに X の実行を検討する」条件付き + 曖昧 = 無視される
巨大なスキルファイル(200 行超)指示の予算を超え、遵守率が下がる
CLAUDE.md のルールを重複させる同じ指示のために予算を二度消費する
すべてのエッジケースを列挙する例を 20 個ではなく 1 つ示す — 残りはエージェントが推論する
「徹底的に」/「注意深く」雰囲気であって指示ではない。「徹底的」の意味を具体的に述べる
複数段落の正当化エージェントが必要とするのはルールであり、背景説明ではない。「なぜ」は最大 1 文
重要なルールを中央に配置プロンプト中央の盲点。上部または下部に移動する
まずテストせずにスキルを書くどの失敗に対処すべきか分からない。削除して RED から始める
ワークフローを要約した説明エージェントは完全なスキルを読み込む代わりに要約に従ってしまう

チェックリスト: リリース前

  • まずスキルなしでテストし(RED フェーズ)、失敗を文書化した
  • スキルは仮定の失敗ではなく、それらの具体的な失敗に対処している
  • 説明は「Use when...」で始まり、ワークフローではなくトリガー条件を列挙している
  • 合計 200 行未満
  • 必須の動作が上部または下部の番号付きチェックリストにある
  • すべてのツール/コマンドが正確に指定されている — 「適切な」や「関連する」は使わない
  • 曖昧な表現がない(「検討する」「適切なときに」「必要なら」)
  • 少なくとも 1 組の良い例/悪い例がある
  • CLAUDE.md や他のスキルと重複がない
  • 逃げ道が明示的な「例外なし」の文言で塞がれている
  • スキルを使って再テストし(GREEN フェーズ)、エージェントが遵守するようになった

コメント

Markdown 対応