Seeding Repos and Skills

Seeding Repos and Skills

Seeding makes curated repo guidance, docs, and skills discoverable through recall without reopening the same files by hand. It is opt-in and layered on top of personal memory: nothing about seeding is required before you can store and recall memories and handoffs.

Memories Work Before Seeding

Memories and handoffs work the moment threadnote is installed. Seed local repos only when you want agents to recall repo guidance, docs, and skills without reopening the source files.

threadnote does not index whole repos. seed imports only the paths listed in your manifest — typically AGENTS.md, CLAUDE.md, README, docs/**, and SKILL.md. Everything else in the working tree stays out of the index. The checked-in instruction files remain the authoritative source of truth; seeded resources are a searchable snapshot of that curated guidance, not a replacement for reading the nearest AGENTS.md or CLAUDE.md from the tree.

The Manifest

Generate a developer-local manifest with init-manifest. --repo is repeatable, paths may be anywhere on the machine, and if no --repo is given the current git repo is used.

threadnote init-manifest --repo ~/src/my-service --repo ~/work/mobile-app

This writes ~/.openviking/seed-manifest.yaml. The manifest is intentionally not checked in — each developer generates one from their own checkouts. init-manifest derives a stable viking://resources/repos/<repo-name> URI per project and keeps the seed patterns conservative.

A realistic manifest:

version: 1
projects:
  - name: web-app
    path: ~/src/web-app
    uri: viking://resources/repos/web-app
    seed:
      - AGENTS.md
      - CLAUDE.md
      - .github/AGENTS.md
      - .github/CLAUDE.md
      - .claude/commands/*.md
      - .claude/skills/**/SKILL.md
      - docs/**/*.md
  - name: mobile-app
    path: ~/src/mobile-app
    uri: viking://resources/repos/mobile-app
    seed:
      - AGENTS.md
      - docs/**/*.md

Each project has a name, a local path, a stable uri under viking://resources/repos/<name>, and a list of seed glob patterns relative to path.

Seeding

Review what will be imported with a dry run, then seed for real:

threadnote seed --dry-run
threadnote seed

seed is an upsert: it never deletes. Re-running it after the source files change re-imports the curated paths into the same viking://resources/repos/<repo-name> URI. Add a new repo later by rerunning init-manifest --repo <path> and seeding again.

Worktrees

By default, seed the stable checkout, not every transient worktree:

threadnote init-manifest --repo ~/src/coda

threadnote treats each worktree path as its own manifest project today. Adding every temporary worktree (for example ~/src/worktrees/coda/my-branch) duplicates the seeded repo resources and makes recall noisier. Add a worktree as its own project only when it is long-lived, or when it carries branch-specific docs, instructions, or repo-local skills that should be recalled separately.

Skills

seed-skills imports global and repo-local SKILL.md files as a searchable resource catalog so agents can discover reusable testing, release, on-call, debugging, or plugin-provided workflows.

threadnote seed-skills --dry-run
threadnote seed-skills

This builds a discoverable catalog only — it does not install or activate skills in the agent runtime. The agent finds relevant skill guidance through recall instead of you reopening the same skill files by hand.

Use the native import path only after you have configured a working VLM provider:

threadnote seed-skills --native

Manifest Resolution Order

seed and seed-skills resolve the manifest in this order:

Source	Purpose
~/.openviking/seed-manifest.yaml	Developer-local default, written by init-manifest.
THREADNOTE_MANIFEST	Environment override for custom teams, experiments, or CI.
--manifest <path>	One-off override for a single seed / seed-skills run.
config/seed-manifest.example.yaml	Checked-in example only. Do not treat it as your live manifest.

How Recall Uses Seeded Resources

Including a seeded project name as a token in a recall query fires a parallel scoped pass against that project's viking://resources/repos/<name> URI. Canonical repo docs come back in the same response as your personal memories.

For example, querying web-app durable feature memories prefers viking://resources/repos/web-app for the project-guidance pass, so seeded AGENTS.md, CLAUDE.md, and docs surface alongside in-flight memories. Treat the seeded resources as the canonical "how does this repo do X" source and personal memories as the per-author context layered on top.

See also: Recall and Read, Configuration, Safety and Security, Migration.