agent-skill-builder

Agent Skill Builder

新しい Claude Code スキルをすばやく作成したり、ChatGPT プロジェクトを Claude Code 形式に変換したりできます。このスキルは、迅速な作成と正しい構造に重点を置いています。反復的なテスト、ベンチマーク、説明の最適化には、Anthropic 公式の skill-creator プラグインを使用してください。

2 つのモード

モード 1：新しいスキルを作成する（/agent-skill-builder new [name]）

適切な構造とベストプラクティスに沿って、新しい Claude Code スキルを作成します。

モード 2：ChatGPT プロジェクトを変換する（/agent-skill-builder translate [name]）

既存の ChatGPT プロジェクトを Claude Code スキルに変換します。

---

新しいスキルを作成する

ステップ 1：目的を確認する

ユーザーに質問します（コンテキストから明らかな内容は省略してください）。

1. スキル名：/slash-command の名前は何にしますか？
2. 目的：このスキルは何をしますか？
3. 使用例：このスキルは実際にどのように使いますか？
4. 起動条件：どのようなユーザーの発言でこのスキルを起動しますか？

ステップ 2：リソースを計画する

各例を分析し、何を含めるべきかを特定します。

• スクリプト（scripts/）：繰り返し書くコードや、確実に同じ結果を得る必要があるコードです。コンテキストに読み込まずに実行します。
• リファレンス（references/）：作業中に Claude が参照するドキュメントです。必要に応じて読み込みます。
• アセット（assets/）：出力に使うファイル（テンプレート、画像、フォント）です。コンテキストには読み込みません。

ステップ 3：ディレクトリと SKILL.md を作成する

mkdir -p ~/.claude/skills/[skill-name]

次のテンプレートに沿って SKILL.md を作成します。

---
name: skill-name
description: "Describes what the skill does and specific triggers for when to use it. Write in third person. Include keywords users would say. Max 1024 characters. This is the PRIMARY triggering mechanism."
---

# Skill Name

[1-2 sentence description]

## Instructions

[Step-by-step guidance — use imperative form]

## Output Format

[Expected output structure]

## Constraints

[Limitations and rules]

ステップ 4：リファレンスファイルを追加する（必要な場合）

複数のドメインやバリエーションがあるスキルでは、SKILL.md を簡潔に保ち、内容をリファレンスに分割します。

skill-name/
├── SKILL.md (overview + navigation, under 500 lines)
└── references/
    ├── variant-a.md
    └── variant-b.md

各ファイルを読むタイミングが明確に分かるよう、SKILL.md から参照します。リファレンスは 1 階層の深さにとどめてください。

ステップ 5：テストする

1. 直接起動します：/skill-name
2. 説明のキーワードに一致したときに Claude が自動で起動するか確認します。
3. 想定どおりにスキルが起動し、関連性がない場合には起動しないことを確認します。

---

ChatGPT プロジェクトを Claude スキルに変換する

ステップ 1：ChatGPT の構成要素を抽出する

ユーザーに次の情報を依頼します。

• システムプロンプト／指示
• ナレッジファイル（PDF、ドキュメント）
• 会話のきっかけ（任意）
• アクション／API の設定（ある場合）

ステップ 2：構成要素を対応付ける

ChatGPT の構成要素	Claude Code での相当項目	保存先
名前	frontmatter の name	SKILL.md
説明	frontmatter の description	SKILL.md
指示	メインの Markdown 本文	SKILL.md
ナレッジファイル	references/ フォルダー（.md に変換）	サブディレクトリ
会話のきっかけ	Examples セクションに記載するか、省略	SKILL.md
アクション（API）	MCP サーバー	~/.claude/mcp.json
Code Interpreter	ネイティブツール：Bash、Read、Write、Edit、Glob、Grep	組み込み
メモリ	直接相当するものはありません。コンテキストファイルまたはスキルの背景セクションを使用します	各種

ステップ 3：指示を変換する

ChatGPT のパターン	Claude での相当項目
「あなたは [role] です……」	役割セクションに記載するか、指示に統合
「あなたのタスクは……」	指示セクション
「必ず／決して……」	制約セクション
「出力形式……」	出力形式セクション
入力プレースホルダー [text]	そのまま使うか、$ARGUMENTS を使用

ステップ 4：ナレッジファイルを変換する

1. PDF／ドキュメントを Markdown に変換し、references/ に配置します。
2. 大きなファイル（10k 語超）では、SKILL.md に grep の検索パターンを記載します。
3. 100 行を超えるファイルには、先頭に目次を追加します。
4. テンプレートとアセットは assets/ に配置します。

ステップ 5：frontmatter を記述する

description フィールドは、スキルを起動する主な仕組みです。三人称で記述し、スキルの機能と使用するタイミングの両方を含めます。起動されにくい状態を防ぐため、起動条件はやや明示的に記述してください。

---

Frontmatter のリファレンス

必須なのは name と description のみです。追加フィールドは Claude Code 固有の拡張機能です。

