Agent skills

agentcrumbs ships with agent skills inside the npm package, built on the @tanstack/intent standard. Tell your agent to run npx @tanstack/intent install and it will set up skill-to-task mappings in your agent config so it knows when to load agentcrumbs patterns.

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

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
description: >
  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.2.0"
sources:
  - "triggerdotdev/agentcrumbs:README.md"
  - "triggerdotdev/agentcrumbs:src/trail.ts"
---

The content includes correct usage patterns, explicitly flags common mistakes, and points agents to CLI help and docs for deeper discovery.

Available skills

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 is the entry point for setting up agentcrumbs in any project.

When the agent runs init, it:

1. Scans repo structure. Looks at apps/, packages/, services/, src/ directories, route groups, worker files, existing logger namespaces.
2. Proposes a namespace catalog. Presents discovered namespaces and asks you to confirm, add, or rename before writing anything.
3. 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:

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 telling your agent to run npx @tanstack/intent install handles all of this automatically.