152 lines
6.1 KiB
Markdown
152 lines
6.1 KiB
Markdown
# 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.
|