descomplicar-meta-plugin/docs/04-GUIA-PLUGINS.md

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/<nome>/SKILL.md
Agents	Agentes especializados	agents/<cat>/<nome>.md
Commands	Comandos invocáveis	commands/<nome>.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

{
  "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

---
name: command-name
description: Descrição curta
argument-hint: "[descrição dos argumentos]"
---

# Título do Comando

## Argumentos

<user_input> #$ARGUMENTS </user_input>

**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

# 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

<plugin-name>@<marketplace>

Marketplaces:

• anthropic-agent-skills - Oficial
• every-marketplace - Every.to
• claude-code-workflows - Workflows
• descomplicar - Interno

---

7. MCPs Bundled

Declaração

{
  "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

# 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

{
  "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
• compound-engineering - Exemplo de referência
• document-skills - Skills Anthropic