eiway112/agent-wiki

Knowledge Base Operation Workflow (LLM Wiki Mode)

Positioning & Applicability

This Skill is a platform-agnostic methodology: transforming external knowledge into behavioral rules (Memory/Standards/Skills) that agents can invoke at runtime. The knowledge base is not a bookmark collection — it is the agent's capability growth engine. Every piece of ingested knowledge must be distilled, and the sole criterion for value is: whether it can directly change the agent's behavioral decisions in a specific scenario.

• If the project already has its own knowledge base specification files (e.g., project-standards.md), those files are authoritative, and conflicts are resolved in their favor.
• When applying this Skill in different platforms/projects, follow the three-tier architecture and workflow; directory names can be localized. The examples/ directory in this repository provides minimal runnable samples.

Three-Tier Architecture

Layer	Recommended Directory	Nature
Raw Sources	raw-sources/ (articles/discussions/videos)	Read-only, immutable after collection
The Wiki	knowledge-base/ (catalog.md, gathered-experience.md, operation-log.md)	LLM-maintained derived content
The Schema	project-standards.md + program-files/config/	Co-maintained by humans and LLMs

Key Principle: Raw files always remain in Raw Sources — they are not moved to the Wiki. After validation passes, establishing a reference in catalog.md is considered "ingested."

Role Separation (Mandatory)

Role	Entity	Responsibility	Prohibited
Planner	Human	Define collection goals, set value contracts, guide analysis direction	Do not directly manipulate files
Generator	LLM	Execute collection, supplement metadata, write summaries, maintain catalog and logs	Forbidden to self-evaluate output quality
Evaluator	Validation tooling (e.g., scripts/validate.py)	Independently validate format, encoding, metadata, cross-references	Do not participate in generation

Core Rule: The model must not grade itself. The Generator records value assessments in the operation log; the Evaluator determines pass/fail. When humans disagree, human judgment takes precedence. If the project lacks tooling, perform manual checks according to the six-dimensional Lint checklist, but the conclusion must still not be self-certified by the Generator.

Ingest

Copy the following checklist to track progress:

- [ ] 1. Pre-collection value contract (three questions)
- [ ] 2. Collect and supplement metadata
- [ ] 3. Read content, extract key information
- [ ] 4. Value assessment (abort if criteria not met)
- [ ] 5. Update catalog.md (summary + cross-references)
- [ ] 6. Append to operation log
- [ ] 7. Distillation evaluation and mark landing status
- [ ] 8. Git commit

Step 1 · Pre-collection Value Contract — Before starting, answer three questions and record them:

1. What problem does this article solve? What is its relationship to existing knowledge? (supplement/compare/extend)
2. Under what conditions is it "valuable"? At least one must be met: introduces a new concept, provides a comparative perspective, offers direct practical reference.
3. At which layer of catalog.md is it expected to be placed? (fundamental theory / architectural paradigm / engineering practice / tools & resources / community updates)

Step 2 · Collection & Metadata — Use the current platform's collection engine to retrieve the original text (see "Collection Engine Abstraction"), save it into the corresponding subdirectory of Raw Sources. File naming follows {source}_{topic}_{date}.{ext} (e.g., github_karpathy_llm_wiki_20260630.md). Required metadata fields: URL, Collection Time, Collection Command; recommended fields: By, Site, Published, Original Source. The collection engine usually extracts only some fields automatically; the rest must be completed.

Step 4 · Value Assessment (including abort) — Evaluate against the contract from Step 1. If the content clearly fails to meet any value condition (empty content, severe duplication, irrelevant to the knowledge base's positioning), explicitly record the abort reason in the operation log and exit, without forcing the ingestion to completion.

Step 6 · Operation Log Format: ## [date] ingest | title (append-only).

Step 7 · Distillation Evaluation — Does this entry contain atomic rules that can directly guide agent behavior?

Mark	Meaning	Action
🟢 Landed	Executable atomic rules exist	Extract and write into Memory/Standards/Skills; note the Memory title in the catalog.md entry
🟡 Partially landed	Some rules exist	Specify which parts are landed and which are not, along with reasons
🔵 Reference index	No executable rules	Briefly state the reason in the operation log

Distillation standard: The rules must be able to change the agent's behavioral decisions in specific scenarios — not abstract ideas or reference information.

Cross-platform Distillation Adaptation: In Qoder, distillation products are written into the Memory system (methodology → task_experience, pitfalls → common_pitfalls_experience, architectural decisions → important_decision_experience, etc.). In other agent platforms, map to that platform's own persistent memory/behavior rule mechanism. The evaluation criteria and three-color markers remain unchanged.

Step 8: git add -A && git commit -m "ingest: title"

Query

1. Read knowledge-base/catalog.md first to locate relevant pages.
2. Dive into the related files, synthesize the answer.
3. Backfill good answers as new pages — so exploration itself generates compounding returns.
4. Append to operation log: ## [date] query | question.
5. After creating a new page: git add -A && git commit -m "query: question"

Lint (Health Check)

Run the project's validation tooling first (this repository provides a zero-dependency example: python scripts/validate.py <knowledge-base-root>). The tooling's decision takes precedence over manual judgment. Without tooling, check against the six dimensions:

1. Metadata Completeness — Are all required fields (URL, Collection Time, Collection Command) present?
2. Encoding Correctness — Double-encoding garbled text, BOM, replacement characters (U+FFFD)
3. Format Compliance — Markdown must start with H1 and metadata must be separated from body by ---; JSON must have a _metadata field
4. Naming Convention — Does it follow the {source}_{topic}_{date} pattern?
5. Cross-references — Do links in catalog.md point to existing files? Orphan page detection.
6. Source Validation — Is the URL on the allowed source whitelist?

Append to operation log: ## [date] lint | scope; if fixes are made, git commit -m "lint: scope".

Harness Decay: Tooling and workflows are auxiliary mechanisms to compensate for model weaknesses — they should monotonically decrease as the model improves. During each Lint, review: which validation rules no longer trigger? Which steps has the model internalized? Delete them.

Collection Engine Abstraction (Cross-platform Adaptation)

The core workflow is not tied to any collection tool. The collection engine is chosen based on platform availability:

Platform Environment	Collection Method
Windows + Edge browser	AutoCLI: autocli read "URL" -f markdown -o "output path", automatically extracts By/Site/URL. Note: under PowerShell, stderr progress may falsely report ExitCode=1; output containing "Saved to ..." indicates success
Agent platforms with web reading capabilities	Web reading tools (WebFetch, etc.) directly fetch and convert to Markdown
Public API sources	Hacker News, Lobsters, etc. — no browser needed, direct API requests
No web tools	User pastes original text, saves to disk manually, and honestly records the Collection Command as "manual paste"

Regardless of the engine, the post-ingestion metadata, validation, and distillation requirements are identical. The Collection Command field must truthfully record the actual engine and command used (including degradation switches) to ensure reproducibility.

Quick Reference

• File naming: {source}_{topic}_{date}.{ext}, source in lowercase
• Operation log: append-only, format ## [date] {ingest|query|lint} | summary
• Commit message: {ingest|query|lint}: {summary}; initialization: init: knowledge base baseline
• Structured lessons learned are recorded in gathered-experience.md, not mixed into the operation log