jeo-skill · diff
v1.0.0 to v1.0.0
151 added, 60 removed. Audit A to A.
---
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.
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.
- ## Instructions
+ ## 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 before installing
+ ### 2. Browse and install
```bash
jeo-skill categories
jeo-skill list --category web
jeo-skill list --category game --subcategory audio
- jeo-skill search "responsive React design"
- jeo-skill related code-review
- ```
- The catalog uses ten stable primary categories:
-
- - `web`: frontend, backend, design, API, data, testing, accessibility, performance
- - `infrastructure`: deployment, environment, observability, security, cloud/data, automation
- - `game`: client, web, server, design/UI, audio, animation, motion/VFX, sprite/image,
- art resources, storytelling, tooling, QA/performance, release
- - `creative-media`: image, video, motion, audio, presentation, diagram, capture, storytelling
- - `cli-tools`: developer, AI, media, automation, search, benchmark CLIs
- - `ai-agents`: orchestration, agent frameworks, skill authoring, evaluation, planning/review
- - `engineering`: code quality, testing, architecture, documentation
- - `research`: academic, web research, data analysis, benchmarking
- - `business`: marketing, support, publishing
- - `utilities`: knowledge, files, Git, workspace, project management, general utilities
-
- ### 3. Prefer the narrowest install
-
- ```bash
# Preview first; no files are installed.
jeo-skill install --bundle web-frontend --dry-run
- jeo-skill install --category game --subcategory audio --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.
- ### 4. Treat overlap as a routing relationship
+ ### 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.
- ### 5. Verify observable behavior
+ ## 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` |
+ | 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 doctor
- jeo-skill categories --json
- jeo-skill install --bundle starter --dry-run
+ jeo-skill install --all --global --yes
```
- `doctor` must resolve a valid catalog and report Python/npx availability. A dry run must
- print the exact selected skill names and installation command without changing the system.
+ ### Selective Installation
- ## Examples
+ Install specific skills or curated bundles:
```bash
- # Web design and frontend implementation
- jeo-skill list -c web -s design
+ # 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
+ ```
- # Focused game workflows
- jeo-skill list -c game -s motion-vfx
- jeo-skill related game-vfx
- jeo-skill install game-vfx rfxgen --global --yes
+ ### Project-Local Installation
- # CLI-only discovery
- jeo-skill list -c cli-tools --interface cli
+ Install within the current project (`./.agents/skills`):
+
+ ```bash
+ jeo-skill install responsive-design react-best-practices --yes
```
+ ### Upgrade from Old PATH-Based Router
- ## Native Projections and Account Access
+ **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.
- Some runtimes do not load skills from the universal shared root (`~/.agents/skills`) and require
- native materialization. The `setup-all-skills-prompt.md` guide handles these automatically;
- here is a reference for manual or CI workflows:
+ ```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
- | Runtime | CLI Arg | Shared Root | Native Root | Scope | Needs Projection |
- |---------|---------|-------------|------------|-------|------------------|
- | jeopi, jeo-code, oh-my-pi, Claude Code, Codex, Gemini CLI, OpenCode | `universal` | `~/.agents/skills` | — | global/project | No (auto-loaded) |
- | GJC | `gjc` | ignored | `~/.gjc/agent/skills` (global) or `.gjc/skills` (project) | both | Yes (copy manually) |
- | Antigravity IDE | `antigravity` | `~/.agents/skills` | `~/.gemini/config/skills` | global only | Yes (copy manually) |
- | Antigravity CLI (agy) | `antigravity-cli` | `~/.agents/skills` | `~/.gemini/antigravity-cli/skills` | global only | Yes (copy manually) |
- | Aside (account-scoped) | — | `~/.agents/skills` | `~/.aside/u/<id>/skills/user/` | per-account | Yes (copy per-account) |
+ # 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
- ### Projection Pattern
+ # Re-install your selected skills with the new router
+ jeo-skill install responsive-design django-patterns --global --yes
- After installing selected skills globally with `skills add -g`, copy skill folders to native roots:
+ # 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
- # Example: GJC global
- cp -R ~/.agents/skills/code-review ~/.gjc/agent/skills/code-review
+ # 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
```
- ### Account Access (Aside)
+ ### GJC and Antigravity CLI Native Projection
- Aside discovers skills from per-account paths. Use account-scoped discovery only; do not share
- credentials between accounts or store tokens in global skill folders.
+ 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
+ ```
+
+ Both commands must succeed and report Python/npx availability and valid catalog metadata.
+
+ ## 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.
- - Keep one central taxonomy projection; do not add category wrapper folders containing
- duplicate `SKILL.md` files.
+ - 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.
- - Run `--dry-run` before any multi-skill install and report the resolved selection.
## 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`