技能自动改进器
- 作者仓库星标 282
- 许可证 MIT
- 作者仓库 asm
- 领域
- 安全
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 94 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @luongnv89 · MIT
- 上下文用量评级
- 较高消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- Python
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
保存起始状态,以便可以审核之前/之后的差异:然后执行`references/frontmatter-audit.md`中描述的Frontmatter审核并将结果保存到`.asm-improver/baseline-frontmatter-audit.md`。如果目标技能位于 git 存储库中,建议将 `.asm-improver/` 添加到 `.gitignore`,以便迭代工件不受版本控制。阅读 JSON 并注意:`overallScore`,`grade`
运行评估器的自动修复程序以获得免费胜利:这可以处理尾随空格、CRLF 标准化、缺少 `effort` 和其他机械问题。然而,当作者或版本丢失时,`asm eval --fix`会写入顶级`author:`(来自`git config user.name`)和/或顶级`version: 0.1.0`——这两者都被`quick_validate.py`拒绝作为意外的键。立即执行下面的标准化步骤。
`quick_validate.py` 和 Frontmatter 审计结果是第一位的,因为它们限制了发布。阅读`references/skill-creator-checklist.md`以获取完整的改造手册。常见修复:描述缺少负面触发子句 → 附加“不要用于 X、Y、Z”。命名 2-3 个相邻域 描述超过 250 个字符 → 修剪对冲词,折叠同义词(1024 是硬上限,250 是运行时预算目标)
按分数升序对 7 个类别进行排序。首先处理最低的一个。当全部都是`>= 8`时停止。对于 8 以下的每个类别:阅读 `references/category-playbook.md` 以查找该类别的修复模式 将其与 `Edit`(小的有针对性的更改)或 `Write`(重组整个部分时)一起应用 重新运行 `asm eval "$SKILL_PATH" --json` 和 `python "$QV" "$SKILL_PATH"` 并检查增量
这些原则在进行第三阶段类别修复时持续适用,而不是作为一个单独的连续阶段。在第三阶段之前阅读一次,并在每次编辑时牢记它们。两个门在正文长度上拉向相反的方向:`asm eval`的`prompt-engineering`奖励最多3000字的正文`asm eval`的`context-efficiency`奖励1500字以下的正文Gate 1将SKILL.md限制在500行(硬技能创造者规则,〜几千字)
此阶段作为第 6 阶段循环的每次迭代中的最后一个操作运行,而不是作为第 6 阶段之后单独的一次性传递。对于叙述流,数字是连续的;实际执行是每次迭代。根据技能创建者的版本管理规则,对 SKILL.md 的每次编辑都必须在保存之前修改 `metadata.version`: 补丁 (`x.y.Z`):拼写错误修复、仅限 frontmatter 标准化、细微的措辞调整
每次迭代后重新运行这两项检查。当其中任何一个为真时,循环停止: 停止条件 · 结果门 1 通过 AND `overallScore > 85` AND `min(scores) >= 8` · PASS — 继续报告已完成的 8 次评估迭代 · BLOCKER — 写入报告 3 个连续迭代,任一门上都没有移动 · BLOCKER — 写入报告
通过时,写入`.asm-improver/report.md`:目标技能路径 两个门的基线与最终:`quick_validate.py`状态、Frontmatter审核结果已清除、`overallScore`、`grade`、每个类别之前/之后表目标技能`metadata.version`:基线→最终文件已更改(列出已编辑或创建的技能目录下的每个路径)
# Skill Auto-Improver
You are running an eval-driven improvement loop for a SKILL.md-based skill. The target skill must clear **two gates** in this order:
1. **Skill-creator standard (must-pass floor)** — `python scripts/quick_validate.py` is clean; the Frontmatter Audit passes; SKILL.md is under 500 lines; description has a negative-trigger clause; `metadata.version` and `metadata.author` are present; `docs/README.md` (if it exists) carries the AI-skip notice; bundled scripts print descriptive errors before exiting.
2. **`asm eval` quality floor (supplementary)** — `overallScore > 85` AND every category score `>= 8`.
A skill that scores 92 on `asm eval` but fails `quick_validate.py` is **not** done. A skill that passes `quick_validate.py` but scores 70 on `asm eval` is **not** done. Both gates must clear, or the loop reports a blocker.
## Repo Sync Before Edits (mandatory)
This skill mutates files in a git repo. Before any edit, sync the local branch with the remote:
```bash
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"
```
If the working tree is dirty, `git stash`, sync, then `git stash pop`. If `origin` is missing or `git pull` hits conflicts, **stop and ask the user** before continuing — do not skip or force the sync.
## When to Use
- The user asks to "improve", "level up", "fix", "polish", or "bring up to standard" an existing skill
- A skill fails `quick_validate.py` or scores below the asm-eval 85/8 floor and must ship
- You are preparing a skill for `asm publish` or inclusion in a catalog
- You want to dogfood quality improvements on one of your own skills
If the user only wants a report without edits, run `asm eval <path>` and `python scripts/quick_validate.py <path>` directly — that is not this skill. If the user is authoring a brand-new skill from scratch, send them to `/skill-creator` instead — this skill assumes a SKILL.md already exists.
## Prerequisites
Verify all of the following before touching any files. Stop and tell the user if any fails.
- `asm` is available on PATH (`command -v asm` or `which asm`)
- Python 3 is available, and `~/.claude/skills/skill-creator/scripts/quick_validate.py` exists (skill-creator must be installed locally)
- The target skill path contains a `SKILL.md` file
- The working tree has no unrelated uncommitted edits (dirty files get mixed into diffs)
- You have write access to the skill directory
Resolve the path to skill-creator's validator once at the start and reuse it:
```bash
QV="$HOME/.claude/skills/skill-creator/scripts/quick_validate.py"
test -f "$QV" || { echo "skill-creator not installed at $QV"; exit 1; }
```
## Inputs
The user provides one of:
- A local skill path: `skills/foo` or `/abs/path/to/skill`
- A direct `SKILL.md` file path (treated as its parent directory)
- A GitHub shorthand: `github:owner/repo` or `github:owner/repo:path/to/skill`
For GitHub inputs, ask the user to clone locally first or whether you should open a PR back to that repo. This skill's default path is **local editing** — remote editing is out of scope for v1.
## The Two Gates
### Gate 1 — Skill-creator standard (must-pass floor)
A skill passes this gate when **all** of these are true:
- `python "$QV" "$SKILL_PATH"` exits 0 (no unexpected keys, name is kebab-case ≤64 chars, description is single-line ≤1024 chars, etc.)
- The Frontmatter Audit (full checklist in `references/frontmatter-audit.md`) passes
- `SKILL.md` body is under 500 lines (split to `references/` if not)
- Description includes a negative-trigger clause naming adjacent domains that should not trigger the skill (`quick_validate.py` warns when missing)
- `metadata.version` follows `MAJOR.MINOR.PATCH`; `metadata.author` is present
- If `docs/README.md` exists, it carries the AI-skip HTML comment at the top
- Any bundled scripts under `scripts/` print descriptive errors on stderr before exiting
This gate is **non-negotiable** — `asm publish` and the catalog rely on it.
### Gate 2 — asm-eval 85/8 quality floor (supplementary)
```
overallScore > 85 AND min(categories[*].score) >= 8
```
Stricter than overall score alone — a skill at 86 with a 5 in `testability` still fails. This forces balanced quality instead of letting one strong area hide a weak one.
## Workflow
Do these phases in order. Do not skip phases or change the order. **Phase 4 is a continuous sidebar that runs throughout Phase 3 — not a standalone step**, which is why it does not appear in the per-phase Step Completion Reports.
### Phase 0 — Capture baseline against both gates
Save the starting state so the before/after diff is auditable:
```bash
mkdir -p .asm-improver
asm eval "$SKILL_PATH" --json > .asm-improver/baseline.json
python "$QV" "$SKILL_PATH" > .asm-improver/baseline-quickvalidate.txt 2>&1 || true
```
Then perform the **Frontmatter Audit** described in `references/frontmatter-audit.md` and save findings to `.asm-improver/baseline-frontmatter-audit.md`.
If the target skill lives inside a git repo, suggest adding `.asm-improver/` to `.gitignore` so iteration artifacts stay out of version control.
Read the JSON and note:
- `overallScore`, `grade`
- Every `categories[].score` (7 categories, each out of 10)
- `topSuggestions` (the evaluator's own priorities)
If the baseline already passes **both** gates, stop immediately — print a one-line summary and skip to the final report. Do not "improve" a skill that already passes.
### Phase 1 — Apply deterministic fixes, then normalize frontmatter
Run the evaluator's auto-fixer for free wins:
```bash
asm eval "$SKILL_PATH" --fix --dry-run # preview the diff
asm eval "$SKILL_PATH" --fix # write, creates SKILL.md.bak
```
This handles trailing whitespace, CRLF normalization, missing `effort`, and other mechanical issues. **However, when authorship or version is missing, `asm eval --fix` writes a top-level `author:` (from `git config user.name`) and/or top-level `version: 0.1.0` — both of which `quick_validate.py` rejects as unexpected keys.** Immediately follow with the normalization step below.
#### Frontmatter normalization (mandatory after `--fix`)
Read `references/frontmatter-audit.md` — section "Normalizing `asm eval --fix` output" — for the exact migration. In short:
- Move top-level `author: <name>` → `metadata.author: <name>` (keep the value). The current fixer writes `author:`; older skills may carry a top-level `creator:` instead — treat it the same way and migrate to `metadata.author:`.
- Move top-level `version: <semver>` → `metadata.version: <semver>` (keep the value)
- Drop any other top-level keys that aren't in the allowed set (`name`, `description`, `license`, `allowed-tools`, `metadata`, `compatibility`, `effort`) — e.g., legacy `tags:`. Surface non-trivial drops to the user before deleting.
- Quote any string value containing `:`, `#`, `-`, `<`, `>`, `|`, `{`, `}`, `[`, `]`, `,`, `&`, `*`, `?`, `=`, `!`, `%`, `@`, or `` ` `` per the YAML safety rule
After normalization, re-run **both** checks:
```bash
asm eval "$SKILL_PATH" --json > .asm-improver/iter-1.json
python "$QV" "$SKILL_PATH"
```
Many skills jump 5–15 points on `asm eval` here without touching the body, and `quick_validate.py` typically goes from fail to pass.
### Phase 2 — Fix Gate 1 failures first
`quick_validate.py` and the Frontmatter Audit findings come first because they gate publish. Read `references/skill-creator-checklist.md` for the full retrofit playbook. Common fixes:
- Description missing a negative-trigger clause → append "Don't use for X, Y, Z." naming 2–3 adjacent domains
- Description over 250 chars → trim hedge words, collapse synonyms (1024 is the hard ceiling, 250 is the runtime-budget target)
- Body over 500 lines → split dense sections into `references/<topic>.md` and replace inline content with a one-line pointer
- Missing AI-skip notice in `docs/README.md` → prepend the HTML comment from `references/skill-creator-checklist.md`
- Bundled script exits silently → add `echo "Error: ..." >&2` lines before each `exit 1` / `sys.exit(1)`
Re-run `python "$QV" "$SKILL_PATH"` after every Gate 1 edit. Do not move to Phase 3 until Gate 1 is clean.
### Phase 3 — Fix the lowest asm-eval categories
Sort the 7 categories by score ascending. Work on the lowest one first. Stop when all of them are `>= 8`.
For each category below 8:
1. Read `references/category-playbook.md` to find the fix patterns for that category
2. Apply them with `Edit` (small targeted changes) or `Write` (when restructuring a whole section)
3. Re-run `asm eval "$SKILL_PATH" --json` and `python "$QV" "$SKILL_PATH"` and check the deltas
**Do not batch-edit multiple categories blindly.** Fixes can interact — expanding the body for `testability` can tank `context-efficiency` or push the body over 500 lines (which fails Gate 1). One category at a time, re-eval after each change, keep the ones that help, revert the ones that regress either gate.
### Phase 4 — Watch for cross-gate tradeoffs (sidebar — applies during Phase 3)
These principles apply continuously while doing Phase 3 category fixes, not as a separate sequential phase. Read them once before Phase 3 and keep them in mind on every edit.
The two gates pull in opposite directions on body length:
- `asm eval`'s `prompt-engineering` rewards bodies up to 3000 words
- `asm eval`'s `context-efficiency` rewards bodies under 1500 words
- Gate 1 caps SKILL.md at **500 lines** (the hard skill-creator rule, ~ a few thousand words)
When you add content, default to **linking out, not inlining**:
- Long examples → `references/examples.md` with `See references/examples.md for...`
- Long scripts → `scripts/foo.sh` with `Run scripts/foo.sh to...`
- Long tables → `references/rubric.md`
- Long prerequisite lists → `references/prerequisites.md`
This pattern earns `context-efficiency` points (the words "reference" / "see" / "link" / "template" are scanned for), keeps SKILL.md under the 500-line Gate 1 cap, and reduces token cost on every invocation.
Concretely, if you would need more than ~80 lines to add a section, put it in `references/` and link to it from SKILL.md in 2-3 lines.
### Phase 5 — Bump the target skill's `metadata.version`
This phase **runs as the last action inside each iteration of Phase 6's loop**, not as a separate one-time pass after Phase 6. The number is sequential for narrative flow; the actual execution is per-iteration.
Per skill-creator's Version Management rule, every edit to a SKILL.md must bump `metadata.version` before saving:
- **Patch** (`x.y.Z`): typo fixes, frontmatter-only normalization, minor wording tweaks
- **Minor** (`x.Y.0`): new sections, new references, expanded triggers, added subagents
- **Major** (`X.0.0`): restructured workflow, breaking output-format changes
If the target SKILL.md has no `metadata.version`, add one starting at `1.0.0`. Bump exactly **once per loop iteration**, not once per edit within an iteration — otherwise the version churns ahead of meaningful change.
Record the bump in the loop log so the final report can show baseline → final version.
### Phase 6 — Loop with a cap
Re-run **both** checks after every iteration. The loop stops when any of these is true:
| Stop condition | Outcome |
| ------------------------------------------------------------ | ------------------------ |
| Gate 1 passes AND `overallScore > 85` AND `min(scores) >= 8` | PASS — proceed to report |
| 8 eval iterations completed | BLOCKER — write report |
| 3 consecutive iterations with no movement on either gate | BLOCKER — write report |
| 2 consecutive iterations with regression on either gate | BLOCKER — revert, report |
**Mid-iteration Gate 1 regressions** — a Phase 3 edit can push SKILL.md over the 500-line cap or otherwise break a Gate 1 check (the two gates pull in opposite directions on body length; see Phase 4). When this happens within an iteration, do not let it close the iteration as a regression: drop back into Phase 2, fix the Gate 1 break in the same iteration, then re-run both checks. Only count the iteration as a regression if both gates are still worse than the previous iteration after that fix lands. This prevents the loop from tripping the "2 consecutive regressions" stop condition on a churn that the agent could resolve in-place.
Save every iteration's JSON to `.asm-improver/iter-N.json` and a one-line gate summary to `.asm-improver/iter-N-gates.txt` so the final report can diff them.
### Phase 7 — Write the final report
On pass, write `.asm-improver/report.md` with:
- Target skill path
- Baseline vs final for **both gates**: `quick_validate.py` status, Frontmatter Audit findings cleared, `overallScore`, `grade`, per-category before/after table
- Target skill's `metadata.version`: baseline → final
- Files changed (list every path under the skill directory that was edited or created)
- Iterations taken (N of 8)
- Key fixes applied (one line per category or audit item that moved)
On blocker, write the same report but add a "Blockers" section explaining why a gate was not cleared. Blocker entries must name the gate (Gate 1 or Gate 2), the specific failing check (e.g., `quick_validate.py: unexpected key 'tags'`), and what the loop was unable to resolve. Do not pretend a blocker is a pass.
Example blocker entry:
> **Gate 2 — testability** (stuck at 6/10): The evaluator wants verifiable outputs and an "Acceptance Criteria" section. The skill's output is a subjective rewrite of prose, which is hard to express as a testable assertion. Author decision needed: accept a 6 here, or redefine scope so output is machine-checkable.
## Step Completion Reports (mandatory)
After each phase, emit a compact status block so pass/fail is scannable:
```
◆ Phase N — [phase name]
··································································
Frontmatter valid: √ pass
quick_validate: √ pass
asm overall: 86 → 91
Min category: 7 → 8
Target version: 1.2.0 → 1.3.0
Result: PASS | FAIL | PARTIAL
```
Use `√` for pass, `×` for fail, `—` for context. Report per phase: Phase 0 (baseline captured), Phase 1 (deterministic + normalization), Phase 2 (Gate 1 fixes), Phase 3 (asm-eval category fixes), Phase 5 (version bump applied), Phase 6 (loop stop condition), Phase 7 (final report written).
## Acceptance Criteria
- `.asm-improver/baseline.json`, `.asm-improver/baseline-quickvalidate.txt`, and `.asm-improver/baseline-frontmatter-audit.md` captured before any edits
- `asm eval --fix` applied, then frontmatter normalized so `quick_validate.py` accepts the result
- Each Gate 1 check addressed at least once before any Gate 2 work
- Each `asm eval` category below 8 addressed at least once
- Re-eval against **both** gates after every iteration, captured to `.asm-improver/iter-N.json` and `.asm-improver/iter-N-gates.txt`
- Target skill's `metadata.version` bumped exactly once per iteration that produced edits
- Loop stops on one of the 4 conditions in Phase 6 — never unbounded
- `.asm-improver/report.md` exists on exit, pass or blocker
- On PASS: `python "$QV" "$SKILL_PATH"` exits 0 AND final eval JSON shows `overallScore > 85` AND `min(categories[*].score) >= 8`
- On BLOCKER: report names every Gate 1 check still failing and every category still below 8 with a one-line reason
### Expected output
See `references/report-template.md` for the full PASS and BLOCKER report templates. On BLOCKER, include a `## Blockers` section naming each failing gate check with a one-line reason.
## Edge Cases
- **Skill already passes both gates**: stop at Phase 0, skip to report. Do not edit passing skills.
- **SKILL.md has no frontmatter**: `asm eval --fix` cannot add it. Ask the user whether to scaffold one (using the skill-creator template) or abort.
- **Iterating regresses either gate**: revert the last edit (`cp SKILL.md.bak SKILL.md` if available, or undo via git) and try a different fix pattern from the playbook.
- **`asm eval --fix` writes a key `quick_validate.py` rejects**: this is expected — Phase 1's normalization step handles it. Do not skip the normalization.
- **Description over 250 chars after edits**: trim. The 250-char target prevents tail-first truncation in Claude Code's `/skills` listing, which would chop your negative-trigger clause.
- **SKILL.md body over 500 lines**: split into `references/` per the progressive-disclosure rule. SKILL.md must drop below 500 before exit.
- **Loop caps out at 8 iterations**: the skill has structural issues auto-improvement cannot solve. Write the blocker report and hand back to the user.
- **GitHub shorthand input**: for v1, ask the user to clone locally first. Remote editing is out of scope.
- **Destructive action**: never `rm -rf` the skill directory. `asm eval --fix` creates `SKILL.md.bak` — leave it in place until the user explicitly cleans up.
## References
- `references/skill-creator-checklist.md` — Gate 1 retrofit playbook (frontmatter, README, scripts, body length)
- `references/frontmatter-audit.md` — full audit checklist plus the `asm eval --fix` normalization migration
- `references/category-playbook.md` — per-category fix patterns for `asm eval` Gate 2
- `references/report-template.md` — PASS and BLOCKER report layouts
- `~/.claude/skills/skill-creator/scripts/quick_validate.py` — the Gate 1 mechanical validator
- `~/.claude/skills/skill-creator/references/frontmatter-rules.md` — upstream source of the audit rules
- `asm eval --help` — flag reference for the evaluator
- `src/evaluator.ts` in the ASM repo — source of truth for how each Gate 2 category is scored
按说明文件中的顺序排列。
编辑前同步仓库(强制)
何时使用
先决条件
输入
1号门——技能创造者标准(必经楼层)
文件/命令 -> python scripts/quick_validate.py · metadata.version · metadata.author · docs/README.md · asm eval · overallScore > 85 · >= 8 · quick_validate.py
内容校验值 -> 04484150367e
当前原文的自动摘译,尚未人工审校。
编辑前同步仓库(强制)
此技能会改变 git 存储库中的文件。在进行任何编辑之前,将本地分支与远程同步:如果工作树是脏的,
git stash,同步,然后git stash pop。如果origin丢失或git pull发生冲突,请在继续之前停止并询问用户 - 不要跳过或强制同步。何时使用
用户要求“改进”、“升级”、“修复”、“抛光”或“达到标准”现有技能 技能失败
quick_validate.py或分数低于 asm-eval 85/8 层,必须交付 您正在为asm publish准备一项技能或将其包含在目录中 您想要对自己的一项技能进行测试质量改进 如果用户只想要一份未经编辑的报告,请运行直接asm eval <path>和python scripts/quick_validate.py <path>——那不是这个技能。如果用户从头开始编写全新的技能,请将其发送到/skill-creator- 该技能假设 SKILL.md 已经存在。先决条件
在接触任何文件之前验证以下所有内容。如果有任何失败,请停止并告诉用户。
asm在 PATH 上可用(command -v asm或which asm) Python 3 可用,并且~/.claude/skills/skill-creator/scripts/quick_validate.py存在(技能创建器必须在本地安装) 目标技能路径包含一个SKILL.md文件 工作树没有不相关的未提交编辑(脏文件会混合到差异中)输入
用户提供以下之一: 本地技能路径:
skills/foo或/abs/path/to/skill直接SKILL.md文件路径(视为其父目录) GitHub 简写:github:owner/repo或github:owner/repo:path/to/skill对于 GitHub 输入,要求用户首先在本地克隆,或者是否应该打开返回该存储库的 PR。该技能的默认路径是本地编辑 - 远程编辑超出了 v1 的范围。1号门——技能创造者标准(必经楼层)
当所有这些都为真时,技能就会通过此门:
python "$QV" "$SKILL_PATH"退出0(没有意外的键,名称是kebab-case≤64个字符,描述是单行≤1024个字符等)Frontmatter审核(references/frontmatter-audit.md中的完整清单)通过SKILL.md主体低于500行(拆分为references/如果没有)描述包括一个负面触发子句,命名不应触发技能的相邻域(quick_validate.py缺失时发出警告)