skill-authoring-workflow

目的

混乱を招かずに、PM スキルを作成または更新します。このワークフローでは、粗いメモ、ワークショップの内容、まとまりきっていないプロンプトの寄せ集めから、検証に合格し、実際にこのリポジトリに適合する skills/<skill-name>/SKILL.md アセットを作成します。

「これでよさそう」という運任せに頼らず、新しいスキルを公開したいときに使います。

入力

元となる資料と目的を用意してください。粗い状態でも問題ありません。このワークフローで仕上げていきます。

• 特に役立つもの： 元のコンテンツ（メモ、議事録、フレームワーク、プロンプトの手順）または更新したい既存のスキル
• あると便利なもの： 想定するスキルの種類（component／interactive／workflow）、対象読者、名前の希望

リクエストに情報を添えて入力した場合（例：「research/pricing-workshop-notes.md を対話型のアドバイザーに変換する」）、その情報を使ってフェーズ 1 からワークフローを開始します。すでに提示された情報を再度尋ねることはありません。何も入力されていない場合は、スキルに変換したいコンテンツを尋ね、ファシリテーションプロトコルに記載された開始方法を提示します。

例：Use skill-authoring-workflow: convert research/pricing-workshop-notes.md into an interactive pricing advisor.

主な概念

まずリポジトリ内のツールを使う

独自のプロセスを考案する前に、リポジトリに標準で備わっているツールや規約を使います。

• scripts/find-a-skill.sh
• scripts/add-a-skill.sh
• scripts/build-a-skill.sh
• scripts/test-a-skill.sh
• scripts/check-skill-metadata.py

適切な作成方法を選ぶ

• ガイド付きウィザード（build-a-skill.sh）： アイデアはあるものの、文章がまだ完成していない場合に最適です。
• コンテンツ優先のジェネレーター（add-a-skill.sh）： 元となるコンテンツがすでにある場合に最適です。
• 手動編集＋検証： 既存のスキルを仕上げる場合に最適です。

完了の定義（例外なし）

以下を満たした場合に限り、スキルは完成です。

1. フロントマターが有効である（name、description、intent、type）
2. セクションの順序が規約に準拠している（Purpose、Input、Key Concepts、Application、Examples、Common Pitfalls、References）
3. メタデータの上限を守っている（name は 64 文字以下、description は 200 文字以下）
4. 説明に、スキルが何をするか、いつ使うかの両方が書かれている
5. Input セクションに、ユーザーが用意できる情報、呼び出し例、入力内容を再度尋ねずにインライン入力を使うこと、入力が一部だけでも、まったくなくても問題ないことが、平易な言葉で明記されている。$ARGUMENTS のような実行時テンプレート構文は使わない（理由については CONTRIBUTING.md の「Why We Don't Use $ARGUMENTS」を参照）
6. Intent に、トリガーを示す Description を置き換えることなく、リポジトリ向けの詳しい要約が記載されている
7. 相互参照がすべて有効である
8. スキルを追加または削除する場合、README のカタログ件数と表が更新されている

ファシリテーションに関する唯一の参照元

このワークフローをガイド付きの会話として実行する場合は、やり取りのプロトコルとして workshop-facilitation を使用してください。

次の内容が定義されています。

• セッション開始時の案内と開始方法（Guided、Context dump、Best guess）
• 平易な言葉による、1 ターンにつき 1 つの質問
• 進捗ラベル（例：Context Qx/8、Scoring Qx/5）
• 中断への対応と一時停止／再開の動作
• 判断の分かれ目での番号付き推奨事項
• 通常の質問に対する番号付きのクイック選択肢（役立つ場合は Other (specify) を含める）

このファイルでは、ワークフローの手順とドメイン固有の成果物を定義します。矛盾がある場合は、このファイルのワークフローのロジックに従ってください。

適用方法

フェーズ 1：事前確認（作業の重複を避ける）

1. 内容が重複するスキルを検索します。

./scripts/find-a-skill.sh --keyword "<topic>"

2. 種類を決めます。

