jeo-skill v1.0.0A

Immutable. This exact content never changes and is served at /api/v1/blob/2cd9be6669d7701c.

---
name: jeo-skill
description: >
  Browse, group, relate, and selectively install the jeo-skills catalog through the
  lightweight `jeo-skill` CLI. Use when the user wants skills organized by web,
  infrastructure, game, creative media, CLI tools, AI/agents, engineering, research,
  business, or utilities; needs a frontend/backend/game-audio/game-VFX subcategory;
  wants overlapping skills connected instead of duplicated; or wants a category,
  bundle, or named skills installed without copying the full repository.
allowed-tools: Bash Read Write Edit Glob Grep
compatibility: Requires Python 3.9+ and npx only when installing skills
metadata:
  tags: skill-management, taxonomy, selective-install, categories, deduplication, cli
  version: "1.0.0"
  source: akillness/jeo-skills
---

# jeo-skill

## When to use this skill

Use this skill as the lightweight catalog front door when the user needs to:

- discover skills by primary category and focused subcategory;
- install only one skill, a curated bundle, or one category slice;
- inspect related or overlapping skills before choosing one;
- avoid a full `.agent-skills` checkout in an agent runtime;
- verify that the local catalog and the `jeo-skill` executable are usable;
- track which installed skills agents actually invoke, and quarantine never-used ones.

Do not physically move skill folders to represent taxonomy. Agent skill discovery expects
`<skill-name>/SKILL.md`; category and relationship metadata belongs in the central catalog.

## Quick Start

### 1. Link the CLI once

From a source checkout or an installed copy of this skill:

```bash
python3 scripts/jeo-skill.py link
jeo-skill doctor
```

This creates only `~/.local/bin/jeo-skill`. It does not install the full catalog.

### 2. Browse and install

```bash
jeo-skill categories
jeo-skill list --category web
jeo-skill list --category game --subcategory audio

# Preview first; no files are installed.
jeo-skill install --bundle web-frontend --dry-run
jeo-skill install responsive-design react-best-practices --dry-run

# Install globally after reviewing the selection.
jeo-skill install responsive-design react-best-practices --global --yes
jeo-skill install --bundle game-web --global --yes

# Optionally run bundled tool setup / smoke verification (--setup) and hook/MCP wiring (--with-hooks):
jeo-skill install open-ontologies openspace rtk --global --yes --setup --dry-run
jeo-skill install open-ontologies openspace rtk --global --yes --setup
```

The CLI delegates file installation to `npx skills add ... --skill ...`; it never copies the
whole repository unless the user explicitly selects every skill. Omit `--global` for a
project-local install. Use `--agent <runtime>` to target a specific supported runtime.
Pass `--setup` to also run the selected skills' bundled CLI/smoke verification helpers
(for example `open-ontologies`, `okf-agent-memory`, `mex`, `openspace`, `ooo`, `rtk`,
`semble`, `cli-anything`, `spec-kit`, `graphify`, `llm-wiki`, `jev-control-plane`, `ecc`),
and `--with-hooks` when you also approve hook/MCP registration.

### 3. Treat overlap as a routing relationship

`jeo-skill related <name>` shows catalog relationship groups. Keep adjacent tools as
separate skills when their runtime or job differs—for example, human code-review judgment
versus the `ocr` CLI. Use a canonical alias only when ordinary prompts truly compete and
backward-compatible exact-name installation is required.

### Optional Jevgrep source discovery

For an explicit Jevgrep request, follow [jevgrep](../jevgrep/SKILL.md) for scoped
skill-document discovery through `jeo-skill explore` with an inert `--dry-run` and
a separate remote-content/cost gate. Catalog metadata search and selection remain
the default; the canonical skill owns setup, consent, and snippet verification.

## Usage tracking and unused-skill cleanup

`jeo-skill usage scan` reads local runtime records (Claude `skillUsage` and transcripts,
Codex rollouts, OpenCode, Antigravity, Aside, jeopi/GJC/OMP/Pi sessions, and the Jev
injection ledger) and stores local usage summaries (per-skill counts, first/last use) plus
incremental scan metadata (record paths, sizes, hashes), never transcript bodies, under
`${JEO_SKILL_STATE_DIR:-${XDG_STATE_HOME:-~/.local/state}/jeo-skill}`. A skill counts as
used only when an agent invoked or loaded it: a Skill/slash invocation, a read of an
installed `<root>/<name>/SKILL.md` or `skill://<name>`, or a Jev full-body injection.
Mentions in prompts, Jev routing without injection, and reads of the catalog source
(`<checkout>/.agent-skills/<name>/SKILL.md`) never count. Evidence survives rotated or
deleted runtime logs. Claude records are read from the default `~/.claude.json` and
`~/.claude/projects` plus every `CLAUDE_CONFIG_DIR` profile: the active one, those listed
in `JEO_SKILL_CLAUDE_CONFIG_DIRS`, and any profile an earlier scan saw (remembered, so a
scheduled scan without the variable still reads it). Linked stores are read once.

