From 5b2f7d4b259f49442037f5841e1b696c4ceab1cc Mon Sep 17 00:00:00 2001 From: Kasper Junge Date: Mon, 22 Jun 2026 13:42:32 +0200 Subject: [PATCH] docs: recommend `agr upgrade` for iterating on in-repo skills The in-repo skills guidance steered users to `agr add ./path --overwrite` to re-sync a locally-edited skill. `agr upgrade ` is purpose-built for this: it reinstalls a fresh on-disk copy of the local skill into every configured tool and refreshes agr.lock, in a shorter name-based command. Update both the SKILL.md Iterate note and references/in-repo-skills.md to lead with `agr upgrade`, keeping `add --overwrite` as the path-based escape hatch for re-adds and clarifying that `agr sync` won't pick up edits. Closes #528 Co-Authored-By: Claude Opus 4.8 --- skills/agr-cli/SKILL.md | 7 +++++-- skills/agr-cli/references/in-repo-skills.md | 14 +++++++++++--- 2 files changed, 16 insertions(+), 5 deletions(-) diff --git a/skills/agr-cli/SKILL.md b/skills/agr-cli/SKILL.md index d0a4840..398a322 100644 --- a/skills/agr-cli/SKILL.md +++ b/skills/agr-cli/SKILL.md @@ -125,8 +125,11 @@ 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. +Iterate: edit `skills/my-skill/SKILL.md`, then `agr upgrade my-skill` to +reinstall the fresh on-disk copy into each configured tool and refresh +`agr.lock`. (`agr add ./skills/my-skill --overwrite` also works, but reach for +it when you've changed the dependency's path or are re-adding it — for plain +edits to an already-registered skill, `agr upgrade` is shorter and lock-aware.) 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. diff --git a/skills/agr-cli/references/in-repo-skills.md b/skills/agr-cli/references/in-repo-skills.md index 2e9fbc9..48ac25c 100644 --- a/skills/agr-cli/references/in-repo-skills.md +++ b/skills/agr-cli/references/in-repo-skills.md @@ -84,11 +84,19 @@ for every tool in `tools`. Edit `skills/my-skill/SKILL.md`, then reinstall: ```bash -agr add ./skills/my-skill --overwrite +agr upgrade my-skill ``` -Or just `agr sync` — but `--overwrite` is more explicit when you've made local -edits. +`agr upgrade` reinstalls a fresh on-disk copy of the local skill into every +configured tool and refreshes `agr.lock` — the canonical re-sync after editing +an already-registered in-repo skill. + +Alternatives: + +- `agr add ./skills/my-skill --overwrite` — path-based; reach for it when the + skill's path changed or you're re-adding it, not for plain edits. +- `agr sync` — only installs what's missing, so it won't pick up edits to an + already-installed skill. Use `agr upgrade` to force the refresh. To test ephemerally (no permanent install) on a path: