Loading
Investigate a topic against preserved sources and write a draft-status research article under `research/` in a Knowledge Base project (the `knowledge-base` starter pack). Read when asked to research a
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 research -a cursor -y
Investigate a topic against preserved sources and write a draft-status research article under `research/` in a Knowledge Base project (the `knowledge-base` starter pack). Read when asked to research a topic, compare options, synthesize sources, gather evidence, or extend an existing research doc. Carries the full procedure: scan existing coverage, agree a research rubric, capture every source verbatim before analyzing, write the article incrementally so a crash never loses work, cite every claim, and link it back into the graph. Does not promote findings to canonical knowledge — that is the sibling `consolidate-notes` skill, after a decision lands.
Investigate a topic against preserved sources and write a draft-status research article under `research/` in a Knowledge Base project (the `knowledge-base` starter pack). Read when asked to research a topic, compare options, synthesize sources, gather evidence, or extend an existing research doc. Carries the full procedure: scan existing coverage, agree a research rubric, capture every source verbatim before analyzing, write the article incrementally so a crash never loses work, cite every claim, and link it back into the graph. Does not promote findings to canonical knowledge — that is the sibling `consolidate-notes` skill, after a decision lands.
research/ in a Knowledge Base project (the knowledge-base starter pack). Read when asked to research a topic, compare options, synthesize sources, gather evidence, or extend an existing research doc. Carries the full procedure: scan existing coverage, agree a research rubric, capture every source verbatim before analyzing, write the article incrementally so a crash never loses work, cite every claim, and link it back into the graph. Does not promote findings to canonical knowledge — that is the sibling consolidate-notes skill, after a decision lands."
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.
Conduct evidence-driven research on a topic and produce a provisional research article under research/. Provisional, not canonical: research articles capture findings, trade-offs, and open questions at a point in time. They are promoted to canonical articles via the /consolidate-notes skill only when decisions solidify.
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.
status: draft and an inline sources: frontmatter list pointing at raw sources captured via the ingest procedure. This is the default unless the user explicitly opts out.Path A is the default because provisional articles compound over time; spoken answers do not.
Legacy reads: Existing articles may use status: provisional and string paths under sources:. Treat those as draft research and source resources. Do not mass-rewrite them; new writes use the OKF shapes below.
| Mode | Behavior | How entered |
|---|---|---|
| Supervised (default) | Stop at the scoping gate for user rubric confirmation. Route coverage decisions interactively. | Default when a user drives the session. |
| Headless | Auto-confirm rubric after proposing it. Auto-select routing decisions. Skip interactive prompts. All other gates (scan, analysis, validation, grounding) still enforced. | Explicit "don't wait for me", "just proceed", "run headless" — or non-interactive container environments. |
In headless mode, propose the rubric AND proceed immediately. Mark the Scoping task completed after proposing.
Hard gates — do NOT skip ahead. If you find yourself about to run a WebFetch or WebSearch without completing Steps 0-2, STOP — you skipped a gate.
Path B shortcut: If the user explicitly requested a direct answer in Step 2, skip Steps 5 and 7. Steps 0, 1, 3, 4, 6, 8 still apply (evidence discipline doesn't relax just because output is conversational).
Research articles default to external framing — investigating third-party topics, technologies, concepts, public repos, papers, official docs. Do NOT mix the user's own codebase analysis into the research article unless the user explicitly asks. Mixing drifts findings from factual synthesis toward opinion-forming applied to the organization, reducing factual fidelity.
PERSIST AS YOU GO — crash-safe checkpoint rule. The single most expensive failure this procedure produces is completed research lost to a mid-session rate limit or crash — analysis held in context, never written, discarded when the session died. The user paid for work that vanished. The knowledge base is the checkpoint; two rules make every step crash-safe:
edit its findings into the article before moving to the next. A crash after reading five of eight sources then leaves five sections safely in the KB; you resume by reading the partial article back, not by re-running the whole sweep.Structured notes that live only in your context are not persisted work. If a finding is worth keeping, it belongs in an ingested source or in the article — written, not held.
ALWAYS THE FIRST ACTION. Before any read, any scan, any fetch — create tasks. They persist across context compaction, make skipped steps immediately visible, and show progress to the user.
Create these tasks via your host's task system (TaskCreate in Claude; equivalent elsewhere):
TaskCreate: "Research: Scan existing coverage + route" → start as in_progress
TaskCreate: "Research: Collaborative scoping — rubric gate" → pending, blocked by #1
TaskCreate: "Research: Capture sources via ingest" → pending, blocked by #2
TaskCreate: "Research: Read + analyze" → pending, blocked by #3
TaskCreate: "Research: Write the research article" → pending, blocked by #4
TaskCreate: "Research: Link aggressively + file Q&A back" → pending, blocked by #5
TaskCreate: "Research: Validate (frontmatter + dead-links)" → pending, blocked by #6
TaskCreate: "Research: Recap + follow-up directions" → pending, blocked by #7
Use the host's blocked-by relation to enforce ordering. As you complete each step, mark the task completed and the next task in_progress.
Path B variant: If scoping determines Path B (direct answer), drop tasks #5 and #7 — they don't apply.
Path C variant: If Step 1 routes to Path C (update existing), drop tasks #3 and #5 (ingest is usually unnecessary and no new article is created) and rename task #4 to "Research: Read existing article + diff deltas."
Why tasks: the observed failure mode is the agent jumping straight to WebFetch without scanning or scoping. Tasks make the skipped gates obvious to the user mid-session.
MANDATORY FIRST RESEARCH STEP. Before any external fetch, scan what the knowledge base already holds.
If the user explicitly references an existing research article (names it, links it, says "update/refresh/extend"): → Skip the scan. Go directly to Path C.
Otherwise, always scan first:
exec("grep -rln <topic-keyword> <content-dir>") — returns matching files with frontmatter enrichment so you can judge relevance without opening each.exec("ls -A <content-dir>") — surfaces folder layout and most-recent-updated doc per subdir.exec("cat <path>") — returns full doc + frontmatter + backlinks + recent shadow-repo activity.Classify:
| Coverage | What it means | Route to |
|---|---|---|
| Fully covered | An existing article directly answers the question with evidence | Present findings; offer to elaborate, verify, extend, or explicitly new-report |
| Partially covered | Related research exists; the specific question is a natural extension | Offer: (1) extend existing via Path C, (2) new article via Path A |
| Not covered | No meaningful overlap | Proceed to Path A (default) or Path B |
Fully covered:
"We already have research on this in
<path>. Here's what it found: [2-4 key findings]. Options: (1) use as-is, (2) verify / refresh (article is from [date]), (3) extend on [specific dimension], (4) new angle if this is a different framing."
Let the user choose. Do NOT start new research when existing research already answers the question.
Partially covered:
"We have related research in
<path>covering [scope]. Your question about [topic] isn't directly answered but it's a natural extension. Options: (1) extend existing via Path C, (2) start new article via Path A. I'd recommend [1 or 2] because [reason]."
Not covered:
Proceed to Step 2 (scoping). If the user asked for a quick answer, flag that Path B may apply and confirm in Step 2's scoping exchange.
Headless mode: auto-select — fully-covered → proceed to new article on the specific angle the caller requested; partially-covered → start new article; not-covered → Path A.
HARD GATE (Supervised mode). Do NOT start external research until the user confirms the rubric. After proposing it, STOP and WAIT for user response. Only then mark the Scoping task completed.
In headless mode: propose the rubric AND proceed. Mark the task completed after proposing.
Return this structure to the user:
## Proposed research rubric
**Question:** [narrowed from the original topic — concrete, answerable, bounded]
**Dimensions to investigate:** [3-7 facets]
1. [Dimension 1]
2. [Dimension 2]
...
**Candidate sources:** [3-8 initial guesses]
- [Source 1 — why it's relevant]
- [Source 2 — why it's relevant]
...
**Success criteria:** [2-3 concrete outcomes — "the article cites X authoritative sources", "open questions are marked explicitly", etc.]
**Output format:** Path A (article) | Path B (direct answer) | Path C (update `<existing-article>`)
For each relevant URL, paper, or document in the confirmed rubric, follow the ingest procedure — it lives in the platform /open-knowledge skill at references/ingest-and-sources.md, not in this pack. Typical research pulls 3-8 sources. Too few → thin synthesis. Too many → you'll be reading for the rest of the session.
curl -sL <url>, or ask the user to paste).Read each ingested source carefully. Also load:
exec("cat <path>") (returns frontmatter + backlinks + shadow-repo activity).exec("cat <path>") for OpenKnowledge markdown.Read for .ts / .js / etc.; exec for in-scope .md / .mdx.Take structured notes:
Write these notes into the article as you take them, not after (MUST — see Persist as you go above). Create the article skeleton — frontmatter + the Step 5 section headings — before you start reading, then edit each source's findings into the relevant section the moment you finish analyzing it. The "notes" ARE the article's Findings section in progress; don't hold them in context to transcribe in one pass at Step 5. A rate limit between here and Step 5 must not be able to discard analysis you've already done. By the time you reach Step 5 the article is mostly written, and Step 5 becomes finalize-and-polish.
Every factual claim in the article must cite its source inline. No unsourced speculation. If you don't have evidence: (a) run another search and cite it, (b) mark inline (TODO: needs source), or (c) don't write the claim. Never fabricate.
If you followed Persist as you go, the article already exists and is substantially filled from Step 4 — this step finalizes it (fill any remaining sections, tighten the recommendation, run the structure + validation checks below) rather than writing from a blank doc. If it does not exist or is thin, and you are resuming after an interruption: exec("cat <path>") the partial article back first and fill only the missing sections — and note that any Step 4 analysis that was never written to the KB was lost when the session broke, so re-derive only what's actually missing. Creating the doc from scratch here means the incremental rule was skipped; that's the failure mode, not the happy path.
Save a markdown document inside the content directory. Path convention:
external-sources/ → research/ → articles/), save under research/<slug>.md.research/<topic>/<subtopic>.md.Filename: descriptive, kebab-case (crdt-alternatives-for-editor.md, llm-wikis-and-knowledge-bases.md). No dates — dates go in frontmatter.
---
title: Descriptive title
description: One-line summary of the research question
type: research-note
status: draft
date: YYYY-MM-DD
tags:
- research
- provisional
- <topic-tag>
sources:
- resource: ../external-sources/<source-1>.md
- resource: ../external-sources/<source-2>.md
---
## Question
[What specific question does this research answer? Be precise.]
## Context
[Why does this matter? What decision does it inform? Who is the reader?]
## Findings
[Main findings organized by theme, option, or criterion. Every claim cites a source inline.]
### Theme / Option 1
- Pros — with evidence links
- Cons — with evidence links
- Evidence: [Source A](../external-sources/source-a.md), [Source B](../external-sources/source-b.md)
### Theme / Option 2
...
## Trade-offs
[What you gain vs. lose with each option. A comparison table often helps.]
## Open questions
[What you still don't know — candidates for further research, prototyping, or human-judgment decisions.]
## Tentative recommendation
[Your best guess, clearly marked as tentative. Explain the reasoning so a future reader can re-evaluate when new information arrives.]
## Further reading
[Links to the ingested sources + adjacent research + any canonical articles on the topic.]
/consolidate-notes skill's job, after decisions land.Research articles are discovery surfaces. Under-linked research becomes an island nobody finds.
[text](./relative/path.md).sources: list: According to [LLM Agents](../external-sources/llm-agents.md)... is stronger than a bare sources: entry.If the user asked a specific question during the research session that produced a citable answer, capture it as its own short page alongside the research — not just as chat. Concrete questions with sourced answers are the highest-signal unit of knowledge you can produce.
what-does-X-mean.md, how-does-Y-work.mdsources: frontmatterRun this checklist before marking complete:
title, description, type: research-note, status: draft, date, and an object-shaped sources: listexec("ls -A <dir>") lists the new file with frontmatter enrichmentaudit({ path: "<doc-path>.md" }) returns clean (every lint violation + broken internal link) — fix every findingClose the loop with the user in conversation:
## Recap
- [Finding 1 — with source]
- [Finding 2 — with source]
- [Key trade-off / contradiction surfaced]
- [1-2 open questions that remain]
**Tentative recommendation:** [state it in one sentence]
**Follow-up research directions** (Path A candidates for later):
1. [Direction 1 — what would it investigate?]
2. [Direction 2 — what would it investigate?]
3. [Direction 3 — what would it investigate?]
Follow-ups should be external-source investigations — not actions on the user's codebase (those belong in a spec, not more research). Each direction should be a standalone topic someone could later research.
In headless mode, write the recap into the research article's "Further reading" section rather than prompting interactively.
/consolidate-notes skill's job after a decision actually lands. Premature canonicalization buries uncertainty and misleads future readers.crdt-alternatives-2.md) and mark the old one as superseded.