write-skill

write-skill

skills/<name>/ の下に、呼び出し時に必要な動作だけを読み込む、簡潔なスキルを作成します。

ワークフロー

1. 不足している必須事項のみ確認します。機能、トリガー、非トリガー、ツール／スクリプトの要件、移植性を確認します。
2. 一意な kebab-case の名前を選びます。
3. SKILL.md をオペレーターカードとして作成します。実行する内容、実行するタイミング、出力の意味、注意すべき落とし穴を記載します。
4. 繰り返し発生する決定的な作業を減らせる場合にのみ、ヘルパーファイルを追加します。
5. 1 回だけ圧縮し、README に 1 行追加します。依頼がない限り、コミットしません。

テンプレート

---
name: <kebab-case>
description: <Concrete capability.> Use when <real phrases, file types, tools, or contexts>. Do NOT use <negative triggers if broad>.
---

# <name>

<One-line operational contract.>

## Usage / Commands / Routing

```bash
scripts/tool_or_helper.py <arg>
```

## Notes

- <What output shape means, or how to consume it.>
- <Hard rule, setup failure, safety boundary, or common mistake.>

説明

説明はルーティングの要です。まずここを最適化します。

• 3 人称、現在形で 1～3 文にします。
• 1 文目で具体的な機能を示します。
• 2 文目は Use when ... で始め、実際のトリガーフレーズ、ファイル形式、ツール、または状況を列挙します。
• レビュー、検索、ドキュメント、macOS、git、ブラウザー作業など、範囲の広い領域には Do NOT use ... を追加します。
• マーケティング用語、時間とともに変わる主張、「このスキルは次の場合に使用する」といった表現の重複は避けます。

本文

次の内容を残します。

• 実行可能なコマンド、または正確なワークフローの手順。
• 初回利用を妨げることが多いセットアップ確認。
• 簡潔な出力仕様。
• ルーティングの境界と安全上の落とし穴。
• コマンドや概念ごとに、具体的な例を 1 つ。

次の内容は削除します。

• 説明の内容を言い換えただけの概要。
• エージェントの動作を変えない限り、インストール、コントリビューション、プライバシー、トラブルシューティングのセクション。
• CLI のヘルプ、スキーマ、フラグの一覧、生成されたドキュメントの転載。
• プロンプト例や定型分析の繰り返し。
• README、リファレンス、ヘルパースクリプトにすでに記載されている詳細。

ツールスキル

• 決定的な作業は scripts/ または既存の実行ファイルにまとめます。
• SKILL.md は、呼び出し方法、出力形式、注意点を示すメニューにします。
• 「すべてのフラグについては Run <tool> --help を実行してください」と記載し、分かりにくいフラグだけを残します。
• 30～60 行を目安にします。セットアップが長い場合は、準備状況の確認を本文に残し、手順の詳細は 1 段階先に移します。

ワークフロースキル

• 観点、判断の順序、出力仕様を残します。
• スキルの核となる価値が構造にある場合を除き、厳格なフルテンプレートは避けます。
• レビュー系スキルでは、所見を先に示します。要約や称賛は任意です。
• 方針、例、ソースに関する注記は references/REFERENCE.md に分けます。出力形式スキルのように、例自体が指示となる場合は、例を本文に残します。

対象環境

共通スキルの対象は Codex、Claude Code、Pi です。タスクに関する知識、受け入れ基準、実行可能なヘルパーは共通化します。繰り返し可能な操作には、既存の CLI を優先します。ハーネス固有の動作は必要な場合にのみ分離し、その依存関係を明記します。別のハーネスのツール名、サブエージェント API、圧縮方法を指定してはいけません。

名前と説明は簡潔にし、タスクに特化させます。モデル固有の修正は、普遍的なルールとしてではなく、実際に確認された失敗に基づき、ローカル設定または関連するリファレンスに記載します。順序や安全性が重要な場合は、手順を詳細に記載します。それ以外の場合は、期待する結果と境界を説明します。

ユーザーが明示的な起動のみを選んだ場合、Claude／Pi ではフロントマターに disable-model-invocation: true を設定し、Codex では agents/openai.yaml に policy.allow_implicit_invocation: false を設定します。既存のメタデータとローカルのオーバーライドは保持します。呼び出し制御によって操作権限が付与されるわけではありません。自動的に役立つ運用スキルは引き続き見つけやすくし、制限対象の操作を実行する際に承認を求めます。

スキル間のポインターについては、否定形（Do NOT use for charts (use dataviz)）は、指定されたスキルが存在しない場合でも問題なく機能します。肯定形（run X first）はリンク先がなくなるため、必ず skills/ 内のスキルを指定してください。

最終確認

• 名前が一意のケバブケースになっています。
• 説明には具体的な Use when ... のトリガーと、必要な Do NOT use ... の境界が記載されています。
• SKILL.md は約120行未満で、ツールラッパーの場合は30〜60行が望ましいです。
• ヘルパーは文章中で重複して説明せず、呼び出されています。
• 他のスキルへの参照を含める場合は、skills/ に存在するスキル名を指定します。
• エージェントまたは OS のみが対象となる要件は、回避策を設けず compatibility: に記載します。
• スキルの目的または呼び出し方法が変わった場合は、既存のカタログ行を更新します。