skillsctl 0.3.1

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

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