SKILL.md body and reference files
Write detailed instructions, link external context
⏱ Est. ~5 min
01 · Read
The markdown body below the frontmatter is where the real power is. This is where you write detailed instructions, examples, constraints, and rules for Claude to follow.
Think of it as a highly specific instruction manual for one task.
Use markdown headings to organize sections, bullet lists for rules, and code fences for examples. The clearer and more specific you are, the more consistently Claude performs.
A body that says "write good code" is useless — Claude is already trying. A body that says "use camelCase for variables, PascalCase for React components, kebab-case for CSS classes" is actionable.
Key points
- The body is free-form markdown — headings, lists, code fences, bold
- Be specific: "use camelCase for variables" beats "use good naming"
- Include examples of what good output looks like
- Organize with headings so Claude can find relevant rules quickly
02 · Code example
Here's an "API Developer" skill with a richly structured body — headings, rules, and code examples.
api-developer/SKILL.md (body section)
## 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 reads every heading, bullet, and code example. When you later say "build me a GET /users endpoint," Claude automatically follows these conventions — kebab-case URLs, camelCase JSON, and the exact error format you specified.
03 · Read
Sometimes your instructions reference external knowledge — a database schema, style guide, type definitions, templates.
Instead of pasting all that into SKILL.md (which gets huge and hard to maintain), you can link reference files.
Put them in the same skill folder as SKILL.md, and reference them from the body. When the skill is active, Claude reads the linked files as extra context.
The benefit of reference files: they're the real source of truth. When your schema changes, Claude automatically sees the latest version — no manual updating of the skill required.
Key points
- Reference files live in the same skill folder as SKILL.md
- They provide context without bloating the skill file
- Common reference files: schema files, style guides, templates, type definitions
- Reference files stay current because they are the source of truth
04 · Code example
Here's a skill that links a Prisma schema as a reference file — giving Claude full knowledge of your database structure.
Folder structure
.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
When this skill is active, Claude can read schema.prisma to understand your database structure. When you later change the schema, Claude automatically sees the latest version — no need to update the skill.
05 · Quiz
Imagine your database schema changes often. Why use a reference file instead of pasting the schema directly into SKILL.md?
- Reference files load faster than inline content
- SKILL.md has a strict 100-line limit
- Claude can only read files separate from SKILL.md
- Reference files stay current as the source changes and keep SKILL.md focused
06 · Match
You've learned the four parts of a skill. Match each component to what it does — think about where metadata, instructions, and external context each live.
(This section is interactive — please enable JavaScript.)
Other lessons in this chapter
⚠ The full interactive experience needs JavaScript. Please enable it and reload.
※ This is an independent Traditional Chinese teaching project — not an official Anthropic product. Claude™ is a trademark of Anthropic, PBC.