breadcrumb_skill

Overview

This skill lets agents leave persistent, file-attached notes that future agents (or your future self) can read in later sessions. It provides simple CLI commands to add, list, view, and remove breadcrumbs tied to specific files. Use it to communicate intent, caveats, or non-obvious reasons for code decisions across agent workflows.

How this skill works

When you add a breadcrumb, the tool stores a short note linked to a file path in a shared store that persists across sessions. Other agents can check a file and see any attached notes before editing or reverting code. Notes are human-readable, lightweight, and meant to surface context like workaround rationale, edge-case fixes, or dependency warnings.

When to use it

• After making a non-obvious change that looks like it could be simplified
• When fixing a tricky edge-case bug so future agents don’t undo the fix
• If you implement an intentional workaround or temporary patch
• When a file has cross-file dependencies that aren’t obvious
• Before leaving code that intentionally deviates from style or common patterns

Best practices

• Write concise, actionable notes: state the why and any constraints
• Include references: issue IDs, tests, or reproduction steps if relevant
• Avoid long essays—aim for one or two sentences with key context
• Update or remove breadcrumbs when the underlying code changes
• Use consistent phrasing for common patterns (e.g., "intentional", "edge-case")

Example use cases

• breadcrumb add ./src/parser.ts "Regex handles unicode edge cases; don't simplify"
• breadcrumb add ./src/auth.ts "OAuth flow depends on legacy token format; validate before changing"
• breadcrumb add ./src/tax.ts "Ceiling division intentional for compliance; see TAX-42"
• breadcrumb ls to review all file notes before a large refactor
• breadcrumb check ./path/to/file to see why a recent fix was applied