使用 AI 智能体自动化重复性项目任务

让 AI 智能体不再需要你反复解释项目背景的最快方法，是将操作流程一次性记录为 Claude Code skill——一个包含 SKILL.md 文件的目录，提交到你的代码仓库后，智能体会直接读取它，而不是每次重新摸索如何运行、初始化数据库或部署应用。

相信不少人都经历过这样的场景：眼看着智能体花了十分钟才重新发现——如果没有初始化数据库和复制 env 文件，应用根本无法启动。而这些步骤，你上周解释过，上上周也解释过。本文将介绍一套具体的实践模式：skill 与 npm 脚本有何不同、项目级 skill 应放在哪里，以及一个可实际运行的示例——从全新 checkout 启动应用并验证其正常运行。核心观点很简单：不要再写那些迟早会被遗忘的一次性脚本，而是为整个团队和智能体共同维护一个项目级的 agent skill。

容易被遗忘的 npm 脚本和过时的配置文档，真正的代价是什么

过时的配置流程，真正昂贵的地方不在于某条命令失效，而在于无论是人还是智能体，每次都要重新推导出那套操作流程。package.json 里会积累各种晦涩的条目（predev:seed、db:reset:ci、start:tunnel），它们的执行顺序和前置条件只存在于某位工程师的脑子里。README 里的”Getting Started”章节，只要有人新增了一个环境变量却忘记更新文档，就会立刻失去同步。新成员只能靠猜；AI 智能体同样只能靠猜，而且两者猜出来的结果往往不一样。

Skill 通过将操作流程记录在智能体本就会查看的地方来解决这个问题。Claude Code 官方文档对何时应该创建 skill 给出了精准的判断标准：当你发现自己反复将相同的说明、检查清单或多步骤流程粘贴到对话框中，或者当 CLAUDE.md 中某个章节已经从”事实描述”演变为”操作流程”时，就应该创建一个 skill。

脚本和 skill 有什么区别？

对于绝对不能有任何变化的步骤，使用脚本；对于需要灵活判断的步骤，使用 skill。npm 脚本按预定顺序执行固定命令；而 skill 借助模型来读取上下文、处理不确定性，并决定下一步该做什么，再将确定性的部分交还给代码执行。两者是互补关系，而非竞争关系。

Anthropic 工程团队主张将确定性工作保留在代码中：某些操作更适合通过传统代码执行来完成，因为通过 token 生成来排序列表，既比运行排序算法慢，也不如后者可靠，而许多工作流程需要只有代码才能提供的可重复性。尤为重要的一点是，捆绑脚本在上下文中的开销极低：对于拥有文件系统和代码执行工具的智能体来说，无需将 skill 的全部内容读入上下文窗口，这意味着可以捆绑到 skill 中的内容在大小上实际上是没有上限的。

Claude Code skill 是什么，它存放在哪里？

Claude Code skill 是一个包含 SKILL.md 文件的目录，文件的 YAML frontmatter 告诉智能体何时使用它。根据 Agent Skills 概述文档，每个 skill 将操作说明、元数据以及可选资源（脚本、模板）打包在一起，Claude 会在相关场景下自动调用。这是正确的理解方式：skill 是一个目录，而不是单独的命令文件。

存放位置决定了作用范围。项目级 skill 从你的起始目录下的 .claude/skills/ 加载，同时也会向上查找父目录直到仓库根目录，因此在项目内任意位置工作的智能体都能发现该 skill，并在请求内容与其描述匹配时自动加载。个人 skill 存放在 ~/.claude/skills/。对于 Claude Code 而言，官方只推荐使用 description 字段；name 字段是可选的，默认使用目录名，也就是你在 / 后面输入的名称。

以下几个概念容易混淆，建议根据实际需求有意识地选择：

• Skill：一个目录 + SKILL.md，以及可选的捆绑脚本。通过 description 自动发现，同时也可以用 /skill-name 主动调用。在 Claude.ai 和 Claude Desktop 中同样适用，团队可以在终端之外共享使用。
• Slash command：历史上是 .claude/commands/ 目录下的单个 .md 文件。Custom commands 已合并到 skills 中：位于 .claude/commands/deploy.md 的文件和位于 .claude/skills/deploy/SKILL.md 的 skill 都会创建 /deploy 命令，两者效果相同。当名称冲突时，skill 优先生效。
• Subagent：位于 .claude/agents/ 下的 .md 文件，在独立的上下文窗口中运行并返回精炼后的结果。当某个任务需要大量读取操作，可能污染主线程上下文时，可以考虑使用它。

实战示例：将”从全新 checkout 运行并验证”固化为 skill

将你的配置流程转化为一个提交到仓库的 skill。创建 .claude/skills/run-app/SKILL.md，其中的 description 要足够具体以便智能体匹配，同时在开头注入实时命令输出，并使用编号步骤：

