upsert-agents-md
Skill4 starsChanged 6 months agoMITView on GitHub
Creates or updates agent instruction files (AGENTS.md, CLAUDE.md) by surveying the repository and generating accurate, current, agent-friendly guidance. Use when the user wants to generate, create, write, update, refresh, or regenerate an AGENTS.md or CLAUDE.md for a repository. TRIGGER when: user asks to create, generate, write, update, or refresh an AGENTS.md, CLAUDE.md, or agent instruction file. DO NOT TRIGGER when: user asks to review, audit, check, or evaluate an existing agent instruction file (use review-agents-md instead).
- Reads credentials
In this repository13 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- audit-skillsSkill
- create-commitSkill
- format-review-commentsSkill
- implement-planSkill
- refine-proseSkill
- review-agents-mdSkill
- review-planSkill
- review-prSkill
- review-skillSkill
- upsert-planSkill
- upsert-skillSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
21 rules. About 0 are common, 12 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈12
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 36
Use Glob to locate all matches.
- Distinctive: line 38
Exactly one file found: use it as the target (update mode).
- Distinctive: line 40
No files found: default to AGENTS.md at the worktree root (create mode).
- Distinctive: line 49
Read README.md if it exists — extract a one-line purpose statement and any key domain details
- Very specific: line 50
Check package.json, pyproject.toml, Cargo.toml, or equivalent for project name, version, and language
- Very specific: line 53
Run Glob with /* (or equivalent) limited to depth 2–3 to produce a representative layout
- Distinctive: line 63
Run git remote get-url origin to confirm the remote
- Distinctive: line 64
Run git branch -a to identify the default branch and any documented branch naming conventions
- Very specific: line 65
Check for CHANGELOG.md, .github/, or commit-lint config
- Very specific: line 68
Check for package.json scripts, Makefile, shell scripts in scripts/ or bin/
- Very specific: line 70
Check .env.example or docs for required environment variables
- Distinctive: line 74
Check for destructive scripts that require confirmation
- Very specific: line 77
Check for .eslintrc, .prettierrc, ruff.toml, .editorconfig, or style docs
- Distinctive: line 84
Where information belongs: Before writing each section, decide whether the content belongs in the agent instruction file at all.
- Distinctive: line 112
Document: secrets management rules, any off-limits destructive operations, and confirmation requirements for destructive scripts.
- Distinctive: line 119
Before self-reviewing, walk the draft section-by-section and prune duplicated prose.
- Distinctive: line 126
After this pass, every retained paragraph should answer *"what should an agent prefer, avoid, or uphold?"* rather than *"how does this …
- Very specific: line 130
Before presenting, check the draft against the review-agents-md checklist dimensions silently:
- Distinctive: line 149
After confirmation, write the file to the target path.
- Very specific: line 153
Run the review-agents-md skill on the file just written.
- Distinctive: line 157
Commit with an appropriate message:
≈ “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
Upsert AGENTS.md
Creates or updates agent instruction files by surveying the actual repository and generating accurate, agent-friendly guidance.
Instructions
1. Determine mode and target file
Mode — if the target file already exists, this is update mode; otherwise create mode.
Target file — if the user provides a filename argument (e.g. /upsert-agents-md CLAUDE.md), use that path. Otherwise, search the repository for existing agent instruction files:
AGENTS.md(worktree root)CLAUDE.md(worktree root or.claude/CLAUDE.md)CURSOR.md(worktree root).github/copilot-instructions.md.cursorrules
Use Glob to locate all matches.
- Exactly one file found: use it as the target (update mode).
- Multiple files found: list each path and ask the user which to update.
- No files found: default to
AGENTS.mdat the worktree root (create mode).
In update mode, read the full contents of the existing file before continuing. Note any intentional customizations (non-standard sections, hand-written prose) to preserve them.
2. Survey the repository
Gather the information needed to write accurate guidance. Work through each area below.
Repository purpose and metadata
- Read
README.mdif it exists — extract a one-line purpose statement and any key domain details - Check
package.json,pyproject.toml,Cargo.toml, or equivalent for project name, version, and language
Directory structure
- Run
Globwith**/*(or equivalent) limited to depth 2–3 to produce a representative layout - Identify key directories: source, tests, scripts, config, docs
- Note any standard conventions (e.g.
src/,.agents/skills/,.github/)
Skills (if .agents/skills/ exists)
- Glob
.agents/skills/*/SKILL.md - For each skill, read the frontmatter
nameand first sentence ofdescription - Build the skills table from this data — do not invent entries
Git workflow
- Run
git remote get-url originto confirm the remote - Run
git branch -ato identify the default branch and any documented branch naming conventions - Check for
CHANGELOG.md,.github/, or commit-lint config
Tooling and environment
- Check for
package.jsonscripts,Makefile, shell scripts inscripts/orbin/ - Identify CLI tools the agent must have: note only tools actually referenced in the repo
- Check
.env.exampleor docs for required environment variables
Security constraints
- Note any secrets-scanning config (
.gitleaks.toml,.pre-commit-config.yaml) - Check for destructive scripts that require confirmation
Coding conventions
- Check for
.eslintrc,.prettierrc,ruff.toml,.editorconfig, or style docs - Note language(s), formatting rules, and test commands
3. Draft the agent instruction file
Produce a Markdown document with these sections. Include only sections for which you found actual content — do not add placeholder sections. In update mode, preserve any existing section that is not stale; replace or augment sections where the survey found newer information.
Where information belongs. Before writing each section, decide whether the content belongs in the agent instruction file at all. Use this heuristic:
| Content type | Home |
| How a module works, callback contracts, struct fields, type signatures | In-source documentation (docstrings, doc comments, header blocks) |
| User-facing setup, installation, and workflow | README.md |
| Agent decision rules — what to prefer, what to avoid, invariants to uphold | AGENTS.md (this file) |
For every paragraph or table you are about to write, ask: could a future agent find this by reading the relevant code or README.md? If yes, emit a one-line pointer (e.g. "See Retcon.Message for the atom/string key contract.") instead of repeating the prose. If no, emit the full explanation — it has no other home.
Do not duplicate in-source documentation in the agent instruction file. Implementation details belong next to the code (in docstrings, doc comments, or whatever each language uses); agent decision rules belong here. Duplicated prose creates two places to keep in sync on every refactor and crowds out the decision rules that justify this file's existence.
Repository Purpose (required)
One short paragraph stating what the repository does and who it is for. Write for an agent, not a human reader.
Structure (required)
A fenced code block with an annotated directory tree. Include only paths that actually exist. Annotate each entry with a brief purpose comment.
Available Skills (include only if .agents/skills/ exists)
A Markdown table with columns Skill, Trigger, and Purpose. Populate from the survey; do not invent rows.
Git Workflow (required)
Cover: default branch name, feature branch naming convention, commit message format (with examples), and PR process. Be explicit — state exact formats, not vague guidance.
Code Style & Conventions (include if conventions were found)
List formatting rules, language-specific style constraints, and test commands. Use imperative phrasing agents can follow directly.
Security (required)
Document: secrets management rules, any off-limits destructive operations, and confirmation requirements for destructive scripts. If no constraints were found beyond standard hygiene, include a minimal section noting "Never commit secrets or credentials."
Environment (include if tools or env vars are required)
List required CLI tools and environment variables. For each, note what it is used for and where to obtain it.
4. Leanness pass
Before self-reviewing, walk the draft section-by-section and prune duplicated prose. For each paragraph, table, or list:
- Locate the canonical home. For module behavior, callback contracts, struct fields, type signatures, or function semantics, open the relevant source file and check its in-source documentation — whichever convention the language uses (docstrings, doc comments, top-of-file headers, or equivalent). For setup, installation, or workflow narrative, check
README.md. - If the canonical home already covers it: replace the section's prose with a one-line pointer naming the file or module — e.g. "See
Retcon.Messagefor the atom/string key contract." or "SeeREADME.md§ Installation for setup." Do not also restate the content. - If the canonical home is missing or thin: the agent instruction file is not the right place to fix that. Note the gap to the user when presenting the draft (step 6) so they can update the code docs or README, but keep this file lean.
- Keep what only belongs here: agent decision rules, preferences, invariants, branch and commit conventions, and explicit do/do-not guidance — these have no other canonical home.
After this pass, every retained paragraph should answer "what should an agent prefer, avoid, or uphold?" rather than "how does this module work?"
5. Self-review
Before presenting, check the draft against the review-agents-md checklist dimensions silently:
- Completeness — required sections present?
- Accuracy — all paths, branch names, and tool names verified against the actual repo?
- Agent-friendliness — instructions are explicit and imperative, not vague?
- Freshness — no stale references; skills table matches actual skill directories?
- Scope coherence — focused on agent guidance, no README/CHANGELOG duplication?
- Leanness — no section mirrors in-source documentation verbatim; duplicated prose has been replaced with pointers?
Fix any issues found before presenting.
6. Present the draft
State whether this is create mode (new file) or update mode (file path will be updated). Show the full draft and ask for confirmation before writing.
In update mode, also briefly describe what changed relative to the existing file: sections added, revised, or preserved.
7. Write the file
After confirmation, write the file to the target path. In update mode, overwrite the existing file entirely with the approved content.
8. Validate with review-agents-md
Run the review-agents-md skill on the file just written. If it surfaces any issue [blocking] findings, address them immediately and re-write the file. Surface suggestion findings to the user as follow-up opportunities; do not block.
9. Commit
Commit with an appropriate message:
- Create mode:
docs: add AGENTS.md - Update mode:
docs: update AGENTS.md(or the target filename)
Examples
Create AGENTS.md from scratch:
/upsert-agents-mdFinds no existing agent instruction file, surveys the repo, generates AGENTS.md, presents it for review, writes it, validates, and commits.
Update an existing CLAUDE.md:
/upsert-agents-md CLAUDE.mdReads the existing CLAUDE.md, surveys the repo for changes, produces an updated draft, presents the diff summary, writes on confirmation, and validates.
Auto-detect and update:
/upsert-agents-mdFinds AGENTS.md in the worktree root, enters update mode automatically.
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.

