Agent Skills 完全ガイド — 公開仕様からSKILL.mdの実務設計、skills.shのセキュリティまで

AIエージェントを使用していると、「スキル」「Agent Skills」「skills.sh」「MCP」「システムプロンプト」といった表現が一度に登場することがあります。名前が似ているため、同じ機関や製品のように見えますが、それぞれの役割は異なります。

まず最初に正すべき点は、Agent Skillsが機関名ではないということです。これは、AIエージェントに特定の業務手順、参考資料、実行コードをパッケージとして追加するための公開ファイル形式の名前です。Anthropicが最初に開発・公開し、現在ではClaudeだけでなく、ChatGPTやCodexなど、多くのエージェント製品がこの形式をサポートしています。

しかし、ISO、IEC、IETF、W3Cのような標準化機関が制定した国際標準ではありません。正確には、複数の実装が採用する公開相互運用フォーマットまたはオープン仕様に近いものです。

この記事では、以下の3つの点を区別して説明します。

Agent Skillsの公開仕様が実際に定義するもの
セキュリティ・監査業務用のスキルを安定的に作成するための実務設計
公開スキルを検索・インストールするskills.shとサプライチェーンセキュリティ

Agent Skillsは誰が作ったのか？

Agent Skills公式ドキュメントによると、この形式はAnthropicで最初に開発され、オープン形式で公開された後、多くのエージェント製品に採用されたと説明されています。共通仕様とドキュメントは、agentskills/agentskillsリポジトリで公開開発されています。

関係を単純化すると以下のようになります。

Anthropic
└── Agent Skills 형식 최초 개발·공개

Agent Skills 공개 사양
├── agentskills.io 문서
├── agentskills/agentskills 사양 저장소
├── Claude의 스킬 구현
├── ChatGPT·Codex의 스킬 구현
└── 기타 호환 에이전트 구현

Anthropicのskillsリポジトリは、現在Claudeで使用されている実装と例が中心です。リポジトリ自体も、共通標準に関する情報はagentskills.ioを参照するように区別しています。

OpenAIもまた、独自の同名規格を新たに作成したわけではありません。OpenAIのスキルに関するドキュメントには、ChatGPTとCodexのスキルが公開Agent Skills仕様に基づいていると明記されています。

したがって、次の文章が最も正確です。

Agent Skillsは、Anthropicが最初に開発・公開したAIエージェント用の軽量スキルパッケージ形式であり、現在、複数の製品が採用している公開相互運用仕様である。

図：Agent Skills仕様と各製品の実装、skills.shの役割関係 · Agent Skills Overview、OpenAI Build skills、skills.sh Documentationを基に再構成

Agent Skills仕様が定義する最小構造

スキルの核は、一つのディレクトリと、その中のSKILL.mdです。

aws-iam-policy-review/
├── SKILL.md              # 必須
├── scripts/              # オプション: 実行コード
├── references/           # オプション: ポリシー・ドキュメント・知識
├── assets/               # オプション: テンプレート・サンプル
└── 그 밖의 파일          # 必要に応じて追加可能

SKILL.mdは、YAML FrontmatterとMarkdown本文で構成されます。

---
name: aws-iam-policy-review
description: >
  Review AWS IAM policies for excessive permissions, privilege escalation,
  unsafe trust relationships, and missing conditions.
  Use when a user asks to assess or harden an IAM policy.
---

# AWS IAM ポリシーレビュー

1. 정책 문법을 확인한다.
2. Action, Resource, Principal, Condition을 분석한다.
3. 권한 상승 가능성을 분석한다.
4. 근거와 최소 권한 수정안을 제안한다.

Agent Skills公式仕様が要求するFrontmatterフィールドは、実質的にnameとdescriptionの2つだけです。



