Modelos do Claude Code: skills, agents, hooks e mais

O que são os modelos do Claude Code?

Os modelos do Claude Code são arquivos de configuração reutilizáveis que personalizam como o Claude Code se comporta em um projeto ou em todo o seu ambiente local. 

O ponto-chave é que os modelos são baseados em arquivos. Você não os instala por uma interface de configurações tradicional, clicando em telas. Em vez disso, o Claude Code detecta pastas e arquivos específicos, carrega os metadados relevantes no contexto e usa essas informações para decidir como agir.

Na prática, eles geralmente são arquivos em Markdown, JSON ou shell, armazenados em pastas no nível do projeto como .claude/, ou empacotados em diretórios no estilo de plugin para compartilhamento.

Uma estrutura típica no nível do projeto pode ser assim:

my-app/
├── CLAUDE.md
├── .mcp.json
└── .claude/
    ├── skills/
    │   └── database-migration/
    │       └── SKILL.md
    ├── agents/
    │   └── security-auditor.md
    ├── commands/
    │   └── summarize-pr.md
    └── settings.json

Modelos do Claude Code vs CLAUDE.md

CLAUDE.md continua importante, mas cumpre outro papel. Pense no CLAUDE.md como o briefing do projeto: o que é o projeto, quais comandos importam, quais padrões de código se aplicam e quais convenções de arquitetura o Claude deve lembrar. 

Para um passo a passo mais completo, veja nosso guia de escrita do CLAUDE.md.

Os modelos são mais modulares:

• Uma skill pode codificar um fluxo de migração. 
• Um agent pode isolar a persona de revisão de segurança. 
• Um hook pode rodar após edições de arquivos. 
• Uma configuração MCP pode conectar o Claude ao GitHub, ao SQLite ou a outro sistema externo.

É aqui também que os modelos se conectam ao design mais amplo do fluxo de trabalho do Claude Code. Modelos bem feitos funcionam melhor quando combinados com bons hábitos de planejamento, testes e passagem de contexto. 

Mais práticas desse tipo estão detalhadas no nosso guia de boas práticas.

Comandos personalizados também são cobertos pelo sistema de skills, embora o formato legado .claude/commands/ ainda funcione. O novo formato recomendado é .claude/skills/<name>/SKILL.md, que dá suporte a invocação por slash-command e à invocação automática pelo Claude.

Quais tipos de modelos do Claude Code posso usar?

O ecossistema de modelos do Claude Code normalmente é organizado em seis categorias: skills, agents, commands, hooks, integrações MCP e plugins. 

As cinco primeiras mudam diretamente o comportamento do Claude. Plugins são um pouco diferentes: são um formato de distribuição que pode agrupar skills, agents, hooks, commands, servidores MCP e outros componentes em um pacote reutilizável.

Vamos explorar cada uma delas a seguir.

1. Skills

Skills são pacotes de instruções para tarefas repetíveis e de múltiplas etapas. Uma skill normalmente é uma pasta contendo um arquivo SKILL.md com frontmatter em YAML e corpo em Markdown. 

O frontmatter descreve o que a skill faz e como deve se comportar; o corpo indica ao Claude quais passos seguir. Para um mergulho dedicado, veja este guia de Claude Skills.

O Claude usa a descrição da skill para decidir quando ela é relevante. Por padrão, tanto o usuário quanto o Claude podem invocar uma skill: você pode digitar /nome-da-skill, ou o Claude pode carregá-la automaticamente quando a tarefa atual corresponder à descrição. Você também pode desativar a invocação automática em fluxos que exigem controle manual, como deploy.

Aqui vai um exemplo curto de arquivo: .claude/skills/database-migration/SKILL.md

---
name: database-migration
description: Use when creating, reviewing, or modifying database migrations. Ensures migrations are reversible, tested, and checked before and after execution.
allowed-tools:
  - Read
  - Write
  - Bash
---

# Database Migration Skill

When working on a database migration:

