Keep the Why skill
Keep the Why keeps decision reasons and rejected options as Markdown in the repo so agents do not propose them twice
- 237 ★ on the repository
- Last commit
- MIT
Minimal access
Why this level
- The skill writes Markdown files into the repository `context/` folder but executes no code and makes no network calls.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/keep-the-whyDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewMinimal accessThe tool runs nothing and makes no network calls.
- The skill writes Markdown files into the repository `context/` folder but executes no code and makes no network calls.
This is third-party code. Review the repository files before installing.
What it does
Keep the Why is a skill and file convention that keeps the reasoning behind code in the repository: architecture decisions, rejected alternatives, workarounds, incident learnings and operational constraints. It is plain Markdown in a `context/` folder committed with the code, so Git provides storage, history and distribution and a pull request shows the reasoning diff beside the code diff. The skill captures reasoning as a byproduct of talking to the agent. On first run it does a short setup: where to store it, whether to start with proactive or explicit capture, how much confirmation to ask for. The author cites an experiment: twenty fresh sessions were asked to simplify a retry wrapper. Without a recorded reason seven of ten offered the rejected simplification again, while with one entry in `context/` all ten found it and none proposed it. Alongside sit the `keep-the-why-lint` linter on PyPI and a GitHub Action, the `keep-the-why-dashboard` panel and plugins for Claude Code, Codex and Cursor.
Who it is for. Maintainers and teams who run long-lived codebases with agents and are tired of re-debating decisions already made and rejected.
Good fit when
- The agent proposes an option you already rejected again and nobody wrote down the reason.
- An old project has odd code and you need to tell whether it is a Chesterton fence or cruft.
- A new hire or a new agent needs the reasons behind decisions and the code author has left.
- In a pull request you want to see reasoning changes beside code changes.
Not a fit when
- You need a database or web knowledge service: Keep the Why keeps everything in Markdown with no database or daemon.
- The project is throwaway and will not live long: the cost of keeping reasons will not pay off.
- You need to rebuild all reasons from history after the fact: code, issues and history return only part, a maintainer must add the rest.
Example request
Install Keep the Why and set it up in this project with default settings, then record the reason we rejected simplifying the retry wrapper.Limitations
The skill captures reasoning while you work with an agent, so on an old repository it recovers only part of the reasons from code, issues and history, and a maintainer must add the rest, which takes effort. Install uses `npx skills add` with the `skills/keep-the-why` folder and needs Node.js; `gh skill install` and `asm install` also work. On first run the skill asks setup questions, so answering default settings is a complete answer. Agents from different vendors follow the capture differently, and a matrix of tested agent and model pairs is published on the project site.
How to disable. Delete the `keep-the-why` skill folder from the agent skills directory. The `context/` files stay in the repository as plain Markdown and can be removed by hand.
FAQ
How do I install Keep the Why?
Run `npx skills add https://github.com/oliver-zehentleitner/keep-the-why/tree/latest/skills/keep-the-why`: the script asks which of the 70+ agents to install for.
Where are the reasons stored?
In plain Markdown files in the `context/` folder inside the repository, next to the code and under Git.
Do I need a database, daemon or account?
No. The author describes the project as a memory layer with no database, daemon or account.
How do I check entries in CI?
With the `keep-the-why-lint` linter from PyPI or the GitHub Action of the same name.
Which agents are tested?
Claude Code, opencode, Pi, Hermes and others. The agent and model matrix is at keepthewhy.com/agent-matrix.
Discussion
No questions or reviews yet.
Related
SkillsSkill setting up Markdown file memory for Codex via AGENTS.md: profile, rules, lessons, errors and capability requests.
Local memory for AI agents in plain Markdown files: it keeps only what you approve and serves it through MCP
Shared team memory for people and AI agents in Git: decisions and handoffs live in Markdown, reachable from Claude Code and Codex.
Skills keep project memory in a docs/ai folder: short size-capped files, a one-page handoff and a verifier for the install
Intent CLI keeps the goal, the latest verified checkpoint and decisions in the project so a new agent session can resume
Agentic Substrate
Agentic Substrate (claude-user-memory)
A short reversible rule set for an agent: research the unclear, plan proportionally, verify the outcome and keep checked knowledge
README in short
The README sets out the why layer idea for repository project memory, the measured twenty-session experiment, installation and links to the linter, dashboard and site. MIT license.