portable-agent-skills
AGENTS.md12 starsChanged 43 days agoApache-2.0View on GitHub
Skills are Markdown that a model obeys. Changing one changes behavior, and most of the guards here fail in ways that do not explain themselves. python3, not python — macOS ships no bare python. On native Windows, py -3. Editing prose fails the build unless you move a number. Every skill has a word count in scripts/skill-budgets.json that must equal what it measures now. Growing past it fails the validator; shrinking below it and leaving the number alone fails a…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,774 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository19 other files it gives its agents.
- clarifySkill
- commitSkill
- cywSkill
- demo-videoSkill
- diff-reviewSkill
- extract-hooksSkill
- handoffSkill
- plan-duelSkill
- plan-initSkill
- plan-init-v1Skill
- plan-phaseSkill
- plan-phase-v1Skill
- plan-runSkill
- plan-run-v1Skill
- review-panelSkill
- security-review-codebaseSkill
- tddSkill
- web-verifySkill
- xcSkill
The file
We split this AGENTS.md into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 18
Editing prose fails the build unless you move a number: Every skill has a word count in scripts/skill-budgets.json that must *equal* what …
- Very specific: line 23
Adding a skill needs two edits nothing discovers: Add it to README's skill table *and* bump the skill count there, and give it an entry in …
- Very specific: line 51
If you were asked to improve a skill you have loaded, you are editing the *installed copy* under ~/.claude/skills/<name>/ or …
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md 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
AGENTS.md
Skills are Markdown that a model obeys. Changing one changes behavior, and most of the guards here fail in ways that do not explain themselves.
Before you finish, run all three
python3 scripts/validate_cross_runtime.py skills/
python3 scripts/validate_cross_runtime.py --test-fixtures tests
python3 -m unittest discover -s tests -p 'test_*.py'python3, not python — macOS ships no bare python. On native Windows, py -3.
Five things that will bite you
Editing prose fails the build unless you move a number. Every skill has a word count in
scripts/skill-budgets.json that must equal what it measures now. Growing past it fails
the validator; shrinking below it and leaving the number alone fails a test. Move the number
in the same change as the prose. Never trim assertions or split a file to duck it.
Adding a skill needs two edits nothing discovers. Add it to README's skill table and
bump the skill count there, and give it an entry in skill-budgets.json. Miss either and
the run fails without saying why.
A skill file may not reference anything outside its own directory. The installer ships
skills/<name>/ alone, so a link to PORTABILITY.md or a path climbing out with ../ is
dead on an installed machine. Do not add a helpful cross-reference to a root document.
The -v1 skills duplicate their current counterparts on purpose. Read the parity ledger
in CONTRIBUTING.md before deduplicating anything. A fix to one side of a mirrored block
lands in its mirror in the same change, and several differences between the two generations
are deliberate rather than drift.
Do not write branded tool names into skill text. No Glob tool, Read tool,
subagent_type, run_in_background. Say what to do — "search for files matching pattern"
— so the same file runs under any runtime. Adapter notes are the one exception.
A green run is not proof
The validator checks the mechanical rules. It does not check hardcoded model names,
autonomous fallbacks on user-prompting steps, or naming both CLAUDE.md and AGENTS.md
when a skill refers to project instruction files. Read for those yourself.
PORTABILITY.md is the authoring contract and closes with the full list of what a green run
does not cover. CONTRIBUTING.md is the procedure.
Editing a skill you are running
If you were asked to improve a skill you have loaded, you are editing the installed copy
under ~/.claude/skills/<name>/ or ~/.agents/skills/<name>/, which git does not track.
Port the change to skills/<name>/SKILL.md here, run the gate above, then python3
install.py to put the reviewed version back.
There is no symlink install, deliberately: a linked install would make the installed path the repo file, and you would be rewriting the instructions you are executing.
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.