Wiki Narrate — Cited Narrative Readouts
Use this skill only for a topic-based Markdown readout. Do not add tag or page-list
selection, prior-query input, voice aliases, HTML, PDF, slides, renderer handoffs, or
new compiled knowledge pages.
Command Contract
/wiki-narrate <topic> [--voice briefing|plain-language|lecturer] [--save]
- Require a non-empty
<topic>.
- The default voice is
briefing.
- Voice names are canonical and case-sensitive. Unsupported values must return an
error listing
briefing, plain-language, and lecturer without searching or
writing.
--save is the only persistence switch.
- For a missing topic, malformed option, or unsupported voice, return a short usage
or validation error and do not search, write, append a log event, or change
hot.md.
Retrieval
Writing profile: Before drafting or rewriting natural-language Markdown, read and apply the Writing Profile Resolution section in llm-wiki/SKILL.md. Framework schema, provenance, safety, and operation-specific requirements take precedence.
WRITING.md preferences apply only to newly drafted or rewritten natural-language Markdown; preserve source content and structured records.
- Resolve configuration with the Config Resolution Protocol, including an inline
@name vault override, then read the target vault's AGENTS.md when it exists.
Load OBSIDIAN_LINK_FORMAT before drafting citations.
- Read
hot.md and index.md first. Select candidates by frontmatter and summary
before reading bodies.
- When configured, use QMD before
rg; if QMD is absent, unconfigured, or fails,
continue with the index and rg path. Treat QMD output as candidate guidance, not
evidence: establish each claim from the allowed vault page itself.
- Honor filtered-mode phrases such as "public only", "user-facing", "no internal
content", "as a user would see it", and "exclude internal". Skip pages tagged
visibility/internal or visibility/pii in that mode: never read, cite, or expose
them.
- Exclude
_readouts/, _raw/, _archives/, _meta/, index.md, log.md,
hot.md, and _insights.md from candidates.
- Read matching sections before full pages, and read full pages only when a factual
claim cannot otherwise be established. Preserve relevant lifecycle and freshness
annotations; do not upgrade a page's trust.
Claim Ledger and Citation Audit
Draft a ledger before prose. Each item contains a claim, supporting [[vault page]]
links, and one status: supported fact, inferred connection, or ambiguous conflict.
When OBSIDIAN_LINK_FORMAT=markdown, render the same supporting page as a standard
Markdown link; otherwise use the vault's [[wikilink]] form.
Ensure every factual sentence has adjacent supporting citations. Mark inferred connections ^[inferred]; mark unresolved conflicts ^[ambiguous]. Never use web knowledge, model memory, or invented examples to close a gap. Omit unsupported claims and name the gap in Coverage. An inference or ambiguity marker supplements, rather than replaces, adjacent citations.
Drafting and Output
Read references/voices.md and use exactly the requested voice skeleton. The selected
voice may change prose and ordering, but cannot change the ledger's factual boundary.
Return Markdown only, structured as:
- A title naming the topic and selected voice.
- The selected voice's sections, in its documented order.
- Adjacent citations for each factual sentence, rendered with
OBSIDIAN_LINK_FORMAT.
- A
## Coverage footer listing cited pages, the count of inferred statements, and
known evidence gaps.
If evidence is weak or contradictory, produce only the supported portion. Mark each
unresolved conflict ^[ambiguous] with citations to all conflicting pages, and list
the remaining gaps in ## Coverage.
Persistence
Present the result by default. For --save, create _readouts/ if necessary and write
_readouts/<slug>.md with title, topic, voice, sources, created, and
updated frontmatter. Use a deterministic, filesystem-safe <slug> derived from the
topic. Save the same completed Markdown readout that was returned in conversation.
A readout is derived output: exclude _readouts/ from retrieval and must not update index.md or .manifest.json. Do not create _readouts/ or a readout file without a successful --save result.
Logging and Hot Cache
After a narration attempt that reaches retrieval, append one WIKI_NARRATE event to
log.md:
- [TIMESTAMP] WIKI_NARRATE topic="<topic>" voice=<voice> result_pages=N mode=normal|filtered saved=true|false outcome=success|no_match|write_failed
- Without
--save, append the event with saved=false after returning the readout;
do not create a readout or change hot.md.
- After a successful
--save write, append the event with saved=true, then refresh
hot.md with the topic, voice, cited pages, inference count, evidence gaps, and
saved readout path. hot.md changes only after a successful save.
- If the readout write fails after drafting, return the completed readout in
conversation, report that saving failed, append a
WIKI_NARRATE event with
saved=false outcome=write_failed when log.md remains writable, and do not update
hot.md.
- If appending
log.md fails, preserve the readout result and report the logging
failure separately. Never represent a failed log or save as successful.
Safe Failure Behavior
- No matching pages: explain that the vault lacks material for the topic. Create
no readout file even if
--save was requested, do not change hot.md, and record a
WIKI_NARRATE event with outcome=no_match when log.md is writable.
- Weak evidence or source conflict: do not resolve it with outside knowledge.
Return only supported claims, label ambiguity where applicable, and make the gap
explicit in
## Coverage; saving remains available for that successful partial
readout.
- QMD unavailable or unconfigured: state the fallback briefly in the working
update and continue safely through
index.md and rg; do not fail the narration
merely because QMD is unavailable.
- Write failure: never leave a partial readout presented as saved, never update
hot.md, and never update index.md or .manifest.json.
1---
2name: wiki-narrate
3description: >
4 Turn a wiki topic into a cited Markdown briefing, plain-language explanation, or
5 progressive lecture. Use this skill for topic-based briefing, explanation, and
6 lecture requests that must stay within the evidence compiled in an Obsidian vault.
7metadata:
8 source: https://skillmd.com/skills/ar9av/wiki-narrate
9---
10
11# Wiki Narrate — Cited Narrative Readouts
12
13Use this skill only for a topic-based Markdown readout. Do not add tag or page-list
14selection, prior-query input, voice aliases, HTML, PDF, slides, renderer handoffs, or
15new compiled knowledge pages.
16
17## Command Contract
18
19`/wiki-narrate <topic> [--voice briefing|plain-language|lecturer] [--save]`
20
21- Require a non-empty `<topic>`.
22- The default voice is `briefing`.
23- Voice names are canonical and case-sensitive. Unsupported values must return an
24 error listing `briefing`, `plain-language`, and `lecturer` without searching or
25 writing.
26- `--save` is the only persistence switch.
27- For a missing topic, malformed option, or unsupported voice, return a short usage
28 or validation error and do not search, write, append a log event, or change `hot.md`.
29
30## Retrieval
31
32**Writing profile:** Before drafting or rewriting natural-language Markdown, read and apply the `Writing Profile Resolution` section in `llm-wiki/SKILL.md`. Framework schema, provenance, safety, and operation-specific requirements take precedence.
33`WRITING.md` preferences apply only to newly drafted or rewritten natural-language Markdown; preserve source content and structured records.
34
351. Resolve configuration with the Config Resolution Protocol, including an inline
36 `@name` vault override, then read the target vault's `AGENTS.md` when it exists.
37 Load `OBSIDIAN_LINK_FORMAT` before drafting citations.
382. Read `hot.md` and `index.md` first. Select candidates by frontmatter and summary
39 before reading bodies.
403. When configured, use QMD before `rg`; if QMD is absent, unconfigured, or fails,
41 continue with the index and `rg` path. Treat QMD output as candidate guidance, not
42 evidence: establish each claim from the allowed vault page itself.
434. Honor filtered-mode phrases such as "public only", "user-facing", "no internal
44 content", "as a user would see it", and "exclude internal". Skip pages tagged
45 `visibility/internal` or `visibility/pii` in that mode: never read, cite, or expose
46 them.
475. Exclude `_readouts/`, `_raw/`, `_archives/`, `_meta/`, `index.md`, `log.md`,
48 `hot.md`, and `_insights.md` from candidates.
496. Read matching sections before full pages, and read full pages only when a factual
50 claim cannot otherwise be established. Preserve relevant lifecycle and freshness
51 annotations; do not upgrade a page's trust.
52
53## Claim Ledger and Citation Audit
54
55Draft a ledger before prose. Each item contains a claim, supporting `[[vault page]]`
56links, and one status: supported fact, inferred connection, or ambiguous conflict.
57When `OBSIDIAN_LINK_FORMAT=markdown`, render the same supporting page as a standard
58Markdown link; otherwise use the vault's `[[wikilink]]` form.
59
60Ensure every factual sentence has adjacent supporting citations. Mark inferred connections `^[inferred]`; mark unresolved conflicts `^[ambiguous]`. Never use web knowledge, model memory, or invented examples to close a gap. Omit unsupported claims and name the gap in Coverage. An inference or ambiguity marker supplements, rather than replaces, adjacent citations.
61
62## Drafting and Output
63
64Read `references/voices.md` and use exactly the requested voice skeleton. The selected
65voice may change prose and ordering, but cannot change the ledger's factual boundary.
66Return Markdown only, structured as:
67
681. A title naming the topic and selected voice.
692. The selected voice's sections, in its documented order.
703. Adjacent citations for each factual sentence, rendered with
71 `OBSIDIAN_LINK_FORMAT`.
724. A `## Coverage` footer listing cited pages, the count of inferred statements, and
73 known evidence gaps.
74
75If evidence is weak or contradictory, produce only the supported portion. Mark each
76unresolved conflict `^[ambiguous]` with citations to all conflicting pages, and list
77the remaining gaps in `## Coverage`.
78
79## Persistence
80
81Present the result by default. For `--save`, create `_readouts/` if necessary and write
82`_readouts/<slug>.md` with `title`, `topic`, `voice`, `sources`, `created`, and
83`updated` frontmatter. Use a deterministic, filesystem-safe `<slug>` derived from the
84topic. Save the same completed Markdown readout that was returned in conversation.
85
86A readout is derived output: exclude `_readouts/` from retrieval and must not update `index.md` or `.manifest.json`. Do not create `_readouts/` or a readout file without a successful `--save` result.
87
88## Logging and Hot Cache
89
90After a narration attempt that reaches retrieval, append one `WIKI_NARRATE` event to
91`log.md`:
92
93```
94- [TIMESTAMP] WIKI_NARRATE topic="<topic>" voice=<voice> result_pages=N mode=normal|filtered saved=true|false outcome=success|no_match|write_failed
95```
96
97- Without `--save`, append the event with `saved=false` after returning the readout;
98 do not create a readout or change `hot.md`.
99- After a successful `--save` write, append the event with `saved=true`, then refresh
100 `hot.md` with the topic, voice, cited pages, inference count, evidence gaps, and
101 saved readout path. `hot.md` changes only after a successful save.
102- If the readout write fails after drafting, return the completed readout in
103 conversation, report that saving failed, append a `WIKI_NARRATE` event with
104 `saved=false outcome=write_failed` when `log.md` remains writable, and do not update
105 `hot.md`.
106- If appending `log.md` fails, preserve the readout result and report the logging
107 failure separately. Never represent a failed log or save as successful.
108
109## Safe Failure Behavior
110
111- **No matching pages:** explain that the vault lacks material for the topic. Create
112 no readout file even if `--save` was requested, do not change `hot.md`, and record a
113 `WIKI_NARRATE` event with `outcome=no_match` when `log.md` is writable.
114- **Weak evidence or source conflict:** do not resolve it with outside knowledge.
115 Return only supported claims, label ambiguity where applicable, and make the gap
116 explicit in `## Coverage`; saving remains available for that successful partial
117 readout.
118- **QMD unavailable or unconfigured:** state the fallback briefly in the working
119 update and continue safely through `index.md` and `rg`; do not fail the narration
120 merely because QMD is unavailable.
121- **Write failure:** never leave a partial readout presented as saved, never update
122 `hot.md`, and never update `index.md` or `.manifest.json`.