claude-plugins/gestao/skills/validate-component/SKILL.md

name, description, layer

name	description	layer
validate-component	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.	wiki

/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 - Secção "Organização de Procedimentos" (padrão referenciação)
• /mcp-dev skill - 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

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