Claude Code Stack Analysis

⚠️ META-CONFIGURAÇÃO Esta skill analisa a ESTRUTURA de primitivos do Claude Code (skills, commands, hooks), não código de projeto.

---

🎯 Objetivo

Analisar a qualidade e estrutura das configurações do Claude Code em um projeto, identificando:

• Problemas de nomenclatura e convenções
• Conflitos de escopo (meta vs domínio)
• Gaps na configuração
• Oportunidades de otimização
• Conformidade com best practices

---

📊 Dimensões de Análise

1. Inventário Estrutural

O que fazer:

• Listar todos os primitivos (skills, commands, hooks)
• Mapear estrutura de diretórios
• Identificar arquivos órfãos ou malformados
• Verificar existência de CLAUDE.md

Comandos:

# Estrutura completa
find .claude -type f -name "*.md" -o -name "*.sh" -o -name "*.py"

# Skills
find .claude/skills -type f -name "SKILL.md"

# Commands
find .claude/commands -type f -name "*.md"

# Hooks
find .claude/hooks -type f -name "*.sh" -o -name "*.py"

# Configurações
cat .claude/settings.json 2>/dev/null || echo "settings.json não encontrado"

2. Análise de Nomenclatura

O que validar:

• Prefixo consistente (cc- para meta, [projeto]- para domínio)
• Nomes descritivos e sem ambiguidade
• Ausência de conflitos com primitivos padrão
• Seguimento de convenção kebab-case

Padrões esperados:

# Meta-repo
Skills:    cc-[funcionalidade]    # Exemplo: cc-hooks-setup
Commands:  cc-[ação].md           # Exemplo: cc-diagnose.md
Hooks:     cc-[evento]-[ação].sh  # Exemplo: cc-session-start.sh

# Projeto de domínio
Skills:    [prefix]-[funcionalidade]    # Exemplo: app-auth-agent
Commands:  [prefix]-[ação].md           # Exemplo: app-deploy.md
Hooks:     [prefix]-[evento]-[ação].sh  # Exemplo: app-pretool-validate.sh

Problemas comuns:

• ❌ hooks-setup → ✅ cc-hooks-setup (falta prefixo)
• ❌ app_auth_agent → ✅ app-auth-agent (underscore em vez de hífen)
• ❌ cc-agent → ✅ cc-agent-config (muito genérico)

3. Validação de Frontmatter (Skills)

Campos obrigatórios:

---
name: [nome-da-skill]              # OBRIGATÓRIO: deve coincidir com nome do diretório
scope: [meta-configuration|domain-implementation]  # OBRIGATÓRIO
target: [claude-code-itself|application-feature|...]  # OBRIGATÓRIO
description: [mínimo 150 caracteres]  # OBRIGATÓRIO
keywords: [pelo menos 5 keywords relevantes]  # OBRIGATÓRIO
allowed-tools: [lista de tools]    # OPCIONAL mas recomendado
---

Validações específicas:

Para meta-skills (scope: meta-configuration):

• ✅ name deve começar com cc-
• ✅ scope deve ser meta-configuration
• ✅ target deve ser claude-code-itself
• ✅ keywords deve incluir claude-code e cc-*
• ✅ description deve mencionar "Claude Code" ou "tool configuration"

Para skills de domínio (scope: domain-implementation):

• ✅ name deve começar com prefixo do projeto (não cc-)
• ✅ scope deve ser domain-implementation
• ✅ target deve ser relacionado ao domínio (application-feature, business-logic, etc.)
• ✅ keywords NÃO devem incluir claude-code ou meta (evitar conflito)

Como validar:

# Extrair frontmatter de todas as skills
for skill in .claude/skills/*/SKILL.md; do
  echo "=== $skill ==="
  sed -n '/^---$/,/^---$/p' "$skill"
done

# Verificar campo específico
grep -h "^name:" .claude/skills/*/SKILL.md
grep -h "^scope:" .claude/skills/*/SKILL.md
grep -h "^keywords:" .claude/skills/*/SKILL.md

4. Análise de Keywords (Detecção de Conflitos)

O que verificar:

