claude-plugins/dev-tools/skills/skill-creator/references/descomplicar-standards.md

# Standards Descomplicar para Skills

Standards adicionais aplicados sobre os padrões Anthropic base.

## Sumário

1. Frontmatter Descomplicar
2. Língua e Estilo PT-PT
3. Integração com MCPs
4. Assinatura de Código
5. Localização no Sistema de Plugins
6. Campos Opcionais do Frontmatter
7. Exemplos de Skills Bem e Mal Estruturadas

---

## 1. Frontmatter Descomplicar

O padrão mínimo segue o Anthropic (apenas `name` + `description`):

```yaml
---
name: nome-da-skill
description: >
  Descrição completa do que a skill faz. Incluir domínio, tecnologias chave
  e triggers explícitos. Usar quando: (1) caso de uso A, (2) caso de uso B,
  (3) caso de uso C.
---
```

**Campo opcional `allowed-tools`** (quando a skill usa ferramentas específicas):

```yaml
---
name: nome-da-skill
description: >
  Descrição da skill. Usar quando [contexto].
allowed-tools: Read, Write, Edit, Bash, mcp__memory-supabase__search_memories
---
```

Incluir `allowed-tools` apenas quando a skill tem dependências de ferramentas não óbvias ou quando restringir o acesso é importante para segurança.

---

## 2. Língua e Estilo PT-PT

**Regra absoluta:** Português europeu estrito em tudo — código, comentários, documentação, output.

### Acentuação obrigatória

| Errado (BR) | Correcto (PT) |
|-------------|---------------|
| descrição | descrição |
| criacao | criação |
| informacao | informação |
| configuracao | configuração |
| autenticacao | autenticação |

### Vocabulário técnico

| Errado | Correcto |
|--------|----------|
| você | tu / o utilizador |
| usuário | utilizador |
| senha | palavra-passe |
| agendar | calendarizar |
| deletar | eliminar |
| implementar (como "deploy") | publicar / implementar |

### Monetário

```
95EUR — correcto
95,00EUR — evitar casas decimais desnecessárias
R$95 — nunca
```

### Estilo

- Usar **negrito** para ênfase (não MAIÚSCULAS)
- Excepção: siglas (API, MCP, CRM, JWT)
- Sem emojis nos ficheiros de skill
- Datas em DD-MM-YYYY nos ficheiros e notas

---

## 3. Integração com MCPs

Skills que necessitam de contexto especializado devem referenciar MCPs relevantes:

### Padrão de consulta NotebookLM

```markdown
## Contexto NotebookLM

Consultar notebooks relevantes antes de executar:

| Notebook | ID | Consultar quando |
|----------|-----|-----------------|
| Nome | id-do-notebook | situação específica |
```

### Notebooks principais por domínio

| Domínio | Notebook ID |
|---------|-------------|
| Programação geral | `24947ffa-0019-448a-a340-2f4a275d2eb1` |
| Arquitectura / Delivery | `24947ffa-0019-448a-a340-2f4a275d2eb1` |
| Roadmap / Prioridades | `79d43410-0e29-4be1-881d-84db6bdc239a` |
| Gestão de Projectos / Agile | `0c9c079c-a426-486c-99eb-1564d42d37ad` |
| Claude Code / IA | `2876d1fe-5cea-4d98-8140-b0e1a81c6bc4` |
| MCPs / Desenvolvimento | `73102308-70ef-403e-9be9-eae0cfc62d55` |

### Padrão de memória

Para skills que aprendem com execuções anteriores:

```markdown
## Memória

Pesquisar experiência anterior antes de começar:
`mcp__memory-supabase__search_memories "[keywords relevantes]"`

Guardar aprendizagens ao concluir:
`mcp__memory-supabase__save_memory { content: "...", tags: ["domínio", "skill"] }`
```

---

## 4. Assinatura de Código

Código produzido por skills deve incluir a assinatura Descomplicar:

### PHP

```php
<?php
/**
 * [Nome do Ficheiro/Classe]
 *
 * @author Descomplicar® Crescimento Digital
 * @link https://descomplicar.pt
 * @copyright 2026 Descomplicar®
 */
```

### JavaScript / TypeScript

```javascript
/**
 * @author Descomplicar® | @link descomplicar.pt | @copyright 2026
 */
```

