🗂️ Estrutura de arquivos e manifesto

Um mod é uma pasta. O nome da pasta é livre. O que o Claude Code procura dentro dela é fixo: .claude-plugin/plugin.json e hooks/hooks.json.

O terceiro arquivo é o módulo, com a função register. Ele mora em hooks/, ao lado do hooks.json. Testes, tipos e README são extras: ajudam, mas o mod carrega sem eles.

Como ler o desenho: os dois quadros verdes são os nomes que o Claude Code procura. A seta azul mostra que o hooks.json não tem código: ele só diz qual arquivo carregar. O quadro tracejado é o que você acrescenta para testar e tipar.

git clone https://github.com/inematds/claude-mods-starter-kit
cd claude-mods-starter-kit

O manifesto do starter-mod tem quatro campos. O mais importante é name: ele identifica o plugin em todo lugar, do prefixo da saída de um comando à chave das opções guardadas.

Compare com o recibo-sessao, do kit INEMA. Ele acrescenta types (o contrato de tipos do estado) e userConfig (uma opção que aparece no /config).

{
  "name": "read-counter-example",
  "version": "0.1.0",
  "description": "Teaching example: count successful Read events.",
  "author": {
    "name": "Prompt Advisers"
  }
}

{
  "name": "recibo-sessao",
  "version": "0.1.0",
  "description": "Recibo da sessão: lista o que o Claude criou ou alterou, com botão para abrir a pasta (/recibo, /recibo ultimo, /recibo limpar)",
  "author": { "name": "INEMA", "email": "inematds@gmail.com" },
  "types": "./types/index.d.ts",
  "userConfig": {
    "abridor": {
      "type": "string",
      "title": "Programa que abre pastas",
      "description": "xdg-open no Linux, open no Mac, explorer no Windows.",
      "default": "xdg-open",
      "options": ["xdg-open", "open", "explorer"]
    }
  }
}

O que olhar na tabela: só name aparece em três lugares diferentes. Trocar o nome depois muda a chave das opções guardadas e o nome de instalação. Escolha cedo (módulo 1.4, tópico 6).

O hooks/hooks.json tem uma chave só: modules, com um caminho. O caminho é relativo ao próprio hooks.json, não à raiz do plugin.

Por isso o starter-mod escreve ./starter.mjs, e não ./hooks/starter.mjs. O módulo apontado pode importar outros arquivos do mod com import normal; esses não entram no hooks.json.

{"modules":["./starter.mjs"]}

{ "modules": ["./register.tsx"] }

O módulo e todo arquivo que ele importa precisam ter uma destas extensões: .ts, .tsx, .jsx, .js, .mjs, .cjs, .mts ou .cts. Arquivo com outro nome não é carregado.

E tem um detalhe que engana: é sempre ES module, qualquer que seja a extensão. Um .cjs aqui não vira CommonJS. Nada de require nem module.exports: use import e export.

O que olhar na tabela: a escolha é sobre conforto, não sobre poder. O Claude Code lê TypeScript direto. Os tipos servem ao seu editor e ao tsc, não ao carregamento.

Cada campo de userConfig vira uma opção. O valor escolhido chega no segundo argumento de register(on, options), já com o padrão preenchido. No recibo-sessao, o mod lê options.abridor.

Um campo string com a lista options vira um seletor no /config, só com aqueles valores. Um valor guardado fora da lista conta como "não definido", e vale o default.

Como ler o desenho: você escreve só a primeira caixa. O Claude Code cuida do seletor e da gravação. O mod nunca lê o settings.json: ele recebe o valor pronto em options, e recebe de novo quando a pessoa troca.

O claude plugin validate lê o manifesto e o código do módulo do jeito que o engine vai ler, sem abrir sessão. Ele lista os eventos que o módulo pendura e os métodos do $ que chama.

É o teste mais barato que existe. Rode a cada mudança no manifesto ou no hooks.json. Se o evento que você escreveu não aparece na lista, o nome está errado.

claude plugin validate templates/starter-mod

Validating plugin manifest: .../templates/starter-mod/.claude-plugin/plugin.json

Validating hooks: .../templates/starter-mod/hooks/hooks.json

  ❯ ./starter.mjs hooks: session.start, tool.call{tool=Read}, command.run{command=readcount}
  ❯ ./starter.mjs calls: $.command.register

✔ Validation passed