—	—	—	—
`name`	必須	1～64文字、英小文字・数字・ハイフン、ディレクトリ名と一致	スキル識別
`description`	必須	1～1,024文字	何をするか、いつ使うかを説明
`license`	オプション	ライセンス名またはファイル参照	配布・使用条件
`compatibility`	オプション	1～500文字	実行環境、パッケージ、ネットワーク要件
`metadata`	オプション	文字列キー・値	作成者・バージョンなど拡張情報
`allowed-tools`	オプション	実装体ごとのサポートの違い	事前許可ツール、実験的機能

allowed-toolsが仕様にあるからといって、すべてのエージェントが同じように解釈すると仮定してはいけません。このフィールドは実験的であり、実装体ごとのサポートと権限モデルを別途確認する必要があります。

エージェントはスキルをどのように発見するのか？

Agent Skillsの重要な設計原則は、漸進的開示（Progressive Disclosure）です。

1. Discovery
   모든 스킬의 name과 description만 확인

2. Activation
   사용자 요청과 맞는 스킬의 SKILL.md 전체 로드

3. Execution
   필요한 scripts·references·assets만 추가 사용

エージェントが最初からすべてのスキルの長い本文を読み込むと、コンテキストが急速に消費されます。そのため、descriptionは単純な紹介ではなく、スキルルーティングルールのように記述する必要があります。

良い説明には、次の3つの要素が含まれます。

무엇을 수행하는가
+ 언제 호출해야 하는가
+ 비슷해 보이지만 호출하지 말아야 할 경우

例えば、「AWSを助ける」よりも「IAMポリシーの過剰な権限と権限昇格をレビューし、一般的なAWSのコスト・ネットワークレビューには使用しない」の方が、はるかに正確なトリガーとなります。

公式仕様では、SKILL.md全体を500行、約5,000トークン以下に保ち、長い資料は別のファイルに分割する方法を推奨しています。これは強制的な制限ではなく、コンテキスト効率のための推奨値です。

公式仕様と実務設計を区別する必要がある

次の項目は、Agent Skillsの公式必須Frontmatterではありません。

역할
목표
입력 조건
허용 범위
금지 범위
판단 기준
출력 형식
오류 처리
완료 기준
테스트 사례

しかし、これらが不要だという意味ではありません。これらは、セキュリティレビュー、審査、コードレビューのように、結果の一貫性と再現性が重要な業務において有用なプロンプトエンジニアリングおよびエージェント設計パターンです。



—	—	—
区分	Agent Skills 公式仕様	実務推奨設計
目的	互換性のあるスキルパッケージ形式の定義	業務結果の一貫性と安全性の確保
必須要素	`SKILL.md`、`name`、`description`	目的、ワークフロー、安全境界、出力契約など
本文目次	強制しない	業務特性に合わせて構造化
テスト	公式必須ディレクトリではない	トリガー・正常・危険・境界事例を推奨
ツール権限	一部メタデータと実装体ポリシー	読み取り・書き込み・承認範囲を明示的に設計

図：公式仕様と実務推奨設計の境界 · Agent Skills SpecificationとBest practices for skill creatorsを基に再構成

セキュリティ・監査スキルに必要な実務構造

セキュリティ業務用のスキルであれば、次の構成を推奨できます。



—	—	—
構成要素	重要度	説明
メタデータ	必須	名前、トリガー説明、バージョン、互換環境
目的	必須	作成すべき最終結果
適用・非適用条件	必須	呼び出すべき状況と除外すべき状況
入力契約	推奨	必須入力、オプション入力、不足時の行動
実行手順	必須	作業順序と意思決定の流れ
判断基準	重要	問題・危険度を判定する根拠
安全境界	重要	禁止作業と承認が必要な作業
ツール使用ポリシー	ツール使用時必須	読み取り・書き込み・外部転送範囲
出力契約	必須	人間が読む、またはシステムが処理する結果構造
エラー処理	推奨	失敗、不確実性、情報不足の処理
検証基準	重要	完了条件とテスト方法

目的は完了状態で記述する

悪い例：

IAM 정책을 분석한다.

良い例：

