# Write A Skill

> 创建、审查和维护 agent 技能（Skill）。Use when creating/refining a Skill or deciding whether Skill、command、hook、rule、AGENTS.md guidance is the right carrier.

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

---


# 编写 Skill

## 来源层级

- 【官方规范】: 目标平台要求，或被广泛记录的 Skill 行为。
- 【本地质量门槛】: 这个 LimCode Skill 采用的更严格默认标准。
- 【社区验证实践】: 来自真实用户反馈和开源实践验证的推荐模式。
- 【本设计扩展】: 用于提高可靠性的扩展，不是官方强制要求。

## 操作原则

创建能解决用户真实重复失败的最小可靠指令载体。可靠不是越完整越好；如果安全清单、eval、维护记录或额外目录会分散 agent 对任务本身的注意力，就降级、合并或删除。

## 工作流

1. **先选择载体**【社区验证实践】。
   - AGENTS.md/rule：一两条长期成立的约定。
   - Command：用户手动触发的原子操作。
   - CLI/script/hook/CI：确定性、脆弱、重复或必须强制执行的操作。
   - Skill：需要可选引用材料的复杂可复用多步骤工作流。
   - 闸门：写文件前说明选择的载体，以及为什么更窄的载体不够。
   - 完整决策树见 `references/carrier-decision-tree.md`。

2. **写作前澄清结构边界**【本设计扩展】。
   - 填写“已知/缺失/假设”矩阵：真实失败场景、目标用户、触发词、负例、输入、输出、工具、成功证据。
   - 检查结构属性：当前 prompt 外是否有必要上下文；输出是否会被当前回复之外的人、agent、工具或未来会话读取；是否会产生多份独立产物；是否触发 scripts、外部内容、secrets、网络/文件访问、破坏性或外部可见操作。
   - 如果关键事实缺失，只问缺失问题；如果上下文足够，先声明假设再继续。

3. **设计渐进披露和注意力预算**。
   - 【官方规范】: 保持 `SKILL.md` 简洁，把详细或条件性材料放入支持文件，并在 `SKILL.md` 中引用。
   - 【本地质量门槛】: 除非用户明确接受更大的本地 Skill，否则 `SKILL.md` 控制在 100 行以内。
   - 【本设计扩展】: 每新增一个目录、章节、eval 或维护字段，都说明它会在实际执行中被谁读取、何时读取、解决什么失败。
   - 如果某部分只是“看起来完整”，但不会改善执行，删除它。
   - 若输出会被当前回复之外的消费者读取，或会产生多份独立产物，读取 `references/distributed-context-boundary.md`，设计外部化上下文、主题化信息库和无相对指代 prompt。

4. **编写合规 frontmatter**。
   - 【官方规范】: `name` 必须匹配父目录，只使用小写字母、数字和连字符，长度不超过 64 字符，并避开禁用标记或平台保留词。
   - 【官方规范】: `description` 必须非空，低于目标平台限制，并说明 Skill 做什么以及何时使用。
   - 【本地写作规范】: 优先使用第三人称、关键词友好的描述；相似工作流容易混淆时，推荐写出负边界。
   - 结构细则见 `references/skill-anatomy.md`。

5. **正文写成任务流程，而不是治理流程**【社区验证实践】。
   - 使用编号步骤、检查点、验证证据、陷阱提示和反合理化说明。
   - 优先写“agent 此刻该关注什么、忽略什么、产出什么”。
   - 避免把一个边界环境中的限制写成所有场景的默认限制。
   - 不要只写“永远不要做 X”；应写“不要做 X，改做 Y”。

6. **只打包真正需要的资源**。
   - 【官方规范】: 只有在明显改善执行效果时，才创建 `references/`、`scripts/` 或 `assets/`。
   - 【官方规范】: scripts 用于确定性工作，并必须输出可执行的错误信息。
   - 【本设计扩展】: `evals/`、`MAINTENANCE.md`、安全清单是风险触发项，不是每个 Skill 的默认配置。

7. **按风险选择评估和审查深度**【社区验证实践】。
   - 简单本地 Skill：可只做正/负触发和人工试用。
   - 共享或高影响 Skill：加入 A/B、逻辑模拟、边界攻击、跨模型或跨 surface 测试。
   - 有 scripts、外部内容、secrets、破坏性操作或共享安装时，再读取 `references/security-and-maintenance.md`。
   - 发布评估结论前读取 `references/evaluation-and-verification.md`。

8. **用结构属性审查，而不是用场景标签审查**【本设计扩展】。
   - 当前 prompt 外有必要上下文：审查是否提供文件路径或内联摘要。
   - 当前回复之外有人、agent、工具或未来会话会消费输出：审查是否禁止相对指代，并提供可定位上下文。
   - 产生多份独立产物、报告或审查结论：审查是否按主题组织状态、决策、证据、阻断项和报告。
   - 触发 scripts、外部内容、secrets、网络/文件访问、破坏性或外部可见操作：读取 `references/security-and-maintenance.md`，安全清单不可降级。
   - 每个额外产物都必须说明读取者、读取时机和解决的失败；否则删除。

## 输出契约

创建或修改 Skill 时，必须提供：

- 载体决策，以及为什么更窄的载体不够。
- 结构边界假设和注意力预算取舍。
- 目录树，且只包含实际会被使用的目录。
- 若触发外部消费者或多产物边界，说明上下文外部化方式、主题分类和回写规则。
- 完整文件内容或精确补丁。
- 验证方式：可轻可重，但必须匹配风险。
- 若触发风险条件，再提供安全清单、维护记录或评估文件；否则明确说明不创建的原因。

## 反合理化

| 借口 | 修正 |
| --- | --- |
| “更好的 description 会让自动触发可靠。” | 优化描述，但可靠性重要时加入 command、AGENTS.md 或 hook 兜底。 |
| “用户给的上下文已经够了。” | 先填写已知/缺失/假设矩阵。 |
| “这只是文档。” | Skill 会改变 agent 行为；必须验证执行效果。 |
| “评估触发过一次，所以可用了。” | 至少测正例和负例；高风险再做 A/B 和回归。 |
| “越完整越安全，总不会错。” | 完整性会消耗注意力；不服务执行的字段、目录和清单都应删减。 |
| “安全清单和维护记录应该默认加。” | 只有风险边界触发时才加；普通工作流优先保持轻量。 |
| “下游读者会理解聊天里的隐含指代。” | 不会。凡脱离当前聊天记录无法唯一解析的指代，都必须改成文件路径或内联摘要。 |