writing-skills

name	writing-skills
description	在创建、精简或改写技能说明，且需要让技能更清晰、可发现、可执行时使用

编写技能

核心目标

技能是给未来代理使用的短参考。它应该说明：什么时候使用、遵循什么原则、怎么执行、哪些错误要避免。

好技能具备四点：

• 触发条件明确：代理知道什么时候该读它。
• 内容自包含：不依赖额外技能、外部文章或脚本才能理解。
• 步骤可执行：读完能直接照做。
• 范围克制：只覆盖当前已知且可复用的模式。

何时创建技能

适合创建：

• 某个方法会重复使用。
• 规则需要判断，不能只靠脚本强制。
• 现有文档太散，代理容易漏掉关键约束。
• 经验可以跨项目复用。

不适合创建：

• 一次性问题记录。
• 项目内部约定；这类内容应放到项目说明中。
• 标准工具的完整手册。
• 没有当前调用场景的“未来可能需要”内容。

文件结构

最小结构：

skills/
  skill-name/
    SKILL.md

只有在确实必要时才添加辅助文件：

• 大型参考材料超过正文承载范围。
• 可复用脚本或模板会被实际调用。
• 示例文件比内联代码更清晰。

否则优先保持单文件、自包含。

SKILL.md 基本结构

---
name: skill-name
description: 在具体触发条件出现时使用
---

# 技能名称

## 概述

用 1-2 句话说明核心原则。

## 何时使用

列出明确触发条件，也说明何时不用。

## 工作流程

给出可执行步骤。

## 快速参考

用表格或短列表帮助扫描。

## 常见错误

说明错误表现和修正方式。

Front Matter

必须包含：

• name：只使用小写字母、数字和连字符。
• description：描述触发条件，而不是总结完整流程。

推荐写法：

description: 在创建或改写技能说明，且需要让代理清楚何时使用该技能时使用

避免写法：

description: 按完整流程创建技能、验证技能并完成发布

原因：描述用于发现技能。它应该回答“什么时候读这个技能”，不要让代理只根据描述执行简化版流程。

写作规则

• 用直接语言，不写叙事复盘。
• 先写原则，再写步骤。
• 一个技能只解决一类问题。
• 优先短句、短列表、表格。
• 示例只保留最能说明模式的一个。
• 不把外部资料当成理解前提。
• 不使用必须安装额外工具才能看懂的格式。
• 不重复其他技能或项目文档中的长篇内容。

可发现性

技能能否被使用，取决于描述和正文关键词是否覆盖真实触发场景。

写描述时包含：

• 具体任务：创建、改写、验证、精简。
• 明确症状：技能太长、依赖太多、触发条件不清、步骤不可执行。
• 领域词：skill、SKILL.md、front matter、description。

正文中自然出现同义词即可，不要堆砌关键词。

示例选择

好示例：

• 真实、短小、能直接改用。
• 只展示关键差异。
• 有必要时解释为什么这样写。

坏示例：

• 多语言重复展示同一概念。
• 人为构造、比正文还难懂。
• 依赖未解释的外部文件。

流程图

只有在决策分支容易误判时才使用流程图。

不用流程图的情况：

• 线性步骤。
• 命令参考。
• 代码示例。
• 简单清单。

能用表格或列表讲清楚时，优先用表格或列表。

质量检查

发布或保存前检查：

• name 简短稳定。
• description 只描述触发条件。
• 开头 100 行内能看懂核心用途。
• 没有理解所必需的外部依赖。
• 没有未验证的未来抽象。
• 没有项目私有细节混入通用技能。
• 常见错误覆盖最可能的误用。
• 辅助文件确实有当前用途。

常见错误

错误	修正
把技能写成事故复盘	改成可复用规则和步骤
描述总结完整流程	改成触发条件
正文依赖其他文档才能理解	内联必要规则，删除非必要引用
为未来场景预留大量分支	只保留当前真实用例
示例过多	保留最有代表性的一个
支持文件太多	合并到正文或删除未使用文件

底线

技能不是百科，也不是会议记录。它是一份短而可靠的操作说明。

能少写就少写；必须写的内容要清楚、具体、可执行。