Skip to content
Skills Library
Programming · Analysis

map-knowledge

/map-knowledge

[Orbit 1.2.1 Code recon] Knowledge graph of the codebase: modules and links with file:line evidence + system overview. Use when: «разберись в репозитории», «как устроен проект», «граф знаний», «построй карту кода», «с чего начать в чужом коде»; understand codebase, knowledge graph.

Licence
MIT
Last repository change
09.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 09.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

[Orbit 1.2.1 Code recon] Knowledge graph of the codebase: modules and links with file:line evidence + system overview. Use when: «разберись в репозитории», «как устроен проект», «граф знаний», «построй карту кода», «с чего начать в чужом коде»; understand codebase, knowledge graph.

Original author description

[Orbit 1.2.1 Code recon] Knowledge graph of the codebase: modules and links with file:line evidence + system overview. Use when: «разберись в репозитории», «как устроен проект», «граф знаний», «построй карту кода», «с чего начать в чужом коде»; understand codebase, knowledge graph.

How it works

  1. When to use
  2. Inputs
  3. Procedure
  4. Output
  5. Check
  6. Example
  7. Pitfalls
  8. Portability
  9. What's improved vs the source
  10. Based on
Original SKILL.md headings · 180 lines, 1,219 words
SKILL.md preview
---
name: map-knowledge
description: '[Orbit 1.2.1 Code recon] Knowledge graph of the codebase: modules and links with file:line evidence + system overview. Use when: «разберись в репозитории», «как устроен проект», «граф знаний», «построй карту кода», «с чего начать в чужом коде»; understand codebase, knowledge graph.'
---

# map-knowledge — build a knowledge graph of the codebase

> **Orbit · ① Understand · step 1.2.1 Code recon**
> **Input:** repository ← `shape-idea`
> **Output:** `.orbit/knowledge/graph.json` + `.orbit/knowledge/overview.md` → next `explain-code`
> **Works with:** `index-code`, `survey-codebase`, `project-map`, `run-parallel`
> **Shared rules:** reply in the user's language per `speak-plain`; generated content defaults to English; act within `stay-in-scope`; artifacts go to `.orbit/` (contract: `ARTIFACTS.md`).

Method from Understand Anything, rewritten to use **built-in tools only**. Output:
`.orbit/knowledge/graph.json` + `overview.md`, read by `explain-code`, `trace-impact`,
`onboard-people`; `project-map` draws from it. Every edge carries `file:line`
evidence — without it the graph is a drawing.

## When to use

- An unfamiliar repository, legacy code or service — especially before a big change.
- Before onboarding a person or writing `docs/ONBOARDING.md`.
- A design discussion needs the real module boundaries, not the README's version.
- `explain-code`/`trace-impact` needs a graph that does not exist yet.

Skip for one file or function — read it (`explain-code`); don't build a 500-node graph
for a one-line question.

## Inputs

- The repository and its size: `git ls-files | wc -l`, `git ls-files | head -500`.
- Manifests: `package.json`, `pom.xml`, `build.gradle*`, `go.mod`, `pyproject.toml`,
  `*.csproj`, `Chart.yaml`, `Dockerfile`, `.gitlab-ci.yml`.
- Entry points: `main`, `cmd/`, `Program.cs`, `app.py`, `index.ts`, CLI scripts, CI jobs.
- An existing index from `index-code`: `.orbit/knowledge/index/` — reuse its notes.
- Prior knowledge: `.orbit/learnings/` and `docs/adr/` for why the layering is what it is.

If the repository is empty or a single package, reduce the module count; if it is
enormous (thousands of files), use the parallel mode in step 2 rather than reading.

## Procedure

1. **Inventory without reading all the code.** `git ls-files | wc -l` gives the size; split
   by extension. Read the manifests and find entry points — 90 % of the shape.
2. **Define 5–15 modules** by directory and responsibility (api, domain, infra, db, jobs,
   external clients). A module is a unit a person would name in a design discussion. Over
   ~300 files, split the modules across parallel agents (`run-parallel`): each writes its
   own graph fragment, and you merge the JSON.