• Keywords muito genéricas (automation, setup, agent)
• Sobreposição entre meta-skills e domain-skills
• Falta de keywords específicas

Estratégia de análise:

# Extrair todas as keywords
grep -h "^keywords:" .claude/skills/*/SKILL.md | \
  sed 's/keywords: //' | \
  tr ',' '\n' | \
  sort | uniq -c | sort -rn

# Detectar duplicações (aparecem >1 vez)
# Se keyword aparece em meta E domain = CONFLITO POTENCIAL

Exemplo de conflito:

# cc-automation-setup/SKILL.md (meta)
keywords: automation, hooks, setup, meta  # ← "automation" é genérico

# app-automation-workflow/SKILL.md (domínio)
keywords: automation, workflows, ci-cd    # ← "automation" conflita!

# ✅ SOLUÇÃO:
# cc-automation-setup/SKILL.md
keywords: claude-code, cc-automation, tool-automation, hook-automation, meta-configuration

# app-automation-workflow/SKILL.md
keywords: application, app-automation, workflow-automation, ci-cd-pipeline, deployment

5. Análise de Hooks

O que validar:

• Permissões de execução (chmod +x)
• Estrutura de input/output correta (JSON via stdin/stdout)
• Timeout razoável (< 60s para maioria, < 300s para complexos)
• Tratamento de erros
• Documentação inline

Validação de permissões:

# Listar hooks sem permissão de execução
find .claude/hooks -type f \( -name "*.sh" -o -name "*.py" \) ! -perm -u+x

Validação de estrutura:

# Hooks bash devem ter shebang
find .claude/hooks -name "*.sh" -exec grep -L "^#!/bin/bash" {} \;

# Hooks python devem ter shebang
find .claude/hooks -name "*.py" -exec grep -L "^#!/usr/bin/env python" {} \;

# Hooks devem ler stdin e retornar JSON
grep -L "cat\|read" .claude/hooks/**/*.sh  # Detecta hooks que não leem stdin
grep -L "echo.*{" .claude/hooks/**/*.sh    # Detecta hooks que não retornam JSON

Verificar registro em settings.json:

# Hooks definidos em settings.json
jq '.hooks' .claude/settings.json

# Comparar com hooks existentes no filesystem
# Se hook existe em settings.json mas não em filesystem = PROBLEMA
# Se hook existe em filesystem mas não em settings.json = UNUSED

6. Análise de Commands

O que validar:

• Estrutura markdown consistente
• Frontmatter com escopo claro
• Instruções executáveis (não ambíguas)
• Exemplos de uso
• Estimativa de tempo (quando aplicável)

Estrutura esperada:

# Título do Command

> **Escopo:** [meta-configuration | domain-implementation]
> **Uso:** /[prefix]:[nome]
> **Descrição:** [O que este comando faz]
> **Tempo estimado:** [X-Y minutos] (opcional)

---

## Tarefa

[Descrição clara da tarefa]

## Passos

1. [Passo 1]
2. [Passo 2]
...

## Resultado Esperado

[O que deve acontecer ao final]

Validações:

# Commands devem ter frontmatter
for cmd in .claude/commands/*.md; do
  if ! grep -q "^>" "$cmd"; then
    echo "❌ $cmd: falta frontmatter"
  fi
done

# Commands devem ter seção de tarefa
for cmd in .claude/commands/*.md; do
  if ! grep -q "## Tarefa" "$cmd"; then
    echo "⚠️ $cmd: falta seção 'Tarefa'"
  fi
done

7. Análise de CLAUDE.md

O que validar:

• Existência de CLAUDE.md na raiz do projeto
• Declaração clara de escopo (meta vs domínio)
• Prefixo definido
• Estrutura adequada ao tipo de projeto

Campos esperados:

Para meta-repo:

# CLAUDE.md - Meta-Configuração Claude Code

> **📍 ESCOPO:** meta-configuration
> **🎯 PREFIXO:** `cc-`
> **📅 Criado:** [DATA]

[Documentação sobre configuração do Claude Code]

Para projeto de domínio:

# CLAUDE.md - Projeto [NOME]

> **📍 ESCOPO:** domain-implementation
> **🎯 PREFIXO:** `[projeto]-`
> **📅 Criado:** [DATA]

[Documentação sobre o projeto]

---

**Meta-configuração herdada de:**
`/caminho/para/claude-code/CLAUDE.md`

Validação:

# Verificar existência
if [ ! -f "CLAUDE.md" ]; then
  echo "❌ CLAUDE.md não encontrado na raiz do projeto"
fi

# Verificar declaração de escopo
if ! grep -q "ESCOPO:" CLAUDE.md; then
  echo "⚠️ CLAUDE.md não declara escopo (meta-configuration ou domain-implementation)"
fi

# Verificar declaração de prefixo
if ! grep -q "PREFIXO:" CLAUDE.md; then
  echo "⚠️ CLAUDE.md não declara prefixo para primitivos"
fi

8. Análise de Settings.json

O que validar:

• JSON válido (sem erros de sintaxe)
• Hooks registrados corretamente
• Permissions adequadas ao projeto
• Output style configurado
• Caminhos de hooks válidos

Validação de sintaxe:

# Validar JSON
jq empty .claude/settings.json 2>&1 && echo "✅ JSON válido" || echo "❌ JSON inválido"

Validação de hooks:

# Extrair comandos de hooks
jq -r '.hooks[][].hooks[].command' .claude/settings.json 2>/dev/null | while read cmd; do
  # Expandir variáveis
  cmd_expanded="${cmd//\$CLAUDE_PROJECT_DIR/.}"

  if [ ! -f "$cmd_expanded" ]; then
    echo "❌ Hook não encontrado: $cmd_expanded"
  fi
done

Validação de permissions:

# Verificar se há permissions configuradas
if ! jq -e '.permissions' .claude/settings.json >/dev/null 2>&1; then
  echo "⚠️ Nenhuma permission configurada em settings.json"
fi

# Listar permissions permitidas
jq -r '.permissions.allow[]' .claude/settings.json 2>/dev/null

---

🎯 Sistema de Scoring

Categorias de Qualidade (Pesos)

Categoria	Peso	Descrição
Nomenclatura	20%	Consistência de prefixos, convenções, clareza
Estrutura	20%	Organização de diretórios, completude de arquivos
Documentação	15%	CLAUDE.md, frontmatter, inline docs
Validação	15%	Frontmatter válido, JSON válido, sintaxe correta
Best Practices	15%	Seguimento de convenções, separação de escopo
Completude	15%	Gaps identificados, features missing

Fórmula de Score

Score Final = (
  (Nomenclatura_Score * 0.20) +
  (Estrutura_Score * 0.20) +
  (Documentação_Score * 0.15) +
  (Validação_Score * 0.15) +
  (BestPractices_Score * 0.15) +
  (Completude_Score * 0.15)
) * 100

Escala: 0-100

Classificação

Score	Classificação	Ação Recomendada
90-100	🟢 Excelente	Manutenção preventiva
80-89	🟢 Bom	Melhorias incrementais
70-79	🟡 Aceitável	Resolver problemas médios
60-69	🟡 Precisa melhorar	Refatoração parcial
50-59	🟠 Problemático	Refatoração significativa
0-49	🔴 Crítico	Reconfiguração completa

---

📋 Workflow de Análise

Fase 1: Descoberta (5-10 min)

# 1. Identificar contexto do projeto
pwd
cat CLAUDE.md 2>/dev/null | head -20

# 2. Mapear estrutura
tree -L 3 .claude/ 2>/dev/null || find .claude -maxdepth 3 -type f

# 3. Inventariar primitivos
echo "=== SKILLS ==="
find .claude/skills -name "SKILL.md" -exec echo {} \;

echo "=== COMMANDS ==="
find .claude/commands -name "*.md" -exec echo {} \;

echo "=== HOOKS ==="
find .claude/hooks -type f \( -name "*.sh" -o -name "*.py" \)

echo "=== SETTINGS ==="
jq . .claude/settings.json 2>/dev/null || echo "settings.json não encontrado"

Fase 2: Validação de Nomenclatura (10-15 min)

# 1. Extrair prefixo esperado de CLAUDE.md
EXPECTED_PREFIX=$(grep "PREFIXO:" CLAUDE.md | grep -o '`[^`]*`' | tr -d '`' | head -1)
echo "Prefixo esperado: $EXPECTED_PREFIX"

# 2. Validar skills
for skill_dir in .claude/skills/*/; do
  skill_name=$(basename "$skill_dir")

  if [[ ! "$skill_name" == $EXPECTED_PREFIX* ]]; then
    echo "❌ Skill $skill_name não começa com $EXPECTED_PREFIX"
  fi
