Emanuel Almeida
6b3a6f2698
- 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>
366 lines
9.4 KiB
Markdown
366 lines
9.4 KiB
Markdown
---
|
|
name: validate-component
|
|
description: Valida skills e agents para alinhamento com procedimentos Hub. Verifica se componente referencia procedimentos (não duplica) e segue padrão de referenciação. Usar quando "validar skill", "verificar agent", "audit component", antes de deploy.
|
|
---
|
|
|
|
# /validate-component - Validador de Componentes
|
|
|
|
Audita skills e agents para garantir alinhamento com padrão de centralização de procedimentos Hub.
|
|
|
|
---
|
|
|
|
## Referências e Documentação
|
|
|
|
**SEMPRE consultar:**
|
|
- **[Hub CLAUDE.md](file:///media/ealmeida/Dados/Hub/CLAUDE.md)** - Secção "Organização de Procedimentos" (padrão referenciação)
|
|
- **[/mcp-dev skill](file:///home/ealmeida/.claude/plugins/marketplaces/descomplicar-plugins/infraestrutura/skills/mcp-dev/SKILL.md)** - Exemplo padrão ouro de referenciação
|
|
|
|
---
|
|
|
|
## O Que Valida
|
|
|
|
### 1. Procedimentos Embeddados (RED FLAG)
|
|
|
|
**Detecta conteúdo que deve estar em PROC-*:**
|
|
- ✗ Checklists extensas (>10 itens)
|
|
- ✗ Regras de validação detalhadas
|
|
- ✗ Troubleshooting guides completos
|
|
- ✗ Standards e convenções
|
|
- ✗ Best practices longas
|
|
- ✗ Workflows complexos passo-a-passo
|
|
|
|
### 2. Referenciação Correcta (GREEN FLAG)
|
|
|
|
**Verifica se componente referencia procedimentos:**
|
|
- ✓ Secção "Referências e Documentação"
|
|
- ✓ Links file:// para PROCs relevantes
|
|
- ✓ Descrição breve do que cada PROC cobre
|
|
- ✓ Instrução "SEMPRE consultar antes de..."
|
|
|
|
### 3. Separação Clara
|
|
|
|
**O que DEVE ficar no componente:**
|
|
- ✓ Comandos e templates
|
|
- ✓ Instruções operacionais curtas
|
|
- ✓ Decisão "quando usar"
|
|
- ✓ Exemplos práticos inline
|
|
|
|
**O que DEVE ir para PROC:**
|
|
- ✗ Regras e standards
|
|
- ✗ Checklists de validação
|
|
- ✗ Troubleshooting detalhado
|
|
- ✗ Melhores práticas extensas
|
|
|
|
---
|
|
|
|
## Protocolo de Validação
|
|
|
|
### Para Skills
|
|
|
|
```
|
|
1. LER skill SKILL.md completo
|
|
|
|
2. VERIFICAR secção "Referências e Documentação":
|
|
- Existe? (GREEN se sim, sugerir criar se não)
|
|
- Tem links file:// para PROCs? (GREEN se sim)
|
|
- Links são relevantes para o domínio da skill?
|
|
|
|
3. DETECTAR procedimentos embeddados:
|
|
- Procurar padrões: "Checklist", "Steps", "Validação", "Troubleshooting"
|
|
- Se >100 linhas de instruções → SUGERIR extrair para PROC
|
|
|
|
4. AVALIAR qualidade referenciação:
|
|
- Links funcionam? (teste paths)
|
|
- Descrição do PROC é clara?
|
|
- Indica quando consultar?
|
|
|
|
5. GERAR relatório (ver formato abaixo)
|
|
```
|
|
|
|
### Para Agents
|
|
|
|
```
|
|
1. LER agent .md completo (frontmatter + system prompt)
|
|
|
|
2. VERIFICAR system prompt tem secção "Referências":
|
|
- Existe? (GREEN se sim)
|
|
- Tem links file:// para PROCs relevantes?
|
|
|
|
3. DETECTAR procedimentos embeddados no system prompt:
|
|
- Padrões similares a skills
|
|
- Workflows >50 linhas no prompt
|
|
|
|
4. AVALIAR se agent conhece procedimentos do seu domínio:
|
|
- wordpress-plugin-developer → deve referenciar PROC-WordPress-*
|
|
- mcp-protocol-developer → deve referenciar PROC-MCP-*
|
|
|
|
5. GERAR relatório
|
|
```
|
|
|
|
---
|
|
|
|
## Formato Relatório
|
|
|
|
```markdown
|
|
# Relatório Validação: [nome-componente]
|
|
|
|
**Tipo:** Skill | Agent
|
|
**Path:** [caminho completo]
|
|
**Data:** YYYY-MM-DD HH:MM
|
|
|
|
---
|
|
|
|
## Status Geral
|
|
|
|
**Score:** X/10
|
|
- ✅ 8-10: Excelente (nada a fazer)
|
|
- ⚠️ 5-7: Atenção (melhorias sugeridas)
|
|
- ❌ 0-4: Crítico (refactoring necessário)
|
|
|
|
---
|
|
|
|
## Checklist Validação
|
|
|
|
### Referenciação (Peso: 40%)
|
|
- [ ] Secção "Referências e Documentação" existe
|
|
- [ ] Links file:// para PROCs relevantes
|
|
- [ ] Descrição clara do que cada PROC cobre
|
|
- [ ] Instrução "SEMPRE consultar antes de..."
|
|
|
|
### Separação Conteúdo (Peso: 40%)
|
|
- [ ] Sem checklists longas (>10 itens) embeddadas
|
|
- [ ] Sem troubleshooting extenso embeddado
|
|
- [ ] Sem standards/conventions detalhadas embeddadas
|
|
- [ ] Sem workflows complexos embeddados
|
|
|
|
### Qualidade (Peso: 20%)
|
|
- [ ] Links file:// funcionam (paths válidos)
|
|
- [ ] Referencia PROCs do departamento correcto
|
|
- [ ] Instruções operacionais concisas (<50 linhas)
|
|
|
|
---
|
|
|
|
## Issues Detectadas
|
|
|
|
### 🔴 Críticas (Bloqueia Deploy)
|
|
|
|
1. **[Tipo Issue]**
|
|
- **Localização:** Linha X-Y
|
|
- **Problema:** Descrição
|
|
- **Impacto:** Duplicação procedimento / Info embeddada
|
|
- **Acção:** Extrair para PROC-[Nome].md em [Departamento]/
|
|
|
|
### ⚠️ Avisos (Recomendado Corrigir)
|
|
|
|
1. **[Tipo Issue]**
|
|
- **Localização:** Secção X
|
|
- **Problema:** Descrição
|
|
- **Sugestão:** Adicionar referência a PROC-[Nome].md
|
|
|
|
### ✅ Boas Práticas Observadas
|
|
|
|
1. Secção "Referências" bem estruturada
|
|
2. Links file:// correctos
|
|
3. Separação clara comando vs regra
|
|
|
|
---
|
|
|
|
## Recomendações
|
|
|
|
### Imediatas (P1)
|
|
1. Extrair checklist linhas X-Y para PROC-[Nome].md
|
|
2. Adicionar link file:// para PROC-[Outro].md
|
|
|
|
### Melhorias (P2)
|
|
1. Expandir descrição PROC na referência
|
|
2. Adicionar exemplo uso combinado skill + PROC
|
|
|
|
### Opcional (P3)
|
|
1. Considerar criar PROC-[NovoTema].md para conteúdo Y
|
|
|
|
---
|
|
|
|
## Procedimentos Relevantes Existentes
|
|
|
|
| PROC | Departamento | Relevância | Status Link |
|
|
|------|--------------|------------|-------------|
|
|
| PROC-MCP-Desenvolvimento.md | D7 | Alta | ✅ Referenciado |
|
|
| PROC-WordPress-Hardening.md | D7 | Média | ❌ Não referenciado |
|
|
|
|
---
|
|
|
|
## Próximos Passos
|
|
|
|
1. [ ] Corrigir issues críticas (se houver)
|
|
2. [ ] Aplicar recomendações P1
|
|
3. [ ] Re-validar com /validate-component
|
|
4. [ ] Deploy quando score ≥7/10
|
|
```
|
|
|
|
---
|
|
|
|
## Exemplos de Uso
|
|
|
|
### Exemplo 1: Skill com Boa Referenciação
|
|
|
|
```
|
|
User: /validate-component /mcp-dev
|
|
Assistant:
|
|
|
|
# Relatório Validação: mcp-dev
|
|
|
|
**Score:** 9/10 ✅
|
|
|
|
## Status Geral
|
|
Excelente! Padrão ouro de referenciação.
|
|
|
|
## Issues Detectadas
|
|
Nenhuma crítica. Pequena sugestão: expandir descrição PROC-MCP-Session-Recovery.md.
|
|
|
|
## Boas Práticas
|
|
- Secção "Referências e Documentação" completa
|
|
- 5 links file:// para PROCs relevantes
|
|
- Instruções "SEMPRE consultar antes de..."
|
|
- Separação clara: comandos na skill, regras nos PROCs
|
|
```
|
|
|
|
### Exemplo 2: Agent com Procedimentos Embeddados
|
|
|
|
```
|
|
User: /validate-component wordpress-plugin-developer
|
|
Assistant:
|
|
|
|
# Relatório Validação: wordpress-plugin-developer
|
|
|
|
**Score:** 4/10 ❌
|
|
|
|
## Issues Críticas
|
|
|
|
1. **Checklist WordPress Security (60 linhas embeddadas)**
|
|
- Localização: Linhas 234-294
|
|
- Problema: Checklist completa hardening no system prompt
|
|
- Acção: Extrair para PROC-WordPress-Hardening.md (D7-Tecnologia)
|
|
|
|
2. **Sem Secção Referências**
|
|
- System prompt não referencia nenhum PROC
|
|
- Deve adicionar links para PROC-WordPress-* relevantes
|
|
|
|
## Recomendações P1
|
|
|
|
1. Criar PROC-WordPress-Hardening.md com checklist
|
|
2. Criar PROC-WordPress-CLI.md com comandos WP-CLI
|
|
3. Adicionar secção "Referências" no system prompt
|
|
4. Re-validar após refactoring
|
|
```
|
|
|
|
### Exemplo 3: Skill Nova Antes de Deploy
|
|
|
|
```
|
|
User: Criei /easypanel-deploy skill. Validar antes de commit?
|
|
Assistant: /validate-component easypanel-deploy
|
|
|
|
# Relatório Validação: easypanel-deploy
|
|
|
|
**Score:** 6/10 ⚠️
|
|
|
|
## Avisos
|
|
|
|
1. **Workflow Deploy (40 linhas)**
|
|
- Localização: Secção "Deployment Workflow"
|
|
- Problema: Workflow passo-a-passo detalhado
|
|
- Sugestão: Considerar PROC-Deployment-EasyPanel.md (D7/INF)
|
|
- Alternativa: Manter se workflow é core da skill
|
|
|
|
2. **API Reference Embeddada**
|
|
- 80 linhas de endpoints EasyPanel
|
|
- Sugestão: Mover para references/easypanel-api.md
|
|
|
|
## Recomendações
|
|
|
|
Score 6/10 é aceitável para deploy. Opcionalmente:
|
|
- Extrair API reference para ficheiro separado (progressive disclosure)
|
|
- Se workflow deploy for usado por outros componentes → PROC
|
|
```
|
|
|
|
---
|
|
|
|
## Integração CI/CD
|
|
|
|
Para validação automática antes de commit:
|
|
|
|
```bash
|
|
# .git/hooks/pre-commit
|
|
if [[ $(git diff --cached --name-only) =~ (skills|agents) ]]; then
|
|
echo "Validating modified components..."
|
|
claude-code /validate-component [path]
|
|
fi
|
|
```
|
|
|
|
---
|
|
|
|
## Critérios de Score
|
|
|
|
### Score 9-10 (Excelente)
|
|
- Secção "Referências" completa e bem estruturada
|
|
- Todos os PROCs relevantes referenciados
|
|
- Zero procedimentos embeddados
|
|
- Separação clara comando vs regra
|
|
|
|
### Score 7-8 (Bom)
|
|
- Secção "Referências" existe
|
|
- Maioria dos PROCs referenciados
|
|
- Pequenos procedimentos embeddados (<20 linhas)
|
|
- Maioria do conteúdo bem separado
|
|
|
|
### Score 5-6 (Aceitável)
|
|
- Algumas referências, mas incompletas
|
|
- Procedimentos embeddados médios (20-50 linhas)
|
|
- Separação parcial
|
|
- Deploy OK mas melhorias recomendadas
|
|
|
|
### Score 3-4 (Crítico)
|
|
- Sem secção "Referências" ou vazia
|
|
- Procedimentos longos embeddados (>50 linhas)
|
|
- Má separação comando vs regra
|
|
- Refactoring necessário antes deploy
|
|
|
|
### Score 0-2 (Bloqueado)
|
|
- Zero referências a PROCs
|
|
- Procedimentos extensos embeddados (>100 linhas)
|
|
- Duplicação crítica de conteúdo
|
|
- Deploy BLOQUEADO até corrigir
|
|
|
|
---
|
|
|
|
## Anti-Patterns
|
|
|
|
**NUNCA:**
|
|
- ❌ Aprovar deploy com score <5/10
|
|
- ❌ Ignorar issues críticas
|
|
- ❌ Validar sem ler componente completo
|
|
- ❌ Sugerir extrair conteúdo que é core da skill
|
|
|
|
**SEMPRE:**
|
|
- ✅ Testar links file:// funcionam
|
|
- ✅ Verificar departamento correcto dos PROCs
|
|
- ✅ Distinguir "core skill" vs "procedimento duplicado"
|
|
- ✅ Dar exemplos concretos de refactoring
|
|
|
|
---
|
|
|
|
## Referência: /mcp-dev (Padrão Ouro)
|
|
|
|
Ver secção "Referências e Documentação" em:
|
|
`/home/ealmeida/.claude/plugins/.../mcp-dev/SKILL.md`
|
|
|
|
**O que faz bem:**
|
|
- Secção dedicada no topo
|
|
- 5 links file:// para PROCs D7-Tecnologia
|
|
- Descrição breve de cada PROC
|
|
- Instrução clara "SEMPRE consultar antes de criar/modificar MCPs"
|
|
- Quick Reference sintética (não duplica PROC)
|
|
|
|
---
|
|
|
|
*Skill v1.0.0 | 2026-02-13 | Plugin gestao | Descomplicar®*
|