jeo-skill
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.
How do I install this agent skill?
npx skills add https://github.com/akillness/jeo-skills --skill jeo-skillIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill is a dedicated management and analytics tool for the jeo-skills catalog. It allows for the discovery, selective installation, and usage tracking of AI agent skills. Key security features include path validation for symlink protection and a redaction mechanism that filters secrets (like API keys) from workflow logs. While the tool performs network requests to fetch catalog data and executes shell commands for tool setup, these behaviors are explicitly documented and essential for its functionality as a skill manager. Data shared with external 'Jev' backends for review or relevance is sanitized and requires explicit user consent via the --allow-remote flag.
- Socketpass
No alerts
- Snykfail
Risk: CRITICAL · 4 issues
What does this agent skill do?
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-skillscheckout in an agent runtime; - verify that the local catalog and the
jeo-skillexecutable 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
# 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
# Five GitHub programs: install the guides and print one offline, read-only readiness report.
jeo-skill install --bundle github-five-programs --global --yes --setup
jeo-skill readiness --global # the same report alone; add --json for every finding
The CLI delegates file installation to npx --yes skills@1.7.0 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, headroom, llm-wiki, jev-control-plane, ecc),
and --with-hooks when you also approve hook/MCP registration.
For fabric, moneyprinter-v2, agent-s, google-maps-scraper and gitingest, --setup installs
nothing: it runs each skill's offline scripts/preflight.py and prints one report. A blocked program is a
missing prerequisite, not an install failure, so the command's exit status is unaffected; installing or running
one of those programs stays a separate approval.
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.
4. Host behavior: jeopi and jeo-code both route
- jeopi / omp / pi / gjc: the OpenSpace
before_agent_startextension ranks the installed catalog for every prompt and hands the model the matchingSKILL.mdpaths, sojeo-skillis picked up from ordinary wording. Check withpython3 ../openspace/scripts/route-hooks.py --host jeopi status. - jeo (jeo-code): command hooks come from
~/.jeo/hooks.json(eventspre-prompt,turn-end, and the tool-looppre-tool,post-turn,post-implementation).python3 ../openspace/scripts/route-hooks.py install --host jeoregisters the same router as apre-prompthook, so each prompt is ranked and the matchingSKILL.mdpaths reach the model as a[pre-prompt hook context]block; check with--host jeo status. A jeo-code build withoutpre-promptsupport ignores that file: there, name the skill in the prompt (jeo-skill, or "use the jeo-skill skill"), becausejeo skills listdiscovers~/.agents/skillsbut the system prompt lists only about 30 of them, ordered by name-token match to the task. jeo-skill usage scanreads jeo sessions from~/.jeo/sessionsplus the project-local<project>/.jeo/sessionsstores, which is where jeo-code actually writes them. Name each project once withjeo-skill usage scan --project-root ~/work/app(repeatable; remembered in the tracker state, so scheduled scans keep reading it), or list session directories inJEO_SKILL_JEO_SESSION_DIRS(os.pathsep-separated absolute paths). Repositories passed tousage relevance --reposand the current directory are read too; nothing walks the filesystem. A skill counts for jeo only when an assistant turnreads itsSKILL.md(orskill://<name>); a skill that jeo merely received through a prompt hook or a slash alias leaves no read, so do not treat a jeo-only skill with zero uses as unused.
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",
"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/skillsis 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
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:
# Install and run --setup for all 8 workflow tools (secondbrain auto-initializes
# ~/.jeo/second-brain-config.json -> ~/vaults/jeo-second-brain by default when global):
jeo-skill install rtk semble mex zvec graphify secondbrain cli-hub specity --global --yes --setup
# Or supply an explicit custom config path (or skip with JEO_SKILLS_SECOND_BRAIN=skip):
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:
# 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:
- The destination jeo-skill.py exists and is readable.
- The current broken symlink is from a previous (now invalid) installation path.
- 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-runto preview every multi-skill installation. - Run
jeo-skill doctorafter 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 --yes skills@1.7.0 --help - Setup automation:
setup-all-skills-prompt.md - Catalog validator:
scripts/validate-catalog-projections.py
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/akillness/jeo-skills/jeo-skill">View jeo-skill on skillZs</a>