• Zero tokens when idle — stateless CLI, no server process, no protocol overhead
• One command to install — git clone → symlink → registered, done in seconds
• Agent-native — every command supports --json with next_actions guidance
• Works today — Claude Code, Codex, and any agent that reads markdown

Quickstart (2 min)

1. Install

pip install skillctl

2. Find a skill

$ skillctl search "pdf"

  ●  pdf               registry  Create, edit, and extract content from PDFs   ★ 0
  ○  pdf-to-markdown   github    Convert PDF files to clean markdown           ★ 89
  ○  pdf-ocr           github    OCR extraction from scanned PDFs              ★ 67

3. Install it

$ skillctl install anthropics/skills --path skills/pdf

  ✓ Cloned anthropics/skills → ~/.skillctl/repos/anthropics__skills
  ✓ Linked → ~/.claude/skills/pdf
  ✓ Registered in manifest

Your agent picks it up immediately — no restart, no config change.

The problem

Every AI agent runtime uses skills — markdown files that define what an agent can do. But skills live scattered across GitHub repos, local folders, and team drives. Developers copy-paste skill files manually and hope they work.

There's no npm install for skills.

The solution

skillctl is a package manager purpose-built for agent skills.

skillctl search "excel"  →  finds xlsx skill (via LLM-enriched keywords)
skillctl install ...      →  git clone → symlink → registered
~/.claude/skills/xlsx/    →  agent picks it up automatically

Using with coding agents

skillctl installs skills as symlinks into directories your agent already reads. No plugin, no integration, no restart.

Claude Code

skillctl config set skills_dir ~/.claude/skills    # default — already set
skillctl install anthropics/skills --path skills/pdf
# Claude Code picks it up on the next message — the /pdf skill appears automatically

OpenAI Codex

skillctl config set skills_dir ~/.codex/skills
skillctl install anthropics/skills --path skills/pdf
# Codex reads the skills directory on session start

Any agent with bash access can use skillctl directly — the CLI follows the same search → install → use pattern agents know from pip, npm, and gh:

# An agent can do this autonomously:
skillctl search "data analysis" --json --fields=slug,installed
skillctl install anthropics/skills --path skills/xlsx -y --json
cat ~/.claude/skills/xlsx/SKILL.md   # agent reads and follows the instructions

[!NOTE] skillctl is designed agent-first. Every command supports --json with guided next_actions, --quiet for piping, --yes to skip prompts, and skillctl schema for runtime self-discovery. Agents don't need documentation — they can introspect the CLI.

Why CLI, not MCP

Most agent tooling burns tokens while idle. skillctl costs zero.

Commands

skillctl search "pdf"                         # Search registries + local
skillctl search "pdf" --source=github         # Broad GitHub search
skillctl install user/repo                    # Full repo as a skill
skillctl install user/repo --path skills/pdf  # Subdirectory from monorepo
skillctl install user/repo --dry-run          # Preview without executing

skillctl list                                 # Show installed skills
skillctl list --quiet                         # Bare names (for piping)
skillctl info my-skill                        # Detailed skill card
skillctl update my-skill                      # Pull latest from git
skillctl update --all                         # Update everything
skillctl remove my-skill                      # Uninstall (ref-counted clones)

skillctl create my-skill --name "My Skill" --desc "Does X"
skillctl lint my-skill                        # Score 0-100 with fix suggestions

  my-skill                              Score: 65/100

  █████████████████████░░░░░░░░░  65%

  ✓ Has name, description, and tags in frontmatter
  ✓ Has 'When to Use' trigger section
  ✗ Missing anti-patterns section      +15 pts
  ✗ No code examples                   +20 pts

skillctl learn                       # Topic index
skillctl learn anatomy               # The 5 layers of a great skill
skillctl learn write                 # Writing for AI comprehension
skillctl learn organize              # Directory structure & naming
skillctl learn examples              # Browse well-written reference skills

skillctl registry                    # List configured registries
skillctl registry add org/repo       # Add (validates skills exist)
skillctl registry remove org/repo
skillctl registry reset              # Reset to defaults

skillctl config                              # Show current config
skillctl config set skills_dir ~/skills      # Change skills directory
skillctl config set registries "org/repo1,org/repo2"

Agent mode

Every command supports --json. Responses include next_actions so agents can chain commands without hallucinating:

$ skillctl search "pdf" --json --fields=slug,installed

{
  "results": [
    {"slug": "pdf", "installed": false},
    {"slug": "pdf-to-markdown", "installed": false}
  ],
  "next_actions": [
    "skillctl install anthropics/skills --path skills/pdf -y --json",
    "skillctl info pdf --json"
  ]
}

$ skillctl schema    # Full CLI introspection — agents discover commands at runtime

How install works

skillctl install anthropics/skills --path skills/pdf
         │
         ├─ git clone → ~/.skillctl/repos/anthropics__skills/
         ├─ symlink   → ~/.claude/skills/pdf → (clone)/skills/pdf
         └─ register  → ~/.skillctl/manifest.json

• Shared clones — installing two skills from the same repo uses one clone
• Ref-counted removal — shared clones are kept until the last skill is removed
• Atomic updates — git pull on the clone updates all skills from that repo

Search

Search uses a three-layer system:

1. Synonym expansion — "excel" finds xlsx, "figma" finds frontend-design
2. Scored ranking — slug > keywords > name > tags > description
3. LLM enrichment — generates search keywords at index time (optional, cached with SHA invalidation)

[!NOTE] Set ANTHROPIC_API_KEY or OPENAI_API_KEY to enable LLM enrichment. Runs once per skill, costs ~$0.0005 each, cached with content-addressed SHA invalidation.

SKILL.md format

Skills are markdown files with YAML frontmatter. Run skillctl learn anatomy for the full breakdown.

---
name: sql-standards
description: SQL coding standards for our team
tags: [sql, standards]
---

## When to Use This Skill
Use when the user asks to write or review SQL.

## Core Principles
- Always use UPPERCASE for SQL keywords
- Never use SELECT *

## Common Mistakes to Avoid
- ✗ SELECT * FROM users → ✓ SELECT id, name FROM users

## Examples

Command reference

Contributing

The easiest way to contribute is to pick an issue with the good first issue tag.

git clone https://github.com/dvlshah/skillctl.git
cd skillctl
pip install -e ".[dev]"
pytest

Bug report? Open an issue. Feature request? Open an issue.

[!TIP] If skillctl saves you time, star the repo — it helps other developers find it.

License

MIT