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.

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

./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:

./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:

./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:

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:

{
  "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:

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:

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.