Agent skills

agentcrumbs ships with agent skills inside the npm package, built on the @tanstack/intent standard. When you install the package and run npx @tanstack/intent install, your agent automatically learns how to use crumbs correctly.

Skills travel with the package version. The agent always has docs matching the installed code, not stale training data from 6 months ago.

Getting started

The fastest way to set up agentcrumbs in a project is to let the agent do it:

npm install agentcrumbs
npx @tanstack/intent install

This scans node_modules for intent-enabled packages and wires the skills into your agent config file (CLAUDE.md, .cursorrules, etc.). Then tell your agent:

"Run the agentcrumbs/init skill to set up debug tracing in this project."

The init skill scans your repo, discovers services and modules, builds a namespace catalog, and writes it to your agent config. After that, the agent knows which namespaces to use and how to drop crumbs correctly.

How @tanstack/intent works

Skills follow the Agent Skills spec, an open standard supported by Claude Code, Cursor, GitHub Copilot, and other AI tools.

Each skill is a Markdown file with YAML frontmatter:

---
name: agentcrumbs/core
description: >
  Core debug tracing with agentcrumbs: trail(), crumb(),
  @crumbs markers, env var config, noop strategy...
type: core
library: agentcrumbs
library_version: "0.1.0"
sources:
  - "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.

Available skills

Skill	What it teaches
`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 init skill

The agentcrumbs/init skill deserves special mention. It's the entry point for setting up agentcrumbs in any project.

When the agent runs init, it:

Scans repo structure. Looks at apps/, packages/, services/, src/ directories, route groups, worker files, existing logger namespaces.
Proposes a namespace catalog. Presents discovered namespaces and asks you to confirm, add, or rename before writing anything.
Writes the config. Appends a minimal agentcrumbs section to your agent config file with the namespace table, a note for PR reviewers, and a 3-line CLI reference.

After init, every agent working in the repo uses the same consistent namespaces. No two agents inventing different names for the same service.

Manual setup

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

Or add a reference in your agent config file manually. But npx @tanstack/intent install handles all of this automatically.