done

# 3. Validar commands
for cmd in .claude/commands/*.md; do
  cmd_name=$(basename "$cmd" .md)

  if [[ ! "$cmd_name" == $EXPECTED_PREFIX* ]]; then
    echo "❌ Command $cmd_name não começa com $EXPECTED_PREFIX"
  fi
done

# 4. Validar hooks
for hook in .claude/hooks/**/*.*sh .claude/hooks/**/*.py; do
  [ -f "$hook" ] || continue
  hook_name=$(basename "$hook")

  if [[ ! "$hook_name" == $EXPECTED_PREFIX* ]] && [[ "$hook" != *"/examples/"* ]]; then
    echo "⚠️ Hook $hook_name não começa com $EXPECTED_PREFIX"
  fi
done

Fase 3: Análise de Frontmatter (15-20 min)

# Para cada skill, validar frontmatter completo
for skill in .claude/skills/*/SKILL.md; do
  echo "=== Analisando: $skill ==="

  # Extrair frontmatter
  frontmatter=$(sed -n '/^---$/,/^---$/p' "$skill" | sed '1d;$d')

  # Validar campos obrigatórios
  for field in name scope target description keywords; do
    if ! echo "$frontmatter" | grep -q "^$field:"; then
      echo "❌ Campo obrigatório ausente: $field"
    fi
  done

  # Validar scope vs target
  scope=$(echo "$frontmatter" | grep "^scope:" | cut -d: -f2- | xargs)
  target=$(echo "$frontmatter" | grep "^target:" | cut -d: -f2- | xargs)

  if [[ "$scope" == "meta-configuration" ]] && [[ "$target" != "claude-code-itself" ]]; then
    echo "⚠️ Scope é meta-configuration mas target não é claude-code-itself"
  fi

  # Validar keywords
  keywords=$(echo "$frontmatter" | grep "^keywords:" | cut -d: -f2-)

  if [[ "$scope" == "meta-configuration" ]] && ! echo "$keywords" | grep -q "claude-code"; then
    echo "⚠️ Meta-skill deve ter keyword 'claude-code'"
  fi

  if [[ "$scope" == "domain-implementation" ]] && echo "$keywords" | grep -q "claude-code\|meta"; then
    echo "⚠️ Domain-skill não deve ter keywords 'claude-code' ou 'meta' (conflito)"
  fi
done

Fase 4: Detecção de Conflitos de Keywords (10-15 min)

# Extrair todas as keywords e contar ocorrências
echo "=== Análise de Keywords ==="

all_keywords=$(grep -h "^keywords:" .claude/skills/*/SKILL.md | \
  sed 's/keywords: //' | \
  tr ',' '\n' | \
  sed 's/^ *//;s/ *$//' | \
  sort)

# Contar duplicações
duplicates=$(echo "$all_keywords" | uniq -d)

if [ -n "$duplicates" ]; then
  echo "⚠️ Keywords duplicadas detectadas:"
  echo "$duplicates"

  # Para cada keyword duplicada, mostrar em quais skills aparece
  while read -r keyword; do
    echo ""
    echo "Keyword '$keyword' aparece em:"
    grep -l "$keyword" .claude/skills/*/SKILL.md
  done <<< "$duplicates"
else
  echo "✅ Nenhuma duplicação de keywords detectada"
fi

# Detectar keywords muito genéricas
generic_keywords="automation setup config agent deployment testing build"
for generic in $generic_keywords; do
  if echo "$all_keywords" | grep -qw "$generic"; then
    echo "⚠️ Keyword genérica detectada: '$generic'"
    echo "   Skills usando essa keyword:"
    grep -l "keywords:.*$generic" .claude/skills/*/SKILL.md
  fi
