@frontmcp/skills 1.2.0 → 1.3.0

package/catalog/frontmcp-setup/references/frontmcp-skills-usage.md

@@ -61,13 +61,33 @@ frontmcp skills install frontmcp-development --provider claude
 
 # Install a skill for Codex
 frontmcp skills install frontmcp-setup --provider codex
+
+# Bulk install — every skill in a category, all at once
+frontmcp skills install --category development --provider claude
+
+# Export a skill as a Cursor rule file (for skills-unaware IDEs)
+frontmcp skills export --name frontmcp-development --target cursor
+
+# Publish a skill to the Smithery marketplace
+frontmcp skills publish frontmcp-development --target smithery --dry-run
 ```
 
 ## CLI Commands
 
+The `frontmcp skills` command tree currently has six subcommands:
+`search`, `list`, `install`, `read`, `export`, `publish`.
+
+<!-- AUTOGEN:skills-cli:start -->
+
 ### `frontmcp skills search <query>`
 
-Semantic search through the catalog using weighted text matching (description 3x, tags 2x, name 1x):
+Semantic search through the catalog using weighted text matching (description 3x, tags 2x, name 1x).
+
+| Flag                  | Description               | Default |
+| --------------------- | ------------------------- | ------- |
+| `-n, --limit <count>` | Maximum results to return | `10`    |
+| `-t, --tag <tag>`     | Filter by tag             | —       |
+| `-c, --category <c>`  | Filter by category        | —       |
 
 ```bash
 frontmcp skills search "authentication oauth"
@@ -77,7 +97,13 @@ frontmcp skills search "plugin hooks" --tag middleware --limit 5
 
 ### `frontmcp skills list`
 
-List all skills, optionally filtered:
+List all skills, optionally filtered.
+
+| Flag                  | Description                                                | Default |
+| --------------------- | ---------------------------------------------------------- | ------- |
+| `-c, --category <c>`  | Filter by category                                         | —       |
+| `-t, --tag <tag>`     | Filter by tag                                              | —       |
+| `-b, --bundle <name>` | Filter by bundle preset (`recommended`, `minimal`, `full`) | —       |
 
 ```bash
 frontmcp skills list                          # All skills
@@ -86,9 +112,14 @@ frontmcp skills list --tag redis              # Skills tagged with redis
 frontmcp skills list --bundle recommended     # Recommended bundle
 ```
 
-### `frontmcp skills read <name> [reference]`
+### `frontmcp skills read <nameOrPath> [reference]`
+
+Read a skill's main SKILL.md, a specific reference, or list available references.
 
-Read a skill's main SKILL.md, a specific reference, or list available references:
+| Flag                     | Description                                                        | Default |
+| ------------------------ | ------------------------------------------------------------------ | ------- |
+| `--refs`                 | List all available references for the skill                        | `false` |
+| `--examples [reference]` | List examples for the skill, optionally filtered by reference name | —       |
 
 ```bash
 # Read main skill content
@@ -97,6 +128,10 @@ frontmcp skills read frontmcp-development
 # List all references for a skill
 frontmcp skills read frontmcp-development --refs
 
+# List every example bundled with the skill (or filter by reference)
+frontmcp skills read frontmcp-development --examples
+frontmcp skills read frontmcp-development --examples create-tool
+
 # Read a specific reference by name
 frontmcp skills read frontmcp-development create-tool
 
@@ -105,19 +140,221 @@ frontmcp skills read frontmcp-development:references/create-tool.md
 frontmcp skills read frontmcp-development:scripts/setup.sh
 ```
 
-### `frontmcp skills install <name>`
+### `frontmcp skills install [name]`
+
+Install one or many skills to a provider-specific directory. `[name]` is
+optional when one of `--all`, `--tag`, or `--category` is supplied —
+those flags select skills in bulk.
 
-Copy a skill to a provider-specific directory:
+| Flag                        | Description                                                                                            | Default  |
+| --------------------------- | ------------------------------------------------------------------------------------------------------ | -------- |
+| `-p, --provider <provider>` | Target provider: `claude` or `codex`                                                                   | `claude` |
+| `-d, --dir <directory>`     | Custom install directory (overrides provider default)                                                  | —        |
+| `-a, --all`                 | Install **every** skill in the catalog (or every `@Skill` entry when `--from-*` is set)                | `false`  |
+| `-t, --tag <tag>`           | Install every skill matching a tag (catalog only)                                                      | —        |
+| `-c, --category <c>`        | Install every skill in a category (catalog only)                                                       | —        |
+| `--from-entry <path>`       | Install `@Skill` entries discovered in a **local project entry file** instead of the framework catalog | —        |
+| `--from-package <pkg>`      | Install `@Skill` entries discovered in a **published package's** main entry                            | —        |
 
 ```bash
-# Claude Code — installs to .claude/skills/<name>/SKILL.md
-frontmcp skills install frontmcp-development --provider claude
+# Single-skill install (positional name)
+frontmcp skills install frontmcp-development --provider claude   # → .claude/skills/<name>/SKILL.md
+frontmcp skills install frontmcp-setup --provider codex          # → .codex/skills/<name>/SKILL.md
+frontmcp skills install frontmcp-guides --dir ./my-skills        # custom destination
+
+# Bulk install — see "Bulk install patterns" below for the full decision matrix
+frontmcp skills install --all --provider claude
+frontmcp skills install --category development --provider claude
+frontmcp skills install --tag middleware --provider codex
+
+# Install a project's own @Skill-decorated entries (see "Installing project-defined skills")
+frontmcp skills install --from-entry src/main.ts --all -p claude
+frontmcp skills install --from-package my-frontmcp-server my-skill -p claude
+```
 
