Canonical, agent-agnostic policy for WHERE a package's AI agent skills live and HOW they are distributed so they're discoverable by `gh skill` (and any agent host — Copilot, Cursor, Codex, Gemini, Claude) AND, where wanted, shipped with `pip install`. Use this skill to set up skills for a new package, migrate an existing repo to the canonical layout, consolidate skills scattered across `.claude/skills/` / `skills/` / `{pkg}/data/skills/`, make every SKILL.md spec-clean, or answer "where should my package's skills live". Also the authority other skills defer to (e.g. wads-skillify). Triggers on "set up skills", "where should skills live", "make skills gh-skill installable", "migrate/restructure the skills layout", "skillify this repo". Maintainer skill.
Canonical, agent-agnostic policy for WHERE a package's AI agent skills live and HOW they are distributed so they're discoverable by `gh skill` (and any agent host — Copilot, Cursor, Codex, Gemini, Claude) AND, where wanted, shipped with `pip install`. Use this skill to set up skills for a new package, migrate an existing repo to the canonical layout, consolidate skills scattered across `.claude/skills/` / `skills/` / `{pkg}/data/skills/`, make every SKILL.md spec-clean, or answer "where should my package's skills live". Also the authority other skills defer to (e.g. wads-skillify). Triggers on "set up skills", "where should skills live", "make skills gh-skill installable", "migrate/restructure the skills layout", "skillify this repo". Maintainer skill.
metadata
{"audience":"developers"}
Skill package setup — canonical layout & distribution
The source of truth for where a package's skills live and how they ship.
Agent-agnostic; other tooling (e.g. wads-skillify) defers here for layout and
spec compliance. Two flows: set up a new package, or migrate an existing
one. Detail lives in the references — read on demand:
references/canonical-layout-and-distribution.md — the discovery facts, the
full distribution matrix, the SKILL.md spec, and the gh skill surface.
references/migration-runbook.md — exact commands for both flows.
Golden rule: observe, don't invent. Every layout move is shown as a plan
before it's applied; never break tests without asking.
Who discovers what (why layout matters)
Location
gh skill discovers?
Claude Code reads?
Ships via pip?
{pkg}/data/skills/<name>/
yes — gh skill matches any non-hidden **/skills/*/SKILL.md (nested-prefix glob)
no
yes (inside the package)
skills/<name>/ (repo root)
yes — same glob, the ecosystem-wide convention
no
no
.claude/skills/<name>/
no — hidden dirs skipped (unless --allow-hidden-dirs)
yes
no
.agents/skills/<name>/
install destination for Copilot/Cursor/Codex/Gemini
no
no
Key fact (confirmed against the gh skill manual): gh skill discovers a
skills/ directory at ANY non-hidden depth, so {pkg}/data/skills/ is a
first-class gh skill source — not a fallback. No single location serves
everyone, though: Claude Code reads only .claude/skills/. Hence the rule.
The rule (memorize this)
Real skill files live in exactly ONE non-hidden location, with relative
per-skill symlinks in .claude/skills/. Pick the location:
Repo kind
Canonical real-files location
Pip-installable package whose skills should ship with pip install
{pkg}/data/skills/<name>/ — ships via pip AND gh skill-discoverable. One location serves both channels.
skills/<name>/ at the repo root — the ecosystem convention.
Never both. Real files in both skills/ and {pkg}/data/skills/ means
gh skill reports duplicate skills. The Step-0 find in the runbook is your
duplicate check.
.claude/skills/<name> is a relative symlink into the chosen location
(../../skills/<name> or ../../<pkg>/data/skills/<name>) — Claude Code
doesn't read the canonical dirs, so this bridge is required. Symlink per skill,
never the whole .claude/skills/ dir (Claude writes .system/ files there).
Don't publish symlinks as the source. Whether gh skill dereferences a
committed symlink at the source path is undocumented — keep real files in the
canonical path; use symlinks only as the .claude/skills/ bridge.
No skills anywhere → Flow A (new). Skills already exist → Flow B (migrate).
Flow A — new package
Pick the canonical location per the rule (pip-shipped → {pkg}/data/skills/,
else skills/).
Scaffold …/<pkg>-quickstart/SKILL.md with spec-valid frontmatter
(name == folder name, lowercase [a-z0-9-]; description ≤ 1024 chars,
packed with trigger keywords). Use skill-build/skill-creator for content.
Add relative per-skill symlinks in .claude/skills/ (or skill link-skills .).
Classify audience (consumer vs developer) — reuse skill-enable's signal
lists. Prefix maintainer skills <pkg>-dev-…; put metadata.audience in
frontmatter.
If pip-shipping, wire package-data (skill-enable owns the mechanics).
README "Skills" section with gh skill install <owner>/<repo> <name> lines
(skill-docs can generate it).
Validate (gh skill publish --dry-run, or skill validate/skills-ref validate), then gh skill publish and tag a release for @vX.Y.Z pinning.
Flow B — migrate an existing repo
Full commands in references/migration-runbook.md. Shape:
Inventory real files vs symlinks; detect duplicates across locations.
Choose the one canonical location (rule above).
Relocate real dirs there with git mv (e.g. out of .claude/skills/),
leaving relative symlinks behind.
Consolidate any duplicates so real files exist in exactly one place.
Fix spec conformance (checklist below).
Validate, update the README, publish.
Spec-conformance checklist (either flow)
Folder name equalsname:; name lowercase [a-z0-9-], ≤64 chars,
no leading/trailing/double hyphens (rename foo_bar → foo-bar + the folder).
Only spec top-level keys: name, description, license,
compatibility, metadata, allowed-tools. Custom keys (notably
audience) go under metadata:. No Claude-only keys (when_to_use,
argument-hint, paths, hooks, …) in portable skills. Never agent-version.
allowed-tools, if present, is a space-separated string, not a YAML list.
description ≤ 1024 chars (what it does + when to use it); body < 500 lines
(push detail to references/).
Provenance keys (github-repo, github-path, github-ref,
github-pinned, github-tree-sha) are never hand-authored — gh skill install writes them on the consumer's machine.
Distribution
Primary:gh skill install <owner>/<repo> <name> --agent <host> — works
for every agent host; supports pinning (@vX.Y.Z / --pin <sha>) and
gh skill update.
Pip-shipped packages additionally deliver skills inside the wheel
({pkg}/data/skills/); document the offline link step too.
Always gh skill preview third-party skills before installing (not verified by GitHub).
Related skills
wads-skillify — wads-fleet repo-improvement entry; defers to this skill
for layout & compliance, adds the wads assessment baseline + dispatch.
