بِسْمِ ٱللَّهِ ٱلرَّحْمَـٰنِ ٱلرَّحِيمِ
AGENTS.md for every project
One block of rules that skillmirror keeps the same in every project, with your own notes below it that it never touches.
An agent that opens a project reads its AGENTS.md first. skillmirror writes the part of that file that should be the same everywhere, and leaves the rest to the project.
What is in the file
The file has two parts. The first is a block that skillmirror owns. It is marked as autogenerated, and it ends with a line that says so in plain words. Everything below the block belongs to the project.
<!-- skillmirror:autogenerated begin checksum=9ff979c83bfb88a3; do not edit inside this block, edit project-files/AGENTS.md in the vault and run: skillmirror agents sync -->
# Coding related
1. If you start fresh, read the doc start skills (`doc-start`). They will inshallah tell you how to read the doc start md file.
2. If you see that you need to make big changes, use the coding skills (`coding`) and the file-tree optimization skills (`file-tree-optimization`), and suggest a file tree to maintain/optimize code readability and scalability.
3. No soft fallbacks. We prefer hard errors with very descriptive error messages. They inshallah help to debug quickly.
4. Short and to-the-point comments are helpful. They help others understand decisions (user defined, performance, etc.).
5. Don't use AI agents unless the user asks for them.
---
*Managed by skillmirror. Everything above this line can be updated automatically, so please change only what comes below it.*
<!-- skillmirror:autogenerated end -->
## Notes for this project
The API is versioned in the URL.The checksum in the first line is how skillmirror tells two cases apart: a block that is out of date because the text changed, and a block that somebody edited by hand. A file is written the way a skill is: built beside the old one and swapped in at once. An edit made while a plan waited is kept, and a link is never written through.
Where the text comes from
The text lives in your vault, in a folder for files that go into every project: ~/skills/project-files/AGENTS.md. That folder holds no SKILL.md, so sync and push never take it for a skill. A file called AGENTS.md at the root of the vault is the vault's own and is never read.
Without a file there, five built-in rules for coding agents are used. agents seed writes them into the vault so that you can edit them:
skillmirror agents seedWrote the built-in text to ~/skills/project-files/AGENTS.md
Edit it there and commit it in the vault. Then `skillmirror agents sync` puts it into the projects: only the managed block of each AGENTS.md changes.seed never overwrites. Run it a second time and it stops:
skillmirror agents seederror: ~/skills/project-files/AGENTS.md already exists
hint: edit ~/skills/project-files/AGENTS.md and run `skillmirror agents sync`; to start again from the built-in text, move it away firstCommit the file in the vault, like any change there.
See where the projects stand
skillmirror agents statustext: ~/skills/project-files/AGENTS.md
~ ~/projects/atlas-api missing
~ ~/projects/docs-site missing
~ ~/projects/infra missing
~ ~/projects/lumen-app outdated
0 current, 1 outdated, 3 without AGENTS.md in 4 projects
`skillmirror agents sync` updates the blocks that are out of date.
`skillmirror agents add --project DIR` makes the file or puts the block in.The first line names the text in use: your file, or the built-in text. status writes nothing. It exits 1 when some project is not current, and --all also lists the ones that are. The plain skillmirror status ends with a line about AGENTS.md when blocks are behind or were edited.
| State | What it means | What brings it in step |
|---|---|---|
current | the block holds the text | nothing to do |
outdated | the block is what skillmirror wrote before, and the text changed since | agents sync |
edited | somebody changed the block by hand | read the lines, then agents sync --force |
missing | the project has no AGENTS.md | agents add |
no block | the file exists and is all the project's own | agents add puts the block in front |
broken | the markers do not make one block, and the output says why | fix the file by hand |
problem | the file cannot be used: a link, not a regular file, above 1 MiB, not UTF-8 | fix the file by hand |
Change the rules everywhere
Edit the text in the vault, commit it, and let agents sync carry it into the projects. The vault's file is a plain file, so a rule is one line:
echo '6. Run the tests before you say a change is done.' >> ~/skills/project-files/AGENTS.md
git -C ~/skills commit -am "agents text: tests"
skillmirror agents sync --diff --dry-runtext: ~/skills/project-files/AGENTS.md
+ ~/projects/lumen-app update
1 to change, 0 unchanged, 3 not for this command
● ~/projects/lumen-app/AGENTS.md
--- AGENTS.md now
+++ AGENTS.md after
@@ -1,4 +1,4 @@
-<!-- skillmirror:autogenerated begin checksum=610aa9c238f204f2; do not edit inside this block, edit project-files/AGENTS.md in the vault and run: skillmirror agents sync -->
+<!-- skillmirror:autogenerated begin checksum=9ff979c83bfb88a3; do not edit inside this block, edit project-files/AGENTS.md in the vault and run: skillmirror agents sync -->
# Coding related
1. If you start fresh, read the doc start skills (`doc-start`). They will inshallah tell you how to read the doc start md file.
@@ -6,6 +6,7 @@
3. No soft fallbacks. We prefer hard errors with very descriptive error messages. They inshallah help to debug quickly.
4. Short and to-the-point comments are helpful. They help others understand decisions (user defined, performance, etc.).
5. Don't use AI agents unless the user asks for them.
+6. Run the tests before you say a change is done.
---
agents sync only touches a file that already has a block, so the three projects without a file are "not for this command". --diff shows the lines that change in each file, --dry-run stops before writing. Run it without --dry-run to write:
skillmirror agents sync --yestext: ~/skills/project-files/AGENTS.md
+ ~/projects/lumen-app updated
1 changed, 0 unchanged, 3 not for this command
Backup: run 20261103-224315-612-22025-0 (undo with: skillmirror undo)The old file goes to the backup, like a skill folder does, so skillmirror undo brings it back.
Add the file to a project
agents add makes an AGENTS.md where a project has none, and puts the block in front of a file that has none. It works on one project, the current folder unless you pass --project.
skillmirror agents add --project ~/projects/atlas-api --yestext: ~/skills/project-files/AGENTS.md
+ ~/projects/atlas-api created
1 changed, 0 unchanged
Backup: run 20261103-224315-647-22107-0 (undo with: skillmirror undo)A project that wrote its own file before skillmirror gets the block above its text, and its text stays as it was. The orbit project of the sandbox world is one of those:
skillmirror agents add --project ~/projects/orbit --dry-run --difftext: ~/skills/project-files/AGENTS.md
+ ~/projects/orbit insert
1 to change, 0 unchanged
● ~/projects/orbit/AGENTS.md
--- AGENTS.md now
+++ AGENTS.md after
@@ -1,3 +1,18 @@
+<!-- skillmirror:autogenerated begin checksum=146608cead48142b; do not edit inside this block, edit project-files/AGENTS.md in the vault and run: skillmirror agents sync -->
+# Coding related
+
+1. If you start fresh, read the doc start skills (`doc-start`).
+2. When you start coding, read the `coding` skill first.
+3. No soft fallbacks. We prefer hard errors with very descriptive error messages.
+4. Short and to-the-point comments are helpful.
+5. Don't use AI agents unless the user asks for them.
+6. Run the tests before you say a change is done.
+
+---
+
+*Managed by skillmirror. Everything above this line can be updated automatically, so please change only what comes below it.*
+<!-- skillmirror:autogenerated end -->
+
# orbit
This project wrote its own AGENTS.md before skillmirror: no autogenerated block yet.skillmirror init makes the file for a new project too, and init --no-agents-md leaves it out (Start a project).
A block that was edited by hand
The block is not the place for a project's own rules, and sync says so when somebody put them there. It stops for that project and changes nothing:
skillmirror agents sync --project ~/projects/infra --dry-runtext: ~/skills/project-files/AGENTS.md
✗ ~/projects/infra failed: the autogenerated block was edited by hand; --force replaces it (the old file is kept for `undo`)
0 to change, 0 unchanged, 1 failedThe exit code is 4: the command ran, and one project failed. Read what --force would throw away before you use it:
skillmirror agents sync --project ~/projects/infra --force --dry-run --difftext: ~/skills/project-files/AGENTS.md
+ ~/projects/infra update
1 to change, 0 unchanged
● ~/projects/infra/AGENTS.md
--- AGENTS.md now
+++ AGENTS.md after
@@ -3,7 +3,7 @@
1. If you start fresh, read the doc start skills (`doc-start`).
2. When you start coding, read the `coding` skill first.
-3. No fallbacks at all. We prefer hard errors with very descriptive error messages.
+3. No soft fallbacks. We prefer hard errors with very descriptive error messages.
4. Short and to-the-point comments are helpful.
5. Don't use AI agents unless the user asks for them.
6. Run the tests before you say a change is done.When the edit is a rule that every project should have, move it into the vault's text first, so that the next sync carries it everywhere. When it is only for this project, move it below the block.
The skills the text names
The built-in text names three skills: doc-start, coding and file-tree-optimization. A project that would not have them gets no file from init or agents add, and the command stops before it writes anything:
skillmirror init ~/projects/orbit --no-mandatory --no-scaffold astro --dry-runerror: the AGENTS.md text names the skills doc-start, coding, file-tree-optimization, which ~/projects/orbit would not have
hint: make them mandatory (`skillmirror mandatory add doc-start coding file-tree-optimization`), name them as skills, or leave AGENTS.md out (`--no-agents-md`)A text of your own in the vault is not checked, so it can name any skills, or none. skillmirror doctor checks that the text can be read.
In the interface
The Agents entry of the interface lists every project with the state of its file. The ones whose block is out of date are ticked. You pick, read the changes with v, confirm, and only the blocks are written.