-# Codex — installs to .codex/skills/<name>/SKILL.md
-frontmcp skills install frontmcp-setup --provider codex
+### `frontmcp skills export`
+
+Convert one or many catalog skills into a rule file for IDEs that
+**don't** speak the skills protocol (Cursor, Windsurf, Copilot). The
+emitted file lives in the current directory by default.
+
+| Flag                    | Description                                           | Default  |
+| ----------------------- | ----------------------------------------------------- | -------- |
+| `-t, --target <target>` | Target IDE: `cursor`, `windsurf`, or `copilot`        | `cursor` |
+| `-n, --name <name>`     | Skill name to export (required unless `--all` is set) | —        |
+| `-a, --all`             | Export **every** skill in the catalog                 | `false`  |
+| `-d, --out <directory>` | Output directory                                      | `cwd`    |
+
+```bash
+frontmcp skills export --name frontmcp-development --target cursor
+frontmcp skills export --name frontmcp-setup --target windsurf
+frontmcp skills export --all --target copilot --out ./.github
+```
+
+See **Other AI clients (Cursor / Windsurf / Copilot)** below for the
+output-filename mapping per target.
+
+### `frontmcp skills publish <name>`
+
+Publish a skill to a public marketplace (Smithery or Glama).
+
+| Flag                    | Description                                                      | Default    |
+| ----------------------- | ---------------------------------------------------------------- | ---------- |
+| `-t, --target <target>` | Marketplace: `smithery` or `glama`                               | `smithery` |
+| `--token <token>`       | API token (defaults to `SMITHERY_TOKEN` / `GLAMA_TOKEN` env var) | env        |
+| `--repository <url>`    | Repository URL to advertise on the marketplace                   | —          |
+| `--dry-run`             | Print the payload + endpoint without submitting                  | `false`    |
+
+```bash
+# Dry run against Smithery (no submission)
+frontmcp skills publish frontmcp-development --dry-run
+
+# Real publish to Glama with a custom repo URL + env-var token
+GLAMA_TOKEN=xxx frontmcp skills publish frontmcp-development \
+  --target glama --repository https://github.com/me/my-frontmcp-server
+```
+
+<!-- AUTOGEN:skills-cli:end -->
+
+## Bulk install patterns
+
+`frontmcp skills install` accepts a single `[name]` OR one of the bulk
+selectors. They are mutually exclusive — pass exactly one. The decision
+matrix:
+
+| Goal                                                  | Command                                            |
+| ----------------------------------------------------- | -------------------------------------------------- |
+| Install one specific skill                            | `frontmcp skills install <name> -p claude`         |
+| Install every skill in the catalog                    | `frontmcp skills install --all -p claude`          |
+| Install all skills in a category (e.g. `development`) | `frontmcp skills install -c development -p claude` |
+| Install all skills with a tag (e.g. `middleware`)     | `frontmcp skills install -t middleware -p codex`   |
+| Install all skills to a non-default directory         | `frontmcp skills install --all -d ./custom-skills` |
+
+Examples:
+
+```bash
+# Onboard a new repo: install everything for Claude Code
+frontmcp skills install --all -p claude
+
+# Scaffold a tools-focused project: only the development category
+frontmcp skills install -c development -p claude
+
+# Cross-IDE setup: install middleware skills into a Codex project
+frontmcp skills install -t middleware -p codex
+
+# Mono-repo with a shared skills folder
+frontmcp skills install --all -d ./shared/.claude/skills
+```
+
+> **Heads up:** `--all` / `--tag` / `--category` make `[name]` optional. Pass
+> exactly one bulk selector OR a `[name]`; combining a positional name with a
+> bulk flag is rejected.
+
+## Installing project-defined skills (`@Skill`)
+
+The same `frontmcp skills install` command can install **your project's
+own** `@Skill`-decorated entries — not just the framework catalog. Use
+this when you ship a FrontMCP server that registers skills (via the
+`@Skill` decorator or the `skill()` helper — see `create-skill`) and
+want end users to drop those skills onto Claude Code's filesystem.
+
+| Flag                   | When to use it                                                                                |
+| ---------------------- | --------------------------------------------------------------------------------------------- |
+| `--from-entry <path>`  | Resolve `@Skill` entries from a local entry file (`src/main.ts`, etc.) in the current project |
+| `--from-package <pkg>` | Resolve `@Skill` entries from an installed package's main entry (works with `npx` workflows)  |
+
+The command bundles the entry once via esbuild, boots the SDK with the
+same in-memory client that `frontmcp build` uses, and enumerates every
+`@Skill` entry. Each entry's instructions file (and any `references/` /
+`examples/` / `scripts/` / `assets/` resource directories) is copied
+under `.claude/skills/<skill-name>/`. If the source instructions file
+has no YAML frontmatter, the CLI prepends one synthesized from the
+`@Skill` decorator metadata (`name`, `description`, `tags`, `license`)
+so Claude Code's filesystem loader picks the skill up.
+
+```bash
+# From a project checkout: install one named skill
+frontmcp skills install example-project --from-entry src/main.ts -p claude
+
+# Install every @Skill the project exposes
+frontmcp skills install --from-entry src/main.ts --all -p claude
+
+# From a published package the user has installed:
+frontmcp skills install --from-package my-frontmcp-server --all -p claude
+npx my-frontmcp-server # ... once installed, skills resolve through `my-frontmcp-server`'s main entry
+frontmcp skills install --from-package my-frontmcp-server example-project -p claude
+```
+
+Selectors and constraints:
 
