feat: refactor 30+ skills to Anthropic progressive disclosure pattern
- All SKILL.md files now <500 lines (avg reduction 69%) - Detailed content extracted to references/ subdirectories - Frontmatter standardised: only name + description (Anthropic standard) - New skills: brand-guidelines, spec-coauthor, report-templates, skill-creator - Design skills: anti-slop guidelines, premium-proposals reference - Removed non-standard frontmatter fields (triggers, version, author, category) Plugins affected: infraestrutura, marketing, dev-tools, crm-ops, gestao, core-tools, negocio, perfex-dev, wordpress, design-media Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,318 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user