skill-writing

スキルの作成

.agents/skills/ にプロジェクトローカルのスキルを作成します。相対シンボリックリンクを使って Claude Code に公開します。リポジトリの標準スキルバリデーターで結果を検証します。

プロンプト作成のガイダンス

新しいスキルとその内容は、特定のモデル向けではなく、現在の Claude モデルと GPT モデル向けに作成してください。スキルの文章でモデル名、モデルのバージョン、モデル固有のデフォルトを挙げないでください。model: フィールドや API パラメーターなど、モデルを選択、設定、または明示する内容は例外です。

スキルは、公式ベンダーガイドに基づいて作成してください。複雑なスキル、長時間実行するスキル、複数のツールを使うスキル、オーケストレーションを多用するスキルを設計または作成する前に、両方のガイドを読んでください。推奨事項は変更される場合があります。

• Anthropic のプロンプト作成に関するベストプラクティス： 現在のすべての Claude モデルを対象としています。モデル固有のガイダンステーブルから、モデルごとのプロンプト作成ページに移動できます。
• OpenAI の最新モデルガイド： 現在の GPT モデルファミリーを対象としています。プロンプト作成の推奨事項は、そのファミリーに属する 1 つのモデルでのテストに基づいています。

モデル名を挙げたアドバイスは、そのモデルで測定されたものとして扱ってください。モデル間のガイダンスが裏付ける場合に限り、ほかのモデルにも適用してください。ガイドがモデルごとに相反する修正を推奨している場合は、望ましい動作を直接記述してください。「簡潔に」や「もっと詳しく書く」のように、あるモデルのデフォルトを修正する指示は書かないでください。

以下の要約は、現在のモデル全般に当てはまるガイダンスを確認するためのものです。ガイドの代わりにはなりません。

• ユーザーの指示がスキルより優先されることを明記してください。
• 明示された前提のもとで、許可された作業を完了してください。避けるべき早すぎる停止と、望ましい停止を明記してください。テキストのみの応答は完了ではなく報告として扱ってください。
• 作業に取りかかる前に、関連する情報源を調べてください。
• 文体、進捗報告、委任に関する希望を明記してください。モデルのデフォルトに任せないでください。
• 一般的な文体の助言ではなく、避けるべき具体的なパターンを挙げてください。
• 検証の度合いは変更の規模に応じて調整してください。
• さらに考えるよう促すのではなく、作業量を適切に調整してください。応答文で推論を求めてはいけません。

STE に準拠した作成とレビュー

スキルの文章を作成または変更する前に、references/asd-ste100.md を最後まで読んでください。説明、指示、参照資料、例、エージェント向けメタデータの説明には、同資料の STE に基づくプロファイルを適用してください。完了を報告する前に、意味と文体をレビューしてください。義務の強さと保護対象の技術情報は維持してください。このプロファイルは、ASD 辞書への公式な準拠を保証するものではありません。

入力

• skill-name（任意）：my-skill のような、ケバブケースの名前です。省略された場合は、スキルの目的を表す、最短かつ一意なケバブケースのドメイン名を導き出してください。文脈としてリポジトリ名やアプリ名を繰り返さないでください。たとえば budget-price-estimator ではなく price-estimator とします。名前を導き出した場合は、完了報告でその名前を明記してください。指定された名前が無効な場合、または既存のスキルと競合する場合に限り、作業を中止してください。手順 2 の競合確認を参照してください。

--global、明示的な保存先パス、その他のスコープ上書きは拒否してください。サポートされるスコープは、コマンドの作業ディレクトリのみです。

ワークフロー

1. リポジトリカタログのガードを適用する

プロジェクトローカルのパスを解決する前に、コマンドの作業ディレクトリに適用されるリポジトリの指示を読んでください。それらの指示にスキルのソースカタログとライフサイクルが定義されている場合は、このワークフローを中止してください。そこで定められたリポジトリ固有のワークフローに従ってください。その場合、.agents/skills/ または .claude/skills/ のパスを作成してはいけません。

2. ローカルのスコープを解決して検証する

