make-skill — スキルを実証済みの方法で作成、改修、リリースする
動作中のリポジトリ（通常 ~/DATA/<name>）からコピー：ssheleg/super-ux
（マルチスキルスイート、Cursorルール）または ssheleg/task-pipeline
（シングルスキルオーケストレーター、リリース自動化）。make-skill 自体もこの規範に従って構築されています。
リファレンス — 必要に応じて読み込む
| 読むもの | タイミング |
|---|---|
references/agent-skills-spec.md | 任意の SKILL.md を作成または監査するとき — 両権威からのハードリミット、オプションフィールド、予算、誰が何を拒否するか |
references/authoring.md | 本文や説明を書いたり調整したりするとき — 命名、第三人称、自由度、スクリプトルール、評価ループ |
references/surfaces.md | Claude Code以外に出荷するとき — Skills APIアップロード/バージョン/1リクエストあたり8個、claude.ai zip、ネットワークなしの制限 |
references/enterprise.md | 他人のスキルをインストールするとき、またはフリートを管理するとき — リスク層、レビューチェックリスト、承認ゲート、ライフサイクル |
references/retrofit.md | 既存のスキル/リポジトリを監査するとき — 14項目のチェックリスト、エビデンスルール、個人スキルのショートフォーム |
references/host-capabilities.md | フック、サブエージェント、コマンド、スクリプト、またはMCP依存関係を出荷するとき — それぞれのメリットとコスト、フックイベントと終了コード、劣化条項 |
references/claude-code-plugin.md | Claude Codeプラグイン/マーケットプレイスとして出荷するものすべて — マニフェストスキーマ、コンポーネントレイアウト、パス変数、validate の失敗 |
references/distribution.md | リポジトリレイアウト、リリース、および5つのチャネルすべて — プラグイン、skills CLI、npx、Cursor、包括的なファミリーリポジトリ |
references/mcp.md, references/mcp-ship.md | スキル対 MCP サーバー、ラッピング — そして出荷：マウント、その404、server.json、レジストリ |
references/a2a.md | スキルが2つの自律エージェント（A2A）にまたがる場合：エージェントカード、タスクライフサイクル、委任 |
このコピーにない場合のフォールバック元：
raw.githubusercontent.com/ssheleg/make-skill/main/plugins/make-skill/skills/make-skill/references/<file>
ワークフローの選択
リクエストと $ARGUMENTS 内のパスから検出し、選択内容を通知します。
| 状況 | ワークフロー |
|---|---|
| 新しいスキル、このユーザーのエージェントのみ | 作成（個人用） |
| 新しいスキル、他の人/他のエージェントがインストール可能 | 作成（配布可能） |
| 既存のスキルまたはこの標準以下のリポジトリ、「これは仕様に合っているか？」 | レトロフィット |
| 個人スキルをインストール可能にしたい | 昇格 |
引数がない場合、質問する代わりに検出する：カレントディレクトリに SKILL.md、.claude-plugin/、
または plugins/*/skills/*/ がある場合 → レトロフィット監査を実行し、
ギャップテーブルと1つの次のアクションを報告します。何も検出されない場合 → 1行で何を作成するか尋ねます。
配布可能な作業は実際のプロジェクトです：コードの前に仕様（docs/superpowers/specs/）、
そして仕様は最初に対象プロジェクトのファイル契約を固定します —
スキルはその契約に対して記述され、アドホックではありません。
オーサリングルール（すべてのワークフロー）
最初に仕様の最低限 — オープン標準
および Anthropicのプラットフォームルール
はどちらも交渉不可です；この規範はその上に追加するだけです。 フィールドテーブル、その違い、
およびチェックリスト：references/agent-skills-spec.md。
name：references/agent-skills-spec.mdの文字ルール；ディレクトリ名と等しいこと。 落とし穴：決してanthropicやclaudeを含んではいけません — Claude Codeが喜んで読み込み、Skills APIがアップロード時に拒否する予約済み部分文字列であり、 そのため失敗は他人のマシンで表面化します。description：≤1024文字（このフィールド単独の上限であり、フロントマターブロック全体ではありません）、 山括弧なし、第三人称 — システムプロンプトに注入され、「私はあなたを助けることができます...」 では選択が低下します。何をするかといつ使用するかを記述します。- 移植可能なオプションセットは
license、compatibility、metadata、およびallowed-tools—references/agent-skills-spec.mdに制限と型があります。 licenseはオプションですが、それでも宣言してください、フロントマターとmarketplace.jsonプラグインエントリの両方で：ルートのLICENSEファイルは プラグインリストにもインストールされたスキルにも到達せず、エラーも発生しないため、ギャップが開いたままになります（ここにある6つのリポジトリすべて、2026-07-30現在）。- ホスト拡張は合法ですが、決して必須ではありません。 Claude Codeはさらにホスト専用の
セット（
references/claude-code-plugin.md）を読み取ります；他のエージェントはそれを無視するため、 これに依存するスキルは他のどこでも壊れます。仕様 ∪ ホストの範囲外 = タイポです。 - 本文は < 500行、< 5000トークンで、5%の余裕を保持します — 予算の99%にある本文は、
次の修正をバリデーターとの戦いに変えます。重い資料はスキルディレクトリ内の
references/、scripts/、assets/に1階層深く配置し、それぞれを本文からリンクして、 読み込みトリガー（「YのときにXを読む」）を記載します — 裸の「references/参照」は決して使わないでください。 100行を超えるリファレンスファイルは## 目次リストで始めます：部分的なhead読み取りが エージェントが得るものです。 - 落とし穴は
SKILL.mdに残します：エージェントは、存在すら知らない罠についてのファイルを 開くことを知ることができません。 - 主張する最も弱いサーフェスに対して記述します（
references/surfaces.md）： Claude APIコンテナにはネットワークがなく、パッケージインストールもなく、claude.aiは異なり、 Claude Codeだけが両方を持っています。pip installや curl を行うスクリプトはClaude Codeスキルです —compatibilityにそう記載するか、削除してください。サーフェス間で同期されるものはありません； gitが信頼できる情報源です。
仕様に追加するハウスルール：
- 散文は英語；リテラルは入力された言語のままにします。 キリル文字は4つの場所でのみ
生き残ります。そこでは文字列自体が重要です：トリガーフレーズ、拒否フレーズ
（オペレーターが両方を入力します — 翻訳されると、発言と一致しなくなります）、
固有名詞、言語の例（
«вы»/«ты»）。スタイルルールよりも予算ルールを優先します： ロシア語は英語の5.0（cl100k）に対して1.9〜2.3文字/トークンでエンコードされ、 8つのsshelegルーターを英語に書き直すと、意味を失うことなく 3408 → 1885トークン に削減されました。 descriptionは「Use when …」で始まり、具体的なトリガーフレーズをリストします — 英語とロシア語（ユーザーは両方で作業します）。誰もトリガーしないスキルは死重です。 ここでも5%の余裕を保持します（≤970/1024）：ニアミスの隣接は「NOT for …」句を強制し、 上限の98%にある説明にはそれを入れる余地がありません。- 1つの命名パターン、できれば動名詞（
processing-pdfs）；決してhelper、utils、tools、dataは使わないでください — 曖昧な名前はあらゆる選択で負けます。 - 1スキル = 1ジョブ。複数の関心事 → 複数のスキル + 共有契約ファイル。
契約はスキルディレクトリ内に配置します（
references/…）：skills CLIはスキル自身の ディレクトリのみを出荷するため、兄弟のskills/references/はClaude Codeプラグインとしては機能しますが、 他のすべてのエージェントでは壊れて到着します。スキル間で共有 → スキルディレクトリごとに 複製し、バリデーターで同一であることを確認します。 - 本文：命令形、手続き型、散文よりもチェックリスト；交渉不可の事項はそのように記載します。
規範の厳格さを脆弱性に合わせます — 破壊的または順序依存の作業には正確なコマンドを、
コンテキストが決定する場合には方向性のみを示します（
references/authoring.md）。 - 散文よりも評価を優先します： スキルなしで対象タスクを実行し、失敗を記録し、 それらに対して≥3つの評価を書き、その後合格する最小限のものを書きます； ベースラインなしで構築されたスキルは、想像上の問題を文書化します。既存のファミリーに 追加する場合 → インストールされているセットに対する共存を測定し、推測しないでください： あなたが名前を挙げる隣接は、通常最も近いものではありません。
- 単一コマンドのエントリポイントを出荷する：冪等 — 状態を検査 → 欠落部分を修復 → ステータスレポート →
正確に1つの推奨される次のアクション。検出モードで、決して質問しないでください。
スキルはそのコマンドです；呼び出し方法はチャネルによって異なります
（スキルディレクトリからは
/<skill>、プラグインとして/<plugin>:<skill>）— 1つを約束するのではなく、READMEに両方を記述します。 - ユーザーデータを決して上書きしない：存在しない場合のみシード；
--forceがある場合のみ上書き。
劣化契約（ホスト機能に触れるすべてのスキル）
フック、サブエージェント、/commands、プラグインパス変数、MCPサーバーはClaude Code内にのみ存在します —
スキルが実行される場所の少数派です。それぞれは、書面によるフォールバックを持つ加速器であり、
スキルはそれがなくても、より遅くても、依然としてジョブを完了します。 3つのケースを本文に、
エージェントの言葉で、それらが必要になる時点で記述します（形状：references/host-capabilities.md）：
- Claude Codeではない場合（Cursor、Codex、skills CLI、API）：フックなし、サブエージェントなし、
/commandなし。インライン手順に名前を付けます；バンドルされたscripts/は依然として 移動するため、チャネルごとにパスを指定します。 - 推奨プラグイン/スキルがない場合：一度、何が劣化しているかを述べ、手動パスを続行します。 オプションのコンパニオンがないために起動を拒否するステージは、厳格ではなく壊れています。
- ツール、インタプリタ、またはMCPサーバーがない場合：一度その旨を述べ、手動手順にフォールバックし、 ループで再試行しません。インタラクティブ認証は人間のステップです。
知っているが書いていないフォールバックは、フォールバックではありません。
このスキルが出荷する実用的な例 — これらをコピーし、自分の記憶は使わないでください
scripts/audit_skill.py は任意のスキルディレクトリを監査します（標準ライブラリ；レトロフィットの機械的な半分）、
Claude Code用に bin/make-skill-audit としてラップされています。その隣には：
hooks/（PostToolUse、SKILL.md が書き込まれた場合を除きサイレント）、
commands/skill-audit.md（意図的にスキル名ではない）、
agents/skill-auditor.md、および6つのスケルトン：assets/SKILL.template.md、
assets/plugin.template.json、assets/marketplace.template.json、
assets/hooks.template.json、assets/agent.template.md、
assets/command.template.md。
作成（個人用）
オーサリングルールに従って ~/.claude/skills/<name>/SKILL.md — 完了。リポジトリなし、
バージョン管理なし；次のセッションで読み込まれます。アップグレードパスとして昇格を言及します。
フック、エージェント、またはMCPサーバーが必要だが、まだリポジトリがない場合？
同じフォルダに .claude-plugin/plugin.json を追加します — Claude Codeはそれを
次のセッションで <name>@skills-dir として読み込みます。
作成（配布可能）
リポジトリツリー、公開リポジトリの最低要件、両方の claude plugin validate … --strict
実行、およびハウスバリデーターの仕様は references/distribution.md にあります →
配布可能なリポジトリレイアウト。最初のファイルの前にそれを開いてください。 何が関係するか：
.claude-plugin/marketplace.jsonをリポジトリルートに；プラグインはplugins/<name>/以下に、独自の.claude-plugin/plugin.jsonを持つ；スキルはplugins/<name>/skills/<skill>/に、references/、scripts/、assets/を その内部に持つ。マニフェストのみが.claude-plugin/に存在します — そこに埋められたコンポーネントは何も読み込まれず、プラグインはまだ動作しているように見えます。- バージョンの同期（ハードルール）： marketplace.json、plugin.json、package.json、および
トップのCHANGELOGエントリは同じ semverを保持し、一緒にバンプされます（
SKILL.mdがmetadata.versionを持つ場合はさらに5番目のポイント）。 - 両方の
--strict実行がグリーンであること、CIで、独自のジョブとして — これらはマニフェストのみを読み取るため、フロントマタールールは独自のtest/validate.pyに 存在し、ネガティブセルフテストが必要です：失敗できないバリデーターは飾りです。$schemaとdisplayNameをplugin.jsonとマーケットプレイスエントリの両方に出荷します （マーケットプレイスルートはどちらも受け入れません）。 - 公開リポジトリは、読者に対して英語優先のREADME、変更を検証するオフラインコマンドを含む
CONTRIBUTING.md、およびプライベートチャネルとインストーラーが触れるものを指定するSECURITY.mdを 提供する義務があります。
初回公開 — エンドツーエンド、同じセッション
すべてを完全に行い、中途半端な引き継ぎはありません。初回公開だけが人間を必要とします
（npm 2FA）；CI公開の準備は出荷の一部であるため、2回目は必要ありません。
11ステップのシーケンスは references/distribution.md → 初回公開 にあります。
完了 = 5つの検証された事実：リポジトリ + CIグリーン、npmがnpxで解決可能、プラグインが
インストールされた、skills-CLI検出が機能している、次のタグ公開が人間なしで動作する。
レトロフィット（既存のスキル/リポジトリを標準に適合させる）
最初に監査、次に修正、同じセッションで。項目ごとの評決：PASS / GAP / NOT-RUN、エビデンス付き —
file:line または実際に実行したコマンドの出力。「大丈夫そう」は評決ではなく、実行ではなく
推論されたチェックのPASSでもありません；ツールがないチェックは、理由付きで NOT-RUN であり、
PASSではありません。
最初にバンドルされた監査ツールを実行します — これは機械的な半分を決定論的に実行し、 設定されていない変数に依存することはありません：
make-skill-audit <skill-dir> --house # Claude Code：プラグインの bin/ が PATH にあります
他の場所では、これを読み取ったmake-skillディレクトリから scripts/audit_skill.py を実行します。
次に、references/retrofit.md の14項目チェックリストを処理します — 仕様の最低限、
プラグインの最低限、サーフェス、1ジョブ、エントリポイント、レイアウトとバージョン同期、
バリデーターとCI、評価、README、配布、リポジトリメタ、落とし穴、プロトコル、ホスト機能。
個人スキルには3項目のみが適用されます；そのファイルがどれかを示します。
その後： ギャップテーブルを報告し、今修正できるものはすべて修正し、マイナー/パッチ バージョンをバンプし、リリースチェックリストを実行します。
昇格（個人用 → 配布可能）
レイアウトに従ってリポジトリを作成し、スキルを plugins/<name>/skills/<skill>/ に移動し、
契約を references/ に抽出し、初回公開をエンドツーエンドで実行します。プラグインのインストールが
確認された後にのみ、古い ~/.claude/skills/<skill> コピーを削除します。
他人のスキルのインストール
スキルはエージェントが実行する指示と、それを読まずに実行するコードです —
スキルをインストールすることはソフトウェアをインストールすることです。自分で書いていないものは
すべて、最初に references/enterprise.md のレビューチェックリストを取得します。最もリスクの高い形状：
URLから指示を取得するスキル — そのコンテンツは、それを承認したレビューの後に変更されます。
プロトコル接続スキル（MCP / A2A）
スキルは指示です；能力を付与することはできません。エージェントに方法を教えることはスキルです。
ライブシステムに対する新しい能力は MCPサーバーです（mcp.md、次に mcp-ship.md で
マウントして公開します）。結果を別の自律エージェントに委任することは A2A です（a2a.md）。
両方のリファレンスはワイヤーレベルのルールを保持しています — ホストごとのツール名検出、
エージェントカード、および人間のステップとしてのインタラクティブ認証