harness.md
AGENTS.md0 starsChanged 4 days agoApache-2.0View on GitHub
Home of the HARNESS.md format (one file that records a project's agent harness design), the official hub of ready-to-use designs, the website, and harness-md, an Agent Plugins v1.0.0 plugin that designs, builds, extracts, and audits harnesses around that file. The repository root is the plugin. This repository's own design is HARNESS.md: open it only when the harness itself is checked or changed, never for an ordinary task. - English is authoritative. A Chinese mirror (README.zh.md, spec/spec.zh.md, hub/README.zh.md, the site's /zh/…
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 repository27 other files it gives its agents.
- github-project-workflowSkill
- human-writingSkill
- openspec-apply-changeSkill
- openspec-archive-changeSkill
- openspec-exploreSkill
- openspec-proposeSkill
- openspec-sync-specsSkill
- openspec-update-changeSkill
- plugin-developmentSkill
- authority-buildingSkill
- completion-buildingSkill
- entropy-buildingSkill
- environment-buildingSkill
- feedback-buildingSkill
- gates-buildingSkill
- harness-architectureSkill
- harness-auditSkill
- harness-buildSkill
- harness-designSkill
- harness-extractSkill
- harness-mdSkill
- knowledge-buildingSkill
- lightweight-spec-workflowSkill
- openspec-workflowSkill
- project-skill-buildingSkill
- spec-driven-developmentSkill
- spec-kit-workflowSkill
The file
We split this AGENTS.md into the rules it gives an agent
3 rules. About 0 are common, 1 is distinctive, and 2 are 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.
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
- Very specific: line 19
Never hand-edit generated files: .claude-plugin/*, .agents/plugins/marketplace.json (just gen), and .agents/skills/openspec-*/ (openspec …
- Distinctive: line 22
Never weaken a check, hook, workflow, permission, or fixture expectation to make a change pass.
- Very specific: line 35
No filled-in example HARNESS.md in the specification or a skill asset.
≈ “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
harness.md
Home of the HARNESS.md format (one file that records a project's agent
harness design), the official hub of ready-to-use designs, the website, and
harness-md, an Agent Plugins v1.0.0 plugin that designs, builds, extracts,
and audits harnesses around that file. The repository root is the plugin.
This repository's own design is HARNESS.md: open it only when the harness
itself is checked or changed, never for an ordinary task.
Always
- English is authoritative. A Chinese mirror (
README.zh.md,spec/spec.zh.md,hub/README.zh.md, the site's/zh/pages) changes in the same change as its English source. Talk to the user in their language. - A change to the format, a shipped skill, the agent, the hub's entry rules,
or the site's behaviour starts as an OpenSpec change and waits for the
spec:approvedlabel; harness, scripts, CI, docs, a hub entry, and site styling or copy go straight to a pull request. - Never hand-edit generated files:
.claude-plugin/*,.agents/plugins/marketplace.json(just gen), and.agents/skills/openspec-*/(openspec init --tools agents --force). - Never weaken a check, hook, workflow, permission, or fixture expectation to make a change pass; propose that change in its own pull request.
- Commits: Conventional Commits, lowercase imperative subject of at most 50 characters, no AI or tool attribution. One commit per verified task; drafts are squashed before a push and never reach the remote.
- Your own task runs to a ready pull request without asking; spec work
waits for
spec:approved; other outward actions are pending decisions. - Nothing secret or private enters the repository, an issue, or a pull
request:
just publish-checkbefore every push and everyghwrite. - Prose for people (specification, READMEs, site copy) is drafted and
reviewed with the
human-writingskill; text for agents follows.agents/knowledge/skill-quality.md. - Break Markdown lines at punctuation, never inside a word or by width alone.
- No filled-in example
HARNESS.mdin the specification or a skill asset. - Report only what you ran: never call a check passed, a page good-looking, or a skill working in a client without having verified it.
Project Map
spec/spec.md spec/spec.zh.md <- the format, prose; spec/fixtures/ = validator cases
hub/<name>/HARNESS.md <- hub entries; hub/README.md holds the entry rules
plugin.json skills/<name>/ <- the plugin and its skills (scripts: Python + uv)
com.anthropic.claude-code/ <- Claude Code's hand-written agent files
.claude-plugin/ .agents/plugins/ <- generated client manifests
openspec/specs/<domain>/ <- long-lived specs: format, cli, skill, agent, hub, site
scripts/ scripts/lib/ <- management code (TypeScript on Node) and tests
site/ DESIGN.md <- the website (Astro, Pagefind; own pnpm package) and its visual design
.agents/knowledge/ .agents/skills/ <- knowledge files; project skills (.claude/skills links)When To Read What
| Situation | Read |
| Adding, changing, or removing a shipped skill or the agent | the plugin-development skill, then .agents/knowledge/plugin-architecture.md |
Writing or editing any file under skills/; a skill misbehaves | .agents/knowledge/skill-quality.md |
Editing a <!-- shared:… --> block in a skill | .agents/knowledge/shared-blocks.md |
| Changing the format, the prose specification, a validator, or a fixture | .agents/knowledge/format-changes.md |
| Adding or reviewing a hub entry | .agents/knowledge/hub.md |
Editing site/ or its workflow | .agents/knowledge/site.md; DESIGN.md before anything visual |
| A client does not load something; touching a wiring or generated file | .agents/knowledge/client-matrix.md |
| A client or OpenSpec was upgraded; removing a workaround | .agents/knowledge/compatibility-watch.md |
| Proposing, implementing, or archiving an OpenSpec change | .agents/knowledge/spec-workflow.md, then the openspec-* skills |
Taking an issue, opening or finishing a pull request, any gh write | the github-project-workflow skill, .agents/knowledge/github-workflow.md |
| A check is red; adding or renaming a recipe or CI job | .agents/knowledge/github/checks.md |
| Branching, committing, squashing, pushing, tags | .agents/knowledge/git-workflow.md |
| Before any issue, push, comment, label, release; an action was refused | .agents/knowledge/agent-authority.md |
| Before reading or changing a remote setting | .agents/knowledge/github/platform-settings.md |
| Editing this file, a knowledge file, or a check; adding a client; every tenth merged pull request | .agents/knowledge/maintenance.md |
Development Environment
Work in the dev container (.devcontainer/): node, pnpm, uv, just,
pre-commit, betterleaks, openspec, gh, and the client CLIs, which use the
person's own login. Never store a credential in the repository.
Validation
| Check | Command |
| Everything CI runs | just check |
| The fast subset (no openspec, site build, or secret scan) | just check-fast |
| Format, lint, types; unit tests | just lint; just test |
| Generated client files are current | just gen --check (regenerate: just gen) |
| Plugin layout, wiring, one spec per shipped entry | just validate |
| Skill rules: budgets, layers, steps, shared blocks, links, spec copy | just skills-check |
| Harness links, recipes, budget, symlinks, mirrors | just harness-check |
HARNESS.md and hub entries conform; hub entry rules | just harness-md-lint; just hub-check |
Both validators agree with spec/fixtures/ | just fixtures-check |
| Specs strict; no unarchived change (merge gate) | just spec-check; just spec-archived |
| Site checks and static build | just site-check; just site-build |
| Plugin loads in the real clients (local only) | just clients-validate |
| Text or commits about to be published hold no secret or personal data | just publish-check <file>; just publish-check --commits <range> |
Workflow
Issue → gh issue develop branch → draft pull request (carrying the
OpenSpec change when one is needed) → maintainer adds spec:approved →
task commits with just check green → behavioural tests for a skill change
→ self-review, ready → maintainer reviews → archive on the branch →
maintainer squash-merges → version bump and v* tag release.
Keep In Sync
<!-- harness: keep-in-sync -->| When this changes | Update |
plugin.json or an agent file | just gen; commit the generated files |
| A skill or the agent is added, renamed, or removed | its spec under openspec/specs/, both README skill tables, the site's plugin pages, just gen |
| A shared block's canon | every skill using that id, same change |
spec/spec.md | spec/spec.zh.md, skills/harness-md/references/specification.md, the format specs |
| A validator rule | the other validator, spec/fixtures/, openspec/specs/cli/lint/spec.md |
A justfile recipe or CI job | the Validation table above, .agents/knowledge/github/checks.md |
README.md, hub/README.md | their .zh.md mirrors, same change |
| The site's colours, type, spacing, or components | DESIGN.md, same change |
| A client's loading behaviour | .agents/knowledge/client-matrix.md and the watch list |
| Harness intent (a rule here, a check, a permission) | HARNESS.md first, same pull request |
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.

