skill-authoring

AI エージェントスキルのベストプラクティス

Claude Code のスキルや MCP ツールを含む、AI エージェントスキルの設計・開発ガイドです。8 つのカテゴリにわたる 46 のルールを、影響度の高い順にまとめ、スキルの作成、レビュー、最適化を支援します。

適用する場面

• 新しい Claude Code のスキルや MCP ツールを作成するとき
• SKILL.md のメタデータや説明を記述・レビューするとき
• スキルのトリガーの信頼性を最適化するとき
• 段階的開示のためにコンテンツを構成するとき
• スキルの起動と動作をテストするとき
• エージェントのワークフロー向けにツールのインターフェースを設計するとき

基本原則

1. 起動は説明によって決まります。 Claude は、ユーザーの意図との説明の一致度に基づいてスキルを選択します。具体的な機能、トリガーキーワード、対象外のケースを含めてください。説明が曖昧なスキルは、起動が不安定になるか、まったく起動しません。

2. 重要な指示を冒頭に置きます。 Claude は長いコンテンツを切り詰めることがあります。譲れないルールは最初の 100 行に置いてください。重要な制約を末尾に埋め込むと、無視されます。

3. 段階的開示でトークンを節約します。 詳細なコンテンツは必要なときだけ読み込みます。2000 行のスキルは、起動するたびにコンテキストを無駄に消費します。次のように構成してください：SKILL.md（概要）→ references/（詳細）→ scripts/（実行）。

4. 実行だけでなく起動もテストします。 完璧に動作しても一度も起動しないスキルは、何の価値もありません。デプロイ前に、実際のユーザーの表現、同義語、エッジケースを使ってテストしてください。

5. ドメインごとにスキルを 1 つにします。 重複するスキルは起動時の競合を引き起こします。明確な境界（言語、フレームワーク、ワークフローの段階）で分割し、それぞれに異なるトリガーキーワードを設定してください。

ルールのカテゴリ

優先度	カテゴリ	影響度	接頭辞
1	スキルのメタデータ設計	CRITICAL	meta-
2	説明の設計	CRITICAL	desc-
3	コンテンツ構成	HIGH	struct-
4	トリガーの最適化	HIGH	trigger-
5	段階的開示	MEDIUM-HIGH	prog-
6	MCP ツールの設計	MEDIUM	mcp-
7	テストと検証	MEDIUM	test-
8	メンテナンスと配布	LOW-MEDIUM	maint-

クイックリファレンス

1. スキルのメタデータ設計（CRITICAL）

• meta-name-format - スキル名は小文字とハイフンを使って記述します
• meta-name-hyphen-boundaries - 名前の先頭または末尾にハイフンを使用しません
• meta-name-no-consecutive-hyphens - 名前に連続したハイフンを使用しません
• meta-name-uniqueness - スキル名がグローバルに一意であることを確認します
• meta-required-frontmatter - 必須の frontmatter フィールドをすべて含めます
• meta-allowed-frontmatter-fields - 許可された frontmatter フィールドのみを使用します
• meta-frontmatter-yaml-syntax - 有効な YAML frontmatter 構文を使用します
• meta-name-length - スキル名を 64 文字未満にします
• meta-directory-match - スキル名とディレクトリ名を一致させます

2. 説明の設計（CRITICAL）

• desc-specific-capabilities - 説明に具体的な機能を記載します
• desc-trigger-keywords - 説明にユーザーが使うトリガーキーワードを含めます
• desc-third-person-voice - 説明は三人称で記述します
• desc-length-optimization - 見つけやすさを考慮して説明の長さを最適化します
• desc-avoid-vague-terms - 説明で曖昧な表現を避けます
• desc-differentiate-similar-skills - 類似するスキルは異なるトリガーで区別します
• desc-include-negative-cases - 精度を高めるため、対象外のケースを含めます

3. コンテンツ構成（HIGH）

• struct-header-hierarchy - 一貫した見出し階層を使用します
• struct-instructions-first - 重要な指示をコンテンツの冒頭に置きます
• struct-imperative-instructions - 指示は命令形で記述します
• struct-code-blocks-with-language - コードブロックに言語を指定します
• struct-line-limit - SKILL.md を 500 行未満にします
• struct-single-responsibility - ドメインごとにスキルを 1 つにします
• project-conventions - リポジトリ固有のスキル規約を維持します

4. トリガーの最適化（高）

• trigger-slash-command-aliases - 説明にスラッシュコマンドのエイリアスを含める
• trigger-file-type-patterns - 説明にファイルタイプのパターンを含める
• trigger-workflow-stages - 説明でワークフローの各段階に言及する
• trigger-error-patterns - デバッグ用スキルにエラーパターンを含める
• trigger-synonym-coverage - 同義語や別の言い回しもカバーする

5. 段階的な情報開示（中〜高）

• prog-three-level-disclosure - 3段階の段階的な情報開示を実装する
• prog-one-level-deep-links - 参照リンクの階層を1段階までに制限する
• prog-scripts-execute-not-read - コードを読むのではなく、スクリプトを実行する
• prog-lazy-load-examples - 例や参照資料を必要に応じて読み込む
• prog-mutual-exclusion - 相互排他的なコンテキストを分ける

6. MCP ツールの設計（中）

• mcp-tool-naming - アクションと対象が明確なツール名を使用する
• mcp-parameter-descriptions - すべてのツールパラメーターを説明する
• mcp-error-messages - 対応方法が分かるエラーメッセージを返す
• mcp-tool-scope - 単一の目的を持つツールを設計する
• mcp-allowed-tools - 安全上の制約に allowed-tools を使用する
• mcp-idempotent-operations - 冪等なツール操作を設計する

7. テストと検証（中）

• test-trigger-phrases - 実際のユーザーフレーズでスキルの有効化をテストする
• test-edge-cases - エッジケースの入力でスキルをテストする
• test-negative-scenarios - 関係のないリクエストではスキルが有効にならないことをテストする
• test-instruction-clarity - 新しいコンテキストで指示の明確さをテストする

8. メンテナンスと配布（低〜中）

• maint-semantic-versioning - スキルのリリースにセマンティックバージョニングを使用する
• maint-changelog - スキルの更新履歴を管理する
• maint-plugin-packaging - 配布用にスキルをプラグインとしてパッケージ化する
• maint-audit-security - 外部ソースからインストールする前にスキルを監査する

ルールの作成

assets/templates/_template.md をコピーし、フロントマターのスキーマに従ってください。

---
title: Rule Title Here
impact: CRITICAL|HIGH|MEDIUM-HIGH|MEDIUM|LOW-MEDIUM|LOW
impactDescription: Quantified impact (e.g., "2-10x improvement")
tags: prefix, technique, related-concepts
---

参照ファイルには、次のパターンを使用します：references/{prefix}-{slug}.md

参考資料

• skills-ref の仕様
• Anthropic Engineering：エージェントスキル
• Claude Code スキルのドキュメント
• Anthropic のスキルリポジトリ
• MCP のベストプラクティス
• プロンプトエンジニアリングガイド：LLM エージェント
• Claude スキルの詳細解説