3. **Write the nodes.** One node per module (or file/service/db/queue/external/config/job
   where the directory split is wrong). The `summary` is 1–2 sentences — **what it does
   and why** — not a retelling of the code. Every `files` entry is a `file:line-range`:

   ```json
   {"id":"api/auth","type":"module","title":"Auth",
    "summary":"Validates JWT, issues a session","files":["src/auth/jwt.ts:1-120"],
    "layer":"api","tags":["security"]}
   ```

4. **Write the edges** — calls / imports / reads / writes / publishes / consumes /
   deploys. Every edge has `file:line` evidence; no evidence → no edge:

   ```json
   {"from":"api/auth","to":"db/users","kind":"calls","evidence":"src/auth/repo.ts:42"}
   ```

5. **Cover the layers deliberately.** Ask per layer: is there a node for it? Missing
   `external`, `queue` or `ops` nodes are the usual blind spots.
6. **Write the overview** `.orbit/knowledge/overview.md`: purpose, modules table (id,
   title, layer, summary), main flows (request → response, event → handling), external
   dependencies, and risk spots (no tests, complex nodes, many incoming edges).
7. **Verify the graph.** Every node's files exist; no dangling edges (every `to` is a
   node id); re-check three random edges against the code. Fix what does not resolve.
8. **Record the limits.** Nodes you could not verify are marked `"hypothesis": true`; the
   overview names what the graph does not cover (generated code, dynamic calls).
9. **Hand off.** `explain-code` starts from a node id; `trace-impact` uses edges for the
   blast radius; `project-map` renders the graph. Commit `.orbit/` only by agreement.

## Output

Artifacts:

```text
.orbit/knowledge/
  graph.json      {"nodes":[...], "edges":[...]}
  overview.md     purpose, modules table, flows, dependencies, risk spots
```

Overview template:

```markdown
# <repo> — overview
Purpose: <what the system does for whom>
**Modules**
| id | title | layer | what it does |
**Main flows**
- request: <client> → <api> → <domain> → <db>
- event: <topic> → <consumer> → <...>
**External dependencies**
- <system> — used by <module> — contract <file:line>
**Risk spots**
- <node> — <why risky> — <file:line>
**Limits**
- hypothesis nodes: <ids>; not covered: <generated code, dynamic calls>
```

## Check

```bash
jq -e '.nodes and .edges' .orbit/knowledge/graph.json
jq '{nodes:(.nodes|length), edges:(.edges|length)}' .orbit/knowledge/graph.json
jq -r '.nodes[].files[]' .orbit/knowledge/graph.json | cut -d: -f1 | sort -u | xargs ls >/dev/null && echo 'files exist'
jq -r '.edges[].to' .orbit/knowledge/graph.json | sort -u > /tmp/to.txt
jq -r '.nodes[].id' .orbit/knowledge/graph.json | sort -u > /tmp/ids.txt
comm -23 /tmp/to.txt /tmp/ids.txt        # dangling edges — must be empty
test -f .orbit/knowledge/overview.md && wc -l .orbit/knowledge/overview.md
```

Pass rule: `graph.json` parses and has both `nodes` and `edges`; 5–15 nodes (more means
the split is too fine, fewer means too coarse); every node has `files` ranges and a
1–2 sentence `summary`; every edge has `evidence` and a `to` that exists; the dangling
check prints nothing; every `file:line` resolves; `overview.md` has the modules table,
flows, dependencies and risk spots. Fix a failing check in the evidence, not the prose.

## Example

A three-module repository, from inventory to verified graph:

```bash
$ git ls-files | wc -l
42
```
`package.json` lists `express` and `pg`. Entries:
```json
{"id":"api/reports","type":"module","title":"Reports API",
 "summary":"Serves the orders report; streams CSV or HTML.","files":["src/reports/router.ts:1-64"],"layer":"api"}
{"id":"db/orders","type":"db","title":"orders table",
 "summary":"Order rows; the single source for reporting.","files":["migrations/003_orders.sql:1-40"],"layer":"infra"}
```
```json
{"from":"api/reports","to":"db/orders","kind":"reads","evidence":"src/reports/query.ts:88"}
{"from":"api/reports","to":"api/auth","kind":"calls","evidence":"src/reports/router.ts:31"}
```
Verification: `jq '{nodes:(.nodes|length), edges:(.edges|length)}'` → `{nodes: 3, edges: 2}`;
the dangling `comm` prints nothing; the `files` paths resolve with `ls`; the
`reports → auth` edge re-checks against `src/reports/router.ts:31`. `overview.md` lists
the modules, the request flow (client → reports → db), and one risk: no CSV streaming test.

## Pitfalls

- **A graph without evidence.** An edge you "know" but cannot point to is a hypothesis.
  Label it or drop it; otherwise `trace-impact` reports a blast radius that does not exist.
- **Summary as a code retelling.** "Calls repo.findAll and maps to DTO" repeats the code;
  the summary answers *what it does and why*, which is what a reader needs.
- **Modules by folder only.** Folders lie: `utils/` may contain a service. Split by
  responsibility; an `id` a designer would say out loud.
- **Missing layers.** No `external`, `queue` or `config` nodes is the classic blind spot.
  Add a node per external system you can name from the manifests.
- **Reading everything.** Entry points plus manifests give the shape; read files only for
  the nodes you write.
- **Secrets in the graph.** Never read or copy `.env`, `*.pem`, `values-secret*` contents.
  A node summary names the dependency, never the credential.
- **A stale graph.** After a migration or module split the graph reports old edges. Refresh
  affected nodes in the `run-spec-loop` loop.

## Portability

Built-in tools only: any agent with file reading, `grep`/`rg`, `git`, `jq` and a shell can
build and verify the graph; the original plugin is not needed. Without subagents, build
the modules sequentially — parallel mode is an accelerator. Without `jq`, validate with
`python3 -m json.tool`. The artifact is plain JSON + Markdown under
`.orbit/knowledge/`, readable by later skills regardless of the agent.

## What's improved vs the source

- Works without the external plugin and its background scripts — built-in tools only.
- Every graph edge must carry `file:line` evidence.
- The graph lives in the shared `.orbit/knowledge/` and feeds `project-map`, `explain-code`, `trace-impact`, `onboard-people` directly.
- A dangling-edge check and a file-existence check make the graph verifiable.
- Hypothesis nodes and graph limits are recorded, so readers know what is unproven.

## Based on

- [Understand Anything](https://github.com/Egonex-AI/Understand-Anything) — method «understand» (MIT). Rewritten in our own words and improved — see "What's improved".

Versions

The database has no other skills named map-knowledge.

Database snapshot: 13.11.2026 · package version e153edcef052 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100understand-chat
    Use when you need to ask questions about a codebase or understand code using a knowledge graph
  • 95graphify
    Use for any question about a codebase, its architecture, file relationships, or project content — especially when graphify-out/ exists. Turns any input (code, docs, papers, images, videos) into a persistent knowledge graph with god nodes, community detection, and…
  • 100project-map
    [Orbit 3.1.1 Maps & diagrams] Interactive project map in one HTML: phases, steps in reading order, transitions, links to code. Use when: «карта проекта», «схема проекта», «как устроено», «интерактивная карта репозитория», «покажи как устроен проект»; project map, how the project works.
  • 100project-knowledge
    Generate project knowledge for any git repo: code graph, knowledge graph, code wiki, and AI-written domain docs under .ai/. Use when onboarding to a repo, asked to document a codebase, or to refresh stale .ai/ knowledge.
  • 90knowledge-graph
    Offline per-repo code knowledge graph (`kg` CLI). Use for graph status, index/refresh/reset, blast radius, what depends on X, or finding the code for X.
  • 100graph
    Use when the user wants to build, refresh, or visualize the repo's knowledge graph — code structure plus the committed wiki/ — via graphify. Produces an interactive graph + a GRAPH_REPORT.md of God Nodes, surprising connections, and suggested questions. Trigger on "/graph",…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.