Back to skills
SkillHub ClubShip Full StackFull Stack

cc-separation-guide

Complete guide for separating meta-configurations (Claude Code tool configuration) from domain configurations (project implementation). Learn how to avoid conflicts when working with multiple projects, especially those using agent SDKs/ADKs like Google ADK, LangChain, or Anthropic SDK. Covers namespace isolation, prefixing conventions, CLAUDE.md hierarchy, scope declaration, and conflict detection strategies.

Packaged view

This page reorganizes the original catalog entry around fit, installability, and workflow context first. The original raw source lives below.

Stars
0
Hot score
74
Updated
March 20, 2026
Overall rating
C0.0
Composite score
0.0
Best-practice grade
N/A

Install command

npx @skill-hub/cli install joaopelegrino-claude-code-cc-separation-guide
claude-codemeta-configurationconflict-resolutionproject-isolationagent-sdk

Repository

joaopelegrino/claude-code

Skill path: .claude/skills/cc-separation-guide

Complete guide for separating meta-configurations (Claude Code tool configuration) from domain configurations (project implementation). Learn how to avoid conflicts when working with multiple projects, especially those using agent SDKs/ADKs like Google ADK, LangChain, or Anthropic SDK. Covers namespace isolation, prefixing conventions, CLAUDE.md hierarchy, scope declaration, and conflict detection strategies.

Open repository

Best for

Primary workflow: Ship Full Stack.

Technical facets: Full Stack.

Target audience: everyone.

License: Unknown.

Original source

Catalog source: SkillHub Club.

Repository owner: joaopelegrino.

This is still a mirrored public skill entry. Review the repository before installing into production workflows.

What it helps with

  • Install cc-separation-guide into Claude Code, Codex CLI, Gemini CLI, or OpenCode workflows
  • Review https://github.com/joaopelegrino/claude-code before adding cc-separation-guide to shared team environments
  • Use cc-separation-guide for development workflows

Works across

Claude CodeCodex CLIGemini CLIOpenCode

Favorites: 0.

Sub-skills: 0.

Aggregator: No.

Original source / Raw SKILL.md

---
name: cc-separation-guide
scope: meta-configuration
target: claude-code-itself
description: Complete guide for separating meta-configurations (Claude Code tool configuration) from domain configurations (project implementation). Learn how to avoid conflicts when working with multiple projects, especially those using agent SDKs/ADKs like Google ADK, LangChain, or Anthropic SDK. Covers namespace isolation, prefixing conventions, CLAUDE.md hierarchy, scope declaration, and conflict detection strategies.
keywords: claude-code, cc-separation, meta-configuration, domain-configuration, namespace, prefixes, conflict-resolution, scope, agent-sdk, adk, separation-of-concerns, project-isolation, cc-conventions
allowed-tools: Read,Grep,Glob,Edit
---

# Claude Code: Separação Meta vs Domínio

> **⚠️ META-CONFIGURAÇÃO CRÍTICA**
> Este skill trata da SEPARAÇÃO entre configurações DO Claude Code (meta) e configurações DE PROJETOS (domínio). Essencial para evitar conflitos.

---

## 🎯 Problema a Resolver

### Cenário de Conflito

Quando você tem:

1. **Meta-repositório** (`/workspace/claude-code`):
   - Base de conhecimento SOBRE Claude Code
   - Skills para CONFIGURAR Claude Code
   - Templates para APLICAR em projetos

2. **Projeto-alvo** (`/workspace/meu-projeto`):
   - Implementação de funcionalidades
   - Skills DE DOMÍNIO (ex: authentication, API)
   - Pode usar SDKs agênticos (Google ADK, LangChain)

**Problema:** Ambos usam terminologia similar:
- "agent", "skill", "command", "hook"
- Mas significados DIFERENTES

