Skill Registry

ChatCLI supports a hybrid, multi-registry Skill Registry system that allows you to 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 that hosts searchable and installable skills
Skill	An `.md` file with YAML frontmatter that defines specialized behavior for agents
Fan-out Search	Parallel search across all enabled registries, with merged and deduplicated results
Moderation	Safety flags (malware, suspicious content) provided by the registries
Trigram Cache	Local fuzzy cache that avoids network requests for similar searches

Default Registries

ChatCLI comes configured with two registries:

Registry	URL	Description
chatcli	`https://registry.chatcli.dev/api/v1`	Official ChatCLI registry
clawhub	`https://clawhub.ai/api/v1`	Public skill marketplace (ClawHub)

Both can be disabled or extended with custom registries.

`/skill` Commands

Search Skills

/skill search <query>

Performs a parallel fan-out search across all enabled registries. Results are merged, deduplicated, and displayed with:

Name, version, and author
Source registry ([chatcli], [clawhub], etc.)
Moderation flags (SUSPICIOUS, BLOCKED)
Installation status ([installed])

Example:

/skill search kubernetes

  Searching across registries for "kubernetes"...

  Results (3 found):

    1. k8s-ops (v2.1.0) by devopsorg  [chatcli]
       Kubernetes operations and troubleshooting guide
       Tags: kubernetes, devops, k8s

    2. k8s-security (v1.0.3) by secteam  [clawhub]
       Kubernetes security best practices
       Tags: kubernetes, security

    3. helm-charts (v1.5.0) by helmorg  [chatcli]  [installed]
       Helm chart development patterns
       Tags: kubernetes, helm

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

Install Skill

/skill install <name>

Searches for the skill in the registries, checks moderation flags, and installs it to ~/.chatcli/skills/<name>/SKILL.md.

Skills with detected malware are blocked automatically
Suspicious skills display a warning and ask for confirmation
Already installed skills are updated (replaced)
After installation, the skill is immediately available in /agent skills

Example:

/skill install k8s-ops

  Installing k8s-ops v2.1.0 from chatcli registry...
  Installed k8s-ops v2.1.0 from chatcli
  Path: ~/.chatcli/skills/k8s-ops/

  Skill 'k8s-ops' is now available.
  Verify with: /agent skills

Uninstall Skill

/skill uninstall <name>

Removes the installed skill from disk.

/skill uninstall k8s-ops

  Removing skill 'k8s-ops'...
  Done. Skill 'k8s-ops' uninstalled.

List Installed Skills

/skill list

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

/skill list

  Installed Skills (3):

    clean-code     v1.2.0  [chatcli]   ~/.chatcli/skills/clean-code/
    error-handling         [local]     ~/.chatcli/skills/error-handling.md
    k8s-ops        v2.1.0  [chatcli]   ~/.chatcli/skills/k8s-ops/

  Registries (2):
    chatcli   https://registry.chatcli.dev/api/v1  [enabled]
    clawhub   https://clawhub.ai/api/v1            [enabled]

Skill Information

/skill info <name>

Displays complete metadata for a skill from the registry (without installing it).

View Configured Registries

/skill registries

Displays all configured registries, their URLs, and status.

/skill registries

  Configured Registries:

    1. chatcli   https://registry.chatcli.dev/api/v1  [enabled]   TTL: 15m
    2. clawhub   https://clawhub.ai/api/v1            [enabled]   TTL: 5m

  Config: ~/.chatcli/registries.yaml
  Edit the config file to add custom registries.

Help

/skill help

Configuration

Configuration File

The ~/.chatcli/registries.yaml file 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
  # Custom registry example:
  - 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

The file is automatically created with the default registries on first run.

Environment Variables

Variable	Description
`CHATCLI_REGISTRY_URLS`	Additional registry URLs (comma-separated). Each URL is added as a custom registry.
`CHATCLI_REGISTRY_DISABLE`	Registry names to disable (comma-separated). E.g., `clawhub,chatcli`
`CHATCLI_SKILL_INSTALL_DIR`	Installation directory (default: `~/.chatcli/skills`)

Example:

# Add a corporate registry
export CHATCLI_REGISTRY_URLS="https://skills.corp.com/api/v1"

# Disable ClawHub
export CHATCLI_REGISTRY_DISABLE="clawhub"

Custom Registry

Any server that implements the standard REST API can be used as a custom registry:

Expected Endpoints

Endpoint	Method	Description
`/skills/search?q=<query>`	GET	Search skills. Returns `{"skills": [...]}` or `[...]`
`/skills/<slug>`	GET	Metadata for a specific skill
`/skills/<slug>/download`	GET	Download the skill content

Response Format (Search)

{
  "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,
        "reason": ""
      }
    }
  ]
}

Authentication

Custom registries may require Bearer token authentication. Configure the token field in registries.yaml:

registries:
  - name: private-reg
    url: https://private.registry.com/api/v1
    enabled: true
    token: "Bearer my-secret-token"

Security and Moderation

The skill registry system includes protections against malicious content:

Moderation Flags

Flag	Behavior
`malware_detected`	FULL BLOCK — installation automatically refused
`quarantined`	FULL BLOCK — skill quarantined by the registry
`suspicious_content`	WARNING — displays a warning and asks for user confirmation

Atomic Installation

Skills are installed using atomic writes:

Content is downloaded to a temporary directory (.tmp-*)
YAML frontmatter is validated
Moderation flags are checked
Directory is atomically renamed to the final destination
On failure, the temporary directory is automatically removed

Name Sanitization

Skill names are sanitized to prevent path traversal:

Converted to lowercase
Spaces replaced with hyphens
Slashes (/) removed
.. sequences removed

Search Cache (Trigram)

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

How It Works

Trigram Extraction: The query is split into subsequences of 3 characters
- "golang" → {"gol", "ola", "lan", "ang"}
Jaccard Similarity: For each cached query, calculates J(A, B) = |A ∩ B| / |A ∪ B|
Threshold: If J >= 0.7, cached results are returned
- "golan" → match with "golang" (J ~ 0.75)
- "python" → no match with "golang" (J ~ 0.0)

Characteristics

Parameter	Default Value
Maximum cache size	50 entries
TTL per entry	5 minutes
Similarity threshold	0.7
Eviction	LRU (Least Recently Used)

The cache is automatically invalidated after installing or uninstalling a skill.

Agent Integration

Skills installed via /skill install are automatically available to the agent system:

Skills are installed to ~/.chatcli/skills/<name>/SKILL.md
The Loader in the persona system (pkg/persona) already scans this directory
/agent skills lists both local skills and those installed via the registry
Agents can reference installed skills in their frontmatter:

---
name: devops-agent
description: Expert DevOps agent
skills: [k8s-ops, docker-best-practices]
---

Skill Precedence

Priority	Location	Description
1 (highest)	`.agent/skills/` (project)	Project-local skills
2	`~/.chatcli/skills/` (global)	Skills installed via registry or manually

Project-local skills always take precedence over global skills with the same name.

Architecture

/skill commands (cli/skill_handler.go)
        |
        v
 RegistryManager (pkg/registry/manager.go) -- fan-out coordinator
        |
        |---> ChatCLIRegistry (registry.chatcli.dev)
        |---> ClawHubRegistry (clawhub.ai)
        +---> CustomRegistry  (user registries)
        |
        v  (merged + deduplicated results)
        v  (install -> Installer -> atomic write to ~/.chatcli/skills/)
        |
pkg/persona/Loader -- scans ~/.chatcli/skills/ automatically

Packages

Package	Responsibility
`pkg/registry/`	Interface, adapters, manager, cache, installer, moderation
`cli/skill_handler.go`	`/skill` command handler
`pkg/persona/`	Local skill loader (unchanged)

Next Steps

Customizable Agents — How to create and use agents with skills
Command Reference — Complete list of all commands
Configuration (.env) — Available environment variables

Home

Getting Started

Core Concepts

Features

Support

Concepts

Default Registries

`/skill` Commands

Search Skills

Install Skill

Uninstall Skill

List Installed Skills

Skill Information

View Configured Registries

Help

Configuration

Configuration File

Environment Variables

Custom Registry

Expected Endpoints

Response Format (Search)

Authentication

Security and Moderation

Moderation Flags

Atomic Installation

Name Sanitization

Search Cache (Trigram)

How It Works

Characteristics

Agent Integration

Skill Precedence

Architecture

Packages

Next Steps

Home

Getting Started

Core Concepts

Features

Support

​Concepts

​Default Registries

​/skill Commands

​Search Skills

​Install Skill

​Uninstall Skill

​List Installed Skills

​Skill Information

​View Configured Registries

​Help

​Configuration

​Configuration File

​Environment Variables

​Custom Registry

​Expected Endpoints

​Response Format (Search)

​Authentication

​Security and Moderation

​Moderation Flags

​Atomic Installation

​Name Sanitization

​Search Cache (Trigram)

​How It Works

​Characteristics

​Agent Integration

​Skill Precedence

​Architecture

​Packages

​Next Steps

Concepts

Default Registries

`/skill` Commands

Search Skills

Install Skill

Uninstall Skill

List Installed Skills

Skill Information

View Configured Registries

Help

Configuration

Configuration File

Environment Variables

Custom Registry

Expected Endpoints

Response Format (Search)

Authentication

Security and Moderation

Moderation Flags

Atomic Installation

Name Sanitization

Search Cache (Trigram)

How It Works

Characteristics

Agent Integration

Skill Precedence

Architecture

Packages

Next Steps