agent-skill-creator/docs/CLAUDE_SKILLS_ARCHITECTURE.md

Claude Skills Architecture: Guia Completo

🎯 Propósito

Este documento elimina a confusão entre diferentes tipos de Skills Claude Code e estabelece terminologia consistente.

📚 Terminologia Padrão

Skill

Uma Skill é uma capacidade completa do Claude Code implementada como uma pasta contendo:

• Arquivo SKILL.md (obrigatório)
• Recursos opcionais (scripts/, references/, assets/)
• Funcionalidade específica para um domínio

Exemplo: minha-skill/ contendo análise de dados financeiros

Component Skill

Uma Component Skill é uma sub-skill especializada que é parte de uma Skill Suite maior.

• Tem seu próprio SKILL.md
• Foca em uma funcionalidade específica
• Compartilha recursos com outras component skills

Exemplo: data-acquisition/SKILL.md dentro de uma suite de análise financeira

Skill Suite

Uma Skill Suite é uma coleção integrada de Component Skills que trabalham juntas.

• Tem marketplace.json como manifest
• Múltiplas component skills especializadas
• Recursos compartilhados entre skills

Exemplo: Suite completa de análise financeira com skills para data acquisition, analysis, e reporting.

Marketplace Plugin

Um Marketplace Plugin é o arquivo marketplace.json que hospeda e organiza uma ou mais Skills.

• NÃO é uma skill - é um manifest organizacional
• Define como as skills devem ser carregadas
• Pode hospedar skills simples ou suites complexas

🏗️ Tipos de Arquitetura

Arquitetura 1: Simple Skill

minha-skill/
├── SKILL.md              ← Single skill file
├── scripts/              ← Optional supporting code
├── references/           ← Optional documentation
└── assets/               ← Optional templates/resources

Quando usar:

• Funcionalidade focada e única
• Workflow simples
• Menos de 1000 linhas de código total
• Um objetivo principal

Exemplos:

• Gerador de propostas comerciais
• Extrator de dados de PDFs
• Calculadora de ROI

Arquitetura 2: Complex Skill Suite

minha-suite/                    ← Skill Suite completa
├── .claude-plugin/
│   └── marketplace.json        ← Manifest das skills
├── componente-1/               ← Component Skill 1
│   ├── SKILL.md
│   └── scripts/
├── componente-2/               ← Component Skill 2
│   ├── SKILL.md
│   └── references/
├── componente-3/               ← Component Skill 3
│   ├── SKILL.md
│   └── assets/
└── shared/                     ← Recursos compartilhados
    ├── utils/
    ├── config/
    └── templates/

Quando usar:

• Múltiplos workflows relacionados
• Funcionalidades complexas que precisam ser separadas
• Mais de 2000 linhas de código total
• Vários objetivos interconectados

Exemplos:

• Suite completa de análise financeira
• Sistema de gestão de projetos
• Plataforma de e-commerce analytics

Arquitetura 3: Hybrid (Simple + Components)

minha-skill-hibrida/           ← Simple skill principal
├── SKILL.md                   ← Orquestração principal
├── scripts/
│   ├── main.py               ← Lógica principal
│   └── components/           ← Componentes especializados
├── references/
└── assets/

Quando usar:

• Funcionalidade principal com sub-componentes
• Complexidade moderada
• Orquestração centralizada necessária

🔍 Decidindo Qual Arquitetura Usar

Use Simple Skill quando:

• ✅ Um objetivo principal claro
• ✅ Workflow linear e sequencial
• ✅ Menos de 3 subprocessos distintos
• ✅ Código < 1000 linhas
• ✅ Uma pessoa pode manter facilmente

Use Complex Skill Suite quando:

• ✅ Múltiplos objetivos relacionados
• ✅ Workflows independentes mas conectados
• ✅ Mais de 3 subprocessos distintos
• ✅ Código > 2000 linhas
• ✅ Equipe ou manutenção complexa

Use Hybrid quando:

• ✅ Orquestração central é crítica
• ✅ Componentes são opcionais/configuráveis
• ✅ Workflow principal com sub-tarefas especializadas

📋 Marketplace.json Explicado

O marketplace.json NÃO É uma skill. É um manifest organizacional:

{
  "name": "minha-suite",
  "plugins": [
    {
      "name": "componente-1",
      "source": "./componente-1/",
      "skills": ["./SKILL.md"]     ← Aponta para a skill real
    },
    {
      "name": "componente-2",
      "source": "./componente-2/",
      "skills": ["./SKILL.md"]     ← Aponta para outra skill
    }
  ]
}

Analogia: Pense no marketplace.json como um índice de livro - ele não é o conteúdo, apenas organiza e aponta para os capítulos (skills).

🚫 Terminologia a Evitar

Para evitar confusão:

❌ "Plugin" para se referir a skills individuais ✅ "Component Skill" ou "Skill Suite"

❌ "Multi-plugin architecture" ✅ "Multi-skill suite"

❌ "Plugin marketplace" ✅ "Skill marketplace" (quando hospeda skills)

✅ Termos Corretos

Situação	Termo Correto	Exemplo (com convenção -cskill)
Arquivo único com habilidade	Simple Skill	gerador-pdf-cskill/SKILL.md
Sub-habilidade especializada	Component Skill	data-extraction-cskill/SKILL.md
Conjunto de habilidades	Skill Suite	financial-analysis-suite-cskill/
Arquivo organizacional	Marketplace Plugin	marketplace.json
Sistema completo	Skill Ecosystem	Suite + Marketplace + Recursos

🏷️ Convenção de Nomenclatura: Sufixo "-cskill"

Propósito do Sufixo "-cskill"

• Identificação Clara: Indica imediatamente que é uma Claude Skill
• Origem Definida: Criada pelo Agent-Skill-Creator
• Padrão Consistente: Convenção profissional em toda documentação
• Evita Confusão: Distingue de skills manuais ou outras fontes
• Organização Facilitada: Fácil identificação e agrupamento

Regras de Nomenclatura

1. Formato Padrão

{descrição-descritiva}-cskill/

2. Simple Skills

pdf-text-extractor-cskill/
csv-data-cleaner-cskill/
weekly-report-generator-cskill/
image-converter-cskill/

3. Complex Skill Suites

financial-analysis-suite-cskill/
e-commerce-automation-cskill/
research-workflow-cskill/
business-intelligence-cskill/

4. Component Skills (dentro de suites)

data-acquisition-cskill/
technical-analysis-cskill/
reporting-generator-cskill/
user-interface-cskill/

5. Formatação

• ✅ Sempre minúsculas
• ✅ Usar hífens para separar palavras
• ✅ Descritivo e claro
• ✅ Terminar com "-cskill"
• ❌ Sem underscores ou espaços
• ❌ Sem caracteres especiais (exceto hífens)

Exemplos de Transformação

Requisito do Usuário	Nome Gerado
"Extract text from PDF documents"	pdf-text-extractor-cskill/
"Clean CSV data automatically"	csv-data-cleaner-cskill/
"Complete financial analysis platform"	financial-analysis-suite-cskill/
"Generate weekly status reports"	weekly-report-generator-cskill/
"Automate e-commerce workflows"	e-commerce-automation-cskill/

🎯 Regra de Ouro

Se tem SKILL.md → É uma Skill (simples ou component) Se tem marketplace.json → É um marketplace plugin (organização)

📖 Exemplos do Mundo Real

Simple Skill: Proposta Comercial

proposta-comercial/
├── SKILL.md              ← "Criar propostas comerciais"
├── references/
│   └── template.md
└── assets/
    └── logo.png

Complex Skill Suite: Análise Financeira

financial-analysis-suite/
├── .claude-plugin/marketplace.json
├── data-acquisition/SKILL.md    ← "Baixar dados de mercado"
├── technical-analysis/SKILL.md  ← "Analisar indicadores técnicos"
├── portfolio-analysis/SKILL.md  ← "Otimizar portfólio"
└── reporting/SKILL.md          ← "Gerar relatórios"

Ambas são Skills Claude Code legítimas - apenas com diferentes níveis de complexidade.

---

🔄 Como Este Documento Ajuda

1. Terminologia clara - Todos usam os mesmos termos
2. Decisões informadas - Saber quando usar cada arquitetura
3. Comunicação efetiva - Sem ambiguidade entre skills e plugins
4. Documentação consistente - Padrão em toda documentação do agent-skill-creator

Resultado: Menos confusão, mais clareza, melhor desenvolvimento!