Writing Skills

本 skill 是元技能：它约束「如何向 apps/skills 添加约束」。它不承载写作法则的真相源——法则在 Axiom 第零部，这里只做收敛、执行与补充。

阅读顺序：先读 apps/skills/axiom/axiom.md 的「第零部 · 五、面向代理的文档写作」，再读本 skill。本文件是 Axiom 的操作手册，不是替代。

---

一、核心写作法则（真相源引用）

写任何面向代理的文档前，先读 Axiom 第零部·五。以下五条原则必须内化，按优先级排序：

1. 前置词的力量

原则：一个预训练已知的紧凑词，替代一句展开描述。

执行：

• 优先使用领域标准术语（如「幂等」「竞态」「回退」），而非口语化解释
• 建立 skill 内部词汇表：在文档首次出现专业术语时，用括号给出一次简明定义，之后直接使用
• 避免「换句话说」「也就是说」等冗余缓冲；如果术语需要反复解释，说明术语选择不当

反例：

当你执行一个操作多次，结果都和执行一次一样，这就是幂等性。

操作必须是幂等的（多次执行与一次执行结果一致）。

词汇表模板（在 SKILL.md 底部或 references/glossary.md）：

## 术语表

- **幂等（Idempotent）**：多次执行与一次执行结果一致，无副作用累积。
- **竞态（Race Condition）**：多执行流对共享状态的非原子访问导致结果不可预期。
- **回退（Fallback）**：主路径失败后启用的降级策略。

---

2. 信息的分层递进

原则：步骤 → 内联参考 → 外置参考；所有分支都需要的留主文件，部分分支需要的推出去。

执行：

• 主文件（SKILL.md）：只放 80% 场景需要的主路径，保持线性阅读体验
• 内联参考：用折叠块（<details>）或脚注存放 15% 场景需要的补充说明
• 外置参考：用 references/ 子目录存放 5% 场景需要的深度材料、背景论文、历史决策

目录结构示例：

my-skill/
├── SKILL.md              # 主路径：快速上手 + 核心约束
├── references/
│   ├── advanced-usage.md # 复杂场景、边缘情况
│   ├── design-rationale.md # 为什么这样设计（ADR）
│   └── api-reference.md  # 详细参数表
├── scripts/
│   └── validate.sh       # 可执行辅助
└── assets/
    └── template.yaml     # 模板资源

渐进披露检查：

• 新用户能在 30 秒内找到「我现在该做什么」
• 进阶用户能在 2 分钟内找到「特殊情况怎么处理」
• 维护者能在 5 分钟内找到「当初为什么这样设计」

---

3. 步骤的完成标准

原则：可检查且有覆盖力——代理能自证已完成，且被迫做足够的工作量。

执行：

• 每个步骤必须以可验证动作结尾，避免「考虑」「注意」「确保」等模糊动词
• 用 [ ] 复选框明确列出完成标准，代理执行后逐项勾选
• 覆盖力检查：如果跳过该步骤，输出是否仍可能合格？如果可能，步骤不够强制

好步骤 vs 坏步骤：

<!-- 坏：不可检查 -->
- 确保数据已经清洗完毕。

<!-- 好：可检查 -->
- [ ] 运行 `scripts/validate-data.sh`，确认输出包含 `✓ All checks passed`
- [ ] 检查 `output/cleaned.csv` 行数与源文件一致（±1% 以内）

覆盖力测试：问自己——如果代理只做了步骤里明确写的事，结果是否可接受？如果可接受，覆盖力足够；如果还需要「常识补充」，说明步骤有漏洞。

---

4. 单一真相源与环境权威

原则：文档只写环境不会告诉你的；重述环境信息即是会过时的缓存。

执行：

• 绝不在 SKILL.md 中复制 API 文档、CLI 帮助文本、配置文件默认值
• 用引用代替复制：「参见 apps/config/schema.json 的 timeout 字段」
• 如果必须提及环境默认值，用动态引用：「使用系统默认超时（当前为 30s，以 config.yaml 为准）」

环境信息分类：

类型	处理方式	示例
稳定契约	可简要提及，附链接	「遵循 POSIX 退出码约定」
易变配置	只写引用，不抄值	「超时配置见 config.yaml」
运行时状态	完全不写，由环境提供	「当前集群节点数」

---

5. 持续修剪

原则：新增一行之前先找可删的一行；空语句（模型默认就会做的指令）不留。

执行：

• 空语句识别：如果删除这句话，代理行为会改变吗？如果不会，删除它。
  • 坏：「请认真检查代码。」（模型默认就会认真）
  • 坏：「不要忽略错误。」（模型默认不会忽略）
  • 坏：「使用最佳实践。」（无具体操作含义）
• 膨胀检测：SKILL.md 超过 200 行时强制审查——是否有可推至 references/ 的内容？
• 版本修剪：每次修改时，删除已失效的过渡方案、历史兼容说明

修剪口诀：

如无必要，勿增实体。如无差异，勿增描述。如无约束，勿增步骤。

---

二、Invocation 选择：两种负载的权衡

