NJCodeX

主题

📅 2026-07-23⏱️ 约 14 分钟Claude CodeSkills实战

自己写一个 Claude Code Skill：从触发词到可复用工作流 ​

这篇不是 Skills 清单的续集。清单回答「有哪些」；这篇回答「你自己的那一个怎么落盘、怎么写到真的会被用上」。

装了一堆 skill 之后，常见下一件事是：某段对话你重复了第三遍——「再发一篇笔记时记得写 frontmatter、改 sidebar、别动 dist」——然后你意识到：这不该再靠临场记忆，该收成 skill。

下面用本仓库真实约定，从 0 写一个 add-blog-note：用户说「发一篇笔记 / 加一篇文章」时，让 Claude 按 NJCodeX 的规矩做完，而不是各写各的。

一、Skill 到底是什么 ​

Skill 不是插件，也不是会自己跑的脚本。它是一份 写好的操作说明书，放在约定目录里：

text
~/.claude/skills/<name>/SKILL.md     # 用户级：所有项目可见
.claude/skills/<name>/SKILL.md       # 项目级：仅本仓库（有的环境也认 .grok/skills）

结构通常是：

text
add-blog-note/
  SKILL.md          # 必填：触发说明 + 步骤
  references/       # 可选：长模板、对照表
  scripts/          # 可选：确定性脚本（校验 frontmatter 等）

Claude 在匹配到你的意图时，会把 SKILL.md 读进上下文，再按里面的步骤干活。
所以 skill 的质量 ≈ 说明书写得清不清楚，不是又套一层「魔法」。

和普通提示词的差别：

临场提示Skill
生命周期这一轮对话可复用、可分享、可版本化
触发你每次手写description 自动匹配，或 /名字
适合一次性问题重复流程、项目约定、易忘检查项

不该做成 skill 的：只问一次的概念题、没有稳定步骤的开放讨论。
该做成 skill 的：你已经用嘴说过两遍以上、且步骤可枚举的流程。

二、最重要的字段：description ​

很多人把正文写得很长，却随便写一行 description。结果是：skill 永远不会被自动调起，因为匹配看的是 description，不是文件名。

yaml
---
name: add-blog-note
description: >
  在 NJCodeX（本 VitePress 博客）新增一篇笔记：写 frontmatter、
  注册 sidebar、避免编辑 dist。在用户说「发一篇笔记」「加篇文章」
  「写新 note」「新增 notes」时使用。
---

写 description 的实用标准：

  1. 动词 + 对象：做什么，不是「帮助用户更好地写作」这种空话
  2. 触发原话：把用户真的会说的中文/英文短语写进去
  3. 边界：适用仓库或场景写清楚，避免和别的 skill 抢触发
  4. 短：过长会占上下文；一两句够用，不要贴半篇 README

反例：

yaml
# ❌ 太空：永远匹配不上具体意图
description: 帮助管理博客内容

# ❌ 太像内部实现：用户不会这么说
description: 调用 createContentLoader 更新 posts 列表

正例里的「发一篇笔记 / 加篇文章」才是触发面。

三、正文怎么组织（可直接套） ​

正文是给 已经触发的 agent 看的，不是给人类博客读者看的。结构建议：

  1. 目标（一句话）
  2. 何时用 / 何时不用
  3. 硬性约定（路径、字段、禁区）
  4. 分步流程（可勾选）
  5. 验收（怎样算做完）
  6. 反例（别做什么）

原则：

  • 步骤写成 命令与文件路径，少写「请酌情考虑」
  • 项目特有的坑单独成条（例如本站 禁止手改 dist/）
  • 能指向现有文件就指向：CLAUDE.md、config.mts，不要把整份架构抄进 skill

四、完整示例：add-blog-note ​

下面是一份可以直接落到 .claude/skills/add-blog-note/SKILL.md 的内容（按本站现状写死约定）。

markdown
---
name: add-blog-note
description: >
  在 NJCodeX VitePress 博客新增一篇 notes 笔记：创建 Markdown、
  补全 frontmatter、注册 docs/.vitepress/config.mts 侧边栏。
  用户说「发一篇笔记」「加篇文章」「写新 note」「新增笔记」时使用。
  不要用于改主题样式或只改已有文章错别字。
---

# 新增博客笔记

## 目标

在 `docs/notes/` 增加一篇可被列表、RSS、搜索收录的笔记，并出现在侧边栏对应分组。

## 不要做

- 不要编辑 `docs/.vitepress/dist/`（构建产物，也是线上 Nginx 根目录，下次 build 会清空）
- 不要在首页 / 笔记索引手写文章列表（列表来自 `docs/posts.data.mts`）
- 不要省略 frontmatter 的 `title`（缺了会在列表里显示空白标题）

## Frontmatter 模板

```yaml
---
title: 标题
description: 一句话摘要，会进 og:description 与列表
date: YYYY-MM-DD
readingTime: 约 N 分钟
tags: [标签1, 标签2]
---
```

可选：`draft: true` 会从列表和 RSS 排除。

## 步骤

1. 与用户确认：标题、slug（英文短横线）、标签、侧边栏分组（Claude Code / 提示词工程 / 实战教程）。
2. 创建 `docs/notes/<slug>.md`，写好 frontmatter 与正文。正文中文，专有名词可保留英文。
3. 打开 `docs/.vitepress/config.mts`，在 `themeConfig.sidebar['/notes/']` 对应 `items` 里加一条：
   `{ text: '侧边栏短标题', link: '/notes/<slug>' }`
4. 若该文应挂进学习路径，同步改 `docs/notes/claude-code-path.md` 的表格（仅 Claude Code 系列需要）。
5. 提醒用户：上线需要 `npm run docs:build`（会短暂清空线上 dist，等同部署）。

## 验收

- [ ] `docs/notes/<slug>.md` 存在且 frontmatter 五字段齐全
- [ ] sidebar 能点到该文
- [ ] 未改动 `dist/`
- [ ] 未手改首页文章列表

## 文风

对齐现有笔记：先给具体结论或代码，再解释；避免空泛形容词；踩坑写真实路径与现象。

这段本身就可以当模板：把「本站」换成你的仓库约定，就成了你的 skill。

五、项目级还是用户级 ​

放哪适合
项目 .claude/skills/依赖本仓库路径、构建命令、sidebar 结构（如 add-blog-note）
用户 ~/.claude/skills/跨项目习惯：提交信息格式、PR 描述、通用 code review 清单

经验法则：离开这个 git 根目录就失效的步骤 → 项目级；到哪都说同样三句话 → 用户级。

本站没有 git 也没关系：skill 是给 agent 读的文件系统约定，不依赖远程仓库。

六、五个最容易写废的坑 ​

1. description 像产品文案 ​

「提升效率的智能写作助手」匹配不到任何真实话语。
改成用户原话：「发笔记」「加 frontmatter」「注册 sidebar」。

2. 正文太长，每轮都全量灌进上下文 ​

Skill 触发后会占 token。把大段参考资料放到 references/frontmatter.md，正文只写「需要时再读 references/xxx」。
本机 skill 很多时，更要克制——否则和 context-budget 类工具盯着的问题一样：能力目录膨胀，有效上下文变窄。

3. 只写「做什么」，不写「别做什么」 ​

Agent 默认会「帮忙」：手改 dist、在 index.md 里 hardcode 一篇、用错日期格式。
禁区列表往往比步骤列表更能防止事故。

4. 步骤不可验证 ​

「确保质量良好」无法验收。改成 checklist：文件在不在、字段齐不齐、sidebar 有没有 link。

5. 和 CLAUDE.md 重复又打架 ​

CLAUDE.md 适合项目全貌与命令；skill 适合 一条具体工作流。
同一条规则两处文案不一致时，agent 会随机站队。改约定时两处一起改，或 skill 里写「以 CLAUDE.md 的 Commands / Content conventions 为准」。

七、怎么知道 skill 生效了 ​

  1. 显式调用：对话里说 用 add-blog-note 或 /add-blog-note（视客户端支持）。
  2. 隐式触发：只说「帮我发一篇关于 Nginx 的笔记」，看它是否先读了你的 SKILL.md（行为上会按 frontmatter + sidebar 清单走，而不是自由发挥）。
  3. 失败时改 description：若从不自动出现，先改触发短语，再改正文。
  4. 装太多时做减法：不会用的 skill 挪走或删掉；清单见 Skills 全量清单。

可选增强：在 scripts/ 里放一个校验 frontmatter 的小脚本，skill 最后一步跑它——确定性检查用脚本，判断性工作留给模型。

八、最小练习（15 分钟） ​

  1. 建目录：mkdir -p .claude/skills/add-blog-note
  2. 把第四节的 SKILL.md 原样放进去（或按你的路径改一版）
  3. 新开一轮对话，只说：「按本站规范加一篇 draft 笔记，标题随意」
  4. 检查：是否出现完整 frontmatter、是否改了 config.mts、是否碰了 dist/

若第 4 步有任意一条偏了，回去改 skill 正文，而不是只怪模型——skill 就是你对代理的接口文档，接口含糊，实现就会漂。

和本站其它文的关系 ​

写 skill 的终点不是「拥有很多 md 文件」，而是：把你已经付过学费的流程，变成默认会再走一遍的路。

用代码记录成长 · RSS 订阅 · 标签

© 2026 NJCodeX · Powered by VitePress