feat: refresh shared skills catalog
This commit is contained in:
vasily committed
1 parent
98bb35e6fb
commit
418792d1ec
49 files changed
+2273
-2390
No files matched your search
@@ -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.
|
||||
@@ -0,0 +1,111 @@
|
||||
# Authoring and maintenance
|
||||
|
||||
Shared workflows live in `skills/<name>/`; JEV runtime-specific skills remain in
|
||||
JEV. Installed directories link to those sources. Maintain one procedure per
|
||||
workflow and use small aliases when an old name needs to remain callable.
|
||||
|
||||
## Add or edit a skill
|
||||
|
||||
Use [skill-architect](../skills/skill-architect/SKILL.md) for catalog work. A skill
|
||||
needs concrete activation criteria, useful steps, and appropriate completion
|
||||
evidence. There is no required phase structure or length quota.
|
||||
|
||||
Example `SKILL.md` metadata:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: example-skill
|
||||
description: >
|
||||
Perform a specific workflow when the user requests its concrete outcome.
|
||||
scope: global
|
||||
---
|
||||
```
|
||||
|
||||
Names use lowercase kebab-case and match the containing directory. Scope values:
|
||||
|
||||
| Scope | Meaning |
|
||||
| --- | --- |
|
||||
| `global` | Reusable workflow; preserve the target repository's conventions. |
|
||||
| `project` | Requires a named project's tooling or layout; explain that dependency. |
|
||||
| `alias` | Explicit compatibility entry point delegating to another skill. |
|
||||
|
||||
Scope is descriptive metadata; a harness must implement its own routing policy.
|
||||
Write optional recipes under `references/` and link them where they help a decision.
|
||||
Keep relative links valid from the source file. Use the
|
||||
[template](../skills/skill-architect/references/sample-skill.md) as an example.
|
||||
|
||||
For catalog changes, validate once from the repository root:
|
||||
|
||||
```sh
|
||||
python3 bin/validate-skills
|
||||
```
|
||||
|
||||
After adding, removing, or moving a skill, preview and sync:
|
||||
|
||||
```sh
|
||||
./sync-skills.sh --dry-run
|
||||
./sync-skills.sh
|
||||
```
|
||||
|
||||
Content-only edits already propagate through existing links. Commit according to
|
||||
the user's request and repository/session conventions; these tools do not commit.
|
||||
|
||||
## Workflow rules
|
||||
|
||||
Follow [shared workflow and verification](../protocols/workflow.md): use existing
|
||||
context, preserve user work, and choose checks that can detect a real failure in
|
||||
the changed behavior. Avoid mandatory cross-skill handoffs, repeated confirmation,
|
||||
full suites for prose edits, or automatic spec creation for ordinary bug fixes.
|
||||
|
||||
In an adopted spec workflow, `spec` owns architecture and task definitions, `build`
|
||||
owns task statuses, and `backprop` owns bug records and bug-related invariants.
|
||||
See [the spec format](../skills/spec/references/format.md). A review-only request
|
||||
produces findings without edits or commits.
|
||||
|
||||
## What validation covers
|
||||
|
||||
`bin/validate-skills` checks metadata, matching names, scope, duplicate source
|
||||
names, and local Markdown targets outside fenced examples. It uses Python's
|
||||
standard library and supports this catalog's scalar/block-string YAML subset.
|
||||
It does not verify web links, Markdown anchors, arbitrary YAML schemas, or whether
|
||||
an agent will activate or execute a skill correctly.
|
||||
|
||||
Both tools accept `--global-dir` and `--jev-dir`. Sync additionally accepts
|
||||
repeatable `--target` arguments. Use source overrides consistently when checking
|
||||
a custom installation. Link ownership is inferred from those source roots; it is
|
||||
not recorded in a separate manifest.
|
||||
|
||||
## Verify tool changes
|
||||
|
||||
When sync, validation, or delivery behavior changes, run the relevant regression
|
||||
checks from the repository root:
|
||||
|
||||
```sh
|
||||
python3 -m unittest discover -s tests -v
|
||||
```
|
||||
|
||||
Tests use temporary source catalogs and targets; they do not change installed
|
||||
agent directories. Coverage includes link ownership, stale cleanup, read-only
|
||||
modes, collisions, missing sources, and delivery command generation.
|
||||
|
||||
[Workflow evaluation cases](../tests/workflow-cases.md) are optional fixtures for
|
||||
trigger or policy changes. A behavioral evaluation requires observed agent actions;
|
||||
passing script tests does not prove routing quality. Use real failures to guide
|
||||
small corrections rather than adding more mandatory checks.
|
||||
|
||||
## Delivery helper
|
||||
|
||||
`bin/t3-deliver` prints a quoted `scp` command using this host's Tailscale address.
|
||||
It requires Bash and `realpath`; the receiving Windows machine needs OpenSSH scp
|
||||
with SFTP support and access to the host. It starts no server or transfer.
|
||||
|
||||
To expose it on PATH, link the helper from the repository root:
|
||||
|
||||
```sh
|
||||
mkdir -p "$HOME/.local/bin"
|
||||
ln -s "$PWD/bin/t3-deliver" "$HOME/.local/bin/t3-deliver"
|
||||
```
|
||||
|
||||
Inspect an existing destination before replacing it. `sync-skills.sh` installs
|
||||
skill directories, not this executable link. On another host, adapt the address
|
||||
in `bin/t3-deliver` and the delivery skill's host-specific instructions together.
|
||||
Reference in new issue
Block a user