Multi-Session Project Docs
This skill defines how to create and maintain standard documentation for projects that develop across many chat sessions over time.
When to activate
Activate in these cases:
- New multi-session project: the user uses phrases like "project", "let's continue next time", "let's pick this back up" to introduce something that will clearly last beyond one session. Offer to set up the four files — don't wait to be asked.
- Existing disorganized project: the user reports (or it is evident from the context or the files) that an already-started project has scattered or inconsistent documentation, or files named differently from the standard.
- Explicit request: the user asks you to create, fix, or reorganize a project's documentation files.
Do not activate for one-off requests with no expected follow-up (e.g. "write me a script to convert this CSV" and nothing more).
The four standard files
| File |
Purpose |
Typical content |
CLAUDE.md |
Behavior |
Rules about HOW the agent should work in this specific project: tone, level of detail, things to do and avoid, workflow preferences |
AGENTS.md |
Stable architecture and rules |
Technical rules not deducible from the code alone, constraints, known traps |
summary_for_new_chat.md |
Session-by-session chronicle |
Progressive log: what was done, decisions taken, current state, next steps. Lets a fresh chat resume without losing context |
README.md |
Outward-facing presentation |
What the project is, what it's for, how to use it — written for a human or tool reading it from outside, not for the agent |
The key rule for AGENTS.md (operational vs descriptive)
Whenever you write or update AGENTS.md (and likewise CLAUDE.md), ALWAYS apply — from the first draft, not only when revising — the following criterion:
- For each line or piece of information, ask: is it OPERATIONAL (a rule, a command, a constraint that could NOT be deduced simply by reading the code)? → keep it.
- Or is it DESCRIPTIVE (an explanation of the architecture, the folder layout, what the project does — things discoverable by exploring the repository)? → cut it, or move it to README.md.
- Exception: an "Architecture" section is not automatically descriptive if it documents non-obvious traps or bugs — that content stays OPERATIONAL.
- Never generate these files with
/init or automated tooling without applying this filter afterwards: auto-generated files are often counterproductive precisely because they are almost entirely descriptive.
Where this comes from: Thibaud Gloaguen, Niels Mündler, Mark Müller, Veselin Raychev, Martin Vechev, "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?" (ETH Zurich and LogicStar.ai, February 2026) — arXiv:2602.11988. The paper is largely skeptical of context files: they do not generally improve task success rates and raise inference cost by over 20%. Its one clear exception is what this criterion is built on — instructions in context files are followed well by agents, whereas repository overviews are not helpful.
summary_for_new_chat.md — when to update it
Do not update it automatically. Update or rewrite it only when the user explicitly asks (e.g. "update the summary", "let's close the session", "prepare the recap for next time"). When you do, append a new dated entry at the end of the file — do not rewrite the earlier history — containing:
- Date / session
- What was done
- Decisions taken, and why
- Current state of the project
- Planned next steps
Where to create the files
Always ask the user where to put the four files before creating them (e.g. project root, a docs/ subfolder). Do not assume a default location.
If the project already has documentation
If you find existing documentation files, even under different names (NOTES.md, TODO.txt, scattered comments, an old README):
- Read all the existing content.
- Propose how you intend to sort the information into the four standard files — show a draft mapping before writing anything.
- Migrate and reorganize the content into the four files, applying the OPERATIONAL/DESCRIPTIVE filter to CLAUDE.md and AGENTS.md.
- Do not delete the original files without the user's explicit confirmation. You may leave them in place or propose archiving them (e.g. under
docs/archive/), but ask first.
Communication style
Use plain language, explain technical terms in parentheses on first use, and walk through your reasoning step by step rather than presenting only the final result.
1---2name: multi-session-project-docs3description: Use this skill when the user starts or mentions a project that will continue across future sessions (cues like "project", "let's continue next time", "let's pick this back up", "new project"), or when the user reports — or the files make obvious — that an existing project has disorganized documentation (scattered files, inconsistent notes, no clear structure). In those cases, apply a standard four-file documentation structure by default: CLAUDE.md (behavior), AGENTS.md (stable architecture and rules), summary_for_new_chat.md (session-by-session chronicle), and README.md (outward-facing presentation). ALWAYS use this skill when the user says things like "set up the four files", "create the documentation files", "clean up the project documentation", "reorganize my project files", or names the skill directly. Do NOT use it for one-off, self-contained tasks with no expected follow-up.4---56# Multi-Session Project Docs78This skill defines how to create and maintain standard documentation for projects that develop across many chat sessions over time.910## When to activate1112Activate in these cases:13141. **New multi-session project**: the user uses phrases like "project", "let's continue next time", "let's pick this back up" to introduce something that will clearly last beyond one session. Offer to set up the four files — don't wait to be asked.152. **Existing disorganized project**: the user reports (or it is evident from the context or the files) that an already-started project has scattered or inconsistent documentation, or files named differently from the standard.163. **Explicit request**: the user asks you to create, fix, or reorganize a project's documentation files.1718Do not activate for one-off requests with no expected follow-up (e.g. "write me a script to convert this CSV" and nothing more).1920## The four standard files2122| File | Purpose | Typical content |23|---|---|---|24| `CLAUDE.md` | Behavior | Rules about HOW the agent should work in this specific project: tone, level of detail, things to do and avoid, workflow preferences |25| `AGENTS.md` | Stable architecture and rules | Technical rules not deducible from the code alone, constraints, known traps |26| `summary_for_new_chat.md` | Session-by-session chronicle | Progressive log: what was done, decisions taken, current state, next steps. Lets a fresh chat resume without losing context |27| `README.md` | Outward-facing presentation | What the project is, what it's for, how to use it — written for a human or tool reading it from outside, not for the agent |2829### The key rule for AGENTS.md (operational vs descriptive)3031Whenever you write or update **AGENTS.md** (and likewise **CLAUDE.md**), ALWAYS apply — from the first draft, not only when revising — the following criterion:3233- For each line or piece of information, ask: is it **OPERATIONAL** (a rule, a command, a constraint that could NOT be deduced simply by reading the code)? → keep it.34- Or is it **DESCRIPTIVE** (an explanation of the architecture, the folder layout, what the project does — things discoverable by exploring the repository)? → cut it, or move it to README.md.35- Exception: an "Architecture" section is not automatically descriptive if it documents non-obvious traps or bugs — that content stays OPERATIONAL.36- Never generate these files with `/init` or automated tooling without applying this filter afterwards: auto-generated files are often counterproductive precisely because they are almost entirely descriptive.3738Where this comes from: Thibaud Gloaguen, Niels Mündler, Mark Müller, Veselin Raychev, Martin Vechev, *"Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?"* (ETH Zurich and LogicStar.ai, February 2026) — [arXiv:2602.11988](https://arxiv.org/abs/2602.11988). The paper is largely skeptical of context files: they do not generally improve task success rates and raise inference cost by over 20%. Its one clear exception is what this criterion is built on — instructions in context files are followed well by agents, whereas repository overviews are not helpful.3940### summary_for_new_chat.md — when to update it4142**Do not update it automatically.** Update or rewrite it only when the user explicitly asks (e.g. "update the summary", "let's close the session", "prepare the recap for next time"). When you do, append a new dated entry at the end of the file — do not rewrite the earlier history — containing:43- Date / session44- What was done45- Decisions taken, and why46- Current state of the project47- Planned next steps4849## Where to create the files5051**Always ask the user where to put the four files** before creating them (e.g. project root, a `docs/` subfolder). Do not assume a default location.5253## If the project already has documentation5455If you find existing documentation files, even under different names (`NOTES.md`, `TODO.txt`, scattered comments, an old README):56571. Read all the existing content.582. Propose how you intend to sort the information into the four standard files — show a draft mapping before writing anything.593. Migrate and reorganize the content into the four files, applying the OPERATIONAL/DESCRIPTIVE filter to CLAUDE.md and AGENTS.md.604. Do not delete the original files without the user's explicit confirmation. You may leave them in place or propose archiving them (e.g. under `docs/archive/`), but ask first.6162## Communication style6364Use plain language, explain technical terms in parentheses on first use, and walk through your reasoning step by step rather than presenting only the final result.
Liquidflow-configurator