如果你最近刷 GitHub大概率会看到一个非常夸张的数字一个围绕 AI skills 概念的生态项目星标数突破了 21 万累计下载量超过了 1400 万次。很多刚接触这个概念的开发者会好奇它到底是什么为什么能让 AI 不那么容易写出让人头皮发麻的“屎山代码”先说结论AI skills 本质上是一套给 AI Agent 使用的、可复用、可分享的“能力包”。它把原来散落在对话 Prompt 里的规则、规范、示例、参考资料整理成结构化的文件让 AI 在真正动手写代码之前先按你约定好的标准来工作。这篇文章会从“屎山代码是怎么来的”开始讲起再完整拆解 skills 的项目结构、核心文件、编写方法和实际运行效果最后补充常见问题与工程建议。1. 背景与核心概念AI Skills 到底是什么1.1 “屎山代码”是怎么被 AI 造出来的“屎山代码”在开发者圈子里是个非常形象的戏称指的是那些能运行、但结构混乱、重复代码多、错误处理缺失、靠一堆临时补丁叠加起来的系统。过去写屎山代码的多是人现在随着 AI 编程工具流行AI 也有能力批量制造屎山代码了。为什么会这样因为大部分 AI 编程工具的默认行为是“尽力生成可以运行的代码”而不是“生成符合你们团队规范的代码”。当你只丢给它一句“写一个用户登录接口”它大概率会给你一个把所有逻辑堆在 Controller 里的版本不处理参数校验、不区分业务异常甚至把数据库密码硬编码在文件里。代码能跑但一上规模维护成本直线上升。这不是 AI 能力不行而是它缺少上下文约束。你在 Prompt 后面加一句“注意分层、注意异常处理”它可能会好一些但下一次换个项目你又得重新说一遍。而且 Prompt 越长越容易丢失关键信息。1.2 AI Skills 与传统 Prompt 的区别AI Skills 解决的核心问题就是把“临时的口头约束”变成“持久的标准化能力”。用一句话概括传统 Prompt 是你在每一次对话里告诉 AI“你应该怎么做”而 Skill 是让 AI 在做某类任务时主动去读取一份长期的、结构化的规则文件。两者的区别可以用下面这个表格说明对比维度传统 PromptAI Skills组织形式一段连续文本目录结构 SKILL.md 脚本 参考资料复用方式每次复制粘贴一次安装全局调用管理能力改起来麻烦容易混乱可以按版本、按团队共享适合场景简单单次对话复杂、重复、工程化的任务AI 记忆负担Prompt 越长越容易失效按需加载减少上下文干扰从使用体验上看Skill 更像是给 AI 配了一个“岗位说明书”。当 AI 面对的任务属于某个 Skill 的能力范围时它会先打开这份说明书再动手。1.3 Skills 的典型应用场景代码规范约束让 AI 生成符合团队编码规范的后端代码例如必须分层、必须处理异常、禁止硬编码。测试用例生成AI 在写业务代码前先读取项目的测试规范输出对应风格的单元测试。前端组件开发规定组件必须使用 TypeScript、必须包含 props 类型校验、必须遵循设计系统的命名方式。文档与代码评审让 AI 按照模板生成接口文档、提交信息或在代码评审中按清单逐项检查。数据迁移脚本约束 AI 在生成 SQL 时必须包含事务、必须考虑回滚、批量操作必须控制条数。这些场景的共同特点是任务重复、规则明确、人工监督成本高。正好适合用 skills 标准化。2. 环境准备从零搭建 skills 使用环境2.1 需要准备的工具实际操作前先确认下面的工具是否齐全。如果你只是想先体验 skills 生态可以不安装完整的后端环境但下面的基础工具基本是必需的Node.js当前主流的 skills CLI 工具多数基于 Node.js 实现建议使用长期支持版本Git用于从 GitHub 克隆 skills 仓库一个支持 skills 规范的 AI 编程工具例如 Claude Code、Codex、OpenCode、Cursor 等。不同工具对 skills 的支持程度略有差异使用前先确认版本支持情况。如果你要在本地做代码检查还需要对应语言的运行环境例如 Java 需要 JDK、Python 需要 Python 3。版本方面不需要刻意追求最新。本文示例以常见的开发环境为例重点演示配置思路实际版本请根据项目要求调整。2.2 获取 Skills 项目进入 GitHub 后可以直接搜索 skills 相关仓库。很多体系化的 skills 集合会按照后端、前端、测试、文档等维度分类一次下载就能获得大量可用技能。如果 GitHub 访问不稳定可以优先考虑这几个缓解手段使用git clone --depth1做浅克隆只拉取最新一次提交能明显减少下载体积。配置 SSH 方式的 remote用 SSH 协议替代 HTTPS通常更稳定。只下载需要的子目录而不是整仓克隆。尽量避免在高峰期反复尝试 clone稍后重试经常比持续等待更有效。如果通过包管理器安装 CLI 工具可以配置国内 npm 镜像提升依赖获取速度。下载得到的是一个包含多个 skill 子目录的仓库。每个子目录就是一个独立技能例如backend-code-quality、frontend-component-builder。2.3 项目结构与核心文件说明一个标准 skill 目录通常长这样skills/ ├── backend-code-quality/ │ ├── SKILL.md # 技能说明文件AI 首次加载时会读取它 │ ├── scripts/ │ │ ├── check_smell.py # 可选本地校验脚本 │ │ └── lint_code.sh # 可选代码检查脚本 │ └── references/ │ └── coding_standards.md # 可选更详细的参考规范 └── frontend-component-builder/ ├── SKILL.md └── templates/ └── component.tsx # 模板文件其中最重要的就是SKILL.md可以理解为“技能说明书”。AI Agent 在执行任务前会先读取这个文件提取里面描述的规则、步骤、约束和示例。3. Skills 的核心原理拆解3.1 SKILL.md 文件的作用SKILL.md 是一种带结构化元信息的 Markdown 文件。文件头部通常用 YAML frontmatter 描述技能的元数据例如名称、用途说明、依赖条件后面是具体的指令正文。来看一个简化但完整的示例结构--- name: backend-code-quality description: 约束 AI 生成符合工程规范的后端 Java 代码包含分层、异常处理、日志和参数校验要求。 --- # 后端代码质量规范 当生成 Java 代码时请严格遵守以下规范 1. 必须采用 Controller / Service / Mapper 分层结构。 2. Controller 不做业务逻辑只做参数接收与响应封装。 3. Service 层必须处理业务异常不允许捕获异常后什么都不做。 4. 禁止在代码中硬编码配置一律读取配置文件。 5. 方法体不超过 80 行超长方法必须拆分。 6. 每个公共方法必须包含 Javadoc 注释。frontmatter 里的name是技能的唯一标识description是给 AI Agent 判断“什么时候该调用这个技能”的关键信息。AI 会根据description的匹配度来决定是否加载该 skill。3.2 skill 的目录组织方式Skill 目录不一定要包含脚本但引入脚本可以显著提升技能的“可执行性”。例如scripts/check_smell.py可以做静态扫描检测代码中是否存在典型坏味道比如超长方法、重复代码、魔法数字等。当 AI 调用这个 skill 时既可以按照 SKILL.md 生成代码也可以把生成结果交给脚本做校验再根据校验结果调整输出。这样就形成了一个“生成 → 检查 → 修正”的闭环。references目录用于存放比较长、比较完整的参考资料。SKILL.md 适合写精简规则详细的设计文档、规范手册可以放到 references 里让 AI 按需翻看。3.3 AI Agent 是如何加载并执行 skill 的这里用一个简化的流程说明用户向 AI Agent 提出任务“写一个用户注册接口。”AI Agent 根据任务描述比对已安装 skill 的description。如果任务与backend-code-quality匹配Agent 会打开该 skill 目录下的SKILL.md。读取规范后Agent 把规范注入当前上下文按照要求生成代码。如果 SKILL.md 中要求调用脚本Agent 可以执行scripts/check_smell.py对输出做自检。校验通过后final answer 返回用户。可以看出SKILL.md 既是触发条件也是执行依据。所以编写质量直接决定 AI 的输出质量。4. 完整实战用 skills 约束 AI 写出规范代码下面我们动手做一个完整的示例创建一个“后端 Java 代码质量规范” skill让 AI 按照这个 skill 生成用户注册接口。4.1 确定目标与能力边界先明确这个 skill 要解决什么问题目标AI 生成 Java 后端代码时自动遵守团队编码规范。约束范围只约束后端 Java 代码不影响前端任务。能力边界AI 生成代码后需要执行本地脚本检查代码坏味道。复杂度控制规则要具体、可执行不能写“代码要优雅”这种模糊描述。规则太笼统是 skill 失效的主要原因之一。比如“注意代码质量”“写得专业一点”这类表述AI 无法转化为具体操作。真正有效的规则是“方法不超过 80 行”“禁止在代码里出现硬编码的数据库连接”“错误日志必须包含请求 ID”。4.2 创建 skill 目录在本地创建一个项目目录名字就叫custom-skillsmkdir -p custom-skills/backend-code-quality/scripts mkdir -p custom-skills/backend-code-quality/references接着在backend-code-quality目录下创建SKILL.md文件--- name: backend-code-quality description: 用于生成符合工程规范的后端 Java 代码。当用户要求编写接口、Service、Mapper 或任何 Java 业务代码时必须使用该技能。 --- # 后端 Java 代码规范 ## 分层要求 1. Controller 只负责接收参数、调用 Service、封装响应。 2. Service 负责业务逻辑事务边界放在 Service 方法上。 3. Mapper 负责数据访问不承载业务逻辑。 ## 异常处理 1. 业务异常使用自定义 BusinessException不直接抛出裸 RuntimeException。 2. 异常捕获后必须记录日志禁止 catch 后不处理。 3. 返回给前端的错误信息必须经过用户提示处理不能直接暴露内部堆栈。 ## 编码细节 1. 禁止硬编码配置如数据库地址、Redis 地址、密钥等统一从 application.yml 读取。 2. 方法体不超过 80 行超过必须拆分。 3. 禁止使用魔法数字常量必须定义在常量类中。 4. 日志必须包含 traceId便于链路追踪。 ## 验证方式 生成代码后执行以下脚本检查坏味道 bash python scripts/check_smell.py 生成的Java文件路径如果脚本返回错误需要根据错误提示修正代码直到脚本通过。这里需要注意的是内部代码块嵌套在 Markdown 里时需要按照实际编辑器规范处理。如果你使用的工具不支持嵌套代码块可以把执行脚本写成一行命令描述例如 markdown 验证方式生成代码后运行 python scripts/check_smell.py 检查坏味道。4.3 编写代码检查脚本在scripts/check_smell.py中我们做一个简单的坏味道扫描器检查方法是否过长、是否包含硬编码 IP、是否 catch 后无处理等基础问题。#!/usr/bin/env python3 一个极简的 Java 代码坏味道扫描器。 用法: python check_smell.py Java文件路径 import re import sys def check_file(file_path): with open(file_path, r, encodingutf-8) as f: lines f.readlines() errors [] # 统计每个方法的行数 method_start None method_count 0 for idx, line in enumerate(lines, start1): stripped line.strip() # 检测方法开始粗略规则包含 public/private/protected 且以 ) { 结尾 if re.search(r(public|private|protected)\s[\w\[\]]\s\w\s*\(, line): if method_start is not None: # 上一个方法超长 if method_count 80: errors.append(f方法超长: 第 {method_start} 行附近行数 {method_count} 行) method_start idx method_count 1 continue if method_start is not None: method_count 1 # 硬编码 IP if re.search(r\d{1,3}(\.\d{1,3}){3}, stripped): errors.append(f发现疑似硬编码 IP: 第 {idx} 行) # catch 后无逻辑 if re.match(rcatch\s*\(, stripped): next_line lines[idx].strip() if idx len(lines) else if next_line in (, // ignore, return null;): errors.append(fcatch 块疑似无处理: 第 {idx} 行) if method_start is not None and method_count 80: errors.append(f方法超长: 第 {method_start} 行附近行数 {method_count} 行) if errors: print(检查到以下问题) for e in errors: print(f - {e}) return 1 else: print(检查通过。) return 0 if __name__ __main__: if len(sys.argv) ! 2: print(用法: python check_smell.py Java文件路径) sys.exit(2) sys.exit(check_file(sys.argv[1]))这段脚本的作用是给 AI 一个“自我纠错”的反馈信号。它不追求完美只需要能捕获最典型的坏味道。4.4 让 AI 加载 skill 并生成代码假设你使用的是支持 skills 的编程工具。运行对话时输入请使用 backend-code-quality 技能生成一个用户注册接口使用 Java Spring Boot。AI 会先读取SKILL.md再按规范生成代码。下面是期望的结构示意// 文件路径src/main/java/com/example/demo/controller/UserController.java package com.example.demo.controller; import com.example.demo.service.UserService; import com.example.demo.vo.RegisterRequest; import com.example.demo.vo.ApiResponse; import org.springframework.web.bind.annotation.*; import javax.annotation.Resource; RestController RequestMapping(/user) public class UserController { Resource private UserService userService; PostMapping(/register) public ApiResponseString register(RequestBody RegisterRequest request) { String userId userService.register(request); return ApiResponse.success(userId); } }// 文件路径src/main/java/com/example/demo/service/UserService.java package com.example.demo.service; import com.example.demo.dto.UserDTO; import com.example.demo.exception.BusinessException; import com.example.demo.mapper.UserMapper; import com.example.demo.vo.RegisterRequest; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.stereotype.Service; import org.springframework.transaction.annotation.Transactional; import javax.annotation.Resource; Service public class UserService { private static final Logger log LoggerFactory.getLogger(UserService.class); private static final int MAX_PASSWORD_LENGTH 64; Resource private UserMapper userMapper; Transactional(rollbackFor Exception.class) public String register(RegisterRequest request) { log.info(开始注册用户手机号: {}, request.getPhone()); if (request.getPassword() null || request.getPassword().length() MAX_PASSWORD_LENGTH) { throw new BusinessException(密码不合法); } UserDTO user userMapper.findByPhone(request.getPhone()); if (user ! null) { throw new BusinessException(手机号已注册); } UserDTO newUser new UserDTO(); newUser.setPhone(request.getPhone()); newUser.setPassword(request.getPassword()); userMapper.insert(newUser); log.info(用户注册成功用户Id: {}, newUser.getId()); return newUser.getId(); } }对比没有 skill 时的 AI 输出最大的差异在于有分层意识业务逻辑没有直接堆在 Controller 中。参数校验放在了 Service 层错误统一抛业务异常。加了日志和事务注解。禁止魔法数字常量被提取为类常量。4.5 运行脚本验证并修正AI 生成代码后如果工具支持可以手动执行脚本验证python scripts/check_smell.py src/main/java/com/example/demo/service/UserService.java如果脚本发现硬编码或 catch 后无处理AI 会按 SKILL.md 中的约定修正代码直到脚本通过。这样一个闭环式的代码生成流程就比原来的“一句话生成代码”可靠得多。4.6 将 skill 共享到团队确认 skill 行为符合预期后可以把它提交到 Git 仓库让团队所有成员共享cd custom-skills git init git add . git commit -m feat: 新增后端 Java 代码质量规范 skill git remote add origin 你的Git仓库地址 git push -u origin main团队成员克隆仓库后即可使用相同规范避免不同人写出的代码风格不一致。5. 常见问题与排查思路问题现象常见原因解决思路从 GitHub 下载或 clone 仓库很慢网络访问不稳定仓库体积过大使用--depth1浅克隆或配置 SSH 方式错峰重试AI 生成了代码但不执行 skill 规则skill 的 description 不够明确没有命中任务检查 description 是否覆盖用户常见提问方式skill 目录没有被识别缺少 SKILL.md或 frontmatter 格式错误打开文件确认 name 和 description 两个字段是否存在AI 只读取了 SKILL.md没有读取 referencesreferences 不是必读项AI 认为规则已足够在 SKILL.md 中显式声明“必要时阅读 references/xxxx”多个 skill 同时触发规则冲突不同 skill 对同类任务有不同约束细化 description限定触发条件避免范围重叠脚本执行报错Python 或 Node 环境不匹配检查脚本解释器路径和依赖先手动执行验证skill 对老项目不生效老项目上下文太复杂AI 忽略规则在 SKILL.md 开头增加“必须遵守优先级最高”等强调如果遇到 AI 完全无视 skill 的情况可以尝试在对话中直接问它“你是否加载了 backend-code-quality 技能给出你的执行计划。”这能让 AI 主动说明它读取了哪些规则。6. 最佳实践与工程建议6.1 skill 命名与版本管理Skill 的name要短、语义化例如backend-code-quality比java-best-practice好因为前者直接描述场景。版本管理方面建议沿用 Git 标签机制发布稳定版本时打 tag团队成员按 tag 锁定版本避免仓库频繁更新导致规范漂移。6.2 让规则足够具体、可校验写规则时试试能不能给这条规则配一个自动检测脚本。例如“禁止硬编码”可以写成规则也可以写成正则检查项而“代码要整洁”则无法自动校验。尽量让每条规则都能被脚本或人工清单验证否则 AI 的遵守情况只会是概率性的。6.3 控制 SKILL.md 的长度SKILL.md 不是越详细越好。太长的说明文件会消耗大量上下文窗口甚至稀释关键规则。建议把核心规范控制在一个屏幕内详细设计放到 references 目录必要的时候让 AI 去查。6.4 在 CI 中校验 AI 生成代码Skill 不只在对话时起作用。把它和 CI 结合起来效果更好AI 生成的代码提交到 MR 之后流水线自动运行规范检查脚本如果发现问题就阻塞合并。这样即使 AI 没有完全遵守规定也有最后一道防线兜底。6.5 安全边界让 AI 执行 skill 中的脚本时注意它运行在本机环境中。不要下载不信任的第三方 skill 后直接运行其脚本最好先人工审查目录里的所有文件。给团队主仓库设置合理的权限避免 skill 内容被任意修改。6.6 在真实项目里逐步推行不要第一天就要求所有代码必须通过所有检查。建议先在简单模块试用确认规则符合团队审美和业务模式后再逐步扩大范围。毕竟技能规范本身就是团队工程文化的沉淀需要持续迭代。7. 总结与下一步学习方向这篇文章从“屎山代码是怎么来的”这个问题出发介绍了 AI skills 解决该问题的整体思路把零散的 Prompt 约束变成结构化的能力包让 AI 在生成代码前先读取规范再用脚本形成闭环校验。我们还完整走了一遍创建 skill 的流程包括编写 SKILL.md、设计脚本、运行验证、共享到团队。在真实项目中建议优先把高频重复、规则明确的场景做成 skill例如接口代码生成、测试用例编写、组件开发、SQL 脚本生成等。下一步可以继续学习的方向尝试在你的 AI 编程工具中安装几个成熟的开源 skills分析它们的 SKILL.md 是怎么设计的。把你团队现有的团队规范文档整理成结构化规则形成第一个内部 skill。为 skill 补充更严格的校验脚本接入 CI/CD 流水线。对比不同模型在加载 skill 后的表现差异找到最适合你场景的组合。真正消除屎山代码不是靠某一个明星项目自动完成而是靠团队把工程规范沉淀下来、让 AI 按标准执行。Skills 提供了一种相当扎实的载体值得你花一个下午亲手试一遍。