🧩 Skills, sub-agents e MCP no Claude Code

Estrutura completa

.claude/skills/minha-skill/
├── SKILL.md              ← obrigatório (frontmatter + body)
├── scripts/             ← scripts auxiliares chamáveis
│   ├── check.sh
│   └── format.py
├── references/          ← docs profundas (lazy-load)
│   ├── api-spec.md
│   └── examples.md
└── assets/              ← imagens, binários, templates
    └── template.html

SKILL.md completo (exemplo real)

---
name: revisar-pr
description: Use quando o usuário pedir pra revisar uma PR ou diff. Triggers: "revisa PR", "review pull request", "olha o diff".
allowed-tools: Bash(git diff:*), Bash(gh pr:*), Read, Grep, Glob
disable-model-invocation: false
---

# Revisar PR

## Passo a passo

1. Identifica a PR (número via $ARGUMENTS ou \`gh pr list\`)
2. Lê diff completo com \`gh pr diff <numero>\`
3. Para cada arquivo mudado, verifica:
   - Bugs de correção (não estilo)
   - Edge cases não tratados
   - Vulnerabilidades comuns
4. Consulta \`references/security-checklist.md\` se tocar em auth
5. Retorna findings categorizados por severity (high/med/low)

## Referências
- Checklist completo: \`references/security-checklist.md\`
- Padrões do repo: \`references/repo-conventions.md\`

Receita pra description de qualidade

Exemplo — .claude/agents/code-reviewer.md

---
name: code-reviewer
description: Use proactively when the user finishes implementing a feature or before merging a PR. Specializes in catching correctness bugs.
tools: Read, Grep, Glob, Bash(git diff:*)
model: claude-opus-4-6
---

You are a senior code reviewer focused on correctness.

## Your role
- Read the diff carefully
- Flag correctness bugs (NOT style — linter handles that)
- Check edge cases (null, empty, off-by-one, race conditions)
- Note security risks (SQLi, XSS, path traversal, auth bypass)

## Output format
A numbered list of findings:
1. **[severity]** file:line — what's wrong, why, suggested fix

Be terse. No fluff.

Description com "proactively" — o segredo

A palavra "proactively" na description é um sinal forte pro Claude principal: "use isto SEM o usuário pedir, quando o contexto bater". Sem ela, o sub-agent quase nunca dispara sozinho.

description: Use proactively when... // dispara sozinho
description: Use when the user explicitly asks... // só sob pedido

.mcp.json (projeto)

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "postgres": {
      "command": "uvx",
      "args": ["mcp-server-postgres", "--db-url", "${DATABASE_URL}"]
    },
    "linear": {
      "type": "http",
      "url": "https://mcp.linear.app/sse",
      "headers": { "Authorization": "Bearer ${LINEAR_TOKEN}" }
    }
  }
}

Allowlist em settings.json

{
  "enabledMcpjsonServers": ["github", "postgres"],   // só estes ativam
  "permissions": {
    "allow": [
      "mcp__github",                          // libera tudo do server
      "mcp__postgres__query"                  // libera tool específica
    ]
  }
}

Exemplo prático

---
name: branch-status
description: Mostra contexto da branch atual antes de propor próxima ação
---

# Status da branch

Branch atual: `!git branch --show-current`
Último commit: `!git log -1 --oneline`

Diff vs main:
`!git diff main...HEAD --stat`

Com base no acima, sugira o próximo passo.

Quando você invoca /branch-status, Claude já recebe um SKILL.md preenchido com os outputs reais. Não precisa pedir "rode git status" — já está lá.

plugin.json — manifesto

{
  "name": "meu-plugin",
  "version": "1.2.0",
  "description": "Conjunto de skills pra refatorar TypeScript",
  "author": "@meu-handle",
  "skills": ["./skills/ts-refactor", "./skills/ts-test-gen"],
  "agents": ["./agents/ts-reviewer.md"],
  "commands": ["./commands/refactor.md"],
  "hooks": [{ "event": "PostToolUse", "matcher": "Edit", "command": "./scripts/format.sh" }]
}