skilly

Manage Agent Skills from the command line or Python. Creates specification-compliant skills, installs from GitHub, Bitbucket Cloud, Bitbucket Data Center, or dependencies, and keeps them up to date.

Installation

uvx skilly --help               # Python (uvx/pip)
npx @xelandernt/skilly --help   # Node (npx)
brew install xelandernt/skilly/skilly  # Homebrew

Python

uvx skilly --help

Ships CLI + Python import surface. Pre-built wheels for Linux x64, macOS arm64/x64, Windows x64.

Node

npx @xelandernt/skilly --help

Ships native Rust CLI (macOS arm64/x64, Linux x64 glibc, Windows x64). No Python import surface.

Homebrew

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

Ships native Rust CLI (macOS arm64/x64, Linux x64).

Info

See the installation guide for a full capability comparison.

Quick Start

skilly create deployment-checks \
  --description "Validate deployment readiness." \
  --instructions "# Instructions\n\nRun the deployment checklist." \
  --yes
skilly list

CLI Commands

Run skilly <command> --help for all options. Run skilly --version to print the installed package version.

Create Skills

See creating skills.

Install Dependency Skills

See dependency scanning.

Install Repository Skills

See installing and managing.

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

In an interactive terminal, skill rows show their source beneath the name (for example, GitHub · owner/repo). list checks known update sources in the background without blocking navigation: a spinner marks pending checks, while ✓, ↑, and ! mark current, updatable, and failed checks. Plain non-interactive output remains local-only.

Set a default destination:

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

--directory overrides all other destination options and SKILLY_DEFAULT_DIRECTORY.

Configuration

skilly configure manages directories and saved repository credentials.

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

Add or remove custom directories via CLI:

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

Configuration is stored in ~/.skilly.toml:

default_directory = ".agents/skills"

[global]
directories = ["~/.agents/skills", "/opt/skills"]

[local]
directories = [".agents/skills", ".project/skills"]

The default directory opens first in interactive menus (list, scan, etc.). When viewing a skill's files, press / to filter by filename and Esc to clear the filter.

Repository Authentication

For download, list, and update, Skilly resolves credentials in this order:

1. --token <TOKEN> for a one-off command.
2. A saved provider credential with the exact provider and base URL.
3. A provider environment variable.

Save a reusable credential with skilly configure, or use the non-interactive command:

skilly configure --add-provider bitbucket-data-center \
  --provider-url https://git.example.com/bitbucket \
  --provider-token "$BITBUCKET_TOKEN"

Saved tokens are redacted from skilly configure --show, never written to installed skill metadata, and stored in ~/.skilly.toml; on Unix that file is owner-only. Remove a saved credential with:

skilly configure --remove-provider bitbucket-data-center \
  --provider-url https://git.example.com/bitbucket

Use --provider bitbucket-data-center for Bitbucket Data Center repositories:

uvx skilly download https://git.example.com/bitbucket/projects/ENG/repos/skills \
  --provider bitbucket-data-center --token "$SKILLY_BITBUCKET_DATA_CENTER_TOKEN"

Python API

Full Python API reference with SkillRepository, local discovery functions, caller-owned repository discovery, source types, SkillsMP client, and custom filesystem protocol.

from pathlib import Path
from skilly import (
    ProjectSettings,
    PythonSource,
    Skill,
    SkillRepository,
)

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

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

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

Load an untrusted skill bundle directly from memory without filesystem or network access:

from pathlib import PurePosixPath
from skilly import Skill, SkillResource

skill = Skill.from_bundle(
    skill_markdown,
    (
        SkillResource(PurePosixPath("references/runbook.md"), "reference", runbook_bytes),
    ),
)

Stateless discovery functions for one-shot reads:

from skilly import (
    NodeSource,
    PythonSource,
    discover_installed_skills,
    discover_package_source_skills,
)

installed = discover_installed_skills()
python_skills = discover_package_source_skills(PythonSource())
node_skills = discover_package_source_skills(NodeSource())

ProjectSettings accepts PythonSource, NodeSource, and MavenSource:

from pathlib import Path

from skilly import (
    MavenSource,
    NodeSource,
    ProjectSettings,
    PythonSource,
    SkillRepository,
)

repository = SkillRepository(
    directory=Path(".agents/skills"),
    project=ProjectSettings(
        sources=(
            NodeSource(
                include_dependencies=True,
                include_dev_dependencies=False,
            ),
        ),
    ),
)

Use ProjectSettings(sources=()) to disable scanning, or pass individual PackageSource entries to scan only specific ecosystems. SkillRepository() defaults to Python, Node, and Maven sources.

Maven support

Maven skills are discovered from JAR artifacts in the local Maven repository (~/.m2/repository by default). The scanner:

• Reads only direct <dependencies> from pom.xml — profiles, plugins, and <dependencyManagement> are ignored.
• Resolves ${property} references defined in the same file's <properties> block.
• Loads skills from recognized archive layouts: .agents/skills/<name>/SKILL.md and skills/<name>/SKILL.md.
• Preserves binary resources inside JARs.
• Rejects coordinates with path traversal components.

Known limitations:

• Only the local repository is used; no remote artifact resolution.
• No POM inheritance or effective-model merging.
• No Gradle build file support.
• Build execution and dependency graph traversal are not performed.
• MavenSource includes compile, runtime, and test scopes by default; provided and system scopes are excluded.

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].repository_url)

Development

just install
just lint
just test
just typecheck

License

MIT