フィールド	必須	説明
name	はい	最大 64 文字。小文字、数字、ハイフンのみ使用できます
description	はい	最大 1024 文字。「何をするか」＋「いつ使うか」を記述します。三人称で書きます。主なトリガーの仕組みです
argument-hint	いいえ	オートコンプリートに表示されるヒント（例："[issue-number]"）
disable-model-invocation	いいえ	true = ユーザーのみが呼び出し可能（自動トリガーなし）
user-invocable	いいえ	false = Claude のみ（スラッシュコマンドメニューには表示されません）
context	いいえ	fork = 分離されたサブエージェントで実行します
agent	いいえ	サブエージェントの種類：Explore、Plan、general-purpose
allowed-tools	いいえ	使用可能なツールを制限します：Read, Grep, Glob
model	いいえ	このスキルで使用するモデルを上書きします

文字列の置換

変数	説明
$ARGUMENTS	/skill-name の後に続くすべての内容
${CLAUDE_SESSION_ID}	現在のセッション ID
!`command`	動的な挿入（スキルの読み込み前に実行されます）

スキルの配置場所

場所	パス	スコープ
個人用	~/.claude/skills/[name]/	すべてのプロジェクト
プロジェクト用	.claude/skills/[name]/	このプロジェクトのみ

作成時のベストプラクティス

Anthropic 公式のスキル作成ガイドに基づいています。

• 簡潔さが重要です。 Claude はすでに高い能力を備えています。Claude が知らないコンテキストだけを追加してください。冗長な説明より、簡潔な例を優先してください。
• 説明がすべてです。 Claude は、100 個以上ある可能性のあるスキルの中からどれを使うかを説明文に基づいて判断します。具体的にし、トリガーとなるキーワードを含め、三人称で書いてください。
• 段階的な情報開示。 SKILL.md は 500 行未満にしてください。詳細なリファレンスは別ファイルに移してください。Claude は必要な場合にのみ読み込みます。
• タスクの脆弱性に合わせて自由度を調整します。 柔軟なタスクには自由度を高く（テキスト指示）、壊れやすい操作には低く（具体的なスクリプト）設定します。
• 理由を説明します。 強い MUST 指示を使うのではなく、指示の根拠を説明してください。Claude は、厳格なルールよりも動機を理解したほうが適切に応答します。
• 用語を統一します。 用語を 1 つ選び、全体で一貫して使用してください。「API endpoint」／「URL」／「API route」／「path」を混在させないでください。
• 不要なファイルは含めません。 README.md、CHANGELOG.md、INSTALLATION_GUIDE.md は含めないでください。スキルに含めるのは、AI エージェントがタスクを実行するために必要なものだけです。
• スラッシュは常に / を使います。 scripts/helper.py を使用し、scripts\helper.py は使用しないでください。

プロンプトの骨組み（すべてのスキルとプロジェクトプロンプト）

すべてのスキルプロンプトと、ChatGPT または Claude のプロジェクトプロンプトでは、次の 5 つのブロックをこの順序で使用します。

1. 目標。 プロンプトが何を、誰のために作成するのかを 1～2 文で説明します。
2. ペルソナ。 エージェントがどのような人物として行動し、その人物がどのように作業を捉えるかを示します。
3. チャットプロトコル。 会話の進め方を示します。1 メッセージにつき質問は 1 つにすること、各メッセージの冒頭にステージ名を記載すること、各ステージの前に短い説明を加えること、ステージ終了後に結果を確認する方法を含めます。
4. ステージ。 番号付きのステージです。各ステージの最後に停止地点を設け、ユーザーの承認（「go」）を待ってから次のステージを開始します。
5. 厳格なルール。 エージェントが決して行わないことを、平易なルールとして記述します。

骨組みには、さらに 2 つのルールがあります。

• 修正回数に上限を設けます。 各ステージで変更できるのは 1～2 回までとし、その後は次のステージに進みます。上限はステージ内に明記します。
• 作り上げないこと。 エージェントは事実、データ、名前、数値を決して捏造しません。情報が不足している場合は、その箇所を明示して（例：[MISSING: price]）、補完するのではなく質問します。

ステージ間の引き継ぎが必要な場合は、各ステージで Markdown ファイルを作成し、次のステージでそのファイルを読み込むようにします。

作成後のチェックリスト

• フロントマターにnameとdescriptionを含むSKILL.mdを作成済み
• 説明に何をするか、いつ使うか（トリガー）を含め、三人称で記述済み
• SKILL.mdが500行未満
• ナレッジファイルをreferences/内のMarkdownに変換済み
• SKILL.mdから参照ファイルまでの階層が1段
• 大きな参照ファイル（100行超）に目次を追加済み
• プロンプトが、停止ポイント、改訂回数の上限、創作禁止ルールを含む5ブロックのひな形に準拠
• /skill-nameと自動呼び出しでスキルをテスト済み
• 不要なドキュメントファイルがない