Adicionar componentes a um plugin

​

Explorar o diretório do plugin

• Uma skill de revisão e um comando about
• Um subagente de revisão de segurança
• Um hook que formata arquivos após Claude editá-los, e a pasta scripts/ que ele chama
• Um monitor de log
• Um estilo de saída e um tema de cor
• Um workflow de auditoria de rotas
• Um executável hello-plugin
• Configurações padrão
• Um servidor MCP local e um servidor de linguagem Go

​

Adicionar cada tipo de componente

​

Skills

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── review/
        └── SKILL.md

---
description: Reviews a pull request for style and test coverage. Use when asked to review code.
---

Review the changed files. Report style problems first, then missing tests.

• Nome do comando: /<plugin>:<directory>, então skills/review/SKILL.md em my-plugin é /my-plugin:review. Se você definir name no frontmatter, ele substitui o último segmento e o prefixo do plugin permanece. Consulte como uma skill obtém seu nome de comando
• Quem a invoca: Claude, o usuário ou ambos, controlado pelo frontmatter. Consulte Controlar quem invoca uma skill

• Diretórios adicionais: liste-os na chave de manifesto skills. Eles adicionam à varredura padrão skills/ em vez de substituí-la, diferentemente de commands e agents
• Uma única skill na raiz do plugin: sem diretório skills/ e sem chave de manifesto skills, um SKILL.md na raiz do plugin carrega como uma skill. Defina name em seu frontmatter, porque caso contrário uma instalação de marketplace nomeia a skill após seu diretório de cache em vez de seu plugin

​

Comandos

​

Definir comandos no manifesto

{
  "name": "my-plugin",
  "commands": {
    "about": {
      "content": "Summarize what this repository does in three sentences.",
      "description": "Summarize the repository"
    }
  }
}

​

Agentes

---
name: security-reviewer
description: Reviews code changes for security issues. Use after edits to authentication or input handling.
model: sonnet
---

You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.

​

Organizar agentes em subpastas

• Frontmatter name: ele substitui apenas o nome do arquivo, então name: audit em agents/review/security.md carrega como my-plugin:review:audit
• Campo de manifesto agents: um arquivo que você lista lá carrega sem nomes de subpasta, então "agents": "./custom/review/security.md" carrega como my-plugin:security

​

Campos de frontmatter em agentes de plugin

• Campos suportados: name, description, model, effort, maxTurns, tools, disallowedTools, skills, memory, background, omitClaudeMd, isolation, color e a chave cacheTtl de experimental. O único valor isolation válido é "worktree". Consulte campos de frontmatter suportados para saber o que cada um faz
• Campos ignorados: permissionMode, hooks, mcpServers e initialPrompt. Um arquivo de agente não pode adicionar hooks ou servidores MCP por conta própria, então adicione-os como plugin hooks e servidores MCP em vez disso
• Frontmatter que não analisa: o agente ainda carrega com cada campo ignorado. É nomeado após o arquivo, e sua descrição lê Agent from my-plugin plugin. Execute claude plugin validate no seu shell para encontrar esses arquivos

​

Hooks

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/format.sh\""
          }
        ]
      }
    ]
  }
}

​

Quando os hooks do plugin disparam

​

Ambiente, citação e correspondência de ferramentas MCP

• Ambiente: cada processo de hook recebe CLAUDE_PLUGIN_ROOT e CLAUDE_PLUGIN_DATA em seu ambiente, mais CLAUDE_PLUGIN_OPTION_<KEY> para cada valor de configuração do usuário, para que seu script possa lê-los de lá
• Citação: quando command não tem args, ele é executado através de um shell, então envolva o caminho ${CLAUDE_PLUGIN_ROOT} em aspas duplas, como o exemplo hooks/hooks.json em Hooks faz, para manter o caminho expandido como uma palavra de shell. Quando você passa args em vez disso, cada elemento é passado como um argumento sem shell e não precisa de citação. Consulte forma exec e forma shell
• Correspondência das próprias ferramentas MCP do plugin: uma ferramenta de um servidor MCP que este plugin declara é nomeada mcp__plugin_<plugin>_<server>__<tool>, então escreva esse nome completo no matcher. Um matcher apenas no nome do servidor nunca dispara. Consulte Corresponder ferramentas MCP

​

Servidores MCP

{
  "mcpServers": {
    "db": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  }
}

​

Alcançar usuários em claude.ai e Cowork

​

Nomes de servidor, nomes de ferramentas e recarregamentos

