Referência de plugins

​

Referência de componentes de plugin

​

Skills

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (opcional)
│   └── scripts/ (opcional)
└── code-reviewer/
    └── SKILL.md

• Skills e comandos são descobertos automaticamente quando o plugin é instalado
• Claude pode invocá-los automaticamente com base no contexto da tarefa
• Skills podem incluir arquivos de suporte ao lado de SKILL.md

​

Agents

---
name: agent-name
description: No que este agent se especializa e quando Claude deve invocá-lo
model: sonnet
effort: medium
maxTurns: 20
disallowedTools: Write, Edit
---

Prompt de sistema detalhado para o agent descrevendo seu papel, expertise e comportamento.

• Agents aparecem na typeahead @-mention sob seu nome com escopo, como my-plugin:code-reviewer, uma vez que o plugin está habilitado
• Claude pode invocar agents automaticamente com base no contexto da tarefa
• Agents podem ser invocados manualmente por usuários
• Agents de plugin funcionam ao lado de agents Claude integrados

​

Hooks

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

• command: executar comandos shell ou scripts
• http: enviar o JSON do evento como uma solicitação POST para uma URL
• mcp_tool: chamar uma ferramenta em um servidor MCP configurado
• prompt: avaliar um prompt com um LLM (usa placeholder $ARGUMENTS para contexto)
• agent: executar um verificador agentic com ferramentas para tarefas de verificação complexas

​

MCP servers

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    },
    "plugin-api-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"]
    }
  }
}

• Servidores MCP de plugin iniciam automaticamente quando o plugin é habilitado
• Servidores aparecem como ferramentas MCP padrão no kit de ferramentas de Claude
• Capacidades do servidor se integram perfeitamente com as ferramentas existentes de Claude
• Servidores de plugin podem ser configurados independentemente de servidores MCP do usuário

​

LSP servers

• Diagnósticos instantâneos: Claude vê erros e avisos imediatamente após cada edição
• Navegação de código: ir para definição, encontrar referências e informações de hover
• Consciência de linguagem: informações de tipo e documentação para símbolos de código

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

{
  "name": "my-plugin",
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": {
        ".go": "go"
      }
    }
  }
}

​

Monitors

[
  {
    "name": "deploy-status",
    "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
    "description": "Mudanças de status de implantação"
  },
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Log de erro da aplicação",
    "when": "on-skill-invoke:debug"
  }
]

​

Themes

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

​

Escopos de instalação de plugin

​

Plugins de diretório de skills

​

Escolha de onde o plugin carrega

• Servidores MCP que declara passam pela mesma aprovação por servidor que um .mcp.json de projeto
• Servidores LSP iniciam apenas depois que você confia no workspace
• Monitors de fundo não carregam

​

Editar, recarregar e desabilitar um plugin de diretório de skills

claude plugin disable my-tool@skills-dir

​

Esquema de manifesto de plugin

​

Esquema completo

{
  "name": "plugin-name",
  "displayName": "Plugin Name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "skills": "./custom/skills/",
  "commands": ["./custom/commands/special.md"],
  "agents": ["./custom/agents/reviewer.md"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./monitors.json"
  },
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

​

Campos obrigatórios

​

Campos não reconhecidos

claude plugin validate ./my-plugin --strict

​

Campos de metadados

​

Habilitação padrão

• A configuração do usuário: uma entrada para o plugin em enabledPlugins em qualquer escopo de configurações. Uma vez escrita, persiste entre atualizações e reinstalações de plugin, então mudar defaultEnabled em uma versão posterior não inverte um usuário existente.
• Um requisito de dependência: quando um plugin é necessário por outro que está ativo, Claude Code escreve true para ele no momento da instalação ou habilitação. Isso lhe dá uma configuração explícita, então seu próprio padrão não se aplica mais. Veja Habilitar ou desabilitar um plugin com dependências.

​

Campos de caminho de componente

​

Componentes experimentais

​

Configuração do usuário

{
  "userConfig": {
    "api_endpoint": {
      "type": "string",
      "title": "API endpoint",
      "description": "O endpoint de API da sua equipe"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "Token de autenticação de API",
      "sensitive": true
    }
  }
}

​

Canais

{
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Token do bot Telegram",
          "sensitive": true
        },
        "owner_id": {
          "type": "string",
          "title": "Owner ID",
          "description": "Seu ID de usuário Telegram"
        }
      }
    }
  ]
}

​

Regras de comportamento de caminho

• Substitui o padrão: commands, agents, outputStyles, experimental.themes, experimental.monitors. Por exemplo, quando o manifesto especifica commands, o diretório padrão commands/ não é verificado. Para manter o padrão e adicionar mais, liste-o explicitamente: "commands": ["./commands/", "./extras/"]
• Adiciona ao padrão: skills. O diretório padrão skills/ é sempre verificado, e diretórios listados em skills são carregados junto com ele. Exceção: para uma entrada do marketplace cuja source resolve para a raiz do marketplace, declarar subdiretórios específicos substitui a verificação padrão skills/
• Regras de mesclagem próprias: hooks, MCP servers e LSP servers. Veja cada seção para como múltiplas fontes se combinam