**Resultado sem separação:**
- 🔴 Claude confunde "agent do Claude Code" com "agent do projeto"
- 🔴 Skills de meta ativam quando devia ativar skills de domínio
- 🔴 Commands conflitam (ex: `/setup` - setup de quê?)
- 🔴 Hooks executam no contexto errado

---

## 🏗️ Arquitetura de Separação

### Princípio Fundamental

```
META-CONFIGURAÇÃO          ≠          CONFIGURAÇÃO DE DOMÍNIO
(Sobre a ferramenta)                  (Sobre o projeto)

Target: Claude Code                   Target: Funcionalidades
Prefixo: cc-                          Prefixo: <projeto>-
Escopo: meta-configuration            Escopo: domain-implementation
Keywords: claude-code, tool, meta     Keywords: application, feature, app
```

### Visualização da Separação

```
┌─────────────────────────────────────────────────────────────┐
│  Meta-Repositório: /workspace/claude-code                   │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ .claude/                                               │ │
│  │ ├── skills/                                            │ │
│  │ │   ├── cc-overview/           ← Sobre Claude Code   │ │
│  │ │   ├── cc-hooks-guide/        ← Sobre Claude Code   │ │
│  │ │   └── cc-separation-guide/   ← Sobre Claude Code   │ │
│  │ ├── commands/                                          │ │
│  │ │   ├── cc-setup.md            ← Setup do Claude Code │ │
│  │ │   └── cc-diagnose.md                                │ │
│  │ └── CLAUDE.md                  ← Diretrizes META      │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

                              ≠

┌─────────────────────────────────────────────────────────────┐
│  Projeto: /workspace/meu-app                                │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ .claude/                                               │ │
│  │ ├── skills/                                            │ │
│  │ │   ├── app-auth-agent/        ← Autenticação da app │ │
│  │ │   ├── app-api-setup/         ← API da app          │ │
│  │ │   └── app-deploy/            ← Deploy da app       │ │
│  │ ├── commands/                                          │ │
│  │ │   ├── app-setup.md           ← Setup da APP        │ │
│  │ │   └── app-test.md            ← Testes da app       │ │
│  │ └── CLAUDE.md                  ← Diretrizes PROJETO  │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```

---

## 📐 Convenções de Nomenclatura

### Regra de Ouro

```
SE artefato é SOBRE Claude Code → prefixo cc-
SE artefato é SOBRE projeto → prefixo do projeto
NUNCA usar nomes genéricos sem prefixo
```

### Tabela de Prefixos

| Contexto | Prefixo | Exemplo Skill | Exemplo Command |
|----------|---------|---------------|-----------------|
| **Meta** (Claude Code) | `cc-` | `cc-hooks-guide` | `cc-setup.md` |
| **Projeto Web** | `app-` | `app-auth-setup` | `app-deploy.md` |
| **Backend API** | `api-` | `api-endpoints` | `api-test.md` |
| **Microserviço** | `svc-` | `svc-payments` | `svc-deploy.md` |
| **SDK Agêntico** | `<sdk>-` | `cva-agent-types` | `cva-new-agent.md` |

### Exemplos Corretos vs Incorretos

#### Skills

| ✅ Correto | ❌ Incorreto | Problema |
|-----------|-------------|----------|
| `cc-hooks-setup` | `hooks-setup` | Ambíguo (hooks de quê?) |
| `app-auth-flow` | `auth-flow` | Conflita com auth do Claude Code |
| `cva-healthcare-pipeline` | `healthcare-pipeline` | Sem namespace, genérico |

#### Commands

| ✅ Correto | ❌ Incorreto | Problema |
|-----------|-------------|----------|
| `/cc:setup` | `/setup` | Conflita com setup de projeto |
| `/app:deploy` | `/deploy` | Ambíguo (deploy de quê?) |
| `/api:test` | `/test` | Genérico demais |

#### Hooks

| ✅ Correto | ❌ Incorreto | Problema |
|-----------|-------------|----------|
| `cc-posttool-format.sh` | `format.sh` | Não indica contexto |
| `app-posttool-lint.sh` | `lint.sh` | Pode conflitar |

