Adom Wiki

@@ -83,34 +83,67 @@ adom-wiki repo clone <owner>/<slug>          # browse / get the source Add `--json` to any command for a `{ status, data, hints[] }` envelope. **Read the hints**: each carries a ready-to-run `cmd` for the next step. -## Skills: the three-tier layout (user vs dev vs publish)+## Skill types: the three-tier layout (user, dev, publish)  Every app should ship a skill, but not every skill you write should reach the-people who install the app. Sort skills into three top-level directories; the-directory IS the tier (nothing goes in the SKILL.md frontmatter):--| Directory | Tier | Who it is for | Ships in the install tarball? |-|---|---|---|---|-| `skills/` | **User** | everyone who installs the app (user-invocable) | YES |-| `dev-skills/` | **Dev** | whoever checks out the source: build, debug, test | NO (source-only) |-| `publish-skills/` | **Publish** | app -> wiki glue: how to publish/release THIS app | NO (source-only) |--`adom-wiki pkg publish` / `pkg pack` **auto-exclude `dev-skills/` and-`publish-skills/` from the tarball** — you no longer have to remember to strip-them. They stay in the source tree, so `adom-wiki repo push` keeps them on the-page (the Files tab and the Skills tab show all three tiers); only `skills/`-installs for consumers. Every pack/publish echoes a `SKILL_LAYOUT` hint telling-you exactly what shipped vs what stayed source-only.--Rule of thumb: if a skill is only useful with the source in front of you (running-the build, wiring the release), it is a dev or publish skill — put it in-`dev-skills/` or `publish-skills/`. If a user of the installed app would invoke-it, it is a user skill — put it in `skills/`.--Writing a good user skill: give it YAML frontmatter with `name` and a rich,-trigger-laden `description` (the phrases a user would actually say), `user-invocable: true`,-and a body that teaches the fastest path, not an exhaustive reference. One skill =-one clear job.+people who install the app. Skills come in **three types**, sorted by a top-level+directory. The directory IS the type — nothing about the type goes in the+SKILL.md frontmatter.++| Directory | Type | For | Examples | In install tarball? | On the page? |+|---|---|---|---|---|---|+| `skills/` | **User** | everyone who installs the app; user-invocable | "deploy my app", "connect to a device", "run a scan" | YES | YES |+| `dev-skills/` | **Dev** | whoever checks out the SOURCE: build, debug, test | "run the test suite", "cross-compile", "debug the daemon", "regenerate fixtures" | NO | YES |+| `publish-skills/` | **Publish** | the app→wiki glue: how to release/publish THIS app | "cut a release", "bump the version and republish", "update the hero/screenshots" | NO | YES |++A root-level `SKILL.md` (no directory) counts as a **User** skill.++### How each type reaches the wiki (the whole point)++There are two storage layers (see above), and the types map onto them:++- **User skills ride the package layer.** `pkg publish` bundles `skills/` + the+  root `SKILL.md` into the install tarball, so every `pkg install` gets them.+- **Dev + Publish skills are source.** `pkg publish` / `pkg pack` **auto-exclude**+  `dev-skills/` and `publish-skills/` from the tarball — you never have to+  remember to strip them. They reach the wiki the way ALL your source does: a+  **`repo push`** into the git page repo (the Files tab). Publish does NOT push+  them for you.++So the normal flow is two commands: `pkg publish` (ships the user skills to+installers) and `repo push` (puts your source — including the dev/publish skills+— on the page). On every pack/publish the CLI prints a `SKILL_LAYOUT` hint with+the split and, when dev/publish tiers exist, the exact command to run:++```bash+adom-wiki repo push <owner>/<slug> --files dev-skills publish-skills -m "add dev/publish skills"+```++### Where they show up++The page's **Skills tab** splits into three sub-tabs — **User | Dev | Publish** —+read from the git repo (with a `?` tooltip explaining the types). A visitor+browsing the page sees all three tiers; a consumer who `pkg install`s the app+gets only the User tier. That is the point of the split: teach/collaborate with+the full set, ship only what users invoke.++### Which type is it?++If a skill is only useful with the source in front of you (running the build,+wiring a release), it is a **dev** or **publish** skill → `dev-skills/` or+`publish-skills/`. If a user of the *installed* app would invoke it, it is a+**user** skill → `skills/`.++### Writing a good skill (any type)++- YAML frontmatter with `name` and a rich, **trigger-laden `description`** — the+  real phrases someone would say. Discovery search and the agent match on this;+  a vague description makes the skill unfindable.+- User skills add `user-invocable: true`.+- Body teaches the **fastest path to the one job**, not an exhaustive reference.+  One skill = one clear job; split a second job into a second skill.+- Keep dev/publish descriptions concrete about the source task ("run `cargo test`+  and read the failures", not "testing").  ## Decision table