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.
pip install skill
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")
# built-in targets: claude-code, codex (symlink), cursor, copilot, windsurf, cline, gemini (translated)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.
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
Enable tab completion for all skill commands:
skill install-completionThis 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.
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.
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.