> ## 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

> Search, install and manage skills from multiple registries — skills.sh, ClawHub, ChatCLI.dev, and custom registries.

ChatCLI supports a multi-registry **Skill Registry** system that lets you search, install, and manage skills from multiple registries simultaneously. Installed skills are immediately available for use with agents via `/agent skills`.

***

## Concepts

| Concept | Description |
| - | - |
| **Registry** | A remote server hosting searchable and installable skills |
| **Skill** | A `SKILL.md` file with YAML frontmatter defining specialized agent behavior |
| **Snapshot** | Complete skill package (SKILL.md + scripts/ + references/ + assets/) downloaded atomically |
| **Fan-out Search** | Parallel search across all enabled registries with merged results |
| **Qualified Name** | Directory name prefixed with source (e.g. `anthropics-skills--frontend-design`) to avoid collisions |
| **Moderation** | Safety flags (malware, suspicious content) provided by registries |
| **Security Audits** | Partner security assessments (Gen Agent Trust Hub, Socket, Snyk) via skills.sh |
| **Trigram Cache** | Local fuzzy cache that avoids network requests for similar queries |

***

## Default Registries

ChatCLI ships with three registries:

| Registry | URL | Type | Description |
| - | - | - | - |
| **chatcli** | `https://registry.chatcli.dev/api/v1` | REST API | Official ChatCLI registry |
| **clawhub** | `https://clawhub.ai/api/v1` | REST API | Public skills marketplace (ClawHub) |
| **skills.sh** | `https://skills.sh` | Snapshot API | Open agent skills directory (Vercel/Anthropic) |

New default registries are automatically added after upgrades — no need to edit config manually.

### skills.sh

[skills.sh](https://skills.sh) is the open agent skills directory, compatible with 30+ agents (Claude Code, Cursor, Codex, Gemini CLI, etc.). Skills hosted on GitHub are indexed with installation metrics and security audits.

ChatCLI consumes 3 skills.sh APIs:

* **Search API** — fuzzy search with install counts
* **Download API** — pre-packaged snapshots with all skill files
* **Audit API** — partner security assessments (ATH, Socket, Snyk)

***

## `/skill` Commands

### Search Skills

```bash theme={"system"}
/skill search <query>
```

Performs a parallel fan-out search across all enabled registries. Skills with the same name from different registries appear separately (no cross-registry dedup), allowing you to compare versions.

```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-system  (4.6K installs)  by supercent-io  [skills.sh]
       (supercent-io/skills-template/frontend-design-system)

  Use /skill install <name> to install a skill.
```

Visual indicators:

* **`(214K installs)`** — install count (skills.sh)
* **`[installed]`** (green) — skill installed from that registry
* **`[installed from other source]`** (yellow) — same-name skill exists from another source
* **`[SUSPICIOUS]`** / **`[BLOCKED]`** — moderation flags

### Install Skill

```bash theme={"system"}
/skill install <name> [--from <registry>]
```

Searches for the skill, checks moderation flags, and installs. When the same skill exists in multiple registries, `--from` resolves the ambiguity:

```text theme={"system"}
# Ambiguous — multiple registries have "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.

# Explicit — install from 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/
```

Other ways to install:

```bash theme={"system"}
# skills.sh slug (always unambiguous)
/skill install anthropics/skills/frontend-design

# If only one registry has it, installs directly
/skill install k8s-ops
```

### Uninstall Skill

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

Removes an installed skill. Accepts both base name and qualified name. When multiple versions exist, lists them for disambiguation.

### List Installed Skills

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

Displays all installed skills with version, source, and path.

### Skill Info

```bash theme={"system"}
/skill info <name> [--from <registry>]
```

Shows full metadata. Without `--from`, prioritizes the registry with richest data (skills.sh with installs and security). With `--from`, queries only that registry.

```text theme={"system"}
/skill info frontend-design

  Name:     frontend-design
  Desc:     Create distinctive, production-grade frontend interfaces...
  Author:   anthropics
  Source:   skills.sh
  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]
    anthropics-skills--frontend-design        [skills.sh]
```

### Manage Registries

```bash theme={"system"}
/skill registries                       # list
/skill registry enable <name>           # enable (hot-reload)
/skill registry disable <name>          # disable (hot-reload)
```

Enable/disable takes **immediate effect** — the registry manager is recreated in real-time, no ChatCLI restart needed.

### Source Preferences

```bash theme={"system"}
/skill prefer                              # list all preferences
/skill prefer <name>                       # show current preference + sources
/skill prefer <name> <source>              # set preference
/skill prefer <name> --reset               # remove preference
```

When multiple skills with the same base name are installed (e.g. local + skills.sh), preferences control which version the agent uses. **Without a preference, local always wins.**

**Priority chain for skill resolution:**

| Priority | Condition |
| - | - |
| 1 (highest) | User preference via `/skill prefer` |
| 2 | Project-local skill (`.agent/skills/`) |
| 3 | Global local skill (`~/.chatcli/skills/exact-name/`) |
| 4 | Global registry skill (`~/.chatcli/skills/source--name/`) |

### Pin Skills for the Session (`/skill pin`)

When you want a skill considered on **every turn** of the conversation — regardless of whether the message matches its `triggers:` or `paths:` — pin it with `/skill pin`. The skill stays injected in the system prompt until you `/skill unpin` it or end the session.

```bash theme={"system"}
/skill pin <name>      # Pin the skill for the current session
/skill unpin <name>    # Remove from the pinned set
/skill pinned          # List pinned skills
```

### Measure What a Skill Does (`/skill stats`)

Every agent and coder run is credited to the skills injected into it — pinned, auto-activated by trigger, or authored by the self-evolve engine — with its turns, tool calls and cost, next to a baseline of every run. `/skill stats` puts the two side by side, per run, so a skill can be judged by what it changes rather than by how often it fires: a negative percentage means the runs that used it were shorter or cheaper than the baseline, a learned skill that stays positive is a candidate for pruning. The ledger lives in `~/.chatcli/skills/.skill-stats.json` and is provider-neutral: turns and tool calls come from the run registry, cost from the tracker, both of which every provider feeds. Each row also says whether the skill was **used**, not only activated: for a skill that declares `allowed-tools`, a run counts as used when one of those tools executed after the injection (`tools used in 3 of 4 runs`); a skill that declares no tools reads `tool use not declared`, because guessing would be worse than not knowing.

```bash theme={"system"}
/skill stats           # Every skill against the baseline, most used first
/skill stats <name>    # One skill
```

**Example:**

```bash theme={"system"}
/skill pin go-testing

  Skill pinned: go-testing
  It will be injected on every turn until /skill unpin.

# Subsequent messages — go-testing shows up in the system prompt even
# when the message has no "test" keyword and no *_test.go file mention

/skill pinned

  Skills pinned for this session (1):

    go-testing  Go testing patterns

/skill unpin go-testing

  Skill unpinned: go-testing
```

**What pin does exactly:**

* Injects the skill into a dedicated `# Pinned Skills` block in the system prompt, before the `# Auto-loaded Skills` block. On `model:`/`effort:` hint conflicts, pinned beats auto-activation (but loses to a manual `/<skill-name>` invocation).
* The pinned block carries `cache_control: ephemeral` — the provider keeps the cache warm across turns as long as the pinned set doesn't change.
* Auto-activation still runs: if a skill is pinned **and** matches by `triggers:`/`paths:`, it's injected exactly once (deduplicated by name).
* Skills uninstalled/renamed during the session silently drop from the set on the next turn (re-resolved through the persona manager).
* `/skill list` shows `[pinned]` next to pinned skills.

**Restrictions:**

* Skills with `disable-model-invocation: true` **cannot** be pinned — the flag exists precisely to forbid automatic injection. Use manual `/<skill-name>` for those.
* The pinned set is session-scoped; it does not persist across chatcli runs (by design — pinning expresses current-session intent).

### How to Activate a Skill: Three Modes

| Mode | Trigger | Scope | Required frontmatter |
| - | - | - | - |
| **Auto-activation** | `triggers:` (contiguous substring, or all words of a multi-word trigger present as whole tokens in any order) or `paths:` (glob against input paths) matches | per-turn (re-evaluated each message) | `triggers:` or `paths:` (without `disable-model-invocation: true`) |
| **Manual `/<skill-name>`** | User types `/<name>` | single-turn | `user-invocable: true` |
| **Pin `/skill pin <name>`** | User pinned explicitly | whole session | any (except `disable-model-invocation: true`) |

**`model:`/`effort:` hint precedence when multiple modes fire on the same turn:**

```
manual > pinned > auto-activated
```

For each mode's details, frontmatter, and examples: see [Advanced frontmatter in Customizable Agents](/agents/customizable-agents#advanced-frontmatter-patterns).

### Skill Injection Budget

Injected skill **bodies** respect a per-block character budget: `CHATCLI_SKILL_INJECT_BUDGET` (default `24000`, `0` = unlimited/legacy). On top of it, a **per-run budget of 2× that value** caps the cumulative skill bytes an agent/coder run may inject (startup + mid-loop); once spent, later activations still announce themselves but their bodies degrade the same way. Skills are rendered in their stable order; every entry now carries a `Source: <path>` line, and once a budget is spent, later skills keep their **header and description** but the body degrades to a read-on-demand pointer at the skill's source file:

```text theme={"system"}
## Skill: servicenow-incident-detail-query (v1.2)

Query incident details from ServiceNow with pagination.

_Body not inlined (skill injection budget). Before applying this skill,
read its full instructions from: ~/.chatcli/skills/servicenow-incident-detail-query/SKILL.md_
```

Nothing is lost — only deferred: the model reads the file when (and only when) it actually applies the skill.

### Skill lifecycle: aging, cooldown and drip (agent/coder)

Mid-loop skill injections no longer ride the window for the whole run. Three mechanisms bound their footprint:

* **Aging**: a mid-loop skill block older than `CHATCLI_SKILL_AGE_TURNS` turns (default `6`) collapses to a one-line stub — the full guidance is archived and recoverable via `@recall`, and the stub names the skills plus their `Source:` paths so nothing is unreachable.
* **Cooldown + re-trigger**: a collapsed skill leaves the run's dedup set. If its trigger fires again after the cooldown (same number of turns), the skill re-injects fresh — aging is eviction, not amnesia.
* **Drip cap**: at most **3 new skills per mid-loop injection**; a burst of matches drips across turn boundaries instead of landing as one giant block (the capped-out skills re-candidate on the next boundary, none are dropped).

Pinned skills and the startup block are untouched — aging applies only to mid-loop user-role injections.

<Info>
  **Why this exists:** a single prompt can auto-activate a burst of skills (e.g. nine ServiceNow skills matching one question), adding tens of KB to **every subsequent request**. Behind a corporate proxy/WAF with a body-size cap, that alone can push the session over the rejection threshold — see [Context Recovery](/context/context-recovery). The default is generous: typical sessions inline every activated skill untouched.
</Info>

The variables are surfaced in `/config agent` (token efficiency section) — `CHATCLI_SKILL_INJECT_BUDGET` and `CHATCLI_SKILL_AGE_TURNS`.

### Help

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

***

## Namespace and Collisions

### How Skills Are Stored on Disk

Registry skills use **qualified names** to avoid collisions:

```text theme={"system"}
~/.chatcli/skills/
  frontend-design/                           # local (no prefix)
  anthropics-skills--frontend-design/         # skills.sh (owner-repo--name)
    SKILL.md
    scripts/
    references/
    assets/
  clawhub--code-review/                       # clawhub (registry--name)
```

The `--` separator is safe because the [agentskills.io spec](https://agentskills.io/specification) forbids consecutive hyphens in skill names.

### Users Never Need to Type Qualified Names

Daily usage is transparent:

```bash theme={"system"}
# Invoke skill by base name — works
/frontend-design

# Automatic triggers — work via frontmatter name
# Autocomplete — shows clean names (from frontmatter)
```

Qualified names only appear in **management** contexts (info, uninstall) when there are conflicts between sources.

***

## Configuration

### Registries File

`~/.chatcli/registries.yaml` controls the 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
install_dir: ~/.chatcli/skills
max_concurrent: 3
search_cache_size: 50
```

### Preferences File

`~/.chatcli/skill-preferences.yaml` stores source preferences:

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

Managed exclusively via `/skill prefer` — no manual editing needed.

### Environment Variables

| Variable | Description |
| - | - |
| `CHATCLI_REGISTRY_URLS` | Additional registry URLs (comma-separated) |
| `CHATCLI_REGISTRY_DISABLE` | Registry names to disable (comma-separated) |
| `CHATCLI_SKILL_INSTALL_DIR` | Install directory (default: `~/.chatcli/skills`) |

***

## Security and Moderation

### Moderation Flags

| Flag | Behavior |
| - | - |
| `malware_detected` | **HARD BLOCK** — installation refused automatically |
| `quarantined` | **HARD BLOCK** — skill quarantined by registry |
| `suspicious_content` | **WARNING** — shows warning and asks for confirmation |

### Security Audits (skills.sh)

For skills.sh skills, `/skill info` shows security assessments from three partner providers:

| Provider | Assessment |
| - | - |
| **Gen Agent Trust Hub (ATH)** | Overall risk level (safe/low/medium/high/critical) |
| **Socket** | Security alert count |
| **Snyk** | Dependency risk analysis |

Data is fetched from `https://add-skill.vercel.sh/audit` with a 3-second timeout — failures are silent (advisory data, never blocks).

### Atomic Installation

Skills are installed using atomic writes:

1. Content downloaded to temporary directory (`.tmp-*`)
2. YAML frontmatter validated
3. Moderation flags checked
4. Scripts receive executable permission
5. `source` and `snapshot_hash` fields injected into frontmatter
6. Directory atomically renamed to final destination
7. On failure, temporary directory is automatically removed

***

## Search Cache (Trigram)

ChatCLI implements a trigram-based fuzzy cache to reduce network calls:

| Parameter | Default |
| - | - |
| Max size | 50 entries |
| TTL per entry | 5 minutes |
| Similarity threshold | 0.7 (Jaccard) |
| Eviction | LRU (Least Recently Used) |

The cache is automatically invalidated after installing or uninstalling a skill, and recreated when enabling/disabling a registry.

***

## Architecture

```text theme={"system"}
/skill commands (cli/skill_handler.go)
        |
        v
RegistryManager (pkg/registry/manager.go) -- fan-out coordinator
        |
        |---> ChatCLIRegistry (registry.chatcli.dev)   -- REST API
        |---> ClawHubRegistry (clawhub.ai)              -- REST API
        |---> SkillsShRegistry (skills.sh)              -- Search + Snapshot + Audit APIs
        +---> CustomRegistry  (user registries)          -- REST API
        |
        |  merged results (no cross-registry dedup)
        |
        |---> Install -> Installer -> atomic writes
        |     |---> Install() for REST registries (buildSkillMD)
        |     +---> InstallFromSnapshot() for skills.sh (preserves structure)
        |
        v
SkillPreferences (pkg/registry/skill_preferences.go)
        |
        v
pkg/persona/Loader (pkg/persona/loader.go)
        |---> GetSkill() resolves by: preference > exact name > base name
        +---> ListSkills() dedup by frontmatter name, applies preferences
```

### Packages

| Package | File | Responsibility |
| - | - | - |
| `pkg/registry/` | `interface.go` | Types: SkillMeta, SnapshotFile, InstalledSkillInfo |
| | `manager.go` | Fan-out search, Install, InstallFrom, GetAllSkillMeta |
| | `installer.go` | Install, InstallFromSnapshot, qualified names, FindInstalled |
| | `skillssh_registry.go` | skills.sh adapter (Search, Download, Audit, enrichMeta) |
| | `skill_preferences.go` | Source preferences per skill |
| | `config.go` | Configuration, mergeDefaultRegistries |
| | `moderation.go` | Safety flags |
| | `trigram.go` | Fuzzy search cache |
| `cli/` | `skill_handler.go` | /skill commands (search, install, info, prefer, registry) |
| | `skill_activation.go` | Auto-activation by triggers and paths |
| | `skill_invoke.go` | Manual invocation via `/<skill-name>` |
| | `cli_completer.go` | Contextual autocomplete |
| `pkg/persona/` | `loader.go` | GetSkill (preference + qualified resolution), ListSkills (dedup) |

***

## Next Steps

* [**Customizable Agents**](/agents/customizable-agents) — How to create and use agents with skills
* [**Command Reference**](/reference/command-reference) — Complete list of all commands
* [**Configuration (.env)**](/reference/configuration) — Available environment variables


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.