agent-harness
CLAUDE.md1 starsChanged 4 months agoMITView on GitHub
editing the library itself, not consuming it from a downstream project). agent-harness — Linlin Jia's curated Claude Code configuration library. The library's content (rules, skills, hooks, recommendations, tooling, templates) is meant to be consumed by other projects. This CLAUDE.md governs edits to the library itself. Read these first rather than re-deriving: INVENTORY.md and INVENTORY.zh.md are manually maintained until Phase 9 ships an auto-gen skill. When adding, removing, or renaming a rule/skill/hook/recommendation/template, update both INVENTORY files in the same edit batch…
In this repository5 other files it gives its agents.
- codex/AGENTS.mdAGENTS.md
- new-hookSkill
- new-ruleSkill
- new-skillSkill
- publishSkill
The file
We split this CLAUDE.md into the rules it gives an agent
4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
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
- Distinctive: line 21
Read these first rather than re-deriving:
- Very specific: line 38
Every markdown file starts with # Title, then > One-line purpose., then ## Master TOC.
- Very specific: line 41
Don't break links — when renaming, grep for the old path in INVENTORY.md and other docs.
- Distinctive: line 52
Don't commit unless the user explicitly asks.
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.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
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working on this repository (i.e. editing the library itself, not consuming it from a downstream project).
Master TOC
- Project
- Authoritative references
- Bilingual policy (this repo)
- Structural conventions
- Inventory must stay in sync
- Commits
- Out of scope
Project
agent-harness — Linlin Jia's curated Claude Code configuration library. The library's content (rules, skills, hooks, recommendations, tooling, templates) is meant to be consumed by other projects. This CLAUDE.md governs edits to the library itself.
Authoritative references
Read these first rather than re-deriving:
docs/PHILOSOPHY.md— the why behind every rule/hook/skill we shipdocs/CONTRIBUTING.md— how to add a new rule, skill, hook, recommendation, or templatedocs/CONSUMPTION.md— the three downstream consumption modes the library supportsINVENTORY.md— the master index; must stay in sync with the actual filesystem state- Each
rules/<name>/RULE.mdandskills/<bucket>/<name>/SKILL.mdis canonical for that item
Bilingual policy (this repo)
- Top-level docs (
README,INVENTORY,docs/PHILOSOPHY,docs/CONSUMPTION) ship asNAME.md(English, canonical) +NAME.zh.md(Chinese mirror), with a header line:> **Language:** English | [中文](NAME.zh.md)(or the mirror). - Content modules (
RULE.md,SKILL.md,hooks/*/README.md,docs/CONTRIBUTING.md, etc.) stay English only — Claude is the primary reader. - Adding a new top-level doc → MUST add both files in the same edit batch.
- This library does NOT enforce bilingual policy on consumer projects. That's the
rules/bilingual-docs/rule, opted-in per project atsetup/init-agent-configtime.
Structural conventions
- Every markdown file starts with
# Title, then> One-line purpose., then## Master TOC. - Directory naming:
kebab-case. Names with proper nouns keep their casing (rare). - Frontmatter format for
RULE.mdandSKILL.md: see.claude/skills/new-rule/SKILL.mdand.claude/skills/new-skill/SKILL.md(added in Phase 9). - Don't break links — when renaming, grep for the old path in
INVENTORY.mdand other docs.
Inventory must stay in sync
INVENTORY.md and INVENTORY.zh.md are manually maintained until Phase 9 ships an auto-gen skill. When adding, removing, or renaming a rule/skill/hook/recommendation/template, update both INVENTORY files in the same edit batch as the content change.
Commits
- Conventional Commits:
feat:,fix:,docs:,refactor:,chore:. - One commit per logically distinct change. Don't split inventory updates from the content change they describe.
- One commit per phase during the initial build (P1 commit, P2 commit, ...).
- Don't commit unless the user explicitly asks.
- Never put a
https://claude.ai/code/session_<id>URL in a commit message or PR body. This repo is public; that link is account-scoped (nobody else can open it), so it only leaks a private session id into public history as clutter. Keep theCo-Authored-By:attribution line if used, but drop theClaude-Session:trailer and any PR-body session line. - Address the Copilot review after every PR. GitHub Copilot auto-posts a "Pull request overview" + inline comments on each PR. After creating/merging a PR, fetch Copilot's findings (
gh api repos/<org>/<repo>/pulls/<n>/commentsfor inline,.../reviewsfor the overview), analyze each, and fix the real ones (skip false-positives, noting why). The fix is itself a PR that Copilot reviews too. Recursion guard — MANDATORY to avoid an infinite fix→review→fix loop: at most 2 rounds of Copilot-driven fixing per originating change, OR stop as soon as Copilot raises no new actionable findings — whichever comes first. Never loop past 2 rounds. - Fold Copilot's recurring review criteria back into
review-gate. After analyzing a batch of Copilot findings, extract the generalizable ones (a review THEME Copilot keeps flagging — e.g. "doc/message/name accuracy", "quoting & regex-metachar robustness", "validate input before path/command interpolation") and add them as review forms inhooks/review-gate/scripts/gate.sh, so review-gate catches that class proactively next turn instead of waiting for Copilot post-hoc. This closes the loop: each Copilot sweep should make review-gate a little stronger. (Forms 9–10 were added this way, tagged "a GitHub-Copilot-recurring miss".)
Out of scope
- Don't rewrite the global
~/.claude/CLAUDE.md. That file is the input to this library (P2 distills it). Edits to the global file belong in a different session, not here. - Don't write content under
rules/,skills/,hooks/etc. without checkingINVENTORY.mdfirst — duplicate entries will drift apart. - Don't pull entries from upstream skill collections (
.orchestra/skills/,.agents/skills/,huggingface-skills, etc.) into this repo. Reference them fromrecommendations/instead — those are upstream-maintained and we shouldn't fork them.
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.

