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: