| name | paper-distillation |
| description | Use when the user wants to distill a captured paper into a canonical wiki page, write the wiki page for a paper, or process the raw evidence of a specific paper. Handles the raw/evidence to wiki/papers transition. |
Paper Distillation
Overview
Turn captured raw evidence (raw/evidence/<paper_id>.md) into a canonical paper page (wiki/papers/<slug>.md). This is the cognitive step where an agent reads a long captured document and produces a short, structured, cross-linked summary with required metadata and concept links.
This skill runs after paper-intake has captured the evidence. For read/index work, use docs/qmd-cli.md and runtime qmd --help.
Available Tools
| Tool | Purpose |
|---|
distill_paper | Resolve raw evidence and write one canonical paper page from a distilled payload |
distill_papers | Apply the same distillation write workflow sequentially to a batch |
upsert_wiki_page | Write the canonical paper page with write-time schema validation |
check_concept_alias | Resolve concept surfaces before linking |
Routing Decision
- User asked to distill, write the wiki page for, or process the raw evidence of a specific paper: locate the evidence with
qmd get, distill_paper(input_value) or by paper_id, read it, extract the structured summary, and call distill_paper(input_value, distilled=...) or upsert_wiki_page(page_type="paper", ...).
- User asked to distill a batch: run the single-paper flow per paper sequentially; use
distill_papers(items) only after each item has grounded distilled content.
- User asked to distill but the paper has not been captured yet: hand off to
paper-intake to run ingest_and_read first.
Required Frontmatter
Every canonical paper page requires:
paper_id — string, e.g. arxiv:2406.09246.title — full paper title.year — integer publication year.venue — publication venue or arXiv if preprint-only.source_layer — usually wiki.key_concepts_topk — one to five canonical concept surfaces, each wikilinked at least once in the body.
The write-time validator rejects pages that violate any of these constraints. Do not attempt to work around the validator by hand-editing files.
Distillation Flow
qmd get the raw evidence file for the paper.- Read the evidence with the extraction questions in references/extraction-template.md in mind.
- Choose
key_concepts_topk using the rules in references/concept-selection.md — prefer reusing existing concepts, call check_concept_alias when uncertain.
- Draft the body following the section structure in references/writing-style.md.
- Call
upsert_wiki_page(page_type="paper", target=<slug>, frontmatter=..., body=...).
- If any entry in
key_concepts_topk is new to the vault and meets the bar for a concept page, create it via upsert_wiki_page(page_type="concept", ...) in a follow-up call.
- Recommend
qmd update after the write round; recommend qmd embed -f only if semantic retrieval must reflect the new page immediately.
Rules
- Distillation is agent-side cognition. Do not copy abstracts verbatim; extract the specific problem, method, results, novelty, and limitations.
- Every
key_concepts_topk entry must appear as [[Concept Name]] at least once in the body.
- Do not edit
raw/evidence/ during distillation — it is the preserved source and must stay intact.
- If the evidence is too shallow to distill (short capture, missing sections), report this as a warning and stop. Do not invent content.
- If the paper draws a strong contrast with an existing vault paper, add a cross-link in the
Relations section so future qmd query runs can surface the comparison.
- After the page lands, apply the Insights Triggers convention in ../../CLAUDE.md: offer (do not auto-write) a conversation or idea note if the distillation surfaced a cross-paper observation or an open research question.
Skill / Tool Contract
This skill is responsible for reading raw evidence, extracting structure, selecting concepts, and producing pages that satisfy write-time validation.
Python tools are responsible for deterministic writes, schema enforcement, and structured errors.
