第1章 1-2 Skill 基础概念与工程定义

Skill基础概念与工程定义AgentSkills多平台应用实战·第1章1-2节Contents目录从核心概念到工程实践，系统掌握Skill的完整知识体系。01Skill核心概念与组成结构02SKILL.md工程化定义规范03实战案例与常见问题排查04课程总结与课后实操任务CHAPTER01Skill核心概念与组成结构系统理解Skill的定义、三层架构与生命周期ArchitectureSkill的工程定义与三层架构Skill是一个以SKILL.md为核心的标准化文件夹，通过"指令文件+脚本资源+参考资料"三层架构，将专业知识与工作流封装为Agent可按需加载的能力扩展包。开发者IDE中的项目文件夹目录结构CORE·指令层SKILL.md指令文件必填核心层，包含名称、描述等元数据及完整操作指令，决定Skill何时被触发以及如何执行ACTION·脚本层Scripts脚本资源提供可执行代码，让Agent从纯文本交互升级为具备文件操作、API调用等实际行动能力KNOWLEDGE·参考层References与Assets提供领域知识文档和输出模板，确保Agent在特定任务上的输出质量远超通用提示词ArchitectureSkillvsPluginvsTool概念辨析Skill、Plugin、Tool三者构成从底层函数到高层能力的递进关系。Tool是原子化的函数调用，Plugin是标准化工具封装，而Skill是融合指令、脚本与领域知识的按需加载能力单元。Tool工具层原子化函数调用，如"读文件""发HTTP请求"，粒度最细但缺乏业务语义，需要Agent自行编排调用链。AtomicFunctionsPlugin插件层多个Tool的标准化封装，通常静态加载且始终占用上下文空间，接口规范但缺少操作指导和领域知识。StandardizedBundleSkill技能层融合指令、脚本与领域知识的按需加载单元，Agent仅在匹配时加载完整内容，兼顾智能识别与专业执行。On-DemandIntelligenceLifecycleSkill生命周期：从创建到淘汰Skill的完整生命周期涵盖创建、注册、调用、迭代四个阶段，形成从开发到退役的闭环管理。理解这一生命周期是实施版本管理、灰度更新和组织级Skill治理的认知基础。01创建开发者编写SKILL.md指令文件与配套脚本资源，定义触发条件、输入输出接口和专家人设，形成完整的Skill文件夹02注册Skill文件夹放入Agent可扫描目录，启动时Agent自动发现并仅加载名称与描述到索引，实现轻量化注册03调用用户意图匹配触发后，Agent动态加载完整SKILL.md到上下文中，按指令执行脚本并返回结构化结果04迭代与淘汰基于执行反馈持续优化规则与示例，版本更新后旧版归档，过时Skill从注册表中移除并标记淘汰版本管理与代码迭代工作场景Chapter02SKILL.md工程化定义规范掌握指令文件编写、参数接口设计与版本管理的工程实践SkillArchitectureSKILL.md文件结构规范SKILL.md是Skill的核心指令文件，遵循"元数据定义+操作指令+Few-Shot示例"三段式结构。编写时需坚持原子性原则（单一职责）、专家人设设定和示例驱动，让Agent在最少的上下文消耗下获得最精准的执行指导。元数据区必填name和description，description使用"当用户需要X时使用此技能"句式，精准覆盖触发场景关键词以提升意图匹配率。name+description指令区用Markdown格式定义操作步骤、约束条件和输出规范，设定专家人设引导Agent以专业视角执行任务。专家人设Few-Shot示例区提供2–3个覆盖典型场景与边界情况的输入输出案例，实例驱动效果远优于纯文字规则描述。2–3案例InterfaceDesign参数接口设计原则Skill的参数接口遵循"最小必要、类型明确、结构可预期"三大原则，通过JSONSchema规范化定义输入输出，既降低Agent的上下文消耗，又确保每次调用返回结构化、可解析的结果。接口定义核心要素要素字段类型说明输入参数sql_querystring（必填）SQL查询语句，Skill核心输入输入参数max_rowsinteger（默认100）最大返回行数，防止结果集过大输入参数timeout_msinteger（默认5000）执行超时时间，保障系统稳定性输出结构statusstring执行状态：success/error输出结构dataarray[object]查询结果数据，标准JSON数组输出结构error_msgstring|null错误信息，仅status=error时返回通过JSONSchema精确定义每个参数的类型、必填性和默认值，确保Agent调用时输入合规、输出可预期SKILLENGINEERING编写高质量Skill的五大法则高质量Skill的编写遵循原子性、Few-Shot、人设、接口设计和迭代优化五大法则，构成Skill工程化开发的完整方法论。01原子性SINGLERESPONSIBILITY坚持单一职责，一个Skill只解决一类问题，像积木一样小而美，复杂任务通过多Skill编排完成02Few-Shot示例EXAMPLEDRIVENFew-Shot示例是最关键法则，不要只写规则说明，直接给2-3个覆盖典型和边界场景的输入输出案例03专家人设PERSONA设定专家人设（如"资深数据分析师"），引导Agent以专业视角和术语执行任务，提升输出质量04接口设计INTERFACE用JSON/Markdown定义清晰的输入输出格式，让调用方有明确预期，Agent输出结构化可解析05迭代优化ITERATE将每次BadCase转化为新规则补充到Skill中，建立"发现问题→修复规则→验证效果"的持续改进闭环CHAPTER03实战案例与常见问题排查通过代码审查助手案例走通全流程，梳理开发调试中的典型陷阱CASESTUDY实战案例：代码审查助手Skill代码审查助手Skill是一个典型的生产级Skill示例，通过完整的三层架构（SKILL.md+检查脚本+规范文档），将团队的代码审查SOP封装为Agent可按需调用的标准化能力，实现从人工逐行审查到AI自动审查的效率跃迁。开发者代码审查协作场景01SKILL.md接口规范—设定「资深代码审查员」专家人设，定义接受diff文本输入、输出含严重等级分类的Markdown审查报告的完整接口规范。02自动检查脚本—check_style.py封装代码风格自动检查逻辑，覆盖命名规范、异常处理、安全漏洞等10项核心检查点。03规范与模板资产—references目录含编码规范文档，assets目录提供标准化报告模板，确保输出格式统一且符合团队工程标准。04Few-Shot质量保障—提供3个示例覆盖命名不规范、异常未捕获、SQL注入风险三种典型场景，确保Agent审查质量稳定。DEBUGGINGGUIDE常见问题排查：Skill开发典型陷阱Skill开发初期最常见的四类问题集中在加载失败、多Skill冲突、输出不稳定和权限报错。掌握这些典型陷阱的排查方法，能显著缩短从'能跑'到'好用'的调试周期。加载与触发Skill未被识别description字段过于模糊，需用更精确的场景关键词和同义词覆盖，确保意图匹配准确。description加载与触发多Skill冲突通过优先级配置或更细粒度的触发条件区分相近Skill，避免Agent摇摆不定。优先级执行与输出输出格式不稳定Few-Shot示例不够充分或Schema定义模糊，补充2-3个覆盖边界情况的输入输出示例可显著改善。Few-Shot执行与输出权限报错检查沙箱环境的文件系统权限和网络白名单，确保所需资源路径已在配置中显式声明并授权。白名单CHAPTER04课程总结与课后实操任务回顾核心知识点，通过实操任务巩固Skill工程化定义能力Summary本节要点回顾本节系统建立了Skill的工程化认知框架：从三层架构定义到SKILL.md编写规范，从五大质量法则到完整生命周期管理，为后续多平台Skill搭建实战奠定坚实的理论与工程基础。01核心认知Skill是以SKILL.md为核心的标准化文件夹，通过"指令文件+脚本资源+参考资料"三层架构封装领域专业能力，实现知识的结构化沉淀与复用。02工程规范SKILL.md遵循"元数据+操作指令+Few-Shot示例"三段式结构，参数接口采用JSONSchema规范化定义，确保跨平台兼容与可维护性。03质量法则原子性、Few-Shot驱动、专家人设、接口设计、迭代优化五条原则构成高质量Skill的完整方法论，指导开发者持续打磨交互体验。04下节预告1-3节将深入Skill运行环境与核心原理，讲解意图匹配、沙箱执行与多平台差异实现，连接理论认知与工程实践。Hands-onPractice课后实操任务：Git提交信息生成器Skill通过从零创建一个"Git提交信息生成器"Skill，实践SKILL.md编写、接口定义和Few-Shot示例设计的完整流程，将本节所学的工程化定义规范转化为可运行的实际产出。Steps任务步骤01创建commit-message-generator目录，包含SKILL.md和scripts/generate.py，Agent加载后可根据gitdiff自动生成ConventionalCommits格式提交信息02在SKILL.md中定义输入接口（gitdiff文本）和输出格式（type(scope):description的JSON结构），并提供至少2个Few-Shot示例03使用一段真实的gitdiff内容进行本地测试，验证Agent调用Skill后输出的提交