wiki-init

wiki-init

Bootstrap a new wiki from scratch — interactively. The wiki's shape depends on the domain, so this skill does not hardcode categories. Instead it asks about the user's domain, proposes a category set that fits, and lets the user edit. The resulting SCHEMA.md is the authoritative config that all other skills read.

"The exact directory structure, the schema conventions, the page formats, the tooling — all of that will depend on your domain, your preferences, and your LLM of choice." — Karpathy, LLM Wiki

When to use

• User asks to create, start, or initialize a wiki or knowledge base
• No wiki exists yet at the configured path

Steps

① Resolve path

Use --path argument, WIKI_PATH env, ~/.ak-wiki/config.yaml, or default ~/wiki. If path already exists and is non-empty, warn the user and ask before overwriting.

② Ask about the domain

If --domain not provided, ask:

"What domain will this wiki cover? Be specific. Examples:

• 'transformer ML research — papers and blog posts'
• 'reading the Lord of the Rings trilogy — characters, places, events'
• 'competitive analysis of SaaS observability tools'
• 'my personal health, psychology, self-improvement'
• 'internal team wiki — projects, decisions, customer calls'"

③ Propose categories that fit the domain

Based on the domain, propose a starter category set. Do not hardcode entities/concepts/comparisons/queries — match the domain:

Research / technical deep-dive:

• entities/ — people, labs, orgs, products, models
• concepts/ — techniques, theories, ideas
• comparisons/ — side-by-side analyses
• queries/ — filed query results

Reading a book / media / fiction:

• characters/, places/, events/, themes/, timeline/, chapters/

Personal / self-improvement:

• journal/, topics/ (health, psychology, career), patterns/, queries/

Business / team:

• people/, projects/, customers/, decisions/, meetings/, queries/

Competitive analysis / market research:

• competitors/, features/, market/, comparisons/, queries/

Trip planning / hobby / custom:

• Ask the user what fits, or propose 3–5 categories based on the domain keywords

Present the proposal:

"For a {domain} wiki, I suggest these categories:

• {cat1}/ — {purpose}
• {cat2}/ — {purpose} ... Accept, edit, or replace?"

If --categories was provided, use them directly. Otherwise wait for user input.

④ Ask about conventions (defaults offered)

Walk through each policy briefly. Offer defaults — don't force. User can press enter to accept each.

• Frontmatter fields — default: title, created, updated, type, tags, sources, published_at, ingested_at. The last two are required by the memory-tier system (step ④c) — keep them unless the user explicitly disables tiers.
• Tag taxonomy — propose 10–20 domain-specific tags. Show the list, accept edits.
• Page creation policy — default: "create a page when the subject is central to a source, or mentioned in 2+ sources". Alternatives: "central only" / "flexible"
• Cross-reference policy — default: "link to related pages wherever there's a genuine connection; no minimum". Alternatives: "≥1 link required" / "≥2 required"
• Page size limit — default: no limit (flag in lint only if user sets one)
• Log rotation threshold — default: no rotation (flag in lint only if set)

Each answer gets written verbatim into SCHEMA.md so future skill runs enforce the user's actual preferences — not plugin defaults.

④b Ask about custom frontmatter dimensions

Beyond standard fields (title, tags, sources, dates), a wiki can declare custom dimensions — extra frontmatter fields specific to the domain. Example: a software project wiki typically wants version: on every page; a research-paper wiki might want venue: or citation_count:; a personal journal might want mood:.

Ask:

"Any custom frontmatter dimensions for this domain? These are extra fields the agent will ask you about every time it ingests a new source. Leave empty to skip.

Example: version (string, required, asked on every ingest) — useful when the wiki tracks a thing that evolves (software, product, treaty)."

For each dimension the user names, capture:

• name — lowercase_snake_case field name
• type — one of string | date | number | enum | list
  • If enum, ask for the allowed values (comma-separated)
• description — short phrase used as the prompt text (e.g. "Which version of the product does this source describe?")
• required — yes / no (default yes)
• default — optional default value, or none
• refresh_on — when does the agent prompt for this field's value?
  • ingest — every wiki-ingest run asks
  • import — every wiki-import run asks (once for the whole batch by default)
  • digest — wiki-digest surfaces pages with stale values and offers to re-prompt
  • manual — never auto-prompts; user supplies via --set version=X
  • Default for string fields that describe evolving state: [ingest, import]
• applies_to — optional list of page types this field applies to (omit = all)

Write the dimensions into SCHEMA.md's custom_dimensions: block (step ⑥) so every other skill can read and enforce them.

④c Ask about memory tier thresholds

The wiki distinguishes three tiers of raw content by age:

• active — recent enough that the wiki prioritizes it in all queries (default: < 1 year)
• archived — older, still accessible but not default (default: 1–2 years)
• frozen — old, read-mostly, candidate for future auto-dreaming (default: > 2 years)

Tiers are computed on-the-fly from a date field, not stored as frontmatter. This means adjusting the thresholds is instant and can't drift.

Ask:

"Memory tier thresholds (press enter for defaults):

• active window: [default 365 days]
• archived window: [default 730 days — anything older is frozen]
• driving date: [default published_at if present, else ingested_at]

Wiki queries default to --tier=active. To disable tiers entirely, say 'off'."

If the user says "off", record memory_tiers: disabled in SCHEMA.md and skip the rest of this step. Otherwise write the thresholds into SCHEMA.md's memory_tiers: block (step ⑥). The thresholds can be changed later with wiki-tier --set-thresholds.

⑤ Create directory structure

{wiki_path}/
├── raw/articles/
├── raw/papers/
├── raw/transcripts/
├── raw/assets/          # Images and attachments referenced by sources
├── {category-1}/        # from step ③
├── {category-2}/
├── ...
└── _archive/            # Superseded pages (removed from index, never deleted)

⑥ Write SCHEMA.md

Include:

• Domain: what this wiki covers (from step ②)
• Categories: the list from step ③ with one-line purpose for each
• Conventions: file naming, wikilinks syntax
• Frontmatter template: the fields chosen in step ④
• Custom dimensions: the fields chosen in step ④b — as a YAML block:

  custom_dimensions:
    - name: version
      type: string
      description: "Which version of the product does this source describe?"
      required: true
      default: null
      refresh_on: [ingest, import]
      applies_to: null   # null = all page types
  

  If the user declared no custom dimensions, write custom_dimensions: [].
• Memory tiers: the thresholds chosen in step ④c — as a YAML block:

  memory_tiers:
    enabled: true
    active_days: 365
    archived_days: 730
    driving_field: published_at   # fallback: ingested_at
  

  If the user said "off", write memory_tiers: { enabled: false }.
• Tag taxonomy: the tags chosen in step ④ (add new tags here BEFORE using them)
• Page creation policy: the rule chosen in step ④
• Cross-reference policy: the rule chosen in step ④
• Page size limit: the rule chosen in step ④ (or "no limit")
• Log rotation: the rule chosen in step ④ (or "no rotation")
• Update policy for contradictions: note both claims with dates, flag for review

Make it clear at the top: this file is user-editable and co-evolves with the wiki. wiki-lint will propose updates over time.

⑦ Write index.md

Sectioned header with one section per category from step ③:

# Wiki Index

> Content catalog. Every wiki page listed under its type with a one-line summary.
> Read this first to find relevant pages for any query.
> Last updated: {date} | Total pages: 0

## {Category 1}
## {Category 2}
...

⑧ Write log.md

# Wiki Log

> Chronological record of all wiki actions. Append-only.
> Format: ## [YYYY-MM-DD] action | subject
> Tip: `grep "^## \[" log.md | tail -5` for the last 5 entries

## [YYYY-MM-DD] init | Wiki initialized
- Domain: {domain}
- Path: {wiki_path}
- Categories: {list}
- Structure created with SCHEMA.md, index.md, log.md

⑨ Suggest git init

At the end, suggest:

"Your wiki is a git repo's worth of markdown — you get version history, branching, and collaboration for free with one command:

cd {wiki_path} && git init && git add . && git commit -m 'wiki: init'

Run it?"

Offer to run it if the user confirms.

⑩ Confirm and suggest first ingest

Report what was created, then suggest:

"Wiki initialized at {path}. Drop a source into raw/articles/ (or paste a URL) and run ak-wiki:wiki-ingest <source> to add your first document. A single source usually touches 10–15 pages — that's the compounding effect."

Output

[Operation] wiki-init | {domain}

[Changes]
- Created: SCHEMA.md (with {N} categories, {M} tags, {policies})
- Created: index.md, log.md
- Created: {list of category dirs and raw/ subdirs}
- Git: {"initialized" | "skipped"}

[Summary]
Wiki initialized for "{domain}" at {path}. Categories: {list}. SCHEMA.md customized
with {N}-tag taxonomy. Ready to ingest first source.

[Suggested next]
→ ak-wiki:wiki-ingest <source>