breadcrumbsmd
Leave a trail for future-you.
Your agent documents your homelab projects as it builds them, so when that cron job breaks eight months from now, you have notes.
Hobby project documentation. Written by your agent. Read by your agent.
Every project gets a breadcrumbs.md, a living design
doc in the project root. It captures what the project does, why it's
built that way, and what just changed: the decisions and trade-offs
that don't live in the code.
You don't write it. You don't maintain it. Your agent does both, and reads it back the next time you open the project.
For builders who struggle with documentation.
You know the lifecycle. You spin up a backup script for your homelab, a dashboard, a little automation. It quietly does its job for months. Then one night it breaks, and the maintainer who left no notes was you.
That's the moment breadcrumbs exists for. Your agent reads the doc before you say a word: it already knows why you picked SQLite, what you tried that didn't work, and what you meant to build next. You fix the thing and get back to your evening. No spelunking, no re-explaining your own project to your own tools.
Nothing about your workflow changes.
Build like you always do.
Prompt your agent, make things, break things. The skill stays out of your way.
Your agent keeps the breadcrumbs current.
As it works, it records decisions, trade-offs, future
ideas, and a plain-English changelog in
breadcrumbs.md.
Next session, it reads the file first.
Tomorrow or next year, the agent picks up where you left off, even if you forgot where that was.
# Project Name Brief one-liner describing what this project does. ## Overview A few paragraphs of high-level context. The "explain it to a new team member" section. ## Tech Stack Language, framework, database, key dependencies. ## Architecture Where code lives. How the pieces connect. How data flows. ## Requirements What it does today. What's planned for next. ## Design Decisions Every non-obvious choice and the reasoning behind it. Old decisions stay: superseded, not deleted. ## Changelog Recent meaningful changes, in plain English. ## Conventions Project-specific patterns a new contributor should know.
One file + one optional line.
skill.md is an
agent skill,
a plain markdown instruction file that AI coding tools load
automatically. It works anywhere skills do: Claude, ChatGPT, Gemini,
Cursor, GitHub Copilot, Open WebUI, OpenClaw, and friends.
Grab the skill file.
Save it where your agent reads persistent instructions:
a skills folder, Claude Projects, Cursor rules, a
CLAUDE.md. Anywhere it loads context every
session.
Optional: add one line to your system prompt.
Most tools now discover skills automatically and don't need this. If yours doesn't, this line is the trigger, and the skill handles the rest: when to create the breadcrumbs, what belongs inside, when to update it.
Not the first crumb on the trail.
breadcrumbs.md was conceived and named independently, but the trail was walked before. In 2025, Dasith Wijesiriwardena published the Breadcrumb Protocol, a more comprehensive system with per-task breadcrumb files, domain-knowledge folders, and specifications, built for teams working on larger codebases.
If breadcrumbs.md feels too small for your project, that's where to go next.
Start leaving breadcrumbs.
Become the builder with the documentation you always wish you had.