jeo-skill

jeo-skill

このスキルを使う場面

ユーザーが次のことを必要としている場合は、このスキルを軽量なカタログの入口として使用します。

• 主カテゴリと詳細なサブカテゴリからスキルを探す。
• 1つのスキル、厳選されたバンドル、または1つのカテゴリの一部だけをインストールする。
• 選択する前に、関連するスキルや重複するスキルを確認する。
• エージェントのランタイムに .agent-skills 全体をチェックアウトせずに済ませる。
• ローカルカタログと jeo-skill 実行可能ファイルが使用可能であることを確認する。
• インストール済みスキルのうち、エージェントが実際に呼び出したものを追跡し、一度も使われていないものを隔離する。

分類を表現するために、スキルのフォルダーを物理的に移動しないでください。エージェントのスキル検索では <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 に従って、無効化された --dry-run と、別途設けるリモートコンテンツ／コストの確認ゲートを通じて、範囲を限定したスキル文書の検索を行います。カタログのメタデータ検索と選択が引き続きデフォルトです。セットアップ、同意、スニペットの確認は、正規スキルが担います。

使用状況の追跡と未使用スキルの整理

jeo-skill usage scan は、ローカルのランタイム記録（Claude の skillUsage とトランスクリプト、Codex のロールアウト、OpenCode、Antigravity、Aside、jeopi/GJC/OMP/Pi のセッション、JeV のインジェクション台帳）を読み取り、ローカルに使用状況の概要（スキルごとの使用回数、初回／最終使用時刻）と増分スキャンのメタデータ（記録のパス、サイズ、ハッシュ）を保存します。トランスクリプト本文は保存しません。保存先は ${JEO_SKILL_STATE_DIR:-${XDG_STATE_HOME:-~/.local/state}/jeo-skill} です。エージェントがスキルを呼び出した、または読み込んだ場合に限り、そのスキルは使用済みと見なされます。具体的には、Skill／スラッシュコマンドの呼び出し、インストール済みの <root>/<name>/SKILL.md または skill://<name> の読み取り、あるいは Jev による本文全体のインジェクションです。プロンプト内での言及、インジェクションを伴わない Jev のルーティング、カタログソース（<checkout>/.agent-skills/<name>/SKILL.md）の読み取りは、使用としてカウントされません。証拠はランタイムログがローテーションまたは削除された後も保持されます。Claude の記録は、デフォルトの ~/.claude.json と ~/.claude/projects に加え、すべての CLAUDE_CONFIG_DIR プロファイルから読み取られます。対象は、現在のプロファイル、JEO_SKILL_CLAUDE_CONFIG_DIRS に記載されたプロファイル、および以前のスキャンで確認されたプロファイルです。以前に確認されたプロファイルは記憶されるため、変数を指定せずにスケジュール実行したスキャンでも読み取られます。リンクされたストアは一度だけ読み取られます。

スキルが削除候補になるのは、保持されているすべての記録で使用が一度も確認されず、追跡開始から30日間（または、後日の場合は、そのスキルがインストール済みとして初めて確認されてから30日間）の猶予期間が経過した場合に限られます。使用が確認されていないことは、生涯にわたり未使用だった証明にはなりません。ランタイムが古い履歴を削除している場合があります。jeo-skill、starter、cli-core、infrastructure-core バンドル、usage keep でピン留めされたスキル、および usage relevance で保護されたスキルは候補になりません。

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

隔離の対象となるのは、カタログに含まれることを確実に確認できる jeo-skills のコピーのみです（ディレクトリ名、フロントマターの名前、最初の見出しがカタログと一致するもの）。サードパーティー製のコピー、シンボリックリンク、リンクされたルートは報告されますが、保持されます。Jev を呼び出す際は、毎回 --allow-remote が必要です。プロファイルのレビュー用バックエンドはホスト型の場合があり、status でも設定済みのエンドポイントに接続します。Jev による deny またはレビューを利用できない場合、適用は中止されます。proposal_only の場合は、--apply が人による承認となるため処理が続行され、レシートはバッチマニフェストに保存されます。--skip-jev-review を指定した場合は、その指定が記録されます。

カタログからの削除は、リポジトリのチェックアウトで別途メンテナーが行う手順です。 python3 scripts/retire-unused-skills.py --usage-report report.json は、jeo-skill usage report --json による提案をプレビューします。--apply --approve name[,name] に加えて、--jev-profile P --allow-remote または記録済みの --skip-jev-review を指定すると、承認済みのスキルを削除し、プロジェクションを再生成して検証します。失敗した場合はロールバックします（レビュー方法の選択なしでの --apply は拒否されます）。

定期レポートを作成するには、ホストのフックまたはスケジューラーからスキャンを実行し、適用は手動で行います。スキャンは同時に1つだけ実行されます（状態ディレクトリ内の OS ファイルロックを使用します）。--if-idle を指定すると、フックまたはスケジューラーは実行中のスキャンの後ろで待機せず、スキップします。~/.claude/settings.json および使用するすべての CLAUDE_CONFIG_DIR プロファイルに設定する Claude Code の SessionEnd フックは次のとおりです。

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

このフックは Claude のセッション終了時にしか実行されないため、他のランタイム用に毎日スキャンをスケジュールしてください。cron エントリ 17 3 * * * $HOME/.local/bin/jeo-skill usage scan --if-idle >/dev/null 2>&1 を設定するか、macOS では LaunchAgent に StartCalendarInterval を設定します（スリープ後に実行されなかったジョブも実行されます）。すべてのスケジュール済みスキャンで JEO_SKILLS_CATALOG を同じカタログに固定してください。カタログが変更されると、次のスキャンですべての有効な記録を再解析します（証拠が失われることはありませんが、時間がかかります）。

ランタイムのインストールガイド

ガイドに沿ってインストールするには、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
Kimi Code	kimi → kimi-code-cli	~/.agents/skills またはプロジェクトの .agents/skills	Kimi は ${KIMI_CODE_HOME:-$HOME/.kimi-code}/skills もスキャンします。ルーターは共有ルートにインストールします	グローバル／プロジェクト	共有ディスカバリー。有効化は別途確認	jeo-skill install responsive-design --agent kimi --global --yes
Grok Build	grok	—	${GROK_HOME:-$HOME/.grok}/skills（グローバル）または .grok/skills（プロジェクト）	グローバル／プロジェクト。明示的な選択のみ	Superagent／VibeKit の grok CLI ではありません。このバイナリのローダーについては保証されません	jeo-skill install responsive-design --agent grok --global --yes
OpenCode	opencode または universal	~/.agents/skills またはプロジェクトの .agents/skills	互換性ルートの ~/.config/opencode/skills が共有コピーを優先する場合があります	グローバル／プロジェクト	共有ディスカバリー	jeo-skill install responsive-design --agent opencode --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 and 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

doctor は、npx が見つからない場合、または Node.js が利用できない、サポート対象外（22.20 未満）、もしくはバージョンチェックに失敗した場合に、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