agentleFS
Gord1yGord1y/countersign-skills/skills/repo-knowledge/SKILL.md

repo-knowledge

Skill2 starsChanged 42 days agoMITView on GitHub

Bootstrap, update and lint a repo's knowledge graph (feature nodes in docs/features, a generated path index, glossary, ADRs, a drift lint in its CI).

The file

Show its rules and text

We split this skill into the rules it gives an agent

15 rules. About 0 are common, 5 are distinctive, and 10 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 10

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Every node holds at least one claim ending as of <short sha>, <date>: the short sha from git rev-parse --short HEAD and the date from date …

    line 89
  2. Very specific:

    Write a record in docs/adr/NNNN-<slug>.md only for a decision that is all three of: hard to reverse, surprising without context, a real …

    line 103
  3. Very specific:

    Run it when docs/features/ has no nodes.

    line 132
  4. Distinctive:

    Read each area as in Readers.

    line 137
  5. Distinctive:

    Write the approved nodes, glossary and records, each claim stamped.

    line 142
  6. Very specific:

    Run scripts/knowledge-lint.sh --write, then scripts/knowledge-lint.sh and fix every line it reports until it prints ok.

    line 145
  7. Very specific:

    Add sh scripts/knowledge-lint.sh to the CI job that lints pull requests and to the local gate.

    line 147
  8. Very specific:

    Add one line to the repo's CLAUDE.md and AGENTS.md: before changing code, read the nodes docs/knowledge/index.md maps to the paths you …

    line 148
  9. Very specific:

    Commit twice: docs(knowledge): map the features for the nodes, glossary, records and the CLAUDE.md and AGENTS.md line, then ci: run the …

    line 150
  10. Very specific:

    Run scripts/knowledge-lint.sh and fix what it reports.

    line 156
  11. Very specific:

    Run scripts/knowledge-lint.sh --write, then scripts/knowledge-lint.sh until it prints ok.

    line 166
  12. Distinctive:

    Check a fact now before writing it.

    line 172
  13. Distinctive:

    No secrets, tokens or personal data in a node, a term or a record.

    line 174
  14. Distinctive:

    Commit locally. Never push.

    line 175
  15. Very specific:

    If local.md exists next to this file, read it.

    line 177

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill 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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Repo knowledge

Agents miss facts that live only in people's heads: why a module is shaped this way, which table a feature writes, what breaks when a field changes. This skill moves those facts into the repo as a Markdown graph. Each feature is a node, a generated index maps code paths to nodes, and a lint that the repo runs in its own CI fails when the graph drifts from the code. The graph works for a developer who has never seen this skill set: nothing in it calls back into this folder.

Repo facts

This skill needs the facts below. Look each one up in the repo's CLAUDE.md (or AGENTS.md) and the files it imports or points to (of a repo-facts file, only this skill's section: sed -n '/^## repo-knowledge$/,/^## /p' <file>), then in local.md next to this file. If neither has it, ask the user once, then suggest the one line to add to CLAUDE.md so the next run finds it.

FactExample
Source roots, the folders whose first-level subfolders are the areassrc, or apps and packages
The CI job that lints pull requeststhe lint job in .github/workflows/ci.yml
The repo's local gatepnpm check, which runs lint, typecheck and tests
How to run the app, and its standing test accountpnpm dev on port 3000; the QA account named in the repo's docs

The layout

docs/
  features/<name>.md          one node per feature, name in lowercase kebab-case
  knowledge/
    index.md                  generated by the lint, never edited
    GLOSSARY.md               the repo's terms
    source-roots.txt          optional: one source root per line, !<area> excludes an area
  adr/NNNN-<slug>.md          decision records
scripts/knowledge-lint.sh     the drift lint, copied from this skill's scripts/ folder

A node

---
code:
  - src/invoices/**
skills: []
api:
  - POST /invoices
related:
  - billing
decisions:
  - docs/adr/0003-invoice-numbering.md
---

# Invoices

## What it is

One or two sentences. As of 3f2a9c1, 2026-11-12.

## Where it lives

The entry points and the files to read first, as paths. As of 3f2a9c1, 2026-11-12.

## Rules and traps

What a newcomer gets wrong, and why. As of 3f2a9c1, 2026-11-12.

## Feature map

- Reach: how to get to the feature in the running app (a route, a screen, a command).
- Drive: the steps and inputs that exercise it, and the account to use.
- Observe: what to see, which request fires, which row or log line proves it worked.

The five keys are all optional and each is key: [] or key: followed by - value lines.

  • code: globs from the repo root. **/ matches zero or more folders, ** anything, * and ? stay inside one folder, {a,b} lists alternatives (no nesting), a trailing / means the whole folder. No ./ or leading /, and none of [, ], | or a backtick.
  • related: names of other nodes. decisions: an ADR as a path from the repo root, a path relative to docs/features/, or a bare slug under docs/adr/ (0001-numbering for docs/adr/0001-numbering.md).
  • skills (repo skills that cover the feature) and api (endpoints) are not checked, because a global skill is absent in CI.

