Generate Knowledge

/generate-knowledge

Generate .agents-kg/ — a self-contained, plain-markdown knowledge base for the current (or a given) repository. Every page is a "define everything" reference: purpose, constants/config, every function and class with signatures, algorithms in plain words, emitted values, and cross-references. .agents-kg/README.md is the index.

This skill is repository-agnostic: it scouts the target repo's actual structure and partitions the work by what it finds, rather than assuming a fixed layout.

When to use

• Starting fresh on an unfamiliar repo and want structural context fast.
• .agents-kg/ is missing, partial, or stale relative to the current branch.
• Asked to "create / recreate / update the knowledge docs", "build a code reference", "document the repo end-to-end", etc.
• Pass an optional repo path to target a specific directory; otherwise use the working directory.

Output contract

Always write into .agents-kg/ at the target repo root (note: NOT .knowledge/). The exact set of area files is determined at scout time (see below), but there is always a README.md index written/updated last, and the links in it must resolve.

Relative links in the README must resolve; each generated file must be genuine content (headings + signatures/functions) — never placeholders or "see other file" stubs.

Workflow

1) Scout the repo (dynamic)

Determine the target root (argument, or cwd). Then map the structure:

• find . -type d -not -path '*/.git/*' -not -path '*/node_modules/*' -not -path '*/.venv/*' -not -path '*/__pycache__/*' -maxdepth 2 | sort
• If Python: find . -name '*.py' -not -path '*/node_modules/*' -not -path '*/.venv/*' | sort and wc -l aggregate.
• If JS/TS: find . \( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' \) -not -path '*/node_modules/*' | sort.
• If Go: find . -name '*.go' | sort. Generalize to the language(s) actually present.
• Other top-level areas: ls for config, scripts, tests, migrations, docs, infra, CI/workflows.

Read the root README (if any) and the main entry point to understand the architecture.

2) Partition into areas

Group the code into a handful of coherent areas (typically 4–12), based on the actual structure. Common patterns you can adapt:

• Entry / app factory — the top-level app/server file and bootstrap.
• Core / framework — config, auth, middleware, db/session, shared utils/deps, DI.
• API / routes — the routing layer and every endpoint/controller/handler.
• Services / domain logic — the business-logic layer, split further if large (e.g. services/evals/core vs services/evals/calculators).
• Models / ORM — ORM models, migrations, schema files.
• Workers / orchestration — background jobs, task queues, workflows, workers.
• Tests — test layout, fixtures/conftest, how tests are run.
• Scripts / tooling — build/CLI/dev scripts, seeders, CI.
• Infra / config — docker, compose, deploys, dependency manifests.
• Docs — the in-repo documentation map.

Split any area that is very large (rough rule: more than 40–60 files or >4,000 lines) into two or more so no single agent is overloaded. Keep each partition disjoint so agents don't fight over the same files.

3) Fan out parallel exploring agents

Launch one general-purpose subagent per area, all in parallel (they are independent). Give each agent:

• the target repo root path;
• the exact file list (and directories) for its area;
• the instruction to read those files completely and write a single exhaustive markdown file to .agents-kg/<area>.md;
• the "define everything" directive: purpose; constants/config (with types/defaults); every class (attributes + methods with signatures); every function (signature, params, return, behavior / side-effects, sync vs async); models/schemas (fields/types/defaults); registries/keys; cross-references; algorithms in plain words;
• use fenced code blocks for signatures; do not skip files.

Suggested description per agent: "Document <area>". Issue the Agent calls in one parallel block.

4) Write/refresh .agents-kg/README.md

Produce an index:

• A table mapping each generated file → what it covers.
• A "Quick orientation" section (entry point, where the API/routes live, where business logic lives, how persistence/orchestration works, how to run tests).
• A generated-date + branch line.

Update existing rows when regenerating an area; keep line "created/updated" accurate.

5) Verify

• ls -1 .agents-kg/*.md — all area files + README present.
• For every README ](<file>.md) link, confirm the target file exists.
• Spot-check one or two files for genuine content (headings, function/class signatures).
• Report the final file list and line count to the user.

Guardrails

• Output location is .agents-kg/, not .knowledge/. If a stale .knowledge/ exists, ask before removing it; do not silently create both.
• The docs are plain markdown — no build tooling needed to view them.
• Skip generated/vendored/third-party code (node_modules, .venv, build artifacts, lockfiles, minified bundles). Focus on first-party source.
• Do not publish .agents-kg/ to discussions/PRs unless asked; it is a local assistant reference.
• Do not duplicate the repo's own docs/. The .agents-kg/ is an independent, code-derived reference; where they disagree, live code is authoritative.
• Reuse before regenerating: if only one area changed, regenerate just that area and update only the README rows that moved, rather than the whole folder.

Example partitioning (adapt, don't copy)

Given a ~200-file Python FastAPI backend, the first successful run produced:

core-app · api-endpoints · workers-orchestration · services-core · services-calculators-processors · services-insights-lifecycle · services-misc · dataset-tooling · data-catalog · tests-scripts-infra · migrations-docs

Your partitioning will differ — scout first, partition second.