docs: add stanza-cli installable agent skill and reference it from AGENTS.md

- Add `skills/stanza-cli/SKILL.md` — a self-contained agent skill covering the published CLI surface: runtime contract, non-interactive `init`/`add`/`remove`/`list`/`search` usage, slot vs. add-on semantics, safety flags (`--dry-run`, `--dangerously-allow-dirty`, `STANZA_REGISTRY`), error handling, and agent rules; intended for agents that don't have access to this source repo
- Add `skills/stanza-cli/agents/openai.yaml` with display name, short description, and default prompt for OpenAI agent tooling
- Update `AGENTS.md` with a "Distributed Skill" section noting that `skills/stanza-cli/SKILL.md` must be kept in sync whenever CLI flags, command behaviour, slot/add-on names, or published package names change

AGENTS.md

@@ -41,6 +41,10 @@ In a **generated project**, `auth`, `db`, and `orm` modules install into their o
 - `pnpm changeset` — create a new changeset describing what changed (run after a substantive PR)
 - `pnpm release` — build CLI/create-stanza and publish to npm (only runs in CI; locally use `pnpm pack` to inspect tarballs)
 
+## Distributed Skill
+
+- `skills/stanza-cli/SKILL.md` is the installable agent skill for using Stanza through the npm-distributed CLI. Keep it accurate whenever CLI flags, command behavior, slot/add-on names, registry resolution, or published package names change; agents using the skill may not have access to this source repo and will rely on the public CLI contract alone.
+
 ## Toolchain invariants
 
 - **Node-only at runtime.** The CLI source uses node APIs and is dev-run via `tsx`; the published binary is plain ESM JS (`#!/usr/bin/env node`). The only place bun appears is the shebang on root maintainer scripts (`scripts/*.ts`) for our own convenience — those scripts don't use any `Bun.*` APIs and run fine under tsx/node

skills/stanza-cli/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: stanza-cli
+description: Use the npm-distributed Stanza CLI non-interactively to scaffold or modify modular full-stack TypeScript monorepos. Use when a user asks an agent to run `stanza`, `create-stanza`, `npm create stanza`, add/remove/list/search Stanza modules, generate a Stanza project in CI, or work with a Stanza-based TypeScript monorepo.
+---
+
+# Stanza CLI
+
+Use only the published CLI surface. Do not assume the Stanza source repo, local `registry/modules`, maintainer scripts, or workspace packages are available unless the user explicitly provides them.
+
+## Runtime Contract
+
+- The CLI package is `@stanza/cli`; the binary is `stanza`.
+- The create package is `create-stanza`; package-manager create commands forward to `stanza init`.
+- Prefer direct npm execution in automation because it avoids package-manager argument-forwarding ambiguity:
+
+```sh
+npx -y @stanza/cli@latest --help
+npx -y @stanza/cli@latest init my-app --yes --framework=next
+```
+
+- If the user wants create-style commands, use the correct separator for their package manager:
+
+```sh
+pnpm create stanza@latest my-app --yes --framework=next
+npm create stanza@latest -- my-app --yes --framework=next
+bun create stanza@latest my-app --yes --framework=next
+```
+
+## Non-Interactive Workflow
+
+1. Check the CLI surface before making assumptions:
+
+```sh
+npx -y @stanza/cli@latest --help
+npx -y @stanza/cli@latest search
+```
+
+2. Discover current module IDs with `stanza search [query]`. Registry contents evolve, so do not hardcode a module unless the user specified it or `search` confirms it.
+
+3. Scaffold with `init --yes`, passing every wanted slot/add-on explicitly:
+
+```sh
+npx -y @stanza/cli@latest init my-app --yes \
+  --framework=next \
+  --styling=tailwind \
+  --db=postgres \
+  --orm=drizzle \
+  --auth=better-auth \
+  --testing=vitest,playwright \
+  --pm=pnpm
+```
+
+4. Install dependencies using the generated manifest's package manager, then run the app's normal scripts:
+
+```sh
+cd my-app
+pnpm install
+pnpm dev
+```
+
+## Commands
+
+- `stanza init [name] --yes ...` scaffolds a new project in a child directory of the current working directory.
+- `stanza add <slot|category> <module>` adds one module to an existing Stanza project.
+- `stanza remove <slot|category> [id]` removes a slot module; add-ons require the module id.
+- `stanza list` prints installed slots and add-ons from the nearest `stanza.json`.
+- `stanza search [query]` lists registry modules and their `group/id` pairs.
+
+Run `add`, `remove`, and `list` from the project root or any child directory containing a parent `stanza.json`.
+
+## Slots And Add-Ons
+
+Current slot names are `framework`, `styling`, `db`, `orm`, and `auth`. Slots are single-choice: adding a filled slot fails until the existing slot is removed.
+
+Current add-on categories are `testing`, `tooling`, `deploy`, `email`, and `monorepo`. Add-ons are multi-choice, so multiple modules can coexist in one category. For `init --yes`, pass add-on ids as comma-separated values, for example `--testing=vitest,playwright`.
+
+`--yes` never chooses defaults for omitted slots or add-ons. Missing selections are skipped.
+
+## Safety Flags
+
+- Use `--dry-run` before a mutating command when the user wants a preview. It writes nothing.
+- Mutating commands refuse to run in a dirty git worktree. Ask the user before using `--dangerously-allow-dirty`; it intentionally allows Stanza edits to mix with existing changes.
+- Use `STANZA_REGISTRY=<url-or-path>` only when the user asks for a custom/self-hosted registry or test fixture. Otherwise let the published CLI use its default registry.
+
+## Error Handling
+
+- `Module not found`: run `stanza search` and use the displayed module id, not the label.
+- `missing-peer`, `incompatible-peer`, or `no-adapter`: the selected module does not fit the current stack. Search for alternatives or add required peer slots first.
+- `No stanza.json found`: run from a generated Stanza project, not the parent directory.
+- Dirty worktree refusal: commit/stash user changes or ask before using `--dangerously-allow-dirty`.
+- After adding package-scoped modules such as db/auth/orm, run the selected package manager install command so workspace packages link correctly.
+
+## Agent Rules
+
+- Treat generated files as user-owned project code after Stanza writes them.
+- Do not edit `stanza.json` by hand unless the user explicitly asks for manual repair.
+- Prefer CLI commands over reconstructing Stanza's template output yourself.
+- When reporting results, include the exact command run, whether it wrote files, and any follow-up package-manager command needed.

skills/stanza-cli/agents/openai.yaml

@@ -0,0 +1,3 @@
+display_name: Stanza CLI
+short_description: Use the Stanza CLI non-interactively.
+default_prompt: Use the Stanza CLI skill to scaffold or modify a Stanza project via the npm-distributed binary.