lovstudio-skill-optimizer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

skill-optimizer — 自动优化 lovstudio skill 并维护版本与 changelog

Runs a lint → fix → bump → changelog pipeline on an existing skill in this repo. Fully automatic — no interactive prompts. Every run produces a concrete version bump and a new CHANGELOG.md entry so optimization history is traceable.

对仓库中的现有skill执行「检查→修复→版本升级→更新变更日志」的自动化流程，全程无需交互提示。每次运行都会生成明确的版本升级和新的CHANGELOG.md条目，优化历史可追溯。

When to Use

使用场景

User mentioned a concrete problem with an existing skill in this conversation (wrong trigger phrases, stale CLI flags, missing README badge, etc.) and wants it fixed.
User asks to "audit", "polish", "refine", "刷一遍" an existing skill.
User explicitly asks to bump a skill's version or update its changelog.
Proactively after another skill has been modified meaningfully — run this to record the change with a version bump.

用户在对话中提到现有skill存在具体问题（如触发词错误、CLI标志过时、缺少README徽章等）并希望修复时。
用户要求对现有skill进行「审计」「打磨」「改进」「刷一遍」时。
用户明确要求升级skill版本或更新其变更日志时。
在其他skill被进行有意义的修改后主动运行——通过版本升级记录变更。

Workflow (MANDATORY, fully automatic)

工作流程（强制要求，完全自动化）

Do not ask the user for options. Infer everything from (a) the target skill name and (b) any optimization notes mentioned in the current conversation.

请勿向用户询问选项。所有信息从以下两点推断：(a) 目标skill名称；(b) 当前对话中提到的任何优化说明。

Step 1: Identify target & context

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

From the user's message, extract:

Target skill name — e.g.
```
any2pdf
```
,
```
lovstudio-any2pdf
```
, or
```
lovstudio:any2pdf
```
. Normalize to the bare name (strip prefix). If the user did not name a skill explicitly, infer it from recent conversation context (the skill they were just working on). If still ambiguous, ask one targeted question.
Context-driven fix list — scan the current conversation for issues the user raised about this skill: wrong flags, trigger misfires, broken CJK rendering, missing options, confusing README, etc. This list is the primary driver. The generic lint only supplements it.

从用户消息中提取：

目标skill名称——例如
```
any2pdf
```
、
```
lovstudio-any2pdf
```
或
```
lovstudio:any2pdf
```
。标准化为纯名称（去除前缀）。如果用户未明确指定skill名称，从最近的对话上下文推断（用户刚处理的skill）。若仍有歧义，仅提出一个针对性问题。
基于上下文的修复列表——扫描当前对话，找出用户提出的关于该skill的问题：错误的标志、触发词失效、CJK渲染问题、缺失选项、README易混淆等。此列表为首要驱动因素，通用检查仅作为补充。

Step 2: Lint

步骤2：代码检查（Lint）

bash

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

Parse the JSON findings. Combine with the context-driven fix list from Step 1. Prioritize in this order:

Fixes the user explicitly mentioned in conversation (highest priority)
Lint
```
error
```
findings
Lint
```
warn
```
findings
Lint
```
info
```
findings — apply only if cheap and safe

bash

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

解析JSON检查结果，与步骤1中基于上下文的修复列表合并。按以下优先级排序：

用户在对话中明确提及的修复（最高优先级）
Lint检测出的
```
error
```
级问题
Lint检测出的
```
warn
```
级问题
Lint检测出的
```
info
```
级问题——仅在成本低且安全的情况下修复

Step 3: Apply fixes directly

步骤3：直接应用修复

Edit

SKILL.md

README.md

scripts/*.py

with the

Edit

tool based on the prioritized fix list. Guidelines:

SKILL.md frontmatter description: make sure it covers what + when + concrete trigger phrases (中文 + English). Don't bloat it; keep under ~800 chars.
CLI args in scripts: if the user hit a bug with a specific flag, fix the root cause — don't paper over it.
Progressive disclosure: if SKILL.md body > 500 lines, split the largest section to
```
references/<topic>.md
```
.
Don't write tests or docs that weren't asked for. The CHANGELOG entry IS the documentation of the change.
Don't add emojis unless the original file already uses them consistently.

基于优先级修复列表，使用编辑工具修改

SKILL.md

、

README.md

、

scripts/*.py

文件。遵循以下准则：

SKILL.md前置元数据描述：确保涵盖功能、适用场景以及具体触发词（中文+英文）。避免冗余，控制在约800字符以内。
脚本中的CLI参数：如果用户遇到特定标志的bug，修复根本原因——不要敷衍了事。
渐进式披露：如果SKILL.md正文超过500行，将最大的章节拆分到
```
references/<topic>.md
```
文件中。
不要编写未被要求的测试或文档。CHANGELOG条目即为变更的文档记录。
不要添加表情符号，除非原始文件已一致使用表情符号。

Step 4: Decide bump type

步骤4：确定版本升级类型

Choose semver bump based on the fixes applied:

Bump	Use when
`patch`	bug fix, wording fix, frontmatter tweak, CJK rendering fix
`minor`	new CLI flag, new option, new reference doc, expanded scope
`major`	breaking CLI change, removed option, renamed skill

Stay in 0.x unless explicitly told otherwise — per repo release conventions.

根据应用的修复选择语义化版本（semver）升级类型：

升级类型	适用场景
`patch`	bug修复、措辞调整、前置元数据修改、CJK渲染修复
`minor`	新增CLI标志、新增选项、新增参考文档、功能范围扩展
`major`	CLI破坏性变更、移除选项、skill重命名

除非明确要求，否则保持在0.x版本范围内——遵循仓库发布规范。

Step 5: Bump version + write changelog

步骤5：升级版本 + 编写变更日志

bash

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

This updates:

```
README.md
```
version badge (source of truth)
```
SKILL.md
```
frontmatter
```
metadata.version
```
(kept in sync if present)
```
CHANGELOG.md
```
— prepends a new entry with today's date (creates the file if missing)

bash

python3 skills/lovstudio-skill-optimizer/scripts/bump_version.py <name> \
  --type <patch|minor|major> \
  --message "<最大变更的单行摘要>" \
  --change "<额外要点>" \
  --change "<额外要点>"

此命令会更新：

```
README.md
```
中的版本徽章（权威来源）
```
SKILL.md
```
前置元数据中的
```
metadata.version
```
（若存在则保持同步）
```
CHANGELOG.md
```
——在文件开头添加带今日日期的新条目（若文件不存在则创建）

Step 6: Re-lint & report

步骤6：重新检查并报告

bash

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

Report to the user, in this exact shape and nothing more:

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

Do not print a trailing summary, self-congratulation, or next-step suggestions. The diff speaks for itself.

bash

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

向用户报告，严格遵循以下格式，不要添加其他内容：

optimized: lovstudio-<name>
version:   <旧版本> → <新版本>
fixes:
  - <要点1>
  - <要点2>
remaining lint warnings: <数量>  (或"none")

请勿添加结尾总结、自我夸赞或下一步建议。差异本身已说明问题。

Step 7: Commit, push & sync all locations

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

Skills live in three locations that must stay in sync:

source (edit here):  ~/projects/lovstudio-skills/        → lovstudio/skills
claude reads from:   ~/.claude/skills/*                   → symlinks to source
distribution repo:   ~/projects/lovstudio-pro-skills/     → lovstudio/pro-skills

7a. Commit & push to source repo:

bash

cd ~/projects/lovstudio-skills
git add skills/lovstudio-<name>/
git commit -m "fix(<name>): <one-line summary>"
git push

Commit message follows repo convention:
```
fix|feat|docs(<skill-name>): <summary>
```
Use
```
fix
```
for patch,
```
feat
```
for minor,
```
feat!
```
for major

7b. Sync to pro-skills distribution repo:

The two repos have independent git histories (not forkable), so sync via file copy:

bash

SRC=~/projects/lovstudio-skills/skills/lovstudio-<name>
DST=~/projects/lovstudio-pro-skills/skills/lovstudio-<name>
rsync -av --delete "$SRC/" "$DST/"
cd ~/projects/lovstudio-pro-skills
git add skills/lovstudio-<name>/
git commit -m "sync(<name>): <version> from lovstudio/skills"
git push origin main

~/.claude/skills/

is already up-to-date via symlinks — no action needed.

If any step fails, report the sync state to the user rather than silently skipping. A partial sync (source updated but pro-skills stale) is the exact problem this step exists to prevent.

Skill存储在三个位置，必须保持同步：

源文件（在此编辑）:  ~/projects/lovstudio-skills/        → lovstudio/skills
Claude读取位置:   ~/.claude/skills/*                   → 链接到源文件
分发仓库:   ~/projects/lovstudio-pro-skills/     → lovstudio/pro-skills

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

bash

cd ~/projects/lovstudio-skills
git add skills/lovstudio-<name>/
git commit -m "fix(<name>): <单行摘要>"
git push

提交信息遵循仓库规范：
```
fix|feat|docs(<skill-name>): <摘要>
```
补丁版本使用
```
fix
```
，次版本使用
```
feat
```
，主版本使用
```
feat!
```

7b. 同步到pro-skills分发仓库：

两个仓库拥有独立的Git历史（不可分叉），因此通过文件复制同步：

bash

SRC=~/projects/lovstudio-skills/skills/lovstudio-<name>
DST=~/projects/lovstudio-pro-skills/skills/lovstudio-<name>
rsync -av --delete "$SRC/" "$DST/"
cd ~/projects/lovstudio-pro-skills
git add skills/lovstudio-<name>/
git commit -m "sync(<name>): <version> from lovstudio/skills"
git push origin main

~/.claude/skills/

已通过链接保持最新——无需操作。

若任何步骤失败，向用户报告同步状态，而非静默跳过。此步骤的存在正是为了防止部分同步（源文件已更新但pro-skills过时）的问题。

CLI Reference

CLI参考

lint_skill.py

lint_skill.py

Argument	Default	Description
`<name>`	—	Skill name (with or without `lovstudio-` prefix)
`--path`	—	Absolute path to skill dir (overrides name)
`--json`	off	Emit findings as JSON

Exit code:

if any

error

-severity finding,

otherwise.

参数	默认值	描述
`<name>`	—	Skill名称（可带或不带 `lovstudio-` 前缀）
`--path`	—	Skill目录的绝对路径（覆盖名称参数）
`--json`	关闭	以JSON格式输出检查结果

退出码：若存在

error

级检查结果则为

，否则为

。

bump_version.py

bump_version.py

Argument	Default	Description
`<name>`	—	Skill name
`--path`	—	Absolute path to skill dir (overrides name)
`--type`	—	`patch` \| `minor` \| `major` (mutually exclusive with `--set` )
`--set`	—	Explicit version e.g. `0.2.0`
`--message` , `-m`	required	Primary changelog bullet
`--change` , `-c`	—	Additional bullet (repeatable)
`--dry-run`	off	Show what would change without writing

参数	默认值	描述
`<name>`	—	Skill名称
`--path`	—	Skill目录的绝对路径（覆盖名称参数）
`--type`	—	`patch` \| `minor` \| `major` （与 `--set` 互斥）
`--set`	—	明确指定版本，例如 `0.2.0`
`--message` , `-m`	必填	变更日志的主要要点
`--change` , `-c`	—	额外要点（可重复使用）
`--dry-run`	关闭	显示将要进行的变更但不实际写入

Dependencies

依赖

Python 3.8+ (stdlib only, no

pip install

needed).

Python 3.8+（仅使用标准库，无需

pip install

安装额外依赖）。

lovstudio-skill-optimizer

Original

Translation

skill-optimizer — 自动优化 lovstudio skill 并维护版本与 changelog

skill-optimizer — 自动优化 lovstudio skill 并维护版本与 changelog

When to Use

使用场景

Workflow (MANDATORY, fully automatic)

工作流程（强制要求，完全自动化）

Step 1: Identify target & context

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

Step 2: Lint

步骤2：代码检查（Lint）

Step 3: Apply fixes directly

步骤3：直接应用修复

Step 4: Decide bump type

步骤4：确定版本升级类型

Step 5: Bump version + write changelog

步骤5：升级版本 + 编写变更日志

Step 6: Re-lint & report

步骤6：重新检查并报告

Step 7: Commit, push & sync all locations

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

CLI Reference

CLI参考

`lint_skill.py`

`lint_skill.py`

`bump_version.py`

`bump_version.py`

Dependencies

依赖