Agent Skills 完全指南从 Prompt Engineering 到 Skill Engineering 的范式革命当所有人还在卷 Prompt 的时候一批开发者已经悄悄把 AI Agent 装上了技能包。2025年12月Anthropic 将 Agent Skills 正式发布为开放标准——继 MCP 之后AI 原生应用的能力层拼图彻底补齐。Claude、Cursor、OpenCode、Letta 等头部工具已率先支持。本文将从概念解析、标准拆解到硬核实战带你完成从指挥 AI到配置 AI的认知跃迁。一、为什么 Agent Skills 是 2026 年最值得学的 AI 技术1.1 一个让你沉默的对比维度Prompt EngineeringSkill Engineering持久性一次性的跨会话不保留永久安装全项目生效复用性每次重新粘贴写一次到处运行精确性靠人力微调措辞结构化Schema驱动协作性只能人→AIAI→AI、Agent→Agent工程化文档散落在聊天记录版本控制、代码审查、CI/CD一句话总结Prompt 是临时工Skill 是正式员工。1.2 行业正在发生的三个信号信号一三大 AI 巨头默契统一OpenAI、Anthropic、Google DeepMind——三家没有联合声明、没有标准委员会却不约而同采用了几乎相同的 Skill 定义格式基于 JSON Schema。这不是巧合是技术收敛的必然。信号二开发工具集体入局Claude Code、Cursor、Qoder、OpenCode、VS Code、Letta……一线 AI 编程工具在 2025 年末至 2026 年初密集上线 Skills 支持。一套 Skill多平台运行。信号三从单 Agent 到多 Agent 架构当 Agent 需要协作时你擅长什么比你能回答什么重要一万倍。Skills 是 Agent 间能力发现的唯一标准化方案。二、什么是 Agent Skills核心概念全解析2.1 一句话定义Agent Skill 是一个可移植的能力包——它让 AI Agent 知道自己能做什么、何时做、怎么做。物理形态上它就是一个文件夹my-skill/ ├── SKILL.md # 必须元数据 指令入口文件 ├── scripts/ # 可选可执行脚本 │ └── validate.sh ├── references/ # 可选参考文档 │ └── REFERENCE.md ├── assets/ # 可选模板、资源文件 │ └── template.md └── examples/ # 可选示例输出 └── sample.md2.2 SKILL.md 的完整结构每个 Skill 的核心是SKILL.md由两部分组成YAML Frontmatter元数据Markdown Body指令。---name:code-review# 必须技能名称小写连字符description:按 OWASP Top 10 标准审查代码检查安全漏洞和最佳实践违规。# 必须描述做什么何时用license:Apache-2.0# 可选许可证compatibility:Requires git,jq# 可选环境依赖metadata:# 可选扩展元数据author:dev-teamversion:1.0allowed-tools:Bash(git:*)Read# 可选预授权工具列表---# 代码审查指令## 步骤1. 使用 git diff 获取待审查的代码变更 2. 逐文件检查以下维度-SQL 注入风险-硬编码密钥/凭证-缺失的错误处理-不安全的反序列化 3. 按 严重/警告/建议 三级分类输出 4. 生成修复建议和具体代码修改## 输出格式|级别|文件|行号|问题描述|修复建议||------|------|------|---------|---------|## 注意事项-忽略 auto-generated 文件-对 test 文件降低严格度2.3 命名规则踩坑必看name字段必须严格遵守规则合法示例非法示例原因仅小写字母数字连字符code-reviewCode-Review大写不允许不能以连字符开头/结尾pdf-process-pdf开头不能是-不能连续连字符data-analysisdata--analysis--不允许必须与目录名一致目录code-review/name 写成cr名不匹配最长 64 字符a-valid-name超过 64 字符长度超限2.4 渐进式披露为什么 1000 个 Skill 也不卡Agent Skills 的杀手级设计——Progressive Disclosure渐进式披露第一阶段Metadata~100 tokens → 系统启动时只加载 name description → Agent 知道我有什么技能但还没加载具体指令 第二阶段Instructions5000 tokens → 当 Agent 决定使用某个 Skill 时才加载 SKILL.md 全文 → 只占上下文一小部分 第三阶段Resources按需 → scripts/、references/、assets/ 中的文件 → 仅在指令中引用到时才加载实际效果给 Agent 装备 1000 个 Skill日常仅占用约 10 万 tokens 的元数据空间。只有真正干活时才按需加载详细指令。这完美解决了 Token 浪费和上下文干扰问题。三、Skills vs Tools vs MCP vs A2A一张图厘清生态定位3.1 四层架构全景┌─────────────────────────────────────────────────┐ │ A2A 协议层 │ │ Agent 间协作的社交网络 │ │ 你能做什么我需要你的帮助 │ ├─────────────────────────────────────────────────┤ │ Skills 能力层 │ │ Agent 的技能包与岗位SOP │ │ 我知道怎么做这是我的操作手册 │ ├─────────────────────────────────────────────────┤ │ MCP 连接层 │ │ 工具调用的通用插座 │ │ 我能连接到数据库、文件系统、API │ ├─────────────────────────────────────────────────┤ │ Agent 执行主体 │ │ 感知 → 规划 → 行动 → 记忆 → 反思 │ └─────────────────────────────────────────────────┘3.2 核心区别对比维度ToolsSkillsMCPA2A本质可执行函数/API知识行为模式连接协议协作协议粒度原子操作复合能力传输通道通信框架解决的问题“能做什么”“做得对不对”“能不能访问”“怎么分工”类比螺丝刀维修手册USB 接口团队协作流程3.3 一次看懂商务邮件场景Tool: send_email(to, subject, body) ← 一个函数调用 Skill: 商务邮件写作规范 ← 包含模板、礼仪、语气指南 MCP: 连接到 Gmail/企业邮箱 ← 建立通信管道 A2A: 邮件Agent ← 接收任务 ← 主Agent ← Agent间委托最佳实践用 MCP 建立连接用 Skill 定义流程用 A2A 分工协作。四、开放标准三大 AI 巨头的默契统一4.1 没有标准委员会的收敛2023 年中OpenAI 率先推出 Function Calling定义了第一个事实标准{name:get_weather,description:Get the current weather for a location,parameters:{type:object,properties:{location:{type:string,description:City and state, e.g. Austin, TX}},required:[location]}}随后Anthropic 的 Tool Use、Google 的 FunctionDeclaration都采用了几乎相同的 JSON Schema 格式。差异仅在表层参数包装方式、调用信号格式、API 传参位置。4.2 为什么是 JSON Schema优势说明已有生态API 文档和数据验证已广泛使用双重可读人类可读 机器可解析类型完备支持 string/number/enum/array/nested object零成本迁移无需新规范直接复用现有工具链4.3 三家实现的差异一览平台定义方式调用信号特色OpenAItools[]→type: function返回tool_calls数组Agents SDK 支持 HandoffAnthropictools[]→input_schema返回tool_use内容块description 对准确率影响最大GoogleFunctionDeclaration返回functionCall部分原生多模态支持关键洞察一个 Skill 定义三家平台只需改包装层核心 Schema 完全通用。跨平台 Skill 适配器完全可行。4.4 MCP vs Skills不要混淆这是开发者最容易混淆的一对概念维度MCPSkills解决问题一个 Agent 如何访问外部工具和数据多个 Agent 间如何描述和共享能力方向Agent → 工具1对多Agent ↔ Agent多对多类比USB 接口通用驱动程序关系基础设施层能力互操作层一句话MCP 是硬件连接Skills 是软件驱动。两者互补而非竞争。五、实战一5 分钟创建你的第一个 Agent Skill5.1 场景Git 变更摘要 Skill每当想看自己改了什么、有没有风险操作一个 Skill 搞定。Step 1创建目录# 个人 Skill所有项目可用mkdir-p~/.claude/skills/summarize-changes# 或项目级 Skill仅当前项目mkdir-p.claude/skills/summarize-changesStep 2编写 SKILL.md---name:summarize-changesdescription: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## InstructionsSummarize the changes above in two or three bullet points,then list any risks you notice such as:-Missing error handling-Hardcoded secrets or API keys-Tests that need updating-Breaking changes to public APIs If the diff is empty,say there are no uncommitted changes.## Output Format**Summary:**-bullet 1-bullet 2**Risks:**-⚠️ risk descriptionor No significant risks detected关键技巧!git diff HEAD是动态上下文注入——Claude Code 会在加载 Skill 前先执行该命令将输出内联替换到 Skill 内容中。这样 Agent 看到的就是实时 diff 数据而非静态文本。Step 3测试在任意 Git 项目中启动 Claude Code# 方式一自然语言触发Claude 根据 description 自动判断 我改了什么 # 方式二直接调用 /summarize-changes5.2 Skill 的三种存放位置位置路径生效范围个人~/.claude/skills/name/SKILL.md你的所有项目项目.claude/skills/name/SKILL.md仅当前项目插件plugin/skills/name/SKILL.md启用插件的位置优先级企业 个人 项目。插件 Skill 使用plugin-name:skill-name命名空间不会冲突。六、实战二企业级代码审查 Skill含脚本参考文档6.1 场景说明构建一个完整的 Go 项目 Code Review Skill包含主指令、Lint 脚本、安全检查参考文档。6.2 目录结构code-review/ ├── SKILL.md # 主指令 ├── scripts/ │ ├── go-lint.sh # Go Lint 检查脚本 │ └── go-vuln.sh # 漏洞扫描脚本 ├── references/ │ ├── SECURITY-CHECKLIST.md # 安全审查清单 │ └── GO-BEST-PRACTICES.md # Go 最佳实践参考 └── assets/ └── review-template.md # 审查报告模板6.3 SKILL.md 主文件---name:code-reviewdescription:Analyze Go code changes based on OWASP Top 10 and Go best practices. Use when reviewing pull requests, checking code quality, or when the user asks for a code review.license:Apache-2.0compatibility:Requires go,git,jqmetadata:author:devops-teamversion:2.0allowed-tools:Bash(git:*)Bash(go:*)Read Write---# Go Code Review Skill## OverviewThis skill performs comprehensive code review for Go projects,covering security,performance,readability,and correctness.## Step-by-step Instructions### Phase 1: Collect Changes1. Run git diff--name-only origin/main...HEAD to identify changed files 2. Filter for .go files only 3. Skip auto-generated files (e.g.,*_test.goin vendor/)### Phase 2: Static AnalysisRun the linting script to catch common issues:bash bash scripts/go-lint.shReview the output and categorize findings.Phase 3: Security ReviewConsult SECURITY-CHECKLIST.md forthe complete security review checklist. Focus on:SQL injection (string concatenation in queries)Hardcoded credentials or API keysUnsafe use ofinterface{}without type assertionMissing input validation on HTTP handlersAlso run vulnerability scanning:bashscripts/go-vuln.shPhase 4: Best Practices CheckReference GO-BEST-PRACTICES.md fordetailed guidelines. Key areas:Error handling: Are errors properly wrapped with context?Concurrency: Are goroutines properly managed with context cancellation?Resource management: Aredeferstatements used for cleanup?API design: Do exported functions follow Go naming conventions?Phase 5: Generate ReportUse the template in review-template.mdto format your findings. Classify each issue as:Critical: Security vulnerability, data loss riskWarning: Performance issue, missing error handlingSuggestion: Code style, readability improvementEdge CasesIf no Go files are changed, report “No Go code changes to review”For test files, reduce severity level by one notchFor generated code (//go:generate), skip entirelyIfgo vetfails to run, note the environment issue and proceed with manual review### 6.4 Lint 脚本 bash #!/bin/bash # scripts/go-lint.sh - Go 静态分析检查 set -euo pipefail echo Go Vet go vet ./... 21 || true echo echo Go Lint (golangci-lint) if command -v golangci-lint /dev/null; then golangci-lint run --timeout5m ./... 21 || true else echo golangci-lint not installed, skipping fi echo echo Go Format Check unformatted$(gofmt -l .) if [ -n $unformatted ]; then echo Files needing formatting: echo $unformatted else echo All files properly formatted fi6.5 安全审查清单!-- references/SECURITY-CHECKLIST.md -- # Go Security Review Checklist ## Input Validation - [ ] All HTTP handler inputs are validated - [ ] File paths are sanitized (no path traversal) - [ ] SQL queries use parameterized statements - [ ] User input is not directly interpolated into templates ## Authentication Authorization - [ ] Sensitive endpoints require authentication - [ ] Role-based access control is properly enforced - [ ] JWT tokens are validated (signature, expiry, issuer) - [ ] Password hashing uses bcrypt/argon2 (not MD5/SHA) ## Data Protection - [ ] No hardcoded secrets or API keys - [ ] Sensitive data is encrypted at rest - [ ] TLS is used for all network communication - [ ] Logs do not contain PII or credentials ## Error Handling - [ ] Internal errors are not exposed to clients - [ ] Stack traces are not returned in production - [ ] Panic recovery middleware is in place - [ ] Context cancellation is properly handled6.6 审查报告模板!-- assets/review-template.md -- # Code Review Report **Date**: {date} **Reviewer**: Agent Skill **Branch**: {branch} ## Summary {2-3 sentence summary of changes} ## Findings | # | Level | File | Line | Issue | Fix | |---|-------|------|------|-------|-----| | 1 | // | | | | | ## Metrics - Files reviewed: {n} - Critical issues: {n} - Warnings: {n} - Suggestions: {n} ## Verdict - [ ] ✅ Approved - No critical issues - [ ] ⚠️ Conditional - Fix warnings before merge - [ ] ❌ Rejected - Critical issues must be resolved6.7 使用方式# 自动触发Claude 根据 description 判断 请审查这个 PR 的代码变更 # 手动调用 /code-review # 指定范围 审查 src/api/ 目录下最近的变更七、实战三多 Skill 协作——构建智能研发工作流7.1 场景三个 Skill 联合完成提交前全流程检查用户: 我要提交代码了帮我做一次完整检查 ┌──────────────────────────────────────────────┐ │ 主 Agent (Claude) │ │ │ │ 1. 自动加载 /summarize-changes │ │ → 获取变更概览和风险标记 │ │ │ │ 2. 自动加载 /code-review │ │ → 执行安全审查 Lint 检查 │ │ │ │ 3. 自动加载 /commit-helper │ │ → 生成规范的 commit message │ │ │ └──────────────────────────────────────────────┘7.2 第三个 SkillCommit Message 生成器---name:commit-helperdescription:Generate conventional commit messages from staged changes. Use when the user wants to commit, needs a commit message, or asks about commit conventions.---## Current staged changes!git diff--cached--stat## InstructionsGenerate a commit message following Conventional Commits format:():Type Selection Guidefeat: New featurefix: Bug fixrefactor: Code restructuring without behavior changedocs: Documentation onlytest: Adding or updating testschore: Build process, dependencies, toolingperf: Performance improvementci: CI/CD configurationRulesSubject line: max 72 characters, imperative moodBody: explain WHY, not WHAT (diff already shows what)Reference issue numbers in footer if applicableBreaking changes: use!after type and explain in footerExamplefeat(api): add rate limiting to user endpoints Implement token bucket rate limiter for /api/users/* endpoints to prevent abuse. Default: 100 requests/minute per IP. Closes #142### 7.3 工作流编排 将三个 Skill 放入项目后只需一句话触发 text 我要提交代码了 Claude 会自动 1. 加载 summarize-changes → 输出变更摘要 2. 加载 code-review → 输出审查报告 3. 加载 commit-helper → 生成 commit message 如果审查有 Critical 问题Claude 会建议先修复再提交。 如果一切正常Claude 会直接帮你执行 git commit。八、主流平台 Skills 支持一览平台Skills 支持存放路径特色功能Claude Code✅ 完整支持~/.claude/skills//.claude/skills/动态上下文注入、子 Agent 执行、自动发现Cursor✅ 已支持项目配置与 Cursor Rules 集成Qoder✅ 内置 create-skill.qoder/skills/交互式 Skill 创建向导/create-skillVS Code✅ 通过插件工作区配置微软官方集成 Agent Skills 标准OpenCode✅ 已支持项目配置开源 AI 编程工具Letta✅ 已支持Agent 配置记忆增强型 Agent 框架8.1 Qoder 的交互式创建方式Qoder 内置了/create-skill命令通过对话引导你逐步创建 SKILL.md /create-skill Qoder: 好的让我们创建一个新的 Skill。 1. 请输入技能名称小写连字符: api-doc-generator 2. 请描述这个技能的功能和适用场景: 自动根据代码注释生成 OpenAPI 文档... 3. 这个技能需要哪些工具权限 Read, Write, Bash(swagger:*) 4. 请提供主要指令内容: ... ✅ Skill 已创建: .qoder/skills/api-doc-generator/SKILL.md8.2 验证你的 Skill使用官方验证工具# 安装验证工具pipinstallskills-ref# 验证 Skill 格式skills-ref validate ./my-skill# 输出示例✅ name: valid ✅ description: valid ✅ frontmatter: valid ✅ directory name matches skill name ✅ SKILL.md found九、编写高质量 Skill 的 10 条黄金法则法则 1Description 是 Skill 的搜索引擎优化# ❌ 差太模糊description:Helps with PDFs.# ✅ 好包含做什么 何时用 关键词description:Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.Agent 根据 description 决定是否激活 Skill。写得越精准自动触发越准确。法则 2SKILL.md 控制在 500 行以内超过 500 行的指令Agent 容易走神。把详细参考资料拆到references/目录主文件只保留核心步骤。法则 3用动态上下文注入替代静态假设# ❌ 差让 Agent 自己猜请检查当前项目的代码变更# ✅ 好用 !command 注入实时数据!git diff HEAD法则 4明确输出格式# ❌ 差分析代码并给出建议# ✅ 好按以下格式输出|级别|文件|行号|问题|修复建议||------|------|------|------|---------|级别分为 Critical / Warning / Suggestion法则 5处理边界情况## Edge Cases-如果没有 Go 文件变更报告 No Go code changes to review-如果 diff 为空报告 No uncommitted changes-如果 lint 工具未安装跳过该步骤并注明法则 6合理使用 allowed-tools# 仅预授权必要的工具避免过度权限allowed-tools:Bash(git:*)Read# 而不是allowed-tools:Bash(*)# 危险允许执行任意命令法则 7区分参考型和任务型Skill# 参考型知识注入Claude 自动使用---name:api-conventionsdescription:API design patterns for this codebase---# 任务型分步操作通常手动调用---name:deploydescription:Deploy the application to productiondisable-model-invocation:true# ← 禁止自动触发---法则 8善用 Monorepo 的嵌套发现my-monorepo/ ├── .claude/skills/ # 全局 Skill │ └── code-review/ ├── packages/ │ ├── frontend/ │ │ └── .claude/skills/ # 前端专用 Skill │ │ └── react-review/ │ └── backend/ │ └── .claude/skills/ # 后端专用 Skill │ └── api-review/当你在packages/frontend/中工作时Claude 会自动发现上下两级目录的 Skill。法则 9版本化你的 Skillmetadata:version:2.1changelog:|v2.1: Added OWASP API Security Top 10 checks v2.0: Restructured to separate references v1.0: Initial release法则 10为 Skill 编写测试# 在项目中创建 Skill 测试脚本test/test-skills.sh#!/bin/bash# 验证 Skill 基本功能echoTesting summarize-changes...echotesttest-file.txt# 在 Claude Code 中运行 /summarize-changes# 预期检测到变更输出摘要rmtest-file.txt十、Agent Skills 的未来从能做到会做10.1 技术趋势趋势说明预期时间Skill 市场成熟类似 VS Code 插件市场的一站式 Skill 分发2026 下半年跨平台互操作一套 Skill 在 Claude/Cursor/Qoder/VS Code 通用已实现基础Skill 链式编排Skill A 的输出自动成为 Skill B 的输入2026 Q3企业 Skill 仓库私有 Skill Registry内部知识沉淀2026 Q2Skill 自动生成AI 根据你的操作记录自动提炼 Skill2026 Q410.2 对开发者的意义从 Prompt Engineer 到 Skill EngineerPrompt Engineer过去 → 写提示词 → 调措辞、换格式 → 聊天记录就是文档 → 经验无法复用 Skill Engineer未来 → 设计能力架构 → 编写结构化指令 → 版本控制、代码审查 → 企业知识可沉淀、可复用、可迁移未来的高价值开发者不再是那些会写漂亮提示词的人而是能将企业隐性知识封装成标准化、可移植 Agent Skills 的人。10.3 行动建议第一步安装 Claude Code 或 Qoder → 创建你的第一个 Skill ↓ 第二步把重复性指令迁移为 Skillcommit message、代码审查、部署流程 ↓ 第三步为团队项目建立共享 Skill 库编码规范、安全检查、CI/CD ↓ 第四步探索多 Agent 多 Skill 协作架构 ↓ 第五步发布你的 Skill 到社区成为 Skill Engineer 先行者附录关键资源资源链接Agent Skills 开放标准规范https://agentskills.io/specificationClaude Code Skills 文档https://code.claude.com/docs/zh-CN/skillsAnthropic Skills GitHubhttps://github.com/anthropics/skillsQoder Skills 文档https://docs.qoder.com/zh/extensions/skillsskills-ref 验证工具https://github.com/agentskills/agentskills/tree/main/skills-refGoogle A2A 协议https://github.com/google/A2AAnthropic MCP 协议https://modelcontextprotocol.ioOpenAI Agents SDKhttps://github.com/openai/openai-agents-pythonDatawhale Agent Skills 教程https://github.com/datawholechina/agent-skills-with-anthropicAgent Skills 不是又一个转瞬即逝的热词它是 AI Agent 从玩具到工具的关键基础设施。就像 npm 之于 Node.js、Docker 之于容器化——当生态的标准层出现才是技术真正爆发的起点。而现在这个标准层刚刚铺好。早一步掌握 Skill Engineering就早一步拿到 AI 2.0 时代的入场券。如果这篇文章对你有帮助点赞收藏关注三连下期我们将深入实战——用 Agent Skills 构建完整的 CI/CD 自动化流水线。