• Todos os caminhos devem ser relativos à raiz do plugin e começar com ./
• Componentes de caminhos personalizados usam as mesmas regras de nomenclatura e namespacing
• Múltiplos caminhos podem ser especificados como arrays
• Quando um caminho de skill aponta para um diretório que contém um SKILL.md diretamente, por exemplo "skills": ["./"] apontando para a raiz do plugin, o campo frontmatter name em SKILL.md determina o nome de invocação da skill. Isso fornece um nome estável independentemente do diretório de instalação. Se name não estiver definido no frontmatter, o nome base do diretório é usado como fallback.

{
  "commands": [
    "./specialized/deploy.md",
    "./utilities/batch-process.md"
  ],
  "agents": [
    "./custom-agents/reviewer.md",
    "./custom-agents/tester.md"
  ]
}

​

Variáveis de ambiente

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/process.sh"
          }
        ]
      }
    ]
  }
}

​

Diretório de dados persistente

{
  "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\""
          }
        ]
      }
    ]
  }
}

{
  "mcpServers": {
    "routines": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": {
        "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
      }
    }
  }
}

​

Cache de plugin e resolução de arquivo

• Através de claude --plugin-dir ou claude --plugin-url, pela duração de uma sessão.
• Através de um marketplace, instalado para sessões futuras.

​

Limitações de travessia de caminho

​

Compartilhar arquivos dentro de um marketplace com symlinks

• Dentro do próprio diretório do plugin: o symlink é preservado como um symlink relativo no cache, então ele continua resolvendo para o alvo copiado em tempo de execução.
• Em outro lugar dentro do mesmo marketplace: o symlink é desreferenciado. O conteúdo do alvo é copiado para o cache em seu lugar. Isso permite que o diretório skills/ de um meta-plugin seja vinculado a skills definidas por outros plugins no marketplace.
• Fora do marketplace: o symlink é ignorado por segurança. Isso impede que plugins puxem arquivos arbitrários do host, como caminhos do sistema, para o cache.

ln -s ../../shared-plugin/skills/foo ./skills/foo

​

Estrutura de diretório de plugin

​

Layout de plugin padrão

enterprise-plugin/
├── .claude-plugin/           # Diretório de metadados (opcional)
│   └── plugin.json             # manifesto de plugin
├── skills/                   # Skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── commands/                 # Skills como arquivos .md planos
│   ├── status.md
│   └── logs.md
├── agents/                   # Definições de subagent
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── output-styles/            # Definições de estilo de saída
│   └── terse.md
├── themes/                   # Definições de tema de cor
│   └── dracula.json
├── monitors/                 # Configurações de monitor de fundo
│   └── monitors.json
├── hooks/                    # Configurações de hook
│   ├── hooks.json           # Configuração de hook principal
│   └── security-hooks.json  # Hooks adicionais
├── bin/                      # Executáveis de plugin adicionados a PATH
│   └── my-tool               # Invocável como comando bare na ferramenta Bash
├── settings.json            # Configurações padrão para o plugin
├── .mcp.json                # Definições de servidor MCP
├── .lsp.json                # Configurações de servidor LSP
├── scripts/                 # Scripts de hook e utilitário
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # Arquivo de licença
└── CHANGELOG.md             # Histórico de versão

​

Referência de localizações de arquivo

​

Referência de comandos CLI

​

plugin init

claude plugin init <name> [options]

• <name>: Nome do plugin. Torna-se o namespace de skill e o nome do diretório sob ~/.claude/skills/, então não pode conter espaços ou separadores de caminho.

# Criar um plugin mínimo
claude plugin init my-helper

# Criar com pastas de skill e hook
claude plugin init my-helper --with skills hooks

# Sobrescrever um scaffold existente
claude plugin init my-helper --force

​

plugin install

claude plugin install <plugin> [options]

• <plugin>: Nome do plugin ou plugin-name@marketplace-name para um marketplace específico

# Instalar em escopo de usuário (padrão)
claude plugin install formatter@my-marketplace

# Instalar em escopo de projeto (compartilhado com equipe)
claude plugin install formatter@my-marketplace --scope project

# Instalar em escopo local (gitignored)
claude plugin install formatter@my-marketplace --scope local

​

plugin uninstall

claude plugin uninstall <plugin> [options]

• <plugin>: Nome do plugin ou plugin-name@marketplace-name

​

plugin prune

claude plugin prune [options]

​

plugin enable

claude plugin enable <plugin> [options]

