From 92b3021688a5e5b5c0dc0822716da090df1b2986 Mon Sep 17 00:00:00 2001
From: Nate Moore <nate@natemoo.re>
Date: Wed, 25 Mar 2026 11:00:54 -0400
Subject: [PATCH 1/8] feat(skills): add skills

---
 .claude-plugin/plugin.json |  4 ++
 skills/build/SKILL.md      | 35 ++++++++++++++++
 skills/dev/SKILL.md        | 33 +++++++++++++++
 skills/format/SKILL.md     | 27 ++++++++++++
 skills/init/SKILL.md       | 25 ++++++++++++
 skills/lifecycle/SKILL.md  | 39 ++++++++++++++++++
 skills/lint/SKILL.md       | 84 ++++++++++++++++++++++++++++++++++++++
 skills/test/SKILL.md       | 72 ++++++++++++++++++++++++++++++++
 8 files changed, 319 insertions(+)
 create mode 100644 .claude-plugin/plugin.json
 create mode 100644 skills/build/SKILL.md
 create mode 100644 skills/dev/SKILL.md
 create mode 100644 skills/format/SKILL.md
 create mode 100644 skills/init/SKILL.md
 create mode 100644 skills/lifecycle/SKILL.md
 create mode 100644 skills/lint/SKILL.md
 create mode 100644 skills/test/SKILL.md

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
new file mode 100644
index 0000000..cccadcf
--- /dev/null
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,4 @@
+{
+  "name": "@bomb.sh/tools",
+  "description": "Claude Code skills for the Bombshell dev toolchain"
+}
diff --git a/skills/build/SKILL.md b/skills/build/SKILL.md
new file mode 100644
index 0000000..19340d5
--- /dev/null
+++ b/skills/build/SKILL.md
@@ -0,0 +1,35 @@
+---
+description: "Build TypeScript modules. Run with `pnpm run build`."
+---
+
+# Build
+
+Builds TypeScript to ESM using tsdown with opinionated defaults.
+
+## Usage
+
+```sh
+pnpm run build
+```
+
+## How It Works
+
+`pnpm run build` runs `bsh build` which calls tsdown with:
+- **Format:** ESM only
+- **Sourcemaps:** enabled
+- **Clean:** removes dist/ before building
+- **Unbundled** by default (each source file produces one output file)
+- **Entry:** defaults to `src/**/*.ts`
+
+## Flags
+
+Pass flags after `--` in pnpm:
+
+```sh
+pnpm run build -- --dts        # Generate .d.mts declaration files
+pnpm run build -- --bundle     # Bundle into single output (disables unbundled mode)
+pnpm run build -- --minify     # Minify output
+pnpm run build -- src/index.ts # Specify custom entry points
+```
+
+Flags can be combined: `pnpm run build -- --dts --minify`
diff --git a/skills/dev/SKILL.md b/skills/dev/SKILL.md
new file mode 100644
index 0000000..ff24ffa
--- /dev/null
+++ b/skills/dev/SKILL.md
@@ -0,0 +1,33 @@
+---
+description: "Run a dev watcher for TypeScript files. Run with `pnpm run dev`."
+---
+
+# Dev
+
+Runs a file with native Node TypeScript support and watches for changes.
+
+## Usage
+
+```sh
+pnpm run dev
+```
+
+## How It Works
+
+`pnpm run dev` runs `bsh dev` which shells out to:
+
+```
+node --experimental-transform-types --no-warnings --watch-path=./src/ <file>
+```
+
+- **Default file:** `./src/index.ts`
+- **Watch path:** `./src/` — restarts on any change in the source directory
+- **No transpiler needed** — Node handles TypeScript natively
+
+## Custom Entry
+
+```sh
+pnpm run dev -- ./src/other.ts
+```
+
+Additional arguments after the file path are passed through to Node.
diff --git a/skills/format/SKILL.md b/skills/format/SKILL.md
new file mode 100644
index 0000000..98e8d4b
--- /dev/null
+++ b/skills/format/SKILL.md
@@ -0,0 +1,27 @@
+---
+description: "Format code with oxfmt. Run with `pnpm run format`."
+---
+
+# Format
+
+Formats source files using oxfmt with the project's configuration.
+
+## Usage
+
+```sh
+pnpm run format
+```
+
+## How It Works
+
+`pnpm run format` runs `bsh format` which calls oxfmt with:
+- **Config:** `oxfmtrc.json` from `@bomb.sh/tools`
+- **Default target:** `./src`
+
+## Custom Targets
+
+```sh
+pnpm run format -- ./path/to/file.ts
+```
+
+Additional arguments are passed through to oxfmt.
diff --git a/skills/init/SKILL.md b/skills/init/SKILL.md
new file mode 100644
index 0000000..3d9c886
--- /dev/null
+++ b/skills/init/SKILL.md
@@ -0,0 +1,25 @@
+---
+description: "Scaffold a new Bombshell project from template. Run with `pnpm run init`."
+---
+
+# Init
+
+Scaffolds a new Bombshell project from the `bombshell-dev/template` GitHub template.
+
+## Usage
+
+```sh
+pnpm run init
+pnpm run init -- my-project
+```
+
+## How It Works
+
+`pnpm run init` runs `bsh init` which:
+1. Clones `gh:bombshell-dev/template` via giget
+2. Replaces `$name` placeholder in `package.json` and `README.md`
+3. Outputs to `.temp/` directory
+
+## Arguments
+
+- First positional arg: project name (defaults to current directory name)
diff --git a/skills/lifecycle/SKILL.md b/skills/lifecycle/SKILL.md
new file mode 100644
index 0000000..6715d71
--- /dev/null
+++ b/skills/lifecycle/SKILL.md
@@ -0,0 +1,39 @@
+---
+description: "Bombshell project lifecycle — how to build, test, lint, format, and run dev tasks. Auto-invoke when working in any project that depends on @bomb.sh/tools."
+---
+
+# Bombshell Project Lifecycle
+
+This project uses `@bomb.sh/tools` (`bsh`) as its dev toolchain. All dev tasks are run through `package.json` scripts.
+
+## Rules
+
+1. **Always use `pnpm run <script>`** to run project tasks
+2. **Never use `npx`, `npm run`, `pnpm dlx`, `yarn`, `bun`, or `tsx`**
+3. **Never run underlying tools directly** — no `pnpm exec tsdown`, `pnpm exec vitest`, `pnpm exec oxlint`, `pnpm exec knip`
+4. **Always ESM** — no CommonJS, no `require()`, no `ts-node`, no `tsx`
+5. **Node handles TypeScript natively** via `--experimental-transform-types`
+6. **pnpm is the only package manager** — never use `npm`, `yarn`, or `bun`
+
+## Available Scripts
+
+All scripts are defined in `package.json` and proxy to `bsh <command>`:
+
+| Script            | What It Does                                      |
+| ----------------- | ------------------------------------------------- |
+| `pnpm run build`  | Build with tsdown (ESM, sourcemaps, clean dist)   |
+| `pnpm run dev`    | Watch mode with native Node TypeScript transforms |
+| `pnpm run format` | Format with oxfmt                                 |
+| `pnpm run lint`   | Parallel lint: oxlint + publint + knip + tsc      |
+| `pnpm run test`   | Run tests with vitest                             |
+| `pnpm run init`   | Scaffold new Bombshell project from template      |
+
+## Do Not
+
+- Run `npx tsx`, `npx ts-node`, or `node -r ts-node/register`
+- Run `npx tsc` or `tsgo` directly — `pnpm run lint` includes type checking
+- Run `npx vitest` directly — use `pnpm run test`
+- Run `npx oxlint` or `npx oxfmt` directly — use `pnpm run lint` / `pnpm run format`
+- Use `require()` or any CommonJS patterns
+- Install `tsx`, `ts-node`, or `esbuild-register`
+- Use `npm`, `yarn`, or `bun` for anything
diff --git a/skills/lint/SKILL.md b/skills/lint/SKILL.md
new file mode 100644
index 0000000..e28cc63
--- /dev/null
+++ b/skills/lint/SKILL.md
@@ -0,0 +1,84 @@
+---
+description: "Run the full lint pipeline (oxlint, publint, knip, tsc). Run with `pnpm run lint`."
+---
+
+# Lint
+
+Runs a multi-tool linting pipeline in parallel with unified output.
+
+## Usage
+
+```sh
+pnpm run lint
+pnpm run lint -- --fix
+```
+
+## How It Works
+
+`pnpm run lint` runs `bsh lint` which executes four tools **in parallel**:
+
+| Tool | What It Checks |
+|------|---------------|
+| **oxlint** | JavaScript/TypeScript linting (fast, Rust-based) |
+| **publint** | package.json correctness (exports, types, etc.) |
+| **knip** | Unused dependencies, exports, types, and files |
+| **tsc** (tsgo) | TypeScript type checking (`--noEmit`) |
+
+Results are merged into a single grouped report with file locations.
+
+## Flags
+
+- `--fix` — Auto-fix what oxlint can fix, then report remaining violations
+- Positional args — Target paths (default: `./src`)
+
+## Exit Codes
+
+- **0** — No errors
+- **1** — Errors found
+
+## Important
+
+Do not run any of these tools individually. `pnpm run lint` runs them all and gives you a unified view.
+
+## Opinionated Rules
+
+The oxlint config enforces Bombshell conventions. When writing code for this project, follow these rules proactively — don't wait for the linter to catch them.
+
+### Paths: Use File URLs, not `node:path`
+
+`node:path` and `path` imports are **banned**. Use `URL` for all path manipulation:
+
+```ts
+// Do this
+const file = new URL("./config.json", import.meta.url);
+const child = new URL("./sub/", base);
+
+// Not this
+import { join } from "node:path";
+const file = join(__dirname, "config.json");
+```
+
+Use `fileURLToPath()` only at third-party module boundaries that require string paths.
+
+### No CommonJS
+
+`import/no-commonjs` is an error. No `require()`, no `module.exports`, no `exports.foo`.
+
+### Imports
+
+- **No default exports** (`import/no-default-export`) — use named exports
+- **Consistent type imports** (`typescript/consistent-type-imports`) — use `import type` for type-only imports
+- **Prefer `node:` protocol** (`unicorn/prefer-node-protocol`) — `import { readFile } from "node:fs/promises"`, not `"fs/promises"`
+
+### Functions
+
+- **Max 2 parameters** (`max-params`, error) — if a function needs more than 2 parameters, refactor to an options bag
+- **Explicit return types on declarations** (`typescript/explicit-function-return-type`, warn) — expressions are exempt
+- **Exported functions should be async** (`bombshell-dev/exported-function-async`, warn)
+- **Exported functions need JSDoc** (`bombshell-dev/require-export-jsdoc`, warn)
+
+### General
+
+- **`const` over `let`** (`prefer-const`) — never use `var`
+- **No generic errors** (`bombshell-dev/no-generic-error`) — use specific error types
+- **No `console.log`** (`no-console`, warn) — use `console.info`, `console.warn`, `console.error`, or `console.debug`
diff --git a/skills/test/SKILL.md b/skills/test/SKILL.md
new file mode 100644
index 0000000..c6c5e6f
--- /dev/null
+++ b/skills/test/SKILL.md
@@ -0,0 +1,72 @@
+---
+description: "Run tests with vitest. Run with `pnpm run test`."
+---
+
+# Test
+
+Runs the test suite using vitest in non-watch mode.
+
+## Usage
+
+```sh
+pnpm run test
+```
+
+## How It Works
+
+`pnpm run test` runs `bsh test` which calls `vitest run` (single run, no watch).
+
+## Filtering
+
+Pass arguments through to vitest:
+
+```sh
+pnpm run test -- src/commands/build.test.ts   # Run specific test file
+pnpm run test -- --reporter=verbose            # Change reporter
+```
+
+## Test Utilities
+
+`@bomb.sh/tools/test-utils` exports `createFixture` for filesystem-based tests.
+
+```ts
+import { createFixture } from "@bomb.sh/tools/test-utils";
+
+const fixture = await createFixture({
+  "hello.txt": "hello world",
+  "package.json": { name: "test", version: "1.0.0" },
+  "icon.png": Buffer.from([0x89, 0x50]),
+  src: {
+    "index.ts": "export default 1",
+  },
+  "link.txt": ({ symlink }) => symlink("./hello.txt"),
+  "info.txt": ({ importMeta }) => `Root: ${importMeta.url}`,
+});
+```
+
+### Fixture API
+
+- `fixture.root` — fixture root as a `file://` URL
+- `fixture.resolve(...segments)` — resolve a relative path within the fixture
+- `fixture.text(file)` — read file as string
+- `fixture.json(file)` — read and parse JSON file
+- `fixture.write(file, content)` — write a file
+- `fixture.isFile(file)` / `fixture.isDirectory(dir)` — check existence
+- `fixture.list(dir)` — list directory contents
+- `fixture.cleanup()` — delete fixture (also runs automatically via `onTestFinished`)
+
+All `hfs` methods are available, scoped to the fixture root.
+
+### Fixtures Are Always Inline
+
+Never extract fixture trees into shared variables, helper files, or beforeEach blocks. Each test should declare its own fixture inline so the test is self-contained and readable.
+
+### File Tree Values
+
+| Type | Behavior |
+|------|----------|
+| `string` | Written as-is |
+| `object` / `array` | Auto-serialized as JSON for `.json` keys |
+| `Buffer` | Written as binary |
+| Nested object (no `.` in key) | Creates a subdirectory |
+| `(ctx) => ...` | Dynamic — receives `importMeta` and `symlink` helpers |

From 619e7d6e5ddc701d5a0ba93c80fc6ab0668790b8 Mon Sep 17 00:00:00 2001
From: Nate Moore <nate@natemoo.re>
Date: Wed, 25 Mar 2026 17:06:17 -0400
Subject: [PATCH 2/8] ref(skills): update skills after testing

---
 skills/build/SKILL.md     |  3 ++-
 skills/dev/SKILL.md       |  3 ++-
 skills/format/SKILL.md    |  3 ++-
 skills/init/SKILL.md      |  3 ++-
 skills/lifecycle/SKILL.md | 31 ++++++++++++++++++++++++++++++-
 skills/lint/SKILL.md      |  3 ++-
 skills/test/SKILL.md      | 18 +++++++++++++++++-
 7 files changed, 57 insertions(+), 7 deletions(-)

diff --git a/skills/build/SKILL.md b/skills/build/SKILL.md
index 19340d5..176d357 100644
--- a/skills/build/SKILL.md
+++ b/skills/build/SKILL.md
@@ -1,5 +1,6 @@
 ---
-description: "Build TypeScript modules. Run with `pnpm run build`."
+name: build
+description: "Use when compiling TypeScript to ESM, generating declaration files, or preparing a package for publish."
 ---
 
 # Build
diff --git a/skills/dev/SKILL.md b/skills/dev/SKILL.md
index ff24ffa..b6e506e 100644
--- a/skills/dev/SKILL.md
+++ b/skills/dev/SKILL.md
@@ -1,5 +1,6 @@
 ---
-description: "Run a dev watcher for TypeScript files. Run with `pnpm run dev`."
+name: dev
+description: "Use when running a TypeScript file in watch mode during development."
 ---
 
 # Dev
diff --git a/skills/format/SKILL.md b/skills/format/SKILL.md
index 98e8d4b..a8c6689 100644
--- a/skills/format/SKILL.md
+++ b/skills/format/SKILL.md
@@ -1,5 +1,6 @@
 ---
-description: "Format code with oxfmt. Run with `pnpm run format`."
+name: format
+description: "Use when formatting source files or checking code style."
 ---
 
 # Format
diff --git a/skills/init/SKILL.md b/skills/init/SKILL.md
index 3d9c886..74a8497 100644
--- a/skills/init/SKILL.md
+++ b/skills/init/SKILL.md
@@ -1,5 +1,6 @@
 ---
-description: "Scaffold a new Bombshell project from template. Run with `pnpm run init`."
+name: init
+description: "Use when creating a new Bombshell project or package from the template."
 ---
 
 # Init
diff --git a/skills/lifecycle/SKILL.md b/skills/lifecycle/SKILL.md
index 6715d71..73a30e6 100644
--- a/skills/lifecycle/SKILL.md
+++ b/skills/lifecycle/SKILL.md
@@ -1,5 +1,6 @@
 ---
