Describe the bug

gh skill update --help says that --force refreshes locally modified skill files but “does not remove extra files added locally.” On 2.102.0, applying an update replaces all contents of the installed skill directory, deleting locally added files. This also happens during a version update without --force.

A user relying on that sentence can lose notes or scripts they added to a skill directory. The documented --force --all example describes restoring modified files without explaining that additional files are discarded.

Affected version

gh version 2.102.0 (2026-09-30)
https://github.com/cli/cli/releases/tag/v2.102.0

Steps to reproduce the behavior

dir=$(mktemp -d)
gh skill install cli/cli gh --dir "$dir"
echo notes > "$dir/gh/LOCAL-NOTES.md"
gh skill update gh --dir "$dir" --force --all
ls "$dir/gh"

A version update reproduces this without --force: install gh with --pin v2.100.0, add LOCAL-NOTES.md, then run gh skill update gh --dir "$dir" --unpin --all.

Expected vs actual behavior

Expected from the help: LOCAL-NOTES.md remains alongside the refreshed SKILL.md.

Actual: LOCAL-NOTES.md is deleted; only SKILL.md remains in this reproduction.

#13449 explicitly made stale-file removal part of an in-place update, and the update test requires a locally planted file to disappear. However, the help still promises to keep extra local files.

Please correct the help to explain that applying any update replaces the installed directory's contents with the upstream skill, discarding local modifications and additional files. The --force description should separately explain that it also applies this replacement when the upstream version has not changed.

Logs

$ gh skill update gh --dir "$dir" --force --all
1 update(s) available:
  • gh (cli/cli) a4791f98 (reinstall) [v2.102.0]

Updated gh
$ ls "$dir/gh"
SKILL.md