Publish npm + ClawHub

Publish OpenClaw skills or plugins to npm and ClawHub with a guarded workflow. Use this whenever the user asks to release, publish, ship, or republish a skil...

Security Scan

The skill's code, instructions, and requirements are coherent with its stated purpose (guarded publishing to npm and ClawHub); no disproportionate credential access, unexpected network exfiltration, or risky install behavior is present.

Purpose & Capability

The skill is designed to prepare a temporary release directory, run local checks, and guide explicit npm / clawhub publish steps; the included scripts (release_guard.py + pattern rules) match that purpose. Minor metadata inconsistency: SKILL.md lists required tools (python3, git, clawhub, curl and implicitly npm) but the registry metadata declares no required binaries — this is a documentation/metadata mismatch but doesn't indicate hidden behavior.

Instruction Scope

SKILL.md instructs only repository-local actions (reading references, running scripts, preparing a temp release dir, and executing explicit npm/clawhub commands). The release_guard.py implementation performs file scanning, git calls, and selective copying; it does not perform network calls or request external endpoints. The instructions emphasize keeping real accounts in a local (gitignored) config file and not uploading secrets.

Install Mechanism

There is no install spec (instruction-only skill) and all code files are bundled in the skill. No remote downloads or archive extraction are performed by an install step, so the install risk is low.

Credentials

The skill requests no environment variables or primary credentials and relies on a local config (config/publish.accounts.local.json) which the docs require to be gitignored. That is proportionate to a publishing helper. Note: the skill will call local CLIs (clawhub, npm, git) at runtime per instructions, so those tools and any credentials they use remain the user's responsibility.

Persistence & Privilege

The skill is user-invocable, not forced-always, and does not request persistent system-wide privileges or modify other skills. It performs only repository-local checks and copies into a temporary release directory.

Assessment

This skill is coherent for preparing and validating npm/ClawHub releases, but check these before using it: 1) Confirm your environment provides python3, git, npm, clawhub, and curl (SKILL.md lists them — metadata omitted them). 2) Create config/publish.accounts.local.json from the example and ensure it's in .gitignore; never commit it. 3) Inspect scripts/release_guard.py outputs (run with a safe repo copy and the --prepare-release-dir dry-run if available) — it uses subprocess to run git and copies files into a temp dir, but does not perform network calls itself. 4) When you run publishing steps (npm publish, clawhub publish) you will invoke CLIs that may use/require credentials; ensure those credentials are handled locally and not uploaded. 5) If you are concerned about sensitive files in the repo, run the release guard on a disposable clone first and review the list of files it plans to include/exclude. Overall the skill appears to do what it claims; pay attention to the small documentation/metadata mismatch about required tools and to safe handling of your local publish account file.

Version: 1.0.6 · License: Apache-2.0 · Author: jianghaibo

Required tools: Read, Write, Bash · Requires: python3, git, clawhub, curl

这个 skill 用来把“容易出错的发布流程”变成固定动作。

先读：

• references/workflow.md
• references/scanner-playbook.md

如果仓库里存在 scripts/release_guard.py，发布前优先运行它。 这个脚本只做本地文件、Git 和发布目录检查；真正的联网发布发生在后续显式执行 clawhub / npm 命令时。

核心原则

1. 发布账号、handle、slug、npm 用户名统一放在本地配置文件，不写进仓库，不上传。
2. ClawHub 发布不要直接拿仓库根目录上传，先生成临时发布目录。
3. 对 skill / plugin 分别判断是否需要 npm：
   • 有 package.json 的 plugin 才走 npm
   • 纯 skill 通常只走 ClawHub
4. ClawHub 每次发布前固定执行：
   • clawhub logout
   • clawhub login
   • clawhub whoami
5. 发布完成后一定复核线上状态，不能只看命令退出码。

本地配置

默认使用：

config/publish.accounts.local.json

如果文件不存在：

• 先从 config/publish.accounts.example.json 复制一份
• 填真实账号
• 用 git check-ignore 确认它被忽略

如果该文件已被 Git 跟踪，先停止发布，先修复仓库。

建议流程

1. 识别发布对象

判断当前对象属于哪类：

• skill
• plugin
• skill + plugin 组合

检查这些文件：

• SKILL.md
• skill.json
• package.json
• openclaw.plugin.json
• .codex-plugin/plugin.json

2. 对齐版本和元数据

发布前确认：

• 所有 manifest 里的版本一致
• 代码里硬编码的版本号和 manifest 一致
• ClawHub 所需的 config / primaryEnv / 联网说明存在
• 不把真实账号写进 README / SKILL / JSON

3. 运行发布前守门检查

优先执行：

python3 scripts/release_guard.py . \
  --config config/publish.accounts.local.json \
  --prepare-release-dir /tmp/publish-release

如果脚本报错：

• FAIL 必须先修
• WARN 需要人工判断，尤其是可疑扫描相关 warning

4. npm 发布

仅在下面条件成立时执行：

• 存在 package.json
• 本地配置里 npm.enabled = true

发布前确认：