-description: "Bombshell project lifecycle — how to build, test, lint, format, and run dev tasks. Auto-invoke when working in any project that depends on @bomb.sh/tools."
+name: lifecycle
+description: "Use when working in any project that depends on @bomb.sh/tools — covers how to run build, test, lint, format, dev, and init tasks."
 ---
 
 # Bombshell Project Lifecycle
@@ -15,6 +16,19 @@ This project uses `@bomb.sh/tools` (`bsh`) as its dev toolchain. All dev tasks a
 5. **Node handles TypeScript natively** via `--experimental-transform-types`
 6. **pnpm is the only package manager** — never use `npm`, `yarn`, or `bun`
 
+## Monorepo vs Single Package
+
+Detect project structure before running commands.
+
+**Single package** (no `pnpm-workspace.yaml`):
+- All scripts run from package root: `pnpm run <script>`
+
+**Monorepo** (has `pnpm-workspace.yaml`):
+- Conventional layout: `packages/` for libraries, `examples/` for demos
+- Root scripts may differ — always check `package.json` before running
+- To target one package: `pnpm --filter <pkg> run <script>`
+- Common pattern: `build`/`test` recursive (`pnpm -r`), `format`/`lint` direct (`bsh`)
+
 ## Available Scripts
 
 All scripts are defined in `package.json` and proxy to `bsh <command>`:
@@ -28,6 +42,21 @@ All scripts are defined in `package.json` and proxy to `bsh <command>`:
 | `pnpm run test`   | Run tests with vitest                             |
 | `pnpm run init`   | Scaffold new Bombshell project from template      |
 
+## Development Workflow
+
+Follow this order when making changes. Write tests first, verify before claiming success.
+
+1. **Test first** — write or update `.test.ts` files before implementation
+2. **Run tests** (`pnpm run test`) — confirm the new test fails (RED)
+3. **Implement** — write the minimum code to pass
+4. **Run tests** (`pnpm run test`) — confirm tests pass (GREEN)
+5. **Lint** (`pnpm run lint`) — fix type errors, unused exports, style
+6. **Format** (`pnpm run format`) — normalize code style
+7. **Build** (`pnpm run build`) — verify the package compiles
+8. **Final test** (`pnpm run test`) — end-to-end confirmation
+
+Never skip straight to implementation. Never claim "tests pass" without running them.
+
 ## Do Not
 
 - Run `npx tsx`, `npx ts-node`, or `node -r ts-node/register`
diff --git a/skills/lint/SKILL.md b/skills/lint/SKILL.md
index e28cc63..33d5859 100644
--- a/skills/lint/SKILL.md
+++ b/skills/lint/SKILL.md
@@ -1,5 +1,6 @@
 ---
-description: "Run the full lint pipeline (oxlint, publint, knip, tsc). Run with `pnpm run lint`."
+name: lint
+description: "Use when checking for lint errors, type errors, unused exports, or package.json issues."
 ---
 
 # Lint
diff --git a/skills/test/SKILL.md b/skills/test/SKILL.md
index c6c5e6f..56c8429 100644
--- a/skills/test/SKILL.md
+++ b/skills/test/SKILL.md
@@ -1,5 +1,6 @@
 ---
-description: "Run tests with vitest. Run with `pnpm run test`."
+name: test
+description: "Use when running tests, writing new tests, or debugging test failures."
 ---
 
 # Test