A skill becomes a removal candidate only with zero observed uses in all retained records
and a 30-day grace after tracking began (or after it was first seen installed, if later).
Zero observed uses is not proof of lifetime non-use: runtimes may have deleted older
history. `jeo-skill`, the `starter`, `cli-core`, and `infrastructure-core` bundles,
`usage keep` pins, and skills protected by `usage relevance` are never candidates.

```bash
jeo-skill usage scan                     # refresh evidence (writes tracker state only)
jeo-skill usage report --status candidate
jeo-skill usage keep rare-but-needed     # pin; `usage unkeep` removes the pin
jeo-skill usage relevance --repos ~/work/app --jev-profile jeopi --dry-run

# Local installs: preview, then quarantine (rescans first; reversible)
jeo-skill prune-unused --global
jeo-skill prune-unused --global --apply --jev-profile jeopi --allow-remote
jeo-skill restore --list
jeo-skill restore --batch <batch-id> --apply
jeo-skill purge-quarantine --older-than 30 --apply   # permanent; preview without --apply
```

Quarantine moves only provable jeo-skills catalog copies (directory, frontmatter name, and
first heading match the catalog); third-party copies, symlinks, and linked roots are
reported and kept. Every Jev call needs `--allow-remote`: the profile's review backend may
be hosted and even `status` contacts configured endpoints. A Jev `deny` or unavailable
review aborts the apply; `proposal_only` proceeds because `--apply` is the human approval,
and the receipt is stored in the batch manifest. `--skip-jev-review` is recorded instead.

Catalog retirement is a separate maintainer step in a repository checkout:
`python3 scripts/retire-unused-skills.py --usage-report report.json` previews proposals from
`jeo-skill usage report --json`; `--apply --approve name[,name]` plus either
`--jev-profile P --allow-remote` or a recorded `--skip-jev-review` retires approved skills,
regenerates projections, validates, and rolls back on any failure (`--apply` without a review
choice is rejected).

For periodic reports, run the scan from a host hook or scheduler and apply manually. Scans
are single-flight (an OS file lock in the state dir); `--if-idle` makes a hook or scheduler
skip instead of queueing behind a running scan. A Claude Code `SessionEnd` hook in
`~/.claude/settings.json` (and in any `CLAUDE_CONFIG_DIR` profile you use):

```json
{"hooks": {"SessionEnd": [{"hooks": [{"type": "command", "timeout": 5,
  "command": "nohup \"$HOME\"/.local/bin/jeo-skill usage scan --if-idle >/dev/null 2>&1 &"}]}]}}
```

Because that hook only fires for Claude sessions, also schedule a daily scan for the other
runtimes: a cron entry `17 3 * * * $HOME/.local/bin/jeo-skill usage scan --if-idle >/dev/null 2>&1`
or, on macOS, a LaunchAgent with `StartCalendarInterval` (runs missed jobs after sleep).
Pin `JEO_SKILLS_CATALOG` to one catalog for every scheduled scan: a catalog change makes
the next scan re-parse all live records (evidence is never lost, but it is slower).

## Runtime Installation Guide

Follow `setup-all-skills-prompt.md` for guided installation. The installer writes files;
runtime loading and account activation are separate checks.

