admin-valentin/agent-skill-creator
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: Translate documentation from Portuguese to English

Browse source 
Translated three core documentation files to American English for
improved international accessibility and consistency:

- docs/CLAUDE_SKILLS_ARCHITECTURE.md
- docs/NAMING_CONVENTIONS.md
- docs/INTERNAL_FLOW_ANALYSIS.md

All technical content, code examples, and document structure preserved.
Verified no Portuguese text remains in translated files.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Francy Lisboa 2025-10-24 15:41:31 -03:00
parent 191c3a68fd
commit a85c6e7468
3 changed files with 440 additions and 440 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

276
docs/CLAUDE_SKILLS_ARCHITECTURE.md
View file

@ -1,192 +1,192 @@
# Claude Skills Architecture: Guia Completo # Claude Skills Architecture: Complete Guide
## 🎯 **Propósito** ## 🎯 **Purpose**
Este documento elimina a confusão entre diferentes tipos de Skills Claude Code e estabelece terminologia consistente. This document eliminates confusion between different types of Claude Code Skills and establishes consistent terminology.
## 📚 **Terminologia Padrão** ## 📚 **Standard Terminology**
### **Skill** ### **Skill**
Uma **Skill** é uma capacidade completa do Claude Code implementada como uma pasta contendo: A **Skill** is a complete Claude Code capability implemented as a folder containing:
- Arquivo `SKILL.md` (obrigatório) - `SKILL.md` file (required)
- Recursos opcionais (scripts/, references/, assets/) - Optional resources (scripts/, references/, assets/)
- Funcionalidade específica para um domínio - Domain-specific functionality
**Exemplo:** `minha-skill/` contendo análise de dados financeiros **Example:** `my-skill/` containing financial data analysis
### **Component Skill** ### **Component Skill**
Uma **Component Skill** é uma sub-skill especializada que é parte de uma Skill Suite maior. A **Component Skill** is a specialized sub-skill that is part of a larger Skill Suite.
- Tem seu próprio `SKILL.md` - Has its own `SKILL.md`
- Foca em uma funcionalidade específica - Focuses on specific functionality
- Compartilha recursos com outras component skills - Shares resources with other component skills
**Exemplo:** `data-acquisition/SKILL.md` dentro de uma suite de análise financeira **Example:** `data-acquisition/SKILL.md` within a financial analysis suite
### **Skill Suite** ### **Skill Suite**
Uma **Skill Suite** é uma coleção integrada de Component Skills que trabalham juntas. A **Skill Suite** is an integrated collection of Component Skills that work together.
- Tem `marketplace.json` como manifest - Has `marketplace.json` as manifest
- Múltiplas component skills especializadas - Multiple specialized component skills
- Recursos compartilhados entre skills - Shared resources between skills
**Exemplo:** Suite completa de análise financeira com skills para data acquisition, analysis, e reporting. **Example:** Complete financial analysis suite with skills for data acquisition, analysis, and reporting.
### **Marketplace Plugin** ### **Marketplace Plugin**
Um **Marketplace Plugin** é o arquivo `marketplace.json` que hospeda e organiza uma ou mais Skills. A **Marketplace Plugin** is the `marketplace.json` file that hosts and organizes one or more Skills.
- **NÃO é uma skill** - é um manifest organizacional - **NOT a skill** - it's an organizational manifest
- Define como as skills devem ser carregadas - Defines how skills should be loaded
- Pode hospedar skills simples ou suites complexas - Can host simple skills or complex suites
## 🏗️ **Tipos de Arquitetura** ## 🏗️ **Architecture Types**
### **Arquitetura 1: Simple Skill** ### **Architecture 1: Simple Skill**
``` ```
minha-skill/ my-skill/
├── SKILL.md ← Single skill file ├── SKILL.md ← Single skill file
├── scripts/ ← Optional supporting code ├── scripts/ ← Optional supporting code
├── references/ ← Optional documentation ├── references/ ← Optional documentation
└── assets/ ← Optional templates/resources └── assets/ ← Optional templates/resources
``` ```
**Quando usar:** **When to use:**
- Funcionalidade focada e única - Focused, single functionality
- Workflow simples - Simple workflow
- Menos de 1000 linhas de código total - Less than 1000 lines of total code
- Um objetivo principal - One main objective
**Exemplos:** **Examples:**
- Gerador de propostas comerciais - Business proposal generator
- Extrator de dados de PDFs - PDF data extractor
- Calculadora de ROI - ROI calculator
### **Arquitetura 2: Complex Skill Suite** ### **Architecture 2: Complex Skill Suite**
``` ```
minha-suite/ ← Skill Suite completa my-suite/ ← Complete Skill Suite
├── .claude-plugin/ ├── .claude-plugin/
│ └── marketplace.json ← Manifest das skills │ └── marketplace.json ← Skills manifest
├── componente-1/ ← Component Skill 1 ├── component-1/ ← Component Skill 1
│ ├── SKILL.md │ ├── SKILL.md
│ └── scripts/ │ └── scripts/
├── componente-2/ ← Component Skill 2 ├── component-2/ ← Component Skill 2
│ ├── SKILL.md │ ├── SKILL.md
│ └── references/ │ └── references/
├── componente-3/ ← Component Skill 3 ├── component-3/ ← Component Skill 3
│ ├── SKILL.md │ ├── SKILL.md
│ └── assets/ │ └── assets/
└── shared/ ← Recursos compartilhados └── shared/ ← Shared resources
├── utils/ ├── utils/
├── config/ ├── config/
└── templates/ └── templates/
``` ```
**Quando usar:** **When to use:**
- Múltiplos workflows relacionados - Multiple related workflows
- Funcionalidades complexas que precisam ser separadas - Complex functionalities that need separation
- Mais de 2000 linhas de código total - More than 2000 lines of total code
- Vários objetivos interconectados - Multiple interconnected objectives
**Exemplos:** **Examples:**
- Suite completa de análise financeira - Complete financial analysis suite
- Sistema de gestão de projetos - Project management system
- Plataforma de e-commerce analytics - E-commerce analytics platform
### **Arquitetura 3: Hybrid (Simple + Components)** ### **Architecture 3: Hybrid (Simple + Components)**
``` ```
minha-skill-hibrida/ ← Simple skill principal my-hybrid-skill/ ← Main simple skill
├── SKILL.md ← Orquestração principal ├── SKILL.md ← Main orchestration
├── scripts/ ├── scripts/
│ ├── main.py ← Lógica principal │ ├── main.py ← Main logic
│ └── components/ ← Componentes especializados │ └── components/ ← Specialized components
├── references/ ├── references/
└── assets/ └── assets/
``` ```
**Quando usar:** **When to use:**
- Funcionalidade principal com sub-componentes - Main functionality with sub-components
- Complexidade moderada - Moderate complexity
- Orquestração centralizada necessária - Centralized orchestration required
## 🔍 **Decidindo Qual Arquitetura Usar** ## 🔍 **Deciding Which Architecture to Use**
### **Use Simple Skill quando:** ### **Use Simple Skill when:**
- ✅ Um objetivo principal claro - ✅ Clear main objective
- ✅ Workflow linear e sequencial - ✅ Linear and sequential workflow
- ✅ Menos de 3 subprocessos distintos - ✅ Less than 3 distinct subprocesses
- ✅ Código < 1000 linhas - ✅ Code < 1000 lines
- ✅ Uma pessoa pode manter facilmente - ✅ One person can easily maintain
### **Use Complex Skill Suite quando:** ### **Use Complex Skill Suite when:**
- ✅ Múltiplos objetivos relacionados - ✅ Multiple related objectives
- ✅ Workflows independentes mas conectados - ✅ Independent but connected workflows
- ✅ Mais de 3 subprocessos distintos - ✅ More than 3 distinct subprocesses
- ✅ Código > 2000 linhas - ✅ Code > 2000 lines
- ✅ Equipe ou manutenção complexa - ✅ Team or complex maintenance
### **Use Hybrid quando:** ### **Use Hybrid when:**
- ✅ Orquestração central é crítica - ✅ Central orchestration is critical
- ✅ Componentes são opcionais/configuráveis - ✅ Components are optional/configurable
- ✅ Workflow principal com sub-tarefas especializadas - ✅ Main workflow with specialized sub-tasks
## 📋 **Marketplace.json Explicado** ## 📋 **Marketplace.json Explained**
O `marketplace.json` **NÃO É** uma skill. É um **manifest organizacional**: The `marketplace.json` **IS NOT** a skill. It's an **organizational manifest**:
```json ```json
{ {
"name": "minha-suite", "name": "my-suite",
"plugins": [ "plugins": [
{ {
"name": "componente-1", "name": "component-1",
"source": "./componente-1/", "source": "./component-1/",
"skills": ["./SKILL.md"] ← Aponta para a skill real "skills": ["./SKILL.md"] ← Points to the actual skill
}, },
{ {
"name": "componente-2", "name": "component-2",
"source": "./componente-2/", "source": "./component-2/",
"skills": ["./SKILL.md"] ← Aponta para outra skill "skills": ["./SKILL.md"] ← Points to another 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). **Analogy:** Think of `marketplace.json` as a **book index** - it's not the content, just organizes and points to the chapters (skills).
## 🚫 **Terminologia a Evitar** ## 🚫 **Terminology to Avoid**
Para evitar confusão: To avoid confusion:
❌ **"Plugin"** para se referir a skills individuais ❌ **"Plugin"** to refer to individual skills
✅ **"Component Skill"** ou **"Skill Suite"** ✅ **"Component Skill"** or **"Skill Suite"**
❌ **"Multi-plugin architecture"** ❌ **"Multi-plugin architecture"**
✅ **"Multi-skill suite"** ✅ **"Multi-skill suite"**
❌ **"Plugin marketplace"** ❌ **"Plugin marketplace"**
✅ **"Skill marketplace"** (quando hospeda skills) ✅ **"Skill marketplace"** (when hosting skills)
## ✅ **Termos Corretos** ## ✅ **Correct Terms**
| Situação | Termo Correto | Exemplo (com convenção -cskill) | | Situation | Correct Term | Example (with -cskill convention) |
|----------|---------------|--------------------------------| |----------|---------------|--------------------------------|
| Arquivo único com habilidade | **Simple Skill** | `gerador-pdf-cskill/SKILL.md` | | Single file with capability | **Simple Skill** | `pdf-generator-cskill/SKILL.md` |
| Sub-habilidade especializada | **Component Skill** | `data-extraction-cskill/SKILL.md` | | Specialized sub-capability | **Component Skill** | `data-extraction-cskill/SKILL.md` |
| Conjunto de habilidades | **Skill Suite** | `financial-analysis-suite-cskill/` | | Set of capabilities | **Skill Suite** | `financial-analysis-suite-cskill/` |
| Arquivo organizacional | **Marketplace Plugin** | `marketplace.json` | | Organizational file | **Marketplace Plugin** | `marketplace.json` |
| Sistema completo | **Skill Ecosystem** | Suite + Marketplace + Recursos | | Complete system | **Skill Ecosystem** | Suite + Marketplace + Resources |
## 🏷️ **Convenção de Nomenclatura: Sufixo "-cskill"** ## 🏷️ **Naming Convention: The "-cskill" Suffix**
### **Propósito do Sufixo "-cskill"** ### **Purpose of the "-cskill" Suffix**
- **Identificação Clara**: Indica imediatamente que é uma Claude Skill - **Clear Identification**: Immediately indicates it's a Claude Skill
- **Origem Definida**: Criada pelo Agent-Skill-Creator - **Defined Origin**: Created by Agent-Skill-Creator
- **Padrão Consistente**: Convenção profissional em toda documentação - **Consistent Standard**: Professional convention across all documentation
- **Evita Confusão**: Distingue de skills manuais ou outras fontes - **Avoids Confusion**: Distinguishes from manual skills or other sources
- **Organização Facilitada**: Fácil identificação e agrupamento - **Easy Organization**: Simple identification and grouping
### **Regras de Nomenclatura** ### **Naming Rules**
**1. Formato Padrão** **1. Standard Format**
``` ```
{descrição-descritiva}-cskill/ {descriptive-description}-cskill/
``` ```
**2. Simple Skills** **2. Simple Skills**
@ -205,7 +205,7 @@ research-workflow-cskill/
business-intelligence-cskill/ business-intelligence-cskill/
``` ```
**4. Component Skills (dentro de suites)** **4. Component Skills (within suites)**
``` ```
data-acquisition-cskill/ data-acquisition-cskill/
technical-analysis-cskill/ technical-analysis-cskill/
@ -213,17 +213,17 @@ reporting-generator-cskill/
user-interface-cskill/ user-interface-cskill/
``` ```
**5. Formatação** **5. Formatting**
- ✅ Sempre minúsculas - ✅ Always lowercase
- ✅ Usar hífens para separar palavras - ✅ Use hyphens to separate words
- ✅ Descritivo e claro - ✅ Descriptive and clear
- ✅ Terminar com "-cskill" - ✅ End with "-cskill"
- ❌ Sem underscores ou espaços - ❌ No underscores or spaces
- ❌ Sem caracteres especiais (exceto hífens) - ❌ No special characters (except hyphens)
### **Exemplos de Transformação** ### **Transformation Examples**
| Requisito do Usuário | Nome Gerado | | User Requirement | Generated Name |
|---------------------|-------------| |---------------------|-------------|
| "Extract text from PDF documents" | `pdf-text-extractor-cskill/` | | "Extract text from PDF documents" | `pdf-text-extractor-cskill/` |
| "Clean CSV data automatically" | `csv-data-cleaner-cskill/` | | "Clean CSV data automatically" | `csv-data-cleaner-cskill/` |
@ -231,42 +231,42 @@ user-interface-cskill/
| "Generate weekly status reports" | `weekly-report-generator-cskill/` | | "Generate weekly status reports" | `weekly-report-generator-cskill/` |
| "Automate e-commerce workflows" | `e-commerce-automation-cskill/` | | "Automate e-commerce workflows" | `e-commerce-automation-cskill/` |
## 🎯 **Regra de Ouro** ## 🎯 **Golden Rule**
**Se tem `SKILL.md` → É uma Skill (simples ou component) **If it has `SKILL.md` → It's a Skill (simple or component)
Se tem `marketplace.json` → É um marketplace plugin (organização)** If it has `marketplace.json` → It's a marketplace plugin (organization)**
## 📖 **Exemplos do Mundo Real** ## 📖 **Real-World Examples**
### **Simple Skill: Proposta Comercial** ### **Simple Skill: Business Proposal**
``` ```
proposta-comercial/ business-proposal/
├── SKILL.md ← "Criar propostas comerciais" ├── SKILL.md ← "Create business proposals"
├── references/ ├── references/
│ └── template.md │ └── template.md
└── assets/ └── assets/
└── logo.png └── logo.png
``` ```
### **Complex Skill Suite: Análise Financeira** ### **Complex Skill Suite: Financial Analysis**
``` ```
financial-analysis-suite/ financial-analysis-suite/
├── .claude-plugin/marketplace.json ├── .claude-plugin/marketplace.json
├── data-acquisition/SKILL.md ← "Baixar dados de mercado" ├── data-acquisition/SKILL.md ← "Download market data"
├── technical-analysis/SKILL.md ← "Analisar indicadores técnicos" ├── technical-analysis/SKILL.md ← "Analyze technical indicators"
├── portfolio-analysis/SKILL.md ← "Otimizar portfólio" ├── portfolio-analysis/SKILL.md ← "Optimize portfolio"
└── reporting/SKILL.md ← "Gerar relatórios" └── reporting/SKILL.md ← "Generate reports"
``` ```
Ambas são **Skills Claude Code legítimas** - apenas com diferentes níveis de complexidade. Both are **legitimate Claude Code Skills** - just with different complexity levels.
--- ---
## 🔄 **Como Este Documento Ajuda** ## 🔄 **How This Document Helps**
1. **Terminologia clara** - Todos usam os mesmos termos 1. **Clear terminology** - Everyone uses the same terms
2. **Decisões informadas** - Saber quando usar cada arquitetura 2. **Informed decisions** - Know when to use each architecture
3. **Comunicação efetiva** - Sem ambiguidade entre skills e plugins 3. **Effective communication** - No ambiguity between skills and plugins
4. **Documentação consistente** - Padrão em toda documentação do agent-skill-creator 4. **Consistent documentation** - Standard across all agent-skill-creator documentation
**Resultado:** Menos confusão, mais clareza, melhor desenvolvimento! **Result:** Less confusion, more clarity, better development!

286
docs/INTERNAL_FLOW_ANALYSIS.md
View file

@ -1,49 +1,49 @@
# Fluxo Interno do Agent-Skill-Creator: O Que Acontece "Por Baixo dos Panos" # Agent-Skill-Creator Internal Flow: What Happens "Under the Hood"
## 🎯 **Cenário Exemplo** ## 🎯 **Example Scenario**
**Comando do Usuário:** **User Command:**
``` ```
"gostaria de automatizar o que esta sendo explicado e descrito nesse artigo [conteúdo do artigo sobre análise de dados financeiros]" "I'd like to automate what is being explained and described in this article [financial data analysis article content]"
``` ```
## 🚀 **Fluxo Completo Detalhado** ## 🚀 **Complete Detailed Flow**
### **FASE 0: Detecção e Ativação Automática** ### **PHASE 0: Detection and Automatic Activation**
#### **0.1 Análise da Intenção do Usuário** #### **0.1 User Intent Analysis**
O Claude Code analisa o comando e detecta padrões de ativação: Claude Code analyzes the command and detects activation patterns:
``` ```
PADRÕES DETECTADOS: DETECTED PATTERNS:
✅ "automatizar" → Ativação de workflow automation ✅ "automate" → Workflow automation activation
✅ "o que esta sendo explicado" → Processamento de conteúdo externo ✅ "what is being explained" → External content processing
✅ "nesse artigo" → Transcrito/intent processing ✅ "in this article" → Transcribed/intent processing
✅ Comando completo → Ativa Agent-Skill-Creator ✅ Complete command → Activates Agent-Skill-Creator
``` ```
#### **0.2 Carregamento da Meta-Skill** #### **0.2 Meta-Skill Loading**
```python ```python
# Sistema interno Claude Code # Claude Code internal system
if matches_pattern(user_input, SKILL_ACTIVATION_PATTERNS): if matches_pattern(user_input, SKILL_ACTIVATION_PATTERNS):
load_skill("agent-creator-en-v2") load_skill("agent-creator-en-v2")
activate_5_phase_process(user_input) activate_5_phase_process(user_input)
``` ```
**O que acontece:** **What happens:**
- O `SKILL.md` do agent-creator é carregado na memória - The agent-creator's `SKILL.md` is loaded into memory
- O contexto da skill é preparado - The skill context is prepared
- As 5 fases são inicializadas - The 5 phases are initialized
--- ---
### **FASE 1: DISCOVERY - Pesquisa e Análise** ### **PHASE 1: DISCOVERY - Research and Analysis**
#### **1.1 Processamento do Conteúdo do Artigo** #### **1.1 Article Content Processing**
```python ```python
# Simulação do processamento interno # Internal processing simulation
def analyze_article_content(article_text): def analyze_article_content(article_text):
# Extração de informações estruturadas # Structured information extraction
workflows = extract_workflows(article_text) workflows = extract_workflows(article_text)
tools_mentioned = identify_tools(article_text) tools_mentioned = identify_tools(article_text)
data_sources = find_data_sources(article_text) data_sources = find_data_sources(article_text)
@ -57,56 +57,56 @@ def analyze_article_content(article_text):
} }
``` ```
**Exemplo Prático - Artigo sobre Análise Financeira:** **Practical Example - Financial Analysis Article:**
``` ```
ARTIGO CONTEÚDO ANALISADO: ANALYZED ARTICLE CONTENT:
├─ Workflows Identificados: ├─ Identified Workflows:
│ ├─ "Baixar dados da bolsa" │ ├─ "Download stock market data"
│ ├─ "Calcular indicadores técnicos" │ ├─ "Calculate technical indicators"
│ ├─ "Gerar gráficos de análise" │ ├─ "Generate analysis charts"
│ └─ "Criar relatório semanal" │ └─ "Create weekly report"
├─ Ferramentas Mencionadas: ├─ Mentioned Tools:
│ ├─ "Biblioteca pandas" │ ├─ "pandas library"
│ ├─ "Alpha Vantage API" │ ├─ "Alpha Vantage API"
│ ├─ "Matplotlib para gráficos" │ ├─ "Matplotlib for charts"
│ └─ "Excel para relatórios" │ └─ "Excel for reports"
└─ Fontes de Dados: └─ Data Sources:
├─ "Yahoo Finance API" ├─ "Yahoo Finance API"
├─ "Arquivos CSV locais" ├─ "Local CSV files"
└─ "Banco de dados SQL" └─ "SQL database"
``` ```
#### **1.2 Pesquisa de APIs e Ferramentas** #### **1.2 API and Tools Research**
```bash ```bash
# WebSearch automático realizado pelo Claude # Automatic WebSearch performed by Claude
WebSearch: "Best Python libraries for financial data analysis 2025" WebSearch: "Best Python libraries for financial data analysis 2025"
WebSearch: "Alpha Vantage API documentation Python integration" WebSearch: "Alpha Vantage API documentation Python integration"
WebSearch: "Financial reporting automation tools Python" WebSearch: "Financial reporting automation tools Python"
``` ```
#### **1.3 Complementação com AgentDB (se disponível)** #### **1.3 AgentDB Enhancement (if available)**
```python ```python
# AgentDB integration transparente # Transparent AgentDB integration
agentdb_insights = query_agentdb_for_patterns("financial_analysis") agentdb_insights = query_agentdb_for_patterns("financial_analysis")
if agentdb_insights.success_rate > 0.8: if agentdb_insights.success_rate > 0.8:
apply_learned_patterns(agentdb_insights.patterns) apply_learned_patterns(agentdb_insights.patterns)
``` ```
#### **1.4 Decisão de Stack Tecnológico** #### **1.4 Technology Stack Decision**
``` ```
DECISÃO TÉCNICA: TECHNICAL DECISION:
✅ Python como linguagem principal ✅ Python as primary language
✅ pandas para manipulação de dados ✅ pandas for data manipulation
✅ Alpha Vantage para dados de mercado ✅ Alpha Vantage for market data
✅ Matplotlib/Seaborn para visualizações ✅ Matplotlib/Seaborn for visualizations
✅ ReportLab para geração de PDFs ✅ ReportLab for PDF generation
``` ```
--- ---
### **FASE 2: DESIGN - Especificação de Funcionalidades** ### **PHASE 2: DESIGN - Functionality Specification**
#### **2.1 Análise de Casos de Uso** #### **2.1 Use Case Analysis**
```python ```python
def define_use_cases(workflows_identified): def define_use_cases(workflows_identified):
use_cases = [] use_cases = []
@ -123,47 +123,47 @@ def define_use_cases(workflows_identified):
return use_cases return use_cases
``` ```
**Casos de Uso Definidos:** **Defined Use Cases:**
``` ```
USE CASE 1: Data Acquisition USE CASE 1: Data Acquisition
- Description: Baixar dados históricos de ações - Description: Download historical stock data
- Input: Lista de tickers, período - Input: List of tickers, period
- Output: DataFrame com dados OHLCV - Output: DataFrame with OHLCV data
- Frequency: Diário - Frequency: Daily
USE CASE 2: Technical Analysis USE CASE 2: Technical Analysis
- Description: Calcular indicadores técnicos - Description: Calculate technical indicators
- Input: DataFrame de preços - Input: Price DataFrame
- Output: DataFrame com indicadores - Output: DataFrame with indicators
- Frequency: Sob demanda - Frequency: On demand
USE CASE 3: Report Generation USE CASE 3: Report Generation
- Description: Criar relatório PDF - Description: Create PDF report
- Input: Resultados da análise - Input: Analysis results
- Output: Relatório formatado - Output: Formatted report
- Frequency: Semanal - Frequency: Weekly
``` ```
#### **2.2 Definição de Metodologias** #### **2.2 Methodology Definition**
```python ```python
def specify_methodologies(use_cases): def specify_methodologies(use_cases):
methodologies = { methodologies = {
'data_validation': 'Validação de qualidade de dados', 'data_validation': 'Data quality validation',
'error_handling': 'Tratamento de erros robusto', 'error_handling': 'Robust error handling',
'caching_strategy': 'Cache de dados para performance', 'caching_strategy': 'Data caching for performance',
'logging': 'Log detalhado para debugging', 'logging': 'Detailed logging for debugging',
'configuration': 'Configuração flexível via JSON' 'configuration': 'Flexible configuration via JSON'
} }
return methodologies return methodologies
``` ```
--- ---
### **FASE 3: ARCHITECTURE - Decisão Estrutural** ### **PHASE 3: ARCHITECTURE - Structural Decision**
#### **3.1 Análise de Complexidade (DECISION_LOGIC.md aplicado)** #### **3.1 Complexity Analysis (DECISION_LOGIC.md applied)**
```python ```python
# Avaliação automática baseada no conteúdo do artigo # Automatic evaluation based on article content
complexity_score = calculate_complexity({ complexity_score = calculate_complexity({
'number_of_workflows': 4, # Data + Analysis + Reports + Alerts 'number_of_workflows': 4, # Data + Analysis + Reports + Alerts
'workflow_complexity': 'medium', # API calls + calculations + formatting 'workflow_complexity': 'medium', # API calls + calculations + formatting
@ -172,27 +172,27 @@ complexity_score = calculate_complexity({
'domain_expertise': ['finance', 'data_science', 'reporting'] 'domain_expertise': ['finance', 'data_science', 'reporting']
}) })
# Decisão de arquitetura # Architecture decision
if complexity_score > SIMPLE_SKILL_THRESHOLD: if complexity_score > SIMPLE_SKILL_THRESHOLD:
architecture = "complex_skill_suite" architecture = "complex_skill_suite"
else: else:
architecture = "simple_skill" architecture = "simple_skill"
``` ```
**Neste exemplo:** **In this example:**
``` ```
RESULTADO DA ANÁLISE: ANALYSIS RESULT:
✅ Múltiplos workflows distintos (4) ✅ Multiple distinct workflows (4)
✅ Complexidade média-alta ✅ Medium-high complexity
✅ Múltiplas fontes de dados ✅ Multiple data sources
✅ Estimativa > 2000 linhas de código ✅ Estimate > 2000 lines of code
✅ Múltiplos domínios de expertise ✅ Multiple domains of expertise
DECISÃO: Complex Skill Suite DECISION: Complex Skill Suite
NOME GERADO: financial-analysis-suite-cskill GENERATED NAME: financial-analysis-suite-cskill
``` ```
#### **3.2 Definição da Estrutura de Componentes** #### **3.2 Component Structure Definition**
```python ```python
def design_component_skills(complexity_analysis): def design_component_skills(complexity_analysis):
if complexity_analysis.architecture == "complex_skill_suite": if complexity_analysis.architecture == "complex_skill_suite":
@ -205,7 +205,7 @@ def design_component_skills(complexity_analysis):
return components return components
``` ```
#### **3.3 Planejamento de Performance e Cache** #### **3.3 Performance and Cache Planning**
```python ```python
performance_plan = { performance_plan = {
'data_cache': 'Cache market data for 1 day', 'data_cache': 'Cache market data for 1 day',
@ -217,35 +217,35 @@ performance_plan = {
--- ---
### **FASE 4: DETECTION - Palavras-Chave e Ativação** ### **PHASE 4: DETECTION - Keywords and Activation**
#### **4.1 Análise de Palavras-Chave** #### **4.1 Keyword Analysis**
```python ```python
def determine_activation_keywords(workflows, tools): def determine_activation_keywords(workflows, tools):
keywords = { keywords = {
'primary': [ 'primary': [
'análise financeira', 'financial analysis',
'dados de mercado', 'market data',
'indicadores técnicos', 'technical indicators',
'relatórios de investimento' 'investment reports'
], ],
'secondary': [ 'secondary': [
'automatizar análise', 'automate analysis',
'gerar gráficos', 'generate charts',
'calcular retornos', 'calculate returns',
'extração de dados' 'data extraction'
], ],
'domains': [ 'domains': [
'finanças', 'finance',
'investimentos', 'investments',
'análise quantitativa', 'quantitative analysis',
'mercado de ações' 'stock market'
] ]
} }
return keywords return keywords
``` ```
#### **4.2 Criação de Descrições Precisas** #### **4.2 Precise Description Creation**
```python ```python
def create_skill_descriptions(components): def create_skill_descriptions(components):
descriptions = {} descriptions = {}
@ -263,11 +263,11 @@ def create_skill_descriptions(components):
--- ---
### **FASE 5: IMPLEMENTATION - Criação do Código** ### **PHASE 5: IMPLEMENTATION - Code Creation**
#### **5.1 Criação da Estrutura de Diretórios** #### **5.1 Directory Structure Creation**
```bash ```bash
# Criado automaticamente pelo sistema # Automatically created by the system
mkdir -p financial-analysis-suite/.claude-plugin mkdir -p financial-analysis-suite/.claude-plugin
mkdir -p financial-analysis-suite/data-acquisition/{scripts,references,assets} mkdir -p financial-analysis-suite/data-acquisition/{scripts,references,assets}
mkdir -p financial-analysis-suite/technical-analysis/{scripts,references,assets} mkdir -p financial-analysis-suite/technical-analysis/{scripts,references,assets}
@ -276,7 +276,7 @@ mkdir -p financial-analysis-suite/reporting/{scripts,references,assets}
mkdir -p financial-analysis-suite/shared/{utils,config,templates} mkdir -p financial-analysis-suite/shared/{utils,config,templates}
``` ```
#### **5.2 Geração do marketplace.json** #### **5.2 marketplace.json Generation**
```json ```json
{ {
"name": "financial-analysis-suite", "name": "financial-analysis-suite",
@ -295,8 +295,8 @@ mkdir -p financial-analysis-suite/shared/{utils,config,templates}
} }
``` ```
#### **5.3 Criação dos SKILL.md Files** #### **5.3 SKILL.md Files Creation**
Para cada componente, o sistema gera: For each component, the system generates:
```markdown ```markdown
--- ---
@ -316,7 +316,7 @@ Use this skill when you need to:
- Store data in standardized format - Store data in standardized format
``` ```
#### **5.4 Geração dos Scripts Python** #### **5.4 Python Scripts Generation**
```python ```python
# data-acquisition/scripts/fetch_data.py # data-acquisition/scripts/fetch_data.py
import pandas as pd import pandas as pd
@ -352,7 +352,7 @@ class FinancialDataFetcher:
return validation_results return validation_results
``` ```
#### **5.5 Criação de Arquivos de Configuração** #### **5.5 Configuration Files Creation**
```json ```json
// shared/config/data_sources.json // shared/config/data_sources.json
{ {
@ -379,7 +379,7 @@ class FinancialDataFetcher:
} }
``` ```
#### **5.6 Geração de Documentação e Referências** #### **5.6 Documentation and References Generation**
```markdown ```markdown
# data-acquisition/references/api_documentation.md # data-acquisition/references/api_documentation.md
@ -396,7 +396,7 @@ class FinancialDataFetcher:
- **Authentication**: None required - **Authentication**: None required
``` ```
#### **5.7 Criação do README Principal** #### **5.7 Main README Creation**
```markdown ```markdown
# Financial Analysis Suite # Financial Analysis Suite
@ -415,7 +415,7 @@ Complete automated financial analysis system that processes market data, perform
- **Reporting**: Professional PDF report generation - **Reporting**: Professional PDF report generation
``` ```
#### **5.8 Teste de Instalação Automático** #### **5.8 Automatic Installation Test**
```python ```python
# scripts/test_installation.py # scripts/test_installation.py
def test_suite_installation(): def test_suite_installation():
@ -462,29 +462,29 @@ if __name__ == "__main__":
--- ---
## 🎯 **Resultado Final - O que o Usuário Recebe** ## 🎯 **Final Result - What the User Receives**
Após aproximadamente **45-90 minutos** de processamento autônomo, o usuário terá: After approximately **45-90 minutes** of autonomous processing, the user will have:
``` ```
financial-analysis-suite-cskill/ financial-analysis-suite-cskill/
├── .claude-plugin/ ├── .claude-plugin/
│ └── marketplace.json ← Manifesto da suite │ └── marketplace.json ← Suite manifest
├── data-acquisition-cskill/ ├── data-acquisition-cskill/
│ ├── SKILL.md ← Component skill 1 │ ├── SKILL.md ← Component skill 1
│ ├── scripts/ │ ├── scripts/
│ │ ├── fetch_data.py ← Código funcional │ │ ├── fetch_data.py ← Functional code
│ │ ├── validate_data.py ← Validação │ │ ├── validate_data.py ← Validation
│ │ └── cache_manager.py ← Cache │ │ └── cache_manager.py ← Cache
│ ├── references/ │ ├── references/
│ │ └── api_documentation.md ← Documentação │ │ └── api_documentation.md ← Documentation
│ └── assets/ │ └── assets/
├── technical-analysis-cskill/ ├── technical-analysis-cskill/
│ ├── SKILL.md ← Component skill 2 │ ├── SKILL.md ← Component skill 2
│ ├── scripts/ │ ├── scripts/
│ │ ├── indicators.py ← Cálculos técnicos │ │ ├── indicators.py ← Technical calculations
│ │ ├── signals.py ← Geração de sinais │ │ ├── signals.py ← Signal generation
│ │ └── backtester.py ← Testes históricos │ │ └── backtester.py ← Historical tests
│ └── references/ │ └── references/
├── visualization-cskill/ ├── visualization-cskill/
│ ├── SKILL.md ← Component skill 3 │ ├── SKILL.md ← Component skill 3
@ -496,23 +496,23 @@ financial-analysis-suite-cskill/
│ ├── utils/ │ ├── utils/
│ ├── config/ │ ├── config/
│ └── templates/ │ └── templates/
├── requirements.txt ← Dependências Python ├── requirements.txt ← Python dependencies
├── README.md ← Guia do usuário ├── README.md ← User guide
├── DECISIONS.md ← Explicação das decisões ├── DECISIONS.md ← Decision explanations
└── test_installation.py ← Teste automático └── test_installation.py ← Automatic test
``` ```
**Nota:** Todos os componentes usam a convenção "-cskill" para identificar que foram criados pelo Agent-Skill-Creator. **Note:** All components use the "-cskill" convention to identify that they were created by Agent-Skill-Creator.
## 🚀 **Como Usar a Skill Criada** ## 🚀 **How to Use the Created Skill**
**Imediatamente após a criação:** **Immediately after creation:**
```bash ```bash
# Instalar a suite # Install the suite
cd financial-analysis-suite cd financial-analysis-suite
/plugin marketplace add ./ /plugin marketplace add ./
# Usar a das componentes # Use the components
"Analyze technical indicators for AAPL using the data acquisition and technical analysis components" "Analyze technical indicators for AAPL using the data acquisition and technical analysis components"
"Generate a comprehensive financial report for portfolio [MSFT, GOOGL, TSLA]" "Generate a comprehensive financial report for portfolio [MSFT, GOOGL, TSLA]"
@ -522,24 +522,24 @@ cd financial-analysis-suite
--- ---
## 🧠 **Inteligência por Trás do Processo** ## 🧠 **Intelligence Behind the Process**
### **O que Torna Isso Possível:** ### **What Makes This Possible:**
1. **Compreensão Semântica**: O Claude entende o conteúdo do artigo, não apenas palavras-chave 1. **Semantic Understanding**: Claude understands the article's content, not just keywords
2. **Extração Estruturada**: Identifica workflows, ferramentas, e padrões 2. **Structured Extraction**: Identifies workflows, tools, and patterns
3. **Decisão Autônoma**: Escolhe a arquitetura adequada sem intervenção humana 3. **Autonomous Decision-Making**: Chooses the appropriate architecture without human intervention
4. **Geração Funcional**: Cria código que realmente funciona, não templates 4. **Functional Generation**: Creates code that actually works, not templates
5. **Aprendizado Contínuo**: Com AgentDB, melhora com cada criação 5. **Continuous Learning**: With AgentDB, improves with each creation
### **Diferencial em Relação a Abordagens Simples:** ### **Differential Compared to Simple Approaches:**
| Abordagem Simples | Agent-Skill-Creator | | Simple Approach | Agent-Skill-Creator |
|------------------|---------------------| |------------------|---------------------|
| Gera templates | Cria código funcional | | Generates templates | Creates functional code |
| Requer programação | Totalmente autônomo | | Requires programming | Fully autonomous |
| Sem decisão de arquitetura | Inteligência de arquitetura | | No architecture decision | Architecture intelligence |
| Documentação básica | Documentação completa | | Basic documentation | Complete documentation |
| Teste manual | Teste automático | | Manual testing | Automatic testing |
**O Agent-Skill-Creator transforma artigos e descrições em skills Claude Code totalmente funcionais e production-ready!** 🎉 **Agent-Skill-Creator transforms articles and descriptions into fully functional, production-ready Claude Code skills!** 🎉

318
docs/NAMING_CONVENTIONS.md
View file

@ -1,119 +1,119 @@
# Convenções de Nomenclatura: Sufixo "-cskill" # Naming Conventions: The "-cskill" Suffix
## 🎯 **Propósito e Visão Geral** ## 🎯 **Purpose and Overview**
Este documento estabelece a convenção de nomenclatura obrigatória para todas as Claude Skills criadas pelo Agent-Skill-Creator, utilizando o sufixo "-cskill" para garantir identificação clara e consistência profissional. This document establishes the mandatory naming convention for all Claude Skills created by Agent-Skill-Creator, using the "-cskill" suffix to ensure clear identification and professional consistency.
## 🏷️ **O Sufixo "-cskill"** ## 🏷️ **The "-cskill" Suffix**
### **Significado** ### **Meaning**
- **CSKILL** = **C**laude **SKILL** (Habilidade Claude) - **CSKILL** = **C**laude **SKILL**
- Indica que a skill foi criada automaticamente pelo Agent-Skill-Creator - Indicates the skill was automatically created by Agent-Skill-Creator
- Diferencia de skills criadas manualmente ou por outras ferramentas - Differentiates from manually created skills or other tools
### **Benefícios** ### **Benefits**
✅ **Identificação Imediata** ✅ **Immediate Identification**
- Qualquer pessoa vê "-cskill" e sabe imediatamente que é uma Claude Skill - Anyone sees "-cskill" and immediately knows it's a Claude Skill
- Reconhecimento instantâneo da origem (Agent-Skill-Creator) - Instant recognition of origin (Agent-Skill-Creator)
✅ **Organização Facilitada** ✅ **Easy Organization**
- Fácil filtrar e encontrar skills criadas pelo creator - Easy to filter and find skills created by the creator
- Agrupamento lógico em sistemas de arquivos - Logical grouping in file systems
- Busca eficiente com padrão consistente - Efficient search with consistent pattern
✅ **Profissionalismo** ✅ **Professionalism**
- Convenção de nomenclatura profissional e padronizada - Professional and standardized naming convention
- Clareza na comunicação sobre origem e tipo - Clarity in communication about origin and type
- Aparência organizada e intencional - Organized and intentional appearance
✅ **Evita Confusão** ✅ **Avoids Confusion**
- Sem ambiguidade sobre o que é uma skill vs plugin - No ambiguity about what's a skill vs plugin
- Distinção clara de skills manuais vs automatizadas - Clear distinction between manual vs automated skills
- Prevenção de conflitos de nomes - Prevention of name conflicts
## 📋 **Regras de Nomenclatura** ## 📋 **Naming Rules**
### **1. Formato Obrigatório** ### **1. Mandatory Format**
``` ```
{descrição-descritiva}-cskill/ {descriptive-description}-cskill/
``` ```
### **2. Estrutura do Nome Base** ### **2. Base Name Structure**
#### **Simple Skills (Objetivo Único)** #### **Simple Skills (Single Objective)**
``` ```
{ação}-{objeto}-csskill/ {action}-{object}-csskill/
``` ```
**Exemplos:** **Examples:**
- `pdf-text-extractor-cskill/` - `pdf-text-extractor-cskill/`
- `csv-data-cleaner-cskill/` - `csv-data-cleaner-cskill/`
- `image-converter-cskill/` - `image-converter-cskill/`
- `email-automation-cskill/` - `email-automation-cskill/`
- `report-generator-cskill/` - `report-generator-cskill/`
#### **Complex Skill Suites (Múltiplos Componentes)** #### **Complex Skill Suites (Multiple Components)**
``` ```
{domínio}-analysis-suite-cskill/ {domain}-analysis-suite-cskill/
{domínio}-automation-cskill/ {domain}-automation-cskill/
{domínio}-workflow-cskill/ {domain}-workflow-cskill/
``` ```
**Exemplos:** **Examples:**
- `financial-analysis-suite-cskill/` - `financial-analysis-suite-cskill/`
- `e-commerce-automation-cskill/` - `e-commerce-automation-cskill/`
- `research-workflow-cskill/` - `research-workflow-cskill/`
- `business-intelligence-cskill/` - `business-intelligence-cskill/`
#### **Component Skills (Dentro de Suites)** #### **Component Skills (Within Suites)**
``` ```
{funcionalidade}-{domínio}-cskill/ {functionality}-{domain}-cskill/
``` ```
**Exemplos:** **Examples:**
- `data-acquisition-cskill/` - `data-acquisition-cskill/`
- `technical-analysis-cskill/` - `technical-analysis-cskill/`
- `reporting-generator-cskill/` - `reporting-generator-cskill/`
- `user-interface-cskill/` - `user-interface-cskill/`
### **3. Regras de Formatação** ### **3. Formatting Rules**
✅ **OBRIGATÓRIO:** ✅ **REQUIRED:**
- Sempre minúsculas - Always lowercase
- Usar hífens (-) para separar palavras - Use hyphens (-) to separate words
- Terminar com "-cskill" - End with "-cskill"
- Ser descritivo e claro - Be descriptive and clear
- Usar apenas caracteres alfanuméricos e hífens - Use only alphanumeric characters and hyphens
❌ **PROIBIDO:** ❌ **PROHIBITED:**
- Letras maiúsculas - Uppercase letters
- Underscores (_) - Underscores (_)
- Espaços em branco - Whitespace
- Caracteres especiais (!@#$%&*) - Special characters (!@#$%&*)
- Números no início - Numbers at the beginning
- Abreviações não-padrão - Non-standard abbreviations
### **4. Comprimento Recomendado** ### **4. Recommended Length**
- **Mínimo:** 10 caracteres (ex: `pdf-tool-cskill`) - **Minimum:** 10 characters (ex: `pdf-tool-cskill`)
- **Ideal:** 20-40 caracteres (ex: `financial-analysis-suite-cskill`) - **Ideal:** 20-40 characters (ex: `financial-analysis-suite-cskill`)
- **Máximo:** 60 caracteres (exceções justificadas) - **Maximum:** 60 characters (justified exceptions)
## 🔧 **Processo de Geração de Nomes** ## 🔧 **Name Generation Process**
### **Lógica Automática do Agent-Skill-Creator** ### **Agent-Skill-Creator Automatic Logic**
```python ```python
def generate_skill_name(user_requirements, complexity): def generate_skill_name(user_requirements, complexity):
""" """
Gera nome da skill seguindo convenção -cskill Generates skill name following -cskill convention
""" """
# 1. Extrair conceitos-chave do input do usuário # 1. Extract key concepts from user input
concepts = extract_key_concepts(user_requirements) concepts = extract_key_concepts(user_requirements)
# 2. Criar nome base baseado na complexidade # 2. Create base name based on complexity
if complexity == "simple": if complexity == "simple":
base_name = create_simple_name(concepts) base_name = create_simple_name(concepts)
elif complexity == "complex_suite": elif complexity == "complex_suite":
@ -121,16 +121,16 @@ def generate_skill_name(user_requirements, complexity):
else: # hybrid else: # hybrid
base_name = create_hybrid_name(concepts) base_name = create_hybrid_name(concepts)
# 3. Sanitizar e formatar # 3. Sanitize and format
base_name = sanitize_name(base_name) base_name = sanitize_name(base_name)
# 4. Aplicar convenção -cskill # 4. Apply -cskill convention
skill_name = f"{base_name}-cskill" skill_name = f"{base_name}-cskill"
return skill_name return skill_name
def create_simple_name(concepts): def create_simple_name(concepts):
"""Cria nome para skills simples""" """Creates name for simple skills"""
if len(concepts) == 1: if len(concepts) == 1:
return f"{concepts[0]}-tool" return f"{concepts[0]}-tool"
elif len(concepts) == 2: elif len(concepts) == 2:
@ -139,30 +139,30 @@ def create_simple_name(concepts):
return "-".join(concepts[:2]) return "-".join(concepts[:2])
def create_suite_name(concepts): def create_suite_name(concepts):
"""Cria nome para suites complexas""" """Creates name for complex suites"""
if len(concepts) <= 2: if len(concepts) <= 2:
return f"{concepts[0]}-automation" return f"{concepts[0]}-automation"
else: else:
return f"{concepts[0]}-{'-'.join(concepts[1:3])}-suite" return f"{concepts[0]}-{'-'.join(concepts[1:3])}-suite"
def sanitize_name(name): def sanitize_name(name):
"""Sanitiza nome para formato válido""" """Sanitizes name to valid format"""
# Converter para minúsculas # Convert to lowercase
name = name.lower() name = name.lower()
# Substituir espaços e underscores por hífens # Replace spaces and underscores with hyphens
name = re.sub(r'[\s_]+', '-', name) name = re.sub(r'[\s_]+', '-', name)
# Remover caracteres especiais # Remove special characters
name = re.sub(r'[^a-z0-9-]', '', name) name = re.sub(r'[^a-z0-9-]', '', name)
# Remover hífens múltiplos # Remove multiple hyphens
name = re.sub(r'-+', '-', name) name = re.sub(r'-+', '-', name)
# Remover hífens no início/fim # Remove hyphens at start/end
name = name.strip('-') name = name.strip('-')
return name return name
``` ```
### **Exemplos de Transformação** ### **Transformation Examples**
| Input do Usuário | Tipo | Conceitos Extraídos | Nome Gerado | | User Input | Type | Extracted Concepts | Generated Name |
|------------------|------|-------------------|-------------| |------------------|------|-------------------|-------------|
| "Extract text from PDF" | Simple | ["extract", "text", "pdf"] | `pdf-text-extractor-cskill/` | | "Extract text from PDF" | Simple | ["extract", "text", "pdf"] | `pdf-text-extractor-cskill/` |
| "Clean CSV data automatically" | Simple | ["clean", "csv", "data"] | `csv-data-cleaner-cskill/` | | "Clean CSV data automatically" | Simple | ["clean", "csv", "data"] | `csv-data-cleaner-cskill/` |
@ -170,9 +170,9 @@ def sanitize_name(name):
| "Automate e-commerce workflows" | Suite | ["automate", "ecommerce", "workflows"] | `ecommerce-automation-cskill/` | | "Automate e-commerce workflows" | Suite | ["automate", "ecommerce", "workflows"] | `ecommerce-automation-cskill/` |
| "Generate weekly status reports" | Simple | ["generate", "weekly", "reports"] | `weekly-report-generator-cskill/` | | "Generate weekly status reports" | Simple | ["generate", "weekly", "reports"] | `weekly-report-generator-cskill/` |
## 📚 **Exemplos Práticos por Domínio** ## 📚 **Practical Examples by Domain**
### **Finanças e Investimentos** ### **Finance and Investments**
``` ```
financial-analysis-suite-cskill/ financial-analysis-suite-cskill/
portfolio-optimizer-cskill/ portfolio-optimizer-cskill/
@ -181,7 +181,7 @@ risk-calculator-cskill/
trading-signal-generator-cskill/ trading-signal-generator-cskill/
``` ```
### **Análise de Dados** ### **Data Analysis**
``` ```
data-visualization-cskill/ data-visualization-cskill/
statistical-analysis-cskill/ statistical-analysis-cskill/
@ -190,7 +190,7 @@ data-cleaner-cskill/
dashboard-generator-cskill/ dashboard-generator-cskill/
``` ```
### **Automação de Documentos** ### **Document Automation**
``` ```
pdf-processor-cskill/ pdf-processor-cskill/
word-automation-cskill/ word-automation-cskill/
@ -199,7 +199,7 @@ presentation-creator-cskill/
document-converter-cskill/ document-converter-cskill/
``` ```
### **E-commerce e Vendas** ### **E-commerce and Sales**
``` ```
inventory-tracker-cskill/ inventory-tracker-cskill/
sales-analytics-cskill/ sales-analytics-cskill/
@ -208,7 +208,7 @@ order-automation-cskill/
price-monitor-cskill/ price-monitor-cskill/
``` ```
### **Pesquisa e Academia** ### **Research and Academia**
``` ```
literature-review-cskill/ literature-review-cskill/
citation-manager-cskill/ citation-manager-cskill/
@ -217,7 +217,7 @@ academic-paper-generator-cskill/
survey-analyzer-cskill/ survey-analyzer-cskill/
``` ```
### **Produtividade e Escritório** ### **Productivity and Office**
``` ```
email-automation-cskill/ email-automation-cskill/
calendar-manager-cskill/ calendar-manager-cskill/
@ -226,105 +226,105 @@ note-organizer-cskill/
meeting-scheduler-cskill/ meeting-scheduler-cskill/
``` ```
## 🔍 **Validação e Qualidade** ## 🔍 **Validation and Quality**
### **Verificação Automática** ### **Automatic Verification**
```python ```python
def validate_skill_name(skill_name): def validate_skill_name(skill_name):
""" """
Valida se o nome segue a convenção -cskill Validates if name follows -cskill convention
""" """
# 1. Verificar sufixo -cskill # 1. Check -cskill suffix
if not skill_name.endswith("-cskill"): if not skill_name.endswith("-cskill"):
return False, "Missing -cskill suffix" return False, "Missing -cskill suffix"
# 2. Verificar formato minúsculas # 2. Check lowercase format
if skill_name != skill_name.lower(): if skill_name != skill_name.lower():
return False, "Must be lowercase" return False, "Must be lowercase"
# 3. Verificar caracteres válidos # 3. Check valid characters
if not re.match(r'^[a-z0-9-]+-cskill$', skill_name): if not re.match(r'^[a-z0-9-]+-cskill$', skill_name):
return False, "Contains invalid characters" return False, "Contains invalid characters"
# 4. Verificar comprimento # 4. Check length
if len(skill_name) < 10 or len(skill_name) > 60: if len(skill_name) < 10 or len(skill_name) > 60:
return False, "Invalid length" return False, "Invalid length"
# 5. Verificar hífens consecutivos # 5. Check consecutive hyphens
if '--' in skill_name: if '--' in skill_name:
return False, "Contains consecutive hyphens" return False, "Contains consecutive hyphens"
return True, "Valid naming convention" return True, "Valid naming convention"
``` ```
### **Checklist de Qualidade** ### **Quality Checklist**
Para cada nome gerado, verificar: For each generated name, verify:
- [ ] **Termina com "-cskill"** ✓ - [ ] **Ends with "-cskill"** ✓
- [ ] **Está em minúsculas** ✓ - [ ] **Is in lowercase** ✓
- [ ] **Usa apenas hífens como separadores** ✓ - [ ] **Uses only hyphens as separators** ✓
- [ ] **É descritivo e claro** ✓ - [ ] **Is descriptive and clear** ✓
- [ ] **Não tem caracteres especiais** ✓ - [ ] **Has no special characters** ✓
- [ ] **Comprimento adequado (10-60 caracteres)** ✓ - [ ] **Appropriate length (10-60 characters)** ✓
- [ ] **Fácil de pronunciar e lembrar** ✓ - [ ] **Easy to pronounce and remember** ✓
- [ ] **Reflete a funcionalidade principal** ✓ - [ ] **Reflects main functionality** ✓
- [ ] **É único no ecossistema** ✓ - [ ] **Is unique in ecosystem** ✓
## 🚀 **Boas Práticas** ## 🚀 **Best Practices**
### **1. Seja Descritivo** ### **1. Be Descriptive**
``` ```
✅ bom: pdf-text-extractor-cskill ✅ good: pdf-text-extractor-cskill
❌ ruim: tool-cskill ❌ bad: tool-cskill
✅ bom: financial-analysis-suite-cskill ✅ good: financial-analysis-suite-cskill
❌ ruim: finance-cskill ❌ bad: finance-cskill
``` ```
### **2. Mantenha Simplicidade** ### **2. Keep It Simple**
``` ```
✅ bom: csv-data-cleaner-cskill ✅ good: csv-data-cleaner-cskill
❌ ruim: automated-csv-data-validation-and-cleaning-tool-cskill ❌ bad: automated-csv-data-validation-and-cleaning-tool-cskill
✅ bom: email-automation-cskill ✅ good: email-automation-cskill
❌ ruim: professional-email-marketing-automation-workflow-cskill ❌ bad: professional-email-marketing-automation-workflow-cskill
``` ```
### **3. Seja Consistente** ### **3. Be Consistent**
``` ```
✅ bom: data-acquisition-cskill, data-processing-cskill, data-visualization-cskill ✅ good: data-acquisition-cskill, data-processing-cskill, data-visualization-cskill
❌ ruim: get-data-cskill, process-cskill, visualize-cskill ❌ bad: get-data-cskill, process-cskill, visualize-cskill
``` ```
### **4. Pense no Usuário** ### **4. Think About the User**
``` ```
✅ bom: weekly-report-generator-cskill (claro o que faz) ✅ good: weekly-report-generator-cskill (clear what it does)
❌ ruim: wrk-gen-cskill (abreviado, confuso) ❌ bad: wrk-gen-cskill (abbreviated, confusing)
``` ```
## 🔄 **Migração e Legado** ## 🔄 **Migration and Legacy**
### **Skills Existentes Sem "-cskill"** ### **Existing Skills Without "-cskill"**
Se você tem skills existentes sem o sufixo: If you have existing skills without the suffix:
1. **Adicione o sufixo imediatamente** 1. **Add the suffix immediately**
```bash ```bash
mv old-skill-name old-skill-name-cskill mv old-skill-name old-skill-name-cskill
``` ```
2. **Atualize referências internas** 2. **Update internal references**
- Atualize SKILL.md - Update SKILL.md
- Modifique marketplace.json - Modify marketplace.json
- Atualize documentação - Update documentation
3. **Teste funcionamento** 3. **Test functionality**
- Verifique que a skill ainda funciona - Verify skill still works
- Confirme instalação correta - Confirm correct installation
### **Documentação de Migração** ### **Migration Documentation**
Para cada skill migrada, documente: For each migrated skill, document:
```markdown ```markdown
## Migration History ## Migration History
- **Original Name**: `old-name` - **Original Name**: `old-name`
@ -334,41 +334,41 @@ Para cada skill migrada, documente:
- **Impact**: None, purely cosmetic change - **Impact**: None, purely cosmetic change
``` ```
## 📖 **Guia Rápido de Referência** ## 📖 **Quick Reference Guide**
### **Para Criar Novo Nome:** ### **To Create New Name:**
1. **Identificar objetivo principal** (ex: "extract PDF text") 1. **Identify main objective** (ex: "extract PDF text")
2. **Extrair conceitos-chave** (ex: extract, pdf, text) 2. **Extract key concepts** (ex: extract, pdf, text)
3. **Montar nome base** (ex: pdf-text-extractor) 3. **Build base name** (ex: pdf-text-extractor)
4. **Adicionar sufixo** (ex: pdf-text-extractor-cskill) 4. **Add suffix** (ex: pdf-text-extractor-cskill)
### **Para Validar Nome Existente:** ### **To Validate Existing Name:**
1. **Verificar sufixo "-cskill"** 1. **Check "-cskill" suffix**
2. **Confirmar formato minúsculas** 2. **Confirm lowercase format**
3. **Checar caracteres válidos** 3. **Check valid characters**
4. **Avaliar descritividade** 4. **Evaluate descriptiveness**
### **Para Solucionar Problemas:** ### **To Troubleshoot:**
- **Nome muito curto**: Adicionar descritor - **Name too short**: Add descriptor
- **Nome muito longo**: Remover palavras secundárias - **Name too long**: Remove secondary words
- **Nome confuso**: Usar sinônimos mais claros - **Confusing name**: Use clearer synonyms
- **Conflito de nomes**: Adicionar diferenciador - **Name conflict**: Add differentiator
## ✅ **Resumo da Convenção** ## ✅ **Convention Summary**
**Fórmula:** `{descrição-descritiva}-cskill/` **Formula:** `{descriptive-description}-cskill/`
**Regras Essenciais:** **Essential Rules:**
- ✅ Sempre terminar com "-cskill" - ✅ Always end with "-cskill"
- ✅ Sempre minúsculas - ✅ Always lowercase
- ✅ Usar hífens como separadores - ✅ Use hyphens as separators
- ✅ Ser descritivo e claro - ✅ Be descriptive and clear
**Resultados:** **Results:**
- 🎯 Identificação imediata como Claude Skill - 🎯 Immediate identification as Claude Skill
- 🏗️ Origem clara (Agent-Skill-Creator) - 🏗️ Clear origin (Agent-Skill-Creator)
- 📁 Organização facilitada - 📁 Easy organization
- 🔍 Busca eficiente - 🔍 Efficient search
- 💬 Comunicação clara - 💬 Clear communication
**Esta convenção garante consistência profissional e elimina qualquer confusão sobre a origem e tipo das skills criadas!** **This convention ensures professional consistency and eliminates any confusion about the origin and type of created skills!**