skill-system-installer

Skill Installer

技能系统的安装器和部署界面。

公开契约：

• 将 sk init（skill-system-cli）用作本仓库的主要引导入口。
• 使用 sk install deploy --target <path> 将 sidecar 高级附加到外部项目。
• scripts/skills.sh 仍是安装和部署操作的实现后端。

项目范围的 DB/MCP 指南

• 使用自动检测，让 PostgreSQL 支持的技能遵循项目范围的 DB 目标（<project>-memory）。
• 不要依赖 shell 全局变量 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（创建的内容）。

此操作具有幂等性，可安全地多次运行。若 Agent 检测到技能系统仅部分初始化，或用户要求设置技能，应运行此命令。

通信

列出精选技能时，显示可用的技能名称，以及当前范围内已安装的技能。

脚本

这些脚本都会使用网络，因此在沙盒中运行时，请申请提升权限。

• 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]（将 sidecar 部署到目标项目；默认生成仪表板）
• scripts/skills.sh dashboard --target <path>（生成目标项目的 dashboard/index.html）
• scripts/skills.sh host-shell <bootstrap|discover|compat|doctor> [--target <path>]（轻量级宿主插件 shell 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）
• 已部署项目中的 sidecar 技能系统痕迹
• 仪表板是否存在（dashboard/index.html），以及仪表板生成器技能入口
• 可选的数据库就绪信号（环境变量/配置及 psql 是否可用）

输出结构：

• status
• target
• checks
• recommended_actions
• healthy

仪表板（目标渲染）

运行 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

部署（Sidecar）

运行 scripts/skills.sh deploy --target /path/to/project [--mode minimal|local|full] [--no-dashboard]，将当前 skill-system 仓库作为 Sidecar 部署到目标项目中。

部署行为：

• 创建或复用目标项目的 .skill-system/，作为受管理的 Sidecar 根目录
• 将 skill-system 资源复制到 Sidecar 中，且不覆盖已有的 Sidecar 文件
• 为目标项目补建缺失的 config/、note/、.tkt/ 和 skills-lock.json
• 将可变的目标状态链接回 Sidecar，使 Sidecar 工具操作目标项目状态
• 确保目标项目的 skills 指向 Sidecar 的 skills，以满足现有 CLI/仪表板的路径预期
• 默认生成 dashboard/index.html；使用 --no-dashboard 可跳过
• 部署后运行 doctor --target 并返回健康状况摘要
• 输出 dashboard_onboarding 负载字段，使用户可以立即运行 /SK-dashboard 或对应的 CLI 命令

精简宿主插件 Shell MVP

安装程序附带了一个最小化宿主 Shell 适配器，用于验证组合边界，同时不接管现有模块。

入口：

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

边界保证：

• Memory 仍以模块为先（mem.py + MCP）。插件行为是可选的适配器逻辑。
• 控制平面仍由 skill-system-tkt 和 skill-system-review 负责。
• 规划仍由 skill-system-workflow 负责。
• 图谱/仪表板/调试仍由各自现有模块负责。

此 Shell 有意保持为 MVP，而非平台重新设计。

更新

使用 scripts/update-skills.py，将已安装的技能目录与 skills-lock.json 中的哈希值进行比较。

• --all 检查所有已锁定的技能；--skill <name> 检查单个技能。
• 添加 --update 可重新安装缺失或存在偏差的技能，并刷新 computedHash。
• 添加 --dry-run 可报告计划执行的更新，而不做任何更改。
• --preserve-insight/--no-preserve-insight 控制本地洞察保留合并行为（默认启用 --preserve-insight）。
• 可选：--lockfile <path> 和 --skills-dir <path>。

启用保留模式时，更新过程会执行三方合并：

原始基线 -> 本地修改 -> 上游新版

冲突不会自动合并。冲突标记会写入文件，供用户检查。

行为和选项

• 对公开的 GitHub 仓库，默认直接下载。
• 如果下载因身份验证/权限错误而失败，则回退到 git 稀疏检出。
• 如果目标技能目录已存在，则中止操作，除非设置了 --force。
• 全局安装使用 $SKILLS_GLOBAL_HOME/skills/<skill-name>（默认路径为 ~/.skills-system/skills）。
• 多个 --path 值可在一次运行中安装多个技能；除非提供 --name，否则每个技能均以路径的基本名称命名。
• 选项：--ref <ref>（默认值为 main）、--dest <path>、--method auto|download|git、--force。

备注

• 精选列表通过 GitHub API 从 https://github.com/openai/skills/tree/main/skills/.curated 获取。如果无法获取，请说明错误并退出。
• 可通过现有 git 凭据或可选的 GITHUB_TOKEN/GH_TOKEN 访问私有 GitHub 仓库以进行下载。
• 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
  }
}