SkillDoAI/skilldo

Skilldo CLI

Skilldo é um pipeline de LLM de 7 estágios que gera arquivos SKILL.md para bibliotecas de software: extrair → mapear → aprender → fatos → criar → revisar → testar

Os estágios 1 a 3 coletam metadados da biblioteca (arquivos-fonte, documentação, dependências, versão). O estágio 4 (fatos) extrai uma tabela verdade compacta com afirmações negativas dos estágios 1 a 3. O estágio 5 gera o SKILL.md. O estágio 6 revisa precisão/segurança. O estágio 7 valida com código de teste gerado.

Instalação

# Homebrew
brew install skilldoai/tap/skilldo

# A partir do código-fonte
cargo install --path .

Início Rápido

# Gera um SKILL.md para o repositório atual
skilldo generate

# Gera para um caminho de repositório específico
skilldo generate /caminho/para/biblioteca

# Especifica linguagem explicitamente
skilldo generate --language python

# Usa uma configuração específica
skilldo generate --config skilldo.toml

Configuração (skilldo.toml)

O Skilldo usa arquivos de configuração TOML. Coloque skilldo.toml na raiz do repositório, ou use --config.

Configuração mínima (provedor único)

[llm]
provider_type = "anthropic"          # anthropic, openai, gemini, openai-compatible, chatgpt
model = "claude-sonnet-4-6"
api_key_env = "ANTHROPIC_API_KEY"  # nome da variável de ambiente que contém a chave

[generation]
max_retries = 10                # repetir em caso de falhas de lint/teste
# telemetry = true              # opt-in: registrar execuções em ~/.skilldo/runs.csv

Substituições de modelo por estágio

Modelos diferentes podem ser usados para os estágios de revisão e teste:

[llm]
provider_type = "anthropic"
model = "claude-sonnet-4-6"
api_key_env = "ANTHROPIC_API_KEY"

[generation]
enable_test = true
enable_review = true
test_mode = "thorough"          # thorough, quick, adaptive, minimal

[generation.review_llm]
provider_type = "openai"
model = "gpt-5.2"
api_key_env = "OPENAI_API_KEY"

[generation.test_llm]
provider_type = "openai"
model = "gpt-5.2"
api_key_env = "OPENAI_API_KEY"

Modelos locais (Ollama)

[llm]
provider_type = "openai-compatible"
model = "qwen3-coder:latest"
base_url = "http://localhost:11434/v1"
api_key_env = "none"            # Ollama não precisa de chave

Provedor CLI (usar ferramentas CLI existentes como backend LLM)

[llm]
provider_type = "cli"
model = "claude-sonnet-4-6"
cli_command = "claude"
cli_args = ["-p", "--no-session-persistence", "--output-format", "text", "--dangerously-skip-permissions"]
request_timeout_secs = 900

Ferramentas CLI suportadas: claude, codex, gemini. O prompt é enviado via stdin; a resposta é capturada do stdout.

Opcional: declarar como a CLI aceita prompts de sistema nativamente:

cli_system_args = ["--system-prompt-file"]  # para claude (lê de arquivo temporário)
# cli_system_args = ["-s"]            # para codex

Quando cli_system_args está definido, as instruções são enviadas pelo canal de sistema nativo em vez de serem concatenadas ao stdin.

URL base personalizada (Bedrock, Vertex AI, proxies)

Todos os provedores suportam base_url opcional para endpoints personalizados:

# Anthropic via AWS Bedrock
[llm]
provider_type = "anthropic"
base_url = "https://bedrock-runtime.us-east-1.amazonaws.com"

# Gemini via Google Vertex AI
[llm]
provider_type = "gemini"
base_url = "https://us-central1-aiplatform.googleapis.com"

Configurações de contêiner (opcional)

[generation.container]
runtime = "podman"              # docker ou podman
timeout = 120                   # segundos
cleanup = true
# setup_commands = ["apt-get update && apt-get install -y cmake"]  # executar antes de dependências/testes

Comandos

skilldo generate [CAMINHO]

