skilly 0.0.30

Manage agent skills.

skilly

Manage Agent Skills from the command line or Python.

skilly creates specification-compliant skills, installs skills from GitHub or Python dependencies, and keeps managed skills up to date.

Table of Contents

• Installation
  • Python
  • Node
  • Homebrew
  • Info
• Quick Start
• CLI Commands
  • Create Skills
  • Install Dependency Skills
  • Install GitHub Skills
  • Destinations
  • Configure Destinations
  • GitHub Authentication
• Python API
• Development
• License

Installation

Python

uvx skilly --help

Node

npx @xelandernt/skilly --help

Homebrew

brew tap xelandernt/skilly https://github.com/xelandernt/skilly
brew install xelandernt/skilly/skilly

Info

Method	Ships
uvx / pip	Python package with import surface + CLI (pre-built wheels: Linux x64, macOS arm64/x64, Windows x64)
npx	Native Rust CLI (macOS arm64/x64, Linux x64 glibc, Windows x64)
brew	Native Rust CLI (macOS arm64/x64, Linux x64)

Quick Start

uvx skilly scan                       # Find skills from Python dependencies
uvx skilly download <github-url>      # Install skills from GitHub
uvx skilly list                       # Browse installed skills
uvx skilly update                     # Preview available updates

CLI Commands

Command	Purpose
scan	Find skills provided by the project's Python dependencies
download <github-url>	Install one or more skills from GitHub
list	Browse, update, or remove installed skills
update	Preview available updates; --yes applies all
remove <name>	Remove an installed skill by directory name
skillsmp search <query>	Search SkillsMP and install a selected result
create	Create a valid skill through a terminal wizard or explicit options
configure	Set which directories skilly manages via TUI or CLI flags

Run skilly <command> --help for all options.

Create Skills

Interactive terminals open a full-screen editor. Ctrl+S creates the skill, Ctrl+X cancels.

uvx skilly create deployment-checks \
  --description "Validate deployment readiness before a production release." \
  --instructions "# Instructions

Run the deployment checklist and report blockers." \
  --metadata owner=platform \
  --with-scripts \
  --yes

Existing skills are rejected unless --overwrite is passed.

Install Dependency Skills

skilly scan reads pyproject.toml and the project's .venv, then surfaces skills shipped by dependencies:

uvx skilly scan

Include or exclude specific extras and dependency groups (flags are repeatable):

uvx skilly scan --group dev --group test --exclude-extra docs

Install GitHub Skills

uvx skilly download https://github.com/example/project

When a repository contains multiple skills:

uvx skilly download https://github.com/example/project --all
uvx skilly download https://github.com/example/project --skill-name code-review

Destinations

All management commands accept the same destination options:

uvx skilly list --local        # .agents/skills
uvx skilly list --global       # ~/.agents/skills
uvx skilly list --claude       # .claude/skills
uvx skilly list --codex        # .codex/skills
uvx skilly list --copilot      # .github/skills (local), ~/.copilot/skills (global)
uvx skilly list --directory ~/custom     # Explicit directory

Flags	Resolved destination
none	SKILLY_DIRECTORY if set, otherwise .agents/skills
--local	.agents/skills
--global	~/.agents/skills
--claude	.claude/skills
--claude --global	~/.claude/skills
--codex	.codex/skills
--codex --global	~/.codex/skills
--copilot	.github/skills
--copilot --global	~/.copilot/skills
--directory <path>	That directory (after ~ expansion)

Set a default destination:

export SKILLY_DIRECTORY="$HOME/.config/skilly/skills"

--directory overrides all other destination options and SKILLY_DIRECTORY.

Configure Destinations

skilly configure lets you choose which directories skilly should manage. Interactive terminals open a two-tab TUI (Global / Local). Non-interactive runs accept flags.

uvx skilly configure                 # Open the TUI
uvx skilly configure --show          # Print current config as TOML
uvx skilly configure --reset         # Restore defaults

Add or remove custom directories:

uvx skilly configure --add-global /opt/skills
uvx skilly configure --add-local .project/skills
uvx skilly configure --remove-global /opt/skills
uvx skilly configure --remove-local .project/skills

Enable or disable built-in destinations (valid keys: agents_global, agents_local, claude_global, claude_local, codex_global, codex_local, copilot_global, copilot_local):

uvx skilly configure --enable agents_global --disable copilot_global

Configuration is stored in ~/.skilly.toml:

enabled_builtin = ["agents_global", "agents_local", ...]
custom_global_dirs = []
custom_local_dirs = []

GitHub Authentication

Set a token for higher API rate limits (first available wins: SKILLY_GITHUB_TOKEN, GITHUB_TOKEN, GH_TOKEN):

export SKILLY_GITHUB_TOKEN=ghp_your_token

All GitHub-fetching commands also accept --github-token.

Python API

SkillRepository bundles a directory and project settings for stateful workflows:

from pathlib import Path
from skilly import ProjectSettings, Skill, SkillRepository

repository = SkillRepository(
    directory=Path(".agents/skills"),
    project=ProjectSettings(
        dependency_groups=("dev",),
        optional_dependencies=("docs",),
    ),
)

repository.install(
    Skill(
        name="code-review",
        description="Review code for correctness and maintainability.",
        content="# Instructions\n\nReview the proposed change.",
    )
)

for match in repository.scan_project():
    print(match.available.name, match.status)

Stateless discovery functions for one-shot reads:

from skilly import discover_installed_skills, discover_venv_skills

installed = discover_installed_skills()
dependency_skills = discover_venv_skills()

SkillsMP client with typed results:

from skilly.skillsmp import ClientSettings, SkillsMp, SkillsMpSearchQuery

client = SkillsMp(settings=ClientSettings(base_url="https://skillsmp.com/api/v1"))
result = client.search(SkillsMpSearchQuery(text="python", limit=5))
print(result.data.skills[0].github_url)

Development

just install      # Install dev dependencies + editable extension
just lint         # Run linters
just test         # Run tests
just typecheck    # Run type checkers

License

MIT