<scope> は、スキルが呼び出された作業ディレクトリに設定します。ソースは <scope>/.agents/skills/<name>/ に作成します。Claude Code のシンボリックリンクは <scope>/.claude/skills/<name> に作成します。ネストされたプロジェクトまたはワークスペースから呼び出された場合、スコープをリポジトリのルートに変更しないでください。~/.agents、~/.claude、~/.codex、またはその他のグローバルインストールディレクトリの下に、スキルを作成したり変更したりしないでください。

シンボリックリンクのターゲットには、常に相対パス ../../.agents/skills/<name> を指定します。

書き込む前に、ソースディレクトリまたはシンボリックリンクのパスがすでに存在する場合は処理を中止してください。

3. 現行フォーマットのソースを読む

scripts/fetch-agentskills-spec.sh のパスを、このスキルのディレクトリを基準に解決します。scripts/fetch-agentskills-spec.sh [--refresh] を一度実行します。返されたファイルを最後まで読みます。このヘルパーは、整合性が検証済みの仕様を 24 時間再利用し、それより古いエントリは条件付きで再検証します。ライブ取得に失敗した場合、7 日以内に検証されたキャッシュを返すことがあります。デフォルトのユーザーキャッシュの場所を利用できない場合、または書き込みできない場合は、AGENTSKILLS_CACHE_DIR を設定します。

明示的に最新版が必要な場合、変更に左右される作業、ポータブル形式のガイダンスに異論がある場合、またはバリデーターの動作と食い違う場合は、--refresh を使用します。stale の結果が返された場合は、使用前に読みます。完了報告には、検証日時と取得失敗を明記してください。ヘルパーが有効なファイルを返せない場合は、書き込みを開始する前に処理を中止します。agentskills.io の仕様を直接取得したり、リポジトリまたはスキルのインストール先にキャッシュを作成したりしないでください。

WebFetch を使って、最新の Claude Code frontmatter リファレンスを取得します。両方のソースで、フィールドの形式、命名規則、段階的開示の規約を確認します。フォーマットは変更されるため、推測しないでください。

4. コントラクトとレイアウトを定義する

コントラクトまたはレイアウトを選択する前に、references/writing-great-skills.md を最後まで読みます。ここでは、作成の原則、コンテンツの振り分け基準、ヘルパーのランタイムのデフォルト、コミュニケーションのコントラクトを定めています。

コントラクトを定義します。サポートされるすべての分岐で、ワークフローが必要とする、呼び出す、または作業を引き継ぐすべてのスキルを特定します。提案、例、関連スキルへの参照、および基盤となるツールの機能は依存関係ではありません。選択したレイアウトで必要と判断されたディレクトリだけを作成します。SKILL.md と agents/openai.yaml は常に必須です。

5. スキルを作成する

mkdir -p "<scope>/.agents/skills/<name>/agents"
# Add only the subdirectories the layout calls for:
# mkdir -p "<scope>/.agents/skills/<name>/scripts"
# mkdir -p "<scope>/.agents/skills/<name>/references"

<scope>/.agents/skills/<name>/SKILL.md を作成し、次の内容を記述します。

• Frontmatter はアルファベット順に並べ、description を最後に配置します。description の先頭には、検出時のトリガーフレーズを記述します。

• ルーティングで依存関係が特定された場合は、skill-dependencies 配列を指定します。同じリポジトリ内のスキルには名前のみを使い、外部スキルには ORG/REPO#SKILL を使います。対象スキル名（名前のみ、または # 以降の部分）、次に識別子全体の順に並べます。

  重複のない文字列を指定します。同じリポジトリ内の名前のみの依存関係はすべて解決してください。所有するスキル自身は、名前のみの依存関係として指定しないでください。バリデーターは外部リポジトリの存在を確認しません。依存関係がない場合は、このフィールドを省略します。

• 短い # タイトル を記述します。

• スキルの機能を説明する1行の要約を記述します。

• スキルが Claude のデフォルトと異なる場合に限り、disable-model-invocation: true または user-invocable: false を追加します。これらの値は省略するだけで表現できるため、disable-model-invocation: false と user-invocable: true は省略します。

