<!-- generated by epythet -->

# skill

AI Agent Skill Search and Management

Manage [Agent Skills](https://agentskills.io) (SKILL.md files) across multiple AI coding agents — Claude Code, Cursor, GitHub Copilot, Windsurf, and more.

## Install

```default
pip install skill
```

## Quick Start

```python
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:

```python
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

```default
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:

```bash
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:

```bash
# 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`](https://cli.github.com/manual/gh_skill) (don’t have it?
[install gh](https://cli.github.com/)):

```bash
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:

```python
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`:

```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.

<p class="epythet-aggregates">This documentation as a single file: <a href="skill.md">skill.md</a> (Markdown, for agents).</p>