QDKT-Skill的概念和原理+Skill开发实践

一、核心概念认知1. 什么是SkillsSkills技能是让AI Agent具备自主决策能力的AI产品形态能够更可控地复用最佳实践的工程策略是Agent使用工具能力的延伸与集大成者并非简单的工具进化。简单来说Skills是一套围绕文件系统终端系统打造的体系能让Agent按需读取文档、运行脚本、调用资料实现更高效的任务处理同时大幅节省TOKEN消耗让Agent使用工具更自如。2. Skills与MCP、Function Calling的关系Skills和Function Calling、MCP属于同类让Agent调用工具的策略但解决了前两者的核心痛点三者的核心关联为底层逻辑相似本质都是让Agent接收到任务后调用对应的工具/程序完成任务最终返回结果Skills是集大成者凝练了Function Calling、MCP以及工作流Workflow的所有流程同时优化了前两者的致命问题是更优的Agent工具调用方案。3. Skills的核心价值大幅减少TOKEN消耗仅通过简短的描述信息让Agent识别技能无需塞入大量复杂参数即使配置上百个技能TOKEN消耗量也远低于MCP和Function Calling按需加载/运行Agent仅在需要时才读取技能的详细内容、运行对应的脚本避免了所有工具信息一次性塞入上下文的冗余问题使用场景更灵活不仅能运行脚本/程序还能让Agent阅读说明文档、调用各类资料如PPT模板、图片、手册复用各类最佳实践兼容性强可适配各类支持Agent的工具如Cursor、Claude Code且开发逻辑与传统AI产品/工作流开发相通易上手。二、Skills的发展背景为什么会出现SkillsSkills的出现是为了解决Function Calling和MCP在实际使用中的核心痛点我们先了解前两者的问题就能理解Skills诞生的必要性1. Function Calling的核心痛点Function Calling从2023年GPT4推出后成为主流但存在上下文冗余、TOKEN消耗大的问题调用工具前需要编写大量参数结构schema即使某个工具不用也需要将其schema塞入上下文工具数量越多塞入的参数信息越多导致Agent运行卡顿、响应变慢。2. MCP的核心痛点MCP的初衷是统一工具调用的规范解决Function Calling各自开发、标准混乱的问题但完全继承了Function Calling的痛点还新增了新问题依旧存在大量上下文拥堵、TOKEN消耗大的问题多个MCP叠加会让Agent运行极慢如安装某MCP后Agent响应延迟超10秒因塞入5万TOKEN的上下文虽有基础协议但实际开发无统一标准各类非标准MCP层出不穷属于“外挂程序”用户可随意在客户端安装大量MCP叠加会让上下文冗余问题雪上加霜。3. 核心需求催生Skills随着工具和MCP的增多行业出现了核心需求能不能让Agent按需加载/运行工具用哪个加载哪个仅传递少量关键信息不用时不占用上下文Skills正是为满足这一需求而生通过“摘要识别按需读取终端运行”的逻辑彻底解决了前两者的核心痛点。三、Skills的核心运行原理零基础学员可通过“传统工具调用流程对比”“生活化类比” 理解Skills的运行原理核心是“先看摘要再按需读详情、跑程序”。1. 传统Function Calling/MCP的运行流程用户向Agent下发任务所有工具/MCP的完整参数、schema被一次性塞入Agent上下文Agent从海量参数中识别需要的工具生成调用参数内置程序Function Calling/客户端MCP运行工具将结果返回AgentAgent循环上述步骤完成任务后交付结果。核心问题无论工具是否使用全部信息都塞入上下文冗余且耗TOKEN。2. Skills的核心运行流程技能部署将每个Skills封装成独立文件夹放入Agent的指定目录每个文件夹内有技能说明文档[skill.md](skill.md)、脚本/程序、资料等摘要加载Agent启动时仅加载所有Skills的名称name简短描述description类似论文标题摘要不加载详细内容占用极少TOKEN任务接收与技能匹配用户下发任务后Agent根据任务需求从已加载的技能摘要中匹配对应的Skills按需读取详情Agent打开匹配成功的Skills的[skill.md](skill.md)读取详细使用说明执行操作根据说明Agent通过终端运行对应的脚本/程序、读取相关资料/文档将结果返回自身循环完成任务Agent重复“匹配-读取-执行”步骤完成所有操作后交付结果。3. 生活化类比实习生工作把Agent比作公司实习生Skills就是公司的各类工作手册工具脚本资料包实习生入职后先看公司的手册/资料包目录简介对应Skills的namedescription知道公司有什么资源接到工作任务后根据任务需求从目录中找到对应的手册/资料包对应匹配Skills打开手册看详细操作步骤对应读取skill.md详情按步骤使用工具/脚本/资料完成工作对应终端运行程序工作完成后向领导交付结果对应Agent向用户返回结果。4. Skills的灵活拓展无脚本也能用Skills并非必须搭配脚本/程序仅靠说明文档也能实现价值比如开发一个“写小红书笔记”的Skills无需编写运行脚本仅在skill.md中写清小红书笔记的写作框架、技巧、爆款公式Agent匹配到该技能后读取说明文档直接按照文档中的方法生成小红书笔记实现最佳实践的复用。四、Skills的基础结构一个技能的标准形态Skills的核心形态是独立文件夹一个文件夹对应一个技能Agent仅识别文件夹内的指定文件结构简单且有明确规范零基础学员按规范搭建即可核心文件为[skill.md](skill.md)其余为可选拓展内容。1. 基础结构总览一个标准的Skills文件夹包含以下内容其中skill.md为必须项其余脚本、文档、资料文件夹为可选可根据技能需求增减Plain Text[技能文件夹名]├─ skill.md 核心技能说明文档Agent唯一必读文件├─ scripts/ 可选存放Python/Nodejs等脚本、终端命令行程序├─ docs/ 可选存放相关说明文档如PDF、Markdown格式的手册└─ assets/ 可选存放各类资料如PPT模板、图片、海报底图等2. 核心文件[skill.md](skill.md)skill.md是Markdown格式的文档是Agent识别和使用Skills的唯一核心包含元数据和技能详细说明两部分有明确的编写规范。1元数据Agent必加载的核心信息元数据采用YML结构是Agent启动时唯一加载的内容必须包含name和description两个字段缺一不可name技能的正式名称Agent唯一识别的技能标识文件夹名无意义Agent不读取description技能的简短描述100字左右即可讲清技能的用途、适用场景让Agent能快速匹配任务。2技能详细说明Agent按需读取的内容元数据下方为技能的详细说明无固定格式核心讲清Agent使用该技能的具体步骤比如什么时候需要运行scripts/文件夹下的某个脚本哪个任务需要读取docs/文件夹下的某份文档调用assets/文件夹下资料的具体场景和方法。3. 命名规范零基础必遵守为避免Agent在终端运行时出现指令错误所有文件夹、文件的命名必须遵守以下规范这是零基础开发的基础要求禁止使用中文、空格、特殊符号如、#、$优先使用英文多个单词之间用连字符-连接如write-xiaohongshu-note脚本/文档/资料的命名与[skill.md](skill.md)中的说明严格对应如[skill.md](skill.md)中写“运行[get-feishu-id.py](get-feishu-id.py)”则scripts文件夹下必须有该文件。4. Agent的技能读取路径以Claude Code为例Skills文件夹需要放在根目录/.claude-code/claude/skills/下Agent启动时会自动扫描该目录下的所有技能文件夹加载元数据Cursor的Skills功能在子Agent选项下默认自带Skill Creator无需手动配置路径直接创建/放入技能文件夹即可。五、Skills开发完整实操流程Skills的开发难度极低核心是把“最佳实践”讲清楚借助AI官方提供的Skill Creator技能创建器零基础学员也能快速开发开发工具优先选择Cursor自带Skill Creator操作更简单也可使用Claude Code。开发前置准备安装最新版Cursor/Claude Code确保工具支持Skills功能Cursor非超老版本均自带确认工具中已加载Skill CreatorCursor在子Agent选项下可找到若无则从官方文档下载后放入Skills目录准备好技能相关的背景信息如需要调用API则准备API文档、需要运行脚本则明确脚本功能。正式开发步骤共4步步骤1明确开发需求梳理核心信息开发前先想清要开发的技能是做什么的并梳理出三大核心信息触发条件、作业流程、能力边界这是向AI描述需求的基础核心是把“最佳实践”梳理成清晰的SOP标准作业流程。比如开发“将文档保存到飞书知识库”的技能需先梳理什么时候用这个技能触发条件保存文档需要的步骤授权→转Markdown→查知识库ID→创建/写入文档作业流程这个技能能做什么、不能做什么能力边界如仅支持Markdown格式不支持大文件。步骤2向AISkill Creator描述开发需求在Cursor/Claude Code中打开Skill Creator用自然语言把梳理好的核心信息背景信息清晰告知AI这一步类似“写产品需求PRD”信息越详细AI生成的技能越精准。描述要求明确讲清三大核心信息触发条件、作业流程、能力边界若涉及API调用、脚本运行需将API文档、脚本功能、参数要求作为附件/文本发给AI讲清技能的预期输出如最终生成飞书知识库的文档链接、返回运行成功/失败的提示。示例描述开发一个“将文档保存到飞书知识库”的技能触发条件当用户需要将产出物保存到飞书知识库时使用。作业流程1. 验证飞书API的授权信息2. 将用户提供的文档转换为Markdown格式3. 调用飞书API查询目标知识库ID4. 若知识库中无对应文档则创建有则追加内容5. 将文档内容分块写入飞书知识库。能力边界仅支持Markdown/TXT格式的文档不支持大于10M的文件需要用户提供飞书API的key和secret存放在scripts文件夹下的config.py中。背景信息飞书知识库API的POST请求地址为xxx请求参数为xxx附API文档。步骤3AI自动生成Skills文件夹Skill Creator接收到需求后会自动完成以下工作零基础学员无需手动编写代码/文档创建独立的Skills文件夹命名符合规范编写skill.md文件包含标准YML元数据和详细的技能说明根据作业流程在scripts文件夹下生成对应的Python/Nodejs脚本如API调用脚本、格式转换脚本若有需要生成docs文件夹写入技能的使用说明/注意事项。步骤4验证技能调试优化AI生成技能后将技能文件夹放入Agent的指定Skills目录通过实际任务测试技能是否能正常运行并根据测试结果调试优化简单测试下发匹配技能的任务看Agent是否能成功匹配、读取技能、运行脚本问题调试若运行失败检查skill.md中的步骤是否清晰、脚本参数是否正确、文件命名是否符合规范优化完善补充能力边界的约束如增加验证策略、终止条件让技能更稳定。六、开发Skills的三大核心关键信息零基础必掌握向AI描述开发需求时三大核心信息是重中之重信息描述不清会导致技能无法正常使用如同写PRD时漏了需求开发出的产品会有各种问题。这三大信息也是零基础学员需要反复练习的核心内容。1. 触发条件让Agent“知道什么时候用这个技能”触发条件是Agent匹配技能的依据必须讲清具体的使用场景分为三类可单独使用也可组合使用描述要精准避免Agent误匹配/不匹配1基于用户需求的触发格式当用户需要【做某件事】时使用该技能示例当用户需要将文档保存到飞书知识库时使用该技能当用户需要写小红书笔记时使用该技能。2基于任务目标的触发格式当完成【某任务目标】需要【做某件事】时使用该技能示例当完成“生成产品运营报告”需要将报告保存为飞书在线文档时使用该技能。3基于Agent能力边界的触发格式当Agent无法【做某件事】/需要【获取某类信息】时使用该技能示例当Agent无法获取飞书知识库的最新文档ID时使用该技能当Agent需要调用飞书API时使用该技能。零基础小技巧description是Agent匹配技能的核心开发完成后可优化description把核心触发条件写进去description的优化未来会成为Skills的“SEO”让你的技能在众多同类技能中被优先匹配。2. 作业流程让Agent“知道一步一步怎么做”作业流程就是技能的SOP标准作业流程需要把Agent完成任务的步骤梳理得清晰、具体、有顺序核心是做好分工——明确哪些步骤由AIAgent完成哪些由脚本/程序完成哪些需要用户提供信息这是技能能正常运行的关键。1作业流程的编写要求按时间顺序编写步骤用“1、2、3、4”标注不跳步每个步骤讲清做什么、由谁做、输入什么、输出什么若需要用户提供信息明确讲清需要什么信息、信息放在哪里如API key放在scripts/config.py中。2核心分工原则零基础必记把步骤分为三类避免职责混乱AIAgent完成无需运行程序仅靠大模型能力即可完成的步骤如写文案、分析内容、生成Markdown格式脚本/程序完成需要调用API、处理数据、执行终端命令的步骤如查询飞书知识库ID、格式转换、文件上传用户提供需要用户手动输入的敏感信息/个性化信息如API key、知识库名称、目标文件路径。示例“写小红书笔记并生成封面”的作业流程Agent接收用户的笔记主题生成符合小红书风格的笔记文案AI完成输入笔记主题输出小红书文案Agent调用scripts文件夹下的text-to-img.py脚本将文案转换为封面图片脚本完成输入小红书文案输出封面图片Agent将笔记文案和封面图片整合返回给用户AI完成输入文案图片输出完整小红书笔记。3. 能力边界让Agent“知道能做什么、不能做什么”能力边界是为了约束Agent的行为让技能更稳定避免Agent为了完成任务“乱操作”如乱改脚本、干不完活就跳过核心是给AI“留出路”讲清预期输出、验证策略、终止条件、备选方案这是零基础学员开发技能时最容易忽略但最关键的一步。1预期输出明确“技能最终要产出什么”讲清技能完成后必须输出的内容避免Agent干到一半就停止描述要具体不能模糊。示例将文档保存到飞书知识库后必须输出飞书知识库的文档链接运行成功的提示生成小红书笔记后必须输出完整的文案高清封面图片分辨率1080*1080。2验证策略让Agent“自己检查做得好不好”为关键步骤添加验证要求让Agent完成后自行验证结果是否符合要求不符合则重新操作避免产出无效结果可选配根据技能重要性决定。示例生成小红书封面图片后Agent自行识别图片检查文字是否完整、无溢出、分辨率是否为1080*1080不符合则重新运行脚本生成。3终止条件让Agent“知道什么时候该停手”讲清技能无法继续运行的场景让Agent在这些场景下直接终止操作不要强行尝试更不要乱改脚本/代码。核心禁止项明确告诉Agent不要修改技能文件夹中的任何脚本/代码避免AI因错误修改导致技能后续无法使用。示例若用户未提供飞书API key终止技能运行向用户提示“请提供飞书API key后再使用该技能”若脚本运行报错如API调用失败终止运行提示报错原因不修改scripts文件夹下的任何代码。4备选方案让Agent“知道做失败了该怎么办”讲清技能运行失败后的替代方案避免Agent因技能失败导致整个任务无法完成核心是“不用这个技能也能把任务做完”。示例若调用飞书API保存文档失败Agent将转换后的Markdown文档直接返回给用户提示“飞书保存失败已为你生成Markdown格式文档请手动上传”。七、Skills的最佳实践与零基础学习注意事项1. 最佳实践套娃式技能——用Skill Creator创建技能AnthropicClaude官方提供了Skill Creator技能这是最经典的“套娃式”最佳实践因为Skills是“最佳实践的标准化封装”所以可以把“创建Skills的流程”也封装成一个Skills即Skill Creator所有支持Agent的工具都能使用Skill Creator让AI帮我们开发Skills实现技能的自动化创建这也是零基础学员开发技能的核心方式。2. 零基础学习注意事项先练SOP梳理再练开发Skills的核心是“复用最佳实践”零基础学员先学会把日常工作/任务梳理成清晰的SOP再尝试将SOP封装成技能比直接学代码/脚本更重要严格遵守命名规范中文、空格、特殊符号是终端运行的“大忌”只要遵守命名规范能避免80%的运行错误信息描述要详细向AI描述需求时不要省略背景信息如API文档、脚本功能AI不知道的信息一定要明确告知避免生成的技能有漏洞多测试、多调试零基础开发的第一个技能大概率会有问题通过实际任务测试根据报错原因调试优化是最快的学习方式不要贪多从小技能开始先开发简单的无脚本技能如“写小红书笔记”“生成周报框架”再开发带脚本/API调用的复杂技能循序渐进。八、零基础开发入门练习建议为帮助零基础学员快速上手推荐3个入门练习从易到难逐步掌握Skills开发无脚本技能开发“生成周报框架”的Skills仅在skill.md中写清周报的核心模块工作完成、问题总结、下周计划让Agent匹配后直接生成框架简单脚本技能开发“将TXT文件转换为Markdown”的Skills让AI生成格式转换脚本梳理简单的作业流程API调用技能开发“将内容保存到石墨文档”的Skills准备石墨文档API文档梳理触发条件、作业流程、能力边界让AI生成完整技能。所有练习完成后可在Cursor/Claude Code中实际测试遇到问题可根据报错信息调试也可参考官方Skill Creator的文档优化。