| Runtime | Arg | Shared Root | Native Root | Scope | Auto-Load | Installation |
|---------|-----|-------------|-------------|-------|-----------|---|
| jeopi, JEO (`jeo-code`), OMP (`oh-my-pi`) | `jeopi`, `jeo`, `omp` → `universal` | `~/.agents/skills` or project `.agents/skills` | — | global/project | shared discovery | `jeo-skill install responsive-design --agent jeopi --global --yes` |
| GJC | `gjc` | `~/.agents/skills` | `~/.gjc/agent/skills` (global) or `.gjc/skills` (project) | global/project | native discovery | `jeo-skill install responsive-design --agent gjc --global --yes` |
| Antigravity CLI | `agy` or `antigravity-cli` | `~/.agents/skills` | `~/.gemini/antigravity-cli/skills` (global) or `.agents/skills` (project) | global/project | placement verified | `jeo-skill install responsive-design --agent agy --global --yes` |
| Kimi Code | `kimi` → `kimi-code-cli` | `~/.agents/skills` or project `.agents/skills` | Kimi also scans `${KIMI_CODE_HOME:-$HOME/.kimi-code}/skills`; the router installs to the shared root | global/project | shared discovery; activation verified separately | `jeo-skill install responsive-design --agent kimi --global --yes` |
| Grok Build | `grok` | — | `${GROK_HOME:-$HOME/.grok}/skills` (global) or `.grok/skills` (project) | global/project; explicit selection only | not the Superagent/VibeKit `grok` CLI; no loader claim for that binary | `jeo-skill install responsive-design --agent grok --global --yes` |
| OpenCode | `opencode` or `universal` | `~/.agents/skills` or project `.agents/skills` | compatibility root `~/.config/opencode/skills` can shadow shared copies | global/project | shared discovery | `jeo-skill install responsive-design --agent opencode --global --yes` |
| Antigravity IDE | `antigravity` | `~/.agents/skills` | `~/.gemini/config/skills` | global native projection | placement verified | `jeo-skill install responsive-design --agent antigravity --global --yes` |
| Aside (account-scoped) | `--agent aside` | — | `~/.aside/u/<account-id>/skills/user/` | per-account | ✗ manual | `jeo-skill install responsive-design django-patterns --agent aside --global --aside-account <id> --yes` |
**Key Points:**
- `~/.agents/skills` is the shared root for most runtimes; install there first.
- GJC and Antigravity global installs automatically project to native roots when the target is selected.
- Aside is account-scoped; use `--agent aside --aside-account <id>`.
- Other upstream runtime IDs pass through to the pinned installer; do not assume universal discovery or activation.
- **Placement ≠ Activation:** These commands only materialize skill files to roots. They do not authenticate, start, or verify that a runtime has loaded the skills. See your runtime's documentation for activation/registration steps (e.g., Claude Code plugin install, GJC CLI reachability, IDE skill auto-discovery).

## Installation Workflows

### Full Catalog (default, via setup-all-skills-prompt.md)

This command installs every catalog skill to the shared root. Follow the setup guide's
targeted runtime steps for native projections; this command alone does not perform them.

```bash
jeo-skill install --all --global --yes
```

### Connected 8-Tool Workflow Setup (`rtk`, `semble`, `mex`, `zvec`, `graphify`, `secondbrain`, `cli-hub`, `specity`)

Both `jeo-skill` and `skill-query-handler.py` resolve shorthand aliases (`zvec` → `zvec-grep`,
`secondbrain` → `obsidian-second-brain`, `cli-hub` → `cli-anything`, `specity`/`specify` → `spec-kit`)
directly. When `--setup` is passed, `jeo-skill` automatically orders `obsidian-second-brain`
last so that `graphify`, `mex-agent`, and `zg` are installed and verified before
`obsidian-second-brain/scripts/setup.py` validates its binary dependencies:

```bash
# Install and run --setup for the 7 standalone CLIs (shorthand aliases supported):
jeo-skill install rtk semble mex zvec graphify cli-hub specity --global --yes --setup

# Or include secondbrain once JEO_SECOND_BRAIN_CONFIG is prepared with explicit consent:
JEO_SECOND_BRAIN_CONFIG=/path/to/second-brain-config.json \
  jeo-skill install rtk semble mex zvec graphify secondbrain cli-hub specity --global --yes --setup
```

### Selective Installation

Install specific skills or curated bundles:

```bash
# By name
jeo-skill install code-review django-patterns responsive-design --global --yes

# By category
jeo-skill install --category game --global --yes

# By curated bundle
jeo-skill install --bundle web-frontend --global --yes
```

### Project-Local Installation

Install within the current project (`./.agents/skills`):

```bash
jeo-skill install responsive-design react-best-practices --yes
```
### Upgrade from Old PATH-Based Router

**Upgrade note:** Run this from the checked-out `jeo-skills` repository root. The commands use `JEO_SKILLS_SOURCE="$PWD"` to reference the local checkout, not a global installation.

