Objetivo: ao final, o consultor entende plugin como unidade instalável e versionada, sabe o que ele consegue empacotar, e reconhece quando vale plugin em vez de .claude/ solto.
bin/ e um settings.json padrão. Na prática, o Nível 3 inteiro cabe num plugin.plugin.json vai dentro de .claude-plugin/. Todas as outras pastas ficam na raiz do plugin — inverter isso é o erro mais comum./wayon-sap:revisao-spec), o que evita colisão entre plugins. Comece solto em .claude/ e empacote quando for compartilhar.wayon-sap/
├── .claude-plugin/
│ └── plugin.json # SÓ o manifesto vai aqui
├── skills/
│ ├── revisao-spec/
│ │ └── SKILL.md
│ └── derivar-testes/
│ └── SKILL.md
├── agents/
│ └── revisor-abap.md
├── hooks/
│ └── hooks.json
├── .mcp.json
└── settings.json
| Diretório / arquivo | Para que serve |
|---|---|
.claude-plugin/plugin.json |
Manifesto: identidade e versão do plugin |
skills/ |
Skills, como pasta <nome>/SKILL.md (módulo 2.4) |
commands/ |
Formato antigo, arquivos .md soltos — use skills/ em plugin novo |
agents/ |
Subagentes (módulo 2.7) |
hooks/hooks.json |
Hooks (módulo 3.2) |
.mcp.json |
Servidores MCP (módulo 3.1) |
.lsp.json |
Servidores LSP, para inteligência de código |
monitors/monitors.json |
Monitores que vigiam log ou arquivo em segundo plano |
bin/ |
Executáveis que entram no PATH do Bash enquanto o plugin está ativo |
settings.json |
Configuração padrão aplicada quando o plugin é ativado (aula 3.3.3) |
Plugin que traz uma única skill pode colocar o SKILL.md direto na raiz, sem criar skills/. Para plugin que pode crescer, use a pasta.
{
"name": "wayon-sap",
"description": "Skills, subagentes e hooks padrão da Wayon para projeto SAP",
"version": "1.2.0",
"author": { "name": "Wayon" }
}
| Campo | Obrigatório? | Detalhe |
|---|---|---|
name |
Sim — é o único obrigatório | É o namespace: define o prefixo das skills (/wayon-sap:...) |
description |
Não | Aparece no gerenciador de plugins, na hora de instalar |
version |
Não | Se você omitir e distribuir por git, o SHA do commit é usado — e cada commit conta como versão nova. Para controlar quando o time recebe atualização, declare e incremente |
author |
Não | Atribuição |
O próprio manifesto é opcional, se os componentes estiverem nos lugares padrão. Mas sem ele você perde controle de versão e descrição — em plugin da consultoria, escreva.
.claude/ solto?Standalone (.claude/) |
Plugin | |
|---|---|---|
| Nome da skill | /revisao-spec |
/wayon-sap:revisao-spec |
| Compartilhar | Copiar arquivo à mão | /plugin install |
| Versão | Não existe | Declarada e rastreada |
| Serve para | Experimentar, projeto único, uso pessoal | Time, comunidade, uso em vários projetos |
Caminho recomendado: comece solto, itere rápido, empacote quando for compartilhar. Migrar depois é mecânico — copiar as pastas para a raiz do plugin e mover o bloco hooks do settings.json para hooks/hooks.json, que usa o mesmo formato.
Ao migrar, remova os arquivos originais de
.claude/. Subagente definido em.claude/agents/do projeto ou do usuário sobrescreve um subagente de plugin com o mesmo nome — então a versão do plugin só passa a valer depois que o original sai. Com skill é diferente: por ser namespaced,/revisao-spece/wayon-sap:revisao-speccoexistem, e você fica com duas.
claude --plugin-dir ./wayon-sap
Carrega o plugin direto do diretório, sem instalar. Depois de qualquer alteração, /reload-plugins recarrega sem reiniciar a sessão — plugins, skills, subagentes, hooks e servidores MCP e LSP do plugin.
Se um plugin carregado com --plugin-dir tem o mesmo nome de um instalado, a cópia local vence naquela sessão — o que permite testar mudança sem desinstalar a versão publicada.
Regra Wayon Plugin da Wayon sempre declara
versionexplícita no manifesto. Sem esse campo, a distribuição por git usa o SHA do commit, e cada commit vira uma versão nova para todo mundo — o time recebe atualização a cada ajuste de vírgula, sem ninguém decidir. Versão declarada é o que separa "eu commitei" de "o time recebeu".
📖 Criar plugins · Referência de plugins
skills/, agents/ e hooks/ dentro de .claude-plugin/, junto do manifesto. O que acontece?.claude-plugin/ é a raiz do plugin, e tudo do plugin vive láA raiz do plugin é o diretório de cima; .claude-plugin/ é apenas onde mora o manifesto.
plugin.json vai dentro de .claude-plugin/; o resto fica na raiz do pluginCorreto. É o erro que a própria documentação destaca por ser o mais comum.
O namespace vem do campo name do manifesto, não da localização das pastas — e neste caso o problema é mais grave: os componentes não são encontrados.
plugin.json, e por quê?version, porque sem ela não há como distribuir atualizaçãoversion é opcional; sem ela, a distribuição por git usa o SHA do commit.
description, porque é o que aparece no gerenciador na hora de instalarAjuda quem instala, mas é opcional.
name, porque é ele que define o namespace das skills do pluginCorreto. É o que faz /wayon-sap:revisao-spec e evita colisão entre plugins.
wayon-sap por git, sem declarar version no manifesto. Um consultor corrige um typo numa description e faz commit. O que o time recebe?version declarada, o SHA do commit é usado, e cada commit conta como versão novaCorreto. É por isso que a Regra Wayon exige version explícita em plugin da consultoria.
/plugin update explicitamenteO mecanismo de versão é o que decide o que é atualização; sem version, cada commit já é uma.
O que conta é o commit, não a natureza da alteração.
revisor-abap de .claude/agents/ para dentro do plugin, mas deixou o arquivo original no lugar. Qual versão vale? ---É o contrário para subagente: a definição em .claude/agents/ do projeto ou do usuário sobrescreve a do plugin com o mesmo nome.
.claude/agents/ — ela sobrescreve o subagente de mesmo nome do plugin, então é preciso remover o originalCorreto. É o passo que falta em migração feita pela metade.
Skill coexiste porque é namespaced; subagente de mesmo nome, não — um sobrescreve o outro.