Add SKILLS.md documentation for Claude Code slash commands by 1a1a11a · Pull Request #312 · 1a1a11a/libCacheSim

1a1a11a · 2026-04-04T22:04:11Z

Summary

This PR adds comprehensive documentation for Claude Code slash-command skills available to agents working in the libCacheSim repository. The new SKILLS.md file serves as a reference guide for developers and automated agents using Claude Code features.

Changes

Added SKILLS.md: A new documentation file that catalogs seven Claude Code skills with:
- Quick reference table for all available skills
- Detailed sections for each skill including purpose, syntax, and usage guidelines
- Practical examples tailored to the libCacheSim project (e.g., eviction algorithm reviews, CMake build verification)
- A comparison table clarifying the distinction between hooks (persistent, automated) and one-off Claude interactions
- Specific guidance on when to use each skill in the context of C/C++ development, build systems, and performance testing

Notable Details

Documentation covers both session-based skills (/simplify, /loop) and persistent infrastructure (/schedule, /session-start-hook)
Includes a concrete example of a SessionStart hook for libCacheSim (CMake configuration and build)
Emphasizes the critical distinction between asking Claude to "remember" a behavior versus registering it durably in settings.json
Provides context-specific examples (cache trace analysis, synthetic trace generation, miss-ratio curve interpretation) to help agents understand when to apply each skill

https://claude.ai/code/session_01KTsbYTi2RdaKZTR6HKd7KF

Documents the seven Claude Code slash-command skills available in this repo, with usage guidance, examples, and a hooks-vs-asking-Claude clarification section. https://claude.ai/code/session_01KTsbYTi2RdaKZTR6HKd7KF

Copilot

Pull request overview

Adds a new top-level SKILLS.md reference document describing Claude Code slash-command “skills” intended for use by agents working in the libCacheSim repository.

Changes:

Introduces SKILLS.md with a quick-reference table and detailed sections for seven skills.
Adds guidance on hooks vs one-off Claude interactions, with libCacheSim-oriented examples.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-04T22:06:15Z

SKILLS.md

+
+**libCacheSim example hook:**
+```bash
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build -j$(nproc)


The libCacheSim example hook uses -j$(nproc), which won’t work on macOS (CI includes macOS). Consider using a cross-platform parallel build flag (e.g., CMake’s --parallel) or documenting an OS-specific alternative so the example runs on all supported platforms.

Suggested change

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build -j$(nproc)

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build --parallel

Copilot · 2026-04-04T22:06:16Z

SKILLS.md

+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
+```


This section says the SessionStart hook verifies dependencies and that tests are green, but the provided example hook only configures and builds. Either adjust the description to match what the example does, or extend the example to also cover dependency setup and running ctest so the guidance is consistent.

gemini-code-assist

Code Review

This pull request introduces a new documentation file, SKILLS.md, which provides a comprehensive guide to Claude Code slash-commands for the libCacheSim repository. The review identified three areas for improvement: updating the quick reference table for the /loop command to reflect that it accepts prompts, standardizing the build directory naming to _build for consistency and portability, and clarifying that the traces in the data/ directory are intended for functional smoke tests rather than performance regression checks.

gemini-code-assist · 2026-04-04T22:06:26Z

SKILLS.md

+| `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 |


The syntax description for the /loop command in the quick reference table is inconsistent with the detailed section (line 76) and the examples (line 82), which show that it can accept a natural language prompt as well as a command.

Suggested change

| `loop` | `/loop [interval] [cmd]` | Run a command repeatedly on a timed interval |

| loop | /loop [interval] [command/prompt] | Run a command or prompt repeatedly on a timed interval |

gemini-code-assist · 2026-04-04T22:06:26Z

SKILLS.md

+
+**libCacheSim example hook:**
+```bash
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build -j$(nproc)


The example uses build as the build directory, but the README.md (line 104) and other parts of the documentation use _build. For consistency and to avoid confusion with .gitignore rules, it's better to use _build. Additionally, nproc is not available on macOS; using cmake --build _build -j is a more portable way to enable parallel builds across the platforms supported by this project.

Suggested change

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build -j$(nproc)

cmake -S . -B _build -DCMAKE_BUILD_TYPE=Release && cmake --build _build -j

gemini-code-assist · 2026-04-04T22:06:26Z

SKILLS.md

