> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Skill Registry

> Busque, instale e gerencie skills de múltiplos registries — skills.sh, ClawHub, ChatCLI.dev e registries customizados.

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

| Conceito            | Descrição                                                                                               |
| ------------------- | ------------------------------------------------------------------------------------------------------- |
| **Registry**        | Um servidor remoto que hospeda skills pesquisáveis e instaláveis                                        |
| **Skill**           | Um arquivo `SKILL.md` com frontmatter YAML que define comportamento especializado para agentes          |
| **Snapshot**        | Pacote completo de uma skill (SKILL.md + scripts/ + references/ + assets/) baixado atomicamente         |
| **Fan-out Search**  | Busca paralela em todos os registries habilitados, com resultados mesclados                             |
| **Qualified Name**  | Nome de diretório com prefixo de source (ex: `anthropics-skills--frontend-design`) para evitar colisões |
| **Moderation**      | Flags de segurança (malware, conteúdo suspeito) fornecidas pelos registries                             |
| **Security Audits** | Avaliações de segurança de parceiros (Gen Agent Trust Hub, Socket, Snyk) via skills.sh                  |
| **Trigram Cache**   | Cache fuzzy local que evita requisições de rede para buscas similares                                   |

***

## Registries Padrão

O ChatCLI vem configurado com três registries:

| Registry      | URL                                   | Tipo         | Descrição                                           |
| ------------- | ------------------------------------- | ------------ | --------------------------------------------------- |
| **chatcli**   | `https://registry.chatcli.dev/api/v1` | REST API     | Registry oficial do ChatCLI                         |
| **clawhub**   | `https://clawhub.ai/api/v1`           | REST API     | Marketplace público de skills (ClawHub)             |
| **skills.sh** | `https://skills.sh`                   | Snapshot API | Diretó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](https://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

```bash theme={"system"}
/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.

```text theme={"system"}
/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

```bash theme={"system"}
/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:

```text theme={"system"}
# 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:

```bash theme={"system"}
# 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

```bash theme={"system"}
/skill uninstall <name>
```

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

```text theme={"system"}
# 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

```bash theme={"system"}
/skill list
```

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

```text theme={"system"}
/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

```bash theme={"system"}
/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.

```text theme={"system"}
/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

```bash theme={"system"}
/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.

```text theme={"system"}
/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

```bash theme={"system"}
/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.**

```text theme={"system"}
# 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:**

| Prioridade | Condição                                                     |
| ---------- | ------------------------------------------------------------ |
| 1 (maior)  | Preferência do usuário via `/skill prefer`                   |
| 2          | Skill local no projeto (`.agent/skills/`)                    |
| 3          | Skill local global (`~/.chatcli/skills/nome-exato/`)         |
| 4          | Skill 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.

```bash theme={"system"}
/skill pin <nome>      # Fixa a skill na sessão atual
/skill unpin <nome>    # Remove do conjunto fixado
/skill pinned          # Lista as skills fixadas
```

**Exemplo:**

```bash theme={"system"}
/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

| Modo                        | Como dispara                                                                   | Escopo                             | Frontmatter necessário                                         |
| --------------------------- | ------------------------------------------------------------------------------ | ---------------------------------- | -------------------------------------------------------------- |
| **Auto-activation**         | `triggers:` (substring keyword) ou `paths:` (glob contra paths do input) batem | per-turn (re-avalia toda mensagem) | `triggers:` ou `paths:` (sem `disable-model-invocation: true`) |
| **Manual `/<skill-name>`**  | Usuário digita `/<nome>`                                                       | single-turn                        | `user-invocable: true`                                         |
| **Pin `/skill pin <name>`** | Usuário fixou explicitamente                                                   | sessão inteira                     | qualquer (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](/pt/features/customizable-agents#padroes-avancados-de-frontmatter).

### Ajuda

```bash theme={"system"}
/skill help
```

```text theme={"system"}
  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:

```text theme={"system"}
~/.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](https://agentskills.io/specification) proíbe hífens consecutivos em nomes de skills.

### O Usuário Nunca Precisa Digitar Nomes Qualificados

O uso diário é transparente:

```bash theme={"system"}
# 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:

```text theme={"system"}
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:

```yaml theme={"system"}
---
name: frontend-design
description: ...
source: "skills.sh"
snapshot_hash: "abc123def456"
---
```

***

## Configuração

### Arquivo de Registries

O arquivo `~/.chatcli/registries.yaml` controla os registries:

```yaml theme={"system"}
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:

```yaml theme={"system"}
preferences:
  frontend-design: "skills.sh"
  code-review: "clawhub"
```

Gerenciado exclusivamente via `/skill prefer` — não precisa editar manualmente.

### Variáveis de Ambiente

| Variável                    | Descrição                                                 |
| --------------------------- | --------------------------------------------------------- |
| `CHATCLI_REGISTRY_URLS`     | URLs adicionais de registries (separadas por vírgula)     |
| `CHATCLI_REGISTRY_DISABLE`  | Nomes de registries a desabilitar (separados por vírgula) |
| `CHATCLI_SKILL_INSTALL_DIR` | Diretó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

| Endpoint                   | Método | Descrição                                            |
| -------------------------- | ------ | ---------------------------------------------------- |
| `/skills/search?q=<query>` | GET    | Busca skills. Retorna `{"skills": [...]}` ou `[...]` |
| `/skills/<slug>`           | GET    | Metadados de uma skill específica                    |
| `/skills/<slug>/download`  | GET    | Download do conteúdo da skill                        |

### Formato de Resposta (Search)

```json theme={"system"}
{
  "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

| Flag                 | Comportamento                                            |
| -------------------- | -------------------------------------------------------- |
| `malware_detected`   | **BLOQUEIO TOTAL** — instalação recusada automaticamente |
| `quarantined`        | **BLOQUEIO TOTAL** — skill em quarentena pelo registry   |
| `suspicious_content` | **AVISO** — 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:

| Provedor                      | O que avalia                                           |
| ----------------------------- | ------------------------------------------------------ |
| **Gen Agent Trust Hub (ATH)** | Análise de risco geral (safe/low/medium/high/critical) |
| **Socket**                    | Contagem de alertas de segurança                       |
| **Snyk**                      | Aná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âmetro                 | Valor Padrão              |
| ------------------------- | ------------------------- |
| Tamanho máximo            | 50 entradas               |
| TTL por entrada           | 5 minutos                 |
| Threshold de similaridade | 0.7 (Jaccard)             |
| Evicção                   | LRU (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:

```bash theme={"system"}
/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

```text theme={"system"}
/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

| Pacote          | Arquivo                | Responsabilidade                                                     |
| --------------- | ---------------------- | -------------------------------------------------------------------- |
| `pkg/registry/` | `interface.go`         | Tipos: SkillMeta, SnapshotFile, InstalledSkillInfo                   |
|                 | `manager.go`           | Fan-out search, Install, InstallFrom, GetAllSkillMeta                |
|                 | `installer.go`         | Install, InstallFromSnapshot, qualified names, FindInstalled         |
|                 | `skillssh_registry.go` | Adapter skills.sh (Search, Download, Audit, enrichMeta)              |
|                 | `clawhub_registry.go`  | Adapter ClawHub                                                      |
|                 | `chatcli_registry.go`  | Adapter ChatCLI.dev                                                  |
|                 | `custom_registry.go`   | Adapter genérico REST                                                |
|                 | `skill_preferences.go` | Preferências de source por skill                                     |
|                 | `config.go`            | Configuração, mergeDefaultRegistries                                 |
|                 | `moderation.go`        | Flags de segurança                                                   |
|                 | `trigram.go`           | Cache fuzzy de busca                                                 |
| `cli/`          | `skill_handler.go`     | Comandos /skill (search, install, info, prefer, registry)            |
|                 | `skill_activation.go`  | Auto-ativação por triggers e paths                                   |
|                 | `skill_invoke.go`      | Invocação manual via `/<skill-name>`                                 |
|                 | `cli_completer.go`     | Autocomplete contextual                                              |
| `pkg/persona/`  | `loader.go`            | GetSkill (resolução por preferência + qualified), ListSkills (dedup) |

***

## Próximos Passos

* [**Customizable Agents**](/pt/features/customizable-agents) — Como criar e usar agentes com skills
* [**Referência de Comandos**](/pt/reference/command-reference) — Lista completa de todos os comandos
* [**Configuração (.env)**](/pt/reference/configuration) — Variáveis de ambiente disponíveis