Skill enablement — shipping skills via pip

How to ship a package's consumer skills with pip install your-package, and how to decide which skills qualify. Layout and spec compliance are owned by the skill-package-setup skill — read it first if you haven't picked a layout.

Where pip-shipped skills go (and why it just works)

To ride along with pip install, skill files must live inside the importable package: {pkg}/data/skills/<name>/. That's the only place a wheel reliably ships non-code data.

Bonus: {pkg}/data/skills/ is also a first-class gh skill source — gh skill discovers any non-hidden **/skills/*/SKILL.md, and {pkg}/data/skills/ contains a skills/ dir under the non-hidden prefix {pkg}/data/. So one real location serves both channels: pip install <pkg> (bundled, offline) and gh skill install <owner>/<repo> <name> (cross-agent). Claude Code reads neither directly, so commit a relative symlink per skill in .claude/skills/ (the bridge that skill-package-setup sets up).

Use {pkg}/data/skills/ only when you actually want skills in the wheel. Pure dev/maintainer skills belong in top-level skills/ instead (skill-package-setup rule). Never put the same skill in both — gh skill would report duplicates.

Step 1: decide which skills to ship (audience classification)

Not every skill should ship with pip install. Two audiences:

• Consumer skills (metadata.audience: users) — help people use the package. These ship ({pkg}/data/skills/). E.g. "how to search for skills", "how to build storage interfaces with dol".
• Contributor skills (metadata.audience: developers) — help people develop/contribute. These stay in top-level skills/ and do NOT ship. E.g. "run the test suite", "set up the dev environment", "CI/CD workflow".

Some serve both — mark metadata.audience: both.

Spec note: audience is not a top-level spec field — put it under metadata:. A bare top-level audience: fails gh skill publish validation.

How to classify

If the skill has metadata.audience, respect it. Otherwise infer from name, description, and body:

Developer-only signals — if most apply and no consumer signals do → developers:

• Name contains: dev, debug, ci, lint, contrib, internal, test, setup-dev, release
• Description: "contribute to", "develop the package", "maintain the codebase", "internal tooling", "run the test suite", "CI/CD pipeline for this project", "set up a development environment"
• Body primarily references: dev setup (virtualenv, editable installs), running tests (pytest/tox/nox), linting/formatting (ruff/black/mypy), git/PR workflow, CI config (.github/workflows/), release processes, contributor-only internals
• Only makes sense with the repo checked out — not just the installed package

Consumer signals — if any apply, likely for users:

• Description focuses on what users do with the package: "use this skill when", "how to search/build/configure"
• Body references the public API available after pip install
• Works for someone who only has the installed package (no repo checkout)

When in doubt, include it — classify users unless clearly developer-only.

Applying it

Ship only consumer skills (users/both) from {pkg}/data/skills/; keep developer-only skills in top-level skills/. For each excluded skill, tell the user:

"Keeping {name} in top-level skills/ (not pip-shipped) — classified developer-only because {reason}. To ship it anyway, set metadata.audience: both."

Step 2: layout (delegate to skill-package-setup)

your-package/
├── your_pkg/
│   └── data/skills/                 ← pip-shipped consumer skills (real files)
│       ├── your-pkg-feature-a/SKILL.md
│       └── your-pkg-feature-b/
│           ├── SKILL.md
│           └── references/api-guide.md
├── skills/                          ← dev/maintainer skills (real files, not shipped)
│   └── your-pkg-dev-task/SKILL.md
├── .claude/skills/                  ← relative symlinks into BOTH of the above
│   ├── your-pkg-feature-a -> ../../your_pkg/data/skills/your-pkg-feature-a
│   └── your-pkg-dev-task  -> ../../skills/your-pkg-dev-task
├── pyproject.toml
└── README.md

(skill-package-setup's runbook has the exact git mv + symlink commands.)

Step 3: include the data in the distribution

Hatchling (most thorwhalen repos):

[tool.hatch.build.targets.wheel]
include = ["your_pkg/data/*"]      # or rely on hatchling's implicit your_pkg/** inclusion

Setuptools:

[tool.setuptools.package-data]
your_pkg = ["data/skills/**/*"]

Verify the wheel actually contains them:

python -m build --wheel >/dev/null && unzip -l dist/*.whl | grep -i skills

Step 4: document install (README)

gh skill is the primary, cross-agent path; pip is the bundled/offline path:

## Skills (AI agent integration)

# Cross-agent (any host), versioned:
gh skill install your-org/your-repo your-pkg-feature-a --agent claude-code

# Or use the skills bundled with the pip package (offline):
pip install your-package
skill link-skills "$(python -c 'import your_pkg, os; print(os.path.join(your_pkg.__path__[0], "data", "skills"))')"

Step 5 (optional): convenience helpers

# your_pkg/__init__.py or your_pkg/skills.py
from pathlib import Path


def skills_dir() -> Path:
    """Return the path to this package's bundled skills directory."""
    return Path(__file__).parent / "data" / "skills"

Then a CLI installer:

def install_skills(target: str = ""):
    """Install this package's bundled AI agent skills."""
    from skill import link_skills
    from your_pkg import skills_dir

    link_skills(str(skills_dir()), target=target)

And/or entry-point registration so skill search finds them pre-link:

[project.entry-points."skill.skill_packs"]
your-pkg = "your_pkg:skills_dir"

Common pitfalls

• Forgetting package-data — declare it (Step 3) or the wheel omits the skills; test with pip install -e . + the unzip -l check.
• Hardcoding paths — use Path(__file__).parent / importlib.resources.
• Same skill in two real locations — gh skill reports duplicates. One real location per skill (skill-package-setup rule).
• Top-level audience: — must be metadata.audience or gh skill publish rejects it.
• Shipping dev-only skills — they clutter users' skill lists; keep them in top-level skills/, not {pkg}/data/skills/.
• Large reference files bloat the wheel — keep references lean or fetch on demand.

Related

• skill-package-setup — the canonical layout & spec authority (read first).
• skill-docs — generate the README "Skills" section.
• skill-build / skill-creator — author skill content.
• skill-sync — keep shipped skills in sync with the code they document.