dev-skills
AGENTS.md1 starsChanged 4 months agoMITView on GitHub
Instructions for any coding agent working on this repository. CLAUDE.md holds the same essentials plus a Claude-Code-specific blueprint profile; nothing here needs to be read twice. dev-skills is a catalog of 30 Agent Skills — pure markdown, zero runtime dependencies. The only executable code is install.sh (+ its install.cmd Windows launcher), scripts/*.sh, evals/tasks/*/*.sh, and ds-brief/assets/verify-brief.py. Shared references live in core/ and are linked from skills as ../core/<file>.md; the installer ships core/ on every install. The gate needs bash, python3, shellcheck,…
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 repository33 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- ds-backendSkill
- ds-benchmarkSkill
- ds-blueprintSkill
- ds-briefSkill
- ds-buildSkill
- ds-commitSkill
- ds-complianceSkill
- ds-debugSkill
- ds-deploySkill
- ds-depsSkill
- ds-devopsSkill
- ds-docsSkill
- ds-fixSkill
- ds-freezeSkill
- ds-frontendSkill
- ds-initSkill
- ds-issueSkill
- ds-launchSkill
- ds-mobileSkill
- ds-pipelineSkill
- ds-productizeSkill
- ds-prSkill
- ds-qualitySkill
- ds-releaseSkill
- ds-repoSkill
- ds-researchSkill
- ds-reviewSkill
- ds-rigSkill
- ds-shipSkill
- ds-simplifySkill
- ds-testSkill
- ds-tuneSkill
The file
We split this AGENTS.md into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 31
Standalone Invariant: Every skill directory must work when installed alone.
- Very specific: line 42
SKILL-SPEC.mdis authoritative: Every ds-* directory must satisfy it.
≈ “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
Instructions for any coding agent working on this repository. CLAUDE.md holds the same
essentials plus a Claude-Code-specific blueprint profile; nothing here needs to be read twice.
dev-skills is a catalog of 30 Agent Skills — pure markdown, zero runtime dependencies. The
only executable code is install.sh (+ its install.cmd Windows launcher), scripts/*.sh,
evals/tasks/*/*.sh, and ds-brief/assets/verify-brief.py. Shared references live in core/
and are linked from skills as ../core/<file>.md; the installer ships core/ on every install.
Commands
| Task | Command |
| Run the quality gate (do this before every commit) | bash scripts/quality.sh |
| Make the gate run on every commit | bash scripts/quality.sh --install-hook |
| Gate red | Fix what it names, re-run, then commit — the hook is never bypassed |
| Install the skills into a host | ./install.sh (or --target <dir>, --project <dir>, --skills a,b) |
| Install for a Claude-5 host with an always-on rules layer | ./install.sh --profile lean — strips the portable-only-marked blocks at install time; repo files always keep the full portable text |
| Install for Claude Code specifically | ./install.sh --profile claude — lean plus one Claude-only sentence injected into ds-ship's delegation step (delegates run as forked subagents); the repo file stays host-neutral |
| Check an installed copy for drift | ./install.sh --check (profile-aware — reads the profile from the version stamp) |
| See installed vs repo vs upstream at a glance | ./install.sh --status — read-only |
| Update an existing install | ./install.sh --update — git pull --ff-only + re-install with the stamped profile; never merges on your behalf |
The gate needs bash, python3, shellcheck, and typos. A missing tool fails the run loudly
and names what went unverified — never treat a skipped check as a passing one. There is no CI;
this gate is the only enforcement, by design.
Conventions that are not guessable from the code
- Standalone Invariant. Every skill directory must work when installed alone. A skill may not reference another skill's files by path, may not link outside its own directory, and may not cite an in-repo file in prose — a lone install ships one directory. Cross-skill prose handoffs are correct and expected. Enforced by consistency checks 21, 22, 23; point at repo files with a full GitHub URL instead.
- Completion Evidence band appears verbatim at both the top and the bottom of every
SKILL.mdin the repo. Both copies are normative — do not "de-duplicate" them in repo files. The repeat is deliberate: model attention is position-biased, and the portable profile supports six hosts. The lean install profile (--profile lean) strips the closing copy and the other<!-- portable-only -->-marked blocks at install time only (SKILL-SPEC §1). - Size ceilings, both gated:
SKILL.md≤ 500 lines and ≤ 48000 bytes;README.md≤ 80 lines. SKILL-SPEC.mdis authoritative. Everyds-*directory must satisfy it; changing a skill's contract usually means changing the spec and the consistency checks in the same commit.- Counts are mechanically checked.
README.md's badge,CLAUDE.md's skill heading, count line, and flat list must all agree with the actual number ofds-*/directories. - A new check needs a fixture. Checks factored into functions in
scripts/check-consistency.shcarry a self-test that proves they fail on deliberately broken input. Add one with your check. - Conventional Commits, and
feat/fixonly when a user-visible capability changes. Docs, tests, tooling, and CI get their own type. Direct push tomainis the deliberate workflow here.
Gotchas
ds/audit/is gitignored scratch space for skill runs — never commit it, never rely on it.- Editing a skill's contract line (
**Owns:** … **Delegates:** … **Receives:** …) breaks the reciprocity check unless the delegation target names the delegator back. _typos.tomlexists becausetyposotherwise reports ~90 false hits on this repo's domain vocabulary. Add a checked entry rather than silencing the tool.
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.