如何把一项重复性任务变成你 AI 编程智能体的可复用技能

如果你总是把同一份清单粘贴给你的 AI 编程智能体——“写一条规范化提交（conventional commit），然后运行测试，再更新变更日志”——那你是在做本该智能体替你记住的工作。大多数现代智能体都允许你把一个反复出现的操作流程打包成一个小巧、可复用的文件。在 Claude Code 中，这些被称为技能（skills）；同一个文件还驱动着像 /deploy 这样的斜杠命令。本指南将带你从零构建一个，然后讲解那些可以迁移到其他工具上的原则。

什么是技能

一个技能就是一个文件夹，里面只有一个 SKILL.md 文件。这个文件有两部分：告诉智能体何时使用该技能的 YAML frontmatter，以及技能运行时它所遵循指令的 markdown 正文。相比把所有内容都塞进一个 CLAUDE.md（或 AGENTS.md）文件，它的关键优势在于渐进式披露（progressive disclosure）：正文只在技能真正被调用时才加载，所以冗长的参考资料在你需要它之前几乎不占用任何成本。

你有两种方式调用技能：直接调用，输入 /skill-name；或者自动调用——智能体读取你的请求，将其与技能的 description 匹配，如果相关就加载它。

技能存放在哪里

你把文件夹放在哪里，决定了谁能使用它。在 Claude Code 中，根据官方文档：

• ~/.claude/skills/<name>/SKILL.md —— 个人，在你所有的项目中都可用。
• .claude/skills/<name>/SKILL.md —— 项目，提交到仓库，这样团队中的每个人都能拥有同一条命令。

文件夹名称就是命令。一个名为 summarize-changes 的文件夹会给你 /summarize-changes。

一个具体的例子

我们来构建一个技能，它会在你提交之前总结你未提交的更改，并标记出任何有风险的内容。创建目录：

mkdir -p ~/.claude/skills/summarize-changes

然后把下面这段保存为 ~/.claude/skills/summarize-changes/SKILL.md：

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any
risks you notice such as missing error handling, hardcoded values, or tests
that need updating. If the diff is empty, say there are no uncommitted changes.

有两点让它得以奏效。第一，description 是为智能体写的，而不是为你写的——它点明了触发条件（“what changed”“wants a commit message”“review their diff”），这样智能体就知道何时该动用它。第二，!`git diff HEAD` 这一行是动态上下文注入：Claude Code 在智能体读取该技能之前就运行那条命令，并把它的输出粘贴进提示词里。指令送达时，你真实的 diff 已经内联其中，所以答案是建立在你真实的工作区之上，而不是凭空猜测。

对任意一个文件做一点小改动，启动你的智能体，然后两种方式都试试——问“我改了什么？”来自动触发它，或者输入 /summarize-changes 来直接运行它。

传递参数

技能可以接受输入。正文中的 $ARGUMENTS 占位符会被你在命令后输入的内容替换，而带索引的变体（$0、$1）则抓取特定的词。一个以 /fix-issue 4821 调用的技能可以直接引用这个问题编号，于是一个文件就能处理所有的问题，而不是每张工单一个文件。

让技能经得起考验的五条原则

无论你是在写一个 Claude Code 技能、一条 Cursor 命令，还是——自 OpenAI 2026 年 6 月的 Record & Replay 功能起——编辑智能体替你录制的某个自动化，这些原则都适用：

1. **为模型而写 description。**把具体的触发短语放在前面。模糊的 description 意味着智能体永远不会自动加载该技能，于是你又回到了敲 / 并努力记住名称的老路上。
2. *让每个技能只做一件事。*一个既部署又*跑迁移又*往 Slack 发消息的技能既难以信任，也更难调试。小巧、单一用途的技能能更好地组合在一起。
3. **注入实时上下文，而不是描述它。**拉入一份真实的 diff、一个测试结果或一份文件清单，胜过告诉智能体“检查当前状态”——这去掉了一个智能体可能猜错的环节。
4. **对任何有副作用的东西设门槛。**对于会部署、迁移或删除的技能，要求显式调用，而不是让智能体自动触发它们。在不可逆的操作之前，你需要一个人在回路之中。
5. **把团队技能提交到仓库。**把项目技能放进 .claude/skills/ 并将其纳入版本控制，意味着每一位开发者——以及 CI 中的每一次智能体运行——都遵循同样的操作流程。你的约定不再只活在某一个人的脑子里。

何时该动用技能

经验法则是：当你第三次粘贴同一份多步骤指令的那一刻，或者你 CLAUDE.md 中的某一节从一条事实变成了一套流程时，就把它挪进一个技能里。你会得到一条可复用的命令，你的上下文文件保持精简，而指令只在真正需要时才加载——这让你和智能体都能专注于眼前的任务。