manuelmauro/skilo

Use Skilo

Skilo é uma ferramenta de linha de comando para desenvolver Agent Skills (Skills de Agente).

Instalação

curl -sSfL https://raw.githubusercontent.com/manuelmauro/skilo/main/install.sh | sh

Início Rápido

skilo new my-skill        # Criar a partir de template
skilo add owner/repo      # Instalar a partir de git
skilo lint .              # Validar conforme a especificação
skilo fmt .               # Formatar arquivos SKILL.md

Execute skilo -h para ver todos os comandos e opções.

SEMPRE Valide Skills

Execute skilo lint e skilo fmt antes de commitar qualquer alteração em skills. Esses comandos aplicam a Especificação de Agent Skills e detectam problemas comuns.

# Validar e formatar em um comando
skilo check .

# Modo estrito para CI (avisos se tornam erros)
skilo check --strict .

Estrutura da Skill

my-skill/
├── SKILL.md        # Obrigatório: manifesto com frontmatter YAML
├── scripts/        # Opcional: código executável
├── references/     # Opcional: documentação adicional (carregada sob demanda)
└── assets/         # Opcional: recursos estáticos

Requisitos de Frontmatter

Campos Obrigatórios

name (1 a 64 caracteres)

• Apenas letras minúsculas, números e hífens (a-z, 0-9, -)
• NÃO deve começar/terminar com - nem conter --
• Deve corresponder ao nome do diretório pai

description (1 a 1024 caracteres)

• Descreva O QUE a skill faz E QUANDO usá-la
• Inclua palavras-chave que ajudem agentes a corresponder solicitações do usuário

Campos Opcionais

• license - Mantenha curto; referencie o arquivo LICENSE para detalhes
• compatibility (máx. 500 caracteres) - Requisitos de ambiente (ex.: Requer git, docker)
• metadata - Pares chave-valor para propriedades personalizadas
• allowed-tools - Lista separada por espaços de ferramentas pré-aprovadas (experimental)

Melhores Práticas

Escreva Descrições Eficazes

A descrição é como os agentes decidem quando ativar sua skill. Seja específico.

# Bom - específico, rico em palavras-chave
description: Extrai texto e tabelas de arquivos PDF, preenche formulários PDF e mescla múltiplos PDFs. Use ao trabalhar com documentos PDF ou quando o usuário mencionar PDFs, formulários ou extração de documentos.

# Ruim - vago, sem pistas de ativação
description: Ajuda com PDFs.

Mantenha o Conteúdo do Corpo Conciso

Todo o corpo do SKILL.md é carregado quando a skill é ativada. Mantenha abaixo de 500 linhas.

• Inclua instruções passo a passo
• Adicione exemplos de entradas e saídas
• Cubra casos extremos comuns
• Mova material detalhado para references/

Use Divulgação Progressiva

Estruture skills para minimizar o uso de contexto:

1. Metadados (~100 tokens) - name + description carregados na inicialização para todas as skills
2. Instruções (<5000 tokens) - Corpo completo carregado quando a skill é ativada
3. Recursos (sob demanda) - scripts/, references/, assets/ carregados apenas quando necessário

Escreva Scripts Autossuficientes

Scripts em scripts/ devem:

• Ser autossuficientes ou documentar claramente as dependências
• Incluir mensagens de erro úteis
• Tratar casos extremos com elegância

Organize Referências de Forma Eficaz

Arquivos em references/ são carregados sob demanda:

• Mantenha arquivos focados (um arquivo = um conceito)
• Use caminhos relativos a partir da raiz da skill
• Evite cadeias de referências profundamente aninhadas

Regras de Lint

Skilo aplica estas regras (configure em .skilorc.toml):

Código	Regra	Padrão
E001	name_format	habilitado
E002	name_length	64 caracteres
E003	name_directory	habilitado
E004	description_required	habilitado
E005	description_length	1024 caracteres
E006	compatibility_length	500 caracteres
E009	references_exist	habilitado
W001	body_length	500 linhas
W002	script_executable	habilitado
W003	script_shebang	habilitado

Integração com CI

- name: Validar skills
  run: |
    curl -sSfL https://raw.githubusercontent.com/manuelmauro/skilo/main/install.sh | sh
    skilo check --strict skills/