Pular para o conteúdo principal
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

ConceitoDescrição
RegistryUm servidor remoto que hospeda skills pesquisáveis e instaláveis
SkillUm arquivo SKILL.md com frontmatter YAML que define comportamento especializado para agentes
SnapshotPacote completo de uma skill (SKILL.md + scripts/ + references/ + assets/) baixado atomicamente
Fan-out SearchBusca paralela em todos os registries habilitados, com resultados mesclados
Qualified NameNome de diretório com prefixo de source (ex: anthropics-skills--frontend-design) para evitar colisões
ModerationFlags de segurança (malware, conteúdo suspeito) fornecidas pelos registries
Security AuditsAvaliações de segurança de parceiros (Gen Agent Trust Hub, Socket, Snyk) via skills.sh
Trigram CacheCache fuzzy local que evita requisições de rede para buscas similares

​
Registries Padrão

O ChatCLI vem configurado com três registries:
RegistryURLTipoDescrição
chatclihttps://registry.chatcli.dev/api/v1REST APIRegistry oficial do ChatCLI
clawhubhttps://clawhub.ai/api/v1REST APIMarketplace público de skills (ClawHub)
skills.shhttps://skills.shSnapshot APIDiretório aberto de agent skills (Vercel/Anthropic)
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

/skill search <query>
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. 
/skill search frontend-design

  Searching registries for "frontend-design"...

  Results (5 found):

    1. frontend-design  (214K installs)  by anthropics  [skills.sh]
       (anthropics/skills/frontend-design)

    2. Frontend Design                                   [clawhub]
       Create distinctive, production-grade frontend interfaces...

    3. frontend-design                                   [clawhub] [installed from other source]
       Visual design and aesthetic direction for frontend interfaces...

    4. frontend-design-system  (4.6K installs)  by supercent-io  [skills.sh]
       (supercent-io/skills-template/frontend-design-system)

  Use /skill install <name> to install a skill.
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

/skill install <name> [--from <registry>]
Busca a skill, verifica flags de moderação e instala. Quando a mesma skill existe em múltiplos registries, o --from resolve a ambiguidade: 
# Ambíguo — múltiplos registries têm "frontend-design"
/skill install frontend-design

  Skill "frontend-design" found in multiple registries:

    1. [clawhub]
       Create distinctive, production-grade frontend interfaces...
    2. [skills.sh]  (214K installs)
       Create distinctive, production-grade frontend interfaces...

  Use /skill install frontend-design --from <registry> to choose.

# Explícito — instalar do skills.sh
/skill install frontend-design --from skills.sh

  Installing frontend-design from skills.sh...
  Installed anthropics-skills--frontend-design from skills.sh
  Path: ~/.chatcli/skills/anthropics-skills--frontend-design/

  Skill 'anthropics-skills--frontend-design' is now available.
  Verify with: /agent skills
Outras formas de instalar: 
# Slug do skills.sh (sempre unambíguo)
/skill install anthropics/skills/frontend-design

# Se só um registry tem a skill, instala direto
/skill install k8s-ops
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

/skill uninstall <name>
Remove a skill instalada. Aceita tanto o nome base quanto o nome qualificado: 
# Se só uma versão existe, remove direto
/skill uninstall k8s-ops

  Removing skill clawhub--k8s-ops...
  Done. Skill 'clawhub--k8s-ops' uninstalled.

# Se múltiplas versões existem, pede especificação
/skill uninstall frontend-design

  Multiple skills matching "frontend-design" found from different sources:

    1. frontend-design                        [local]
    2. anthropics-skills--frontend-design      [skills.sh]

  Use the full name to specify which one to uninstall.

# Explícito
/skill uninstall anthropics-skills--frontend-design

​
Listar Skills Instaladas

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

  Installed Skills (3):

    anthropics-skills--frontend-design         [skills.sh]
    clawhub--code-review           v1.2.0      [clawhub]
    my-local-skill                             [local]

  Registries (3):
    chatcli   https://registry.chatcli.dev/api/v1  [disabled]
    clawhub   https://clawhub.ai/api/v1            [enabled]
    skills.sh https://skills.sh                    [enabled]

