| name | skill-spec |
| description | Use when creating, updating, or maintaining skills, understanding skill structure, or implementing SKILL.md files. Also use when user says スキル, SKILL.md, skills. Claude Code プラグインの skill 仕様知識で、スキルの正しい形式、フロントマター、description のベストプラクティスを提供する。 |
| context | fork |
| user-invocable | false |
| allowed-tools | Read, Grep, Glob |
Skill Spec スキル
Claude Code プラグインの skill 仕様知識を提供する。
Instructions
このスキルは skill の正しい形式と実装パターンについての知識を提供します。
重要: 実装前に必ず公式ドキュメント（英語版）を確認し、最新の仕様に従ってください。
Multi-tool compatibility (v1.5.0+, OpenCode は v1.6.0+)
5 ツール (Claude Code / Codex CLI / Cursor / Copilot CLI / OpenCode) 共通認識のため、
SKILL.md 作成時は以下を厳守する:
name: kebab-case 識別子 (必須)description: 1 行目を Use when <発動条件> で始める。これにより Cursor / Codex /
Copilot / OpenCode が自然言語で発動判定できる- Claude Code 固有フィールド (
context: fork, user-invocable) は skills のみで使える。
agents/commands に付けるとリンターがエラーを返す
- skills では
model フィールドは使用不可 (tools も不可、allowed-tools を使う)
- プラグイン側では
AGENTS.md にこの skill を列挙すること
公式ドキュメント
スキルとは
- Claude が特定タスクを実行する方法を教える Markdown ファイル
- ユーザーの要求が description にマッチすると Claude が自動的に適用
- PR レビュー、コミット生成、データベースクエリなどの標準化に最適
ファイル配置
skills/{skill-name}/SKILL.md
- kebab-case を使用（例:
my-skill/SKILL.md）
- ファイル名は必ず
SKILL.md（大文字）
name とディレクトリ名の関係
name はスキル識別子（Claude Code 上、スキルを一意に識別するのは name でありディレクトリ名ではない）- 原則:
name とディレクトリ名は一致させる
- 例外（プラグイン内プレフィックス許容）:
commit, push, merge, validation のように汎用的で他プラグインと衝突しうる名前の場合、プラグイン名由来の prefix を付けて一意化してよい
skills/commit/ → name: git-commit（git-actions プラグイン）skills/validation/ → name: plugin-validation（plugin-generator プラグイン）
- prefix を使う場合は当該プラグインの
CLAUDE.md / AGENTS.md に対応表を明記
フロントマター
必須フィールド
---
name: skill-name
description: 説明
---
オプションフィールド
---
name: skill-name
description: 説明
allowed-tools: Read, Grep, Glob
context: fork
agent: custom-agent
user-invocable: true
---
| フィールド | 型 | 説明 |
|---|
name | String | スキル識別子（必須） |
description | String | いつ使うかを含む説明（必須） |
allowed-tools | String | 使用可能ツールを制限 |
context | String | fork でサブエージェントとして実行（v2.1.0+） |
agent | String | 実行エージェント指定（v2.1.0+） |
user-invocable | Boolean | スラッシュメニュー表示制御（v2.1.3+） |
hooks | Object | スキル固有フック（v2.1.0+） |
重要: skills では model 指定は使用できません。モデル指定が必要な場合は agents を使用してください。
description のベストプラクティス
良い例
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
ポイント:
- 具体的なアクション名を含める（extract, fill, merge）
- ユーザーが使う用語を含める（PDFs, forms）
- いつ使うかを明記（Use when ...）
悪い例
description: Helps with documents
問題:
- 曖昧すぎる
- いつ使うかが不明
- ユーザーの用語が含まれていない
構造
---
name: my-skill
description: 説明。Use when ...
allowed-tools: Read, Grep, Glob
---
# スキル名
## Instructions
ステップバイステップの指示
## Examples
具体的な使用例
重要: フロントマターは必ず1行目から --- で開始（空行不可）
本文構造の 2 パターン
| パターン | 用途 | 必須セクション |
|---|
| アクションスキル | 手順実行型（commit, scan, deploy 等） | ## Instructions + ## Examples |
| 知識 / リファレンススキル | 発動時にドメイン知識をロードする型 | 独自見出し可（概要 / API / ベストプラクティス 等） |
知識スキル例外を採用する場合、以下をすべて満たすこと:
description が "Use when user asks about ..." 等の知識提供トリガーを含むcontext: fork または user-invocable: false を設定allowed-tools は Read / Grep / Glob 中心で書き換え系ツールを含めない- 本文冒頭で「知識提供型スキルである」ことを明示
代表例: cloudflare-knowledge/*, *-cli-spec/*-cli-knowledge, gemini-api-spec/*, agent-browser-spec/*, web-search-unified/unified-search 等
呼び出しフロー
- Discovery: 起動時に name と description のみロード
- Activation: ユーザー要求が description にマッチ → 確認プロンプト
- Execution: 承認後、完全な SKILL.md をロードして実行
フォークコンテキスト（v2.1.0+）
context: fork を指定すると、スキルが独立したサブエージェントとして実行されます。
利点
- メイン会話のコンテキストを汚染しない
- トークン消費を抑制
- 複雑なスキルの干渉を防止
agent フィールドとの組み合わせ
---
name: web-research
description: Web 検索を実行。Use when user needs web research.
context: fork
agent: researcher
---
使用ケース
| ケース | context 設定 |
|---|
| 単純な知識提供 | 省略（メインコンテキスト） |
| 複雑な調査・分析 | fork |
| 独立した検索・レポート生成 | fork + agent 指定 |
| セキュリティレビュー | fork + allowed-tools 制限 |
user-invocable オプション（v2.1.3+）
user-invocable: true（デフォルト）: スラッシュコマンドメニューに表示user-invocable: false: メニューから非表示（自動トリガーのみ）
実装例
基本的なスキル
---
name: code-formatter
description: コードをフォーマットする。Use when user mentions formatting, prettier, or code style.
allowed-tools: Read, Bash
---
# Code Formatter スキル
## Instructions
1. 対象ファイルを特定
2. prettier または適切なフォーマッターを実行
3. 結果を報告
## Examples
### TypeScript ファイルのフォーマット
```bash
npx prettier --write "src/**/*.ts"
### 知識提供型スキル
```markdown
---
name: api-design
description: REST API 設計の知識を提供。Use when user asks about API design, endpoints, or REST patterns.
allowed-tools: Read, Grep, Glob
---
# API Design スキル
## Instructions
このスキルは REST API 設計のベストプラクティスを提供します。
### エンドポイント命名規則
- リソース名は複数形（例: `/users`, `/posts`）
- 動詞は使用しない（例: `/getUsers` → `/users`）
- ネストは2レベルまで（例: `/users/{id}/posts`）
### HTTP メソッド
| メソッド | 用途 |
|---------|------|
| GET | リソース取得 |
| POST | リソース作成 |
| PUT | リソース全体更新 |
| PATCH | リソース部分更新 |
| DELETE | リソース削除 |
## Examples
### ユーザー API
- `GET /users` - ユーザー一覧
- `GET /users/{id}` - ユーザー詳細
- `POST /users` - ユーザー作成
フォークコンテキストを使ったスキル
---
name: comprehensive-research
description: 複数情報源から包括的調査を実施。Use when user needs deep analysis or multi-source research.
context: fork
agent: Explore
allowed-tools: Read, Bash, WebFetch, Grep
---
# Comprehensive Research スキル
## Instructions
1. 対象トピックの概要を把握
2. 複数の情報源から調査
3. 結果を統合して分析
4. 簡潔なレポートを作成
## Examples
### 技術調査
「React と Vue の比較調査」→ 公式ドキュメント、ベンチマーク、エコシステムを調査
バリデーションルール
| ルール | 重要度 |
|---|
フロントマターに name 必須 | エラー |
フロントマターに description 必須 | エラー |
| ディレクトリ名は kebab-case | 推奨 |
ファイル名は SKILL.md | 必須 |
model フィールドは使用不可 | 注意 |
Examples
スキル作成の相談
Q: スキルの description はどう書けばいい？
A: 具体的なアクション名と「Use when ...」でいつ使うかを明記してください。
例: "Extract data from CSV files. Use when user mentions CSV or spreadsheet data."
model 指定の相談
Q: スキルで使うモデルを指定したい
A: skills では model 指定は使用できません。モデル指定が必要な場合は、
agents を作成し、そのエージェントからスキルを参照してください。
