optimizing-descriptions

优化技能描述

用于审查和改写 SKILL.md description 字段的操作指南，确保它们按 mizchi 的预期触发。

上游参考资料：agentskills.io/skill-creation/optimizing-descriptions。此技能保留原有框架，并在此基础上添加 mizchi 特有的双轨策略。

为什么需要此指南

Agent 在启动时会看到 name + description（渐进式披露），并仅根据这些信息决定是否加载完整的 SKILL.md。描述就是完整的触发约定：

• 说明不足 → 应触发时，技能却不会触发。
• 范围过宽 → 不应触发时，技能却触发了，浪费上下文。

这两种问题都不会显现出来——技能只是在悄悄失效。此审查会让它们显现出来。

何时调用

元技能，仅限显式调用。触发条件：

• “优化 / 审查 / 改写此技能的描述”
• “按照 agentskills 审查描述”
• “调整触发准确性”
• “检查 mizchi/skills 并修正描述”

不要用于：

• 正常编写技能时的单个技能临时编辑。
• 尚未使用过的新技能（将描述作为 superpowers:writing-skills 的一部分来编写；只有观察到误触发后才进行调整）。

双轨策略

mizchi 的技能分为两类，需要采用不同的描述形式。选错类型是审查时最常见的疏漏。

轨道	触发策略	描述形式	示例
项目	积极触发——适合自动触发	Use when ... — [症状关键词]. Trigger on [文件类型] even if user does not name [领域].	playwright-test、cloudflare-deploy、gh-fix-ci、node-sqlite-vec、aws-vault-mfa-iam
元技能	避免过度触发——仅显式调用	Invoke ONLY when the user explicitly asks ... Do NOT auto-invoke on [常见环境信号].	skill-selector、skill-finder、waxa-eval、apm-usage、empirical-prompt-tuning、retrospective-codify、chezmoi-management、此技能

如何判断要审查的技能属于哪一类：

• 正文包含“Meta-skill” / “explicit invocation” / “明示 invoke” → 元技能。
• 正文是“X 的最佳实践” / “Y 的参考资料” / “如何使用 Z” → 项目。
• 人设类 / 仅聊天类技能（例如 chloe-chat）采用元技能形式，但使用“Activate during ...”措辞。

审查清单

通用（适用于两条轨道）

• 使用祈使措辞——Use when ...（项目）或 Invoke ONLY when ...（元技能）。不要以 Reference for ... 开头，除非后面接有祈使句。
• 聚焦用户意图——描述用户想做什么，而不是技能的内部机制。
• 简洁——少于 1024 个字符（规范的硬性上限；描述在优化过程中往往会变长，因此每次编辑都要检查）。
• 首个分句涵盖触发条件——Agent 实际上最先扫描的是 name + first sentence。

项目轨道附加项

• 列出症状 / 表面关键词：文件名（.gleam、gleam.toml）、错误字符串（network is unreachable、InvalidClientTokenId）、命令（pi.registerTool、apm install）。
• 使用积极触发措辞——even if user doesn't name <domain> / Trigger on <symptom> even when <tool> isn't mentioned。这样即使用户描述了问题却没有说出技术名称，也能捕获相关情况。

元技能轨道附加项

• 以 Invoke ONLY when ... / Use ONLY when ... 开头。
• 加上 Do NOT auto-invoke on ... 条款，列出通常会误触发该技能的常见环境信号（例如操作某些文件、完成某些任务等）。
• 列出用户实际会说的触发短语（例如 "codify today's lessons"、"find a Stripe skill"）——写出确切说法能帮助 Agent 更好地匹配自然语言。

常见改写模式

根据对 mizchi/skills 的单轮审查整理而成（12 次改写，2026-05-12）。

项目轨道改写

# Before: passive, no trigger
Reference for the dotenvx environment variable management tool.

# After: imperative + symptom + pushy
Use when working with the dotenvx env-var tool — encrypting .env, juggling
.env.production / .env.staging, committing .env.vault / .env.keys, wiring
into GitHub Actions. Trigger on `.env.vault` / `.env.keys` symptoms even
when the user does not say "dotenvx".

# Before: best-practices opener, no trigger
Best practices for building and reviewing Gleam projects on the Erlang target.

# After: imperative + file shapes + BEAM symptoms
Use when writing or reviewing Gleam on the Erlang target — Wisp + Mist HTTP
services, OTP processes, gleeunit testing. Trigger on `gleam.toml`,
`.gleam` files, or Erlang/BEAM symptoms even when "Gleam" isn't named.

# Before: describes the situation but no imperative
ECS Service Connect の DNS alias が IPv6 アドレスを返して接続できない問題の回避策。

# After: imperative + error-string symptoms
Use when ECS Service Connect の DNS alias が IPv6 アドレスを返し、 IPv4-only
の Fargate task から `network is unreachable` / `EAI_AGAIN` で接続失敗する
とき。 OTel Collector → Tempo の OTLP gRPC、 Fargate → Service Connect
の HTTP/gRPC 通信が失敗する症状から起動 (user が IPv6 と特定していなくても OK)。

Meta 重写

# Before: "Use after X" promotes auto-trigger
On task completion, pair "what failed first" with "what finally worked"
and codify ... Use after trial-and-error solutions to spare future-you
the same trap. Trigger phrases: "codify today's lessons," ...

# After: explicit-only with user-phrase trigger anchoring
Pair "what failed first" with "what finally worked" and codify the
should-have-known-it insight as an ast-grep rule, a skill, or a
CLAUDE.md rule. Meta-skill: invoke ONLY when the user explicitly says
"codify today's lessons," "make it a skill," "drop it into lint," or
asks to extract a reusable rule from a trial-and-error fix. Do NOT
auto-invoke at every task completion.

# Before: "Consult when touching" auto-triggers on path matches
mizchi's chezmoi dotfiles operations: source location, diff/apply flow,
skill addition, the APM vs chezmoi boundary, pre-commit. Consult when
touching ~/.claude/, ~/.config/, or ~/.zshrc, or initializing a new
machine.

# After: explicit-intent + Do NOT auto-invoke clause
Meta-skill for mizchi's chezmoi dotfiles. Invoke ONLY when the user
explicitly asks to manage / diff / apply chezmoi sources, add a skill
to dotfiles, audit the APM vs chezmoi boundary, or initialize a new
machine. Do NOT auto-invoke when the task only happens to touch a path
under ~/.claude/, ~/.config/, or ~/.zshrc — consult only on explicit
dotfile-management intent.

工作流

1. 提取每个 description: 字段。快速操作方法：

   for f in */SKILL.md; do
     dir=$(dirname "$f")
     echo "=== $dir ==="
     awk 'BEGIN{in_fm=0; in_desc=0}
          /^---$/{in_fm=!in_fm; if(!in_fm) exit; next}
          in_fm && /^description:/{in_desc=1; sub(/^description:[[:space:]]*/,""); print; next}
          in_fm && in_desc && /^[a-zA-Z]+:/{in_desc=0}
          in_fm && in_desc{print}' "$f"
     echo
   done
   

2. 分类每项技能：根据正文将其归为 Meta 或 Project（参见上方的双轨政策表）。

3. 应用检查清单逐项检查技能。记录未通过的检查项，暂时不要修复。

4. 批量修补。 重写所有标记的描述。不要将描述调整提交与技能正文编辑混在一起——只修改 description: 行，让差异便于审查，作为纯描述审计。

5. 使用 waxa audit <skill> 验证——检查前置元数据中的表面问题（长度、名称格式、触发条件格式）。错误必须为零；有关正文 / LICENSE 的警告不在此范围内。

6. 同步到 ~/.claude/skills/<name>/SKILL.md（mizchi 传播约定——让正在运行的会话无需等待 apm install -g --update 就能获取更新）。

7. 合并为一个提交，并在提交消息中逐项总结技能。每轮审计对应一个提交，即使涉及 10 项以上技能也如此。

触发准确性测试（下一阶段）

agentskills.io 页面介绍了一种基于人工审查的实证步骤：在安装了该技能的 Agent 上运行一组查询，统计每个查询的触发率，并划分训练集 / 验证集以避免过拟合。waxa 目前还不支持此功能——将来支持后（通过未来版本中的 waxa trigger 子命令），此技能生成的人工审计结果将作为输入层，触发率测量则作为验证层。在此之前，人工审计 + waxa audit 是当前可行的方法。

如果你要手动执行实证步骤，请遵循 agentskills.io 的具体要求：

• 20 个查询：约 10 个应触发，约 10 个不应触发。
• 每个查询运行 3 次（对非确定性结果取平均值）；应触发查询的通过阈值为 trigger_rate ≥ 0.5，不应触发查询的通过阈值为 < 0.5。
• 按 60/40 划分训练集 / 验证集；根据验证集通过率而非训练集通过率选择最佳迭代版本。
• 最有价值的不应触发查询是近似匹配（关键词重叠，但意图不同）。

常见误区

错误	修正方法
逐字添加导致触发失败的查询中的特定关键词	这会导致过拟合。概括为类别（.gleam files ≫ gleam.toml exists）。
从内部实现的角度编写描述	改从用户意图出发重写。“用户想做什么？”
Meta 技能使用 Use after X / Consult when X	这会根据环境信号自动触发。改写为 Invoke ONLY when explicitly asked ... Do NOT auto-invoke on X。
Project 技能使用 ONLY when the user explicitly says ...	这会导致触发不足。改得更明确主动：Use when ... Trigger on [symptoms] even if X not named.
重写时描述超过 1024 个字符	每次编辑都检查长度；优先删去承载信息最少的从句。
反复修改五轮却没有改善	问题出在查询集，而不是描述。检查查询示例——它们是否太简单 / 太难 / 标注有误？
在同一个提交中重写描述和正文	难以审查和撤销。描述调整应单独批量提交。

相关内容

• agentskills.io/skill-creation/optimizing-descriptions — 上游方法论文档（本技能实际运用的框架）。
• superpowers:writing-skills — 从头创建新技能时使用；描述只是多个组成部分之一。仅当技能已经存在且经过实际观察后，才使用本技能（optimizing-descriptions）。
• waxa-eval — 用于实证测量触发准确性（waxa trigger 上线后）。
• waxa audit <skill> — 检查前置元数据中的表面问题（长度、名称格式、基本触发条件措辞），与本审计的检查项有重叠；可用作快速预检。
• skill-finder — 其中的评估标准包含“frontmatter-health”，与本技能的通用检查清单有所重叠；评估外部技能候选项时，skill-finder 会隐式使用 optimizing-descriptions 中的模式。