clankbrain
AGENTS.md16 starsChanged 7 months agoMITView on GitHub
A skill does one job. An agent, in Clankbrain, is a longer workflow made of several steps. It runs those steps in order and stops at checkpoints so you can review before it continues. Each agent is a markdown file in .claude/agents/. Use an agent when a job has several stages, such as building a feature or fixing a hard bug. For a single small task, a skill is enough. Note: the installer does not copy agents into your project.…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,774 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository45 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- actSkill
- security-checkSkill
- environment-checkSkill
- run-verificationSkill
- refactorSkill
- debug-session-archivedSkill
- generate-guardsSkill
- check-anthropicSkill
- code-reviewerSkill
- code-reviewSkill
- debug-sessionSkill
- end-sessionSkill
- evolve-checkSkill
- evolveSkill
- fix-bugSkill
- forgetSkill
- frontend-designSkill
- guardSkill
- kit-healthSkill
- learnSkill
- map-codebaseSkill
- modeSkill
- parallel-prototypesSkill
- planSkill
- powershell-safeSkill
- product-riskSkill
- progress-reportSkill
- prototype-hypothesisSkill
- recallSkill
- refactoring-uiSkill
- scan-codebaseSkill
- scan-conventionsSkill
- search-firstSkill
- search-memorySkill
- shadow-codeSkill
- skill-creatorSkill
- smart-resumeSkill
- start-sessionSkill
- strategic-compactSkill
- tourSkill
- ux-heuristicsSkill
- verification-loopSkill
The file
We split this agents.md into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 5
Use an agent when a job has several stages, such as building a feature or fixing a hard bug.
- Very specific: line 61
Create a file in .claude/agents/, for example my-workflow.md.
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Agents: Multi-Step Workflows
A skill does one job. An agent, in Clankbrain, is a longer workflow made of several steps. It runs those steps in order and stops at checkpoints so you can review before it continues. Each agent is a markdown file in .claude/agents/.
Use an agent when a job has several stages, such as building a feature or fixing a hard bug. For a single small task, a skill is enough.
Note: the installer does not copy agents into your project. They live in this repo's .claude/agents/ folder. To use one, copy the file into your own project's .claude/agents/ folder.
The four agents
| Agent file | Use it when | Steps |
feature-build.md | You are building a new feature | search first, plan, implement, review, verify, learn |
bug-fix.md | You are chasing a bug | reproduce, isolate, fix, verify, log and learn |
end-session.md | You are finishing for the day | extract lessons, update memory, guard scan, drift check, update STATUS.md, evolve check, sync (if set up), final report |
plan.md | You are designing something | understand the goal, research, draft options, write the plan, execute, close |
How they work: breakpoints
A breakpoint is a stop sign inside the agent file. At a breakpoint Claude shows what it found or made, then waits for you to say "continue." You can also stop, change direction, or ask for something different.
## Step 1 — Search
Run `/search-first` with the feature description.
Find every related function. Note call chains and DB tables involved.
**BREAKPOINT — Show findings. Wait for "continue" before Step 2.**Example of what you see:
Claude: Step 1 done. Found 3 related functions and 2 tables (details above).
Reply "continue" to start the plan.
You: continueMost steps end with a breakpoint. The end-session agent has fewer, because its steps are routine.
Agents compared with skills
| Skills | Agents | |
| Size | One task | A whole workflow |
| How to start | A matching phrase or /name | Ask for it by name |
| Stops to check with you | No, it runs to the end | Yes, at each breakpoint |
| Linking to the next step | An ## Auto-Chain section | Steps written in order |
| Best for | One clear task | A feature or a bug fix |
Write your own agent
- Create a file in
.claude/agents/, for examplemy-workflow.md. - Paste this and edit it:
---
name: my-workflow
description: When to use this agent
---
## Step 1 — First thing
Do this. Check that. Report findings.
**BREAKPOINT — Show [what]. Wait for "continue" before Step 2.**
## Step 2 — Second thing
Do this next.Tips:
- End each step with one breakpoint.
- Say exactly what Claude should show at the breakpoint (findings, a plan, review results).
- Say which word to wait for, such as "continue."
- Where you can, write
Run /skill-nameinstead of repeating instructions. That keeps agents short and skills reusable.
See skills.md for the skills these agents call, and extending.md for other ways to customize Clankbrain.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.