project-docs
Skill2 starsChanged 4 months agoMITView on GitHub
How to maintain this project's knowledge base — where a new fact goes, how to close a work package with a log entry, when something earns a place in CLAUDE.md, and how to run the lint pass. Use when closing a WP, recording a measurement or finding, adding an ADR or spec, updating the index, or when CLAUDE.md is growing.
22 other projects use a version of this.
Adopted by
Most recently taken up by
- avinashankur/skillstheir own version, first seen Nov 15, 2026
- ainiaa/skills-project-docstheir own version, first seen Nov 8, 2026
- snowfluke/tech-lead-skillstheir own version, first seen Nov 8, 2026
- MasihMoafi/skillstheir own version, first seen Nov 1, 2026
- coco-research/cocotheir own version, first seen Nov 1, 2026
- byrodi/project-docstheir own version, first seen Nov 1, 2026
Used with
Projects with it also use test-audit, to-issues and 3 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
BlockSkilltest-audit
Invoke whenever writing, changing, reviewing, or sweeping tests in buzz-app. Authoring gate for new tests plus audit workflow for low-value, implementation-coupled, or duplicative tests and the test-only production seams they demand.
Also in 3 projects that use this
GoogleSkillto-issues
Break a plan, spec, or PRD into independently-grabbable issues on the project issue tracker using tracer-bullet vertical slices.
Also in 3 projects that use this
GoogleSkillto-prd
Turn the current conversation into a PRD and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed.
Also in 3 projects that use this
Google CloudSkilltriage
Gather context on a change or bug and plan the implementation.
Also in 3 projects that use this
BlockSkillfrontend-design
Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
Also in 3 projects that use this
Other versions22 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 22
- xstongxue/best-skills★ 2.9ksame name
- coco-research/coco★ 797same name
- vstorm-co/agenticos★ 315same name
- s-hiraoku/synapse-a2a★ 17same name
- cablate/ai-toolkit★ 15same name
- MasihMoafi/skills★ 8same name
- snowfluke/my-tech-lead-flow★ 8same name
- snowfluke/tech-lead-skills★ 8same name
- ainiaa/skills-project-docs★ 4same name
- lorissun2025/project-docs★ 2same name
12 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository2 other files it gives its agents.
- .claude/rules/agents.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
The file
We split this skill into the rules it gives an agent
9 rules. 0 are common, 5 are distinctive, and 4 are very specific to this project.
0
Common
Most of the 18 edited versions we read keep these.
5
Distinctive
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
Ask in this order and stop at the first yes.
- Distinctive: line 29
Write what changed, *why it was wrong before*, what is proven live versus keyless only, and what you deliberately did not do.
- Very specific: line 32
If the WP added or changed a document, add it to docs/index.md.
- Distinctive: line 33
If it changed a count, threshold or version that a doc repeats, update that doc in the same commit — or better, replace the value with a …
- Distinctive: line 35
Only then consider CLAUDE.md (next section).
- Very specific: line 52
Verify with git -C eval/results status -sb (nothing ahead) and git -C eval/results ls-remote origin naming the commit.
- Very specific: line 61
Not
rsync: every key of the git user on tank is restricted to git-shell since 2026-11-12, so rsync, scp and a shell are refused — … - Very specific: line 84
Never put in CLAUDE.md: counts, versions, thresholds, test totals, "N tests green", file inventories, or anything derivable from the code.
- Distinctive: line 89
Run periodically, and after any batch of doc changes.
“Common” is measured: kept by at least 6 in 10 of the 18 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Maintaining the vault-agent knowledge base
The structure and its rationale: docs/methodology/llm-wiki-mapping.md. This file is the
procedure. It loads only when you are actually maintaining something, which is why the procedure
is not in CLAUDE.md.
Where a new fact goes
Ask in this order and stop at the first yes.
- Would an agent silently do the wrong thing without it? → an invariant in
CLAUDE.md, in trigger/action/evidence form. See the admission rule below — this is the expensive layer. - Is it true only while working on one subsystem? →
.claude/rules/<topic>.mdwith apaths:glob, so it loads only when a matching file is read. - Is it a decision with alternatives and consequences? → a new ADR in
docs/architecture/adrs/, numbered, fromADR-template.md. - Is it work to be done? → a spec plus kick-off under
docs/architecture/backlog-2026-07/. - Otherwise → an entry in
docs/log.md. This is the default, and most things belong here.
Closing a work package
- Definition of done first:
uv run pytest,uv run ruff check, bareuv run mypy. - Append one entry to
docs/log.md:## [YYYY-MM-DD] WPnn — one line. Newest at the bottom. Write what changed, why it was wrong before, what is proven live versus keyless only, and what you deliberately did not do. Corrections to earlier entries go in this entry, never into the earlier one. - If the WP added or changed a document, add it to
docs/index.md. - If it changed a count, threshold or version that a doc repeats, update that doc in the same commit — or better, replace the value with a pointer to the code.
- Only then consider
CLAUDE.md(next section). Most WPs change nothing there.
Securing the evidence of a paid run
eval/results/ (result JSON, step files, review.json, LLM transcripts, ablation comparisons)
is git-ignored and exists only on this machine, yet every measurement entry in docs/log.md
cites it by stamp. Since 2026-11-14 the directory is a git repository of its own (remote
tank:/tank/git/vault-agent-eval-results.git, branch master). After recording a run — or at
the latest in the same session — commit and push it:
git -C eval/results pull --ff-only # a second machine (ZEUS) pushes there too
git -C eval/results add -A
git -C eval/results commit -m "<what was run, with its stamp>"
git -C eval/results push # never --force: the remote refuses it, by the owner's settingVerify with git -C eval/results status -sb (nothing ahead) and git -C eval/results ls-remote
origin naming the commit. On a checkout without the directory: git clone
tank:/tank/git/vault-agent-eval-results.git eval/results. Kept projects of a run
(--keep-outputs) go under eval/results/kept-outputs/<case>/<stamp>/ without dbt's target/.
A script kept there as evidence is stored as .py.txt: bare mypy reads eval/ and takes a .py
file for project code (2026-11-15).
The repository is the evidence's second copy, not a dataset: nothing reads it back, and it never
goes to GitHub.
Not rsync: every key of the git user on tank is restricted to git-shell since
2026-11-12, so rsync, scp and a shell are refused — deliberately; do not look for a way
round it. A new repository on tank is the owner's to create. The repository holds every
run since 2026-07-08 (ZEUS's 858 files were merged in on 2026-11-14) and is the only copy
besides the working machines: the former rsync mirror on tank was removed by the owner on
2026-11-15, without a file-by-file comparison. The remote has receive.denyNonFastForwards
and receive.denyDeletes set — do not test that with a real force-push.
The admission rule for CLAUDE.md
Budget: 250 lines (200 until 2026-10-09, raised by the owner: condensing at 200 had started to cost knowledge), and it is a real limit, not an aspiration — the file is loaded in full on every request, and the documented guidance is that longer files reduce adherence.
An entry is admitted only if both hold:
- there is a concrete incident where an agent did the wrong thing without it — name it; and
- it can be phrased as trigger / action / evidence. If it cannot, it is a fact, not a rule, and facts go in the log or the index.
At budget, an addition requires an eviction: say which rule leaves and why it is no longer earning its place (usually because a gate, a type or a test now enforces it mechanically — that is the good outcome).
Never put in CLAUDE.md: counts, versions, thresholds, test totals, "N tests green", file
inventories, or anything derivable from the code. /doctor will propose trimming exactly these.
The lint pass
Run periodically, and after any batch of doc changes. It is a reading task, not a script.
- Contradictions — two documents stating incompatible things. Newer wins; record the
correction as a new dated entry, do not edit the older. Check the maintained pages against the
record, not only against each other:
CLAUDE.md's "Open items" is the likeliest place for a claim that a later log entry or findings document has already overtaken. The first lint pass missed exactly this by comparing maintained pages among themselves. - Derivable facts stored as values — gate counts, version pins, caps, thresholds in prose. Replace with a pointer. This is the failure mode this project has hit most often.
- Stale status — a document claiming live verification whose subject has changed since. Downgrade the claim in a new entry; say what is now merely keyless-tested.
- Orphans — files in
docs/thatdocs/index.mddoes not list, and index entries whose file no longer exists. - Rules without a trigger — entries in
CLAUDE.mdthat read as memories rather than rules. They are eviction candidates. - Budget —
wc -l CLAUDE.mdagainst 250 (200 until 2026-10-09).
Report findings; apply only the mechanical ones (index, pointers) without asking. Anything that changes meaning is the human's call.
Ownership — append-only
docs/architecture/ (ADRs, specs, kick-offs, reviews, spike memos) and docs/log.md are
dated records. Index them, link them, quote them. Never revise them, never "clean them up",
never fix a claim inside them — a new dated entry does that. Their value is precisely that they
show what was believed when, which is what makes a later correction legible.
Maintained and rewritable: docs/index.md, CLAUDE.md, .claude/rules/, this skill.
Frontmatter for new documents
New documents under docs/ carry:
---
type: adr | spec | kickoff | review | memo | guide | log | index
status: verified-live | keyless-only | not-measured | superseded
updated: YYYY-MM-DD
supersedes: <path>#<section> # optional
---status is the axis this project argues about most — say which claims are live-proven and which
are only keyless-tested. Existing documents were not retrofitted: adding frontmatter to a
dated record would mean editing it, which the ownership rule forbids.
The guard that protects the move
tests/test_log_completeness.py asserts that every paragraph of the pre-retrofit CLAUDE.md
still exists verbatim in docs/log.md. If you ever restructure the log, that test must keep
passing — the log is append-only, so it only ever gets stricter.
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.

