一个开源、可上手的 Skill 写作教程。
课堂主题：在城市治理热线场景里，用 Agent + Skill 把"描述-诊断-预测-规范"四层分析落到可复核的产物。
在线预览（不用 clone，直接打开看）：
- 📘 Skill 原文 — https://files.lingti.com/multi-source-diagnosis-Jie-Feng.html
- 📊 实跑诊断答案（含 5 张 Chart.js 图表） — https://files.lingti.com/诊断答案-Jie-Feng.html
读完并动手一遍，你会：
- 理解什么是 Skill：为什么 Skill 比 Prompt / 一次性指令更值得投入；它和"长 System Prompt"、"自定义 Agent"的边界在哪。
- 学会写一份合格的 Skill：固定流程、强制输出模板、风险分级、Human-in-the-loop 节点、测试清单——一项不少。
- 跑一次真实数据：用提供的 5 张治理数据表，让你写的 Skill 在 Claude Code / Claude.ai / QClaw 等环境里跑出可复核的诊断报告。
- 看到一个完整的示范交付：
submissions/jie-feng/里有可直接对照的 Skill + HTML + 实跑答案（含图表）。
读完不再"觉得 Skill 是个时髦词"——你会把它当成一类可工程化的产物：有约束、有红线、有自检、可复核。
# 1. clone 本项目
git clone https://github.com/hophacker/skill-writing.git
cd skill-writing
# 2. 安装示范 Skill 到你的 Claude Code（全局）
mkdir -p ~/.claude/skills/multi-source-diagnosis
cp skills/multi-source-diagnosis/SKILL.md ~/.claude/skills/multi-source-diagnosis/
# 3. 进入数据目录，用 Claude Code 跑一次
cd data
claude "use the multi-source-diagnosis skill，请基于 2025-09 的数据做一次描述-诊断"如果想要看"跑出来应该长什么样"，不用 clone 也能看：
- Skill 原文（HTML 版）：https://files.lingti.com/multi-source-diagnosis-Jie-Feng.html
- 实跑诊断答案（含 5 张 Chart.js 图表）：https://files.lingti.com/诊断答案-Jie-Feng.html
GitHub 上直接点
.html文件只会显示源码、不会渲染——所以图表用上面这两个 lingti 静态托管链接看效果。
skill-writing/
├── README.md ← 你正在看
├── LICENSE ← MIT
├── CONTRIBUTING.md ← 提交你自己的 Skill
│
├── decks/ ← 原始教学幻灯片（NotebookLM 生成）
│ ├── 编写Skill的方法与技巧.pptx Day1：如何写 Skill
│ └── 数据治理与大数据分析.pptx Day2：四层分析与作业要求
│
├── data/ ← 案例数据集（5 张表 + 数据字典）
│ ├── README.md
│ ├── 01_热线工单表.csv
│ ├── 02_网格巡查与现场核验表.csv
│ ├── 03_资源排班与部门容量表.csv
│ ├── 04_天气节假日与活动表.csv
│ └── 05_处置规则与政策口径.md
│
├── docs/ ← 文字版教学材料（PPT 的可读化提炼）
│ ├── methodology.md ← 如何写 Skill 的方法论（Day1）
│ ├── case-study.md ← 城市治理作业说明（Day2）
│ ├── skill-template.md ← 空白 Skill 模板，复制即用
│ └── rubric.md ← 自评打分细则
│
├── skills/ ← 可直接安装的参考 Skill
│ └── multi-source-diagnosis/
│ └── SKILL.md
│
└── submissions/ ← 学员作品（欢迎 PR 你的 Skill）
├── README.md
└── jie-feng/ ← 第一份示范提交
├── SKILL.md ← 多源描述-诊断 Skill 原文
├── SKILL.html ← 同上，HTML 渲染版
├── run-report.md ← 在 2025-09 数据上的实跑答案
└── run-report.html ← 实跑答案 HTML 版（含 5 张图表）
按下面这个顺序，总共 2–3 小时：
| 阶段 | 投入时间 | 看什么 | 你应该学到 |
|---|---|---|---|
| ① 看原始幻灯片 | 30 min | decks/编写Skill的方法与技巧.pptx（Day1） |
概念框架：Skill 是什么、放哪、怎么跑 |
| ② 读文字版方法论 | 30 min | docs/methodology.md |
提炼成可查阅的清单：6 个红线、5 步流程、3 个强制输出 |
| ③ 看一个完整范例 | 20 min | submissions/jie-feng/SKILL.md + 实跑答案在线版 |
看真东西怎么写出来、跑出来（图表只在在线版可见） |
| ④ 抄模板写一份 | 60 min | docs/skill-template.md + data/ |
自己写一份 Skill，让它在 5 张数据表上跑出结果 |
| ⑤ 自评 + 提 PR | 30 min | docs/rubric.md + CONTRIBUTING.md |
6 项验收清单全 ✓，提交进 submissions/<你的名字>/ |
Skill = 一个写在
SKILL.md里的、被 Agent 在合适场景自动调起的"可复用任务文件"。
它不是：
- 一次性写完就丢的 Prompt
- 长得像小说的 System Prompt
- 一个对话历史
它是：
- 有 frontmatter（
name+description），让 Agent 知道何时调用它； - 有固定流程、强制输出格式、红线约束；
- 长得像一份任务 SOP 文档——一个新人按它跑也能跑出同样质量的结果；
- 可以被反复调用、版本化、加测试。
如果你做过：DAG / Makefile / Linter 规则 / API 接口定义——Skill 给你的感觉应该类似：把方法外化成可被机器执行的契约。
skills/multi-source-diagnosis/SKILL.md 是一份完整示范，专门用于 多源描述-诊断分析：
- 输入：5 张数据表（工单 / 网格 / 排班 / 天气活动 / 处置规则）。
- 强制走 5 步：字段理解 → 描述画像 → 异常提取 → 多假设诊断 → 复核清单。每步走完必须显式打
[done]。 - 强制三件套输出：「事实卡片」+「竞争性假设」+「复核清单」，散文形式直接判不合格。
- 6 条红线：
- 不读
07_*.csv（教师参考答案，本仓库未提供，但 Skill 主动隔离） - 不把
05_处置规则当终审判决 - 不输出 P0/P1/P2 等级
- 单一假设直接判罪 = 不合格
- 不能打乱 5 步顺序
- 不替部门拍板
- 不读
- 自检 6 项：数据源 / 时序 / 结构 / 多假设 / 红线 / 复核点——任一未过回到对应步骤重写。
实跑产物（在线版含图表 · 仓库内源码）是 Skill 在 2025-09 数据上的实跑产物，包括：
- 4 张事实卡片（城管局超时、街道办超时+低满意度、东文昌-01 重复投诉聚集、capacity_pressure_level 全"低"口径异常）；
- 8 个竞争假设，每个带证据 + 反证 + 置信度 + 必须人工拍板的具体问题；
- 12 项复核清单，明确归口部门 + 1 周回话期；
- 5 张 Chart.js 图表（部门超时率对比 / 类目超时 vs 重复率 / 同类目跨部门处置时长 / 网格重复率 Top10 / 容量压力分布饼图）。
# 全局安装
mkdir -p ~/.claude/skills/multi-source-diagnosis
cp skills/multi-source-diagnosis/SKILL.md ~/.claude/skills/multi-source-diagnosis/
# 或只在本项目安装
mkdir -p .claude/skills/multi-source-diagnosis
cp skills/multi-source-diagnosis/SKILL.md .claude/skills/multi-source-diagnosis/Claude Code 启动后看到匹配的描述即自动触发；显式调用：
use multi-source-diagnosis skill，请基于 2025-09 数据描述并诊断东城区文昌街道的异常
- 创建一个 Project
- 把
skills/multi-source-diagnosis/SKILL.md上传到 Project Knowledge - 把
data/5 张表也上传 - 对话里说："按 multi-source-diagnosis Skill 处理 ..."
把 SKILL.md 与 data/ 放进工作区目录，prompt 里点名 Skill 名即可。
把整个 SKILL.md 内容粘贴作为 System Prompt，然后用户消息附数据。这是最原始的 fallback。
按这个顺序操作：
- 复制模板：
cp docs/skill-template.md submissions/<你的英文名>/SKILL.md - 想清楚你的 Skill 解决什么问题——一句话能说清的那种。建议从作业三选一：
- 多源描述-诊断 Skill（已有参考实现，建议你写一个不同视角的版本）
- 预测-规范 Skill（基于现状预测并比选处置方案，更难）
- 跨城市/跨部门对照 Skill（脱离本案例，去你的工作场景）
- 填模板：每个
<TODO: ...>都要填掉；不会填的，回头看docs/methodology.md。 - 跑一遍：装到 Claude Code → 在
data/上跑一次 → 把过程输出存为run-report.md。 - 自评：对照
docs/rubric.md6 项打分；任一未过回去改，不要先美化文字。 - 提 PR：见
CONTRIBUTING.md。
数据是教学模拟数据——不对应任何真实城市、街道、部门或人员。详见 data/README.md。
警告：
data/05_处置规则与政策口径.md里所有的"职责边界 / P0/P1/P2 口径"都是课堂模拟规则，不是任何地区的正式政策文件，请勿在真实工作中作为依据使用。
- ❌ 不教数据分析方法本身：Skill 是分析方法的"封装方式"，不是分析方法本身。要先有方法。
- ❌ 不提供生产环境数据：数据是模拟的，仅用于教学。
- ❌ 不替代真实决策：示范 Skill 明确拒绝输出 P0/P1/P2 等级，复核清单必然回到人。
- ❌ 不锁定某一家厂商：Skill 格式遵循 Claude Skills 约定，但内容上是 vendor-neutral 的 Markdown SOP，任何 Agent 系统都能消费。
- 原始幻灯片由 NotebookLM 协助生成。
- 教学案例数据集为课堂模拟，不对应真实地区。
- 代码与文档遵循 MIT 协议。
欢迎 fork / PR / 提 issue。如果你拿这个项目在企业或学校开课，欢迎给我们留个 issue 让我们知道——可能加进"Used By"列表。
- 第一份示范 Skill：
multi-source-diagnosis - 第二份示范 Skill：
forecast-and-prescribe（实操二：预测-规范） - 提交模板的 GitHub Actions 自动 lint（检查 frontmatter / 字数 / 必填章节）
- 英文版 README & docs
- 与 Claude Code Plugin Marketplace 的对接（把
skills/发为一个 plugin）
issue / PR 欢迎挑路线图里的任意一项。