mstar-skill-authoring

Skill Authoring

本 skill 约束如何编写、审查与验证 任意 agent skill（SKILL.md）。面向 skill 工作，不是普通应用实现。

Load Order

在本 harness 仓库内工作时：先 Read mstar-harness-core（加载 / 冲突裁决）；仓库维护另遵根目录 AGENTS.md。

在其它仓库 / 宿主上使用本 skill 时：按当地入口文档加载；本文件的原则与门控仍然适用。

改现有 skill 时：读完被改 skill 及其 SSOT 引用；禁止仅为文风重写相邻 skill。

详细 writer 流程与输出模板 → references/skillsbench-authoring.md（需要完整循环时再读）。

Workflow

主链：按「Frontmatter Contract」先定触发契约（原则 3）→ 按「Body 必须回答的 5 问」写默认紧凑 body（原则 2）→ 变体细节按「Progressive Disclosure」进 references/ / templates/ / scripts/ → 行为塑形改动按「验证门控（Evidence，原则 4 + 6）」留 paired 证据 → 按「Review Template」自审并完成「完成时主动说明」三问。

6 条作者原则（Decision Rules，必须遵守）

来源：SkillsBench 大规模实验。违反任一都会降低 agent 性能。

Body 必须回答的 5 问

合格 SKILL.md 只清晰回答：

1. 何时加载？（触发 / 排除）
2. 按什么顺序与关键决策点执行？
3. 哪些约束 / 不变量绝不可违反？
4. 正确结果长什么样？（成功标准 / 证据）
5. 主路径不够时打开哪些额外资源？

答不进这 5 问的内容 → 删或移到 references/。

运行时别名（runtime alias map）

已发布的 mstar-* 专题 skill 允许运行时模式（lintFiveQuestion(body, "runtime")）用锁定别名表回答同一问题（引擎常量 RUNTIME_HEADING_ALIASES）：

• 别名表是锁定表：改表必须同步引擎回归测试与 corpus。
• 新写 / greenfield skill（authoring / strict）仍要求 canonical 标题；运行时别名只豁免已发布专题 skill 的机械 lint，不豁免语义——别名标题必须真实回答对应问题，正文不得因别名而缩水。

Skill Purpose Test

仅当全部成立才新建 / 扩写 skill：

1. 行为应跨多项目、角色或任务复用。
2. 需要判断或排序，且不宜用代码强制。
3. 现有 skill 树尚未拥有同一规则（避免副本）。
4. 触发条件可写清，agent 知道何时读取。

不要为这些建 skill：一次性项目约定（放项目 AGENTS.md / 等价处）、可 lint/脚本化的机械规则、无复用手法的事故叙述、已有 skill 规则的副本。

Frontmatter Contract

---
name: example-skill
description: Use when...
---

• name：稳定、小写、连字符。
• description：触发契约，不是流程摘要。写清症状、上下文、角色、产物与排除条件。
• 第三人称；足够具体以避免无关加载（原则 3）。
• 禁止在 description 里总结整条 workflow（否则 agent 可能只跟摘要、跳过 body）。

Bad：Explains how to write plans with steps, tests, commits, and review gates.
Better：Use when a non-trivial task has a spec or requirements and needs a written implementation plan before code changes.

Engine check (when available): run mstar skill lint <skill-dir> (or import { lintFrontmatter, lintFiveQuestion } from "@mstar-harness/engine" in a host hook) to lint the frontmatter contract and the five-question body contract above. On fail -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.

默认 Body 结构

# Skill Title

## Load Order
## Scope
## Workflow
## Decision Rules
## Evidence
## References

Keep SKILL.md focused on the main execution path. Move long examples, templates, schemas, and detailed variants into references/, templates/, or scripts/.

Skill-relative script and asset paths

When a skill ships executables or assets under scripts/ / templates/ / references/, name them as skill → relative path：

• Good: skill my-skill → scripts/do-thing
• Good: <my-skill>/scripts/do-thing（已加载 skill 根的占位写法）
• Bad：把 skills/my-skill/scripts/do-thing 写成消费仓库 cwd 下的字面路径

Agents 按 skill 名 发现 skill；文档若给出完整仓内相对路径，agent 常在应用仓库 cwd 下按字面搜索而找不到。先解析已加载 skill 根目录，再拼 scripts/… / references/…。

在本 harness：解析方式见 mstar-host § Resolve loaded skill root（omp skill://、各宿主插件挂载等）。其它环境按当地 skill 安装约定解析。

Engine check (when available): import resolveAssetPath from @mstar-harness/engine in a host hook to resolve a skill-relative asset per the convention above (no CLI form yet). On fail -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.

Progressive Disclosure

1. Frontmatter：仅触发
2. SKILL.md：主执行路径
3. references/ / templates/ / scripts/：变体细节，按需加载

多宿主 / 多域细节按文件拆分，并在 body 写明「何时打开哪份」。

验证门控（Evidence，原则 4 + 6）

行为塑形改动必须留下证据，任选可观测形式：

• 2–3 个压力 prompt（无 skill 易失败；有 skill 应通过）
• before/after 期望 + 触发短语 + 一次具体校验（检索、链接、dry-run）
• 记录失败原因、token / 延迟回归；未提升则回滚文案

压力场景骨架：

{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "会诱使 agent 违反目标规则的真实任务",
      "expected_output": "合规行为长什么样",
      "files": []
    }
  ]
}

完成时主动说明

写完 / 大改 skill 后必须交代：

1. 删了 / 压了什么，以及如何满足原则 2 与 5
2. 如何验证原则 6（paired 证据或压力场景）
3. 触发契约是否仍足够窄（原则 3）

Review Template

## Skill Review
- Trigger contract:
- 5 questions covered:
- Principles 2/5 compactness:
- SSOT alignment:
- Progressive disclosure:
- Evidence for behavior change (P6):
- Stale references checked:
- Verdict: Approve | Request Changes | Needs Discussion | Unconfirmed
- Unconfirmed: paired evidence (P6) cannot be established or verified

References