Para especificações técnicas completas e esquemas, veja Referência de plugins. Para gerenciamento de marketplace, veja Marketplaces de plugins.
Os plugins permitem que você estenda o Claude Code com funcionalidades personalizadas que podem ser compartilhadas entre projetos e equipes. Instale plugins de marketplaces para adicionar comandos, agentes, hooks e servidores MCP pré-construídos, ou crie os seus próprios para automatizar seus fluxos de trabalho.

​
Início rápido

Vamos criar um plugin de saudação simples para familiarizá-lo com o sistema de plugins. Construiremos um plugin funcional que adiciona um comando personalizado, testá-lo localmente e entender os conceitos principais.

​
Pré-requisitos

  • Claude Code instalado em sua máquina
  • Familiaridade básica com ferramentas de linha de comando

​
Crie seu primeiro plugin

1

Crie a estrutura do marketplace

mkdir test-marketplace
cd test-marketplace
2

Crie o diretório do plugin

mkdir my-first-plugin
cd my-first-plugin
3

Crie o manifesto do plugin

Create .claude-plugin/plugin.json
mkdir .claude-plugin
cat > .claude-plugin/plugin.json << 'EOF'
{
"name": "my-first-plugin",
"description": "A simple greeting plugin to learn the basics",
"version": "1.0.0",
"author": {
"name": "Your Name"
}
}
EOF
4

Adicione um comando personalizado

Create commands/hello.md
mkdir commands
cat > commands/hello.md << 'EOF'
---
description: Greet the user with a personalized message
---

# Hello Command

Greet the user warmly and ask how you can help them today. Make the greeting personal and encouraging.
EOF
5

Crie o manifesto do marketplace

Create marketplace.json
cd ..
mkdir .claude-plugin
cat > .claude-plugin/marketplace.json << 'EOF'
{
"name": "test-marketplace",
"owner": {
"name": "Test User"
},
"plugins": [
{
  "name": "my-first-plugin",
  "source": "./my-first-plugin",
  "description": "My first test plugin"
}
]
}
EOF
6

Instale e teste seu plugin

Start Claude Code from parent directory
cd ..
claude
Add the test marketplace
/plugin marketplace add ./test-marketplace
Install your plugin
/plugin install my-first-plugin@test-marketplace
Selecione “Install now”. Você precisará reiniciar o Claude Code para usar o novo plugin.
Try your new command
/hello
Você verá o Claude usar seu comando de saudação! Verifique /help para ver seu novo comando listado.
Você criou e testou com sucesso um plugin com estes componentes principais:
  • Manifesto do plugin (.claude-plugin/plugin.json) - Descreve os metadados do seu plugin
  • Diretório de comandos (commands/) - Contém seus comandos de barra personalizados
  • Marketplace de teste - Permite testar seu plugin localmente

​
Visão geral da estrutura do plugin

Seu plugin segue esta estrutura básica: 
my-first-plugin/
├── .claude-plugin/
│   └── plugin.json          # Plugin metadata
├── commands/                 # Custom slash commands (optional)
│   └── hello.md
├── agents/                   # Custom agents (optional)
│   └── helper.md
└── hooks/                    # Event handlers (optional)
    └── hooks.json
Componentes adicionais que você pode adicionar:
  • Comandos: Crie arquivos markdown no diretório commands/
  • Agentes: Crie definições de agentes no diretório agents/
  • Hooks: Crie hooks/hooks.json para manipulação de eventos
  • Servidores MCP: Crie .mcp.json para integração de ferramentas externas
Próximos passos: Pronto para adicionar mais recursos? Pule para Desenvolver plugins mais complexos para adicionar agentes, hooks e servidores MCP. Para especificações técnicas completas de todos os componentes de plugins, veja Referência de plugins.

​
Instalar e gerenciar plugins

Aprenda como descobrir, instalar e gerenciar plugins para estender suas capacidades do Claude Code.

​
Pré-requisitos

  • Claude Code instalado e executando
  • Familiaridade básica com interfaces de linha de comando

​
Adicionar marketplaces

Marketplaces são catálogos de plugins disponíveis. Adicione-os para descobrir e instalar plugins:
Add a marketplace
/plugin marketplace add your-org/claude-plugins
Browse available plugins
/plugin
Para gerenciamento detalhado de marketplace incluindo repositórios Git, desenvolvimento local e distribuição de equipe, veja Marketplaces de plugins.

​
Instalar plugins

​
Via menu interativo (recomendado para descoberta)

Open the plugin management interface
/plugin
Selecione “Browse Plugins” para ver opções disponíveis com descrições, recursos e opções de instalação.

​
Via comandos diretos (para instalação rápida)

Install a specific plugin
/plugin install formatter@your-org
Enable a disabled plugin
/plugin enable plugin-name@marketplace-name
Disable without uninstalling
/plugin disable plugin-name@marketplace-name
Completely remove a plugin
/plugin uninstall plugin-name@marketplace-name

​
Verificar instalação

Após instalar um plugin:
  1. Verificar comandos disponíveis: Execute /help para ver novos comandos
  2. Testar recursos do plugin: Experimente os comandos e recursos do plugin
  3. Revisar detalhes do plugin: Use /plugin → “Manage Plugins” para ver o que o plugin fornece

​
Configurar fluxos de trabalho de plugins de equipe

