# Skill Style

> 创建或修改任何 SKILL.md 前必须读取并遵守本 skill：管技能内容红线与 lint 机检；外部技能入库验收、臃肿技能瘦身拆分也走这里。凡起草/修改/评审/合并技能、"太长了/废话多/写得行不行"、要跑技能 lint 都触发；仅使用某技能干活且不改其文本时不触发。

- Skill: `caikiji/skill-style` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add caikiji/skill-style`
- Raw SKILL.md: https://api.skillmd.com/api/skills/caikiji/skill-style/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: caikiji (https://skillmd.com/u/caikiji)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/caikiji/skill-style

---


# Skill Style

约束 SKILL.md 的写作质量：SKILL.md 是写给 agent 的执行指令，不是用户文档，只装触发条件、动作与验收标准，装不下的进 references/ 或 scripts/；用户视角话术（如`供审阅`、`先给结论`、`一目了然`）与解释性叙述一律删。

## 红线（违规必改）

| 编号 | 规则 | 判定方式 |
|------|------|----------|
| R1 | frontmatter 含 name/description，name 与目录名一致 | 机检 |
| R2 | description 按「写作规范·description 设计」执行，≤300 字符，不写背景故事 | 机检+人工 |
| R3 | SKILL.md 全文 ≤60 行，硬上限 120 行 | 机检 |
| R4 | 不写哲学句：动机、理念、生态价值类叙述一律删；也不写元叙述（来源/动机/原理说明，如`我们实战跑出来的` `实测不生效`，使用方不关心）；不用性质/价值修饰词定位技能（如`透明化`、`智能化`、`高效`），定位只写触发条件与动作 | 机检特征词+人工 |
| R5 | 规则可判定：能回答"违反了没"；不可度量表述改硬阈值或删；不用 agent 无法可靠感知的指标（如耗时/时长/预估时间），特征词表见 scripts/lint.py 常量 | 机检特征词+人工 |
| R6 | 规则只在一处定义，SKILL.md 与 references/scripts 不互相复制语句（模板示例除外）；也不得复述相邻/依赖 skill 已定义的内容（如 herdr-flows 不复述 herdr 的命令细节），冲突处只写"见 <skill>" | 机检+人工 |
| R7 | 文中相对链接指向的文件必须存在 | 机检 |

## 写作规范

- 每条以动作开头，用祈使句；技能自身不做性质/价值定位（如`透明化`、`高效`、`智能`），这类词对模型执行无帮助，定位只写触发条件与动作；"解释"只在它是验收标准时保留，例："自包含：读者无本会话上下文也能看懂"。
- description 设计（触发面）：硬时机句＋能力锚点半句＋正向枚举＋反向豁免句；时机锚点（动作前/提交前/收尾后）必写，高频场景排前。
- 枚举分两型：请求型埋用户真实原话与近义动词；状态型写工作特征（如"本次改了命令用法"），供模型自主判定时机。
- 反向豁免句只划最近邻：与正向枚举共享词汇/语义、但目标不同的场景；与锚点天然互斥的场景不写（如写码技能列出「README 不触发」）。与邻技能的分工在 description 直接点名对方。
- 两测过关才算完：回放——拟 5~10 句用户真实措辞逐句对照能否命中；替身——把别的技能名换进来读，无违和即边界没写清。
- 输出物路径与命名写死为常量格式，不留开放式描述。
- 章节骨架二选一：任务型技能（替用户干活）用"触发时机 → 流程（编号步骤）→ 输出规范 → 边界"；治理型技能（约束其它技能怎么写）用"定位 → 规则 → 工作流 → 边界"。两者的触发场景都写在 description，不设重复小节。

## 工作流

### 创建

1. 需要访谈、测试用例、评估循环时先用 skill-creator 出稿；简单技能直接起稿。
2. 按"章节骨架"起草；description 过回放与替身两测。
3. 用户话术排查：逐句朗读正文，给 agent 下命令的保留，给用户解释设计/价值/理念的删或改写。
4. 对照红线逐条自查，跑 `python <本技能目录>/scripts/lint.py <技能目录>`，错误清零后交付。

### 修改

1. 只约束新增内容：新增句子同样受红线约束；历史遗留违规仅口头提示，不顺手改。
2. 改完跑 lint。

### 优化（瘦身）

按序逐项处理，输出修改清单（每项一句理由）：

1. 删哲学句（R4）；不可度量表述改硬阈值或删（R5）；
2. 跨文件重复语句合并到唯一定义处（R6）；
3. 单选项占位符改为字面值；
4. 超 R3 预算时把细节拆入 references/ 或 scripts/，正文留指针。

## 边界

- lint 只做机检；语义判断（是否哲学句）由执行者按红线清单人工判。
- 优化阶段只删减合并，不新增功能或改变技能行为。