Skill · once, then every few commits on its own

Project Knowledge

Every new developer, and every new agent session, rebuilds how the codebase works from the code. Most of it was already known to someone. This writes it down once, in the repository, and keeps it true.

Soumya Rauth · Creator & maintainer

npx -y github:soumyaRauth/skills-hub knowledge init

The problem

clone → a week of rediscovery → the same questions the last person asked

Why orders only turn paid on the webhook, which env var makes jobs run inline, which refactor was tried and reverted: it lives in someone’s head or in a closed pull request. An agent session starts from zero every time, too.

Set up a repository, once

npx -y github:soumyaRauth/skills-hub knowledge init

Run it in the project’s root, then type /learn in Claude Code (or ask it to learn this codebase), and commit what it wrote. Type /learn again whenever you decide the knowledge should catch up. It adds, as files you commit: the skill (so teammates install nothing), the /learn command, a Stop hook that keeps the knowledge current, and an MCP server entry in .mcp.json. --dry-run shows the plan first; knowledge remove takes it back out and keeps the knowledge.

Only the skill, for one agent: npx skills add soumyaRauth/skills-hub --skill project-knowledge

A new developer’s first day

1. Clone the repository and open Claude Code.
2. Approve the project-knowledge MCP server (asked once).
3. /mcp__project-knowledge__onboard   — or just ask how the codebase works.

There is no server to host. The MCP server is a small dependency-free script that each developer’s agent starts on their own machine, and it reads the knowledge from their clone. Sharing it is the same as sharing code: commit, push, pull. It works with any MCP client.

What it keeps

.agents/knowledge/
  architecture.md     what each part is for, how a request flows, how to run it
  decisions.md        dated, append-only: what was decided, why, what was rejected
  gotchas.md          what will bite you, and “don’t change X without Y”
  .learn-state.json   learned as of which commit (shared by every clone)

Each entry comes from the code, the history or a person, and names its source. It never records a secret value, only that a variable exists and what it controls. A reason the history does not explain is written down as an open question, not invented.

Current without being asked

commit → Stop hook counts commits past the cursor
   → at 5 (LEARN_EVERY), asks the agent for a run
   → commit messages · git diff --stat · full diffs only where structure changed
   → update the sections that moved, move the cursor

The hook is bash and git, so it costs nothing until it fires, and it fires once per commit at most. A run reads the change, not the codebase, and never commits for you.

When it activates

Engages	Asked to learn the codebase, capture or update project knowledge, make a repository AI-ready or prep a handover; the Stop hook reports the knowledge is behind.
Stays quiet	Ordinary work in a repository without `.agents/knowledge/`, a question about one file, a request for user documentation. It never starts a full scan nobody asked for.
Depth	Shapes the work when asked. Otherwise it only reads: where knowledge exists, the agent checks it before the code.
Works with	Architecture Engineer, Project Compass, Engineering Investigator, Release Engineer