SebastianElvis · SebastianElvis · May 2, 2026 · May 2, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -27,7 +27,12 @@ pip install arxiv requests beautifulsoup4
 
 ## Key conventions
 
-- Skills are the unit of composition. Each skill directory contains a `SKILL.md` with YAML frontmatter — `name` (lowercase + hyphens, matches the directory name) and `description` are required by the [`vercel-labs/skills`](https://github.com/vercel-labs/skills) parser; everything else is optional.
+- Skills follow the [Agent Skills specification](https://agentskills.io/specification). Each skill directory contains a `SKILL.md` with YAML frontmatter. Required fields: `name` (1–64 chars, lowercase alphanumeric + hyphens, no leading/trailing/consecutive hyphens, must match the parent directory name) and `description` (1–1024 chars, describes both what the skill does and when to use it). Recognized optional fields: `license`, `compatibility`, `metadata`, `allowed-tools`. All skills in this repo set `license: Apache-2.0`.
+- Skill authoring follows the [best practices](https://agentskills.io/skill-creation/best-practices) and [description guidance](https://agentskills.io/skill-creation/optimizing-descriptions):
+  - Keep `SKILL.md` under 500 lines / ~5000 tokens; use `references/` for detail loaded on demand, and tell the agent *when* to load each reference file.
+  - Spend context wisely: add what the agent lacks, omit what it knows. Provide a clear default rather than a menu of options.
+  - Match instruction specificity to task fragility — be prescriptive for fragile/destructive operations, descriptive (with the *why*) for flexible ones.
+  - Descriptions use imperative phrasing ("Use when…"), focus on user intent, and stay under 1024 chars.
 - The orchestrator skill (`/reaper`) runs the full pipeline: clarify → analyze → literature → formalize → brainstorm → investigate ↔ critique → synthesize. After delivery, users can iterate by re-invoking the `/critique` skill with feedback.
 - Runtime state goes in `reaper-workspace/` (gitignored). Never commit workspace artifacts.
 - The six methodology principles (separation of concerns, fixed evaluation signal, structured results log, keep-or-discard loop, never stop, clarity and simplicity) govern how skills behave.

diff --git a/skills/analyze-paper/SKILL.md b/skills/analyze-paper/SKILL.md
@@ -3,6 +3,8 @@ name: analyze-paper
 description: "Extract structured information from a research paper: system model, theorem statements, proof techniques, complexity claims, and red flags. Use when asked to analyze, summarize, or review an academic paper."
 user-invocable: true
 argument-hint: "<paper-path> [--output <path>] [--goal \"<goal>\"]"
+license: Apache-2.0
+compatibility: "Requires PDF reading capability for the paper under analysis."
 ---
 
 # Analyze Paper
@@ -25,26 +27,14 @@ analyze-paper reaper-workspace/papers/2024-1234.pdf --goal "post-quantum thresho
 - `--output <path>`: Write output to the given path instead of the default `reaper-workspace/notes/paper-summary.md`.
 - `--goal "<text>"`: The research goal as additional context. When provided, the output includes a **Relevance** section assessing how the paper relates to this goal, and reading depth is calibrated by relevance (see Step 1).
 
-## Path Resolution Protocol
-
-This skill references files in sibling skills. **`{{REAPER_SKILL_DIR}}`** below is a template placeholder — **you MUST substitute it with the absolute install path of the `/reaper` skill before reading, or the read will fail.** Common install locations:
-
-- `~/.claude/skills/reaper/` (Claude Code)
-- `~/.cursor/skills/reaper/` (Cursor)
-- `~/.agents/skills/reaper/` (Codex CLI, Cline, Gemini CLI, Copilot, OpenCode, Warp, Goose, Replit — universal target)
-- `~/.continue/skills/reaper/` (Continue)
-- `~/.windsurf/skills/reaper/` (Windsurf)
-- `<repo-root>/skills/reaper/` (during repo development)
-
-**Sibling-skill dependency**: This skill assumes the full `/reaper` package was installed together (`npx skills add SebastianElvis/reaper`). Single-skill installs will fail to resolve sibling references.
 
 ## Instructions
 
 ### 1. Read the Paper
 
 Read the paper at the provided path using your host's file-read primitive (works for PDFs and text files on hosts that support PDF reading; otherwise extract text first).
 
-Follow the three-pass strategy from `{{REAPER_SKILL_DIR}}/references/paper-analysis.md`:
+Follow the three-pass strategy from `../reaper/references/paper-analysis.md`:
 
 - **Pass 1 (skeleton)**: Abstract, introduction, conclusion, theorem statements. Identify the main claims.
 - **Pass 2 (construction)**: Protocol details, proof sketches, figures. Understand the key technical idea.
@@ -76,7 +66,7 @@ Write the extracted information to `reaper-workspace/notes/paper-summary.md` (or
 What problem does this paper solve? Why does it matter?
 
 ## System Model
-[Extract all model dimensions relevant to the paper's domain. Consult `{{REAPER_SKILL_DIR}}/references/model.md` for the domain-appropriate dimensions to extract. Every applicable dimension must have a concrete answer.]
+[Extract all model dimensions relevant to the paper's domain. Consult `../reaper/references/model.md` for the domain-appropriate dimensions to extract. Every applicable dimension must have a concrete answer.]
 
 ## Construction Overview
 High-level protocol description. Key technical idea. Building blocks used.
@@ -105,7 +95,7 @@ Overall proof approach. Key lemmas. Reduction chain. Where the corruption thresh
 Non-standard notation. Formal definitions referenced by the proofs.
 
 ## Red Flags
-Any concerns identified during reading (see `{{REAPER_SKILL_DIR}}/references/paper-analysis.md` for common red flags).
+Any concerns identified during reading (see `../reaper/references/paper-analysis.md` for common red flags).
 
 ## Relevance
 [Present ONLY when --goal is provided. Tag one or more: *problem definition*, *formalization*, *solution technique*, *negative result*, *literature/context*, *writing model*. One sentence per tag explaining how this paper relates to the research goal.]

diff --git a/skills/brainstorm/SKILL.md b/skills/brainstorm/SKILL.md
@@ -3,6 +3,7 @@ name: brainstorm
 description: "Generate, prioritize, and refine research ideas based on current investigation state. Use when the pipeline needs new or better hypotheses — after formalization, between investigation batches, or when all current ideas are resolved."
 user-invocable: true
 argument-hint: "[context-hint]"
+license: Apache-2.0
 ---
 
 # Brainstorm
@@ -42,18 +43,6 @@ brainstorm "explore liveness under partial synchrony"
 - `reaper-workspace/papers/` — downloaded PDFs and per-paper notes
 - The optional context hint from the argument
 
-## Path Resolution Protocol
-
-This skill references files in sibling skills. **`{{REAPER_SKILL_DIR}}`** below is a template placeholder — **you MUST substitute it with the absolute install path of the `/reaper` skill before reading, or the read will fail.** Common install locations:
-
-- `~/.claude/skills/reaper/` (Claude Code)
-- `~/.cursor/skills/reaper/` (Cursor)
-- `~/.agents/skills/reaper/` (Codex CLI, Cline, Gemini CLI, Copilot, OpenCode, Warp, Goose, Replit — universal target)
-- `~/.continue/skills/reaper/` (Continue)
-- `~/.windsurf/skills/reaper/` (Windsurf)
-- `<repo-root>/skills/reaper/` (during repo development)
-
-**Sibling-skill dependency**: This skill assumes the full `/reaper` package was installed together (`npx skills add SebastianElvis/reaper`). Single-skill installs will fail to resolve sibling references.
 
 ## Process
 
@@ -71,7 +60,7 @@ Apply these techniques systematically. Not all will produce ideas every time —
 
 #### Gap-Finding (Qian: Fill in the Blank)
 
-Map the dimensions of existing work and find unexplored combinations. Consult `{{REAPER_SKILL_DIR}}/references/model.md` for the domain-appropriate gap-finding matrix dimensions. Which cells in this matrix are empty? Those are candidate hypotheses.
+Map the dimensions of existing work and find unexplored combinations. Consult `../reaper/references/model.md` for the domain-appropriate gap-finding matrix dimensions. Which cells in this matrix are empty? Those are candidate hypotheses.
 
 #### Problem Inversion (Hamming)
 
@@ -100,7 +89,7 @@ If a hypothesis has trended toward refutation over 3+ cycles (counterexample att
 
 ### 3. Screen Against Known Impossibilities
 
-For each candidate idea, check whether it contradicts a known impossibility or lower bound. Consult `{{REAPER_SKILL_DIR}}/references/impossibility-results.md` for the domain-relevant impossibility results and lower bounds.
+For each candidate idea, check whether it contradicts a known impossibility or lower bound. Consult `../reaper/references/impossibility-results.md` for the domain-relevant impossibility results and lower bounds.
 
 If a candidate contradicts a known impossibility:
 1. Flag it explicitly with a warning
@@ -109,7 +98,7 @@ If a candidate contradicts a known impossibility:
 
 ### 4. Prioritize (Hamming: Importance Filter)
 
-Not all ideas are equally worth investigating. Rank by consequence — ask: "If we resolved this idea, who would care and why?" Consult `{{REAPER_SKILL_DIR}}/references/model.md` for domain-specific examples of how to rank by importance.
+Not all ideas are equally worth investigating. Rank by consequence — ask: "If we resolved this idea, who would care and why?" Consult `../reaper/references/model.md` for domain-specific examples of how to rank by importance.
 
 ### 5. Write Output
 

diff --git a/skills/clarify-goal/SKILL.md b/skills/clarify-goal/SKILL.md
@@ -3,6 +3,7 @@ name: clarify-goal
 description: "Ask the user targeted clarifying questions about their research goal before the pipeline runs. Use when the research goal is vague, ambiguous, or missing key context (e.g., which sections to focus on, threat model assumptions, what 'broken' means). Works with or without a paper."
 user-invocable: true
 argument-hint: "\"<research-goal>\" [paper-path]"
+license: Apache-2.0
 ---
 
 # Clarify Goal

diff --git a/skills/critique/SKILL.md b/skills/critique/SKILL.md
@@ -3,6 +3,8 @@ name: critique
 description: "Provide critique on investigation results via human feedback, Codex consultation, or self-review. Can trigger additional investigation cycles for deepen/explore feedback. Use when iterating on research, requesting AI review, or providing human feedback."
 user-invocable: true
 argument-hint: "\"<feedback>\" | --codex | --self"
+license: Apache-2.0
+compatibility: "--codex mode requires an MCP-capable host with the codex-cli MCP server configured; --self and human-feedback modes have no extra requirements."
 ---
 
 # Critique
@@ -24,18 +26,6 @@ critique --codex
 critique --self
 ```
 
-## Path Resolution Protocol
-
-This skill references files in sibling skills. **`{{REAPER_SKILL_DIR}}`** below is a template placeholder — **you MUST substitute it with the absolute install path of the `/reaper` skill before reading, or the read will fail.** Common install locations:
-
-- `~/.claude/skills/reaper/` (Claude Code)
-- `~/.cursor/skills/reaper/` (Cursor)
-- `~/.agents/skills/reaper/` (Codex CLI, Cline, Gemini CLI, Copilot, OpenCode, Warp, Goose, Replit — universal target)
-- `~/.continue/skills/reaper/` (Continue)
-- `~/.windsurf/skills/reaper/` (Windsurf)
-- `<repo-root>/skills/reaper/` (during repo development)
-
-**Sibling-skill dependency**: This skill assumes the full `/reaper` package was installed together (`npx skills add SebastianElvis/reaper`). Single-skill installs will fail to resolve sibling references.
 
 ## Inputs
 
@@ -98,7 +88,7 @@ For **deepen** and **explore**, after completing the cycles, the orchestrator sh
 
 Consult an external AI (OpenAI Codex via MCP) for an independent second opinion on the current investigation state. This establishes an automated feedback loop where Codex plays **devil's advocate** or provides **alternative inspiration**.
 
-See `{{REAPER_SKILL_DIR}}/references/codex-consultation.md` (placeholder defined in the Path Resolution Protocol section above) for MCP setup, fallback behavior, session continuity, and context compression rules. The critique skill's Codex mode is the most thorough consultation — other skills have lighter-weight checkpoint consultations.
+See `../reaper/references/codex-consultation.md` for MCP setup, fallback behavior, session continuity, and context compression rules. The critique skill's Codex mode is the most thorough consultation — other skills have lighter-weight checkpoint consultations.
 
 ### Determining the Role
 

diff --git a/skills/formalize-problem/SKILL.md b/skills/formalize-problem/SKILL.md
@@ -3,6 +3,7 @@ name: formalize-problem
 description: "Formalize a research question into precise, testable hypotheses with model assumptions, core properties, and explicit success/failure conditions. Use when asked to formalize, define, or scope a research problem after paper analysis."
 user-invocable: true
 argument-hint: "<research-goal>"
+license: Apache-2.0
 ---
 
 # Formalize Problem
@@ -17,18 +18,6 @@ Invoke this skill by name with the research goal as a quoted string. On slash-co
 formalize-problem "determine if the security proof in Section 4 holds under asynchrony"
 ```
 
-## Path Resolution Protocol
-
-This skill references files in sibling skills. **`{{REAPER_SKILL_DIR}}`** below is a template placeholder — **you MUST substitute it with the absolute install path of the `/reaper` skill before reading, or the read will fail.** Common install locations:
-
-- `~/.claude/skills/reaper/` (Claude Code)
-- `~/.cursor/skills/reaper/` (Cursor)
-- `~/.agents/skills/reaper/` (Codex CLI, Cline, Gemini CLI, Copilot, OpenCode, Warp, Goose, Replit — universal target)
-- `~/.continue/skills/reaper/` (Continue)
-- `~/.windsurf/skills/reaper/` (Windsurf)
-- `<repo-root>/skills/reaper/` (during repo development)
-
-**Sibling-skill dependency**: This skill assumes the full `/reaper` package was installed together (`npx skills add SebastianElvis/reaper`). Single-skill installs will fail to resolve sibling references.
 
 ## Instructions
 
@@ -48,21 +37,21 @@ What exactly needs to be resolved? Be specific. "Is this protocol secure?" is to
 
 ### 3. Pin Down Model Assumptions (must be unambiguous before hypotheses)
 
-Pin down every dimension of the system/trust model. If any dimension is left vague, the investigation will produce ambiguous results. Consult `{{REAPER_SKILL_DIR}}/references/model.md` for the domain-appropriate checklist of dimensions that must be specified. Every field must have a concrete answer, not "TBD".
+Pin down every dimension of the system/trust model. If any dimension is left vague, the investigation will produce ambiguous results. Consult `../reaper/references/model.md` for the domain-appropriate checklist of dimensions that must be specified. Every field must have a concrete answer, not "TBD".
 
 Every hypothesis must reference these model assumptions by specifying which parameters it holds under. A hypothesis that states a claim without pinning every relevant dimension is rejected.
 
 ### 4. Apply Importance Filter (Hamming)
 
-Not all questions are equally worth investigating. Prioritize by consequence — ask: "If we resolved this question, who would care and why?" Consult `{{REAPER_SKILL_DIR}}/references/model.md` for domain-specific examples of how to rank by importance.
+Not all questions are equally worth investigating. Prioritize by consequence — ask: "If we resolved this question, who would care and why?" Consult `../reaper/references/model.md` for domain-specific examples of how to rank by importance.
 
 ### 5. Apply Gap-Finding (Qian)
 
-Map the dimensions of existing work and find unexplored combinations. Consult `{{REAPER_SKILL_DIR}}/references/model.md` for the domain-appropriate gap-finding matrix dimensions. Which cells in this matrix are empty? Those are candidate hypotheses.
+Map the dimensions of existing work and find unexplored combinations. Consult `../reaper/references/model.md` for the domain-appropriate gap-finding matrix dimensions. Which cells in this matrix are empty? Those are candidate hypotheses.
 
 ### 6. Screen Against Known Impossibilities
 
-For each hypothesis, check whether it contradicts a known impossibility or lower bound. Consult `{{REAPER_SKILL_DIR}}/references/impossibility-results.md` for the domain-relevant impossibility results and lower bounds.
+For each hypothesis, check whether it contradicts a known impossibility or lower bound. Consult `../reaper/references/impossibility-results.md` for the domain-relevant impossibility results and lower bounds.
 
 If a hypothesis asks to prove something that an impossibility result rules out:
 1. **Flag it explicitly** in the hypothesis with a warning
@@ -71,7 +60,7 @@ If a hypothesis asks to prove something that an impossibility result rules out:
 
 ### 7. Enforce Definitional Hygiene
 
-Each core property listed in the output must be stated precisely. Consult `{{REAPER_SKILL_DIR}}/references/definitional-standards.md` for the domain-appropriate acceptable definition forms. Informal or ambiguous terms without formal definitions are NOT acceptable — different papers define the same terms differently, so pin it down. If the paper under analysis uses informal definitions, formalize them explicitly and note that you are doing so.
+Each core property listed in the output must be stated precisely. Consult `../reaper/references/definitional-standards.md` for the domain-appropriate acceptable definition forms. Informal or ambiguous terms without formal definitions are NOT acceptable — different papers define the same terms differently, so pin it down. If the paper under analysis uses informal definitions, formalize them explicitly and note that you are doing so.
 
 ### 8. Write Output
 
@@ -84,7 +73,7 @@ Write to `reaper-workspace/notes/problem-statement.md`:
 [Restate the goal precisely]
 
 ## Model Assumptions
-[One field per dimension from `{{REAPER_SKILL_DIR}}/references/model.md`. Every dimension must have a concrete answer.]
+[One field per dimension from `../reaper/references/model.md`. Every dimension must have a concrete answer.]
 
 ## Security Properties Under Investigation
 [What must hold? List each property with its formal definition or reference.]