---
name: run-app
description: Get this app running from a clean checkout and verify it boots. Use when setting up the project, onboarding, or checking the app still starts after a change.
allowed-tools: Bash(npm *) Bash(./scripts/verify.sh *)
---

## Environment
```!
node --version
npm --version
```

## Steps
1. Install dependencies with `npm ci`.
2. If `.env` is missing, copy `.env.example` to `.env`; ask before overwriting.
3. Start the app with `npm run dev`.
4. Run `./scripts/verify.sh` and report PASS or FAIL.

Expected output: a single PASS/FAIL line and the local URL the app serves on.

以 ```! 包裹的代码块使用了动态上下文注入功能：Claude Code 会在智能体读取 skill 之前先执行这些命令并将输出内联进来，这样操作流程在到达智能体时就已经基于你的实际工具链，而非凭空猜测。输入”get the app running”，智能体会根据描述自动加载该 skill；输入 /run-app 则可以强制触发。

Claude Code 还将这一模式作为内置 skill 提供。/run-skill-generator 会在干净的环境中启动你的应用，记录成功的步骤（安装命令、环境变量、启动脚本），并将其作为项目级 skill 提交到 .claude/skills/run-<name>/。此后，/run、/verify 以及仓库中的任何其他智能体都将遵循这份记录好的流程，而不是重新摸索。/run、/verify 和 /run-skill-generator 需要 Claude Code v2.1.145 或更高版本。

让 skill 可靠，然后提交它

保持每个 skill 的原子性，并明确说明预期输出：一个 skill，一项职责，一个可以在 pull request 中审查的明确结果。模糊的说明会导致行为漂移；明确的输出格式能让每次运行保持一致，也让下游解析更加安全。

将不允许变化的步骤放入捆绑的 scripts/verify.sh 中，让 SKILL.md 的主体负责处理需要判断的部分：报告验证失败的原因，发现缺失的环境变量。正是这种分工，让整个工作流程具备可重复性，而非依赖概率。

有一个真实的局限性需要坦诚面对：自动调用完全依赖于 description 的质量，它并不总是会触发。官方文档的第一条排查建议，就是检查 description 中是否包含用户自然会说出的关键词。当你需要确保手动触发时（任何具有副作用的操作），请设置 disable-model-invocation: true，这样 skill 只会在你输入 /name 时执行。

然后将 .claude/skills/ 提交到版本控制。这一步将整个流程形成闭环：操作流程变得可版本化、可审查、可共享，下一位贡献者和下一次智能体会话都将继承一套可用的流程，而不是从头重建。Skills 在 Claude.ai、Claude Code 和 API 中均可使用，根据 Anthropic 支持文档，该功能目前对 Claude Code 用户以及所有使用代码执行工具的 API 用户处于 beta 阶段，因此提交到仓库的项目 skill 会随代码库一起流转，而不是只存在于某个人的 shell 历史记录中。

从你最常重复的任务开始（全新 checkout 后的启动流程、发布变更日志、数据库初始化与重置）：编写对应的 SKILL.md，将确定性部分封装为脚本，然后提交。下次任何人（或智能体）需要这套流程时，它已经在那里等着了。

常见问题

我还能手动调用 Claude Code skill 吗，还是只能自动触发？

两种方式都可以。默认情况下，你和 Claude 都可以调用任何 skill：输入 /skill-name 直接运行，或者当 Claude 判断你的请求与某个 skill 的描述匹配时，它会自动加载。声称 skill 无法手动运行的旧版教程已经过时。如果你希望某个具有副作用的 skill 只能手动触发，请将 disable-model-invocation 设置为 true，这样它只会在你输入名称时执行。

当 slash command 和 skill 同名时会发生什么？

skill 优先生效。Custom commands 已合并到 skills 中：位于 .claude/commands/deploy.md 的文件和位于 .claude/skills/deploy/SKILL.md 的 skill 都会创建相同的 /deploy 命令，两者效果完全一致。当同名的两者同时存在时，Claude Code 会加载 skill 而非命令文件，因此无需为同一个命令同时维护两者。

skill 中捆绑的脚本会消耗上下文窗口的 token 吗？

不会。当 skill 的说明中引用了一个可执行脚本时，Claude 会通过 bash 运行它，并只接收输出结果；脚本代码本身不会进入上下文窗口。这正是将确定性工作封装为脚本比让模型推理执行更高效、更可靠的原因，也是 skill 可以捆绑的资源在大小上实际没有上限的原因。

使用 Claude Code skills 需要付费订阅吗？

不需要。根据 Anthropic 支持文档，skills 在 Free、Pro、Max、Team 和 Enterprise 计划中均可使用，且需要启用代码执行功能。在 Claude Code 中，skills 目前处于 beta 阶段；对于所有使用代码执行工具的 API 用户，skills 同样可用。由于可用性详情可能随时变化，请以 Anthropic 当前的支持文档为准。