1. Inspect the existing schema and migration history before writing changes.
2. Confirm whether the migration is additive, destructive, or data-transforming.
3. Create a reversible migration whenever the framework supports rollback.
4. Run the project’s migration check command before applying the migration.
5. Run tests that cover the affected models, queries, or API endpoints.
6. After writing the migration, summarize:
   - schema changes
   - rollback behavior
   - affected tables
   - test commands run

Isso é útil porque as instruções são procedimentais. Você não está apenas dizendo ao Claude para “ter cuidado com migrações”. Você está oferecendo um checklist repetível. 

Skills são ideais para tudo o que você colaria no Claude mais de duas vezes: gerar endpoints de API, escrever changelogs, criar testes, preparar notas de release, revisar pull requests ou executar checagens de migração.

Para mais inspiração sobre o que os desenvolvedores estão transformando em fluxos de trabalho de IA reutilizáveis, veja nossa lista de Agent Skills.

2. Agents

Agents, mais precisamente subagents personalizados no Claude Code, são assistentes de IA especializados com sua própria definição em Markdown, frontmatter em YAML, restrições de ferramentas, escolha de modelo e prompt de sistema. 

Eles podem ficar em .claude/agents/ para escopo do projeto ou em ~/.claude/agents/ para escopo pessoal. Agents são criados pedindo ao Claude ou editando diretamente arquivos markdown na pasta .claude/agents/.

Existe uma diferença entre skills e agents. Uma skill define como executar uma tarefa. Um agent define quem o Claude deve ser enquanto trabalha: seu papel, foco, permissões e limites.

Veja este exemplo de agent:

---
name: security-auditor
description: Reviews code for security vulnerabilities and produces a findings report without modifying files.
tools: Read, Glob, Grep, Bash
model: sonnet
---

You are a security auditor.

Your task is to inspect the codebase for vulnerabilities, risky patterns, and missing safeguards.

Rules:
- Do not edit files.
- Do not suggest broad rewrites unless directly tied to a security issue.
- Focus on authentication, authorization, input validation, secrets, dependency risk, and unsafe shell or SQL usage.
- Produce a findings report with severity, affected files, evidence, and recommended next steps.

Esse agent é útil porque dá limites claros ao Claude. Em uma sessão geral, o Claude pode acabar tentando corrigir problemas assim que os encontra. Um agent auditor de segurança é instruído a apenas inspecionar e reportar, evitando modificações. 

Agents são ideais para domínios especializados, como auditoria de segurança, revisão de documentação, revisão de arquitetura, engenharia de dados ou checagem de qualidade de código, onde isolamento de contexto e limites de permissão importam.

Agents também são ótimos quando combinados com skills especializadas. Por exemplo, um agent auditor de segurança pode chamar uma skill de relatório de achados, enquanto um agent revisor de frontend pode usar uma skill de testes de componentes.

3. Commands

Commands são atalhos invocados por slash, como /generate-tests, /check-deps ou /summarize-pr. Historicamente, comandos personalizados eram armazenados como arquivos Markdown em .claude/commands/, usando o nome do arquivo como nome do comando. 

O Claude Code ainda oferece suporte a esse formato legado, mas eu recomendo usar skills para novos fluxos de trabalho do tipo comando, pois elas aceitam a mesma invocação por /nome e podem ser acionadas automaticamente quando fizer sentido.

Commands são melhores quando você quer que o gatilho seja explícito. Uma skill pode ativar automaticamente quando o Claude detectar uma tarefa correspondente, mas um command deve rodar apenas quando você decidir. Isso torna commands úteis como checkpoints: “gerar testes agora”, “resumir este PR agora”, “checar dependências agora” ou “preparar a mensagem de commit agora”.

4. Hooks

Hooks são regras de automação que rodam em resposta a eventos do ciclo de vida do Claude Code. São comandos de shell definidos pelo usuário, executados em pontos específicos do ciclo de vida do Claude Code, dando controle determinístico sobre o comportamento. 