@@ -12,6 +13,21 @@ Runs the test suite using vitest in non-watch mode.
 pnpm run test
 ```
 
+## Test File Conventions
+
+- **Colocate tests with source** — next to the code they test, never in `__tests__/` or `test/`
+- **`.test.ts`** suffix for runtime tests
+- **`.test-d.ts`** suffix for type-level tests (compile-time assertions only)
+
+```
+src/
+  framework/
+    schema.ts
+    schema.test.ts
+    params.ts
+    params.test-d.ts
+```
+
 ## How It Works
 
 `pnpm run test` runs `bsh test` which calls `vitest run` (single run, no watch).

From 0dbf4ae1f35c281ddd9dc942e649cac997615607 Mon Sep 17 00:00:00 2001
From: Nate Moore <nate@natemoo.re>
Date: Wed, 25 Mar 2026 17:09:09 -0400
Subject: [PATCH 3/8] fix(pub): update files

---
 package.json | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/package.json b/package.json
index 559f5b1..f84a58f 100644
--- a/package.json
+++ b/package.json
@@ -21,6 +21,14 @@
   "bin": {
     "bsh": "dist/bin.mjs"
   },
+  "files": [
+    "dist",
+    ".claude-plugin",
+    "tsconfig.json",
+    "package.json",
+    "oxfmtrc.json",
+    "oxlintrc.json"
+  ],
   "type": "module",
   "exports": {
     ".": {

From db646dd7bd28ce12a057ab8b0c067dbfd07e863c Mon Sep 17 00:00:00 2001
From: Nate Moore <nate@natemoo.re>
Date: Wed, 25 Mar 2026 17:33:45 -0400
Subject: [PATCH 4/8] fix(pub): update plugin.json

---
 .claude-plugin/plugin.json | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index cccadcf..1d4927a 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,4 +1,18 @@
 {
   "name": "@bomb.sh/tools",
-  "description": "Claude Code skills for the Bombshell dev toolchain"
+  "version": "0.2.8",
+  "description": "Claude Code skills for the Bombshell dev toolchain",
+  "author": {
+    "name": "Bombshell",
+    "email": "oss@bomb.sh",
+    "url": "https://bomb.sh"
+  },
+  "homepage": "https://bomb.sh",
+  "repository": "https://github.com/bombshell-dev/tools",
+  "license": "MIT",
+  "keywords": [
+    "bombshell",
+    "cli",
+    "internal"
+  ]
 }

From 5ca810dbcb785d549424b2e76685faf8cb5a2d34 Mon Sep 17 00:00:00 2001
From: Nate Moore <nate@natemoo.re>
Date: Wed, 25 Mar 2026 20:00:17 -0400
Subject: [PATCH 5/8] fix(pub): remove plugin

---
 .claude-plugin/plugin.json | 18 ------------------
 1 file changed, 18 deletions(-)
 delete mode 100644 .claude-plugin/plugin.json

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
deleted file mode 100644
index 1d4927a..0000000
--- a/.claude-plugin/plugin.json
+++ /dev/null
@@ -1,18 +0,0 @@
-{
-  "name": "@bomb.sh/tools",
-  "version": "0.2.8",
-  "description": "Claude Code skills for the Bombshell dev toolchain",
-  "author": {
-    "name": "Bombshell",
-    "email": "oss@bomb.sh",
-    "url": "https://bomb.sh"
-  },
-  "homepage": "https://bomb.sh",
-  "repository": "https://github.com/bombshell-dev/tools",
-  "license": "MIT",
-  "keywords": [
-    "bombshell",
-    "cli",
-    "internal"
-  ]
-}

From 50854ad3679e3b6eac2c8f95ba27b313185fbfca Mon Sep 17 00:00:00 2001
From: Nate Moore <nate@natemoo.re>
Date: Wed, 25 Mar 2026 23:01:04 -0400
Subject: [PATCH 6/8] feat(skills): run tanstack intent

---
 .github/workflows/check-skills.yml    | 143 +++++++
 .github/workflows/notify-intent.yml   |  51 +++
 .github/workflows/validate-skills.yml |  52 +++
 package.json                          |   8 +-
 pnpm-lock.yaml                        |  34 +-
 skills/_artifacts/domain_map.yaml     | 542 ++++++++++++++++++++++++++
 skills/_artifacts/skill_spec.md       | 148 +++++++
 skills/_artifacts/skill_tree.yaml     | 138 +++++++
 skills/build/SKILL.md                 |  81 +++-
 skills/dev/SKILL.md                   |  72 +++-
 skills/format/SKILL.md                |  87 ++++-
 skills/init/SKILL.md                  |  50 ++-
 skills/lifecycle/SKILL.md             | 248 +++++++++---
 skills/lint/SKILL.md                  | 291 +++++++++++---
 skills/lint/references/lint-rules.md  |  52 +++
 skills/migrate/SKILL.md               | 124 ++++++
 skills/test/SKILL.md                  | 267 +++++++++++--
 17 files changed, 2221 insertions(+), 167 deletions(-)
 create mode 100644 .github/workflows/check-skills.yml
 create mode 100644 .github/workflows/notify-intent.yml
 create mode 100644 .github/workflows/validate-skills.yml
 create mode 100644 skills/_artifacts/domain_map.yaml
 create mode 100644 skills/_artifacts/skill_spec.md
 create mode 100644 skills/_artifacts/skill_tree.yaml
 create mode 100644 skills/lint/references/lint-rules.md
 create mode 100644 skills/migrate/SKILL.md

diff --git a/.github/workflows/check-skills.yml b/.github/workflows/check-skills.yml
new file mode 100644
index 0000000..d1bc862
--- /dev/null
+++ b/.github/workflows/check-skills.yml
@@ -0,0 +1,143 @@
+# check-skills.yml — Drop this into your library repo's .github/workflows/
+#
+# Checks for stale intent skills after a release and opens a review PR
+# if any skills need attention. The PR body includes a prompt you can
+# paste into Claude Code, Cursor, or any coding agent to update them.
+#
+# Triggers: new release published, or manual workflow_dispatch.
+#
+# Template variables (replaced by `intent setup`):
+#   @bomb.sh/tools — e.g. @tanstack/query or my-workspace workspace
+
+name: Check Skills
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch: {}
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  check:
+    name: Check for stale skills
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install intent
+        run: npm install -g @tanstack/intent
+
+      - name: Check staleness
+        id: stale
+        run: |
+          OUTPUT=$(intent stale --json 2>&1) || true
+          echo "$OUTPUT"
+
+          # Check if any skills need review
+          NEEDS_REVIEW=$(echo "$OUTPUT" | node -e "
+            const input = require('fs').readFileSync('/dev/stdin','utf8');
+            try {
+              const reports = JSON.parse(input);
+              const stale = reports.flatMap(r =>
+                r.skills.filter(s => s.needsReview).map(s => ({ library: r.library, skill: s.name, reasons: s.reasons }))
+              );
+              if (stale.length > 0) {
+                console.log(JSON.stringify(stale));
+              }
+            } catch {}
+          ")
+
+          if [ -z "$NEEDS_REVIEW" ]; then
+            echo "has_stale=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_stale=true" >> "$GITHUB_OUTPUT"
+            # Escape for multiline GH output
+            EOF=$(dd if=/dev/urandom bs=15 count=1 status=none | base64)
+            echo "stale_json<<$EOF" >> "$GITHUB_OUTPUT"
+            echo "$NEEDS_REVIEW" >> "$GITHUB_OUTPUT"
+            echo "$EOF" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build summary
+        if: steps.stale.outputs.has_stale == 'true'
+        id: summary
+        run: |
+          node -e "
+            const stale = JSON.parse(process.env.STALE_JSON);
+            const lines = stale.map(s =>
+              '- **' + s.skill + '** (' + s.library + '): ' + s.reasons.join(', ')
+            );
+            const summary = lines.join('\n');
+
+            const prompt = [
+              'Review and update the following stale intent skills for @bomb.sh/tools:',
+              '',
+              ...stale.map(s => '- ' + s.skill + ': ' + s.reasons.join(', ')),
+              '',
+              'For each stale skill:',
+              '1. Read the current SKILL.md file',
+              '2. Check what changed in the library since the skill was last updated',
+              '3. Update the skill content to reflect current APIs and behavior',
+              '4. Run \`npx @tanstack/intent validate\` to verify the updated skill',
+            ].join('\n');
+
+            // Write outputs
+            const fs = require('fs');
+            const env = fs.readFileSync(process.env.GITHUB_OUTPUT, 'utf8');
+            const eof = require('crypto').randomBytes(15).toString('base64');
+            fs.appendFileSync(process.env.GITHUB_OUTPUT,
+              'summary<<' + eof + '\n' + summary + '\n' + eof + '\n' +
+              'prompt<<' + eof + '\n' + prompt + '\n' + eof + '\n'
+            );
+          "
+        env:
+          STALE_JSON: ${{ steps.stale.outputs.stale_json }}
+
+      - name: Open review PR
+        if: steps.stale.outputs.has_stale == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION="${{ github.event.release.tag_name || 'manual' }}"
+          BRANCH="skills/review-${VERSION}"
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git checkout -b "$BRANCH"
+          git commit --allow-empty -m "chore: review stale skills for ${VERSION}"
+          git push origin "$BRANCH"
+
+          gh pr create \
+            --title "Review stale skills (${VERSION})" \
+            --body "$(cat <<'PREOF'
+          ## Stale Skills Detected
+
+          The following skills may need updates after the latest release:
+
+          ${{ steps.summary.outputs.summary }}
+
+          ---
+
+          ### Update Prompt
+
+          Paste this into your coding agent (Claude Code, Cursor, etc.):
+
+          ~~~
+          ${{ steps.summary.outputs.prompt }}
+          ~~~
+
+          PREOF
+          )" \
+            --head "$BRANCH" \
+            --base main
diff --git a/.github/workflows/notify-intent.yml b/.github/workflows/notify-intent.yml
new file mode 100644
index 0000000..bd9a4b0
--- /dev/null
+++ b/.github/workflows/notify-intent.yml
@@ -0,0 +1,51 @@
+# notify-intent.yml — Drop this into your library repo's .github/workflows/
+#
+# Fires a repository_dispatch event whenever docs or source files change
+# on merge to main. This triggers the skill staleness check workflow.
+#
+# Requirements:
+#   - A fine-grained PAT with contents:write on this repository stored
+#     as the INTENT_NOTIFY_TOKEN repository secret.
+#
+# Template variables (replaced by `intent setup`):
+#   @bomb.sh/tools — e.g. @tanstack/query or my-workspace workspace
+#   docs/**       — e.g. docs/**
+#   src/**        — e.g. packages/query-core/src/**
+
+name: Trigger Skill Review
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "src/**"
+
+jobs:
+  notify:
+    name: Trigger Skill Review
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - name: Collect changed files
+        id: changes
+        run: |
+          FILES=$(git diff --name-only HEAD~1 HEAD | jq -R -s -c 'split("\n") | map(select(length > 0))')
+          echo "files=$FILES" >> "$GITHUB_OUTPUT"
+
+      - name: Dispatch to intent repo
+        uses: peter-evans/repository-dispatch@v3
+        with:
+          token: ${{ secrets.INTENT_NOTIFY_TOKEN }}
+          repository: ${{ github.repository }}
+          event-type: skill-check
+          client-payload: |
+            {
+              "package": "@bomb.sh/tools",
+              "sha": "${{ github.sha }}",
+              "changed_files": ${{ steps.changes.outputs.files }}
+            }
diff --git a/.github/workflows/validate-skills.yml b/.github/workflows/validate-skills.yml
new file mode 100644
index 0000000..8c62379
--- /dev/null
+++ b/.github/workflows/validate-skills.yml
@@ -0,0 +1,52 @@
+# validate-skills.yml — Drop this into your library repo's .github/workflows/
+#
+# Validates skill files on PRs that touch the skills/ directory.
+# Ensures frontmatter is correct, names match paths, and files stay under
+# the 500-line limit.
+
+name: Validate Skills
+
+on:
+  pull_request:
+    paths:
+      - "skills/**"
+      - "**/skills/**"
+
+jobs:
+  validate:
+    name: Validate skill files
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install intent CLI
+        run: npm install -g @tanstack/intent
+
+      - name: Find and validate skills
+        run: |
+          # Find all directories containing SKILL.md files
+          SKILLS_DIR=""
+          if [ -d "skills" ]; then
+            SKILLS_DIR="skills"
+          elif [ -d "packages" ]; then
+            # Monorepo — find skills/ under packages
+            for dir in packages/*/skills; do
+              if [ -d "$dir" ]; then
+                echo "Validating $dir..."
+                intent validate "$dir"
+              fi
+            done
+            exit 0
+          fi
+
+          if [ -n "$SKILLS_DIR" ]; then
+            intent validate "$SKILLS_DIR"
+          else
+            echo "No skills/ directory found — skipping validation."
+          fi
diff --git a/package.json b/package.json
index f84a58f..0c7d74b 100644
--- a/package.json
+++ b/package.json
@@ -5,7 +5,9 @@
   "keywords": [
     "bombshell",
     "cli",
-    "internal"
+    "internal",
+    "skills",
+    "tanstack-intent"
   ],
   "homepage": "https://bomb.sh",
   "license": "MIT",
@@ -23,6 +25,8 @@
   },
   "files": [
     "dist",
+    "skills",
+    "!skills/_artifacts",
     ".claude-plugin",
     "tsconfig.json",
     "package.json",
@@ -34,6 +38,7 @@
     ".": {
       "import": "./dist/bin.mjs"
     },
+    "./skills/*": "./skills/*",
     "./test-utils": {
       "types": "./dist/test-utils.d.mts",
       "import": "./dist/test-utils.mjs"
@@ -69,6 +74,7 @@
   },
   "devDependencies": {
     "@changesets/cli": "^2.28.1",
+    "@tanstack/intent": "^0.0.23",
     "@types/node": "^22.13.14"
   },
   "volta": {
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 77c2475..1d738f6 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -40,11 +40,14 @@ importers:
         version: 0.21.0-beta.2(@typescript/native-preview@7.0.0-dev.20260307.1)(oxc-resolver@11.19.1)(publint@0.3.18)(typescript@5.9.3)
       vitest:
         specifier: ^4.0.18
-        version: 4.0.18(@types/node@22.13.14)(jiti@2.6.1)
+        version: 4.0.18(@types/node@22.13.14)(jiti@2.6.1)(yaml@2.8.3)
     devDependencies:
       '@changesets/cli':
         specifier: ^2.28.1
         version: 2.28.1
+      '@tanstack/intent':
+        specifier: ^0.0.23
+        version: 0.0.23
       '@types/node':
         specifier: ^22.13.14
         version: 22.13.14
@@ -895,6 +898,10 @@ packages:
   '@standard-schema/spec@1.1.0':
     resolution: {integrity: sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==}
 
+  '@tanstack/intent@0.0.23':
+    resolution: {integrity: sha512-q5e0sh5e+xBOR5Z7eoZTBcXtakgTwucm2m0bNUkj7h4UagSgIDmPRYbtC7B81AF4FB5rW2OP1zgl7Jd9EH4qEw==}
+    hasBin: true
+
   '@tybys/wasm-util@0.10.1':
     resolution: {integrity: sha512-9tTaPJLSiejZKx+Bmog4uSubteqTvFrVrURwkmHixBo0G4seD0zUxp98E1DzUBJxLQ3NPwXrGKDiVjwx/DpPsg==}
 
@@ -1662,6 +1669,11 @@ packages:
     engines: {node: '>=8'}
     hasBin: true
 
+  yaml@2.8.3:
+    resolution: {integrity: sha512-AvbaCLOO2Otw/lW5bmh9d/WEdcDFdQp2Z2ZUH3pX9U2ihyUY0nvLv7J6TrWowklRGPYbB/IuIMfYgxaCPg5Bpg==}
+    engines: {node: '>= 14.6'}
+    hasBin: true
+
   zod@4.3.6:
     resolution: {integrity: sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg==}
 
@@ -2295,6 +2307,11 @@ snapshots:
 
   '@standard-schema/spec@1.1.0': {}
 
+  '@tanstack/intent@0.0.23':
+    dependencies:
+      cac: 6.7.14
+      yaml: 2.8.3
+
   '@tybys/wasm-util@0.10.1':
     dependencies:
       tslib: 2.8.1
@@ -2357,13 +2374,13 @@ snapshots:
       chai: 6.2.2
       tinyrainbow: 3.0.3
 
-  '@vitest/mocker@4.0.18(vite@7.3.1(@types/node@22.13.14)(jiti@2.6.1))':
+  '@vitest/mocker@4.0.18(vite@7.3.1(@types/node@22.13.14)(jiti@2.6.1)(yaml@2.8.3))':
     dependencies:
       '@vitest/spy': 4.0.18
       estree-walker: 3.0.3
       magic-string: 0.30.21
     optionalDependencies:
-      vite: 7.3.1(@types/node@22.13.14)(jiti@2.6.1)
+      vite: 7.3.1(@types/node@22.13.14)(jiti@2.6.1)(yaml@2.8.3)
 
   '@vitest/pretty-format@4.0.18':
     dependencies:
@@ -2990,7 +3007,7 @@ snapshots:
     dependencies:
       rolldown: 1.0.0-rc.5
 
-  vite@7.3.1(@types/node@22.13.14)(jiti@2.6.1):
+  vite@7.3.1(@types/node@22.13.14)(jiti@2.6.1)(yaml@2.8.3):
     dependencies:
       esbuild: 0.27.3
       fdir: 6.5.0(picomatch@4.0.3)
@@ -3002,11 +3019,12 @@ snapshots:
       '@types/node': 22.13.14
       fsevents: 2.3.3
       jiti: 2.6.1
+      yaml: 2.8.3
 
-  vitest@4.0.18(@types/node@22.13.14)(jiti@2.6.1):
+  vitest@4.0.18(@types/node@22.13.14)(jiti@2.6.1)(yaml@2.8.3):
     dependencies:
       '@vitest/expect': 4.0.18
-      '@vitest/mocker': 4.0.18(vite@7.3.1(@types/node@22.13.14)(jiti@2.6.1))
+      '@vitest/mocker': 4.0.18(vite@7.3.1(@types/node@22.13.14)(jiti@2.6.1)(yaml@2.8.3))
       '@vitest/pretty-format': 4.0.18
       '@vitest/runner': 4.0.18
       '@vitest/snapshot': 4.0.18
@@ -3023,7 +3041,7 @@ snapshots:
       tinyexec: 1.0.2
       tinyglobby: 0.2.15
       tinyrainbow: 3.0.3
-      vite: 7.3.1(@types/node@22.13.14)(jiti@2.6.1)
+      vite: 7.3.1(@types/node@22.13.14)(jiti@2.6.1)(yaml@2.8.3)
       why-is-node-running: 2.3.0
     optionalDependencies:
       '@types/node': 22.13.14
@@ -3051,4 +3069,6 @@ snapshots:
       siginfo: 2.0.0
       stackback: 0.0.2
 
+  yaml@2.8.3: {}
+
   zod@4.3.6: {}
diff --git a/skills/_artifacts/domain_map.yaml b/skills/_artifacts/domain_map.yaml
new file mode 100644
index 0000000..d3659db
--- /dev/null
+++ b/skills/_artifacts/domain_map.yaml
@@ -0,0 +1,542 @@
+# domain_map.yaml
+# Generated by skill-domain-discovery
+# Library: @bomb.sh/tools
+# Version: 0.2.8
+# Date: 2026-03-25
+# Status: reviewed
+
+library:
+  name: '@bomb.sh/tools'
+  version: '0.2.8'
+  repository: 'https://github.com/bombshell-dev/tools'
+  description: 'Unified internal CLI (bsh) that standardizes dev workflows across all Bombshell ecosystem projects by orchestrating opinionated configurations of industry-standard tools.'
+  primary_framework: 'framework-agnostic'
+
+domains:
+  - name: 'development workflow'
+    slug: 'workflow'
+    description: 'The end-to-end development lifecycle — from project creation through TDD loop to production readiness'
+
+  - name: 'code quality'
+    slug: 'quality'
+    description: 'Linting, formatting, and opinionated conventions that keep code coherent across repositories'
+
+  - name: 'compilation'
+    slug: 'compilation'
+    description: 'Building TypeScript to ESM and running TypeScript natively during development'
+
+  - name: 'testing'
+    slug: 'testing'
+    description: 'Writing and running tests with colocated conventions and filesystem fixture utilities'
+
+  - name: 'project setup'
+    slug: 'setup'
+    description: 'Creating new projects and migrating existing ones to the bsh toolchain'
+
+skills:
+  - name: 'Development Lifecycle'
+    slug: 'lifecycle'
+    domain: 'workflow'
+    description: 'The TDD-driven development workflow — command ordering, monorepo vs single-package detection, and the red/green/refactor loop'
+    type: 'lifecycle'
+    covers:
+      - 'TDD workflow (test-implement-lint-format-build-test)'
+      - 'pnpm run <script> as the only entry point'
+      - 'monorepo vs single-package detection'
+      - 'pnpm --filter for targeting packages'
+      - 'human-owned PRs (no full autopilot)'
+    tasks:
+      - 'Start working on a feature from a GitHub issue'
+      - 'Run the full development loop'
+      - 'Detect whether a project is a monorepo or single package'
+      - 'Target a specific package in a monorepo'
+    failure_modes:
+      - mistake: 'Using npx instead of pnpm run'
+        mechanism: 'Agent defaults to npx for running CLI tools; Bombshell always uses pnpm run for local scripts or pnpm dlx for one-off downloads'
+        wrong_pattern: |
+          npx vitest run
+          npx tsdown src/index.ts
+        correct_pattern: |
+          pnpm run test
+          pnpm run build
+        source: 'skills/lifecycle/SKILL.md, maintainer interview'
+        priority: 'CRITICAL'
+        status: 'active'
+        version_context: 'Agents consistently default to npx'
+
+      - mistake: 'Running underlying tools directly'
+        mechanism: 'Agent bypasses bsh wrapper and calls tsdown, vitest, oxlint, knip, or oxfmt directly, missing opinionated defaults'
+        wrong_pattern: |
+          pnpm exec vitest run
+          pnpm exec oxlint ./src
+          pnpm exec tsdown src/index.ts
+        correct_pattern: |
+          pnpm run test
+          pnpm run lint
+          pnpm run build
+        source: 'skills/lifecycle/SKILL.md, maintainer interview'
+        priority: 'CRITICAL'
+        status: 'active'
+        version_context: 'Agents assume they need to configure underlying tools'
+
+      - mistake: 'Skipping TDD and implementing first'
+        mechanism: 'Agent writes implementation code before writing tests, violating the red/green/refactor cycle'
+        wrong_pattern: |
+          # 1. Write implementation
+          # 2. Write tests after
+          # 3. Run tests
+        correct_pattern: |
+          # 1. Write failing test (RED)
+          # 2. Run test — confirm failure
+          # 3. Implement minimum code (GREEN)
+          # 4. Run test — confirm pass
+        source: 'skills/lifecycle/SKILL.md, maintainer interview'
+        priority: 'HIGH'
+        status: 'active'
+
+      - mistake: 'Using npm, yarn, or bun'
+        mechanism: 'Agent uses wrong package manager; pnpm is the only allowed package manager'
+        wrong_pattern: |
+          npm install foo
+          yarn add foo
+        correct_pattern: |
+          pnpm add foo
+        source: 'skills/lifecycle/SKILL.md'
+        priority: 'CRITICAL'
+        status: 'active'
+
+      - mistake: 'Running tsc directly for type checking'
+        mechanism: 'Agent runs tsc or tsgo directly instead of pnpm run lint which includes type checking via tsgo internally'
+        wrong_pattern: |
+          pnpm exec tsc --noEmit
+          npx tsgo
+        correct_pattern: |
+          pnpm run lint
+        source: 'skills/lint/SKILL.md, maintainer interview'
+        priority: 'HIGH'
+        status: 'active'
+
+      - mistake: 'Full autopilot PR creation'
+        mechanism: 'Agent creates PRs, pushes branches, and acts autonomously; humans must own the code and author their own PRs'
+        source: 'maintainer interview'
+        priority: 'HIGH'
+        status: 'active'
+
+  - name: 'Lint'
+    slug: 'lint'
+    domain: 'quality'
+    description: 'Running the multi-tool linting pipeline and understanding the opinionated rules that keep Bombshell code coherent'
+    type: 'core'
+    covers:
+      - 'oxlint (JS/TS linting)'
+      - 'publint (package.json correctness)'
+      - 'knip (unused deps/exports/types)'
+      - 'tsgo (type checking)'
+      - 'Bombshell-specific lint rules'
+    tasks:
+      - 'Run the linter and fix violations'
+      - 'Understand why a lint rule exists'
+      - 'Write code that passes lint on first run'
+      - 'Consider whether a new lint rule should be added'
+    failure_modes:
+      - mistake: 'Using node:path instead of URL'
+        mechanism: 'node:path imports are banned; URL and file URL APIs are required for all path manipulation'
+        wrong_pattern: |
+          import { join } from 'node:path';
+          const file = join(__dirname, 'config.json');
+        correct_pattern: |
+          const file = new URL('./config.json', import.meta.url);
+        source: 'skills/lint/SKILL.md'
+        priority: 'CRITICAL'
+        status: 'active'
+        skills: ['lint', 'lifecycle']
+
+      - mistake: 'Functions with more than 2 parameters'
+        mechanism: 'Max 2 params enforced; agents write inline multi-param functions instead of using an options bag'
+        wrong_pattern: |
+          export async function create(name: string, path: string, options: Options, logger: Logger): Promise<void> {}
+        correct_pattern: |
+          interface CreateOptions {
+            name: string;
+            path: string;
+            options: Options;
+            logger: Logger;
+          }
+          export async function create({ name, path, options, logger }: CreateOptions): Promise<void> {}
+        source: 'skills/lint/SKILL.md, maintainer interview'
+        priority: 'HIGH'
+        status: 'active'
+        skills: ['lint', 'lifecycle']
+
+      - mistake: 'Using console.log'
+        mechanism: 'console.log is warned; agents should use console.info, console.warn, console.error, or console.debug'
+        wrong_pattern: |
+          console.log('Processing...');
+        correct_pattern: |
+          console.info('Processing...');
+        source: 'skills/lint/SKILL.md'
+        priority: 'MEDIUM'
+        status: 'active'
+
+      - mistake: 'Using default exports'
+        mechanism: 'Default exports are banned; all exports must be named'
+        wrong_pattern: |
+          export default function parse() {}
+        correct_pattern: |
+          export function parse() {}
+        source: 'skills/lint/SKILL.md'
+        priority: 'HIGH'
+        status: 'active'
+
+      - mistake: 'Not using import type for type-only imports'
+        mechanism: 'Type-only imports must use import type syntax'
+        wrong_pattern: |
+          import { MyInterface } from './types.ts';
+        correct_pattern: |
+          import type { MyInterface } from './types.ts';
+        source: 'skills/lint/SKILL.md'
+        priority: 'MEDIUM'
+        status: 'active'
+
+      - mistake: 'Over-commenting obvious code'
+        mechanism: 'Agents add redundant comments that restate what the code already says via its declaration name or implementation'
+        wrong_pattern: |
+          // Parse the input string
+          function parseInput(input: string) { ... }
+          // The result of parsing
+          const result = parseInput(raw);
+        correct_pattern: |
+          function parseInput(input: string) { ... }
+          const result = parseInput(raw);
+        source: 'maintainer interview'
+        priority: 'MEDIUM'
+        status: 'active'
+        skills: ['lint', 'lifecycle']
+
+      - mistake: 'Not using bleeding-edge Node builtins'
+        mechanism: 'Agents prefer npm packages over stable Node 22+ builtins; Bombshell targets Node 22 LTS and prefers builtins over dependencies'
+        source: 'maintainer interview'
+        priority: 'HIGH'
+        status: 'active'
+        skills: ['lint', 'lifecycle']
+
+  - name: 'Build'
+    slug: 'build'
+    domain: 'compilation'
+    description: 'Compiling TypeScript to ESM with tsdown and opinionated defaults'
+    type: 'core'
+    covers:
+      - 'tsdown with ESM output'
+      - 'sourcemaps, clean dist/'
+      - 'unbundled by default'
+      - '--dts, --bundle, --minify flags'
+    tasks:
+      - 'Build a package for publishing'
+      - 'Generate declaration files'
+      - 'Customize build entry points'
+    failure_modes:
+      - mistake: 'Passing unnecessary flags to build'
+        mechanism: 'Agent tries to configure tsdown directly or passes flags that are already defaults (ESM, sourcemaps, clean)'
+        wrong_pattern: |
+          pnpm run build -- --format esm --sourcemap --clean
+        correct_pattern: |
+          pnpm run build
+        source: 'skills/build/SKILL.md, maintainer interview'
+        priority: 'MEDIUM'
+        status: 'active'
+
+      - mistake: 'Running tsdown directly'
+        mechanism: 'Agent calls tsdown binary instead of using pnpm run build which wraps it with correct defaults'
+        wrong_pattern: |
+          pnpm exec tsdown src/index.ts --format esm
+        correct_pattern: |
+          pnpm run build
+        source: 'skills/build/SKILL.md'
+        priority: 'HIGH'
+        status: 'active'
+
+      - mistake: 'CommonJS output configuration'
+        mechanism: 'Agent tries to configure CJS output; Bombshell is ESM-only'
+        wrong_pattern: |
+          pnpm run build -- --format cjs
+        correct_pattern: |
+          pnpm run build
+        source: 'skills/build/SKILL.md'
+        priority: 'HIGH'
+        status: 'active'
+
+  - name: 'Test'
+    slug: 'test'
+    domain: 'testing'
+    description: 'Writing and running tests with vitest, colocated test files, and the createFixture utility'
+    type: 'core'
+    covers:
+      - 'vitest run (non-watch)'
+      - 'colocated .test.ts files'
+      - '.test-d.ts for type-level tests'
+      - 'createFixture for filesystem tests'
+      - '@bomb.sh/tools/test-utils'
+    tasks:
+      - 'Write a new test for a feature'
+      - 'Run the test suite'
+      - 'Create filesystem fixtures for testing'
+      - 'Write type-level tests'
+    failure_modes:
+      - mistake: 'Placing tests in __tests__ directory'
+        mechanism: 'Tests must be colocated next to source files, never in __tests__/ or test/ directories'
+        wrong_pattern: |
+          __tests__/
+            schema.test.ts
+          src/
+            schema.ts
+        correct_pattern: |
+          src/
+            schema.ts
+            schema.test.ts
+        source: 'skills/test/SKILL.md'
+        priority: 'HIGH'
+        status: 'active'
+
+      - mistake: 'Extracting fixtures into shared variables'
+        mechanism: 'Fixtures must be declared inline in each test for readability; never in beforeEach or shared helpers'
+        wrong_pattern: |
+          const sharedFixture = { 'index.ts': 'export default 1' };
+          test('a', async () => {
+            const f = await createFixture(sharedFixture);
+          });
+        correct_pattern: |
+          test('a', async () => {
+            const fixture = await createFixture({
+              'index.ts': 'export default 1',
+            });
+          });
+        source: 'skills/test/SKILL.md'
+        priority: 'MEDIUM'
+        status: 'active'
+
+      - mistake: 'Testing implementation details instead of behavior'
+        mechanism: 'Agent writes tests tightly coupled to internal implementation rather than high-level behavioral assertions'
+        source: 'maintainer interview'
+        priority: 'HIGH'
+        status: 'active'
+
+      - mistake: 'Running vitest directly'
+        mechanism: 'Agent calls vitest binary instead of pnpm run test'
+        wrong_pattern: |
+          pnpm exec vitest run
+          npx vitest
+        correct_pattern: |
+          pnpm run test
+        source: 'skills/test/SKILL.md'
+        priority: 'HIGH'
+        status: 'active'
+
+  - name: 'Format'
+    slug: 'format'
+    domain: 'quality'
+    description: 'Formatting source files with oxfmt using project configuration'
+    type: 'core'
+    covers:
+      - 'oxfmt with oxfmtrc.json config'
+      - 'tabs, single quotes, semicolons, trailing commas'
+      - '100-char line width'
+    tasks:
+      - 'Format code before committing'
+      - 'Format specific files'
+    failure_modes:
+      - mistake: 'Running prettier or biome format'
+        mechanism: 'Agent uses familiar formatters instead of oxfmt via pnpm run format'
+        wrong_pattern: |
+          npx prettier --write .
+          npx biome format .
+        correct_pattern: |
+          pnpm run format
+        source: 'skills/format/SKILL.md, maintainer interview'
+        priority: 'HIGH'
+        status: 'active'
+
+      - mistake: 'Using spaces instead of tabs'
+        mechanism: 'Bombshell uses tabs for indentation; agents default to spaces'
+        source: 'conventions.md'
+        priority: 'MEDIUM'
+        status: 'active'
+
+      - mistake: 'Using double quotes'
+        mechanism: 'Bombshell uses single quotes; agents often default to double quotes'
+        source: 'conventions.md'
+        priority: 'MEDIUM'
+        status: 'active'
+
+  - name: 'Dev'
+    slug: 'dev'
+    domain: 'compilation'
+    description: 'Running TypeScript in watch mode with native Node transforms during development'
+    type: 'core'
+    covers:
+      - 'node --experimental-transform-types'
+      - 'watch mode on ./src/'
+      - 'custom entry files'
+    tasks:
+      - 'Start a dev server with file watching'
+      - 'Run a custom entry file in dev mode'
+    failure_modes:
+      - mistake: 'Using tsx or ts-node for development'
+        mechanism: 'Agent installs tsx or ts-node; Node handles TypeScript natively in this toolchain'
+        wrong_pattern: |
+          npx tsx watch src/index.ts
+          npx ts-node src/index.ts
+        correct_pattern: |
+          pnpm run dev
+        source: 'skills/dev/SKILL.md, skills/lifecycle/SKILL.md'
+        priority: 'CRITICAL'
+        status: 'active'
+
+      - mistake: 'Installing TypeScript transpilers as dependencies'
+        mechanism: 'Agent adds tsx, ts-node, or esbuild-register to dependencies; these are unnecessary'
+        wrong_pattern: |
+          pnpm add tsx
+          pnpm add ts-node
+        correct_pattern: |
+          # No additional dependency needed — use pnpm run dev
+        source: 'skills/lifecycle/SKILL.md'
+        priority: 'HIGH'
+        status: 'active'
+
+  - name: 'Init'
+    slug: 'init'
+    domain: 'setup'
+    description: 'Scaffolding a new Bombshell project from the template repository'
+    type: 'core'
+    covers:
+      - 'giget clone from bombshell-dev/template'
+      - '$name placeholder replacement'
+      - 'output to .temp/'
+    tasks:
+      - 'Create a new package in the Bombshell ecosystem'
+    failure_modes:
+      - mistake: 'Manually scaffolding project structure'
+        mechanism: 'Agent creates files manually instead of using bsh init which clones the canonical template'
+        wrong_pattern: |
+          mkdir my-project
+          # manually create package.json, tsconfig.json, etc.
+        correct_pattern: |
+          pnpm run init -- my-project
+        source: 'skills/init/SKILL.md'
+        priority: 'MEDIUM'
+        status: 'active'
+
+  - name: 'Migrate'
+    slug: 'migrate'
+    domain: 'setup'
+    description: 'Migrating an existing project to the bsh toolchain — removing old tools, replacing configs, and consolidating to a single @bomb.sh/tools dependency'
+    type: 'lifecycle'
+    covers:
+      - 'Removing prettier, biome, eslint, tsup, unbuild, rollup configs'
+      - 'Removing old tool devDependencies'
+      - 'Replacing package.json scripts with bsh equivalents'
+      - 'Adding @bomb.sh/tools as single devDependency'
+      - 'Updating test file locations to colocated pattern'
+    tasks:
+      - 'Migrate build from tsup/unbuild/rollup to bsh build'
+      - 'Migrate linting from eslint/biome to bsh lint'
+      - 'Migrate formatting from prettier/biome to bsh format'
+      - 'Remove old config files and dependencies'
+      - 'Consolidate to single @bomb.sh/tools dependency'
+    migration_checklist:
+      - 'Check existing tools — identify what is already in use'
+      - 'Add unimplemented commands (likely lint, format) first'
+      - 'Replace 1:1 commands directly (e.g. vitest → bsh test)'
+      - 'Evaluate which remaining commands can be migrated'
+      - 'Migrate remaining commands one by one'
+    failure_modes:
+      - mistake: 'Leaving old tool configs alongside bsh'
+        mechanism: 'Agent adds @bomb.sh/tools but leaves .prettierrc, biome.json, .eslintrc, etc. creating conflicting configs'
+        wrong_pattern: |
+          # .prettierrc still exists
+          # biome.json still exists
+          # package.json still has prettier, biome in devDependencies
+        correct_pattern: |
+          # Remove all old config files
+          # Remove old tool devDependencies
+          # Only @bomb.sh/tools remains
+        source: 'maintainer interview'
+        priority: 'HIGH'
+        status: 'active'
+
+      - mistake: 'Keeping old tool-specific scripts'
+        mechanism: 'Agent preserves old script patterns like "lint": "eslint ." instead of replacing with bsh equivalents'
+        wrong_pattern: |
+          "scripts": {
+            "lint": "eslint . && tsc --noEmit",
+            "format": "prettier --write ."
+          }
+        correct_pattern: |
+          "scripts": {
+            "lint": "bsh lint",
+            "format": "bsh format"
+          }
+        source: 'maintainer interview'
+        priority: 'HIGH'
+        status: 'active'
+
+      - mistake: 'Not moving tests to colocated pattern'
+        mechanism: 'Agent migrates build/lint but leaves tests in __tests__/ directory instead of colocating next to source'
+        source: 'maintainer interview'
+        priority: 'MEDIUM'
+        status: 'active'
+
+tensions:
+  - name: 'Prototyping speed vs production lint strictness'
+    skills: ['lifecycle', 'lint']
+    description: 'Skipping lint is fine for prototyping but not for shipping; agents tend to either always skip lint or always run it'
+    implication: 'Agent either wastes time linting during exploratory work or ships unlinted code to production'
+
+  - name: 'Opinionated defaults vs explicit configuration'
+    skills: ['build', 'lint', 'format']
+    description: 'bsh wraps tools with strong defaults; agents assume they need to pass flags to configure everything explicitly'
+    implication: 'Agent over-configures by passing redundant flags or fighting against defaults instead of trusting them'
+
+  - name: 'Dev command stability vs experimental Node features'
+    skills: ['dev', 'lifecycle']
+    description: 'dev relies on --experimental-transform-types which may change; other commands are stable'
+    implication: 'Agent treats dev command as equally stable as build/test; may need to adapt if underlying approach changes'
+
+cross_references:
+  - from: 'lifecycle'
+    to: 'lint'
+    reason: 'Lint rules encode the coding conventions that lifecycle enforces; understanding lint rules prevents violations during implementation'
+  - from: 'lifecycle'
+    to: 'test'
+    reason: 'TDD workflow requires understanding test conventions and createFixture usage'
+  - from: 'migrate'
+    to: 'lifecycle'
+    reason: 'After migration, developers need to adopt the bsh lifecycle workflow'
+  - from: 'migrate'
+    to: 'lint'
+    reason: 'Migration requires understanding which old tool configs to remove and what bsh lint replaces'
+  - from: 'test'
+    to: 'lint'
+    reason: 'Tests must follow the same coding conventions enforced by lint'
+  - from: 'build'
+    to: 'dev'
+    reason: 'Both handle TypeScript compilation but in different modes; understanding one informs the other'
+  - from: 'init'
+    to: 'lifecycle'
+    reason: 'After init, the developer enters the lifecycle workflow'
+
+gaps:
+  - skill: 'migrate'
+    question: 'Is there a specific migration checklist or order of operations that works best?'
+    context: 'Migration is the most common onboarding task but has no existing skill file'
+    status: 'resolved'
+    resolution: 'Checklist: check existing tools → add unimplemented commands (lint, format) → replace 1:1 commands (vitest → bsh test) → evaluate remaining → migrate one by one'
+  - skill: 'dev'
+    question: 'When would dev switch from --experimental-transform-types to tsdown dev mode?'
+    context: 'Maintainer flagged dev as most experimental command'
+    status: 'resolved'
+    resolution: 'Most packages do not have a dev mode; TDD loop and running examples directly IS the dev loop. Dev command stability is low priority.'
+  - skill: 'test'
+    question: 'What additional test utilities are planned (ANSI snapshots, etc)?'
+    context: 'Maintainer mentioned possible expansion of test-utils'
+    status: 'resolved'
+    resolution: 'Clack repo has MockReadable/MockWritable for terminal I/O simulation and vitest-ansi-serializer for ANSI snapshot testing. These are candidates for extraction into @bomb.sh/tools/test-utils.'
diff --git a/skills/_artifacts/skill_spec.md b/skills/_artifacts/skill_spec.md
new file mode 100644
index 0000000..bbbc21a
--- /dev/null
+++ b/skills/_artifacts/skill_spec.md
@@ -0,0 +1,148 @@
+# @bomb.sh/tools — Skill Spec
+
+Unified internal CLI (`bsh`) that standardizes development workflows (build, dev, format, init, lint, test) across all Bombshell ecosystem projects by orchestrating opinionated configurations of industry-standard tools (tsdown, oxlint, oxfmt, vitest, knip, publint).
+
+## Domains
+
+| Domain | Description | Skills |
+| ------ | ----------- | ------ |
+| development workflow | End-to-end development lifecycle — TDD loop, command ordering, monorepo detection | lifecycle |
+| code quality | Linting, formatting, and opinionated conventions | lint, format |
+| compilation | Building TypeScript to ESM and running TypeScript natively | build, dev |
+| testing | Writing and running tests with colocated conventions and fixture utilities | test |
+| project setup | Creating new projects and migrating existing ones to bsh | init, migrate |
+
+## Skill Inventory
+
+| Skill | Type | Domain | What it covers | Failure modes |
+| ----- | ---- | ------ | -------------- | ------------- |
+| lifecycle | lifecycle | workflow | TDD workflow, pnpm run, monorepo detection, human-owned PRs | 6 |
+| lint | core | quality | oxlint + publint + knip + tsgo, Bombshell conventions | 8 |
+| build | core | compilation | tsdown ESM output, sourcemaps, declaration files | 3 |
+| test | core | testing | vitest, colocated tests, createFixture, type-level tests | 4 |
+| format | core | quality | oxfmt, tabs/single-quotes/semicolons style | 3 |
+| dev | core | compilation | Node --experimental-transform-types, watch mode | 2 |
+| init | core | setup | Template scaffolding via giget | 1 |
+| migrate | lifecycle | setup | Removing old tools, consolidating to @bomb.sh/tools | 3 |
+
+## Failure Mode Inventory
+
+### Lifecycle (6 failure modes)
+
+| # | Mistake | Priority | Source | Cross-skill? |
+| - | ------- | -------- | ------ | ------------ |
+| 1 | Using npx instead of pnpm run | CRITICAL | skill + interview | — |
+| 2 | Running underlying tools directly | CRITICAL | skill + interview | — |
+| 3 | Skipping TDD and implementing first | HIGH | skill + interview | — |
+| 4 | Using npm, yarn, or bun | CRITICAL | skill | — |
+| 5 | Running tsc directly | HIGH | skill + interview | — |
+| 6 | Full autopilot PR creation | HIGH | interview | — |
+
+### Lint (8 failure modes)
+
+| # | Mistake | Priority | Source | Cross-skill? |
+| - | ------- | -------- | ------ | ------------ |
+| 1 | Using node:path instead of URL | CRITICAL | skill | lifecycle |
+| 2 | Functions with more than 2 parameters | HIGH | skill + interview | lifecycle |
+| 3 | Using console.log | MEDIUM | skill | — |
+| 4 | Using default exports | HIGH | skill | — |
+| 5 | Not using import type | MEDIUM | skill | — |
+| 6 | Over-commenting obvious code | MEDIUM | interview | lifecycle |
+| 7 | Not using bleeding-edge Node builtins | HIGH | interview | lifecycle |
+| 8 | Preferring dependencies over builtins | HIGH | interview | lifecycle |
+
+### Build (3 failure modes)
+
+| # | Mistake | Priority | Source | Cross-skill? |
+| - | ------- | -------- | ------ | ------------ |
+| 1 | Passing unnecessary flags | MEDIUM | skill + interview | — |
+| 2 | Running tsdown directly | HIGH | skill | — |
+| 3 | CommonJS output configuration | HIGH | skill | — |
+
+### Test (4 failure modes)
+
+| # | Mistake | Priority | Source | Cross-skill? |
+| - | ------- | -------- | ------ | ------------ |
+| 1 | Placing tests in __tests__ directory | HIGH | skill | — |
+| 2 | Extracting fixtures into shared variables | MEDIUM | skill | — |
+| 3 | Testing implementation details | HIGH | interview | — |
+| 4 | Running vitest directly | HIGH | skill | — |
+
+### Format (3 failure modes)
+
+| # | Mistake | Priority | Source | Cross-skill? |
+| - | ------- | -------- | ------ | ------------ |
+| 1 | Running prettier or biome format | HIGH | skill + interview | — |
+| 2 | Using spaces instead of tabs | MEDIUM | conventions | — |
+| 3 | Using double quotes | MEDIUM | conventions | — |
+
+### Dev (2 failure modes)
+
+| # | Mistake | Priority | Source | Cross-skill? |
+| - | ------- | -------- | ------ | ------------ |
+| 1 | Using tsx or ts-node | CRITICAL | skill | — |
+| 2 | Installing TypeScript transpilers | HIGH | skill | — |
+
+### Init (1 failure mode)
+
+| # | Mistake | Priority | Source | Cross-skill? |
+| - | ------- | -------- | ------ | ------------ |
+| 1 | Manually scaffolding project structure | MEDIUM | skill | — |
+
+### Migrate (3 failure modes)
+
+| # | Mistake | Priority | Source | Cross-skill? |
+| - | ------- | -------- | ------ | ------------ |
+| 1 | Leaving old tool configs alongside bsh | HIGH | interview | — |
+| 2 | Keeping old tool-specific scripts | HIGH | interview | — |
+| 3 | Not moving tests to colocated pattern | MEDIUM | interview | — |
+
+## Tensions
+
+| Tension | Skills | Agent implication |
+| ------- | ------ | ----------------- |
+| Prototyping speed vs production lint strictness | lifecycle <-> lint | Agent either wastes time linting during exploration or ships unlinted code |
+| Opinionated defaults vs explicit configuration | build <-> lint <-> format | Agent over-configures by passing redundant flags |
+| Dev command stability vs experimental Node features | dev <-> lifecycle | Agent treats dev as equally stable as other commands |
+
+## Cross-References
+
+| From | To | Reason |
+| ---- | -- | ------ |
+| lifecycle | lint | Lint rules encode conventions that lifecycle enforces |
+| lifecycle | test | TDD workflow requires understanding test conventions |
+| migrate | lifecycle | After migration, adopt bsh lifecycle workflow |
+| migrate | lint | Migration requires knowing which old configs to remove |
+| test | lint | Tests must follow same coding conventions |
+| build | dev | Both handle TS compilation in different modes |
+| init | lifecycle | After init, enter lifecycle workflow |
+
+## Subsystems & Reference Candidates
+
+| Skill | Subsystems | Reference candidates |
+| ----- | ---------- | -------------------- |
+| lint | oxlint, publint, knip, tsgo | Bombshell-specific lint rules (>10 rules) |
+| test | — | createFixture API |
+| All others | — | — |
+
+## Resolved Gaps
+
+| Skill | Question | Resolution |
+| ----- | -------- | ---------- |
+| migrate | Migration order of operations? | Check existing → add unimplemented commands → replace 1:1 → evaluate remaining → migrate one by one |
+| dev | When switch from experimental-transform-types? | Most packages don't need dev mode; TDD + running examples IS the dev loop |
+| test | Additional test utilities planned? | Clack has MockReadable/MockWritable and vitest-ansi-serializer — candidates for extraction into test-utils |
+
+## Recommended Skill File Structure
+
+- **Core skills:** build, test, format, dev, init
+- **Framework skills:** none (framework-agnostic)
+- **Lifecycle skills:** lifecycle, migrate
+- **Composition skills:** none (self-contained toolchain)
+- **Reference files:** lint (dense rule surface)
+
+## Composition Opportunities
+
+| Library | Integration points | Composition skill needed? |
+| ------- | ------------------ | ------------------------- |
+| @bomb.sh/args | Argument parsing in CLI commands | No — internal dependency, not user-facing integration |
diff --git a/skills/_artifacts/skill_tree.yaml b/skills/_artifacts/skill_tree.yaml
new file mode 100644
index 0000000..8d87dda
--- /dev/null
+++ b/skills/_artifacts/skill_tree.yaml
@@ -0,0 +1,138 @@
+# skills/_artifacts/skill_tree.yaml
+library:
+  name: '@bomb.sh/tools'
+  version: '0.2.8'
+  repository: 'https://github.com/bombshell-dev/tools'
+  description: 'Unified internal CLI (bsh) that standardizes dev workflows across Bombshell ecosystem projects.'
+generated_from:
+  domain_map: 'skills/_artifacts/domain_map.yaml'
+  skill_spec: 'skills/_artifacts/skill_spec.md'
+generated_at: '2026-03-25'
+
+skills:
+  - name: 'Development Lifecycle'
+    slug: 'lifecycle'
+    type: 'lifecycle'
+    domain: 'workflow'
+    path: 'skills/lifecycle/SKILL.md'
+    description: >
+      TDD-driven development workflow for Bombshell projects. Covers command ordering
+      (test→implement→lint→format→build→test), pnpm run as only entry point, monorepo
+      vs single-package detection, pnpm --filter for targeting packages. Use when
+      starting work on any Bombshell project.
+    requires: []
+    sources:
+      - 'bombshell-dev/tools:skills/lifecycle/SKILL.md'
+      - 'bombshell-dev/tools:src/bin.ts'
+
+  - name: 'Lint'
+    slug: 'lint'
+    type: 'core'
+    domain: 'quality'
+    path: 'skills/lint/SKILL.md'
+    description: >
+      Multi-tool linting pipeline: oxlint, publint, knip, tsgo in parallel. Covers
+      Bombshell coding conventions: URL over node:path, max 2 params, named exports
+      only, import type, prefer node builtins, no console.log. Use when checking code
+      quality or understanding lint rule violations.
+    requires:
+      - 'lifecycle'
+    sources:
+      - 'bombshell-dev/tools:skills/lint/SKILL.md'
+      - 'bombshell-dev/tools:src/commands/lint.ts'
+      - 'bombshell-dev/tools:oxlintrc.json'
+    references:
+      - 'references/lint-rules.md'
+
+  - name: 'Build'
+    slug: 'build'
+    type: 'core'
+    domain: 'compilation'
+    path: 'skills/build/SKILL.md'
+    description: >
+      TypeScript to ESM compilation via tsdown with opinionated defaults. Covers
+      sourcemaps, clean dist/, unbundled output, --dts, --bundle, --minify flags.
+      Use when building a package for publish or generating declaration files.
+    requires:
+      - 'lifecycle'
+    sources:
+      - 'bombshell-dev/tools:skills/build/SKILL.md'
+      - 'bombshell-dev/tools:src/commands/build.ts'
+
+  - name: 'Test'
+    slug: 'test'
+    type: 'core'
+    domain: 'testing'
+    path: 'skills/test/SKILL.md'
+    description: >
+      Vitest test runner with colocated .test.ts files and createFixture utility for
+      filesystem-based tests. Covers .test-d.ts type-level tests, inline fixture
+      declarations, fixture API (root, resolve, text, json, write, cleanup). Use when
+      writing or running tests.
+    requires:
+      - 'lifecycle'
+    sources:
+      - 'bombshell-dev/tools:skills/test/SKILL.md'
+      - 'bombshell-dev/tools:src/commands/test.ts'
+      - 'bombshell-dev/tools:src/test-utils.ts'
+
+  - name: 'Format'
+    slug: 'format'
+    type: 'core'
+    domain: 'quality'
+    path: 'skills/format/SKILL.md'
+    description: >
+      Code formatting via oxfmt with project configuration. Tabs, single quotes,
+      semicolons always, trailing commas, 100-char line width. Use when formatting
+      source files.
+    requires:
+      - 'lifecycle'
+    sources:
+      - 'bombshell-dev/tools:skills/format/SKILL.md'
+      - 'bombshell-dev/tools:src/commands/format.ts'
+      - 'bombshell-dev/tools:oxfmtrc.json'
+
+  - name: 'Dev'
+    slug: 'dev'
+    type: 'core'
+    domain: 'compilation'
+    path: 'skills/dev/SKILL.md'
+    description: >
+      Watch mode development using Node --experimental-transform-types. No transpiler
+      needed. Watches ./src/ directory, restarts on changes. Experimental — may switch
+      to tsdown dev mode. Use when running TypeScript in dev mode.
+    requires:
+      - 'lifecycle'
+    sources:
+      - 'bombshell-dev/tools:skills/dev/SKILL.md'
+      - 'bombshell-dev/tools:src/commands/dev.ts'
+
+  - name: 'Init'
+    slug: 'init'
+    type: 'core'
+    domain: 'setup'
+    path: 'skills/init/SKILL.md'
+    description: >
+      Scaffold new Bombshell project from bombshell-dev/template via giget. Replaces
+      $name placeholder, outputs to .temp/. Use when creating a new package in the
+      Bombshell ecosystem.
+    requires: []
+    sources:
+      - 'bombshell-dev/tools:skills/init/SKILL.md'
+      - 'bombshell-dev/tools:src/commands/init.ts'
+
+  - name: 'Migrate'
+    slug: 'migrate'
+    type: 'lifecycle'
+    domain: 'setup'
+    path: 'skills/migrate/SKILL.md'
+    description: >
+      Migrate existing project to bsh toolchain. Covers removing prettier, biome,
+      eslint, tsup, unbuild, rollup configs and dependencies. Replacing scripts with
+      bsh equivalents. Consolidating to single @bomb.sh/tools devDependency. Migration
+      checklist: check existing → add unimplemented → replace 1:1 → evaluate → migrate
+      one by one. Use when onboarding a project to the Bombshell ecosystem.
+    requires:
+      - 'lifecycle'
+    sources:
+      - 'bombshell-dev/tools:skills/lifecycle/SKILL.md'
diff --git a/skills/build/SKILL.md b/skills/build/SKILL.md
index 176d357..4410f35 100644
--- a/skills/build/SKILL.md
+++ b/skills/build/SKILL.md
@@ -1,13 +1,24 @@
 ---
 name: build
-description: "Use when compiling TypeScript to ESM, generating declaration files, or preparing a package for publish."
+description: >
+  TypeScript to ESM compilation via tsdown with opinionated defaults. Sourcemaps,
+  clean dist/, unbundled output. Flags: --dts, --bundle, --minify. Default entry
+  src/**/*.ts. Use when building a package for publish or generating declarations.
+metadata:
+  type: core
+  library: '@bomb.sh/tools'
+  library_version: '0.2.8'
+  requires:
+    - lifecycle
+  sources:
+    - 'bombshell-dev/tools:src/commands/build.ts'
 ---
 
 # Build
 
 Builds TypeScript to ESM using tsdown with opinionated defaults.
 
-## Usage
+## Setup
 
 ```sh
 pnpm run build
