Stop Re-explaining Your Project to AI Coding Agents: Distill Session Lessons into AGENTS.md

It's Monday. You tell your AI coding agent: "this project uses pnpm, not npm." By Wednesday, a fresh session runs npm install again. Your corrections live in dozens of session logs; switch machines or switch tools and they're gone. Ask the AI to write a project conventions file instead, and you get a 500-line "best practices" dump — half common sense, half commands that were never run. The fatter the file, the more selectively the model reads it.

agentsmd-skill is built for exactly these moments: it distills the lessons from your current session into one-line, executable rules in an AGENTS.md file at your project root. Every new session — Claude Code, Codex, Cursor — reads it before starting work. It holds four hard lines: one rule says one thing, the whole file stays under 120 lines, every command is actually run before being written, and every change waits for your approval.

This post walks through five real scenarios — when to use it and how.

1. The same pitfall, re-discovered every session

The classic case. In this session you corrected the AI three times: tests need a local database running first, the deploy script must never touch main, read logs with pnpm logs. Next session, it does all three wrong again.

At the end of the session, say:

Distill this session's lessons into project rules

It runs a fixed pipeline. Collect: only mistakes you pointed out, pitfalls actually hit, and preferences repeated twice or more count — one-off details and common sense are excluded up front. Distill: generalize, compress to one line, route to the right section, and pass three gates — "will recur", "violating it costs something", "fits in one line". Fail any gate, drop the rule. Merge: compare against existing rules — duplicates are discarded, overlaps merged, conflicts resolved in favor of the newer. Approve: the full change plan is shown to you; nothing is written until you approve.

2. Your AGENTS.md is already a junk drawer

Four hundred lines of mutually contradicting rules, half of them common sense? The model reading it is functionally reading nothing.

Same one-liner:

Update project rules: merge this session's lessons via the merge decision table; over 120 lines, cut before adding

It merges organically rather than appending: five gates (drop equivalents / merge overlaps / replace special cases with their general version / resolve conflicts toward the newer / delete outdated) filter everything, and as the file nears the 120-line hard cap it cuts before it adds. Content that still has value but doesn't clear the bar — say, rarely-used operational details — moves to docs/<topic>.md with a one-line reference left in the root file. What gets deleted is redundancy, not memory.

3. Cold start: you want a spec that actually runs

New project, no AGENTS.md yet. You want a first version that grows out of the directory structure, README, and build config — not a template with blanks.

No AGENTS.md yet — generate a first version with agentsmd; verify every command by actually running it

The difference here is command verification: every build and test command is executed for real before being written. Commands that can't safely run — deploys, migrations — are cross-checked line by line against package.json scripts, the Makefile, and CI config; anything that doesn't match doesn't get written. Why so stubborn? Because this file is trusted context for the agent: one hallucinated command is more dangerous than ten missing rules — the agent will believe it and run it.

4. A directory with no code, only documents and data

Report libraries, writing collaboration folders, data workspaces — there's no package.json, so "build commands" and "lint rules" are meaningless sections. What actually needs governing is data definitions, naming and archiving conventions, delivery review.

Settle working rules for this collaboration directory, and gather the scattered reports, data, and reference material

Before starting, it classifies the project as coding or work. Work-mode scans the document structure and naming conventions; rules lean toward data definitions, archiving, and delivery. Gathering moves documents into docs/, machine-readable data into data/, reference material into references/ — after checking references project-wide first, leaving cited files in place, and fixing links after every move. And every move requires your approval.

5. Your agent has personal memory, but it's disconnected from the project

Personal agents with memory systems (Hermes, OpenClaw) accumulate entries that drift away from specific projects: which project does this lesson belong to? Still valid here next week?

The low-effort move is to fold it into the same request:

Write the lessons into AGENTS.md, and gather the documents and data scattered in the root

It doesn't invent a private memory format — it rides the host. If your agent has a memory system, project-level memory is persisted in the host's own format, deduplicated and written only after approval; no memory system, it silently skips. TODO and CHANGELOG get updated along the way. Wherever it's installed, it grows into that agent's shape.

Install

# Option 1: skills CLI (recommended; one-liner updates later) npx skills add kelegele/agentsmd-skill npx skills update agentsmd # Option 2: git clone into your skills dir (project-level: .claude/skills/agentsmd) git clone https://github.com/kelegele/agentsmd-skill.git ~/.claude/skills/agentsmd git -C ~/.claude/skills/agentsmd pull # Option 3: install nothing — hand the repo URL to your agent: # "Install this skill for me: https://github.com/kelegele/agentsmd-skill" 

Also listed on ClawHub (clawhub install agentsmd) and the LobeHub Skills Marketplace. Some agents need a restart or a fresh session to pick it up. AGENTS.md itself follows the open spec — Claude Code, Codex, Cursor, and Gemini CLI all read the same file.

Three quick answers

Will it stuff the file with generic filler? No — piling up common sense to look productive is an explicit ban, and one-off details are filtered at the collection stage.

Will the file grow forever? No. 120-line hard cap, appending is forbidden, cuts come first; valuable detail migrates to docs/ with a one-line reference.

Will it touch files without asking? No. Rules file, memory, progress files, document moves — all come back to you as a complete plan before anything executes.

Start small

Pick a project where you keep correcting the same mistakes. Install the skill, end your next session with one sentence, and read the change plan it hands you — what enters, what merges, what gets cut, and why each rule reads the way it does. You'll know within one review whether this is your kind of tool.

Repo on GitHub; issues and ideas welcome. If you want the design reasoning, I wrote about why 120 lines beats 500, and how four of my design assumptions got falsified in two months.