agent-skills-suite
AGENTS.md0 starsChanged 28 days agoMITView on GitHub
Purpose. Always-loaded contract for agents developing/validating this skill suite and running its per-task pipeline. Precedence (highest first). Host/user instruction and task contract; role rule for permissions; this file for conventions; skill docs for procedure. On conflict, stop and escalate. Authority. Prompt rules are advisory; CI gates, branch protection and CODEOWNERS are authoritative. Skills are self-contained; this file is never a runtime dependency. Safety. Never commit secrets/PII or run destructive commands without explicit confirmation; verify resolved paths before delete/move and never…
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 32,671 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 repository24 other files it gives its agents.
- changeSkill
- convergeSkill
- devSkill
- diagnose-windows-sandbox-aclSkill
- plan-linterSkill
- prd-generatorSkill
- qaSkill
- quality-engineeringSkill
- reviewSkill
- spec-generatorSkill
- task-decompositionSkill
- test-engineeringSkill
- diagnose-windows-sandbox-aclSkill
- changeSkill
- convergeSkill
- devSkill
- plan-linterSkill
- prd-generatorSkill
- qaSkill
- quality-engineeringSkill
- reviewSkill
- spec-generatorSkill
- task-decompositionSkill
- test-engineeringSkill
The file
We split this AGENTS.md into the rules it gives an agent
6 rules. About 0 are common, 4 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
2
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
- Distinctive: line 83
Intent and issue (user-triggered, batched): Do not open an issue or PR for every change or conversation turn.
- Very specific: line 98
Test and evidence before commit: Run targeted tests, then the full suite: python -m unittest discover -s tests/unit -p "test_*.py".
- Very specific: line 105
Commit: Use conventional commits (feat(scope): ..., fix(scope): ..., docs(scope): ..., security(scope): ...).
- Distinctive: line 128
Only when the user says "standard open-source workflow", "git flow", "issue/PR", "commit/push/PR/tag" or equivalent do you open the …
- Distinctive: line 144
Keep this always-loaded summary at most 155 lines.
- Distinctive: line 145
Do not duplicate role permissions, gate details or pinned versions.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 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 — Global Rules for the Agent Skills Suite
Purpose. Always-loaded contract for agents developing/validating this skill suite and running its per-task pipeline.
Precedence (highest first). Host/user instruction and task contract; role rule for permissions; this file for conventions; skill docs for procedure. On conflict, stop and escalate.
Authority. Prompt rules are advisory; CI gates, branch protection and CODEOWNERS are authoritative. Skills are self-contained; this file is never a runtime dependency.
Safety. Never commit secrets/PII or run destructive commands without explicit confirmation; verify resolved paths before delete/move and never modify outside the declared write scope.
1. Repository map
| Path | Purpose |
.agents/skills/ | Canonical skills: SKILL.md, references/, assets/ (incl. CI templates), scripts/ |
skills/workflow/ | Installable mirror; byte-identical to .agents/skills/ |
.agents/rules/ | Role permissions and enforcement model |
tests/unit/ | Black-box tests for skills, tools, templates and distribution |
tools/ | Maintainer helpers (quickstart.py, install_skills.py) |
docs/, tasks/ | Guides/strategy; per-task bundles used by the delivery pipeline |
2. Work types
2.1 Discovery and specification
idea -> PRD (PM + prd-generator) -> ADRs/tech spec (Architect + spec-generator) -> task bundles (Planner + task-decomposition) -> Gate 1 -> Gate 2 -> Dev <-> QA -> Gate 3 -> converge
- PM /
prd-generatorwrites.specs/01-prd.mdand.specs/01-prd/: stableREQ-*/CON-*/NFR-*/FORK-*IDs and#sec-*anchors, with open questions explicit. - Architect /
spec-generatorwrites.specs/adr/*.md,.specs/02-tech-spec.mdand.specs/02-tech-spec/: one ADR per fork,INV-*/#sec-*IDs, no unresolved placeholders. - Four-perspective review, subagents and chain-of-thought are brainstorming techniques; the deliverable is the traceable PRD/spec, not the deliberation itself.
- Handoff is PRD -> spec -> task bundles.
task-decompositionauthors bundles from spec anchors;plan-linteris the Gate 1 validator, not the author; Gate 2reviewchecks semantic alignment. - Bounded brownfield changes use
change: proposal -> one task bundle. They may skip a full PRD but must preserve spec anchors and record deviations;convergewrites confirmed deviations back.
2.2 Per-task delivery
task bundles -> Gate 1 -> Gate 2 -> Dev <-> QA -> Gate 3 -> converge
- Planner writes
01-contract.md(Gherkin +dod.feature_file); Dev writes02-dev-workspace.md; QA writes03-qa-verification.md;04-process.mdis derived and never hand-edited. - Dev and QA share one task branch recorded in
02, nevermain/master; never start Dev without a contract or QA withoutWAITING_FOR_QA, and never merge a red gate. Done =QA_PASSED+ Gate 3 + clean role audit.
2.3 Skill-suite development
Changes to skills, rules, templates, tools, manifests, CI or docs follow §4; use it to improve the suite, not to deliver one task bundle.
3. Roles, gates and single sources of truth
- Role matrix:
enforcement.md#role-matrixis the canonical list of owners, write scopes and read-only areas. Do not duplicate it here; each role follows its.agents/rules/<role>.md. - Gates: Gate 1
plan-lintervalidates contracts/Gherkin feature/anchors/DAG; Gate 2review; Gate 3verification_linter.pyaudits V(G)/MSI/provenance and cross-validates supplied complexity and mutation artifacts; mutation runs pre-merge viamutation_gate.py; RBACrbac_audit.py, branch guardbranch_guard.py; scripts/CI templates live inquality-engineering:.agents/skills/quality-engineering/assets/templates/ci/README.md. - Quality bar: PRD/spec have no unresolved placeholders, stable IDs/anchors and every ADR fork
resolved or explicitly open before decomposition. Code:
V(G) <= 10per function (11-15waiver,>15rejected);Test Cases >= V(G);MSI >= 80%(>= 90%forrisk_level: core); no critical surviving mutant; no fabricated evidence. - Evidence and freshness: current files, commands and tests are the evidence for current behavior. Archived notes explain history only and never establish a current gap; read before claiming.
- Task bundles and Goldilocks:
01Planner contract,02Dev handoff,03QA evidence/verdict,04derived and tooling-owned;task_idin01equals the directory name. Default 1–3 touched files and 50–250 estimated diff lines; split larger work and merge smaller work.
4. Skill change workflow (authoring -> optimization -> tests -> git flow)
This section applies when changing the suite itself (SKILL.md, references/, assets, scripts,
rules, templates, manifests, CI or docs). It does not replace §2.2. Principles: small, reviewable,
reversible; evidence over claims; one writer per file; no bypassed gates.
- Intent and issue (user-triggered, batched). Do not open an issue or PR for every change or conversation turn. Accumulate related fixes and open one issue/PR when the user asks or the work is release-worthy; that issue may cover several fixes from the same development effort. Behavior, security, gate or CI changes still need a problem statement, acceptance criteria, test plan and risk in that issue (or in the PR when the user skips the issue).
- Branch and write scope. Branch from an up-to-date
mainusingfeat/<topic>,fix/<topic>,docs/<topic>,chore/<topic>orsecurity/<topic>. Keep one coherent workstream per branch; related fixes may share it. Never commit directly tomain. Parallel agents must use disjoint write scopes; the Lead integrates and reviews, and two agents must not edit the same file. - Author or optimize. Edit canonical
.agents/skills/<name>/and the byte-identical mirrorskills/workflow/<name>/; keepSKILL.mdunder 200 lines, canonical English, self-contained; put detail inreferences//assets/; keep templates token-free where Gate 1 scans them. Compose with other skills by name, never by copying their scripts or a barescripts/...path. Update the role rule, docs,metadata.version,CHANGELOG.md,VERSIONand plugin manifests for behavior changes; document breaking changes and migration. Never weaken a gate, test or boundary. - Test and evidence before commit. Run targeted tests, then the full suite:
python -m unittest discover -s tests/unit -p "test_*.py". Verify dual-tree parity, self-containment, line limits, YAML/JSON parse,git diff --checkand the CI matrix (Ubuntu/Windows, Python 3.9/3.12, plugin manifests). For distribution changes run an install smoke test; for manifest changes runclaude plugin validate .when available. CI is authoritative: local tests are necessary but not sufficient. Never delete, skip or weaken a test, and never use|| true/continue-on-errorto hide a failure. - Commit. Use conventional commits (
feat(scope): ...,fix(scope): ...,docs(scope): ...,security(scope): ...). Keep commits atomic; stage only intended files; never commit secrets, credentials, generated caches or unrelated reformatting. - Pull request and review (when triggered). Push the branch and open a PR against
mainusing the PR template:Closes #<issue>, summary, test evidence, risk/rollback, release/tag plan. Required checks must be green; behavior/security/gate/CI changes need an independent reviewer (CODEOWNERS/branch protection where configured). Docs-only changes may self-merge when permitted. - Merge, sync and post-merge verification. Merge only with required checks and review complete;
do not force-push a reviewed branch; delete the branch and
git switch main && git pull --ff-only. Watch post-merge CI; ifmainis red, fix forward with a new PR or revert with a PR. - Tag and release (SemVer). Release only from merged
main. Breaking -> major, feature -> minor, fix -> patch; docs/chore only when user-visible or bundled with a release. UpdateVERSION,CHANGELOG.md, plugin manifests and skill metadata, create an annotatedvX.Y.Ztag (sign it if required), push it, and verify the release workflow, assets, GitHub release and install smoke. Never move or delete a published tag; a bad release gets a new patch release. - Definition of done. Issue/PR linked when one was opened; tests and CI green; independent review where required; mirrors byte-identical; docs, version, changelog and manifests agree; PR merged; post-merge CI watched; tag/release verified when released; rollback path documented.
- Prohibited shortcuts. Direct commits to
main; force-pushing shared branches; bypassing required checks (|| true,continue-on-error,[skip ci]on required gates); deleting or skipping tests; editing only one tree; committing secrets; self-approving behavior/security/gate changes; tagging before merge; moving published tags; declaring done without evidence.
Only when the user says "standard open-source workflow", "git flow", "issue/PR", "commit/push/PR/tag" or equivalent do you open the issue/PR and execute this section without asking again. Otherwise work and commit locally; never create issues or PRs on your own initiative.
5. Commands
python -m unittest discover -s tests/unit -p "test_*.py"
python -m compileall -q .agents tools
python tools/gen_manifest.py --check # tracked-file SHA-256 manifest
claude plugin validate . # when manifests change; optional if unavailable
python tools/quickstart.py --target .tmp-smoke --dry-run # distribution smoke
git diff --check6. Maintaining this file
- Keep this always-loaded summary at most 155 lines; move detail to the source of truth linked above.
- Do not duplicate role permissions, gate details or pinned versions; changes need a docs PR, the workflow guard tests and §4 review. If this conflicts with a role rule, the role rule wins.
References
enforcement.md— canonical role matrix and enforcement model.skills/README.md— skill index, discovery and per-skill contract.quality-engineeringCI guide — bundled gates, stack profiles and four-stage pipeline.CONTRIBUTING.md— contributor setup, tests and PR conventions.docs/README.md— user-facing docs index;docs/archive/— historical notes.docs/skills-guide.zh-CN.md— usage walkthrough.
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.

