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:
454
docs/01-GUIA-SKILLS.md
Executable file
454
docs/01-GUIA-SKILLS.md
Executable file
@@ -0,0 +1,454 @@
|
||||
# Guia Definitivo: Skills Claude Code
|
||||
|
||||
**Versão:** 2.0 | **Data:** 2026-02-04 | **Autor:** Descomplicar®
|
||||
|
||||
---
|
||||
|
||||
## 1. Conceitos Fundamentais
|
||||
|
||||
### O que são Skills?
|
||||
|
||||
Skills são **meta-tools que injectam instruções especializadas** no contexto do Claude. Transformam o Claude generalista em especialista equipado com conhecimento procedimental.
|
||||
|
||||
### Arquitectura de Carregamento
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Nível 1: METADATA (~100 tokens) │
|
||||
│ → name + description carregados SEMPRE │
|
||||
│ → Claude usa para decidir quando activar │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Nível 2: BODY (<5k tokens) │
|
||||
│ → SKILL.md completo carregado quando activado │
|
||||
│ → Instruções injectadas no contexto │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Nível 3: RESOURCES (on-demand) │
|
||||
│ → Ficheiros em references/ carregados via Read tool │
|
||||
│ → Scripts executados quando necessário │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Mecanismo de Selecção
|
||||
|
||||
**Não há routing algorítmico** - Claude usa raciocínio semântico:
|
||||
1. Lê descrições de todas as skills disponíveis
|
||||
2. Compara com o intent do utilizador
|
||||
3. Selecciona baseado em compreensão de linguagem natural
|
||||
|
||||
**Implicação Crítica:** A `description` determina se a skill é activada.
|
||||
|
||||
---
|
||||
|
||||
## 2. Estrutura de Ficheiros
|
||||
|
||||
### Estrutura Mínima
|
||||
|
||||
```
|
||||
skill-name/
|
||||
└── SKILL.md # OBRIGATÓRIO
|
||||
```
|
||||
|
||||
### Estrutura Completa
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md # OBRIGATÓRIO (<500 linhas)
|
||||
├── scripts/ # Código executável
|
||||
│ └── helper.py
|
||||
├── references/ # Documentação detalhada
|
||||
│ ├── api-docs.md
|
||||
│ └── examples.md
|
||||
└── assets/ # Ficheiros de output
|
||||
└── template.html
|
||||
```
|
||||
|
||||
### Regras de Profundidade
|
||||
|
||||
```
|
||||
✅ SKILL.md → references/api.md (1 nível)
|
||||
❌ SKILL.md → docs/api.md → docs/endpoints.md (2 níveis)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. SKILL.md - Estrutura
|
||||
|
||||
### Formato Obrigatório
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: nome-da-skill
|
||||
description: >
|
||||
[Capacidade principal]. [Capacidades secundárias].
|
||||
Use when [trigger1], [trigger2], or when user mentions
|
||||
"[keyword1]", "[keyword2]", "[keyword3]".
|
||||
---
|
||||
|
||||
# Título da Skill
|
||||
|
||||
[Instruções que Claude segue quando skill activa]
|
||||
```
|
||||
|
||||
### Frontmatter - Campos
|
||||
|
||||
| Campo | Obrigatório | Descrição |
|
||||
|-------|-------------|-----------|
|
||||
| `name` | Sim | Identificador único, kebab-case, <64 chars |
|
||||
| `description` | **Sim** | O que faz + quando usar, <1024 chars |
|
||||
| `argument-hint` | Não | Hint para argumentos: `[issue-number]` |
|
||||
| `disable-model-invocation` | Não | `true` = só invocação manual via `/skill` |
|
||||
| `user-invocable` | Não | `false` = esconde do menu `/` |
|
||||
| `allowed-tools` | Não | Tools permitidos sem confirmação |
|
||||
| `model` | Não | Modelo específico para esta skill |
|
||||
| `context` | Não | `fork` para executar em subagent |
|
||||
|
||||
### Campos Custom Descomplicar
|
||||
|
||||
| Campo | Uso |
|
||||
|-------|-----|
|
||||
| `author` | `Descomplicar®` |
|
||||
| `version` | Versão semântica (1.0.0) |
|
||||
| `desk_task` | ID da tarefa no Desk CRM |
|
||||
| `sdk` | SDK a que pertence |
|
||||
|
||||
### Controlo de Invocação
|
||||
|
||||
| Configuração | Utilizador Invoca | Claude Invoca |
|
||||
|--------------|-------------------|---------------|
|
||||
| (default) | ✅ | ✅ |
|
||||
| `disable-model-invocation: true` | ✅ | ❌ |
|
||||
| `user-invocable: false` | ❌ | ✅ |
|
||||
|
||||
---
|
||||
|
||||
## 4. Descrições Eficazes
|
||||
|
||||
### Taxa de Sucesso por Optimização
|
||||
|
||||
| Abordagem | Taxa Activação |
|
||||
|-----------|----------------|
|
||||
| Sem optimização | ~20% |
|
||||
| Descrição optimizada | 50% |
|
||||
| + Keywords específicas | 72% |
|
||||
| + Hooks de avaliação | 84-90% |
|
||||
|
||||
### Fórmula de Descrição
|
||||
|
||||
```
|
||||
[Capacidade principal]. [Capacidades secundárias].
|
||||
Use when [trigger 1], [trigger 2], or when user mentions
|
||||
"[keyword1]", "[keyword2]", "[keyword3]".
|
||||
```
|
||||
|
||||
### Exemplos
|
||||
|
||||
**❌ Mau:**
|
||||
```yaml
|
||||
description: Ajuda com WordPress
|
||||
```
|
||||
|
||||
**✅ Bom:**
|
||||
```yaml
|
||||
description: >
|
||||
Desenvolvimento WordPress especializado - plugins, temas, WooCommerce.
|
||||
Use when user asks to "criar plugin", "desenvolver tema", "woocommerce",
|
||||
"wordpress", "wp", "gutenberg", "elementor", "child theme".
|
||||
```
|
||||
|
||||
### Regras de Descrição
|
||||
|
||||
1. **Duas partes obrigatórias:** Capacidade + Triggers
|
||||
2. **5+ keywords específicas** do workflow real
|
||||
3. **Mencionar tipos de ficheiros** relevantes (.php, functions.php)
|
||||
4. **Terceira pessoa** (This skill... não Use this...)
|
||||
5. **Evitar linguagem vaga** (helps with, works with)
|
||||
6. **Declarar limites** - o que NÃO faz
|
||||
|
||||
---
|
||||
|
||||
## 5. Conteúdo do SKILL.md
|
||||
|
||||
### Dois Tipos de Skills
|
||||
|
||||
**Reference Skills (Conhecimento):**
|
||||
```yaml
|
||||
---
|
||||
name: api-conventions
|
||||
description: API design patterns for this codebase
|
||||
---
|
||||
|
||||
When writing API endpoints:
|
||||
- Use RESTful naming conventions
|
||||
- Return consistent error formats
|
||||
```
|
||||
|
||||
**Task Skills (Acções):**
|
||||
```yaml
|
||||
---
|
||||
name: deploy
|
||||
description: Deploy the application to production
|
||||
---
|
||||
|
||||
Deploy the application:
|
||||
1. Run test suite
|
||||
2. Build application
|
||||
3. Push to deployment target
|
||||
```
|
||||
|
||||
### Limites de Tamanho
|
||||
|
||||
| Componente | Limite |
|
||||
|------------|--------|
|
||||
| SKILL.md total | < 500 linhas |
|
||||
| description | < 1024 caracteres |
|
||||
| name | < 64 caracteres |
|
||||
| Conteúdo principal | < 5000 tokens |
|
||||
|
||||
### Progressive Disclosure
|
||||
|
||||
```markdown
|
||||
# SKILL.md
|
||||
|
||||
## Instruções Principais
|
||||
[Conteúdo essencial - carregado sempre]
|
||||
|
||||
## Recursos Adicionais
|
||||
- Para API completa: [docs/reference.md](references/reference.md)
|
||||
- Para exemplos: [docs/examples.md](references/examples.md)
|
||||
|
||||
[Claude carrega via Read tool apenas quando necessário]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Scripts, References e Assets
|
||||
|
||||
### Scripts (`scripts/`)
|
||||
|
||||
**Quando incluir:**
|
||||
- Código reescrito repetidamente
|
||||
- Tarefas que precisam de reliability determinística
|
||||
- Operações complexas que beneficiam de código testado
|
||||
|
||||
**Exemplo:**
|
||||
```python
|
||||
# scripts/validate.py
|
||||
import sys
|
||||
import json
|
||||
|
||||
def validate_config(path):
|
||||
with open(path) as f:
|
||||
config = json.load(f)
|
||||
# validation logic
|
||||
return True
|
||||
```
|
||||
|
||||
### References (`references/`)
|
||||
|
||||
**Quando incluir:**
|
||||
- Documentação de APIs
|
||||
- Schemas de base de dados
|
||||
- Políticas e guidelines
|
||||
- Conhecimento de domínio específico
|
||||
|
||||
**Best Practice:** Se > 10k palavras, incluir grep patterns no SKILL.md.
|
||||
|
||||
### Assets (`assets/`)
|
||||
|
||||
**Quando incluir:**
|
||||
- Templates (HTML, PPTX, etc.)
|
||||
- Logos e imagens
|
||||
- Boilerplate code
|
||||
|
||||
**Diferença de References:** Assets são usados no OUTPUT, não carregados em contexto.
|
||||
|
||||
---
|
||||
|
||||
## 7. Anti-Patterns
|
||||
|
||||
| Anti-Pattern | Problema | Solução |
|
||||
|--------------|----------|---------|
|
||||
| Context Bloat | 5000 linhas inline | Usar references/ |
|
||||
| Paths Absolutos | Quebra em outros sistemas | Paths relativos |
|
||||
| Descrição Vaga | Não activa | Keywords específicas |
|
||||
| Over-Specification Tools | Risco segurança | Apenas necessários |
|
||||
| Info Time-Sensitive | Desactualiza | Linguagem atemporal |
|
||||
| Múltiplas Opções Sem Preferência | Ambiguidade | Preferência clara |
|
||||
|
||||
---
|
||||
|
||||
## 8. Métricas de Qualidade
|
||||
|
||||
### Score (0-100)
|
||||
|
||||
| Critério | Peso |
|
||||
|----------|------|
|
||||
| Descrição optimizada | 25 |
|
||||
| Estrutura correcta | 20 |
|
||||
| Tamanho adequado (<500 linhas) | 15 |
|
||||
| Exemplos práticos | 15 |
|
||||
| Limites definidos | 10 |
|
||||
| Tools mínimos | 10 |
|
||||
| Testada 3+ cenários | 5 |
|
||||
|
||||
### Níveis
|
||||
|
||||
| Nível | Score | Requisitos |
|
||||
|-------|-------|------------|
|
||||
| **Production** | 90+ | Todos os critérios |
|
||||
| **Beta** | 70-89 | Descrição + estrutura + exemplos |
|
||||
| **Draft** | <70 | Em desenvolvimento |
|
||||
|
||||
---
|
||||
|
||||
## 9. Integração Descomplicar
|
||||
|
||||
### Registo no Component Registry
|
||||
|
||||
```sql
|
||||
INSERT INTO cr_skills (name, slug, description, path, sdk_id, status)
|
||||
VALUES ('Nome Skill', 'skill-slug', 'Descrição...', '~/.claude/skills/skill-slug', 1, 'active');
|
||||
```
|
||||
|
||||
### Relações
|
||||
|
||||
```sql
|
||||
-- Skill → SDK
|
||||
INSERT INTO cr_sdk_skills (sdk_id, skill_id) VALUES (1, 100);
|
||||
|
||||
-- Skill → Agent (se usado por agent)
|
||||
INSERT INTO cr_agent_skills (agent_id, skill_id) VALUES (1, 100);
|
||||
```
|
||||
|
||||
### Tarefa Desk CRM
|
||||
|
||||
Toda skill deve ter tarefa associada no projecto #65 com:
|
||||
- Milestone: 294 (Skills Claude Code)
|
||||
- Tags: skill (79), stackworkflow (75), claude-code (81)
|
||||
- Responsáveis: Emanuel (1) + AikTop (25)
|
||||
|
||||
---
|
||||
|
||||
## 10. Checklist de Validação
|
||||
|
||||
```
|
||||
□ FRONTMATTER
|
||||
□ name: kebab-case, <64 chars
|
||||
□ description: <1024 chars, "Use when..." com 5+ keywords
|
||||
□ version: semver
|
||||
□ desk_task: ID válido
|
||||
|
||||
□ ESTRUTURA
|
||||
□ SKILL.md <500 linhas
|
||||
□ Título corresponde ao name
|
||||
□ Secções: Quando Usar, Protocolo, Exemplos
|
||||
□ references/ linkados como markdown [](./references/file.md)
|
||||
|
||||
□ CONTEÚDO
|
||||
□ Limites definidos (quando NÃO usar)
|
||||
□ Exemplos input/output concretos
|
||||
□ Sem paths absolutos
|
||||
□ Sem informação time-sensitive
|
||||
|
||||
□ QUALIDADE
|
||||
□ Testada com 3+ cenários reais
|
||||
□ Score >= 70
|
||||
□ allowed-tools mínimos
|
||||
|
||||
□ INTEGRAÇÃO
|
||||
□ Registada em cr_skills
|
||||
□ SDK associado
|
||||
□ Tarefa Desk criada/actualizada
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. Template Padrão Descomplicar
|
||||
|
||||
```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*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Referências:**
|
||||
- [Documentação Oficial Skills](https://code.claude.com/docs/en/skills)
|
||||
- [anthropics/skills](https://github.com/anthropics/skills)
|
||||
- [VoltAgent/awesome-agent-skills](https://github.com/VoltAgent/awesome-agent-skills)
|
||||
Reference in New Issue
Block a user