know-my-repo

Day-one onboarding for AI agents — from zero knowledge to a cited, verified understanding of your repository.

know-my-repo is an agent skill for the moment an agent meets a codebase it has never seen: no CLAUDE.md, no architecture docs, no notes. Instead of guessing from file names and training-data vibes, the agent earns its understanding — by reading the code, running the commands, and citing every claim — then writes the initial knowledge set so no future session starts from zero again.

What it does

/know-my-repo .

1. Recon — detects the stack and writes the numbered Newcomer Questions the whole read must answer; if substantial knowledge files already exist it stops and recommends clean-slate instead of writing competing docs.
2. Deep read — six parallel exploration scopes: structure & entry points, data flow (write AND read path), wiring, tests & CI, git trajectory, and operational reality (deploy pipeline, environments, background jobs). Every component classified works / half-wired / dead with a proving file path. Reading ends when every Newcomer Question is answered or tagged UNVERIFIED — not when every file has been read.
3. Convention extraction — the repo's actual patterns, each proven by 2+ examples and no counterexample; conflicting patterns are reported as inconsistencies, never silently resolved.
4. Command verification — build/test/lint found in manifests and CI, then actually run (safe ones only). A failing test suite is a first-class finding, not a secret.
5. Exemplar trace — one real, recently-touched feature followed end to end (route → handler → service → storage → output). This becomes "How to add a feature here": the repo's own pattern, proven by its own code.
6. Write — first a 10–20 line findings brief in chat (target file names, command results, inconsistencies with recommended resolutions) confirmed once, then AGENTS.md (under 150 lines, behavior-changing lines only) and docs/ARCHITECTURE.md (component map, data flow, exemplar trace, how it deploys, inconsistencies). Every fact cited; the unverifiable tagged UNVERIFIED.
7. Cold-start test — re-reads only the generated docs as a fresh agent and answers the numbered Newcomer Questions from them alone; mechanical checks (line budget, no fabricated metadata, 2+ citations per convention, cited gotchas) must pass before presenting.
8. Report — findings, sharp edges, inconsistencies for the team to settle, and half-wired components worth a deep-plan run.

Nothing is deleted — this skill only creates.

The skill family

Shared law: no claim without evidence. A convention needs two examples; a command needs a real run; a fact needs a file:line.

Install

npx skills add silkyland/know-my-repo

Or copy this directory into your agent's skills folder (e.g. ~/.claude/skills/know-my-repo/).

Structure

know-my-repo/
├── SKILL.md                          # 8-step workflow + evidence rules
├── references/
│   ├── exploration-guide.md          # The 6 parallel scopes + classification
│   ├── conventions-guide.md          # 2+ examples rule, dimensions, counterexample checks
│   └── knowledge-templates.md        # AGENTS.md / ARCHITECTURE.md structures
└── evals/
    ├── scenarios.md                  # 3 manual eval scenarios (query + expected behavior)
    └── fixtures/                     # Small repos each scenario runs the skill against

Follows the Vercel skills single-skill layout and Anthropic's skill authoring best practices.

License

MIT