跳转至

智能体技能（Agent Skills）/ SKILLS.md

概述

智能体技能（Agent Skills，亦称 SKILLS.md 这一新兴惯例）是可复用、可共享的工作流定义，允许 Claude Code 智能体——以及任何兼容的智能体运行框架（harness）——通过斜杠命令按需执行可重复的工程流程。Anthropic 于 2025 年推出 Skills，将其作为一等的、受版本控制的任务模块：团队只需将最佳实践编写一次，项目中的任何智能体均可一致地调用。

CLAUDE.md / AGENTS.md 控制的是智能体的常驻行为，Skills 控制的则是按需任务执行。两者相辅相成：CLAUDE.md 设定持久化指令与约束，SKILLS.md 则封装特定的、可触发的工作流。

核心概念

什么是 Skill

Skill 是一个 Markdown 文档（或其中的具名章节），包含以下内容： - 名称 — 斜杠命令触发词（/skill-name） - 描述 — 在 /help 输出中展示的单行摘要 - 指令 — 调用该 Skill 时 Claude 必须按序执行的步骤

Skill 默认是无状态的。每次调用都会重新开始，读取文件、测试和上下文的当前状态，而不会假设任何先前状态。

调用模型

用户通过斜杠命令触发 Skill：

/skill-name [optional arguments]

Claude Code 在会话启动时发现匹配的 Skill 定义，将其加载到上下文中，并在用户输入触发词后执行声明的步骤。参数以自由文本形式传入，在指令中以 $args 引用或通过上下文描述。

作用域

作用域 位置 可见性
项目级 .claude/skills/<name>.md 通过版本控制对所有团队成员可见
用户全局 ~/.claude/skills/<name>.md 单个用户，跨所有项目
内联（CLAUDE.md） 在仓库根目录的 CLAUDE.md 或 SKILLS.md 中定义 项目全局，单文件

项目级 Skill 是团队的推荐方式：技能与其所操作的代码放在一起，经过 Pull Request 评审，并随代码库同步演进。

Skill 文件格式

Skill 是一个遵循以下结构的 Markdown 文件（或具名章节）：

# <Skill Name>

<One-line description of what this skill does.>

## Instructions

When the user invokes /<skill-name> [describe argument handling]:

1. <First step>
2. <Second step — reference $args or specific files as needed>
3. <Continue…>

Report results to the user after each major step.

规范 Skill 文件的编写规则： - H1 标题即为斜杠命令名称（转为小写，空格替换为连字符）。 - 指令必须足够明确，使智能体无需提问即可执行。 - Skill 应引用具体的工具、路径或命令，而非泛泛的指导建议。 - 避免依赖会话记忆的指令——Skill 必须是自包含的。

示例：代码审查 Skill

# review

Run a structured code review of the current diff.

## Instructions

When the user invokes /review [optional focus area]:

1. Run `git diff main...HEAD` to gather the full diff.
2. If $args specifies a focus (e.g. "security", "performance"), weight findings accordingly.
3. Check for correctness bugs, missing error handling at system boundaries, and obvious security issues (injection, XSS, unvalidated input).
4. Report findings as a numbered list ordered by severity. For each finding include: file, line range, issue, and a one-line fix suggestion.
5. End with a summary: total findings by severity, and an overall recommendation (approve / approve with minor changes / request changes).

示例：部署 Skill

# deploy

Run pre-deploy checks and deploy to staging.

## Instructions

When the user invokes /deploy [environment]:

1. Run the full test suite. Stop and report if any tests fail.
2. Run `npm run build` (or equivalent). Stop and report build errors.
3. Check that all required environment variables are set for $args environment (default: staging).
4. Execute the deploy command for $args: `./scripts/deploy.sh $args`.
5. Tail the deploy log for 60 seconds and surface any ERROR lines.
6. Report final status: deployed / failed, with the URL if successful.

架构与发现机制

Claude 如何发现 Skill

会话启动时，智能体运行框架（harness）扫描已配置的 Skill 目录，并将 Skill 清单注入系统上下文。清单列出了所有可用的斜杠命令及其描述，使 /help 能够枚举出全部 Skill，而无需加载完整的指令内容。

当用户输入斜杠命令时，运行框架会： 1. 将命令与清单进行匹配。 2. 将完整的 Skill 指令内容加载到当前上下文窗口。 3. 将控制权连同用户参数一并交给 Claude。 4. Claude 按指令执行各步骤，并按需调用可用工具（Bash、Read、Edit 等）。

与 CLAUDE.md 和 AGENTS.md 的关系

文件 用途 触发方式
CLAUDE.md / AGENTS.md 持久化智能体指令、约束与编码风格 始终生效
SKILLS.md / .claude/skills/*.md 可触发的任务工作流 按需触发，斜杠命令
HOOKS（settings.json） 事件驱动自动化（工具调用前/后） 事件驱动

Skills 与持久化指令互不冲突：CLAUDE.md 确立智能体的基准行为，Skills 则在此基准之上封装特定流程。

最佳实践

挑战 / 领域 描述 解决方案 / 建议
幂等性 Skill 可能在相同状态下被多次调用 将指令写成重复执行也能产生相同结果的形式；写入前先检查是否已有输出
参数处理 自由格式参数可能存在歧义 在指令中明确说明参数格式；当 $args 为空时提供默认值
职责蔓延 试图处理过多事务的 Skill 会产生不可预期的结果 一个 Skill 专注一个目标；将复杂工作流拆分为可组合的子 Skill
指令过时 为旧版仓库结构编写的 Skill 会静默失败 让 Skill 与代码库同步演进；在结构变更的 PR 中同步审查 Skill 文件
可发现性 团队成员不清楚有哪些 Skill 可用 维护一份 skills/README.md，以表格形式列出所有可用 Skill 及其触发词
Skill 测试 不实际运行很难验证 Skill 行为 编写配套测试 Skill（/test-skill <name>），在固定分支上对该 Skill 进行执行验证
密钥处理 涉及部署或 API 调用的 Skill 存在凭据泄露到日志中的风险 切勿在 Skill 文件中硬编码密钥；通过名称引用环境变量，而非直接写入值

应用场景

软件开发

  • /review — 支持可配置关注点的结构化代码审查
  • /test — 为已修改文件生成或运行测试
  • /docs — 根据近期代码变更更新文档
  • /refactor — 对指定模块应用预定义的重构模式

DevOps 与部署

  • /deploy [env] — 部署前检查 + 部署到指定环境
  • /rollback [version] — 回滚到特定版本并进行验证
  • /migrate — 执行数据库迁移，包含前置和后置检查
  • /infra-check — 在 apply 前验证基础设施配置

安全与质量

  • /security-review — 扫描 diff 中的 OWASP Top 10 问题及密钥泄露
  • /lint-fix — 运行 linter 并自动应用安全修复
  • /depcheck — 审计依赖项中的已知漏洞

知识与流程

  • /standup — 根据近期提交和待处理 PR 生成站会摘要
  • /estimate — 为描述的任务生成时间与复杂度评估
  • /onboard — 引导新团队成员完成项目设置清单

厂商 Skill 仓库

主要 AI 与云厂商均维护着公开的即用型 Skill 仓库，团队可直接导入至兼容的运行框架。下表列出了截至 2025—2026 年的官方源仓库。

厂商 仓库 / 安装命令 备注
Anthropic github.com/anthropics/skills Claude Code 参考集合，涵盖代码审查、部署、安全及文档工作流
Google github.com/google/skills 适用于 Gemini CLI 和基于 Google ADK 的运行框架
Microsoft github.com/microsoft/azure-skills 面向 Azure AI Agent Service 和 Semantic Kernel 工具链
OpenAI github.com/openai/skills 适用于 OpenAI Codex 和基于 Responses API 的智能体
AWS npx skills add aws/agent-toolkit-for-aws/skills 通过 Skills CLI 从 AWS Agent Toolkit 注册表安装，面向 Strands Agents 和 Kiro
Cloudflare github.com/cloudflare/skills 适用于 Cloudflare Workers AI 和边缘部署的智能体
Vercel github.com/vercel-labs/skills 面向 AI SDK 和 Vercel 托管的智能体部署
NVIDIA github.com/NVIDIA/skills 约 200+ 个 NVIDIA 官方验证技能的目录（以产品名为前缀，如 cuopt-、nemo-、tao-），用于使用 NVIDIA 软件/平台；每日从各产品仓库同步。每个技能都附带 SKILL.md、skill-card.md 以及 OMS 格式的加密签名（skill.oms.sig），可对照 nv-agent-root-cert.pem 验证以保障供应链完整性。双许可 Apache 2.0 / CC BY 4.0；可通过 npx skills CLI 在兼容的运行框架（Claude、Cursor、Codex）中安装

从厂商仓库安装 Skill

大多数仓库遵循相同的模式——通过 Skills CLI 克隆或安装，然后按名称引用 Skill：

# GitHub-hosted (any provider)
git clone https://github.com/<org>/skills .claude/skills/<provider>

# AWS registry via npm-style CLI
npx skills add aws/agent-toolkit-for-aws/skills

# Selective install — copy a single skill file
cp .claude/skills/anthropics/review.md .claude/skills/review.md

厂商 Skill 由社区维护，其演进独立于运行框架。在生产环境中，请固定到特定的提交或标签，防止未经审查的变更在会话启动时被加载到智能体上下文中。

社区 Skill 市场与精选列表

除上述官方厂商仓库外，越来越多由社区维护的精选列表和市场正在跨厂商、跨应用场景地汇聚各类 Skill：

资源 类型 说明
ComposioHQ/awesome-claude-skills 精选列表 GitHub 上由社区维护的 Claude 专属 Skill 精选列表
VoltAgent/awesome-agent-skills 精选列表 汇聚了来自官方厂商团队和社区、跨多个运行框架的 1000+ 个 Skill
Agent-Skills-for-Context-Engineering 精选列表 专注于上下文工程和生产智能体系统 Skill
Agensi 市场 Skill 市场，提供付费（商业）Skill 与免费 Skill
Claude Skills Marketplace 目录 可搜索的 Claude Skill 社区目录
Smithery 注册表 同时支持 Skill 和 MCP 服务器的联合注册表，支持在兼容运行框架中一键安装

这些列表与官方厂商仓库（anthropics/skills、openai/skills）在覆盖范围上有所重叠，但将发现渠道延伸至尚未纳入官方目录的社区贡献和厂商贡献 Skill。与厂商仓库一样，在生产环境中采用社区 Skill 时，请固定到特定提交，因为这些列表不受与官方仓库相同的审查流程约束。

与智能体运行框架的集成

Skills 是 Claude Code 运行框架（harness）中的一等概念，同时也被设计为可移植的。任何满足以下条件的运行框架均可实现 SKILLS.md 惯例： 1. 在会话启动时读取 Skill 清单 2. 在命令匹配时将 Skill 指令注入上下文 3. 将用户参数传递给智能体

这使得 Skills 成为与 AGENTS.md 和 MCP 并列的标准化候选，是新兴智能体 AI 互操作层的组成部分。

与 MCP 及工具调用的关系

Skills 编排的是智能体如何使用其现有工具，而非为其添加新工具。MCP 服务器扩展智能体的工具集（新增能力），Skills 则将智能体的现有能力引导至特定工作流。例如，一个部署 Skill 可能会调用 Bash 工具、Read 工具以及 MCP 提供的部署 API 工具——Skill 是工作流，MCP 提供的是基础原语。

参见

参考资料