### Python

```python
# -*- coding: utf-8 -*-
"""
Nome do módulo.

@author: Descomplicar® Crescimento Digital
@link: https://descomplicar.pt
@copyright: 2026 Descomplicar®
"""
```

### CSS

```css
/**
 * Nome do ficheiro
 * @author Descomplicar® | descomplicar.pt | © 2026
 */
```

---

## 5. Localização no Sistema de Plugins

Skills do ecossistema Descomplicar residem em:

```
~/.claude/plugins/cache/descomplicar-plugins/<plugin-name>/<versão>/skills/<skill-name>/
```

**Plugins disponíveis e as suas skills:**

| Plugin | Path | Skills típicas |
|--------|------|----------------|
| dev-tools | `dev-tools/1.0.0/skills/` | php-dev, db-design, react-patterns, nextjs, security-check |
| gestao | `gestao/*/skills/` | worklog, desk, today |
| crm-ops | `crm-ops/*/skills/` | orcamento, lead-approach |
| core-tools | `core-tools/*/skills/` | _core, reflect |

**Skill nova para plugin existente:**
1. Identificar o plugin mais adequado pelo domínio
2. Criar pasta em `skills/<nome-da-skill>/`
3. Verificar se o `plugin.json` precisa de ser actualizado

**Skill nova para novo plugin:**
Coordenar com o processo de criação de plugin (fora do âmbito desta skill).

---

## 6. Campos Opcionais do Frontmatter

O Anthropic define apenas `name` e `description` como obrigatórios. O sistema Descomplicar aceita `allowed-tools` como campo adicional documentado:

```yaml
---
name: nome-da-skill
description: >
  Descrição completa com triggers.
allowed-tools: Read, Write, Edit, Bash, mcp__memory-supabase__search_memories, mcp__notebooklm__notebook_query
---
```

**Não adicionar** outros campos não documentados — quebra a compatibilidade com o packaging script.

---

## 7. Exemplos de Skills Bem e Mal Estruturadas

### Má: Description vaga sem triggers

```yaml
---
name: php-helper
description: Ajuda com PHP.
---
```

**Problema:** O agente não sabe quando activar esta skill.

### Má: Corpo do SKILL.md com "Quando Usar"

```markdown
# PHP Helper

## Quando Usar Esta Skill

- Quando precisar de criar APIs
- Quando precisar de autenticação
```

**Problema:** A secção "Quando Usar" no corpo nunca é lida pelo sistema de triggering (que usa apenas a `description`). Esta informação pertence à `description`.

### Má: Conteúdo duplicado

```yaml
description: Usar quando criar APIs RESTful com Laravel.
```

```markdown
# PHP Dev

## Quando usar

- Criar APIs RESTful com Laravel  ← duplicado da description
```

### Má: Ficheiros auxiliares desnecessários

```
php-dev/
├── SKILL.md
├── README.md       ← não deve existir
├── CHANGELOG.md    ← não deve existir
└── references/
```

### Boa: Description completa com triggers explícitos

```yaml
---
name: php-dev
description: >
  Desenvolvimento PHP moderno com Laravel, Symfony e APIs RESTful — autenticação
  (JWT, OAuth, Sanctum), service classes e refactorização de código legacy
  seguindo padrões PSR. Usar quando: (1) criar APIs RESTful, (2) implementar
  autenticação, (3) desenvolver service classes, (4) refactorizar código PHP,
  (5) integrar com APIs externas.
---
```

### Boa: Progressive disclosure correcta

```markdown
# PHP Dev

## Protocolo obrigatório

1. Pesquisar memória: `mcp__memory-supabase__search_memories "[keywords]"`
2. Consultar NotebookLM: ver tabela em references/notebooklm-context.md
3. Implementar com padrões Laravel: ver references/laravel-patterns.md

## Checklist de entrega

- [ ] Assinatura Descomplicar® em todos os ficheiros
- [ ] Type hints completos
- [ ] PSR-12 compliant
```

O corpo do SKILL.md é conciso e delega detalhes para references.

### Boa: Estrutura de directório mínima e limpa

```
php-dev/
├── SKILL.md
└── references/
    ├── laravel-patterns.md
    └── security-checklist.md
```

Apenas o necessário, sem ficheiros auxiliares.