Add kb-add skill: Capture new knowledge into the KB

[williamthorsen]

Problem

Capturing a new knowledge-base note today is manual: open Obsidian, copy a template, fill in frontmatter, decide where the note belongs, pick tags, name the file. Mid-conversation insights either don't get captured at all or land in _triage/ to be sorted later. There's no fast path from "I just figured this out" to a well-formed, schema-valid note in the right folder.

Context

This skill is the third in a trio built on @codeassembly/kb-core:

• Build KB foundation library: discovery, config, schema, frontmatter parsing #635 kb-core: foundation library (discovery, schema, frontmatter, tags, rules), merged.
• Add kb-retrieve skill: Query knowledge base for relevant notes #636 kb-retrieve: query KB notes by relevance, merged.
• Add kb-add skill: Capture new knowledge into the KB #637 kb-add: capture new notes (this ticket).

The vault at ~/repos/vaults/coding already has .kb/schema.yaml and .kb/tag-aliases.yaml. Existing notes follow Obsidian-style filenames (human-readable with spaces) and a small Diátaxis type vocabulary (howto, concept, reference, tutorial). The _triage/ folder is a historical artifact from migrating legacy free-form content; it should not become a tooling-managed pile for fresh captures.

The kb-retrieve skill established the architectural pattern: a bundled TypeScript helper does wide, mechanical work; SKILL.md instructions tell the agent how to do narrow, judgment-driven work. kb-add follows the same split.

Proposed solution

A user-invocable /kb-add skill that captures a new note into the appropriate KB through agent-mediated classification, with a confirm-by-default flow and an --auto escape hatch for silent best-effort capture.

The skill ships as a SKILL.md plus a co-located bundled helper (kb-add.mjs), built via the existing bundle-skill-helpers.ts pipeline.

Labor split:

• The agent classifies (folder, type, title, tags), surveys the destination KB's layout, runs kb-retrieve to surface related notes, and composes the body, including cross-references where they aid comprehension.
• The helper resolves the target KB, generates UTC dates, canonicalizes known-alias tags via tag-aliases.yaml, validates the proposed frontmatter against the destination KB's effective schema, and writes the file. It errors on filename collision rather than auto-disambiguating, so the agent can decide whether to re-title, append to the existing note, or abort.

Flow:

• Default mode: Agent gathers context, proposes placement and body, user confirms or redirects, helper writes.
• Auto mode (--auto): Agent gathers context, picks its best guess, helper writes silently. The agent never asks clarifying questions in this mode.

KB selection mirrors kb-retrieve's defaults: A discovered .kb/ wins over the registry default; the chosen KB is surfaced in the proposal so the user can redirect via --kb.

Cross-referencing is a first-class part of the flow. The agent's pre-write retrieve pass identifies related notes; the agent embeds links inline (where the reference contributes at the point of mention) or under a ## See also block (where it's tangential).

Acceptance criteria

• /kb-add is invokable as a user-facing skill, accepting note content from the conversation or via a file argument.
• Default mode presents the proposed KB, folder, type, title, tags, and body to the user before writing, and writes only after confirmation.
• --auto writes silently to the inferred location with no clarifying questions.
• The agent's flow includes a kb-retrieve pass for the note's topic, and the proposed body includes cross-references (inline or grouped) to related notes when surfaced.
• Written notes carry valid frontmatter per the destination KB's schema; the helper refuses to write notes that fail validation.
• Known-alias tags are canonicalized at write time via tag-aliases.yaml; unknown tags pass through unchanged.
• Filename collisions surface as helper errors; the agent recovers (re-title, append, abort) rather than silent disambiguation.
• New behavior is covered by tests, including helper unit tests against fixtures and an end-to-end test of the write flow.
• Documentation reflects the new skill, including the package README, the agent skill listing, and any user-facing help text.

Dependencies

Depends on #635 (kb-core, merged). Sibling to #636 (kb-retrieve, merged). The install-bug surfaced during design is filed as #648 and is independent.

[williamthorsen]

Implementation note carried over from #636

If kb-add's placement heuristic invokes ripgrep (e.g., to find similar notes or existing tags for dedup and canonicalization), parse rg --json output rather than text. The text format's separator characters (:, -) collide with date-shaped path segments (2026-05-01/, 2026-05-01-note.md), and any text-format parser will eventually misclassify a real path as a content line and silently drop notes from a vault that uses dated filenames or directories. The --json event stream emits data.path.text and data.line_number as discrete fields with no boundary heuristic. See #636 for the bug history.