skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
ar9av/obsidian-wiki408 installs

wiki-narrate

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.

How do I install this agent skill?

npx skills add https://github.com/ar9av/obsidian-wiki --skill wiki-narrate
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    This skill generates briefings from Obsidian vault content using local CLI tools and file operations. It incorporates privacy filters for sensitive data. Primary security considerations include indirect prompt injection from vault content and potential command injection in shell-based logging.

  • Socketpass

    No alerts

  • Snykwarn

    Risk: MEDIUM · 1 issue

What does this agent skill do?

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:

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.

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/ar9av/obsidian-wiki/wiki-narrate">View wiki-narrate on skillZs</a>