---

## 📝 Declaração Explícita de Escopo

### YAML Frontmatter Obrigatório

Toda skill DEVE declarar seu escopo no frontmatter:

#### Meta-Skill (Claude Code)

```yaml
---
name: cc-hooks-guide
scope: meta-configuration              # ← OBRIGATÓRIO
target: claude-code-itself             # ← O QUE configura
description: Complete guide to Claude Code hooks. This is about CONFIGURING the Claude Code TOOL itself, not project code.
keywords: claude-code, cc-hooks, meta-configuration, tool-configuration, automation
allowed-tools: Read,Edit,Write
---

# Claude Code Hooks Guide

> **⚠️ META-CONFIGURAÇÃO**
> Este skill configura o PRÓPRIO Claude Code, não código de projeto.
```

#### Domain-Skill (Projeto)

```yaml
---
name: app-auth-setup
scope: domain-implementation           # ← OBRIGATÓRIO
target: application-feature            # ← O QUE implementa
description: Authentication setup for the application using OAuth2 and JWT. This is about APPLICATION functionality, not Claude Code configuration.
keywords: application, app-auth, authentication, oauth2, jwt, security
allowed-tools: Read,Edit,Write,Bash
---

# Application Authentication Setup

> **🎯 FUNCIONALIDADE DO PROJETO**
> Este skill implementa autenticação na aplicação, não configura Claude Code.
```

### Campos Obrigatórios

| Campo | Meta | Domínio | Propósito |
|-------|------|---------|-----------|
| `scope` | `meta-configuration` | `domain-implementation` | Identifica escopo |
| `target` | `claude-code-itself` | `application-feature` | Identifica alvo |
| `description` | Deve incluir "Claude Code" e "tool" | Deve incluir nome do projeto/feature | Auto-discovery |
| `keywords` | Incluir `claude-code`, `cc-*`, `meta` | Incluir nome do projeto, features | Evitar sobreposição |

---

## 🧭 Hierarquia CLAUDE.md

### Estrutura de Precedência

```
~/.claude/CLAUDE.md                    # Nível 1: Global
    ↓  (princípios universais de desenvolvimento)

/workspace/claude-code/CLAUDE.md       # Nível 2: Meta
    ↓  (diretrizes de configuração do Claude Code)

/workspace/meu-projeto/CLAUDE.md       # Nível 3: Projeto
    ↓  (diretrizes específicas do projeto)
```

**Regra de Precedência:**
```
Projeto (mais específico) > Meta > Global (mais genérico)
```

### Conteúdo de Cada CLAUDE.md

#### Global (`~/.claude/CLAUDE.md`)

```markdown
# CLAUDE.md - Diretrizes Globais

> **Escopo:** Todos os projetos
> **Foco:** Princípios universais de desenvolvimento

## Conteúdo

- Princípios de execução autônoma
- Gestão de dependências
- Versionamento (SemVer)
- CI/CD patterns
- Quality gates
- Observabilidade

**Aplicável a:** Qualquer projeto, qualquer linguagem
```

#### Meta (`/workspace/claude-code/CLAUDE.md`)

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

> **Escopo:** Configuração do Claude Code
> **Foco:** Como configurar a ferramenta

## Conteúdo

- Separação meta vs domínio
- Prefixos obrigatórios (cc-)
- Estrutura de skills/commands/hooks
- Convenções de nomenclatura
- Templates para projetos

**Aplicável a:** Configuração do Claude Code em qualquer projeto
```

#### Projeto (`/workspace/meu-projeto/CLAUDE.md`)

```markdown
# CLAUDE.md - Projeto [Nome]

> **Escopo:** Desenvolvimento do projeto [Nome]
> **Prefixo:** `app-`

## Conteúdo

- Arquitetura do projeto
- Convenções específicas (app- prefix)
- Workflows de desenvolvimento
- Testing strategies
- Deployment procedures

**Herda de:** `/workspace/claude-code/CLAUDE.md` (meta-config)
**Sobrescreve:** Diretrizes conflitantes (precedência)
```

---

## 🔍 Detecção de Contexto

### Checklist de Verificação

Claude deve SEMPRE verificar antes de executar tarefas:

#### 1. Qual diretório estou?

```bash
pwd
# /workspace/claude-code        → Contexto META
# /workspace/meu-projeto        → Contexto PROJETO
```

#### 2. Qual CLAUDE.md tem precedência?

```python
if exists("/workspace/meu-projeto/CLAUDE.md"):
    context = "project"
    prefix = extract_prefix_from_claudemd()  # ex: "app-"
elif exists("/workspace/claude-code/CLAUDE.md"):
    context = "meta"
    prefix = "cc-"
else:
    context = "global"
    prefix = None  # use generic
```

#### 3. Prefixo esperado?

```
Contexto META → cc-
Contexto PROJETO → <projeto>- (extrair de CLAUDE.md)
```

#### 4. Keywords evitam conflito?

```yaml
# META
keywords: claude-code, cc-*, tool-*, meta-configuration

# PROJETO
keywords: application, app-*, feature-*, business-logic

# ✅ Zero sobreposição
```

---

## 🎭 Resolução de Ambiguidades

### Cenário 1: Pergunta Sobre "Agent"

**Pergunta ambígua:**
```
"Como configuro um agent?"
```

**Claude detecta ambiguidade:**
```python
# Verificar contexto
pwd = get_current_directory()

if "claude-code" in pwd:
    # Contexto meta
    likely_meaning = "Claude Code agent (autonomous AI)"
    relevant_skill = "cc-agent-config"
else:
    # Contexto projeto
    likely_meaning = "Domain agent (LLM agent, workflow agent)"
    relevant_skill = "app-agent-setup"  # ou similar

# Se não houver certeza (keywords ambíguas), PERGUNTAR
```

**Claude pergunta ao usuário:**
```
🤔 Preciso clarificar o contexto da sua pergunta:

Você quer:

A) **Configurar Claude Code** (o agente autônomo da Anthropic)?
   → Contexto: Meta-configuração
   → Skill relevante: cc-agent-config
   → Exemplo: Configurar comportamento, permissões, output style

B) **Criar/configurar um agente de domínio** no seu projeto?
   → Contexto: Implementação de projeto
   → Skill relevante: app-agent-setup
   → Exemplo: Agente LLM, workflow agent, microserviço

Qual dos dois?
```

### Cenário 2: Auto-Discovery Correto

#### Usuário em `/workspace/claude-code`

```
Pergunta: "Como adiciono hooks?"

Claude detecta:
  - pwd: /workspace/claude-code
  - CLAUDE.md: Meta-configuração
  - Prefixo esperado: cc-

Claude busca skills:
  - Match: cc-hooks-guide
  - Keywords: claude-code, hooks, tool-configuration, meta

Claude ativa: cc-hooks-guide
Claude responde: "Hooks do Claude Code (SessionStart, PostToolUse, etc.)"
```

#### Usuário em `/workspace/meu-app`

```
Pergunta: "Como adiciono hooks?"

Claude detecta:
  - pwd: /workspace/meu-app
  - CLAUDE.md: Projeto (prefixo app-)
  - Prefixo esperado: app-

Claude busca skills:
  - Match: app-hooks-workflow (se existir)
  - Keywords: application, webhooks, event-handlers

Se skill existe:
  Claude ativa: app-hooks-workflow
  Claude responde: "Hooks da aplicação (webhooks, lifecycle events)"

Se skill NÃO existe:
  Claude pergunta: "Você quer configurar hooks do Claude Code ou implementar hooks na aplicação?"
```

### Cenário 3: Command Conflitante

**Comando:** `/setup`

```python
# Verificar contexto
pwd = get_current_directory()

