# Guia Definitivo: Plugins Claude Code **Versão:** 2.0 | **Data:** 2026-02-04 | **Autor:** Descomplicar® --- ## 1. Conceitos Fundamentais ### O que são Plugins? Plugins são **pacotes de extensibilidade baseados em ficheiros Markdown** que estendem as capacidades do Claude Code. Não requerem código compilado - são directórios com convenções de estrutura específicas. ### Componentes de um Plugin | Componente | Descrição | Localização | |------------|-----------|-------------| | **Skills** | Conhecimento e workflows | `skills//SKILL.md` | | **Agents** | Agentes especializados | `agents//.md` | | **Commands** | Comandos invocáveis | `commands/.md` | | **MCPs** | Servidores bundled | `plugin.json` | ### Filosofia Core > **Skills são "onboarding guides"** - transformam Claude de agente generalista em especialista equipado com conhecimento procedimental. **Princípios:** 1. **Progressive Disclosure** - Informação em camadas 2. **Agent-Native** - Tudo via tools 3. **Composability** - Novas features = novos prompts 4. **YAGNI** - Só o necessário --- ## 2. Estrutura de Ficheiros ### Estrutura Mínima ``` meu-plugin/ ├── .claude-plugin/ │ └── plugin.json # OBRIGATÓRIO ├── skills/ │ └── minha-skill/ │ └── SKILL.md # OBRIGATÓRIO └── README.md ``` ### Estrutura Completa ``` meu-plugin/ ├── .claude-plugin/ │ └── plugin.json # Manifest ├── agents/ │ ├── review/ # Categoria │ │ └── meu-reviewer.md │ ├── research/ │ │ └── meu-researcher.md │ └── workflow/ │ └── meu-workflow.md ├── commands/ │ ├── workflows/ # Namespace │ │ ├── plan.md │ │ └── work.md │ └── utility-command.md ├── skills/ │ └── minha-skill/ │ ├── SKILL.md │ ├── scripts/ │ │ └── helper.py │ ├── references/ │ │ └── api-docs.md │ └── assets/ │ └── template.html ├── CLAUDE.md # Regras dev ├── CHANGELOG.md # Histórico ├── README.md # Docs └── LICENSE ``` --- ## 3. Manifest (plugin.json) ### Localização ``` .claude-plugin/plugin.json ``` ### Schema Completo ```json { "name": "meu-plugin", "version": "1.0.0", "description": "Descrição do plugin. X agents, Y commands, Z skills.", "author": { "name": "Descomplicar®", "email": "dev@descomplicar.pt", "url": "https://descomplicar.pt" }, "homepage": "https://docs.descomplicar.pt/plugins/meu-plugin", "repository": "https://git.descomplicar.pt/plugins/meu-plugin", "license": "MIT", "keywords": [ "keyword1", "keyword2", "domain-specific" ], "mcpServers": { "meu-mcp": { "type": "http", "url": "https://mcp.descomplicar.pt/meu-mcp" } } } ``` ### Campos Obrigatórios | Campo | Descrição | |-------|-----------| | `name` | Identificador único (kebab-case) | | `version` | Versão semver (MAJOR.MINOR.PATCH) | | `description` | Descrição com contagem de componentes | ### Campos Recomendados | Campo | Descrição | |-------|-----------| | `author` | Informação do autor | | `license` | MIT recomendado | | `repository` | URL do repositório | | `keywords` | Palavras-chave | | `mcpServers` | MCPs bundled | --- ## 4. Commands ### Estrutura de um Command ```markdown --- name: command-name description: Descrição curta argument-hint: "[descrição dos argumentos]" --- # Título do Comando ## Argumentos #$ARGUMENTS **Se vazio:** "O que pretende fazer?" ## Workflow ### 1. [Fase] [Instruções] ### 2. [Fase] [Instruções] ## Output [O que é produzido] ``` ### Namespacing **Problema:** Colisão com comandos built-in (`/plan`, `/review`). **Solução:** Usar namespace. ``` commands/ ├── workflows/ # Namespace "workflows:" │ ├── plan.md → /workflows:plan │ └── work.md → /workflows:work └── utility.md → /utility ``` --- ## 5. Versionamento ### Regra Crítica **TODA mudança requer actualização de 3 ficheiros:** 1. `.claude-plugin/plugin.json` → Bump version 2. `CHANGELOG.md` → Documentar mudança 3. `README.md` → Verificar contagens ### Regras Semver | Tipo | Quando | Exemplo | |------|--------|---------| | **MAJOR** | Breaking changes | 1.0.0 → 2.0.0 | | **MINOR** | Novos componentes | 1.0.0 → 1.1.0 | | **PATCH** | Bug fixes, docs | 1.0.0 → 1.0.1 | ### Formato CHANGELOG ```markdown # Changelog ## [Unreleased] ### Added - Nova skill para X ## [1.1.0] - 2026-02-04 ### Added - Agent: code-simplicity-reviewer - Command: /workflows:plan ### Changed - Melhorada description da skill Y ### Fixed - Corrigido link em references/api.md ## [1.0.0] - 2026-01-15 ### Added - Release inicial - 5 skills, 3 agents, 2 commands ``` --- ## 6. Nomenclatura ### Convenções | Componente | Convenção | Exemplo | |------------|-----------|---------| | Plugin | kebab-case | `meu-plugin` | | Skill | kebab-case | `api-design` | | Agent | kebab-case | `code-reviewer` | | Command | namespace:nome | `workflows:plan` | | Directório | kebab-case | `my-skill/` | ### Namespace Composto ``` @ ``` **Marketplaces:** - `anthropic-agent-skills` - Oficial - `every-marketplace` - Every.to - `claude-code-workflows` - Workflows - `descomplicar` - Interno --- ## 7. MCPs Bundled ### Declaração ```json { "mcpServers": { "context7": { "type": "http", "url": "https://mcp.context7.com/mcp" }, "local-mcp": { "type": "stdio", "command": "node", "args": ["./mcp-server/index.js"] } } } ``` ### Tipos | Tipo | Descrição | |------|-----------| | `http` | MCP remoto via HTTP | | `stdio` | MCP local via stdin/stdout | --- ## 8. Documentação ### Ficheiros | Ficheiro | Propósito | Audiência | |----------|-----------|-----------| | `README.md` | Docs pública | Utilizadores | | `CLAUDE.md` | Regras dev | Contribuidores | | `CHANGELOG.md` | Histórico | Todos | | `LICENSE` | Termos | Legal | ### README.md ```markdown # Nome do Plugin > Tagline curta ## Instalação ```bash claude /plugin install nome-plugin ``` ## Componentes ### Skills (X) | Skill | Descrição | |-------|-----------| | skill-1 | Faz X | ### Agents (Y) | Agent | Descrição | |-------|-----------| | agent-1 | Especializado em Y | ### Commands (Z) | Command | Descrição | |---------|-----------| | /cmd-1 | Executa Z | ## Uso [Exemplos] ## Licença MIT ``` --- ## 9. Anti-Patterns | Anti-Pattern | Problema | Solução | |--------------|----------|---------| | Segunda pessoa | "Use this when..." | "This should be used when..." | | Backticks refs | `` `references/file.md` `` | `[file](./references/file.md)` | | Sem namespace | `name: plan` | `name: workflows:plan` | | Versão errada | `v1.0` | `1.0.0` | | Skills gigantes | Contexto esgotado | Usar references/ | | Código em SKILL | Difícil testar | Usar scripts/ | --- ## 10. Checklists ### Nova Skill ``` □ Directório: skills// □ SKILL.md com frontmatter válido □ name em kebab-case □ description em terceira pessoa □ references/ linkados como markdown □ Versão bumped □ CHANGELOG actualizado □ README contagens actualizadas ``` ### Novo Agent ``` □ Ficheiro: agents//.md □ Frontmatter com name, description, model □ description com exemplos □ Persona definida □ Output format especificado □ Versão bumped □ CHANGELOG actualizado ``` ### Novo Command ``` □ Ficheiro: commands/.md ou commands//.md □ Namespace usado se necessário □ #$ARGUMENTS incluído □ Workflow documentado □ Versão bumped □ CHANGELOG actualizado ``` ### Release ``` □ Todos os componentes testados □ Versão semver em plugin.json □ description com contagens □ CHANGELOG completo □ README actualizado □ Sem ficheiros temporários □ Links funcionais □ LICENSE presente □ Git tag criada ``` --- ## 11. Estrutura Descomplicar ### Plugins Internos ``` ~/.claude/plugins/descomplicar/ ├── marketing/ │ ├── .claude-plugin/plugin.json │ ├── skills/ │ │ ├── seo-master/ │ │ ├── copywriting/ │ │ └── cro/ │ └── agents/ │ └── marketing-strategist.md ├── engineering/ │ ├── skills/ │ │ ├── php-master/ │ │ ├── frontend-master/ │ │ └── database/ │ └── agents/ │ └── senior-fullstack.md ├── wordpress/ │ ├── skills/ │ │ ├── wp-dev/ │ │ └── woocommerce/ │ └── agents/ │ └── wordpress-expert.md └── ... ``` ### Registo no Component Registry ```sql INSERT INTO cr_plugins (name, slug, version, description, path, author, status) VALUES ( 'Plugin Marketing', 'descomplicar-marketing', '1.0.0', 'Plugin Marketing Descomplicar. 7 skills, 1 agent.', '~/.claude/plugins/descomplicar/marketing', 'Descomplicar®', 'active' ); ``` --- ## 12. Template Plugin Descomplicar ### plugin.json ```json { "name": "descomplicar-[domain]", "version": "1.0.0", "description": "Plugin [Domain] Descomplicar®. X skills, Y agents, Z commands.", "author": { "name": "Descomplicar®", "email": "dev@descomplicar.pt", "url": "https://descomplicar.pt" }, "homepage": "https://docs.descomplicar.pt/plugins/[domain]", "repository": "https://git.descomplicar.pt/plugins/descomplicar-[domain]", "license": "MIT", "keywords": [ "descomplicar", "[domain]", "[keyword1]", "[keyword2]" ], "mcpServers": {} } ``` ### Estrutura ``` descomplicar-[domain]/ ├── .claude-plugin/ │ └── plugin.json ├── skills/ │ └── [skill-1]/ │ ├── SKILL.md │ └── references/ ├── agents/ │ └── [agent-1].md ├── CLAUDE.md ├── CHANGELOG.md ├── README.md └── LICENSE ``` --- **Referências:** - [Claude Code Plugins](https://code.claude.com/docs/en/plugins) - [compound-engineering](https://github.com/EveryInc/compound-engineering) - Exemplo de referência - [document-skills](https://github.com/anthropics/anthropic-agent-skills) - Skills Anthropic