Flatbread skill
Flatbread keeps a project's decisions and constraints as Markdown in Git, and its Proof skill gives agents shared long-term memory
- 69 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The skill lets the agent write Markdown record files into the repository
- The install command downloads an npm package and adds it to devDependencies
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/flatbreadDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The skill lets the agent write Markdown record files into the repository
- The install command downloads an npm package and adds it to devDependencies
This is third-party code. Review the repository files before installing.
What it does
Flatbread turns a repository's Markdown and YAML files into records of named collections linked through refs in flatbread.config.js. The graph is validated before it is read, and you read it through GraphQL, generated TypeScript or bounded CLI commands. The files stay the source of truth, with ordinary Git branches, review and history. The Proof package is meant for agents. npx --yes flatbread@latest proof install-skill downloads the latest CLI, pins its exact version as a devDependency and copies the Proof skill. The agent records Issues, Findings, Decisions, Constraints and Risks under an Effort, one coherent thread of work, in the repository. Each record is a separate Markdown file, so the next session and coworkers read the same reasons, review them in a pull request and trace how a decision changed. npx flatbread proof bootstrap --verify checks the setup and prints JSON with status ready. proof write creates a record from a JSON description, and proof list reads, for example with --status active. The second use case is sites, documentation and internal tools built on linked files, with flatbread start --watch and GraphQL on port 5057.
Who it is for. Teams and solo developers whose long work runs across many Claude Code or Codex sessions and whose reasons for decisions get lost in chats.
Good fit when
- A task spans several weeks, and every new agent session starts without the context of past decisions
- The reasons for choosing a library should go through review in a pull request along with the code
- Coworkers need to read the same findings and constraints the agent sees
- A site or documentation is built from Markdown with links between records, such as posts and authors
- You want bounded CLI commands the agent reads the graph with, instead of the whole repository
Not a fit when
- The project is not on Node: Flatbread needs Node 20.19 or newer
- You need an external database with queries over a large volume of data: files are the only storage here
- A single notes file such as CLAUDE.md is enough: a collection schema and refs would be excessive
- You want memory captured from chats automatically: the agent creates records itself under the skill's rules
Example request
Set up Proof in this project, create an Effort called "Choose a search index" and record the first constraintLimitations
- Every package requires Node 20.19 or newer.
- The Proof content model is wired in by hand: add proofContent() to flatbread.config.js and two lines to .gitignore for working state.
- proof bootstrap only inspects the project and edits nothing.
- GraphQL is only one way to read, and the generated TypeScript layer is called a prototype in the README and still runs queries through GraphQL.
- There is no flatbread dev command: wrap dev and build scripts with flatbread start.
How to disable. Remove the Proof skill from the agent's skills folder, drop proofContent() from flatbread.config.js and the flatbread package from devDependencies. The Markdown records stay in the repository as ordinary files.
FAQ
What is Proof in Flatbread?
Proof is the package for agents' long-term memory. The agent records Issues, Findings, Decisions, Constraints and Risks in Markdown files under an Effort. They live in your repository and do not depend on a private chat or hosted store.
How do I install Proof in a project?
Run npx --yes flatbread@latest proof install-skill. It pins the CLI version in devDependencies and copies the skill. Then wire proofContent() into the config and check the setup with npx flatbread proof bootstrap --verify.
Do I need GraphQL to use Proof?
No. Agents read through bounded CLI commands such as npx flatbread proof list --status active and get JSON with a path to a Markdown digest. GraphQL serves the second use case, sites and apps.
Which records does the agent keep in Proof?
Issues, Findings, Decisions, Constraints and Risks under an Effort, one coherent thread of work. Each record is a separate Markdown file visible in Git history and in a pull request.
Which Node version is required?
Node 20.19 or newer for every published Flatbread package. The proof install-skill command pins the exact CLI version in the project's devDependencies.
Discussion
No questions or reviews yet.
Related
Skillsomnistack-agent installs four skills for Claude Code, Copilot, Cursor and Codex: debug, review, security, engineering
A skill set against AI slop: UI and typography audits, change review, releases, docs and SEO.
Two skills for Codex and Claude Code: prd keeps a living implementation checklist and review audits designs from the user's side
Builder Skills
Skills for agents
A set of small skills from Builder.io for agent work habits: visual plans and diff recaps, docs-first checks, cross-agent review and clean status updates
Eleven skills for Claude Code and Codex: test audit, git worktree cleanup, plan pages, screen recording transcripts and 1Password sign-in
planr keeps agent-driven development tasks in Git Markdown files and shows what is ready, blocked and waiting on you
README in short
The README splits users into two paths: memory for coding agents through Proof and linked content for apps. Each path comes with step-by-step commands, followed by how the engine works: a source finds files, a transformer makes records, content groups them into collections, refs link them, and the validated graph is exposed through GraphQL, TypeScript or Proof commands.