Wikismith

Wikismith

An agent-maintained personal knowledge base. The agent does all the writing and bookkeeping; the user does the sourcing and thinking. See README.md for conceptual background.

Throughout this document, "the agent" means whichever AI agent is running this skill. Claude Code is the tested reference; any Agent Skills–compatible tool that can read and write files should work.

---

Directory layout

/
├── capture/           # All incoming content — quick captures and source documents
│   └── assets/        # Locally downloaded images
├── wiki/              # agent-maintained markdown pages
│   ├── index.md       # Content catalog — read first on every query
│   ├── log.md         # Append-only chronological record
│   ├── overview.md    # High-level synthesis of the whole wiki
│   ├── projects/      # Active deliverables (one folder per project)
│   ├── areas/         # Ongoing responsibilities
│   ├── resources/     # Shared reference-document pool
│   └── archive/       # Inactive projects/areas (created on demand)
└── schema.md          # The schema — wiki conventions and domain config

Organizing model

Three orthogonal axes make the wiki easy to browse and query for both humans and machines:

| Axis | Encoded by | |------|-----------| | Location | PARA bucket (project/area/resource/archive) — the directory the page lives in | | Links | Cross-references from effort pages (projects/areas) to the resources they depend on | | Tags | Namespaced tags (e.g. technology/x, vendor/y) drawn from schema.md's ## Tag vocabulary |

Analyses and member pages live inside their owning project/area folder. schema.md is authoritative on all conventions.

The agent maintains everything in wiki/ and never modifies capture/. All of it belongs to the user.

The capture directory is capture/ by default. schema.md's ## Capture section may rename it or point at a folder the user already saves into (a web clipper's target, for example). Wherever it lives, the operation is still Capture and the items are still captures — throughout this document, capture/ means the configured capture directory. If it lies outside the wiki root, git in the wiki root won't track it; cover it with rclone or its own backup. And if it points at a folder inside another git repository (an already-tracked Obsidian vault, say), leave that repository's ignore rules alone — they aren't this wiki's to configure.

capture/ holds two kinds of content:

• Quick captures — timestamped notes/links/quotes dropped in without processing, named -.md
• Source documents — articles, PDFs, transcripts, and other raw material ready to organize

Both are immutable once written.

---

Startup: finding or creating a wiki

When the user invokes this skill, the agent should:

1. Locate the wiki root. Check if a schema.md or wiki/index.md exists in the

current directory or a parent. If found, that's the wiki root — read schema.md and wiki/index.md to orient. Never the skill's own repository: the folder holding this SKILL.md (the repo the skill was installed from) is not a wiki root, and its files are not a schema — if invoked there, say so and ask where the wiki should live. Legacy fallback: a wiki created with an earlier version names its schema file CLAUDE.md. If schema.md is absent but CLAUDE.md exists at the root, use CLAUDE.md as the schema and offer once to rename it to schema.md (an ordinary file any agent reads, not just Claude Code).

1. If no wiki exists, ask the user:

• What topic/domain is this wiki for?
• Where should the root directory live?

Then initialize the structure (see Init below).

1. If ambiguous (multiple candidates), ask the user which one.

---

Init

When creating a fresh wiki:

mkdir -p /capture/assets /wiki

If the user wants captures somewhere else — or already has a folder a clipper saves into — skip creating capture/ and record the location in schema.md's ## Capture section instead.

Create /schema.md using the following template, filled in with the user's domain details:

#  — Wiki Schema

## Domain

## Page types
- **entity** — a person, organization, model, tool, or named thing
- **concept** — an idea, technique, or principle
- **source** — a processed reference document (article, paper, transcript, note); lives in `resources/`
- **analysis** — a comparison, synthesis, decision doc, or express output; owned by one area/project
- **overview** — a high-level synthesis page

## Organizing model
Three orthogonal axes make the wiki easy to browse and query for both humans and machines:

| Axis | Encoded by |
|------|-----------|
| **Location** | **PARA bucket** (Projects/Areas/Resources/Archives) — the directory the page lives in |
| **Links** | **Cross-references** from effort pages (projects/areas) to the resources they depend on |
| **Tags** | **Namespaced tags** (e.g. `technology/x`, `vendor/y`) drawn from `## Tag vocabulary` below |

## Frontmatter fields
All pages use: `type`, `title`, `tags` (namespaced topics only, from `## Tag vocabulary` below), `last_updated`, `source_count`, `distill_level`

## Domain-specific notes

## Tag vocabulary
Namespaced topic tags only. Add here before using; one canonical spelling per concept.
People and companies are entities (a page + a link), not tags.

### technology/
### vendor/
### process/

## Writing style

Base: 

## Capture

Directory: capture/

## Backup

Pattern: 
Command: rclone sync  :

Also create /wiki/projects/, areas/, resources/ directories.

Create /wiki/index.md:

# Index
_Last updated: _

## Resources
| Page | Summary | Date |
|------|---------|------|

## Entities

## Concepts

## Analyses
_Grouped by parent area/project._

Create /wiki/log.md:

# Log

## [] init | Wiki created
Domain: 

Create /wiki/overview.md as a brief placeholder.

Finally, check whether the wiki root is already inside a parent git repo. If it is, do not offer git setup — a nested repo is rarely intended. If it isn't, ask the user: "Do you want to track this wiki with git version control? It keeps a full history, so you can see what changed and restore any earlier version of any page. If unsure, say yes — it's invisible day to day, and it gives you undo." If yes, read setup-git.md and follow its setup steps.

Then ask about cloud backup: "Do you want to back up this wiki to cloud storage via rclone? Options: (1) binaries only — rclone backs up your raw capture files, and git covers the wiki pages (pushed to a remote like GitHub); (2) full repo — rclone syncs everything including git history, no GitHub needed (good for single-user wikis); (3) rclone only — no git, rclone is your only backup. Or skip for now."

If the user chooses a pattern, read setup-rclone.md, ask for the rclone remote name and destination path, then add a ## Backup section to schema.md:

## Backup
Pattern: 
Command: rclone sync  :

For binaries-only, ` is the capture directory (default /capture/). For **full-repo** and **rclone-only**, it is /. If the user skips backup setup, omit the ## Backup` section entirely.

If git was set up and an rclone pattern was chosen, also create the post-commit hook (see setup-rclone.md for the hook script). Skip this step for the rclone-only pattern (no git, no hook).

---

Operations

Capture

Triggered by: "capture this", "quick note", "save this for later", "add to inbox", or any short idea/link/quote the user tosses over without asking for full processing.

Flow:

1. Save the item to capture/-.md with minimal structure:

```markdown --- captured: source: ---

```

1. Confirm: "Captured to capture/. You have N unprocessed items — want me to organize any?"

---

Organize (O in CODE)

Triggered by: "organize this", "process my inbox", "add this to the wiki", "read this article/paper/transcript", dropping a file in capture/, or pasting content directly with the intent to integrate it.

Flow:

1. Read the source. If it's in capture/, read it from there. If pasted, save

to capture/.md first.

1. Discuss with the user — but only if the content is surprising, contradicts

existing wiki pages, or the user's intent is unclear. Surface one key takeaway and ask one focused question at most. Skip discussion entirely if: the user pasted content directly and gave no other instruction, the user said "just organize it", or the source is straightforward (a single clear topic, no contradictions). Default is to proceed, not to ask.

1. Read wiki/index.md to understand what already exists.

1. Assign topic tags + note which efforts it serves. Scan schema.md's ## Tag vocabulary

for existing namespaced tags. Choose the topics that fit, adding new ones to schema.md first. Separately, note which projects/areas the document serves — record that as forward links on those project/area pages (step 6), not as a tag. Confirm briefly if unclear: > "Topics vendor/tektelic + technology/lorawan; serves project/migration. OK?"

1. Write a source summary page in the reference pool — wiki/resources/.md

