Skill Forge

鉄則：スキル内のあらゆる行はトークンコストを正当化する必要があります。モデルの出力をより良く、一貫性を高め、信頼性を向上させない場合は、削除してください。

スキルとは

スキルは Claude の「オンボーディングガイド」で、汎用エージェントから手続き知識、ドメイン専門知識、バンドルされたツールを備えた特化したものに変わします。

skill-name/
├── SKILL.md           # 必須: ワークフロー + 説明 (<500行)
├── scripts/           # オプション: 決定的で反復可能な操作
├── references/        # オプション: 必要に応じてコンテキストに読み込まれる
└── assets/            # オプション: 出力で使用され、コンテキストに読み込まれない

デフォルトの前提条件：Claude は既に非常に優秀です。 Claude が既に知っていないことだけを追加してください。すべての段落に異議を唱えてください：「これはトークンコストを正当化しているか？」

ワークフロー

このチェックリストをコピーして、完了した項目をチェックしてください：

Skill Forge進捗状況:

- [ ] ステップ 1: スキルを理解する ⚠️ 必須
  - [ ] 1.1 目的と具体的なユースケースを明確にする
  - [ ] 1.2 3つ以上の具体的な使用例を収集する
  - [ ] 1.3 トリガーシナリオとキーワードを特定する
- [ ] ステップ 2: アーキテクチャを計画する
  - [ ] 2.1 再利用可能なリソース (スクリプト、リファレンス、アセット) を特定する
  - [ ] 2.2 段階的なロード戦略を設計する
  - [ ] 2.3 パラメータシステムを設計する (該当する場合)
- [ ] ステップ 3: 初期化 ⛔ ブロッキング (スキルが既に存在する場合はスキップ)
  - [ ] init_skill.py を実行する
- [ ] ステップ 4: 説明を記述する
  - [ ] references/description-guide.md を読み込む
  - [ ] キーワード爆撃技法を適用する
- [ ] ステップ 5: SKILL.md の本文を記述する
  - [ ] 5.1 鉄則を設定する
  - [ ] 5.2 ワークフロー チェックリストを設計する
  - [ ] 5.3 確認ゲートを追加する
  - [ ] 5.4 パラメータシステムを追加する (該当する場合)
  - [ ] 5.5 執筆技法を適用する
  - [ ] 5.6 アンチパターンリストを追加する
  - [ ] 5.7 納品前チェックリストを追加する
- [ ] ステップ 6: リソースを構築する
  - [ ] 6.1 スクリプトを実装およびテストする
  - [ ] 6.2 リファレンスファイルを記述する
  - [ ] 6.3 アセットを準備する
- [ ] ステップ 7: レビュー ⚠️ 必須
  - [ ] 納品前チェックリストを実行する (ステップ 9)
  - [ ] 確認のためにユーザーに概要を提示する
- [ ] ステップ 8: パッケージ化
  - [ ] package_skill.py を実行する
- [ ] ステップ 9: 実際の使用に基づいて反復する

ステップ 1: スキルを理解する ⚠️ 必須

自分に問いかけてください：

• このスキルが解決する特定の問題は何か、Claude が単独では上手く対応できないものは？
• ユーザーが本当にこのスキルをトリガーするために入力するのは何か？
• 現実的な入力と期待される出力を伴う 3～5 つの具体的なユースケースは？

不明な場合は、ユーザーに聞いてください (一度にすべてを聞かないでください — 最も重要なものから始めてください)：

• 「このスキルをどのように使う 3 つの例を挙げてもらえますか？」
• 「実際に何と言ってトリガーしますか？」
• 「良い出力がどのようなものか説明してください」

少なくとも 3 つの具体的な例が揃うまで、先に進まないでください。

ステップ 2: アーキテクチャを計画する

各具体的な例について、問いかけてください：

1. どの操作が決定的で反復可能か？ → scripts/
2. Claude が特定のステップで必要なドメイン知識は？ → references/
3. どのファイルが出力で使用されるが推論には使用されないか？ → assets/

主な制約：

• SKILL.md は 500 行以下で保つ必要があります — その他すべては references/ に移動します
• リファレンスはドメインごとに編成され、ネストは 1 レベルのみ
• references/architecture-guide.md を読み込んで、段階的なロードパターンと編成戦略を確認してください

ステップ 3: 初期化 ⛔ ブロッキング

既存のスキルで作業している場合はスキップしてください。それ以外の場合は、以下を実行してください：

python3 scripts/init_skill.py <skill-name> --path <output-directory>

スクリプトは、鉄則プレースホルダー、ワークフローチェックリスト、適切なディレクトリ構造を含むテンプレートを作成します。

ステップ 4: 説明を記述する

これはスキルの最も過小評価されている部分です。説明は以下を決定します：

1. スキルが自動的にトリガーされるかどうか
2. ユーザーが検索で見つけるかどうか

references/description-guide.md を読み込んで、キーワード爆撃技法と良い例・悪い例を確認してください。

重要なルール：「使用時期」情報は SKILL.md の本文に入れないでください。本文はトリガー後に読み込まれます — 遅すぎます。

ステップ 5: SKILL.md の本文を記述する

各サブステップで必要に応じてリファレンスファイルを読み込んでください：

5.1 鉄則を設定する

「このスキルでモデルが最も犯しやすいたった 1 つのミスは何か？」と質問してください。 それを防ぐルールを記述します。SKILL.md の最上部、frontmatter の直後に配置します。

→ references/writing-techniques.md を読み込んで、鉄則パターンと危険信号を確認してください。