Every node holds at least one claim ending as of <short sha>, <date>: the short sha from git rev-parse --short HEAD and the date from date +%F, taken when the claim was checked, so staleness is visible. Point to code, never copy it. qa-tester and a per-repo verify-<app> skill drive QA from the feature map; a node with no running surface writes none under each of its three lines.

Glossary

docs/knowledge/GLOSSARY.md holds one section per term: ## Term, a definition ending with the stamp, and a last line _Avoid_: bill, statement listing synonyms nobody should use for it. Add a term when two people used different words for one thing, or one word for two things.

ADRs

Write a record in docs/adr/NNNN-<slug>.md only for a decision that is all three of: hard to reverse, surprising without context, a real trade-off. Take the next 4-digit number from ls docs/adr. Sections: Status, Context, Decision, Consequences. The user picks which decisions get a record. A decision that fails one of the three belongs in the node's Rules and traps.

Readers

Bootstrap and update read one area per reader, so the main context stays small. Each reader gets this brief, with the area's absolute path filled in:

Read the area <absolute path> and report at most 30 lines: what the feature is; the files that
hold it, with line ranges; the rules and traps a newcomer would miss; how to reach and drive it
in the running app; the endpoints it exposes; the other areas it calls or is called by. Facts
only, each with a path and range. Never include secrets.

Claude Code. One Agent call per area, up to four in one message: subagent_type: "researcher" when the researcher agent is installed and "general-purpose" otherwise, model: "haiku", effort: "low", run_in_background: false.

Under Codex there is no Agent tool. Under T3 Code, dispatch each area as a delegate_task child with mode: "wait", target: {providerInstanceId: "codex", model: "gpt-6.1-terra", options: {reasoningEffort: "low"}} and the same brief, which starts by telling the child to begin with a fresh context. Without T3 Code, read one area at a time yourself, holding only that area's report before the next.

Bootstrap

Run it when docs/features/ has no nodes. It adds a CI job, so it runs only when the user asks or as a slice of an approved plan; an agent that finds no nodes mid-run proposes it as a parked row in the run's decision log instead.

  1. List the areas: the first-level folders under each source root, from git ls-files.
  2. Read each area as in Readers.
  3. Propose one plan: the nodes with their names, globs and related nodes, the glossary terms, the ADR candidates that pass all three tests, and a source-roots.txt when the roots are not src. In an interactive session, ask once, through the agent's question tool or in plain text, and wait. In a run, the approved plan slice is the answer.
  4. Write the approved nodes, glossary and records, each claim stamped.
  5. Copy the lint from the folder that holds this SKILL.md: mkdir -p scripts && cp <this folder>/scripts/knowledge-lint.sh scripts/ && chmod +x scripts/knowledge-lint.sh.
  6. Run scripts/knowledge-lint.sh --write, then scripts/knowledge-lint.sh and fix every line it reports until it prints ok.
  7. Add sh scripts/knowledge-lint.sh to the CI job that lints pull requests and to the local gate.
  8. Add one line to the repo's CLAUDE.md and AGENTS.md: before changing code, read the nodes docs/knowledge/index.md maps to the paths you touch.
  9. Commit twice: docs(knowledge): map the features for the nodes, glossary, records and the CLAUDE.md and AGENTS.md line, then ci: run the knowledge lint for the script and the gate and CI steps. Never push.

Update and lint

  1. Run scripts/knowledge-lint.sh and fix what it reports.
  2. For each node and each of its code globs, list what changed since the node's stamp: git log --oneline <stamp sha>..HEAD -- ':(glob)<glob>'. Git's glob does not read {a,b}; run one command per alternative. A sha that git does not know (git cat-file -e <sha> fails) marks the node stale.
  3. Re-read each stale or uncovered area as in Readers. Refresh the claims that changed, add the nodes for new areas, retire the nodes for deleted ones, and restamp only what you checked.
  4. Compare the repo's script with this skill's: cmp scripts/knowledge-lint.sh <this folder>/scripts/knowledge-lint.sh. When they differ, show the diff and offer to replace the repo's copy; the user decides. In a run, put the diff in the closing summary instead.
  5. Run scripts/knowledge-lint.sh --write, then scripts/knowledge-lint.sh until it prints ok. Make one commit, docs(knowledge): refresh the nodes.

Rules

  • The knowledge lives only in the repo. CI never calls into this skill's folder.
  • Check a fact now before writing it. An unchecked claim does not get a stamp.
  • Point to code with paths and ranges. Do not paste it.
  • No secrets, tokens or personal data in a node, a term or a record.
  • Commit locally. Never push.

If local.md exists next to this file, read it; where it disagrees with this file, it wins.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.