A diferença entre hooks e os outros modelos até aqui é que eles não são disparados pelo que você pede, e sim pelo que o Claude faz.

Em termos simples, você não precisa torcer para o Claude lembrar de formatar um arquivo após editá-lo; um hook pode fazer isso automaticamente.

Os nomes de eventos de hook atuais incluem itens como PreToolUse, PostToolUse, Notification e Stop. 

Exemplo: executar um formatador depois que o Claude edita ou escreve um arquivo:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

Example: block risky shell commands before Claude runs them:
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/block-dangerous-bash.py"
          }
        ]
      }
    ]
  }
}

Hooks são ideais para regras que o Claude não deve conseguir pular: rodar um linter, formatar arquivos editados, bloquear edições em arquivos protegidos, checar código gerado ou enviar notificações quando o Claude precisar de input. 

Para um tutorial detalhado, leia nosso guia de Claude Code Hooks.

5. Integrações MCP

Integrações MCP conectam o Claude Code a ferramentas externas, fontes de dados e APIs por meio do Model Context Protocol. O MCP atua como uma camada de conexão entre sistemas de IA e ferramentas externas. No Claude Code, isso significa que o Claude pode ir além de arquivos locais e comandos de shell. 

Isso permite que o Claude interaja com serviços externos como GitHub, bancos de dados, sistemas de documentação, plataformas de nuvem ou APIs internas, dependendo de quais servidores MCP você configurar. Para uma explicação completa e um projeto de demonstração, veja nosso tutorial sobre Model Context Protocol.

Um servidor MCP pode expor três tipos amplos de capacidade:

• Tools: funções executáveis que o Claude pode chamar, como criar uma issue no GitHub ou executar uma query no banco de dados.
• Resources: fontes de contexto somente leitura, como um arquivo, uma linha de banco ou um documento.
• Prompts: modelos de tarefas reutilizáveis expostos pelo servidor.

Um .mcp.json no nível do projeto pode configurar vários servidores lado a lado:

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "sqlite": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sqlite",
        "./data/app.db"
      ]
    }
  }
}

Isso é importante porque o Claude só consegue raciocinar a partir do contexto e das ferramentas às quais tem acesso. Sem MCP, ele pode inspecionar arquivos locais, mas não o seu tracker de issues, o banco de dados, o ambiente em nuvem ou a sua API interna. 

Use MCP quando o Claude precisar trabalhar com a stack real, em vez de um snapshot estático do código, e quando precisar de acesso a dados externos.

6. Plugins

Plugins são pacotes. Eles podem incluir skills, agents, hooks, configurações MCP, commands e outros componentes dentro de uma única estrutura instalável. 

No Claude Code, um plugin normalmente inclui um manifesto .claude-plugin/plugin.json e pastas de componentes como skills/, agents/, hooks/ e .mcp.json na raiz do plugin.

Exemplo de estrutura de plugin:

frontend-workflow-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── component-test/
│       └── SKILL.md
├── agents/
│   └── frontend-reviewer.md
├── hooks/
│   └── hooks.json
└── .mcp.json

Exemplo de plugin json:

{
  "name": "frontend-workflow",
  "displayName": "Frontend Workflow",
  "version": "1.0.0",
  "description": "Fluxo de desenvolvimento frontend com agents de revisão, skills de teste e hooks de formatação",
  "author": {
    "name": "Your Team"
  }
}

Plugins não adicionam um novo tipo de comportamento. Eles tornam os outros tipos portáteis. Use plugins quando quiser compartilhar uma configuração completa com o time, reutilizar o mesmo fluxo em vários projetos ou instalar um pacote mantido pela comunidade em vez de criar cada arquivo manualmente.

Para criar um do zero, veja o guia passo a passo de Claude Code Plugins da DataCamp.

Qual tipo de modelo devo escolher?

É totalmente compreensível: tantos tipos podem confundir. Todos mudam como o Claude se comporta. A diferença está principalmente em como são acionados e no tipo de controle que oferecem.

