docs: rewrite SKILLS.md as libCacheSim capability guide for agents

claude · claude · commit 34e1a3c8e311 · 2026-04-04T22:07:54.000Z
Documents what agents can actually do in this repo: build, simulate, analyze traces, profile MRCs, plot results, use the C API, add algorithms, write plugins, and run tests. https://claude.ai/code/session_01KTsbYTi2RdaKZTR6HKd7KF
diff --git a/SKILLS.md b/SKILLS.md
@@ -1,145 +1,225 @@
-# Claude Code Skills for libCacheSim
+# libCacheSim Skills for Agents
 
-This file documents the Claude Code slash-command skills available to agents working in this repository. Skills are pre-built behaviors that extend Claude Code; invoke them with the `/skill-name` syntax in any Claude Code session.
+What you can do in this repository. Each section maps to a concrete capability, the tool or API that provides it, and the commands to invoke it.
 
-## Quick Reference
+---
+
+## Build
+
+```bash
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build -j$(nproc)
+```
+
+Produces three binaries in `build/bin/`: `cachesim`, `traceAnalyzer`, `mrcProfiler`.  
+Optional features require XGBoost/LightGBM; omit them unless the algorithm specifically needs it.
 
-| Skill | Command | Purpose |
-|---|---|---|
-| `update-config` | `/update-config` | Configure the Claude Code harness via `settings.json` |
-| `session-start-hook` | `/session-start-hook` | Set up `SessionStart` hooks (build checks, linters) |
-| `simplify` | `/simplify` | Review changed code for quality, reuse, and efficiency |
-| `loop` | `/loop [interval] [cmd]` | Run a command repeatedly on a timed interval |
-| `schedule` | `/schedule` | Create scheduled remote agents on a cron schedule |
-| `claude-api` | `/claude-api` | Build tools or integrations using the Anthropic SDK |
-| `keybindings-help` | `/keybindings-help` | Customize keyboard shortcuts |
+Install dependencies first if not present:
+
+```bash
+bash scripts/install_dependency.sh
+```
 
 ---
 
-## Skills
+## Simulate a cache
+
+`cachesim` runs one or more eviction algorithms against a trace file and reports hit/miss ratios.
 
-### `update-config` — Configure the harness
+```bash
+# Single algorithm, one cache size
+./build/bin/cachesim trace.oracleGeneral oracleGeneral 1073741824 LRU
 
-Use this when you want to add automated behaviors: "before every commit run the linter", "after each edit rebuild", etc. Automated behaviors are executed by the **harness** (not by Claude at prompt time), so they must be registered in `settings.json` via hooks—asking Claude to remember something is not sufficient.
+# Multiple algorithms in parallel
+./build/bin/cachesim trace.oracleGeneral oracleGeneral 1073741824 LRU,S3-FIFO,Sieve
 
-```
-/update-config
+# Auto-detect working set, sweep a range of sizes
+./build/bin/cachesim trace.oracleGeneral oracleGeneral 0 LRU --num-thread 4
+
+# CSV trace with custom column mapping
+./build/bin/cachesim trace.csv csv 1073741824 LRU \
+  -t "time-col=0, obj-id-col=1, obj-size-col=2, delimiter=,"
 ```
 
-**When to use:**
-- Setting up pre/post-tool hooks (e.g., run `cmake --build` after file edits)
-- Storing project-level defaults or allowed tool lists
-- Enabling or disabling specific capabilities for automated sessions
+**Supported eviction algorithms** (pass by name):  
+FIFO, LRU, Clock, SLRU, LFU, LFUDA, ARC, TwoQ, CLOCK-PRO, Belady, BeladySize, GDSF,  
+Hyperbolic, LeCaR, Cacheus, LHD, LRB, GLCache, WTinyLFU, 3LCache, QD-LP, S3-FIFO, Sieve
 
----
+**Admission algorithms** (combine with `-a`): Adaptsize, Bloomfilter, Prob, Size
 
-### `session-start-hook` — Ensure the project is ready at session start
+Full parameter reference: `./build/bin/cachesim --help`
 
-Sets up a `SessionStart` hook so every new Claude Code session begins by verifying the project is in a known-good state: dependencies installed, build passing, tests green.
+---
 
-```
-/session-start-hook
-```
+## Analyze a trace
 
-**When to use:**
-- First-time setup of a repo for Claude Code on the web
-- Ensuring `cmake` configuration and build succeed before an agent starts editing C code
-- Running `ctest` at session start to confirm no pre-existing failures
+`traceAnalyzer` extracts statistics and generates plot-ready data from a trace.
 
-**libCacheSim example hook:**
 ```bash
