From agentops
Compiles `.agents/` knowledge artifacts into an interlinked Markdown wiki with backlinks, an index, and linting for contradictions and orphans. Invoke via `/compile` or let Claude auto-activate when building a persistent, context-sized knowledge base.
How this skill is triggered — by the user, by Claude, or both
Slash command
/agentops:compileThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> **Loop position:** move 7 (capture + ratchet) of the [operating loop](../../docs/architecture/operating-loop.md) — compiles promoted `.agents/` learnings into the interlinked wiki (the compound sub-step).
Loop position: move 7 (capture + ratchet) of the operating loop — compiles promoted
.agents/learnings into the interlinked wiki (the compound sub-step).
Reads raw .agents/ artifacts and compiles them into a structured, interlinked
markdown wiki. Inspired by Karpathy's LLM Knowledge Bases.
The knowledge flywheel captures signal reactively (via /post-mortem,
/forge). /compile closes the loop by:
.agents/ (existing)No vector DB. At personal scale (~100-400 articles), the compiled wiki fits in context windows. The wiki IS the retrieval layer.
Output: .agents/compiled/ — encyclopedia-style markdown with [[backlinks]],
index.md catalog, and log.md chronological record.
Set AGENTOPS_COMPILE_RUNTIME to choose the LLM backend:
| Value | Backend | Notes |
|---|---|---|
codex-cli | Local codex binary | Zero-config. Inherits your Codex CLI auth — no API key needed. Auto-selected if codex is on PATH and nothing else is set. |
ollama | Ollama API | Default model: gemma3:27b. Set OLLAMA_HOST for remote (e.g., ssh -L 11435:localhost:11435 bushido-windows). |
claude | Claude API (HTTP) | Uses ANTHROPIC_API_KEY. Model: claude-sonnet-4-20250514. |
openai | OpenAI-compatible | Uses OPENAI_API_KEY + OPENAI_BASE_URL. |
| (unset) | Claude Code session | Compilation happens inline via the current session's LLM. |
When AGENTOPS_COMPILE_RUNTIME is unset, ao compile first tries to
auto-detect a local codex binary (codex-cli runtime). If that is also
absent, headless compile fails fast with an explicit error naming the env var
to set. Interactive /compile invocations still run compilation prompts
inline — the agent reading this SKILL.md IS the compiler.
To force a non-auto-detected runtime permanently (e.g. you have claude
installed but prefer Ollama for privacy), set it in
~/.agentops/config.yaml:
compile:
preferred_runtime: ollama
Precedence (high → low): --runtime flag, AGENTOPS_COMPILE_RUNTIME
env, compile.preferred_runtime config, codex-binary auto-detect,
empty (error).
ao compile passes --batch-size to the headless compiler (default 25
changed files per LLM prompt). A fresh run against a 2000+ file corpus will
split into batches automatically instead of sending one giant prompt.
Flags:
--batch-size N — files per batch (default 25)--max-batches N — cap batches per invocation; remaining files are picked
up on the next run (default 0 = unlimited)Phase-by-phase detail lives in references/phases.md. Summary of modes:
/compile — Full cycle: Mine → Grow → Compile → Lint → Defrag/compile --compile-only — Skip mine/grow, just compile + lint/compile --lint-only — Only lint the existing compiled wiki/compile --defrag-only — Only run defrag/cleanup/compile --mine-only — Only run mine + grow (legacy behavior)The steps are:
.agents/research/ + complexity hotspots[[backlinks]].agents/compile/YYYY-MM-DD-report.mdSee references/phases.md for the full per-phase procedure, confidence-scoring table, auto-promotion rules, template shapes for article / index / log / lint-report / compile-report, and the normalization defect scan.
Lightweight defrag (prune + dedup, no mining or compilation) runs automatically at
session end via the compile-session-defrag.sh hook. This keeps the knowledge store
clean without requiring manual /compile invocations. The hook:
SessionEnd event after session-end-maintenance.shao CLI is not availableao defrag --prune --dedup (no compilation or mining)For full compilation, invoke /compile manually or schedule the headless compiler
script with your host OS:
# Example: external cron entry for nightly compilation on bushido
0 3 * * * cd /path/to/repo && AGENTOPS_COMPILE_RUNTIME=ollama bash skills/compile/scripts/compile.sh --force
AgentOps exposes this flow through ao compile. If you want unattended
compilation, use your host scheduler (launchd, cron, systemd, CI, etc.)
to invoke ao compile --force --runtime ollama or call the lower-level
bash skills/compile/scripts/compile.sh directly.
If you want the broader out-of-session compounding loop, run it on the
out-of-session substrate (NTM + MCP + managed-agents) instead of inventing a
parallel Dream wrapper inside /compile.
These modes describe the interactive /compile skill behavior:
| Mode | Description |
|---|---|
--compile-only | Skip mine/grow, just compile + lint |
--lint-only | Only lint the existing compiled wiki |
--defrag-only | Only run defrag/cleanup |
--mine-only | Only run mine + grow (legacy behavior) |
--full | Full cycle: mine → grow → compile → lint → defrag |
--since 26h | Time window for the mine phase |
--incremental | Skip unchanged source files (hash-based) |
--force | Recompile all articles regardless of hashes |
For unattended runs, bash skills/compile/scripts/compile.sh supports:
| Flag | Default | Description |
|---|---|---|
--sources <dir> | .agents | Source root for learnings, patterns, research, retros, forge, and knowledge |
--output <dir> | .agents/compiled | Target directory for compiled wiki output |
--incremental | on | Skip unchanged source files (hash-based) |
--force | off | Recompile all articles regardless of hashes |
--lint-only | off | Only run the lint pass on the existing compiled wiki |
--full | on | Accepted for parity; default behavior already runs the full headless compile path |
User says: /compile — Full Mine → Grow → Compile → Lint → Defrag cycle.
User says: /compile --compile-only — Just compile raw artifacts into wiki.
User says: /compile --lint-only — Scan existing wiki for health issues.
User says: /compile --since 7d — Mines with a wider window (7 days).
Scheduled externally: Nightly compilation on bushido GPU via Ollama.
Pre-evolve warmup: Run /compile before /evolve for a fresh, validated knowledge base.
| Problem | Cause | Solution |
|---|---|---|
ao mine not found | ao CLI not in PATH | Use manual fallback in Step 1 |
| No orphaned research | All research already referenced | Skip 2b, proceed to synthesis |
| Empty mine output | No recent activity | Widen --since window |
| Oscillation sweep empty | No oscillating goals | Healthy state — no action needed |
| Ollama connection refused | Tunnel not running or wrong host | Run ssh -L 11435:localhost:11435 bushido-windows or check OLLAMA_HOST |
| Compilation too slow | Large corpus on small model | Use --incremental or switch to larger model |
| Hash file missing | First compilation | Normal — full compile runs, hashes saved after |
references/compile.feature — Executable spec: Mine→Grow→Lint→Defrag rebuild, lint-not-autofix, incremental batching, evolve warmup (soc-qk4b)
references/phases.md — full per-phase procedure (mine → grow → compile → lint → defrag → report)
npx claudepluginhub boshu2/agentops --plugin agentopsUse when compiling raw sources into the wiki, querying the knowledge base, running health checks or lint on the wiki, evolving or improving wiki coverage, or when user says 'compile', 'update the wiki', 'query', 'lint', 'health check', 'evolve', 'what's missing', or 'suggest improvements'. Also triggers on questions that should be answered from the knowledge base.
Manages LLM-compiled knowledge bases in .wiki/ or ~/wiki/: ingests sources to raw/, compiles interconnected markdown articles with indexes, queries, lints, and supports topic sub-wikis.
Compiles Markdown source files from configured directories into topic-based wiki articles via 5-phase algorithm: scan sources, classify topics, generate templated pages. Invoked by /wiki-compile.