القائمة
Use when creating new skills or editing existing skills for the Rune skill library — guides skill authoring with CSO optimization, TDD testing methodology, and anti-rationalization patterns
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | writing-skills |
| description | Use when creating new skills or editing existing skills for the Rune skill library — guides skill authoring with CSO optimization, TDD testing methodology, and anti-rationalization patterns |
为 Rune skill 库创建和维护 skill 的元技能。
核心方法论： TDD applied to process documentation — 未观察到 agent 在无 skill 时失败，就不知道 skill 是否教了正确的东西。
启动时公告： "使用 writing-skills skill 创建/修改 skill。"
创建： agent 自然行为会出错的技术方法 | 跨项目可复用 | 模式适用广泛
不创建： 一次性方案 | 标准实践已有完整文档 | 项目特定约定（放 CLAUDE.md）| 可用 hook 强制执行的约束（用 hook，不浪费文档）
.claude/skills/
skill-name/
SKILL.md # 主文件（必须）
supporting-file.* # 仅在需要时（重参考 100+ 行、prompt 模板）
扁平命名空间。所有 skill 在同一可搜索空间下。
Description 是 Claude 决定是否加载 skill 的唯一入口。写错 = skill 形同虚设。
# ❌ 总结了流程 — Claude 会按 description 执行，跳过正文
description: Use when executing plans — dispatches subagent per task with two-stage review
# ✅ 只有触发条件
description: Use when executing implementation plans with independent tasks
为什么关键： 测试证明，description 总结流程时 Claude 直接按描述执行（如只做一次审查），忽略 SKILL.md 中的详细流程图（如两段审查）。去掉流程摘要后 Claude 才会正确读取完整内容。
用 Claude 会搜索的词汇：错误信息（"race condition"）、症状（"flaky"）、同义词（"timeout/hang/freeze"）、工具名（实际命令、库名）。
动词优先：writing-skills 非 skill-creation，using-git-worktrees 非 git-worktree-usage。
---
name: skill-name-with-hyphens # 仅字母、数字、连字符
description: Use when [触发条件]
---
可选字段：origin（来源标记）、metadata（author、version 等）。
# Skill Name
## 概述
核心原则，1-2 句。
## 何时使用
触发条件 + 不适用场景
## 核心模式
Before/after 代码对比（内联或链接到单独文件）
## 快速参考
表格或列表
## 常见错误
出错 + 修复
## Red Flags（纪律型 skill 必须）
借口 → 现实对照表
using-rune 始终加载，每个 token 都有成本。
| Skill 类型 | 目标字数 |
|---|---|
| 始终加载（using-rune） | <300 词 |
| 其他 skill | <500 词 |
技巧： 重参考移到单独文件，SKILL.md 只链接 | 交叉引用用 skill name 不重复内容 | 一个优质示例胜过多语言重复 | 消除与交叉引用 skill 的冗余
铁律： NO SKILL WITHOUT A FAILING TEST FIRST
| TDD 概念 | Skill 创建对应 |
|---|---|
| 测试用例 | subagent 压力场景 |
| 生产代码 | SKILL.md |
| RED | 无 skill → agent 违反规则（baseline） |
| GREEN | 有 skill → agent 遵守 |
| REFACTOR | 堵住新发现的绕过方式 |
无 skill 时用 subagent 运行压力场景，记录 agent 的选择、理由（逐字）、触发违反的压力类型。
针对 baseline 发现的具体理由写 skill。用有 skill 的同样场景再测，确认 agent 遵守。
agent 找到新理由绕过 → 加显式对策 → 重测直到无法绕过。
| Skill 类型 | 测试方法 | 成功标准 |
|---|---|---|
| 流程型（纪律执行） | 学术问题 + 压力场景 + 组合压力 | 最大压力下仍遵守 |
| 模式型（思维框架） | 识别场景 + 应用场景 + 反例 | 正确识别何时用/何时不用 |
| 参考型（文档/API） | 检索 + 应用 + 缺口测试 | 找到并正确应用信息 |
纪律型 skill 需要显式堵住绕过理由。
# ❌ 只写规则
写代码前没写测试？删掉它。
# ✅ 堵住所有变体
写代码前没写测试？删掉它。从头来。
**无例外：**
- 不保留作"参考"
- 不在写测试时"适配"已有代码
- 不看它
- 删就是删
**违反字面就是违反精神。**
切断"我在遵循精神"类借口。
从 baseline 测试收集所有借口：
| 借口 | 现实 |
|------|------|
| "这个简单，不用测试" | 简单代码也出错。测试只要 30 秒。 |
| "先实现再补测试" | 测试立刻通过什么也证明不了。 |
## Red Flags
- 先写代码再写测试
- "这个太简单不需要"
- "这次特殊因为..."
**出现任何一条 = 停下，从头来。**
每个 skill 创建/修改后必须完成：
| 借口 | 现实 |
|---|---|
| "skill 内容很清楚，不用测" | 对你清楚 ≠ 对其他 agent 清楚 |
| "只是参考文档" | 参考文档也有缺口。测检索。 |
| "测 skill 太费事" | 部署有问题的 skill 费更多事 |
| "我先写完再一起测" | 批量创建不测试 = 部署未测代码 |
| "这个改动很小不用测" | 小改动也能引入歧义 |
Use when starting any creative work — creating features, components, or functionality, modifying behavior, or solving ambiguous problems — before design or implementation. Covers product discovery, competitive research, feature analysis, technical design, and capability spec writing. Applies to every project; routes to writing-plans (non-UI) or design-workflow (UI).
Use when finishing an edit to source files — runs format, typecheck, and console.log detection before moving to the next task.
Use when implementation of a bug fix or feature task is complete — dispatches the appropriate language and global reviewers and returns a binary APPROVE/BLOCK verdict.
Use when about to git commit — validates commit message format, lints staged files, and scans staged content for secrets and debug artifacts.
Use when reaching the design-workflow V2-4 hard gate — adversarially reviews design artifacts (token coverage, contract completeness, artifact consistency, accessibility docs, responsive coverage, DESIGN.md compliance) against docs/designs/<feature>/ before development handoff.
Use when a task involves UI — new pages, components, visual interactions, or design tokens — including work in docs/designs/, *.pen files, or with Pencil MCP tools. Skip for backend-only, config-only, or refactoring without visual impact. Routes to writing-plans on completion.