claude-howto 自评技能输出模板设计：用空白 Markdown 模板结构化 Claude Code 评估结果

本文围绕 claude-howto 仓库中 self-assessment 技能的输出模板文件 .claude/skills/self-assessment/references/output-templates.md 展开，完整拆解其 Quick Assessment、Deep Assessment 与 Learning Path 三套空白结果模板的字段设计、占位符约定与计分映射，并结合 SKILL.md 的"模板逐字重复"策略，讲清 Claude Code 技能（Skill）如何以纯 Markdown 约定实现确定性、可复用的结构化 Agent 输出。

一、背景：self-assessment 技能与输出模板的角色

claude-howto 是一个"示例驱动"的 Claude Code 教程仓库，除 10 个教学模块外，还在 .claude/skills/ 目录下内置了两个可直接被 Claude Code 调用的技能：self-assessment（能力自评与学习路径建议）与 lesson-quiz（单课测验）。两者的 README 与 根 README 均说明，用户可直接在 Claude Code 中运行 /self-assessment 获取自评结果。

从 SKILL.md 的 frontmatter 看，该技能当前版本为 2.3.0，其描述明确列出了触发语（"assess my level"、"take the quiz"、"where should I start"、"what should I learn next" 等），流程为五步：

1. Step 1：让用户选择评估模式（Quick 约 2 分钟 / Deep 约 5 分钟）；
2. Step 2A/2B：按模式提问（Quick 为 8 题多选，Deep 为 5 轮、每轮 4 选项覆盖 2 个主题）；
3. Step 3：计算并呈现结果；
4. Step 4：生成个性化学习路径；
5. Step 5：提供后续动作（开始学习 / 深挖薄弱点 / 练习项目 / 重测）。

输出模板文件正是 Step 3 与 Step 4 的"输出契约"。文件开头的定位说明很直接：

Blank markdown templates for the assessment results and learning path. The Step 3A/3B result templates and the Step 4 path-format template are duplicated verbatim in SKILL.md so results can be produced without re-reading this file.

即：模板是"空白骨架"，供模型在运行时填充占位符；并且 3A/3B 结果模板和 Step 4 路径模板会被逐字复制进 SKILL.md，保证技能无需重新读取这个 references 文件就能产出格式一致的结果。文末元信息显示模板最后更新于 2026-08-19，对应 Claude Code 版本 2.1.235。

二、模板一：Quick Assessment 结果（Step 3A）

Quick 模式只做 8 题经验勾选，按总分判级：0–2 分 Level 1（Beginner）、3–5 分 Level 2（Intermediate）、6–8 分 Level 3（Advanced）（计分规则见 SKILL.md Step 2A）。输出模板要求模型产出一篇结构固定的结果报告：

## Claude Code Skill Assessment Results

### Your Level: [Level 1: Beginner / Level 2: Intermediate / Level 3: Advanced]

You checked **N/8** items.

[One-line motivational summary based on level]

### Your Skill Profile

| Area | Status |
|------|--------|
| Basic CLI & Conversations | [Checked/Gap] |
| CLAUDE.md & Memory | [Checked/Gap] |
| Slash Commands (built-in) | [Checked/Gap] |
| Custom Commands & Skills | [Checked/Gap] |
| MCP Servers | [Hooks/Gap] |
| Hooks | [Checked/Gap] |
| Subagents | [Checked/Gap] |
| Print Mode & CI/CD | [Checked/Gap] |

### Identified Gaps

[For each unchecked item, provide a 1-line description of what to learn and a link to the tutorial]

### Your Personalized Learning Path

[Output the level-specific learning path — see Step 4]

（注：上表 "MCP Servers" 行按 output-templates.md 原文为 [Checked/Gap]，此处为排版统一。）

这个模板的设计要点：

• 8 行技能画像表与 8 道题目一一对应。Quick 模式的两组问题（Basics 组 4 题 + Advanced 组 4 题）在 SKILL.md Step 2A 中定义为：启动对话、创建/编辑 CLAUDE.md、使用过 3 个以上内置斜杠命令、创建过自定义命令/技能，以及配置过 MCP、设置过 hooks、创建/使用过 subagents、用过 claude -p 打印模式。表格按这 8 个领域固定顺序列出，勾选状态填 Checked 或 Gap，保证任何两次运行的结果结构完全一致。
• ### Identified Gaps 强制"缺口 → 教程链接"绑定：对每个未勾选项，要求给出一行学习说明和指向教程目录的链接。这为下一步（学习路径）提供了数据来源。
• 结尾强制引用 Step 4 路径模板，把"结果呈现"与"路径生成"两个输出环节串联成一篇完整报告。

三、模板二：Deep Assessment 结果（Step 3B）

Deep 模式共 5 轮提问，每轮 4 个选项覆盖 2 个功能主题，每个主题 0–2 分，总分 20 分（题目与计分映射详见 deep-assessment-rounds.md）。结果模板是三种模板中字段最丰富的一份：

## Claude Code Skill Assessment Results

### Overall Level: [Level 1 / Level 2 / Level 3]

**Total Score: N/20 points**

[One-line motivational summary]

### Your Skill Profile

| Feature Area | Score | Mastery | Status |
|-------------|-------|---------|--------|
| Slash Commands | N/2 | [None/Basic/Proficient] | [Learn/Review/Mastered] |
| Memory | N/2 | [None/Basic/Proficient] | [Learn/Review/Mastered] |
| Skills | N/2 | [None/Basic/Proficient] | [Learn/Review/Mastered] |
| Hooks | N/2 | [None/Basic/Proficient] | [Learn/Review/Mastered] |
| MCP | N/2 | [None/Basic/Proficient] | [Learn/Review/Mastered] |
| Subagents | N/2 | [None/Basic/Proficient] | [Learn/Review/Mastered] |
| Checkpoints | N/1 | [None/Proficient] | [Learn/Mastered] |
| Advanced Features | N/2 | [None/Basic/Proficient] | [Learn/Review/Mastered] |
| Plugins | N/2 | [None/Basic/Proficient] | [Learn/Review/Mastered] |
| CLI | N/2 | [None/Basic/Proficient] | [Learn/Review/Mastered] |

**Mastery key:** 0 = None, 1 = Basic, 2 = Proficient

### Strength Areas
[List topics with score 2/2 — these are mastered]

### Priority Gaps (Learn Next)
[List topics with score 0 — these need attention first, ordered by dependency]

### Review Areas
[List topics with score 1/2 — basics known but advanced features not yet used]

### Your Personalized Learning Path

[Output gap-specific learning path — see Step 4]

结合 SKILL.md 的 Step 2B，模板中各字段的含义与取值来源非常明确：

• 10 行画像表对应 10 个功能领域，与仓库的 10 个教程模块（01-slash-commands/ 到 10-cli/）一一对应，这也是 技能 README 中"Evaluates 10 feature areas"承诺的落点。
• N/2 分数格式直接由计分映射决定：每轮 4 个选项中，前 2 个选项归第一个主题、后 2 个归第二个主题，勾选数即得分。唯一的例外是 Round 4：选项 1 单独映射 Checkpoints（0–1 分，所以表中该行是 N/1），选项 2–4 映射 Advanced Features（0–3 分但封顶 2）。模板表格把这种不对称精确编码进了两行的分母差异中。
• Mastery 三档与 Status 三档是严格映射：0 分 = None → Learn，1 分 = Basic → Review，2 分 = Proficient → Mastered，Mastery key 一行把映射显式写进输出，避免读者猜测。
• 三个分层小节对应三个分数区间：2/2 进 Strength Areas，0 分进 Priority Gaps（且要求"ordered by dependency"，即按依赖顺序排列），1/2 进 Review Areas。依赖顺序在 SKILL.md Step 4 中定义：Slash Commands → Skills、Memory → Subagents、CLI Basics → CLI Mastery、Hooks 依赖 Slash Commands、MCP → Plugins（Plugins 还依赖 Skills 与 Hooks）、Advanced Features 依赖此前所有主题。
• 总体等级阈值与分数联动：0–6 分 Level 1，7–13 分 Level 2，14–20 分 Level 3。

四、模板三：Learning Path（Step 4）

第三套模板负责把学习路径渲染成分阶段、可验收的计划。原文模板如下：

### Your Personalized Learning Path

**Estimated time**: ~N hours (adjusted for your current skills)

#### Phase 1: [Phase Name] (~N hours)
[Only if they have gaps in these areas]

**[Topic Name]** — [Learn from scratch / Deep dive into advanced features]
- Tutorial: [link to tutorial directory]
- Focus on: [specific sections/concepts they need]
- Key exercise: [one concrete exercise to do]
- You'll know it's done when: [specific success criterion]

**[Topic Name]** — ...

---

#### Phase 2: [Phase Name] (~N hours)
...

---

### Recommended Practice Projects

Based on your gaps, try these real-world exercises to solidify your learning:

1. **[Project name]**: [1-line description combining 2-3 gap topics]
2. **[Project name]**: [1-line description]
3. **[Project name]**: [1-line description]

每个主题条目由四个必填要素构成：Tutorial（指向仓库内教程目录）、Focus on（该用户具体缺的章节/概念）、Key exercise（一个可执行的具体练习）、Done when（可验证的完成判据）。这个"四要素"格式并非凭空而来，SKILL.md Step 4 与独立参考文件 topic-recommendations.md 为 10 个主题分别写好了现成内容（0 分版与 1 分复核版各一份），例如 Hooks（score 0）的推荐条目为：教程指向 06-hooks/、重点在 matcher + hooks 配置结构、PreToolUse/PostToolUse 事件、退出码（0=成功、2=拦截）与 JSON 输入输出格式，关键练习是"写一个校验 Bash 命令的 PreToolUse hook"，完成判据是"hook 能在执行前拦截危险命令"。

路径生成还受五条规则约束（见 SKILL.md 的 "Rules for Path Generation"）：跳过 2/2 的已掌握主题；按依赖顺序排序；1/2 分主题推荐"深入进阶"而非从头学；总时长只累加需要学习/复核的主题；按 2–3 个主题一组划分阶段。模板顶部的 Estimated time: ~N hours (adjusted for your current skills) 正是第 4 条规则的体现——时长随个人基线动态调整，而非固定值。

五、设计解析：为什么"逐字重复"模板进 SKILL.md

从源码结构看，这是该文件最值得借鉴的设计决策。模板文件自己声明了重复策略：Step 3A/3B 结果模板和 Step 4 路径格式模板逐字复制在 SKILL.md 的 Step 3 与 Step 4 中；而 Step 2B 的 5 轮题目则同时完整存在于 SKILL.md 和 deep-assessment-rounds.md，后者开头也注明"The scoring map for each round is duplicated in SKILL.md Step 2B so results can be computed without re-reading this file"。

这体现了 Claude Code 技能的**渐进式披露（progressive disclosure）**思路：SKILL.md 是技能被调用时首先加载的指令主体，其中必须包含"产出结果所必需的一切"——题目、计分规则、输出模板；而 topic-recommendations.md 这类只有"生成路径时才需要逐条查阅"的素材，则留在 references/ 目录按需读取。这样既保证高频路径（出题 → 计分 → 出报告）零额外文件读取、格式稳定，又避免把全部素材一次性塞进上下文。

对照仓库中另一个技能 lesson-quiz 的输出模板 results-template.md，可以印证这类模板的通用写法：开头用一句话声明"何时使用本模板、哪些部分保持原样"（"Fill the bracketed placeholders; keep the headings and table columns as shown"），再用一个完整代码块给出含占位符的成品骨架，并显式处理条件分支（pre/during/after 三种时点各对应一段不同文案）。self-assessment 的三套模板遵循同一范式，只是把条件分支从"时点"换成了"评估模式/分数区间"。

六、错误处理与模板的兜底

模板只覆盖了"正常完成评估"的输出，SKILL.md Error Handling 则为异常输入定义了兜底行为，这些行为最终都会回落到同一套模板上：

• 某一轮未勾选任何选项 → 该轮主题计 0 分，继续下一轮；
• 全部轮次都未勾选 → 直接判 Level 1: Beginner，输出完整的 Level 1 学习路径；
• 用户要求重测 → 从 Step 1 重新跑一遍新评估；
• 用户不认同判定等级 → 认可其自我认知，询问其认同的等级，并对可能遗漏的主题做前置检查后给出路径；
• 用户在评估中途询问某个具体主题 → 记下来，结果呈现后无论得分如何都在学习路径中突出该主题。

此外，SKILL.md 末尾的 Validation 小节给出了触发/不触发的测试套件（如 "assess my level" 应触发，"review my code"、"what is a checkpoint" 不应触发），使技能的自动调用边界同样可测试。

七、小结

output-templates.md 虽只有百余行，却展示了用纯 Markdown 约束 LLM 输出的完整方法论：

1. 空白骨架 + 方括号占位符：标题、表头、列名固定，只有数值与文案留空，从格式层面消除两次运行结果的结构差异；
2. 模板字段与上游计分规则严格对齐：N/8、N/20、N/1、Mastery 三档、Status 三档，全部可回溯到 SKILL.md 中明确的题目与计分映射；
3. 输出与内容解耦：结果模板负责"怎么呈现"，topic-recommendations.md 负责"写什么内容"，两者在 Step 4 汇合；
4. 关键模板内联进 SKILL.md，以渐进式披露降低技能运行时的文件读取依赖，同时保留 references/ 文件作为可独立查阅的规范副本。

这套"技能指令 + 参考文件 + 输出模板"的组织方式，对任何想为 Claude Code 编写确定性输出的自定义技能（.claude/skills/<name>/SKILL.md + references/）都有直接的参考价值：读者可以参照 self-assessment 技能 README 中的流程图（选择模式 → 答题 → 按主题计分 → 生成路径 → 开始学习），在自己项目中复刻一个同样结构的评估类技能。