技能打包

把「自己能跑」的技术方案，变成「别人能装、能跑、能上架」的技能包。

何时使用

• "帮我把这个技能打包" / "打包上传到技能平台"
• "这个技能想共享给同事" / "发布到 SkillHub"
• "平台提示解析失败，帮我看看" / "技能上架被拒"
• 想给自用技能做一次"对外发布前的体检"

核心认知：官方校验是假绿灯

WorkBuddy 官方 quick_validate.py 只用正则判断字段是否存在，根本不解析 YAML：

if 'name:' not in frontmatter:      # 只看这串字符在不在
    return False, "Missing 'name' in frontmatter"

它报 Skill is valid! 的技能，照样可能因 YAML 语法被平台拒绝。实战中最隐蔽的一个坑：

# 错：「scaffold: KPI cards」被当成嵌套映射，YAML 直接崩
description_en: Ships a scaffold: KPI cards, monthly trend...

# 对：用英文双引号包住
description_en: "Ships a scaffold: KPI cards, monthly trend..."

所以官方脚本通过 ≠ 能上架。本技能在官方校验之外额外做 yaml.safe_load() 严格解析。

三个上架必踩的坑

工作流

Step 1 先问清 author 与英文名

打包前向用户确认两件事，其余可自动派生：

• author（合作方名称）：平台必填。用户没给就问，别自己编公司名
• 英文 slug：--name。不指定会从描述自动派生，但常常不贴切

Step 2 跑打包脚本

# 用托管 venv 的python；把路径换成你自己的 venv 或系统 python
python "<本技能目录>/scripts/pack_skill.py" "<技能目录>" \
  --name <english-slug> --author "<合作方>" --version 1.0.0

本机实测可用的调用方式（若你有自己的 Python，直接替换成相对路径更清爽）：

"<你的 python 路径>" "<本技能目录>/scripts/pack_skill.py" "<技能目录>" --name <slug> --author "<作者>"

常用参数：

脚本做六件事：密钥与垃圾文件扫描 → 建发布副本（绝不改原技能目录）→ 修 frontmatter → 严格 YAML 复检 → 可移植性整改 → 打包回读校验 + 出上架指引。

Step 3 处理 WARN 项再交付

BLOCK 项脚本已拦下，必须先修。WARN 项要逐条看，尤其这几类：

• 硬编码个人绝对路径 —— 别人下载后跑不起来，必须改。bat 里做多级回退 + 首跑自动装依赖
• bat 含中文 —— 改英文注释，脚本不能替你翻译
• 缺 description_en —— 平台必填且面向海外用户，别用占位符糊弄
• 自动补的 README 是模板 —— 得按实际情况改写

Step 4 交付并说明上传路径

把 zip 和「上架指引.md」一起 present_files，并说清三个入口：技能市场（主路径）、开放平台（需实名）、直接发 zip 给同事。

关键原则

• 先问平台：SkillHub 和 WorkBuddy 市场规则不同。SkillHub 有严格文件类型白名单（.md .txt .json .yaml .yml .js .ts .py .sh .png .jpg .jpeg .svg），.html/.css/.bat/.csv 一律拒收，单文件还限 1 MB。同一个包可能 WorkBuddy 能传、SkillHub 被拒。默认就按 SkillHub 严格模式查。
• SkillHub 报错只提示第一个违规文件：删掉它再提交才报下一个。所以必须打包前一次性扫清，别靠提交试错来回返工。
• 带 Web 前端的技能在 SkillHub 上走不通：.html+.css 是主体时，四种方案见 references/publish-troubleshoot.md（纯方法论版/ 代码内嵌 Markdown / 拆包外部仓库 / 只内部共享）。
• 不改原技能目录：所有改动只发生在输出目录的暂存副本里，原技能随时可继续用
• BLOCK 与 WARN 分级：BLOCK 是不改就必然失败，WARN 是上传前建议处理。别把两者混为一谈
• 改 bat 要顺手加依赖自检："%PY%" -c "import flask" 2>nul + if errorlevel 1 pip install，否则别人双击只看到一片红字
• 占位符要保留形态：wbpk_xxxxxxxx 比空字符串有用，别人一看就知道填什么；但真实值绝不能进包

资源清单