Gera um SKILL.md para um repositório de biblioteca.

Principais flags:

• --language <LINGUA> — força linguagem (python, javascript, rust, go, java). Detectada automaticamente se omitida
• --config <CAMINHO> — caminho do arquivo de configuração (padrão: ./skilldo.toml ou ~/.config/skilldo/config.toml)
• --model <MODELO> — substitui o modelo LLM
• --provider <PROVEDOR> — provedor LLM: anthropic, openai, chatgpt, gemini, openai-compatible
• --base-url <URL> — URL base para provedores openai-compatible
• -i, --input <CAMINHO> — SKILL.md existente para usar como referência para atualizações
• -o <CAMINHO> — arquivo de saída (padrão: SKILL.md)
• --debug-stage-files <DIR> — despeja a saída bruta de cada estágio do pipeline para depuração
• --replay-from <DIR> — carrega saídas em cache de estágios extract/map/learn de uma execução anterior --debug-stage-files, ignorando essas chamadas LLM. Reduz o tempo de iteração de ~15 minutos para ~5 minutos
• --no-test — pula validação de teste
• --no-review — pula validação de revisão
• --no-security-scan — pula varredura YARA/unicode/injeção
• --no-parallel — executa extract/map/learn sequencialmente (para modelos locais)
• --best-effort — sai com código 0 mesmo com erros
• --telemetry / --no-telemetry — alterna registro de execução
• --container — executa agente de teste em contêiner (padrão: bare-metal com uv/cargo)
• --install-source <MODO> — como o agente de teste instala a biblioteca para validação de código: registry (de crates.io/PyPI/npm, padrão), local-install (monta repositório local e constrói via gerenciador de pacotes), local-mount (monta repositório e define o caminho do módulo diretamente, sem etapa de construção)
• --source-path <CAMINHO> — caminho da fonte local para modos local-install/local-mount
• --test-mode <MODO> — thorough testa TODOS os padrões (padrão), quick testa até 3 para iteração rápida, minimal testa 1, adaptive começa com 1 e expande
• --review-model <MODELO> / --review-provider <PROVEDOR> — substitui modelo/provedor apenas para o estágio de revisão
• --test-model <MODELO> / --test-provider <PROVEDOR> — substitui modelo/provedor apenas para o estágio de geração de código de teste
• --max-retries <N> — máximo de repetições criar→validar antes de desistir (padrão: da configuração)
• --skill-version <VER> — força uma versão específica da biblioteca no frontmatter (ex.: "2.1.0") em vez de detecção automática
• --version-from <ESTRATEGIA> — como detectar a versão: package (Cargo.toml/pyproject.toml), git-tag, branch, commit
• -q, --quiet — suprime saída informativa (apenas avisos/erros)
• -v, --verbose — exibe saída de depuração detalhada (equivalente a RUST_LOG=debug)
• --request-timeout <SEGUNDOS> — substitui o tempo limite de requisição LLM em segundos (padrão: 120)
• --dry-run — usa cliente LLM simulado para teste (sem chamadas de API)

skilldo lint <CAMINHO>

Verifica um SKILL.md quanto a erros estruturais (frontmatter, seções, blocos de código).

skilldo review <CAMINHO>

Revisão baseada em LLM de um SKILL.md existente para precisão e segurança.

Principais flags:

• --config <CAMINHO> — configuração com definições LLM

skilldo config check --config <CAMINHO>

Valida um arquivo de configuração quanto à correção.

skilldo auth login|status|logout

Gerencia tokens OAuth para provedores que usam OAuth (ex.: ChatGPT).

Linguagens Suportadas

Linguagem	Ecossistema	Detecção
Python	pip/uv, pyproject.toml, setup.py	*.py, pyproject.toml
JavaScript/TypeScript	npm, package.json	*.js, *.ts, package.json
Go	go modules, go.mod	*.go, go.mod
Rust	cargo, Cargo.toml	*.rs, Cargo.toml
Java	Maven/Gradle, pom.xml, build.gradle	*.java, pom.xml, build.gradle

Configuração (skilldo.toml)

Campos principais de [generation]:

Campo	Valores	Descrição
language	python, javascript (ou typescript/ts/js), rust, go, java	Substitui detecção automática
security_context	"api-client" ou omitir	Relaxa varredura de segurança para SDKs de cliente de API que discutem credenciais/auth
redact_env_vars	["NOME_VAR", ...]	Valores de variáveis de ambiente mascarados com ***REDACTED*** na saída/logs de teste
custom_instructions	"""..."""	Instruções específicas do repositório para o estágio de criação (substitui regras de estilo/conteúdo)
enable_test	true/false	Alterna validação de teste (padrão: true)
enable_review	true/false	Alterna validação de revisão (padrão: true)
test_mode	thorough/quick/minimal/adaptive	Testa todos/até 3/1/1+ padrões
max_retries	inteiro	Máximo de repetições criar→validar (padrão: 10)

Comunicação do Modelo

O modelo relata incerteza por meio de comentários HTML na saída (removidos antes do SKILL.md final):

• <!-- SKILLDO-CONFLICT: descrição --> — conflitos entre documentação e código encontrados
• <!-- SKILLDO-UNVERIFIED: descrição --> — APIs que o modelo não conseguiu verificar a partir da fonte

Visualize-os com RUST_LOG=info ou RUST_LOG=debug. CONFLICT é registrado em info, UNVERIFIED em warn.

Fluxos de Trabalho Comuns

Gerar com Anthropic

source ~/.anthropic
skilldo generate --provider anthropic --model claude-sonnet-4-6

Gerar com OpenAI

source ~/.openai
skilldo generate --provider openai --model gpt-5.2

Gerar com Ollama local

skilldo generate --provider openai-compatible --model qwen3-coder:latest --base-url http://localhost:11434/v1

Geração em lote (vários repositórios)

for repo in /caminho/para/repos/*/; do
  skilldo generate "$repo" --config shared-config.toml --best-effort
done

Gerar para um SDK de cliente de API

# skilldo.toml — para bibliotecas que discutem chaves de API/auth
[generation]
security_context = "api-client"
redact_env_vars = ["MY_API_KEY"]

export MY_API_KEY="..."  # necessário para validação de teste
skilldo generate . --config skilldo.toml

Iteração rápida de prompt com replay

# Captura cache uma vez
skilldo generate /caminho/para/lib --debug-stage-files /tmp/cache -o /tmp/baseline.md

# Itera nos prompts (apenas estágio de criação executa, ~5 min vs ~15 min)
skilldo generate /caminho/para/lib --replay-from /tmp/cache -o /tmp/variant.md

Depurar estágios do pipeline

skilldo generate . --debug-stage-files ./debug-output/
# Escreve: 1-extract.md, 2-map.md, 3-learn.md, 4-create-raw.md, 4-create-system.md, facts.md,
#         5-review-*.txt, 6-normalized.md

Revisar um SKILL.md existente

skilldo review SKILL.md --config skilldo.toml

Telemetria

Quando telemetry = true, cada execução adiciona uma linha a ~/.skilldo/runs.csv:

• Timestamp, linguagem, nome da biblioteca, versão
• Modelos e provedores usados (generate, review, test)
• Passou/falhou, contagem de repetições, duração, detalhes da falha

Os dados são apenas locais — nada é enviado a lugar nenhum.

Solução de Problemas

• "Nenhum arquivo de teste encontrado" — um aviso, não um erro. O pipeline continua sem padrões derivados de teste. Use --language para substituir se a detecção estiver errada.
• Falhas de teste em loop — tente --test-mode minimal ou --no-test para uma primeira passagem.
• Limitação de taxa — aumente retry_delay na configuração, ou mude para um modelo local.
• Erros OAuth — execute skilldo auth status --config <caminho> para verificar o estado do token.
• Erros install_source em não-Python — local-install/local-mount funciona apenas para Python. Use o padrão registry para outras linguagens.

Documentação

Documentação completa — configuração, linguagens, arquitetura, autenticação, melhores práticas e telemetria: docs/