done

Fase 5: Análise de Hooks (10-15 min)

echo "=== Análise de Hooks ==="

# 1. Verificar permissões
echo "Hooks sem permissão de execução:"
find .claude/hooks -type f \( -name "*.sh" -o -name "*.py" \) ! -perm -u+x

# 2. Verificar shebang
echo ""
echo "Scripts Bash sem shebang:"
find .claude/hooks -name "*.sh" -exec grep -L "^#!/bin/bash\|^#!/usr/bin/env bash" {} \;

echo ""
echo "Scripts Python sem shebang:"
find .claude/hooks -name "*.py" -exec grep -L "^#!/usr/bin/env python" {} \;

# 3. Verificar estrutura de input/output
echo ""
echo "Hooks que podem não estar lendo stdin:"
for hook in .claude/hooks/**/*.sh; do
  [ -f "$hook" ] || continue
  if ! grep -q "cat\|read" "$hook"; then
    echo "⚠️ $hook: pode não estar lendo stdin"
  fi
done

# 4. Comparar hooks registrados vs existentes
echo ""
echo "Hooks registrados em settings.json:"
registered_hooks=$(jq -r '.hooks[][].hooks[].command' .claude/settings.json 2>/dev/null | \
  sed 's|\$CLAUDE_PROJECT_DIR|.|g')

echo "$registered_hooks" | while read -r hook_path; do
  if [ ! -f "$hook_path" ]; then
    echo "❌ Hook registrado não encontrado: $hook_path"
  fi
done

# 5. Hooks existentes mas não registrados
echo ""
echo "Hooks não registrados em settings.json:"
for hook in .claude/hooks/**/*.*sh .claude/hooks/**/*.py; do
  [ -f "$hook" ] || continue
  [ -x "$hook" ] || continue  # Só considerar executáveis

  hook_relative=".claude/${hook#*.claude/}"

  if ! echo "$registered_hooks" | grep -q "$hook_relative"; then
    echo "⚠️ Hook não registrado: $hook_relative"
  fi
done

Fase 6: Cálculo de Score (10-15 min)

# Implementar sistema de scoring baseado em problemas detectados

# Inicializar scores
nomenclatura_score=100
estrutura_score=100
documentacao_score=100
validacao_score=100
bestpractices_score=100
completude_score=100

# Deduzir pontos baseado em problemas detectados

# Nomenclatura (deduzir 10 pontos por prefixo incorreto)
incorrect_prefixes=$(find .claude/skills .claude/commands -name "*.md" | wc -l)  # Simplificado
nomenclatura_score=$((nomenclatura_score - (incorrect_prefixes * 10)))

# Estrutura (deduzir por arquivos faltantes)
[ ! -f "CLAUDE.md" ] && estrutura_score=$((estrutura_score - 30))
[ ! -f ".claude/settings.json" ] && estrutura_score=$((estrutura_score - 20))

