1. 从“经验”到“能力”为什么我们需要Agent Skills最近在折腾各种AI Agent框架时我总在思考一个问题我们花大量时间调教一个Agent让它学会处理某个特定任务比如分析日志、生成SQL或者格式化代码。这个过程本质上是在向它灌输我们的“经验”。但下次换个项目、换个环境甚至只是重启一下对话这些好不容易积累的经验就清零了一切又得从头开始。这就像你教会了一个实习生一套复杂的报表流程结果他第二天就忘了或者换了个部门这套经验就带不走了。这显然不是我们想要的协作方式。我们真正需要的是把这些“经验”固化下来变成一种可以随时、随地、被任意Agent调用的标准化“能力”。这就是Agent Skills智能体技能概念正在解决的问题。它不是一个虚无缥缈的学术概念而是当前AI应用工程化落地中最实际、最迫切的需求。看看围绕它的热词——SKILL.md、AGENTS.md、MCP、skill开发——你会发现整个社区都在试图用不同的工具和协议来解决同一个核心问题如何将人类或AI的最佳实践封装成可复用、可组合、可分发的原子化能力单元。简单来说一个Skill就是一个封装好的功能模块。它定义了能力是什么输入、输出、描述以及如何调用它具体的实现逻辑或接口。当你的Agent遇到一个任务时它不再需要从零开始“思考”如何解决而是可以去自己的“技能库”里检索找到合适的Skill直接调用。这极大地提升了效率、准确性和一致性。举个例子你为团队封装了一个“生成数据库变更SQL评审报告”的Skill那么无论是资深工程师还是AI助手都能通过调用这个Skill产出格式统一、内容完整的报告而不是每个人或每个AI都按自己的理解随意发挥。2. 技能生态的核心拼图MCP协议与技能描述文件要理解Skills如何工作必须认识两个关键角色MCPModel Context Protocol协议和技能描述文件如SKILL.md、AGENTS.md。它们是连接AI模型如Claude、GPT与外部工具、数据的桥梁也是技能得以定义和调用的基石。2.1 MCP协议技能调用的“普通话”你可以把MCP想象成AI世界里的“普通话”或“通用插座协议”。在没有MCP之前每个AI模型Claude、ChatGPT、Cursor等要和外部工具数据库、搜索引擎、API对话都需要定制开发一套“方言”或转接头工作量大且无法互通。MCP协议的核心价值在于标准化。它定义了一套统一的通信方式让AI模型可以通过标准接口去“发现”服务器提供了哪些工具即Skills并按照标准格式去调用它们。一个MCP服务器MCP Server就是一个能力的提供方它可以封装对数据库的查询、对搜索引擎的调用、对文件系统的操作甚至是一个复杂的业务逻辑流程。对于开发者而言你只需要按照MCP协议的标准为你想要提供的能力编写一个MCP Server。一旦完成这个Server就能被任何支持MCP协议的客户端如Claude Desktop、Cursor、Windsurf识别和调用。这就是为什么你会看到tavily-mcp搜索、brave-search-mcp搜索、sqlite-mcp数据库等各种MCP服务器项目。它们都在做同一件事把一种特定的外部能力通过MCP这个“普通话”暴露给AI使用。2.2 技能描述文件能力的“说明书”与“菜单”MCP解决了“如何调用”的问题而SKILL.md和AGENTS.md这类文件解决的则是“有什么能力可以调用”以及“这个能力是干什么的”的问题。它们是技能的元数据metadata和声明文件。SKILL.md通常用于描述一个单一、原子化的技能。它就像这个技能的“说明书”或“身份证”。一份标准的SKILL.md可能会包含以下信息技能名称Name清晰的功能标识如generate_sql_from_nl。描述Description用自然语言详细说明这个技能是做什么的解决什么问题。输入参数Input Schema定义调用这个技能需要提供哪些信息以及每个信息的类型和格式。例如一个翻译技能可能需要text字符串和target_language枚举值。输出格式Output Schema定义技能执行后会返回什么格式的数据。调用示例Examples展示几个具体的调用案例帮助AI和开发者理解如何使用。实现方式Implementation可能指向一个具体的函数、API端点、MCP工具名或者是一段提示词Prompt。AGENTS.md通常用于描述一个具备多个技能的智能体Agent或者是一个技能的集合。它更像是一份“菜单”或“服务目录”。一个AGENTS.md文件可能会列出Agent的总体介绍和能力范围。该Agent所集成的所有Skills的列表每个技能附上简要说明。如何配置和启用这个Agent。不同技能之间的协作关系。为什么需要这两个文件因为AI模型尤其是大语言模型在决定是否以及如何调用一个技能时需要清晰的指引。SKILL.md提供了足够详细的上下文让AI能准确判断“这个技能是否适合当前任务”以及“我需要提供什么参数”。而AGENTS.md则帮助用户或上层系统快速了解一个Agent的能力边界。像trae这类AI编码助手就会主动去识别项目目录下的AGENTS.md文件来加载可用的技能。3. 实战从零构建与集成一个自定义Skill理解了理论我们来看如何动手。假设我们有一个常见需求为项目自动生成CHANGELOG更新日志。我们将把这个经验封装成一个Skill并集成到Codex或Cursor中。3.1 第一步定义技能说明书SKILL.md首先我们在项目根目录或一个专门的skills目录下创建generate_changelog_skill.md文件。# 技能生成更新日志 (generate_changelog) **描述** 本技能用于根据指定的Git标签范围或最近N次提交自动分析提交历史并按照约定式提交Conventional Commits规范生成格式化的Markdown版本CHANGELOG。它能够自动识别feat、fix、docs、style等类型的提交并进行分类归组。 **输入参数** json { repo_path: { type: string, description: Git仓库的本地路径。默认为当前目录。, required: false }, from_tag: { type: string, description: 起始的Git标签不包含。例如‘v1.2.0’。, required: false }, to_tag: { type: string, description: 结束的Git标签包含。例如‘v1.3.0’。, required: false }, commit_count: { type: number, description: 如果未提供标签则分析最近N次提交。默认为20。, required: false } } **输出** 一个格式化的Markdown字符串内容为CHANGELOG。 **调用示例** 1. 比较两个标签之间的变更{from_tag: v1.2.0, to_tag: v1.3.0} 2. 生成最近10次提交的日志{commit_count: 10} **实现方式** 本技能通过调用一个本地Python脚本实现。具体命令为 bash python scripts/generate_changelog.py --from_tag from_tag --to_tag to_tag --count commit_count 这个SKILL.md文件本身不包含执行代码它只是一份清晰的“合约”告诉AI和系统“我有一个这样的能力你需要这样来调用我。”3.2 第二步实现技能背后的逻辑接下来我们需要实现真正的处理逻辑。创建scripts/generate_changelog.py#!/usr/bin/env python3 import subprocess import argparse import re from collections import defaultdict from datetime import datetime def get_commits(repo_path, from_tagNone, to_tagNone, count20): 获取指定范围内的提交信息 cmd [git, -C, repo_path, log, --oneline, --format%H|%s|%ad, --dateshort] if from_tag and to_tag: cmd.append(f{from_tag}..{to_tag}) elif count: cmd.append(f-{count}) result subprocess.run(cmd, capture_outputTrue, textTrue) if result.returncode ! 0: raise Exception(fGit命令执行失败: {result.stderr}) commits [] for line in result.stdout.strip().split(\n): if line: hash_, subject, date line.split(|, 2) commits.append({hash: hash_, subject: subject, date: date}) return commits def parse_conventional_commit(subject): 解析约定式提交消息 pattern r^(\w)(?:\(([^)])\))?: (.)$ match re.match(pattern, subject) if match: type_, scope, description match.groups() return type_.lower(), scope, description return None, None, subject def generate_markdown(commits): 生成Markdown格式的CHANGELOG categorized defaultdict(list) for commit in commits: type_, scope, desc parse_conventional_commit(commit[subject]) key type_ if type_ in [feat, fix, docs, style, refactor, test, chore] else other categorized[key].append(f- {desc} ({commit[hash][:7]})) # 定义输出顺序和标题 order [feat, fix, docs, style, refactor, test, chore, other] titles { feat: ✨ 新功能, fix: 修复, docs: 文档, style: 样式, refactor: ♻️ 重构, test: ✅ 测试, chore: 维护, other: 其他变更 } output [f# CHANGELOG\n\n*生成时间: {datetime.now().strftime(%Y-%m-%d %H:%M)}*\n] for key in order: if key in categorized and categorized[key]: output.append(f\n## {titles[key]}\n) output.extend(categorized[key]) return \n.join(output) if __name__ __main__: parser argparse.ArgumentParser(description生成CHANGELOG) parser.add_argument(--repo_path, default.) parser.add_argument(--from_tag) parser.add_argument(--to_tag) parser.add_argument(--count, typeint, default20) args parser.parse_args() commits get_commits(args.repo_path, args.from_tag, args.to_tag, args.count) changelog generate_markdown(commits) print(changelog)这个脚本完成了实际的Git历史分析和格式化工作。它就是我们Skill的“发动机”。3.3 第三步通过MCP服务器暴露技能要让Codex、Claude这类AI客户端能直接调用这个技能我们需要将它包装成一个MCP服务器。这里我们使用一个简单的Node.js示例利用modelcontextprotocol/sdk。首先安装依赖npm install modelcontextprotocol/sdk。然后创建mcp-server.jsconst { Server } require(modelcontextprotocol/sdk/server/index.js); const { StdioServerTransport } require(modelcontextprotocol/sdk/server/stdio.js); const { spawn } require(child_process); const path require(path); const server new Server( { name: changelog-generator, version: 0.1.0, }, { capabilities: { tools: {}, }, } ); // 定义我们的“生成CHANGELOG”工具 server.setRequestHandler(tools/list, async () { return { tools: [ { name: generate_changelog, description: 根据Git标签或提交数量生成格式化的更新日志。, inputSchema: { type: object, properties: { repo_path: { type: string, description: Git仓库路径可选 }, from_tag: { type: string, description: 起始标签可选 }, to_tag: { type: string, description: 结束标签可选 }, commit_count: { type: number, description: 分析的提交数量可选 }, }, }, }, ], }; }); // 处理工具调用 server.setRequestHandler(tools/call, async (request) { if (request.params.name ! generate_changelog) { throw new Error(未知工具: ${request.params.name}); } const args request.params.arguments || {}; const cliArgs []; if (args.from_tag) cliArgs.push(--from_tag, args.from_tag); if (args.to_tag) cliArgs.push(--to_tag, args.to_tag); if (args.commit_count) cliArgs.push(--count, args.commit_count.toString()); // repo_path 在Python脚本中通过 -C 处理这里我们传给脚本的--repo_path参数 if (args.repo_path) cliArgs.push(--repo_path, args.repo_path); const scriptPath path.join(__dirname, scripts, generate_changelog.py); return new Promise((resolve, reject) { const pythonProcess spawn(python, [scriptPath, ...cliArgs], { stdio: [pipe, pipe, pipe] }); let stdout ; let stderr ; pythonProcess.stdout.on(data, (data) { stdout data.toString(); }); pythonProcess.stderr.on(data, (data) { stderr data.toString(); }); pythonProcess.on(close, (code) { if (code 0) { resolve({ content: [{ type: text, text: stdout }], }); } else { reject(new Error(脚本执行失败 (${code}): ${stderr})); } }); }); }); async function main() { const transport new StdioServerTransport(); await server.connect(transport); console.error(MCP 变更日志服务器已启动); } main().catch((error) { console.error(服务器错误:, error); process.exit(1); });这个MCP服务器启动后就会通过标准输入输出stdio与AI客户端通信。当客户端如Codex查询工具列表时它会返回generate_changelog这个工具的定义当客户端调用这个工具时它会启动我们之前写的Python脚本并返回结果。3.4 第四步在AI客户端中配置与调用以Claude Desktop为例你需要编辑其配置文件通常在~/Library/Application Support/Claude/claude_desktop_config.jsonon macOS。{ mcpServers: { changelog-generator: { command: node, args: [/ABSOLUTE/PATH/TO/YOUR/mcp-server.js] } } }配置完成后重启Claude Desktop。当你在对话中提及需要生成更新日志时Claude就能“看到”并建议使用这个generate_changelog工具你只需授权它调用即可。对于Cursor或Windsurf配置方式类似通常也是在设置中找到MCP Servers配置项添加你的服务器命令路径。注意这是最基础的MCP服务器示例。在生产环境中你需要考虑错误处理、安全性如路径注入、性能以及更复杂的参数验证。社区中已有许多优秀的框架如用Python的mcp库可以简化开发。4. 技能开发与集成的核心避坑指南在实际操作中把Skill跑通只是第一步。要让技能真正好用、可靠以下几个坑点必须提前了解。4.1 技能描述的清晰度直接决定调用成功率AI模型完全依赖SKILL.md或MCP工具定义中的description和inputSchema来理解你的技能。模糊的描述会导致误用或不被调用。反面例子description: “处理数据。”inputSchema缺失或过于简单。正面例子description: “根据用户提供的自然语言描述生成符合MySQL 8.0语法的SELECT查询语句。描述中应包含表名、字段和筛选条件。”并在inputSchema中明确定义query_description字段为必填字符串。实操心得在编写描述时把自己想象成在给一个非常聪明但对你领域一无所知的新人写任务清单。要具体、无歧义并包含关键约束条件。4.2 MCP服务器实现的稳定性与错误处理你的MCP服务器必须非常健壮。AI客户端可能会传入意外的参数、空值或者服务器依赖的外部服务可能不可用。参数验证必须在服务器端对输入参数进行严格的类型和有效性校验不能完全依赖客户端的Schema提示。全面的错误处理使用try-catch包裹核心逻辑并将错误信息以结构化的方式返回给客户端。MCP协议允许返回错误信息这能帮助AI理解问题所在而不是得到一个崩溃的无响应。超时控制为长时间运行的任务设置超时避免阻塞AI客户端的会话。日志记录服务器应记录详细的日志便于调试技能为何没有被成功调用或调用失败。4.3 技能粒度的权衡原子化与复合技能这是技能设计中的核心哲学问题。技能应该多“细”原子化技能一个技能只做一件事并且做到最好。例如validate_email验证邮箱格式、fetch_user_by_id根据ID查用户。优点是复用性极高易于组合和测试。复合技能一个技能封装一个完整的业务流程。例如onboard_new_user新用户 onboarding包含创建账号、发送欢迎邮件、初始化配置等。优点是对于固定流程非常高效AI一次调用即可完成复杂任务。我的经验是优先设计原子化技能。复合技能可以通过让AI按顺序调用多个原子化技能来实现。这更灵活也更容易维护。当某个子步骤如发送邮件的逻辑需要修改时你只需更新send_email这个原子技能所有使用它的复合流程都会自动受益。只有当某个流程极其固定、性能要求极高且永远不会变化时才考虑封装为复合技能。4.4 技能的管理与发现AGENTS.md的最佳实践当项目中的技能越来越多时一个清晰的AGENTS.md文件至关重要。它不应该只是简单的列表。一个优秀的AGENTS.md应该包含概述本Agent或本技能库的主要目标和适用场景。技能目录以表格形式列出所有技能包含名称、简短描述、输入/输出示例和状态如稳定/测试中。使用场景示例给出2-3个典型的任务描述并展示Agent如何组合不同技能来解决它。配置要求运行这些技能需要什么环境、依赖或API密钥。更新日志记录技能的添加、更新和废弃情况。这不仅能帮助人类开发者快速上手也能为更高级的“Agent编排器”提供元信息实现技能的自动规划和调用。5. 技能生态的现状与未来展望观察搜索类 mcp 服务器、cursor使用mcp、skill开发等热词可以看出当前生态的焦点集中在两个方面丰富的基础能力工具化和开发体验的优化。基础能力工具化搜索Tavily, Brave、数据库操作SQLite、浏览器自动化Playwright、设计工具对接Figma等都被快速封装成MCP服务器。这是生态的“基础设施”建设阶段。开发体验优化大家关心如何在Cursor、Codex中安装和禁用Skill如何配置MCP连接。这说明工具链正在成熟从“能否实现”过渡到“是否好用”。关于figma mcp 还原度很低的原因是什么这类问题正揭示了当前阶段的挑战保真度与复杂性。将复杂的图形设计操作完全无损地通过文本接口还原本身就极其困难。这涉及到动作的抽象层级问题。一个“将按钮颜色改为蓝色”的指令在Figma中可能对应多种实现路径修改样式层、覆盖颜色变量等。目前的MCP技能可能只实现了最直接、最通用的路径无法覆盖所有边界情况。解决之道在于技能设计的精细化可能需要拆分成多个更细粒度的技能如get_component_styles、update_fill_color并由AI进行多次调用和状态判断。展望未来我认为有几个关键趋势技能市场与分发会出现类似“Skill商店”的平台开发者可以发布和共享技能使用者可以一键安装。mcp市场这个词已初现端倪。技能的动态组合与编排AI不仅能调用单个技能还能根据复杂目标自动规划、编排一系列技能的调用顺序和参数传递。技能的版本化与测试像管理代码一样管理技能具备版本控制、单元测试和集成测试能力确保技能的可靠迭代。领域特定技能库DSL的崛起在金融、法律、医疗等垂直领域会出现高度专业化、术语准确的技能库极大降低领域AI应用的门槛。把经验变成可调用的Agent Skills本质上是在构建人机协作的新一代“标准作业程序”。它让AI从需要详尽指令的“实习生”变成了一个可以自主调用标准化工具包的“熟练工”。这个过程虽然仍有不少工程挑战但无疑是当前让AI能力真正落地、融入工作流的最务实路径。开始动手封装你的第一个Skill吧从自动化一个你每天都要重复三次的小任务开始你会立刻感受到它带来的改变。
)
