lessons-learnt
Skill2 starsChanged 16 days agoApache-2.0View on GitHub
Captures the important, reusable knowledge from the current session (decisions, rules we now follow, what failed and why, facts gathered with sources) as dated markdown files in a `lessons-learnt/` folder, written so both an AI agent and a human can use them. Use when the user asks to "write the lessons learnt", "record what we learned", "add this session to lessons-learnt", or at the end of a long working session.
In this repository19 other files it gives its agents.
- .agents/AGENTS.mdAGENTS.md
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- cross-platform-dev-scriptsSkill
- multi-agent-docsSkill
- preflight-test-engineerSkill
- public-repo-release-reviewSkill
- readme-designerSkill
- saas-app-builderSkill
- third-party-skill-verifierSkill
- skill-creatorSkill
- cross-platform-dev-scriptsSkill
- lessons-learntSkill
- multi-agent-docsSkill
- preflight-test-engineerSkill
- public-repo-release-reviewSkill
- readme-designerSkill
- saas-app-builderSkill
- third-party-skill-verifierSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 7 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 20
Look in the repo root, in this order, and use the first that exists: docs/lessons-learnt/, lessons-learnt/.
- Very specific: line 22
If neither exists, create docs/lessons-learnt/ when a docs/ folder exists, otherwise lessons-learnt/.
- Distinctive: line 39
Write one file per kind that has real content.
- Distinctive: line 55
Leave out: step-by-step narration, file contents already in the repo, anything git log records, guesses presented as facts.
- Very specific: line 61
Every file starts with a title, a Written: line (date, time, timezone) and one sentence saying when to read it.
- Distinctive: line 106
If a README.md exists in the folder, add one row per new file at the top of its index (newest first) with a one-line summary, matching the …
- Distinctive: line 108
If none exists, create a short one: purpose, the file-name pattern, the kinds table, the rules ("important things only", "no secrets", …
- Distinctive: line 115
Append-only: Never edit or delete an existing dated file.
- Distinctive: line 118
Do not paste whole transcripts or logs.
- Distinctive: line 119
Do not run commit or push.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill 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
lessons-learnt
Turn what this session taught us into durable notes so the next session starts from what is already known instead of re-deriving it (fewer tokens, fewer repeated mistakes). Notes are for two readers: an AI agent that has no memory of this session, and a human skimming for the "why".
1. Find or create the folder
Look in the repo root, in this order, and use the first that exists:
docs/lessons-learnt/, lessons-learnt/.
If neither exists, create docs/lessons-learnt/ when a docs/ folder exists,
otherwise lessons-learnt/. Never put it inside a build, vendor or generated
folder. If the folder has a README.md, read it first and follow its rules
(index format, append-only, kinds). If the project's AGENTS.md/CLAUDE.md
protects this folder or any file you would touch, stop and tell the user.
2. Name the files
YYYY-MM-DD_HHMM_<kind>_<topic>.md, local time, from date +%Y-%m-%d_%H%M
(run it, do not guess). Example: 2026-10-31_1506_failures_guardrails.md.
<kind>is one of:session: decisions and outcomes of the session (the "why is it like this").failures: what broke or was missed, plus the rules we now follow.recon: facts gathered from outside the repo (versions, docs, tool behaviour), each with its source and date.
<topic>: 1-4 lowercase words joined with-, naming the subject, not the day.- Write one file per kind that has real content; skip empty kinds. Use the same timestamp for files written in the same run.
3. Decide what goes in (be selective)
Include only what would change what someone does next time and cannot be read from the code or git history:
- Decisions and the reason behind them; alternatives rejected and why.
- Things that failed, the root cause (not just the symptom) and the fix.
- Rules distilled from those failures, phrased as instructions.
- Non-obvious facts about the environment, tools, sandbox or permissions.
- Commands or checks that proved something, so they can be re-run.
- Open follow-ups only a human can do, and anything not verified (say what access was missing).
Leave out: step-by-step narration, file contents already in the repo, anything git log records, guesses presented as facts. Never write secrets (tokens, keys, passwords, private URLs, personal data).
4. File template
Every file starts with a title, a Written: line (date, time, timezone) and one
sentence saying when to read it. Then:
# <Kind> <date>: <one-line subject>
**Written:** YYYY-MM-DD HH:MM <TZ>. **Read when:** <the situation that makes this file relevant>.
## TL;DR
- 2-5 bullets: the outcome and the rules that matter most.
## Rules we now follow (failures files: put this first)
1. **<Imperative rule>.** Why, in one sentence. *(evidence: file, command or ID)*
## What happened / decisions (session files)
- <Decision or event> — because <reason>. Rejected: <alternative> (<why>).
## What broke (one line each) (failures files)
- (H/M/L) <ID> <symptom> → <root cause> → <fix or status>.
## Facts and sources (recon files)
- <Fact>. Source: <URL or doc>. Checked: YYYY-MM-DD. Re-check by: <date or trigger>.
## How to re-check
- `<command>`: what a pass or fail means.
## Open items
- [ ] <human or agent follow-up>. Not verified: <what and why>.Writing style: short sentences, concrete names (paths, commands, rule IDs), imperative rules, severity or status tags where useful. A human should get the gist from the TL;DR; an agent should be able to act from the rules and commands without reading anything else. Link related files with relative links.
Example of one good rule line (specific, causal, re-checkable):
17. **Every command in `permissions.allow` must be safe to run unattended, including `make run`.** It launches agent-written code with the user's file access. *(G-07; check: `grep -n "make run" .claude/settings.json`)*A weak version to avoid: "Be careful with permissions." (no cause, no check).
5. Update the index
If a README.md exists in the folder, add one row per new file at the top of
its index (newest first) with a one-line summary, matching the existing format.
If none exists, create a short one: purpose, the file-name pattern, the kinds
table, the rules ("important things only", "no secrets", "append-only"), and the
index. If the README has a checklist for the next session, add only lessons that
are genuinely new.
6. Rules for the files themselves
- Append-only. Never edit or delete an existing dated file. To correct an
old fact, write a new file that says "supersedes
<file>". OnlyREADME.md(the index) is edited in place. - Do not paste whole transcripts or logs; quote the one line that proves a point.
- Do not run commit or push. Tell the user which files were written and let them decide.
7. Finish
Reply with the list of files written (as links), a one-line summary of each, and anything you left out on purpose or could not verify.
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.