+```
+
+**When to use:**
+- Nightly performance regression checks against reference traces in `data/`


The README.md (line 364) explicitly states that the traces in data/ are small samples and should not be used for evaluating performance or miss ratios. Suggesting "performance regression checks" against these traces might lead to misleading results due to their small size and high variance. It would be more accurate to describe these as functional regression checks or smoke tests.

Suggested change

- Nightly performance regression checks against reference traces in `data/`

- Nightly functional regression checks (smoke tests) against sample traces in data/

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

haochengxia

Layout looks good but content may need some modification. I can make correction if need.

haochengxia · 2026-04-05T05:10:14Z

SKILLS.md

+# libCacheSim Skills for Agents
+
+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.


Following the doc https://code.claude.com/docs/en/skills

We can change it with standard frontmatter

e.g.

--- name: libcachesim description: Build, run, profile, and extend libCacheSim in this repository. Use this skill when the task involves cache simulation, miss ratio analysis, trace inspection, MRC profiling, trace conversion, synthetic trace generation, or adding a new eviction algorithm. --- # libCacheSim Skill

haochengxia · 2026-04-05T05:27:22Z

SKILLS.md

+./build/test_plugin trace.oracleGeneral oracleGeneral 1073741824
+```
+
+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`.


Hallucination happens: file name and hook name mismatching

haochengxia · 2026-04-05T05:27:44Z

SKILLS.md

+
+## Trace formats
+
+| Format | Description |


Do we want to add lcs format?

haochengxia · 2026-04-05T05:33:24Z

SKILLS.md

+## Add a new eviction algorithm
+
+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.


Halluciation happens:

Extra metadata should be registered in libCacheSim/include/libCacheSim/cacheObj.h and algo name map should be added via libCacheSim/bin/cachesim/cache_init.h

docs: add SKILLS.md for agents

ef4570a

Documents the seven Claude Code slash-command skills available in this repo, with usage guidance, examples, and a hooks-vs-asking-Claude clarification section. https://claude.ai/code/session_01KTsbYTi2RdaKZTR6HKd7KF

1a1a11a requested a review from haochengxia as a code owner April 4, 2026 22:04

Copilot AI review requested due to automatic review settings April 4, 2026 22:04

Copilot started reviewing on behalf of 1a1a11a April 4, 2026 22:04 View session

Copilot AI reviewed Apr 4, 2026

View reviewed changes

gemini-code-assist bot reviewed Apr 4, 2026

View reviewed changes

haochengxia reviewed Apr 5, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add SKILLS.md documentation for Claude Code slash commands#312

Add SKILLS.md documentation for Claude Code slash commands#312
1a1a11a wants to merge 2 commits intodevelopfrom
claude/create-skills-documentation-naCHk

1a1a11a commented Apr 4, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

gemini-code-assist bot Apr 4, 2026

Uh oh!

gemini-code-assist bot Apr 4, 2026

Uh oh!

gemini-code-assist bot Apr 4, 2026

Uh oh!

haochengxia left a comment •

edited

Loading

Uh oh!

haochengxia Apr 5, 2026

Uh oh!

haochengxia Apr 5, 2026

Uh oh!

haochengxia Apr 5, 2026

Uh oh!

haochengxia Apr 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	cmake -S . -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build -j$(nproc)
	cmake -S . -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build --parallel

	\| `loop` \| `/loop [interval] [cmd]` \| Run a command repeatedly on a timed interval \|
	\| loop \| /loop [interval] [command/prompt] \| Run a command or prompt repeatedly on a timed interval \|

	cmake -S . -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build -j$(nproc)
	cmake -S . -B _build -DCMAKE_BUILD_TYPE=Release && cmake --build _build -j

	- Nightly performance regression checks against reference traces in `data/`
	- Nightly functional regression checks (smoke tests) against sample traces in data/

		# libCacheSim Skills for Agents

		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.

Conversation

1a1a11a commented Apr 4, 2026

Summary

Changes

Notable Details

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

haochengxia left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

haochengxia Apr 5, 2026

Choose a reason for hiding this comment

Uh oh!

haochengxia Apr 5, 2026

Choose a reason for hiding this comment

Uh oh!

haochengxia Apr 5, 2026

Choose a reason for hiding this comment

Uh oh!

haochengxia Apr 5, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

haochengxia left a comment •

edited

Loading