Skill Registry - ChatCLI

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

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:` (substring keyword) 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.

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

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

​How to Activate a Skill: Three Modes

​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