-# Custom directory
-frontmcp skills install frontmcp-guides --dir ./my-skills
+- Pass **either** `<name>` **or** `--all`. `--tag` / `--category` are
+  catalog-only and are rejected when `--from-entry` / `--from-package` is
+  set — the project's `@Skill` list is the authoritative source.
+- `--from-entry` and `--from-package` are mutually exclusive.
+- The CLAUDE.md auto-generated `<!-- frontmcp:skills -->` block lists
+  every installed skill in `.claude/skills/`, catalog **and**
+  project-defined together. Re-running install keeps the block coherent.
+
+> **Tip:** This is the lightest path for shipping a project's own skills.
+> If you also want to ship slash commands, environment hints, and a
+> `.claude-plugin/plugin.json` manifest in one shot, use the per-bin
+> `<bin> install -p claude` (see `frontmcp-deployment`) — it wraps the
+> same enumeration plus the rest of the plugin surface.
+
+## Other AI clients (Cursor / Windsurf / Copilot)
+
+For IDEs that don't natively load `SKILL.md` files, `frontmcp skills
+export` converts a skill into the target IDE's native rule format and
+writes it into the current directory (or `--out <dir>`).
+
+| Target     | Output path (per skill, relative to `--out` / cwd) | Loaded by      |
+| ---------- | -------------------------------------------------- | -------------- |
+| `cursor`   | `.cursor/rules/<skill>.mdc`                        | Cursor         |
+| `windsurf` | `.windsurfrules` (single file)                     | Windsurf       |
+| `copilot`  | `.github/instructions/<skill>.md`                  | GitHub Copilot |
+
+```bash
+# Cursor: export one skill → .cursor/rules/frontmcp-development.mdc
+frontmcp skills export --name frontmcp-development --target cursor
+
+# Windsurf: export every skill into a single .windsurfrules in the cwd
+frontmcp skills export --all --target windsurf
+
+# Copilot: export every skill, one file per skill, under .github/instructions/
+frontmcp skills export --all --target copilot
+```
+
+> Today `--provider` on `install` accepts `claude` and `codex` only.
+> Cursor / Windsurf / Copilot integration goes through `export` instead
+> because those clients consume rule files, not skill packages.
+
+## Publishing to marketplaces
+
+`frontmcp skills publish <name>` ships a skill to a public catalog so
+other developers can discover and install it.
+
+| Target     | Marketplace           | Token env var    |
+| ---------- | --------------------- | ---------------- |
+| `smithery` | <https://smithery.ai> | `SMITHERY_TOKEN` |
+| `glama`    | <https://glama.ai>    | `GLAMA_TOKEN`    |
+
+The CLI reads the token from the matching env var by default; override
+with `--token <value>`. Use `--dry-run` to inspect the request payload
+before submitting.
+
+```bash
+# Inspect the request without sending it
+frontmcp skills publish frontmcp-development --target smithery --dry-run
+
+# Publish to Smithery with a repo link (token from SMITHERY_TOKEN env)
+SMITHERY_TOKEN=sk_xxx frontmcp skills publish frontmcp-development \
+  --target smithery \
+  --repository https://github.com/me/my-frontmcp-server
+
+# Publish to Glama with an explicit token
+frontmcp skills publish frontmcp-development \
+  --target glama \
+  --token "$GLAMA_TOKEN"
 ```
 
 ## Two Approaches: Static vs Dynamic
@@ -240,13 +477,17 @@ frontmcp skills list --category guides       # End-to-end examples and best prac
 
 ## Common Patterns
 
-| Pattern                     | Correct                                                                   | Incorrect                                       | Why                                                                                                    |
-| --------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| Installing a skill          | `frontmcp skills install frontmcp-development --provider claude`          | `cp node_modules/.../SKILL.md .claude/skills/`  | The CLI handles directory creation, naming, and reference files automatically                          |
-| Searching skills            | `frontmcp skills search "oauth authentication"`                           | `frontmcp skills list \| grep oauth`            | Search uses weighted text matching (description 3x, tags 2x) for better relevance                      |
-| Choosing delivery mode      | Install 2-4 core skills statically; search the rest on demand             | Install every skill statically into the project | Static skills consume tokens on every agent invocation; keep the set small                             |
-| Updating an installed skill | `frontmcp skills install frontmcp-development --provider claude` (re-run) | Manually editing the installed SKILL.md file    | Re-installing overwrites with the catalog bundled in the installed CLI version and preserves structure |
-| Filtering by category       | `frontmcp skills list --category deployment`                              | `frontmcp skills search "deployment"`           | `--category` uses the manifest taxonomy; search is for free-text queries                               |
+| Pattern                       | Correct                                                                    | Incorrect                                                  | Why                                                                                                    |
+| ----------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| Installing a skill            | `frontmcp skills install frontmcp-development --provider claude`           | `cp node_modules/.../SKILL.md .claude/skills/`             | The CLI handles directory creation, naming, and reference files automatically                          |
+| Bulk install (entire catalog) | `frontmcp skills install --all --provider claude`                          | Loop over `frontmcp skills install <name>` per skill name  | `--all` resolves the manifest in a single pass and writes consistently into the provider directory     |
+| Bulk install (subset)         | `frontmcp skills install --category development --provider claude`         | `frontmcp skills install --all` followed by manual cleanup | `--category`/`--tag` filter at install time so you only ship the skills you need                       |
+| Searching skills              | `frontmcp skills search "oauth authentication"`                            | `frontmcp skills list \| grep oauth`                       | Search uses weighted text matching (description 3x, tags 2x) for better relevance                      |
+| Choosing delivery mode        | Install 2-4 core skills statically; search the rest on demand              | Install every skill statically into the project            | Static skills consume tokens on every agent invocation; keep the set small                             |
+| Updating an installed skill   | `frontmcp skills install frontmcp-development --provider claude` (re-run)  | Manually editing the installed SKILL.md file               | Re-installing overwrites with the catalog bundled in the installed CLI version and preserves structure |
+| Filtering by category         | `frontmcp skills list --category deployment`                               | `frontmcp skills search "deployment"`                      | `--category` uses the manifest taxonomy; search is for free-text queries                               |
+| Skills-unaware IDE (Cursor)   | `frontmcp skills export --name <skill> --target cursor`                    | `frontmcp skills install <skill> --provider cursor`        | Cursor / Windsurf / Copilot consume rule files; `install` only writes `SKILL.md` packages              |
+| Publishing                    | `frontmcp skills publish <name> --dry-run` first, then without `--dry-run` | Submitting directly without inspecting the payload         | `--dry-run` prints the exact endpoint + body so you can audit before submitting credentials            |
 
 ## Verification Checklist
 

package/catalog/frontmcp-setup/references/setup-project.md

@@ -375,6 +375,35 @@ Then start the server normally:
 frontmcp dev
 ```
 
+### Port conflict handling
+
+`frontmcp dev` performs a pre-flight TCP probe before spawning `tsx --watch`.
+If the port is already in use, the command exits with a one-line message
+listing remediation options — never a raw `EADDRINUSE` stack trace
+(issue #398).
+
+| Flag              | Behaviour                                                                     |
+| ----------------- | ----------------------------------------------------------------------------- |
+| `--port <n>`      | Bind the dev server to TCP port `<n>` (sets `PORT=<n>` in the child's env).   |
+| `--auto-port`     | If the requested port is busy, walk forward to the next free port.            |
+| `--show-conflict` | On EADDRINUSE, run `lsof` (POSIX) to print which process is holding the port. |
+
+```bash
+# Pick a different port for this run
+frontmcp dev --port 3100
+
+# Let the CLI pick the next free port automatically
+frontmcp dev --auto-port
+
+# Show what's holding the port
+frontmcp dev --show-conflict
+```
+
+> The `PORT` env var (or `--port`) only takes effect when your `@FrontMcp`
+> metadata reads it via `Number(process.env.PORT) || 3000`. Hard-coding
+> `http.port: 4000` in metadata makes the child bind to 4000 regardless of
+> `--port`/`PORT`, so the pre-flight probe becomes advisory only.
+
 Test with curl:
 
 ```bash

package/catalog/frontmcp-setup/references/setup-sqlite.md

@@ -57,8 +57,14 @@ The `sqlite` field in the `@FrontMcp` decorator accepts a `SqliteOptionsInput` o
 
 ```typescript
 interface SqliteOptionsInput {
-  /** Path to the .sqlite database file (required) */
-  path: string;
+  /**
+   * Path to the .sqlite database file. **Optional** — when omitted the SDK
+   * picks a sensible default at startup:
+   *   - dev + node + non-CLI → `<projectRoot>/dist/sessions.sqlite`
+   *   - prod OR CLI mode    → `~/.{info.name}/sessions.sqlite`
+   * Set this to override either default (e.g. `./.data/sessions.sqlite`).
+   */
+  path?: string;
 
   /** Enable WAL mode for better read concurrency (default: true) */
   walMode?: boolean;
@@ -74,6 +80,29 @@ interface SqliteOptionsInput {
 }
 ```
 
+### Default-path policy (issue #401)
+
+If you set `sqlite: {}` without a `path`, the SDK resolves it as follows:
+
+| Environment                                              | Resolved path                        |
+| -------------------------------------------------------- | ------------------------------------ |
+| `frontmcp dev` (NODE_ENV=development, node, no CLI mode) | `<projectRoot>/dist/sessions.sqlite` |
+| Built CLI binary (`cliMode`)                             | `~/.{info.name}/sessions.sqlite`     |
+| Production node server (`NODE_ENV=production`)           | `~/.{info.name}/sessions.sqlite`     |
+
+The home-directory namespace is **derived from your `info.name`**, so two
+frontmcp apps from different projects never share the same database
+(e.g. `my-server` → `~/.my-server/sessions.sqlite`,
+`other-app` → `~/.other-app/sessions.sqlite`). If `info.name` is unset or
+sanitization strips it to empty, the fallback is `~/.frontmcp/`.
+
+The SDK also `mkdir -p`'s the parent directory at startup, so you don't
+need to pre-create it. The resolved path is logged at INFO level:
+
+```text
+[FrontMcp] No `sqlite.path` set — using default { path: '/Users/you/.my-server/sessions.sqlite' }
+```
+
 ### Basic SQLite setup
 
 Update the `@FrontMcp` decorator in `src/main.ts`:
@@ -98,12 +127,12 @@ export default class Server {}
 
 Configuration reference:
 
-| Option                 | Type                 | Default     | Description                                         |
-| ---------------------- | -------------------- | ----------- | --------------------------------------------------- |
-| `path`                 | `string`             | (required)  | Absolute or `~`-prefixed path to the `.sqlite` file |
-| `walMode`              | `boolean`            | `true`      | Enable WAL mode for better read concurrency         |
-| `encryption`           | `{ secret: string }` | `undefined` | AES-256-GCM encryption for values at rest           |
-| `ttlCleanupIntervalMs` | `number`             | `60000`     | Interval for purging expired keys (milliseconds)    |
+| Option                 | Type                 | Default     | Description                                                                                                          |
+| ---------------------- | -------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------- |
+| `path`                 | `string`             | (optional)  | Absolute or `~`-prefixed path to the `.sqlite` file. Auto-resolved when omitted — see the default-path policy below. |
+| `walMode`              | `boolean`            | `true`      | Enable WAL mode for better read concurrency                                                                          |
+| `encryption`           | `{ secret: string }` | `undefined` | AES-256-GCM encryption for values at rest                                                                            |
+| `ttlCleanupIntervalMs` | `number`             | `60000`     | Interval for purging expired keys (milliseconds)                                                                     |
 
 ### With at-rest encryption
 
@@ -198,7 +227,37 @@ You do not call any factory yourself. The SDK constructs the SQLite session stor
 - TTL cleanup interval setup for automatic key expiration
 - Creating the database file and parent directories if they do not exist
 
-In other words, the only public API you interact with is the `sqlite: { ... }` block in the decorator config from Step 2. There is no `createSqliteSessionStore` helper exported from `@frontmcp/sdk` -- session store wiring is an internal concern of the framework.
+### How the wiring works (issue #401)
+
+Top-level `sqlite` is treated by the SDK as the **default SQLite backend** for
+three subsystems:
+
+| Subsystem                     | Default source     | Override                       |
+| ----------------------------- | ------------------ | ------------------------------ |
+| Transport session persistence | top-level `sqlite` | `transport.persistence.sqlite` |
+| Background task store         | top-level `sqlite` | `tasks.sqlite`                 |
+| Elicitation store             | top-level `sqlite` | `elicitation.sqlite`           |
+
+If you want different files per subsystem, set the subsystem's own `sqlite`
+block — it takes precedence over the top-level one. To disable a single
+subsystem, set its `enabled: false` (or set `transport.persistence: false` for
+transports).
+
+If you set the top-level `sqlite` block but disable every consuming subsystem,
+the SDK emits a WARN at startup so the no-op doesn't go silent:
+
+```text
+[FrontMcp] Top-level `sqlite` config was provided but no subsystem consumes it ...
+```
+
+`createSqliteSessionStore` lives in
+`libs/sdk/src/auth/session/index.ts` for the framework's own wiring, but
+it is **not** re-exported from `@frontmcp/sdk`'s public entrypoint and
+there is no `@frontmcp/sdk/auth/session` subpath export. End-user code
+should rely on the decorator path (top-level `sqlite: {...}` on
+`@FrontMcp`) — same guidance as
+[`configure-session`](../../frontmcp-config/references/configure-session.md):
+the SDK constructs the session store; user code does not.
 
 If you need to share the same SQLite config in another part of your code, declare it once and reuse it:
 

package/catalog/frontmcp-testing/SKILL.md

@@ -36,7 +36,7 @@ Entry point for testing FrontMCP applications. This skill helps you navigate tes
 - You need to build components, not test them (see `frontmcp-development`)
 - You need to deploy, not test (see `frontmcp-deployment`)
 
-> **Decision:** Use this skill for testing strategy and routing. Use `setup-testing` for hands-on Jest configuration and test writing.
+> **Decision:** Use this skill for testing strategy and routing. Open the `setup-testing` reference under `references/` for hands-on Jest configuration and test writing.
 
 ## Prerequisites
 
@@ -46,17 +46,17 @@ Entry point for testing FrontMCP applications. This skill helps you navigate tes
 
 ## Steps
 
-This is a router skill. Follow this order to pick a testing approach, then move to the target skill.
+This is a router skill. Follow this order to pick a testing approach, then move to the target reference under `references/`.
 
 1. **Pick the test layer** — unit (fastest, mock DI), integration (real DI scope), or E2E (real MCP client + server). Use the Testing Strategy table below.
 2. **Pick the component flavour** — tool / resource / prompt / agent / job — each has a distinct recipe.
-3. **Pick the runtime concern** — auth, browser/CLI build, direct vs streamable transport — and add the matching skill to your reading list.
-4. **Open the target skill** (e.g. `test-tool-unit`, `test-e2e-handler`, `test-auth`) and follow its Steps section.
-5. **Enforce coverage** — confirm the project's 95%+ thresholds are wired into Jest before merging (see `setup-testing`).
+3. **Pick the runtime concern** — auth, browser/CLI build, direct vs streamable transport — and add the matching reference to your reading list.
+4. **Open the target reference** (e.g. `references/test-tool-unit.md`, `references/test-e2e-handler.md`, `references/test-auth.md`) and follow its Steps section.
+5. **Enforce coverage** — confirm the project's 95%+ thresholds are wired into Jest before merging (see `references/setup-testing.md`).
 
 ## Scenario Routing Table
 
-| Scenario                                | Skill / Section                 | Description                                                                                          |
+| Scenario                                | Reference / Section             | Description                                                                                          |
 | --------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------- |
 | Set up Jest, coverage, and test harness | `setup-testing`                 | Full Jest config, test utilities, and coverage thresholds                                            |
 | Write unit tests for a tool             | `test-tool-unit`                | Mock DI, validate input/output, test error paths                                                     |
@@ -87,17 +87,17 @@ This is a router skill. Follow this order to pick a testing approach, then move
 
 ## Cross-Cutting Testing Patterns
 
-| Pattern            | Rule                                                                                                                                                                                                                                                                                                 |
-| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| File naming        | Always `.spec.ts` (not `.test.ts`); E2E uses `.e2e.spec.ts`                                                                                                                                                                                                                                          |
-| File organization  | Split E2E tests by app/feature: `e2e/calc.e2e.spec.ts`, `e2e/ecommerce.e2e.spec.ts`. Never put all tests in a single `server.e2e.spec.ts`                                                                                                                                                            |
-| Test runner        | Standalone projects: use `frontmcp test` (auto-generates Jest/SWC config). Nx monorepos: use `nx test <lib>` (resolves the project's `jest.config.ts`). Never invoke `jest --config ...` directly                                                                                                    |
-| Coverage threshold | 95%+ across statements, branches, functions, lines                                                                                                                                                                                                                                                   |
-| Test descriptions  | Plain English, no prefixes like "PT-001"; describe behavior not implementation                                                                                                                                                                                                                       |
-| Mocking            | Mock providers via DI token replacement, never mock the framework                                                                                                                                                                                                                                    |
-| httpMock scope     | `httpMock` intercepts HTTP in the **test process** only, NOT in the MCP server subprocess. Do not use httpMock to intercept server-to-API calls — those happen in the child process. Use httpMock for verifying client-to-server request shapes or mocking external APIs called from the test itself |
-| Error testing      | Assert `instanceof` specific error class AND MCP error code                                                                                                                                                                                                                                          |
-| Async              | Always `await` async operations; use `expect(...).rejects.toThrow()` for async errors                                                                                                                                                                                                                |
+| Pattern            | Rule                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| File naming        | Always `.spec.ts` (not `.test.ts`); E2E uses `.e2e.spec.ts`                                                                                                                                                                                                                                                                                                                                                                                 |
+| File organization  | Split E2E tests by app/feature: `e2e/calc.e2e.spec.ts`, `e2e/ecommerce.e2e.spec.ts`. Never put all tests in a single `server.e2e.spec.ts`                                                                                                                                                                                                                                                                                                   |
+| Test runner        | Standalone projects: use `frontmcp test` (auto-generates Jest/SWC config; discovers `src/**/*.spec.ts(x)`, `__tests__/**/*.spec.ts(x)`, and `e2e/**/*.e2e.spec.ts(x)`; transforms both `.ts` and `.tsx` with the automatic JSX runtime; delegates to a user-provided `jest.config.{ts,js,mjs,cjs,json}` if present). Nx monorepos: use `nx test <lib>` (resolves the project's `jest.config.ts`). Never invoke `jest --config ...` directly |
+| Coverage threshold | 95%+ across statements, branches, functions, lines                                                                                                                                                                                                                                                                                                                                                                                          |
+| Test descriptions  | Plain English, no prefixes like "PT-001"; describe behavior not implementation                                                                                                                                                                                                                                                                                                                                                              |
+| Mocking            | Mock providers via DI token replacement, never mock the framework                                                                                                                                                                                                                                                                                                                                                                           |
+| httpMock scope     | `httpMock` intercepts HTTP in the **test process** only, NOT in the MCP server subprocess. Do not use httpMock to intercept server-to-API calls — those happen in the child process. Use httpMock for verifying client-to-server request shapes or mocking external APIs called from the test itself                                                                                                                                        |
+| Error testing      | Assert `instanceof` specific error class AND MCP error code                                                                                                                                                                                                                                                                                                                                                                                 |
+| Async              | Always `await` async operations; use `expect(...).rejects.toThrow()` for async errors                                                                                                                                                                                                                                                                                                                                                       |
 
 ## Common Patterns