Corpo do SKILL.md e arquivos de referência
Escreva instruções detalhadas e conecte contexto externo
⏱ Estim. ~5 min
01 · Ler
O corpo markdown abaixo do frontmatter é onde mora o poder de verdade. É aqui que você escreve instruções detalhadas, exemplos, restrições e regras para o Claude seguir.
Pense como um manual de instruções altamente específico para uma tarefa.
Use cabeçalhos markdown para organizar seções, listas para regras e code fences para exemplos. Quanto mais claro e específico você for, mais consistente fica a saída do Claude.
Um corpo dizendo "escreva um bom código" não serve para nada — o Claude já está tentando. Um corpo dizendo "use camelCase para variáveis, PascalCase para componentes React, kebab-case para classes CSS" é executável.
Pontos-chave
- O corpo é markdown livre — cabeçalhos, listas, code fences, negrito
- Seja explícito: "use camelCase para variáveis" ganha de "use bons nomes"
- Inclua exemplos de como deve ser uma boa saída
- Organize com cabeçalhos para o Claude achar as regras relevantes rápido
02 · Exemplo de código
Abaixo está uma skill "API Developer" com um corpo rico, incluindo cabeçalhos, regras e exemplos de código.
api-developer/SKILL.md (trecho do corpo)
## 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
O Claude lê cada cabeçalho, lista e exemplo de código. Quando, mais tarde, você disser "me ajude a construir um endpoint GET /users", o Claude vai seguir essas convenções automaticamente — URLs em kebab-case, JSON em camelCase, exatamente o formato de erro que você especificou.
03 · Ler
Às vezes suas instruções fazem referência a conhecimento externo — um schema de banco, um style guide, definições de tipo, templates.
Em vez de colar tudo isso dentro do SKILL.md (que vai ficar gigante e difícil de manter), você pode referenciar arquivos.
Coloque-os na mesma pasta da skill, junto do SKILL.md, e mencione-os a partir do corpo. Quando a skill é ativada, o Claude lê os arquivos referenciados como contexto adicional.
A vantagem dos arquivos de referência: eles são a fonte real da verdade. Se o seu schema mudar, o Claude vê a versão mais recente automaticamente — sem precisar atualizar a skill manualmente.
Pontos-chave
- Arquivos de referência ficam na mesma pasta da skill que o SKILL.md
- Eles fornecem contexto sem inchar o arquivo da skill
- Referências comuns: arquivos de schema, style guides, templates, definições de tipo
- Arquivos de referência se mantêm atualizados, porque são a fonte da verdade
04 · Exemplo de código
Abaixo está uma skill que referencia um schema Prisma como arquivo de referência — dando ao Claude conhecimento completo da estrutura do seu banco.
Estrutura de pastas
.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
Quando essa skill é ativada, o Claude consegue ler schema.prisma para entender a estrutura do seu banco. Se você mudar o schema depois, o Claude vê a versão mais recente automaticamente — sem precisar atualizar a skill.
05 · Quiz
Imagine que o schema do seu banco muda com frequência. Por que usar um arquivo de referência em vez de colar o schema direto no SKILL.md?
- Arquivos de referência carregam mais rápido do que conteúdo embutido
- SKILL.md tem um limite rígido de 100 linhas
- O Claude só consegue ler arquivos separados do SKILL.md
- Arquivos de referência se mantêm atualizados conforme a fonte muda e deixam o SKILL.md focado
06 · Combinar
Você aprendeu as quatro partes de uma skill. Combine cada componente com o que ele faz — pense em onde ficam metadados, instruções e contexto externo.
(Esta seção é interativa — ative o JavaScript para usar.)
Outras lições deste capítulo
⚠ A experiência interativa completa precisa de JavaScript. Ative-o e recarregue a página.
※ Este é um projeto educacional independente — não é um produto oficial da Anthropic. Claude™ é uma marca registrada da Anthropic, PBC.