Back to Details

using-skills

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Getting Started with Skills

技能使用入门

Critical Rules

关键规则

  1. Use Read tool before announcing skill usage. The session-start hook does NOT read skills for you. Announcing without calling Read = lying.
  2. Follow mandatory workflows. Brainstorming before coding. Check for skills before ANY task.
  3. Create TodoWrite todos for checklists. Mental tracking = steps get skipped. Every time.
  1. 在宣布使用技能前必须使用Read工具。会话启动钩子不会自动为你读取技能内容。未调用Read就宣布使用技能等同于违规。
  2. 遵循强制工作流。编码前先进行头脑风暴。在执行任何任务前都要检查是否有可用技能。
  3. 为检查项创建TodoWrite待办事项。仅靠大脑追踪步骤必然会导致遗漏。

Mandatory Workflow: Before ANY Task

强制工作流：执行任何任务前

1. Check skills list at session start, or run 
find-skills [PATTERN]
to filter.
2. If relevant skill exists, YOU MUST use it:
  • Use Read tool with full path: 
    ${SUPERPOWERS_SKILLS_ROOT}/skills/category/skill-name/SKILL.md
  • Read ENTIRE file, not just frontmatter
  • Announce: "I've read [Skill Name] skill and I'm using it to [purpose]"
  • Follow it exactly
Don't rationalize:
  • "I remember this skill" - Skills evolve. Read the current version.
  • "Session-start showed it to me" - That was using-skills/SKILL.md only. Read the actual skill.
  • "This doesn't count as a task" - It counts. Find and read skills.
Why: Skills document proven techniques that save time and prevent mistakes. Not using available skills means repeating solved problems and making known errors.
If a skill for your task exists, you must use it or you will fail at your task.
1. 检查技能列表：在会话开始时查看，或运行
find-skills [PATTERN]
进行筛选。
2. 若存在相关技能，你必须使用它：
  • 使用Read工具并指定完整路径：
    ${SUPERPOWERS_SKILLS_ROOT}/skills/category/skill-name/SKILL.md
  • 阅读整个文件，而不仅仅是前置元数据
  • 宣布："我已阅读[技能名称]技能，并将用它来[用途]"
  • 严格按照技能内容执行
请勿找借口：
  • "我记得这个技能"——技能会迭代更新，请阅读当前版本。
  • "会话启动时已经展示过它了"——那仅展示了using-skills/SKILL.md的内容，请阅读实际的技能文档。
  • "这不算是正式任务"——所有事项都算。请查找并阅读相关技能。
原因： 技能文档记录了经过验证的技巧，能节省时间并避免错误。不使用可用技能意味着重复解决已解决的问题，犯下已知的错误。
如果存在适用于你任务的技能，你必须使用它，否则任务将会失败。

Skills with Checklists

带检查项的技能

If a skill has a checklist, YOU MUST create TodoWrite todos for EACH item.
Don't:
  • Work through checklist mentally
  • Skip creating todos "to save time"
  • Batch multiple items into one todo
  • Mark complete without doing them
Why: Checklists without TodoWrite tracking = steps get skipped. Every time. The overhead of TodoWrite is tiny compared to the cost of missing steps.
Examples: skills/testing/test-driven-development/SKILL.md, skills/debugging/systematic-debugging/SKILL.md, skills/meta/writing-skills/SKILL.md
如果某个技能包含检查项，你必须为每一项创建TodoWrite待办事项。
严禁：
  • 仅在脑中过一遍检查项
  • 以"节省时间"为借口跳过创建待办事项
  • 将多个检查项合并为一个待办事项
  • 未执行就标记完成
原因： 没有TodoWrite追踪的检查项必然会导致步骤遗漏。与遗漏步骤的代价相比，使用TodoWrite的成本微乎其微。
示例： skills/testing/test-driven-development/SKILL.md、skills/debugging/systematic-debugging/SKILL.md、skills/meta/writing-skills/SKILL.md

Announcing Skill Usage

宣布技能使用情况

After you've read a skill with Read tool, announce you're using it:
"I've read the [Skill Name] skill and I'm using it to [what you're doing]."
Examples:
  • "I've read the Brainstorming skill and I'm using it to refine your idea into a design."
  • "I've read the Test-Driven Development skill and I'm using it to implement this feature."
  • "I've read the Systematic Debugging skill and I'm using it to find the root cause."
Why: Transparency helps your human partner understand your process and catch errors early. It also confirms you actually read the skill.
使用Read工具阅读技能后，需宣布你将使用该技能：
"我已阅读[技能名称]技能，并将用它来[你要执行的操作]。"
示例：
  • "我已阅读头脑风暴技能，并将用它来把你的想法细化为设计方案。"
  • "我已阅读测试驱动开发技能，并将用它来实现这个功能。"
  • "我已阅读系统化调试技能，并将用它来查找问题根源。"
原因： 透明化的操作能帮助你的人类伙伴理解你的流程，并尽早发现错误。同时也能确认你确实阅读了该技能文档。

How to Read a Skill

如何阅读技能文档

Every skill has the same structure:
  1. Frontmatter - 
    when_to_use
    tells you if this skill matches your situation
  2. Overview - Core principle in 1-2 sentences
  3. Quick Reference - Scan for your specific pattern
  4. Implementation - Full details and examples
  5. Supporting files - Load only when implementing
Many skills contain rigid rules (TDD, debugging, verification). Follow them exactly. Don't adapt away the discipline.
Some skills are flexible patterns (architecture, naming). Adapt core principles to your context.
The skill itself tells you which type it is.
每个技能文档都遵循相同的结构：
  1. 前置元数据 - 
    when_to_use
    字段会告诉你该技能是否适用于当前场景
  2. 概述 - 用1-2句话说明核心原则
  3. 快速参考 - 快速查找你需要的特定模式
  4. 实施细节 - 完整的细节和示例
  5. 支持文件 - 仅在实施时加载
许多技能包含严格规则（如TDD、调试、验证）。请严格遵循，不要随意调整规则的严谨性。
部分技能是灵活的模式（如架构、命名）。可根据实际环境调整核心原则。
技能文档本身会说明它属于哪一类。

Instructions ≠ Permission to Skip Workflows

指令≠跳过工作流的许可

Your human partner's specific instructions describe WHAT to do, not HOW.
"Add X", "Fix Y" = the goal, NOT permission to skip brainstorming, TDD, or RED-GREEN-REFACTOR.
Red flags: "Instruction was specific" • "Seems simple" • "Workflow is overkill"
Why: Specific instructions mean clear requirements, which is when workflows matter MOST. Skipping process on "simple" tasks is how simple tasks become complex problems.
人类伙伴的具体指令描述的是要做什么，而非怎么做。
"添加X"、"修复Y"是目标，而非允许你跳过头脑风暴、TDD或RED-GREEN-REFACTOR（红-绿-重构）流程的许可。
危险信号： "指令很具体"•"看起来很简单"•"工作流太繁琐"
原因： 具体的指令意味着明确的需求，而这正是工作流最重要的时刻。在"简单"任务上跳过流程，正是简单任务演变为复杂问题的原因。

Summary

总结

Starting any task:
  1. Run find-skills to check for relevant skills
  2. If relevant skill exists → Use Read tool with full path (includes /SKILL.md)
  3. Announce you're using it
  4. Follow what it says
Skill has checklist? TodoWrite for every item.
Finding a relevant skill = mandatory to read and use it. Not optional.
开始任何任务时：
  1. 运行find-skills检查是否有相关技能
  2. 若存在相关技能→使用Read工具并指定完整路径（需包含/SKILL.md）
  3. 宣布你将使用该技能
  4. 严格按照技能内容执行
技能包含检查项？ 为每一项创建TodoWrite待办事项。
找到相关技能=必须阅读并使用它，而非可选操作。