@@ -21,16 +32,72 @@ pnpm run build
 - **Clean:** removes dist/ before building
 - **Unbundled** by default (each source file produces one output file)
 - **Entry:** defaults to `src/**/*.ts`
+- **Config:** explicitly disabled (`config: false`) — tsdown.config.ts is ignored
 
 ## Flags
 
 Pass flags after `--` in pnpm:
 
+| Flag | Effect |
+|------|--------|
+| `--dts` | Generate `.d.mts` declaration files |
+| `--bundle` | Bundle into single output (disables unbundled mode) |
+| `--minify` | Minify output |
+| positional args | Custom entry points (replaces default `src/**/*.ts`) |
+
+```sh
+pnpm run build -- --dts
+pnpm run build -- --bundle
+pnpm run build -- --minify
+pnpm run build -- src/index.ts
+pnpm run build -- --dts --minify
+```
+
+## Common Mistakes
+
+### MEDIUM: Passing unnecessary flags
+
+ESM, sourcemaps, and clean are already defaults. Don't pass them explicitly.
+
+```sh
+# Wrong
+pnpm run build -- --format esm --sourcemap --clean
+```
+
+```sh
+# Correct
+pnpm run build
+```
+
+### HIGH: Running tsdown directly
+
+Always go through the `bsh` wrapper to get correct defaults.
+
+```sh
+# Wrong
+pnpm exec tsdown src/**/*.ts --format esm
+npx tsdown src/**/*.ts
+```
+
 ```sh
-pnpm run build -- --dts        # Generate .d.mts declaration files
-pnpm run build -- --bundle     # Bundle into single output (disables unbundled mode)
-pnpm run build -- --minify     # Minify output
-pnpm run build -- src/index.ts # Specify custom entry points
+# Correct
+pnpm run build
 ```
 
-Flags can be combined: `pnpm run build -- --dts --minify`
+### HIGH: CommonJS output configuration
+
+Bombshell is ESM-only. Never configure CJS output.
+
+```sh
+# Wrong
+pnpm run build -- --format cjs
+```
+
+```sh
+# Correct — ESM is the only format, no flag needed
+pnpm run build
+```
+
+## See Also
+
+- `dev/SKILL.md` — Both handle TS compilation in different modes
diff --git a/skills/dev/SKILL.md b/skills/dev/SKILL.md
index b6e506e..4436d22 100644
--- a/skills/dev/SKILL.md
+++ b/skills/dev/SKILL.md
@@ -1,13 +1,24 @@
 ---
 name: dev
-description: "Use when running a TypeScript file in watch mode during development."
+description: >
+  Watch mode development using Node --experimental-transform-types. No transpiler
+  needed. Watches ./src/, restarts on changes. Custom entry files supported.
+  Experimental command — may change. Use when running TypeScript in dev mode.
+metadata:
+  type: core
+  library: '@bomb.sh/tools'
+  library_version: '0.2.8'
+  requires:
+    - lifecycle
+  sources:
+    - 'bombshell-dev/tools:src/commands/dev.ts'
 ---
 
 # Dev
 
-Runs a file with native Node TypeScript support and watches for changes.
+Runs a TypeScript file with native Node TypeScript support and watches for changes.
 
-## Usage
+## Setup
 
 ```sh
 pnpm run dev
@@ -23,7 +34,7 @@ node --experimental-transform-types --no-warnings --watch-path=./src/ <file>
 
 - **Default file:** `./src/index.ts`
 - **Watch path:** `./src/` — restarts on any change in the source directory
-- **No transpiler needed** — Node handles TypeScript natively
+- **No transpiler needed** — Node handles TypeScript natively via `--experimental-transform-types`
 
 ## Custom Entry
 
@@ -32,3 +43,56 @@ pnpm run dev -- ./src/other.ts
 ```
 
 Additional arguments after the file path are passed through to Node.
+
+## Note
+
+This is an experimental command that relies on Node's `--experimental-transform-types` flag. Most Bombshell packages use a TDD loop (`pnpm run test`) as their primary development workflow rather than the dev server. The dev command is useful for running scripts or servers during development, not as the main iteration cycle.
+
+> **Tension:** Dev command stability vs experimental Node features. The underlying `--experimental-transform-types` flag may change behavior between Node versions. If you hit issues, fall back to the test-driven workflow.
+
+## Common Mistakes
+
+### CRITICAL: Using tsx or ts-node
+
+Node handles TypeScript natively. External transpilers are unnecessary and add complexity.
+
+```sh
+# Wrong
+npx tsx src/index.ts
+npx tsx watch src/index.ts
+npx ts-node src/index.ts
+node -r ts-node/register src/index.ts
+```
+
+```sh
+# Correct
+pnpm run dev
+```
+
+### HIGH: Installing TypeScript transpilers as dependencies
+
+These packages are not needed in Bombshell projects.
+
+```json
+// Wrong — package.json
+{
+  "devDependencies": {
+    "tsx": "^4.0.0",
+    "ts-node": "^10.0.0",
+    "esbuild-register": "^3.0.0"
+  }
+}
+```
+
+```json
+// Correct — no transpiler dependencies needed
+{
+  "devDependencies": {
+    "@bomb.sh/tools": "^0.2.8"
+  }
+}
+```
+
+## See Also
+
+- `build/SKILL.md` — Both handle TS compilation in different modes
diff --git a/skills/format/SKILL.md b/skills/format/SKILL.md
index a8c6689..4267470 100644
--- a/skills/format/SKILL.md
+++ b/skills/format/SKILL.md
@@ -1,13 +1,25 @@
 ---
 name: format
