global-skills/docs/installation.md

# 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.