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):

---
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):

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

## 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:

## 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
/**
 * [Nome do Ficheiro/Classe]
 *
 * @author Descomplicar® Crescimento Digital
 * @link https://descomplicar.pt
 * @copyright 2026 Descomplicar®
 */

JavaScript / TypeScript

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

Python

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

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

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:

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

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

# 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

description: Usar quando criar APIs RESTful com Laravel.

# 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

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

# 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.