jeo-skill

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:

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

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

The CLI delegates 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.

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

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):

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

jeo-skill install --all --global --yes

Selective Installation

Install specific skills or curated bundles:

# 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):

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.

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:

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

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

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

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

# 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