agent-skills-creator

Agent Skills Creator

パターンの選択から検証、README の更新まで、Agent Skills のオープンフォーマットでスキルを作成、改善します。

• 対象: 新しいエージェントスキルの作成、および既存スキルの監査や書き直し：SKILL.md、参照ファイル、ルールフォルダー、スクリプト、評価。
• 対象外: AGENTS.md/CLAUDE.md 指示ファイル（agents-md を使用）および一般的なドキュメントの品質（ghostwriter を使用）。

モードを選択する

• 新しいスキル → 以下の作成ワークフロー。
• 既存スキルの監査、改善、または書き直し → references/improving-existing-skills.md。11 の監査項目を採点し、順序に沿って書き直した後、検証とリリースのためにステップ 5～8 を再利用します。
• スキルを簡素化する、またはコレクションを更新する → 同じ参照ファイルに加え、保持するかどうかの判断とコレクション台帳について references/capability-delta.md を参照します。
• スキルがまったく起動しない、誤ったプロンプトで起動する、または一覧が混み合っていて説明が短縮されている → references/evaluation-and-iteration.md のルーティング評価セクションを確認し、その後に説明を見直します。本文の編集ではルーティングの問題は解決しません。
• スキルが初稿の後で作業を止め、依頼されていないレビューのために作業を返してしまう → references/authoring-tips.md の「Say Where the Work Ends」を確認します。修正するのは手順ではなく、完了の範囲とレビューのチェックポイントです。

参照ファイル

ファイル	参照するタイミング
references/capability-delta.md	一般的なコーチングを削除する、モデルのアップグレードを評価する、またはコレクション全体を監査する場合
references/authoring-tips.md	本文の作成または削減時のデフォルト。ルールより判断を優先すること、制約の調整、権限と完了範囲、自由度、コンテンツパターン、説明
references/skill-patterns.md	構造パターンを選択する場合
references/format-specification.md	ディレクトリ構成、仕様と Claude Code 専用のフロントマター、本文の置き換え、読み込みのセマンティクス、各ホストがどこからスキルを読み込み何ができるか、命名
references/rules-folder-structure.md	ルールベースの監査／リンティングスキルを構築する場合
references/improving-existing-skills.md	既存スキルを監査、採点、簡素化、または書き直す場合。コレクション監査でのモジュールレンズのルール
references/executable-code.md	スキルにスクリプトが含まれる、! でライブコンテキストを挿入する、パッケージに依存する、または MCP ツールを呼び出す場合
references/evaluation-and-iteration.md	evals/evals.json の作成、モデル間での採用判断のテスト、ルーティングテスト、制約のアブレーション、明示された目標に向けたスキルのヒルクライミング、またはスキルの改訂のレビューを行う場合
references/adopt-adapt-author.md	作成または採用の前に、作業の担当範囲を確認する、公開する範囲を選ぶ、またはサードパーティ製スキルを取り込む、適応する、置き換えるかを判断する場合

バリデーターは、機械的なゲートを示す唯一のローカルな基準です。リポジトリのルートから実行します。

skills/agent-skills-creator/scripts/validate.sh skills/<name>   # one skill
skills/agent-skills-creator/scripts/validate.sh --all           # every skill in the repo

作成ワークフロー

進捗を記録するため、このチェックリストをコピーします。

Skill creation progress:
- [ ] Step 1: Choose a pattern
- [ ] Step 2: Create directory and frontmatter
- [ ] Step 3: Write SKILL.md body
- [ ] Step 4: Add reference or rule files
- [ ] Step 5: Validate
- [ ] Step 6: Update README.md (and docs/skills.mdx where the repo has one)
- [ ] Step 7: Smoke-test installation
- [ ] Step 8: Evaluate and iterate

ステップ 1：パターンを選択する

スキルを作成する前に、その作業をすでに担当しているものがないか確認します。再利用と範囲の決定には references/adopt-adapt-author.md を参照してください。

シンプル／ハブ、ワークフロー、ルールベース、または混合型を選びます。references/skill-patterns.md には、各パターンの構成、リポジトリ内の例、問題とパターンの適合度を示す表があります。

