Interlinked Markdown Wiki

Use this skill when an agent must maintain a navigable knowledge base rather than merely write an isolated document. The knowledge base is a set of reviewable Markdown files whose links, sources, time semantics, and unresolved questions remain inspectable by a person and by simple repository tools.

Operating contract

• Treat the knowledge base as a bounded workspace. Read only paths and sources the operator has made available; do not discover or copy unrelated data.
• Preserve source facts. Never overwrite an immutable source snapshot, silently delete a page, or turn an inference into an organization fact.
• Default to read-only analysis or a draft. When a write is authorized, make the smallest additive or revisioned change and record what changed.
• Keep facts, interpretations, proposed changes, and unknowns in separate sections. Cite the source page or snapshot for every material claim.
• Prefer deterministic Markdown and plain-text indexes over a database or opaque embedding store. A graph or vector index may be an optional derived view, never the only copy of knowledge.
• Treat conflicting sources as unresolved until a human or an explicitly authoritative source settles the conflict.

Knowledge package layout

Use an existing workspace layout when one is already established. Otherwise create or propose this layout before writing:

knowledge/
├── pages/              # curated topic pages, one stable page per concept
├── sources/            # immutable or append-only source snapshots
├── maintenance/       # page ownership, review cadence, and open questions
├── indexes/            # generated navigation, backlinks, and unresolved links
├── reports/            # dated health and change reports
└── activity/           # append-only maintenance events

Do not create all directories merely as placeholders. Create only the parts needed for the requested operation and explain any proposed additions.

Page and source shapes

Every curated page should begin with frontmatter like:

---
id: topic-slug
title: Human-readable title
type: topic
status: draft
aliases: []
updated_at: 2026-01-01T00:00:00Z
review_after: 2026-04-01
sources:
  - source-id
---

Required page rules:

• id is stable, lowercase, and unique; renaming a title does not change it.
• status is one of draft, review, published, stale, or archived. Archiving requires an explicit human decision and a replacement or reason.
• updated_at records the page revision time, not the source publication time.
• review_after is a review prompt, not proof that the page became false.
• sources names source records; do not cite a source that was not captured or otherwise made available.
• Use [[topic-slug]] for internal links. Use an alias only when it resolves unambiguously, such as [[topic-slug|display text]].

Source records should preserve the original text or a bounded snapshot, with:

---
id: source-id
kind: document
title: Source title
origin: https://example.invalid/original
retrieved_at: 2026-01-01T00:00:00Z
published_at: UNKNOWN
content_hash: sha256:UNKNOWN
authority: stated | inferred | unknown
---

If a source changes, append a new snapshot or revision record. Do not make a mutable page appear to be an immutable source.

Validate the page-to-source relationship, not only the presence of a sources field:

• every page source ID must match exactly one source record in the bounded sources/ set;
• page IDs and source IDs must each be unique;
• status must be one of draft, review, published, stale, or archived;
• source kind must identify the capture (document, message, web, record, or unknown) and authority must be stated, inferred, or unknown;
• content_hash must be sha256:<64 hexadecimal characters> when known; sha256:UNKNOWN is an explicit review signal, not a verified hash.

If a page cites a missing source, report the source ID and page ID together; do not silently drop the citation or treat a syntactically valid frontmatter field as evidence that the source exists.

Maintenance workflow

1. Inventory: identify the requested workspace, existing layout, authority boundary, and the sources actually available.
2. Capture: preserve new source material with retrieval time and provenance before synthesizing it. Mark missing metadata UNKNOWN.
3. Plan: choose create, revise, link, review, or report mode. List pages and indexes that may change before making writes.
4. Synthesize: write a concise page that separates source-backed facts, interpretation, decisions, open questions, and conflicting evidence.
5. Link: add links to related pages and update the backlink/index view. Keep links stable even when display titles change.
6. Audit: detect broken links, duplicate IDs, orphan pages, stale review dates, missing citations, source drift, and unrecorded changes.
7. Report: produce a dated maintenance event and a human-readable health report. State what was changed, what was not changed, and what needs review.

For a deterministic file-level audit, emit separate result sets for:

• unresolved links: a page points to an ID that is not present;
• orphans: a page has neither an incoming nor an outgoing internal link;
• roots: a page has no incoming link but does have an outgoing link;
• missing sources: a page cites an ID absent from the source records;
• stale review: review_after is earlier than the scan date;
• unknown source metadata: missing/UNKNOWN authority, retrieval time, publication time, or content hash.

Do not collapse roots into orphans: a deliberately navigational entry page is different from a disconnected page. A simple script, repository validator, or manual inspection may perform this audit; the report must preserve these categories and list the affected IDs.

Index and health report

An index is a derived view and may be regenerated. At minimum it should make these conditions visible:

• page ID, title, status, last update, and review date;
• outgoing links and backlinks;
• unresolved link targets and duplicate IDs;
• pages with no source, no inbound link, or no recent review;
• source records with missing retrieval/authority metadata;
• conflicting claims or pages awaiting human review.

Use counts only as evidence from the current snapshot. A zero count means "none found in this scan", not "none exists".

The health report should also include the scan timestamp, bounded root, validator or method used, and a short disposition for each non-empty result set. If a report was generated from a lightweight script rather than a repository command, name the script/method instead of implying a stronger validation guarantee.

Append an activity event for every maintenance pass that changes or derives knowledge. Use an append-only Markdown record with at least:

---
event_id: 2026-01-01T00-00-00Z-knowledge-audit
actor: agent-or-person
occurred_at: 2026-01-01T00:00:00Z
mode: audit | draft | revise | publish | archive
changed_paths: []
source_ids: []
unresolved_risks: []
---

For publication, conflict resolution, deletion, archival, access changes, or high-impact claims, add a review-queue item before taking the action. Include an item ID, request type, status, evidence paths, owner, created time, and the explicit human decision (or PENDING).

Safe change and review boundaries

• For uncertain synthesis, create or update a draft page and add an item to maintenance/review-queue.md instead of publishing it.
• For destructive requests, prepare a proposed deletion/archive record and ask for explicit confirmation; do not remove the only copy of a source.
• For access-controlled or personal data, preserve the access boundary and record that the source was unavailable rather than requesting broader access.
• For automated recurring maintenance, append an activity event with actor, timestamp, changed paths, source IDs, and unresolved risks.
• A health report is not an approval, legal conclusion, product decision, or claim that the knowledge base is complete.

Completion checklist

Before declaring a maintenance task complete, verify:

• every changed page has stable frontmatter and source references;
• all [[wikilink]] targets resolve or are listed as unresolved;
• backlinks/indexes reflect the changed links;
• source snapshots were not rewritten or silently omitted;
• freshness, conflicts, unknowns, and review work are explicit;
• the activity log and dated health report describe the result.