-cmake -S . -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build -j$(nproc)
-```
+# Overall statistics
+./build/bin/traceAnalyzer trace.oracleGeneral oracleGeneral --task stat
 
----
+# Request rate over time (window = 300 s)
+./build/bin/traceAnalyzer trace.oracleGeneral oracleGeneral --task reqRate -w 300
 
-### `simplify` — Code review after changes
+# Object size distribution
+./build/bin/traceAnalyzer trace.oracleGeneral oracleGeneral --task size
 
-After making edits, invoke this skill to review the changed code for redundancy, reuse opportunities, and inefficiencies. The skill finds issues and fixes them in place.
+# Reuse distance / reuse time distribution
+./build/bin/traceAnalyzer trace.oracleGeneral oracleGeneral --task reuse
 
-```
-/simplify
+# Popularity (frequency distribution)
+./build/bin/traceAnalyzer trace.oracleGeneral oracleGeneral --task popularity
+
+# Run all analysis tasks and write output files for plotting
+./build/bin/traceAnalyzer trace.oracleGeneral oracleGeneral --task all
 ```
 
-**When to use:**
-- After adding a new eviction algorithm to check for duplicated logic
-- After editing `CMakeLists.txt` to verify build targets aren't redundant
-- As a final pass before committing
+Output files are written to the current directory and consumed by scripts in `scripts/traceAnalysis/`.
 
 ---
 
-### `loop` — Recurring tasks
+## Profile a miss ratio curve (MRC)
 
-Runs a prompt or slash command on a repeating interval. Defaults to every 10 minutes if no interval is specified.
+`mrcProfiler` builds an MRC without simulating every cache size from scratch.
 
-```
-/loop [interval] [command or prompt]
-```
+```bash
+# SHARDS sampler — fast, LRU only
+./build/bin/mrcProfiler trace.oracleGeneral oracleGeneral SHARDS
 
-**Examples:**
-```
-/loop 5m /simplify
-/loop 2m check if the cmake build is still passing and report any errors
+# MINISIM sampler — supports any algorithm, multi-threaded
+./build/bin/mrcProfiler trace.oracleGeneral oracleGeneral MINISIM --num-thread 8
+
+# MRC relative to working set size
+./build/bin/mrcProfiler trace.oracleGeneral oracleGeneral SHARDS --use-wss
 ```
 
-**When to use:**
-- Watching a long `ctest` run and summarizing new failures as they appear
-- Periodically re-running the trace analyzer on a data file and diffing results
+SHARDS achieves ~23× speedup over full replay at <0.1% MAE.  
+MINISIM supports all algorithms that `cachesim` supports.
 
 ---
 
-### `schedule` — Cron-based remote agents
+## Plot results
+
+Python scripts in `scripts/` consume output from `traceAnalyzer` and `mrcProfiler`.
+
+```bash
+# Miss ratio curve vs cache size
+python3 scripts/plot_mrc_size.py --input result.mrc
+
+# MRC over time
+python3 scripts/plot_mrc_time.py --input result.mrc
 
-Creates, updates, lists, or runs scheduled remote agents that execute on a cron schedule. Unlike `/loop` (which runs in the current session), scheduled agents persist and run independently.
+# Approximate MRC (SHARDS / MINISIM output)
+python3 scripts/plot_appr_mrc.py --input result.mrc
 
+# Trace-level plots (run after traceAnalyzer --task all)
+python3 scripts/traceAnalysis/access_pattern.py
+python3 scripts/traceAnalysis/req_rate.py
+python3 scripts/traceAnalysis/popularity.py
+python3 scripts/traceAnalysis/reuse.py
 ```
-/schedule
+
+---
+
+## Generate a synthetic trace
+
+```bash
+# Zipf workload: 1M requests, 100K objects, alpha=1.0
+python3 scripts/data_gen.py --num-req 1000000 --num-obj 100000 --alpha 1.0 \
+  --output synthetic.oracleGeneral
 ```
 
-**When to use:**
-- Nightly performance regression checks against reference traces in `data/`
-- Weekly sweeps to ensure all example projects still build cleanly
-- Automated benchmark runs on a fixed schedule
+---
+
+## Inspect or convert a trace
+
+```bash
+# Print trace as human-readable text
+./build/bin/tracePrint trace.oracleGeneral oracleGeneral | head -20
+
+# Convert between trace formats
+./build/bin/traceConv trace.csv csv trace.oracleGeneral oracleGeneral
+```
 
 ---
 
