descomplicar-meta-plugin/docs/06-TEMPLATES.md

# Templates de Componentes

**Versão:** 2.0 | **Data:** 2026-02-04 | **Autor:** Descomplicar®

---

## Template: Skill

```yaml
---
name: skill-name
description: >
  [Capacidade principal]. [Capacidades secundárias].
  Use when [trigger1], [trigger2], or when user mentions
  "[keyword1]", "[keyword2]", "[keyword3]".
author: Descomplicar®
version: 1.0.0
desk_task: XXXX
sdk: sdk-slug
allowed-tools: Read, Grep
---

# [Nome da Skill]

Skill para [objectivo principal] seguindo padrões Descomplicar®.

## Quando Usar

- [Cenário 1]
- [Cenário 2]
- [Cenário 3]

## Quando NÃO Usar

- [Limite 1] → usar /skill-x em vez
- [Limite 2] → fora do escopo

## Protocolo

### 1. Verificação Inicial

[Passos de verificação antes de agir]

### 2. Execução

[Passos principais]

### 3. Validação

[Como verificar que funcionou]

## Exemplos

### Exemplo 1: [Cenário Normal]

**Input:**
```
[Exemplo de input]
```

**Output:**
```
[Exemplo de output]
```

### Exemplo 2: [Edge Case]

**Input:**
```
[Edge case]
```

**Output:**
```
[Como é tratado]
```

## Recursos Adicionais

- [API Reference](./references/api.md)
- [Template Output](./assets/template.md)

## Integração

- **MCPs:** [lista]
- **Skills Relacionadas:** [lista]
- **Agents:** [lista]

---
*Skill v1.0.0 | Descomplicar® | desk.descomplicar.pt/tasks/view/XXXX*
```

---

## Template: Agent

```markdown
---
name: agent-slug
description: >
  [Capacidade principal] com expertise em [área 1], [área 2], [área 3].
  Usar para [trigger 1], [trigger 2], ou quando utilizador menciona
  "[keyword1]", "[keyword2]", "[keyword3]".
model: sonnet
tools: Read, Write, Edit, Grep, Glob
allowed-mcps: desk-crm-v3, filesystem
skills: skill-1, skill-2
category: dev
author: Descomplicar®
version: 1.0.0
desk_task: XXXX
---

# [Nome do Agente]

Agente especializado em [domínio] seguindo padrões Descomplicar®.

## Identidade

Sou um especialista em [área], com foco em [especialização].
Abordo problemas de forma [metódica/criativa/analítica].

## Especialização

### Domínio Principal

- [Área 1]
- [Área 2]
- [Área 3]

### Capacidades Técnicas

- [Capacidade 1]
- [Capacidade 2]
- [Capacidade 3]

## Workflow Padrão

### 1. Análise Inicial

- Compreender requisitos
- Identificar constraints
- Definir scope

### 2. Pesquisa

- Consultar MCPs relevantes
- Verificar padrões existentes
- Identificar dependências

### 3. Execução

- Implementar solução
- Seguir best practices
- Documentar decisões

### 4. Validação

- Testar resultado
- Verificar qualidade
- Confirmar com utilizador

## Colaborações

| Agente | Tipo | Quando |
|--------|------|--------|
| [agent-1] | technical | [cenário] |
| [agent-2] | cross-domain | [cenário] |

## Limites

### NÃO faço:

- [Limite 1] → delegar a [outro agente]
- [Limite 2] → fora do scope

### Escalar quando:

- [Condição 1]
- [Condição 2]

## MCPs Disponíveis

| MCP | Tipo | Uso |
|-----|------|-----|
| [mcp-1] | Primary | [função] |
| [mcp-2] | Recommended | [função] |

## Skills Integradas

- `/skill-1` - [descrição]
- `/skill-2` - [descrição]

## Output Format

```json
{
  "status": "success|partial|failed",
  "result": {},
  "confidence": 0.85,
  "next_steps": []
}
```

---
*Agent v1.0.0 | Descomplicar® | desk.descomplicar.pt/tasks/view/XXXX*
```

---

## Template: Plugin (plugin.json)

```json
{
  "name": "descomplicar-[domain]",
  "version": "1.0.0",
  "description": "Plugin [Domain] Descomplicar®. X skills, Y agents.",
  "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": {}
}
```

---

## Template: Command

```markdown
---
name: namespace:command-name
description: [Descrição breve do que faz]
argument-hint: "[descrição dos argumentos esperados]"
---

# [Título do Comando]

## Introdução

[Contexto e propósito deste comando]

## Argumentos

<user_input> #$ARGUMENTS </user_input>

**Se argumentos vazios:** "O que pretende [acção]?"

## Workflow

### 1. [Fase]

[Instruções]

### 2. [Fase]

[Instruções]

### 3. [Fase]

[Instruções]

## Output

[Descrição do que é produzido]

**Formato:**

```
[Exemplo de output]
```

## Opções Pós-Conclusão

Após completar, oferecer:

1. [Opção 1]
2. [Opção 2]
3. [Opção 3]
```

---

## Template: README.md (Plugin)

```markdown
# [Nome do Plugin]

> [Tagline curta]

## Instalação

```bash
claude /plugin install descomplicar-[domain]
```

## Componentes

### Skills (X)

| Skill | Descrição |
|-------|-----------|
| [skill-1] | [Faz X] |
| [skill-2] | [Faz Y] |

### Agents (Y)

| Agent | Descrição |
|-------|-----------|
| [agent-1] | [Especializado em X] |

### Commands (Z)

| Command | Descrição |
|---------|-----------|
| /[cmd-1] | [Executa X] |

## Uso

### Exemplo 1: [Caso de Uso]

```
[Exemplo de uso]
```

### Exemplo 2: [Caso de Uso]

```
[Exemplo de uso]
```

## Configuração

[Se aplicável]

## Licença

MIT

---

**Descomplicar®** | [Link para docs]
```

---

## Template: CHANGELOG.md

```markdown
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

- [Nova feature]

### Changed

- [Alteração]

### Fixed

- [Correcção]

## [1.0.0] - YYYY-MM-DD

### Added

- Release inicial
- X skills
- Y agents
- Z commands
```

---

## Template: CLAUDE.md (Plugin Dev)

```markdown
# Plugin Development Guidelines

## Versioning

**EVERY change requires updating 3 files:**

1. `.claude-plugin/plugin.json` - bump version
2. `CHANGELOG.md` - document change
3. `README.md` - verify counts

## Directory Structure

```
plugin-name/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── skill-name/
│       └── SKILL.md
├── agents/
│   └── agent-name.md
├── commands/
│   └── command-name.md
├── CLAUDE.md
├── CHANGELOG.md
├── README.md
└── LICENSE
```

## Naming Conventions

- Directories: kebab-case
- Files: kebab-case.md
- Skills: kebab-case
- Agents: kebab-case
- Commands: namespace:kebab-case

## Quality Checklist

Before committing:

- [ ] Version bumped
- [ ] CHANGELOG updated
- [ ] README counts correct
- [ ] All links work
- [ ] No temp files
```

---

## Template: Tarefa Desk CRM (HTML)

```html
<h3>Propósito</h3>
<p>[Descrição clara do componente]</p>

<h3>Funcionalidades</h3>
<ul>
  <li>[Funcionalidade 1]</li>
  <li>[Funcionalidade 2]</li>
  <li>[Funcionalidade 3]</li>
</ul>

<h3>Dependências</h3>
<p>[MCPs, outras skills, requisitos]</p>

<h3>Estado</h3>
<p>Activo | Em desenvolvimento | Inactivo</p>

<h3>Ficheiros</h3>
<table>
  <tr><th>Ficheiro</th><th>Função</th></tr>
  <tr><td><code>~/.claude/skills/nome/SKILL.md</code></td><td>Definição principal</td></tr>
</table>

<hr>
<p><strong>Versão:</strong> 1.0.0 | <strong>SDK:</strong> [nome-sdk]</p>
```

---

## Frases Standard

### Quando Não Sabe

```
Não tenho informação suficiente sobre [X]. Posso:
1. Pesquisar em [fonte]
2. Pedir-te mais contexto sobre [Y]

Qual preferes?
```

### Quando Falha

```
Não consegui completar [acção] porque [razão específica].

Alternativas:
1. [Workaround manual]
2. [Abordagem diferente]

Queres que tente [alternativa]?
```

### Quando Tem Baixa Confiança

```
Baseado em [fontes], a minha resposta é [X].

⚠️ Confiança: [0.6] - Recomendo verificar porque [razão].

Fontes consultadas:
- [fonte 1]
- [fonte 2]
```

### Quando Fora do Scope

```
Esta tarefa está fora da minha especialização.

Recomendo:
- /[skill-apropriada] para [razão]
- [agent-apropriado] para [razão]

Posso ajudar com [alternativa dentro do scope]?
```

---

**Descomplicar®** | 2026-02-04