Criador de Habilidades: Crie Habilidades Eficazes no Claude

--- name: criador-de-habilidades description: Guia para criar habilidades eficazes. Esta habilidade deve ser usada quando os usuários quiserem criar uma nova habilidade (ou atualizar uma existente) que estenda as capacidades do Claude com conhecimento especializado, fluxos de trabalho ou integrações de ferramentas. licença: Termos completos em LICENSE.txt --- # Criador de Habilidades Esta habilidade fornece orientação para criar habilidades eficazes. ## Sobre Habilidades Habilidades são pacotes modulares e autocontidos que estendem as capacidades do Claude, fornecendo conhecimento especializado, fluxos de trabalho e ferramentas. Pense nelas como "guias de integração" para domínios ou tarefas específicas - elas transformam o Claude de um agente de propósito geral em um agente especializado, equipado com conhecimento processual que nenhum modelo pode possuir completamente. ### O que as Habilidades Fornecem 1. Fluxos de trabalho especializados - Procedimentos de múltiplas etapas para domínios específicos 2. Integrações de ferramentas - Instruções para trabalhar com formatos de arquivo ou APIs específicas 3. Expertise de domínio - Conhecimento específico da empresa, esquemas, lógica de negócios 4. Recursos agrupados - Scripts, referências e ativos para tarefas complexas e repetitivas ## Princípios Fundamentais ### Concisão é Fundamental A janela de contexto é um bem público. As habilidades compartilham a janela de contexto com tudo o mais que o Claude precisa: prompt do sistema, histórico da conversa, metadados de outras habilidades e a solicitação real do usuário. **Premissa padrão: o Claude já é muito inteligente.** Adicione apenas contexto que o Claude ainda não possui. Questione cada informação: "O Claude realmente precisa dessa explicação?" e "Este parágrafo justifica seu custo de tokens?" Prefira exemplos concisos a explicações verbosas. ### Defina Graus Apropriados de Liberdade Combine o nível de especificidade com a fragilidade e variabilidade da tarefa: **Alta liberdade (instruções baseadas em texto)**: Use quando múltiplas abordagens são válidas, as decisões dependem do contexto ou heurísticas guiam a abordagem. **Liberdade média (pseudocódigo ou scripts com parâmetros)**: Use quando existe um padrão preferido, alguma variação é aceitável ou a configuração afeta o comportamento. **Baixa liberdade (scripts específicos, poucos parâmetros)**: Use quando as operações são frágeis e propensas a erros, a consistência é crítica ou uma sequência específica deve ser seguida. Pense no Claude como explorando um caminho: uma ponte estreita com penhascos precisa de guarda-corpos específicos (baixa liberdade), enquanto um campo aberto permite muitas rotas (alta liberdade). ### Anatomia de uma Habilidade Toda habilidade consiste em um arquivo SKILL.md obrigatório e recursos agrupados opcionais: ``` nome-da-habilidade/ ├── SKILL.md (obrigatório) │ ├── Metadados YAML frontmatter (obrigatório) │ │ ├── name: (obrigatório) │ │ └── description: (obrigatório) │ └── Instruções em Markdown (obrigatório) └── Recursos Agrupados (opcional) ├── scripts/ - Código executável (Python/Bash/etc.) ├── references/ - Documentação destinada a ser carregada no contexto conforme necessário └── assets/ - Arquivos usados na saída (modelos, ícones, fontes, etc.) ``` #### SKILL.md (obrigatório) Todo SKILL.md consiste em: - **Frontmatter** (YAML): Contém os campos `name` e `description`. Estes são os únicos campos que o Claude lê para determinar quando a habilidade será usada, portanto é muito importante ser claro e abrangente ao descrever o que a habilidade é e quando deve ser usada. - **Corpo** (Markdown): Instruções e orientações para usar a habilidade. Só é carregado APÓS a habilidade ser acionada (se for o caso). #### Recursos Agrupados (opcional) ##### Scripts (`scripts/`) Código executável (Python/Bash/etc.) para tarefas que exigem confiabilidade determinística ou são reescritas repetidamente. - **Quando incluir**: Quando o mesmo código está sendo reescrito repetidamente ou é necessária confiabilidade determinística - **Exemplo**: `scripts/rotate_pdf.py` para tarefas de rotação de PDF - **Benefícios**: Eficiente em tokens, determinístico, pode ser executado sem ser carregado no contexto - **Nota**: Os scripts ainda podem precisar ser lidos pelo Claude para correções ou ajustes específicos do ambiente ##### Referências (`references/`) Documentação e material de referência destinados a serem carregados conforme necessário no contexto para informar o processo e o pensamento do Claude. - **Quando incluir**: Para documentação que o Claude deve consultar enquanto trabalha - **Exemplos**: `references/finance.md` para esquemas financeiros, `references/mnda.md` para modelo de NDA da empresa, `references/policies.md` para políticas da empresa, `references/api_docs.md` para especificações de API - **Casos de uso**: Esquemas de banco de dados, documentação de API, conhecimento de domínio, políticas da empresa, guias de fluxo de trabalho detalhados - **Benefícios**: Mantém o SKILL.md enxuto, carregado somente quando o Claude determina que é necessário - **Melhor prática**: Se os arquivos forem grandes (>10k palavras), inclua padrões de busca grep no SKILL.md - **Evite duplicação**: A informação deve estar no SKILL.md ou nos arquivos de referência, não em ambos. ##### Ativos (`assets/`) Arquivos não destinados a serem carregados no contexto, mas sim usados na saída que o Claude produz. - **Quando incluir**: Quando a habilidade precisa de arquivos que serão usados na saída final - **Exemplos**: `assets/logo.png` para ativos de marca, `assets/slides.pptx` para modelos do PowerPoint - **Casos de uso**: Modelos, imagens, ícones, código boilerplate, fontes, documentos de exemplo ### Princípio de Design de Divulgação Progressiva As habilidades usam um sistema de carregamento de três níveis para gerenciar o contexto com eficiência: 1. **Metadados (nome + descrição)** - Sempre no contexto (~100 palavras) 2. **Corpo do SKILL.md** - Quando a habilidade é acionada (<5k palavras) 3. **Recursos agrupados** - Conforme necessário pelo Claude Mantenha o corpo do SKILL.md no essencial e abaixo de 500 linhas para minimizar o inchaço do contexto. ## Processo de Criação de Habilidades A criação de habilidades envolve estas etapas: 1. Entenda a habilidade com exemplos concretos 2. Planeje o conteúdo reutilizável da habilidade (scripts, referências, ativos) 3. Inicialize a habilidade (execute init_skill.py) 4. Edite a habilidade (implemente recursos e escreva o SKILL.md) 5. Empacote a habilidade (execute package_skill.py) 6. Itere com base no uso real ### Etapa 3: Inicializando a Habilidade Ao criar uma nova habilidade do zero, sempre execute o script `init_skill.py`: ```bash scripts/init_skill.py <nome-da-habilidade> --path <diretório-de-saída> ``` ### Etapa 4: Edite a Habilidade Consulte estes guias úteis com base nas necessidades da sua habilidade: - **Processos de múltiplas etapas**: Veja references/workflows.md para fluxos de trabalho sequenciais e lógica condicional - **Formatos de saída específicos ou padrões de qualidade**: Veja references/output-patterns.md para modelos e padrões de exemplo ### Etapa 5: Empacotando uma Habilidade ```bash scripts/package_skill.py <caminho/para/pasta-da-habilidade> ``` O script de empacotamento valida e cria um arquivo .skill para distribuição. ARQUIVO:references/workflows.md # Padrões de Fluxo de Trabalho ## Fluxos de Trabalho Sequenciais Para tarefas complexas, divida as operações em etapas claras e sequenciais. Muitas vezes é útil dar ao Claude uma visão geral do processo no início do SKILL.md: ```markdown O preenchimento de um formulário PDF envolve estas etapas: 1. Analise o formulário (execute analyze_form.py) 2. Crie o mapeamento de campos (edite fields.json) 3. Valide o mapeamento (execute validate_fields.py) 4. Preencha o formulário (execute fill_form.py) 5. Verifique a saída (execute verify_output.py) ``` ## Fluxos de Trabalho Condicionais Para tarefas com lógica de ramificação, guie o Claude pelos pontos de decisão: ```markdown 1. Determine o tipo de modificação: **Criando novo conteúdo?** → Siga o "Fluxo de criação" abaixo **Editando conteúdo existente?** → Siga o "Fluxo de edição" abaixo 2. Fluxo de criação: [etapas] 3. Fluxo de edição: [etapas] ``` ARQUIVO:references/output-patterns.md # Padrões de Saída Use estes padrões quando as habilidades precisarem produzir saída consistente e de alta qualidade. ## Padrão de Modelo Forneça modelos para o formato de saída. Combine o nível de rigor com suas necessidades. **Para requisitos estritos (como respostas de API ou formatos de dados):** ```markdown ## Estrutura do relatório SEMPRE use esta estrutura de modelo exata: # [Título da Análise] ## Resumo executivo [Visão geral em um parágrafo das principais descobertas] ## Principais descobertas - Descoberta 1 com dados de apoio - Descoberta 2 com dados de apoio - Descoberta 3 com dados de apoio ## Recomendações 1. Recomendação específica e acionável 2. Recomendação específica e acionável ``` **Para orientação flexível (quando a adaptação é útil):** ```markdown ## Estrutura do relatório Aqui está um formato padrão sensato, mas use seu melhor julgamento: # [Título da Análise] ## Resumo executivo [Visão geral] ## Principais descobertas [Adapte as seções com base no que você descobrir] ## Recomendações [Adapte ao contexto específico] Ajuste as seções conforme necessário para o tipo específico de análise. ``` ## Padrão de Exemplos Para habilidades onde a qualidade da saída depende de ver exemplos, forneça pares de entrada/saída: ```markdown ## Formato de mensagem de commit Gere mensagens de commit seguindo estes exemplos: **Exemplo 1:** Entrada: Adicionada autenticação de usuário com tokens JWT Saída: ``` feat(auth): implementar autenticação baseada em JWT Adicionar endpoint de login e middleware de validação de token ``` **Exemplo 2:** Entrada: Corrigido bug onde as datas eram exibidas incorretamente nos relatórios Saída: ``` fix(reports): corrigir formatação de datas na conversão de fuso horário Usar timestamps UTC de forma consistente na geração de relatórios ``` Siga este estilo: tipo(escopo): descrição breve, depois explicação detalhada. ``` Exemplos ajudam o Claude a entender o estilo e o nível de detalhe desejados mais claramente do que descrições sozinhas. ARQUIVO:scripts/quick_validate.py #!/usr/bin/env python3 """ Script de validação rápida para habilidades - versão mínima """ import sys import os import re import yaml from pathlib import Path def validate_skill(skill_path): """Validação básica de uma habilidade""" skill_path = Path(skill_path) # Verifica se SKILL.md existe skill_md = skill_path / 'SKILL.md' if not skill_md.exists(): return False, "SKILL.md não encontrado" # Lê e valida o frontmatter content = skill_md.read_text() if not content.startswith('---'): return False, "Nenhum frontmatter YAML encontrado" # Extrai o frontmatter match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL) if not match: return False, "Formato de frontmatter inválido" frontmatter_text = match.group(1) # Analisa o frontmatter YAML try: frontmatter = yaml.safe_load(frontmatter_text) if not isinstance(frontmatter, dict): return False, "O frontmatter deve ser um dicionário YAML" except yaml.YAMLError as e: return False, f"YAML inválido no frontmatter: {e}" # Define propriedades permitidas ALLOWED_PROPERTIES = {'name', 'description', 'license', 'allowed-tools', 'metadata'} # Verifica propriedades inesperadas (excluindo chaves aninhadas sob metadata) unexpected_keys = set(frontmatter.keys()) - ALLOWED_PROPERTIES if unexpected_keys: return False, ( f"Chave(s) inesperada(s) no frontmatter do SKILL.md: {', '.join(sorted(unexpected_keys))}. " f"As propriedades permitidas são: {', '.join(sorted(ALLOWED_PROPERTIES))}" ) # Verifica campos obrigatórios if 'name' not in frontmatter: return False, "'name' ausente no frontmatter" if 'description' not in frontmatter: return False, "'description' ausente no frontmatter" # Extrai o nome para validação name = frontmatter.get('name', '') if not isinstance(name, str): return False, f"O nome deve ser uma string, obteve {type(name).__name__}" name = name.strip() if name: # Verifica convenção de nomenclatura (hífen-case: minúsculas com hífens) if not re.match(r'^[a-z0-9-]+$', name): return False, f"O nome '{name}' deve estar em hífen-case (apenas letras minúsculas, dígitos e hífens)" if name.startswith('-') or name.endswith('-') or '--' in name: return False, f"O nome '{name}' não pode começar/terminar com hífen ou conter hífens consecutivos" # Verifica comprimento do nome (máximo 64 caracteres por especificação) if len(name) > 64: return False, f"O nome é muito longo ({len(name)} caracteres). O máximo é 64 caracteres." # Extrai e valida a descrição description = frontmatter.get('description', '') if not isinstance(description, str): return False, f"A descrição deve ser uma string, obteve {type(description).__name__}" description = description.strip() if description: # Verifica colchetes angulares if '<' in description or '>' in description: return False, "A descrição não pode conter colchetes angulares (< ou >)" # Verifica comprimento da descrição (máximo 1024 caracteres por especificação) if len(description) > 1024: return False, f"A descrição é muito longa ({len(description)} caracteres). O máximo é 1024 caracteres." return True, "Habilidade válida!" if __name__ == "__main__": if len(sys.argv) != 2: print("Uso: python quick_validate.py <diretório-da-habilidade>") sys.exit(1) valid, message = validate_skill(sys.argv[1]) print(message) sys.exit(0 if valid else 1) ARQUIVO:scripts/init_skill.py #!/usr/bin/env python3 """ Inicializador de Habilidades - Cria uma nova habilidade a partir de modelo Uso: init_skill.py <nome-da-habilidade> --path <caminho> Exemplos: init_skill.py minha-nova-habilidade --path skills/public init_skill.py meu-ajudante-de-api --path skills/private init_skill.py habilidade-personalizada --path /local/personalizado """ import sys from pathlib import Path SKILL_TEMPLATE = """--- name: {skill_name} description: [TODO: Explicação completa e informativa do que a habilidade faz e quando usá-la. Inclua QUANDO usar esta habilidade - cenários específicos, tipos de arquivo ou tarefas que a acionam.] --- # {skill_title} ## Visão Geral [TODO: 1-2 frases explicando o que esta habilidade permite] ## Recursos Esta habilidade inclui diretórios de recursos de exemplo que demonstram como organizar diferentes tipos de recursos agrupados: ### scripts/ Código executável (Python/Bash/etc.) que pode ser executado diretamente para realizar operações específicas. ### references/ Documentação e material de referência destinados a serem carregados no contexto para informar o processo e o pensamento do Claude. ### assets/ Arquivos não destinados a serem carregados no contexto, mas sim usados na saída que o Claude produz. --- **Quaisquer diretórios desnecessários podem ser excluídos.** Nem toda habilidade requer todos os três tipos de recursos. """ EXAMPLE_SCRIPT = '''#!/usr/bin/env python3 """ Script auxiliar de exemplo para {skill_name} Este é um script placeholder que pode ser executado diretamente. Substitua pela implementação real ou exclua se não for necessário. """ def main(): print("Este é um script de exemplo para {skill_name}") # TODO: Adicione a lógica real do script aqui if __name__ == "__main__": main() ''' EXAMPLE_REFERENCE = """# Documentação de Referência para {skill_title} Este é um placeholder para documentação de referência detalhada. Substitua pelo conteúdo de referência real ou exclua se não for necessário. """ EXAMPLE_ASSET = """# Arquivo de Ativo de Exemplo Este placeholder representa onde os arquivos de ativos seriam armazenados. Substitua pelos arquivos de ativos reais (modelos, imagens, fontes, etc.) ou exclua se não for necessário. """ def title_case_skill_name(skill_name): """Converte o nome da habilidade com hífens para Title Case para exibição.""" return ' '.join(word.capitalize() for word in skill_name.split('-')) def init_skill(skill_name, path): """Inicializa um novo diretório de habilidade com SKILL.md de modelo.""" skill_dir = Path(path).resolve() / skill_name if skill_dir.exists(): print(f"❌ Erro: O diretório da habilidade já existe: {skill_dir}") return None try: skill_dir.mkdir(parents=True, exist_ok=False) print(f"✅ Diretório da habilidade criado: {skill_dir}") except Exception as e: print(f"❌ Erro ao criar diretório: {e}") return None skill_title = title_case_skill_name(skill_name) skill_content = SKILL_TEMPLATE.format(skill_name=skill_name, skill_title=skill_title) skill_md_path = skill_dir / 'SKILL.md' try: skill_md_path.write_text(skill_content) print("✅ SKILL.md criado") except Exception as e: print(f"❌ Erro ao criar SKILL.md: {e}") return None try: scripts_dir = skill_dir / 'scripts' scripts_dir.mkdir(exist_ok=True) example_script = scripts_dir / 'example.py' example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name)) example_script.chmod(0o755) print("✅ scripts/example.py criado") references_dir = skill_dir / 'references' references_dir.mkdir(exist_ok=True) example_reference = references_dir / 'api_reference.md' example_reference.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title)) print("✅ references/api_reference.md criado") assets_dir = skill_dir / 'assets' assets_dir.mkdir(exist_ok=True) example_asset = assets_dir / 'example_asset.txt' example_asset.write_text(EXAMPLE_ASSET) print("✅ assets/example_asset.txt criado") except Exception as e: print(f"❌ Erro ao criar diretórios de recursos: {e}") return None print(f"\n✅ Habilidade '{skill_name}' inicializada com sucesso em {skill_dir}") return skill_dir def main(): if len(sys.argv) < 4 or sys.argv[2] != '--path': print("Uso: init_skill.py <nome-da-habilidade> --path <caminho>") sys.exit(1) skill_name = sys.argv[1] path = sys.argv[3] print(f"🚀 Inicializando habilidade: {skill_name}") print(f" Local: {path}") print() result = init_skill(skill_name, path) sys.exit(0 if result else 1) if __name__ == "__main__": main() ARQUIVO:scripts/package_skill.py #!/usr/bin/env python3 """ Empacotador de Habilidades - Cria um arquivo .skill distribuível de uma pasta de habilidade Uso: python utils/package_skill.py <caminho/para/pasta-da-habilidade> [diretório-de-saída] Exemplo: python utils/package_skill.py skills/public/minha-habilidade python utils/package_skill.py skills/public/minha-habilidade ./dist """ import sys import zipfile from pathlib import Path from quick_validate import validate_skill def package_skill(skill_path, output_dir=None): """Empacota uma pasta de habilidade em um arquivo .skill.""" skill_path = Path(skill_path).resolve() if not skill_path.exists(): print(f"❌ Erro: Pasta da habilidade não encontrada: {skill_path}") return None if not skill_path.is_dir(): print(f"❌ Erro: O caminho não é um diretório: {skill_path}") return None skill_md = skill_path / "SKILL.md" if not skill_md.exists(): print(f"❌ Erro: SKILL.md não encontrado em {skill_path}") return None print("🔍 Validando habilidade...") valid, message = validate_skill(skill_path) if not valid: print(f"❌ Falha na validação: {message}") print(" Corrija os erros de validação antes de empacotar.") return None print(f"✅ {message}\n") skill_name = skill_path.name if output_dir: output_path = Path(output_dir).resolve() output_path.mkdir(parents=True, exist_ok=True) else: output_path = Path.cwd() skill_filename = output_path / f"{skill_name}.skill" try: with zipfile.ZipFile(skill_filename, 'w', zipfile.ZIP_DEFLATED) as zipf: for file_path in skill_path.rglob('*'): if file_path.is_file(): arcname = file_path.relative_to(skill_path.parent) zipf.write(file_path, arcname) print(f" Adicionado: {arcname}") print(f"\n✅ Habilidade empacotada com sucesso em: {skill_filename}") return skill_filename except Exception as e: print(f"❌ Erro ao criar arquivo .skill: {e}") return None def main(): if len(sys.argv) < 2: print("Uso: python utils/package_skill.py <caminho/para/pasta-da-habilidade> [diretório-de-saída]") sys.exit(1) skill_path = sys.argv[1] output_dir = sys.argv[2] if len(sys.argv) > 2 else None print(f"📦 Empacotando habilidade: {skill_path}") if output_dir: print(f" Diretório de saída: {output_dir}") print() result = package_skill(skill_path, output_dir) sys.exit(0 if result else 1) if __name__ == "__main__": main()