chemenu/raw/notes/copilot-skill-restructure-instructions.md

# 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-<name>
description: <one-line, third-person, describes when to invoke this skill>
---

# <Skill Title>

**Purpose:** <one sentence>
**Trigger:** <when this skill should be invoked>

## Steps

<the numbered steps from the corresponding AGENTS.md workflow section, unchanged in substance>

## wikitool commands used

<the exact CLI invocations, copied from AGENTS.md's command reference table>

## Output

<what this skill produces>
```

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.