feat: refresh shared skills catalog

docs/installation.md

@@ -0,0 +1,151 @@
+# Installation and usage
+
+## Get the source
+
+Use an existing checkout or clone the repository into a stable location. Replace
+`<repository-url>` with the URL of your copy; this checkout has no configured Git
+remote from which to derive one.
+
+```sh
+git clone <repository-url> ~/Projects/work/global-skills
+cd ~/Projects/work/global-skills
+```
+
+Requirements: Bash, Python 3, and symbolic-link support. No Python packages or Node
+packages are needed for syncing. Keep the checkout after installing: installed
+links point into it.
+
+The commands here target a Linux host. Native Windows installation and junction
+management are not implemented by this script.
+
+## Install the catalog
+
+```sh
+./sync-skills.sh --dry-run
+./sync-skills.sh
+./sync-skills.sh --check
+```
+
+The first command previews changes, the second applies them, and the third checks
+the result without writing. Default destinations are `~/.agents/skills`,
+`~/.codex/skills`, and `~/.claude/skills`.
+
+Sync includes every valid skill directory from this checkout and, when available,
+`~/Projects/work/JEV/.agents/skills`. A source skill must have a kebab-case directory
+name and a `SKILL.md` file. Duplicate names across sources stop sync before writes.
+Existing unrelated destinations are preserved and reported as conflicts.
+
+If JEV is absent, sync warns and installs the shared catalog. Some skill references
+and the `anti-slop-editor` alias depend on JEV or the expected sibling-checkout
+layout. The optional catalog validator reports unresolved local references; it is
+not required to install the shared skills.
+
+## Install into selected agent directories
+
+`--target` replaces the default destinations. Repeat it to select several:
+
+```sh
+./sync-skills.sh --target "$HOME/.codex/skills"
+./sync-skills.sh --target "$HOME/.codex/skills" --target "$HOME/.claude/skills"
+```
+
+Both commands install the available source catalogs, not a selected subset of
+skills. Targets cannot overlap a source catalog.
+
+For a different JEV location, use the same override for syncing and checking:
+
+```sh
+./sync-skills.sh --jev-dir /path/to/JEV/.agents/skills --target "$HOME/.codex/skills"
+./sync-skills.sh --check --jev-dir /path/to/JEV/.agents/skills --target "$HOME/.codex/skills"
+```
+
+`--global-dir` overrides the shared source directory. Moving sources may require
+manual removal of old links: the script recognizes ownership only under the source
+roots supplied for that invocation.
+
+## Install one shared skill
+
+For a small selection, create links directly instead of running catalog sync.
+From the repository root:
+
+```sh
+mkdir -p "$HOME/.codex/skills"
+ln -s "$PWD/skills/interface-kit" "$HOME/.codex/skills/interface-kit"
+```
+
+Repeat with the desired skill name and agent directory. Link the whole skill
+directory so its references remain available. Keep the checkout and its protocols;
+copying just `SKILL.md` can break relative references.
+
+`ln -s` fails if that destination already exists. Inspect an existing entry before
+replacing it. Catalog sync later adds all available skills to that target; it is
+not a subset installer.
+
+## Antigravity
+
+The sync script does not edit Antigravity configuration. On this host, Antigravity
+reads source directories listed in `~/.gemini/config/skills.json`:
+
+```json
+{
+  "entries": [
+    { "path": "/absolute/path/to/global-skills/skills" },
+    { "path": "/absolute/path/to/JEV/.agents/skills" }
+  ]
+}
+```
+
+Use your actual absolute paths and omit JEV if unavailable. Merge entries with
+existing configuration rather than overwriting unrelated sources. This is the
+configuration used by the current host integration; another Antigravity version
+or setup may discover skills differently.
+
+## Use and update
+
+Ask for work normally or explicitly name a skill. For example:
+
+```text
+Use app-security to check authorization on these routes. Give me a report first.
+Use deepen to simplify this module while preserving its public behavior.
+Use fuck-slop to edit this draft without changing its claims.
+```
+
+The agent decides applicability from its available skill catalog. Naming a skill
+does not authorize unrelated edits, publishing, or other external actions.
+
+Edit the canonical source to update a skill. Existing links expose that content
+immediately; start a new agent session if the running session cached older
+instructions. Sync after changes to skill names or directory locations.
+
+For Git updates, follow your checkout's branch/remote convention. Inspect local
+changes before pulling; this project does not impose a remote or auto-update policy.
+
+## Remove an installation
+
+Remove an individual symlink from the agent directory after inspecting it:
+
+```sh
+ls -l "$HOME/.codex/skills/interface-kit"
+```
+
+If it points to this checkout, remove that link. Removing an installed link leaves
+the source intact; the next full sync recreates it. To retire a skill from the
+catalog, remove its source directory and sync while the source root is still
+available. Missing JEV sources cause their old links to be preserved, not removed.
+
+## Troubleshooting
+
+| Result | Meaning and next step |
+| --- | --- |
+| `check: 0 changes, 0 conflicts` | Installed links match the available catalogs. |
+| Check exits `1` with changes | Preview with `--dry-run`, then sync to apply the changes. |
+| `SKIP: unrelated entry` or `unrelated symlink` | Inspect that destination; sync preserves it. Choose another target or deliberately resolve the collision. |
+| Colliding skill name, exit `2` | Rename or consolidate the source skills; there is no silent precedence rule. |
+| JEV unavailable warning | Shared skills can install; JEV links are preserved until its source is available. |
+| Validator reports missing local links | Restore the referenced file/checkouts or correct the source link. Sync checks installation, not reference integrity. |
+| Skill missing in a running agent | Check the source and installed link, then refresh that agent's session/catalog. |
+
+`--dry-run` and `--check` make no changes. Dry-run exits `0` for a conflict-free
+preview even when changes are needed. Check exits `1` for drift or conflicts.
+Sync also exits `1` for destination conflicts; unaffected destinations may already
+have been updated. Invalid source catalogs/arguments exit `2` before syncing.