Criar um plugin Claude Code

• Nada ainda: siga Criar seu primeiro plugin, depois Desenvolver sem um marketplace e Testar e depurar.
• Arquivos sob .claude/ já existem: faça o passo a passo do primeiro plugin uma vez para aprender o layout, depois siga Converter uma configuração .claude/ existente.

​

Decidir quando usar um plugin

• Onde os arquivos vão: sob o diretório próprio do plugin, chamado de raiz do plugin, como skills/, agents/, hooks/hooks.json e .mcp.json.
• Como são nomeados: skills e agents do plugin recebem o nome do plugin como prefixo, como /my-plugin:hello, para que dois plugins possam cada um fornecer uma skill hello sem colidir.

​

Criar seu primeiro plugin

mkdir -p my-first-plugin/.claude-plugin

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

mkdir -p my-first-plugin/skills/hello

---
name: hello
description: Greet the user with a friendly message
disable-model-invocation: true
---

Greet the user warmly and ask how you can help them today.

claude plugin validate ./my-first-plugin

claude --plugin-dir ./my-first-plugin

/my-first-plugin:hello

​

Compartilhar seu plugin

• Envie-o para algumas pessoas diretamente: dê a elas o diretório do plugin ou um .zip dele, e nada precisa ser publicado. Veja Compartilhar um plugin sem um marketplace.
• Liste-o em seu próprio marketplace: colegas de equipe adicionam seu marketplace uma vez e instalam o plugin por nome, e recebem suas atualizações. Veja Publicar através de seu próprio marketplace.
• Envie-o para o marketplace da comunidade da Anthropic: uma vez listado, qualquer pessoa que adicione esse marketplace pode instalá-lo. Veja Enviar para o marketplace da comunidade.

​

Layout do plugin

​

Desenvolver sem um marketplace

• --plugin-dir: carrega um diretório ou arquivo .zip para uma sessão.
• --plugin-url: busca um arquivo .zip de uma URL para uma sessão.
• claude plugin init: estrutura um plugin sob ~/.claude/skills/ que carrega a cada sessão.

​

Carregar um plugin para uma sessão

​

De um diretório ou .zip

claude --plugin-dir ./my-first-plugin --plugin-dir ./other-plugin.zip

​

De uma pasta de plugins

• Uma subpasta que você adiciona carrega como um novo plugin assim que seu manifest existe.
• Quando você remove uma subpasta, seu plugin descarrega.

​

De uma URL

claude --plugin-url https://example.com/my-first-plugin.zip

​

De uma variável de ambiente

​

Fazer um plugin carregar em cada sessão

​

Estruturar o plugin com claude plugin init

claude plugin init my-tool

​

Nomear as skills do plugin

​

Parar de carregar o plugin

​

Compartilhar o plugin através de um repositório

​

Testar e depurar

1. Em seu shell, execute claude plugin validate <path>. Verifica o manifest e o frontmatter de cada arquivo de skill, agent e command, e sai com 0 em Validation passed. Adicione --strict para falhar em avisos também. Códigos de saída e manipulação de diretório estão na referência de comandos de plugin.
2. Na sessão em execução, execute /reload-plugins para aplicar edições que você fez no disco. Imprime uma linha Reloaded: com contagens. Depois confirme que uma skill carregou digitando seu comando /plugin-name:skill, ou encontrando o plugin na aba Installed de /plugin.
3. Na mesma sessão, execute /plugin. A aba Installed lista seu plugin e, nos detalhes do plugin, os componentes que Claude Code encontrou. A aba Errors lista o que falhou ao carregar e por quê, como um caminho em seu manifest que não existe.
4. De volta em seu shell, execute claude plugin list. Imprime plugins de sessão única e diretório de skills em suas próprias seções com Status: ✔ loaded ou o erro de carregamento. Para incluir o plugin que você está desenvolvendo, passe --plugin-dir com seu caminho antes de plugin list.

​

Um caminho de componente não é encontrado

​

--plugin-dir em uma raiz de marketplace não carrega os plugins sob plugins/

​

O plugin carrega mas suas skills estão faltando

​

O diálogo userConfig nunca aparece

​

Verificar que o plugin muda o comportamento de Claude

​

Converter uma configuração .claude/ existente

mkdir -p my-plugin/.claude-plugin

{
  "name": "my-plugin",
  "description": "Migrated from standalone configuration",
  "version": "1.0.0"
}

cp -r .claude/commands my-plugin/

cp -r .claude/agents my-plugin/

cp -r .claude/skills my-plugin/

mkdir -p my-plugin/hooks

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix" }]
      }
    ]
  }
}

claude --plugin-dir ./my-plugin

• Skills e agents: os dois conjuntos não colidem, porque as skills e agents do plugin carregam o prefixo my-plugin:. /deploy e /my-plugin:deploy funcionam ambos, e Claude vê reviewer e my-plugin:reviewer como dois subagents.
• Hooks: hooks não têm prefixo, então um hook que está em seu arquivo de configurações e em hooks/hooks.json executa duas vezes cada vez que seu evento dispara.

​

Próximos passos

• Componentes de plugin: adicione agents, hooks, servidores MCP, servidores LSP e configuração de usuário ao seu plugin
• Testar plugins com evals: escreva casos de eval e execute-os com claude plugin eval para verificar com que confiabilidade o plugin orienta o comportamento de Claude
• Publicar um plugin: versione-o, coloque-o em um marketplace e envie-o para o marketplace da comunidade
• Plugins em claude.ai e em Cowork: a mesma pasta de plugin instala em claude.ai e em Cowork. Alguns componentes são apenas Claude Code
• Referência do manifest do plugin: cada campo plugin.json, regra de caminho e diretório
• Skills: escreva as skills que seu plugin fornece
• Plugins da Anthropic no repositório claude-code: exemplos completos trabalhados do layout nesta página, como feature-dev e code-review