Step 2: ディレクトリとフロントマターを作成する

skills/<name>/SKILL.md を作成し、1 行目に --- を置いて name と description を記述します。description は人間向けの要約ではなく、モデルを起動するための説明として書きます。何を行うのか、何を扱うのかに続けて、「Use when...」の後にユーザーが実際に使う表現を記載します。予算を超えると一覧で末尾から切り詰められるため、重要なユースケースを最初に置いてください。適用条件が伝わる範囲で、できるだけ短くします。インストール済みの description はすべてのセッションで読み込まれ、適用範囲を誇張すると役に立たないスキルまで読み込まれるためです。制限は validate.sh が適用するので、ルーティングのために記述し、制約の確認はスクリプトに任せてください。

ほかのフィールドを追加する前に、このスキルをどこで実行するか決めます。このコレクションでは、移植可能なフィールドを使い、実行環境に本当に必要な前提条件は compatibility に記載してください。ホスト固有のフィールドを使う場合は、最新のホストドキュメントを確認し、意図的にホスト固有のパッケージにしてください。ワークフローでデプロイ、送信、または支出を行う場合は、本文で認可の境界を明記し、安全なループについても同じように明示してください。本文には、この両側の範囲を記載します。これらの契約については、フォーマットのリファレンスで説明しています。

Step 3: SKILL.md の本文を書く

まず references/authoring-tips.md を読んでください。何をどの程度明確に記載するか、権限と完了の範囲、自由度、コンテンツのパターン、段階的な情報開示に関する判断基準が記載されています。Gotchas セクションは、実際に観測された失敗をもとに作成してください。これは、どのスキルでも最も有益な情報となる部分です。

Step 4: リファレンスまたはルールのファイルを追加する

• ワークフロー／混合型：references/ フォルダーを作成し、各ファイルへのリンクと「Read when」の条件を SKILL.md に記載します
• ルールベース：rules/ フォルダーを作成します。references/rules-folder-structure.md で _sections.md、_template.md、ファイル名の付け方について説明しています
• シンプル／ハブ型：ファイルを SKILL.md と同じ場所に置き、トラックの表からリンクします

コードを含むリファレンスを優先してください。既存の実装やテストスイートは、契約を説明する文章よりも確実に契約を定められます（「Reference-as-Spec」）。行数ではなく、読み込み条件に応じて分割してください。異なるタイミングで読む 2 つのトピックは、別々のファイルにします。

応用的な内容については、references/executable-code.md と references/format-specification.md にすべて記載されています。エージェントが組み立てる実行可能ファイルには scripts/ を使い、インストール済みの SKILL.md を基準に相対パスで解決します。Claude Code では ${CLAUDE_SKILL_DIR} に置き換えられます。スキルの呼び出し時に必ず必要となるデータ（diff、PR コメントなど）には、!`command` による注入を使います。スキルの有効中にだけ存在すべき PreToolUse ゲートには、hooks フロントマターを使います。毎回のセッションで再度尋ねることになるセットアップ情報には、config.json を使います。

Step 5: 検証する

skills/agent-skills-creator/scripts/validate.sh skills/<name>

出力では、ローカルのゲートとして採用された推奨事項を含め、フォーマット要件とプロジェクト内の規約が分けて表示されます。FAIL をすべて修正してください。メタデータと名前付けを別途確認するには、skills-ref validate <dir> を実行します。どちらのチェックも、動作の品質やすべてのホストとの互換性を保証するものではありません。

Step 6: README.md を更新する

該当するカテゴリ見出しの下にスキルの箇条書きを追加し、件数を更新します。validate.sh は両方を確認し、不足している項目を示します。リポジトリに docs/skills.mdx も含まれている場合は、そこにも同じ箇条書きを追加してください。

Step 7: スモークテストを実施する

