SKILL.md オープン標準 · 三段階プログレッシブ開示 · Cursor / Claude Code 共通 · リモート Mac 検収
こんな方に向けた記事です。Cursor、Claude Code、Gemini CLI で Agent を使っているのに、デプロイ手順や PR の開き方、監査フローを毎回コピペしている——コンテキストが埋まり、Token 請求だけが増えていませんか。結論：手順を Agent Skill（YAML ヘッダ付き SKILL.md フォルダ）として封装すれば、Agent が必要なときだけ読み込み、会話をまたいで再利用できます。macOS スクリプトや Xcode 手順を含む Skill は、VNC リモート Mac をレンタルして scripts/ の出力を検収するのが現実的です。構成：Skill vs Rule → ファイル仕様 → 三段階ロード → 作成・移行 → ベストプラクティス → 2026 エコシステム → 実践例 → FAQ。
AI Agent の進化は「チャットボット → タスクアシスタント → 専門領域を持つエージェント」という流れがはっきりしています。従来の Prompt には三つの痛みがあります。複雑なフローを毎回説明し直すこと、無関係な Rule がコンテキストを占有すること、チームのノウハウがプロジェクト間で共有できないことです。
Agent Skill は「あることをどう実行するか」を再利用可能なモジュールにまとめます。必要時ロード、Token 節約、会話・チームをまたいだ共有が可能です。Anthropic が 2025 年末に agentskills.io オープン標準を推進して以降、Cursor、Claude Code、OpenAI Codex、Gemini CLI が同一の SKILL.md ディレクトリ構造に対応しています。
一言で言えば、Skill は AI Agent 向けの操作マニュアルであり、毎回ゼロから推論させるのではなく、適切なタイミングで正しい手順を実行させます。
反復作業：デプロイ・テスト・PR 説明を毎回 Prompt で書くと、1 回あたり平均 2k〜8k Token を余分に消費します。
コンテキスト汚染：500 行の規約を Rules に詰め込むと、無関係なファイル編集にも丸ごと載ります。
バージョン管理不可：口頭の約束は PR Review できず、新人 onboarding はチャット履歴のコピペに頼りがちです。
プラットフォーム分断：同じデプロイ手順を Cursor と Claude Code で二重管理——Skill 標準化後は Git で共有可能です。
| 比較軸 | Rule（ルール） | Skill（スキル） |
|---|---|---|
| ロードタイミング | 常時ロード | 必要時 / 関連時のみ |
| 適用場面 | 永続的な約束（命名、スタイル） | 複雑ワークフロー（デプロイ、監査） |
| コンテキスト占有 | 固定占有 | 動的で効率的 |
| トリガー | システムプロンプトへ自動注入 | Agent ルーティング + /skill-name |
| たとえ | 新人向け就業規則 | 専門操作マニュアル |
Skill でさらにできること：カスタム / コマンド（例 /deploy）、多段階ワークフローのパッケージ化、ドメイン知識の注入、Bash/Python/Node スクリプトの同梱、Hooks や MCP との連携です。当サイトのOpenClaw スキル市場実践は製品内プラグインの話です。本記事はエディタ横断の Skill ファイル形式を扱い、概念は近いもののエコシステムは異なります。
標準ディレクトリは次のとおりです（フォルダ名 = skill 名）：
.cursor/skills/
└── deploy-app/
├── SKILL.md # 必須
├── scripts/ # 任意：実行可能スクリプト
│ ├── deploy.sh
│ └── validate.py
├── references/ # 任意：必要時ロードの参考文書
└── assets/ # 任意：テンプレートと静的リソース互換パスには .agents/skills/（Claude Code、Codex、Gemini CLI）、~/.cursor/skills/（ユーザーグローバル）、~/.agents/skills/（ツール横断グローバル）があります。
--- name: deploy-app description: >- ユーザーが staging または production へアプリをデプロイしたいときに使用。 キーワード：デプロイ、リリース、本番、環境切替。 paths: - "apps/web/**" disable-model-invocation: false --- # アプリをデプロイ ## 実行手順 1. `scripts/validate.py` で環境変数の完整性を確認 2. `scripts/deploy.sh <environment>` を実行 3. ヘルスチェックエンドポイントが 200 を返すことを確認
| フィールド | 必須 | 説明 |
|---|---|---|
| name | はい | 小文字+ハイフン、フォルダ名と一致必須 |
| description | はい | ルーティングキー：トリガー条件を書く（要約ではない） |
| paths | いいえ | Glob で有効ファイル範囲を限定 |
| disable-model-invocation | いいえ | true なら手動 /skill-name のみ |
Agent Skills はプログレッシブ開示（Progressive Disclosure）を採用しており、公式ドキュメントと agentskills.io では三フェーズと説明されています。
発見フェーズ（起動時）：各 Skill の name + description のみ読み、現タスクとの関連を判定します。
活性化フェーズ（マッチ時）：完全な SKILL.md 本文を読み、手順どおり実行します。
オンデマンド（実行中）：references/ の詳細文書を読み、scripts/ 実行時は出力だけをコンテキストに戻します。スクリプト本体は Token を消費しません。
トリガー方法：自動（Agent が関連と判断、デフォルト）、手動 /skill-name、コンテキスト添付 @skill-name。危険操作を含む Skill は disable-model-invocation: true で人間確認後のみロードさせます。
参考数値：2026 年初時点で利用可能 Skill は 31,000 超とコミュニティ統計があります。これらをすべて Rules に入れると、1 回の会話コンテキストが 10 倍以上に膨らむ可能性があります。プログレッシブ開示により、Agent は「たくさんのマニュアルがあることを知りつつ、今必要な一冊だけ開く」動きができます。
最速ルート：Cursor Agent ダイアログで /create-skill を入力し、欲しい Skill を説明すると Agent がディレクトリと SKILL.md を生成します。
手動作成：.cursor/skills/your-skill-name/ に SKILL.md を新規作成し、frontmatter と手順を記述します。
任意スクリプト：反復コマンドを scripts/ に置き、本文から相対パスで参照します。
認識確認：Cursor Settings → Rules、または Agent セッション再起動で Skill が一覧に出るか確認します。
旧 Rule 移行：Cursor 2.4+ では /migrate-to-skills で dynamic rules と slash commands を Skill フォルダへ変換できます。
Windows メインの開発者が Cursor で Skill を書いたあと、scripts/ に bash、xcodebuild、notarytool が含まれる場合、ローカルでは真の実行ができません。推奨フローはGit でリモート Mac に同期 → VNC で Cursor またはターミナルを開く → Skill をトリガー → スクリプトの exit code とログを照合、です。キーチェーン、公証、TCC 権限が絡む手順はVNC 必須であり、当サイトのリモート Mac 権限チェックリストと同じ原則です。
① description はルーティングキーであり、要約ではありません。誤り：「この skill はデプロイ関連の指示を含む」。正しい：「ユーザーがデプロイ、本番、staging/production 切替に言及したときに使用」。
② プログレッシブ開示：SKILL.md は 500 行以内に抑え、詳細は references/、実行ロジックは scripts/ へ。
③ 単一責任：1 Skill は 1 領域に集中。「デプロイ + セキュリティ監査 + テスト作成」は 3 Skill に分割して組み合わせます。
④ 理由を説明：「環境変数欠落による起動失敗を防ぐためデプロイ前に validate.py を実行」と書き、「validate.py を実行」だけにしない。
⑤ Gather → Act → Verify：情報収集 → 実行 → 検証の順を明示すると、Agent が異常時にも対処を広げやすくなります。
⑥ 用語統一、パスはスラッシュ、エラー処理を明記：スクリプト失敗時にリトライ、ロールバック、中止のどれを取るか本文で決めます。
| カテゴリ | 代表 Skill | 用途 |
|---|---|---|
| 開発効率 | Prompt Lookup、Skill Installer、Ralph コーディングループ | 指示品質向上、他 Skill インストール、TDD 自律反復 |
| フロント / Web | React Best Practices、Web Design Audit、Next.js Cache Optimizer | Vercel 系パフォーマンス・アクセシビリティ監査 |
| ワークフロー | PR Skill、TDD Skill、Skill Writer | コミット→プッシュ→PR 作成、テスト駆動、メタ Skill |
| クリエイティブ | Remotion Video Editor | React で動画を記述しクリップ生成 |
エコシステム要点（2026）：agentskills.io がクロスプラットフォーム共通基盤です。Cursor Marketplace では Rules + Skills + MCP の組み合わせをワンクリックインストールできます。Monorepo では .cursor/skills/shipping/deploy-staging/SKILL.md のようなネストでスコープ分離も可能です。
MCP との関係：MCP は外部 API（DB、ブラウザ、GitHub）へ接続します。Skill は「いつ、どの順序で」それらのツールを呼ぶかを編成します。例えば PR Skill に「先に git status、次に GitHub MCP で PR 作成」と書けば、両者は補完関係であり代替ではありません。
シナリオ：毎回コミット → プッシュ → PR 作成 → 説明記入。Skill 指示：全変更をコミット → 新ブランチへプッシュ → gh pr create → テンプレートで説明を埋める。/pr 一発で完結します。
シナリオ：テストが通るまでコードを反復修正。Skill ロジック：テスト実行 → 失敗なら Agent が修正 → 再実行 → 成功までループ。Hooks と組み合わせれば CI 失敗時に Agent を自動起動できます。
シナリオ：Windows 開発者が xcodebuild archive、notarytool submit を含む Skill を保守。ローカル Cursor では Markdown 編集のみ可能です。真の検収は VNCMac リモート Mac：VNC 接続 → Skill トリガー → Agent がスクリプト実行 → キーチェーン「常に許可」を GUI でクリック。これは公証 staple 検収チェックリストと同じ「SSH だけでは足りない、VNC が要る」典型です。
| 検収項目 | ローカル Windows | リモート Mac + VNC |
|---|---|---|
| SKILL.md 編集 | 可能 | 可能 |
| bash デプロイスクリプト | WSL で一部可 | 完全な macOS 環境 |
| xcodebuild / 公証 | 不可 | 必須 |
| キーチェーン / TCC ダイアログ | 不可 | VNC で GUI クリック |
Skill は構造化されたガイダンスであり、強制実行ではありません。Model は依然として自律判断します。description と手順が明確なほど一貫性は高まります。コミュニティ Skill を入れる前に scripts/ の内容を読むことをおすすめします。
description のトリガー語句で実タスクをテストしてください。自動ロードされない場合は手動 /skill-name を試し、それでも失敗なら description 冒頭に同義語を追加します。
汎用ワークフロー（コミット、テスト作成）は ~/.cursor/skills/ へ。リポジトリ固有（内部 API、デプロイパス）は .cursor/skills/ に置き Git コミットします。
形式の理念は近い（再利用可能な能力モジュール）ですが、OpenClaw は ClawHub と Gateway プラグイン体系、Cursor Agent Skill は SKILL.md + agentskills.io 標準です。併用も可能で、OpenClaw が 7×24 Gateway、Cursor Skill が日常コーディングを担う構成はよく見られます。
Agent Skill は、チーム内で「ベテランだけが知っている」手順を、バージョン管理・Review・クロスプラットフォーム共有可能な SKILL.md に変えます。description にトリガー条件、本文に Gather-Act-Verify、スクリプトは scripts/ で Token 節約——この三つができれば、Agent は「毎回教え直す相手」から「マニュアルを開けば動く相手」へ変わります。
現実的な限界もあります。macOS ビルド、公証、キーチェーンを含む Skill は Windows ローカルでは書けるが検証できず、SSH のみのリモート Mac ではシステムダイアログをクリックできません。Agent を年間稼働させるチームには Mac mini 自前購入も合理的ですが、Skill ライブラリを構築中、または月次で iOS/macOS スクリプトを検収するだけの方には、VNC リモート Mac レンタルで「Skill を書く端末」と「Skill を走らせる端末」を分ける方が、 occasional 需要のためにハードを買うより経済的です。
Skill の価値は再利用にあり、再利用の前提は環境が動くことです。下記からリモート Mac プランへ進み、macOS 専用 Skill を VNC で検収できるノードを用意してください。