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 · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add llopresto87/Cypress --skill knowledge-graph技能说明
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
| Tier | What | Loaded |
|---|---|---|
| 0 | The kernel (AGENTS.md / CLAUDE.md) | Always, by the host tool |
| 1 | docs/graph/index.md — the router | Every task, first |
| 2 | docs/graph/nodes/*.md — one subject each | By traversal from the router |
| 3 | Detailed 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
阅读完整来源 ↗