-description: "Use when formatting source files or checking code style."
+description: >
+  Code formatting via oxfmt with project configuration. Tabs, single quotes,
+  semicolons always, trailing commas, 100-char line width. Use when formatting
+  source files before committing.
+metadata:
+  type: core
+  library: '@bomb.sh/tools'
+  library_version: '0.2.8'
+  requires:
+    - lifecycle
+  sources:
+    - 'bombshell-dev/tools:src/commands/format.ts'
+    - 'bombshell-dev/tools:oxfmtrc.json'
 ---
 
 # Format
 
 Formats source files using oxfmt with the project's configuration.
 
-## Usage
+## Setup
 
 ```sh
 pnpm run format
@@ -16,13 +28,76 @@ pnpm run format
 ## How It Works
 
 `pnpm run format` runs `bsh format` which calls oxfmt with:
-- **Config:** `oxfmtrc.json` from `@bomb.sh/tools`
+- **Config:** `oxfmtrc.json` bundled in `@bomb.sh/tools`
 - **Default target:** `./src`
-
-## Custom Targets
+- Additional arguments are passed through to oxfmt
 
 ```sh
 pnpm run format -- ./path/to/file.ts
 ```
 
-Additional arguments are passed through to oxfmt.
+## Style Rules
+
+| Rule | Value |
+|------|-------|
+| Indentation | Tabs |
+| Quotes | Single quotes |
+| Semicolons | Always |
+| Trailing commas | Yes |
+| Line width | 100 characters |
+
+These are enforced by `oxfmtrc.json`. The config file is resolved from the `@bomb.sh/tools` package, not from the project root.
+
+> **Tension:** Opinionated defaults vs explicit configuration. Trust the defaults — don't pass extra flags to override style rules. The project convention is uniform formatting across all Bombshell packages.
+
+## Common Mistakes
+
+### HIGH: Running prettier or biome format
+
+The project uses oxfmt exclusively. Other formatters will produce different output.
+
+```sh
+# Wrong
+npx prettier --write src/
+npx biome format src/
+pnpm exec prettier --write .
+```
+
+```sh
+# Correct
+pnpm run format
+```
+
+### MEDIUM: Using spaces instead of tabs
+
+oxfmt enforces tabs. If your editor is configured for spaces, the formatter will rewrite them.
+
+```ts
+// Wrong — spaces
+function hello() {
+    return 'world';
+}
+```
+
+```ts
+// Correct — tabs
+function hello() {
+	return 'world';
+}
+```
+
+### MEDIUM: Using double quotes instead of single quotes
+
+oxfmt enforces single quotes. Don't fight the formatter.
+
+```ts
+// Wrong
+import { readFile } from "node:fs/promises";
+const name = "bombshell";
+```
+
+```ts
+// Correct
+import { readFile } from 'node:fs/promises';
+const name = 'bombshell';
+```
diff --git a/skills/init/SKILL.md b/skills/init/SKILL.md
index 74a8497..7abddea 100644
--- a/skills/init/SKILL.md
+++ b/skills/init/SKILL.md
@@ -1,26 +1,64 @@
 ---
 name: init
-description: "Use when creating a new Bombshell project or package from the template."
+description: >
+  Scaffold new Bombshell project from bombshell-dev/template via giget. Replaces
+  $name placeholder in package.json and README.md. Outputs to .temp/. Use when
+  creating a new package in the Bombshell ecosystem.
+metadata:
+  type: core
+  library: '@bomb.sh/tools'
+  library_version: '0.2.8'
+  sources:
+    - 'bombshell-dev/tools:src/commands/init.ts'
 ---
 
 # Init
 
 Scaffolds a new Bombshell project from the `bombshell-dev/template` GitHub template.
 
-## Usage
+## Setup
 
 ```sh
-pnpm run init
 pnpm run init -- my-project
 ```
 
 ## How It Works
 
 `pnpm run init` runs `bsh init` which:
+
 1. Clones `gh:bombshell-dev/template` via giget
-2. Replaces `$name` placeholder in `package.json` and `README.md`
+2. Replaces `$name` placeholder in `package.json` and `README.md` with the project name
 3. Outputs to `.temp/` directory
 
-## Arguments
+### Arguments
+
+- First positional arg: project name
+- If no name is provided, defaults to the parent directory name
+
+```sh
+pnpm run init -- my-project    # Creates .temp/my-project
+pnpm run init                   # Uses parent directory name
+```
+
+## Common Mistakes
+
+### MEDIUM: Manually scaffolding project structure
+
+The template includes all Bombshell conventions (package.json scripts, tsconfig, etc.). Don't create these by hand.
+
+```sh
+# Wrong
+mkdir my-project
+cd my-project
+npm init -y
+# ... manually adding scripts, configs, etc.
+```
+
+```sh
+# Correct
+pnpm run init -- my-project
+```
+
+## See Also
 
-- First positional arg: project name (defaults to current directory name)
+- `lifecycle/SKILL.md` — After init, enter the lifecycle workflow
diff --git a/skills/lifecycle/SKILL.md b/skills/lifecycle/SKILL.md
index 73a30e6..94149fb 100644
--- a/skills/lifecycle/SKILL.md
+++ b/skills/lifecycle/SKILL.md
@@ -1,68 +1,224 @@
 ---
 name: lifecycle
-description: "Use when working in any project that depends on @bomb.sh/tools — covers how to run build, test, lint, format, dev, and init tasks."
+description: >
+  TDD-driven development workflow for Bombshell projects using bsh CLI. Covers
+  pnpm run as only entry point, command ordering (test→implement→lint→format→build→test),
+  monorepo vs single-package detection with pnpm --filter, human-owned PRs.
+  Use when starting work on any project that depends on @bomb.sh/tools.
+metadata:
+  type: lifecycle
+  library: '@bomb.sh/tools'
+  library_version: '0.2.8'
+  sources:
+    - 'bombshell-dev/tools:skills/lifecycle/SKILL.md'
+    - 'bombshell-dev/tools:src/bin.ts'
 ---
 
-# Bombshell Project Lifecycle
+# Development Lifecycle
 
-This project uses `@bomb.sh/tools` (`bsh`) as its dev toolchain. All dev tasks are run through `package.json` scripts.
+TDD-driven workflow for all Bombshell projects. Follow the checklist below for every change.
 
-## Rules
+## Available Scripts
+
+All scripts proxy to `bsh <command>` via `package.json`. Never bypass them.
 
-1. **Always use `pnpm run <script>`** to run project tasks
-2. **Never use `npx`, `npm run`, `pnpm dlx`, `yarn`, `bun`, or `tsx`**
-3. **Never run underlying tools directly** — no `pnpm exec tsdown`, `pnpm exec vitest`, `pnpm exec oxlint`, `pnpm exec knip`
-4. **Always ESM** — no CommonJS, no `require()`, no `ts-node`, no `tsx`
-5. **Node handles TypeScript natively** via `--experimental-transform-types`
-6. **pnpm is the only package manager** — never use `npm`, `yarn`, or `bun`
+| Command              | Runs         | Purpose                                    |
+| -------------------- | ------------ | ------------------------------------------ |
+| `pnpm run build`     | `bsh build`  | Build with tsdown (ESM, sourcemaps, clean) |
+| `pnpm run dev`       | `bsh dev`    | Watch mode with native Node TS transforms  |
+| `pnpm run format`    | `bsh format` | Format with oxfmt                          |
+| `pnpm run lint`      | `bsh lint`   | Parallel: oxlint + publint + knip + tsgo   |
+| `pnpm run test`      | `bsh test`   | Run tests with vitest (single run)         |
+| `pnpm run init`      | `bsh init`   | Scaffold new project from template         |
 
 ## Monorepo vs Single Package
 
-Detect project structure before running commands.
+Detect the project structure before running any commands.
 
-**Single package** (no `pnpm-workspace.yaml`):
-- All scripts run from package root: `pnpm run <script>`
+**Single package** — no `pnpm-workspace.yaml` at root:
 
-**Monorepo** (has `pnpm-workspace.yaml`):
-- Conventional layout: `packages/` for libraries, `examples/` for demos
-- Root scripts may differ — always check `package.json` before running
-- To target one package: `pnpm --filter <pkg> run <script>`
-- Common pattern: `build`/`test` recursive (`pnpm -r`), `format`/`lint` direct (`bsh`)
+```sh
+pnpm run test
+pnpm run lint
+```
 
-## Available Scripts
+**Monorepo** — has `pnpm-workspace.yaml`:
+
+```sh
+# Target a specific package
+pnpm --filter <package-name> run test
+pnpm --filter <package-name> run build
+
+# Run recursively across all packages
+pnpm -r run build
+pnpm -r run test
+
+# Root-level scripts (lint/format typically run from root)
+pnpm run lint
+pnpm run format
+```
+
+Check `pnpm-workspace.yaml` for the workspace layout. Conventional structure:
+- `packages/` for libraries
+- `examples/` for demos
+
+Always read the root `package.json` before assuming which scripts exist.
+
+## Workflow Checklist
+
+Follow this order for every change. Do not skip steps, do not reorder.
+
+### 1. Write Tests First (RED)
+
+- [ ] Create or update `.test.ts` files **before** writing implementation
+- [ ] Colocate tests next to source — never in `__tests__/` or `test/`
+- [ ] Run tests and confirm new tests **fail**:
+
+```sh
+pnpm run test
+```
+
+### 2. Implement (GREEN)
+
+- [ ] Write the minimum code to make tests pass
+- [ ] Run tests and confirm they **pass**:
 
-All scripts are defined in `package.json` and proxy to `bsh <command>`:
+```sh
+pnpm run test
+```
 
-| Script            | What It Does                                      |
-| ----------------- | ------------------------------------------------- |
-| `pnpm run build`  | Build with tsdown (ESM, sourcemaps, clean dist)   |
-| `pnpm run dev`    | Watch mode with native Node TypeScript transforms |
-| `pnpm run format` | Format with oxfmt                                 |
-| `pnpm run lint`   | Parallel lint: oxlint + publint + knip + tsc      |
-| `pnpm run test`   | Run tests with vitest                             |
-| `pnpm run init`   | Scaffold new Bombshell project from template      |
+### 3. Lint
 
-## Development Workflow
+- [ ] Run the full lint pipeline:
 
-Follow this order when making changes. Write tests first, verify before claiming success.
+```sh
+pnpm run lint
+```
 
-1. **Test first** — write or update `.test.ts` files before implementation
-2. **Run tests** (`pnpm run test`) — confirm the new test fails (RED)
-3. **Implement** — write the minimum code to pass
-4. **Run tests** (`pnpm run test`) — confirm tests pass (GREEN)
-5. **Lint** (`pnpm run lint`) — fix type errors, unused exports, style
-6. **Format** (`pnpm run format`) — normalize code style
-7. **Build** (`pnpm run build`) — verify the package compiles
-8. **Final test** (`pnpm run test`) — end-to-end confirmation
+- [ ] Fix all errors. Use `--fix` for auto-fixable issues:
 
-Never skip straight to implementation. Never claim "tests pass" without running them.
+```sh
+pnpm run lint -- --fix
+```
+
+### 4. Format
+
+- [ ] Normalize code style:
+
+```sh
+pnpm run format
+```
+
+### 5. Build
+
+- [ ] Verify the package compiles:
+
+```sh
+pnpm run build
+```
+
+### 6. Final Test
+
+- [ ] End-to-end confirmation after build:
+
+```sh
+pnpm run test
+```
+
+### 7. PR Handoff
+
+- [ ] Present a summary of changes to the human
+- [ ] **Human creates the PR** — agents do not create or merge PRs autonomously
 
 ## Do Not
 
-- Run `npx tsx`, `npx ts-node`, or `node -r ts-node/register`
-- Run `npx tsc` or `tsgo` directly — `pnpm run lint` includes type checking
-- Run `npx vitest` directly — use `pnpm run test`
-- Run `npx oxlint` or `npx oxfmt` directly — use `pnpm run lint` / `pnpm run format`
-- Use `require()` or any CommonJS patterns
-- Install `tsx`, `ts-node`, or `esbuild-register`
-- Use `npm`, `yarn`, or `bun` for anything
+These are hard rules. Violating any of them is a failed task.
+
+| Forbidden                                    | Use Instead                         |
+| -------------------------------------------- | ----------------------------------- |
+| `npx <anything>`                             | `pnpm run <script>`                 |
+| `pnpm dlx` for local tools                   | `pnpm run <script>`                 |
+| `npm run`, `yarn`, `bun`                     | `pnpm run <script>`                 |
+| `tsx`, `ts-node`, `esbuild-register`         | Native Node TS (`--experimental-transform-types`) |
+| `npx vitest` / `pnpm exec vitest`           | `pnpm run test`                     |
+| `npx oxlint` / `pnpm exec oxlint`           | `pnpm run lint`                     |
+| `npx oxfmt` / `pnpm exec oxfmt`             | `pnpm run format`                   |
+| `npx tsdown` / `pnpm exec tsdown`           | `pnpm run build`                    |
+| `npx knip` / `pnpm exec knip`               | `pnpm run lint`                     |
+| `npx tsc` / `tsgo` directly                 | `pnpm run lint` (includes type checking) |
+| `require()`, `module.exports`               | ESM `import` / `export`             |
+| Implement before writing tests               | Write tests first (RED→GREEN)       |
+| Claim "tests pass" without running them      | Always run `pnpm run test`          |
+| Create PRs autonomously                      | Present summary, human authors PR   |
+
+## Common Mistakes
+
+### CRITICAL: Using npx instead of pnpm run
+
+Agents default to `npx`. Bombshell projects always use `pnpm run` for local scripts. If you need a one-off binary not in the project, use `pnpm dlx` — but local tools must go through `pnpm run`.
+
+### CRITICAL: Running underlying tools directly
+
+Never call `tsdown`, `vitest`, `oxlint`, `knip`, `oxfmt`, or `tsgo` directly. The `bsh` wrapper configures flags, paths, and parallelism. Bypassing it produces wrong behavior.
+
+### CRITICAL: Using npm, yarn, or bun
+
+`pnpm` is the only package manager. Do not install, run, or execute with any other package manager.
+
+### HIGH: Skipping TDD and implementing first
+
+Always write or update tests before implementation. The RED→GREEN cycle is not optional. If you find yourself writing code without a failing test, stop and write the test first.
+
+### HIGH: Running tsc directly for type checking
+
+`pnpm run lint` runs `tsgo --noEmit` as part of its parallel pipeline. Do not run `tsc` or `tsgo` separately — the lint command handles it.
+
+### HIGH: Full autopilot PR creation
+
+Agents assist with code changes. Humans own the code and author PRs. Present your changes and let the human decide when and how to submit.
+
+### CRITICAL: Using node:path instead of URL
+
+`node:path` is banned by oxlint config. Use `URL` for all path manipulation:
+
+```ts
+// Correct
+const file = new URL("./config.json", import.meta.url);
+
+// Wrong — will fail lint
+import { join } from "node:path";
+const file = join(__dirname, "config.json");
+```
+
+Use `fileURLToPath()` only at boundaries where a third-party API requires a string path.
+
+### HIGH: Functions with more than 2 parameters
+
+Refactor to an options bag. `max-params` is set to 2 and is an error:
+
+```ts
+// Correct
+function createServer(options: { port: number; host: string; ssl: boolean }): void { }
+
+// Wrong — 3 params, fails lint
+function createServer(port: number, host: string, ssl: boolean): void { }
+```
+
+### MEDIUM: Over-commenting obvious code
+
+Do not add comments that restate what the code does. Comments should explain **why**, not **what**.
+
+### HIGH: Not using bleeding-edge Node builtins
+
+Prefer Node built-in APIs over third-party dependencies. Check Node docs for newer APIs before reaching for a package.
+
+## Tensions
+
+**Prototyping speed vs lint strictness** — During early prototyping you may want to move fast, but all code that gets committed must pass `pnpm run lint`. Prototype freely, lint before committing. See also: `lint/SKILL.md`.
+
+**Dev command stability vs experimental Node features** — `pnpm run dev` uses `--experimental-transform-types` which is stable enough for development but may have edge cases. If you hit issues, check Node version compatibility.
+
+## Cross-References
+
+- **lint/SKILL.md** — Full lint rules and conventions that this lifecycle enforces
+- **test/SKILL.md** — Test file conventions, fixture API, and filtering
diff --git a/skills/lint/SKILL.md b/skills/lint/SKILL.md
index 33d5859..bd0d357 100644
--- a/skills/lint/SKILL.md
+++ b/skills/lint/SKILL.md
@@ -1,85 +1,282 @@
 ---
 name: lint
-description: "Use when checking for lint errors, type errors, unused exports, or package.json issues."
+description: >
+  Multi-tool linting pipeline: oxlint, publint, knip, tsgo run in parallel via
+  pnpm run lint. Covers Bombshell conventions: URL over node:path, max 2 params
+  with options bag, named exports only, import type, prefer node builtins, no
+  console.log, no generic Error. Use when checking code quality or understanding
+  lint violations.
+metadata:
+  type: core
+  library: '@bomb.sh/tools'
+  library_version: '0.2.8'
+  requires:
+    - lifecycle
+  sources:
+    - 'bombshell-dev/tools:skills/lint/SKILL.md'
+    - 'bombshell-dev/tools:src/commands/lint.ts'
+    - 'bombshell-dev/tools:oxlintrc.json'
 ---
 
 # Lint
 
-Runs a multi-tool linting pipeline in parallel with unified output.
+Multi-tool linting pipeline. All four tools run in parallel with unified output.
 
-## Usage
+## Setup
 
 ```sh
