Ar9av/obsidian-wiki / skills/wiki-narrate
wiki-narrate
VerifiedTurn a wiki topic into a cited Markdown briefing, plain-language explanation, or progressive lecture. Use this skill for topic-based briefing, explanation, and lecture requests that must stay within the evidence compiled in an Obsidian vault.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.6 KB |
| references/voices.md | markdown | 646 B |
SKILL.md
View on GitHub---
name: wiki-narrate
description: >
Turn a wiki topic into a cited Markdown briefing, plain-language explanation, or
progressive lecture. Use this skill for topic-based briefing, explanation, and
lecture requests that must stay within the evidence compiled in an Obsidian vault.
---
# 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.
1. 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.
2. Read `hot.md` and `index.md` first. Select candidates by frontmatter and summary
before reading bodies.
3. 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.
4. 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.
5. Exclude `_readouts/`, `_raw/`, `_archives/`, `_meta/`, `index.md`, `log.md`,
`hot.md`, and `_insights.md` from candidates.
6. 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.
## Approved Facts Gate
If `$OBSIDIAN_VAULT_PATH/_meta/facts.md` exists, read its approved rows before
drafting. They are the claims about the owner and their company that may be repeated
in public. Before returning the readout, pipe the draft through
`obsidian-wiki facts check - --vault "$OBSIDIAN_VAULT_PATH" --json`:
- `retired`: the sentence uses a claim the owner has retired. Replace it with the
current approved fact, or drop it. Never ship a retired claim.
- `unsupported`, about the owner or their company (their numbers, customers,
rankings, certifications): keep it only if an adjacent vault citation supports it,
and list it in `## Coverage` under "Not in approved facts". In filtered mode
("public only", "user-facing"), drop it instead.
- `unsupported`, about anything else: no action. The check is a heuristic.
If the file is missing or the command is unavailable, skip this gate silently.
## 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:
1. A title naming the topic and selected voice.
2. The selected voice's sections, in its documented order.
3. Adjacent citations for each factual sentence, rendered with
`OBSIDIAN_LINK_FORMAT`.
4. 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`.
## Owner Voice
If `$OBSIDIAN_VAULT_PATH/_meta/voice.md` exists, read it with
`obsidian-wiki voice show --json --vault "$OBSIDIAN_VAULT_PATH"` before drafting.
Open a few of the `love` pages for rhythm and word choice, and skim the `hate` pages
for what to avoid. The voice file shapes prose only. It never adds a claim the
ledger lacks, and it never changes the selected voice's section skeleton.
Before returning, pipe the draft through `obsidian-wiki voice check -`. Rewrite every
flagged word or phrase, using the suggested replacement when one is given, and check
again. Quoted source text keeps its original words. If the file is missing or the
command is unavailable, skip this step silently.
## 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`:
```bash
obsidian-wiki memory log WIKI_NARRATE \
topic="<topic>" voice=<voice> result_pages=<N> \
mode=<normal|filtered> saved=<true|false> \
outcome=<success|no_match|write_failed>
```
This is the **only** write a narration without `--save` may perform. Do not touch `index.md` or `hot.md` by hand.
- 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
the hot cache with a one-line takeaway naming the topic, voice, cited-page count, and
saved readout path: `obsidian-wiki memory hot --takeaways "<line>"`. `hot.md` changes
only after a successful save, and only through that command.
- 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`.
Before explicit takeaway replacement, read/reconcile the full current Key Takeaways and obtain TAKEAWAYS_REVISION from hot.takeaways_sha256 in memory status --json (llm-wiki/references/MEMORY.md). Preserve still-valid owner conclusions. Omit --takeaways for mechanical bookkeeping; stale revisions require review, not blind retry.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |