feat: refactor built-in skills into a runtime-served multi-skill system

.github/workflows/validate-skills.yml

@@ -5,13 +5,15 @@ on:
   pull_request:
     paths:
       - 'skills/**'
+      - 'skill-data/**'
       - 'package.json'
       - '.github/workflows/validate-skills.yml'
   push:
     branches:
       - main
     paths:
       - 'skills/**'
+      - 'skill-data/**'
       - 'package.json'
       - '.github/workflows/validate-skills.yml'
 

README.md

@@ -153,20 +153,27 @@ Recommended sequence:
 5. Export WebM recordings when reviewers need motion proof.
 6. Destroy the session when done.
 
-## AI agent skill
+## AI agent skills
 
-The public skill lives under `skills/agent-tty/` and ships in the npm package as well as the GitHub Release tarball.
-Install `agent-tty` from npm first (or from a GitHub Release tarball when you need a registry-independent fallback), then either use the packaged skill directly or let TanStack Intent map it into your agent config.
+`agent-tty` ships two related skill trees in the npm package as well as the GitHub Release tarball:
 
-For coding agents that can ingest instructions on demand, `agent-tty skill` prints the packaged `SKILL.md` directly to stdout after installation.
+- `skills/agent-tty/` is the thin public bootstrap used by TanStack Intent and other skill loaders that discover files directly.
+- `skill-data/` contains the canonical runtime skills served by the CLI.
+- `agent-tty skills list` discovers the bundled runtime skills, including `agent-tty` and `dogfood-tui`.
+
+Install `agent-tty` from npm first (or from a GitHub Release tarball when you need a registry-independent fallback), then either copy the bootstrap skill into your agent config or let the CLI print the canonical runtime skill on demand.
+
+For coding agents that can ingest instructions on demand, `agent-tty skills get <name>` prints the packaged runtime `SKILL.md` directly to stdout after installation.
 
 ```bash
-agent-tty skill
+agent-tty skills get agent-tty
 ```
 
+Use `agent-tty skills list` to discover every bundled runtime skill, and `agent-tty skills get dogfood-tui` when you want the built-in TUI dogfooding skill.
+
 ### TanStack Intent integration
 
-After installing `agent-tty` in the project, let Intent wire the mapping into `AGENTS.md`, `CLAUDE.md`, or another supported agent config file.
+After installing `agent-tty` in the project, let Intent wire the bootstrap from `skills/agent-tty/` into `AGENTS.md`, `CLAUDE.md`, or another supported agent config file.
 
 ```bash
 PACKAGE_VERSION=<version>
@@ -175,27 +182,29 @@ npx @tanstack/intent@latest list
 npx @tanstack/intent@latest install
 ```
 
-That workflow keeps the skill version aligned with the installed `agent-tty` package and avoids writing one-off instructions for each individual coding agent.
+That workflow keeps the skill version aligned with the installed `agent-tty` package, while the bootstrap stays small and points agents back to the CLI-served runtime skill.
 
 ### Mux skill installation
 
-After installing the npm package globally:
+After installing the npm package globally, copy the bootstrap skill from `skills/agent-tty/`:
 
 ```bash
 mkdir -p ~/.mux/skills/agent-tty
 cp -R "$(npm root -g)/agent-tty/skills/agent-tty/." ~/.mux/skills/agent-tty/
 ```
 
+Mux can then discover the bootstrap normally, and the bootstrap instructs the agent to load the canonical runtime skill with `agent-tty skills get agent-tty`.
+
 ### Direct skill copy for other skill loaders
 
-After installing the npm package globally:
+After installing the npm package globally, copy the same bootstrap for loaders that read skill files directly:
 
 ```bash
 mkdir -p ~/.claude/skills/agent-tty
 cp -R "$(npm root -g)/agent-tty/skills/agent-tty/." ~/.claude/skills/agent-tty/
 ```
 
