1. 项目概述与核心价值如果你和我一样每天都在和 Codex、Claude Code、Cursor 这类 AI 编程助手打交道那你肯定也经历过这样的场景每次想让它帮你查个最新的 API 文档、自动化测试一个网页或者规划一个复杂的重构任务时都得重新组织语言写一长串提示词。更头疼的是不同项目、不同助手之间这些好不容易调教好的“工作流”还无法复用一切又得从头再来。mxyhi/ok-skills这个项目就是为了解决这个痛点而生的。它本质上是一个可复用的 AI 智能体技能库或者说是一个“提示词工程”的标准化工具箱。它把我们在日常开发、研究、自动化中那些高频、通用的任务封装成了一个个独立的SKILL.md文件。你只需要把这些技能克隆到本地然后在你的AGENTS.md文件里像引用函数一样声明一下下次再遇到类似任务直接对 AI 说“用 planning-with-files 技能来规划这个模块重构”它就能自动调用一整套预设的最佳实践流程。这个仓库目前打包了39 个经过实战检验的技能覆盖了从文档查询、浏览器自动化、GitHub 工作流调试到前端设计、视频制作、Office 文档处理等众多场景。无论你是想提升 AI 助手的上下文理解能力还是希望建立一套跨项目、跨工具的标准化协作流程ok-skills都提供了一个即插即用的起点。它特别适合那些已经深度使用 AI 编码助手并希望将其能力系统化、工程化的开发者、技术负责人和效率追求者。2. 核心设计思路与架构解析2.1 技能Skill的本质标准化的 AI 工作流在ok-skills的语境里一个“技能”不是一个可执行程序而是一个高度结构化的 Markdown 文档即SKILL.md。这个文档定义了一个特定任务的标准操作流程SOP。它通常包含以下几个核心部分触发条件明确告诉 AI 助手“在什么情况下应该使用这个技能”。例如gh-fix-ci技能的触发条件可能是“当用户需要诊断和修复失败的 GitHub Actions 工作流时”。前置依赖列出执行该技能所需的环境、工具或权限比如需要安装ghCLI 并完成 GitHub 认证。操作步骤分步、详细地指导 AI 如何完成任务。这不仅仅是简单的命令罗列更包含了决策逻辑。例如planning-with-files技能会指导 AI 先创建task_plan.md来拆解需求再通过findings.md记录调研过程最后用progress.md跟踪实施。示例输入/输出提供具体的对话示例展示用户如何请求以及 AI 应如何响应和执行让 AI 能更好地理解技能的使用场景。这种设计将模糊的、依赖临场发挥的“提示词对话”转变为了清晰的、可重复的“技能调用”。AI 助手在接收到“使用某某技能”的指令后会去读取对应的SKILL.md文件并严格按照里面定义的步骤和逻辑来执行任务极大地提高了任务执行的一致性和可靠性。2.2 AGENTS.md技能的调度中心如果说SKILL.md是定义好的函数那么AGENTS.md就是你的“主程序”或“路由配置”。它是一个位于项目根目录或用户全局配置中的文件其核心作用是声明在本项目或本工作环境中有哪些技能可用以及何时使用它们。一个典型的AGENTS.md片段如下## 可用的技能 - **planning-with-files**: 当任务复杂、需要多步骤研究或执行时间可能超过 5 个工具调用时使用。 - **context7-cli**: 当需要获取最新、最准确的第三方库、API 或 SDK 文档时使用。 - **agent-browser**: 当需要进行网页导航、表单填写、截图、数据抓取或 Web 功能测试时使用。 - **gh-fix-ci**: 当 GitHub Actions 检查失败需要查看日志并制定修复方案时使用。通过这份“技能清单”你相当于为 AI 助手装备了一个外置的“技能面板”。当你发出指令时AI 会优先匹配AGENTS.md中定义的技能从而获得远超其内置能力的、专门化的工作流程。这种“配置即代码”的方式使得团队协作和技能共享变得异常简单——你只需要共享AGENTS.md和对应的技能库路径即可。2.3 仓库组织结构模块化与可维护性ok-skills的目录结构设计得非常清晰便于管理和扩展~/.agents/skills/ok-skills/ ├── brainstorming/ # 独立技能头脑风暴 │ └── SKILL.md ├── planning-with-files/ # 独立技能基于文件的规划 │ └── SKILL.md ├── agent-browser/ # 独立技能浏览器自动化 │ └── SKILL.md ├── hyperframes/ # 技能包视频制作 (来自上游仓库) │ ├── hyperframes/ │ ├── hyperframes-cli/ │ └── ... ├── gsap-skills/ # 技能包动画库 (来自上游仓库) │ ├── gsap-core/ │ ├── gsap-timeline/ │ └── ... └── ...这种结构有几个关键优势扁平化管理每个顶级技能目录都是独立的可以直接被AGENTS.md引用。技能包Vendored Packs对于像hyperframes视频和gsap-skills动画这样由多个关联技能组成的生态项目采用了“供应商化”的方式将整个上游技能仓库作为一个子目录引入并保留了其原有的内部结构。这既保证了功能的完整性又明确了代码来源和版权归属相关 LICENSE 文件均被保留。路径即约定技能目录的命名直接作为技能 ID 使用这种约定大于配置的方式减少了复杂度。3. 核心技能深度解析与实战指南3.1 研究规划类技能让 AI 先想清楚再做planning-with-files是我个人最推崇的技能之一它完美诠释了如何让 AI 进行“深度工作”。很多初级使用者常犯的错误是直接让 AI 开始写代码导致它因为缺乏全局规划而陷入细节频繁回溯修改。这个技能的核心是引导 AI 创建并维护三个 Markdown 文件task_plan.md用于拆解需求。AI 会在这里列出所有已知和未知的信息定义验收标准并将大任务分解为具体、可执行的小步骤。这一步强制进行了任务澄清避免了方向性错误。findings.md用于记录调研过程。当 AI 需要查阅文档、搜索方案或尝试不同方法时所有中间发现、链接、代码片段和决策理由都记录在此。这相当于一个可追溯的“思考过程白板”对于后续调试和团队复盘至关重要。progress.md用于跟踪执行进度。AI 会在此标记每个子任务的完成状态遇到阻塞时也会在这里记录。这为你提供了清晰的项目仪表盘。实操心得不要只在巨型项目中使用它。即使是修改一个中等复杂度的函数让 AI 先用此技能规划一下往往能提前发现边界条件处理、错误处理等潜在问题最终节省的时间远超规划本身花费的时间。brainstorming技能则侧重于创意和设计的前期阶段。它通过一系列结构化的问题引导 AI和你一起发散思考、评估选项、收敛到具体的设计方案。这对于 UI/UX 设计、系统架构选型、甚至给新项目起名都很有帮助。3.2 文档与上下文获取技能打破 AI 的“知识截止日期”AI 模型的知识有截止日期且无法直接访问互联网。context7-cli和get-api-docs这类技能就是解决这个问题的“外挂”。context7-cli它背后是 Context7 服务能够为 AI 实时获取最新、最准确的官方文档。你只需要告诉 AI “用 context7-cli 查一下 Next.js 15 的useOptimistichook 的用法”它就能调用相关工具获取并解析文档将最新信息注入到当前对话上下文中。get-api-docs更侧重于获取特定 API 或 SDK 的文档。其工作流程通常包括识别用户提到的库、定位其官方文档源、获取内容并提取关键部分如安装、快速开始、核心 API。注意事项这类技能通常需要额外的配置如设置 Context7 的 API 密钥或确保网络通畅。务必在初次使用前按照SKILL.md中的“前置依赖”部分完成配置否则技能会失效。3.3 自动化与测试技能赋予 AI“手和眼”agent-browser和browser-use是浏览器自动化的利器。它们允许 AI 控制一个真实的浏览器实例从而完成功能测试自动执行一系列用户操作点击、输入、导航验证网页功能。数据抓取从网页中提取结构化信息尤其适用于那些没有开放 API 的网站。可视化回归测试通过截图对比检查 UI 是否在修改后出现意外变化。表单填充自动填写冗长的表单用于测试或数据录入。electron技能则将这个能力扩展到了桌面端可以自动化基于 Electron 构建的应用程序。dogfood吃自己的狗粮技能则代表了一种更高级的测试理念——结构化探索性测试。它指导 AI 像一名挑剔的测试工程师一样系统性地探索一个 Web 应用寻找错误并自动生成包含步骤、截图、甚至屏幕录制视频的详细错误报告。避坑指南浏览器自动化对环境要求较高。确保你的运行环境安装了 Chrome/Chromium并且版本与自动化驱动兼容。在无头服务器环境下运行时可能需要安装额外的虚拟显示驱动如xvfb。首次运行出现连接问题时仔细检查端口占用和浏览器路径配置。3.4 GitHub 工作流技能无缝衔接团队协作对于使用 GitHub 的团队gh-fix-ci和gh-address-comments是提升效率的神器。gh-fix-ci当 CI/CD 流水线失败时开发者通常需要手动点开 GitHub Actions 日志在冗长的输出中寻找错误信息。这个技能自动化了这个过程。AI 会调用ghCLI 获取失败的 workflow run 详情和日志自动分析错误摘要并基于日志内容提出修复建议。这相当于为每个 PR 配备了一个自动化的 CI 诊断助手。gh-address-comments在代码评审中经常需要逐一回复评审意见并提交修改。此技能引导 AI 系统地遍历 PR 或 Issue 中的评论针对每个评论生成或修改代码并使用ghCLI 提交新的 commit甚至可以直接回复评论。这确保了每个反馈都得到闭环处理不会遗漏。yeet技能的名字很有趣它代表了一个极致的“一键发布”流程暂存所有更改、提交、推送到远程仓库、并自动创建 Pull Request。务必注意该技能的触发条件被设计得非常严格仅在用户明确要求执行这一完整流程时才使用以防止意外提交。3.5 创意与内容生成技能释放 AI 的创造力这一组技能展示了 AI 在非代码领域的强大能力。frontend-skill专注于快速生成视觉吸引力强的落地页、网站原型或应用 UI。它通常结合了现代 CSS 框架、组件库和交互设计模式。shader-dev为 WebGL GLSL 着色器开发提供深度指导。从简单的颜色过渡到复杂的噪声和光线模拟这个技能能引导 AI 写出在 ShaderToy 等平台上运行的炫酷视觉效果代码。ai-elements专门用于构建 AI 聊天界面组件遵循shadcn/ui等流行库的设计哲学产出可组合、样式美观的聊天气泡、输入框、消息列表等组件。Office 文档套件minimax-docx, minimax-pdf, pptx-generator, minimax-xlsx则解决了程序化生成和编辑办公文档的难题。它们不是简单的文本拼接而是指导 AI 利用相应的底层库如 OpenXML SDK、PptxGenJS去操作文档的底层结构实现复杂的格式、样式、图表插入等操作。4. 从零开始的完整配置与集成实战4.1 环境准备与技能库安装假设你主要使用 Cursor 或 Claude Code以下是在 macOS/Linux 系统上的标准配置流程创建技能目录首先为你的 AI 技能建立一个统一的存放位置。这个路径是一个约定大多数支持AGENTS.md的工具都会在此寻找技能。mkdir -p ~/.agents/skills cd ~/.agents/skills克隆 ok-skills 仓库git clone https://github.com/mxyhi/ok-skills.git ok-skills完成后你的技能库路径将是~/.agents/skills/ok-skills。安装核心依赖工具许多技能依赖于外部 CLI 工具。建议一次性安装以下常用工具GitHub CLI (gh)这是gh-fix-ci,gh-address-comments,yeet等技能的基础。前往 GitHub CLI 官网 下载安装并执行gh auth login完成认证。浏览器驱动确保系统已安装 Chrome 或 Chromium。agent-browser技能通常使用puppeteer或playwright它们会自动下载浏览器但确保系统有必要的依赖如ca-certificates,libnss3等。Node.js 环境部分技能如涉及前端构建、CLI工具需要 Node.js。建议使用nvm管理 Node 版本。4.2 配置 AGENTS.md 文件AGENTS.md文件可以放在两个地方全局配置~/.agents/AGENTS.md。此处定义的技能对所有项目生效。项目级配置你的项目根目录/.agents/AGENTS.md。此处定义的技能仅对该项目生效。项目级配置会覆盖或扩展全局配置。一个功能全面的全局~/.agents/AGENTS.md配置示例# 我的 AI 助手技能库 以下是已安装并可随时调用的技能列表。在对话中你可以直接对我说“使用 [技能名] 来...”。 ## 核心工作流技能 - **planning-with-files**: 当任务复杂、涉及多步骤、或需要深入研究时使用。用于创建 task_plan.md, findings.md, progress.md 进行规划。 - **brainstorming**: 当需要创意发散、方案设计或评估不同技术选型时使用。 - **test-driven-development**: 在开始实现任何新功能或修复 bug 前强制先编写测试。 ## 开发与调试技能 - **context7-cli**: 需要查询最新第三方库、框架、API 的官方文档时使用。 - **get-api-docs**: 当需要快速获取某个特定 API 接口文档时使用。 - **opensrc**: 当需要深入理解某个依赖库的内部实现为其添加补丁或进行深度调试时使用。 ## GitHub 与协作技能 - **gh-fix-ci**: 当 GitHub Actions CI 构建失败需要分析日志并制定修复计划时使用。 - **gh-address-comments**: 当需要处理 Pull Request 或 Issue 中的评论并进行代码修改和回复时使用。 - **yeet**: **仅在用户明确要求“提交、推送并创建 PR”时使用**。用于一键完成代码提交到创建 PR 的全流程。 ## 自动化与测试技能 - **agent-browser**: 当需要进行网页自动化操作如截图、表单测试、数据抓取或功能验证时使用。 - **dogfood**: 当需要对一个 Web 应用进行系统性的探索性测试并生成带证据的测试报告时使用。 ## 前端与创意技能 - **frontend-skill**: 当需要快速构建一个美观的登录页、产品原型或演示界面时使用。 - **better-icons**: 当需要在项目中寻找并引入合适的 SVG 图标时使用。4.3 在 AI 助手中激活与使用不同的 AI 编码助手激活方式略有不同CursorCursor 内置了对~/.agents目录下技能的良好支持。配置好AGENTS.md后在 Cursor 的聊天框中你直接输入“用 planning-with-files 技能来帮我重构这个用户认证模块”它就能识别并应用该技能。Claude Code / Codex这些工具通常需要通过特定的项目配置或插件来读取AGENTS.md。你可能需要在项目根目录放置一个配置文件如.cursorrules或特定插件的配置在其中指向你的技能库路径。请查阅你所使用工具的最新文档。通用方法最直接的方式是在给 AI 助手的指令中明确给出技能文件的路径作为上下文。例如“请参考~/.agents/skills/ok-skills/planning-with-files/SKILL.md中定义的工作流来规划本次数据库迁移任务。”4.4 实战案例使用技能完成一次功能开发假设我们要为一个项目添加“用户密码重置”功能。启动规划我对 AI 助手说“使用 planning-with-files 技能来规划‘用户密码重置’功能的开发。”AI 执行规划AI 会调用该技能创建task_plan.md并开始与我对话澄清需求前端页面还是 API 端点邮件服务用什么Token 有效期多长它会将任务分解为① 设计数据库表或字段② 实现发送重置邮件端点③ 实现重置密码验证端点④ 前端重置页面。调研依赖我接着问“关于发送邮件我们该用哪个服务用 context7-cli 查一下 Resend 和 SendGrid 的 Node.js SDK 文档。” AI 调用技能获取并总结两个服务的最新文档、安装方式、核心 API 和定价。实施与测试在 AI 编写代码的过程中我提醒“在实现每个端点前记得使用 test-driven-development 技能先写测试。” AI 会为每个端点先编写单元测试和集成测试。调试 CI代码提交后GitHub Actions 失败了。我让 AI“用 gh-fix-ci 技能看看哪里出错了。” AI 分析日志发现是测试数据库连接字符串配置问题并给出修改建议。UI 验证功能完成后我想看看前端页面在不同浏览器下的表现。“用 agent-browser 技能在 Chrome 和 Firefox 上打开重置页面截图并测试表单提交。” AI 控制浏览器完成操作并返回截图。通过这一套组合拳AI 不再是零散地响应指令而是像一个配备了专业工具箱的资深工程师有条不紊地推进整个项目。5. 常见问题排查与进阶技巧5.1 技能调用失败或未被识别问题现象可能原因解决方案AI 助手完全无视“使用 XX 技能”的指令。1.AGENTS.md文件路径不正确。2. AI 助手未启用或未配置技能发现功能。1. 确认AGENTS.md文件位于~/.agents/或项目根目录的.agents/下。2. 查阅你所用的 AI 助手Cursor/Claude Code的官方文档确认如何启用外部技能。可能需要设置环境变量或修改配置。AI 识别了技能名但说“找不到该技能”。技能库 (ok-skills) 的路径未正确关联到AGENTS.md。在AGENTS.md中技能名必须与ok-skills目录下的子目录名完全一致。检查拼写和大小写。确保ok-skills目录位于~/.agents/skills/下。AI 读取了技能但执行出错如命令未找到。技能所需的外部 CLI 工具未安装或未正确配置。仔细阅读出错技能目录下的SKILL.md文件检查“Prerequisites”或“Dependencies”部分。安装并配置所有必需的工具如gh,node, 特定 SDK。5.2 技能执行效果不佳问题现象可能原因解决方案AI 机械地执行技能步骤缺乏灵活判断。技能描述可能过于刻板或 AI 模型本身的理解能力有限。1.优化你的AGENTS.md触发描述不仅写“做什么”更写“为什么做”和“何时做”给 AI 更多上下文。2.在对话中提供额外约束例如“用 planning-with-files 技能但这次我们时间紧请先聚焦于核心流程忽略边缘情况。”浏览器自动化技能 (agent-browser) 超时或截图失败。1. 网络环境或目标网站加载慢。2. 无头浏览器环境缺少必要资源。3. 页面元素选择器不稳定。1. 在技能调用指令中增加超时和等待条件例如“等待 #submit-button 元素可见后再点击。”2. 在服务器环境运行确保已安装xvfb等虚拟显示服务。3. 鼓励 AI 使用更稳定的选择器如>gh-fix-ci技能无法获取私有仓库的日志。ghCLI 的认证令牌 (GITHUB_TOKEN) 权限不足或未对当前仓库授权。1. 运行gh auth status检查认证状态。2. 确保用于认证的 Token 具有actions:read权限。3. 如果是组织内的私有仓库确认 Token 对该组织有访问权。5.3 自定义与扩展技能ok-skills的真正威力在于它是可扩展的。当你发现某个重复性任务没有现成技能时完全可以自己创建。创建技能目录在~/.agents/skills/下新建一个目录例如my-deploy-skill。编写 SKILL.md这是核心。文件结构可参考现有技能# 我的部署技能 (my-deploy-skill) ## 触发条件 当用户需要将项目部署到预发布或生产环境时使用。 ## 前置依赖 - 已安装并配置 AWS CLI (aws) 或 Vercel CLI (vercel)。 - 项目根目录存在正确的配置文件如 vercel.json, .env.production。 ## 操作步骤 1. **确认环境**询问用户要部署到哪个环境staging 或 production。 2. **运行测试**执行 npm run test 或 pytest确保所有测试通过。 3. **构建项目**执行 npm run build 或对应的构建命令。 4. **执行部署** - 对于 Vercel: vercel --prod - 对于 AWS S3: aws s3 sync ./dist s3://my-bucket --delete 5. **验证部署**获取部署后的 URL并进行一次快速的健康检查如访问主页检查关键 API。 6. **通知结果**向用户报告部署是否成功并给出访问链接。 ## 示例 用户: “请使用 my-deploy-skill 将前端部署到生产环境。” AI: “我将为您执行生产环境部署。首先运行单元测试...”更新 AGENTS.md在你的全局或项目AGENTS.md中添加一行- **my-deploy-skill**: 用于将项目部署到预发布或生产环境。测试在对话中尝试触发你的新技能。5.4 性能与维护建议按需加载不需要一次性在AGENTS.md中声明所有技能。可以根据项目类型建立不同的配置文件。例如一个前端项目可能只需要frontend-skill,better-icons,agent-browser而一个后端项目则更需要planning-with-files,test-driven-development,gh-fix-ci。定期更新ok-skills仓库本身会更新上游技能包如hyperframes,gsap-skills也会有新版本。定期执行git pull更新你的本地技能库。但要注意更新后某些技能的接口或依赖可能发生变化建议在非关键项目上先测试。理解原理而非死记花时间阅读几个核心技能如planning-with-files,agent-browser的SKILL.md文件。理解其设计哲学和步骤逻辑这比单纯调用技能更能提升你与 AI 协作的深度。你甚至可以借鉴其思路优化自己的工作流。将 AI 助手从“一个聪明的聊天对象”转变为“一个拥有标准化操作流程的智能同事”这中间的关键一步就是技能化。mxyhi/ok-skills项目提供了一个极其丰富的工具箱和一套行之有效的方法论。我个人的体会是成功集成的标志不是你调用了多少次技能而是你开始习惯性地在任务开始时思考“这个问题有没有一个现成的技能可以套用” 这种思维转变能让你和 AI 的协作效率提升一个数量级。刚开始可能会觉得配置有点繁琐但一旦跑通它就会像你的 IDE 快捷键一样成为肌肉记忆再也回不去了。