feat(v1.5.2): Execute database migrations and complete setup
- Execute all 6 migrations on Desk CRM production database - Create missing tables: cr_lsps, cr_agent_lsps, cr_lsp_usage - Create archive tables: cr_*_usage_archive (4 tables) - Create system tables: cr_migrations, cr_maintenance_log - Make all scripts executable (chmod +x) - Total cr_* tables: 38 Migration files: - 001_initial_schema.sql - 002_add_lsps.sql - 003_add_relationships.sql - 004_add_telemetry.sql - 005_add_archive_tables.sql - 006_add_maintenance_log.sql Scripts: - session-init.sh, session-end.sh - inject-context.sh, inject-agent-context.sh - record-usage.sh, db-backup.sh, sync-to-mysql.sh Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
508
docs/04-GUIA-PLUGINS.md
Executable file
508
docs/04-GUIA-PLUGINS.md
Executable file
@@ -0,0 +1,508 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user