Writing Skills

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

写作法则（真相源引用）

写任何面向代理的文档前，先读 apps/skills/axiom/axiom.md 的「第零部 · 五、面向代理的文档写作」，遵守其中五条原则：

• 前置词的力量：一个预训练已知的紧凑词替代一句展开描述
• 信息的分层递进：步骤 → 内联参考 → 外置参考；所有分支都需要的留主文件，部分分支需要的推出去
• 步骤的完成标准：可检查且有覆盖力——代理能自证已完成，且被迫做足够的工作量
• 单一真相源与环境权威：文档只写环境不会告诉你的；重述环境信息即是会过时的缓存
• 持续修剪：新增一行之前先找可删的一行；空语句（模型默认就会做的指令）不留

Invocation 选择（两种负载的权衡）

	model-invoked	user-invoked
成本	description 常驻上下文，每轮付费	零上下文成本
代价	——	人必须记住它存在（认知负载）
适用	agent 须自主触发，或其他 skill 要引用	只有手动才会用

规则：

• 默认 model-invoked：写好 description 即可
• 仅手动触发的设 disable-model-invocation: true，description 退化为一行人类摘要
• 手唤 skill ≥ 5 个时再引入 router skill（一个索引型 skill 收口）——此前引入是过早抽象

上架清单

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

• 目录名 == frontmatter name；小写字母数字连字符；≤64 字符；不以连字符开头/结尾；无连续连字符
• description 同时回答「做什么」与「何时用」，埋用户会说出的触发关键词，≤1024 字符
• 可选字段按需：license / compatibility / metadata（如 version）/ allowed-tools

内容结构：

• 正文先定义（是什么），再理由（为什么），再准则（怎么做）；准则用祈使句
• 大体量参考材料放 references/ 或子文档，SKILL.md 只留主路径（渐进披露）
• 可执行辅助放 scripts/；模板资源放 assets/

来源追溯（对应 Axiom 第零部·二「从实践到原则的提炼方法」）：

• 提炼自真实项目实践的：同目录附 CREATION-LOG.md，记录来源项目、提炼触发条件（同一模式 ≥3 个独立场景重复）、包含/排除决策
• 纯规范类（非提炼所得）：在 SKILL.md 尾部标注所依据的上位文件

上架动作：

• 运行 axiom skill install——自动发现并挂载到各 agent 的 skills 目录
• 构建站点，确认 [skills] injected 日志包含新条目