Make skills repo agent-agnostic

README.md

@@ -1,58 +1,143 @@
-# pi skills (shared)
+# skills
 
-Shared pi skills and extensions used by the team. Add this repo as a local package in pi to load them.
+A shared collection of skills and extensions for AI coding agents.
 
 ## What's included
 
 ### Skills
 
-- `buildkite-cli` — use the local `bkci` CLI for LLM-friendly Buildkite JSON (builds, logs, artifacts, auth scopes).
-- `buildkite-mcp` *(deprecated)* — legacy mcporter/mcp-remote Buildkite access kept for compatibility.
-- `buildkite-playwright-failures` — extract failed-only Playwright tests from Buildkite logs.
-- `gh-address-comments` — fetch PR review comments, apply fixes with build verification, and commit each fix atomically. *(Derived from [skills.sh](https://skills.sh/openai/skills/gh-address-comments), Apache 2.0)*
-- `github` — use the `gh` CLI for issues, PRs, and runs.
-- `github-repo-search` — search any repo via `gh search` and deep-read files via the GitHub API without cloning.
-- `multi-review` — multi-model PR review workflow.
-- `tmux` — drive tmux sessions for interactive tools.
+Skills are agent-agnostic markdown instructions compatible with any AI coding agent that supports loading markdown context. See [Setup](#setup) for how to wire them up.
+
+- [`buildkite-cli`](skills/buildkite-cli/) — use the local `bkci` CLI for LLM-friendly Buildkite JSON (builds, logs, artifacts, auth scopes).
+- [`buildkite-mcp`](skills/buildkite-mcp/) *(deprecated)* — legacy mcporter/mcp-remote Buildkite access kept for compatibility.
+- [`buildkite-playwright-failures`](skills/buildkite-playwright-failures/) — extract failed-only Playwright tests from Buildkite logs.
+- [`gh-address-comments`](skills/gh-address-comments/) — fetch PR review comments, apply fixes with build verification, and commit each fix atomically. *(Derived from [skills.sh](https://skills.sh/openai/skills/gh-address-comments), Apache 2.0)*
+- [`github`](skills/github/) — use the `gh` CLI for issues, PRs, and runs.
+- [`github-repo-search`](skills/github-repo-search/) — search any repo via `gh search` and deep-read files via the GitHub API without cloning.
+- [`multi-review`](skills/multi-review/) — multi-model PR review workflow.
+- [`tmux`](skills/tmux/) — drive tmux sessions for interactive tools.
 
 ### Extensions
 
-- `buildkite-failures` — `/bk-playwright-errors <url>` shows a selectable list of failing Playwright tests and opens the Buildkite job in a browser.
-- `cronjob` — `/cron` command for scheduled prompts (cron expressions), optional job names, and queued runs while busy.
-- `loop` — `/loop` command that keeps a follow-up loop running until a breakout condition is met.
-- `notify` — desktop notification when the agent finishes and waits for input.
-- `start-design-plan` — Claude-style design workflow extension with `/start-design-plan` and `/resume-design-plan`, plus `ask_user_question` and `design_plan_tracker` tools. Ported from concepts in `ed3d-plan-and-execute` (`https://github.com/ed3dai/ed3d-plugins`). Extension-specific license in `extensions/start-design-plan/LICENSE`.
-- `pi-skills-update-checker` — checks for new commits on startup and shows a widget when updates are available.
+Extensions are TypeScript plugins that run inside **pi** only and are not compatible with other agents.
+
+- [`buildkite-failures`](extensions/buildkite-failures.ts) — `/bk-playwright-errors <url>` shows a selectable list of failing Playwright tests and opens the Buildkite job in a browser.
+- [`cronjob`](extensions/cronjob.ts) — `/cron` command for scheduled prompts (cron expressions), optional job names, and queued runs while busy.
+- [`loop`](extensions/loop.ts) — `/loop` command that keeps a follow-up loop running until a breakout condition is met.
+- [`notify`](extensions/notify.ts) — desktop notification when the agent finishes and waits for input.
+- [`start-design-plan`](extensions/start-design-plan/) — Claude-style design workflow with `/start-design-plan` and `/resume-design-plan`, plus `ask_user_question` and `design_plan_tracker` tools. Ported from concepts in `ed3d-plan-and-execute` (`https://github.com/ed3dai/ed3d-plugins`). Extension-specific license in `extensions/start-design-plan/LICENSE`.
+- [`pi-skills-update-checker`](extensions/pi-skills-update-checker.ts) — checks for new commits on startup and shows a widget when updates are available.
+
+## Setup — Skills (with Claude, Codex, etc)
+
+Skills are standalone markdown files. Clone the repo once, then wire individual skills into your agent.
+
+### 1. Clone the repo
+
+```bash
+git clone https://github.com/PSPDFKit-labs/pi-skills ~/dev/skills
+```
+
+Keep it somewhere stable — your symlinks and references will point here. To update:
+
+```bash
+cd ~/dev/skills && git pull
+```
+
+### 2. Wire up your agent
+
+#### Slash commands — Claude Code, Cursor, Windsurf
+
+Symlink individual skills into your agent's commands directory so updates are picked up automatically:
+
+```bash
+# Claude Code
+mkdir -p .claude/commands
+ln -s ~/dev/skills/skills/github/SKILL.md .claude/commands/github.md
+ln -s ~/dev/skills/skills/multi-review/SKILL.md .claude/commands/multi-review.md
+
+# Cursor / Windsurf (adjust path to match your agent)
+mkdir -p .cursor/rules
+ln -s ~/dev/skills/skills/github/SKILL.md .cursor/rules/github.md
+```
+
+#### Skills directory — Codex and others
+
+Agents that scan a skills directory (e.g. Codex reads `.agents/skills/`) can use a single symlink for all skills:
+
+```bash
+# Codex
+ln -s ~/dev/skills/skills .agents/skills
+
+# Claude Code also supports a skills folder
+ln -s ~/dev/skills/skills .claude/skills
+```
+
+#### Context / memory files — Claude Code
+
+Claude Code supports `@path` imports in `CLAUDE.md` to pull in skill content at startup:
+
+```markdown
+<!-- in CLAUDE.md -->
+@~/dev/skills/skills/github/SKILL.md
+@~/dev/skills/skills/multi-review/SKILL.md
+```
+
+For other agents (e.g. Codex's `AGENTS.md`), paste the skill content directly or use the skills directory approach above.
+
+#### Direct prompt reference
+
+For one-off use, just tell your agent where to find the skill:
+
+```
+Follow the instructions in ~/dev/skills/skills/multi-review/SKILL.md
+```
+
+---
+
+## Setup — pi (skills + extensions)
 
-## Usage
+[pi](https://pi.dev/) ([repository](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent)) has native package support for this repo. Unlike other agents, pi loads both skills (as slash commands) and extensions (as hooks and tools registered on session start).
+
+### Install
 
 Install as a project-local package (writes `.pi/settings.json`):
 
 ```bash
-pi install -l /absolute/path/to/pi-skills-nutrient
+pi install -l ~/dev/skills
 ```
 
-Install directly from GitHub:
+Or directly from GitHub without cloning first:
 
 ```bash
 pi install -l https://github.com/PSPDFKit-labs/pi-skills
 ```
 
-Or add it manually:
+Or add manually to `.pi/settings.json`:
 
 ```json
 {
   "packages": [
-    "/path/to/pi-skills-nutrient"
+    "/absolute/path/to/pi-skills"
   ]
 }
 ```
 
-After pulling updates, run `/reload` in pi to reload extensions, skills, and prompts.
+### Update
+
+Pull the repo, then reload inside pi to pick up changes without restarting:
+
+```bash
+cd ~/dev/skills && git pull
+```
+
+```
+/reload
+```
 
 ## Layout
 
-- `skills/` — each skill lives in its own folder with a `SKILL.md`.
+- `skills/` — each skill in its own folder with a `SKILL.md`.
 - `extensions/` — TypeScript extensions loaded by pi.
 
 ## Adding content

skills/multi-review/SKILL.md

@@ -1,17 +1,17 @@
 ---
 name: multi-review
-description: Multi-model code review. Runs code-review skill with 2 models in parallel, then synthesizes findings.
+description: Multi-model code review. Runs 2 sub-agent reviews in parallel, then synthesizes findings with active validation.
 ---
 
 # Multi Review
 
-Runs the `code-review` skill with 2 different models in parallel, then synthesizes with **active validation**.
+Runs 2 sub-agent reviews with different models in parallel, then synthesizes with **active validation**.
 
 ## Process
 
 ### Phase 1: Gather Reviews
 
-1. **Create a unique temp dir + get the PR diff** (same as code-review)
+1. **Create a unique temp dir + get the PR diff**
    ```bash
    # Unique temp dir for this run
    TMP_DIR="$(mktemp -d -t multi-review.XXXXXX)"
@@ -22,11 +22,11 @@ Runs the `code-review` skill with 2 different models in parallel, then synthesiz
    ```
 
 2. **Run 2 parallel reviews via bash**
-   ```bash
-   pi -p --model claude-opus-4-6 "Read and follow ~/dev/pi-skills/code-review/SKILL.md to review the PR. Diff is at $PR_DIFF" > "$TMP_DIR/review-opus.md" &
-   pi -p --model gpt-5.3-codex --provider openai-codex "Read and follow ~/dev/pi-skills/code-review/SKILL.md to review the PR. Diff is at $PR_DIFF" > "$TMP_DIR/review-codex.md" &
-   wait
-   ```
+
+   Use your agent CLI to spawn two sub-agents with different models. The review prompt for each:
+   > "Review the PR diff at `$PR_DIFF` thoroughly. Look for bugs, security issues, performance problems, incorrect logic, and code quality issues. Output a detailed markdown report of your findings."
+
+   Run them in parallel and write each result to a separate file, e.g. `$TMP_DIR/review-model-a.md` and `$TMP_DIR/review-model-b.md`, then `wait` for both to finish.
 
 ### Phase 2: Active Validation (IMPORTANT)
 
@@ -104,7 +104,7 @@ Runs the `code-review` skill with 2 different models in parallel, then synthesiz
 Each issue should include:
 - **File**: path/to/file.ext#L10-L15
 - **Status**: ✅ Confirmed | ⚠️ Needs verification | ❌ False positive
-- **Found by**: Opus / Codex / PR feedback
+- **Found by**: Model A / Model B / PR feedback
 - **Description**: What's wrong and why it matters
 - **Suggestion**: How to fix (if applicable)
 
@@ -115,8 +115,8 @@ Each issue should include:
 [Things all models may have missed - especially check PR description claims]
 
 ## 📊 Model Coverage
-| Issue | Opus | Codex | PR | Status |
-|-------|:----:|:-----:|:--:|--------|
+| Issue | Model A | Model B | PR | Status |
+|-------|:-------:|:-------:|:--:|--------|
 | Issue 1 | ✅ | ✅ | - | ✅ Confirmed |
 | Issue 2 | ❌ | ✅ | - | ✅ Confirmed |
 | Issue 3 | ✅ | ❌ | - | ❌ False positive |