你有没有遇到过这种情况别人推荐了一个很火的 Agent Skills你照着文档安装好了满怀期待地让 AI 执行任务结果它完全没反应甚至还在用通用方式回答。你第一反应是“装错了”于是删掉重装、切换目录、重启终端折腾半小时问题依旧。如果你也有类似的经历问题大概率不是安装步骤而是对 Skills 的理解还停留在“插件”的层面。Skills 不是插件。它不注册钩子不暴露接口也不提供按钮。它的核心是一份写给 AI 看的说明书外加一组可执行的脚本或模板。AI 在运行时会根据用户意图自动决定要不要加载它、怎么使用它。这个机制和传统软件开发里的“模块化”完全不是一回事但恰恰是这种差异让 Skills 正在重新定义 AI 开发者的能力边界。这篇文章会从概念到实操把 Agent Skills 的来龙去脉讲清楚并给出一个可以落地的 Spring Boot 3 项目骨架生成技能示例。读完你可以自己开发、安装、调试一个完整的 Skill并避开那些最容易踩的坑。1. Skills 为什么突然成为开发者的热门话题如果你最近关注过 Claude Code、OpenCode、Codex 这些 AI 编程工具会发现“Skills”这个词出现的频率越来越高。甚至在 Google 搜索相关的技术关键词里“skills 推荐”“skills 下载”“skills 开发”都成了高频组合。这个现象背后的技术趋势值得展开讲一讲。过去一年AI 编程助手解决的主要问题是“帮你想代码”“给你改代码”但人和 AI 协作的主要成本一直没降下来你还是要反复描述项目背景、技术栈、代码规范、目录结构甚至每次都要在提示词里重新粘贴一遍。遇到复杂任务一段提示词可能写上千字AI 还不一定理解到位。于是有了一个很朴素的需求能不能把那些固定的、可复用的“做事方法”打包起来让 AI 随用随取Skills 就是在这个背景下出现的。它不是某一个公司的独有产品而是一套逐渐成型的社区规范。基本思路是把完成某类任务所需的行为说明、脚本、模板、参考资料集中放在一个目录里并给这个目录一个 AI 能读懂的身份文件。当用户说“我要初始化一个项目”时AI 看到需求会去搜索可用的技能包如果匹配就自动加载并按照技能包里的步骤执行。这个变化的意义在于AI 的能力不再只靠模型本身的推理而是可以像安装软件一样安装“行为包”。从搜索热词看Google 生态在这股浪潮中的存在感也很强。Google 的开发者工具比如 Gemini CLI、Google Antigravity、AI Edge Gallery以及“google / skills”这种搜索组合说明很多开发者都在把 Skills 当作新的效率工具来研究。这说明什么说明 Skills 已经从“小众玩具”进入了“生产力工具”的视野值得花时间系统学习。2. Skills 的核心概念它不是插件而是“AI 的行为包”先给一个清晰的定义Agent Skills 是一组描述“如何完成某类任务”的文件集合由 AI 在运行时根据用户意图自动加载并执行。它由两部分组成能力说明文件通常是一个 Markdown 文档社区常见命名为 SKILL.md包含技能的名称、描述、适用场景、使用步骤、注意事项。执行资源可以是脚本、模板、配置文件、参考文档甚至是命令行工具封装。和传统插件最大的区别在于插件是程序主动调用某个 API 或钩子而 Skill 是 AI 阅读你的说明后自己决定是否使用、如何编排。换句话说插件是“你调它”Skill 是“AI 按你写的说明去调它”。2.1 SKILL.md 是技能包的“入口文件”一个最基本的 Skills 目录结构长这样my-skill/ ├── SKILL.md └── scripts/ └── generate.pySKILL.md 是这个技能包的门面AI 会优先读取它。它的头部通常是 YAML 格式的元信息用来快速索引--- name: springboot3-project-generator description: 根据用户输入的 groupId、artifactId 和依赖列表生成一个 Spring Boot 3 项目骨架包括 pom.xml 和基础目录结构。适合在用户需要快速创建新项目时使用。 --- # Spring Boot 3 项目骨架生成 当用户需要创建新项目时按照以下步骤操作 1. 解析用户的 groupId、artifactId、Java 版本等参数。 2. 运行 scripts/generate_project.py 生成目录结构和 pom.xml。 3. 校验生成结果输出项目路径。name是技能的唯一标识description非常关键因为 AI 是通过它来判断“当前用户意图是否匹配这个技能”的。描述写得越贴近用户真实表达命中率越高。2.2 运行时的工作机制当 AI 收到一条用户消息时它会先理解意图。如果觉得自己具备完成该任务的能力它会检查可用技能列表并读取描述。如果匹配就加载 SKILL.md 全文然后按照里面的说明逐步执行。这个过程是动态的技能不需要常驻内存也不会影响不相关的任务。这个设计有一个非常大的好处技能之间是隔离的。一个技能包再复杂也不会污染其他任务的上下文除非用户确实需要它。它和“把提示词写在 system prompt 里”完全是两种体验——后者会导致模型被固定指令限制影响日常对话的灵活性。2.3 Skills 与插件、MCP 的对比很多刚接触的人容易把 Skills 和 MCPModel Context Protocol混在一起这里做一个对比维度Skills传统插件MCP模型上下文协议核心形式文档 脚本程序代码、API 接口标准化服务协议触发方式AI 自然语言理解后自动加载用户或程序显式调用工具调用AI 按需选择开发成本低一个 Markdown 加脚本即可高需要熟悉宿主 API中需要实现协议端点和工具适用场景沉淀可复用的 AI 使用流程需要稳定 UI 或事件入口对接外部数据源、第三方服务对 AI 透明性说明文档对 AI 完全可见通常是黑盒工具描述对 AI 可见一句话总结MCP 解决了“AI 如何连接外部系统”的问题Skills 解决的是“AI 如何按照既定流程工作”的问题。两者可以配合使用但不要混为一谈。如果你要做的是“给 AI 一个统一的数据查询入口”选 MCP如果你要做的是“让 AI 学会一套标准的项目初始化流程”选 Skills。3. 环境准备用什么工具、需要装什么在动手之前先确认你的环境。Skills 的官方标准还没完全统一但社区已经形成了几个主流约定。本文的示例以 Claude Code 和 OpenCode 的通用习惯为准版本细节以你实际使用的工具为准。你需要准备的内容如下一个支持 Skills 的 AI 编程助手客户端例如 Claude Code桌面版或 CLI、OpenCode、Codex CLI 等。不同客户端的技能目录位置可能不同但逻辑一样。一个可用的模型 API 权限确保客户端能正常连接模型服务这一步是基础。本地开发环境本文示例涉及 Python 3 和 Maven 基础命令。如果你不想生成 Java 项目也可以替换成任何你熟悉的语言脚本。在安装 Skills 前建议你先确认客户端的版本。社区里很多“不生效”的问题最后都指向版本太旧、不支持 Skills 规范。你可以检查--version类的输出也可以直接从官网或仓库获取最新稳定版。还需要提醒一点如果使用的是第三方 AI 工具一定要确认账号和 API Key 的权限范围。部分服务对地区、账号类型有明确限制某些账号会提示“无法订阅 AI 方案”或“所在地区不提供此应用”。这些问题通常在服务商官方文档里有说明不要轻易使用非官方途径绕过限制安全合规是第一优先级。4. 核心流程拆解从开发到安装一个 Skill开发一个 Skill 并不难关键在于流程要清晰。按下面四步走每一步都有明确的目标。4.1 第一步确定技能边界先想清楚一个问题这个技能要帮助 AI 完成什么任务边界越小描述越容易写AI 的命中率越高。例如“生成 Spring Boot 3 项目骨架”这个边界就很清楚输入是 groupId、artifactId、Java 版本、依赖列表输出是目录结构和 pom.xml。它不负责帮你写业务代码也不负责启动服务。如果你把边界定成“帮忙做 Java 开发”那 AI 在绝大多数场景下都会忽略这个技能因为它太宽泛了描述写不出足够的区分度。4.2 第二步准备技能文件技能包需要有一个目录目录下至少包含 SKILL.md 和真正执行任务的脚本。先把 SKILL.md 写好把执行脚本写好再考虑安装位置。4.3 第三步选择安装目录大多数支持 Skills 的客户端会扫描两个位置用户级目录所有项目都能使用一般建议放通用性强的技能。项目级目录只对当前项目生效适合和项目上下文强相关的技能比如团队规范、代码检查规则。用户级目录常见位置是~/.claude/skills/或~/.config/opencode/skills/项目级目录常见位置是项目根目录下的.claude/skills/或.skills/。具体要看你的客户端文档不同工具约定不完全一致。4.4 第四步验证与调用安装完技能后不要直接进正式流程。先在一个测试目录里发起一次任务请求用简单明确的指令触发技能。比如“使用 springboot3-project-generator 技能帮我生成一个 base-common 项目groupId 是 com.example”。如果技能正常加载执行过程会有日志输出生成结果也会出现在预期路径。整个过程看似简单但最容易出问题的两个点一个是 SKILL.md 的格式写错了另一个是描述和用户表达不匹配。后面第 6 章会专门讲排查方法。5. 完整示例一个可以复用的 Spring Boot 3 项目生成 Skills现在用一个真实可用的例子把概念落地。假设你想让 AI 帮你快速生成 Spring Boot 3 项目骨架避免每次手动创建 pom.xml、写目录结构。我们把这个技能包命名为springboot3-project-generator。5.1 创建目录结构首先建立一个技能目录mkdir -p ~/.claude/skills/springboot3-project-generator/scripts如果你用 OpenCode可以换成mkdir -p ~/.config/opencode/skills/springboot3-project-generator/scripts5.2 编写 SKILL.md文件路径~/.claude/skills/springboot3-project-generator/SKILL.md--- name: springboot3-project-generator description: Generates a Spring Boot 3 project skeleton from user-provided groupId, artifactId, Java version, and dependencies. Use this when the user wants to create a new Spring Boot project. --- # Spring Boot 3 Project Generator 当用户需要创建新的 Spring Boot 3 项目时使用此技能。 ## 使用步骤 1. 解析用户输入获取以下参数 - groupId必须例如 com.example - artifactId必须例如 demo-service - javaVersion可选默认 17 - dependencies可选逗号分隔例如 web,data-jpa,validation 2. 调用 Python 脚本生成项目目录 bash python3 scripts/generate_project.py --groupId com.example --artifactId demo-service --javaVersion 17 --dependencies web,data-jpa检查生成结果确认 pom.xml 存在输出项目路径。注意事项如果用户没有给出 groupId 或 artifactId请先向用户确认不要擅自使用默认值。脚本只负责生成骨架不执行 Maven 打包也不要尝试启动 Spring Boot 应用。如果依赖列表中有无效的 artifact请忽略并提醒用户。这个文件的意义在于它让 AI 知道自己什么时候该用这个技能以及具体怎么用。脚本会由 AI 调用但脚本本身不依赖 AI它可以独立运行。这样设计的好处是即使 AI 理解有偏差脚本的输入输出边界也是清晰的便于人工检查和修复。 ### 5.3 编写生成脚本 文件路径~/.claude/skills/springboot3-project-generator/scripts/generate_project.py python #!/usr/bin/env python3 import argparse import os import sys def main(): parser argparse.ArgumentParser(descriptionGenerate Spring Boot 3 project skeleton) parser.add_argument(--groupId, requiredTrue, helpMaven groupId) parser.add_argument(--artifactId, requiredTrue, helpMaven artifactId) parser.add_argument(--javaVersion, default17, helpJava version, default 17) parser.add_argument(--dependencies, defaultweb, helpComma separated dependency names) args parser.parse_args() group_id args.groupId artifact_id args.artifactId java_version args.javaVersion dependencies [item.strip() for item in args.dependencies.split(,) if item.strip()] base_dir os.path.abspath(artifact_id) os.makedirs(os.path.join(base_dir, src, main, java, *group_id.split(.)), exist_okTrue) os.makedirs(os.path.join(base_dir, src, main, resources), exist_okTrue) os.makedirs(os.path.join(base_dir, src, test, java, *group_id.split(.)), exist_okTrue) pom_path os.path.join(base_dir, pom.xml) with open(pom_path, w, encodingutf-8) as f: f.write(generate_pom(group_id, artifact_id, java_version, dependencies)) main_application_dir os.path.join(base_dir, src, main, java, *group_id.split(.)) main_class_path os.path.join(main_application_dir, f{camel_case(artifact_id)}Application.java) with open(main_class_path, w, encodingutf-8) as f: f.write(generate_main_class(group_id, camel_case(artifact_id))) print(fProject generated at {base_dir}) print(fMain class: {main_class_path}) print(fpom.xml: {pom_path}) def generate_pom(group_id: str, artifact_id: str, java_version: str, dependencies: list[str]) - str: dependency_xml \n.join([f dependency\n groupIdorg.springframework.boot/groupId\n artifactIdspring-boot-starter-{dep}/artifactId\n /dependency for dep in dependencies]) return f?xml version1.0 encodingUTF-8? project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.3.5/version relativePath/ /parent groupId{group_id}/groupId artifactId{artifact_id}/artifactId version0.0.1-SNAPSHOT/version name{artifact_id}/name descriptionGenerated by Spring Boot 3 Skill/description properties java.version{java_version}/java.version /properties dependencies {dependency_xml} dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency /dependencies build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin /plugins /build /project def generate_main_class(group_id: str, class_name: str) - str: return fpackage {group_id}; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; SpringBootApplication public class {class_name}Application {{ public static void main(String[] args) {{ SpringApplication.run({class_name}Application.class, args); }} }} def camel_case(name: str) - str: parts name.replace(-, _).split(_) return .join(part.capitalize() if i 0 else part for i, part in enumerate(parts)) if parts else name if __name__ __main__: sys.exit(main())这个脚本做了几件事解析命令行参数获取 groupId、artifactId、Java 版本和依赖列表。创建 Maven 标准目录结构。生成 pom.xml其中 Spring Boot 父依赖版本为 3.3.5。生成一个简单的SpringBootApplication启动类。注意脚本里的依赖映射方式用户传入web就会生成spring-boot-starter-web。这是最简单的映射规则实际项目中可能更复杂但演示原理足够了。脚本还假设groupId是类似com.example的多级包名自动在 src/main/java 下创建对应目录。如果 groupId 只有一级比如example目录结构也正确。5.4 测试脚本是否可以独立运行在把技能交给 AI 之前先手动测试脚本确保基础逻辑没问题cd ~/.claude/skills/springboot3-project-generator python3 scripts/generate_project.py --groupId com.example --artifactId demo-service --javaVersion 17 --dependencies web,data-jpa,validation预期输出Project generated at /Users/you/.claude/skills/springboot3-project-generator/demo-service Main class: /Users/you/.claude/skills/springboot3-project-generator/demo-service/src/main/java/com/example/demo/ServiceApplication.java pom.xml: /Users/you/.claude/skills/springboot3-project-generator/demo-service/pom.xml5.5 在 AI 客户端中触发技能现在在 AI 客户端中输入一条自然语言指令使用 springboot3-project-generator 技能帮我生成一个 user-service 项目groupId 是 com.company.businessJava 版本 17依赖用 web、data-jpa、validation。如果一切正常AI 会读取 SKILL.md调用脚本然后告诉你项目生成在哪个目录。你会注意到这中间不需要你手动执行任何脚本命令也不需要打开终端敲 Maven 命令。6. 运行结果与效果验证技能运行成功后你需要验证两个层面目录结构是否正确pom.xml 是否可以被 Maven 解析。在项目根目录执行cd user-service mvn -q validate如果 pom.xml 没有问题Maven 会静默退出。如果依赖或格式有问题会有明确的错误输出。这一步很有必要因为 Skills 生成的结果也是代码代码必须经过构建工具验证才算真正可用。另外你还可以检查生成的启动类find src -name *.java预期输出类似src/main/java/com/company/business/UserServiceApplication.java src/test/java/com/company/business注意启动类名称由 artifactId 转换而来。user-service会被转换为UserService最终类名是UserServiceApplication。这样符合 Spring Boot 的命名习惯。如果验证失败优先检查 Python 脚本里的camel_case逻辑。例如 artifactId 是user-service-api转换结果是UserServiceApi启动类就是UserServiceApiApplication。这些规则在描述文件里写清楚AI 调用时才不会困惑。7. 常见问题与排查思路Skills 开发和使用的过程中有几个问题非常典型。下面用表格整理出来按出现频率排列。问题现象可能原因排查方式解决方案AI 完全忽略技能没有触发SKILL.md 的 description 与用户意图匹配度低检查技能目录是否被客户端扫描到查看客户端日志是否加载了技能重写 description加入常见触发词把技能放到用户级目录技能被加载但脚本执行失败脚本依赖缺失或运行环境不一致手动执行脚本查看报错信息在 SKILL.md 中写明脚本运行前提把 Python 相对路径改为绝对路径安装后提示技能不存在目录名或 SKILL.md 文件名大小写错误确认目录名和文件名完全一致Skills 对文件名大小写敏感SKILL.md 必须严格遵守驼峰或全大写约定技能只在某个项目生效装到了项目级目录确认当前工作目录把技能复制到用户级目录或者按需使用项目级目录Google 相关服务提示账号异常或地区限制账号风控、地区政策、服务订阅限制查看服务商官方说明确认账号状态使用合规方式注册或订阅不要尝试绕过限制涉及密钥时轮换并清理AI 生成了包名但目录不对脚本输入参数解析错误手动运行脚本观察参数接收检查脚本中的 argparse 参数名称与 SKILL.md 中的命令模板是否一致7.1 “技能没生效”时最有效的检查顺序不要漫无目的地猜测。按下面顺序排查确认客户端版本支持 Skills。版本太旧目录结构再正确也没用。确认技能目录在正确的位置。用户级目录和项目级目录的差异很大。确认 SKILL.md 的 YAML frontmatter 格式正确name和description不能缺失。手动执行脚本确认脚本本身没有 bug。在客户端里用最直白的指令触发直接喊“使用 XX 技能”。90% 的问题都出在第 1 步和第 2 步。8. Skills 开发最佳实践与工程建议如果你准备在团队里推广 Skills 文化有几条建议值得提前定下来。8.1 命名与描述规范技能名称要唯一且能代表任务领域不要用my-skill、test-skill这种无意义命名。描述部分建议包含三要素触发场景什么时候应该使用这个技能。输入要求用户需要提供哪些关键参数。输出结果技能会产生什么结果。描述写得好不好直接决定 AI 能否命中这是整个技能包里最重要的文本。建议写完后自己读一遍如果一句话里能清楚说出“在什么场景、解决什么问题、输出什么”就算合格。8.2 一个技能只做一件事尽量把技能边界缩小。项目骨架生成就只做骨架生成不要顺手帮用户提交 Git 代码或执行 Maven 打包。技能越聚焦描述越容易写AI 的调用成功率也越高。复杂的业务流程可以拆成多个技能让 AI 在运行时自行编排。8.3 脚本要幂等且不破坏环境同一个技能可能被调用很多次。脚本执行后不应产生不可逆的副作用。比如生成项目骨架时如果目录已存在建议报错或覆盖前确认而不是直接清空目录。调用外部命令如 curl、git、mvn时先检查命令是否存在给出可读性好的错误提示。8.4 安全边界密钥、权限与外部输入这是最重要的一条。不要在 SKILL.md 或脚本中写入任何 API Key、Token、密码。技能包通常会被复制、分享一旦泄漏影响面不可控。如果脚本需要访问外部系统必须使用环境变量或密钥管理工具传入敏感信息并确保技能包内没有明文密钥。对用户输入做校验。用户传入的依赖列表、项目名、包名都可能包含恶意内容。虽然 AI 调用场景相对封闭但脚本作为独立程序运行时必须像处理普通命令行输入一样严格校验。如果依赖第三方 AI 平台或 Google 相关服务务必确认订阅和账号的合法权限不要在账号异常或授权范围不明的情况下强行使用。8.5 技能包要纳入版本管理技能不是一次性脚本它会随团队规范变化而迭代。建议把技能包单独建仓或者放到团队的 dotfiles 仓库里。每次修改都要写 changelog方便回溯。团队的技能仓库最好有负责人避免出现同名技能互相覆盖的情况。8.6 从“复制提示词”到“沉淀技能”团队协作时很多人喜欢分享“好用的大段提示词”。这种分享方式有局限提示词无法被结构化检索AI 也不一定在正确场景下想起它。Skills 提供了一个更好的替代把提示词、脚本、规范打包成可安装的技能文件。别人只需要装一下就能获得同样的行为表现。这个转变值得在团队里推广。它本质上是在把个人经验转化为团队资产。9. 总结与后续学习方向到这里你应该已经理解Agent Skills 不是插件而是一套“给 AI 使用的行为包”它解决的不是代码复用问题而是 AI 使用流程复用的问题它和 MCP 各有分工但在当前 AI 编程工具链里它是提升效率非常务实的一环。我建议你接下来的行动路径是这样的把本文的 Spring Boot 3 项目生成技能亲手装一遍跑通整个流程。尝试写一个与你日常工作强相关的技能例如“代码审查”“SQL 优化”“日志分析”把重复性描述和操作步骤沉淀进去。关注你所用 AI 客户端对 Skills 的版本更新以及社区里新的技能包规范。Google 等公司在 AI 开发者工具上的推进速度很快相关生态也会继续演进。最后给你一个实操建议在团队里试用 Skills 时先从一个低风险、高频次的场景开始比如“新项目初始化”或“统一代码格式检查”。等大家感受到效益再逐步扩大使用范围。不要一上来就追求大而全的技能库那样维护成本会很快超过收益。技能不是越多越好而是越精准越好。这既是 Skills 开发的原则也是团队 AI 工程化落地的原则。 Agent Skills 不是插件而是 AI 行为包：概念、原理与 Spring Boot 实战
你有没有遇到过这种情况别人推荐了一个很火的 Agent Skills你照着文档安装好了满怀期待地让 AI 执行任务结果它完全没反应甚至还在用通用方式回答。你第一反应是“装错了”于是删掉重装、切换目录、重启终端折腾半小时问题依旧。如果你也有类似的经历问题大概率不是安装步骤而是对 Skills 的理解还停留在“插件”的层面。Skills 不是插件。它不注册钩子不暴露接口也不提供按钮。它的核心是一份写给 AI 看的说明书外加一组可执行的脚本或模板。AI 在运行时会根据用户意图自动决定要不要加载它、怎么使用它。这个机制和传统软件开发里的“模块化”完全不是一回事但恰恰是这种差异让 Skills 正在重新定义 AI 开发者的能力边界。这篇文章会从概念到实操把 Agent Skills 的来龙去脉讲清楚并给出一个可以落地的 Spring Boot 3 项目骨架生成技能示例。读完你可以自己开发、安装、调试一个完整的 Skill并避开那些最容易踩的坑。1. Skills 为什么突然成为开发者的热门话题如果你最近关注过 Claude Code、OpenCode、Codex 这些 AI 编程工具会发现“Skills”这个词出现的频率越来越高。甚至在 Google 搜索相关的技术关键词里“skills 推荐”“skills 下载”“skills 开发”都成了高频组合。这个现象背后的技术趋势值得展开讲一讲。过去一年AI 编程助手解决的主要问题是“帮你想代码”“给你改代码”但人和 AI 协作的主要成本一直没降下来你还是要反复描述项目背景、技术栈、代码规范、目录结构甚至每次都要在提示词里重新粘贴一遍。遇到复杂任务一段提示词可能写上千字AI 还不一定理解到位。于是有了一个很朴素的需求能不能把那些固定的、可复用的“做事方法”打包起来让 AI 随用随取Skills 就是在这个背景下出现的。它不是某一个公司的独有产品而是一套逐渐成型的社区规范。基本思路是把完成某类任务所需的行为说明、脚本、模板、参考资料集中放在一个目录里并给这个目录一个 AI 能读懂的身份文件。当用户说“我要初始化一个项目”时AI 看到需求会去搜索可用的技能包如果匹配就自动加载并按照技能包里的步骤执行。这个变化的意义在于AI 的能力不再只靠模型本身的推理而是可以像安装软件一样安装“行为包”。从搜索热词看Google 生态在这股浪潮中的存在感也很强。Google 的开发者工具比如 Gemini CLI、Google Antigravity、AI Edge Gallery以及“google / skills”这种搜索组合说明很多开发者都在把 Skills 当作新的效率工具来研究。这说明什么说明 Skills 已经从“小众玩具”进入了“生产力工具”的视野值得花时间系统学习。2. Skills 的核心概念它不是插件而是“AI 的行为包”先给一个清晰的定义Agent Skills 是一组描述“如何完成某类任务”的文件集合由 AI 在运行时根据用户意图自动加载并执行。它由两部分组成能力说明文件通常是一个 Markdown 文档社区常见命名为 SKILL.md包含技能的名称、描述、适用场景、使用步骤、注意事项。执行资源可以是脚本、模板、配置文件、参考文档甚至是命令行工具封装。和传统插件最大的区别在于插件是程序主动调用某个 API 或钩子而 Skill 是 AI 阅读你的说明后自己决定是否使用、如何编排。换句话说插件是“你调它”Skill 是“AI 按你写的说明去调它”。2.1 SKILL.md 是技能包的“入口文件”一个最基本的 Skills 目录结构长这样my-skill/ ├── SKILL.md └── scripts/ └── generate.pySKILL.md 是这个技能包的门面AI 会优先读取它。它的头部通常是 YAML 格式的元信息用来快速索引--- name: springboot3-project-generator description: 根据用户输入的 groupId、artifactId 和依赖列表生成一个 Spring Boot 3 项目骨架包括 pom.xml 和基础目录结构。适合在用户需要快速创建新项目时使用。 --- # Spring Boot 3 项目骨架生成 当用户需要创建新项目时按照以下步骤操作 1. 解析用户的 groupId、artifactId、Java 版本等参数。 2. 运行 scripts/generate_project.py 生成目录结构和 pom.xml。 3. 校验生成结果输出项目路径。name是技能的唯一标识description非常关键因为 AI 是通过它来判断“当前用户意图是否匹配这个技能”的。描述写得越贴近用户真实表达命中率越高。2.2 运行时的工作机制当 AI 收到一条用户消息时它会先理解意图。如果觉得自己具备完成该任务的能力它会检查可用技能列表并读取描述。如果匹配就加载 SKILL.md 全文然后按照里面的说明逐步执行。这个过程是动态的技能不需要常驻内存也不会影响不相关的任务。这个设计有一个非常大的好处技能之间是隔离的。一个技能包再复杂也不会污染其他任务的上下文除非用户确实需要它。它和“把提示词写在 system prompt 里”完全是两种体验——后者会导致模型被固定指令限制影响日常对话的灵活性。2.3 Skills 与插件、MCP 的对比很多刚接触的人容易把 Skills 和 MCPModel Context Protocol混在一起这里做一个对比维度Skills传统插件MCP模型上下文协议核心形式文档 脚本程序代码、API 接口标准化服务协议触发方式AI 自然语言理解后自动加载用户或程序显式调用工具调用AI 按需选择开发成本低一个 Markdown 加脚本即可高需要熟悉宿主 API中需要实现协议端点和工具适用场景沉淀可复用的 AI 使用流程需要稳定 UI 或事件入口对接外部数据源、第三方服务对 AI 透明性说明文档对 AI 完全可见通常是黑盒工具描述对 AI 可见一句话总结MCP 解决了“AI 如何连接外部系统”的问题Skills 解决的是“AI 如何按照既定流程工作”的问题。两者可以配合使用但不要混为一谈。如果你要做的是“给 AI 一个统一的数据查询入口”选 MCP如果你要做的是“让 AI 学会一套标准的项目初始化流程”选 Skills。3. 环境准备用什么工具、需要装什么在动手之前先确认你的环境。Skills 的官方标准还没完全统一但社区已经形成了几个主流约定。本文的示例以 Claude Code 和 OpenCode 的通用习惯为准版本细节以你实际使用的工具为准。你需要准备的内容如下一个支持 Skills 的 AI 编程助手客户端例如 Claude Code桌面版或 CLI、OpenCode、Codex CLI 等。不同客户端的技能目录位置可能不同但逻辑一样。一个可用的模型 API 权限确保客户端能正常连接模型服务这一步是基础。本地开发环境本文示例涉及 Python 3 和 Maven 基础命令。如果你不想生成 Java 项目也可以替换成任何你熟悉的语言脚本。在安装 Skills 前建议你先确认客户端的版本。社区里很多“不生效”的问题最后都指向版本太旧、不支持 Skills 规范。你可以检查--version类的输出也可以直接从官网或仓库获取最新稳定版。还需要提醒一点如果使用的是第三方 AI 工具一定要确认账号和 API Key 的权限范围。部分服务对地区、账号类型有明确限制某些账号会提示“无法订阅 AI 方案”或“所在地区不提供此应用”。这些问题通常在服务商官方文档里有说明不要轻易使用非官方途径绕过限制安全合规是第一优先级。4. 核心流程拆解从开发到安装一个 Skill开发一个 Skill 并不难关键在于流程要清晰。按下面四步走每一步都有明确的目标。4.1 第一步确定技能边界先想清楚一个问题这个技能要帮助 AI 完成什么任务边界越小描述越容易写AI 的命中率越高。例如“生成 Spring Boot 3 项目骨架”这个边界就很清楚输入是 groupId、artifactId、Java 版本、依赖列表输出是目录结构和 pom.xml。它不负责帮你写业务代码也不负责启动服务。如果你把边界定成“帮忙做 Java 开发”那 AI 在绝大多数场景下都会忽略这个技能因为它太宽泛了描述写不出足够的区分度。4.2 第二步准备技能文件技能包需要有一个目录目录下至少包含 SKILL.md 和真正执行任务的脚本。先把 SKILL.md 写好把执行脚本写好再考虑安装位置。4.3 第三步选择安装目录大多数支持 Skills 的客户端会扫描两个位置用户级目录所有项目都能使用一般建议放通用性强的技能。项目级目录只对当前项目生效适合和项目上下文强相关的技能比如团队规范、代码检查规则。用户级目录常见位置是~/.claude/skills/或~/.config/opencode/skills/项目级目录常见位置是项目根目录下的.claude/skills/或.skills/。具体要看你的客户端文档不同工具约定不完全一致。4.4 第四步验证与调用安装完技能后不要直接进正式流程。先在一个测试目录里发起一次任务请求用简单明确的指令触发技能。比如“使用 springboot3-project-generator 技能帮我生成一个 base-common 项目groupId 是 com.example”。如果技能正常加载执行过程会有日志输出生成结果也会出现在预期路径。整个过程看似简单但最容易出问题的两个点一个是 SKILL.md 的格式写错了另一个是描述和用户表达不匹配。后面第 6 章会专门讲排查方法。5. 完整示例一个可以复用的 Spring Boot 3 项目生成 Skills现在用一个真实可用的例子把概念落地。假设你想让 AI 帮你快速生成 Spring Boot 3 项目骨架避免每次手动创建 pom.xml、写目录结构。我们把这个技能包命名为springboot3-project-generator。5.1 创建目录结构首先建立一个技能目录mkdir -p ~/.claude/skills/springboot3-project-generator/scripts如果你用 OpenCode可以换成mkdir -p ~/.config/opencode/skills/springboot3-project-generator/scripts5.2 编写 SKILL.md文件路径~/.claude/skills/springboot3-project-generator/SKILL.md--- name: springboot3-project-generator description: Generates a Spring Boot 3 project skeleton from user-provided groupId, artifactId, Java version, and dependencies. Use this when the user wants to create a new Spring Boot project. --- # Spring Boot 3 Project Generator 当用户需要创建新的 Spring Boot 3 项目时使用此技能。 ## 使用步骤 1. 解析用户输入获取以下参数 - groupId必须例如 com.example - artifactId必须例如 demo-service - javaVersion可选默认 17 - dependencies可选逗号分隔例如 web,data-jpa,validation 2. 调用 Python 脚本生成项目目录 bash python3 scripts/generate_project.py --groupId com.example --artifactId demo-service --javaVersion 17 --dependencies web,data-jpa检查生成结果确认 pom.xml 存在输出项目路径。注意事项如果用户没有给出 groupId 或 artifactId请先向用户确认不要擅自使用默认值。脚本只负责生成骨架不执行 Maven 打包也不要尝试启动 Spring Boot 应用。如果依赖列表中有无效的 artifact请忽略并提醒用户。这个文件的意义在于它让 AI 知道自己什么时候该用这个技能以及具体怎么用。脚本会由 AI 调用但脚本本身不依赖 AI它可以独立运行。这样设计的好处是即使 AI 理解有偏差脚本的输入输出边界也是清晰的便于人工检查和修复。 ### 5.3 编写生成脚本 文件路径~/.claude/skills/springboot3-project-generator/scripts/generate_project.py python #!/usr/bin/env python3 import argparse import os import sys def main(): parser argparse.ArgumentParser(descriptionGenerate Spring Boot 3 project skeleton) parser.add_argument(--groupId, requiredTrue, helpMaven groupId) parser.add_argument(--artifactId, requiredTrue, helpMaven artifactId) parser.add_argument(--javaVersion, default17, helpJava version, default 17) parser.add_argument(--dependencies, defaultweb, helpComma separated dependency names) args parser.parse_args() group_id args.groupId artifact_id args.artifactId java_version args.javaVersion dependencies [item.strip() for item in args.dependencies.split(,) if item.strip()] base_dir os.path.abspath(artifact_id) os.makedirs(os.path.join(base_dir, src, main, java, *group_id.split(.)), exist_okTrue) os.makedirs(os.path.join(base_dir, src, main, resources), exist_okTrue) os.makedirs(os.path.join(base_dir, src, test, java, *group_id.split(.)), exist_okTrue) pom_path os.path.join(base_dir, pom.xml) with open(pom_path, w, encodingutf-8) as f: f.write(generate_pom(group_id, artifact_id, java_version, dependencies)) main_application_dir os.path.join(base_dir, src, main, java, *group_id.split(.)) main_class_path os.path.join(main_application_dir, f{camel_case(artifact_id)}Application.java) with open(main_class_path, w, encodingutf-8) as f: f.write(generate_main_class(group_id, camel_case(artifact_id))) print(fProject generated at {base_dir}) print(fMain class: {main_class_path}) print(fpom.xml: {pom_path}) def generate_pom(group_id: str, artifact_id: str, java_version: str, dependencies: list[str]) - str: dependency_xml \n.join([f dependency\n groupIdorg.springframework.boot/groupId\n artifactIdspring-boot-starter-{dep}/artifactId\n /dependency for dep in dependencies]) return f?xml version1.0 encodingUTF-8? project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.3.5/version relativePath/ /parent groupId{group_id}/groupId artifactId{artifact_id}/artifactId version0.0.1-SNAPSHOT/version name{artifact_id}/name descriptionGenerated by Spring Boot 3 Skill/description properties java.version{java_version}/java.version /properties dependencies {dependency_xml} dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency /dependencies build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin /plugins /build /project def generate_main_class(group_id: str, class_name: str) - str: return fpackage {group_id}; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; SpringBootApplication public class {class_name}Application {{ public static void main(String[] args) {{ SpringApplication.run({class_name}Application.class, args); }} }} def camel_case(name: str) - str: parts name.replace(-, _).split(_) return .join(part.capitalize() if i 0 else part for i, part in enumerate(parts)) if parts else name if __name__ __main__: sys.exit(main())这个脚本做了几件事解析命令行参数获取 groupId、artifactId、Java 版本和依赖列表。创建 Maven 标准目录结构。生成 pom.xml其中 Spring Boot 父依赖版本为 3.3.5。生成一个简单的SpringBootApplication启动类。注意脚本里的依赖映射方式用户传入web就会生成spring-boot-starter-web。这是最简单的映射规则实际项目中可能更复杂但演示原理足够了。脚本还假设groupId是类似com.example的多级包名自动在 src/main/java 下创建对应目录。如果 groupId 只有一级比如example目录结构也正确。5.4 测试脚本是否可以独立运行在把技能交给 AI 之前先手动测试脚本确保基础逻辑没问题cd ~/.claude/skills/springboot3-project-generator python3 scripts/generate_project.py --groupId com.example --artifactId demo-service --javaVersion 17 --dependencies web,data-jpa,validation预期输出Project generated at /Users/you/.claude/skills/springboot3-project-generator/demo-service Main class: /Users/you/.claude/skills/springboot3-project-generator/demo-service/src/main/java/com/example/demo/ServiceApplication.java pom.xml: /Users/you/.claude/skills/springboot3-project-generator/demo-service/pom.xml5.5 在 AI 客户端中触发技能现在在 AI 客户端中输入一条自然语言指令使用 springboot3-project-generator 技能帮我生成一个 user-service 项目groupId 是 com.company.businessJava 版本 17依赖用 web、data-jpa、validation。如果一切正常AI 会读取 SKILL.md调用脚本然后告诉你项目生成在哪个目录。你会注意到这中间不需要你手动执行任何脚本命令也不需要打开终端敲 Maven 命令。6. 运行结果与效果验证技能运行成功后你需要验证两个层面目录结构是否正确pom.xml 是否可以被 Maven 解析。在项目根目录执行cd user-service mvn -q validate如果 pom.xml 没有问题Maven 会静默退出。如果依赖或格式有问题会有明确的错误输出。这一步很有必要因为 Skills 生成的结果也是代码代码必须经过构建工具验证才算真正可用。另外你还可以检查生成的启动类find src -name *.java预期输出类似src/main/java/com/company/business/UserServiceApplication.java src/test/java/com/company/business注意启动类名称由 artifactId 转换而来。user-service会被转换为UserService最终类名是UserServiceApplication。这样符合 Spring Boot 的命名习惯。如果验证失败优先检查 Python 脚本里的camel_case逻辑。例如 artifactId 是user-service-api转换结果是UserServiceApi启动类就是UserServiceApiApplication。这些规则在描述文件里写清楚AI 调用时才不会困惑。7. 常见问题与排查思路Skills 开发和使用的过程中有几个问题非常典型。下面用表格整理出来按出现频率排列。问题现象可能原因排查方式解决方案AI 完全忽略技能没有触发SKILL.md 的 description 与用户意图匹配度低检查技能目录是否被客户端扫描到查看客户端日志是否加载了技能重写 description加入常见触发词把技能放到用户级目录技能被加载但脚本执行失败脚本依赖缺失或运行环境不一致手动执行脚本查看报错信息在 SKILL.md 中写明脚本运行前提把 Python 相对路径改为绝对路径安装后提示技能不存在目录名或 SKILL.md 文件名大小写错误确认目录名和文件名完全一致Skills 对文件名大小写敏感SKILL.md 必须严格遵守驼峰或全大写约定技能只在某个项目生效装到了项目级目录确认当前工作目录把技能复制到用户级目录或者按需使用项目级目录Google 相关服务提示账号异常或地区限制账号风控、地区政策、服务订阅限制查看服务商官方说明确认账号状态使用合规方式注册或订阅不要尝试绕过限制涉及密钥时轮换并清理AI 生成了包名但目录不对脚本输入参数解析错误手动运行脚本观察参数接收检查脚本中的 argparse 参数名称与 SKILL.md 中的命令模板是否一致7.1 “技能没生效”时最有效的检查顺序不要漫无目的地猜测。按下面顺序排查确认客户端版本支持 Skills。版本太旧目录结构再正确也没用。确认技能目录在正确的位置。用户级目录和项目级目录的差异很大。确认 SKILL.md 的 YAML frontmatter 格式正确name和description不能缺失。手动执行脚本确认脚本本身没有 bug。在客户端里用最直白的指令触发直接喊“使用 XX 技能”。90% 的问题都出在第 1 步和第 2 步。8. Skills 开发最佳实践与工程建议如果你准备在团队里推广 Skills 文化有几条建议值得提前定下来。8.1 命名与描述规范技能名称要唯一且能代表任务领域不要用my-skill、test-skill这种无意义命名。描述部分建议包含三要素触发场景什么时候应该使用这个技能。输入要求用户需要提供哪些关键参数。输出结果技能会产生什么结果。描述写得好不好直接决定 AI 能否命中这是整个技能包里最重要的文本。建议写完后自己读一遍如果一句话里能清楚说出“在什么场景、解决什么问题、输出什么”就算合格。8.2 一个技能只做一件事尽量把技能边界缩小。项目骨架生成就只做骨架生成不要顺手帮用户提交 Git 代码或执行 Maven 打包。技能越聚焦描述越容易写AI 的调用成功率也越高。复杂的业务流程可以拆成多个技能让 AI 在运行时自行编排。8.3 脚本要幂等且不破坏环境同一个技能可能被调用很多次。脚本执行后不应产生不可逆的副作用。比如生成项目骨架时如果目录已存在建议报错或覆盖前确认而不是直接清空目录。调用外部命令如 curl、git、mvn时先检查命令是否存在给出可读性好的错误提示。8.4 安全边界密钥、权限与外部输入这是最重要的一条。不要在 SKILL.md 或脚本中写入任何 API Key、Token、密码。技能包通常会被复制、分享一旦泄漏影响面不可控。如果脚本需要访问外部系统必须使用环境变量或密钥管理工具传入敏感信息并确保技能包内没有明文密钥。对用户输入做校验。用户传入的依赖列表、项目名、包名都可能包含恶意内容。虽然 AI 调用场景相对封闭但脚本作为独立程序运行时必须像处理普通命令行输入一样严格校验。如果依赖第三方 AI 平台或 Google 相关服务务必确认订阅和账号的合法权限不要在账号异常或授权范围不明的情况下强行使用。8.5 技能包要纳入版本管理技能不是一次性脚本它会随团队规范变化而迭代。建议把技能包单独建仓或者放到团队的 dotfiles 仓库里。每次修改都要写 changelog方便回溯。团队的技能仓库最好有负责人避免出现同名技能互相覆盖的情况。8.6 从“复制提示词”到“沉淀技能”团队协作时很多人喜欢分享“好用的大段提示词”。这种分享方式有局限提示词无法被结构化检索AI 也不一定在正确场景下想起它。Skills 提供了一个更好的替代把提示词、脚本、规范打包成可安装的技能文件。别人只需要装一下就能获得同样的行为表现。这个转变值得在团队里推广。它本质上是在把个人经验转化为团队资产。9. 总结与后续学习方向到这里你应该已经理解Agent Skills 不是插件而是一套“给 AI 使用的行为包”它解决的不是代码复用问题而是 AI 使用流程复用的问题它和 MCP 各有分工但在当前 AI 编程工具链里它是提升效率非常务实的一环。我建议你接下来的行动路径是这样的把本文的 Spring Boot 3 项目生成技能亲手装一遍跑通整个流程。尝试写一个与你日常工作强相关的技能例如“代码审查”“SQL 优化”“日志分析”把重复性描述和操作步骤沉淀进去。关注你所用 AI 客户端对 Skills 的版本更新以及社区里新的技能包规范。Google 等公司在 AI 开发者工具上的推进速度很快相关生态也会继续演进。最后给你一个实操建议在团队里试用 Skills 时先从一个低风险、高频次的场景开始比如“新项目初始化”或“统一代码格式检查”。等大家感受到效益再逐步扩大使用范围。不要一上来就追求大而全的技能库那样维护成本会很快超过收益。技能不是越多越好而是越精准越好。这既是 Skills 开发的原则也是团队 AI 工程化落地的原则。