From 13742f241526742873fb46d4398dd0ec429836be Mon Sep 17 00:00:00 2001 From: Paul Gebheim <86010+pgebheim@users.noreply.github.com> Date: Sun, 9 Aug 2026 15:15:14 +0000 Subject: [PATCH] fix(install): deliver agents-md skills to .agents/skills/ so agents find them MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The agents-md target flattened each skill to `.rig/skills/.md` and leaned on a generated `## Rig` index in AGENTS.md telling the agent to "read `.rig/skills/.md` and follow it". Nothing actually looks there. Codex, Pi, Cursor, Gemini CLI, Copilot and Rovo Dev all discover skills from `.agents/skills//SKILL.md` — scanning cwd -> parents -> repo root -> $HOME -> system — and auto-invoke on each skill's frontmatter description. Skills delivered by this target were invisible to the agents it exists for. Copy the whole skill directory to `.agents/skills//` instead. The kit's `skills//` dirs are already in exactly that shape, so this mirrors the claude-code adapter with a different root. `.rig/` keeps the pieces the standard doesn't cover — `config.json`, `agents/`, `scripts/`, `REVIEWER.md` — so there's still one rig home for non-skill content, and `review.patternsFile` still defaults to `.rig/REVIEWER.md` here. The AGENTS.md block shrinks to a pointer. Enumerating skills was redundant once they're self-discovered, and the "read this file" instruction was wrong; the block now names `.rig/config.json` and the persona-adoption rule for subagent-less agents. `.agents/` joins the detection markers for the target. The `agents-md` target name is unchanged — it's a public `--target` value and still writes AGENTS.md, just a smaller block. claude-code delivery untouched. Upgrading an install from the old layout: re-running delivers to the new location and rewrites the marker-delimited AGENTS.md block, but leaves the now-dead `.rig/skills/*.md` in place — install.sh is additive-only and can't get consent to delete. rig-onboard detects the legacy layout, reports it in its summary, and offers to remove it with confirmation. Partially reverses the skills half of #63; agents/scripts/config stay put. Verified: `install.sh --target agents-md` into a temp repo writes `.agents/skills/rig-review/SKILL.md`, leaves `.rig/{agents,scripts,REVIEWER.md, config.json}` as before, injects the trimmed block with no per-skill listing, and is idempotent on re-run (one marker pair, nothing clobbered). `bun test scripts/` — 39 pass. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_014oVJgHRkCkeCiayKUJ4iSg --- README.md | 4 +-- install.sh | 40 ++++++++++++------------- skills/rig-onboard/SKILL.md | 59 ++++++++++++++++++++++++++----------- 3 files changed, 62 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index fe1b44e..bde0ca9 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ read at runtime from a small **project profile** you fill in during onboarding. | Layer | Contents | How it's delivered | |---|---|---| -| **Skills** (`skills/`) | `rig-doctor`, `rig-debug`, `rig-spike`, `rig-tidy`, `rig-issue`, `rig-worktree`, `rig-review` (`find`/`fix`), `rig-plan`, `rig-task`, `rig-sprint`, `rig-epic` | Copied into `/.claude/skills/` | +| **Skills** (`skills/`) | `rig-doctor`, `rig-debug`, `rig-spike`, `rig-tidy`, `rig-issue`, `rig-worktree`, `rig-review` (`find`/`fix`), `rig-plan`, `rig-task`, `rig-sprint`, `rig-epic` | Copied into `/.claude/skills/` (or `.agents/skills/` for non-Claude agents — see "Works with your agent" below) | | **Agents** (`agents/`) | `rig-debugger`, `rig-reviewer`, `rig-architect`, `rig-qa`, `rig-coder` | Copied into `/.claude/agents/` | | **Support docs** (`templates/`) | starter `REVIEWER.md` (+ `REVIEWER.scope-template.md`), `label-mapping.md` | Copied into `/.claude/` (only if absent) | | **Scripts** (`scripts/`) | `setup-worktree.sh`, `remove-worktree.sh`, `mint-gh-app-token.sh`, `scope-reviewer.ts`, `set-session-name.sh` (Claude-only) | Copied into `/.claude/scripts/` | @@ -26,7 +26,7 @@ your agent's own conventions via **targets** (auto-detected from repo markers): | Target | Delivered as | Covers | |---|---|---| | **`claude-code`** | `.claude/skills//`, `.claude/agents/`, `.claude/scripts/` (native skills + subagents) | Claude Code | -| **`agents-md`** | a neutral `.rig/` dir (alongside the shared config profile) + an idempotent `## Rig` index injected into `AGENTS.md` ("read `.rig/skills/.md` and follow it") | Codex, Cursor, Gemini, Amp, Zed, Jules — any `AGENTS.md`-reading agent | +| **`agents-md`** | `.agents/skills//` — the standard cross-agent Agent Skills layout, auto-discovered natively (no index needed) — plus `.rig/agents/`, `.rig/scripts/`, `.rig/REVIEWER.md` for the pieces the standard doesn't cover, and a minimal `## Rig` pointer block injected into `AGENTS.md` (config + persona adoption) | Codex, Cursor, Gemini CLI, Copilot, Rovo Dev — any agent that scans `.agents/skills/` or reads `AGENTS.md` | For agents without subagents, the `.rig/agents/` personas are adopted **inline** rather than delegated — the skills reference roles through the `agents.*` diff --git a/install.sh b/install.sh index 9870ad7..a08c8d4 100644 --- a/install.sh +++ b/install.sh @@ -13,10 +13,14 @@ # # Targets (adapters): # claude-code -> .claude/skills//, .claude/agents/, .claude/scripts/ -# agents-md -> .rig/skills/.md + .rig/agents/ + .rig/scripts/, and an -# idempotent "## Rig" index injected into AGENTS.md. Works for -# any AGENTS.md-reading agent (Codex, Cursor, Gemini, Amp, -# Zed, Jules, ...). +# agents-md -> .agents/skills// (the cross-agent Agent Skills +# standard, auto-discovered natively by Codex, Cursor, +# Gemini CLI, Copilot, Rovo Dev, ...), plus .rig/agents/, +# .rig/scripts/, .rig/REVIEWER.md for the pieces the +# standard doesn't cover, and a minimal idempotent "## Rig" +# pointer block injected into AGENTS.md (config profile + +# persona-adoption note - no per-skill listing, since +# .agents/skills/ is self-discovered). # # With no --target, the target agent(s) are auto-detected from repo markers # (falling back to claude-code). Repeat/comma-separate to install several. @@ -64,8 +68,9 @@ fi detect_targets() { local found=() if [[ -d "$TARGET/.claude" || -f "$TARGET/CLAUDE.md" ]]; then found+=(claude-code); fi - if [[ -f "$TARGET/AGENTS.md" || -d "$TARGET/.cursor" || -f "$TARGET/.github/copilot-instructions.md" \ - || -f "$TARGET/GEMINI.md" || -d "$TARGET/.windsurf" ]]; then found+=(agents-md); fi + if [[ -f "$TARGET/AGENTS.md" || -d "$TARGET/.agents" || -d "$TARGET/.cursor" \ + || -f "$TARGET/.github/copilot-instructions.md" || -f "$TARGET/GEMINI.md" \ + || -d "$TARGET/.windsurf" ]]; then found+=(agents-md); fi if [[ ${#found[@]} -eq 0 ]]; then found=(claude-code); fi # safe default printf '%s\n' "${found[@]}" } @@ -125,15 +130,10 @@ install_claude_code() { } # --- Adapter: agents-md (universal) ------------------------------------------ -skill_desc() { # extract the frontmatter description of a skill, unquoted - grep -m1 '^description:' "$RIG_DIR/skills/$1/SKILL.md" 2>/dev/null \ - | sed -E 's/^description:[[:space:]]*//; s/^"//; s/"[[:space:]]*$//' || true -} - install_agents_md() { - echo "[agents-md] skills -> .rig/skills/*.md" + echo "[agents-md] skills -> .agents/skills// (cross-agent Agent Skills standard)" for s in "${SKILLS[@]}"; do - if [[ -f "$RIG_DIR/skills/$s/SKILL.md" ]]; then copy_no_clobber "$RIG_DIR/skills/$s/SKILL.md" "$TARGET/.rig/skills/$s.md" + if [[ -d "$RIG_DIR/skills/$s" ]]; then copy_no_clobber "$RIG_DIR/skills/$s" "$TARGET/.agents/skills/$s" else echo " unknown skill: $s" >&2; fi done echo "[agents-md] agents -> .rig/agents/, scripts -> .rig/scripts/" @@ -153,15 +153,13 @@ install_agents_md() { block="$( echo "## Rig" echo - echo "This project uses [Rig](https://github.com/agent-rig/rig) skills — self-contained" - echo "markdown procedures. **When a request matches a skill's triggers, read that" - echo "file and follow it.** Project config lives in \`.rig/config.json\`." + echo "This project uses [Rig](https://github.com/agent-rig/rig) skills, delivered as" + echo "standard Agent Skills under \`.agents/skills/\` — your agent discovers and" + echo "invokes them automatically from each skill's trigger description; nothing to" + echo "do here to use them." echo - for s in "${SKILLS[@]}"; do - [[ -f "$RIG_DIR/skills/$s/SKILL.md" ]] || continue - echo "- **$s** — $(skill_desc "$s")" - echo " → read \`.rig/skills/$s.md\` and follow it." - done + echo "Project config lives in \`.rig/config.json\` — read it for the test command," + echo "base branch, tracker, and review-bot settings before running any skill." echo echo "**Roles/subagents:** personas live in \`.rig/agents/\` (rig-reviewer, rig-coder," echo "rig-architect, rig-qa, rig-debugger). If your agent supports subagents," diff --git a/skills/rig-onboard/SKILL.md b/skills/rig-onboard/SKILL.md index 91ccdf8..4f972a2 100644 --- a/skills/rig-onboard/SKILL.md +++ b/skills/rig-onboard/SKILL.md @@ -62,13 +62,19 @@ Read, don't ask. Gather: from repo markers to delivery **targets** (may be more than one): - `.claude/` or `CLAUDE.md` → **`claude-code`** (native: `.claude/skills/`, `.claude/agents/`). - - `AGENTS.md`, `.cursor/`, `.github/copilot-instructions.md`, `GEMINI.md`, or - `.windsurf/` → **`agents-md`** (universal: skills/agents/scripts under the - neutral `.rig/` dir — the same home as the config profile — plus a `## Rig` - index injected into `AGENTS.md`; works for Codex, Cursor, Gemini, Amp, Zed, - Jules…). If none detected, default to `claude-code`; if unsure, ask. -- **Existing `.claude/`**: note any skills/agents already present so you can warn - before overwriting. + - `AGENTS.md`, `.agents/`, `.cursor/`, `.github/copilot-instructions.md`, + `GEMINI.md`, or `.windsurf/` → **`agents-md`** (universal: skills land in + `.agents/skills//` — the standard cross-agent "Agent Skills" layout + that Codex, Cursor, Gemini CLI, Copilot, and Rovo Dev auto-discover + natively, so no per-skill index file is needed; agents/scripts/review + patterns stay under `.rig/`, the same home as the config profile, since + nothing else standardizes those; plus a minimal `## Rig` pointer block + injected into `AGENTS.md`). If none detected, default to `claude-code`; if + unsure, ask. +- **Existing `.claude/` or `.agents/skills/`**: note any skills/agents already + present so you can warn before overwriting. Also check for a legacy + `.rig/skills/*.md` flat-file layout from a pre-`.agents/skills/` onboarding — + see "Re-running" below. Summarize what you found in a short table before moving on. @@ -120,17 +126,23 @@ skill/agent/catalog without diff-and-confirm. `/.claude/agents/`; `RIG_DIR/scripts/*` → `/.claude/scripts/` (`chmod +x`); and starter `REVIEWER.md` / `label-mapping.md` → `/.claude/` **only if absent**. -- **`agents-md`:** the payload lives under `.rig/` — the same dir as the shared - config profile, so there's one rig home (not a `rig/`-vs-`.rig/` pair). Copy - each chosen skill's `SKILL.md` → `/.rig/skills/.md`; agents → - `/.rig/agents/`; scripts → `/.rig/scripts/`; starter docs → - `/.rig/` (if absent). Then inject an idempotent `## Rig` section into - `/AGENTS.md` (between `` / `` - markers — replace any existing block, don't duplicate) that lists each - installed skill with its one-line description and trigger phrases and says - "read `.rig/skills/.md` and follow it", plus a note that subagent-less - agents should adopt the `.rig/agents/` personas inline. Set - `review.patternsFile` in the profile to `.rig/REVIEWER.md` for this target. +- **`agents-md`:** skills are delivered as full directories — copy each chosen + `RIG_DIR/skills//` → `/.agents/skills//` (same shape as + the `claude-code` copy, just a different root). This is the location the + target agent already scans on its own, so **no per-skill index or "read and + follow" pointer is written** — the agent auto-discovers each skill from its + `SKILL.md` frontmatter `description`. Everything the standard doesn't cover + keeps living under `.rig/` (the same dir as the shared config profile, so + there's still one rig home for non-skill pieces): agents → + `/.rig/agents/`; scripts → `/.rig/scripts/`; starter docs + (`REVIEWER.md`, `label-mapping.md`) → `/.rig/` (if absent). Then + inject/refresh an idempotent `## Rig` section into `/AGENTS.md` + (between `` / `` markers — replace any + existing block, don't duplicate). Keep this block short: a pointer to + `.rig/config.json` for project settings, and a note that subagent-less + agents should adopt the `.rig/agents/` personas inline — it no longer + enumerates skills. Set `review.patternsFile` in the profile to + `.rig/REVIEWER.md` for this target. ## 5. Offer CI (optional, gated on consent) @@ -157,3 +169,14 @@ secrets setup you can't do for them). See `ci/README.md#review-bot-bundle`. Onboarding is idempotent-ish: re-running detects the existing `.rig/config.json`, offers to update it, and only copies pieces that are missing or that the user explicitly asks to refresh. Use it to pull kit updates. + +Projects onboarded before this change may still have the old flat +`.rig/skills/.md` files and a `## Rig` block that lists them by name. +Re-running onboarding delivers skills into `.agents/skills//` and +replaces the `## Rig` block (it's idempotent between the markers), but it will +**not** delete the old `.rig/skills/*.md` files on its own — `copy_no_clobber` +and the rest of the install path only ever add files, never remove them. Point +this out in your Step 1 summary and Step 6 wrap-up, and — because you're +interactive and a human is present to confirm — offer to delete the now-dead +`.rig/skills/` directory for them. Don't delete it silently, and don't do this +from `install.sh` (non-interactive, no consent to delete).