lovstudio-skill-optimizer

用途

skill-optimizer 用于对 lovstudio 仓库中已有的 skill 进行审计与自动优化，并在每次优化后维护版本号与变更日志。它对已有技能运行 lint → fix → bump → changelog 流水线，全自动执行，不提供交互式提示；每次运行都会产生具体的版本升级和一条新的 CHANGELOG.md 条目，从而让优化历史可追溯。

何时使用

• 用户在当前对话中指出了某个已有技能的具体问题（例如触发短语错误、CLI 参数过时、缺少 README 徽章等）并希望修复。
• 用户要求对已有技能执行 audit、polish、refine 或“刷一遍”。
• 用户明确要求升级某个技能的版本或更新其 changelog。
• 在另一个技能被实质性修改后主动运行，以版本升级的方式记录该变更。

工作流程（强制、全自动）

不向用户询问选项，全部从（a）目标技能名称和（b）当前对话中提到的优化备注推断。

步骤 1：确定目标与上下文

从用户消息中提取目标技能名称，例如 any2pdf、lovstudio-any2pdf、any2pdf-skill，并规范化为裸名称（去掉前缀）。如果用户未明确命名技能，则从近期对话上下文（刚处理过的技能）推断。若仍不明确，只提一个有针对性的问题。

同时扫描当前对话，收集用户提出的与该技能相关的问题（错误参数、触发失配、CJK 渲染损坏、缺失选项、README 混乱等），形成“上下文驱动修复列表”。该列表是主要驱动，通用 lint 仅作为补充。

步骤 2：Lint

运行：

python3 skills/lovstudio-skill-optimizer/scripts/lint_skill.py <name> --json

解析 JSON 结果，与步骤 1 的修复列表合并，按以下优先级排序：

1. 用户在对话中明确提到的问题（最高优先级）
2. lint error 级发现
3. lint warn 级发现
4. lint info 级发现（仅当廉价且安全时应用）

对于标准化工作，当技能可被其他用户复用时，可移植性发现为高优先级。Mark/LovStudio 私有路径应被移除、迁移到 references/user-config.md 配合 env/profile 处理，或在 compatibility 中明确标注为仅作者使用。

步骤 3：直接应用修复

根据优先级修复列表，用 Edit 工具编辑 SKILL.md、README.md、scripts/*.py。准则：

• SKILL.md frontmatter description：覆盖 what + when + 具体触发短语（中文 + 英文），不要臃肿，控制在约 800 字符以内。
• 脚本中的 CLI 参数：如果用户遇到某个 flag 的 bug，修复根因而非掩盖。
• 渐进式披露：如果 SKILL.md 正文超过 500 行，将最大的一节拆分到 references/<topic>.md。
• 用户初始化：如果技能引用了个人工作区路径、私有品牌资产、设计指南或输出根目录，添加 references/user-config.md 的 profile/env 契约，并把必需的本地路径替换为 CLI flags、环境变量或 profile 查找。
• 不编写未被要求的测试或文档；CHANGELOG 条目就是变更文档。
• 除非原文件已一致使用 emoji，否则不添加 emoji。

步骤 4：决定升级类型

按修复内容选择 semver 升级：

升级	适用场景
patch	bug 修复、措辞修复、frontmatter 调整、CJK 渲染修复
minor	新增 CLI flag、新增选项、新增参考文档、范围扩大
major	破坏性 CLI 变更、移除选项、重命名技能

除非明确要求，否则保持在 0.x（遵循仓库发布约定）。

步骤 5：升级版本并写入 changelog

python3 skills/lovstudio-skill-optimizer/scripts/bump_version.py <name> \
  --type <patch|minor|major> \
  --message "<one-line summary of the biggest change>" \
  --change "<additional bullet>" \
  --change "<additional bullet>"

该操作会更新：

• README.md 版本徽章（事实来源）
• SKILL.md frontmatter 的 metadata.version（如果存在则保持同步）
• CHANGELOG.md — 在顶部插入一条带当天日期的新条目（文件不存在则创建）

步骤 6：重新 lint 并报告

python3 skills/lovstudio-skill-optimizer/scripts/lint_skill.py <name>

若需全仓库标准化基线：

python3 skills/lovstudio-skill-optimizer/scripts/lint_skill.py --all --root .

向用户报告时使用以下确切格式，不多不少：

optimized: lovstudio-<name>
version:   <old> → <new>
fixes:
  - <bullet 1>
  - <bullet 2>
remaining lint warnings: <count>  (or "none")

不要打印结尾总结、自我表扬或后续步骤建议，diff 本身足以说明。

步骤 7：提交、推送并同步所有位置

技能可能存在于源仓库加上一个分发目录中，需保持所有已发布位置同步：

• source repo：lovstudio/<name>-skill 或 lovstudio/dev-skills
• general catalog：lovstudio/general-skills，用于公开/付费的通用技能
• dev-skills catalog：lovstudio/dev-skills，用于打包的 meta/dev 工具

7a. 提交并推送到源仓库：

cd <source-checkout>
git add <changed files>
git commit -m "fix(<name>): <one-line summary>"
git push

提交信息遵循仓库约定：fix|feat|docs(<skill-name>): <summary>。patch 用 fix，minor 用 feat，major 用 feat!。

7b. 同步到相关分发仓库，使用该 catalog 仓库自身的同步脚本，然后渲染并校验元数据：

cd <general-skills-or-dev-skills-checkout>
python3 scripts/sync-skills.py
python3 scripts/render-marketplace.py
python3 scripts/render-readme.py
python3 scripts/validate_deps.py
git add <manifest and synced skill paths>
git commit -m "chore: sync <name> skill"
git push origin main

如果任一步骤失败，向用户报告同步状态，而不是静默跳过。部分同步（源已更新但 pro-skills 陈旧）正是此步骤要防止的问题。

CLI 参考

lint_skill.py

参数	默认	说明
<name>	—	技能名称（可带或不带 lovstudio- 前缀）
--path	—	技能目录绝对路径（覆盖 name）
--json	off	以 JSON 输出发现

退出码：存在任何 error 级发现时为 2，否则为 0。

bump_version.py

参数	默认	说明
<name>	—	技能名称
--path	—	技能目录绝对路径（覆盖 name）
--type	—	patch
--set	—	显式版本号，例如 0.2.0
--message, -m	必填	主 changelog 条目
--change, -c	—	附加条目（可重复）
--dry-run	off	仅显示将发生的变更而不写入

依赖

Python 3.8+（仅标准库，无需 pip install）。