Loading
Promote existing research into a stable-status canonical article under `articles/` in a Knowledge Base project (the `knowledge-base` starter pack). Read when a decision has actually been made and the
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add inkeep/open-knowledge --skill consolidate -a cursor -y
Promote existing research into a stable-status canonical article under `articles/` in a Knowledge Base project (the `knowledge-base` starter pack). Read when a decision has actually been made and the team wants the source-of-truth written down, or when asked to consolidate, canonicalize, promote research, or supersede an older article. Carries the decision-confirmation gate, the `supersedes:` chain that keeps the evidence trail intact, and the canonical voice. Does not conduct new research — that is the sibling `research-with-sources` skill.
Promote existing research into a stable-status canonical article under `articles/` in a Knowledge Base project (the `knowledge-base` starter pack). Read when a decision has actually been made and the team wants the source-of-truth written down, or when asked to consolidate, canonicalize, promote research, or supersede an older article. Carries the decision-confirmation gate, the `supersedes:` chain that keeps the evidence trail intact, and the canonical voice. Does not conduct new research — that is the sibling `research-with-sources` skill.
articles/ in a Knowledge Base project (the knowledge-base starter pack). Read when a decision has actually been made and the team wants the source-of-truth written down, or when asked to consolidate, canonicalize, promote research, or supersede an older article. Carries the decision-confirmation gate, the supersedes: chain that keeps the evidence trail intact, and the canonical voice. Does not conduct new research — that is the sibling research-with-sources skill."
compatibility: "Any agent host with the OpenKnowledge MCP server configured. Installed project-local by ok seed --pack knowledge-base (ok-beta for Beta)."
type: Document
metadata:
pack: "knowledge-base"
author: "Inkeep"
repository: "https://github.com/inkeep/open-knowledge-skills"This skill is pack guidance. The platform
/open-knowledgeskill (read/write/preview/linking/grounding rules) still governs every markdown operation — this layers the procedure on top.
Promote existing research on a topic into a canonical article under articles/. Canonical, not provisional — the output is the source of truth for future agents, not a snapshot of uncertainty.
The content directory is the resolved content.dir — read it with config({ key: 'content.dir' }) if you don't already know it. Paths below are relative to it.
Legacy reads: Existing research and articles may use status: provisional / canonical, and existing sources: may contain string paths. Treat those as draft / stable and source resources. Do not mass-rewrite them; new writes use the OKF forms below.
Consolidation is promotion, not creation. If the team hasn't decided, the resulting "canonical" article lies about the team's state of understanding — future agents read it, act on it, and the false certainty compounds.
Before any write, confirm out loud with the user:
If the decision is still open, do not consolidate. Tell the user: "The research is still provisional. When the team decides, come back and consolidate with the outcome." Then stop.
Do NOT consolidate when:
A consolidated article is the source of truth. Agents reading it should not need to dig further for context — it should stand on its own. That means:
Locate research articles on this topic:
exec("grep -rn <topic-keyword> <content-dir>") to find prior research, or exec("ls -A research") if the project groups research in a known locationexec("cat <path>") (rich enrichment gives frontmatter + shadow-repo activity + project git history + backlinks)sources: frontmatter list — read every referenced source fileIf there is no research to consolidate, stop. Consolidation is promotion, not creation. Do the /research-with-sources skill first.
You already confirmed the decision at the STOP gate at the top. This step is a brief re-check after loading the research in Step 1 — occasionally the research surfaces something that makes the "decision" look less decided than the user initially claimed (an un-rebutted open question, an alternative they forgot about). If the loaded research reveals that, pause and re-confirm with the user before writing.
Persist as you go (MUST). For a large consolidation drawing on several research docs, create the article skeleton — frontmatter + the headings below — first, then edit each section in as you finish it; don't hold the whole synthesis in context for one final write. A rate limit or crash mid-synthesis then costs you one section, not the entire article. (The platform skill's Writing section carries this rule for all long-running work: the knowledge base is your checkpoint.)
Save inside the content directory. Path convention depends on the project:
external-sources/ → research/ → articles/), save under articles/, grouped by topic subfolder when the area is broad (e.g., articles/editor/crdt-architecture.md)docs/, guides/, etc.), save there in a location that matches the project's conventionsFrontmatter:
---
title: Descriptive title
description: One-line summary of what this article covers
type: article
status: stable
date: YYYY-MM-DD
tags:
- article
- canonical
- topic-tag
supersedes:
- <path-to-research-article>.md
---
Structure:
## Summary
[One paragraph: what the decision is and why. A reader who reads only this paragraph should know the outcome.]
## Context
[What problem does this solve? What constraints shaped the decision?]
## Decision
[The chosen approach, stated directly. Not "we recommend" — "we chose".]
## Rationale
[Why this path over alternatives. Grounded in the constraints from Context.]
## Trade-offs
[What we gave up by choosing this path. Frame against the chosen decision, not as a menu.]
## Alternatives considered
[Briefly: what else was on the table, why it was rejected. Link to the research article for deeper analysis.]
## Implementation notes
[How this gets realized in the codebase — key files, patterns, gotchas.]
## Further reading
[Links to research articles and external sources for readers who want the trail.]
Canonical articles are destinations — they should be linked heavily from everywhere they're relevant and link out to every related page themselves. Underlinked canonical articles lose most of their value.
exec("grep -rn <topic> <content-dir>")) and add a link to the new article from each — usually under a "See also" section or inline where the new article is relevant. This makes the article discoverable via backlinks, not just by remembering the path.Add a supersedes: list in the new article's frontmatter pointing at the research article(s) it consolidates. This creates an audit trail.
Do NOT delete the research articles — they remain as historical context for how the decision was reached. Edit their frontmatter to add:
status: deprecated
superseded_by: <path-to-new-canonical-article>.md
type: article and status: stable frontmatterstatus: deprecated and a superseded_by pointerexec("ls -A <target-dir>") shows the new filesuperseded_by marker