제공된 IAM 정책에서 과도한 권한, 권한 상승 경로,
신뢰 정책 오류와 조건문 누락을 식별하고,
각 발견의 근거와 최소 권한 수정안을 제공한다.

入力が不足している場合でも行動を定義する

확인 가능한 위험은 먼저 분석한다.
확인할 수 없는 항목은 추정하지 않고 검토 제한 사항으로 표시한다.
SCP와 권한 경계가 없으면 전체 유효 권한을 확정하지 않는다.

安全境界は行動権限として記述する

읽기 작업                  자동 수행 가능
정책 수정안 생성            자동 수행 가능
실제 정책 변경              사용자 승인 필요
정책 삭제·권한 확대          기본 실행 금지
인증정보 원문 재출력          금지

「安全に行動する」のように抽象的に書くのではなく、どのような動作を自動実行し、どのような動作は承認を受け、どのような動作は実行しないのかを具体化する必要があります。

出力契約とエラー処理を固定する

人間が読むレポートは、次のように構成できます。

1. 검토 요약
2. 주요 발견 사항 표
3. 발견별 근거와 영향
4. 권한 상승 경로
5. 최소 권한 수정안
6. 검토 제한 사항
7. 추가로 필요한 정보

自動後処理が必要な場合は、JSON Schemaで深刻度、確信度、位置、証拠、推奨事項のタイプを固定する方が安定します。

ディレクトリは役割別に分けるのが良い

長いスキル一つにすべてのポリシーと例を詰め込むのではなく、次のように分離できます。

aws-iam-policy-review/
├── SKILL.md
├── references/
│   ├── severity-criteria.md
│   ├── privilege-escalation-patterns.md
│   ├── sensitive-actions.md
│   ├── condition-key-guidance.md
│   └── output-schema.json
├── scripts/
│   ├── validate_policy.py
│   └── normalize_statements.py
├── assets/
│   ├── report-template.md
│   └── sample-policy.json
└── tests/
    ├── trigger-evals.json
    ├── policy-cases/
    └── expected-results/

tests/は公式仕様の必須ディレクトリではありませんが、運用品質のために追加できます。コアワークフローはSKILL.mdに、長い判定表はreferences/に、決定的な検証はscripts/に、出力骨格はassets/に、回帰検証はtests/に置くと管理しやすくなります。

システムプロンプト、Agent Skills、MCPは何が違うのか？

これら3つの要素は競合関係ではなく、それぞれ異なる層に属します。



—	—	—	—
区分	システムプロンプト	Agent Skills	MCP
質問	常にどのように行動すべきか？	特定の業務をどのように実行すべきか？	どのようなデータ・ツールとどのように接続すべきか？
適用範囲	すべてのリクエスト	関連する作業のみ	接続されたサーバーのリソース・ツール
主要内容	全体原則と最上位境界	ドメイン手順・判断・例	Resources・Prompts・Tools通信
ロード	会話開始時から	必要な時に	接続・呼び出し時
スクリプト・資料	通常含まない	一緒にパッケージ化可能	外部システムが機能提供

AWS IAMレビューを例にとると、次のように結合します。

시스템 프롬프트
└── 승인 없는 변경 금지, 비밀 보호

Agent Skill
└── 정책 수집 → 정규화 → 위험 판단 → 수정안 작성 절차

MCP Tools
├── IAM 정책 조회
├── Access Analyzer 결과 조회
├── 공식 문서 검색
└── 보고서 저장

スキルはツールに接続するプロトコルではなく、MCPはセキュリティレビュー手順自体を定義するものではありません。

skills.shとは何か？

skills.shはAgent Skills仕様そのものではありません。Vercelが運営する公開スキル検索ディレクトリであり、vercel-labs/skillsで公開されているskills CLIと連携しています。

一文で区別すると以下のようになります。

Agent Skills
= 스킬을 어떤 파일 형식으로 작성할 것인가

skills.sh
= 작성된 스킬을 어디서 찾고 여러 에이전트에 어떻게 설치할 것인가



