triggerdotdev · ericallam · Mar 10, 2026 · Mar 10, 2026 · Mar 10, 2026 · Mar 10, 2026
diff --git a/.changeset/fix-skill-discovery.md b/.changeset/fix-skill-discovery.md
@@ -0,0 +1,9 @@
+---
+"agentcrumbs": minor
+---
+
+Fix @tanstack/intent skill discovery and consolidate skills
+
+- Add parent SKILL.md at the namespace level so the intent walker can recurse into skill subdirectories
+- Consolidate 6 granular skills into 2: a top-level usage skill and the init skill
+- Top-level skill covers workflow, core API, markers, CLI reference, and pointers to further discovery
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,15 @@
+# CLAUDE.md
+
+## Changesets
+
+Never run `changeset version` — that happens in CI. Only add changeset files via `pnpm changeset` or by creating a markdown file in `.changeset/`.
+
+## Skills
+
+After modifying any `SKILL.md` files, validate before committing:
+
+```bash
+cd packages/agentcrumbs && npx @tanstack/intent@latest validate
+```
+
+This also runs automatically via `prepublishOnly` in the package.
diff --git a/README.md b/README.md
@@ -29,11 +29,8 @@ agentcrumbs ships with [@tanstack/intent](https://tanstack.com/blog/from-docs-to
 
 | Skill | What it teaches |
 | --- | --- |
+| `agentcrumbs` | Core workflow, API, markers, CLI reference, common mistakes |
 | `agentcrumbs/init` | Scans repo, discovers namespaces, writes config |
-| `agentcrumbs/core` | `trail()`, `crumb()`, markers, env var, noop guarantee |
-| `agentcrumbs/scopes-and-context` | `scope()`, `wrap()`, `child()`, `snapshot()`, `assert()` |
-| `agentcrumbs/sessions-and-tags` | `session()`, tags, grouping and filtering |
-| `agentcrumbs/cli` | `collect`, `tail`, `query`, `strip`, `session` |
 
 Skills travel with the package version. The agent always has docs matching the installed code.
 

diff --git a/docs/content/docs/skills.mdx b/docs/content/docs/skills.mdx
@@ -30,43 +30,34 @@ Each skill is a Markdown file with YAML frontmatter:
 
 ```yaml
 ---
-name: agentcrumbs/core
+name: agentcrumbs
 description: >
-  Core debug tracing with agentcrumbs: trail(), crumb(),
-  @crumbs markers, env var config, noop strategy...
+  Debug mode for AI coding agents. Drop structured traces inline
+  while writing code, query them when something breaks, strip
+  before merge.
 type: core
 library: agentcrumbs
-library_version: "0.1.0"
+library_version: "0.2.0"
 sources:
+  - "triggerdotdev/agentcrumbs:README.md"
   - "triggerdotdev/agentcrumbs:src/trail.ts"
-  - "triggerdotdev/agentcrumbs:src/env.ts"
 ---
 ```
 
-The content includes correct usage patterns, explicitly flags common mistakes, and defines constraints the agent must follow.
+The content includes correct usage patterns, explicitly flags common mistakes, and points agents to CLI help and docs for deeper discovery.
 
 ## Available skills
 
 | Skill | What it teaches |
 | --- | --- |
+| `agentcrumbs` | Core workflow, API, markers, CLI quick reference, critical mistakes, and pointers to further discovery |
 | `agentcrumbs/init` | Scans repo structure, discovers namespaces, writes config to CLAUDE.md or .cursorrules |
-| `agentcrumbs/core` | `trail()`, `crumb()`, `// @crumbs` markers, `#region @crumbs` blocks, env var, noop guarantee |
-| `agentcrumbs/scopes-and-context` | `scope()`, `wrap()`, `child()`, `snapshot()`, `assert()`, context propagation |
-| `agentcrumbs/sessions-and-tags` | `session()`, tags, grouping crumbs for replay and filtering |
 
-| `agentcrumbs/cli` | `collect`, `tail`, `query`, `strip`, `session`, and other CLI commands |
-
-## What each skill contains
-
-**Patterns.** Correct usage examples the agent can copy. These show the right way to use each API, with proper markers, at module scope, with structured data.
-
-**Common mistakes.** Explicitly marked with severity levels (CRITICAL, HIGH, MEDIUM). Things like: checking `process.env.AGENTCRUMBS` on every call instead of using the noop, creating `trail()` inside request handlers, forgetting `// @crumbs` markers. The agent learns what to avoid, not just what to do.
-
-**Constraints.** Hard rules: every crumb line must have a marker, don't invent namespaces without checking the catalog, create trails at module scope.
+The top-level `agentcrumbs` skill covers the essentials an agent needs to use crumbs correctly: the write-collect-query-strip workflow, core API (`trail`, `crumb`, `child`, `scope`), marker syntax, and the most common mistakes. For deeper functionality like sessions, tags, scopes, and testing patterns, it points agents to CLI help (`agentcrumbs --help`), type definitions, and the docs.
 
 ## The init skill
 
-The `agentcrumbs/init` skill deserves special mention. It's the entry point for setting up agentcrumbs in any project.
+The `agentcrumbs/init` skill is the entry point for setting up agentcrumbs in any project.
 
 When the agent runs init, it:
 
@@ -81,9 +72,8 @@ After init, every agent working in the repo uses the same consistent namespaces.
 If you don't use @tanstack/intent, you can point agents to skills directly:
 
 ```
-skills/agentcrumbs/core/SKILL.md
-skills/agentcrumbs/cli/SKILL.md
-skills/agentcrumbs/init/SKILL.md
+node_modules/agentcrumbs/skills/agentcrumbs/SKILL.md
+node_modules/agentcrumbs/skills/agentcrumbs/init/SKILL.md
 ```
 
 Or add a reference in your agent config file manually. But `npx @tanstack/intent install` handles all of this automatically.
diff --git a/docs/public/favicon.ico b/docs/public/favicon.ico
diff --git a/docs/src/app/home.css b/docs/src/app/home.css
@@ -120,6 +120,12 @@
 .hp-skills h2 { font-family: var(--hp-title); font-size: 28px; font-weight: 700; letter-spacing: -0.02em; margin-bottom: 12px; }
 .hp-skills-install { background: var(--hp-bg-code); border: 1px solid var(--hp-border); border-radius: 8px; overflow: hidden; margin-bottom: 24px; }
 .hp-skills-pre { padding: 20px; overflow-x: auto; font-family: var(--hp-mono); font-size: 12.5px; line-height: 1.7; color: var(--hp-text-dim); margin: 0; background: transparent !important; }
+.hp-skills-config { padding: 20px; font-family: var(--hp-mono); font-size: 13px; }
+.hp-skills-config-heading { color: var(--hp-text); font-weight: 600; margin-bottom: 12px; }
+.hp-skills-table { width: 100%; border-collapse: collapse; margin-bottom: 16px; }
+.hp-skills-table th { text-align: left; color: var(--hp-text-dim); font-weight: 500; padding: 6px 16px 6px 0; border-bottom: 1px solid var(--hp-border); }
+.hp-skills-table td { color: var(--hp-text-dim); padding: 6px 16px 6px 0; border-bottom: 1px solid var(--hp-border); }
+.hp-skills-config-note { color: var(--hp-text-muted); font-size: 12px; }
 .hp-skills-detail { display: flex; gap: 32px; }
 .hp-skills-detail p { color: var(--hp-text-dim); font-size: 14px; line-height: 1.6; flex: 1; }
 .hp-skills-detail a { color: var(--hp-accent); }

diff --git a/docs/src/app/page.tsx b/docs/src/app/page.tsx
@@ -225,30 +225,33 @@ export default function HomePage() {
       {/* SKILLS */}
       <section className="hp-skills">
         <div className="hp-container">
-          <h2>The init skill is the real setup</h2>
-          <p className="hp-section-subtitle">After installing, tell your agent to run <code>agentcrumbs/init</code>. It scans your repo, discovers your services and modules, and builds a <strong>namespace catalog</strong> that gets written to your agent config (CLAUDE.md, .cursorrules, etc.).</p>
-          <p className="hp-section-subtitle">This is the critical step. Without the catalog, every agent invents its own namespace names: <code>auth</code>, <code>auth-service</code>, <code>authService</code>, <code>authentication</code>, all pointing at the same thing. The catalog locks it down. Every agent, every session, same names.</p>
+          <h2>Set up with <code>agentcrumbs/init</code></h2>
+          <p className="hp-section-subtitle">The init skill scans your repo, discovers services and modules, and writes a namespace table to your agent config (CLAUDE.md, .cursorrules, etc.). Agents use the table to pick consistent namespace names across sessions.</p>
 
           <div className="hp-skills-install">
             <div className="hp-code-pane-header" style={{ borderRadius: '8px 8px 0 0' }}>
               <div className="hp-code-pane-label">what init writes to your agent config</div>
             </div>
-            <pre className="hp-skills-pre"><code dangerouslySetInnerHTML={{ __html: `<span class="trail-msg">## agentcrumbs</span>
-
-<span class="trail-msg">### Namespaces</span>
-
-<span class="cc-dim">| Namespace        | Description                      | Path              |</span>
-<span class="cc-dim">| ---              | ---                              | ---               |</span>
-| <span class="trail-name">api-gateway</span>    | <span class="cc-dim">HTTP API and routing</span>             | <span class="cc-dim">apps/gateway</span>      |
-| <span class="trail-name-b">auth-service</span>   | <span class="cc-dim">Authentication and token handling</span> | <span class="cc-dim">apps/auth</span>         |
-| <span class="trail-name-c">billing</span>        | <span class="cc-dim">Stripe integration and charges</span>   | <span class="cc-dim">apps/billing</span>      |
-| <span class="trail-name">task-runner</span>    | <span class="cc-dim">Background job execution</span>         | <span class="cc-dim">apps/worker</span>       |
-
-<span class="cc-dim">Do not invent new namespaces. Pick from this table or ask first.</span>` }} /></pre>
+            <div className="hp-skills-config">
+              <div className="hp-skills-config-heading">## agentcrumbs</div>
+              <div className="hp-skills-config-heading">### Namespaces</div>
+              <table className="hp-skills-table">
+                <thead>
+                  <tr><th>Namespace</th><th>Description</th><th>Path</th></tr>
+                </thead>
+                <tbody>
+                  <tr><td className="trail-name">api-gateway</td><td>HTTP API and routing</td><td>apps/gateway</td></tr>
+                  <tr><td className="trail-name-b">auth-service</td><td>Authentication and token handling</td><td>apps/auth</td></tr>
+                  <tr><td className="trail-name-c">billing</td><td>Stripe integration and charges</td><td>apps/billing</td></tr>
+                  <tr><td className="trail-name">task-runner</td><td>Background job execution</td><td>apps/worker</td></tr>
+                </tbody>
+              </table>
+              <div className="hp-skills-config-note">Do not invent new namespaces. Pick from this table or ask first.</div>
+            </div>
           </div>
 
           <div className="hp-skills-detail">
-            <p>agentcrumbs ships 5 skills via <a href="https://tanstack.com/blog/from-docs-to-agents" target="_blank">@tanstack/intent</a>, covering the full API, CLI, and common mistakes. Skills travel with the package version, so the agent always has docs matching the installed code.</p>
+            <p>agentcrumbs ships 2 skills via <a href="https://tanstack.com/blog/from-docs-to-agents" target="_blank">@tanstack/intent</a>: one covering the core workflow, API, and common mistakes, and an init skill that sets up your repo. Skills travel with the package version, so the agent always has docs matching the installed code.</p>
             <p>Compatible with Claude Code, Cursor, GitHub Copilot, and any agent that supports the <a href="https://agentskills.io" target="_blank">Agent Skills spec</a>.</p>
           </div>
         </div>

diff --git a/packages/agentcrumbs/README.md b/packages/agentcrumbs/README.md
@@ -29,11 +29,8 @@ agentcrumbs ships with [@tanstack/intent](https://tanstack.com/blog/from-docs-to
 
 | Skill | What it teaches |
 | --- | --- |
+| `agentcrumbs` | Core workflow, API, markers, CLI reference, common mistakes |
 | `agentcrumbs/init` | Scans repo, discovers namespaces, writes config |
-| `agentcrumbs/core` | `trail()`, `crumb()`, markers, env var, noop guarantee |
-| `agentcrumbs/scopes-and-context` | `scope()`, `wrap()`, `child()`, `snapshot()`, `assert()` |
-| `agentcrumbs/sessions-and-tags` | `session()`, tags, grouping and filtering |
-| `agentcrumbs/cli` | `collect`, `tail`, `query`, `strip`, `session` |
 
 Skills travel with the package version. The agent always has docs matching the installed code.
 

diff --git a/packages/agentcrumbs/package.json b/packages/agentcrumbs/package.json
@@ -43,7 +43,8 @@
     "build": "tsc",
     "dev": "tsc --watch",
     "test": "vitest",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npx @tanstack/intent@latest validate"
   },
   "devDependencies": {
     "@types/node": "^25.3.3",

diff --git a/packages/agentcrumbs/skills/agentcrumbs/SKILL.md b/packages/agentcrumbs/skills/agentcrumbs/SKILL.md
@@ -0,0 +1,113 @@
+---
+name: agentcrumbs
+description: >
+  Debug mode for AI coding agents. Drop structured traces inline while writing
+  code, query them when something breaks, strip before merge. Covers the core
+  workflow: trail, crumb, markers, collector, query, strip. Activate when using
+  agentcrumbs, adding debug tracing, or when an agent needs to understand
+  runtime behavior.
+type: core
+library: agentcrumbs
+library_version: "0.2.0"
+sources:
+  - "triggerdotdev/trigger-labs:debug-mode/README.md"
+  - "triggerdotdev/trigger-labs:debug-mode/src/trail.ts"
+  - "triggerdotdev/trigger-labs:debug-mode/src/types.ts"
+---
+
+# agentcrumbs
+
+Structured debug traces that agents drop inline while writing code, then query when something breaks. Stripped before merge, zero cost when off.
+
+## Workflow
+
+```
+1. Write code + crumbs   →  crumb("user verified", { userId }); // @crumbs
+2. Run with collector     →  agentcrumbs collect & AGENTCRUMBS=1 node app.js
+3. Something breaks       →  agentcrumbs query --since 5m
+4. Fix the bug            →  (read the trail, find the cause, fix it)
+5. Strip before merge     →  agentcrumbs strip
+```
+
+## Core API
+
+```typescript
+import { trail } from "agentcrumbs"; // @crumbs
+const crumb = trail("my-service"); // @crumbs — create once at module level
+
+// Basic crumb
+crumb("checkout started", { cartId: "c_91" }); // @crumbs
+
+// With tags (third arg) for filtering
+crumb("cache miss", { key }, { tags: ["perf"] }); // @crumbs
+
+// Child context for per-request tracing
+const reqCrumb = crumb.child({ requestId: req.id }); // @crumbs
+reqCrumb("handling request", { path: req.url }); // @crumbs
+
+// Scoped operations with automatic enter/exit/error tracking
+const user = await crumb.scope("validate-token", async (ctx) => { // @crumbs
+  ctx.crumb("checking jwt"); // @crumbs
+  return await verifyToken(token); // @crumbs
+}); // @crumbs
+
+// Guard expensive args
+if (crumb.enabled) { crumb("dump", { state: structuredClone(big) }); } // @crumbs
+```
+
+## Markers
+
+Every crumb line needs a marker so `agentcrumbs strip` can remove it before merge.
+
+```typescript
+// Single-line marker
+crumb("event", { data }); // @crumbs
+
+// Block marker for multi-line sections
+// #region @crumbs
+const result = await crumb.scope("operation", async (ctx) => {
+  ctx.crumb("step 1");
+  ctx.crumb("step 2");
+  return value;
+});
+// #endregion @crumbs
+```
+
+**Unmarked crumbs will leak into production code.** The strip command only removes lines with `// @crumbs` or code inside `#region @crumbs` blocks.
+
+## CLI quick reference
+
+```bash
+agentcrumbs collect           # Start HTTP collector (required for query/tail)
+agentcrumbs tail              # Live tail (--ns, --tag, --match filters)
+agentcrumbs query --since 5m  # Query history (--ns, --tag, --session, --json)
+agentcrumbs strip             # Remove all crumb markers from source
+agentcrumbs strip --check     # CI gate — exits 1 if markers found
+agentcrumbs --help            # Full command reference
+```
+
+Run `agentcrumbs <command> --help` for detailed options on any command.
+
+## Enable tracing
+
+```bash
+AGENTCRUMBS=1 node app.js              # Enable all namespaces
+AGENTCRUMBS='{"ns":"auth-*"}' node app.js  # Filter by namespace
+```
+
+When `AGENTCRUMBS` is not set, `trail()` returns a frozen noop. No conditionals, no overhead.
+
+## Critical mistakes
+
+1. **Missing markers** — Every crumb line needs `// @crumbs` or a `#region @crumbs` block. Without them, `strip` can't clean up.
+2. **Creating trail() in hot paths** — `trail()` parses the env var each call. Create once at module scope, use `child()` for per-request context.
+3. **No collector running** — Without `agentcrumbs collect`, crumbs go to stderr only and can't be queried. Start the collector before reproducing issues.
+
+## Further discovery
+
+- **CLI details**: `agentcrumbs --help` and `agentcrumbs <command> --help`
+- **TypeScript types**: Check the type definitions in `node_modules/agentcrumbs/dist/index.d.ts`
+- **Docs**: https://agentcrumbs.dev/docs
+- **Sessions and tags**: `crumb.session()` for grouping, `{ tags: [...] }` as third arg for filtering
+- **Testing**: `import { MemorySink, addSink } from "agentcrumbs"` to capture crumbs in tests
+- **Scopes**: `crumb.scope()`, `crumb.wrap()`, `crumb.snapshot()`, `crumb.assert()` for structured tracing