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

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

<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

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

```
<plugin-name>@<marketplace>
```

**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/<nome>/
□ 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/<categoria>/<nome>.md
□ Frontmatter com name, description, model
□ description com exemplos
□ Persona definida
□ Output format especificado
□ Versão bumped
□ CHANGELOG actualizado
```

### Novo Command

```
□ Ficheiro: commands/<nome>.md ou commands/<namespace>/<nome>.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