# Skill Package Setup

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-thorwhalen-skill-skill-package-setup`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [thorwhalen](https://agentstack.voostack.com/s/thorwhalen)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [thorwhalen](https://github.com/thorwhalen)
- **Source:** https://github.com/thorwhalen/skill/tree/master/skills/skill-package-setup
- **Website:** https://thorwhalen.github.io/skill/

## Install

```sh
agentstack add skill-thorwhalen-skill-skill-package-setup
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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/`).
2. 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.
3. Add relative per-skill symlinks in `.claude/skills/` (or `skill link-skills .`).
4. Classify audience (consumer vs developer) — reuse **skill-enable**'s signal
   lists. Prefix maintainer skills `-dev-…`; put `metadata.audience` in
   frontmatter.
5. If pip-shipping, wire package-data (**skill-enable** owns the mechanics).
6. README "Skills" section with `gh skill install / ` lines
   (**skill-docs** can generate it).
7. 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.
4. **Consolidate** any duplicates so real files exist in exactly one place.
5. **Fix spec conformance** (checklist below).
6. **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](https://github.com/thorwhalen)
- **Source:** [thorwhalen/skill](https://github.com/thorwhalen/skill)
- **License:** MIT
- **Homepage:** https://thorwhalen.github.io/skill/

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-thorwhalen-skill-skill-package-setup
- Seller: https://agentstack.voostack.com/s/thorwhalen
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.