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 interface /agents
• 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
• 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"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

• 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"
      }
    }
  }
}

​

Escopos de instalação de plugin

​

Esquema de manifesto de plugin

​

Esquema completo

{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "[email protected]",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "commands": ["./custom/commands/special.md"],
  "agents": "./custom/agents/",
  "skills": "./custom/skills/",
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json"
}

​

Campos obrigatórios

​

Campos de metadados

​

Campos de caminho de componente

​

Configuração do usuário

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

​

Canais

{
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": { "description": "Token do bot Telegram", "sensitive": true },
        "owner_id": { "description": "Seu ID de usuário Telegram", "sensitive": false }
      }
    }
  ]
}

​

Regras de comportamento de caminho

• Se commands/ existe, é carregado além de caminhos de comando personalizados
• Todos os caminhos devem ser relativos à raiz do plugin e começar com ./
• Comandos de caminhos personalizados usam as mesmas regras de nomenclatura e namespacing
• Múltiplos caminhos podem ser especificados como arrays para flexibilidade

{
  "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, pela duração de uma sessão.
• Através de um marketplace, instalado para sessões futuras.

​

Limitações de travessia de caminho

​

Trabalhando com dependências externas

# Dentro de seu diretório de plugin
ln -s /path/to/shared-utils ./shared-utils

​

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
├── commands/                 # Localização de comando padrão
│   ├── status.md
│   └── logs.md
├── agents/                   # Localização de agent padrão
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── skills/                   # Skills de Agent
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── hooks/                    # Configurações de hook
│   ├── hooks.json           # Configuração de hook principal
│   └── security-hooks.json  # Hooks adicionais
├── 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 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 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

​

Ferramentas de depuração e desenvolvimento

​

Comandos de depuração

• Quais plugins estão sendo carregados
• Quaisquer erros em manifestos de plugin
• Registro de comando, 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, 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

{
  "name": "my-plugin",
  "version": "2.1.0"
}

• MAJOR: Mudanças de quebra (mudanças de API incompatíveis)
• MINOR: Novos recursos (adições compatíveis com versões anteriores)
• PATCH: Correções de bugs (correções compatíveis com versões anteriores)

• Começar em 1.0.0 para seu primeiro lançamento estável
• Atualizar a versão em plugin.json antes de distribuir mudanças
• Documentar mudanças em um arquivo CHANGELOG.md
• Usar versões de pré-lançamento como 2.0.0-beta.1 para testes

​

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