skill-forge

Skill Forge

鉄の掟：スキル内のすべての行は、そのトークンコストに見合う価値を持たなければなりません。モデルの出力を改善しない、一貫性を高めない、信頼性を向上させない記述は削除してください。

スキルとは

スキルは、Claude のための「オンボーディングガイド」です。手続きに関する知識、専門分野の知見、付属ツールを備えた、汎用エージェントを専門エージェントへと変えます。

skill-name/
├── SKILL.md           # Required: workflow + instructions (<500 lines)
├── scripts/           # Optional: deterministic, repeatable operations
├── references/        # Optional: loaded into context on demand
└── assets/            # Optional: used in output, never loaded into context

前提：Claude はすでに非常に賢いということです。 Claude がすでに知っていることは追加しないでください。各段落について、「そのトークンコストに見合う価値があるか？」と問い直してください。

ワークフロー

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

Skill Forge Progress:

- [ ] Step 1: Understand the Skill ⚠️ REQUIRED
  - [ ] 1.1 Clarify purpose and concrete use cases
  - [ ] 1.2 Collect 3+ concrete usage examples
  - [ ] 1.3 Identify trigger scenarios and keywords
- [ ] Step 2: Plan Architecture
  - [ ] 2.1 Identify reusable resources (scripts, references, assets)
  - [ ] 2.2 Design progressive loading strategy
  - [ ] 2.3 Design parameter system (if applicable)
- [ ] Step 3: Initialize ⛔ BLOCKING (skip if skill already exists)
  - [ ] Run init_skill.py
- [ ] Step 4: Write Description
  - [ ] Load references/description-guide.md
  - [ ] Apply keyword bombing technique
- [ ] Step 5: Write SKILL.md Body
  - [ ] 5.1 Set Iron Law
  - [ ] 5.2 Design workflow checklist
  - [ ] 5.3 Add confirmation gates
  - [ ] 5.4 Add parameter system (if applicable)
  - [ ] 5.5 Apply writing techniques
  - [ ] 5.6 Add anti-patterns list
  - [ ] 5.7 Add pre-delivery checklist
- [ ] Step 6: Build Resources
  - [ ] 6.1 Implement and test scripts
  - [ ] 6.2 Write reference files
  - [ ] 6.3 Prepare assets
- [ ] Step 7: Review ⚠️ REQUIRED
  - [ ] Run pre-delivery checklist (Step 9)
  - [ ] Present summary to user for confirmation
- [ ] Step 8: Package
  - [ ] Run package_skill.py
- [ ] Step 9: Iterate based on real usage

ステップ 1：スキルを理解する ⚠️ REQUIRED

自問してください。

• このスキルは、Claude が単独ではうまく解決できないどのような具体的な問題を解決しますか？
• ユーザーはこのスキルを起動するために、実際にどのような言葉を入力しますか？
• 現実的な入力と期待される出力を含む、具体的な使用例を 3〜5 個挙げられますか？

不明点がある場合は、ユーザーに質問してください（一度にすべてを尋ねず、最も重要なことから始めます）。

• 「このスキルをどのように使うか、例を 3 つ挙げてもらえますか？」
• 「このスキルを起動するには、実際にどのような言葉を入力しますか？」
• 「どのような出力が理想的ですか？」

具体例を少なくとも 3 つ得るまでは、先に進まないでください。

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

具体例ごとに、次の点を確認してください。

1. 決定論的で繰り返し実行できる操作は何ですか？ → scripts/
2. 特定の手順で Claude が必要とする専門知識は何ですか？ → references/
3. 推論には使わず、出力で使うファイルは何ですか？ → assets/

主な制約：

• SKILL.md は 500 行未満にしてください。それ以外はすべて references/ に移します。
• 参照ファイルは分野ごとに整理し、ネストは 1 階層のみにします。
• 段階的な読み込み方法と整理方法については、references/architecture-guide.md を読み込みます。

ステップ 3：初期化する ⛔ BLOCKING

既存のスキルを編集している場合はスキップしてください。それ以外の場合は、次を実行します。

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

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