维度	model-invoked	user-invoked
上下文成本	description 常驻，每轮付费	零上下文成本
触发方式	模型自主判断，或其他 skill 引用	用户必须显式调用（如 #skill-name）
认知负载	对用户透明，零记忆负担	用户必须记住它存在
适用场景	agent 须自主触发；高频通用能力	低频、专业、手动操作
description 要求	必须精确，是模型的触发器	退化为人类摘要，一行即可

决策流程

开始
  │
  ▼
该 skill 是否必须在 agent 自主运行时自动触发？
  ├── 是 → model-invoked
  │         └── 写好 description（见下方指南）
  │
  └── 否 → 用户是否会在 ≥3 个不同场景中手动调用？
            ├── 是 → user-invoked
            │         └── 设 disable-model-invocation: true
            │         └── description 写一行人类可读摘要
            │
            └── 否 → 暂不上架，或合并到现有 skill

description 写作指南（model-invoked 关键）

description 是模型的「鼻子」——它靠这个气味决定是否调用该 skill。错误描述导致该触发时不触发，不该触发时乱触发。

好 description 的 CHECKS 标准：

• Concise：≤1024 字符，每字必争
• Hooked：前 20 字必须包含核心触发场景
• Explicit：明确回答「做什么」和「何时用」
• Keyword-rich：埋入用户实际会说的触发词（如「审查」「上架」「frontmatter」）
• Scoped：边界清晰，不说「所有写作场景」，而说「SKILL.md 的编写与审查」

description 模板：

description: |
  [动作] + [对象] + [触发条件]。覆盖 [范围]。
  使用场景：[场景1]、[场景2]、[场景3]。
  关键词：[词1]、[词2]、[词3]。

示例对比：

# 坏：模糊、无触发词、无边界
description: "帮助用户更好地写作。"

# 好：精确、有触发词、有边界
description: |
  约束 SKILL.md 的编写、审查与上架规范。
  使用场景：创建新 skill、调整 frontmatter、决定 model/user-invoked、
  将实践经验提炼为可复用技能、review 他人 skill PR。
  关键词：skill 写作、SKILL.md、frontmatter、model-invoked、元技能。

Router Skill 引入时机

规则：手唤 skill ≥ 5 个时，才引入 router skill（一个索引型 skill 收口）。此前引入是过早抽象。

router skill 的职责：

• 不承载具体约束，只做「用户意图 → 目标 skill」的分发
• description 只描述分发能力，不描述具体领域
• 示例：「根据用户意图，将请求路由到合适的开发技能（写作、测试、部署等）。」

---

三、上架清单（完整版）

3.1 目录与命名（规范硬约束）

• 目录名 == frontmatter name
• 小写字母、数字、连字符；≤64 字符
• 不以连字符开头/结尾；无连续连字符（--）
• description 同时回答「做什么」与「何时用」，埋触发关键词，≤1024 字符
• 可选字段按需添加：
  • license：代码/内容许可证（如 MIT、Apache-2.0、CC-BY-4.0）
  • compatibility：适用 agent 类型（如 all-agents、coding-agent、cli-agent）
  • metadata：version、last-reviewed、author、reviewers
  • allowed-tools：如果 skill 需要限制可用工具列表，显式声明

命名反例纠正：

坏	为什么坏	好
My_Skill	含大写和下划线	my-skill
api--calling	连续连字符	api-calling
-my-skill-	以连字符开头/结尾	my-skill
this-is-a-very-long-skill-name-that-exceeds-sixty-four-characters-limit	>64 字符	short-skill-name

3.2 内容结构

黄金结构：定义（是什么）→ 理由（为什么）→ 准则（怎么做）

• 定义优先：首段明确 skill 的边界，回答「不是什么」与「是什么」
• 理由支撑：每个准则后附「如果不这样做会怎样」，建立内在动机
• 准则用祈使句：动词开头，无主语，可执行
• 大体量参考材料放 references/ 或子文档，SKILL.md 只留主路径
• 可执行辅助放 scripts/（验证脚本、生成脚本、检查脚本）
• 模板资源放 assets/（YAML 模板、Markdown 模板、配置片段）

段落组织原则：

1. 一段一义：一个段落只表达一个完整思想，段首句概括全段
2. 列表即结构：用有序列表表达步骤（有先后），无序列表表达并列选项
3. 代码即规范：示例代码优先于文字描述，坏示例与好示例成对出现
4. 折叠藏细节：用 <details> 包裹背景知识、历史沿革、边缘情况

标题层级规范：

# SKILL.md 一级标题 = skill 名称（唯一）
## 大章节（如：核心法则、上架清单、附录）
### 子章节（如：前置词的力量、完成标准）
#### 仅在需要细分时使用，避免过深

代码块规范：

• 所有代码块必须带语言标识（yaml、bash、```markdown）
• 配置示例用注释标注「好/坏」
• 长脚本不内联，放 scripts/ 后用 <!-- see scripts/validate.sh --> 引用

3.3 来源追溯（对应 Axiom 第零部·二）

分类处理：

类型	处理方式	文件
提炼自真实项目实践	同目录附 CREATION-LOG.md	记录来源项目、提炼触发条件、包含/排除决策
纯规范类（非提炼所得）	在 SKILL.md 尾部标注所依据的上位文件	如「本规范依据 axiom/axiom.md 第零部·五」

CREATION-LOG.md 模板：

# Creation Log: [skill-name]

## 来源项目
- 项目：[repo-name]
- 路径：[相关文件路径]
- 时间：[YYYY-MM]

## 提炼触发条件
同一模式在 ≥3 个独立场景中重复出现：

1. [场景1 描述]
2. [场景2 描述]
3. [场景3 描述]

## 包含决策（为什么放进 skill）
- [原因1]
- [原因2]

## 排除决策（为什么某些经验没有放进 skill）
- [排除项1]：过于特定，仅适用于 [某项目]
- [排除项2]：已被 [其他 skill] 覆盖

## 验证方式
- [ ] 在 [项目A] 试用通过
- [ ] 在 [项目B] 试用通过

3.4 上架动作

• 运行 axiom skill install——自动发现并挂载到各 agent 的 skills 目录
• 构建站点，确认 [skills] injected 日志包含新条目
• 验证触发：在测试对话中模拟触发条件，确认 model 正确调用
• 验证边界：模拟非触发场景，确认 model 不误调用
• 审查清单：对照本 skill 的「审查清单」章节自检

---

四、风格与语气指南

代理文档 vs 人类文档

维度	面向代理（SKILL.md）	面向人类（README.md）
主语	祈使句/无主语（「运行」「检查」）	可用人称（「你可以」「我们建议」）
情感	零情感，零寒暄	可适当友好
冗余	零容忍	可容忍解释性冗余
结构	列表、表格、代码块优先	段落叙述优先
引用	精确路径、命令、返回值	概念性链接、背景阅读

语气检查清单

• 没有「请」「谢谢」「抱歉」等社交润滑剂
• 没有「显然」「众所周知」「简单」等假设性副词
• 没有「可能」「也许」「一般」等弱化词，除非确实描述不确定性
• 否定句优先于双重否定（「不要复制」而非「避免不引用」）

---

五、常见反模式（不要这样做）

反模式 1：全能 skill

症状：一个 skill 覆盖写作、测试、部署、监控。 治疗：按「单一职责」拆分，用 router skill 收口。

反模式 2：文档即代码

症状：在 SKILL.md 里写长脚本、大段配置。 治疗：脚本放 scripts/，配置放 assets/，SKILL.md 只留调用指令。

反模式 3：历史堆积

症状：「之前我们使用 X，现在改用 Y，但 Z 场景仍保留 X。」 治疗：只描述当前规范，历史放 references/history.md 或删除。

反模式 4：假设上下文

症状：「像之前那样处理」「按常规方式配置」。 治疗：每个指令必须自包含，或显式引用具体文件/步骤。

反模式 5：过度防御

症状：「不要删除系统文件」「不要泄露密码」。 治疗：模型默认不会作恶，防御性指令只针对真实发生过的误操作。

---

六、审查清单（Review Checklist）

审查他人（或自己）提交的 skill 时，逐项检查：

Frontmatter

• name 与目录名一致
• name 符合命名规范（小写、连字符、≤64 字符）
• description ≤1024 字符，含触发关键词
• description 同时回答「做什么」和「何时用」
• invocation 选择符合决策流程（model vs user）
• 如需限制工具，显式声明 allowed-tools

内容结构

• 首段定义边界（是什么/不是什么）
• 遵循「定义 → 理由 → 准则」结构
• 准则用祈使句，可检查
• 有坏/好示例对比
• 大体量内容已推至 references/
• 无空语句（模型默认就会做的指令）

来源与维护

• 实践提炼类附 CREATION-LOG.md
• 规范类标注上位文件依据
• 无环境信息缓存（未复制易变配置）
• 运行 axiom skill install 无报错
• 构建日志确认注入成功

---

七、附录

附录 A：SKILL.md 最小可用模板

---
name: [skill-name]
description: |
  [一句话定义]。[触发条件]。
  使用场景：[场景1]、[场景2]。
  关键词：[词1]、[词2]。
---

# [Skill 名称]

## 是什么

[一句话定义边界。]

## 何时触发

- [触发条件1]
- [触发条件2]

## 怎么做

### 步骤 1：[动作]
- [ ] [可检查的标准1]
- [ ] [可检查的标准2]

### 步骤 2：[动作]
- [ ] [可检查的标准]

## 参考

- 上位规范：[路径]
- 详细说明：[references/advanced.md]

附录 B：术语表

• 空语句（Vacuous Statement）：删除后不会改变代理行为的指令，如「请认真处理」。
• 覆盖力（Coverage）：步骤迫使代理完成足够工作的程度，跳过即失败。
• 渐进披露（Progressive Disclosure）：按用户熟练度分层展示信息，新手看主干，专家看细节。
• Router Skill：不承载具体约束，只做意图分发的索引型 skill。

---

规范依据

本规范依据 apps/skills/axiom/axiom.md 第零部·二「从实践到原则的提炼方法」、第零部·五「面向代理的文档写作」制定。