Skill Registry

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

/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.

/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

/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:

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

# 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

/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

/skill list

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

Skill Info

/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.

/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

/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

/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.

/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.

/skill stats           # Every skill against the baseline, most used first
/skill stats <name>    # One skill

Example:

/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.

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:

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

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. The default is generous: typical sessions inline every activated skill untouched.

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

Help

/skill help

Namespace and Collisions

How Skills Are Stored on Disk

Registry skills use qualified names to avoid collisions:

~/.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 forbids consecutive hyphens in skill names.

Users Never Need to Type Qualified Names

Daily usage is transparent:

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

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:

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:

Content downloaded to temporary directory (.tmp-*)
YAML frontmatter validated
Moderation flags checked
Scripts receive executable permission
source and snapshot_hash fields injected into frontmatter
Directory atomically renamed to final destination
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

/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 — How to create and use agents with skills
Command Reference — Complete list of all commands
Configuration (.env) — Available environment variables

Get started

Documentation

Concepts

Default Registries

skills.sh

`/skill` Commands

Search Skills

Install Skill

Uninstall Skill

List Installed Skills

Skill Info

Manage Registries

Source Preferences

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

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

How to Activate a Skill: Three Modes

Skill Injection Budget

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

Help

Namespace and Collisions

How Skills Are Stored on Disk

Users Never Need to Type Qualified Names

Configuration

Registries File

Preferences File

Environment Variables

Security and Moderation

Moderation Flags

Security Audits (skills.sh)

Atomic Installation

Search Cache (Trigram)

Architecture

Packages

Next Steps

​Concepts

​Default Registries

​skills.sh

​/skill Commands

​Search Skills

​Install Skill

​Uninstall Skill

​List Installed Skills

​Skill Info

​Manage Registries

​Source Preferences

​Pin Skills for the Session (/skill pin)

​Measure What a Skill Does (/skill stats)

​How to Activate a Skill: Three Modes

​Skill Injection Budget

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

​Help

​Namespace and Collisions

​How Skills Are Stored on Disk

​Users Never Need to Type Qualified Names

​Configuration

​Registries File

​Preferences File

​Environment Variables

​Security and Moderation

​Moderation Flags

​Security Audits (skills.sh)

​Atomic Installation

​Search Cache (Trigram)

​Architecture

​Packages

​Next Steps

Concepts

Default Registries

skills.sh

`/skill` Commands

Search Skills

Install Skill

Uninstall Skill

List Installed Skills

Skill Info

Manage Registries

Source Preferences

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

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

How to Activate a Skill: Three Modes

Skill Injection Budget

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

Help

Namespace and Collisions

How Skills Are Stored on Disk

Users Never Need to Type Qualified Names

Configuration

Registries File

Preferences File

Environment Variables

Security and Moderation

Moderation Flags

Security Audits (skills.sh)

Atomic Installation

Search Cache (Trigram)

Architecture

Packages

Next Steps