AI实践(10)Skills技能Author: Once Day Date: 2026年3月18日一位热衷于Linux学习和开发的菜鸟试图谱写一场冒险之旅也许终点只是一场白日梦…漫漫长路有人对你微笑过嘛…全系列文章可参考专栏: AI实践成长_Once-Day的博客-CSDN博客参考文章:Prompt Engineering Guide提示词技巧 – Claude 中文 - Claude AI 开发技术社区Documentation - Claude API DocsOpenAI for developersSkills技能 – Claude 中文 - Claude AI 开发技术社区模式库把工程经验沉淀为 Skills – Claude 中文 - Claude AI 开发技术社区持续学习把会话复盘沉淀成 Skills – Claude 中文 - Claude AI 开发技术社区Agent Skills - Claude API DocsEquipping agents for the real world with Agent Skills \ Anthropic | Claude技能编写最佳实践 - Claude API 文档 — Skill authoring best practices - Claude APIDocsSkills | OpenAI APISpecification - Agent SkillsClaude Skills 完全指南从入门到精通 - 知乎火爆全网的Skills看这一篇就够了大家好我是势必要把Skills咬烂嚼碎的码哥 Skills 最近火得一塌糊涂 - 掘金AI那些趣事系列117从入门到实战Claude Skills 彻底指南 —— 让 AI 像专业助手一样精准干活-CSDN博客文章目录AI实践(10)Skills技能1. Skills介绍2. Skills公开仓库3. Skills工作原理4. Skills结构5. Skills最佳实践5.1 保持精简5.2 设定合理的自由度5.3 跨模型测试5.4 控制文件规模与引用深度5.5 使用工作流拆解复杂任务6. Skills评估与迭代6.1 优先构建评估体系6.2 评估驱动开发6.3 借助 Claude 迭代开发7. Skills代码执行8. Skills实践8.1 目录结构8.2 SKILL.md 编写8.3 检查清单8.4 辅助脚本8.5 使用效果1. Skills介绍Agent Skills是一种模块化的能力扩展机制用于增强Claude等大语言模型在特定领域的表现。每个Skill将指令、元数据以及可选资源如脚本、模板等打包为一个独立单元当对话场景与其匹配时模型能够自动加载并使用对应的Skill。这一机制的核心目标是将通用型 AI 代理转变为具备专业领域知识的专家型助手。在传统的交互模式中用户往往需要在每次对话开始时反复提供相同的背景信息、工作流程和约束条件。例如一个团队若希望Claude始终遵循特定的代码审查规范就不得不在每次新会话中重新描述这些规范。这种方式不仅效率低下而且容易因遗漏或表述差异导致输出质量不稳定。Skills的出现正是为了解决这一痛点——将领域知识固化为可复用的文件级资源从根本上消除重复输入的负担。Skills与普通Prompt之间存在本质区别。Prompt是会话级别的指令作用于单次对话适合处理一次性、临时性的任务而Skills是文件系统级别的持久化资源按需加载能够跨会话生效。可以将两者的关系类比为函数调用中的内联代码与库函数——前者灵活但不可复用后者封装良好且可在多处调用。特性PromptSkill作用范围单次会话跨会话持久化加载方式手动输入按需自动加载可复用性低高维护成本每次重写一次创建持续使用适用场景临时任务领域专业化从实际收益来看Skills机制提供了三个方面的核心价值。其一是专业化能力定制通过为特定领域编写Skill可以使模型在代码开发、文档撰写、数据分析等垂直场景下表现出更高的准确性和一致性。其二是降低重复劳动团队成员无需各自维护冗长的提示词共享的Skill文件即可统一工作标准。其三是能力的可组合性多个Skill可以协同工作通过组合简单的模块构建出复杂的自动化工作流。这种模块化的设计理念与软件工程中关注点分离的思想一脉相承。每个Skill聚焦于一项具体能力保持自身的内聚性同时通过元数据声明与外部环境的接口关系。随着Skill数量的积累整个 AI 代理的能力边界将逐步扩展形成一个可维护、可演进的能力生态。2. Skills公开仓库随着Skills机制在开发者社区中的普及围绕其生态已经形成了多个公开的共享仓库。这些仓库为用户提供了开箱即用的Skill资源同时也为Skill的创作者搭建了分发与协作的平台。根据维护主体和定位的不同当前主流的公开仓库大致可以分为官方市场和社区生态两类。Anthropic 官方 Skills 市场是最具权威性的资源来源。该市场由Anthropic直接维护收录的Skill经过官方审核在质量和安全性方面有较高保障。官方市场通常会提供与Claude Code深度集成的安装方式用户可以通过/install-skill等命令直接将Skill部署到本地项目中。对于初次接触Skills的开发者而言官方市场是最推荐的起步资源。GitHub社区生态则是规模最大、覆盖面最广的分发渠道。大量开发者将自己编写的Skill以独立仓库或monorepo的形式托管在GitHub上涵盖代码审查、测试生成、文档撰写、DevOps 流程等多种场景。这类仓库通常附带README说明和使用示例用户通过git clone获取后将Skill文件放置到项目的.claude/skills/目录即可启用。由于缺乏统一的审核机制使用前需自行评估其指令内容的合理性。仓库维护方特点获取方式Anthropic 官方市场Anthropic质量可靠官方审核/install-skill命令集成GitHub 社区生态开源社区数量丰富覆盖广泛git clone手动部署ObraSuperpowersObra 社区聚焦工程实践工具链完善社区平台下载awesome-claude-skills社区策展精选索引分类清晰链接导航至源仓库skillsmp社区市场市场化运营支持检索与评价平台直接安装ObraSuperpowers是一个较为活跃的社区驱动项目其定位偏向于工程实践场景提供的Skill多与开发工作流、项目管理和自动化任务相关。该社区维护了相对完善的工具链支持方便用户对Skill进行本地调试和版本管理。awesome-claude-skills遵循GitHub上经典的awesome-list模式本身并不直接托管Skill文件而是充当策展与索引的角色。维护者按照领域和用途对优质Skill进行分类整理并提供指向源仓库的链接。这种聚合方式降低了开发者的搜索成本适合在选型阶段快速浏览可用资源。skillsmp则采用了更接近传统应用市场的运营模式提供Skill的检索、评分和安装功能。用户可以根据关键词、使用场景或社区评价筛选合适的Skill一定程度上弥补了纯GitHub生态中缺乏统一发现机制的不足。3. Skills工作原理Skills的运行依赖于Claude所处的虚拟机环境。与纯文本形式的Prompt不同Claude在该环境中具备文件系统的访问能力因此Skill可以作为一个目录结构存在其中包含指令文件、可执行脚本和参考资料。这种组织方式类似于为新成员准备的入职指南——将所需的知识、流程和工具集中放置在一个可导航的文件体系中由模型在运行时按需读取。这种基于文件系统的架构带来了一个关键设计优势渐进式信息披露Progressive Disclosure。传统Prompt模式下所有上下文信息必须在对话开始时一次性注入这会大量消耗有限的上下文窗口。而Skills机制允许Claude分阶段按需加载信息仅在实际需要时才读取对应的内容从而显著提升了上下文的利用效率。Skill的内容按照加载时机的不同划分为三个层级每个层级承担不同的职责Level 1 — Metadata此层级的内容始终被加载。每个Skill在SKILL.md文件头部通过YAML frontmatter声明元数据包括名称、描述、触发条件等发现信息。Claude在会话初始化时会扫描所有可用Skill的元数据以判断当前对话场景是否与某个Skill相关。由于仅加载轻量的描述字段这一阶段对上下文窗口的占用极小。一个典型的元数据声明如下---name:code-reviewdescription:Performs structured code review following team standardstrigger:When user asks for code review or submits a PRtools:bash,read_file---Level 2 — Instructions当元数据匹配成功后Claude会进一步加载SKILL.md的主体部分。这部分包含过程性知识即具体的工作流步骤、最佳实践准则和行为指导。其内容本质上是结构化的Markdown文本描述模型在该场景下应该如何思考和行动。这一层级的设计使得Skill的核心逻辑与触发条件解耦便于独立维护和更新。Level 3 — Resources and Code这是最细粒度的加载层级仅在执行过程中按需引入。其包含三类资源附加的Markdown指令文件如FORMS.md、REFERENCE.md用于提供更专业的子流程指导可执行脚本如fill_form.py、validate.pyClaude通过bash工具调用这些脚本来完成确定性操作避免将计算逻辑交由模型推理从而消耗上下文以及静态参考资料包括数据库 Schema、API 文档、模板文件等。4. Skills结构Skills遵循开放的Agent Skills Standard规范。该标准定义了一套通用的Skill描述与组织格式旨在使不同平台和工具链之间的Skill资源能够互相兼容。其核心思想是以文件系统目录作为Skill的封装边界通过约定的文件命名和元数据格式实现自描述能力。遵循该标准编写的Skill不仅可以在Claude Code中使用也具备向其他兼容 Agent 框架迁移的潜力。每个Skill的入口文件是SKILL.md其结构由两部分组成头部的YAML frontmatter和主体的Markdown正文。YAML frontmatter用于声明元数据对应前文所述的 Level 1 层级Markdown正文则承载具体的指令内容对应 Level 2 层级。一个最小可用的SKILL.md文件结构如下--- name: your-skill-name description: Brief description of what this Skill does and when to use it --- # Your Skill Name ## Instructions [Clear, step-by-step guidance for Claude to follow] ## Examples [Concrete examples of using this Skill]YAML frontmatter中有两个必填字段name和description。name作为Skill的唯一标识符在加载和引用时起到索引作用description则为模型提供语义层面的匹配依据Claude根据该字段判断当前任务是否应触发此Skill。两个字段各自有明确的格式约束字段约束条件说明name最长 64 字符用作唯一标识仅允许小写字母、数字和连字符如code-review、pdf-analyzer不得包含 XML 标签防止注入风险不得使用保留词anthropic、claude避免与官方资源冲突description不得为空最长 1024 字符供模型进行语义匹配不得包含 XML 标签同上name字段的命名约定值得注意。小写字母加连字符的格式kebab-case与常见的npm包名、Docker镜像标签等命名规则保持一致有利于在文件系统和命令行环境中无歧义地引用。禁止使用保留词的规则则确保用户自定义的Skill不会与Anthropic官方发布的资源产生标识冲突。Markdown正文部分通常包含Instructions和Examples两个核心章节。Instructions提供清晰的分步指导描述Claude在该Skill激活后应执行的具体流程Examples给出典型的使用场景和预期输出帮助模型更准确地理解指令意图。在编写实践中指令的表述应尽量具体且无歧义避免使用模糊的修饰语。当Skill涉及较复杂的功能时单个SKILL.md文件可能不足以承载全部内容。此时可以将附加指令、脚本和参考资料组织为完整的目录结构pdf/ ├── SKILL.md # 主指令文件触发时加载 ├── FORMS.md # 表单填写指南按需加载 ├── reference.md # API 参考文档按需加载 ├── examples.md # 使用示例按需加载 └── scripts/ ├── analyze_form.py # 工具脚本通过 bash 执行不注入上下文 ├── fill_form.py # 表单填写脚本 └── validate.py # 校验脚本在这个目录结构中SKILL.md是唯一的必需文件其余均为可选资源。附加的Markdown文件如FORMS.md、reference.md在SKILL.md的指令中通过文件路径引用Claude在执行过程中按需读取。scripts/目录下的脚本不会被注入到上下文窗口中而是由Claude通过bash工具直接执行其输出结果再回传给模型进行后续处理。5. Skills最佳实践5.1 保持精简上下文窗口是一种共享资源。Skill的内容与对话历史、系统指令以及其他已加载的Skill共同竞争有限的上下文空间。虽然并非每个token都会立即产生开销——启动阶段仅预加载所有Skill的元数据name和descriptionSKILL.md正文仅在Skill被触发时才读取附加文件更是按需加载——但一旦SKILL.md被加载其中的每个token都在与对话上下文争夺空间。因此精简性是Skill编写的首要原则。具体而言应避免在指令中堆砌冗余的背景解释将重点放在可操作的步骤和明确的约束条件上。5.2 设定合理的自由度Skill指令的详细程度应当与任务本身的脆弱性和可变性相匹配。一个实用的类比是将Claude想象为一个在路径上探索的机器人。窄桥场景低自由度任务只有唯一正确的执行路径偏离即会造成严重后果。此时应提供精确的操作步骤和严格的护栏约束。典型例子是数据库迁移脚本必须按照严格顺序执行任何步骤的遗漏或乱序都可能导致数据损坏。开阔地带场景高自由度多条路径都能通向正确的结果限制过多反而会降低效率。此时只需给出大致方向信任模型自行选择最优策略。代码审查就是典型案例最佳的审查重点取决于具体的代码上下文过于僵化的检查清单反而会忽略真正关键的问题。错误地为高自由度任务设定过多约束会导致Skill变得冗长且不灵活而对低自由度任务放松约束则可能引发严重的执行错误。在编写前先判断任务落在这个光谱的哪个位置是设计合理Skill的关键前置步骤。5.3 跨模型测试Skills本质上是对底层模型能力的增强层其实际效果与所使用的模型密切相关。同一份Skill指令在不同模型上的表现可能存在显著差异——某些模型对隐含指令的理解更强而另一些模型则需要更明确的步骤拆解。因此在正式部署前应使用所有计划适配的模型分别进行测试确保Skill在各模型上都能稳定工作。5.4 控制文件规模与引用深度SKILL.md应当充当目录的角色像入职指南的目录页一样为Claude提供全局概览并指引其在需要时查阅详细资料。在具体的规模控制上需要遵循以下准则SKILL.md正文控制在 500 行以内接近此限制时应将内容拆分到独立文件中所有引用文件应从SKILL.md直接链接保持引用深度为一层超过 100 行的引用文件应在顶部添加目录索引引用深度的限制源于Claude的实际读取行为。当遇到嵌套引用即引用文件中又引用了其他文件时Claude可能仅使用head -100等命令预览部分内容而非完整读取导致信息缺失。将所有引用保持在一层深度可以确保Claude在需要时能够读取完整的文件内容。对于超长的引用文件顶部目录的作用在于即使Claude仅进行部分预览也能感知到文件中全部可用信息的范围。# 推荐扁平引用结构 SKILL.md → FORMS.md ✅ 一层引用完整读取 SKILL.md → reference.md ✅ 一层引用完整读取 # 避免嵌套引用结构 SKILL.md → FORMS.md → helpers.md ❌ 嵌套引用可能部分读取5.5 使用工作流拆解复杂任务当Skill涉及多步骤的复杂操作时应将其拆解为清晰的顺序工作流。每个步骤应明确描述输入、操作和预期产出避免步骤之间存在模糊的依赖关系。对于特别复杂的工作流一种有效的策略是在指令中提供可勾选的检查清单Claude可以将其复制到回复中并逐项标记完成状态这既帮助模型维持执行的完整性也使用户能够直观地追踪进度。## Deployment Workflow - [ ] Step 1: Run test suite and confirm all tests pass - [ ] Step 2: Generate changelog from commit history - [ ] Step 3: Update version number in package.json - [ ] Step 4: Build production artifacts - [ ] Step 5: Run validation script ./scripts/validate.py - [ ] Step 6: Deploy to staging and verify这种检查清单模式在数据库迁移、发布流程、环境配置等对步骤完整性要求较高的场景中尤为适用。6. Skills评估与迭代6.1 优先构建评估体系一个常见的误区是在动手编写Skill之前先投入大量精力撰写详尽的指令文档。这种做法的风险在于开发者可能基于主观假设去描述想象中的问题而非解决实际存在的缺陷。更合理的策略是先构建评估体系再编写Skill内容。评估体系的存在确保每一条指令都有明确的验证标准避免Skill陷入文档膨胀而效果模糊的状态。6.2 评估驱动开发评估驱动的Skill开发遵循一个从发现问题到验证解决方案的闭环流程其核心思路与测试驱动开发TDD高度相似先明确什么是失败再有针对性地编写解决方案。第一步是识别缺陷。在不提供任何Skill的情况下让Claude处理一组具有代表性的真实任务仔细记录其失败的具体表现——是遗漏了关键步骤、使用了错误的工具调用方式还是缺乏特定领域的上下文知识。这些记录构成了Skill开发的需求来源。第二步是围绕这些缺陷创建至少三个评估场景每个场景对应一个已观察到的具体失败模式。随后在无Skill条件下执行这些场景记录模型的输出质量作为性能基线。基线的存在使后续的改进具备可量化的对比依据。在基线确立之后开始编写Skill指令。此阶段的关键原则是最小化——仅编写足以解决已识别缺陷的内容抵制预防性文档化的冲动。每一条新增的指令都应能追溯到某个具体的评估场景。编写完成后重新执行评估并与基线对比未达标则继续调整指令直到所有场景均通过。这种方法从根本上约束了Skill的膨胀趋势。未经评估验证的指令往往是对需求的猜测它们不仅增加上下文开销还可能在某些场景下引入意外的干扰。6.3 借助 Claude 迭代开发Skill开发中最高效的实践模式涉及两个Claude实例的协作。开发者与一个实例称为Claude A合作设计和优化Skill的指令内容然后由另一个独立实例Claude B在真实任务中测试这些指令。Claude A扮演指令作者的角色Claude B则扮演指令执行者的角色。这种双实例模式之所以有效是因为Claude模型本身对 Agent 指令的编写和解读具有双向理解能力——Claude A能够预判什么样的表述方式最易于另一个 Agent 实例准确执行同时能够根据Claude B的实际执行偏差快速定位指令中的歧义或遗漏。相比开发者独自反复修改和测试这种协作方式显著缩短了迭代周期。7. Skills代码执行Skills中的脚本承担着确定性计算任务其执行结果会直接回传给Claude用于后续推理。因此脚本的健壮性直接影响整个Skill的可靠性。一个核心设计原则是脚本应自行处理错误条件而非将异常抛回给模型。当脚本抛出未处理的异常时Claude收到的是一段错误堆栈信息它需要消耗上下文去分析错误原因并决定下一步操作这既浪费了上下文空间也引入了不确定性。良好的错误处理应当在脚本内部完成闭环——遇到可预见的异常时提供合理的降级方案或默认行为并通过标准输出告知Claude实际发生了什么。以文件处理为例defprocess_file(path):Process a file, creating it if it doesnt exist.try:withopen(path)asf:returnf.read()exceptFileNotFoundError:# 文件不存在时主动创建而非让调用方处理异常print(fFile{path}not found, creating default)withopen(path,w)asf:f.write()returnexceptPermissionError:# 权限不足时返回默认值避免流程中断print(fCannot access{path}, using default)return这段代码对FileNotFoundError和PermissionError两种常见异常分别提供了降级策略。Claude接收到的是清晰的状态描述如File not found, creating default而非Python的traceback输出从而可以直接基于该信息继续执行工作流。这种模式应推广到所有Skill脚本中网络请求应处理超时和连接失败数据解析应处理格式异常文件操作应处理路径不存在和权限不足等情况。脚本中的配置参数同样需要审慎对待。John Ousterhout在其软件设计理论中提出的 “voodoo constants” 问题在Skill场景下尤为突出——如果开发者自己都无法解释某个常量的取值依据Claude在执行时更无从判断该值是否适用于当前场景。每个配置参数都应附带简明的取值理由# HTTP 请求通常在 30 秒内完成# 较长的超时时间用于兼容慢速网络连接REQUEST_TIMEOUT30# 3 次重试在可靠性与速度之间取得平衡# 大多数间歇性故障在第 2 次重试时即可恢复MAX_RETRIES3对比两种风格的差异可以更直观地理解这一原则风格示例问题不透明常量TIMEOUT 30无法判断 30 是经验值、规范要求还是随意设定自文档化常量TIMEOUT 30 # HTTP typical slow network margin取值依据清晰便于后续调整不透明常量RETRIES 3无从评估是否适用于当前任务自文档化常量RETRIES 3 # Most transient failures resolve by retry 2隐含了可调整的判断依据注释中记录的不仅是值是什么更是为什么选择这个值。当Claude在不同的执行环境中运行脚本时这些注释为其提供了评估参数适用性的依据。例如如果任务涉及已知的高延迟 APIClaude可以根据注释中慢速连接的说明合理判断是否需要调大超时值而非盲目沿用默认配置。8. Skills实践8.1 目录结构整个Skill的文件组织如下遵循前文所述的扁平引用原则所有资源文件均从SKILL.md直接引用cpp-code-review/ ├── SKILL.md # 主指令文件 ├── checklist.md # 审查检查清单 ├── common-issues.md # 常见问题参考手册 └── scripts/ ├── check_includes.py # 头文件依赖分析 └── count_complexity.py # 圈复杂度统计8.2 SKILL.md 编写SKILL.md作为入口文件控制在 500 行以内聚焦于工作流的整体编排--- name: cpp-code-review description: Performs structured C/C code review focusing on memory safety, coding standards, and performance. Trigger when asked to review C or C source files, pull requests, or code changes. --- # C/C Code Review ## Instructions When asked to review C/C code, follow these steps in order. Copy the checklist from checklist.md into your response and check off items as you complete them. ### Step 1: Static Analysis Run the include dependency check and complexity analysis: python3 scripts/check_includes.py target_directory python3 scripts/count_complexity.py target_files Report any findings before proceeding. ### Step 2: Memory Safety Review Examine the code for memory-related issues: - Unmatched malloc/free or new/delete pairs - Buffer overflows from unchecked array indexing or strcpy - Use-after-free and dangling pointer risks - Missing null checks after allocation Refer to common-issues.md Section 1 for detailed patterns. ### Step 3: Coding Standards Check adherence to project conventions: - Naming consistency (variables, functions, types) - Header guard correctness (#pragma once or #ifndef pattern) - Const correctness for function parameters and member functions ### Step 4: Performance Considerations Identify potential performance issues: - Unnecessary copies in loops (prefer references or std::move) - Repeated allocations that could be hoisted - Algorithm complexity mismatches for data scale ### Step 5: Summary Provide a severity-ranked list of all findings. Each finding must include: file path, line number, severity (critical/warning/info), and a concrete fix suggestion. ## References - checklist.md — Copy into response and track progress - common-issues.md — Detailed patterns for common C/C defects8.3 检查清单checklist.md提供可复制的工作流追踪模板Claude在审查过程中逐项标记# Code Review Checklist - [ ] Static analysis scripts executed - [ ] Include dependencies verified (no circular includes) - [ ] Cyclomatic complexity within threshold (≤15 per function) - [ ] Memory allocation/deallocation paired - [ ] Buffer access bounds checked - [ ] Null pointer checks present after allocation - [ ] Naming conventions consistent - [ ] Header guards present and correct - [ ] Const correctness verified - [ ] Unnecessary copies identified - [ ] Algorithm complexity appropriate - [ ] Summary with severity ranking produced8.4 辅助脚本辅助脚本遵循自行处理错误和自文档化常量的原则。以圈复杂度统计脚本为例all_findings[]forarginsys.argv[1:]:pathPath(arg)ifpath.is_file():all_findings.extend(analyze_file(path))elifpath.is_dir():forextin(*.c,*.cpp,*.cc,*.h,*.hpp):forfinpath.rglob(ext):all_findings.extend(analyze_file(f))else:print(fSKIP:{arg}is not a valid file or directory)ifnotall_findings:print(OK: All functions are within complexity threshold f({COMPLEXITY_THRESHOLD}))else:print(fFOUND:{len(all_findings)}function(s) exceed fcomplexity threshold ({COMPLEXITY_THRESHOLD}):\n)forfinsorted(all_findings,keylambdax:-x[complexity]):print(f{f[file]}:{f[line]}— f{f[function]}() complexity{f[complexity]})if__name____main__:main()该脚本的设计体现了几个关键实践COMPLEXITY_THRESHOLD和BRANCH_KEYWORDS两个常量均附带了取值依据的注释FileNotFoundError和UnicodeDecodeError在函数内部被捕获并输出SKIP标记不会导致脚本崩溃输出格式对Claude友好以OK或FOUND开头明确传递分析结论后续的条目按严重程度降序排列便于模型优先处理高复杂度函数。8.5 使用效果当用户在Claude Code中发出类似review the src/ directory for C issues的指令时Claude根据description字段匹配到该Skill加载SKILL.md后按照工作流依次执行先运行辅助脚本获取静态分析数据再结合代码内容逐项完成检查清单最终输出按严重等级排序的审查报告。整个过程中脚本负责确定性的度量计算Claude负责需要语义理解的代码分析两者各自发挥所长。Once Day也信美人终作土不堪幽梦太匆匆......如果这篇文章为您带来了帮助或启发不妨点个赞和关注(◕‿◕)感谢您的阅读与支持~~~