openspace

OpenSpace

このホストエージェントが、大規模なカタログから適切な SKILL.md をどのように見つけ、信頼し、改善するのか、という問いに対処するときにこのスキルを使います。ユーザーが単に1つのスキルの実行を求めている場合には使いません。

OpenSpace の README では、OpenSpace は「AI エージェントのためのスキル管理レイヤー」と説明されています。スキルは増え続けますが、OpenSpace は実行のたびにスキルの検索、評価、進化を支援します。このリポジトリでの役割は、具体的には jeo-skills のスキル検索／取得レイヤーとして動作することです。ホストエージェントに OpenSpace を一度インストールすると、エージェントはフラットなスキル一覧から推測したり、人間が手作業でルーティングルールを管理したりする代わりに、.agent-skills/（および $HOME/.agents/skills にコピーされた場所）にすでにインストールされている約150個のスキルから、適切な SKILL.md を検索、順位付け、読み込みできます。

このスキルを使う場面

• ユーザーがOpenSpace をインストールし、ホストエージェントが既存のスキルカタログを検索できるようにしたい
• ユーザー（またはエージェント）が、多数のインストール済みスキルからタスクに最適なスキルを取得／順位付けする必要がある
• ユーザーが、説明だけでなく実際の実行結果に基づいて、どのインストール済みスキルが実際に機能するかを知りたい
• ユーザーが、実際の実行結果に基づく管理されたスキルの進化（FIX／DERIVED／CAPTURED）を望んでいる
• ユーザーが、ローカル優先のハブを通じてスキルを共有またはインポートしたい（パッケージの閲覧、明示的なインポート、信頼性チェックを経たアップロード）
• ユーザーが、OpenSpace と、通常のカタログ検索、長期的に使うナレッジ Wiki、またはリポジトリごとのエージェントメモリのどれを選ぶべきか判断している

このスキルを使わない場面

• ユーザーが既存のスキルカタログをキーワード検索／grep で調べたいだけの場合 → codebase-search または semble に振り分けます。単発の検索のために、完全な MCP スキル管理レイヤーを導入しないでください
• ユーザーが、長期的に利用する、統合された Markdown のナレッジ（概念、インデックス、調査メモ）を求めている場合 → llm-wiki に振り分けます
• ユーザーが、スキル選択とは関係のない、リポジトリごとのエージェントメモリ（引き継ぎメモ、意思決定ログ、マニフェスト）を求めている場合 → opencontext に振り分けます
• ユーザーが、すでに名前の分かっている特定のスキルを1つ実行したいだけの場合 → そのスキルの SKILL.md を直接読み込みます。OpenSpace はスキルの検索と評価のためのものであり、スキルの使用に取って代わるものではありません

手順

ステップ 1：作業をルーティングモードに分類する

ほかのことを始める前に、主要モードを1つだけ選びます。

1. install-as-skill-finder — OpenSpace をホストエージェントに接続し、このカタログを検索できるようにする
2. retrieve-a-skill — タスクに応じて適切な SKILL.md を検索、順位付け、読み込む
3. evaluate-skill-quality — 実行記録に基づき、インストール済みスキルの信頼性を評価する
4. evolve-skills — 証拠に基づく FIX／DERIVED／CAPTURED の更新を適用する
5. share-import-hub — 信頼できるスキルを公開する、またはローカル優先のクラウドハブからスキルを取得する
6. route-out — 作業が実際には codebase-search／semble、llm-wiki、または opencontext に該当する

各モードの詳細と振り分けの考え方については、references/skill-discovery-routing.md を参照してください。

ステップ 2：OpenSpace をインストールする（パス A のクイックスタート）

上流のクイックスタートに基づいています。

git clone --filter=blob:none --sparse https://github.com/HKUDS/OpenSpace.git ~/.openspace/OpenSpace
cd ~/.openspace/OpenSpace
git sparse-checkout set --no-cone '/*' '!/assets/'   # skips the ~50 MB assets/ folder

# A dedicated venv, not the system Python: `pip install -e .` against a Homebrew or
# distro Python fails with PEP 668 "externally-managed-environment", which is how
# openspace-mcp ends up missing on a machine that "installed successfully".
python3 -m venv ~/.agents/venvs/openspace          # or: uv venv --python 3.12 ~/.agents/venvs/openspace
~/.agents/venvs/openspace/bin/python -m pip install -e .
~/.agents/venvs/openspace/bin/openspace-mcp --help  # verify installation
ln -sf ~/.agents/venvs/openspace/bin/openspace-mcp ~/.local/bin/openspace-mcp

Python 3.12+ が必要です。

または、同じ手順を非対話型で実行し、2つのホストスキル（ステップ 4）をコピーして、MCP サーバー（ステップ 3）を登録する、同梱のインストーラーを実行してください。

bash scripts/install-openspace.sh --help
bash scripts/install-openspace.sh --dry-run
bash scripts/install-openspace.sh

ホストごとの接続手順の詳細については、references/install-and-mcp-wiring.md を参照してください。

ステップ 3：OPENSPACE_HOST_SKILL_DIRS をこのリポジトリのスキルのルートに設定して、MCP サーバーを接続します

マシンにインストールされているすべての AI ランタイムに openspace MCP サーバーを登録します — Claude Code とその Anthropic 互換フォーク（kimi、glm/zai、deepseek、grok、qwen）、 Codex、Gemini CLI、Cursor、OpenCode、および pi / gjc / jeopi エージェントランタイムです。jeo-skills の場合、OPENSPACE_HOST_SKILL_DIRS は $HOME/.agents/skills を指している必要があります — このリポジトリのインストーラーがホストエージェントに読み込ませるスキルをコピーする場所であり、OpenSpace がスキャンして照合するディレクトリだからです。

各設定を手作業で編集する代わりに、同梱の登録ツールを使います。

bash scripts/register-openspace-mcp.sh --dry-run   # preview every runtime it would touch
bash scripts/register-openspace-mcp.sh             # merge in place
bash scripts/register-openspace-mcp.sh --force     # overwrite an existing openspace entry

このツールは、mcpServers JSON（~/.claude.json、~/.claude/claude_desktop_config.json、 ~/.gemini/settings.json、~/.qwen/settings.json、~/.cursor/mcp.json、 ~/.kimi/mcp.json、~/.glm/mcp.json、~/.zai/mcp.json、~/.deepseek/mcp.json、 ~/.pi/agent/mcp.json、~/.gjc/agent/mcp.json、~/.jeopi/agent/mcp.json）、TOML [mcp_servers.openspace]（~/.codex/config.toml、~/.grok/config.toml）、および type: local を指定した OpenCode の mcp ブロック（~/.config/opencode/opencode.json）を書き込みます。既存ファイルのモードを維持したまま、アトミックに置き換えます。シンボリックリンクと通常ファイル以外の設定ファイルは拒否されます。設定ディレクトリが存在しないランタイムは、作成せずにスキップされます。絶対パスの仮想環境バイナリが書き込まれるため、エージェントの PATH に ~/.local/bin が含まれていなくても登録できます（解決順序：$OPENSPACE_VENV/bin/openspace-mcp、~/.local/bin/openspace-mcp、PATH、従来の ~/.openspace/venv/bin/openspace-mcp）。

書き込まれるエントリは次の内容と同等です。

{
  "mcpServers": {
    "openspace": {
      "command": "$HOME/.agents/venvs/openspace/bin/openspace-mcp",
      "toolTimeout": 600,
      "env": {
        "OPENSPACE_HOST_SKILL_DIRS": "$HOME/.agents/skills",
        "OPENSPACE_WORKSPACE": "$HOME/.openspace/OpenSpace",
        "OPENSPACE_CLOUD_MODE": "local",
        "OPENSPACE_CLOUD_API_KEY": "sk-xxx (optional, for cloud)"
      }
    }
  }
}

OpenSpace は 3 つの起動モードをサポートしています。ローカルでの利用には stdio を推奨します。

• stdio — ホスト設定では command: "openspace-mcp" のままにします（最も簡単な方法です）
• SSE — openspace-mcp --transport sse --host 127.0.0.1 --port 8080 → エンドポイント http://127.0.0.1:8080/sse
• ストリーミング可能な HTTP — openspace-mcp --transport streamable-http --host 127.0.0.1 --port 8081 → エンドポイント http://127.0.0.1:8081/mcp

openspace-mcp --help が動作し、MCP クライアントから OpenSpace のツールを確認できるようになるまでは、インストール成功と報告しないでください。時間のかかる execute_task 呼び出しには、少なくとも 600 秒の toolTimeout が必要です。

ステップ 4：OpenSpace をいつ、どのように呼び出すかをエージェントに教える 2 つのホストスキルをコピーします

cp -r OpenSpace/openspace/host_skills/delegate-task/ /path/to/your/agent/skills/
cp -r OpenSpace/openspace/host_skills/skill-discovery/ /path/to/your/agent/skills/

