Cursor 的 Skill 不是魔法插件，而是一份「交给模型的操作说明」：放在仓库里，和代码一起评审、一起演进。本仓库里的 .cursor/skills/hugo-blog-article/SKILL.md 就是一次完整实践——把「从用户意图到可构建的 Hugo 文章」拆成可重复的步骤、表格约定和交付清单。下面按编写顺序说明我怎么落盘，哪些坑可以避免；文末附录贴出该 Skill 的完整原文，不依赖 GitHub 能否打开。
1. 放哪：项目级 Skill 与目录约定
个人常用、与单一仓库强绑定的流程，适合放在项目根的 .cursor/skills/<skill-name>/SKILL.md。这样协作者 clone 下来就自带同一套规范，PR 里也能 diff 到「模型行为」的变更。
Cursor 内置/系统占用的技能目录是 ~/.cursor/skills-cursor/，文档里会明确不要往那里塞自己的 Skill——那是产品预留路径，升级时可能被覆盖或管理策略不同。自定义内容一律走 ~/.cursor/skills/（全局）或 .cursor/skills/（本项目）。
2. 元数据：name 与 description 决定「会不会被想起来」
SKILL.md 顶部需要 YAML，至少两项：
name：小写字母、数字、连字符，在本机作为标识符。description：第三人称、写清 做什么 + 什么场景该用，并塞进用户口头会说的触发词（例如「新文章」「content/posts」「hugo」）。
以 hugo-blog-article 为例，描述里直接点名 myhugo、Dream v3、<!--more-->、hugo 校验——模型做路由时靠的是这段文字，而不是正文第一段的标题。具体字句见附录中的文件开头。
写作技巧可以压缩成一句：描述是给「调度层」看的摘要，正文才是给「执行层」看的细则。
3. 正文结构：先「何时启用」，再「不可跳步的流程」
执行型 Skill 最怕写成散文。hugo-blog-article 采用的分层是：
- 何时启用：几条 bullet，对应用户会怎么开口。
- 总流程：编号步骤（对齐意图 → 大纲 → 导语与
<!--more-->→ 正文 → 配图 →hugo），每一步写清产出物与常见遗漏。 - 约定表：front matter 字段表，减少模型自由发挥。
- 可复制模板：一整块 fenced markdown，降低格式错误率。
- 文风与禁区：与站点/用户规则对齐，避免套话和引流式结尾。
- 交付清单：checkbox，结束前自检。
这套顺序的本质是：先帮模型判断「该不该用我」，再约束「怎么用我」，最后给 验收标准。写其他主题（例如「按团队规范写 PR 描述」「跑一遍发布前检查」）时，可以原样复用骨架，只替换中间步骤与表格。
4. 范围控制：Skill 写的是「边界」，不是第二份 README
hugo-blog-article 刻意把 Hugo Extended 版本、主题名 写在描述和流程里，但不展开 Dream 主题的每一个参数——那些属于 README.md 与 config.toml。Skill 只保留「写文时一定会踩到」的约束：<!--more--> 位置、description 与标题分工、默认不在正文交代封面来源、构建命令等。
反过来，若把通用文档整本抄进 Skill，上下文变长、维护双份，模型还容易混淆优先级。Skill 应该引用仓库里已有事实（路径、已有文章样例），而不是复制粘贴整站文档。
5. 迭代方式：从一次对话到可复用资产
这篇 Skill 的来源，是把「某次写博文」里有效的协作逻辑抽出来：硬大纲、front matter 顺序、外链与构建验证。之后每次改站点约定（例如摘要策略变了），只改 Skill 一处，后续会话就能对齐。
若你发现模型经常在同一类任务上漏步骤，优先往 「总流程」加一步 或往 「交付清单」加一条，比加长系统提示词更干净——因为 Skill 是按需挂载的，不会污染无关对话。
6. 和官方「写 Skill」指引的关系
Cursor 自带的 create-skill 类指引（目录结构、description 规范、name 字符集等）适合在新建 Skill 时对照一遍。项目里已经有一份成形的 SKILL.md 时，更务实的做法是：打开 create-skill 核对元数据，再对照本仓库范例改内容，而不是从零空想。
附录：hugo-blog-article/SKILL.md 全文
以下与本地 .cursor/skills/hugo-blog-article/SKILL.md 保持一致，便于直接复制或 diff。（文中含嵌套的 Markdown 代码围栏，故外层用四反引号包裹。）
---
name: hugo-blog-article
description: >-
为 myhugo 仓库（Hugo Extended + Dream v3）撰写、润色与落地 Markdown 博文：front matter、列表摘要与 <!--more-->、可选封面、分节论证、权威链接与本地 hugo 校验。在用户要求新文章、改写 content/posts、把要点/大纲整理成可发布长文时使用。
---
# Hugo 博客文章撰写（myhugo）
本技能把「从意图到可构建的 `content/posts/*.md`」拆成可重复执行的步骤，并与本仓库已有文章、Dream 主题约定对齐。
## 何时启用
- 用户要为 **`content/posts/`** 新增或重写一篇文章
- 用户给出零碎观点、大纲或口述要点，需要**理顺逻辑、补全论据、落成博文**
- 需要统一 **YAML front matter**、**摘要与 SEO 字段**、**配图策略**
- 写完需要确认 **Hugo 能成功构建**
若用户明确要求「按某个人/品牌的固定声线」写作，可先配合其 `brand-voice` 或样例文；本技能默认：**简体中文、技术随笔向、句子紧凑、少用空泛形容词**。
## 写作逻辑（总流程）
按顺序执行，避免跳步导致结构散或 front matter 缺项。
1. **对齐意图**
- 文章要帮读者解决什么问题、核心论点一句说清。
- 是否需要**外链/仓库引用**（官方文档、GitHub 等），避免编造链接。
- 是否需要**封面**：需要则走下方「配图」；不需要可省略 `cover` / `images`（与仓库中部分文章一致即可）。
2. **硬大纲**
- 一节只干一件事；章节标题尽量**陈述结论或范畴**，少用「背景 / 引言」等空标题。
- 用户给的要点逐条映射到章节，**顺序符合认知**：先立论 → 展开条件/反例 → 工程化或行动建议 → 简短小结。
3. **导语 + 列表摘要**
- `---` 后的第一段：用具体对象（工具、场景、对比）**把论点摆出来**，再解释。
- 第一段之后立刻插入 **`<!--more-->`**：其上是列表/首页摘要，其下是正文主体（与仓库惯例一致）。
4. **正文**
- 技术文：**类比与定义**要准确；**清单**用于步骤、边界、验收。
- **小结**可收束全文，避免「互动引流式」结尾；不必每篇都提问读者。
- 代码、路径、命令用 fenced code；引用站内或 GitHub 用完整 URL。
5. **配图（可选）**
- `cover` 与 `images` 使用同一张图时，两处 URL 保持一致。
- 外链图推荐带裁剪参数，例如：
`https://images.unsplash.com/photo-xxx?auto=format&fit=crop&w=1200&q=80`
- **默认不在正文里单独说明封面来源**（除非用户明确要求署名或许可说明）。
6. **验证**
- 在仓库根目录执行 `hugo`；若环境对缓存目录有限制，可去掉 `--gc` 再试。
- 修复构建报错后再交付。
## Front matter 约定
字段顺序建议与现有文章保持一致，便于 diff 与阅读。
| 字段 | 说明 |
|------|------|
| `title` | 中文标题，简洁有信息量 |
| `date` | `YYYY-MM-DDTHH:MM:SS+08:00` |
| `lastmod` | 大改时更新，可与 `date` 相同或晚于 `date` |
| `author` | 本站点使用 `lew` |
| `categories` | 通常一项，如 `AI`；与站点已有分类对齐 |
| `tags` | 3～5 个为宜；与同类文章标签风格一致 |
| `description` | 一两句摘要，供列表与 meta 使用，避免标题重复 |
| `cover` | 可选；绝对 URL 或 `/img/...` |
| `images` | 可选；OG 等，常与 `cover` 同图 |
**新建草稿**时可加 `draft: true`，正式发布前去掉。
**文件名**：小写、连字符，与 slug 相关，例如 `agent-skills-capability-sop.md`；避免中文文件名。
## 正文结构模板（可复制再填）
```markdown
---
title: "……"
date: YYYY-MM-DDTHH:MM:SS+08:00
lastmod: YYYY-MM-DDTHH:MM:SS+08:00
author: lew
categories:
- …
tags:
- …
description: "……"
cover: "https://……"
images:
- "https://……"
---
具体开篇：场景/定义/对比，直接指向全文论点。
<!--more-->
## 1. …
## 2. …
---
**小结**：……
```
## 文风与禁区
- **先具体后抽象**：Artifact、对比、清单在前，总结在后。
- **理据**：技术判断要有机制层面的理由；引用外部事实需有可点击来源。
- **禁止**空洞套话：如「在当今快速变化的时代」「游戏规则改变者」、纯为互动的收尾提问。
- **语言**：简体中文；专有名词可保留英文（Agent、SOP、PR 等）。
- **用户规则对齐**：成稿应像可读的技术博文——**克制、清楚、不堆术语架子**。
## 与仓库的对齐方式
- 新建文前扫一眼 **`content/posts/`** 下同类文章：`categories` / `tags` / 标题风格。
- 站点与构建说明见 **`README.md`**；`baseURL`、语言等见 **`config.toml`**。
- 不确定主题是否识别某 front matter 字段时，以 **已有能通过构建的文章** 为准。
## 交付前检查清单
- [ ] 论点清晰，章节顺序无跳步
- [ ] `<!--more-->` 位置正确（导语后）
- [ ] `description` 与正文一致，无夸大
- [ ] 外链真实可用；GitHub 用 `https://github.com/...` 完整路径
- [ ] 默认正文**不**单独交代封面图片来源（除非用户要求）
- [ ] `hugo` 构建通过
- [ ] 仅改动本任务相关文件，不顺带大改无关页面
小结：项目 Skill = .cursor/skills/<name>/SKILL.md + 给调度层看的 description + 给执行层看的 编号流程 / 表 / 模板 / 清单。hugo-blog-article 演示了如何把「写 Hugo 博文」这类高频、多步骤任务，收敛成可评审、可 diff 的文本资产。你手头若已有重复三次以上的协作套路，不妨用同一骨架抽第一份 Skill——通常比堆长系统提示词更稳。