-If your assistant supports repository-backed skills, point it at `coder/agent-tty` and select the `agent-tty` skill directory.
+If your assistant supports repository-backed skills, point it at `coder/agent-tty` and select the `skills/agent-tty/` bootstrap directory.
 
 ### Suggested `AGENTS.md` / `CLAUDE.md` snippet
 
@@ -214,7 +223,7 @@ Preferred workflow:
 6. Destroy the session when the task is done.
 ```
 
-Maintainers can validate the shipped skill locally with:
+Maintainers can validate the shipped bootstrap skill locally with:
 
 ```bash
 npm run intent:validate

docs/CONTRIBUTING.md

@@ -41,7 +41,7 @@ Or use the combined entry point:
 npm run verify
 ```
 
-If you touch the public skill, also run:
+If you touch the public bootstrap under `skills/` or the bundled runtime skills under `skill-data/`, also run:
 
 ```bash
 npm run intent:validate
@@ -51,5 +51,6 @@ npm run intent:validate
 
 - Keep the root docs split clear: `README.md` for overview, `RELEASE.md` for current scope, `ROADMAP.md` for future scope.
 - Update [`design/README.md`](../design/README.md) when the active vs archived design split changes.
+- Keep the skill split clear in docs and packaging notes: `skills/` contains the thin public bootstrap, while `skill-data/` contains the canonical runtime skills served by `agent-tty skills get`.
 - Update [`dogfood/CATALOG.md`](../dogfood/CATALOG.md) when you add or promote a reviewer-facing proof bundle.
 - Prefer public `agent-tty ...` invocations in shipped skill/docs examples; do not commit repo-local `npx tsx src/cli/main.ts ...` substitutions into public-facing examples.

docs/RELEASE-PROCESS.md

@@ -40,7 +40,7 @@ If `mise` is unavailable, run:
 npm run verify
 ```
 
-If the public skill changed, also run:
+If the public bootstrap under `skills/` or the bundled runtime skills under `skill-data/` changed, also run:
 
 ```bash
 npm run intent:validate