if "claude-code" in pwd:
    # Buscar /cc:setup ou cc-setup.md
    execute_command("cc-setup")
else:
    # Buscar /<projeto>:setup ou <projeto>-setup.md
    project_prefix = extract_prefix()
    execute_command(f"{project_prefix}-setup")

# Se comando não existe, sugerir criar com prefixo
```

---

## 📊 Matriz de Conflitos Comuns

| Termo Ambíguo | Contexto Meta | Contexto Projeto |
|---------------|---------------|------------------|
| **agent** | Claude Code (IA autônoma) | Agente de domínio (LLM, workflow) |
| **skill** | Claude Code skill (SKILL.md) | Agent skill (capability, function) |
| **hook** | Claude Code lifecycle hook | Webhook, event handler |
| **command** | Slash command do Claude Code | CLI command, API endpoint |
| **tool** | Claude Code tool (Read, Write) | External tool (API client, lib) |
| **setup** | Setup do Claude Code | Setup do projeto/ambiente |
| **config** | Claude Code config (settings.json) | App config (env vars, config files) |

### Como Disambiguar

1. **Usar qualificadores:**
   ```
   "Claude Code hook" vs "application hook"
   "Claude Code agent" vs "domain agent"
   "Claude Code skill" vs "agent skill"
   ```

2. **Verificar prefixo:**
   ```
   cc-hook-setup     → META (Claude Code)
   app-hook-handler  → DOMÍNIO (Application)
   ```

3. **Verificar keywords:**
   ```yaml
   # Meta
   keywords: claude-code, tool, meta, cc-*

   # Domínio
   keywords: application, feature, app-*, business
   ```

4. **Perguntar quando incerto:**
   ```
   Claude: "Para clarificar: você está perguntando sobre
           configuração do Claude Code ou implementação do projeto?"
   ```

---

## 🛠️ Aplicação em Novos Projetos

### Template: Novo Projeto

#### Passo 1: NÃO Copiar Meta-Repo Inteiro

```bash
# ❌ ERRADO
cp -r /workspace/claude-code/.claude /workspace/novo-projeto/

