05. Skills 详解

什么是 Skill

Skill 是一段"带描述的指令集",Claude Code 在合适的时候会自动调用它。你可以把它理解成"我给 AI 写的一份 SOP(标准作业流程)"。

Skill 通常包含:

  • name:Skill 名称
  • description:何时调用(自动触发条件)
  • 指令正文:具体步骤

Skill 的调用机制

关键点:Claude 是根据 Skill 的 description 自动判断要不要用的。

  • description 写得越清楚,触发越准
  • 用户也可以用 /<skill-name> 显式调用
  • 触发后,Skill 的正文会被注入到上下文

一个最小 Skill 示例

文件名:~/.claude/skills/learning-tips/SKILL.md

---
name: learning-tips
description: Use when the user is learning a new concept or asking for study advice - provides evidence-based learning techniques like spaced repetition, active recall, and Feynman technique
---

When the user is studying or learning something:

1. First, ask them what they already know about the topic
2. Suggest they try explaining it in their own words (Feynman technique)
3. Recommend spaced repetition: review at 1 day, 3 days, 7 days, 30 days
4. Provide 2-3 practice questions they can try
5. Always encourage teaching it back to someone else

Format response as a supportive tutor, not a lecturer.

常用内置 Skill(以 superpowers 系列为例)

Skill用途
superpowers:brainstorming任何创造工作前必须用——澄清意图、需求、设计
superpowers:test-driven-development写代码前先写测试
superpowers:systematic-debugging调试时用——根因分析而不是乱试
superpowers:writing-plans多步骤任务先写计划
superpowers:verification-before-completion声称完成前必须验证
superpowers:using-superpowers对话开始就用——指导你怎么用 skills
brainstorming-v2把模糊想法变成可执行方案——澄清意图 → 多轮提问 → 2-3 个备选 → 逐节确认 → 落档为 spec(详见下一节)

怎么用 Skill

显式调用

> 用 superpowers:brainstorming 帮我设计一个学生作业自动评分系统

让 Claude 自动用

只需要描述你的需求,如果 description 写得清楚,Claude 会自己挑合适的 Skill。

Skill 的存放位置

位置作用范围
~/.claude/skills/<name>/SKILL.md所有项目都能用
<project>/.claude/skills/<name>/SKILL.md仅当前项目
插件市场通过插件安装

自己写 Skill 的要点

description 是灵魂

❌ 不好:

description: Helps with Python

✅ 好:

description: Use when writing Python data processing scripts - enforces type hints, docstrings, pandas usage patterns, and avoids for loops in favor of vectorized operations

指令要可执行

不要写"请好好写代码",要写:

  • 具体步骤(1, 2, 3)
  • 具体检查项
  • 具体输出格式

包含反例

## Don't

- Don't use var, only let/const
- Don't suggest using jQuery for new projects

给教师的实用 Skill 模板

模板 1:作业点评助手

---
name: assignment-grader
description: Use when the user asks to grade student assignments or review submitted code - provides structured feedback focusing on correctness, style, and learning opportunities
---

When grading student assignments:

1. First identify the assignment requirements (ask if unclear)
2. Review the code for:
   - Correctness (does it solve the problem?)
   - Style (naming, structure, comments)
   - Edge cases (what about empty input, negative numbers?)
3. Provide feedback in three sections:
   - ✅ Strengths (be specific, mention 2-3 things they did well)
   - 🔧 Improvements (actionable, with code examples)
   - 💡 Concepts to review (link to 1-2 resources)
4. Never give a direct score - let the teacher decide
5. Always be encouraging - emphasize learning over judgment

模板 2:课程设计助手

---
name: course-designer
description: Use when designing a new course, lecture, or curriculum - applies backward design principles starting from learning outcomes
---

When designing a course or lecture:

1. Start by asking: what should students be able to DO after this?
2. Define 3-5 measurable learning outcomes (use Bloom's taxonomy verbs)
3. Design assessments that prove those outcomes
4. Then design learning activities that prepare for assessments
5. Finally, decide what content to teach
6. Output a syllabus with: outcomes, weekly topics, assignments, readings

应用介绍: brainstorm skill(把想法变成设计)

来源:brainstorming-v2。下面内容整理自该 skill 的 SKILL.md。

一句话定义

把脑子里一个模糊的想法,通过多轮对话打磨成一份可执行的方案文档(spec),然后交给 writing-plans 生成实施计划。

和"普通提问"最大的区别:它不让你一次说完需求,而是一次只问一个问题,一层层澄清。

一个必读的反模式警告(skill 原文)

"This Is Too Simple To Need A Design"

Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.

翻译:没有"太简单所以跳过设计"的项目。哪怕是改一个配置文件,设计可以很短(几句话),但必须呈现并获得你的确认。

8 步工作流(checklist)

调用 brainstorming-v2 后,Claude 会按顺序完成:

  1. 了解项目上下文 —— 看文件、文档、最近的提交
  2. (可选)询问是否启用浏览器伴侣 —— 如果接下来涉及视觉问题(mockup、布局),单独发一条消息问你是否要在浏览器里看
  3. 逐个提问澄清 —— 一次一个问题,优先多选,聚焦"目的 / 约束 / 成功标准"
  4. 提出 2-3 个方案 —— 带权衡分析,给推荐和理由
  5. 分段呈现设计 —— 架构 / 组件 / 数据流 / 错误处理 / 测试,每段独立确认
  6. 写设计文档 —— 落档到 docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md,提交到 git
  7. spec 自检 —— 检查占位符、内部矛盾、歧义、范围,有问题就地修
  8. 用户审阅 → 转入 writing-plans —— 你确认后,只调用 writing-plans 写实施计划,不调其他实现类 skill

流程图(简化)

[看项目上下文]
   ↓
[是否要视觉内容?]
   是 → [单独发消息,问你要不要浏览器伴侣] → ↓
   否 ───────────────────────────────────────→ ↓
                                                ↓
[逐个提问澄清]
   ↓
[给 2-3 个方案 + 推荐]
   ↓
[分段呈现设计] ←──→ (有疑问就回头改)
   ↓ (你说"OK")
[写 spec + 自检]
   ↓
[你审阅 spec] ←──→ (有改动则修)
   ↓ (批准)
[调用 writing-plans]

老师场景示例:从一句话到完整 spec

你输入:

> 我要下学期新开一门《行为经济学》,帮我设计一下。

Claude 不会一连串问完才开始,而是一次一个问题:

  1. 这门课的对象?(多选:本科 / 硕士 / MBA / 博士)
  2. 学生学过什么基础课?(开放)
  3. 学时?(单选:32 / 48 / 64)
  4. 课程结束后,学生能做什么?(用 Bloom 动词:能解释 / 能设计实验 / 能识别认知偏差)
  5. 有没有现成教材?(开放)
  6. 评估方式?(多选:闭卷 / 案例分析 / 小组项目 / 课程论文)
  7. ... 直到双方都明确"我们在做什么"

接着给你 2-3 个课程框架(比如"理论驱动 / 案例驱动 / 实验驱动"),带权衡和推荐。

你确认方向后,它逐段呈现:

  • 总体架构(16 周怎么切)
  • 教学单元(每个单元的 1 句话目标)
  • 评估体系(平时 / 期中 / 期末配比)
  • 错误处理(挂科、抄袭、讨论冷淡)
  • 测试(教学评估问卷、期中反馈)

每段你确认后,才进入下一段。最后落档到:

docs/superpowers/specs/2026-05-18-行为经济学-design.md

你和系里可以拿去审,审完再让 writing-plans 拆成可执行的周计划。

适合 / 不适合的场景

适合 ✅不适合 ❌
新开一门课(整体设计)改一个错别字
申报一个新课题(立项书)解释一段文字
设计一项调研(问卷 + 访谈)单点数据查询
设计一个教学案例库(框架 + 字段)已经有 spec、只缺执行的小活
设计一门 MOOC(章节 + 录制)简单改一份 docx 格式

几个关键原则(skill 原文)

  • 一次一个问题 —— 不要一连串发问
  • 多选优先 —— 比开放问题容易回答
  • YAGNI(You Aren't Gonna Need It) —— 设计里不必要的功能全砍
  • 探索多个方案 —— 永远先给 2-3 个再定
  • 逐段确认 —— 设计文档一段段过,不一次性给完整版
  • 保持灵活 —— 哪里不对就回头改

三个注意

  • 这个 skill 只产出 spec,不写代码也不直接动手。它的全部职责是"想清楚"。
  • spec 落地后,下一步只该调 writing-plans 写实施计划,不要跳到 frontend-design / mcp-builder 等其他实现类 skill。
  • 涉及视觉问题时,skill 会单独发一条消息问你要不要启用浏览器伴侣(网页 mockup、布局对比),不是默认行为。

调试 Skill 的小技巧

写完一个 Skill,可以用以下方式测试:

> 我在学习 JavaScript 的闭包概念,请给我一些学习建议

观察 Claude 是否自动调用了你的 learning-tips Skill。如果没有,看 description 写得够不够具体。

下一步