• Nome do servidor: plugin:<plugin>:<server>, então o servidor db em my-plugin é plugin:my-plugin:db em /mcp. Use a mesma forma para nomear o servidor em um hook mcp_tool
• Nomes de ferramentas: mcp__plugin_<plugin>_<server>__<tool>, então uma ferramenta query naquele servidor db é mcp__plugin_my-plugin_db__query. Esse é o nome a usar em regras de permissão e matchers de hook
• Substituição: ${CLAUDE_PLUGIN_ROOT} e as outras variáveis de caminho são substituídas em command, args e env. Nenhuma citação é necessária em args, porque cada elemento é passado como um argumento
• Recarga: quando o usuário executa /reload-plugins e o recarga se aplica, um servidor cuja configuração não foi alterada mantém sua conexão. Um servidor cuja configuração mudou se reconecta, e um que você removeu se desconecta

​

Incluir um servidor MCPB empacotado

{
  "name": "my-plugin",
  "mcpServers": "./servers/db.mcpb"
}

​

Servidores LSP

{
  "gopls": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

• Binário ausente: Claude Code inicia command por nome do PATH do usuário. Quando o binário não está lá, o servidor falha ao iniciar e claude --debug registra LSP server <name> failed to start
• Conflitos de extensão: quando dois servidores habilitados reivindicam a mesma extensão, o primeiro registrado manipula esses arquivos e o outro não é usado para eles, se os servidores vêm de um plugin ou dois. A aba Errors de /plugin mostra o aviso LSP server "<name>" is not used for <ext> files

​

Executáveis

#!/bin/bash
echo "hello from my-plugin"

​

Configurações padrão

{
  "agent": "security-reviewer"
}

• Arquivo sobre manifesto: quando ambos existem e settings.json define pelo menos uma chave suportada, settings.json se aplica e o settings do manifesto é ignorado
• Configurações do usuário sobre padrões do plugin: entre fontes de configurações, padrões de plugin são a camada mais baixa, então um agent próprio do usuário em ~/.claude/settings.json substitui o seu
• Dois plugins definem a mesma chave: o valor do plugin carregado por último se aplica, e claude --debug registra overrides setting

​

Temas e estilos de saída

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555"
  }
}

​

Canais

{
  "name": "my-plugin",
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": { "BOT_TOKEN": "${user_config.bot_token}" }
    }
  },
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        }
      }
    }
  ]
}

​

Monitores

[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]

• Apenas sessões interativas: monitores de plugin iniciam em uma sessão interativa e nunca em modo não-interativo com a flag -p. Eles também iniciam apenas onde a ferramenta Monitor está disponível
• Sem configuração do usuário: command obtém as variáveis de caminho e ${ENV_VAR} do ambiente, mas nunca ${user_config.*}. Um monitor que referencia um não inicia, e processos de monitor não recebem CLAUDE_PLUGIN_OPTION_<KEY> também
• Desabilitação no meio da sessão: se você desabilitar um plugin no meio da sessão, Claude Code não para monitores que já estão em execução. Eles param quando a sessão termina

​

Solicitar ao usuário valores de configuração

{
  "name": "my-plugin",
  "userConfig": {
    "api_url": {
      "type": "string",
      "title": "API URL",
      "description": "Base URL of your team's API"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "Token for your team's API",
      "sensitive": true
    }
  }
}

​

Quando o diálogo de configuração aparece

• Instala o plugin em /plugin
• Executa /plugin install <plugin>@<marketplace> dentro de uma sessão
• Habilita o plugin da aba Installed em /plugin

​

Referenciar caminhos de plugin e armazenar dados

• ${CLAUDE_PLUGIN_ROOT}: o diretório de instalação do plugin. Cada versão tem seu próprio diretório de cache, então o caminho muda quando o plugin é atualizado. Não escreva estado lá
• ${CLAUDE_PLUGIN_DATA}: um diretório que sobrevive a atualizações, para node_modules, ambientes virtuais e caches. Ele se resolve para ~/.claude/plugins/data/<id>/ e é criado quando primeiro referenciado
• ${CLAUDE_PROJECT_DIR}: a raiz do projeto, o mesmo valor que hooks recebem

​

Instalar dependências no diretório de dados

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
          }
        ]
      }
    ]
  }
}

​

Próximos passos

• Referência de manifesto de plugin: campos plugin.json, regras de caminho e o layout padrão
• Testar plugins com evals: verifique se os componentes que você adicionou alteram o comportamento de Claude da forma que você pretende
• Publicar e distribuir um plugin: versione o plugin e coloque-o em um marketplace
• Solucionar problemas de plugins: o que fazer quando um componente não carrega ou um hook não dispara