---
name: spec-write-skill
description: 编写、改写、迁移或按 audit findings 修复 spec-first source skill 时使用：先判断是否值得做成 skill，再更新 skills/NAME/SKILL.md 的触发、边界、I/O、渐进披露、resources/evals、治理和验证。不要用于一次性回答、解释/总结/翻译、只审计、文档导出、第三方安装、普通代码评审、公开 /spec:* workflow 执行，或手改 generated runtime mirrors。
---

# Spec Write Skill

`spec-write-skill` 是写 skill 的 standalone skill。它不是公开 Claude `/spec:*` 或 Codex `$spec-*` workflow，也不是 `spec-skill-audit` 的替代品：本 skill 只把明确目标转成 source patch。

## Purpose

把值得复用的 skill authoring 请求转成治理清晰、渐进披露、可验证的 spec-first source patch。

## Contract Summary

### When To Use
新建/改写/迁移/修复 `skills/<skill-name>/` source skill 的触发、边界、I/O、资源、治理或验证。

### When Not To Use
一次性回答、解释/总结/翻译、只审计、文档导出、第三方安装、普通 review、公开 workflow 执行、generated mirror 修补。

### Inputs
用户目标、目标 skill、相邻 skill、repo 契约、`skills-governance.json`、audit findings、必要外部 skill 文本。

### Outputs
`do-not-create-skill`、near-neighbor route、source patch、治理/测试/docs 更新、验证状态和 residual risks。

### Artifacts
`skills/<skill-name>/SKILL.md`、必要 resources/evals、治理 JSON、runtime catalog、tests、CHANGELOG；generated mirrors 只由 `spec-first init` 投影。

### Failure Modes
复用价值/输出/近邻排除不清，entry surface 不清，source/runtime 混淆，audit finding 被自动改写。

### Workflow
先资格判断和意图澄清，再定 mode/tier/entry surface，写 patch，更新治理/测试/docs，跑匹配风险的 gate。

### Downstream Consumers
`spec-work`、`spec-skill-audit`、runtime catalog、skill 维护者和最终用户。

## Hard Boundaries

- Source of truth 是 `skills/`、`src/cli/contracts/dual-host-governance/skills-governance.json`、相关 docs/tests；不要手改 `.claude/`、`.codex/` 或 `.agents/skills/`。
- Durable source mutation 需要明确授权或 active source-edit workflow；否则先输出 patch plan / preview。
- 脚本或测试只证明确定性事实；LLM 判断触发语义、边界和质量风险。
- 外部 skill 必须重写 entry surface、source/runtime 边界、验证和治理口径。
- 不照搬 `yao-meta-skill` 的完整 SkillOps 平台；只借鉴资格判断、意图澄清、分级 gate、资源边界和反模式 eval。

## Quality Tiers

`scaffold` 只做 structure/source boundary；`production` 加 trigger/boundary eval；`library` 加 packaging/readiness evidence；`governed` 加 owner/review cadence/rollback boundary。细节见 [Authoring Method](references/authoring-method.md) 与 [Delivery Gates](references/delivery-gates.md)。

## Workflow

1. 资格判断：读 [Authoring Method](references/authoring-method.md)，确认 repeated use、reusable output contract、near-neighbor exclusions 和 non-goals；一次性/解释/文档导出/未来 outline 输出 `do-not-create-skill` 或 near-neighbor route。
2. 目标模糊时只问会改变 package 设计的 2-3 个问题；收敛 recurring job、real inputs、required outputs、exclusions、至少 1 个 should-trigger 示例、至少 1 个 near-neighbor 示例、quality tier 和 first eval target。
3. 明确模式、质量层级、目标 repo、目标 skill 名称和 entry surface：`workflow_command`、`standalone_skill` 或 `internal_only`。
4. 读取相邻 skill、治理记录和项目契约；新建/改写前读 [Skill Quality Vocabulary](references/skill-quality-vocabulary.md)。借鉴按 external benchmark -> user source -> local fit，只提炼 pattern，不复制 wording。
5. 写触发描述：描述是 trigger contract，不是摘要；包含正向意图、负向边界和近邻；先测试 route，再扩展目录。
6. 设计信息层级：`SKILL.md` 放共用步骤和边界；条件细节放 `references/`；确定性重复操作放 `scripts/`；素材放 `assets/`；维护者验证放 `evals/`。空目录、装饰性 reports、未引用资源不进 baseline。
7. 为写入、shell、runtime、delegate 或 handoff 步骤写可检查 completion criterion；读-only 轻 skill 可保持更轻。
8. 更新 source-owned consumers：新增 skill 必须更新 `skills-governance.json`；用户可见或 catalog 变化要更新 runtime catalog、必要 docs/tests 和 `CHANGELOG.md`。
9. 按 [Delivery Gates](references/delivery-gates.md) 跑与 tier 匹配的最窄验证；可分发或复杂 skill 尽量跑官方 `quick_validate.py`、package smoke 或 forward-testing，并记录未执行原因。
10. 输出变更摘要、验证结果、generated runtime mirror 状态、residual risks 和必要下一步。

## References

- [Authoring Method](references/authoring-method.md)
- [Skill Quality Vocabulary](references/skill-quality-vocabulary.md)
- [Delivery Gates](references/delivery-gates.md)