• Component：1 つの成果物またはテンプレート
• Interactive：適応型の質問 3～5 件と番号付きの選択肢
• Workflow：複数フェーズのオーケストレーション

フェーズ 2：ドラフトを生成する

元となる資料がある場合：

./scripts/add-a-skill.sh research/your-framework.md

ガイド付きのプロンプトを使う場合：

./scripts/build-a-skill.sh

フェーズ 3：スキルを磨き上げる

次の点を手作業で確認します。

• 「いつ使うか」が明確に示されている
• 具体例が1つあること。理想的には、異なるビジネス領域から2つ（SaaSを1つ、産業／非SaaSを1つ）用意し、フレームワークが幅広く適用できることを明確にします。リポジトリ内の架空の世界（SaaSにはFieldlight／Wrenchline、産業にはHelix／Northfield／Corvid）を再利用し、2つ目のファイルには領域を示す接尾辞を付けます（sample-industrial.md）。
• スキルが成果物を生成する場合は、品質チェック付きのコピーして記入できる出力スキーマとしてtemplate.mdを用意する
• 明示的なアンチパターンが1つある
• 水増し表現や曖昧なコンサルタント風の言い回しがない

フェーズ 4：厳密に検証する

コミットを考える前に、厳密なチェックを実行します。

./scripts/test-a-skill.sh --skill <skill-name> --smoke
python3 scripts/check-skill-metadata.py skills/<skill-name>/SKILL.md
python3 scripts/check-skill-triggers.py skills/<skill-name>/SKILL.md --show-cases

フェーズ 5：リポジトリのドキュメントに統合する

新しいスキルの場合：

1. 適切なREADMEカテゴリの表に追加する
2. スキルの合計数とカテゴリ別の数を更新する
3. リンク先のパスが解決できることを確認する

フェーズ 6：任意のパッケージ化

Claudeのカスタムスキルのアップロードを対象とする場合：

./scripts/zip-a-skill.sh --skill <skill-name>
# or zip one category:
./scripts/zip-a-skill.sh --type component --output dist/skill-zips
# or use a curated starter preset:
./scripts/zip-a-skill.sh --preset core-pm --output dist/skill-zips

例

例：ワークショップのメモをスキルにする

入力：research/pricing-workshop-notes.md
目標：対話型アドバイザーを新規作成する

./scripts/add-a-skill.sh research/pricing-workshop-notes.md
./scripts/test-a-skill.sh --skill <new-skill-name> --smoke
python3 scripts/check-skill-metadata.py skills/<new-skill-name>/SKILL.md

期待される結果：

• 新しいスキルフォルダーが存在する
• スキルが構造とメタデータのチェックに合格する
• READMEのカタログ項目が追加／更新される

アンチパターンの例

「便利なスキルを作ったが、検証を省略し、READMEの数を更新し忘れたまま出荷した。」

結果：

• 参照切れ
• カタログの数に不整合が生じる
• コントリビューターとユーザーが混乱する

よくある落とし穴

• 基準ではなく、その場のノリで出荷する。
• 実際にはコンポーネントのテンプレートが適切なタスクに、workflowを選ぶ。
• アップロード上限を超えるほど説明を長くする。
• スキルの内容だけを説明し、Claudeがいつ起動すべきかを示さない。
• 説明が200文字の上限に気づかないまま達し、文の途中で切れてしまう。
• 弱い起動条件の説明の代わりに、intentを使う。
• スキル追加後にREADMEの数を更新し忘れる。
• 生成された出力をレビューせずに最終版として扱う。

参考資料

• README.md
• AGENTS.md
• CLAUDE.md
• docs/Building PM Skills.md
• docs/Add-a-Skill Utility Guide.md
• AnthropicのClaude向けスキル構築の完全ガイド
• scripts/add-a-skill.sh
• scripts/build-a-skill.sh
• scripts/find-a-skill.sh
• scripts/test-a-skill.sh
• scripts/check-skill-metadata.py
• scripts/check-skill-triggers.py
• scripts/zip-a-skill.sh