skill-catalog/skills/skill-catalog/SKILL.md

platforms
darwin linux

skill-catalog

把「对外发布的技能」发布成一个自托管目录站（https://pi.vhkd.top）：每个技能一页，写清能干什么、 先装什么、要配什么、依赖谁、一条安装命令。线上是 serve.mjs 常驻进程（Node HTTP，从 catalog.json 每次请求现渲染，带 /api/skills 与 /healthz）；build 另落一份同源静态快照（过渡与回退用）。 页面由声明生成，永不手改。

收录规则：只有 interface.json 里声明了 publish 的技能才上页（见 skill-interface 的 REFERENCE §12）。依赖里出现未公开的技能会在页面上标出来且不给安装命令。

首次使用

1. 想公开的技能，在它的 interface.json 里声明 publish（repo 是 CLI 仓，包仓名默认去 -cli）；
2. pi-skill skill-catalog check —— 看收录规则、部署目标与线上健康（缺 deploy_path 会告诉你）；
3. pi-skill skill-catalog build 生成，pi-skill skill-catalog preview 本地动态预览；
4. pi-skill skill-catalog deploy 发布（relay→host 两跳，release 目录 + current 软链切换； 内容切换不用重启，代码变了 deploy 会踢一下 systemd 进程）。

服务器托管（一次性）：目标机要跑 serve.mjs 的 systemd 单元、Caddy 用 reverse_proxy 127.0.0.1:8788 反代；scripts/setup-hosting.sh 幂等完成（含没有 Node 时自动装）， 见 REFERENCE「托管」。

页面上的隐私边界

• 只出现声明元数据：摘要、用法、命令、依赖、要配的键名（不含值）、版本、仓库地址；
• 不渲染 REFERENCE 全文，设置值一概不上页；
• 生成后整站过一遍泄漏扫描（密钥 / 真实家目录 / 工单号），error 级直接拒绝产出；
• 上服务器的只有公开快照（catalog.json + assets + 服务代码），没有 skills 仓库。

失败 → 动作

• error=usage → pi-skill skill-catalog help；
• 生成被拦（blocked: …）→ 检查技能声明里是否混进了密钥或真实家目录，页面只该出现声明元数据；
• 部署失败 → 确认 deploy_relay/deploy_host 能 ssh、deploy_path 可写；
• 线上 502 或 /healthz 不是 JSON → 看目标机 systemctl status pi-hub 与 journalctl -u pi-hub -n 50； 一次性配置见 REFERENCE §4。