skill-discovery/SKILL.md はホストエージェントにスキルの検索と発見方法を教えます。 delegate-task/SKILL.md は実行、修正、アップロードの方法を教えます。jeo-skills の場合は、 両方を $HOME/.agents/skills/ にコピーします（これは scripts/install-openspace.sh が自動で行います）。その後、追加のプロンプトは不要です。ホストエージェントは推測する代わりに、いつ OpenSpace を利用すべきかを認識できるようになります。

Step 5: タスクに適したスキルを取得・検出する

インストール後は、カタログを手作業で調べるのではなく、ホストエージェントに（openspace MCP ツールまたは skill-discovery を介して）現在のタスクに適したスキルを検索し、順位付けするよう依頼してください。 OpenSpace は、OPENSPACE_HOST_SKILL_DIRS、設定済みの skills.skill_dirs、.openspace/skills などのプロジェクトルート、~/.openspace/skills などのユーザールート、そして最後に独自の同梱先である openspace/skills の順でスキルを検出します。この優先順位に従います。検出されたすべてのスキルは、読み込み前に check_skill_safety を通過します。プロンプトインジェクションや認証情報の窃取など、危険なパターンを含むスキルはブロックされ、記録されます。

どちらの順位付け段階も実行時には任意で、失敗しても通知されません。 BM25 には OpenSpace の venv に rank_bm25 パッケージが必要です。セマンティックな再順位付けには、OpenAI 互換のキー（OPENAI_API_KEY／OPENROUTER_API_KEY、または nanobot／OpenClaw のホスト設定）が必要です。どちらもない場合でも、search_skills は引き続き応答しますが、すべての結果の score: 0.0 となり、順序は任意です。つまり、スキル検索機能は実質的に名前検索になります。順位付けが機能していなくても通る名前検索ではなく、必ず 意図を示すクエリ（"scrape a javascript rendered page" なら scrapling が表示されるはずです）で確認してください。

順位付けの詳細と、別の方法へ振り分ける際の判断については、references/skill-discovery-routing.md を参照してください。

Step 6: 実際の実行結果を根拠にスキルの品質を評価する

説明文がよく書けているからといって、スキルを信頼しないでください。OpenSpace の品質レイヤーは、スキルが 選択、適用、完了されたか、またはフォールバックしたか、そして基盤となるツールの信頼性が低下したり、遅くなったり、リスクが高まったりしていないかを追跡します。自己申告ではなく、実際のタスクでの挙動を根拠として使用します。

Step 7: 根拠がある場合にのみスキルを進化させる

OpenSpace は、次の 3 つの制御されたトリガーを通じてスキルを進化させます。

• FIX — 壊れたスキルや古くなったスキルを修復します
• DERIVED — 既存のスキルから、より優れたバージョンや、より専門化されたバージョンを作成します
• CAPTURED — 再利用可能なサブワークフローを 1 つ保存します。ただし、元のトレースに、その実行と、主張された事後条件の独立した検証の両方が記録されている場合に限ります

新規または進化したスキルは、デフォルトで 暫定 です。独立した利用が成功するとスキルは 信頼済み に昇格し、原因を特定できる失敗があると降格します。enabled は、この信頼性のライフサイクルとは独立して再利用を制御します。ブロックされた提案や確実性の低い提案は、監査専用の候補のままです。繰り返し発生しても、自動的に昇格することはありません。

詳細については、references/quality-and-evolution.md を参照してください。

Step 8: ローカル優先のハブを通じてスキルを共有またはインポートする

スキルの実行と進化は ローカル で行われます。クラウドは実行ではなく、検出とレビューに使用します。

openspace-download-skill  # download a skill from the cloud
openspace-upload-skill --skill-dir /path/to/skill/dir  # upload a trusted skill

クラウドへのアップロードには、対応するローカルの SkillStore レコードが trusted である必要があります。暫定または不明なレコードの場合、パブリックアップロードもプライベートアップロードも失敗として処理されます。ローカルの信頼状態自体がクラウドに送信されることはありません。任意のクラウドのブートストラップ：

openspace-cloud-auth bootstrap-agent-key --email [email protected] --agent-name openspace-local-agent

クラウドのブートストラップを行わなくても、すべてのローカル機能（タスク実行、進化、ローカルでのスキル検索）は通常どおり動作します。

Step 9: OpenSpace が適切なレイヤーではない場合は、正直に別の方法へ振り分ける

• 単純な grep／キーワードによるカタログ検索（順位付け／品質評価／進化が不要） → codebase-search または semble
• 長期的に保持する、統合済みの Markdown ナレッジ（スキルの選択ではない） → llm-wiki
• リポジトリごとのエージェントメモリ／引き継ぎメモ／意思決定ログ（スキルの選択ではない） → opencontext

例

例 1：OpenSpace をこのリポジトリのスキル検索レイヤーとしてインストールする

入力

OpenSpace を設定して、私が手動でスキルを指定しなくても、コーディングエージェントがインストール済みの 150 個のスキルから適切なスキルを見つけられるようにしてください。

出力の概要

• モード：install-as-skill-finder
• bash scripts/install-openspace.sh を実行します（クローン + pip install -e . + openspace-mcp --help による確認）
• bash scripts/register-openspace-mcp.sh を実行して、インストール済みのすべてのランタイムに openspace MCP サーバーを登録します（OPENSPACE_HOST_SKILL_DIRS=$HOME/.agents/skills、OPENSPACE_WORKSPACE=$HOME/.openspace/OpenSpace）
• skill-discovery/ と delegate-task/ を $HOME/.agents/skills/ にコピーします
• ツールが認識され、軽量なローカルスキル検索が機能することを確認します

例 2：タスクに適したスキルを見つける

入力

JS でレンダリングされるページをスクレイピングしたいのですが、インストール済みのスキルのうち、どれを使えばよいですか？

出力の概要

• モード：retrieve-a-skill
• OPENSPACE_HOST_SKILL_DIRS にあるスキルから「JS-rendered page scraping」を検索し、順位付けするよう OpenSpace に依頼します
• BM25 + 埋め込みのハイブリッド順位付けを使って、scrapling（または同等のスキル）が汎用的な候補より上位に表示され、その後、そのスキルの SKILL.md が読み込まれることを確認します

例 3：スキルの信頼性が保たれているか判断する

入力

deployment-automation スキルを 12 回使いました。実際にきちんと機能しているのでしょうか？

出力の概要

• モード：evaluate-skill-quality
• 実行記録を取得します：選択／適用／完了／フォールバックの各回数、ツールの信頼性シグナル
• スキル自身の説明を鵜呑みにせず、信頼ステータス（暫定または信頼済み）を報告します

例 4：実行してはいけない場合 — 通常のカタログ検索

入力

「playwright」と記載されているスキルを探すため、リポジトリを grep してください。

出力の概要

• モード：route-out
• これは通常のキーワード検索であり、スキルの順位付け／品質評価／進化ではありません。OpenSpace のインストールや呼び出しではなく、codebase-search／semble にルーティングします

ベストプラクティス

1. OpenSpace はスキルそのものの代替ではなく、スキル検索レイヤーとして位置付けます。OpenSpace が選定・評価し、エージェントが実行します。
2. このリポジトリでは OPENSPACE_HOST_SKILL_DIRS を $HOME/.agents/skills に設定し、実際にインストールされているカタログを対象に順位付けします。
3. ローカルの MCP 接続には stdio を優先します。ホストが stdio を使用できない場合や、スタンドアロン／リモートサーバーが必要な場合に限り、SSE／ストリーミング可能な HTTP を使用します。
4. スキルの説明文の出来ではなく、証拠（選択／適用／完了／フォールバック）に基づいて信頼します。
5. 進化は制御された状態に保ちます。FIX／DERIVED／CAPTURED と、暫定から信頼済みへの昇格を用い、黙って自動書き換えを行わないでください。
6. クラウドハブは検索専用として扱います。実行と信頼性の判断はローカルに保ち、アップロードには trusted ステータスが必要です。
7. 実際の作業がスキルの検索／品質評価／進化ではない場合は、codebase-search／semble、llm-wiki、または opencontext に適切にルーティングします。
8. openspace-mcp --help が動作し、MCP クライアントから OpenSpace のツールが見えるようになるまでは、インストール成功と報告しないでください。

参考資料

• インストールと MCP 接続設定
• スキルの検索とルーティング
• 品質と進化
• scripts/install-openspace.sh — 対話不要のインストーラー、ホストスキルのコピー、MCP 登録
• scripts/register-openspace-mcp.sh — インストール済みのすべてのランタイム設定に openspace MCP エントリーを統合します（claude / codex / gemini / cursor / opencode / kimi / glm / zai / deepseek / grok / qwen / pi / gjc / jeopi）
• OpenSpace GitHub リポジトリ