クロスエージェントSKILL.mdスキルの作成方法
スキルとは、SKILL.mdファイルを含むフォルダです。ファイルはYAMLフロントマターブロック（name + description）で始まり、その後にエージェントが必要に応じて読み込むMarkdown形式の指示が続きます。Claude Code、DeepSeek Harness (dsh)、Codex CLI、Gemini CLI、Copilot、Cursorはすべて同じ形式を読み取るため、適切に作成された1つのスキルがあらゆるエージェントで利用できます。
構成
my-skill/
├── SKILL.md # 必須: フロントマター + 指示
├── references/ # 任意: エージェントが必要に応じて読み込む長文ドキュメント
└── scripts/ # 任意: スキルが実行する可能性のあるヘルパースクリプト
---
name: my-skill
description: >-
1〜2文で説明: 何をするか、いつ使うか。これはエージェントがユーザーのリクエストと照合するトリガーです。ルーティングルールのように記述してください。
---
# My skill
ステップバイステップの指示。有能なエンジニアを想定し、具体的かつ明確に記述してください。漠然とした表現は避けてください。
スキルが機能するためのルール
nameはkebab-caseである必要があります — 小文字、数字、ハイフンのみ。最大64文字。エージェントは他の形式の名前を拒否または破損させます。aipxは自動的に正規化しますが、最初から正しく設定してください。descriptionはトリガーであり、ドキュメントではありません。 悪い例：「ものを扱うためのユーティリティ」。良い例：「URLからYouTube/Bilibili動画やポッドキャストを要約します。ユーザーが動画や音声リンクを貼り付けたときに使用します。」- SKILL.mdは約500行以内に抑えてください。 詳細は
references/*.mdに記述し、そこへのリンクを張ってください（例：「references/schema.mdを参照」）。エージェントはスキルがトリガーされた場合のみ本文を読み込みます。本文が大きすぎるとコンテキストを浪費し、動作が不安定になります。 - スキルを入れ子にしないでください。 スキル検出はスキルルートの直接の子のみをスキャンします。
skills/a/SKILL.mdは検出されますが、skills/a/b/SKILL.mdは検出されません。 - 相対リンクは相対のままにしてください。 SKILL.mdが
scripts/x.pyを参照している場合、フォルダ全体が一緒に移動します。スキルディレクトリの外部にリンクしないでください。
スキルの保存場所（ユーザールート）
| ルート | 読み取り元 |
|---|---|
~/.agents/skills/<name>/SKILL.md | DeepSeek Harness (dsh), Codex CLI |
~/.claude/skills/<name>/SKILL.md | Claude Code |
~/.gemini/skills/<name>/SKILL.md | Gemini CLI |
~/.copilot/skills/<name>/SKILL.md | GitHub Copilot CLI |
プロジェクトスコープの同等の場所も存在します（例：リポジトリ内の.claude/skills/、.agents/skills/）。手動でコピーしないでください。代わりにaipx syncを使用して、1つのコピーをすべてのエージェントルートにリンクしてください。
公開前のテスト
# パースおよび検出されるか確認
aipx install ./my-skill --dry-run
aipx install ./my-skill
aipx list
次にエージェントを開き、スキルが表示されることを確認します（Claude Code：スキルリストに表示されます。dsh：/コマンドパレット → Skillsグループ）。
公開チェックリスト
- リポジトリにスキルフォルダが安定したパスで含まれている（例：
skills/my-skill/） -
descriptionに機能だけでなくトリガー条件が記載されている - クリーンインストールで動作する（
aipx install owner/repo#path:/skills/my-skill） - 検出可能にするためGitHubトピックを追加する：
agent-skills、claude-code、dsh-plugin（dshバンドルも同梱する場合）、deepseek（DS関連の場合） - 任意：デュアルターゲットパッケージング —
dsh-plugin-devおよびclaude-plugin-devスキルを参照