# Documentação (deduzir por frontmatter incompleto)
incomplete_frontmatter=$(grep -L "description:" .claude/skills/*/SKILL.md | wc -l)
documentacao_score=$((documentacao_score - (incomplete_frontmatter * 15)))

# Validação (deduzir por erros de sintaxe)
! jq empty .claude/settings.json 2>/dev/null && validacao_score=$((validacao_score - 40))

# Best practices (deduzir por keywords conflitantes)
conflicting_keywords=$(echo "$duplicates" | wc -l)
bestpractices_score=$((bestpractices_score - (conflicting_keywords * 10)))

# Completude (deduzir por hooks não registrados)
unregistered_hooks=$(find .claude/hooks -type f -executable | wc -l)  # Simplificado
completude_score=$((completude_score - (unregistered_hooks * 5)))

# Garantir scores >= 0
nomenclatura_score=$((nomenclatura_score < 0 ? 0 : nomenclatura_score))
estrutura_score=$((estrutura_score < 0 ? 0 : estrutura_score))
documentacao_score=$((documentacao_score < 0 ? 0 : documentacao_score))
validacao_score=$((validacao_score < 0 ? 0 : validacao_score))
bestpractices_score=$((bestpractices_score < 0 ? 0 : bestpractices_score))
completude_score=$((completude_score < 0 ? 0 : completude_score))

# Calcular score final
score_final=$(awk "BEGIN {
  printf \"%.1f\", (
    ($nomenclatura_score * 0.20) +
    ($estrutura_score * 0.20) +
    ($documentacao_score * 0.15) +
    ($validacao_score * 0.15) +
    ($bestpractices_score * 0.15) +
    ($completude_score * 0.15)
  )
}")

echo ""
echo "=== SCORE FINAL ==="
echo "Nomenclatura:   $nomenclatura_score/100 (20%)"
echo "Estrutura:      $estrutura_score/100 (20%)"
echo "Documentação:   $documentacao_score/100 (15%)"
echo "Validação:      $validacao_score/100 (15%)"
echo "Best Practices: $bestpractices_score/100 (15%)"
echo "Completude:     $completude_score/100 (15%)"
echo ""
echo "SCORE FINAL: $score_final/100"

# Classificação
if (( $(echo "$score_final >= 90" | bc -l) )); then
  echo "Classificação: 🟢 Excelente"
elif (( $(echo "$score_final >= 80" | bc -l) )); then
  echo "Classificação: 🟢 Bom"
elif (( $(echo "$score_final >= 70" | bc -l) )); then
  echo "Classificação: 🟡 Aceitável"
elif (( $(echo "$score_final >= 60" | bc -l) )); then
  echo "Classificação: 🟡 Precisa melhorar"
elif (( $(echo "$score_final >= 50" | bc -l) )); then
  echo "Classificação: 🟠 Problemático"
else
  echo "Classificação: 🔴 Crítico"
fi

Fase 7: Geração de Relatório (10-15 min)

Gerar relatório markdown com:

• Executive summary (score, classificação)
• Inventário completo (primitivos detectados)
• Problemas por severidade (críticos, altos, médios, baixos)
• Recomendações priorizadas
• Roadmap de melhorias (quick wins vs long-term)

Template: Usar estrutura similar ao audit-report-template.md do BOM-STACK-PLANEJAMENTO, adaptado para análise de primitivos do Claude Code.

---

🛠️ Recomendações Padrão

Problemas Críticos (Bloquear uso)

Problema	Impacto	Recomendação
settings.json inválido	Configuração não carrega	Corrigir sintaxe JSON imediatamente
Hooks sem permissão	Hooks não executam	chmod +x em todos os hooks
Conflito de escopo	Auto-discovery quebrado	Renomear skills conflitantes com prefixo correto
CLAUDE.md ausente	Ambiguidade de contexto	Criar CLAUDE.md declarando escopo

Problemas Altos (Resolver em 7 dias)

Problema	Impacto	Recomendação
Prefixos inconsistentes	Confusão, conflitos futuros	Padronizar todos os prefixos
Keywords genéricas	Colisão entre skills	Especializar keywords com namespaces
Frontmatter incompleto	Skills não descobertas	Completar YAML frontmatter
Hooks não registrados	Funcionalidades não ativas	Registrar em settings.json

Problemas Médios (Resolver em 30 dias)

Problema	Impacto	Recomendação
Documentação inline fraca	Baixa manutenibilidade	Adicionar comentários, exemplos
Commands sem estrutura	Difícil de usar	Adicionar frontmatter, seções
Hooks sem timeout	Risco de travamento	Definir timeout apropriado
Skills muito genéricas	Auto-discovery impreciso	Especializar descrição, keywords

Melhorias Oportunísticas (Backlog)

Melhoria	Benefício	Recomendação
Knowledge base vazio	Menos contexto para Claude	Criar documentação de referência
Templates ausentes	Menos padronização	Criar templates para novos primitivos
Tests ausentes	Menor confiabilidade	Adicionar testes de validação
CI/CD não configurado	Validação manual	Automatizar validação em PRs

---

🎓 Insights Educacionais

Separação de Escopo: Meta vs Domínio

A confusão mais comum é misturar primitivos de configuração DO Claude Code com primitivos de implementação DO projeto.

Regra de Ouro:

SE o primitive configura, otimiza, ou debug o PRÓPRIO Claude Code:
  → scope: meta-configuration
  → prefixo: cc-
  → target: claude-code-itself
  → keywords: claude-code, cc-*, meta, tool-*

SE o primitive implementa funcionalidades DO projeto/aplicação:
  → scope: domain-implementation
  → prefixo: [projeto]-
  → target: application-feature (ou similar)
  → keywords: application, [projeto]-*, business-logic, feature-*

Exemplo:

❌ ERRADO (mistura conceitos):
   Skill: app-hooks-setup
   Descrição: "Configure hooks for the Claude Code tool"
   → Meta-conceito (Claude Code) em primitivo de domínio (app-)

✅ CORRETO (separado):
   # Meta-repo
   Skill: cc-hooks-setup
   Descrição: "Configure Claude Code lifecycle hooks"

   # Projeto
   Skill: app-webhook-handler
   Descrição: "Handle application webhooks for external integrations"

Auto-Discovery: Como Funciona

Claude Code detecta skills relevantes baseado em:

1. Keywords matching (pergunta do usuário vs keywords da skill)
2. Description similarity (embedding vectors)
3. Context awareness (working directory, CLAUDE.md)

Otimização:

• Keywords específicas aumentam precision (menos false positives)
• Description detalhada aumenta recall (menos false negatives)
• Separação clara de escopo evita conflicts

Exemplo:

# ❌ MAL OTIMIZADO (genérico)
keywords: hooks, setup, automation
description: Setup hooks

# ✅ BEM OTIMIZADO (específico)
keywords: claude-code, cc-hooks, hook-automation, SessionStart, PostToolUse, PreToolUse, lifecycle-hooks, meta-configuration
description: Expert in configuring Claude Code lifecycle hooks (SessionStart, PostToolUse, PreToolUse) including bash/python implementation, JSON I/O validation, timeout management, error handling, and registration in settings.json

---

🚀 Uso desta Skill

Quando Ativar

Esta skill deve ser ativada quando o usuário:

• Pergunta "Como está minha configuração do Claude Code?"
• Pede "Analise a estrutura de skills/commands/hooks"
• Quer "Auditar a qualidade das configurações"
• Relata "Skills não estão sendo descobertas corretamente"
• Menciona "Validar separação de escopo meta vs domínio"

Workflow Típico

Usuário: "Pode analisar minha configuração do Claude Code?"

Claude (ativa cc-stack-analysis):
  1. Executa Fase 1-7 do workflow
  2. Gera score e classificação
  3. Lista problemas priorizados
  4. Fornece recomendações acionáveis
  5. Oferece gerar relatório completo

Integração com Outros Commands

Esta skill complementa:

• /cc:manage-primitives - CRUD operations nos primitivos
• /cc:setup - Configuração inicial de novos projetos
• /cc:diagnose - Diagnóstico de problemas específicos

Workflow recomendado:

1. /cc:stack-analysis → Identificar problemas
2. /cc:manage-primitives update → Corrigir problemas
3. /cc:stack-analysis → Validar correções

---

✅ Checklist de Análise Completa

• Inventário estrutural realizado (skills, commands, hooks, settings)
• Nomenclatura validada (prefixos, convenções, kebab-case)
• Frontmatter validado (campos obrigatórios, scope, target, keywords)
• Conflitos de keywords detectados e documentados
• Hooks analisados (permissões, estrutura, registro)
• Commands analisados (estrutura, frontmatter, clareza)
• CLAUDE.md validado (existência, escopo, prefixo)
• Settings.json validado (sintaxe, hooks, permissions)
• Score calculado (6 categorias ponderadas)
• Classificação determinada (Excelente → Crítico)
• Problemas priorizados (Críticos, Altos, Médios, Oportunísticos)
• Recomendações geradas (acionáveis, com exemplos)
• Relatório formatado (markdown, estruturado)

---

Esta skill foi projetada para garantir qualidade e consistência nas configurações do Claude Code, facilitando manutenção, evolução e troubleshooting.