ステップ 4：説明を書く

これは、スキルの中でも特に重要性が見過ごされがちな部分です。説明によって、次の 2 点が決まります。

1. スキルが自動的に起動するかどうか
2. ユーザーが検索でスキルを見つけられるかどうか

キーワードを盛り込むテクニックと、良い例・悪い例については、references/description-guide.md を読み込みます。

重要なルール：「使用するタイミング」の情報を SKILL.md 本文に絶対に記載しないでください。本文が読み込まれるのは起動後なので、遅すぎます。

ステップ 5：SKILL.md の本文を書く

各サブステップで必要に応じて参照ファイルを読み込みます。

5.1 鉄の掟を定める

「このスキルを使う際、モデルが最も犯しやすい間違いは何か？」と問いかけます。 それを防ぐルールを書きます。SKILL.md の先頭、フロントマターの直後に配置してください。

→ 鉄の掟のパターンと危険信号については、references/writing-techniques.md を読み込みます。

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

次の要素を含む、進捗を追跡できるチェックリストを作成します。

• 省略してはならない手順には ⚠️ REQUIRED を付ける
• 前提条件には ⛔ BLOCKING を付ける
• 複雑な手順はサブステップにネストする
• 先行する選択に依存する手順には「（条件付き）」を付ける

→ チェックリストのパターンと例については、references/workflow-patterns.md を読み込みます。

5.3 確認ゲートを追加する

次の操作を行う前に、必ずモデルを止めてユーザーに確認させます。

• 破壊的な操作（削除、上書き、変更）
• 大きなコストがかかる生成操作
• 分析に基づく変更の適用

→ 確認ゲートのパターンについては、references/workflow-patterns.md を読み込みます。

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

このスキルが --quick、--style、--regenerate N のようなフラグからメリットを得られる場合：

→ $ARGUMENTS、フラグ、argument-hint、部分実行のパターンについては、references/parameter-system.md を読み込みます。

5.5 ライティングテクニックを適用する

出力品質を大幅に向上させるテクニックは 3 つあります。

1. 質問形式の指示：曖昧な指示ではなく、質問を使う
2. アンチパターンの文書化：してはいけないことを列挙する
3. 鉄の掟と危険信号：モデルが近道をしないようにする

→ 3 つすべてのテクニックと例については、references/writing-techniques.md を読み込みます。

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 を追加可能)
• description にトリガーキーワードと使用シナリオが含まれている
• README.md、CHANGELOG.md、その他の不要なファイルがない
• 初期化時に残ったサンプル/プレースホルダーファイルがない

品質

• 冒頭にアイアンローまたは核心的な制約がある
• ⚠️/⛔ マーカー付きの追跡可能なワークフローチェックリストがある
• 破壊的/生成的な操作の前に確認ゲートがある
• 曖昧な指示ではなく、質問形式の指示を使用している
• アンチパターン(やってはいけないこと)を列挙している
• リファレンスは最初にすべてではなく、段階的にロードされる

リソース

• スクリプトがテスト済みで実行可能
• リファレンスがドメインごとに整理され、1 階層の深さ
• 大きなリファレンスには目次がある
• アセットは出力で使用され、コンテキストにはロードされない

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

• すべてを 1 つの巨大な SKILL.md に詰め込む(500 行超)
• 「X のためのツール」のような曖昧な description
• ワークフローがない — モデルに自由にやらせる
• 確認ゲートがない — モデルがチェックされずに最後まで実行される
• 具体的なチェックではなく「品質を確保する」のような曖昧な指示
• README.md、INSTALLATION_GUIDE.md、その他のドキュメントファイルを含める
• 「使用する場面」の情報を description フィールドではなく本文に書く

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

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

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

ステップ 9: 反復

実際の使用後:

1. モデルがどこでつまずくか、または一貫性を欠くかに気づく
2. どのワークフローステップを改善する必要があるかを特定する
3. より具体的な指示、例、またはアンチパターンを追加する
4. 再テストして再パッケージ化する