Para deixar mais claro, aqui vai uma comparação entre eles:

Uma regra simples de decisão ajuda:

• Se você quer impor uma regra automaticamente toda vez que o Claude tocar no código, use um hook. 
• Se quer que o Claude assuma uma expertise profunda de domínio para uma tarefa específica, use um agent. 
• Se quer codificar um fluxo de trabalho que o Claude deve repetir com consistência, use uma skill. 
• Se quer acionar uma ação você mesmo no momento certo, use um command ou uma skill do tipo command. 
• Se o Claude precisa de serviços externos ou dados em tempo real, use MCP. 
• Se quer instalar ou compartilhar uma configuração completa de fluxo, use um plugin.

Em projetos reais, esses tipos costumam ser combinados. Um plugin de segurança pode agrupar um agent security-auditor, uma skill audit-findings, um command de checagem de dependências e um hook de pre-commit. O agent define o papel, a skill define a estrutura do relatório, o command fornece um checkpoint explícito e o hook impõe a regra.

Para fluxos em que o Claude deve seguir um plano formal antes da implementação, o spec-driven development often é uma opção melhor do que prompts ad hoc.

Onde posso encontrar modelos do Claude Code?

Há três fontes práticas: Anthropic, coleções da comunidade e você mesmo.

Primeiro, comece com recursos oficiais da Anthropic e sua documentação. A documentação do Claude Code da Anthropic cobre skills, subagents, hooks, MCP e plugins, e é o melhor lugar para verificar formatos atuais de arquivos e comportamentos antes de publicar algo para produção.

Segundo, use coleções da comunidade. O hub mais visível é o aitmpl.com, que se descreve como um catálogo de configurações prontas para projetos com Claude Code. A navegação inclui Skills, Agents, Commands, Settings, Hooks, MCPs e Plugins. 

O comando de instalação interativa atual é:

npx claude-code-templates@latest

A documentação do projeto também mostra um atalho mais curto:

npx cct@latest

Para componentes específicos, o README no GitHub mostra comandos de instalação como:

npx claude-code-templates@latest --agent development-tools/code-reviewer --yes
npx claude-code-templates@latest --command performance/optimize-bundle --yes
npx claude-code-templates@latest --hook git/pre-commit-validation --yes
npx claude-code-templates@latest --mcp database/postgresql-integration --yes

Ele também mostra como instalar em lote uma stack completa usando várias flags em um único comando.

Ao avaliar modelos da comunidade, confira alguns sinais de qualidade:

• A description é específica o suficiente para o Claude acionar a skill ou o agent corretamente?

• As allowed-tools têm escopo restrito, ou o modelo pede permissões amplas de escrita e bash sem necessidade?

• O repositório foi mantido recentemente?

• O modelo explica o que ele altera?

• Ele inclui hooks ou servidores MCP que executam código que você não revisou?

Terceiro, escreva os seus próprios. Geralmente é a melhor resposta para fluxos estreitamente acoplados à sua stack. Um modelo da comunidade pode servir de base útil, mas não conhece sua política interna de migração, convenções de nomenclatura, modelo de dados ou tolerância a risco no deploy.

Considerações finais

Os modelos do Claude Code são a forma de transformar o Claude Code de um assistente por sessão em um ambiente de desenvolvimento persistente. 

As seis categorias mencionadas são camadas: skills codificam fluxos, agents definem papéis, commands criam ações explícitas, hooks impõem regras, MCP conecta sistemas externos e plugins empacotam tudo para reutilização.

O melhor ponto de partida não é um stack enorme de plugins. Comece com uma skill para o seu fluxo mais repetido. Quando perceber onde o comportamento padrão do Claude ainda gera atrito, adicione um agent para revisão especializada, um hook para imposição de regras ou um servidor MCP para acesso ao sistema em tempo real.

Para continuar aprendendo sobre Claude Code, confira nossos cursos Claude Code 101 e Claude Code in Action.