• スキルが宣言するデフォルトのワークフローでリポジトリファイルを書き込まない場合、またはリポジトリのメタデータのみを書き込む場合に限り、coordination: exempt を設定します。これを設定する場合は、新しいスキルの本文に通常の文章としてこの宣言を追加します。以下のコードフェンスは、この作成用スキルの宣言を説明するものです。このスキル自体の宣言ではありません。

  This skill is coordination-exempt: skip the ai-coord gate for its declared work.
  

  宣言された動作を超える明示的に許可されたエスカレーションは、ゲートの対象に戻ります。

• ## Arguments（該当する場合）と、簡潔な命令形のワークフローを記述します。順序が重要な場合に限り、固定手順を使用します。それ以外の場合は、契約を示し、リポジトリ内の根拠に基づいて実行できるようにします。

• ワークフローで必要になる references/ の各ファイルへの明示的なリンクと、いつ参照するかを説明する1行の注記を記述します。

• バンドルされているすべてのヘルパーについて、引数、出力、デフォルト値、ランタイムコマンドを含む CLI シグネチャを記述します。これにより、エージェントはソースを読まずに実行できます。

命令形の文章を使用します。バンドルされている references/、scripts/、examples/、assets/ のパスは、所有するスキルのディレクトリを基準に解決します。実行時のエージェントが使用しない、リポジトリ形式のサポートファイルや作成用アーティファクトは追加しないでください。コロンの後にスペースが続く YAML のプレーンスカラーは引用符で囲んでください。囲まない場合、frontmatter パーサーが拒否する可能性があります。

<scope>/.agents/skills/<name>/agents/openai.yaml を作成し、次の内容を記述します。

policy:
  allow_implicit_invocation: true

allow_implicit_invocation は、SKILL.md の disable-model-invocation の反転値に設定します。後から Codex UI メタデータまたは MCP／ツール依存関係を追加する場合は、同じファイルに統合します。ポリシーは維持してください。

6. Claude Code のシンボリックリンクを作成する

Claude Code が独自の検出パスからスキルを検出できるよう、必ず相対シンボリックリンクを作成します。

mkdir -p "<scope>/.claude/skills"
ln -s "../../.agents/skills/<name>" "<scope>/.claude/skills/<name>"

7. 検証と報告

• パッチ適用ツールはファイルをモード 0644 で作成します。最初の検証を実行する前に、scripts/ と tests/ 内のすべての実行可能ファイルに chmod 755 を実行してください。スキャフォールドされたテストが初回実行時に Permission denied (os error 13) で失敗する場合は、このモードの問題です。
• test -f "<scope>/.agents/skills/<name>/SKILL.md"
• test -f "<scope>/.agents/skills/<name>/agents/openai.yaml"
• readlink "<scope>/.claude/skills/<name>" の結果が ../../.agents/skills/<name> と一致し、リンク先がソースディレクトリに解決されること。
• すべての scripts/* と tests/* の実行可能ファイルに test -x を実行し、chmod の漏れが後で権限エラーとして発生するのではなく、その場で確実に失敗するようにします。
• ai-skillet doctor --root "<scope>/.agents/skills/<name>" が 0 で終了すること。これがローカルのスキーマとポリシーを確認する正式なゲートです。
• 作成または変更したすべての文章の対象について、references/asd-ste100.md に従って意味とスタイルをレビューします。既存の文章はそのソースと、新しい文章は正式な仕様と照合してください。保護対象のコンテンツと精度に関する例外も明示的に確認します。
• 最後に ### 🧩 Skill created: <name>、作成したパスのツリー、および正確なチェック項目を記載した ### ✅ Verified を含めます。ファイルへのリンクには絶対パス .agents/skills/<name>/ を使い、.claude/skills/<name> シンボリックリンク経由にはしないでください。
• リクエストまたは継続的な指示で許可されている場合は、コミットします。許可されていない場合は、コミットを提案します。すでに得ている許可を再度求めないでください。

新しいスキルの出力仕様で別途求められていない限り、ヘルパーの標準出力、コマンド、パス、フロントマター、生成されたスキルのコンテンツには装飾を加えないでください。