• <plugin>: Nome do plugin ou plugin-name@marketplace-name

​

plugin disable

claude plugin disable <plugin> [options]

• <plugin>: Nome do plugin ou plugin-name@marketplace-name

​

plugin update

claude plugin update <plugin> [options]

• <plugin>: Nome do plugin ou plugin-name@marketplace-name

​

plugin list

claude plugin list [options]

​

plugin details

claude plugin details <name>

• <name>: Nome do plugin ou plugin-name@marketplace-name

• Always-on: tokens adicionados a cada sessão pelo texto de listagem do plugin, como descrições de skill, descrições de agent e nomes de comando, independentemente de qualquer componente disparar.
• On-invoke: tokens que um componente custa quando dispara. Mostrado por componente, não como total do plugin, porque uma sessão típica invoca apenas um subconjunto de componentes.

dependency-guard 1.2.0
  Dependency analysis for Claude Code sessions
  Source: dependency-guard@example-marketplace

Component inventory
  Skills (2)  scan-dependencies, review-changes
  Agents (0)
  Hooks (1)  (harness-only — no model context cost)
  MCP servers (0)
  LSP servers (0)

Projected token cost
  Always-on:   ~180 tok   added to every session

Per-component (rounded)
  component            always-on  on-invoke
  scan-dependencies        ~100      ~2400
  review-changes            ~80      ~1800

  On-invoke cost is paid each time a skill or agent fires.
  Token counts are estimates and may differ from actual usage.

​

plugin tag

claude plugin tag [options]

​

Ferramentas de depuração e desenvolvimento

​

Comandos de depuração

• Quais plugins estão sendo carregados
• Quaisquer erros em manifestos de plugin
• Registro de skill, agent e hook
• Inicialização de servidor MCP

​

Problemas comuns

​

Exemplos de mensagens de erro

• Invalid JSON syntax: Unexpected token } in JSON at position 142: verificar vírgulas ausentes, vírgulas extras ou strings não citadas
• Plugin has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Required: um campo obrigatório está faltando
• Plugin has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...: erro de sintaxe JSON

• Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.: caminho de comando existe mas não contém arquivos de comando válidos
• Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.: o caminho source em marketplace.json aponta para um diretório inexistente
• Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.: remover definições de componentes duplicadas ou remover strict: false na entrada do marketplace

​

Solução de problemas de hook

1. Verificar se o script é executável: chmod +x ./scripts/your-script.sh
2. Verificar a linha shebang: Primeira linha deve ser #!/bin/bash ou #!/usr/bin/env bash
3. Verificar se o caminho usa ${CLAUDE_PLUGIN_ROOT}: "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/your-script.sh"
4. Testar o script manualmente: ./scripts/your-script.sh

1. Verificar se o nome do evento está correto (sensível a maiúsculas): PostToolUse, não postToolUse
2. Verificar se o padrão de matcher corresponde às suas ferramentas: "matcher": "Write|Edit" para operações de arquivo
3. Confirmar se o tipo de hook é válido: command, http, mcp_tool, prompt, ou agent

​

Solução de problemas de servidor MCP

1. Verificar se o comando existe e é executável
2. Verificar se todos os caminhos usam variável ${CLAUDE_PLUGIN_ROOT}
3. Verificar os logs do servidor MCP: claude --debug mostra erros de inicialização
4. Testar o servidor manualmente fora do Claude Code

1. Garantir que o servidor está adequadamente configurado em .mcp.json ou plugin.json
2. Verificar se o servidor implementa o protocolo MCP corretamente
3. Verificar timeouts de conexão na saída de depuração

​

Erros de estrutura de diretório

my-plugin/
├── .claude-plugin/
│   └── plugin.json      ← Apenas manifesto aqui
├── commands/            ← No nível raiz
├── agents/              ← No nível raiz
└── hooks/               ← No nível raiz

1. Executar claude --debug e procurar por mensagens “loading plugin”
2. Verificar se cada diretório de componente está listado na saída de depuração
3. Verificar se as permissões de arquivo permitem ler os arquivos de plugin

​

Referência de distribuição e versionamento

​

Gerenciamento de versão

1. O campo version no plugin.json do plugin
2. O campo version na entrada do marketplace do plugin em marketplace.json
3. O SHA do commit git do plugin, para fontes github, url, git-subdir e relative-path em um marketplace hospedado em git
4. unknown, para fontes npm ou diretórios locais não dentro de um repositório git

​

Veja também

• Plugins - Tutoriais e uso prático
• Marketplaces de plugins - Criando e gerenciando marketplaces
• Skills - Detalhes de desenvolvimento de skill
• Subagents - Configuração e capacidades de agent
• Hooks - Manipulação de eventos e automação
• MCP - Integração de ferramenta externa
• Configurações - Opções de configuração para plugins