好的 skill 如何定义

好 Skill 的 6 个标准

1. 触发准确
   description 同时说明：

   • 能做什么
   • 何时使用
   • 用户可能怎么表达
   • 哪些场景不该触发

2. 输入输出明确
   写清必需输入、最终产物、完成条件。例如：“生成 TSX、CSS、Story、dist，并通过 TypeScript 检查”。

3. 流程可执行
   使用命令式步骤，避免空泛表达。

   差：

   注意页面质量。

   好：

   读取 layout spec → 选择模板 → 复制到 render → 实现 → 编译 → 报告产物路径。

4. 自由度合适

   • 创意任务：提供原则和判断标准
   • 固定流程：提供明确步骤
   • 易出错操作：封装成脚本，减少临场发挥

5. 上下文精简
   SKILL.md 只保留核心工作流。详细资料放到：

   • references/：规范、API、业务知识
   • scripts/：重复且需要稳定执行的操作
   • assets/：模板、图片、字体、样板工程

6. 可以验证
   Skill 必须定义“怎样算完成”，并通过真实任务测试，而不是只检查文档写得像不像。

推荐结构

my-skill/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── scripts/
├── references/
└── assets/

一个简洁的 SKILL.md 可以这样写：

---
name: page-audit
description: 检查 React 页面是否符合设计系统规范。用于用户要求页面审查、设计规范校验、Token 检查或交付前验收时。
---

# Page Audit

## 所需输入

- 页面源码路径
- 设计规范或组件注册表

## 工作流

1. 确认目标页面和检查范围。
2. 读取相关设计规范。
3. 检查组件、布局、Token 和交互状态。
4. 运行 TypeScript、构建和自动化检查。
5. 按严重程度输出问题清单。

## 完成标准

- 每个问题包含文件、位置、原因和修改建议。
- 区分阻塞问题与优化建议。
- 不修改范围外文件。

## 资源

- Token 规则：读取 `references/tokens.md`
- 自动检查：运行 `scripts/audit-page.mjs`

最常见的坏 Skill

• description 只有“帮助处理页面”，导致误触发或不触发
• 把背景知识堆满 SKILL.md
• 只有原则，没有操作步骤
• 没有异常、降级和禁止事项
• 输出格式与完成条件不明确
• 每次都要求 AI 重写相同脚本
• 同一个 Skill 包揽需求、设计、开发、验证、发布
• 写了很多规则，却没有用真实任务验证

最实用的判断题是：

换一个完全不了解背景的 Codex，仅阅读这个 Skill，能否在正确场景触发，并稳定产出可验收结果？

能做到这一点，才算真正的好 Skill。