skill-system-installer

スキルインストーラー

スキルシステムのインストールおよびデプロイ用インターフェースです。

公開契約：

• このリポジトリの主要なブートストラップエントリーポイントとして、sk init（skill-system-cli）を使用してください。
• 外部プロジェクトへの高度なサイドカー接続には、sk install deploy --target <path>を使用してください。
• scripts/skills.shは、インストーラーおよびデプロイ操作の実装バックエンドとして引き続き使用します。

プロジェクトスコープのDB/MCPガイダンス

• PostgreSQLを利用するスキルでは、自動検出によるプロジェクトスコープのDBターゲティング（<project>-memory）に従ってください。
• シェル全体に適用されるSKILL_PGDATABASEには依存せず、必要な場合に限りプロジェクトローカルのオーバーライドを優先してください。
• 環境に設定されたPGDATABASEによって、スキルの実行時のDBターゲットが暗黙的に変更されないようにしてください。
• グローバルインストール構成では、MCP サーバーのエントリーに絶対パスのスキルパスを使用してください。

タスクに応じて、ヘルパースクリプトを使用してください。

• 利用可能なスキルについてユーザーから尋ねられた場合、またはユーザーがこのスキルを使用するものの、何をすべきか指定していない場合は、厳選されたスキルの一覧を表示します。
• ユーザーがスキル名を指定した場合は、厳選された一覧からインストールします。
• ユーザーがGitHubリポジトリまたはパス（プライベートリポジトリを含む）を指定した場合は、別のリポジトリからインストールします。

ヘルパースクリプトを使用してスキルをインストールしてください。

ブートストラップ（初回実行時）

scripts/skills.sh bootstrapを実行して、スキルシステムを検出し、ひな形を作成します。

1. 検出：不足している構造（config/、note/、.tkt/、skills-lock.json）
2. ひな形の作成：不足しているディレクトリにスタブファイルを追加
3. ハッシュの計算：skills-lock.json内の"pending"エントリーのハッシュを計算
4. 検証：インストール済みのすべてのスキルにSKILL.mdがあることを確認
5. 確認：依存関係（python3、git、bash）

scripts/skills.sh bootstrap
# or via sk CLI:
sk install bootstrap

出力はJSON形式で、検出された内容を示すchecksと、作成されたものを示すactions_takenが含まれます。

この処理は冪等で、複数回実行しても安全です。スキルシステムが一部だけ初期化されていることを検出した場合、またはユーザーからスキルのセットアップを依頼された場合、エージェントはこれを実行してください。

コミュニケーション

厳選されたスキルを一覧表示する際は、利用可能な名前と、現在のスコープにすでにインストールされているスキルを示してください。

スクリプト

これらのスクリプトはすべてネットワークを使用するため、サンドボックス内で実行する場合は、実行時に権限昇格を要求してください。

• scripts/list-curated-skills.py（インストール済みの注記付きで厳選リストを出力）
• scripts/list-curated-skills.py --format json
• scripts/skills.sh（インストール、一覧表示、更新、同期、デプロイ用の統合ラッパー）
• scripts/skills.sh doctor --target <path>（変更を加えずに事前チェックを実行）
• scripts/skills.sh deploy --target <path> [--mode minimal|local|full] [--no-dashboard]（ターゲットプロジェクトにサイドカーをデプロイ。デフォルトではダッシュボードを生成）
• scripts/skills.sh dashboard --target <path>（ターゲットのdashboard/index.htmlを生成）
• scripts/skills.sh host-shell <bootstrap|discover|compat|doctor> [--target <path>]（ホストプラグイン向けの軽量なシェルMVP）
• scripts/install-skill-from-github.py --repo <owner>/<repo> --path <path/to/skill> [<path/to/skill> ...]
• scripts/install-skill-from-github.py --url https://github.com/<owner>/<repo>/tree/<ref>/<path>
• scripts/update-skills.py --all
• scripts/update-skills.py --skill <skill-name> [--update] [--dry-run]

Doctor（事前チェック）

scripts/skills.sh doctor --target /path/to/projectを実行して、ターゲットプロジェクトを変更せずに調査します。

Doctorは以下を報告します。

• ターゲットの存在、ディレクトリの種類、書き込み可能かどうか
• gitバイナリおよびリポジトリの有無
• 必須構造（config/、note/、.tkt/、skills-lock.json）の有無
• デプロイ済みプロジェクトのサイドカースキルシステムの構成
• ダッシュボード（dashboard/index.html）およびダッシュボード生成スキルのエントリーポイントの有無
• オプションのデータベース準備状況（環境変数／設定およびpsqlの利用可否）

出力の構成：

• status
• target
• checks
• recommended_actions
• healthy

ダッシュボード（ターゲットのレンダリング）

/path/to/project を対象にダッシュボードを生成するには、scripts/skills.sh dashboard --target /path/to/project を実行します。

ダッシュボードの生成動作：

• skills/skill-system-dashboard/scripts/generate.py を唯一のレンダリング元として再利用します
• ターゲットプロジェクトのコンテキスト（skills/、.tkt/、.memory/、および任意の .env／.env.local のデータベース URL）を読み取ります
• デフォルトでは <target>/dashboard/index.html に出力を書き込みます
• ターゲットの構造が欠けていても、失敗する代わりに空のセクションをレンダリングします
• 構造化 JSON（status、output、target を含む）を返します
• /SK-dashboard を sk dashboard に対応付ける、ワンクリック起動の案内を含みます

デプロイ（サイドカー）

現在のスキルシステムリポジトリをターゲットプロジェクトにサイドカーとしてデプロイするには、scripts/skills.sh deploy --target /path/to/project [--mode minimal|local|full] [--no-dashboard] を実行します。

デプロイの動作：

• 管理対象のサイドカールートとして、ターゲットの .skill-system/ を作成または再利用します
• 既存のサイドカーファイルを上書きせずに、スキルシステムのアセットをサイドカーにコピーします
• ターゲットに不足している config/、note/、.tkt/、skills-lock.json を作成します
• 変更可能なターゲットの状態をサイドカーにリンクし、サイドカーのツールがターゲットプロジェクトの状態を操作できるようにします
• 既存の CLI／ダッシュボードのパス要件に合わせ、ターゲットの skills がサイドカーの skills を参照するようにします
• デフォルトで dashboard/index.html を生成します。スキップするには --no-dashboard を使用します
• デプロイ後に doctor --target を実行し、ヘルスサマリーを返します
• ユーザーがすぐに /SK-dashboard または同等の CLI コマンドを実行できるよう、dashboard_onboarding ペイロードのフィールドを出力します

薄型ホストプラグインシェルの MVP

インストーラーには、既存モジュールの所有権を奪うことなく構成の境界を検証するための、最小限のホストシェルアダプターが含まれています。

エントリーポイント：

scripts/skills.sh host-shell bootstrap --target /path/to/project
scripts/skills.sh host-shell discover --target /path/to/project
scripts/skills.sh host-shell compat
scripts/skills.sh host-shell doctor --target /path/to/project

境界に関する保証：

• メモリーは引き続きモジュールファーストです（mem.py + MCP）。プラグインの動作は任意のアダプターロジックです。
• コントロールプレーンの所有権は、引き続き skill-system-tkt と skill-system-review にあります。
• 計画の所有権は、引き続き skill-system-workflow にあります。
• グラフ／ダッシュボード／デバッグの所有権は、引き続きそれぞれの既存モジュールにあります。

これは意図的に MVP シェルとして設計されており、プラットフォームの再設計ではありません。

更新

skills-lock.json のハッシュとインストール済みスキルディレクトリを比較するには、scripts/update-skills.py を使用します。

• --all はロックされたすべてのスキルをチェックし、--skill <name> は1つのスキルをチェックします。
• --update を追加すると、不足または差異のあるスキルを再インストールし、computedHash を更新します。
• --dry-run を追加すると、変更を加えずに予定されている更新を報告します。
• --preserve-insight/--no-preserve-insight は、ローカルのインサイトを保持するマージ動作を制御します（デフォルトは --preserve-insight の true）。
• 任意のオプション：--lockfile <path> および --skills-dir <path>。

保持モードを有効にして更新を実行すると、インストーラーは3方向マージを行います。

original baseline -> local modified -> upstream new

競合は自動マージされません。ユーザーが確認できるように、競合マーカーが書き込まれます。

動作とオプション

• 公開 GitHub リポジトリでは、デフォルトで直接ダウンロードします。
• 認証／権限エラーでダウンロードに失敗すると、git のスパースチェックアウトにフォールバックします。
• --force が設定されていない場合、インストール先のスキルディレクトリがすでに存在すると中止します。
• グローバルインストール先は $SKILLS_GLOBAL_HOME/skills/<skill-name> です（デフォルトは ~/.skills-system/skills）。
• 複数の --path 値を指定すると、1回の実行で複数のスキルをインストールします。--name を指定しない場合、それぞれの名前にはパスのベース名が使われます。
• オプション：--ref <ref>（デフォルトは main）、--dest <path>、--method auto|download|git、--force。

注記

• 厳選された一覧は、GitHub API を介して https://github.com/openai/skills/tree/main/skills/.curated から取得されます。利用できない場合は、エラーを説明して終了します。
• プライベート GitHub リポジトリには、既存の git 認証情報、またはダウンロード用の任意の GITHUB_TOKEN／GH_TOKEN を使ってアクセスできます。
• Git のフォールバックでは、まず HTTPS を試し、次に SSH を試します。
• インストール済みの注釈は、スコープ付きスキルディレクトリ（$SKILLS_GLOBAL_HOME/skills およびプロジェクトローカルの skills/）から取得されます。

{
  "schema_version": "2.0",
  "id": "skill-system-installer",
  "version": "1.0.0",
  "capabilities": ["skill-install", "skill-list", "skill-update", "skill-status", "skill-sync", "skill-bootstrap", "skill-doctor", "skill-dashboard", "skill-deploy"],
  "effects": ["net.fetch", "fs.write", "fs.read", "proc.exec"],
  "operations": {
    "bootstrap": {
      "description": "First-run setup: detect missing structure, scaffold directories, compute pending lockfile hashes, validate skills.",
      "input": {},
      "output": {
        "description": "Bootstrap report with checks and actions taken",
        "fields": { "checks": "object", "actions_taken": "array" }
      },
      "entrypoints": {
        "unix": ["bash", "scripts/skills.sh", "bootstrap"]
      }
    },
    "doctor": {
      "description": "Detect-only preflight checks for a target project. Reports readiness and recommended actions without changing files.",
      "input": {
        "target": { "type": "string", "required": false, "default": ".", "description": "Target project directory to inspect" }
      },
      "output": {
        "description": "Preflight report",
        "fields": {
          "status": "ok | error",
          "target": "string",
          "checks": "object",
          "recommended_actions": "array",
          "healthy": "boolean"
        }
      },
      "entrypoints": {
        "unix": ["bash", "scripts/skills.sh", "doctor", "--target", "{target}"]
      }
    },
    "dashboard": {
      "description": "Generate target dashboard/index.html using target project context and tolerant empty-section rendering.",
      "input": {
        "target": { "type": "string", "required": false, "default": ".", "description": "Target project directory" }
      },
      "output": {
        "description": "Dashboard generation report",
        "fields": {
          "status": "ok | error",
          "output": "string",
          "target": "string"
        }
      },
      "entrypoints": {
        "unix": ["bash", "scripts/skills.sh", "dashboard", "--target", "{target}"]
      }
    },
    "deploy": {
      "description": "Deploy the current skill-system repo as a sidecar into a target project and report post-deploy health.",
      "input": {
        "target": { "type": "string", "required": true, "description": "Target project directory" },
        "mode": { "type": "string", "required": false, "default": "full", "description": "Bootstrap profile: minimal, local, or full" },
        "dashboard": { "type": "boolean", "required": false, "default": false, "description": "Generate dashboard/index.html after deploy" }
      },
      "output": {
        "description": "Deploy report with paths, actions taken, and doctor health summary",
        "fields": {
          "status": "ok | error",
          "target": "string",
          "sidecar": "string",
          "deployed_paths": "object",
          "actions_taken": "array",
          "health_summary": "object"
        }
      },
      "entrypoints": {
        "unix": ["bash", "scripts/skills.sh", "deploy", "--target", "{target}", "--mode", "{mode}"]
      }
    },
    "list": {
      "description": "List available curated skills with installed annotations and show local/global installed skills.",
      "input": {
        "format": { "type": "string", "required": false, "default": "text", "description": "Output format: text or json" }
      },
      "output": {
        "description": "List of curated skills with install status",
        "fields": { "skills": "array of {name, installed}" }
      },
      "entrypoints": {
        "unix": ["python3", "scripts/list-curated-skills.py", "--format", "{format}"],
        "windows": ["python", "scripts/list-curated-skills.py", "--format", "{format}"]
      }
    },
    "install": {
      "description": "Install a skill from GitHub repo path. The scripts/skills.sh wrapper provides a scoped alternative entrypoint.",
      "input": {
        "repo": { "type": "string", "required": true, "description": "GitHub owner/repo" },
        "path": { "type": "string", "required": true, "description": "Path to skill within repo" }
      },
      "output": {
        "description": "Installed skill path",
        "fields": { "installed_path": "string" }
      },
      "entrypoints": {
        "unix": ["python3", "scripts/install-skill-from-github.py", "--repo", "{repo}", "--path", "{path}"],
        "windows": ["python", "scripts/install-skill-from-github.py", "--repo", "{repo}", "--path", "{path}"],
        "unix_wrapper": ["bash", "scripts/skills.sh", "install", "--repo", "{repo}", "--path", "{path}"]
      }
    },
    "update": {
      "description": "Check skill drift against lockfile and optionally update drifted skills.",
      "input": {
        "scope": { "type": "string", "required": true, "description": "Either all or one" },
        "skill": { "type": "string", "required": false, "description": "Skill name when scope is one" },
        "apply": { "type": "boolean", "required": false, "default": false, "description": "Apply updates when true" },
        "dry_run": { "type": "boolean", "required": false, "default": false, "description": "Report only" },
        "preserve_insight": { "type": "boolean", "required": false, "default": true, "description": "Preserve local insight edits via 3-way merge with conflict markers" }
      },
      "output": {
        "description": "Drift report and optional update actions",
        "fields": { "status": "ok | error", "table": "skill_name/local_hash/lock_hash/status" }
      },
      "entrypoints": {
        "unix": ["python3", "scripts/update-skills.py", "--all"],
        "windows": ["python", "scripts/update-skills.py", "--all"]
      }
    },
    "status": {
      "description": "Report drift/version status and spec-compatibility warnings.",
      "input": {
        "scope": { "type": "string", "required": false, "description": "global or local", "default": "local" },
        "skill": { "type": "string", "required": false, "description": "Optional skill name" }
      },
      "output": {
        "description": "Status rows with warning details",
        "fields": { "status": "ok | error", "skills": "array" }
      },
      "entrypoints": {
        "unix": ["bash", "scripts/skills.sh", "status"],
        "windows": ["bash", "scripts/skills.sh", "status"]
      }
    },
    "sync": {
      "description": "Synchronize global skills into the local workspace.",
      "input": {
        "strategy": { "type": "string", "required": false, "default": "copy", "description": "Sync strategy: copy or symlink" },
        "force": { "type": "boolean", "required": false, "default": false, "description": "Overwrite existing local skills when true" },
        "skills": { "type": "string", "required": false, "description": "Comma-separated skill names" }
      },
      "output": {
        "description": "Sync report and updated local lockfile",
        "fields": { "status": "ok | error", "skills": "array of synced or skipped skill names" }
      },
      "entrypoints": {
        "unix": ["bash", "scripts/skills.sh", "sync"]
      }
    }
  },
  "stdout_contract": {
    "last_line_json": false
  }
}