@@ -60,6 +60,8 @@ cat "$RELEASE_DIR/package-metadata.json"
 sha256sum -c "$RELEASE_DIR"/*.tgz.sha256
 ```
 
+When skill packaging changes, also inspect `npm pack --dry-run` output to confirm the tarball still includes both `skills/` (bootstrap) and `skill-data/` (runtime skills).
+
 That command produces the same tarball, checksum, and metadata shape that the GitHub release workflow uploads and later reuses for npm publishing.
 
 ## Release flow overview

dogfood/20260413-skills-runtime-refactor/agent-tty-home.txt

@@ -0,0 +1 @@
+/tmp/tmp.FCAJKW974f

dogfood/20260413-skills-runtime-refactor/command-log.tsv

@@ -0,0 +1,28 @@
+agent-tty-home.txt	0	mktemp -d > /home/coder/.mux/src/agent-terminal/agent_exec_db10489d06/dogfood/20260413-skills-runtime-refactor/agent-tty-home.txt
+skills-list.json	0	npx tsx src/cli/main.ts skills list --json > /home/coder/.mux/src/agent-terminal/agent_exec_db10489d06/dogfood/20260413-skills-runtime-refactor/skills-list.json
+skills-get-agent-tty.json	0	npx tsx src/cli/main.ts skills get agent-tty --json > /home/coder/.mux/src/agent-terminal/agent_exec_db10489d06/dogfood/20260413-skills-runtime-refactor/skills-get-agent-tty.json
+skills-get-dogfood-tui.json	0	npx tsx src/cli/main.ts skills get dogfood-tui --json > /home/coder/.mux/src/agent-terminal/agent_exec_db10489d06/dogfood/20260413-skills-runtime-refactor/skills-get-dogfood-tui.json
+skills-path-agent-tty.json	0	npx tsx src/cli/main.ts skills path agent-tty --json > /home/coder/.mux/src/agent-terminal/agent_exec_db10489d06/dogfood/20260413-skills-runtime-refactor/skills-path-agent-tty.json
+skills-path-dogfood-tui.json	0	npx tsx src/cli/main.ts skills path dogfood-tui --json > /home/coder/.mux/src/agent-terminal/agent_exec_db10489d06/dogfood/20260413-skills-runtime-refactor/skills-path-dogfood-tui.json
+npm-pack-skill-files.txt	0	npm pack --json --dry-run 2>/dev/null | jq -r '.[0].files[] | .path' | grep -E '^(skills|skill-data)/' > /home/coder/.mux/src/agent-terminal/agent_exec_db10489d06/dogfood/20260413-skills-runtime-refactor/npm-pack-skill-files.txt
+tui-doctor.json	0	npx tsx src/cli/main.ts --home /tmp/tmp.FCAJKW974f doctor --json > /home/coder/.mux/src/agent-terminal/agent_exec_db10489d06/dogfood/20260413-skills-runtime-refactor/tui-doctor.json
+tui-create.json	0	npx tsx src/cli/main.ts --home /tmp/tmp.FCAJKW974f create --json -- npx tsx test/fixtures/apps/hello-prompt/main.ts > /home/coder/.mux/src/agent-terminal/agent_exec_db10489d06/dogfood/20260413-skills-runtime-refactor/tui-create.json
+session-id.txt	0	jq -r '.result.sessionId' /home/coder/.mux/src/agent-terminal/agent_exec_db10489d06/dogfood/20260413-skills-runtime-refactor/tui-create.json > /home/coder/.mux/src/agent-terminal/agent_exec_db10489d06/dogfood/20260413-skills-runtime-refactor/session-id.txt
+tui-wait-ready.json	0	npx tsx src/cli/main.ts --home /tmp/tmp.FCAJKW974f wait 01KP34JQENXVMGTMHQW8GSTHJH --json --text READY\>\  > /home/coder/.mux/src/agent-terminal/agent_exec_db10489d06/dogfood/20260413-skills-runtime-refactor/tui-wait-ready.json
+tui-type-agent.json	0	npx tsx src/cli/main.ts --home /tmp/tmp.FCAJKW974f type 01KP34JQENXVMGTMHQW8GSTHJH --json Agent > /home/coder/.mux/src/agent-terminal/agent_exec_db10489d06/dogfood/20260413-skills-runtime-refactor/tui-type-agent.json
+tui-send-enter.json	0	npx tsx src/cli/main.ts --home /tmp/tmp.FCAJKW974f send-keys 01KP34JQENXVMGTMHQW8GSTHJH --json Enter > /home/coder/.mux/src/agent-terminal/agent_exec_db10489d06/dogfood/20260413-skills-runtime-refactor/tui-send-enter.json
+tui-wait-echo.json	0	npx tsx src/cli/main.ts --home /tmp/tmp.FCAJKW974f wait 01KP34JQENXVMGTMHQW8GSTHJH --json --text ECHO:\ Agent > /home/coder/.mux/src/agent-terminal/agent_exec_db10489d06/dogfood/20260413-skills-runtime-refactor/tui-wait-echo.json
+tui-wait-stable.json	0	npx tsx src/cli/main.ts --home /tmp/tmp.FCAJKW974f wait 01KP34JQENXVMGTMHQW8GSTHJH --json --screen-stable-ms 500 > /home/coder/.mux/src/agent-terminal/agent_exec_db10489d06/dogfood/20260413-skills-runtime-refactor/tui-wait-stable.json
+tui-snapshot-text.json	0	npx tsx src/cli/main.ts --home /tmp/tmp.FCAJKW974f snapshot 01KP34JQENXVMGTMHQW8GSTHJH --format text --json > /home/coder/.mux/src/agent-terminal/agent_exec_db10489d06/dogfood/20260413-skills-runtime-refactor/tui-snapshot-text.json
+tui-screenshot-echo.json	0	npx tsx src/cli/main.ts --home /tmp/tmp.FCAJKW974f screenshot 01KP34JQENXVMGTMHQW8GSTHJH --json > /home/coder/.mux/src/agent-terminal/agent_exec_db10489d06/dogfood/20260413-skills-runtime-refactor/tui-screenshot-echo.json
+copy-screenshot	0	cp /tmp/tmp.FCAJKW974f/sessions/01KP34JQENXVMGTMHQW8GSTHJH/artifacts/screenshot-5-reference-dark.png /home/coder/.mux/src/agent-terminal/agent_exec_db10489d06/dogfood/20260413-skills-runtime-refactor/screenshots/hello-prompt-echo.png
+tui-type-exit.json	0	npx tsx src/cli/main.ts --home /tmp/tmp.FCAJKW974f type 01KP34JQENXVMGTMHQW8GSTHJH --json exit > /home/coder/.mux/src/agent-terminal/agent_exec_db10489d06/dogfood/20260413-skills-runtime-refactor/tui-type-exit.json
+tui-send-enter-exit.json	0	npx tsx src/cli/main.ts --home /tmp/tmp.FCAJKW974f send-keys 01KP34JQENXVMGTMHQW8GSTHJH --json Enter > /home/coder/.mux/src/agent-terminal/agent_exec_db10489d06/dogfood/20260413-skills-runtime-refactor/tui-send-enter-exit.json
+tui-wait-exit.json	0	npx tsx src/cli/main.ts --home /tmp/tmp.FCAJKW974f wait 01KP34JQENXVMGTMHQW8GSTHJH --json --exit > /home/coder/.mux/src/agent-terminal/agent_exec_db10489d06/dogfood/20260413-skills-runtime-refactor/tui-wait-exit.json
+tui-inspect-final.json	0	npx tsx src/cli/main.ts --home /tmp/tmp.FCAJKW974f inspect 01KP34JQENXVMGTMHQW8GSTHJH --json > /home/coder/.mux/src/agent-terminal/agent_exec_db10489d06/dogfood/20260413-skills-runtime-refactor/tui-inspect-final.json
+tui-record-export-cast.json	0	npx tsx src/cli/main.ts --home /tmp/tmp.FCAJKW974f record export 01KP34JQENXVMGTMHQW8GSTHJH --format asciicast --out /home/coder/.mux/src/agent-terminal/agent_exec_db10489d06/dogfood/20260413-skills-runtime-refactor/recordings/hello-prompt.cast --json > /home/coder/.mux/src/agent-terminal/agent_exec_db10489d06/dogfood/20260413-skills-runtime-refactor/tui-record-export-cast.json
+tui-record-export-webm.json	0	npx tsx src/cli/main.ts --home /tmp/tmp.FCAJKW974f record export 01KP34JQENXVMGTMHQW8GSTHJH --format webm --out /home/coder/.mux/src/agent-terminal/agent_exec_db10489d06/dogfood/20260413-skills-runtime-refactor/recordings/hello-prompt.webm --json > /home/coder/.mux/src/agent-terminal/agent_exec_db10489d06/dogfood/20260413-skills-runtime-refactor/tui-record-export-webm.json
+tui-destroy.json	0	npx tsx src/cli/main.ts --home /tmp/tmp.FCAJKW974f destroy 01KP34JQENXVMGTMHQW8GSTHJH --json > /home/coder/.mux/src/agent-terminal/agent_exec_db10489d06/dogfood/20260413-skills-runtime-refactor/tui-destroy.json
+validate-bundle	0	node --input-type=module <bundle-validation>
+manifest.json	0	write /home/coder/.mux/src/agent-terminal/agent_exec_db10489d06/dogfood/20260413-skills-runtime-refactor/manifest.json
+notes.md	0	python3 <write-notes>