> ## 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 ``` 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 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 [--from ] ``` 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 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 ``` 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 [--from ] ``` 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 # enable (hot-reload) /skill registry disable # 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 # show current preference + sources /skill prefer # set preference /skill prefer --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 # Pin the skill for the current session /skill unpin # Remove from the pinned set /skill pinned # List pinned skills ``` **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 `/` 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 `/` 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 `/`** | User types `/` | single-turn | `user-invocable: true` | | **Pin `/skill pin `** | 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](/features/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). Skills are rendered in their stable order; once the 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. **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](/features/context-recovery). The default is generous: typical sessions inline every activated skill untouched. The variable is surfaced in `/config agent` (token efficiency section). ### 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 `/` | | | `cli_completer.go` | Contextual autocomplete | | `pkg/persona/` | `loader.go` | GetSkill (preference + qualified resolution), ListSkills (dedup) | *** ## Next Steps * [**Customizable Agents**](/features/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