skill-authoring-lifecycle

スキル作成ライフサイクル

Skill Steward マーケットプレイスの skills/ に、インストール可能なスキルパッケージを追加、レビュー、検証します。

使用するタイミング

• ユーザーがこのリポジトリに新しいスキルを追加したい場合
• 「このスキルをレビューして」や「この SKILL.md は有効ですか？」と依頼された場合
• npx skills との互換性を考慮して SKILL.md を作成する場合
• PR で skills/*/SKILL.md が変更された場合

フェーズ 1：作成ワークフロー

1. 意図を確認する — 意図が既存のスキルと重複していないか確認します。同じ大まかな目標を達成するもの、または同じライフサイクルの前半と後半にあたるものであれば、既存のスキルに統合します（ADR 0016）。
2. 例を集める — このスキルが起動されるべき具体的なユーザープロンプトを 2～3 個と、起動されるべきでないプロンプトを 1 個作成します。依頼に明確な使用パターンがすでに示されている場合に限り、省略できます。
3. リソースを計画する — スキルに必要なのが手順だけか、繰り返し発生する操作や失敗しやすい操作のための scripts/、詳細な知識のための references/、テンプレートや静的ファイルのための assets/ も必要かを決めます。
4. 名前を決める — Agent Skills のルールに従った kebab-case の名前を付けます。長さは 1～64 文字です（docs/STANDARDS.mdx を参照）。
5. ディレクトリを作成する — skills/{name}/ を作成します（ディレクトリ名は frontmatter の name と一致させます）。
6. テンプレートをコピーする — templates/skill/SKILL.md からコピーし、プレースホルダーを置き換えます。
7. 説明を書く — スキルの「内容」と「使用するタイミング」（ユーザーが使う起動フレーズ）を簡潔にまとめます。起動に不可欠な振り分け条件は、本文の「使用するタイミング」セクションだけでなく、説明にも記載します。
8. 出典を記載する — templates/skill/references/sources.md を基に references/sources.md を作成し、使用した仕様、リポジトリ、論文ごとに行を追加します。
9. 本文を書く — 番号付きの手順、例、出力形式を含め、500 行以内に収めます。
10. 評価 — 動作が重要な T1 スキル（STANDARDS を参照）では、references/evals.md と 2 件以上の evals/cases/*.yaml を用意します。それ以外のスキルでは、evals.md は任意です。
11. 任意のメタデータ — Codex アプリの UI メタデータ、呼び出しポリシー、またはツール依存関係が役立つ場合に限り、agents/openai.yaml を追加します。
12. 任意のリソース — 必要な scripts/、references/、assets/ ディレクトリのみを作成し、プレースホルダーのリソースは削除します。
13. スキルを登録する：

• 現在のリポジトリスキーマに従って、skills.sh.json にスキル ID を追加します。
• ルートの README.md にあるスキル一覧表に行を追加します。

14. 難しいスキルは事前にテストする — 広範囲に及ぶワークフローや失敗しやすいワークフローでは、自然なユーザープロンプトと加工していない成果物を使い、新しいサブエージェントまたはスレッドでテストします。検証プロンプトに、意図した回答、疑っているバグ、予定している修正を含めないでください。

Frontmatter テンプレート

---
name: {same-as-directory}
description: {capability + trigger phrases, 20-1024 chars}
license: MIT
type: governance
metadata:
  author: skill-steward
  version: "1.0.0"
  category: {marketplace|multi-agent|...}
---

フェーズ 2：レビューと監査のチェックリスト

skills.sh へのマージまたは公開の前に、スキルパッケージをレビューします。

スキルの一貫性

• ライフサイクル全体を網羅：エージェントがタスクの途中でツールを切り替えずに済むよう、スキルが（作成と検証などの）一連の作業全体をカバーしている
• 仕組みを含む：抽象的なルールや文化的なガイドラインが、それを適用する仕組みとともに含まれている

構成

• ディレクトリ名が kebab-case で、frontmatter の name と一致している
• ファイル名が大文字と小文字を含めて正確に SKILL.md である
• スキルフォルダー内に README.md がない（代わりに references/ を使用する）

Frontmatter

• name：1～64 文字で、[a-z0-9-] に一致し、先頭と末尾が - ではなく、-- を含まない
• description：1～1024 文字で、機能と起動するタイミングの両方を記載している
• リポジトリが MIT でない場合、license が設定されている
• metadata.version と metadata.author が設定されている
• スキルで git、ネットワーク、docker、または特定の製品が必要な場合、compatibility が設定されている
• agents/openai.yaml が存在するのは、Codex 固有の UI、ポリシー、依存関係のメタデータが役立つ場合のみ

本文

• 明確な番号付きワークフローがある
• 約 500 行以内（または references/ に分割されている）
• 相対ファイルリンクが 1 階層以内である
• 外部の主張について URL を記載した references/sources.md がある
• インストールコマンドが記載されている：npx skills add arenukvern/skill_steward --skill <name>

スクリプト（存在する場合）

• Shebang がある（bash または node）
• bash の場合は set -euo pipefail を使用している
• ログは stderr に、機械可読な出力は stdout に出力している
• 代表的なスクリプトを実際に実行しているか、スキップした理由を記録している

レジストリ（このリポジトリ）

• skills.sh.json にスキル ID がある
• ルートの README.md の表に行がある
• pnpm run validate が成功する（sources.md の警告なし）
• T1 の動作に関わる変更：evals/cases/*.yaml と pnpm run eval

フェーズ 3：非推奨化と名前変更（Changesets）

リポジトリが煩雑になるため、恒久的な「墓標」スキルは残しません。その代わり、スキルの名前変更や統合は互換性を破る API 変更として扱い、標準的なエコシステムのツール（Changesets）を使って告知します。

スキルの名前を変更する、または統合する場合：

1. 古いスキルのディレクトリを安全に rm -rf します。
2. skills.sh.json と README.md から古いスキルを削除します。
3. 削除内容を記録したチェンジセット（pnpm changeset）を生成するか、.changeset/skill-consolidation.md ファイルを手動で作成します。削除した理由と、置き換え先のスキルを明確に説明します。
4. 変更履歴を読むエージェントやユーザーには、移行先が自動的に表示されます。

レビューの出力形式

次の形式で報告します：

## Summary
{pass | needs changes}

## Errors (blocking)
...
## Warnings
...

インストール

npx skills add arenukvern/skill_steward --skill skill-authoring-lifecycle

ソース

references/sources.md を参照してください。調査する際は、skill-source-citations に従ってください。