skillsctl

CLI tool for installing skills, agents, workflows, and rules from an Enterprise Skills Catalog server.

Think npm install but for enterprise knowledge — versioned markdown files that define reusable AI skills, agent prompts, operational runbooks, and compliance rules.

Installation

pip install skillsctl

Quick Start

# Point at your org's catalog
export SKILLSCTL_SOURCE=https://catalog.your-company.com

# Search for available items
skillsctl search slack

# Install a skill (its dependencies come along too)
skillsctl install send-slack-notification

# Install into a custom directory (flat, no category subfolder)
skillsctl install my-rule --path .claude/commands

# Set a project-wide default output directory
skillsctl config base-dir .claude     # → .claude/skills/… .claude/agents/… etc.
skillsctl config base-dir .windsurf   # → .windsurf/rules/… .windsurf/agents/… etc.
skillsctl config base-dir --unset     # reset to .skillsctl (default)

# List what's installed
skillsctl list

# Update everything to latest
skillsctl sync

Commands

skillsctl install

Download and save items from the catalog into your project.

# Install one or more items (required dependencies are pulled in by default)
skillsctl install send-slack-notification http-request

# Skip dependency resolution
skillsctl install send-email --no-deps

# Install to a custom path (flat, no category subfolder)
skillsctl install my-rule --path .claude/commands

Files are saved to .skillsctl/{category}/{name}.md by default and tracked in skills.yaml.

skillsctl config

Set project-wide configuration stored in skills.yaml.

# Change the default install directory for all future installs
skillsctl config base-dir .claude      # saves to .claude/{category}/{name}.md
skillsctl config base-dir .windsurf   # saves to .windsurf/{category}/{name}.md

# Reset to default (.skillsctl)
skillsctl config base-dir --unset

skillsctl search

Search the remote catalog.

skillsctl search "database"
skillsctl search "deploy" --category workflows
skillsctl search "auth" --tag security

skillsctl list

Show all installed items from your skills.yaml lockfile.

skillsctl list

skillsctl update

Update specific items to their latest catalog version.

skillsctl update send-slack-notification
skillsctl update http-request send-email

skillsctl sync

Re-download all installed items, updating any that have newer versions.

skillsctl sync

skillsctl remove

Remove installed items and clean up the lockfile.

skillsctl remove send-slack-notification

Configuration

Catalog Source

The catalog server URL is resolved in this order:

1. --source CLI flag: skillsctl --source https://catalog.example.com install my-skill
2. source field in skills.yaml
3. SKILLSCTL_SOURCE environment variable
4. Default: http://localhost:8000

Lockfile (skills.yaml)

skillsctl maintains a lockfile in your project root that tracks the catalog source, configuration, and installed items with pinned versions:

source: https://catalog.your-company.com
base_dir: .claude                        # optional — set via `skillsctl config base-dir`
installed:
  http-request: "1.3.0"                 # default path — bare string
  send-slack-notification: "2.1.0"
  slack-ops-agent: "1.0.0"
  my-rule:                              # installed with --path
    version: "1.0.0"
    path: .claude/commands              # custom flat path stored here

Project Structure

After installing items, your project will look like:

your-project/
├── skills.yaml                              # lockfile (commit this)
├── .skillsctl/                              # default install directory (commit this)
│   ├── skills/
│   │   ├── http-request.md
│   │   └── send-slack-notification.md
│   ├── agents/
│   │   └── slack-ops-agent.md
│   └── rules/
│       └── no-direct-production-deploy.md
└── ... your code ...

With skillsctl config base-dir .claude:

your-project/
├── skills.yaml
├── .claude/
│   ├── skills/
│   │   └── http-request.md
│   └── agents/
│       └── slack-ops-agent.md
└── ... your code ...

Commit both skills.yaml and the install directory to version control so your entire team uses the same skills at the same versions.

How It Works

┌─────────────────────────────┐
│  Skills Catalog Server      │
│  (FastAPI + in-memory index)│
│                             │
│  Serves .md files from any  │
│  git repo or local folder   │
└──────────────┬──────────────┘
               │
               │  REST API
               ▼
┌─────────────────────────────┐
│  skillsctl (this CLI)       │
│                             │
│  install / search / sync    │
│  remove / update / list     │
│  config                     │
│                             │
│  Writes .md files into      │
│  your project + lockfile    │
└─────────────────────────────┘

1. skillsctl install <name> calls GET /api/v1/items/<name> to fetch metadata
2. Downloads the raw .md file via GET /api/v1/items/<name>/raw
3. Saves it to .skillsctl/{category}/{name}.md (or custom path if --path is set)
4. Updates skills.yaml with the installed version
5. Recursively resolves and installs items listed in requires (suppress with --no-deps)

Setting Up a Catalog Server

See the Skills Catalog repo for the server that skillsctl connects to. The server indexes markdown files with YAML frontmatter and serves them via a REST API + web UI.

# Quick start
pip install fastapi uvicorn python-frontmatter watchdog pydantic pydantic-settings jinja2 aiofiles markdown packaging
uvicorn catalog.main:app --port 8000

# Or point at your org's git repo
CATALOG_CONTENT_REPO=https://github.com/your-org/playbooks.git uvicorn catalog.main:app --port 8000

License

MIT