Configure plugins no nível do repositório para garantir ferramentas consistentes em sua equipe. Quando os membros da equipe confiam na pasta do seu repositório, o Claude Code instala automaticamente marketplaces e plugins especificados. Para configurar plugins de equipe:
  1. Adicione configuração de marketplace e plugin ao .claude/settings.json do seu repositório
  2. Membros da equipe confiam na pasta do repositório
  3. Plugins instalam automaticamente para todos os membros da equipe
Para instruções completas incluindo exemplos de configuração, configuração de marketplace e melhores práticas de implementação, veja Configurar marketplaces de equipe.

​
Desenvolver plugins mais complexos

Uma vez que você esteja confortável com plugins básicos, você pode criar extensões mais sofisticadas.

​
Organizar plugins complexos

Para plugins com muitos componentes, organize sua estrutura de diretório por funcionalidade. Para layouts de diretório completos e padrões de organização, veja Estrutura de diretório de plugins.

​
Testar seus plugins localmente

Ao desenvolver plugins, use um marketplace local para testar mudanças iterativamente. Este fluxo de trabalho se baseia no padrão de início rápido e funciona para plugins de qualquer complexidade.
1

Configure sua estrutura de desenvolvimento

Organize seu plugin e marketplace para teste:
Create directory structure
mkdir dev-marketplace
cd dev-marketplace
mkdir my-plugin
Isso cria:
dev-marketplace/
├── .claude-plugin/marketplace.json  (you'll create this)
└── my-plugin/                        (your plugin under development)
    ├── .claude-plugin/plugin.json
    ├── commands/
    ├── agents/
    └── hooks/
2

Crie o manifesto do marketplace

Create marketplace.json
mkdir .claude-plugin
cat > .claude-plugin/marketplace.json << 'EOF'
{
"name": "dev-marketplace",
"owner": {
"name": "Developer"
},
"plugins": [
{
  "name": "my-plugin",
  "source": "./my-plugin",
  "description": "Plugin under development"
}
]
}
EOF
3

Instale e teste

Start Claude Code from parent directory
cd ..
claude
Add your development marketplace
/plugin marketplace add ./dev-marketplace
Install your plugin
/plugin install my-plugin@dev-marketplace
Teste os componentes do seu plugin:
  • Experimente seus comandos com /command-name
  • Verifique se os agentes aparecem em /agents
  • Verifique se os hooks funcionam como esperado
4

Itere em seu plugin

Após fazer mudanças no código do seu plugin:
Uninstall the current version
/plugin uninstall my-plugin@dev-marketplace
Reinstall to test changes
/plugin install my-plugin@dev-marketplace
Repita este ciclo conforme você desenvolve e refina seu plugin.
Para múltiplos plugins: Organize plugins em subdiretórios como ./plugins/plugin-name e atualize seu marketplace.json adequadamente. Veja Fontes de plugins para padrões de organização.

​
Depurar problemas de plugins

Se seu plugin não estiver funcionando como esperado:
  1. Verifique a estrutura: Certifique-se de que seus diretórios estão na raiz do plugin, não dentro de .claude-plugin/
  2. Teste componentes individualmente: Verifique cada comando, agente e hook separadamente
  3. Use ferramentas de validação e depuração: Veja Ferramentas de depuração e desenvolvimento para comandos CLI e técnicas de solução de problemas

​
Compartilhar seus plugins

Quando seu plugin estiver pronto para compartilhar:
  1. Adicione documentação: Inclua um README.md com instruções de instalação e uso
  2. Versione seu plugin: Use versionamento semântico em seu plugin.json
  3. Crie ou use um marketplace: Distribua através de marketplaces de plugins para instalação fácil
  4. Teste com outros: Peça para membros da equipe testarem o plugin antes de distribuição mais ampla
Para especificações técnicas completas, técnicas de depuração e estratégias de distribuição, veja Referência de plugins.

​
Próximos passos

Agora que você entende o sistema de plugins do Claude Code, aqui estão caminhos sugeridos para diferentes objetivos:

​
Para usuários de plugins

  • Descobrir plugins: Navegue por marketplaces da comunidade para ferramentas úteis
  • Adoção de equipe: Configure plugins no nível do repositório para seus projetos
  • Gerenciamento de marketplace: Aprenda a gerenciar múltiplas fontes de plugins
  • Uso avançado: Explore combinações de plugins e fluxos de trabalho

​
Para desenvolvedores de plugins

  • Crie seu primeiro marketplace: Guia de marketplaces de plugins
  • Componentes avançados: Aprofunde-se em componentes específicos de plugins:
    • Comandos de barra - Detalhes de desenvolvimento de comandos
    • Subagentes - Configuração e capacidades de agentes
    • Hooks - Manipulação de eventos e automação
    • MCP - Integração de ferramentas externas
  • Estratégias de distribuição: Empacote e compartilhe seus plugins efetivamente
  • Contribuição da comunidade: Considere contribuir para coleções de plugins da comunidade

​
Para líderes de equipe e administradores

  • Configuração de repositório: Configure instalação automática de plugins para projetos de equipe
  • Governança de plugins: Estabeleça diretrizes para aprovação de plugins e revisão de segurança
  • Manutenção de marketplace: Crie e mantenha catálogos de plugins específicos da organização
  • Treinamento e documentação: Ajude membros da equipe a adotar fluxos de trabalho de plugins efetivamente

​
Veja também