-pnpm run lint
-pnpm run lint -- --fix
+pnpm run lint              # Report violations
+pnpm run lint -- --fix     # Auto-fix (oxlint only), then report remaining
+pnpm run lint -- src/foo.ts  # Target specific files (default: ./src)
 ```
 
+Do not run oxlint, publint, knip, or tsgo directly. Always use `pnpm run lint`.
+
+See [lifecycle/SKILL.md](../lifecycle/SKILL.md) for where lint fits in the development workflow (step 5: after tests pass, before format).
+
 ## How It Works
 
-`pnpm run lint` runs `bsh lint` which executes four tools **in parallel**:
+`pnpm run lint` runs `bsh lint`, which executes four tools via `Promise.allSettled`:
+
+| Tool | What It Checks | Fix Support |
+|------|---------------|-------------|
+| **oxlint** | JS/TS linting via Rust-based engine with Bombshell config | Yes (`--fix`) |
+| **publint** | `package.json` exports, types, and field correctness (strict mode) | No |
+| **knip** | Unused dependencies, devDependencies, exports, types, files | No |
+| **tsgo** | TypeScript type errors (`--noEmit`, native Go compiler) | No |
+
+Results merge into a single report grouped by file. Exit code 1 if any errors exist.
+
+## Core Patterns
+
+These are the Bombshell coding conventions enforced by oxlint. Write code that follows these from the start.
+
+### URL over `node:path`
+
+All `node:path` and `path` imports are banned. Use the `URL` API for path manipulation. Use `fileURLToPath()` only at boundaries where a third-party API requires a string path.
+
+```ts
+// Correct
+const config = new URL("./config.json", import.meta.url);
+const child = new URL("sub/dir/", parentUrl);
 
-| Tool | What It Checks |
-|------|---------------|
-| **oxlint** | JavaScript/TypeScript linting (fast, Rust-based) |
-| **publint** | package.json correctness (exports, types, etc.) |
-| **knip** | Unused dependencies, exports, types, and files |
-| **tsc** (tsgo) | TypeScript type checking (`--noEmit`) |
+// Correct — boundary where string path is required
+import { fileURLToPath } from "node:url";
+const configPath = fileURLToPath(new URL("./config.json", import.meta.url));
+await thirdPartyLib(configPath);
+```
 
-Results are merged into a single grouped report with file locations.
+### Options bag for >2 parameters
 
-## Flags
+Functions must have at most 2 parameters. Use an options object for anything beyond that.
 
-- `--fix` — Auto-fix what oxlint can fix, then report remaining violations
-- Positional args — Target paths (default: `./src`)
+```ts
+// Correct
+interface FormatOptions {
+  indent: number;
+  lineWidth: number;
+  quotes: "single" | "double";
+}
+export async function format(input: string, options: FormatOptions): Promise<string> {
+  // ...
+}
+
+// Correct — 2 params is fine
+export async function resolve(specifier: string, base: URL): Promise<URL> {
+  // ...
+}
+```
 
-## Exit Codes
+### Named exports only
 
-- **0** — No errors
-- **1** — Errors found
+Default exports are banned. Every export must be named.
+
+```ts
+// Correct
+export async function createApp(): Promise<App> { /* ... */ }
+export const VERSION = "1.0.0";
+
+// Wrong
+export default function createApp() { /* ... */ }
+```
 
-## Important
+### `import type` for type-only imports
 
-Do not run any of these tools individually. `pnpm run lint` runs them all and gives you a unified view.
+Separate type imports from value imports.
 
-## Opinionated Rules
+```ts
+// Correct
+import type { Config } from "./config.ts";
+import { loadConfig } from "./config.ts";
 
-The oxlint config enforces Bombshell conventions. When writing code for this project, follow these rules proactively — don't wait for the linter to catch them.
+// Wrong
+import { Config, loadConfig } from "./config.ts";
+```
 
-### Paths: Use File URLs, not `node:path`
+### `node:` protocol for builtins
 
-`node:path` and `path` imports are **banned**. Use `URL` for all path manipulation:
+Always use the `node:` prefix when importing Node.js built-in modules.
 
 ```ts
-// Do this
-const file = new URL("./config.json", import.meta.url);
-const child = new URL("./sub/", base);
+// Correct
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+// Wrong
+import { readFile } from "fs/promises";
+```
+
+### Prefer Node 22+ builtins over dependencies
+
+Node 22 ships builtins that replace common npm packages. Use them.
+
+| Instead of | Use |
+|-----------|-----|
+| `glob` / `fast-glob` | `node:fs` with `{ recursive: true }` or `fs.glob` |
+| `dotenv` | `--env-file` flag or `node:process` env loading |
+| `node-fetch` | Global `fetch` |
+| `chalk` / `kleur` | `node:util` `styleText()` |
+| `minimatch` | `node:path` `matchesGlob()` — but remember, use URL-based alternatives where possible |
+
+### `const` over `let`, no `var`
+
+Use `const` by default. Use `let` only when reassignment is necessary. `var` is banned.
 
-// Not this
-import { join } from "node:path";
-const file = join(__dirname, "config.json");
+### Exported functions: `async`, explicit return types, JSDoc
+
+All three are enforced (as warnings) on exported functions:
+
+```ts
+// Correct
+/** Resolves the configuration from the given root. */
+export async function resolveConfig(root: URL): Promise<Config> {
+  // ...
+}
 ```
 
-Use `fileURLToPath()` only at third-party module boundaries that require string paths.
+## Common Mistakes
 
-### No CommonJS
+These are the ranked failure modes. Each shows the wrong pattern and the fix.
 
-`import/no-commonjs` is an error. No `require()`, no `module.exports`, no `exports.foo`.
+### 1. Using `node:path` instead of URL (CRITICAL)
+
+```ts
+// Wrong
+import { join, resolve } from "node:path";
+const config = join(__dirname, "config.json");
+const abs = resolve("./src");
 
-### Imports
+// Correct
+const config = new URL("./config.json", import.meta.url);
+const abs = new URL("./src/", import.meta.url);
+```
+
+### 2. Functions with more than 2 parameters (HIGH)
+
+```ts
+// Wrong
+export async function createServer(port: number, host: string, ssl: boolean): Promise<Server> {
+  // ...
+}
+
+// Correct
+interface ServerOptions {
+  port: number;
+  host: string;
+  ssl: boolean;
+}
+export async function createServer(options: ServerOptions): Promise<Server> {
+  // ...
+}
+```
+
+### 3. Using `console.log` (MEDIUM)
+
+```ts
+// Wrong
+console.log("Server started on port", port);
+
+// Correct
+console.info("Server started on port", port);
+```
+
+Use `console.info` for informational output, `console.warn` for warnings, `console.error` for errors, `console.debug` for debug-level output.
+
+### 4. Using default exports (HIGH)
+
+```ts
+// Wrong
+export default class Router { /* ... */ }
+
+// Correct
+export class Router { /* ... */ }
+```
+
+### 5. Not using `import type` for type-only imports (MEDIUM)
+
+```ts
+// Wrong
+import { SomeInterface } from "./types.ts";
+
+// Correct
+import type { SomeInterface } from "./types.ts";
+```
+
+### 6. Over-commenting obvious code (MEDIUM)
+
+Agents frequently add redundant comments. Do not explain what code does when the code is self-explanatory.
+
+```ts
+// Wrong
+// Create a new URL for the config file
+const config = new URL("./config.json", import.meta.url);
+// Read the file contents
+const contents = await readFile(config, "utf-8");
+
+// Correct
+const config = new URL("./config.json", import.meta.url);
+const contents = await readFile(config, "utf-8");
+```
+
+Comments should explain _why_, not _what_. Use JSDoc on exported APIs.
+
+### 7. Not using bleeding-edge Node builtins (HIGH)
+
+```ts
+// Wrong
+import glob from "fast-glob";
+const files = await glob("src/**/*.ts");
+
+// Correct
+import { glob } from "node:fs/promises";
+const files = await Array.fromAsync(glob("src/**/*.ts"));
+```
+
+### 8. Using generic `Error` (HIGH)
+
+```ts
+// Wrong
+throw new Error("Config file not found");
+throw new TypeError("Expected a string");
+
+// Correct — define project-specific error classes
+class ConfigError extends Error {
+  code: string;
+  constructor(message: string, code: string) {
+    super(message);
+    this.code = code;
+  }
+}
+throw new ConfigError("Config file not found", "CONFIG_NOT_FOUND");
+```
 
-- **No default exports** (`import/no-default-export`) — use named exports
-- **Consistent type imports** (`typescript/consistent-type-imports`) — use `import type` for type-only imports
-- **Prefer `node:` protocol** (`unicorn/prefer-node-protocol`) — `import { readFile } from "node:fs/promises"`, not `"fs/promises"`
+Builtin error constructors (`Error`, `TypeError`, `RangeError`, `ReferenceError`, `SyntaxError`, `URIError`, `EvalError`, `AggregateError`) are all banned. Use structured error classes with codes and metadata.
 
-### Functions
+## Tensions
 
-- **Max 2 parameters** (`max-params`, error) — if a function needs more than 2 parameters, refactor to an options bag
-- **Explicit return types on declarations** (`typescript/explicit-function-return-type`, warn) — expressions are exempt
-- **Exported functions should be async** (`bombshell-dev/exported-function-async`, warn)
-- **Exported functions need JSDoc** (`bombshell-dev/require-export-jsdoc`, warn)
+- **Prototyping speed vs lint strictness**: During early prototyping (see [lifecycle](../lifecycle/SKILL.md)), you may want to move fast. The lint rules still apply -- write correct code from the start rather than fixing lint after the fact.
+- **Opinionated defaults vs explicit config**: The lint config is intentionally strict and not configurable per-project. If a rule is wrong, change it in `oxlintrc.json` upstream.
 
-### General
+## Reference
 
-- **`const` over `let`** (`prefer-const`) — never use `var`
-- **No generic errors** (`bombshell-dev/no-generic-error`) — use specific error types
-- **No `console.log`** (`no-console`, warn) — use `console.info`, `console.warn`, `console.error`, or `console.debug`
+See [references/lint-rules.md](references/lint-rules.md) for the complete rule table covering all oxlint rules, custom plugin rules, and tool configurations.
diff --git a/skills/lint/references/lint-rules.md b/skills/lint/references/lint-rules.md
new file mode 100644
index 0000000..6d8a1d9
--- /dev/null
+++ b/skills/lint/references/lint-rules.md
@@ -0,0 +1,52 @@
+# Lint Rules Reference
+
+Complete rule table for `oxlintrc.json` and custom Bombshell plugin rules.
+
+## oxlint Built-in Rules
+
+| Rule | Severity | Source | Description |
+|------|----------|--------|-------------|
+| `no-restricted-imports` | error | oxlint | Bans `node:path`, `path`, `node:path/posix`, `node:path/win32` |
+| `import/no-commonjs` | error | oxlint/import | No `require()`, `module.exports`, `exports.foo` |
+| `import/no-default-export` | error | oxlint/import | All exports must be named |
+| `unicorn/prefer-node-protocol` | error | oxlint/unicorn | Require `node:` prefix on Node.js builtins |
+| `typescript/consistent-type-imports` | error | oxlint/typescript | Use `import type` for type-only imports |
+| `no-console` | warn | oxlint | Bans `console.log`; allows `console.info`, `warn`, `error`, `debug` |
+| `prefer-const` | error | oxlint | Use `const` when variable is never reassigned |
+| `no-var` | error | oxlint | No `var` declarations |
+| `max-params` | error | oxlint | Max 2 parameters per function |
+| `typescript/explicit-function-return-type` | warn | oxlint/typescript | Function declarations need return types (expressions exempt) |
+| `node/no-path-concat` | error | oxlint/node | No string concatenation with `__dirname`/`__filename` |
+
+## Bombshell Custom Plugin Rules
+
+Defined in `rules/plugin.js`, registered as the `bombshell-dev` plugin.
+
+| Rule | Severity | Description |
+|------|----------|-------------|
+| `bombshell-dev/no-generic-error` | error | No `throw new Error(...)` or other builtin error constructors. Use project-specific error classes. |
+| `bombshell-dev/require-export-jsdoc` | warn | Exported functions and classes must have a `/** ... */` JSDoc comment. |
+| `bombshell-dev/exported-function-async` | warn | Exported functions must use `async`. Adding async later is a breaking change. |
+
+## oxlint Categories
+
+These apply in addition to individual rules:
+
+| Category | Severity |
+|----------|----------|
+| `correctness` | error |
+| `suspicious` | warn |
+
+## Enabled Plugins
+
+`unicorn`, `typescript`, `oxc`, `import`, `node`, plus the custom `bombshell-dev` JS plugin.
+
+## Other Tools in the Pipeline
+
+| Tool | What It Catches |
+|------|----------------|
+| **publint** | Incorrect `package.json` exports, missing types, invalid fields |
+| **knip** | Unused dependencies, devDependencies, exports, types, files |
+| **tsgo** | TypeScript type errors (`--noEmit`) |
+
+These tools have no configurable rules in this project. They run with defaults (publint in strict mode, knip configured in `package.json`).
diff --git a/skills/migrate/SKILL.md b/skills/migrate/SKILL.md
new file mode 100644
index 0000000..ec9e9c1
--- /dev/null
+++ b/skills/migrate/SKILL.md
@@ -0,0 +1,124 @@
+---
+name: migrate
+description: >
+  Migrate existing project to bsh toolchain. Remove prettier, biome, eslint, tsup,
+  unbuild, rollup configs and dependencies. Replace scripts with bsh equivalents.
+  Consolidate to single @bomb.sh/tools devDependency. Migration order: check existing
+  tools, add unimplemented commands, replace 1:1 commands, evaluate remaining, migrate
+  one by one. Use when onboarding a project to the Bombshell ecosystem.
+type: lifecycle
+library: '@bomb.sh/tools'
+library_version: '0.2.8'
+requires:
+  - lifecycle
+sources:
+  - 'bombshell-dev/tools:skills/lifecycle/SKILL.md'
+---
+
+# @bomb.sh/tools — Migration Checklist
+
+Run through each section when migrating a project to the bsh toolchain.
+
+## Step 1: Inventory Existing Tools
+
+Check what the project currently uses:
+- Build: tsup, unbuild, rollup, custom scripts, raw tsc?
+- Lint: eslint, biome, tslint?
+- Format: prettier, biome?
+- Test: vitest, jest, mocha?
+- Type check: tsc directly?
+
+## Step 2: Add @bomb.sh/tools
+
+```sh
+pnpm add -D @bomb.sh/tools
+```
+
+## Step 3: Replace 1:1 Commands
+
+For each tool that maps directly:
+
+| Old Tool | New Command | Notes |
+|----------|------------|-------|
+| vitest | pnpm run test | Likely already compatible |
+| prettier / biome format | pnpm run format | oxfmt replaces both |
+| eslint / biome lint | pnpm run lint | oxlint + publint + knip + tsgo |
+| tsup / unbuild / rollup | pnpm run build | tsdown with ESM defaults |
+| tsc --noEmit | pnpm run lint | Type checking included in lint |
+
+## Step 4: Add Unimplemented Commands
+
+If the project didn't have lint or format before, add them now:
+
+Update package.json scripts:
+```json
+{
+  "scripts": {
+    "build": "bsh build",
+    "dev": "bsh dev",
+    "format": "bsh format",
+    "lint": "bsh lint",
+    "test": "bsh test"
+  }
+}
+```
+
+## Step 5: Remove Old Config Files
+
+Delete these if present:
+- .prettierrc, .prettierrc.json, .prettierrc.yaml, prettier.config.js
+- biome.json, biome.jsonc
+- .eslintrc, .eslintrc.json, .eslintrc.yaml, eslint.config.js, eslint.config.mjs
+- rollup.config.js, rollup.config.mjs
+- tsup.config.ts, tsup.config.js
+- unbuild.config.ts, build.config.ts
+
+## Step 6: Remove Old Dependencies
+
+Remove from devDependencies:
+- prettier, eslint, biome, @biomejs/biome
+- tsup, unbuild, rollup and rollup plugins
+- eslint plugins and configs
+- prettier plugins
+- Any TypeScript runners: tsx, ts-node, esbuild-register
+
+## Step 7: Move Tests to Colocated Pattern
+
+If tests are in __tests__/ or test/ directories, move them next to source:
+- __tests__/schema.test.ts → src/schema.test.ts (next to src/schema.ts)
+- Use .test.ts for runtime, .test-d.ts for type-level
+
+## Step 8: Verify
+
+Run through the full lifecycle to confirm migration:
+```sh
+pnpm run test      # Tests still pass
+pnpm run lint      # No unexpected violations
+pnpm run format    # Code formatted correctly
+pnpm run build     # Package builds cleanly
+pnpm run test      # Final confirmation
+```
+
+## Common Mistakes
+
+1. **HIGH: Leaving old tool configs alongside bsh**
+   - Wrong: .prettierrc, biome.json still exist alongside @bomb.sh/tools
+   - Correct: Remove all old config files — bsh provides all configuration
+   - Old configs can shadow or conflict with bsh defaults.
+
+2. **HIGH: Keeping old tool-specific scripts**
+   - Wrong: `"lint": "eslint . && tsc --noEmit"`
+   - Correct: `"lint": "bsh lint"`
+   - Old scripts bypass the unified bsh pipeline.
+
+3. **MEDIUM: Not moving tests to colocated pattern**
+   - Wrong: Tests remain in __tests__/ directory after migration
+   - Correct: Tests colocated next to source files as .test.ts
+   - Bombshell convention requires colocated tests for readability.
+
+## Cross-references
+
+- See also: lifecycle/SKILL.md — After migration, adopt the bsh lifecycle workflow
+- See also: lint/SKILL.md — Understanding lint rules helps during migration
+
+Source: maintainer interview
diff --git a/skills/test/SKILL.md b/skills/test/SKILL.md
index 56c8429..9e2fd1b 100644
--- a/skills/test/SKILL.md
+++ b/skills/test/SKILL.md
@@ -1,81 +1,114 @@
 ---
 name: test
-description: "Use when running tests, writing new tests, or debugging test failures."
+description: >
+  Vitest test runner with colocated .test.ts files and createFixture utility from
+  @bomb.sh/tools/test-utils. Covers .test-d.ts type-level tests, inline fixture
+  declarations, fixture API (root, resolve, text, json, write, isFile, isDirectory,
+  list, cleanup). Use when writing or running tests in Bombshell projects.
+metadata:
+  type: core
+  library: '@bomb.sh/tools'
+  library_version: '0.2.8'
+  requires:
+    - lifecycle
+  sources:
+    - 'bombshell-dev/tools:src/commands/test.ts'
+    - 'bombshell-dev/tools:src/test-utils.ts'
 ---
 
 # Test
 
-Runs the test suite using vitest in non-watch mode.
+Vitest test runner with colocated test files and a filesystem fixture utility.
 
-## Usage
+## Setup
+
+Run the full test suite:
 
 ```sh
 pnpm run test
 ```
 
+Filter to a specific file:
+
+```sh
+pnpm run test -- src/commands/build.test.ts
+```
+
+Pass any vitest flags after `--`:
+
+```sh
+pnpm run test -- --reporter=verbose
+```
+
 ## Test File Conventions
 
-- **Colocate tests with source** — next to the code they test, never in `__tests__/` or `test/`
-- **`.test.ts`** suffix for runtime tests
-- **`.test-d.ts`** suffix for type-level tests (compile-time assertions only)
+Tests are colocated next to the source they test. Never use `__tests__/`, `test/`, or any other separate directory.
+
+- **`.test.ts`** — runtime tests
+- **`.test-d.ts`** — type-level tests (compile-time assertions only)
 
 ```
 src/
