Nível 3 — Automação e escala · Módulo 3.3 — Plugins: distribuindo o setup do time

3.3.4 · Empacotando o `.claude` da Wayon

4 min de vídeo TEC BASIS

Objetivo: ao final, o consultor transforma um .claude/ funcional em plugin publicável e validado, pronto para entrar no marketplace da Wayon.

O que você precisa levar desta aula

A migração é mecânica: skills/ e agents/ são copiados sem alteração; o bloco hooks sai do settings.json e vai para hooks/hooks.json, no mesmo formato.
claude plugin validate ./plugin valida antes de publicar (--strict trata aviso como erro), e claude --plugin-dir ./plugin carrega para testar sem instalar.
Remova o subagente original de .claude/agents/ depois de migrar — ele sobrescreve o do plugin com o mesmo nome, e a versão do plugin não pega.

Antes e depois

Em `.claude/` (antes)	No plugin (depois)
`.claude/skills/revisao-spec/SKILL.md`	`wayon-sap/skills/revisao-spec/SKILL.md`
`.claude/agents/revisor-abap.md`	`wayon-sap/agents/revisor-abap.md`
Bloco `hooks` em `.claude/settings.json`	`wayon-sap/hooks/hooks.json`
`.mcp.json` do projeto	`wayon-sap/.mcp.json`
—	`wayon-sap/.claude-plugin/plugin.json` (novo)
`/revisao-spec`	`/wayon-sap:revisao-spec`

Os passos

# 1. casca do plugin
mkdir -p wayon-sap/.claude-plugin

# 2. componentes que vão sem alteração
cp -r .claude/skills wayon-sap/
cp -r .claude/agents wayon-sap/

# 3. hooks mudam de arquivo, não de formato
mkdir wayon-sap/hooks
# recorte o bloco "hooks" de .claude/settings.json para wayon-sap/hooks/hooks.json

# 4. testar sem instalar
claude --plugin-dir ./wayon-sap

# 5. validar antes de publicar
claude plugin validate ./wayon-sap

O manifesto, em wayon-sap/.claude-plugin/plugin.json:

{
  "name": "wayon-sap",
  "description": "Skills, subagentes e hooks padrão da Wayon para projeto SAP",
  "version": "1.0.0",
  "author": { "name": "Wayon" }
}

O que testar antes de publicar

Componente	Como confirmar
Skill	Invocar pelo nome namespaced: `/wayon-sap:revisao-spec`
Subagente	`/context` → aparece sob Custom Agents; ou @-mencionar pelo nome
Hook	Disparar o evento que ele casa de verdade (pedir uma edição, para um `PostToolUse`) e conferir o efeito
Tudo, depois de alterar	`/reload-plugins`, sem reiniciar a sessão

Hook é o que mais engana em teste: ele parece configurado e só se prova quando o evento acontece. E se o caminho de bloqueio usar exit 1, ele passa no teste visual e falha na prática — é a aula 3.2.4.

Ponto de partida da comunidade

secondsky/sap-skills tem skills voltadas a ABAP e CAP. Vale como ponto de partida a adaptar, com a mesma ressalva da aula 2.8.T3 e todo o peso da aula 3.3.3: ler antes, adaptar ao padrão da Wayon, e nunca instalar direto em máquina com dado de cliente sem passar pelo checklist.

Regra Wayon Nenhum plugin entra no marketplace da Wayon sem: version declarada, claude plugin validate passando, revisão de par, e confirmação de que não carrega particularidade de cliente (nome de sistema, transação Z, regra de negócio). O último item é o que impede que o plugin da casa se torne um canal de vazamento entre contas.

📖 Converter configuração em plugin · Distribuir um marketplace

Quiz — 4 questões

1.Ao migrar os hooks de .claude/settings.json para o plugin, o que muda no conteúdo?

a)Nada no formato — o bloco hooks é recortado e colado em hooks/hooks.json
Correto. Muda o arquivo, não a estrutura do JSON.
b)É preciso converter os matchers para o formato de plugin, que usa expressão diferente
Não há formato de matcher específico de plugin; a estrutura é a mesma.
c)Cada hook passa a precisar de um campo plugin identificando a origem
O namespacing do plugin não exige declaração dentro de cada hook.

Ver resposta e por quê

✅a) Correto. Muda o arquivo, não a estrutura do JSON.

❌b) Não há formato de matcher específico de plugin; a estrutura é a mesma.

❌c) O namespacing do plugin não exige declaração dentro de cada hook.

2.Você migrou tudo, publicou o plugin, o time instalou — e o subagente revisor-abap continua se comportando como na versão antiga. Qual é a causa mais provável?

a)O plugin precisa de /reload-plugins para os subagentes carregarem
Boa hipótese, e vale tentar, mas há uma causa mais específica quando o comportamento é o da versão antiga e não ausência de subagente.
b)O arquivo original ficou em .claude/agents/, e definição de projeto sobrescreve subagente de plugin com o mesmo nome
Correto. É o passo que falta em migração feita pela metade.
c)O name do plugin está errado, então o namespace não se aplica ao subagente
Namespace afeta invocação de skill; o sintoma descrito é de sobrescrita por definição local.

Ver resposta e por quê

❌a) Boa hipótese, e vale tentar, mas há uma causa mais específica quando o comportamento é o da versão antiga e não ausência de subagente.

✅b) Correto. É o passo que falta em migração feita pela metade.

❌c) Namespace afeta invocação de skill; o sintoma descrito é de sobrescrita por definição local.

3.Qual comando valida um plugin antes de publicá-lo no marketplace?

a)claude --plugin-dir ./wayon-sap, que falha se houver erro de estrutura
Carrega o plugin para teste, mas não é o validador — ele não emite relatório de validação.
b)claude plugin validate ./wayon-sap
Correto, e --strict faz aviso ser tratado como erro.
c)/reload-plugins, que reporta erros ao recarregar
Recarrega os componentes na sessão; não é a validação prévia à publicação.

Ver resposta e por quê

❌a) Carrega o plugin para teste, mas não é o validador — ele não emite relatório de validação.

✅b) Correto, e --strict faz aviso ser tratado como erro.

❌c) Recarrega os componentes na sessão; não é a validação prévia à publicação.

4.Qual é a forma correta de testar se um hook do plugin realmente funciona?

a)Conferir que o hooks/hooks.json está bem formado e que o plugin aparece instalado
Confirma que está configurado, não que funciona — hook se prova na execução.
b)Rodar claude plugin validate, que executa os hooks em modo de teste
A validação confere estrutura e metadados; ela não dispara os hooks.
c)Disparar de verdade o evento que ele casa e conferir o efeito — inclusive se o caminho de bloqueio usa exit 2
Correto. Hook parece configurado e só se prova no evento real; exit 1 passa em teste visual e falha na prática.

Ver resposta e por quê

❌a) Confirma que está configurado, não que funciona — hook se prova na execução.

❌b) A validação confere estrutura e metadados; ela não dispara os hooks.

✅c) Correto. Hook parece configurado e só se prova no evento real; exit 1 passa em teste visual e falha na prática.