# Instruction Set: Restructure AGENTS.md into Cross-Platform Agent Skills You are restructuring the `llm-wiki-test1` repository's monolithic `AGENTS.md` (~30KB) into a set of discrete, invocable agent skills that work identically across **GitHub Copilot (VS Code)**, **Claude Code**, **Codex CLI**, and **Mistral Vibe**. This document contains all background context, rationale, and concrete requirements needed to do this restructuring correctly. Read it fully before making changes. --- ## 1. Why this restructuring is happening ### 1.1 Current state `AGENTS.md` is a single file describing five workflows (INGEST, QUERY, LINT, CREATE, UPDATE), the wiki's frontmatter schema, entity/concept type tables, provenance/citation rules, naming conventions, and a confidence-scoring formula. It is loaded in full regardless of which workflow the LLM is actually executing. The repo already has a deterministic CLI, `tools/wikitool` (Python, backed by `tools/wiki_tools/`), which handles all mechanical operations: frontmatter scaffolding (`new_page.py`), structural linting (`lint.py`), link-graph analysis (`repo_scan.py`), and source/citation provenance tracking (`provenance.py`). The LLM's job is prose and judgment; `wikitool` guarantees structural correctness. This split (deterministic tool + LLM judgment) is already correct and should be preserved and reinforced, not undone. ### 1.2 The problem with the monolith Evidence from the LLM-wiki ecosystem (see `awesome-llm-wiki`, https://github.com/gavischneider/awesome-llm-wiki) converges on the same diagnosis: - **Token economics**: a full ingest against a compiled wiki costs roughly 5–8× the source token count because the agent reads the entire relevant instruction set plus target pages; a query against just an index plus 2–4 pages costs a fraction of that. A monolithic instructions file loaded on every task pays the higher cost even for simple queries. - **Scale ceiling**: single-context approaches (one big instructions file, full index re-read every session) start degrading in quality once a wiki passes roughly 100–200 pages — the LLM starts missing connections and quality drops. One documented case (RTFM / retrieval-layer approach) cut token usage by 61% and improved resolve rate from ~55-64% to 100% on an 8,260-file corpus by serving metadata first and expanding only what's needed, instead of loading everything. - **Governance vs. procedure**: not everything needs splitting. Declarative rules (schema, provenance requirements, confidence formula, naming conventions) are cheap to keep centralized. It's the **procedural workflows** (multi-step operations like INGEST or LINT) that benefit from being isolated, because each is only relevant to one task at a time. ### 1.3 The precedent this restructuring follows Several implementations in the ecosystem already do exactly this split for a Karpathy-pattern wiki: - **`kfchou/wiki-skills`**: six standalone Claude Code skills — `wiki-init`, `wiki-ingest`, `wiki-query`, `wiki-lint`, `wiki-update`, `wiki-audit` — each its own file, loaded only when invoked. This is the closest 1:1 structural analog to what we're building (general-purpose/IT wiki, not a personal journal). - **Leo Alexandru's production setup**: twelve skills total, organized by cadence (daily/capture/maintenance), each a subfolder with its own `skill.md`, invoked via `/skill-name`. Demonstrates this scales in real daily use. - **Farza's personal wiki skill** (https://gist.github.com/farzaa/c35ac0cfbeb957788650e36aabea836d): the origin of the command-scoped pattern (`/wiki ingest`, `/wiki absorb`, `/wiki query`, `/wiki cleanup`, `/wiki breakdown`, `/wiki status`), though it keeps everything in one file — useful for the *command taxonomy* idea, not for the context-isolation mechanism itself. - **`vanillaflava/llm-wiki-skills`**: the reference implementation for **cross-platform distribution** — six wiki skills tested against Claude Code, Gemini CLI, Codex CLI, and GitHub Copilot simultaneously, installed via a shared CLI that symlinks skills into each tool's native location. - **`yugasun/llm-wiki-skills`**: another cross-platform repo explicitly targeting Claude Code, GitHub Copilot, and Codex. --- ## 2. Target skill set Split `AGENTS.md`'s five workflows into five (optionally six) standalone skills. Each skill file must be self-contained: a user or agent invoking it should not need to have read the other skill files first, only the shared root context (section 4). | Skill name | Replaces AGENTS.md section | Core `wikitool` commands it drives | |---|---|---| | `wiki-ingest` | INGEST Workflow (11 steps) | `new source`, `new entity`, `new concept`, `xref add`, `xref link-source`, `sources rebuild-index`, `index rebuild`, `sources coverage`, `log append`, `publish` | | `wiki-query` | QUERY Workflow | (read-only; no wikitool mutation commands — reads `wiki/index.md`, entity/concept/source pages) | | `wiki-lint` | LINT Workflow | `lint --markdown`, `sources coverage`, `confidence decay --apply`, `sources rebuild-index`, `index rebuild`, `log append` | | `wiki-create` | CREATE Workflow | `new entity`\|`concept`\|`source`\|`comparison`, `xref add`, `sources rebuild-index`, `index rebuild`, `log append`, `publish` | | `wiki-update` | UPDATE Workflow | `xref add`, `sources rebuild-index`, `index rebuild`, `log append`, `publish` | | `wiki-status` (optional, new) | not currently in AGENTS.md — add if useful | read-only stats: page counts, orphans, uncovered raw files | Each skill file should follow this internal structure: ```markdown --- name: wiki- description: --- # **Purpose:** **Trigger:** ## Steps ## wikitool commands used ## Output ``` Preserve the exact step-by-step content, command syntax, and rules currently in each AGENTS.md workflow section — this is a structural extraction, not a rewrite of the logic. Do not change what the workflows do, only where they live. --- ## 3. Cross-platform file layout Use a single shared skill directory so all four target tools resolve to the same files without duplication: ``` llm-wiki-test1/ ├── AGENTS.md # slimmed root file (see section 4) ├── .agents/ │ └── skills/ │ ├── wiki-ingest/ │ │ └── SKILL.md │ ├── wiki-query/ │ │ └── SKILL.md │ ├── wiki-lint/ │ │ └── SKILL.md │ ├── wiki-create/ │ │ └── SKILL.md │ └── wiki-update/ │ └── SKILL.md ├── tools/ │ └── wiki_tools/ # unchanged └── wiki/ # unchanged ``` `.agents/skills/` is the emerging shared convention across agent tools (used natively by Mistral Vibe as a project-shared skill location, and adopted by `vanillaflava/llm-wiki-skills` as the canonical install target that gets symlinked into tool-specific directories). Putting skills here once avoids maintaining four copies. ### Per-tool wiring | Tool | How it finds `.agents/skills/` | Action needed | |---|---|---| | **Claude Code** | Native skill discovery in `.claude/skills/` | Symlink or copy: `~/.claude/skills/wiki-*` → `.agents/skills/wiki-*` (or configure Claude Code to point at `.agents/skills/` directly if supported in your version) | | **Codex CLI** | Native skill discovery in `~/.codex/skills/` | Same symlink pattern as Claude Code | | **Mistral Vibe** | Reads `.agents/skills/` directly as a shared project location (also supports `.vibe/skills/` project-local or `~/.vibe/skills/` global) | No action needed if using `.agents/skills/` — Vibe resolves it natively | | **GitHub Copilot (VS Code)** | Reads skill locations configured via the `chat.agentSkillsLocations` VS Code setting | Add to `.vscode/settings.json`: `"chat.agentSkillsLocations": ["${workspaceFolder}/.agents/skills"]` | If a symlink-based install script is wanted, model it after `vanillaflava/llm-wiki-skills`'s installer pattern: a small script that creates the shared directory once and symlinks it into each tool's native skill path, so a single source of truth is edited and all four tools stay in sync. --- ## 4. What stays in the root `AGENTS.md` (slimmed) Keep only the **declarative, cross-cutting** content that every skill needs regardless of task. Do not duplicate this into each skill file — skills should reference it, not repeat it. Retain in root `AGENTS.md`: - Repository architecture diagram (raw/, wiki/, tools/ layout) - Entity Types table (Project, System, Tool, Technology, Person + directories) - Concept Types table (Architecture, Pattern, Protocol, Workflow, Decision, Problem) - Relationship Types list (depends on, uses, implements, etc.) - Page Formats (Entity/Concept/Source/Comparison templates, Index Entry Format, Log Entry Format) - Naming Conventions (file naming, wikilinks, IDs/references) - Provenance and Citation rules (`raw_files:`, `provenance:` field, inline `^[[Source - X]]` citation marker, `wiki/provenance.md` reverse index, "no confident answer without a source" rule) - Confidence Scoring formula and decay rule - Quality Standards checklists (Content Quality, Cross-Reference Quality) - IT-Specific Guidelines (per-entity-type documentation expectations) - Maintenance Schedule table - User Preferences section - Version History Remove from root `AGENTS.md` (move into individual skills per section 2): - The full step-by-step INGEST Workflow - The full step-by-step QUERY Workflow - The full step-by-step LINT Workflow - The full step-by-step CREATE Workflow - The full step-by-step UPDATE Workflow - The Git Automation section's operational steps (keep the *policy* — e.g. "never call raw `git commit`/`git push`" — in root; move the per-workflow "when to call `wikitool publish`" instruction into each relevant skill) The result should shrink root `AGENTS.md` from ~30KB to roughly a third of that, containing only schema and policy, while all executable workflow logic lives in `.agents/skills/`. --- ## 5. Execution checklist 1. Create `.agents/skills/wiki-ingest/SKILL.md` through `.agents/skills/wiki-update/SKILL.md`, each populated per section 2, using the frontmatter format shown there. 2. Extract the five workflow sections verbatim from the current `AGENTS.md` into their corresponding skill files, converting from `### N. WORKFLOW Workflow` headings to the skill file structure in section 2. Preserve every numbered step, every `wikitool` command, and every rule (e.g., "never hand-edit `wiki/index.md`"). 3. Rewrite root `AGENTS.md` to contain only the sections listed as "retain" in section 4. Add a short new section near the top: "## Skills" listing the five skill names, one-line purpose each, and a pointer to `.agents/skills/`. 4. Create `.vscode/settings.json` (or update it if it exists) with the `chat.agentSkillsLocations` entry from section 3. 5. Do not modify anything under `tools/wiki_tools/` or `tools/wikitool` — this restructuring is documentation/skill-layer only, no CLI behavior changes. 6. Verify: read back the new root `AGENTS.md` and each skill file, and confirm no workflow step, `wikitool` invocation, or hard rule ("never hand-edit X", "always run Y before Z") was dropped during extraction. This is a lossless move, not a summarization. 7. Update the Version History table at the bottom of `AGENTS.md` with a new row describing this restructuring (date, "Split workflow sections into `.agents/skills/` for cross-platform skill support (Claude Code, Codex, Mistral Vibe, GitHub Copilot); slimmed root AGENTS.md to schema/policy only", author). Do not invent new workflows, commands, or rules beyond what already exists in the current `AGENTS.md` and `tools/wiki_tools/` codebase. This task is a structural reorganization for context efficiency and cross-tool compatibility, not a redesign of the wiki's logic.