+  commands/
+    build.ts
+    build.test.ts
   framework/
     schema.ts
     schema.test.ts
     params.ts
     params.test-d.ts
+  test-utils.ts
+  test-utils.test.ts
 ```
 
-## How It Works
+## Core Patterns
 
-`pnpm run test` runs `bsh test` which calls `vitest run` (single run, no watch).
+### createFixture
 
-## Filtering
-
-Pass arguments through to vitest:
-
-```sh
-pnpm run test -- src/commands/build.test.ts   # Run specific test file
-pnpm run test -- --reporter=verbose            # Change reporter
-```
-
-## Test Utilities
-
-`@bomb.sh/tools/test-utils` exports `createFixture` for filesystem-based tests.
+Creates a temporary directory from an inline file tree. Returns a `Fixture` with filesystem methods scoped to that directory. Cleanup runs automatically via `onTestFinished`.
 
 ```ts
+import { describe, it, expect } from "vitest";
 import { createFixture } from "@bomb.sh/tools/test-utils";
 
-const fixture = await createFixture({
-  "hello.txt": "hello world",
-  "package.json": { name: "test", version: "1.0.0" },
-  "icon.png": Buffer.from([0x89, 0x50]),
-  src: {
-    "index.ts": "export default 1",
-  },
-  "link.txt": ({ symlink }) => symlink("./hello.txt"),
-  "info.txt": ({ importMeta }) => `Root: ${importMeta.url}`,
+describe("my-feature", () => {
+  it("reads files from the fixture", async () => {
+    const fixture = await createFixture({
+      "hello.txt": "hello world",
+      "package.json": { name: "test", version: "1.0.0" },
+      "icon.png": Buffer.from([0x89, 0x50]),
+      src: {
+        "index.ts": "export default 1",
+      },
+      "link.txt": ({ symlink }) => symlink("./hello.txt"),
+      "info.txt": ({ importMeta }) => `Root: ${importMeta.url}`,
+    });
+
+    expect(await fixture.text("hello.txt")).toBe("hello world");
+    expect(await fixture.json("package.json")).toEqual({
+      name: "test",
+      version: "1.0.0",
+    });
+    expect(await fixture.isFile("src/index.ts")).toBe(true);
+  });
 });
 ```
 
 ### Fixture API
 
-- `fixture.root` — fixture root as a `file://` URL
-- `fixture.resolve(...segments)` — resolve a relative path within the fixture
-- `fixture.text(file)` — read file as string
-- `fixture.json(file)` — read and parse JSON file
-- `fixture.write(file, content)` — write a file
-- `fixture.isFile(file)` / `fixture.isDirectory(dir)` — check existence
-- `fixture.list(dir)` — list directory contents
-- `fixture.cleanup()` — delete fixture (also runs automatically via `onTestFinished`)
-
-All `hfs` methods are available, scoped to the fixture root.
-
-### Fixtures Are Always Inline
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `fixture.root` | `URL` | Fixture root as a `file://` URL |
+| `fixture.resolve(...segments)` | `URL` | Resolve a relative path within the fixture root |
+| `fixture.text(file)` | `Promise<string \| undefined>` | Read file contents as a string |
+| `fixture.json(file)` | `Promise<unknown \| undefined>` | Read and parse a JSON file |
+| `fixture.write(file, content)` | `Promise<void>` | Write a file to the fixture |
+| `fixture.isFile(file)` | `Promise<boolean>` | Check if path is a file |
+| `fixture.isDirectory(dir)` | `Promise<boolean>` | Check if path is a directory |
+| `fixture.list(dir)` | `Promise<Iterable>` | List directory contents |
+| `fixture.cleanup()` | `Promise<void>` | Delete the fixture directory (auto-runs via `onTestFinished`) |
 
-Never extract fixture trees into shared variables, helper files, or beforeEach blocks. Each test should declare its own fixture inline so the test is self-contained and readable.
+All [`hfs`](https://github.com/humanwhocodes/humanfs) methods are available on the fixture, scoped to the fixture root. The table above covers the most common ones.
 
 ### File Tree Values
 
@@ -84,5 +117,153 @@ Never extract fixture trees into shared variables, helper files, or beforeEach b
 | `string` | Written as-is |
 | `object` / `array` | Auto-serialized as JSON for `.json` keys |
 | `Buffer` | Written as binary |
-| Nested object (no `.` in key) | Creates a subdirectory |
+| Nested object (key has no `.`) | Creates a subdirectory |
 | `(ctx) => ...` | Dynamic — receives `importMeta` and `symlink` helpers |
+
+The `importMeta` context provides:
+
+- `importMeta.url` — fixture root as a `file://` URL string
+- `importMeta.filename` — absolute filesystem path to the fixture root
+- `importMeta.dirname` — same as `filename` (root is a directory)
+- `importMeta.resolve(path)` — resolve a relative path against the fixture root
+
+The `symlink` helper creates a symbolic link:
+
+```ts
+{
+  "target.txt": "real content",
+  "link.txt": ({ symlink }) => symlink("./target.txt"),
+}
+```
+
+### Type-Level Tests
+
+Files ending in `.test-d.ts` run compile-time type assertions using `expectTypeOf` from vitest. No runtime code executes — these tests verify that types resolve correctly.
+
+```ts
+import { describe, expectTypeOf, test } from "vitest";
+import type { PathParams } from "./params.ts";
+
+describe("PathParams", () => {
+  test("extracts single param", () => {
+    expectTypeOf({} as PathParams<"/users/[id]">).toMatchTypeOf<{
+      id: string;
+    }>();
+  });
+
+  test("extracts spread params", () => {
+    expectTypeOf(
+      {} as PathParams<"/files/[...path]">
+    ).toMatchTypeOf<{ path: string[] }>();
+  });
+
+  test("no params returns empty object", () => {
+    expectTypeOf({} as PathParams<"/static/page">).toMatchTypeOf<
+      Record<string, never>
+    >();
+  });
+});
+```
+
+## Common Mistakes
+
+### HIGH: Placing tests in a separate directory
+
+Tests must be colocated next to the source file they test.
+
+```
+# Wrong
+__tests__/
+  schema.test.ts
+src/
+  schema.ts
+
+# Wrong
+test/
+  schema.test.ts
+src/
+  schema.ts
+
+# Correct
+src/
+  schema.ts
+  schema.test.ts
+```
+
+### MEDIUM: Extracting fixtures into shared variables
+
+Fixtures must be declared inline in each test. Shared fixtures make tests coupled and hard to read.
+
+```ts
+// Wrong — shared fixture across tests
+const sharedTree = {
+  "package.json": { name: "test", version: "1.0.0" },
+  "src/index.ts": "export default 1",
+};
+
+it("test a", async () => {
+  const fixture = await createFixture(sharedTree);
+  // ...
+});
+
+it("test b", async () => {
+  const fixture = await createFixture(sharedTree);
+  // ...
+});
+
+// Correct — each test declares its own fixture
+it("test a", async () => {
+  const fixture = await createFixture({
+    "package.json": { name: "test", version: "1.0.0" },
+  });
+  // ...
+});
+
+it("test b", async () => {
+  const fixture = await createFixture({
+    "src/index.ts": "export default 1",
+  });
+  // ...
+});
+```
+
+### HIGH: Testing implementation details instead of behavior
+
+Write tests that verify observable outputs and side effects, not internal function calls, mock counts, or private state.
+
+```ts
+// Wrong — testing internal implementation
+it("calls internal parser three times", async () => {
+  const spy = vi.spyOn(internals, "parse");
+  await processConfig(input);
+  expect(spy).toHaveBeenCalledTimes(3);
+});
+
+// Correct — testing observable behavior
+it("produces valid output from config", async () => {
+  const fixture = await createFixture({
+    "config.json": { entry: "src/index.ts" },
+  });
+  const result = await processConfig(fixture.root);
+  expect(result.entry).toBe("src/index.ts");
+});
+```
+
+### HIGH: Running vitest directly
+
+Always use `pnpm run test`. The `bsh test` wrapper configures vitest correctly.
+
+```sh
+# Wrong
+pnpm exec vitest run
+npx vitest
+vitest run
+
+# Correct
+pnpm run test
+pnpm run test -- src/commands/build.test.ts
+```
+
+## Cross-References
+
+See also: **lint/SKILL.md** — Tests must follow the same coding conventions (no `node:path`, consistent type imports, named exports, etc.).

From 8c66a3a3f6a231f80c476ebce649c760fed88300 Mon Sep 17 00:00:00 2001
From: Nate Moore <nate@natemoo.re>
Date: Wed, 25 Mar 2026 23:09:06 -0400
Subject: [PATCH 7/8] feat(skills): update instructions

---
 .changeset/thirty-jeans-retire.md | 7 +++++++
 README.md                         | 4 ++++
 2 files changed, 11 insertions(+)
 create mode 100644 .changeset/thirty-jeans-retire.md

diff --git a/.changeset/thirty-jeans-retire.md b/.changeset/thirty-jeans-retire.md
new file mode 100644
index 0000000..ebd57b8
--- /dev/null
+++ b/.changeset/thirty-jeans-retire.md
@@ -0,0 +1,7 @@
+---
+"@bomb.sh/tools": minor
+---
+
+Adds TanStack Intent skills for coding agents. Eight skills cover the full `bsh` toolchain — lifecycle, lint, build, test, format, dev, init, and a new migration checklist for onboarding existing projects.
+
+Skills are discoverable by running `npx @tanstack/intent@latest install`.
diff --git a/README.md b/README.md
index db29b90..9edf6a9 100644
--- a/README.md
+++ b/README.md
@@ -11,3 +11,7 @@ If you'd like to use this package for your own projects, please consider forking
 - `bsh format` command, using [`oxfmt`](https://oxc.rs/docs/guide/usage/formatter)
 - `bsh lint` command, using [`oxlint`](https://oxc.rs/docs/guide/usage/linter), [`publint`](https://publint.dev/), [`knip`](https://knip.dev), [`tsgo`](https://npmx.dev/@typescript/native-preview)
 - shared `tsconfig.json` file
+
+## Agent Skills
+
+If you use an AI coding agent, run `pnpm add -D @bomb.sh/tools` then have your agent run `pnpm dlx @tanstack/intent@latest install` to load project-specific skills for `@bomb.sh/tools`.

From d3b05a01d10d86280c0af1ff589e071a2d640381 Mon Sep 17 00:00:00 2001
From: Nate Moore <natemoo-re@users.noreply.github.com>
Date: Wed, 25 Mar 2026 23:12:14 -0400
Subject: [PATCH 8/8] Revise skills description and installation steps

Updated the description for coding agent skills and installation instructions.
---
 .changeset/thirty-jeans-retire.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.changeset/thirty-jeans-retire.md b/.changeset/thirty-jeans-retire.md
index ebd57b8..21d2396 100644
--- a/.changeset/thirty-jeans-retire.md
+++ b/.changeset/thirty-jeans-retire.md
@@ -2,6 +2,6 @@
 "@bomb.sh/tools": minor
 ---
 
-Adds TanStack Intent skills for coding agents. Eight skills cover the full `bsh` toolchain — lifecycle, lint, build, test, format, dev, init, and a new migration checklist for onboarding existing projects.
+Adds skills for coding agents. Eight skills cover the full `bsh` toolchain — lifecycle, lint, build, test, format, dev, init, and migration for onboarding an existing project.
 
-Skills are discoverable by running `npx @tanstack/intent@latest install`.
+If you use an AI coding agent, run `pnpm add -D @bomb.sh/tools` then have your agent run `pnpm dlx @tanstack/intent@latest install` to load project-specific skills for `@bomb.sh/tools`.