jeo-skill

jeo-skill

何时使用此技能

当用户需要以下操作时，可将此技能用作轻量级目录入口：

• 按主要类别和细分子类别查找技能；
• 仅安装一个技能、一个精选技能包或某个类别中的部分技能；
• 在选择技能前查看相关或重叠的技能；
• 避免在 Agent 运行时完整检出 .agent-skills；
• 确认本地目录和 jeo-skill 可执行文件可用。

请勿通过物理移动技能文件夹来表示分类。Agent 技能发现要求使用 <skill-name>/SKILL.md；类别和关系元数据应放在中央目录中。

快速入门

1. 创建一次 CLI 链接

在源代码检出目录或此技能的已安装副本中运行：

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

此操作只会创建 ~/.local/bin/jeo-skill，不会安装完整目录。

2. 浏览并安装

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

CLI 会将安装操作交由 npx skills add ... --skill ... 处理；除非用户明确选择了所有技能，否则不会复制整个仓库。在项目本地安装时，省略 --global。使用 --agent <runtime> 可指定受支持的运行时。

3. 将重叠视为路由关系

jeo-skill related <name> 会显示目录中的关系组。如果相邻工具的运行时或用途不同，请将其保留为独立技能，例如人工代码审查判断与 ocr CLI。只有当普通提示词确实无法区分它们，且需要向后兼容的精确名称安装时，才使用规范别名。

可选：Jevgrep 源发现

如果用户明确请求使用 Jevgrep，请遵循 jevgrep，通过 jeo-skill explore 并使用无副作用的 --dry-run 来发现指定范围内的技能文档，同时单独设置远程内容/成本确认关卡。默认仍使用目录元数据进行搜索和选择；规范技能负责设置、征求同意以及验证代码片段。

运行时安装指南

按照 setup-all-skills-prompt.md 进行引导式安装。安装程序会写入文件；运行时加载和账户激活需要分别检查。

运行时	参数	共享根目录	原生根目录	范围	自动加载	安装
jeopi、JEO（jeo-code）、OMP（oh-my-pi）	jeopi、jeo、omp → universal	~/.agents/skills 或项目 .agents/skills	—	全局/项目	共享发现	jeo-skill install responsive-design --agent jeopi --global --yes
GJC	gjc	~/.agents/skills	~/.gjc/agent/skills（全局）或 .gjc/skills（项目）	全局/项目	原生发现	jeo-skill install responsive-design --agent gjc --global --yes
Antigravity CLI	agy 或 antigravity-cli	~/.agents/skills	~/.gemini/antigravity-cli/skills（全局）或 .agents/skills（项目）	全局/项目	已验证放置位置	jeo-skill install responsive-design --agent agy --global --yes
Antigravity IDE	antigravity	~/.agents/skills	~/.gemini/config/skills	全局原生投影	已验证放置位置	jeo-skill install responsive-design --agent antigravity --global --yes
Aside（账户范围）	--agent aside	—	~/.aside/u/<account-id>/skills/user/	每个账户	✗ 手动	jeo-skill install responsive-design django-patterns --agent aside --global --aside-account <id> --yes
要点：

• ~/.agents/skills 是大多数运行时的共享根目录；请先安装到此处。
• 安装目标选中 GJC 和 Antigravity 的全局安装后，会自动投影到原生根目录。
• Aside 按账户划分范围；请使用 --agent aside --aside-account <id>。
• 其他上游运行时 ID 会传递给固定版本的安装程序；不要假设它们支持通用发现或激活。
• 放置 ≠ 激活： 这些命令只会将技能文件写入根目录，不会验证身份、启动运行时，也不会确认运行时已加载技能。请参阅运行时文档，了解激活/注册步骤（例如，安装 Claude Code 插件、确保 GJC CLI 可访问、IDE 技能自动发现）。

安装工作流

完整目录（默认，通过 setup-all-skills-prompt.md）

此命令会将目录中的所有技能安装到共享根目录。原生投影请按照设置指南中的目标运行时步骤操作；仅执行此命令不会完成这些步骤。

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

选择性安装

安装指定技能或精选组合：

# 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

项目本地安装

在当前项目中安装（./.agents/skills）：

jeo-skill install responsive-design react-best-practices --yes

从旧版基于 PATH 的路由器升级

升级说明： 请在已检出的 jeo-skills 仓库根目录中运行此操作。命令使用 JEO_SKILLS_SOURCE="$PWD" 引用本地检出内容，而非全局安装。

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 账户访问

每个 Aside 账户都需要明确指定账户 ID 和可选的主目录路径：

# 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 和 Antigravity CLI 原生投影

安装到共享根目录后，将其投影到原生运行时：

# 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

重要： 安装多个技能前，请使用 --dry-run 预览将要安装和复制的确切内容。

修复损坏的链接

如果之前的安装在 ~/.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

除非已确认以下事项，否则不要强制创建链接：

1. 目标 jeo-skill.py 存在且可读。
2. 当前损坏的符号链接指向之前（现已无效）的安装路径。
3. 重新创建的链接将指向共享路由器。

验证

每次安装或升级后：

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

当缺少 npx，或者 Node.js 不可用、不受支持（低于 22.20）或未通过版本检查时，doctor 会报告 ok: false，包含可执行的 errors，并以非零状态码退出。linked 会单独报告：未链接的检出目录 CLI 仍可通过前置条件检查。浏览仅需要 Python；categories 不会检查安装工具。搜索接受非负的 --limit 值（0 表示不返回匹配项）；负值会被拒绝。

JEO_SKILLS_CATALOG=/path/to/skills.json 会覆盖所有浏览、安装和 doctor 命令的目录发现设置。指定的路径必须可读取且有效：文件或目录不存在时会报错，绝不会静默回退到检出目录或远程目录。取消设置该变量即可恢复自动发现。

示例

# 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

最佳实践

• 优先按名称或精选套件安装，再安装整个类别。
• 使用 --dry-run 预览每次多技能安装。
• 每次安装后运行 jeo-skill doctor，验证链接状态。
• 保留一个中央分类投影；不要添加类别包装文件夹。
• 通过关系组关联相邻技能，而不是重复说明。
• 将上游大型应用、模型、MCP 服务和运行时保留在各个技能中，并按需使用。

参考资料

• 目录：.agent-skills/skills.json
• 紧凑投影：.agent-skills/skills.toon
• Agent Skills 安装程序：npx skills --help
• 设置自动化：setup-all-skills-prompt.md
• 目录验证器：scripts/validate-catalog-projections.py