Skill Spec

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 を列挙すること

公式ドキュメント

• Skills

スキルとは

• 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           # 必須: kebab-case（最大64文字）
description: 説明           # 必須: いつ使うか明記（最大1024文字）
---

オプションフィールド

---
name: skill-name
description: 説明
allowed-tools: Read, Grep, Glob
context: fork                     # v2.1.0+
agent: custom-agent               # v2.1.0+
user-invocable: true              # v2.1.3+
---

重要: 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 パターン

知識スキル例外を採用する場合、以下をすべて満たすこと:

• 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 等

呼び出しフロー

1. Discovery: 起動時に name と description のみロード
2. Activation: ユーザー要求が description にマッチ → 確認プロンプト
3. Execution: 承認後、完全な SKILL.md をロードして実行

フォークコンテキスト（v2.1.0+）

context: fork を指定すると、スキルが独立したサブエージェントとして実行されます。

利点

• メイン会話のコンテキストを汚染しない
• トークン消費を抑制
• 複雑なスキルの干渉を防止

agent フィールドとの組み合わせ

---
name: web-research
description: Web 検索を実行。Use when user needs web research.
context: fork
agent: researcher  # ビルトイン: Explore, Plan / カスタム: .claude/agents/ のエージェント
---

使用ケース

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 の比較調査」→ 公式ドキュメント、ベンチマーク、エコシステムを調査

バリデーションルール

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 を作成し、そのエージェントからスキルを参照してください。