Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Design & UI

knowledge-graph

Build and maintain the project's knowledge graph — a tiered set of nodes under docs/graph/ that lets an agent load only the few facts a task needs instead of the whole codebase. Use when adopting a project, when a fact changes, when a node grows too large, or when a task should have matched a node's triggers and didn't. Enforces one home per fact (dedup), honest per-node budgets, cite-don't-fabricate, and a mechanical linter. The library wiki (docs/graph/libraries/) is a leaf tier of this graph, not a separate system.

llopresto87 · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add llopresto87/Cypress --skill knowledge-graph

About this skill


name: knowledge-graph description: Build and maintain the project's knowledge graph — a tiered set of nodes under docs/graph/ that lets an agent load only the few facts a task needs instead of the whole codebase. Use when adopting a project, when a fact changes, when a node grows too large, or when a task should have matched a node's triggers and didn't. Enforces one home per fact (dedup), honest per-node budgets, cite-don't-fabricate, and a mechanical linter. The library wiki (docs/graph/libraries/) is a leaf tier of this graph, not a separate system. id: skill.knowledge-graph tier: 2 kind: skill origin: seed title: knowledge-graph — author and maintain the tiered node graph the router traverses, lint-enforced owns:

  • knowledge-graph.method
  • knowledge-graph.node-contract
  • knowledge-graph.linter requires: peers:
  • skill.context-router
  • skill.library-wiki
  • skill.validate-knowledge load_when:
  • "author or edit a graph node"
  • "one home per fact violation"
  • "graph-lint fails"
  • "add or sharpen a load_when trigger"
  • "split an oversized node"
  • "build the docs/graph structure" artifacts:
  • templates/knowledge-graph/_schema.md
  • templates/knowledge-graph/graph-lint.py
  • templates/knowledge-graph/index.md
  • templates/knowledge-graph/node.template.md
  • templates/docs/nodes/_deviation.template.md
  • templates/docs/nodes/_expertise.template.md est_tokens: 2519

knowledge-graph

The graph at docs/graph/ is how a project stays legible when it no longer fits in a context window. Each node is one subject; edges say what a task must load with it; tiers bound the depth. An agent starts at the router index and traverses (see context-router); this skill is the discipline of authoring and maintaining what it traverses.

Scale is agnostic: a "subsystem" node may describe a package in a single repo or a whole repo in a multi-repo program. The graph does not privilege either shape — nodes describe subjects, and how many repos those subjects span is a property of the project, not of the method.

Tiers

TierWhatLoaded
0The kernel (AGENTS.md / CLAUDE.md)Always, by the host tool
1docs/graph/index.md — the routerEvery task, first
2docs/graph/nodes/*.md — one subject eachBy traversal from the router
3Detailed collections below docs/graph/Only when a Tier-2 node names the leaf and the task needs it

A Tier-2 node never loads another node's content by copying it. It names the node id and lets the traversal do the work.

The node contract

Every node begins with frontmatter. The full contract — every key's semantics (id, owns, requires, peers, composes, artifacts, libraries, load_when, est_tokens) and the anti-patterns — lives in docs/graph/_schema.md, the file installed beside the graph itself; copy an existing node rather than authoring frontmatter from scratch. The key that carries the whole design: owns — each fact-key appears in exactly one node's list, project-wide.

An expertise node is authored to route, never to inform. It owns exactly two facts — <slug>.applicability (when this stack element is in play, and what must not be done without it) and <slug>.composition (which sub-expertises apply under which condition) — and it carries at least one libraries:/artifacts: edge to the depth it points at. The API, the pin, and the standard stay on those leaves; the node names the leaf that serves each purpose and restates none of them. Its specialisations hang off composes:, and a child that requires: its parent must appear in that parent's list — the reciprocity the linter checks, so a child cannot be added without the menu learning about it.

The rules

1. One home per fact

Every fact has exactly one owning node, declared in its owns list. No other file restates it; other files link. Duplicated facts rot asymmetrically — one copy gets updated, the other silently lies, and a lying doc is worse than a missing one. When two nodes both want a fact, extract it to a shared node and have both require it.

Two corollaries. One name per concept: a term maps one-to-one onto the thing it names, a near-miss synonym is a fault rather than an alias, and the graph uses the name the world already holds — a serialized, wire, or externally held identifier is a contract, never renamed to match internal vocabulary; a deliberate mismatch is recorded so nobody "fixes" it (skill.holistic-editing owns the rename mechanics). Rendered views are generated, hand-edited files are shaped for their editor: an index table or status summary is regenerated from its home (status-register.py), never hand-edited; the files a human does maintain — the linter's PROJECT CONFIG, the plant: block — stay comment-bearing, grouped, and stably ordered, with no shape chosen for machine convenience.

2. Version pins live in the library tier

An exact version belongs on its docs/graph/libraries/<name>.md page. A node body may summarize a version only if it owns the corresponding *.versions fact-key; otherwise it links to the page. This keeps a version from being stated in five places and updated in one.

3. Cite; do not fabricate

Every non-obvious claim has a source. Never invent a URL, a CVE id, a version, or a fact to fill a section. Write "not recorded" or "not audited" instead — an honest gap is usable; a confident fabrication is a trap. This is the single most important authoring rule, because a graph exists to be trusted over model memory.

Separate observed from audited. A fact described because it was seen in source is not the same as a fact that was audited or certified, and a page's prose must never let the first read as the second — "the handler validates the token" (observed in one path) does not mean "every path validates the token" (a coverage claim nobody checked). Say which you did. Where a page's scope is partial, add an

Read the complete source ↗