SKILL.md の本体と参照ファイル
詳細な指示を書き、外部のコンテキストにリンクする
⏱ 想定 ~5 分
01 · 読む
Frontmatter の下にある markdown 本体こそが本当の力の源です。ここに詳細な指示、例、制約、Claude に守らせたいルールを書きます。
ひとつのタスクに対する極めて具体的な指示書だと考えてください。
markdown の見出しでセクションを整理し、箇条書きでルールを並べ、code fence で例を示しましょう。明確で具体的であればあるほど、Claude の振る舞いは一貫します。
「良いコードを書いて」とだけ書いた本体は役に立ちません—Claude はもともとそうしようとしています。「変数は camelCase、React コンポーネントは PascalCase、CSS クラスは kebab-case を使う」と書いた本体は実行できる指示になります。
ポイントまとめ
- 本体は自由な markdown—見出し、箇条書き、code fence、太字を使える
- 明確に:「変数は camelCase」のほうが「良い命名を使う」より効く
- 良い出力がどんな見た目になるかの例を含める
- 見出しで構造化して、Claude が関連するルールをすぐに見つけられるようにする
02 · コード例
下は「API Developer」skill です。本体の構造が豊かで、見出し、ルール、コード例が揃っています。
api-developer/SKILL.md (本体セクション)
## API Conventions
- All endpoints return JSON
- Use kebab-case for URL paths: `/user-profiles` not `/userProfiles`
- Use camelCase for JSON fields: `{ "firstName": "Ada" }`
- Always include `Content-Type: application/json` header
## Error Response Format
Always return errors in this exact shape:
```json
{
"error": {
"code": "NOT_FOUND",
"message": "User with id 42 not found"
}
}
```
## Status Code Rules
- 200 for successful reads
- 201 for successful creates
- 400 for invalid input
- 404 for missing resources
- 500 should never be intentional — fix the bug
Claude は各見出し、箇条書き、コード例を読み込みます。あとから「GET /users エンドポイントを作って」と頼むと、Claude はこれらの慣習に自動的に従ってくれます—kebab-case の URL、camelCase の JSON、指定したエラー形式まで含めて。
03 · 読む
あなたの指示が外部の知識を参照することがあります—データベースの schema、スタイルガイド、型定義、テンプレートなどです。
それらをすべて SKILL.md に貼り付ける(すると巨大になり、保守も大変になる)代わりに、参照ファイルにリンクできます。
SKILL.md と同じ skill フォルダに置き、本体から参照します。Skill が有効になると、Claude はリンクされたファイルを追加のコンテキストとして読みます。
参照ファイルの利点:それらは信頼できる唯一の情報源になります。schema を変えれば、Claude は自動的に最新版を見られます—skill を手動で更新する必要はありません。
ポイントまとめ
- 参照ファイルは SKILL.md と同じ skill フォルダに置く
- コンテキストを提供しつつ、skill ファイルを膨らませない
- よくある参照ファイル: schema ファイル、スタイルガイド、テンプレート、型定義
- 参照ファイルは常に最新—それ自体が情報源だから
04 · コード例
下は Prisma の schema を参照ファイルとしてリンクする skill です—Claude にあなたのデータベース構造の完全な知識を与えます。
フォルダ構造
.claude/skills/db-developer/
├── SKILL.md
└── schema.prisma
db-developer/SKILL.md
---
name: Database Developer
description: Writes database queries and migrations following our schema
---
## Context
Our database schema is defined in `schema.prisma` (included in this skill folder).
Always reference it when writing queries or migrations.
## Rules
- Never use raw SQL — use Prisma Client
- Always include `createdAt` and `updatedAt` on new models
- Foreign keys must have `onDelete: Cascade` unless specified otherwise
- Index any column used in WHERE clauses
この skill が有効になると、Claude は schema.prisma を読んでデータベース構造を理解できます。あとで schema を変更しても、Claude は自動的に最新版を見られます—skill を更新する必要はありません。
05 · クイズ
あなたのデータベース schema が頻繁に変わると想像してください。schema を SKILL.md に直接貼るのではなく、参照ファイルを使うべき理由は？
- 参照ファイルはインライン内容より読み込みが速いから
- SKILL.md は厳格な 100 行の上限があるから
- Claude は SKILL.md と別のファイルしか読めないから
- 参照ファイルは元データの変化に追従して常に最新で、SKILL.md を焦点の絞られた状態に保てるから
06 · 対応づけ
skill の 4 つの要素を学びました。それぞれが何の役割を果たすかをマッチさせてください—メタデータ、指示、外部コンテキストがそれぞれどこに住むかを思い浮かべて。
（このセクションはインタラクティブです — JavaScript を有効にしてください。）
⚠ 全機能のインタラクティブ体験には JavaScript が必要です。JavaScript を有効にして再読み込みしてください。
※ このサイトは独立した教育プロジェクトで、Anthropic の公式製品ではありません。Claude™ は Anthropic, PBC の商標です。