インストール時の動作を変更した場合は、インストーラーで文書化されているローカルソースのオプションを使い、編集したローカルソースを使い捨てのインストール先にインストールします。読み込まれた SKILL.md と同梱のリファレンスまたはスクリプトを作業コピーと照合してください。編集内容のスモークテストでグローバルインストールを上書きしないでください。また、まだプッシュしていない変更の証拠として、リモートのデフォルトブランチをインストールしないでください。

ステップ 8：評価して反復する

references/evaluation-and-iteration.md。evals/evals.json にシナリオを 2～3 件記述し、最初の実行後にアサーションを追加して、スキルありとスキルなしを新しいセッションで比較します。この比較が継続するかどうかの判断基準です。スキルは、そのコストに見合うだけの改善をもたらす必要があります。ルーティングは should-trigger プロンプトと near-miss プロンプトで個別にテストします。各対象モデルでテストし、不要だと思われるルールはアブレーションします。ルールを削除してシナリオを再実行し、どれかが悪化した場合に限って、そのルールを残します。1 回のラウンドを超えて目標を追求するのは、この参照にある The Hillclimb Loop であり、agent-evals CLI を使って実行します。

注意点

• ~/.agents/skills/<name>/ にインストールされたコピーは、リポジトリへのリンクではなくコピーです。リポジトリを編集しても実行中のセッションには反映されず、古いコピーが黙って読み込まれるため、正しく見えていてもスキルが複数のコミット分遅れていることがあります。評価で編集済みのローカルソースが読み込まれていることを確認してください。
• 参照チェーンの読み込み失敗が起きた場合は、同じ依存関係を別の表現でごまかすのではなく、読み込み条件を SKILL.md に移してください。
• skills add の --agent は可変長引数で、スペース区切りです（--agent codex cursor）。次に - で始まる引数までを消費します。カンマ区切りのリストは要素ごとに検証され、無効な名前 1 つとして全体が拒否されます。空の ~/.codex/skills を見て、インストールに失敗したと判断しないでください。skillsDir が .agents/skills のエージェントはすべて共通として扱われ、~/.agents/skills/ にインストールされます。これらのエージェントはそこから直接読み込みます。
• toc-over-100-lines は、100 行を超える参照ファイルの最初の 20 行以内に ## Contents があることを求めます。それより下にある Contents 見出しはカウントされないため、ファイルは問題がないように見えても失敗します。
• 説明に「Use when」が含まれていない場合、description-triggers はただちに失敗します。一方、このフレーズがあってもトリガーワードが間違っていれば、何も失敗せず、単にルーティングされません。バリデーターではこれを検出できず、ルーティング評価でのみ確認できます。
• description-length は 1024 文字未満なら何でも合格します。また、個々の説明がすべて合格していても、説明を集めたときにホストの一覧表示の上限を超えることがあります。その場合、ホストはすべての説明を短縮し、「Use when」の節は最初に削られます。説明は単独ではなく、一覧でほかの説明と並べて評価してください。
• 「ここで停止し、結果をレビュー用に提示する」というステップは、ユーザーが作業全体を依頼していて、見ていない場合でも、現在の最先端モデルではタスクを終了させます。このステップは安全ルールのように読めるため、制約を削る際にもほとんど疑問視されません。その結果、実装を 1 つ手前で止めるスキルがリリースされます。

アンチパターン

• 仕様全体を参照ファイルではなく SKILL.md の本文に詰め込む
• 「2025 年 8 月以前は……を使用する」のような時期に依存する内容。ルールの根拠としてモデル名を挙げる場合も含む
• 本文がタスクではなくガイドラインである context: fork スキル。サブエージェントには規約だけが渡され、プロンプトがないため、何も返しません
• モデルがルーティングの判断材料にできない、helper、utils、tools、documents、data のような曖昧な名前

関連スキル

• AGENTS.md／CLAUDE.md の指示ファイルを監査する agents-md
• ドキュメントの品質を高める ghostwriter

メンテナンス専用：evals/evals.json には、このスキルを変更する人向けの動作シナリオとルーティングプロンプトが格納されています。ユーザーのタスク中に読み込まれることはありません。これは references/improving-existing-skills.md が求めるベースライン Phase A です。