my-thing-skillpack/            (one wiki repo, one adompkg package)
  SKILL.md                     # the main skill — REQUIRED at repo root by the registry
  README.md                    # rendered on the Overview tab; includes the skill-map table
  page.json                    # title, brief, hero, visibility
  package.json                 # version, files[] lists EVERY skill file, scripts.install/uninstall
  install.sh                   # copies the main skill AND every sub-skill to ~/.claude/skills/<name>/
  uninstall.sh                 # removes them all
  screenshots/hero.png
  skills/
    sub-a/SKILL.md             # each sub-skill: its own folder + SKILL.md
    sub-b/SKILL.md

#!/usr/bin/env bash
set -e
DEST="$HOME/.claude/skills"
install_skill() { mkdir -p "$DEST/$1"; cp "$2" "$DEST/$1/SKILL.md"; }
install_skill my-thing-skillpack SKILL.md
install_skill sub-a              skills/sub-a/SKILL.md
install_skill sub-b              skills/sub-b/SKILL.md
echo "OK: Installed my-thing-skillpack plus 2 bundled skills to $DEST/."

---
name: wiki-skillpack
description: >-
  How to build a Skillpack — one Adom Wiki repo that bundles a main skill plus
  many sub-skills, installed together by a single adompkg install, with the slug
  suffix -skillpack so the class is recognizable. Covers the bundle layout (root
  SKILL.md + skills/<sub>/SKILL.md), an install.sh that lists every skill, the
  package.json files[] whitelist, frontmatter conventions, and the skill-map
  table. Read BEFORE creating a new skill set so you never make a repo per skill.
  Trigger words: make a skillpack, super skill, bundle skills, one repo many
  skills, skill bundle, do not make a repo per skill, skillpack suffix, author a
  skill set, SKILL.md bundle, install.sh skills, wiki skill package.
---

Parent skill: **adom-wiki-skillpack**

# Building a Skillpack (super-skill bundle)

A **Skillpack** is one wiki repo / one installable package that carries a main
skill plus many sub-skills, all deployed by a single `adompkg install`. Use it
when one author owns all the skills and they version together — see
**wiki-repo-styles** for Skillpack-vs-Family.

> **The mistake to never make:** do **not** create one wiki page per small skill.
> A skill as small as a tooltip spec is a *file in a bundle*, not its own repo. A
> page per skill clutters the namespace, fragments install, and duplicates
> metadata. If you catch yourself looping `POST /pages` for many small skills,
> stop — you want one Skillpack with many files under `skills/`.

## The `-skillpack` suffix convention

A Skillpack's slug ends in **`-skillpack`** (e.g. `adom-wiki-skillpack`) so the
class is instantly recognizable in the wiki grid and in `~/.claude/skills/`. The
prior example `adom-ui-design` predates the convention and is grandfathered; new
super-skill bundles should adopt the suffix.

## The bundle layout

```
my-thing-skillpack/            (one wiki repo, one adompkg package)
  SKILL.md                     # the main skill — REQUIRED at repo root by the registry
  README.md                    # rendered on the Overview tab; includes the skill-map table
  page.json                    # title, brief, hero, visibility
  package.json                 # version, files[] lists EVERY skill file, scripts.install/uninstall
  install.sh                   # copies the main skill AND every sub-skill to ~/.claude/skills/<name>/
  uninstall.sh                 # removes them all
  screenshots/hero.png
  skills/
    sub-a/SKILL.md             # each sub-skill: its own folder + SKILL.md
    sub-b/SKILL.md
```

`adompkg install my-thing-skillpack` then drops the main skill plus every
sub-skill onto the container as separate, independently-loadable skill files.

## install.sh lists every skill explicitly

The publish linter rejects an `install.sh` that misses any bundled sub-skill, so
**list each one — do not rely on a glob.**

```bash
#!/usr/bin/env bash
set -e
DEST="$HOME/.claude/skills"
install_skill() { mkdir -p "$DEST/$1"; cp "$2" "$DEST/$1/SKILL.md"; }
install_skill my-thing-skillpack SKILL.md
install_skill sub-a              skills/sub-a/SKILL.md
install_skill sub-b              skills/sub-b/SKILL.md
echo "OK: Installed my-thing-skillpack plus 2 bundled skills to $DEST/."
```

`uninstall.sh` removes the same set. `package.json` `files[]` must list `SKILL.md`,
`README.md`, `page.json`, `install.sh`, `uninstall.sh`, every `skills/<sub>/SKILL.md`,
and any `screenshots/*`, plus `scripts.install`/`scripts.uninstall`.

## Sub-skill naming & frontmatter

- Name sub-skills to avoid clobbering generic names in the shared
  `~/.claude/skills/` dir — prefix them with the pack's domain (this pack uses
  `wiki-*`: `wiki-api`, `wiki-hero`). The folder name = the `name:` frontmatter.
- First body line of each sub-skill: `Parent skill: **<pack-slug>**`.
- Only `name` + `description` are pre-loaded, so the description must carry enough
  signal to be picked, ending with a generous list of quoted trigger phrases. Keep
  each body to one job; if a skill grows past one purpose, split it into another
  file in the same bundle.

## The skill-map table

The main `SKILL.md` and the `README.md` should each carry a **skill-map table**
(Skill | what it's for) so both the AI and humans can see the whole set and route
to the right sub-skill. This is the navigational backbone of a Skillpack.

## Publishing

Publish the whole package via the standard workflow (**wiki-api** /
**wiki-publish-safely**): create the page once, `adompkg publish` the tarball,
push all files to git with a complete `page.json` LAST, then verify in pup that
`adompkg install` deploys every skill. The live reference for this whole pattern
is **adom-ui-design** (and this pack itself).