foundry

name

foundry

description

Scaffolds and operates a personal knowledge vault — an agent-maintained wiki in the spirit of Karpathy's LLM wiki and James Bedford's Foundry. Use when the user wants a self-contained, compounding knowledge base where Claude ingests sources (URLs, PDFs, pasted text), writes evergreen concept notes, logs queries with answers, and densifies the wiki over time. Provides slash commands /foundry-init, /foundry-ask, /foundry-triage, /foundry-densify, /foundry-lint.

Build and maintain a compounding personal wiki. The vault is the durable asset; the agent is its full-time maintainer. Knowledge enters through a single `inbox/`, is promoted to immutable atomic source notes under `sources/`, and is woven into evergreen concept pages under `wiki/` that get denser as material accumulates. Cross-referenced via wikilinks. Linted by the agent.

<essential_principles>

The vault has exactly three folders: `inbox/` (staging), `sources/` (immutable atomic source notes — one per article/paper/transcript/tweet), and `wiki/` (concepts, queries, people, plus three always-present singletons: `index.md`, `log.md`, `health.md`). Note kind is discriminated by the `type` frontmatter field, not by folder nesting. No external read contract. The skill operates entirely inside one vault. If the user later wants to cite into a second vault (e.g. an existing Obsidian vault), they can add that as a one-way read contract in the vault's `CLAUDE.md` — but the skill does not assume one exists. Once a source note is written and triaged, it is not rewritten. It is the atomic ledger of what entered the system. Concept pages under `wiki/` are the compounding asset — they get edited, densified, re-organised, and cross-linked indefinitely. Queries are written-once but can be cited from concepts later. Every ingestion and every query is a densification opportunity. When `/foundry-triage` writes a source, it also proposes concept-page work (new stubs or edits to existing concepts) for the user to accept. When `/foundry-ask` produces a dense, evergreen answer, it offers to crystallise it as a concept note. The wiki only compounds if every interaction tries to compound it. All internal references use `[[Note Name]]` wikilinks. Cross-references make the vault a graph rather than a pile. The lint command surfaces orphans and broken links. Every note has YAML frontmatter with at minimum `type`, `area`, `date_created`. The closed list of `type` values is: `concept`, `query`, `person`, `source`, `index`, `log`, `health`. `area` is user-defined (the skill ships with an empty taxonomy — the user adds areas as they go). `keyword` is free-form and accumulates organically. See `templates/vault-CLAUDE.md` for the full schema, which is copied verbatim into each scaffolded vault. When ingesting a source or writing a concept, if the `area` is ambiguous, ask the user. Never silently invent a new area. Adding to the closed list is a meaningful schema change. Append a one-line entry to `wiki/log.md` for: created concept, created query, ingested source(s), ran lint, ran densify. The log is the audit trail of what the agent did.

</essential_principles>

The skill exposes five slash commands. Each is fully specified in its file under commands/.

Command	When	File
/foundry-init	No vault exists yet, or user asks to scaffold a new one	commands/foundry-init.md
/foundry-ask "<question>"	User asks a question worth a permanent answer	commands/foundry-ask.md
/foundry-triage	New items have been dropped into inbox/	commands/foundry-triage.md
/foundry-densify	Periodic pass to weave recent sources/queries into concept pages	commands/foundry-densify.md
/foundry-lint	Refresh health.md and index.md, surface issues	commands/foundry-lint.md

<natural_language_routing>

If the user does not invoke a slash command but is clearly doing foundry work, route based on intent:

• "Build me a knowledge vault" / "set up a wiki" / "I want to start a foundry" → run /foundry-init
• "Why does X work the way it does?" / "What's the case for Y?" + research effort → run /foundry-ask
• "There are new things in the inbox" / "process these PDFs" → run /foundry-triage
• "Pull these sources into the wiki" / "the wiki feels thin" → run /foundry-densify
• "Audit the vault" / "what's broken" / "is the wiki healthy" → run /foundry-lint

</natural_language_routing>

When scaffolding a new vault (/foundry-init) or writing new notes, copy from templates/:

• templates/vault-CLAUDE.md — the operating contract that lives at the root of the user's vault. The single source of truth for that vault's schema. This is what /foundry-init copies first. It encodes the same principles as this SKILL.md but for the vault, not the skill.
• templates/concept.md, templates/query.md, templates/person.md, templates/source.md — note skeletons. Copy and fill.
• templates/index.md, templates/log.md, templates/health.md — vault singletons. Created once on scaffold, then maintained by the agent.

<authoring_conventions>

When writing into the vault:

• Filenames. Concepts: descriptive title (Two-layer knowledge systems.md). Queries: YYYY-MM-DD-<kebab-slug>.md. People: the person's name (Andrej Karpathy.md). Sources: short descriptive title with optional author suffix (LLM Knowledge Bases (Karpathy).md).
• Voice. Dense, declarative, terse. No filler ("It is worth noting that…"). No journalistic hedging. Imitate the user's voice if there are prior notes to learn from.
• Citations. Every claim that came from a source gets a wikilink to that source. Quote verbatim when feasible; paraphrase only when length forces it.
• Cross-links. When writing a note, look for 2–4 existing concepts it should link to. Don't force links if none fit. A [[bracket]] to a not-yet-created concept is fine — it marks something worth writing.
• Frontmatter first. Always write the YAML frontmatter before the body. Required fields per type are listed in templates/vault-CLAUDE.md.

</authoring_conventions>

<success_criteria>

A well-operating foundry vault:

• has more wiki concept notes than source notes after a few weeks of use (sources compound into concepts, not the other way around)
• has no orphan notes (every note links to or is linked from at least one other)
• has zero broken wikilinks (/foundry-lint flags them)
• has an index.md that reflects the current set of concepts grouped by area
• has a log.md with one line per significant action
• has a CLAUDE.md at root that is the load-bearing operating contract for that vault

</success_criteria>