skills-manual

スキルマニュアル

AI コーディングエージェント向けの効果的なスキルの構築方法。Anthropic の完全なガイドについては、references/skill-builder-guide.md を参照してください。

スキルの構造

your-skill-name/              # kebab-case, no spaces, no capitals, no underscores
  SKILL.md                    # Required — must be exactly this name (case-sensitive)
  references/                 # Optional — supporting docs loaded on demand
  scripts/                    # Optional — executable code
  assets/                     # Optional — templates, icons

• メインファイルの名前は必ず SKILL.md にしてください。skill.md、SKILL.MD、その他の名前は使用できません
• スキルフォルダー内に README.md を含めないでください
• フォルダー名はケバブケースにしてください（例：notion-project-setup）

YAML フロントマター

---
name: your-skill-name                     # Required — kebab-case, must match folder name
description: "What and when."             # Required — max 1024 chars, no < > brackets
license: MIT                              # Optional
allowed-tools: "Bash(python:*) WebFetch"  # Optional — restrict tool access
metadata:                                 # Optional
  author: Name
  version: 1.0.0
---

セキュリティ上の制限

• フロントマターには XML の山括弧（< >）を含めないでください。システムプロンプトに表示されます
• スキル名に「claude」や「anthropic」を含めないでください（予約済み）

説明の書き方

説明は最も重要なフィールドです。プログレッシブディスクロージャーを通じて、スキルが読み込まれるタイミングを制御します。

1. フロントマター（常に読み込まれます）— Claude は説明を読んで関連性を判断します
2. SKILL.md 本文（関連する場合に読み込まれます）— 詳細な指示
3. リンクされたファイル（必要に応じて読み込まれます）— 参照資料、スクリプト、アセット

説明には必ず次の両方を含めてください。

• スキルが何をするか
• いつ使うか — ユーザーが実際に使いそうな具体的なトリガーフレーズ

良い例：

description: "Manages Linear project workflows including sprint planning,
  task creation, and status tracking. Use when user mentions 'sprint',
  'Linear tasks', 'project planning', or asks to 'create tickets'."

悪い例：

description: "Helps with projects."

デバッグするには、Claude に「[スキル名] スキルはどんなときに使いますか？」と尋ねてください。説明をそのまま引用するため、不足している点が明らかになります。

指示の書き方

構成

---
name: your-skill
description: [...]
---

# Skill Name

## Instructions
Step-by-step workflow with clear actions.

## Examples
Common scenarios with expected inputs/outputs.

## Troubleshooting
Common errors, causes, and fixes.

ルール

• 最も重要なルールから先に書く
• 具体的に書く — コマンド、ファイルパス、想定される出力を含める
• 順序に従うワークフローには番号付きの手順を、ガイドラインには箇条書きを使う
• 正しい使用例と誤った使用例を示す
• よくある失敗に対するエラー処理を含める
• 同梱ファイルを明示的に参照する（例：「references/api-guide.md を参照」）
• SKILL.md は 5,000 語未満にし、詳細なドキュメントは references/ に移す
• 合成可能性 — 他のスキルも同時に読み込まれることを前提にする

改善の手がかり

手がかり	意味	対応
読み込まれるべきときにスキルが読み込まれない	トリガー不足	説明にトリガーフレーズやキーワードを追加する
無関係な問い合わせでスキルが読み込まれる	トリガー過多	除外トリガーを追加し、対象範囲を絞る
Claude が指示に従わない	冗長すぎる、または曖昧	箇条書きを使い、明確に書き、詳細は参照資料に移す
結果に一貫性がない	例や検証が不足	例、エラー処理、品質チェックを追加する