From 099295ca9ba49693e4a679edc6bf3f4730466f86 Mon Sep 17 00:00:00 2001 From: Kasper Junge Date: Fri, 1 May 2026 08:32:46 +0200 Subject: [PATCH 1/2] feat: add agr-cli and improve-skill skills MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two new in-repo skills under skills/: - agr-cli: helps an agent operate the agr CLI on the user's behalf — set up new repos, install/sync/upgrade skills, manage agr.toml / agr.lock, and scaffold in-repo skills under skills/. Thin SKILL.md index pointing at 8 workflow-oriented references (setup, handles, installing-skills, syncing, in-repo-skills, configuration, running-skills, troubleshooting). - improve-skill: retrospective-driven loop for updating an existing skill based on session feedback. Listens, proposes, aligns, applies, commits, and runs `agr upgrade` to re-install. For remote skills, offers to file an issue upstream via `gh` or fork to in-repo. Both skills are self-contained — they call `agr` directly and have no hard dependency on each other or on agr-release. Co-Authored-By: Claude Opus 4.7 (1M context) --- skills/agr-cli/SKILL.md | 273 ++++++++++++++++++ skills/agr-cli/references/configuration.md | 189 ++++++++++++ skills/agr-cli/references/handles.md | 112 +++++++ skills/agr-cli/references/in-repo-skills.md | 180 ++++++++++++ .../agr-cli/references/installing-skills.md | 121 ++++++++ skills/agr-cli/references/running-skills.md | 116 ++++++++ skills/agr-cli/references/setup.md | 140 +++++++++ skills/agr-cli/references/syncing.md | 143 +++++++++ skills/agr-cli/references/troubleshooting.md | 186 ++++++++++++ skills/improve-skill/SKILL.md | 255 ++++++++++++++++ 10 files changed, 1715 insertions(+) create mode 100644 skills/agr-cli/SKILL.md create mode 100644 skills/agr-cli/references/configuration.md create mode 100644 skills/agr-cli/references/handles.md create mode 100644 skills/agr-cli/references/in-repo-skills.md create mode 100644 skills/agr-cli/references/installing-skills.md create mode 100644 skills/agr-cli/references/running-skills.md create mode 100644 skills/agr-cli/references/setup.md create mode 100644 skills/agr-cli/references/syncing.md create mode 100644 skills/agr-cli/references/troubleshooting.md create mode 100644 skills/improve-skill/SKILL.md diff --git a/skills/agr-cli/SKILL.md b/skills/agr-cli/SKILL.md new file mode 100644 index 0000000..c3e7af7 --- /dev/null +++ b/skills/agr-cli/SKILL.md @@ -0,0 +1,273 @@ +--- +name: agr-cli +description: > + Install, share, sync, and create AI agent skills across coding tools (Claude + Code, Cursor, Codex, OpenCode, Copilot, Antigravity) using the agr CLI. Use + whenever the user mentions agr, agr.toml, agr.lock, agrx, or asks to: add a + skill ("install the pdf skill", "agr add ..."), sync agent resources across + tools, share skills with their team, scaffold a new SKILL.md, run a skill + ephemerally (agrx), set up a repo to manage AI agent dependencies, or + configure tools/sources/instruction-syncing. Also use whenever an agr.toml + or agr.lock is present in the project and the user is doing + resource-management work. +--- + +# agr CLI + +agr is the package manager for AI agent skills. It installs, shares, and syncs +SKILL.md folders across Claude Code, Cursor, Codex, OpenCode, GitHub Copilot, +and Antigravity. This skill helps you operate the `agr` CLI on the user's +behalf — set up new repos, install and sync skills, manage `agr.toml` / +`agr.lock`, and scaffold in-repo skills under `skills/`. + +## When to use + +Use this skill when the user wants to: + +- Install or remove a remote skill (`agr add anthropics/skills/pdf`). +- Sync `agr.toml` after pulling teammates' changes (`agr sync`). +- Upgrade an installed skill past its pinned commit (`agr upgrade`). +- Run a skill once without persisting it (`agrx ...`) or invoke an installed one (`agr run`). +- Scaffold a new skill (`agr init my-skill`) — especially as in-repo skills under `skills/`. +- Set up a repo from scratch to use agr (multi-tool config, instruction syncing, sources). +- Add a local in-repo skill to the project's dependency list. +- Inspect, edit, or troubleshoot `agr.toml` / `agr.lock` / `agr config`. +- Or whenever `agr.toml` is present and the user is doing resource-management work. + +Do NOT use this skill for: + +- Authoring the *body* of a SKILL.md. This skill scaffolds and registers; for + writing effective skill instructions, defer to the user or to a dedicated + authoring skill such as `anthropics/skills/skill-creator`. +- Iterating on an existing skill based on session feedback or a retrospective. + That's a separate workflow — listen, propose, edit, commit, re-install. If + the user has a dedicated improvement skill installed (e.g. `improve-skill`), + use it; otherwise just do the workflow directly. + +## Prerequisites + +Before running anything, verify agr is installed: + +```bash +agr --version +``` + +If missing, the standard install is `uv tool install agr`. **Do not install agr +without checking with the user first** — they may prefer pipx, brew, or a +pinned version in CI. + +## Mental model — read first + +- A **skill** is a folder containing a `SKILL.md`. agr copies the whole folder + into each configured AI tool's skills directory (`.claude/skills/`, + `.cursor/skills/`, `.opencode/skills/`, `.agents/skills/`, etc.). +- A **handle** identifies a remote skill: `user/skill` (assumes a repo named + `skills`), `user/repo/skill` (any repo), or `./local/path` (on disk). +- `agr.toml` is the **manifest** (hand-edited or written by `agr add`). + `agr.lock` is the **lockfile** (auto-generated, pins commit SHAs and content + hashes — never edit by hand). +- **Project-local** vs **global** scope: every command takes `-g` to operate on + `~/.agr/agr.toml` and global tool dirs. +- `agr sync` only installs *missing* deps. To move past a pinned commit, use + `agr upgrade`. +- Resource types: **skill** (consumed by AI tools), **ralph** (autonomous + agent loop), **package** (a folder with its own `agr.toml`, expanded + transitively). `agr add` auto-detects the type. + +For the full conceptual model: [references/handles.md](references/handles.md). + +## Workflows + +### 1. Set up a new repo for agr + +When the user wants to start using agr in a project that has none configured: + +1. Run `agr init`. agr auto-detects which AI tools the repo uses + (`.claude/`, `CLAUDE.md`, `.cursor/`, `.cursorrules`, `.codex/`, `.opencode/`, + `.github/copilot-instructions.md`, `.gemini/`) and writes `agr.toml`. +2. Confirm or adjust the detected tools. For multi-tool: + `agr config set tools claude codex opencode`. +3. If the user maintains a canonical instruction file (e.g. `CLAUDE.md`) and + wants it mirrored to others (`AGENTS.md`, `GEMINI.md`), enable instruction + syncing: `agr config set sync_instructions true` then + `agr config set canonical_instructions CLAUDE.md`. +4. Commit `agr.toml`. (`agr.lock` will appear after the first `agr add` or + `agr sync` — commit it too.) + +Full details: [references/setup.md](references/setup.md). + +### 2. Install a skill + +```bash +agr add anthropics/skills/pdf +``` + +Notes: + +- Multi: `agr add user/skill1 user/skill2` (skills from the same repo are + batched into one download). +- `--overwrite` / `-o` to replace. +- `-g` for global (available in every project). +- `agr add` auto-creates `agr.toml` if missing — no need to `agr init` first. + +For handle formats and private repos: [references/handles.md](references/handles.md) +and [references/installing-skills.md](references/installing-skills.md). + +### 3. In-repo skills (the recommended workflow for skills shipping with the codebase) + +Place project-specific skills under `skills/` at the repo root (or at the root +of a relevant submodule). This keeps the skill in version control, reviewable +in PRs, and sharable across the team via `agr.toml`. + +```bash +agr init my-skill # scaffolds my-skill/SKILL.md in CWD +mkdir -p skills && mv my-skill skills/ +agr add ./skills/my-skill # records {path = "./skills/my-skill", type = "skill"} in agr.toml +``` + +Iterate: edit `skills/my-skill/SKILL.md`, then +`agr add ./skills/my-skill --overwrite` to reinstall into each configured tool. + +Teammates pick it up with `agr sync` after pulling. The local `path` dependency +travels with the repo, so contributors don't need network access to use it. + +For structuring (scripts/, references/, assets/), iteration patterns, and +testing with `agrx`: [references/in-repo-skills.md](references/in-repo-skills.md). + +### 4. Sync after pulling teammates' changes + +```bash +agr sync +``` + +This (1) syncs instruction files, (2) runs directory migrations, (3) installs +any deps missing for any tool, (4) refreshes `agr.lock`. + +CI flags: + +- `agr sync --frozen` — install exactly what `agr.lock` says; fail if lock is + missing or doesn't cover all deps. Use in deploy pipelines for byte-identical + installs. +- `agr sync --locked` — fail if `agr.lock` is stale vs `agr.toml`. Use in PR + checks to enforce lockfile hygiene. +- `--frozen` and `--locked` are mutually exclusive. + +Full lifecycle: [references/syncing.md](references/syncing.md). + +### 5. Upgrade past pinned commits + +`agr sync` only installs what is missing. To pull the latest upstream code for +a skill that is already installed, use `agr upgrade`: + +```bash +agr upgrade # everything in scope +agr upgrade pdf # short-name match (errors on ambiguity) +agr upgrade anthropics/skills/pdf # full handle +``` + +**Gotcha**: upgrading one skill from a multi-skill repo (e.g. +`anthropics/skills/pdf`) does NOT refresh siblings. Run `agr upgrade` with no +args, or name each sibling explicitly, to refresh the whole repo together. + +### 6. Run a skill + +```bash +agr run pdf # invoke installed skill in default tool +agr run pdf -- "summarise report.pdf" # extra prompt +agr run pdf -i # interactive +agr run pdf --tool cursor # override tool +agrx anthropics/skills/pdf -p "Extract" # ephemeral, no install +``` + +`agr run` requires the skill to be already installed. `agrx` downloads, runs, +and cleans up. Difference and tool-resolution rules: +[references/running-skills.md](references/running-skills.md). + +### 7. Configure agr + +Keys: `tools`, `default_tool`, `default_owner`, `default_source`, +`sync_instructions`, `canonical_instructions`, `sources`. + +```bash +agr config show +agr config set tools claude codex opencode +agr config add tools cursor +agr config remove tools cursor # ⚠ DELETES that tool's skills directory +``` + +Private repos / custom Git hosts: + +```bash +agr config add sources gitlab --url "https://gitlab.com/{owner}/{repo}.git" +export GITHUB_TOKEN="..." # auth for private GitHub repos +``` + +Add `-g` to operate on `~/.agr/agr.toml` instead of the project file. + +All keys with defaults: [references/configuration.md](references/configuration.md). + +### 8. List and inspect + +```bash +agr list # status of every dep: installed / partial / not synced / invalid +agr list -g # global skills +cat agr.toml # the manifest +cat agr.lock # the lockfile (READ ONLY) +``` + +`partial (claude, cursor)` means a skill is installed in some tools but not +others — `agr sync` to fan it out to the rest. + +## Boundaries + +- **Never edit `agr.lock` by hand.** It's regenerated by `agr add`/`agr sync`/ + `agr remove`/`agr upgrade`. If it looks wrong, run `agr sync` (or + `agr sync --locked` to confirm hygiene). +- **`agr config remove tools ` deletes that tool's skills directory.** + Confirm with the user before running it. The skills can be re-installed by + re-adding the tool. +- **Don't author the body of a new skill on the user's behalf** unless they + explicitly asked. This skill scaffolds and registers; SKILL.md content + authoring is a separate task. +- **Always confirm before `--overwrite`** on a skill the user has been editing + locally — overwriting will replace their working copy. +- **Don't install agr globally** without checking — the user may have a pinned + version, alternative install method, or CI constraints. +- **Don't push or `git tag`** as part of these workflows. Commit changes + locally; let the user push. + +## Troubleshooting pointers + +- "Skill not found" → check the handle format (2 vs 3 parts), see + [references/handles.md](references/handles.md). +- "agr.lock out of date" in CI → user added a dep but didn't commit the + lockfile; run `agr sync` locally and commit. +- `partial` install status → `agr sync` to fan out to all configured tools. +- Auth errors on private repos → check `GITHUB_TOKEN` is exported. +- Type errors after manually editing `agr.toml` → run `agr add` to let agr + rewrite the entry with the correct `type` field. + +Full list: [references/troubleshooting.md](references/troubleshooting.md). + +## References + +- [setup.md](references/setup.md) — repo bootstrap, multi-tool, instruction syncing +- [handles.md](references/handles.md) — handle formats, resolution, resource types, scopes +- [installing-skills.md](references/installing-skills.md) — `agr add` / `agr remove`, sources, private repos +- [syncing.md](references/syncing.md) — `agr sync` / `agr upgrade`, lockfile, CI patterns +- [in-repo-skills.md](references/in-repo-skills.md) — `skills/` workflow, scaffolding, iterating +- [configuration.md](references/configuration.md) — all `agr config` keys, sources, scopes +- [running-skills.md](references/running-skills.md) — `agr run` vs `agrx` +- [troubleshooting.md](references/troubleshooting.md) — common errors and fixes + +For the canonical CLI reference, point the user at +https://computerlovetech.github.io/agr/reference/ or run `agr --help`. + +## Related capabilities (separate skills if installed) + +- **Greenfield skill authoring** — scaffolding a brand-new SKILL.md from a + blank slate. Canonical option: `anthropics/skills/skill-creator`. +- **Retrospective-driven skill improvement** — listening to feedback after a + session and updating an existing skill. If the user has a dedicated + workflow skill for this, use it; otherwise the workflow is editing the + source under `skills//`, committing, and `agr upgrade `. diff --git a/skills/agr-cli/references/configuration.md b/skills/agr-cli/references/configuration.md new file mode 100644 index 0000000..7a1d01b --- /dev/null +++ b/skills/agr-cli/references/configuration.md @@ -0,0 +1,189 @@ +# Configuration — `agr config` and `agr.toml` + +The full surface for managing project (and global) configuration. + +## Subcommands + +```bash +agr config show # formatted view of current config +agr config path # print path to agr.toml +agr config edit # open in $VISUAL or $EDITOR +agr config get # read a value +agr config set # write scalar or replace list +agr config add # append to a list +agr config remove # remove from a list +agr config unset # clear to default +``` + +Add `-g` / `--global` to operate on `~/.agr/agr.toml` instead of `./agr.toml`. + +## All keys + +| Key | Type | Default | What it does | +|---|---|---|---| +| `tools` | list | `["claude"]` | AI tools to install skills into. Skills fan out to every tool listed; ralphs ignore this. | +| `default_tool` | string | first in `tools` | Tool used by `agrx` and as the canonical for instruction sync | +| `default_owner` | string | `computerlovetech` | GitHub owner for 1-part handles (`agr add setup` → `/skills/setup`) | +| `default_source` | string | `github` | Source used when `--source` is not specified | +| `sync_instructions` | bool | `false` | Mirror canonical instruction file to other tools on `agr sync` | +| `canonical_instructions` | string | derived from `default_tool` | Source of truth: `CLAUDE.md`, `AGENTS.md`, or `GEMINI.md` | +| `sources` | list | `[github]` | Git URL templates (see [Sources](#sources)) | + +## Common operations + +```bash +# Multi-tool +agr config set tools claude codex opencode +agr config add tools cursor +agr config remove tools cursor # ⚠ deletes that tool's skills/ + +# Default tool for agrx +agr config set default_tool claude + +# Custom owner +agr config set default_owner my-org + +# Instruction syncing +agr config set sync_instructions true +agr config set canonical_instructions CLAUDE.md +agr config unset sync_instructions # back to default (false) +``` + +## ⚠ `agr config remove tools ` deletes skills + +Removing a tool from `tools` also deletes that tool's skills directory +(`.cursor/skills/`, etc.). Skills remain in the *other* configured tools. +Re-adding the tool with `agr config add tools cursor` followed by `agr sync` +re-installs them. + +Always confirm with the user before running this command. + +## Sources + +A source is a Git URL template: + +```toml +[[source]] +name = "github" +type = "git" +url = "https://github.com/{owner}/{repo}.git" +``` + +`{owner}` and `{repo}` come from the handle. + +### Add a custom source + +```bash +agr config add sources gitlab \ + --url "https://gitlab.com/{owner}/{repo}.git" + +agr config add sources self-hosted \ + --url "https://git.internal.example.com/{owner}/{repo}.git" +``` + +`--type` defaults to `git` and is the only supported type today. + +### Use a non-default source + +Per-command: + +```bash +agr add team/internal-tool --source gitlab +``` + +Per-dep (in `agr.toml`): + +```toml +dependencies = [ + {handle = "team/internal-tool", type = "skill", source = "gitlab"}, +] +``` + +Switch the default: + +```bash +agr config set default_source gitlab +``` + +### Private repos + +Set the host's auth token before invoking agr: + +```bash +export GITHUB_TOKEN="ghp_..." +agr add my-org/private-skills/secret-skill +``` + +For GitLab, use `GITLAB_TOKEN`; for self-hosted Git, see your host's docs. + +## Instruction syncing + +When the user maintains a canonical instructions file (e.g. `CLAUDE.md`) and +wants the same content in the other tools' equivalents (`AGENTS.md`, +`GEMINI.md`), enable instruction syncing: + +```bash +agr config set sync_instructions true +agr config set canonical_instructions CLAUDE.md +``` + +Then `agr sync` copies the canonical file to the others. Mappings: + +| Tool | Instruction file | +|---|---| +| Claude Code | `CLAUDE.md` | +| Codex / OpenCode / Copilot | `AGENTS.md` | +| Antigravity / Gemini | `GEMINI.md` | + +Only fires when 2+ tools are configured. With one tool, it's a no-op. + +## Full agr.toml example + +```toml +default_source = "github" +default_owner = "my-org" +tools = ["claude", "codex", "opencode"] +default_tool = "claude" +sync_instructions = true +canonical_instructions = "CLAUDE.md" + +dependencies = [ + {handle = "anthropics/skills/pdf", type = "skill"}, + {handle = "anthropics/skills/frontend-design", type = "skill"}, + {path = "./skills/project-conventions", type = "skill"}, + {handle = "team/internal-tool", type = "skill", source = "gitlab"}, + {handle = "your-username/agent-resources/bug-hunter", type = "ralph"}, +] + +[[source]] +name = "github" +type = "git" +url = "https://github.com/{owner}/{repo}.git" + +[[source]] +name = "gitlab" +type = "git" +url = "https://gitlab.com/{owner}/{repo}.git" +``` + +Dependencies must come BEFORE any `[[source]]` blocks (TOML semantics). + +## Project vs global + +| Path | Used for | +|---|---| +| `./agr.toml` | Per-project deps, tools, sources. Committed to git. | +| `~/.agr/agr.toml` | User's global skills, available across all projects. | + +`-g` / `--global` on every config subcommand operates on the global file: + +```bash +agr config -g show +agr config -g set tools claude cursor +``` + +## See also + +- [setup.md](setup.md) — initial repo bootstrap +- [handles.md](handles.md) — handle formats and resolution +- [syncing.md](syncing.md) — what `agr sync` does with this config diff --git a/skills/agr-cli/references/handles.md b/skills/agr-cli/references/handles.md new file mode 100644 index 0000000..300c4bc --- /dev/null +++ b/skills/agr-cli/references/handles.md @@ -0,0 +1,112 @@ +# Handles, resources, and scopes + +agr identifies every resource by a **handle**. Get the handle format wrong and +nothing else works, so this is the page to consult first when an `agr add` +fails with "not found". + +## Handle formats + +| Form | Resolves to | When to use | +|---|---|---| +| `user/skill` | `github.com/user/skills` repo, `skill/` subdirectory | When the publisher follows the convention of putting all skills in a repo named `skills` | +| `user/repo/skill` | `github.com/user/repo` repo, `skill/` subdirectory | When the repo has a different name | +| `skill` (1-part) | `/skills/skill` | When `default_owner` is configured (defaults to `computerlovetech`) | +| `./path/to/skill` | Local directory | In-repo or scratch skills | + +**Examples:** + +```bash +agr add anthropics/skills/pdf # 3-part: anthropics, repo "skills", folder "pdf" +agr add anthropics/pdf # 2-part: same thing (assumes "skills" repo) +agr add vercel-labs/agent-browser/agent-browser # 3-part: repo isn't called "skills" +agr add ./skills/my-skill # local +``` + +When in doubt, ask the user for the GitHub URL and translate. + +## Resource types + +agr manages three resource types. Every dep entry in `agr.toml` carries a +`type` field that agr fills in automatically on `agr add`. + +| Type | Marker file | Installed to | Notes | +|---|---|---|---| +| `skill` | `SKILL.md` | Each configured tool's skills dir | The common case | +| `ralph` | `RALPH.md` | `.agents/ralphs//` (per project) | Autonomous agent loop, executed by a runtime like ralphify. Ignores the `tools` list. Project-scoped only — `-g` is rejected. | +| `package` | `agr.toml` (no marker file at top) | N/A — expanded transitively | A folder whose `agr.toml` lists more deps. Adding a package installs all its skills/ralphs and records the parent relationship in `agr.lock`. | + +`agr add` detects type automatically: + +- For local paths, from the marker file inside the directory. +- For remote handles, by searching the repo for a matching skill first, then + falling back to ralph. + +There is no `--type` flag — the `type` is recorded after a successful install. + +## Scopes + +Every `add` / `remove` / `sync` / `list` accepts `-g` / `--global`: + +| Scope | Manifest | Skills installed to | +|---|---|---| +| Project (default) | `./agr.toml` | `.claude/skills/`, `.cursor/skills/`, … in the repo | +| Global (`-g`) | `~/.agr/agr.toml` | `~/.claude/skills/`, `~/.cursor/skills/`, … | + +Global skills are available across every project on the machine. Useful for +personal productivity skills the user wants everywhere; not useful for +team-shared, project-specific skills. + +Ralphs are project-scoped only — `-g` is rejected for ralph deps. + +## Sources + +A **source** is a Git URL template. Default source is `github`: + +```toml +[[source]] +name = "github" +type = "git" +url = "https://github.com/{owner}/{repo}.git" +``` + +Add a custom source for GitLab, self-hosted, or mirrored Git: + +```bash +agr config add sources gitlab --url "https://gitlab.com/{owner}/{repo}.git" +agr add team/internal-tool --source gitlab +agr config set default_source gitlab # change the default +``` + +`{owner}` and `{repo}` are substituted from the handle. + +## Private repos + +Set `GITHUB_TOKEN` (or the equivalent for your source) before running agr: + +```bash +export GITHUB_TOKEN="ghp_..." +agr add my-org/private-skills/secret-skill +``` + +For CI, set the token as a secret. The token needs read access to the repo. + +## Pinning a single dep to a non-default source + +In `agr.toml`: + +```toml +dependencies = [ + {handle = "team/internal-tool", type = "skill", source = "gitlab"}, +] +``` + +Or via CLI: + +```bash +agr add team/internal-tool --source gitlab +``` + +## See also + +- [installing-skills.md](installing-skills.md) — `agr add` and `agr remove` in depth +- [configuration.md](configuration.md) — the full `agr config` surface diff --git a/skills/agr-cli/references/in-repo-skills.md b/skills/agr-cli/references/in-repo-skills.md new file mode 100644 index 0000000..2e9fbc9 --- /dev/null +++ b/skills/agr-cli/references/in-repo-skills.md @@ -0,0 +1,180 @@ +# In-repo skills — the recommended workflow + +Skills that ship with the codebase (project conventions, internal workflows, +domain-specific helpers) belong in version control alongside the code they +describe. The convention this skill encourages: keep them under `skills/` at +the repo root (or at the root of a relevant submodule) and install them as +local-path deps in `agr.toml`. + +This page covers scaffolding, structuring, iterating, and shipping in-repo +skills. + +## Why `skills/` at the repo root + +- **Reviewable in PRs.** Changes to skill content show up in code review. +- **No drift between tools.** One source of truth in `skills//`; agr + fans it out to every configured tool's skills dir. +- **Travels with the repo.** New contributors run `agr sync` and immediately + have the team's skills loaded into their AI tools. +- **Distinct from `.claude/skills/` etc.** Those are gitignored, generated, + and managed by agr. `skills/` is the source. + +For monorepos / repos with submodules, place a `skills/` dir at the root of +each submodule that has its own concerns. Each submodule maintains its own +`agr.toml` referencing its local-path skills. + +## Scaffold a new skill + +```bash +agr init my-skill +mkdir -p skills && mv my-skill skills/ +``` + +`agr init ` creates `/SKILL.md` in the current directory with a +starter template. Move it under `skills/` after. + +The starter template: + +```markdown +--- +name: my-skill +description: TODO — describe what this skill does and when to use it +--- + +# my-skill + +## When to use + +Describe when this skill should be used. + +## Instructions + +Provide detailed instructions here. +``` + +Edit `skills/my-skill/SKILL.md`: + +- **`name`** must match the directory name. 1–64 chars, lowercase, hyphens + allowed (no leading/trailing/consecutive `-`). +- **`description`** is the only trigger signal — make it pushy and specific. + List the user phrases / contexts that should fire it. + +For body authoring guidance, defer to the user or the official `skill-creator` +skill; this skill scaffolds and registers, but does not write skill content. + +## Register in agr.toml + +```bash +agr add ./skills/my-skill +``` + +Writes: + +```toml +dependencies = [ + {path = "./skills/my-skill", type = "skill"}, +] +``` + +And installs into `.claude/skills/my-skill/`, `.cursor/skills/my-skill/`, etc. +for every tool in `tools`. + +## Iterate + +Edit `skills/my-skill/SKILL.md`, then reinstall: + +```bash +agr add ./skills/my-skill --overwrite +``` + +Or just `agr sync` — but `--overwrite` is more explicit when you've made local +edits. + +To test ephemerally (no permanent install) on a path: + +```bash +agrx ./skills/my-skill -p "test prompt" +``` + +## Structure for complex skills + +Beyond a single SKILL.md: + +``` +skills/my-skill/ +├── SKILL.md # required — agent instructions, < 500 lines +├── references/ # docs the agent reads on demand +│ └── api-schema.md +├── scripts/ # deterministic shell-outs +│ └── validate.sh +└── assets/ # templates, fixtures + └── template.json +``` + +| Folder | Use when | +|---|---| +| `references/` | The agent needs background info that's too long for SKILL.md (style guides, schema dumps, decision matrices). Reference from SKILL.md as `[name](references/name.md)`. | +| `scripts/` | A workflow has more than 2 piped shell commands, or needs deterministic output (lint, codegen, validation). Avoids re-deriving the pipeline every run. | +| `assets/` | Templates, JSON fixtures, sample inputs. Things the skill emits or fills in. | + +Keep SKILL.md focused — under 500 lines. The body should be a thin index that +points into `references/` for depth. + +## Promote a remote skill to in-repo + +If the user wants to fork a remote skill and modify it locally: + +```bash +agr remove anthropics/skills/pdf +git clone --depth 1 https://github.com/anthropics/skills /tmp/skills-src +cp -r /tmp/skills-src/pdf skills/pdf +agr add ./skills/pdf +``` + +(Or download just the folder via `git sparse-checkout` if cloning the whole +repo is overkill.) + +Mention to the user that this forks the skill — they're now responsible for +keeping it up to date. Better to upstream improvements via PR if possible. + +## Sharing in-repo skills as a public package + +Once stable, other repos can install via remote handle: + +```bash +# In another project +agr add your-username/this-repo/my-skill +``` + +The 3-part handle works because the skill lives at `/my-skill/` +when downloaded — wait, no: the skill lives under `skills/my-skill/` here, +which means the remote handle is actually `your-username/this-repo/skills/my-skill`? + +Actually `agr add` searches the repo for any directory containing a SKILL.md +matching the requested name, so `your-username/this-repo/my-skill` works as +long as there's a `my-skill/` (under `skills/` or anywhere else) with a +SKILL.md inside. If you publish a dedicated skills repo named `skills`, the +short handle `your-username/my-skill` works. + +Two convenience layouts: + +- **Dedicated skills repo** (`your-username/skills`): one folder per skill at + the repo root → users install with 2-part handle `your-username/my-skill`. +- **Skills nested under a project repo** (`your-username/myproj/skills/foo`): + users install with 3-part handle `your-username/myproj/foo`. + +## Checklist when adding a new in-repo skill + +- [ ] Scaffolded with `agr init ` +- [ ] Moved to `skills//` +- [ ] `name` in frontmatter matches directory name +- [ ] `description` lists explicit trigger phrases / contexts +- [ ] Registered with `agr add ./skills/` +- [ ] Tested with `agrx ./skills/` or `agr run ` +- [ ] `agr.toml`, `agr.lock`, and `skills//` committed + +## See also + +- [installing-skills.md](installing-skills.md) — `agr add --overwrite` +- [running-skills.md](running-skills.md) — testing with `agr run` / `agrx` +- [setup.md](setup.md) — repo bootstrap diff --git a/skills/agr-cli/references/installing-skills.md b/skills/agr-cli/references/installing-skills.md new file mode 100644 index 0000000..90047a3 --- /dev/null +++ b/skills/agr-cli/references/installing-skills.md @@ -0,0 +1,121 @@ +# Installing and removing skills + +Day-to-day operations for `agr add` and `agr remove`. For canonical flag +listings: `agr add --help`. + +## agr add + +```bash +agr add ... +``` + +- Installs into every tool listed in `tools`. +- Auto-creates `agr.toml` if missing — no `agr init` first. +- Skills from the same repository are batched into one download. + +### Common patterns + +```bash +agr add anthropics/skills/pdf # remote skill +agr add anthropics/skills/pdf anthropics/skills/docx # multi +agr add ./skills/my-skill # local in-repo +agr add anthropics/skills/pdf --overwrite # replace existing +agr add anthropics/skills/pdf --source gitlab # use named source +agr add -g anthropics/skills/pdf # global (~/.claude/skills/, etc.) +``` + +### Flags + +| Flag | Effect | +|---|---| +| `--overwrite`, `-o` | Replace existing skills/ralphs | +| `--source`, `-s ` | Use a non-default source from `agr.toml` | +| `--global`, `-g` | Install globally; ralph deps are skipped under `-g` | + +### What `agr add` writes + +After a successful install, `agr add` adds a line to `agr.toml`: + +```toml +dependencies = [ + {handle = "anthropics/skills/pdf", type = "skill"}, +] +``` + +And writes the resolved commit + content hash into `agr.lock`. Both files +should be committed. + +### --overwrite gotcha + +`--overwrite` replaces the installed copy. If the user has been editing a +locally-installed in-repo skill (e.g. tweaking `.claude/skills/my-skill/` by +hand instead of editing `skills/my-skill/`), `--overwrite` will discard those +edits. Confirm with the user first if there's any chance of local mods. + +For in-repo skills, the workflow is: edit the source under `skills//`, +then `agr add ./skills/ --overwrite` to push it into each tool's skills +dir. + +## agr remove + +```bash +agr remove ... +``` + +- Deletes the skill from every tool's skills directory. +- Removes the entry from `agr.toml`. +- Refreshes `agr.lock`. + +### Common patterns + +```bash +agr remove anthropics/skills/pdf +agr remove ./skills/my-skill +agr remove -g anthropics/skills/pdf # remove from global +agr remove pdf docx # multi (short names work if unambiguous) +``` + +### Flags + +| Flag | Effect | +|---|---| +| `--global`, `-g` | Remove from `~/.agr/agr.toml` and global tool dirs | + +`agr remove` is destructive but reversible — the user can `agr add` again. +Still, confirm before running on shared/in-repo skills, since removing also +deletes the entry from `agr.toml` (the user may have intended to just +uninstall locally without touching the manifest, but agr does not support +that — you have to comment the dep out manually if needed). + +## Listing and inspecting + +```bash +agr list # everything in agr.toml + status +agr list -g # everything in ~/.agr/agr.toml +``` + +Status values: + +| Status | Meaning | +|---|---| +| `installed` | Present in all configured tools | +| `partial (claude, cursor)` | Installed in some tools but not all — `agr sync` to fix | +| `not synced` | In `agr.toml` but not on disk — `agr sync` | +| `invalid` | Handle in `agr.toml` cannot be parsed — fix the handle | + +## Troubleshooting installs + +- **"Repository not found"** — handle wrong or repo private. Check the handle + format ([handles.md](handles.md)) and whether `GITHUB_TOKEN` is set. +- **"Skill not found in repo"** — directory name in the handle is wrong. Look + at the GitHub repo to confirm the folder name. +- **Install succeeds but `agr list` shows `partial`** — a tool's directory + isn't writable, or migrations haven't run. Run `agr sync`. +- **`agr.lock` rejected by `--locked` in CI** — local user added a dep but + didn't commit the regenerated lock. Run `agr sync` locally and commit. + +## See also + +- [syncing.md](syncing.md) — `agr sync` and `agr upgrade` lifecycle +- [handles.md](handles.md) — handle formats and resolution +- [in-repo-skills.md](in-repo-skills.md) — local-path workflow diff --git a/skills/agr-cli/references/running-skills.md b/skills/agr-cli/references/running-skills.md new file mode 100644 index 0000000..525fd91 --- /dev/null +++ b/skills/agr-cli/references/running-skills.md @@ -0,0 +1,116 @@ +# Running skills — `agr run` vs `agrx` + +Two commands for invoking skills. They look similar; the difference matters. + +## `agr run` — invoke an already-installed skill + +```bash +agr run [-- ] +``` + +Looks up the skill in the configured tool's skills directory and shells out +to that tool's CLI with the skill prompt prefilled. No download, no cleanup, +no network — the skill must already be installed (via `agr add` or +`agr sync`). + +### Examples + +```bash +agr run pdf # default tool +agr run pdf -- "summarise report.pdf" # extra prompt after -- +agr run pdf -p "summarise report.pdf" # same, via -p +agr run pdf --tool cursor # override tool +agr run pdf -i # interactive session +agr run pdf -g # global skill +``` + +### Flags + +| Flag | Effect | +|---|---| +| `--tool`, `-t ` | Override `default_tool` | +| `--interactive`, `-i` | Open the tool in interactive mode with the skill prompt prefilled | +| `--prompt`, `-p ` | Append this prompt after the skill reference | +| `--global`, `-g` | Look up in `~/./skills/` instead of `././skills/` | + +Anything after `--` is appended to the prompt as free-form input, after `-p` +if both are passed. + +### Tool resolution order + +1. `--tool` flag +2. `default_tool` in `agr.toml` +3. First entry in `tools` +4. `claude` + +If the skill isn't installed in the chosen tool, `agr run` lists the tools' +available skills so you can correct the name or `agr sync` first. + +### Short-name matching + +`agr run pdf` works when one installed skill has the short name `pdf`. With +collisions, agr falls back to the qualified name like `user--repo--skill`; +match that or the full handle. + +## `agrx` — ephemeral skill runner + +```bash +agrx [options] +``` + +Downloads the skill, runs it via the selected tool's CLI, then cleans up. +Nothing is added to `agr.toml`, nothing persists in the project. + +### Examples + +```bash +agrx anthropics/skills/pdf +agrx anthropics/skills/pdf -p "Extract tables from report.pdf" +agrx anthropics/skills/skill-creator -i # interactive +agrx anthropics/skills/pdf --tool cursor +agrx vercel-labs/agent-browser/agent-browser --source github +agrx ./skills/my-skill -p "test" # local path works too +agrx -g anthropics/skills/pdf # install to global tool dir +``` + +### Flags + +| Flag | Effect | +|---|---| +| `--tool`, `-t ` | Tool CLI to use; defaults to `default_tool` from config | +| `--interactive`, `-i` | Run skill, then continue in interactive mode | +| `--prompt`, `-p ` | Pass a prompt to the skill | +| `--source`, `-s ` | Use a specific source from `agr.toml` | +| `--global`, `-g` | Install to global tool skills directory rather than the repo-local one | + +## When to use which + +| Need | Command | +|---|---| +| Skill is installed; just invoke it | `agr run` | +| Try a skill once without persisting | `agrx ` | +| Test an in-repo skill while iterating | `agrx ./skills/` | +| Skill not installed but you want it permanent | `agr add` first, then `agr run` | +| Quick demo / one-shot for a teammate | `agrx -p "..."` | + +## Tool prerequisites + +Both commands shell out to the tool's CLI: + +| Tool | CLI command | +|---|---| +| Claude Code | `claude` | +| Cursor | (via Cursor IDE / agent integration — check user's setup) | +| Codex | `codex` | +| OpenCode | `opencode` | +| Copilot | `gh copilot` | +| Antigravity | (IDE-driven) | + +If the tool's CLI isn't installed, both commands will fail with a "command +not found" error. Surface that clearly to the user — agr can't help install +the AI tool itself. + +## See also + +- [installing-skills.md](installing-skills.md) — installing for `agr run` +- [in-repo-skills.md](in-repo-skills.md) — testing during iteration with `agrx` diff --git a/skills/agr-cli/references/setup.md b/skills/agr-cli/references/setup.md new file mode 100644 index 0000000..624b230 --- /dev/null +++ b/skills/agr-cli/references/setup.md @@ -0,0 +1,140 @@ +# Setup — bootstrap a repo for agr + +How to initialize `agr.toml`, configure tools, and set up instruction syncing. +For the canonical CLI reference, run `agr init --help` or +`agr config --help`. + +## Prerequisites + +- `agr --version` works (install with `uv tool install agr` if not). +- The repo has at least one supported AI tool's marker — `.claude/`, + `CLAUDE.md`, `.cursor/`, `.cursorrules`, `.codex/`, `.opencode/`, + `.github/copilot-instructions.md`, `.gemini/`, etc. agr auto-detects from + these. + +## Initialize + +```bash +agr init +``` + +Creates `agr.toml` and detects tools from repo signals. + +Override detection upfront: + +```bash +agr init --tools claude,codex,opencode --default-tool claude +``` + +Flags: + +| Flag | Effect | +|---|---| +| `--tools` | Comma-separated list of tools (override auto-detect) | +| `--default-tool` | Tool used by `agrx` and instruction sync (defaults to first in `tools`) | +| `--sync-instructions` / `--no-sync-instructions` | Mirror canonical instruction file to others on `agr sync` | +| `--canonical-instructions` | Source of truth for instructions: `CLAUDE.md`, `AGENTS.md`, or `GEMINI.md` | + +Anything you skip can be set later with `agr config`. + +## Adjust tools after the fact + +```bash +agr config set tools claude codex opencode # replace +agr config add tools cursor # append +agr config remove tools cursor # ⚠ deletes that tool's skills/ +``` + +Skills install into each configured tool's directory: + +| Tool | Skills directory | +|---|---| +| Claude Code | `.claude/skills//` | +| Cursor | `.cursor/skills//` | +| Codex | `.agents/skills//` (older repos: `.codex/`) | +| OpenCode | `.opencode/skills//` (older: `.opencode/skill/`) | +| GitHub Copilot | `.github/skills//` | +| Antigravity / Gemini | `.gemini/skills//` (older: `.agent/`) | + +`agr sync` runs migrations automatically when it sees old layouts. + +The `tools` list does NOT apply to ralphs — they always install once into +`.agents/ralphs//`. + +## Multi-tool consistency + +Once `tools = ["claude", "codex", "opencode"]`, every `agr add` and `agr sync` +fans out to each tool. `agr list` shows `partial` if a skill is missing from +any of the configured tools — run `agr sync` to fix. + +## Instruction syncing + +If the user keeps a canonical instruction file and wants it mirrored to other +tools' equivalents: + +```bash +agr config set sync_instructions true +agr config set canonical_instructions CLAUDE.md +``` + +Mappings: + +- `CLAUDE.md` ↔ `.claude/CLAUDE.md` +- `AGENTS.md` ↔ Codex / OpenCode +- `GEMINI.md` ↔ Antigravity + +`agr sync` copies the canonical file to the others. Only fires when 2+ tools +are configured. If only one tool is configured, instruction syncing is a no-op. + +## Default owner (1-part handles) + +`default_owner` lets the user write `agr add setup` to mean +`/skills/setup`. Defaults to `computerlovetech`. Override: + +```bash +agr config set default_owner my-org +``` + +This is mostly useful for organizations that publish their own `skills` repo +and want short handles. + +## What to commit + +| File / dir | Commit? | Why | +|---|---|---| +| `agr.toml` | YES | The manifest — your team's source of truth | +| `agr.lock` | YES | Pins exact commits and content hashes — required for `--frozen` / `--locked` CI | +| `skills/` (in-repo) | YES | The skill source itself, reviewed in PRs | +| `.claude/skills/`, `.cursor/skills/`, etc. | NO | Generated from agr.toml; usually gitignored | +| `~/.agr/` | N/A | User-specific global config | + +If `.claude/skills/` is currently committed, decide with the user whether to +gitignore it now that agr is managing it. + +## Worked example: from zero to first skill + +```bash +# 1. Install agr (confirm with user first) +uv tool install agr + +# 2. Bootstrap config in the repo +agr init --tools claude,cursor --default-tool claude + +# 3. Add a remote skill +agr add anthropics/skills/pdf + +# 4. Scaffold an in-repo skill +agr init project-conventions +mkdir -p skills && mv project-conventions skills/ +agr add ./skills/project-conventions + +# 5. Verify +agr list +git status # show what to commit: agr.toml, agr.lock, skills/project-conventions/ +``` + +## See also + +- [handles.md](handles.md) — handle formats and resolution +- [in-repo-skills.md](in-repo-skills.md) — full `skills/` workflow +- [configuration.md](configuration.md) — all config keys diff --git a/skills/agr-cli/references/syncing.md b/skills/agr-cli/references/syncing.md new file mode 100644 index 0000000..0de1273 --- /dev/null +++ b/skills/agr-cli/references/syncing.md @@ -0,0 +1,143 @@ +# Syncing, upgrading, and the lockfile + +`agr sync` is what teammates run after pulling. `agr upgrade` is what the +release captain runs to pull in upstream changes. Don't confuse them. + +## agr sync + +```bash +agr sync +``` + +Runs four stages in order: + +1. **Instruction sync** — copies the canonical instruction file + (`CLAUDE.md` / `AGENTS.md` / `GEMINI.md`) to the others. Fires only when + `sync_instructions = true` and 2+ tools are configured. +2. **Migrations** — renames legacy skill directories + (`.codex/skills/` → `.agents/skills/`, `.opencode/skill/` → + `.opencode/skills/`, etc.). Automatic; no user action needed. +3. **Dependency install** — installs any deps from `agr.toml` not already on + disk. Same-repo skills are batched into one download. Already-installed + deps are left alone (this is the key difference from `agr upgrade`). +4. **Lockfile update** — writes `agr.lock` with the resolved commit SHA and + content hash for every dep. + +### Use cases + +| Situation | Command | +|---|---| +| You pulled and a teammate added new deps | `agr sync` | +| You added a tool to `tools = [...]` and want existing deps in the new tool | `agr sync` | +| You need byte-identical installs in CI | `agr sync --frozen` | +| You want CI to fail if `agr.lock` is stale | `agr sync --locked` | +| You want the latest upstream code, even if already installed | `agr upgrade` (NOT `agr sync`) | + +### Flags + +| Flag | Effect | +|---|---| +| `--frozen` | Install exactly what `agr.lock` says. Fail if lock is missing or doesn't cover every dep. Never re-resolves. **CI deploy.** | +| `--locked` | Fail if `agr.lock` is out of date vs `agr.toml`, then install from the lock. **CI PR check.** | +| `--global`, `-g` | Sync `~/.agr/agr.toml`. Ralph deps are skipped (project-scoped only). | + +`--frozen` and `--locked` are mutually exclusive. + +## CI patterns + +### PR check + +Make CI fail if a contributor added a dep without committing the regenerated +lockfile: + +```yaml +# .github/workflows/ci.yml (sketch) +- run: agr sync --locked +``` + +### Deploy + +Lock everything to the recorded commits — no surprise upstream updates: + +```yaml +- run: agr sync --frozen +``` + +## agr upgrade + +```bash +agr upgrade # everything in scope +agr upgrade pdf # short-name match +agr upgrade anthropics/skills/pdf # full handle +agr upgrade pdf collaboration # several at once +``` + +`agr upgrade` re-fetches the named (or all) deps at the current upstream HEAD +and refreshes `agr.lock`. Runs the same instruction-sync and migration stages +as `agr sync` first. + +### Short-name matching + +`agr upgrade pdf` works when exactly one dep has the installed name `pdf`. If +two deps share a name (e.g. `user1/skills/pdf` and `user2/skills/pdf`), agr +errors and asks you to disambiguate with the full handle. + +### Same-repo siblings — important gotcha + +Upgrading one skill from a multi-skill repo only refreshes that one. Sibling +skills in the same repo keep their existing lockfile commit and on-disk +content. + +```bash +# Bad: only refreshes pdf, leaves docx and xlsx pinned +agr upgrade anthropics/skills/pdf + +# Good: refreshes all anthropics/skills siblings together +agr upgrade # everything in scope +# or +agr upgrade anthropics/skills/pdf anthropics/skills/docx anthropics/skills/xlsx +``` + +If the user only wants to bump siblings together (e.g. all of +`anthropics/skills/*`), they must list each one explicitly. + +### Flags + +| Flag | Effect | +|---|---| +| `--global`, `-g` | Upgrade global deps from `~/.agr/agr.toml` | + +## agr.lock + +Auto-generated; never hand-edit. Format: + +```toml +version = 1 + +[[skill]] +handle = "anthropics/skills/pdf" +source = "github" +commit = "a0d5bfd4d9658073029d33f979ac5a027568caec" +content-hash = "sha256:75e47..." +installed-name = "pdf" + +[[skill]] +path = "skills/internal-review" +installed-name = "internal-review" +``` + +Local-path deps record `path` instead of `handle`/`source`/`commit` — there's +nothing to pin remotely. + +If `agr.lock` looks broken or out of sync: + +1. Try `agr sync` first (re-resolves and rewrites the lock). +2. If still broken, delete the lock and `agr sync` to regenerate. + +Never fix it by hand. + +## See also + +- [installing-skills.md](installing-skills.md) — `agr add` and `agr remove` +- [configuration.md](configuration.md) — `tools`, `sources`, instruction sync +- [troubleshooting.md](troubleshooting.md) — fixing common errors diff --git a/skills/agr-cli/references/troubleshooting.md b/skills/agr-cli/references/troubleshooting.md new file mode 100644 index 0000000..5e6d89c --- /dev/null +++ b/skills/agr-cli/references/troubleshooting.md @@ -0,0 +1,186 @@ +# Troubleshooting + +Common failure modes and their fixes. + +## Install errors + +### "Repository not found" / "skill not found" + +The handle format is wrong, or the repo is private. + +- Check 2-part vs 3-part: `user/skill` assumes a repo named `skills`. If the + repo has a different name, use `user/repo/skill`. +- Open the URL `https://github.com//` in a browser to confirm + the repo exists. +- For private repos: `export GITHUB_TOKEN=...` before re-running. + +See [handles.md](handles.md) for full handle resolution. + +### "Skill directory not found in repo" + +The repo exists but the named subdirectory doesn't. + +```bash +agr add anthropics/skills/typo-here # → not found +``` + +Look at the GitHub repo and confirm the folder name. agr searches for any +directory containing a SKILL.md matching the requested name. + +### "Auth required" on a private repo + +```bash +export GITHUB_TOKEN="ghp_..." # GitHub +export GITLAB_TOKEN="..." # GitLab +agr add my-org/private-skills/secret +``` + +The token needs read access to the repo. + +## Sync / lockfile errors + +### "agr.lock is out of date" (--locked failure in CI) + +A contributor added a dep but didn't commit the regenerated lockfile. + +```bash +agr sync # locally — re-resolves and rewrites agr.lock +git add agr.lock +git commit -m "chore: refresh agr.lock" +``` + +Then push. + +### "agr.lock missing or incomplete" (--frozen failure in CI) + +Either `agr.lock` isn't committed, or a dep was added to `agr.toml` without +running `agr sync`. Same fix as above. + +### `agr list` shows `partial (claude, cursor)` + +The skill is installed in some configured tools but not all (e.g. you added +a tool to `tools = [...]` and didn't sync yet, or one tool's skills dir +wasn't writable). + +```bash +agr sync +``` + +If still partial, check permissions on the missing tool's skills dir. + +### `agr list` shows `not synced` + +Listed in `agr.toml` but not on disk. + +```bash +agr sync +``` + +### `agr list` shows `invalid` + +The handle in `agr.toml` cannot be parsed. Open `agr.toml` and fix the entry +manually, or remove and re-add: + +```bash +# manually edit agr.toml to remove the bad entry, then: +agr add +``` + +## Manifest errors + +### "agr.toml syntax error" + +You hand-edited `agr.toml` and broke TOML syntax. Common causes: + +- `[[source]]` block placed before `dependencies = [...]` (deps must come + first). +- Missing `type` on a dep entry. +- Unclosed array. + +Easiest fix: open in editor, paste a known-good snippet from +[configuration.md](configuration.md), and re-add deps with `agr add`. + +### Type errors after manual edit + +If you hand-edited a dep entry and `agr sync` complains about the `type`, +let agr rewrite it: + +```bash +# Remove the manually-edited entry, then re-add: +agr add +``` + +## Run-time errors + +### "claude: command not found" (or codex / opencode / etc.) + +The AI tool's CLI isn't installed. agr only manages skills — it doesn't +install the AI tools themselves. Direct the user to the tool's install docs. + +### "Skill not installed for tool X" + +`agr run pdf --tool cursor` but the skill isn't in `.cursor/skills/`. + +- If `cursor` is in `tools`: `agr sync` to fan out. +- If `cursor` is NOT in `tools`: add it first + (`agr config add tools cursor`), then `agr sync`. + +### `agr run pdf` errors with "ambiguous short name" + +Two installed skills share the name `pdf`. Use the full handle: + +```bash +agr run user--repo--pdf # collision-fallback installed-name +# or +agrx anthropics/skills/pdf # ephemeral with full handle +``` + +## Configuration errors + +### Removed a tool by accident; lost its skills + +```bash +agr config remove tools cursor # this DELETED .cursor/skills/ +``` + +Recover: + +```bash +agr config add tools cursor +agr sync +``` + +The skills are re-installed from `agr.toml` (using the pinned commits in +`agr.lock`). + +### `default_owner` resolving wrong handle + +You set `default_owner = "my-org"` but `agr add setup` is hitting +`computerlovetech`. Check: + +```bash +agr config get default_owner +agr config show +``` + +If global config overrides it, `-g` lets you check / fix the global file. + +## When all else fails + +1. `agr config show` — confirm config matches expectations. +2. `agr list` — see what agr thinks is installed. +3. `cat agr.toml agr.lock` — look at the manifest and lockfile. +4. Delete `agr.lock` and run `agr sync` to regenerate from scratch. +5. As a nuclear option: `rm -rf .claude/skills/ .cursor/skills/ ...` then + `agr sync` to reinstall everything. (Confirm with the user first.) + +## Reporting bugs upstream + +agr issues: https://github.com/computerlovetech/agr/issues + +Useful info to include: + +- `agr --version` +- `agr config show` +- `agr.toml` and `agr.lock` (redact private handles if needed) +- The exact command and full error output diff --git a/skills/improve-skill/SKILL.md b/skills/improve-skill/SKILL.md new file mode 100644 index 0000000..6b7e1de --- /dev/null +++ b/skills/improve-skill/SKILL.md @@ -0,0 +1,255 @@ +--- +name: improve-skill +description: > + Iteratively improve an existing AI agent skill (SKILL.md) based on session + feedback or a retrospective after using it. Use whenever the user says: + "improve the X skill", "update the X skill", "let's revise X based on what + we just did", "the X skill should also handle Y", "X skill didn't trigger + when it should have", "feedback on X skill", "retrospective on X", or + otherwise wants to capture lessons from a session back into the skill that + drove it. Handles in-repo skills (under skills/) by editing the source, + committing, and re-installing via `agr upgrade`. Handles remote/upstream + skills by offering to fork them in-repo or to file a GitHub issue via `gh`. + Do NOT use for greenfield skill authoring (a separate concern — see + `anthropics/skills/skill-creator`) or for installing / syncing / removing + skills (use the `agr` CLI directly). +--- + +# Improve Skill + +Capture lessons from a session into the skill that drove it. The default +shape is **listen → propose → align → apply → re-install**. + +## When to use + +Trigger when the user wants to revise an existing SKILL.md based on what +happened in the session. Examples: + +- "improve the X skill" +- "let's update X based on what we learned" +- "X skill should also handle …" +- "X didn't trigger when it should have" +- "retrospective on X" / "feedback on X" + +Do NOT use this skill for: + +- **Greenfield skill authoring.** Use `agr init` to scaffold a SKILL.md and + defer the body content to the user — or to a dedicated authoring skill + such as `anthropics/skills/skill-creator` + (`agr add anthropics/skills/skill-creator`). +- **Installing / syncing / removing skills.** That's plain `agr` CLI work + (`agr add`, `agr sync`, `agr upgrade`, `agr remove`). + +## Step 1: Identify the skill + +Ask which skill is being improved if it isn't obvious from context. Then +locate the source: + +```bash +agr list # see installed deps and short names +ls skills/ # in-repo source if present +cat agr.toml # see whether the dep is local-path or remote +``` + +Two cases — they have different update paths: + +| Case | Source location | Update path | +|---|---|---| +| **In-repo** (`{path = "./skills/", type = "skill"}` in `agr.toml`) | `skills//` | Edit source → commit → `agr upgrade ` | +| **Remote** (`{handle = "user/repo/", …}`) | Upstream GitHub repo | Cannot edit directly — see Step 5 | + +If the skill isn't installed at all but the user wants to improve it, ask +whether to add it first (and which case applies). + +## Step 2: Receive feedback + +**Listen.** The user invoked this skill because they have something to say +— let them say it. Do not interrogate. Do not run a checklist of questions +at them. Take in whatever they offer, in whatever shape they offer it. + +Only ask a clarifying question if you genuinely cannot proceed without one +(e.g. the user named a skill that doesn't exist, or two skills share the +name and you need to disambiguate). Even then, ask the minimum. + +Be **dynamic**. The user may surface things in any shape — a single +sentence ("the description should also fire on X"), a structured list, or a +ramble that you need to distill. They may also surface things outside the +standard buckets below (rename a section, restructure `references/`, change +output format, drop a deprecated workflow, fix a typo). Apply whatever the +user actually says. + +The buckets below are a mental map for *you* when distilling what you +heard, not a checklist to recite at the user: + +- **`description` / triggers** — under-fired or over-fired +- **Gotchas / boundaries** — a foot-gun the skill didn't warn about +- **Workflow steps** — missing, wrong, or out of order +- **References** — a topic kept needing more depth → new `references/.md` +- **Examples / output format** — vague where it should be concrete +- **Pruning** — outdated content that misled + +## Step 3: Propose changes + +Summarize what you heard, then propose specific edits. Format: + +> **Proposed changes to `skills//SKILL.md`** (and any references): +> +> 1. **Description** — add trigger phrase "…" (because: …) +> 2. **Boundaries** — add: never X (because: discovered this in session) +> 3. **New section "Y"** — describes the workflow that was missing +> +> Want me to apply these, revise, or add more? + +For small edits, show the exact diff inline. For larger changes, summarize +first and apply section by section. + +**Wait for explicit user approval before editing.** "yes" / "go ahead" / +similar. If the user revises, loop back to Step 2 or 3. + +## Step 4: Apply (in-repo case) + +Edit the source file(s) under `skills//`. Then: + +```bash +git status # confirm only the intended files changed +git add skills// +git commit -m "skill(): " +agr upgrade # re-installs into all configured tools, refreshes agr.lock +git add agr.lock +git commit --amend --no-edit # or commit separately; match the repo's style +``` + +**Do not push.** Stop after the commit and let the user push when ready. + +### Commit message style + +Use a conventional-commits-style scope: + +``` +skill(): +``` + +Examples: + +``` +skill(agr-cli): clarify upgrade vs sync for local paths +skill(agr-cli): add gotcha for same-repo siblings +skill(code-review): drop outdated linter pre-check +``` + +If the repo's commit style differs (check `git log --oneline -20`), match it. + +### Why `agr upgrade` and not `agr sync`? + +`agr sync` only installs **missing** deps — it does NOT re-copy a local-path +skill that's already installed. `agr upgrade ` re-copies it and +refreshes `agr.lock`. Use `agr upgrade`. + +(Equivalent: `agr add ./skills/ --overwrite`. Pick `upgrade` for +consistency — it's the same verb used to refresh remote skills.) + +## Step 5: Apply (remote case) + +If the skill is a remote dep, the change cannot be applied directly. Ask +the user which path they want: + +### Option A — File an issue upstream via `gh` + +Best when the change benefits everyone (a real bug or universal improvement +in someone else's published skill). + +Resolve the upstream repo from the handle: + +- `anthropics/skills/pdf` → `--repo anthropics/skills` +- `user/myrepo/skill` → `--repo user/myrepo` + +Confirm the title and body with the user, then: + +```bash +gh issue create \ + --repo / \ + --title "[] " \ + --body "$(cat <<'EOF' +## What I observed + + + +## Suggested change + + + +## Why + + +EOF +)" +``` + +`gh issue create` posts publicly — treat it the same as any other shared- +state action. **Always confirm before running.** + +If the user has push access and a local clone, also offer to open a PR +instead of (or alongside) the issue. + +### Option B — Fork to in-repo + +Best when the change is project-specific or unlikely to be accepted +upstream. Copies the skill into `skills//` so future retros work the +in-repo way. + +Suggested flow: + +```bash +# 1. Find the upstream commit (agr.lock has it) +agr list + +# 2. Sparse-checkout or full clone, then copy the folder: +mkdir -p skills +cp -r /tmp/upstream-clone/ skills/ + +# 3. Swap the dep +agr remove anthropics/skills/ +agr add ./skills/ +``` + +Tell the user this **forks** the skill — they're now responsible for +keeping it current with upstream. Then continue from Step 3 with the +in-repo flow. + +### Both A and B + +Offer Option A first when the change is generally useful. Offer Option B +when upstream is unlikely to accept, or when the user wants the change +*now* without waiting on upstream. + +## Step 6: Verify + +After re-installing (in-repo case): + +```bash +agr list # status should be `installed` +diff skills//SKILL.md .claude/skills//SKILL.md # should be empty +``` + +For remote case (issue filed): confirm the issue URL with the user. + +Tell the user what's done and what's pending (commit done, push pending; or +issue filed, awaiting response). + +## Boundaries + +- **Don't edit a skill without explicit user approval of the proposed + changes.** Skills are user-owned content — never silently revise. +- **Don't push.** Commit only; the user pushes when ready. +- **Don't open issues or PRs without confirming the title and body** with + the user first. `gh issue create` is publicly visible — treat it as + shared-state. +- **Don't edit `agr.lock` by hand** — `agr upgrade` regenerates it. +- **Don't broaden the scope of the edit** beyond what was discussed. If the + user asked to fix one gotcha, don't also restructure the file. +- **Don't write a skill from scratch** — that's a separate workflow. + +## See also + +- `anthropics/skills/skill-creator` — canonical greenfield skill authoring + (install with `agr add anthropics/skills/skill-creator` if needed) From 24456f11179dd4f89aa216f518fa820e45154aa6 Mon Sep 17 00:00:00 2001 From: Kasper Junge Date: Fri, 1 May 2026 08:50:16 +0200 Subject: [PATCH 2/2] refactor: rename improve-skill to skill-debrief MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rename for clearer semantic signal: "debrief" reads more naturally as end-of-session feedback / retrospective on a skill, and matches the `skill-creator` naming style. Adds "debrief"-flavored trigger phrases to the description and the When-to-use list while keeping all earlier trigger phrases (improve, retrospective, feedback, …) so existing invocations still fire. Updates the cross-reference in agr-cli/SKILL.md to point at `skill-debrief`. Co-Authored-By: Claude Opus 4.7 (1M context) --- skills/agr-cli/SKILL.md | 4 +-- .../{improve-skill => skill-debrief}/SKILL.md | 33 ++++++++++--------- 2 files changed, 19 insertions(+), 18 deletions(-) rename skills/{improve-skill => skill-debrief}/SKILL.md (88%) diff --git a/skills/agr-cli/SKILL.md b/skills/agr-cli/SKILL.md index c3e7af7..3054e37 100644 --- a/skills/agr-cli/SKILL.md +++ b/skills/agr-cli/SKILL.md @@ -41,8 +41,8 @@ Do NOT use this skill for: authoring skill such as `anthropics/skills/skill-creator`. - Iterating on an existing skill based on session feedback or a retrospective. That's a separate workflow — listen, propose, edit, commit, re-install. If - the user has a dedicated improvement skill installed (e.g. `improve-skill`), - use it; otherwise just do the workflow directly. + the user has a dedicated debrief / improvement skill installed (e.g. + `skill-debrief`), use it; otherwise just do the workflow directly. ## Prerequisites diff --git a/skills/improve-skill/SKILL.md b/skills/skill-debrief/SKILL.md similarity index 88% rename from skills/improve-skill/SKILL.md rename to skills/skill-debrief/SKILL.md index 6b7e1de..bf042ed 100644 --- a/skills/improve-skill/SKILL.md +++ b/skills/skill-debrief/SKILL.md @@ -1,35 +1,36 @@ --- -name: improve-skill +name: skill-debrief description: > - Iteratively improve an existing AI agent skill (SKILL.md) based on session - feedback or a retrospective after using it. Use whenever the user says: - "improve the X skill", "update the X skill", "let's revise X based on what - we just did", "the X skill should also handle Y", "X skill didn't trigger - when it should have", "feedback on X skill", "retrospective on X", or - otherwise wants to capture lessons from a session back into the skill that - drove it. Handles in-repo skills (under skills/) by editing the source, - committing, and re-installing via `agr upgrade`. Handles remote/upstream - skills by offering to fork them in-repo or to file a GitHub issue via `gh`. - Do NOT use for greenfield skill authoring (a separate concern — see + Debrief an AI agent skill (SKILL.md) after using it — capture session + feedback or a retrospective and fold it back into the skill. Use whenever + the user says: "debrief the X skill", "let's debrief X", "retrospective on + X", "feedback on X skill", "improve the X skill", "update the X skill", + "let's revise X based on what we just did", "the X skill should also + handle Y", "X didn't trigger when it should have", or otherwise wants to + capture lessons from a session back into the skill that drove it. Handles + in-repo skills (under skills/) by editing the source, committing, and + re-installing via `agr upgrade`. Handles remote/upstream skills by + offering to fork them in-repo or to file a GitHub issue via `gh`. Do NOT + use for greenfield skill authoring (a separate concern — see `anthropics/skills/skill-creator`) or for installing / syncing / removing skills (use the `agr` CLI directly). --- -# Improve Skill +# Skill Debrief Capture lessons from a session into the skill that drove it. The default shape is **listen → propose → align → apply → re-install**. ## When to use -Trigger when the user wants to revise an existing SKILL.md based on what +Trigger when the user wants to debrief an existing SKILL.md based on what happened in the session. Examples: -- "improve the X skill" -- "let's update X based on what we learned" +- "debrief the X skill" / "let's debrief X" +- "retrospective on X" / "feedback on X" +- "improve the X skill" / "let's update X based on what we learned" - "X skill should also handle …" - "X didn't trigger when it should have" -- "retrospective on X" / "feedback on X" Do NOT use this skill for: