writing-skills
当创建新技能、编辑现有技能或在部署前验证技能是否有效时使用
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
Not yet listed on ClawHub or SkillsMP
// README
superpowers-zh(AI 编程超能力 · 中文增强版)
🌐 简体中文 | 繁體中文 | English (upstream)
🦸 superpowers(300k+ ⭐)完整汉化 + 4 个中国原创 skills — 让 Claude Code / Copilot CLI / Hermes Agent / Cursor / Windsurf / Kiro / Gemini CLI / Qoder 等 26 款 AI 编程工具真正会干活。从头脑风暴到代码审查,从 TDD 到调试,每个 skill 都是经过实战验证的工作方法论。
Chinese community edition of superpowers — 21 skills across 26 AI coding tools, including full translations and China-specific development skills.
📖 免费配套学习 → 从零学会 AI 编程(182 节)+ 从零构建 AI 智能体(40 节):两门免费实操课 + 实战社区,superpowers 装好后配上方法论效率翻倍(站上共 14 门课、700 节,全部 ¥0——另有 大模型原理 / AI 绘画 / 写小说 / 漫剧 / 量化 / DeepSeek / 深度专注 等)
🧠 新:让 Claude Code / Codex / Cursor / Gemini CLI 不再失忆 → engram:一条
npx @jnmetacode/engram install,自动记住每次会话问过什么、改了哪些文件、最后怎么解决的,下次开会话自动带回(带出处)。记忆跨工具共享——Codex 里定的事,Claude Code 也知道。全本地、零依赖、中文友好。
📊 项目规模
| 📦 翻译 Skills | 🇨🇳 中国原创 Skills | 🤖 支持工具 |
|---|---|---|
| 15 | 4另有 2 个上游历史保留 | Claude Code / Copilot CLI / Hermes Agent / Cursor / Windsurf / Kiro / Gemini CLI / Codex / Aider / Trae / VS Code (Copilot) / DeerFlow / OpenCode / OpenClaw / Qwen Code / Antigravity / Claw Code / Qoder / CodeBuddy(腾讯)/ CodeArts(华为云码道)/ Cline / Kilo Code / Crush |
❤️ 赞助商 🙏 想出现在这里?联系 [email protected] 赞助
感谢 APINEBULA 大屏赞助本项目!APINEBULA 是银河录像局旗下的企业级 AI 聚合平台,背靠大平台资源,面向开发者、团队与企业用户提供稳定、高性价比的大模型 API 接入服务。平台聚合 Claude、GPT、Gemini 等主流满血模型,一个接口接入全球顶尖 AI 大模型,各大模型价格低至 1 折起,支持企业级高并发、正式合同、对公打款与开票服务,适合 AI 编程、Agent 开发、业务系统集成等多种场景!
🎁 通过此链接注册并在充值时填写 agent 优惠码可享 9 折优惠!
感谢 APIXO 赞助本项目!无需编程,在 APIXO 网页端即可生成 AI 图片与视频,也可通过 API 接入自己的应用与自动化工作流。黑五期间,seedream5.5仅 $0.014/张,原价 $0.02/张,限时 7 折。指定模型与规格较活动页列示的市场参考价最高省 66%,优惠自动生效,无需优惠码。活动截至北京时间 2026 年 12 月 31 日 23:59。 查看 APIXO 黑五优惠 →
88API Token聚合平台 🧠 聚合 GPT、Claude、Gemini、Grok、DeepSeek、Kimi、GLM 等语言与编程模型; 🎨 图片模型:GPT-Image、Gemini、Grok 等; 🎬 视频模型:Seedance、Veo、MiniMax H3、Kling、Grok 等; 🎙️ 语音能力:Whisper、TTS 等。从文案、出图、改图,到视频生成与配音 🎁新用户注册送体验额度,可以检测模型能力。站内有人工客服值守! 👉香港正规企业运营 稳定供应 全绿满血 不降智 提供发票
感谢 Cubence 对本项目的支持。Cubence 是一家致力为客户提供稳定、高效的 API 中转服务商。从 25 年 9 月运营至今,提供了 Claude Code、Codex、Gemini 等多种模型支持。🎁 Cubence 为本开源项目的用户提供了特别的专属优惠码 AGENCY,通过此链接注册的用户,首次购买即可享受 9 折优惠!
感谢 字节火山引擎 赞助本项目!火山方舟 Agent/Coding Plan 国模套餐首购 9.9,支持 GLM-5.3、Kimi-K3、DeepSeek、MiniMax、Doubao 等,注册免费领 2500w Token,统一 API,适配编码与智能体开发。👉 立即前往
这是什么?
superpowers 是目前最火的 AI 编程 skills 框架(300k+ stars),为 AI 编程工具提供系统化的工作方法论。
superpowers-zh 在完整翻译的基础上,新增了面向中国开发者的特色 skills。
没装 superpowers-zh:
你:给用户模块加个批量导出功能
AI:好的,我来实现...(直接开始写代码)
export async function exportUsers() { ... }
你:等等,格式不对,没分页,大数据量会 OOM...
装了 superpowers-zh:
你:给用户模块加个批量导出功能
AI:在开始实现之前,我需要了解几个关键问题:
1. 导出格式是 CSV 还是 Excel?
2. 预计数据量多大?需要异步处理吗?
3. 有权限要求吗?
→ 给出 2-3 个方案,确认后再动手
🆚 与英文上游的区别(老被问,一次说清)
| 维度 | superpowers(英文上游) | superpowers-zh(中文增强版) |
|---|---|---|
| ⭐ Star 数 | 300k+ | — |
| 📦 Skills 总数 | 15 | 21(15 翻译 + 4 国产原创 + 2 上游历史保留) |
| 🌐 语言 | 英文 | 中文(技术术语保留英文) |
| 🤖 支持工具 | 6 款:Claude Code / Cursor / Codex / OpenCode / Copilot CLI / Gemini CLI | 26 款:上述 6 款 + Hermes Agent / Trae / Kiro / Qwen Code / OpenClaw / Claw Code / Antigravity / DeerFlow / VS Code / Windsurf / Aider / Qoder / CodeBuddy(腾讯) / CodeArts(华为云码道) / Cline / Kilo Code / Crush / ZCode(智谱)/ DeepSeek Harness / Reasonix |
| ⚡ 安装方式 | 按工具分别装(每款一条不同的 plugin marketplace 命令) | npx superpowers-zh 一条命令自动识别项目里的工具并安装;识别不出可 --tool <name> 显式指定 |
| 🇨🇳 Git 平台 | GitHub 为主 | GitHub + Gitee + Coding + 极狐 GitLab + CNB(腾讯云原生构建) |
| 🇨🇳 CI/CD 示例 | GitHub Actions | GitHub Actions + Gitee Go + Coding CI + 极狐 CI + .cnb.yml |
| 🇨🇳 代码审查风格 | 西方直接风格 | 适配国内团队沟通文化 |
| 🇨🇳 Git 提交规范 | 无 | Conventional Commits 中文适配 |
| 🇨🇳 中文文档规范 | 无 | 中文排版 + 中英混排规则 + 告别机翻味 |
| ➕ MCP 服务器构建 | 无 | 独立 mcp-builder skill |
| ➕ 工作流执行器 | 无 | 独立 workflow-runner skill(多角色 YAML 编排) |
| ➕ 翻译 skill 内的增量 | — | using-superpowers 保留显式标注的「中国特色技能路由」;brainstorming 补充「你看着办 / 你定吧」不等于跳过流程的中文语境说明,依据与 eval 范围见 v1.8.0 更新日志。executing-plans 原有「常见异常处理」已于 v1.7.14 删除,避免与上游内联执行流程冲突。 |
| 🔄 版本跟进 | 独立迭代 | 同步上游 + 国产增量叠加 |
| 🤝 接受新 skill PR | 一般不接受(原文:"we don't generally accept contributions of new skills") | 欢迎 PR(中国开发者痛点优先) |
| 💬 社区 | Discord | 微信公众号「AI不止语」 |
// HOW IT'S BUILT
// FILES
2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
skills/writing-skills/SKILL.md14 KBupstream ↗
--- name: writing-skills description: 当创建新技能、编辑现有技能或在部署前验证技能是否有效时使用 version: "1.0.0" license: MIT metadata: hermes: tags: [skills, documentation] --- # 编写技能 ## 概述 **编写技能就是将测试驱动开发应用于流程文档。** **个人技能存放在智能体特定的目录中(Claude Code 用 `~/.claude/skills`,Codex 用 `~/.agents/skills/`)** 你编写测试用例(带子智能体的压力场景),观察它们失败(基线行为),编写技能(文档),观察测试通过(智能体遵守规则),然后重构(堵住漏洞)。 **核心原则:** 如果你没有观察到智能体在没有该技能时失败,你就不知道这个技能是否教了正确的东西。 **必需背景:** 在使用此技能前,你必须理解 test-driven-development。该技能定义了基本的红-绿-重构循环。本技能将 TDD 适配到文档编写中。 **官方指南:** Anthropic 官方的技能编写最佳实践请参见 anthropic-best-practices.md。该文档提供了补充本技能 TDD 导向方法的额外模式和指南。 ## 什么是技能? **技能**是经过验证的技术、模式或工具的参考指南。技能帮助未来的 Claude 实例找到并应用有效的方法。 **技能是:** 可复用的技术、模式、工具、参考指南 **技能不是:** 关于你某次如何解决问题的叙事 ## TDD 映射到技能 | TDD 概念 | 技能创建 | |----------|---------| | **测试用例** | 带子智能体的压力场景 | | **生产代码** | 技能文档(SKILL.md) | | **测试失败(红)** | 智能体在没有技能时违反规则(基线) | | **测试通过(绿)** | 智能体在有技能时遵守规则 | | **重构** | 在保持合规的同时堵住漏洞 | | **先写测试** | 在编写技能之前先运行基线场景 | | **观察失败** | 记录智能体使用的确切合理化借口 | | **最小代码** | 编写针对那些具体违规行为的技能 | | **观察通过** | 验证智能体现在遵守规则 | | **重构循环** | 发现新的合理化借口 → 堵住 → 重新验证 | 整个技能创建过程遵循红-绿-重构。 ## 何时创建技能 **创建条件:** - 技术对你来说不是直觉上显而易见的 - 你会在不同项目中反复引用 - 模式具有广泛适用性(非项目特定) - 其他人也会受益 **不要创建:** - 一次性解决方案 - 其他地方有充分文档的标准实践 - 项目特定的约定(放在 CLAUDE.md 中) - 机械性约束(如果可以用正则/验证强制执行,就自动化——文档留给需要判断的场景) ## 技能类型 ### 技术类 有具体步骤的方法(condition-based-waiting、root-cause-tracing) ### 模式类 思考问题的方式(flatten-with-flags、test-invariants) ### 参考类 API 文档、语法指南、工具文档(office docs) ## 目录结构 ``` skills/ skill-name/ SKILL.md # 主参考文档(必需) supporting-file.* # 仅在需要时 ``` **扁平命名空间** - 所有技能在一个可搜索的命名空间中 **分离文件的情况:** 1. **大量参考内容**(100+ 行)- API 文档、全面的语法说明 2. **可复用工具** - 脚本、实用程序、模板 **保持内联:** - 原则和概念 - 代码模式(< 50 行) - 其他所有内容 ## SKILL.md 结构 **Frontmatter(YAML):** - 两个必需字段:`name` 和 `description`(完整支持字段参见 [agentskills.io/specification](https://agentskills.io/specification)) - 总计最多 1024 字符 - `name`:只使用字母、数字和连字符(不要用括号、特殊字符) - `description`:第三人称,仅描述何时使用(不是做什么) - 以"Use when..."开头,聚焦于触发条件 - 包含具体的症状、场景和上下文 - **绝不总结技能的流程或工作流**(参见 SDO 章节了解原因) - 尽量控制在 500 字符以内 ```markdown --- name: Skill-Name-With-Hyphens description: Use when [具体的触发条件和症状] --- # 技能名称 ## 概述 这是什么?用 1-2 句话说明核心原则。 ## 何时使用 [如果决策不明显,使用小型内联流程图] 症状和用例的要点列表 不适用的场景 ## 核心模式(技术/模式类) 前后代码对比 ## 快速参考 用于快速浏览常见操作的表格或要点 ## 实现 简单模式内联代码 大量参考或可复用工具链接到文件 ## 常见错误 常见问题 + 修复方法 ## 实际效果(可选) 具体结果 ``` ## 技能发现优化(SDO) **发现至关重要:** 未来的 Claude 需要找到你的技能 ### 1. 丰富的描述字段 **目的:** Claude 读取描述来决定为当前任务加载哪些技能。让它能回答:"我现在应该读这个技能吗?" **格式:** 以"Use when..."开头,聚焦于触发条件 **关键:描述 = 何时使用,不是技能做什么** 描述应该只描述触发条件。不要在描述中总结技能的流程或工作流。 **为什么这很重要:** 测试表明,当描述总结了技能的工作流时,Claude 可能会跟随描述而非阅读完整的技能内容。一个写着"任务间进行代码审查"的描述导致 Claude 只做了一次审查,尽管技能的流程图清楚地展示了两次审查(先规格合规再代码质量)。 当描述改为仅"在当前会话中执行包含独立任务的实现计划时使用"(无工作流摘要)时,Claude 正确地阅读了流程图并遵循了两阶段审查流程。 **陷阱:** 总结工作流的描述创建了 Claude 会走的捷径。技能正文变成了 Claude 跳过的文档。 ```yaml # 错误:总结了工作流 - Claude 可能会跟随描述而非阅读技能 description: Use when executing plans - dispatches subagent per task with code review between tasks # 错误:流程细节太多 description: Use for TDD - write test first, watch it fail, write minimal code, refactor # 正确:只有触发条件,无工作流摘要 description: Use when executing implementation plans with independent tasks in the current session # 正确:仅触发条件 description: Use when implementing any feature or bugfix, before writing implementation code ``` **内容:** - 使用具体的触发条件、症状和场景来表明此技能适用 - 描述问题(竞态条件、行为不一致)而非语言特定的症状(setTimeout、sleep) - 保持触发条件技术无关,除非技能本身是技术特定的 - 如果技能是技术特定的,在触发条件中明确说明 - 用第三人称写(注入到系统提示中) - **绝不总结技能的流程或工作流** ```yaml # 错误:太抽象、模糊,未包含何时使用 description: For async testing # 错误:第一人称 description: I can help you with async tests when they're flaky # 错误:提到了技术但技能并非该技术特定的 description: Use when tests use setTimeout/sleep and are flaky # 正确:以"Use when"开头,描述问题,无工作流 description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently # 正确:技术特定的技能带有明确的触发条件 description: Use when using React Router and handling authentication redirects ``` ### 2. 关键词覆盖 使用 Claude 会搜索的词语: - 错误信息:"Hook timed out"、"ENOTEMPTY"、"race condition" - 症状:"flaky"、"hanging"、"zombie"、"pollution" - 同义词:"timeout/hang/freeze"、"cleanup/teardown/afterEach" - 工具:实际命令、库名称、文件类型 ### 3. 描述性命名 **使用主动语态,动词优先:** - ✅ `creating-skills` 而非 `skill-creation` - ✅ `condition-based-waiting` 而非 `async-test-helpers` ### 4. Token 效率(关键) **问题:** getting-started 和频繁引用的技能会加载到每个对话中。每个 token 都很重要。 **目标字数:** - getting-started 工作流:每个 <150 词 - 频繁加载的技能:总计 <200 词 - 其他技能:<500 词(仍要简洁) **技巧:** **将细节移到工具帮助中:** ```bash # 错误:在 SKILL.md 中列出所有参数 search-conversations supports --text, --both, --after DATE, --before DATE, --limit N # 正确:引用 --help search-conversations 支持多种模式和过滤器。运行 --help 查看详情。 ``` **使用交叉引用:** ```markdown # 错误:重复工作流细节 搜索时,用模板分派子智能体…… [20 行重复的说明] # 正确:引用其他技能 始终使用子智能体(节省 50-100 倍上下文)。必需:使用 [other-skill-name] 工作流。 ``` **压缩示例:** ```markdown # 错误:冗长的示例(42 词) 你的搭档:"我们之前是怎么处理 React Router 中的认证错误的?" 你:我来搜索过去对话中的 React Router 认证模式。 [用搜索查询分派子智能体:"React Router authentication error handling 401"] # 正确:精简的示例(20 词) 搭档:"我们之前是怎么处理 React Router 中的认证错误的?" 你:正在搜索…… [分派子智能体 → 整合] ``` **消除冗余:** - 不要重复交叉引用的技能中已有的内容 - 不要解释从命令中就能看出的东西 - 不要为同一模式提供多个示例 **验证:** ```bash wc -w skills/path/SKILL.md # getting-started 工作流:目标 <150 每个 # 其他频繁加载的:目标总计 <200 ``` **用你做的事或核心洞察来命名:** - ✅ `condition-based-waiting` > `async-test-helpers` - ✅ `using-skills` 而非 `skill-usage` - ✅ `flatten-with-flags` > `data-structure-refactoring` - ✅ `root-cause-tracing` > `debugging-techniques` **动名词(-ing)适合描述流程:** - `creating-skills`、`testing-skills`、`debugging-with-logs` - 主动的,描述你正在进行的操作 ### 5. 交叉引用其他技能 **编写引用其他技能的文档时:** 仅使用技能名称,带有明确的必需标记: - ✅ 好的:`**必需子技能:** 使用 test-driven-development` - ✅ 好的:`**必需背景:** 你必须理解 systematic-debugging` - ❌ 差的:`参见 skills/testing/test-driven-development`(不清楚是否必需) - ❌ 差的:`@skills/testing/test-driven-development/SKILL.md`(强制加载,浪费上下文) **为什么不用 @ 链接:** `@` 语法会立即强制加载文件,在你需要之前就消耗 200k+ 的上下文。 ## 流程图使用 ```dot digraph when_flowchart { "需要展示信息?" [shape=diamond]; "我可能在决策中犯错?" [shape=diamond]; "使用 markdown" [shape=box]; "小型内联流程图" [shape=box]; "需要展示信息?" -> "我可能在决策中犯错?" [label="是"]; "我可能在决策中犯错?" -> "小型内联流程图" [label="是"]; "我可能在决策中犯错?" -> "使用 markdown" [label="否"]; } ``` **仅在以下情况使用流程图:** - 非显而易见的决策点 - 你可能过早停止的流程循环 - "何时使用 A vs B"的决策 **绝不使用流程图用于:** - 参考资料 → 表格、列表 - 代码示例 → Markdown 代码块 - 线性指令 → 编号列表 - 无语义意义的标签(step1、helper2) 参见 @graphviz-conventions.dot 了解 graphviz 样式规则。 **为你的搭档可视化:** 使用此目录中的 `render-graphs.js` 将技能的流程图渲染为 SVG: ```bash ./render-graphs.js ../some-skill # 每个图表分别渲染 ./render-graphs.js ../some-skill --combine # 所有图表合并为一个 SVG ``` ## 代码示例 **一个优秀的示例胜过多个平庸的** 选择最相关的语言: - 测试技术 → TypeScript/JavaScript - 系统调试 → Shell/Python - 数据处理 → Python **好的示例:** - 完整可运行 - 注释良好,解释为什么 - 来自真实场景 - 清晰展示模式 - 可以直接适配(不是通用模板) **不要:** - 用 5 种以上语言实现 - 创建填空模板 - 写人为构造的示例 你擅长语言移植——一个优秀的示例就够了。 ## 文件组织 ### 自包含技能 ``` defense-in-depth/ SKILL.md # 所有内容内联 ``` 适用场景:所有内容都能放下,无需大量参考 ### 带可复用工具的技能 ``` condition-based-waiting/ SKILL.md # 概述 + 模式 example.ts # 可适配的工作代码 ``` 适用场景:工具是可复用的代码,不只是叙述 ### 带大量参考的技能 ``` pptx/ SKILL.md # 概述 + 工作流 pptxgenjs.md # 600 行 API 参考 ooxml.md # 500 行 XML 结构 scripts/ # 可执行工具 ``` 适用场景:参考资料太多无法内联 ## 铁律(与 TDD 相同) ``` 没有失败的测试就不写技能 ``` 这适用于新技能和对现有技能的编辑。 先写技能再测试?删掉它。重新开始。 编辑技能不测试?同样违规。 **无例外:** - 不适用于"简单的添加" - 不适用于"只是加一个章节" - 不适用于"文档更新" - 不要保留未测试的更改作为"参考" - 不要在运行测试时"调整" - 删除就是删除 **必需背景:** test-driven-development 技能解释了为什么这很重要。相同的原则适用于文档。 ## 测试所有技能类型 不同类型的技能需要不同的测试方法: ### 纪律执行类技能(规则/要求) **例如:** TDD、完成前验证、编码前设计 **测试方式:** - 学术性问题:它们理解规则吗? - 压力场景:它们在压力下遵守吗? - 多重压力组合:时间 + 沉没成本 + 疲惫 - 识别合理化借口并添加明确的反驳 **成功标准:** 智能体在最大压力下遵循规则 ### 技术类技能(操作指南) **例如:** condition-based-waiting、root-cause-tracing、defensive-programming **测试方式:** - 应用场景:它们能正确应用技术吗? - 变体场景:它们能处理边界情况吗? - 缺失信息测试:说明是否有遗漏? **成功标准:** 智能体成功将技术应用于新场景 ### 模式类技能(心智模型) **例如:** reducing-complexity、information-hiding 概念 **测试方式:** - 识别场景:它们能识别模式何时适用吗? - 应用场景:它们能使用心智模型吗? - 反例:它们知道何时不应用吗? **成功标准:** 智能体正确识别何时/如何应用模式 ### 参考类技能(文档/API) **例如:** API 文档、命令参考、库指南 **测试方式:** - 检索场景:它们能找到正确的信息吗? - 应用场景:它们能正确使用找到README.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/jnmetacode-superpowers-zh-skills-writing-skills.md