​
Informações de uma Skill

/skill info <name> [--from <registry>]
Exibe metadados completos. Sem --from, prioriza o registry com dados mais ricos (skills.sh com installs e security). Com --from, consulta exclusivamente aquele registry. 
/skill info frontend-design

  Name:     frontend-design
  Desc:     Create distinctive, production-grade frontend interfaces...
  Author:   anthropics
  Source:   skills.sh
  Tags:     license:Apache-2.0
  Installs: 214K
  Repo:     https://github.com/anthropics/skills
  Page:     https://skills.sh/anthropics/skills/frontend-design
  Security:
    Gen Agent Trust Hub: Safe
    Socket:              0 alerts
    Snyk:                Low Risk
  Status:   installed (2 sources)
    frontend-design                           [local]     ~/.chatcli/skills/frontend-design
    anthropics-skills--frontend-design        [skills.sh] ~/.chatcli/skills/anthropics-skills--frontend-design

# Forçar metadata do clawhub
/skill info frontend-design --from clawhub

  Name:     Frontend Design
  Desc:     Create distinctive, production-grade...
  Version:  1.0.0
  Author:   anthropics
  Source:   clawhub
  Downloads: 5200
  Status:   installed from other source

​
Gerenciar Registries

/skill registries                       # listar
/skill registry enable <name>           # ativar (hot-reload)
/skill registry disable <name>          # desativar (hot-reload)
Ativar/desativar registries tem efeito imediato — o registry manager é recriado em tempo real, sem necessidade de reiniciar o ChatCLI. 
/skill registries

  Configured Registries:

    1. chatcli       https://registry.chatcli.dev/api/v1  [disabled]
    2. clawhub       https://clawhub.ai/api/v1            [enabled]
    3. skills.sh     https://skills.sh                    [enabled]

  Config: ~/.chatcli/registries.yaml
  Use /skill registry enable|disable <name> to toggle.

/skill registry disable clawhub

  Disabled clawhub

​
Preferências de Source

/skill prefer                              # listar preferências
/skill prefer <name>                       # ver preferência atual + fontes
/skill prefer <name> <source>              # definir preferência
/skill prefer <name> --reset               # remover preferência
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. 
# Ver situação atual
/skill prefer frontend-design

  Preference: frontend-design (default -- local wins)

  Available sources:
    frontend-design                           [local]
    anthropics-skills--frontend-design        [skills.sh] <- preferred

# Preferir a versão do skills.sh
/skill prefer frontend-design skills.sh

  Preference set: frontend-design -> skills.sh
  This takes effect on the next skill activation.

# Voltar ao padrão
/skill prefer frontend-design --reset

  Preference removed for frontend-design
Cadeia de prioridade para resolução de skills:
PrioridadeCondição
1 (maior)Preferência do usuário via /skill prefer
2Skill local no projeto (.agent/skills/)
3Skill local global (~/.chatcli/skills/nome-exato/)
4Skill de registry global (~/.chatcli/skills/source--nome/)

​
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. 
/skill pin <nome>      # Fixa a skill na sessão atual
/skill unpin <nome>    # Remove do conjunto fixado
/skill pinned          # Lista as skills fixadas
Exemplo: 
/skill pin go-testing

  Skill fixada: go-testing
  Será injetada em todo turno até /skill unpin.

# Próximas mensagens — go-testing aparece no system prompt mesmo
# que a mensagem não mencione "test" ou arquivos *_test.go

/skill pinned

  Skills fixadas nesta sessão (1):

    go-testing  Padrões de teste em Go

/skill unpin go-testing

  Skill removida do conjunto fixado: go-testing
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

ModoComo disparaEscopoFrontmatter necessário
Auto-activationtriggers: (substring keyword) ou paths: (glob contra paths do input) batemper-turn (re-avalia toda mensagem)triggers: ou paths: (sem disable-model-invocation: true)
Manual /<skill-name>Usuário digita /<nome>single-turnuser-invocable: true
Pin /skill pin <name>Usuário fixou explicitamentesessão inteiraqualquer (exceto disable-model-invocation: true)
Precedência de hints model:/effort: quando múltiplos modos disparam no mesmo turno: 
manual > pinned > auto-activated
Detalhes de cada modo, frontmatter e exemplos: veja Frontmatter avançado em Customizable Agents.

​
Ajuda

/skill help

  Skill Registry Commands:
  --------------------------------------------------

    /skill search <query>                Search for skills across registries
    /skill install <name> [--from <reg>] Install a skill from a registry
    /skill uninstall <name>              Remove an installed skill
    /skill list                          List installed skills
    /skill info <name> [--from <reg>]    Show skill details (local + registry)
    /skill registries                    Show configured registries
    /skill registry enable|disable <name> Enable or disable a registry
    /skill prefer [name] [source]        Set preferred source for conflicting skills
    /skill pin <name>                    Pin a skill for the session
    /skill unpin <name>                  Remove a skill from the pinned set
    /skill pinned                        List pinned skills
    /skill help                          Show this help

​
Namespace e Colisões

​
Como Skills São Armazenadas no Disco

Skills de registries usam nomes qualificados para evitar colisões: 
~/.chatcli/skills/
  frontend-design/                           # local (sem prefixo)
    SKILL.md
  anthropics-skills--frontend-design/         # skills.sh (owner-repo--name)
    SKILL.md
    scripts/
    references/
    assets/
  clawhub--code-review/                       # clawhub (registry--name)
    SKILL.md
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: 
# Invocar skill pelo nome base — funciona
/frontend-design

# Triggers automáticos — funcionam pelo frontmatter name
# Auto-complete — mostra nomes limpos (do frontmatter)
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: 
anthropics-skills--frontend-design/
  SKILL.md                    # frontmatter original preservado
  scripts/
    lint.sh                   # permissão executável preservada
  references/
    REFERENCE.md              # documentação sob demanda
  assets/
    template.html             # recursos estáticos
O SKILL.md recebe campos adicionais de proveniência: 
---
name: frontend-design
description: ...
source: "skills.sh"
snapshot_hash: "abc123def456"
---

​
Configuração

​
Arquivo de Registries

O arquivo ~/.chatcli/registries.yaml controla os registries: 
registries:
  - name: chatcli
    url: https://registry.chatcli.dev/api/v1
    enabled: true
    cache_ttl: 15m
    type: chatcli
  - name: clawhub
    url: https://clawhub.ai/api/v1
    enabled: true
    cache_ttl: 5m
    type: clawhub
  - name: skills.sh
    url: https://skills.sh
    enabled: true
    cache_ttl: 10m
    type: skillssh
  # Custom registry:
  - name: my-company
    url: https://skills.mycompany.com/api/v1
    enabled: true
    cache_ttl: 10m
    type: custom
    token: "my-auth-token"  # optional
install_dir: ~/.chatcli/skills
max_concurrent: 3
search_cache_size: 50
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: 
preferences:
  frontend-design: "skills.sh"
  code-review: "clawhub"
Gerenciado exclusivamente via /skill prefer — não precisa editar manualmente.

​
Variáveis de Ambiente

VariávelDescrição
CHATCLI_REGISTRY_URLSURLs adicionais de registries (separadas por vírgula)
CHATCLI_REGISTRY_DISABLENomes de registries a desabilitar (separados por vírgula)
CHATCLI_SKILL_INSTALL_DIRDiretório de instalação (padrão: ~/.chatcli/skills)

​
Registry Customizado

Qualquer servidor que implemente a API REST padrão pode ser usado como registry customizado:

​
Endpoints Esperados

EndpointMétodoDescrição
/skills/search?q=<query>GETBusca skills. Retorna {"skills": [...]} ou [...]
/skills/<slug>GETMetadados de uma skill específica
/skills/<slug>/downloadGETDownload do conteúdo da skill
{
  "skills": [
    {
      "name": "my-skill",
      "slug": "my-skill",
      "description": "Description here",
      "version": "1.0.0",
      "author": "author",
      "tags": ["go", "devops"],
      "downloads": 150,
      "download_url": "https://...",
      "moderation": {
        "malware_detected": false,
        "suspicious_content": false,
        "quarantined": false
      }
    }
  ]
}

​
Segurança e Moderação

​
Flags de Moderação

FlagComportamento
malware_detectedBLOQUEIO TOTAL — instalação recusada automaticamente
quarantinedBLOQUEIO TOTAL — skill em quarentena pelo registry
suspicious_contentAVISO — exibe warning e pede confirmação do usuário

​
Security Audits (skills.sh)

Para skills do skills.sh, o /skill info exibe avaliações de segurança de três provedores parceiros:
ProvedorO que avalia
Gen Agent Trust Hub (ATH)Análise de risco geral (safe/low/medium/high/critical)
SocketContagem de alertas de segurança
SnykAnálise de risco de dependências
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:
ParâmetroValor Padrão
Tamanho máximo50 entradas
TTL por entrada5 minutos
Threshold de similaridade0.7 (Jaccard)
EvicçãoLRU (Least Recently Used)
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: 
/skill [TAB]          # subcomandos: search, install, info, ...
/skill install [TAB]  # após nome: --from
/skill install frontend-design --from [TAB]  # nomes de registries
/skill registry [TAB] # enable, disable
/skill registry disable [TAB]  # nomes de registries
/skill prefer frontend-design [TAB]  # --reset, nomes de registries, local

​
Arquitetura

/skill commands (cli/skill_handler.go)
        |
        v
RegistryManager (pkg/registry/manager.go) -- coordenador fan-out
        |
        |---> ChatCLIRegistry (registry.chatcli.dev)   -- REST API
        |---> ClawHubRegistry (clawhub.ai)              -- REST API
        |---> SkillsShRegistry (skills.sh)              -- Search + Snapshot + Audit APIs
        +---> CustomRegistry  (registries do usuário)   -- REST API
        |
        |  resultados mesclados (sem dedup cross-registry)
        |
        |---> Install -> Installer -> escrita atômica
        |     |---> Install() para REST registries (buildSkillMD)
        |     +---> InstallFromSnapshot() para skills.sh (preserva estrutura)
        |
        v
SkillPreferences (pkg/registry/skill_preferences.go)
        |
        v
pkg/persona/Loader (pkg/persona/loader.go)
        |---> GetSkill() resolve por: preferência > nome exato > base name
        +---> ListSkills() dedup por frontmatter name, aplica preferências

​
Pacotes

PacoteArquivoResponsabilidade
pkg/registry/interface.goTipos: SkillMeta, SnapshotFile, InstalledSkillInfo
manager.goFan-out search, Install, InstallFrom, GetAllSkillMeta
installer.goInstall, InstallFromSnapshot, qualified names, FindInstalled
skillssh_registry.goAdapter skills.sh (Search, Download, Audit, enrichMeta)
clawhub_registry.goAdapter ClawHub
chatcli_registry.goAdapter ChatCLI.dev
custom_registry.goAdapter genérico REST
skill_preferences.goPreferências de source por skill
config.goConfiguração, mergeDefaultRegistries
moderation.goFlags de segurança
trigram.goCache fuzzy de busca
cli/skill_handler.goComandos /skill (search, install, info, prefer, registry)
skill_activation.goAuto-ativação por triggers e paths
skill_invoke.goInvocação manual via /<skill-name>
cli_completer.goAutocomplete contextual
pkg/persona/loader.goGetSkill (resolução por preferência + qualified), ListSkills (dedup)

​
Próximos Passos