Agentsmd Skill
Distill session lessons into a lean AGENTS.md (create or update), following the open agents.md spec: collect lessons, distill them into one-line rules, organically merge, verify every command, and write only after user approval. Adapts to coding and work (non-code collaboration directory) scenarios; syncs project memory and progress/status records; collects scattered docs and data (fixed buckets for coding, work-type-fitted taxonomy for work). Trigger on requests like "write the lessons into AGENTS.md", "solidify this session's pitfalls into project rules", "update project guidelines", "organize project docs and data" — 中文触发词:「总结经验/教训写进 AGENTS.md」「把这次踩的坑固化成项目规则」「更新项目规范」「整理项目文档与数据」「沉淀项目协作规范」「文档归档到 docs」。All file changes require user confirmation first.
Lessons To AGENTS.md
Goal
Turn one-off lessons into a small set of durable, reusable, executable rules in the project root's AGENTS.md. Four iron rules:
- Concise: every rule is one line, imperative, directly executable. No narrative, no explanatory paragraphs.
- Compliant: structure follows the open agents.md spec (see
references/agents-md-spec.md) — pure Markdown, standard sections, written for AI coding agents. - No bloat:
AGENTS.mdis organic consolidation, not an append-only log. Hard cap 120 lines (excluding blank lines); near the cap you must delete before adding. Content that still has long-term value but fails the root-file admission bar moves todocs/with a one-line reference (see Step 4). Rules that lost generality, were superseded, or duplicate others get deleted or merged. - Confirm before writing: every write — updating
AGENTS.md, agent memory, progress/status files, moving collected files — must be shown to the user and approved first. Without approval, propose only; touch nothing.
Workflow
Step 1 Collect lessons
Extract lessons from this session/task:
- Errors, corrections, and rework the user explicitly pointed out (highest priority)
- Pitfalls actually hit: errors, environment issues, wrong approaches
- User preferences that repeated (2+ occurrences; a single occurrence doesn't count)
- Approaches that were validated to work
Exclude: one-off task details, temporary paths/parameters, obvious common sense, unverified guesses.
Step 2 Distill rules
Process each lesson in three passes:
- Generalize: raise the specific case into a general rule. "Wrong path alias in tsconfig.json broke the build" → "Run
npm run buildafter changing path aliases". - Compress: one rule per line, format
- do X (reason ≤ half a line if needed). Example:- Commits must pass lint and tests; CI blocks non-compliant commits. - Classify: put it in the closest section (see the template's standard and optional sections). Only create a new section when nothing fits, and keep total sections ≤ 9.
Admission bar: a rule must pass all three — (a) likely to recur; (b) violating it causes real loss (rework/bugs/wasted time); (c) expressible in one line. Miss any one, discard.
Step 3 Read current state
- First detect the scenario: coding or work (a non-code collaboration directory). Later steps follow the matching column in Scenario Adaptation.
- Check whether
AGENTS.mdexists in the project root. - Exists: read it fully and build a list of existing rules (enumerate every one).
- Missing: build project understanding yourself, then generate the first
AGENTS.md:- Scan project structure, README, build/dependency configs (
package.json/pyproject.toml/Makefile/*.csproj…), and CI configs to identify the stack, package manager, build and test commands. - Combine with this session's lessons and generate the first version per the agents.md spec (skeleton:
assets/AGENTS-template.md; granularity benchmark:assets/AGENTS-example.md). Omit standard/optional sections that don't apply — never leave empty placeholder sections. Keep section names in English (community convention); entry language follows the project's dominant language. - Command verification: every command written in the first version must be verified — run build/test/lint commands for real; commands impractical to run (deploy, migrations) must be cross-checked against
package.jsonscripts /Makefile/ CI configs for existence and exact spelling. Never write a command that fails or can't be verified. - Apply Step 2's admission bar and concision rules to the first version too. Piling up generic common sense "to look complete" is forbidden.
- Scan project structure, README, build/dependency configs (
Step 4 Organic merge (core)
For each new rule, compare against every existing rule and do exactly one of the following. Unconditional appending is forbidden:
| Situation | Action |
|---|---|
| Equivalent rule exists | Discard the new rule; touch nothing |
| Partially overlaps | Merge into one more precise/more general statement |
| Is a special case of an existing rule | Replace the existing rule with the general version (one general > three special cases) |
| Contradicts an existing rule | Keep the new one (newer practice), delete the old |
| Existing rule clearly outdated (env/tooling changed) | Delete |
| New and passes the admission bar | Append to the matching section |
Length control:
- After merging, total length (excluding blank lines) ≤ 120 lines. Over the cap, prune in this order: outdated rules → duplicates/mergeable items → low-generality special cases → entries in the least-triggered sections.
- Pruning ≠ always deleting: pruned content that still has long-term reference value but fails the root-file admission bar (background, operational details, low-frequency special cases) moves to
docs/<topic>.md, leaving a one-line reference in place (e.g.- Deployment details: [docs/deploy.md](docs/deploy.md)). Outdated and duplicate content is deleted outright, not migrated. - Reference lines are scarce by design: keep only when truly useful on demand, at most 1–2 per section, so
docs/doesn't bloat the root file indirectly. - Aim for ≤ 8 entries per section; more means the section is accumulating details — converge downward.
Step 5 Confirm and write
- Present the complete change plan to the user (must include):
- Rules to add (verbatim, with target section)
- Rules to merge/replace/delete, with reasons
- Content to migrate to
docs/, target files, and the reference line left in the root file (writingdocs/also requires approval) - Updated total line count and remaining capacity
- Write
AGENTS.mdonly after user approval, using your file-editing tools; leave all other sections untouched. Never write files before approval.
Step 6 Sync memory and progress (conditional)
- Agent memory: if the current agent has a project memory mechanism (memory files/directories, brain, etc.), sync this session's lessons as project memory entries — follow the agent's own memory format, dedupe before writing.
- Progress/status files: if the project tracks progress (TODO.md, CHANGELOG.md, PROGRESS.md, STATUS.md), update the relevant entries for this change.
- Same hard gate: list the files to update and a content summary, and get user approval before writing. No memory mechanism or relevant files → skip silently, don't mention it.
Step 7 Collect docs and data (optional closing)
After AGENTS.md is written, check for scattered output files (not yet grouped by topic, dumped at the top level) and group each by nature:
- Documents (for humans: MD/HTML/PPT/PDF) →
docs/<topic>/ - Data files (machine-readable: CSV/XLSX/JSON/SQL dumps, exported results, datasets) →
data/<topic>/
These two buckets are the defaults for coding scenarios; work scenarios may propose a taxonomy that fits the work type instead (see Scenario Adaptation).
- Check references before proposing: for each candidate file, grep the whole project first (code, scripts, build/CI configs). Referenced files never move — moving breaks things. Files whose nature is unclear (document or data?) get flagged for the user; don't decide for them.
- Scan only, touch nothing: present the list (path, nature, suggested destination) for approval — approve all or pick individually; "keep in place" is always allowed. Exceptions that stay in the root: project config files (
AGENTS.md/CLAUDE.md/skills-lock.json…),README,LICENSE. Never move, rename, or modify any file before the user approves. - Execute after approval: move files → fix every relative-path reference (links in MD/HTML) → grep the whole project to verify no broken links (covering the reference points from step 1) → report the move list and reference fixes.
Section conventions
Prefer the template's standard sections; semantic mapping:
- Build/environment lessons →
Build & Test CommandsorDev Environment Tips - Code style, naming, structure →
Code Style - Workflow constraints (commits, PRs, branches) →
PR / Workflow Instructions - Project-specific recurring pitfalls →
Project-Specific Gotchas
Optional sections only when the project really has that fixed process; same admission bar applies, scarce by design:
- Build artifacts, env config, deploy commands, CI/CD →
Build & Deployment - Secret handling, permission model, security test requirements →
Security Notes - Frequent-error triage paths, log locations, debug entry points →
Debugging & Troubleshooting
Nesting: a lesson that only applies to one subdirectory doesn't go in the root file — suggest a local AGENTS.md in that subdirectory (agents honor the nearest file when working there); the root keeps globally applicable content only.
Scenario adaptation (coding / work)
In Step 3, detect the scenario first. Both share one workflow; only three spots differ:
- Detection: any code-project marker (package.json / pyproject.toml / Makefile / *.csproj / source dirs / CI config) → coding; only documents, spreadsheets, and reference material → work (report libraries, collaboration directories, etc.).
| Aspect | coding | work |
|---|---|---|
| Initial scan & verification | Scan build/dependency/CI configs; run each command or cross-check it | Scan README, directory structure, naming conventions; no commands to verify — instead verify referenced paths exist |
| Section semantics | Build & Test / Code Style / PR rules | Data definitions & source freshness, file naming & archiving, delivery & review process; mostly custom sections, still ≤ 9 total |
| Step 7 collection & references | docs→docs/, data→data/; grep code references | docs/ data/ references/ are defaults only — may propose a type-fitted taxonomy (see below); check MD/HTML relative links and paths inside AGENTS.md |
Work-scenario collection relaxation: the three buckets are defaults, not mandates. Propose top-level folders that fit the work type (e.g. a report library might use reports/, minutes/, drafts/), reusing the directory's existing structure and naming conventions first; deliverables / data drafts / reference material is one suggested dimension, not the only one. The full proposed tree goes into the approval list (flow unchanged), and once approved the taxonomy is recorded in AGENTS.md so later sessions reuse it instead of reinventing it.
Reference resources
references/agents-md-spec.md— key points of the agents.md spec; required reading before creating an AGENTS.md for a project.assets/AGENTS-template.md— section skeleton reference; prune to the project's reality, never keep empty sections that don't apply.assets/AGENTS-example.md— the official agents.md example (pnpm/Turborepo monorepo); use it to calibrate the granularity and density of a good finished file.
About
- Repo & updates: kelegele/agentsmd-skill
- Author site: kelegele.com
- Chinese reference translation: docs/zh-CN/SKILL.md (for human readers; the agent loads this English file)
- Downloads
- Security audit
- Review
- Last updated
- 1d ago
- Current version
- v1.6.0
- License
- MIT-0