-### `claude-api` — Build tools with the Anthropic SDK
+## Use the C API in code
+
+The library API lets you build custom simulators. See `example/` for complete working programs.
+
+```c
+#include "libCacheSim.h"
+
+// Open a trace
+reader_t *reader = open_trace("trace.oracleGeneral", ORACLE_GENERAL_TRACE, NULL);
+
+// Create a cache (e.g. 1 GiB LRU)
+common_cache_params_t params = default_common_cache_params();
+params.cache_size = 1 * GiB;
+cache_t *cache = LRU_init(params, NULL);
 
-Triggered automatically when code imports `anthropic` or `@anthropic-ai/sdk`. Also invoke manually when you want to build a script or integration that calls Claude programmatically.
+// Simulate
+request_t *req = new_request();
+while (read_one_req(reader, req) == 0) {
+    cache->get(cache, req);  // returns true on hit
+}
 
+free_request(req);
+free_cache(cache);
+close_trace(reader);
 ```
-/claude-api
+
+**Multi-size simulation** (runs N cache sizes in one pass):
+
+```c
+simulate_at_multi_sizes(reader, cache, n_sizes, cache_sizes, NULL, 0, 4 /*threads*/);
 ```
 
-**When to use in libCacheSim context:**
-- Writing a Python script that uses Claude to analyze cache trace output and suggest algorithm tuning
-- Building a Node.js tool on top of `libcachesim-node` that calls Claude to interpret miss-ratio curves
-- Generating synthetic trace files with LLM assistance
+See `example/cacheSimulator/` for a minimal single-cache example and  
+`example/cacheSimulatorConcurrent/` for multi-size and CSV trace usage.
 
 ---
 
-### `keybindings-help` — Customize keyboard shortcuts
+## Add a new eviction algorithm
 
-Modifies `~/.claude/keybindings.json` to rebind keys, add chord shortcuts, or change the submit key.
+1. Create `libCacheSim/cache/eviction/MyAlgo.c` — implement `init`, `get`, `find`, `insert`, `evict`, `remove`, `free`.
+2. Register it in `libCacheSim/cache/cacheObj.c` and the algo name map.
+3. Add it to `CMakeLists.txt`.
+4. Rebuild and verify with `cachesim`.
 
-```
-/keybindings-help
+See `doc/advanced_lib_extend.md` for the full walkthrough and `doc/advanced_lib.md` for internal data structures.
+
+---
+
+## Write a plugin (without modifying core)
+
+The plugin system lets you implement an algorithm as a shared library loaded at runtime.
+
+```bash
+cd example/plugin_v2
+cmake -S . -B build && cmake --build build
+./build/test_plugin trace.oracleGeneral oracleGeneral 1073741824
 ```
 
-**When to use:**
-- Rebinding a key that conflicts with your terminal emulator
-- Adding a chord shortcut for a frequently used command like `/simplify`
+Implement the six hooks in your plugin: `plugin_init`, `plugin_hit`, `plugin_miss`, `plugin_eviction`, `plugin_remove`, `plugin_free`. See `example/plugin_v2/myPlugin.cpp`.
 
 ---
 
-## Hooks vs. Asking Claude
+## Run tests
 
-A common confusion: asking Claude "always run the linter after you edit a file" does **not** persist beyond the current session. To make a behavior automatic and durable, it must be registered as a hook in `settings.json`. Use `/update-config` or `/session-start-hook` to set this up correctly.
+```bash
+cd build && ctest --output-on-failure
+```
 
-| Goal | Right approach |
+---
+
+## Trace formats
+
+| Format | Description |
 |---|---|
-| Run `cmake --build` after every file edit | `/update-config` → PostToolUse hook |
-| Verify build at the start of every session | `/session-start-hook` |
-| One-off code review | `/simplify` |
-| Recurring check during a session | `/loop` |
-| Persistent scheduled agent | `/schedule` |
+| `oracleGeneral` | Binary struct: `{uint32 timestamp, uint64 obj_id, uint32 obj_size, int64 next_access_vtime}`. Supports `.zst` compression. |
+| `csv` | Plain text; column mapping required via `-t` flag. |
+| `binary` | Raw fixed-width binary records. |
+
+Object IDs in oracleGeneral are hashed values. `next_access_vtime` is logical time (request count, not wall clock).
