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 <name>` 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 <noreply@anthropic.com>

Author: 2 people

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.

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: