skill-system-installer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Installer

Skill 安装器

Installer and deploy surface for the skill system.

Public contract:

Use
```
sk init
```
(
```
skill-system-cli
```
) as the primary bootstrap entrypoint for this repository.
Use
```
sk install deploy --target <path>
```
for advanced sidecar attachment into external projects.
```
scripts/skills.sh
```
remains the implementation backend for installer/deploy operations.

Skill系统的安装与部署工具集。

公开约定：

使用
```
sk init
```
（即
```
skill-system-cli
```
）作为本仓库的主要初始化入口。
使用
```
sk install deploy --target <path>
```
实现向外部项目的高级边车挂载。
```
scripts/skills.sh
```
仍是安装/部署操作的底层实现脚本。

Project-Scoped DB/MCP Guidance

项目级DB/MCP指导规范

PostgreSQL-backed skills should follow project-scoped DB targeting (
```
<project>-memory
```
) by auto-detection.
Do not rely on shell-global
```
SKILL_PGDATABASE
```
; prefer project-local overrides only when required.
Do not allow ambient
```
PGDATABASE
```
to silently steer skill runtime DB targets.
MCP server entries should use absolute skill paths in globally-installed setups.

Use the helper scripts based on the task:

List curated skills when the user asks what is available, or if the user uses this skill without specifying what to do.
Install from the curated list when the user provides a skill name.
Install from another repo when the user provides a GitHub repo/path (including private repos).

Install skills with the helper scripts.

基于PostgreSQL的Skill应通过自动检测遵循项目级DB目标（格式为
```
<project>-memory
```
）。
不要依赖全局环境变量
```
SKILL_PGDATABASE
```
；仅在必要时使用项目本地覆盖配置。
不允许环境变量
```
PGDATABASE
```
默认控制Skill运行时的DB目标。
在全局安装环境中，MCP服务器条目应使用Skill的绝对路径。

根据任务选择对应辅助脚本：

当用户询问可用Skill，或未指定具体操作时，列出精选Skill。
当用户提供Skill名称时，从精选列表中安装。
当用户提供GitHub仓库/路径（包括私有仓库）时，从对应仓库安装Skill。

使用辅助脚本安装Skill。

Bootstrap (First-Run)

初始化（首次运行）

Run

scripts/skills.sh bootstrap

to detect and scaffold the skill system:

Detect missing structure:
```
config/
```
,
```
note/
```
,
```
.tkt/
```
,
```
skills-lock.json
```
Scaffold any missing directories with stub files
Compute hashes for any
```
"pending"
```
entries in
```
skills-lock.json
```
Validate all installed skills have
```
SKILL.md
```
Check dependencies (
```
python3
```
,
```
git
```
,
```
bash
```
)

bash

scripts/skills.sh bootstrap

执行

scripts/skills.sh bootstrap

来检测并搭建Skill系统：

检测缺失结构：
```
config/
```
、
```
note/
```
、
```
.tkt/
```
、
```
skills-lock.json
```
搭建任何缺失的目录并生成占位文件
计算
```
skills-lock.json
```
中所有
```
"pending"
```
条目的哈希值
验证所有已安装Skill均包含
```
SKILL.md
```
文件
检查依赖项（
```
python3
```
、
```
git
```
、
```
bash
```
）

bash

scripts/skills.sh bootstrap

or via sk CLI:

或通过sk CLI执行：

sk install bootstrap


Output is JSON with `checks` (what was found) and `actions_taken` (what was created).

This is idempotent — safe to run multiple times. Agents should run it when they detect the skill system is partially initialized or when a user asks to set up skills.

sk install bootstrap


输出为包含`checks`（检测结果）和`actions_taken`（执行操作）的JSON格式数据。

该操作具有幂等性——可安全重复执行。当Agent检测到Skill系统未完全初始化，或用户要求设置Skill时，应执行此操作。

Communication

交互逻辑

When listing curated skills, show available names and which ones are already installed in the current scope.

列出精选Skill时，需显示可用Skill名称及当前环境中已安装的Skill。

Scripts

脚本列表

All of these scripts use network, so when running in the sandbox, request escalation when running them.

```
scripts/list-curated-skills.py
```
(prints curated list with installed annotations)

scripts/list-curated-skills.py --format json

```
scripts/skills.sh
```
(unified wrapper for install, list, update, sync, deploy)

scripts/skills.sh doctor --target <path>

(detect-only preflight checks)

scripts/skills.sh deploy --target <path> [--mode minimal|local|full] [--no-dashboard]

(sidecar deploy into a target project; dashboard generated by default)

scripts/skills.sh dashboard --target <path>

(generate target dashboard/index.html)

scripts/skills.sh host-shell <bootstrap|discover|compat|doctor> [--target <path>]

(thin host plugin 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]

所有以下脚本均需联网，因此在沙箱环境中运行时，需申请权限升级。

```
scripts/list-curated-skills.py
```
（打印带安装状态标注的精选Skill列表）

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>

（为目标项目生成仪表盘

index.html

）

scripts/skills.sh host-shell <bootstrap|discover|compat|doctor> [--target <path>]

（轻量宿主插件外壳最小可行版本）

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 (Preflight)

预检（Doctor）

Run

scripts/skills.sh doctor --target /path/to/project

to inspect a target project without modifying it.

Doctor reports:

target existence, directory type, and writability
git binary/repo signal
required structure presence (
```
config/
```
,
```
note/
```
,
```
.tkt/
```
,
```
skills-lock.json
```
)
sidecar skill-system footprint for deployed projects
dashboard presence (
```
dashboard/index.html
```
) and dashboard generator skill entrypoint
optional database readiness signal (env/config + psql availability)

Output shape:

```
status
```
```
target
```
```
checks
```
```
recommended_actions
```
```
healthy
```

执行

scripts/skills.sh doctor --target /path/to/project

可检查目标项目状态，且不会修改项目文件。

预检报告包含：

目标路径的存在性、目录类型及可写性
Git二进制文件/仓库状态
必要结构的存在性（
```
config/
```
、
```
note/
```
、
```
.tkt/
```
、
```
skills-lock.json
```
）
已部署项目的边车Skill系统痕迹
仪表盘存在性（
```
dashboard/index.html
```
）及仪表盘生成器Skill入口
可选的数据库就绪状态（环境/配置+psql可用性）

输出结构：

```
status
```
```
target
```
```
checks
```
```
recommended_actions
```
```
healthy
```

Dashboard (Target Render)

仪表盘（目标渲染）

Run

scripts/skills.sh dashboard --target /path/to/project

to generate a dashboard for a target project.

Dashboard generation behavior:

reuses

skills/skill-system-dashboard/scripts/generate.py

as the single rendering source

reads target project context (
```
skills/
```
,
```
.tkt/
```
,
```
.memory/
```
, and optional
```
.env
```
/
```
.env.local
```
database URL)
writes output to
```
<target>/dashboard/index.html
```
by default
tolerates missing target structures by rendering empty sections instead of failing
returns structured JSON (including
```
status
```
,
```
output
```
, and
```
target
```
)

执行

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
```
）

Deploy (Sidecar)

部署（边车模式）

Run

scripts/skills.sh deploy --target /path/to/project [--mode minimal|local|full] [--no-dashboard]

to deploy the current skill-system repo as a sidecar into a target project.

Deploy behavior:

creates or reuses target
```
.skill-system/
```
as the managed sidecar root
copies skill-system assets into the sidecar without overwriting existing sidecar files
scaffolds missing target
```
config/
```
,
```
note/
```
,
```
.tkt/
```
, and
```
skills-lock.json
```
links mutable target state back into the sidecar so sidecar tools operate on target project state
ensures target
```
skills
```
resolves to sidecar
```
skills
```
for existing CLI/dashboard path expectations
generates dashboard/index.html by default; use
```
--no-dashboard
```
to skip
runs
```
doctor --target
```
after deployment and returns a health summary

执行

scripts/skills.sh deploy --target /path/to/project [--mode minimal|local|full] [--no-dashboard]

可将当前Skill系统仓库作为边车部署到目标项目中。

部署逻辑：

创建或复用目标项目下的
```
.skill-system/
```
作为托管边车根目录
将Skill系统资源复制到边车目录，不会覆盖边车中已有的文件
为目标项目搭建缺失的
```
config/
```
、
```
note/
```
、
```
.tkt/
```
及
```
skills-lock.json
```
将目标项目的可变状态链接到边车目录，使边车工具可操作目标项目状态
确保目标项目的
```
skills
```
路径指向边车的
```
skills
```
目录，以符合现有CLI/仪表盘的路径预期
默认生成
```
dashboard/index.html
```
；使用
```
--no-dashboard
```
可跳过此步骤
部署完成后执行
```
doctor --target
```
并返回健康状态摘要

Thin Host Plugin Shell MVP

轻量宿主插件外壳最小可行版本（MVP）

The installer ships a minimal host-shell adapter to validate composition boundaries without taking ownership from existing modules.

Entry:

bash

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

Boundary guarantees:

Memory remains module-first (
```
mem.py
```
+ MCP). Plugin behavior is optional adapter logic.
Control-plane ownership remains with
```
skill-system-tkt
```
and
```
skill-system-review
```
.
Planning ownership remains with
```
skill-system-workflow
```
.
Graph/dashboard/debug ownership remains with their existing modules.

This is intentionally an MVP shell and not a platform redesign.

本安装器提供了一个轻量宿主插件外壳，用于验证组合边界，且不会接管现有模块的控制权。

入口命令：

bash

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外壳，而非平台重设计。

Update

更新

Use

scripts/update-skills.py

to compare installed skill directories with hashes from

skills-lock.json

```
--all
```
checks every locked skill;
```
--skill <name>
```
checks one skill.
Add
```
--update
```
to reinstall missing/drifted skills and refresh
```
computedHash
```
.
Add
```
--dry-run
```
to report planned updates without making changes.
```
--preserve-insight/--no-preserve-insight
```
controls local insight-preservation merge behavior (
```
--preserve-insight
```
default true).
Optional:
```
--lockfile <path>
```
and
```
--skills-dir <path>
```
.

When update runs with preserve mode enabled, the installer performs a 3-way merge:

original baseline -> local modified -> upstream new

Conflicts are never auto-merged. Conflict markers are written for user review.

使用

scripts/update-skills.py

可对比已安装Skill目录与

skills-lock.json

中的哈希值。

```
--all
```
检查所有已锁定的Skill；
```
--skill <name>
```
检查单个Skill。
添加
```
--update
```
可重新安装缺失/偏离的Skill并刷新
```
computedHash
```
。
添加
```
--dry-run
```
可报告计划执行的更新，但不会实际修改。
```
--preserve-insight/--no-preserve-insight
```
控制本地洞察信息的合并保留行为（默认
```
--preserve-insight
```
为true）。
可选参数：
```
--lockfile <path>
```
和
```
--skills-dir <path>
```
。

当更新操作启用保留模式时，安装器会执行三方合并：

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

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

Behavior and Options

行为与选项

Defaults to direct download for public GitHub repos.
If download fails with auth/permission errors, falls back to git sparse checkout.
Aborts if the destination skill directory already exists unless
```
--force
```
is set.

Global installs use

$SKILLS_GLOBAL_HOME/skills/<skill-name>

(default

~/.skills-system/skills

Multiple
```
--path
```
values install multiple skills in one run, each named from the path basename unless
```
--name
```
is supplied.

Options:

--ref <ref>

(default

main

--dest <path>

--method auto|download|git

--force

公共GitHub仓库默认使用直接下载方式。
若下载因权限/认证失败，会 fallback 到Git稀疏检出方式。
若目标Skill目录已存在，除非设置
```
--force
```
，否则会中止操作。

全局安装会使用

$SKILLS_GLOBAL_HOME/skills/<skill-name>

（默认路径为

~/.skills-system/skills

）。

多个
```
--path
```
参数可在一次运行中安装多个Skill，每个Skill默认以路径的basename命名，也可通过
```
--name
```
指定名称。

可选参数：

--ref <ref>

（默认

main

）、

--dest <path>

、

--method auto|download|git

、

--force

。

Notes

注意事项

Curated listing is fetched from
```
https://github.com/openai/skills/tree/main/skills/.curated
```
via the GitHub API. If it is unavailable, explain the error and exit.
Private GitHub repos can be accessed via existing git credentials or optional
```
GITHUB_TOKEN
```
/
```
GH_TOKEN
```
for download.
Git fallback tries HTTPS first, then SSH.
Installed annotations come from scoped skill directories (
```
$SKILLS_GLOBAL_HOME/skills
```
and project-local
```
skills/
```
).

skill

{
  "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
  }
}

精选列表通过GitHub API从
```
https://github.com/openai/skills/tree/main/skills/.curated
```
获取。若无法访问，需说明错误并退出。
私有GitHub仓库可通过现有Git凭据或可选的
```
GITHUB_TOKEN
```
/
```
GH_TOKEN
```
进行访问下载。
Git fallback 会先尝试HTTPS，再尝试SSH。
安装状态标注来自作用域内的Skill目录（
```
$SKILLS_GLOBAL_HOME/skills
```
和项目本地的
```
skills/
```
）。

skill

{
  "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
  }
}