Skip to main content
O ChatCLI suporta um sistema de Skill Registry multi-registry que permite buscar, instalar e gerenciar skills de múltiplos registries simultaneamente. Skills instaladas ficam imediatamente disponíveis para uso com agentes via /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

Realiza busca fan-out paralela em todos os registries habilitados. Skills com o mesmo nome de registries diferentes aparecem separadamente (sem dedup cross-registry), permitindo comparar versões.
Indicadores visuais:
  • (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

Busca a skill, verifica flags de moderação e instala. Quando a mesma skill existe em múltiplos registries, o --from resolve a ambiguidade:
Outras formas de instalar:
Comportamento de segurança:
  • 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

Remove a skill instalada. Aceita tanto o nome base quanto o nome qualificado:

Listar Skills Instaladas

Exibe todas as skills instaladas com versão, origem e caminho.

Informações de uma Skill

Exibe metadados completos. Sem --from, prioriza o registry com dados mais ricos (skills.sh com installs e security). Com --from, consulta exclusivamente aquele registry.

Gerenciar Registries

Ativar/desativar registries tem efeito imediato — o registry manager é recriado em tempo real, sem necessidade de reiniciar o ChatCLI.

Preferências de Source

Quando múltiplas skills com o mesmo nome base estão instaladas (ex: local + skills.sh), o sistema de preferências define qual versão é usada pelo agente. Sem preferência, a local sempre ganha.
Cadeia de prioridade para resolução de skills:

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.
Exemplo:
O que pin faz exatamente:
  • Injeta a skill num bloco dedicado # Pinned Skills no system prompt, antes do bloco # Auto-loaded Skills. Em conflito de hints model: / 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 list mostra [fixada] ao lado das skills fixadas.
Restrições:
  • Skills com disable-model-invocation: true nã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:
Detalhes de cada modo, frontmatter e exemplos: veja Frontmatter avançado em Customizable Agents.

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:
Nada se perde — só é adiado: o modelo lê o arquivo quando (e somente quando) realmente aplicar a 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_TURNS turnos (default 6) colapsa para um stub de uma linha — a guidance completa é arquivada e recuperável via @recall, e o stub nomeia as skills e seus paths Source:, 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).
Skills pinadas e o bloco de startup ficam intocados — o aging vale só para injeções mid-loop de role user.
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.
As variáveis aparecem no /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:
O separador -- é 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:
Nomes qualificados só aparecem em contextos de gestão (info, uninstall) quando há conflito entre sources.

Snapshots do skills.sh

Skills instaladas do skills.sh preservam a estrutura original completa:
O SKILL.md recebe campos adicionais de proveniência:

Configuração

Arquivo de Registries

O arquivo ~/.chatcli/registries.yaml controla os registries:
O arquivo é criado automaticamente na primeira execução. Novos registries padrão são mergeados automaticamente após upgrades.

Arquivo de Preferências

O arquivo ~/.chatcli/skill-preferences.yaml armazena preferências de source:
Gerenciado exclusivamente via /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


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:
  1. Conteúdo baixado para diretório temporário (.tmp-*)
  2. Frontmatter YAML validado
  3. Flags de moderação verificadas
  4. Scripts recebem permissão executável
  5. Campo source e snapshot_hash injetados no frontmatter
  6. Diretório renomeado atomicamente para o destino final
  7. 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:
  1. Skills são instaladas em ~/.chatcli/skills/<qualified-name>/SKILL.md
  2. O Loader do sistema de personas escaneia o diretório e resolve por nome do frontmatter (base name)
  3. /agent skills lista skills disponíveis
  4. Auto-ativação por triggers e paths funciona transparentemente
  5. Invocação manual via /<skill-name> resolve pelo base name
  6. 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