# Skills Reference

CodeWiki provides eight specialized skills. Each skill is self-contained with instructions, contracts, and scripts.

---

## 1. `wiki-init`
- **Location:** [`skills/wiki-init/SKILL.md`](../skills/wiki-init/SKILL.md)
- **Purpose:** Initialize and generate a complete, living, grounded CodeWiki for any codebase directly using native agent tools.
- **Workflow:**
  1. **Phase 1: Research** — Explore the repository structure, package manifests, build scripts, entry points, and tests.
  2. **Phase 2: Taxonomy Formulation** — Draft a structured page plan following OKF conventions (`overview.md`, `architecture/*.md`, `modules/*.md`, `workflows/*.md`).
  3. **Phase 3: Page Generation** — Write OKF v0.2 Markdown pages, embed source-grounded Mermaid diagrams, and invoke `claims.mjs` to compute evidence versions.
  4. **Phase 4: Sidecar & Manifest Persistence** — Generate factual claims in `codewiki/.claims/` and record page versions in `codewiki/.page-manifest.json`.

---

## 2. `wiki-update`
- **Location:** [`skills/wiki-update/SKILL.md`](../skills/wiki-update/SKILL.md)
- **Purpose:** Incrementally synchronize documentation by detecting source drift from git diffs, updating affected pages, and reconciling claims.
- **Key Capabilities:**
  - Detects committed, staged, unstaged, and untracked file changes.
  - Compares existing claim evidence versions against current working tree code.
  - Re-verifies affected documentation pages and flags stale or deleted claims.

---

## 3. `wiki-query`
- **Location:** [`skills/wiki-query/SKILL.md`](../skills/wiki-query/SKILL.md)
- **Purpose:** Precision retrieval and synthesis of grounded knowledge from an existing CodeWiki to answer developer queries with minimal token usage.
- **Key Capabilities:**
  - Reads `codewiki/index.md` and navigation tables rather than loading all pages into context.
  - Pulls only relevant section headers and claims.
  - Verifies key factual details directly against source code before responding.

---

## 4. `claims-grounding`
- **Location:** [`skills/claims-grounding/SKILL.md`](../skills/claims-grounding/SKILL.md)
- **Purpose:** Extract, verify, and reconcile falsifiable factual propositions (Claims) grounded in source code.
- **Helper Script:** [`skills/claims-grounding/scripts/claims.mjs`](../skills/claims-grounding/scripts/claims.mjs)
- **Claim Structure:**
  ```json
  {
    "id": "claim_01h7x8...",
    "statement": "The API server listens on port 8080 by default.",
    "evidence": [
      {
        "resource": "repo://src/config/server.ts#L12-L14",
        "version": "repo-lines-v1:sha256:..."
      }
    ]
  }
  ```

---

## 5. `okf-format`
- **Location:** [`skills/okf-format/SKILL.md`](../skills/okf-format/SKILL.md)
- **Purpose:** Author, validate, and maintain documentation pages conforming to the Open Knowledge Format (OKF v0.2).
- **Standards:**
  - Frontmatter schema (`type`, `title`, `description`, `tags`, `sources`, `generated`, `verified`).
  - Strict type definitions (`overview`, `architecture`, `module`, `workflow`, `concept`, `decision`).
  - Deterministic table-of-contents and navigation layout in `index.md`.

---

## 6. `mermaid-diagrams`
- **Location:** [`skills/mermaid-diagrams/SKILL.md`](../skills/mermaid-diagrams/SKILL.md)
- **Purpose:** Embed source-grounded Mermaid diagrams in documentation pages.
- **Supported Diagram Types:**
  - Flowcharts (`flowchart TD`, `flowchart LR`)
  - Sequence Diagrams (`sequenceDiagram`)
  - State Diagrams (`stateDiagram-v2`)
  - Entity-Relationship Diagrams (`erDiagram`)
  - Class Diagrams (`classDiagram`)
- **Rules:** Node labels with special characters must be quoted; diagrams must directly match code structure.

---

## 7. `wiki-workspace`
- **Location:** [`skills/wiki-workspace/SKILL.md`](../skills/wiki-workspace/SKILL.md)
- **Purpose:** Link multiple repository CodeWikis into shared workspaces to enable cross-repository search and unified architecture mapping across microservices or monorepos.
- **Workspace Location:** `~/.codewiki/workspaces/` or directory specified by the `CODEWIKI_CONFIG_DIR` environment variable.

---

## 8. `wiki-visualize`
- **Location:** [`skills/wiki-visualize/SKILL.md`](../skills/wiki-visualize/SKILL.md)
- **Purpose:** Generate a visual, standalone browser explorer for the CodeWiki with live Mermaid rendering and cross-linked page navigation.
- **Output:** Built outside the generated wiki tree (e.g. in `.codewiki-viewer/`) so repository documentation remains clean.