—	—	—
区分	Agent Skills	skills.sh・skills CLI
性質	作成形式・公開仕様	検索ディレクトリ・インストールツール
核	`SKILL.md`構造	`npx skills`コマンド
役割	スキル定義・ロード	発見・インストール・更新・ランキング
開始・運営	Anthropicで開始、公開開発	Vercel
保存場所	各Gitリポジトリとローカルディレクトリ	元のリポジトリを見つけてエージェントパスに配置
国際標準機関	ではない	ではない
比喩	パッケージ仕様	検索ディレクトリと汎用インストールマネージャー

skills CLIはどのように使用するのか？

公開リポジトリのスキルリストのみ確認：

npx skills add vercel-labs/agent-skills --list

特定のスキルをプロジェクトスコープにインストール：

npx skills add vercel-labs/agent-skills 
  --skill web-design-guidelines

Codexにのみインストール：

npx skills add vercel-labs/agent-skills 
  --skill web-design-guidelines 
  --agent codex

インストールせずに一時的に使用：

npx skills use 
  vercel-labs/agent-skills@web-design-guidelines 
  --agent claude-code

管理コマンド：

npx skills list
npx skills update
npx skills remove <skill-name>
npx skills init aws-iam-policy-review

CLIは現在、Claude Code、Codex、Cursor、GitHub Copilot、Gemini CLIなど、約70のエージェントインストールパスをサポートしています。デフォルトのインストール範囲は現在のプロジェクトであり、-gまたは--globalを使用するとユーザー全体にインストールされます。インストール方法は、共通のコピーを指すシンボリックリンクと個別のファイルコピーから選択できます。

skills.shのランキングとOfficialの意味

skills.shのドキュメントによると、ランキングはCLIが収集した匿名インストール統計に基づいています。したがって、ランキングは人気と発見可能性を示すものであり、正確性・セキュリティ・メンテナンス品質のスコアではありません。

テレメトリーを使用しない場合は、CLIが案内する環境変数を使用できます。

DISABLE_TELEMETRY=1 npx skills add owner/repo

DONOTTRACKも代替設定として案内されています。

Officialリストは、該当製品や技術を作成した組織が提供するスキルをまとめて見る機能です。しかし、次の3つの文章は異なります。

공식 제작자가 배포했다                 가능
Vercel이 내용 전체를 보증한다           아님
보안상 무조건 안전하고 최신이다          보장되지 않음

公式作成者のスキルを優先するのは良い出発点ですが、インストール前に現在のコミットとスクリプト、権限要件を確認する必要があります。

公開スキルはなぜサプライチェーンリスクになるのか？

スキルは単純な説明文ではない場合があります。

SKILL.md
├── 명령 실행 절차
├── 파일 변경 지침
├── 외부 도구 사용 규칙
└── 기존 지침과 충돌할 수 있는 문장

scripts/
├── Python·Bash·JavaScript 실행 코드
├── 의존성 설치
└── 외부 통신

スキル自体が新しいオペレーティングシステム権限を作成するわけではありません。しかし、エージェントがすでに持っているファイル、シェル、ネットワーク、リポジトリ、クラウド権限を特定の方向に使用するように誘導する可能性があります。

悪意のある、または不注意なスキルは、次の動作を誘導する可能性があります。

機密ファイルと環境変数の読み取り
外部サーバーへのデータ転送
リポジトリコードと設定の変更
パッケージまたは実行ファイルのインストール
クラウドポリシーの変更とデプロイ
セキュリティ検査または上位ガイドラインの回避試行

skills.shセキュリティ監査ページは、Gen Agent Trust Hub、Socket、Snykなどの結果をまとめて表示します。しかし、ツールごとに判定基準が異なり、skills.shのドキュメントもすべてのスキルの品質とセキュリティを保証できないため、インストール前に直接レビューするよう明記しています。

企業ではどのように導入すべきか？