(schema.md is authoritative on the pool's folder name and conventions): ``markdown --- type: source title: date_organized: tags: [vendor/tektelic, technology/lorawan] distill_level: 0 --- # **Summary:** **Key claims:** bullet list **Cross-references:** links to entity/concept pages this touches ``

1. Update existing wiki pages that this source extends, contradicts, or enriches.

A single source typically touches 5–15 pages. For each affected page:

• Add new information
• Note contradictions inline: > ⚠️ Contradiction: says X, but says Y
• For each project/area page that uses this source: add a forward cross-reference link to the source page (e.g. in a "Resources" or "References" section). This is how the resource-effort relationship is recorded — on the effort side, not on the resource.

1. Create new pages for any entity, concept, or theme that appears significantly

in the source and doesn't have a page yet. File each in the right bucket directory.

1. Update wiki/index.md — add the source to the sources table, add/update

entries for any new or significantly changed pages.

1. Append to wiki/log.md:

`` ## [] organize | Pages updated: New pages: ``

If a .git directory exists in the wiki root, suggest: git add . && git commit -m "organize: ". Wait for user confirmation before running.

1. If the source came from capture/, leave it in place — capture/ is immutable.

The wiki now contains the processed knowledge; the capture file is its provenance.

1. Optionally update wiki/overview.md if the source meaningfully shifts the

overall synthesis.

---

Distill (D in CODE)

Triggered by: "distill this page", "distill my notes on X", "progressive summary", or automatically suggested by the agent when a page reaches 5+ sources. Not triggered by questions like "what are the key ideas on X" — that's a Query.

Forte's progressive summarization: each pass bold-highlights the most important sentences, then a further pass extracts those into a short executive summary at the top. The agent applies this to wiki pages.

Flow:

1. Identify pages to distill. Either the user names a page/topic, or the agent

suggests candidates: pages with high source_count, pages last distilled long ago, or pages the user is about to use for Express.

1. Read the page and its current distill_level (0 = raw, 1 = bolded, 2 = summary added, 3 = condensed).

1. Apply the next distillation level:

• Level 0 → 1: Bold the most important phrases and sentences (≈20% of content).

Don't remove anything yet.

• Level 1 → 2: Add a ## ✦ Distilled Summary block at the top — 3–5 bullets

capturing the essential claims. The full content remains below.

• Level 2 → 3: Condense the body, removing detail that is fully captured in the

summary. Preserve anything the summary doesn't cover. The page should now be significantly shorter without losing meaning.

1. Update distill_level in frontmatter and last_distilled date.

1. Show the user the before/after for approval before writing. Or if the user said

"just distill it", write directly.

1. Append to log:

`` ## [] distill | Level: → ``

If .git exists in the wiki root, suggest: git add . && git commit -m "distill: (level ->)". Wait for user confirmation before running.

---

Express (E in CODE)

Triggered by: "write a draft about X", "create a report on Y", "I need to make a decision about Z", "turn my wiki into something I can share/publish/send". The key signal is a finished artifact for an audience or purpose outside the wiki. Not triggered by "summarize what I know about X" — that's a Query.

Every Express output is a starting draft: the agent assembles it from the wiki; the user reviews, finishes, and owns it.

Flow:

1. Clarify the output type if not obvious:

• Draft (blog post, essay, article) — flowing prose, argument-led
• Report (research summary, briefing) — structured, comprehensive, cited
• Decision doc (options + recommendation) — problem statement, options,

criteria, recommendation, risks

The agent picks the most fitting type based on context and confirms briefly.

1. Read wiki/index.md and pull all relevant pages — prioritize pages with

high distill_level (already refined) and pages in the relevant project/area folder or tagged with related topics. If key pages are at distill_level 0, suggest distilling first.

1. Apply the user's voice, then draft. If a voice profile exists (see Calibrate),

load the base wiki/style.md, then layer the named profile matching the output type on top — schema.md's ## Writing style maps types to profiles; the named profile wins on conflicts, and "do not" rules from both apply. Draft the output in that composed voice, drawing on wiki content with inline citations to source pages. Do not reproduce wiki content verbatim — synthesize and rewrite for the target format. Before finalizing, run the draft against the union of both files' Hard rules and fix any violations. If no profile exists, write in a clean neutral voice, then offer once: "Want me to calibrate a writing-style profile so future drafts sound like you?"

1. Determine the filing location. Every analysis belongs to exactly one area or project — the one

it serves. Infer it from context (the user's active project, the folder/topics of the source pages used) and confirm briefly if unclear: > "I'll file this under project/methanetrack-infra-migration — correct?"

1. For drafts/reports: write the output inside that project/area's folder alongside its

index.md (e.g. wiki/projects//.md, wiki/areas//.md), and give it namespaced topic tags. Promote a flat area/project page to a folder if needed. schema.md is authoritative on placement. Then update index + log.

1. For decision docs: use this structure:

``markdown ## Decision: **Context:** ... **Options:** | Option | Pros | Cons | |--------|------|------| **Criteria:** ... **Recommendation:** ... **Risks & open questions:** ... **Sources:** links to wiki pages used `` File it under its parent, same as drafts/reports (step 5).

1. Link the analysis from its parent page (an "Analyses" section on the area/project page) so

it isn't an orphan, and add it under the matching parent group in wiki/index.md.

1. Append to log:

`

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dougcallaway
• Source: dougcallaway/wikismith
• License: MIT

Install and usage instructions live in the source repository linked above.