/agent skills.
Conceitos
Registries Padrão
O ChatCLI vem configurado com três registries:
Novos registries padrão são adicionados automaticamente após upgrades — sem necessidade de editar o config manualmente.
skills.sh
O skills.sh é o diretório aberto de agent skills, compatível com 30+ agentes (Claude Code, Cursor, Codex, Gemini CLI, etc.). Skills hospedadas no GitHub são indexadas com métricas de instalação e auditorias de segurança. O ChatCLI consome 3 APIs do skills.sh:- Search API — busca fuzzy com contagem de instalações
- Download API — snapshots pré-empacotados com todos os arquivos da skill
- Audit API — avaliações de segurança de parceiros (ATH, Socket, Snyk)
Comandos /skill
Buscar Skills
(214K installs)— contagem de instalações (skills.sh)[installed](verde) — skill instalada daquele registry[installed from other source](amarelo) — existe uma com mesmo nome de outro lugar[SUSPICIOUS]/[BLOCKED]— flags de moderação
Instalar Skill
--from resolve a ambiguidade:
- Skills com malware detectado são bloqueadas automaticamente
- Skills suspeitas exibem aviso e pedem confirmação
- Skills já instaladas da mesma source são atualizadas (substituídas)
- Skills de sources diferentes coexistem (nomes qualificados no disco)
Desinstalar Skill
Listar Skills Instaladas
Informações de uma Skill
--from, prioriza o registry com dados mais ricos (skills.sh com installs e security). Com --from, consulta exclusivamente aquele registry.
Gerenciar Registries
Preferências de Source
Fixar Skills na Sessão (/skill pin)
Quando você quer que uma skill seja considerada em todo turno da conversa — independente de a mensagem casar com seus triggers: ou paths: — fixe ela com /skill pin. A skill fica injetada no system prompt até você dar /skill unpin ou encerrar a sessão.
- Injeta a skill num bloco dedicado
# Pinned Skillsno system prompt, antes do bloco# Auto-loaded Skills. Em conflito de hintsmodel:/effort:, pinned vence sobre auto-activation (mas perde para/<skill-name>manual). - Bloco pinned carrega
cache_control: ephemeral— provider mantém cache quente entre turns enquanto o conjunto fixado não muda. - Auto-activation continua rodando: se uma skill é fixada e casa por
triggers:/paths:, é injetada uma única vez (dedup por nome). - Skills desinstaladas/renomeadas durante a sessão saem do conjunto silenciosamente no próximo turno (re-resolvidas via persona manager).
/skill listmostra[fixada]ao lado das skills fixadas.
- Skills com
disable-model-invocation: truenão podem ser fixadas — o flag existe justamente pra proibir injeção automática. Use/<skill-name>manual nesses casos. - O conjunto fixado é por sessão; não persiste entre execuções do chatcli (por design — fixar é uma intenção de uso atual).
Como Ativar uma Skill: Três Modos
Precedência de hints
model:/effort: quando múltiplos modos disparam no mesmo turno:
Budget de Injeção de Skills
Os corpos de skills injetadas respeitam um budget de caracteres por bloco:CHATCLI_SKILL_INJECT_BUDGET (default 24000, 0 = ilimitado/legado). Sobre ele, um budget por execução de 2× esse valor limita os bytes cumulativos de skill que um run de agent/coder pode injetar (startup + mid-loop); esgotado, ativações posteriores ainda se anunciam mas os corpos degradam do mesmo jeito. As skills são renderizadas na ordem estável; cada entrada agora carrega uma linha Source: <path>, e esgotado um budget, as seguintes mantêm header e descrição mas o corpo degrada para um ponteiro de leitura on-demand no arquivo-fonte da skill:
Ciclo de vida de skills: aging, cooldown e drip (agent/coder)
Injeções de skill mid-loop não viajam mais na janela pelo run inteiro. Três mecanismos limitam o footprint:- Aging: um bloco de skill mid-loop mais velho que
CHATCLI_SKILL_AGE_TURNSturnos (default6) colapsa para um stub de uma linha — a guidance completa é arquivada e recuperável via@recall, e o stub nomeia as skills e seus pathsSource:, então nada fica inalcançável. - Cooldown + re-ativação: uma skill colapsada sai do dedup set do run. Se o trigger disparar de novo após o cooldown (mesmo número de turnos), a skill re-injeta fresca — aging é ejeção, não amnésia.
- Drip cap: no máximo 3 skills novas por injeção mid-loop; uma rajada de matches pinga entre turn boundaries em vez de cair como um bloco gigante (as que passaram do cap re-candidatam no próximo boundary, nenhuma é dropada).
Por que isso existe: um único prompt pode auto-ativar uma rajada de skills (ex.: nove skills de ServiceNow casando com uma pergunta), somando dezenas de KB a cada requisição subsequente. Atrás de um proxy/WAF corporativo com limite de tamanho de corpo, só isso já empurra a sessão para além do limiar de rejeição — veja Context Recovery. O default é generoso: sessões típicas inlinam todas as skills ativadas sem corte.
/config agent (seção de eficiência de tokens) — CHATCLI_SKILL_INJECT_BUDGET e CHATCLI_SKILL_AGE_TURNS.
Ajuda
Namespace e Colisões
Como Skills São Armazenadas no Disco
Skills de registries usam nomes qualificados para evitar colisões:-- é seguro porque a spec do agentskills.io proíbe hífens consecutivos em nomes de skills.
O Usuário Nunca Precisa Digitar Nomes Qualificados
O uso diário é transparente:Snapshots do skills.sh
Skills instaladas do skills.sh preservam a estrutura original completa:SKILL.md recebe campos adicionais de proveniência:
Configuração
Arquivo de Registries
O arquivo~/.chatcli/registries.yaml controla os registries:
Arquivo de Preferências
O arquivo~/.chatcli/skill-preferences.yaml armazena preferências de source:
/skill prefer — não precisa editar manualmente.
Variáveis de Ambiente
Registry Customizado
Qualquer servidor que implemente a API REST padrão pode ser usado como registry customizado:Endpoints Esperados
Formato de Resposta (Search)
Segurança e Moderação
Flags de Moderação
Security Audits (skills.sh)
Para skills do skills.sh, o/skill info exibe avaliações de segurança de três provedores parceiros:
Os dados são obtidos da API
https://add-skill.vercel.sh/audit com timeout de 3 segundos — falhas são silenciosas (dados advisory, nunca bloqueiam).
Instalação Atômica
Skills são instaladas usando escrita atômica:- Conteúdo baixado para diretório temporário (
.tmp-*) - Frontmatter YAML validado
- Flags de moderação verificadas
- Scripts recebem permissão executável
- Campo
sourceesnapshot_hashinjetados no frontmatter - Diretório renomeado atomicamente para o destino final
- Em caso de falha, diretório temporário removido automaticamente
Proteção contra Path Traversal
- Nomes sanitizados (lowercase, sem
.., sem/) - Paths em snapshots validados (rejeita
..e paths absolutos) - Separador
--impede confusão entre nomes qualificados e paths
Cache de Busca (Trigram)
O ChatCLI implementa um cache fuzzy baseado em trigramas para reduzir chamadas de rede:
O cache é invalidado automaticamente após instalar ou desinstalar uma skill, e é recriado ao ativar/desativar um registry.
Integração com Agentes
Skills instaladas ficam automaticamente disponíveis para o sistema de agentes:- Skills são instaladas em
~/.chatcli/skills/<qualified-name>/SKILL.md - O
Loaderdo sistema de personas escaneia o diretório e resolve por nome do frontmatter (base name) /agent skillslista skills disponíveis- Auto-ativação por triggers e paths funciona transparentemente
- Invocação manual via
/<skill-name>resolve pelo base name - Preferências (
/skill prefer) controlam qual versão ganha em caso de conflito
Autocomplete
O tab-complete oferece sugestões contextuais:Arquitetura
Pacotes
Próximos Passos
- Customizable Agents — Como criar e usar agentes com skills
- Referência de Comandos — Lista completa de todos os comandos
- Configuração (.env) — Variáveis de ambiente disponíveis