From 7bc24420753b8290d678458ba645872a1c785550 Mon Sep 17 00:00:00 2001 From: Runchao Han Date: Sat, 18 Apr 2026 21:54:21 +0800 Subject: [PATCH] Drop /reaper: prefix from slash-command examples Claude Code no longer requires the plugin prefix for skill slash commands, so all docs and Usage blocks now reference `/` directly. Co-Authored-By: Claude Opus 4.7 --- CLAUDE.md | 2 +- README.md | 4 ++-- dev/ROADMAP.md | 6 +++--- evals/evals.json | 2 +- skills/analyze-paper/SKILL.md | 2 +- skills/brainstorm/SKILL.md | 2 +- skills/clarify-goal/SKILL.md | 2 +- skills/critique/SKILL.md | 2 +- skills/formalize-problem/SKILL.md | 2 +- skills/investigate/SKILL.md | 2 +- skills/reaper/SKILL.md | 6 +++--- skills/review-literature/SKILL.md | 4 ++-- skills/search-arxiv/SKILL.md | 2 +- skills/search-iacr/SKILL.md | 2 +- skills/synthesize/SKILL.md | 2 +- 15 files changed, 21 insertions(+), 21 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index e3df7f2..f07b2de 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -45,7 +45,7 @@ Primary distribution: [`vercel-labs/skills`](https://github.com/vercel-labs/skil - Pin syntax: `npx skills add SebastianElvis/reaper#v0.3.9`. Tagged releases are the pin contract. - The installer copies the entire skill directory (including Python scripts and `references/`); only `metadata.json`, `.git`, `__pycache__`, `__pypackages__` are excluded. -- All `SKILL.md` files must use host-agnostic phrasing ("invoke the `` skill") for inter-skill calls. Sub-skill `Usage` blocks may show host-specific invocation forms (e.g. `/reaper:` for Claude Code) as examples, clearly labeled as such. +- All `SKILL.md` files must use host-agnostic phrasing ("invoke the `` skill") for inter-skill calls. Sub-skill `Usage` blocks may show host-specific invocation forms (e.g. `/` on slash-command hosts like Claude Code) as examples, clearly labeled as such. Secondary distribution: Claude Code plugin via `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json`. When adding, removing, or renaming a skill, keep the `skills` array in `marketplace.json` in sync. Keep `version` in both `plugin.json` and `marketplace.json` consistent with the current release tag — note that `marketplace.json.version` is ignored by `npx skills` (which uses git tags), so it serves only the Claude Code plugin path. diff --git a/README.md b/README.md index 2a77ce4..24ef248 100644 --- a/README.md +++ b/README.md @@ -74,7 +74,7 @@ Each skill can be used independently or composed by the orchestrator. Invoke by | `/search-arxiv` | Search arXiv papers, download PDFs, and trace citation graphs | | `/search-iacr` | Search IACR ePrint archive for cryptography papers | -> The `/` form is the canonical display convention used throughout these docs. Slash-command hosts (Claude Code) invoke them directly that way (with sub-skills as `/reaper:clarify-goal` etc.). Auto-discovery hosts (Cursor, Codex CLI, Cline, Continue, Gemini CLI, Copilot, Windsurf, …) invoke them by the bare skill name — drop the leading `/` when asking the agent to run a skill. +> The `/` form is the canonical display convention used throughout these docs. Slash-command hosts (Claude Code) invoke them directly that way (e.g. `/clarify-goal`). Auto-discovery hosts (Cursor, Codex CLI, Cline, Continue, Gemini CLI, Copilot, Windsurf, …) invoke them by the bare skill name — drop the leading `/` when asking the agent to run a skill. ## Installation @@ -128,7 +128,7 @@ See the [Claude Code plugin docs](https://code.claude.com/docs/en/discover-plugi ### Invocation across hosts -- **Slash-command hosts** (Claude Code): `/reaper ""`, `/reaper:analyze-paper `, etc. The `/:` routing is built into the host. +- **Slash-command hosts** (Claude Code): `/reaper ""`, `/analyze-paper `, etc. Each skill is available as a top-level slash command. - **Auto-discovery hosts** (Cursor, Codex CLI, Cline, Continue, Gemini CLI, Copilot, Windsurf, …): the agent loads `SKILL.md` files from its skills folder and invokes them by name when the task matches the skill's `description`. Ask the agent to run the skill, e.g. *"use the reaper skill to research X"*. - **Manual invocation**: any host can be pointed at a specific `SKILL.md` if its native discovery doesn't pick it up. diff --git a/dev/ROADMAP.md b/dev/ROADMAP.md index 3de0622..ec144b8 100644 --- a/dev/ROADMAP.md +++ b/dev/ROADMAP.md @@ -424,7 +424,7 @@ Different models have different strengths. The critique skill should route consu | Host | Skills folder | Discovery model | Notes | |------|--------------|-----------------|-------| -| Claude Code | `.claude/skills/` | Slash commands (`/reaper:`) + Skill tool | Native plugin path also available via `.claude-plugin/marketplace.json` | +| Claude Code | `.claude/skills/` | Slash commands (`/`) + Skill tool | Native plugin path also available via `.claude-plugin/marketplace.json` | | Cursor | `.agents/skills/` (universal) | Auto-route by `description` match | | | OpenAI Codex CLI | `.agents/skills/` (universal) | Auto-route by `description` match | | | Cline | `.agents/skills/` (universal) | Auto-route by `description` match | | @@ -443,14 +443,14 @@ Different models have different strengths. The critique skill should route consu - The `--codex` flag depends on a host with MCP support and a registered Codex MCP server. Non-MCP hosts silently fall back to self-review. - Auto-discovery quality varies by host. Reliable routing depends on the skill's `description` matching the user's request — Reaper's descriptions are tuned for action-verb match (e.g. "Run the full Reaper research pipeline…") to improve auto-routing. - Python dependencies (`arxiv`, `requests`, `beautifulsoup4`) are not installed by `npx skills` — users must `pip install` separately. The skill prose tells the agent to do this if missing. -- Sub-skill `Usage` blocks now lead with the bare-name form and show `/reaper:` as a slash-command-host example only. +- Sub-skill `Usage` blocks now lead with the bare-name form and show `/` as a slash-command-host example only. #### Tasks - [x] Adopt `vercel-labs/skills` `SKILL.md` convention as the canonical distribution format - [x] Audit all skill frontmatter for `npx skills` parser compliance (`name` regex, `name` matches directory) - [x] Rewrite orchestrator + critique inter-skill triggers to host-agnostic phrasing -- [x] Update sub-skill `Usage` blocks to lead with skill-name invocation, mark `/reaper:` as slash-command-host example +- [x] Update sub-skill `Usage` blocks to lead with skill-name invocation, mark `/` as slash-command-host example - [x] Document multi-host install in README (`npx skills add` as primary, Claude Code plugin as secondary) - [x] Add CI: frontmatter validation + `npx skills add` discovery check - [ ] Per-host smoke test: same research goal on Cursor, Codex CLI, Gemini CLI — compare workspace output quality and routing reliability diff --git a/evals/evals.json b/evals/evals.json index 49b2b97..f5052ca 100644 --- a/evals/evals.json +++ b/evals/evals.json @@ -125,7 +125,7 @@ "evaluation_protocol": { "setup": "1. Place a test paper PDF in dev/test-papers/ with the filename matching the test case\n2. Open any skills-supporting AI agent (Claude Code, Cursor, Codex CLI, Cline, Continue, Gemini CLI, Copilot, Windsurf, OpenCode, Warp, Goose, Replit, etc.) in the repo root with the reaper skills installed (`npx skills add SebastianElvis/reaper`)", "run_full_pipeline": "Invoke the `reaper` skill with arguments: `\"\" dev/test-papers/.pdf`. On slash-command hosts: `/reaper \"\" dev/test-papers/.pdf`. On auto-discovery hosts: ask the agent to run reaper with the goal and paper path.", - "run_individual_skill": "Invoke the named sub-skill (e.g. `analyze-paper`, `review-literature`) by name with its arguments. On slash-command hosts: `/reaper: `. On auto-discovery hosts: ask the agent to run the skill by name.", + "run_individual_skill": "Invoke the named sub-skill (e.g. `analyze-paper`, `review-literature`) by name with its arguments. On slash-command hosts: `/ `. On auto-discovery hosts: ask the agent to run the skill by name.", "evaluate": "After the pipeline completes, check each expected_output and quality_criteria. Score pass/fail per criterion.", "iterate": "For each failure, identify whether the issue is in the skill prompt, the orchestrator composition, or the model's capability. Fix skill prompts first." } diff --git a/skills/analyze-paper/SKILL.md b/skills/analyze-paper/SKILL.md index a12616a..dfc49f1 100644 --- a/skills/analyze-paper/SKILL.md +++ b/skills/analyze-paper/SKILL.md @@ -11,7 +11,7 @@ Extract structured information from an academic paper, producing a comprehensive ## Usage -Invoke this skill by name with the paper path (and optional flags). On slash-command hosts, prefix with `/reaper:` (e.g. `/reaper:analyze-paper `). +Invoke this skill by name with the paper path (and optional flags). On slash-command hosts, prefix with `/` (e.g. `/analyze-paper `). ``` # Analyze the primary paper under study diff --git a/skills/brainstorm/SKILL.md b/skills/brainstorm/SKILL.md index 99c66d3..079974f 100644 --- a/skills/brainstorm/SKILL.md +++ b/skills/brainstorm/SKILL.md @@ -11,7 +11,7 @@ The recurring ideation step. Reads the current research state and proposes new o ## Usage -Invoke this skill by name; pass an optional context hint as a quoted string. On slash-command hosts, prefix with `/reaper:` (e.g. `/reaper:brainstorm ""`). +Invoke this skill by name; pass an optional context hint as a quoted string. On slash-command hosts, prefix with `/` (e.g. `/brainstorm ""`). ``` # Generate ideas based on current state diff --git a/skills/clarify-goal/SKILL.md b/skills/clarify-goal/SKILL.md index d51e4bb..85352f8 100644 --- a/skills/clarify-goal/SKILL.md +++ b/skills/clarify-goal/SKILL.md @@ -11,7 +11,7 @@ Ask the user targeted questions to sharpen a vague research goal into something ## Usage -Invoke this skill by name with the research goal (and optional paper path). On slash-command hosts, prefix with `/reaper:` (e.g. `/reaper:clarify-goal ""`). +Invoke this skill by name with the research goal (and optional paper path). On slash-command hosts, prefix with `/` (e.g. `/clarify-goal ""`). ``` # Without a paper — goal-driven research diff --git a/skills/critique/SKILL.md b/skills/critique/SKILL.md index ba29c70..6109ae6 100644 --- a/skills/critique/SKILL.md +++ b/skills/critique/SKILL.md @@ -11,7 +11,7 @@ Provide external perspective on investigation results. Three modes: human feedba ## Usage -Invoke this skill by name; pass either feedback as a quoted string, `--codex`, or `--self`. On slash-command hosts, prefix with `/reaper:` (e.g. `/reaper:critique ""`). +Invoke this skill by name; pass either feedback as a quoted string, `--codex`, or `--self`. On slash-command hosts, prefix with `/` (e.g. `/critique ""`). ``` # Human feedback — iterate on existing results diff --git a/skills/formalize-problem/SKILL.md b/skills/formalize-problem/SKILL.md index 7b53a61..9ff7c17 100644 --- a/skills/formalize-problem/SKILL.md +++ b/skills/formalize-problem/SKILL.md @@ -11,7 +11,7 @@ Transform a research goal into precise, testable hypotheses with explicit succes ## Usage -Invoke this skill by name with the research goal as a quoted string. On slash-command hosts, prefix with `/reaper:` (e.g. `/reaper:formalize-problem ""`). +Invoke this skill by name with the research goal as a quoted string. On slash-command hosts, prefix with `/` (e.g. `/formalize-problem ""`). ``` formalize-problem "determine if the security proof in Section 4 holds under asynchrony" diff --git a/skills/investigate/SKILL.md b/skills/investigate/SKILL.md index f031808..5d6a0c8 100644 --- a/skills/investigate/SKILL.md +++ b/skills/investigate/SKILL.md @@ -11,7 +11,7 @@ The core research loop. Run N investigation cycles, each testing a hypothesis an ## Usage -Invoke this skill by name with an optional cycle count. On slash-command hosts, prefix with `/reaper:` (e.g. `/reaper:investigate 10`). +Invoke this skill by name with an optional cycle count. On slash-command hosts, prefix with `/` (e.g. `/investigate 10`). ``` # Run 10 investigation cycles diff --git a/skills/reaper/SKILL.md b/skills/reaper/SKILL.md index 86d953f..8f97e3a 100644 --- a/skills/reaper/SKILL.md +++ b/skills/reaper/SKILL.md @@ -38,7 +38,7 @@ If any of these are missing from your agent's skills folder, ask the user to rei References below to running a sub-skill use the host-agnostic phrase "invoke the `` skill" — invoke each sub-skill by its `name` using your host's native skill-loading mechanism. The loaded `SKILL.md` provides the full instructions for that stage. Concrete invocation form varies by host: -- **Slash-command hosts** (e.g. Claude Code): `/reaper:` (e.g. `/reaper:clarify-goal`) +- **Slash-command hosts** (e.g. Claude Code): `/` (e.g. `/clarify-goal`) - **Auto-discovery hosts** (e.g. Cursor, Codex CLI, Cline, Continue, Gemini CLI, Copilot, Windsurf, OpenCode): the agent loads peer `SKILL.md` files from the skills folder and routes by `name` + `description` match. - **Manual invocation hosts**: explicitly point the agent at the installed skill's `SKILL.md` (typical paths: `~/.claude/skills//SKILL.md`, `~/.cursor/skills//SKILL.md`, `~/.agents/skills//SKILL.md`, `~/.continue/skills//SKILL.md`, `~/.windsurf/skills//SKILL.md`, or `/skills//SKILL.md` during development — substitute `` with the sub-skill directory name like `clarify-goal`). @@ -191,7 +191,7 @@ After synthesis completes: After presenting results, let the user know they can iterate: -> If you'd like to refine, deepen, or challenge any aspect of this research, invoke the `/critique` skill with your feedback as a quoted string. (Slash-command hosts: `/reaper:critique "your feedback here"`.) +> If you'd like to refine, deepen, or challenge any aspect of this research, invoke the `/critique` skill with your feedback as a quoted string. (Slash-command hosts: `/critique "your feedback here"`.) Do **not** block waiting for a response — the pipeline is complete. The user can invoke `/critique` with quoted feedback at any time to start a feedback round. The critique skill classifies the feedback, may run targeted investigation cycles, and then you should re-invoke `/synthesize` to produce an updated report. @@ -220,7 +220,7 @@ Do **not** block waiting for a response — the pipeline is complete. The user c ## Important Notes -- Sub-skills are invoked using the host agent's native skill mechanism — by `name` plus arguments. The exact API differs per host (e.g. Claude Code's `Skill` tool with `skill: "reaper:analyze-paper", args: "paper.pdf"`; Cursor/Codex/Cline auto-route based on the loaded `SKILL.md`). Refer to the host's skill documentation for the exact form. +- Sub-skills are invoked using the host agent's native skill mechanism — by `name` plus arguments. The exact API differs per host (e.g. Claude Code's `Skill` tool with `skill: "analyze-paper", args: "paper.pdf"`; Cursor/Codex/Cline auto-route based on the loaded `SKILL.md`). Refer to the host's skill documentation for the exact form. - Skills communicate exclusively through workspace files — no in-memory state passing - If a skill fails, read its output file to diagnose, then retry - The workspace is the source of truth — if context is compressed, re-read workspace files diff --git a/skills/review-literature/SKILL.md b/skills/review-literature/SKILL.md index fcdcac9..1eb0632 100644 --- a/skills/review-literature/SKILL.md +++ b/skills/review-literature/SKILL.md @@ -11,7 +11,7 @@ Search for related academic work, download and deeply read the most important pa ## Usage -Invoke this skill by name with the research topic as a quoted string. On slash-command hosts, prefix with `/reaper:` (e.g. `/reaper:review-literature ""`). +Invoke this skill by name with the research topic as a quoted string. On slash-command hosts, prefix with `/` (e.g. `/review-literature ""`). ``` review-literature "post-quantum threshold signatures" @@ -151,7 +151,7 @@ After downloading, **delegate paper reading to `/analyze-paper`**. For each down reaper-workspace/papers/.pdf --goal "" --output reaper-workspace/papers/-notes.md ``` -(On Claude Code: `/reaper:analyze-paper `. On other agents: invoke by skill name with the same arguments.) +(On Claude Code: `/analyze-paper `. On other agents: invoke by skill name with the same arguments.) **Spawn parallel subagents** (using your host's parallel-spawn primitive — e.g. Claude Code's `Agent` tool — or run sequentially if unavailable) to analyze multiple papers concurrently — each paper is independent. diff --git a/skills/search-arxiv/SKILL.md b/skills/search-arxiv/SKILL.md index fbcc42f..9bb1471 100644 --- a/skills/search-arxiv/SKILL.md +++ b/skills/search-arxiv/SKILL.md @@ -11,7 +11,7 @@ Search arXiv for academic papers using the `arxiv` Python package, with citation ## Usage -Invoke this skill by name with the query as a quoted string. On slash-command hosts, prefix with `/reaper:` (e.g. `/reaper:search-arxiv ""`). +Invoke this skill by name with the query as a quoted string. On slash-command hosts, prefix with `/` (e.g. `/search-arxiv ""`). ``` search-arxiv "post-quantum threshold signatures" --max-results 15 --categories cs.CR diff --git a/skills/search-iacr/SKILL.md b/skills/search-iacr/SKILL.md index ad3fddd..4e6fc62 100644 --- a/skills/search-iacr/SKILL.md +++ b/skills/search-iacr/SKILL.md @@ -11,7 +11,7 @@ Search the IACR Cryptology ePrint Archive for cryptography and security papers. ## Usage -Invoke this skill by name with the query as a quoted string. On slash-command hosts, prefix with `/reaper:` (e.g. `/reaper:search-iacr ""`). +Invoke this skill by name with the query as a quoted string. On slash-command hosts, prefix with `/` (e.g. `/search-iacr ""`). ``` search-iacr "threshold signatures" --max-results 15 diff --git a/skills/synthesize/SKILL.md b/skills/synthesize/SKILL.md index 0c78596..03b0f6d 100644 --- a/skills/synthesize/SKILL.md +++ b/skills/synthesize/SKILL.md @@ -11,7 +11,7 @@ Generate a formal research paper from all investigation results. The output shou ## Usage -Invoke this skill by name; no arguments required. On slash-command hosts, prefix with `/reaper:` (e.g. `/reaper:synthesize`). +Invoke this skill by name; no arguments required. On slash-command hosts, prefix with `/` (e.g. `/synthesize`). ``` synthesize