5.2 ワークフロー チェックリストを設計する

以下を含む追跡可能なチェックリストを作成します：

• ⚠️ 必須: スキップしてはならないステップの場合
• ⛔ ブロッキング: 前提条件の場合
• サブステップネスト: 複雑なステップの場合
• (条件付き) 前のステップの選択に依存するステップの場合

→ references/workflow-patterns.md を読み込んで、チェックリストパターンと例を確認してください。

5.3 確認ゲートを追加する

以下を実行する前にモデルを停止させ、ユーザーに確認を求めるように強制します：

• 破壊的な操作 (削除、上書き、変更)
• 大きなコストを伴う生成的操作
• 分析に基づく変更の適用

→ references/workflow-patterns.md を読み込んで、確認ゲートパターンを確認してください。

5.4 パラメータシステムを追加する (該当する場合)

スキルが --quick、--style、--regenerate N などのフラグから利益を得る場合：

→ references/parameter-system.md を読み込んで、$ARGUMENTS、フラグ、argument-hint、部分実行パターンを確認してください。

5.5 執筆技法を適用する

出力品質を劇的に向上させる 3 つの技法：

1. 質問形式の指示: 漠然とした指示ではなく質問を与える
2. アンチパターンドキュメント: 何をしてはいけないかを列挙する
3. 鉄則 + 危険信号: モデルがショートカットを取ることを防ぐ

→ references/writing-techniques.md を読み込んで、例付きで 3 つすべてを確認してください。

5.6 アンチパターンリストを追加する

「このタスクで Claude の怠け者的なデフォルトは何か？」と質問してください。次にそれを明示的に禁止します。

→ references/writing-techniques.md を読み込んで、アンチパターンの例を確認してください。

5.7 納品前チェックリストを追加する

具体的で検証可能なチェックを追加します。各項目は、モデルが出力を見て確認できるほど十分に具体的である必要があります。「品質の確保」ではなく「プレースホルダーテキストが残っていない (TODO、FIXME、xxx)」のようなものです。

→ references/output-patterns.md を読み込んで、チェックリストパターンと優先度ベースの出力を確認してください。

執筆の原則

• 簡潔性: Claude が既に知っていないことだけを追加する
• 命令形: 「入力を分析してください」ではなく「入力を分析する」
• 自由度と脆弱性のマッチング: 狭い橋 → 具体的なガードレール; 開放地帯 → 多くのルート
  • 高い自由度 (テキスト)：複数の有効なアプローチ
  • 中程度 (疑似コード/パラメータ)：推奨パターン、若干の変動可
  • 低い (特定のスクリプト)：脆弱な操作、一貫性が重要

ステップ 6: リソースを構築する

スクリプト

• 決定的で反復可能な操作をカプセル化する
• スクリプトはコンテキストに読み込まれずに実行します — 主要なトークン節約
• パッケージ化する前にすべてのスクリプトをテストする
• SKILL.md では、ソースコードではなく、コマンドと引数のみをドキュメント化する

リファレンス

• タイプではなく、ドメインごとに編成する
• ネストは 1 レベルのみ
• SKILL.md から明確な「いつ読み込むか」指示で参照される各ファイル
• 大きなファイル (100 行以上) は、最上部に目次を含める必要があります

アセット

• テンプレート、画像、出力で使用されるフォント
• コンテキストに読み込まれず、パスで参照されるだけです

→ references/architecture-guide.md を読み込んで、詳細なパターンを確認してください。

ステップ 7: レビュー ⚠️ 必須

スキル概要をユーザーに提示し、パッケージ化する前に確認してください。

納品前チェックリスト

構造

• SKILL.md は 500 行以下
• Frontmatter に name と description のみが含まれます (オプションで allowed-tools、license、metadata)
• 説明にはトリガーキーワードと使用シナリオが含まれます
• README.md、CHANGELOG.md、その他不要なファイルはありません
• 初期化から残されたサンプルプレースホルダーファイルはありません

品質

• 最上部に鉄則またはコアな制約がある
• ⚠️/⛔ マーカー付きの追跡可能なワークフロー チェックリストがある
• 破壊的/生成的操作の前に確認ゲートがある
• 漠然とした指示ではなく質問形式の指示を使用している
• アンチパターンをリストしている (何をしてはいけないか)
• リファレンスが段階的に読み込まれ、全て事前に読み込まれていない

リソース

• スクリプトはテストされ実行可能である
• リファレンスはドメインごとに編成され、1 レベル深い
• 大きなリファレンスは目次を含んでいる
• アセットは出力で使用され、コンテキストに読み込まれていない

避けるべきアンチパターン

• すべてを 1 つの大規模な SKILL.md に詰め込む (>500 行)
• 「X のツール」のような漠然とした説明
• ワークフローなし — モデルが自由にアドリブする
• 確認ゲートなし — モデルが完了まで無制限に実行される
• 「品質の確保」のような漠然とした指示ではなく、具体的なチェック
• README.md、INSTALLATION_GUIDE.md、その他のドキュメントファイルを含める
• 本文に「使用時期」情報を入れる、説明フィールドではなく

ステップ 8: パッケージ化

python3 scripts/package_skill.py <path/to/skill-folder> [output-directory]

パッケージ化の前に自動的に検証します。エラーを修正して再実行してください。

ステップ 9: 反復

実際の使用後：

1. モデルが苦労したり、一貫性がない場所を注意する
2. どのワークフロー ステップを改善する必要があるかを特定する
3. より具体的な指示、例、またはアンチパターンを追加する
4. 再テストして再パッケージ化する