# ✅ CORRETO (copiar apenas templates)
mkdir -p /workspace/novo-projeto/.claude
cp -r /workspace/claude-code/.claude/templates/* \
      /workspace/novo-projeto/.claude/
```

**Por quê?**
- Meta-repo tem skills SOBRE Claude Code
- Projeto precisa de skills SOBRE funcionalidades
- Copiar tudo = conflito garantido

#### Passo 2: Adaptar Prefixos

```bash
cd /workspace/novo-projeto/.claude

# Substituir todos os cc- pelo prefixo do projeto
PROJECT_PREFIX="myapp"

# Skills
find skills/ -type f -name "*.md" -exec sed -i "s/cc-/${PROJECT_PREFIX}-/g" {} +

# Commands
find commands/ -type f -name "*.md" -exec sed -i "s/cc-/${PROJECT_PREFIX}-/g" {} +

# Hooks
find hooks/ -type f -exec sed -i "s/cc-/${PROJECT_PREFIX}-/g" {} +

# Renomear arquivos/diretórios
for dir in skills/cc-*; do
  mv "$dir" "${dir/cc-/${PROJECT_PREFIX}-}"
done
```

#### Passo 3: Criar CLAUDE.md do Projeto

```bash
cat > /workspace/novo-projeto/CLAUDE.md <<'EOF'
# CLAUDE.md - Projeto [Nome]

> **📍 ESCOPO:** Desenvolvimento do projeto [Nome]
> **🎯 PREFIXO:** `myapp-` (para skills, commands, hooks)
> **📅 Criado:** $(date +%Y-%m-%d)

---

## 🎯 Visão Geral

Este projeto implementa [descrição].

## 📐 Convenções

### Nomenclatura
- **Prefixo obrigatório:** `myapp-`
- **Escopo:** domain-implementation
- **Target:** application-feature

### Skills
- `myapp-overview` - Visão geral do projeto
- `myapp-auth` - Autenticação
- `myapp-api` - Endpoints da API
- `myapp-deploy` - Deploy

### Commands
- `/myapp:setup` - Setup do ambiente
- `/myapp:test` - Executar testes
- `/myapp:deploy` - Deploy para produção

---

**Meta-configuração herdada de:**
`/home/notebook/workspace/claude-code/CLAUDE.md`

**Documentação de referência:**
`/home/notebook/workspace/claude-code/ARCHITECTURE_ANALYSIS.md`
EOF
```

#### Passo 4: Atualizar Frontmatter das Skills

```yaml
# Template do meta-repo (claude-code)
---
name: cc-exemplo
scope: meta-configuration
target: claude-code-itself
description: Configure Claude Code hooks
keywords: claude-code, cc-exemplo, meta, tool-configuration
---

↓ TRANSFORMAR EM ↓

# Skill do projeto (novo-projeto)
---
name: myapp-exemplo
scope: domain-implementation         # ← Mudou
target: application-feature          # ← Mudou
description: Configure application webhooks for real-time notifications
keywords: application, myapp-exemplo, webhooks, notifications, app-feature  # ← Mudou
---
```

#### Passo 5: Validar Separação

```bash
# Checklist de validação
./scripts/validate-separation.sh

# Saída esperada:
# ✅ Todos os skills têm prefixo myapp-
# ✅ Todos os commands têm prefixo myapp-
# ✅ CLAUDE.md declara escopo: domain-implementation
# ✅ Keywords não sobrepõem com meta-keywords
# ✅ Nenhum cc- permaneceu (exceto em referências)
```

---

## ✅ Checklist de Validação

### Antes de Commitar no Meta-Repo

- [ ] Todos os skills têm prefixo `cc-`
- [ ] Todos os commands têm prefixo `cc-`
- [ ] Todos os hooks têm prefixo `cc-`
- [ ] CLAUDE.md declara `scope: meta-configuration`
- [ ] Skills têm `scope: meta-configuration` em YAML
- [ ] Skills têm `target: claude-code-itself` em YAML
- [ ] Keywords incluem `claude-code`, `cc-*`, `meta-configuration`
- [ ] Nenhuma keyword genérica que possa conflitar
- [ ] Documentação inline indica "META-CONFIGURAÇÃO"

### Antes de Aplicar em Projeto

- [ ] Copiei apenas templates, NÃO estrutura completa
- [ ] Substituí TODOS os `cc-` pelo prefixo do projeto
- [ ] Criei CLAUDE.md específico do projeto
- [ ] Atualizei frontmatter: `scope: domain-implementation`
- [ ] Atualizei frontmatter: `target: application-feature`
- [ ] Substituí keywords meta por keywords de domínio
- [ ] Validei que nenhum `cc-` permaneceu
- [ ] Executei script de validação de separação
- [ ] Documentei link para meta-repo no CLAUDE.md

---

## 🎓 Exemplos Práticos

### Exemplo 1: Projeto com Google ADK

**Problema:** Google ADK usa "agents" → conflito com "agent" do Claude Code

**Solução:**
```yaml
# Meta-skill (claude-code)
---
name: cc-agent-config
keywords: claude-code, autonomous-ai, claude-agent, tool-agent
description: Configure Claude Code autonomous agent behavior
---

# Project-skill (google-adk-project)
---
name: cva-agent-types
keywords: google-adk, llm-agents, sequential-agents, parallel-agents
description: Google ADK agent types (LLM, Sequential, Parallel)
---
```

**Resultado:** Zero sobreposição de keywords = zero conflito

### Exemplo 2: Projeto com LangChain

**Problema:** LangChain usa "tools" → conflito com "tools" do Claude Code

**Solução:**
```yaml
# Meta-skill
---
name: cc-tools-reference
keywords: claude-code-tools, read-tool, write-tool, bash-tool
description: Claude Code built-in tools (Read, Write, Edit, Bash)
---

# Project-skill
---
name: lc-tools-integration
keywords: langchain-tools, external-apis, tool-calling, function-calling
description: LangChain tool integration with external APIs
---
```

### Exemplo 3: Microserviços com Múltiplos Repos

**Estrutura:**
```
workspace/
├── claude-code/              # Meta-repo (cc-)
├── payment-service/          # Serviço 1 (pay-)
├── auth-service/             # Serviço 2 (auth-)
└── notification-service/     # Serviço 3 (notif-)
```

**Prefixos únicos:**
- Meta: `cc-`
- Payment: `pay-`
- Auth: `auth-`
- Notification: `notif-`

**Resultado:** Cada repo tem namespace isolado

---

## 🔧 Ferramentas de Validação

### Script: validate-separation.sh

```bash
#!/bin/bash
# Valida separação de escopo

# Detectar contexto
if [[ "$PWD" == *"claude-code"* ]]; then
  CONTEXT="meta"
  EXPECTED_PREFIX="cc-"
else
  CONTEXT="domain"
  EXPECTED_PREFIX=$(grep "PREFIXO:" CLAUDE.md 2>/dev/null | grep -oP '`\K[^`]+' || echo "UNKNOWN")
fi

echo "🔍 Validando separação de escopo..."
echo "📍 Contexto: $CONTEXT"
echo "🏷️  Prefixo esperado: $EXPECTED_PREFIX"

# Validar skills
echo ""
echo "📦 Validando skills..."
ERRORS=0

for skill in .claude/skills/*/SKILL.md; do
  SKILL_NAME=$(basename "$(dirname "$skill")")

  # Verificar prefixo
  if [[ "$SKILL_NAME" != $EXPECTED_PREFIX* ]]; then
    echo "❌ $SKILL_NAME (deveria começar com $EXPECTED_PREFIX)"
    ((ERRORS++))
  else
    # Verificar frontmatter
    SCOPE=$(grep "^scope:" "$skill" | cut -d':' -f2 | xargs)
    TARGET=$(grep "^target:" "$skill" | cut -d':' -f2 | xargs)

    if [[ "$CONTEXT" == "meta" ]]; then
      if [[ "$SCOPE" != "meta-configuration" ]]; then
        echo "⚠️  $SKILL_NAME: scope deveria ser 'meta-configuration', não '$SCOPE'"
      fi
      if [[ "$TARGET" != "claude-code-itself" ]]; then
        echo "⚠️  $SKILL_NAME: target deveria ser 'claude-code-itself', não '$TARGET'"
      fi
    fi

    echo "✅ $SKILL_NAME"
  fi
done

if [[ $ERRORS -gt 0 ]]; then
  echo ""
  echo "❌ $ERRORS erro(s) encontrado(s)"
  exit 1
else
  echo ""
  echo "✅ Validação concluída com sucesso!"
  exit 0
fi
```

---

## 📚 Recursos Adicionais

### Documentação Relacionada

- `ARCHITECTURE_ANALYSIS.md` - Análise detalhada de riscos
- `CLAUDE.md` - Diretrizes completas do meta-repo
- `cc-overview` - Overview do Claude Code
- `cc-hooks-guide` - Guia de hooks
- `cc-skills-guide` - Guia de skills

### Links Externos

- [Claude Code Documentation](https://docs.claude.com/claude-code)
- [Skills Best Practices](https://docs.claude.com/claude-code/skills)
- [Naming Conventions](https://docs.claude.com/claude-code/best-practices)

---

**🎯 Próximo Passo:**

Aplicar estas diretrizes ao criar qualquer configuração nova:
1. Identificar contexto (meta ou domínio)
2. Usar prefixo correto
3. Declarar escopo no frontmatter
4. Validar separação com script
5. Documentar no CLAUDE.md

---

**Última atualização:** 2025-10-30
**Versão:** 1.0.0