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

name, description

name	description
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.

/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ã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:

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