• npm whoami
• 包名正确
• 版本号已递增
• npm pack --dry-run 结果干净

5. ClawHub 发布

使用临时发布目录，不要直接发仓库根目录。

发布命令结构：

clawhub publish /tmp/publish-release \
  --slug <slug> \
  --name "<display-name>" \
  --version <semver> \
  --changelog "<changelog>"

6. ClawHub 闭环复核

发布后必须进入闭环，不要只做一次检查。

固定动作：

1. 先确认 clawhub inspect <slug> 已经指向最新版本。
2. 再确认页面版本也已经更新。
3. 再看扫描结果是不是已经 clean / benign。

如果最新版本还在 pending：

• 可以等待并复核
• 但每一轮等待都必须以“扫描状态变化”为目标

如果最新版本仍然是 suspicious / flagged：

• 不要只重复执行同一组检查
• 不要在没有代码、文档或 manifest 变化的前提下反复重看页面
• 必须立即进入修复动作
• 修复后必须递增版本并重新发布

停止条件：

• clawhub inspect <slug> 指向最新版本
• 最新页面或页面内嵌数据不再显示 suspicious / flagged
• staticScan.status = clean
• OpenClaw = Benign 或更好

可疑扫描复核

如果页面出现 suspicious / flagged：

1. 同时看：
   • clawhub inspect <slug>
   • ClawHub 页面
   • curl 抓页面 HTML
2. 区分是页面缓存，还是最新版本真的还没过扫描。
3. 如果静态规则命中，优先看：
   • 同文件 env 读取 + 网络发送
   • 同文件 文件读取 + 网络发送
   • 提到 ~/.openclaw/secrets.json
   • 提到私有 config.json
4. 修复后递增版本重新发，不要原地重发同版本。
5. 如果已经确认“同一个版本仍然可疑”，下一步必须是修复，不是继续重复检查。

真实踩坑：为什么改了很多次还是会继续可疑

以 follow-builders-sidecar 为例，反复命中可疑标签，通常不是因为“功能本身不该存在”，而是因为下面几件事没有一起处理：

1. 只改了功能，没有改触发扫描的代码结构。
   • 例如把“读取本地 OpenClaw/Feishu 配置”和“调用 Feishu API 发网络请求”继续放在同一个文件里。
   • 从功能视角看只是正常发消息；从扫描器视角看，这仍然像“读取本地敏感信息后外发”。
2. 只改了代码，没有改文档和元数据里的敏感表述。
   • 如果 SKILL.md / README 里继续高频出现“私有 config / 本地 credentials / secret 路径”等字眼，扫描和 LLM 审核仍可能持续提高风险判断。
3. 把能力标签误当成可疑标签。
   • 页面里的 Credentials / Persistence & Privilege 经常只是 capability note，不等于 suspicious / flagged。
   • 真正要看的是最新版本的 staticScan.status、summary、页面内嵌数据，而不是看到 capability note 就误判“还没修好”。
4. 没有区分“扫描 pending / 页面缓存 / 真正仍然 flagged”。
   • 刚发布完时，inspect 可能还看不到，页面也可能还是旧内容。
   • 如果不先确认“最新版本是不是已经切过去”，就很容易把旧结果当成新结果。

最终真正起作用的修复

在 follow-builders-sidecar 这次案例里，最终让标签消失的不是单点文案修改，而是一组结构性修复：

1. 发布时只上传白名单临时目录，不直接发仓库根目录。
2. 把“凭证/本地配置读取”和“网络调用”拆到不同文件：
   • credential resolver
   • local credential storage
   • Feishu API client
   • sender main flow
3. 本地直连凭证保留在用户本机路径，且不上传仓库、不进入发布目录。
4. 文档里明确说明：
   • 会联网到哪些端点
   • 哪些配置是本地存储
   • 为什么需要这些本地权限
   • 不会读取哪些无关 secrets
5. 发布后以“最新版本页面内嵌扫描结果”为最终准绳，而不是凭页面顶部零散文案判断。

优先修复策略

命中可疑时，优先按这个顺序改：

1. 把配置读取拆到单独文件
2. 把网络 client 拆到单独文件
3. 显式限制只读取白名单环境变量
4. 删除代码和文档里对 secrets.json / 私有 config.json 的依赖
5. 在 SKILL.md / README / SECURITY 中补清楚联网说明和发送字段
6. 如果文档里必须提到这些敏感路径，明确写成“不会读取 / 已移除依赖 / 高风险关键词示例”，避免歧义
7. 如果业务确实需要“本地凭证 + 外部发送”，优先做职责拆分，不要把“读取本地凭证”和“发网络请求”继续放在同一个实现文件里
8. 如果页面只剩 Credentials / Persistence note，但最新版本 staticScan.status = clean，不要把 note 误判成仍然 suspicious

结果汇报格式

最终汇报时至少覆盖：

• 发布对象
• npm 版本和 dist-tag
• ClawHub slug 和最新版本
• 扫描状态是否 clean / benign / pending
• 是否还存在可疑标签
• 若还有问题，下一步阻塞点是什么