# Generate Knowledge

> Generate a self-contained markdown knowledge base (functions, classes, variables, flow) for ANY codebase into a <repo>/.agents-kg/ folder. Use at the start of work on an unfamiliar repo, when .agents-kg/ is missing or stale, or when asked to 'create the docs', 'generate knowledge', 'build a code reference', 'make a knowledge base', or 'document the whole repo'. Dynamically scouts the repository structure and fans out parallel agents, one per main area. Trigger: /generate-knowledge

- Skill: `imnotdev25/generate-knowledge` (Agent Skill)
- Install (CLI): `npx skillmds@latest add imnotdev25/generate-knowledge`
- Raw SKILL.md: https://api.skillmd.com/api/skills/imnotdev25/generate-knowledge/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: imnotdev25 (https://skillmd.com/u/imnotdev25)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/imnotdev25/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.