公開スキルをすぐにグローバルにインストールするよりも、承認されたサプライチェーンを構築する方が安全です。

図：公開スキルの企業導入検討とデプロイフロー · skills.sh Documentationとvercel-labs/skills READMEを基に再構成

공개 skills.sh·Git 저장소
        ↓
출처·라이선스 확인
        ↓
SKILL.md와 scripts 전체 검토
        ↓
외부 URL·의존성·요구 권한 분석
        ↓
검토된 커밋 고정
        ↓
사내 승인 저장소
        ↓
프로젝트 범위 설치
        ↓
샌드박스·최소 권한·사람 승인
        ↓
업데이트 전 diff와 회귀 테스트


統制項目	推奨案

—	—
出所	公式組織または検証済みリポジトリを優先
バージョン	ブランチ最新版ではなく、レビュー済みコミットを固定
インストール範囲	グローバルよりもプロジェクト単位を優先
コードレビュー	`SKILL.md`だけでなく、`scripts/`全体を確認
外部通信	ドメインと転送データ、依存関係のインストールをレビュー
実行権限	シェル・ネットワーク・クラウド書き込み権限を最小化
秘密情報	不要な資格情報はエージェント環境から削除
高リスク作業	ポリシー変更・デプロイ・削除に人間による承認を適用
更新	自動追従よりも差分レビューと再検証
デプロイ	社内ミラーまたは承認済みGitリポジトリを運用

特に、次のコマンドは便利ですが、レビューされていないリポジトリには使用しない方が良いでしょう。

npx skills add unknown-owner/unknown-repo --all -g -y

これは、すべてのスキルをグローバルスコープに確認なしでインストールする組み合わせであるためです。まず--listでスキルを確認し、元のコミットのSKILL.md、scripts/、外部URLとライセンスをレビューした後、必要なスキルのみをプロジェクトスコープにインストールする手順が安全です。

npmと同じものなのか？

似ている面はありますが、完全に同じではありません。



—	—	—
区分	npm	skills.sh
オリジナル配布	レジストリにパッケージを公開	主にGitリポジトリのスキルを発見・接続
インストール対象	JavaScriptパッケージと依存関係	指示・スクリプト・参考資料・アセット
インストール場所	`node_modules`	エージェントごとのスキルディレクトリ
主要管理	パッケージバージョン・依存関係	エージェントごとの配置・検索・インストール統計
実行リスク	インストール・ランタイムコード	エージェントが従う指示と実行コード

したがって、skills.shを「Agent Skills用のnpm」と断定するよりも、検索ディレクトリと複数のエージェントのための汎用インストールマネージャーを組み合わせたサービスと説明する方が正確です。

最終まとめ

Agent Skills、skills.sh、システムプロンプト、MCPの役割を一度にまとめると以下のようになります。

Agent Skills
= 업무 절차를 패키징하는 공개 파일 형식

SKILL.md 실무 설계
= 그 형식 안에 목적·절차·판단·안전·출력 기준을 채우는 방법

skills.sh
= 공개 스킬을 검색하고 여러 에이전트에 설치하는 디렉터리·CLI

시스템 프롬프트
= 모든 요청에 적용되는 상위 행동 원칙

MCP
= 외부 데이터와 도구를 연결하는 통신 프로토콜

Agent Skillsが公式に強制する最小要素は小さいです。しかし、実際の運用品質はSKILL.mdのワークフロー、判断基準、安全境界、エラー処理、テストによって決まります。

skills.shの検索ランキングやOfficial表示は、発見を助けるシグナルであり、セキュリティ保証書ではありません。公開スキルをコードサプライチェーンのようにレビューし、固定されたバージョンとプロジェクト単位のインストール、最小権限、人間による承認を組み合わせることで、安全に活用できます。

Agent Skillsは機関や国際標準ではなく、公開スキルパッケージ形式であり、skills.shはその形式を使用するスキルを見つけてインストールするエコシステムである。形式の互換性と運用の安全性は別の問題である。