karpathy-wiki-ingest
For a detached wiki ingester only. The main agent never loads this. Defines orientation protocol, page format, role guardrail, validator contract, manifest protocol, and deterministic completion contract. Loaded by the provider-aware runtime worker.
toolboxmd · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add toolboxmd/karpathy-wiki --skill karpathy-wiki-ingest技能说明
name: karpathy-wiki-ingest description: | For a detached wiki ingester only. The main agent never loads this. Defines orientation protocol, page format, role guardrail, validator contract, manifest protocol, and deterministic completion contract. Loaded by the provider-aware runtime worker.
karpathy-wiki ingest (for detached runtime ingester only)
You are a detached wiki ingester invoked by the provider-aware runtime worker. Your job: process one already-claimed capture into wiki pages and complete it through the runtime helper. The main agent does NOT read this skill; it is loaded by the provider adapter's prompt.
Perform this ingest yourself. You must not launch or delegate the work to another model or agentic CLI. The runtime has already selected the provider, model, and reasoning effort for this run.
Deep orientation
Before any wiki write, run this 9-step orientation protocol. The goal: your view of the wiki is shaped by the actual page content, not by titles alone.
Steps 1-3: read the wiki's current state
- Read
<wiki>/schema.md— current categories, taxonomy, thresholds. - Read
<wiki>/index.md(or<wiki>/<category>/_index.mdper category) — what pages exist with one-line summaries. - Read the last ~10 entries of
<wiki>/log.md— recent activity.
Steps 4-7: pick and read 0-7 candidate pages
-
Extract candidate signals from the capture. From the body and frontmatter, gather:
- Words and phrases from the capture title (lowercase, split on non-alphanumerics).
- Frontmatter
tags:list (if any). - For
chat-onlyandchat-attachedcaptures: meaningful nouns and proper-noun phrases from the body. Use judgment — you're an LLM, not a regex; pick names, identifiers, technical terms, version numbers. - For
raw-directcaptures: filename basename + the file's first 200 lines.
-
Score candidates against the index. A page is a candidate if ANY extracted signal:
- Substring-matches its title (case-insensitive), OR
- Matches a tag (exact, case-insensitive), OR
- Appears in its
_index.mdone-line summary.
This is a deterministic substring + tag match — no embeddings, no semantic similarity. See "Why no embeddings / vector search" below for the rationale.
-
Pick up to 7 candidates ordered by:
- Signal-match count (descending — more matches = stronger candidate).
- Title length (ascending — shorter titles rank higher for the same match count; they tend to be more general / canonical).
- Tie-break: alphabetical by title.
-
Read all picked candidates in full. Zero is a valid count for a small or fresh wiki — see "Cold start" below.
Steps 8-9: decide and report observations
-
Decide: create new page, augment an existing page, or no-op (the capture's content is already covered by an existing page). Write your decision rationale into the commit message later.
-
Issue reporting (during steps 5-7). While reading the index and the candidate pages, observe issues. Append each as one JSONL line to
<wiki>/.ingest-issues.jsonlviabash "${WIKI_PLUGIN_ROOT}/scripts/wiki-issue-log.sh". Do NOT fix issues inline; report only —wiki doctorconsumes the log later.Example invocation:
bash "${WIKI_PLUGIN_ROOT}/scripts/wiki-issue-log.sh" \ --wiki "${WIKI_ROOT}" \ --ingester-run "${WIKI_RUN_ID}" \ --capture "${WIKI_CAPTURE#${WIKI_ROOT}/}" \ --page "concepts/auth.md" \ --type broken-cross-link \ --severity warn \ --detail "Links to /concepts/legacy.md which does not exist." \ --suggested-action "Remove link or create stub"Issue types to watch for (the
--typeenum inwiki-issue-log.sh):- broken-cross-link: page links to
/path/foo.mdbut that file does not exist. - contradiction: page makes a claim that contradicts another page you're reading or the capture itself.
- schema-drift: page has
type: concept(singular) but directory isconcepts/; page lacks required frontmatter; page uses retired categories. - stale-claim: page says "as of 2025-12 library X is at version Y" and the capture or another source clearly indicates a newer version.
- tag-drift: same concept tagged two different ways across pages.
- quality-concern: page's
quality.overall < 3.0was rated by ingester (not human). - orphan: page exists but is not linked from any
_index.mdor other page. - other: anything else worth noting.
Severity:
- error: blocks ingestion (rare — only if reading the schema or a candidate page fails outright).
- warn: default. Issue noted; ingestion proceeds.
- info: observational; usually for tag-drift or quality-concern.
Each issue gets one JSONL line, ≤ 4096 bytes total. Over-length
--detailis auto-truncated by the helper. - broken-cross-link: page links to
Cold start: wikis with ≤ 7 pages
When the candidate list from step 6 is empty or near-empty (the index
has fewer than 8 pages total), step 7 reads few or no pages. The role
guardrail in <wiki>/.wiki-config becomes the PRIMARY lens, not a
backup tripwire:
role: projectorrole: project-pointer: write specifics about THIS codebase / instance / situation. Document the symptom, the pinpoint, what code path triggered it. Do NOT generalize.role: main: write general patterns reusable across projects. Do NOT name specific apps or instances; abstract them.
In the cold-start state the index has insufficient gravity to shape the page; the role hint carries the lens. Defer cross-linking to a future ingester run when more pages exist.
Why no embeddings / vector search
The substring + tag match in step 5 is deterministic, scriptable, testable, and cheap. Embedding-based candidate selection is the "smart" upgrade but explicitly out of scope per CLAUDE.md ("do not add: vector
阅读完整来源 ↗