skill 0.1.11

AI Agent Skill Search and Management

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 its own AI agent skills (in skills/), installable into any agent host with gh skill (GitHub CLI ≥ 2.90.0):

gh skill preview thorwhalen/skill skill-package-setup        # inspect before installing
gh skill install thorwhalen/skill skill-package-setup --agent claude-code
gh skill install thorwhalen/skill skill-enable

Skill	What it covers
skill-package-setup	Canonical layout & distribution policy — where a package's skills live, gh skill setup, and migration
skill-build	Author skills for a package by analyzing its code, tests, and docs
skill-enable	Ship skills via pip ({pkg}/data/skills/) + audience classification
skill-docs	Document a project's skills in its README
skill-manage	Search, list, inspect, install/uninstall skills across agents
skill-sync	Keep skills in sync with the code they document

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/).

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.