Awesome-omni-skill breadcrumb

Leave notes on files for other agents to see in future sessions. Use after making non-obvious changes, fixing tricky bugs, or when code looks wrong but is intentional.

install

source · Clone the upstream repo

git clone https://github.com/diegosouzapw/awesome-omni-skill

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/diegosouzapw/awesome-omni-skill "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data-ai/breadcrumb" ~/.claude/skills/diegosouzapw-awesome-omni-skill-breadcrumb && rm -rf "$T"

manifest: skills/data-ai/breadcrumb/SKILL.md

source content

Breadcrumb

Leave notes on files that persist across agent sessions.

When to use

After making changes that future agents might misunderstand:

Non-obvious code that looks like it could be simplified
Bug fixes for edge cases
Intentional workarounds
Security-critical patterns
Performance tuning

Core workflow

1. Before editing, check for warnings:

breadcrumb check ./src/api/users.ts

Exit 0 = safe to proceed (clear/info)
Exit 1 = warning exists, read the
```
suggestion
```
field

2. After non-obvious changes, leave a note:

breadcrumb add ./src/api/users.ts "Retry logic tuned for rate limits"

Command reference

Command	Purpose
`breadcrumb check <path>`	Check path for notes ( `-r` for recursive)
`breadcrumb add <path> <message>`	Leave a note ( `-s` severity, `--ttl` expiration)
`breadcrumb edit <path-or-id>`	Edit a note ( `-m` message, `-a` append, `-s` severity)
`breadcrumb verify [path]`	Check if notes are stale ( `--update` to refresh hashes)
`breadcrumb search <query>`	Find notes by content ( `-r` for regex)
`breadcrumb coverage [path]`	Show breadcrumb coverage stats
`breadcrumb ls`	List all notes ( `-s` filter by severity)
`breadcrumb status`	Quick overview (counts)
`breadcrumb rm <path>`	Remove a note ( `-i` by ID)
`breadcrumb prune`	Remove expired notes

Staleness detection

Notes track file content hashes. When you see

[STALE]

prefix:

The file has changed since the note was written
The note may no longer be accurate
Use judgment: the warning might still apply, or might be outdated

📝 BREADCRUMB: [STALE] Don't simplify this regex
                ↑ Code changed - verify note still applies

After reviewing stale notes, update hashes with:

breadcrumb verify --update

Output format

All commands output JSON. Key fields:

```
status
```
: "clear", "info", or "warn"
```
suggestion
```
: Actionable guidance when warnings exist
```
breadcrumbs
```
: Array of matching breadcrumb objects
```
staleness
```
: "verified", "stale", or "unknown" (per breadcrumb)