🧩 Skills, sub-agents, and MCP in Claude Code

Complete structure

.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

Complete SKILL.md (real example)

---
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\`

Recipe for a quality description

Example — .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 with “proactively” — the secret

The word “proactively” in the description is a strong signal to the main Claude: “use this WITHOUT the user asking, when the context matches.” Without it, the subagent almost never fires on its own.

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

.mcp.json (project)

{
  "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 in settings.json

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

Practical example

---
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.

When you invoke /branch-status, Claude already receives an SKILL.md populated with the actual outputs. No need to ask "run git status" — it's already there.

plugin.json — manifest

{
  "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" }]
}