```bash
cd /path/to/checked-out/jeo-skills
JEO_SKILLS_SOURCE="$PWD" JEO_SKILLS_SELECTION=router JEO_SKILLS_AGENT=universal INSTALL_GLOBAL=true JEO_SKILLS_DRY_RUN=true bash ./install.sh

# Refresh the shared router; preserve its existing CLI link
JEO_SKILLS_SOURCE="$PWD" JEO_SKILLS_SELECTION=router JEO_SKILLS_AGENT=universal INSTALL_GLOBAL=true JEO_SKILLS_DRY_RUN=false bash ./install.sh
# Verify the installed router directly, not an unrelated PATH command
python3 "$HOME/.agents/skills/jeo-skill/scripts/jeo-skill.py" doctor

# Re-install your selected skills with the new router
jeo-skill install responsive-design django-patterns --global --yes

# For GJC/Antigravity CLI, re-project to native roots:
# For GJC native projection:
jeo-skill install responsive-design django-patterns --agent gjc --global --yes
# For Antigravity CLI native projection:
jeo-skill install responsive-design django-patterns --agent antigravity-cli --global --yes
```

### Aside Account Access

Each Aside account requires explicit account ID and optional home path:

```bash
# List available Aside accounts
ls ~/.aside/u/

# Install skills for a specific account
jeo-skill install responsive-design --agent aside --global \
  --aside-account <account-id> --yes

# Optional: custom Aside home (defaults to ~/.aside)
jeo-skill install responsive-design --agent aside --global \
  --aside-account <account-id> --aside-home /path/to/aside --yes
```

### GJC and Antigravity CLI Native Projection

After installing to the shared root, project to native runtimes:

```bash
# Install to shared root first
jeo-skill install code-review django-patterns --global --yes

# Project to GJC native root (both global and project-local)
jeo-skill install code-review django-patterns --agent gjc --global --yes
jeo-skill install code-review django-patterns --agent gjc --yes  # project-local .gjc/skills

# Antigravity CLI supports global native and project-local installation
jeo-skill install code-review --agent agy --global --yes
jeo-skill install code-review --agent agy --yes  # project-local .agents/skills

# Project to Antigravity IDE global root
jeo-skill install code-review --agent antigravity --global --yes
```

**Important:** Use `--dry-run` before multi-skill installs to preview exactly what will be
installed and copied.

## Recovery from Broken Links

If a previous installation left a broken or stale symlink in `~/.local/bin/jeo-skill`:

```bash
# Inspect the current link
ls -la ~/.local/bin/jeo-skill

# Check where the linked file actually is
find ~/.agents/skills -name "jeo-skill.py" -type f

# If the path is wrong or missing, force re-link after confirming intent
python3 ~/.agents/skills/jeo-skill/scripts/jeo-skill.py link --force
jeo-skill doctor
```

Do not force-link unless you have verified:
1. The destination jeo-skill.py exists and is readable.
2. The current broken symlink is from a previous (now invalid) installation path.
3. The re-linked version will point to the shared router.

## Verification

After any installation or upgrade:

```bash
jeo-skill doctor
jeo-skill categories --json  # Verify catalog is accessible
```

`doctor` reports `ok: false`, includes actionable `errors`, and exits nonzero when
`npx` is missing or Node.js is unavailable, unsupported (below 22.20), or fails its
version check. `linked` is reported separately: an unlinked checkout CLI can still
pass the prerequisite check. Browsing requires only Python; `categories` does not
check installation tools. Search accepts non-negative `--limit` values (`0` returns
no matches); negative values are rejected.

`JEO_SKILLS_CATALOG=/path/to/skills.json` overrides catalog discovery for all browse,
install, and doctor commands. An explicit path must be readable and valid: a missing
file or directory is an error, never a silent fallback to the checkout or remote
catalog. Unset the variable to restore automatic discovery.

## Examples

```bash
# Web design and frontend implementation
jeo-skill list -c web -s design
jeo-skill install --bundle web-frontend --global --yes

# Focused game workflows
jeo-skill list -c game -s motion-vfx
jeo-skill related game-vfx
jeo-skill install game-vfx rfxgen --global --yes

# CLI-only discovery
jeo-skill list -c cli-tools --interface cli

# Full global installation (all skills to shared root)
jeo-skill install --all --global --yes
```

## Best practices

- Install by name or curated bundle before installing an entire category.
- Use `--dry-run` to preview every multi-skill installation.
- Run `jeo-skill doctor` after any installation to verify linkage.
- Keep one central taxonomy projection; do not add category wrapper folders.
- Connect neighboring skills with relationship groups rather than duplicating instructions.
- Keep heavy upstream apps, models, MCP servers, and runtimes on-demand inside each skill.

## References

- Catalog: `.agent-skills/skills.json`
- Compact projection: `.agent-skills/skills.toon`
- Agent Skills installer: `npx skills --help`
- Setup automation: `setup-all-skills-prompt.md`
- Catalog validator: `scripts/validate-catalog-projections.py`