Skill Package Setup

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// | yes — gh skill matches any non-hidden **/skills/*/SKILL.md (nested-prefix glob) | no | yes (inside the package) | | skills// (repo root) | yes — same glob, the ecosystem-wide convention | no | no | | .claude/skills// | no — hidden dirs skipped (unless --allow-hidden-dirs) | yes | no | | .agents/skills// | 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// — ships via pip AND gh skill-discoverable. One location serves both channels. | | Everything else (apps, skill-only repos, dev/maintainer-only skills) | skills// 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/ is a relative symlink into the chosen location

(../../skills/ or ../..//data/skills/) — 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.

Decide: new vs migrate

1. Inventory: find . -name SKILL.md -not -path './.git/*' + ls -la .claude/skills.
2. No skills anywhere → Flow A (new). Skills already exist → Flow B (migrate).

Flow A — new package

1. Pick the canonical location per the rule (pip-shipped → {pkg}/data/skills/,

else skills/).

1. Scaffold …/-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.

1. Add relative per-skill symlinks in .claude/skills/ (or skill link-skills .).
2. Classify audience (consumer vs developer) — reuse skill-enable's signal

lists. Prefix maintainer skills -dev-…; put metadata.audience in frontmatter.

1. If pip-shipping, wire package-data (skill-enable owns the mechanics).
2. README "Skills" section with gh skill install / lines

(skill-docs can generate it).

1. 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:

1. Inventory real files vs symlinks; detect duplicates across locations.
2. Choose the one canonical location (rule above).
3. Relocate real dirs there with git mv (e.g. out of .claude/skills/),

leaving relative symlinks behind.

1. Consolidate any duplicates so real files exist in exactly one place.
2. Fix spec conformance (checklist below).
3. Validate, update the README, publish.

Spec-conformance checklist (either flow)

• [ ] Folder name equals name:; 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 / --agent ` — works

for every agent host; supports pinning (@vX.Y.Z / --pin ) 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.

• skill-enable — pip package-data wiring + audience classification.
• skill-build / skill-creator — author skill content.
• skill-docs — README "Skills" section.
• skill-sync — keep skill content in sync with the code it documents.

Full gh skill surface and Agent Skills spec: references/canonical-layout-and-distribution.md.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: thorwhalen
• Source: thorwhalen/skill
• License: MIT
• Homepage: https://thorwhalen.github.io/skill/

Install and usage instructions live in the source repository linked above.