skill

AI Agent Skill Search and Management

Manage Agent Skills (SKILL.md files) across multiple AI coding agents — Claude Code, Cursor, GitHub Copilot, Windsurf, and more.

Install

pip install skill

Quick Start

from skill import search, create, install, validate

# Create a skill locally
skill = create("my-skill", description="My custom coding rules")

# Validate it
issues = validate("/path/to/skill-dir")

# Search for skills
results = search("react best practices", local_only=True)

# Install to an agent target
install("_local/my-skill", agent_targets=["claude-code"], scope="project")

Link skills from a project

If a project ships skills (in .claude/skills/, {pkg}/data/skills/, or a dedicated folder), you can symlink them all into your agent’s skills directory in one shot:

from skill import link_skills

# Point at a project root — it finds the skills automatically
link_skills("/path/to/my-project")

# Or point at the skills folder directly
link_skills("/path/to/my-project/my_pkg/data/skills")

# Symlink into a specific target instead of ~/.claude/skills
link_skills("/path/to/my-project", target="/other/project/.claude/skills")

Each skill is validated before linking — invalid skills are skipped with a warning. The target directory is also checked to ensure it’s a recognized skills directory.

CLI

skill create my-skill --description "My custom coding rules"
skill search "react best practices" --local-only
skill validate ./my-skill/
skill list-skills
skill install _local/my-skill --agent-targets claude-code
skill link-skills /path/to/project
skill link-skills /path/to/project --target ~/.claude/skills --force

Shell completion

Enable tab completion for all skill commands:

skill install-completion

This detects your shell (bash/zsh) and adds the registration line to your shell config (~/.bashrc or ~/.zshrc). Restart your shell or source the config file to activate.

If you prefer to set it up manually:

# Add to your shell config:
eval "$(register-python-argcomplete skill)"

The first time you run any skill command without completion set up, you’ll see a one-time hint reminding you to run skill install-completion.

Skills

This package ships agent skills you can install into any agent host with gh skill (don’t have it? install gh):

gh skill install thorwhalen/skill skill-package-setup --agent claude-code
gh skill install thorwhalen/skill skill-build
gh skill install thorwhalen/skill skill-enable
gh skill install thorwhalen/skill skill-docs
gh skill install thorwhalen/skill skill-manage
gh skill install thorwhalen/skill skill-sync

Skill	Use it when…
skill-manage	searching, listing, inspecting, or installing/uninstalling skills across agents
skill-enable	shipping a package’s skills via pip install and deciding which to ship
skill-package-setup	deciding where a package’s skills live and making them gh skill-installable (maintainer)
skill-build	authoring skills for a package by analyzing its code, tests, and docs (developer)
skill-docs	documenting a project’s skills in its README (developer)
skill-sync	keeping skills in sync with the source code they document (developer)

These are dev/maintainer skills, so they’re not bundled in the wheel — install them with gh skill as above. See skill-package-setup for the layout policy this repo follows (real files in skills/, relative symlinks in .claude/skills/).

Packages can also install their own GitHub-published skills programmatically via skill.install_from_github(repo, names, agent='claude-code'), a thin wrapper over the gh skill CLI.

Plugin System

skill has a registry-based plugin architecture with four extension points:

Registry	What it holds	Import
Agent targets	Where agents expect skills installed	from skill.install import agent_targets
Translators	SKILL.md → target format converters	from skill.translate import translators
Backends	Remote skill sources for search	from skill.search import backends
Validators	Pluggable validation rules	from skill.create import validators

Register at runtime:

from skill.install import agent_targets, AgentTarget

agent_targets.register(
    "windsurf",
    AgentTarget(
        name="windsurf",
        project_path="{project}/.windsurf/rules/{name}.md",
        format="skill.md",
    ),
)

Or via entry points in your pyproject.toml:

[project.entry-points."skill.agent_targets"]
windsurf = "my_package:windsurf_target"

See Plugin System Documentation for full details on contracts, interfaces, and built-in registrations.

This documentation as a single file: skill.md (Markdown, for agents).