如果你最近在折腾 Claude Code、Codex 或者 OpenCode大概率已经撞见过一个高频词AI Skills。我最近大概有一半的编码时间都花在这些 skills 上——从 GitHub 扒别人写好的技能包到改造成自己能用的再到自己动手写新的。这东西说白了就是把“怎么干一件事”的经验打包成一个小文件夹扔给 AI 编程工具就能用。这篇文章不聊虚的直接讲三件事skills 到底是什么、怎么从 GitHub 手动装到本地、怎么自己写一个能跑的 skill。适合正在用 AI 编程工具但不满足于默认行为的同学也适合那些想在团队里沉淀一套“AI 工作法”的人。1. 先从根上理解AI Skills 到底是个什么东西1.1 用“给后厨递菜谱”来理解 Skills我经常用一句话解释 Skills它是一份结构化的“工作手册”让 AI 在遇到对应任务时知道按什么流程、用什么工具、产出什么格式。你可以把大语言模型想象成一个特别聪明但有点“脸皮薄”的新人厨师。你直接说“帮我做一道剁椒鱼头”他大概率能做得像模像样但每次都会自由发挥火候、摆盘、调料比例全看心情。如果你递给他一份写好的菜谱里面清楚标注了原料清单、步骤顺序、成品标准他就能稳定复现。Skills 就是这个菜谱。一个典型的 AI Skill在文件系统层面就是一个文件夹里面通常有一个SKILL.md文件记录“这个技能用来干什么、怎么干”还可以带上参考文档、脚本、模板等附属文件。AI 工具会在对话过程中根据用户需求自动判断要不要调用这个技能调用后按SKILL.md的指示去执行。1.2 它跟 Prompt 模板、插件有什么本质区别很多人第一次接触 Skills会把它和“ Prompt 模板”“插件”混在一起。我用一个表说清楚差异对比维度Prompt 模板插件 / MCP 工具AI Skills本质一段文本代码级扩展可调用外部服务结构化文档 可选脚本/资源稳定性每次都要模型重新理解结果飘确定性强但重、要改运行环境介于两者之间模型按手册执行是否可复用需要复制粘贴分散在各处可复用但开发成本高可复用文件夹即单元适合场景临时任务、一句话指令需要确定性工具调用沉淀团队经验、批量复用工作流一句话总结Prompt 是“口述”插件是“外挂机器”Skills 是“培训手册”。它的核心优势在于轻——不需要改代码、不需要注册服务就是一个文档驱动的协议任何会写 Markdown 的人都能做。1.3 为什么 2025 年 Skills 突然成了 AI 编程的标配过去我们觉得模型上下文窗口越来越大直接把背景资料一股脑塞给 AI 不就行了实际用过就明白窗口大不代表会用塞进去一堆无关信息反而会干扰判断。Skills 解决的是“知识可用性”问题把任务相关的操作说明、注意事项、判断规则整理好在需要的时刻才被触发不占用对话上下文也不会被遗忘。另一个原因是多智能体协作。现在 Claude Code、Codex 这类工具越来越强调 Agent 自主规划、自动执行每个 Agent 需要统一的“技能协议”才能互相读懂彼此的产出。Skills 恰好提供了一个轻量的公共约定一个文件夹、一个 Markdown 文件就能让你的 Agent“学会”一门手艺。所以你会看到 GitHub 上出现了大量 skills 仓库社区里也开始讨论“技能资产”的沉淀和管理可以说这已经成了 AI 工程实践里的一个新兴方向。2. 从 GitHub 手动安装 Skills最实用的完整流程2.1 动手前先搞懂三件事格式、路径、触发装 skills 之前得先把三个关键概念理清楚否则很容易出现“明明装了但 AI 就是不用”的情况。第一是格式。绝大多数社区 skills 遵循一套约定一个文件夹内至少有一个SKILL.md文件文件头部是 YAML frontmatter包含 name 和 description 字段正文部分写具体的操作流程、规则、注意事项。AI 工具就是靠解析 description 来判断“什么时候该用这个技能”。第二是路径。以 Claude Code 为例用户级 skills 一般放在~/.claude/skills目录下项目级 skills 放在当前项目的.claude/skills目录下Codex 也有类似约定通常放在~/.codex/skills或对应配置目录OpenCode 则常见于~/.config/opencode/skills。具体以你所用工具的最新文档为准但大思路一致找到一个“技能目录”把文件夹放进去。第三是触发。Skills 不是显式命令而是由模型根据对话内容自动判断是否调用。所以 description 写得好不好、路径放得对不对直接决定了触发率。我见到太多人装了一堆技能结果 AI 一次都没用过八成是 description 太差或者路径错了。2.2 手动安装五步走下面是我实际操作中验证过的一套流程以 Claude Code 为例其他工具换一下路径就行。第一步打开 GitHub搜索awesome claude skills、agent skills这类关键词或者直接找superpower skills这类知名项目。你会看到大量集合型仓库和单技能仓库。第二步进入某个仓库后先看它的目录结构确认是不是有skills/子目录或者多个技能文件夹。不要心急先扫一眼 README搞清楚作者约定的安装方式。第三步把仓库拉到本地。可以用 git clone也可以直接下载 ZIP 包git clone https://github.com/your-name/your-skill-repo.git我习惯先 clone 到临时目录再挑选需要的子目录复制过去而不是直接原地安装因为你往往只需要整个仓库里的某一个技能全塞进去会让 AI 的选择器“选择困难”。第四步把选中的技能文件夹复制到正确路径。假设我要安装一个叫latex-helper的技能mkdir -p ~/.claude/skills cp -r ~/tmp/your-skill-repo/skills/latex-helper ~/.claude/skills/注意复制后确认目录结构是~/.claude/skills/latex-helper/SKILL.md而不是~/.claude/skills/latex-helper/skills/latex-helper/SKILL.md。这种“套娃”错误是我见过最多的问题。第五步重启你的 AI 编程工具或者在工具里手动触发一次技能扫描不同工具入口不同有的在设置面板有的重启即自动加载。然后找一个真实任务测试而不是问“你有哪些技能”——这种问题模型不一定老实回答直接用真实需求测才靠谱。2.3 验证安装是否生效验证这一步千万别省。我会按顺序做三个检查先看文件系统确认路径没错find ~/.claude/skills -name SKILL.md再看工具日志或配置界面确认技能被加载。有的工具会在启动时输出加载了哪些 skills有的需要你打开命令面板查看。最后做一次实际测试。比如我装了一个“代码审查”技能就拿一段有明显问题的代码让它走一遍审查流程看它的输出是否符合SKILL.md里约定的格式。如果输出和普通回答没区别那基本可以断定技能没有触发赶紧回头查路径和 description。这里有个小技巧你可以在SKILL.md的正文里加一句固定输出标记比如“本报告由 code-review skill 生成”这样一看到标记就知道技能确实被调用成功了。3. 写一个自己的 SkillSKILL.md 拆解与模板实战3.1 最小可用 Skill 长什么样安装别人的技能只是第一步真正有价值的是写自己的技能。你不需要会写代码——一个纯文档型 Skill 就足以覆盖很多场景。先看一个最小可用的SKILL.md--- name: meeting-notes description: 根据会议录音转写文本生成结构化会议纪要适合项目复盘、周会、客户沟通等场景。输入是一段对话文本输出是包含结论、待办、风险三部分的纪要。 --- ## 任务目标 把用户提供的会议对话转成结构化纪要。 ## 处理步骤 1. 通读文本识别发言人角色。 2. 提取关键决策和结论。 3. 整理待办事项标注重负责人和截止时间若原文有。 4. 识别风险点用一句话概括风险内容。 ## 输出格式 - 会议结论三到五条每条不超过五十字。 - 待办事项表格展示列为“事项 / 负责人 / 截止时间”。 - 风险记录每条包含“风险描述 / 影响程度高/中/低/ 建议动作”。这段内容看起来简单但它已经定义了 AI 该在什么场景用、该怎么一步步做、最后输出什么结构。模型看到description里的关键词比如“会议纪要”“周会”“转录文本”就很容易在合适时机触发。3.2 写好 description 的 3 个技巧description 是整个 skill 的“触发命门”。我踩过不少坑总结出三个技巧第一写清楚“什么时候用”。不要写“这是一个有用的工具”这种空话要写“当用户提供会议录音转写文本并要求整理纪要时使用”。直接点出输入信号。模型是靠关键词和意图匹配的不是你写得越长越好。第二写清楚“输入是什么、输出是什么”。比如“输入是转录文本输出是结构化 md 文件”这让模型知道触发条件也提前锁定了产出格式避免自由发挥。第三加上“不适用”的反例。比如“当用户只是想闲聊会议内容时不要使用本技能”。反例能显著降低误触发率这一点很多人忽略。我给自己的每个技能都会加一句“若非以下情况请忽略本技能”。3.3 让 Skill 学会调脚本进阶玩法纯文档型 skill 覆盖知识性任务没问题但如果你想让它真正“干活”比如批量处理文件、调用 API、跑数据清洗就需要让 skill 调用外部脚本。做法很简单在 skill 文件夹下放一个scripts/子目录把 Python、Node 或 Shell 脚本放进去然后在SKILL.md正文里告诉模型“执行某个脚本时需要用什么命令、传什么参数”。## 工具调用 当需要计算数据集的统计指标时使用项目内脚本 python3 ~/.claude/skills/data-helper/scripts/stats.py --input 文件路径 --output 结果路径这里有个安全红线不要给模型任意执行命令的权限。我一般只会授权它执行技能目录内固定脚本并限制参数范围。具体做法是在脚本入口写白名单逻辑只允许处理当前工作目录下的文件禁止危险操作同时要求模型在执行前先打印命令由你确认。3.4 常见设计误区写 skills 最大的问题不是写不出来而是写得“让 AI 不会用”。我复盘过自己踩过的坑一是把SKILL.md写成长篇大论恨不得塞进整个项目文档。模型处理超长文档的成本很高而且重点会被淹没。正确做法是正文只写任务流程和关键约束详细参考内容放到references/子目录并按需引用。二是把 description 写成“营销文案”。比如“本技能可以大幅提升效率帮助你写出更好的代码”——模型听完完全不理解何时触发。正确做法是描述输入信号和场景而不是吹嘘效果。三是脚本没有错误处理。如果脚本一遇到非法输入就抛异常模型会被卡住它会尝试各种方式绕过问题最后可能直接放弃。我在脚本里都会加try/catch并输出友好错误让模型能拿到“可理解”的报错信息继续处理。四是忽略命名规范。文件夹名最好用短横线命名比如> 
长河君 · 2026/10/3 5:58:10 · 阅读 1.2k AI Skills实战指南：从安装到编写，沉淀你的AI工作流
如果你最近在折腾 Claude Code、Codex 或者 OpenCode大概率已经撞见过一个高频词AI Skills。我最近大概有一半的编码时间都花在这些 skills 上——从 GitHub 扒别人写好的技能包到改造成自己能用的再到自己动手写新的。这东西说白了就是把“怎么干一件事”的经验打包成一个小文件夹扔给 AI 编程工具就能用。这篇文章不聊虚的直接讲三件事skills 到底是什么、怎么从 GitHub 手动装到本地、怎么自己写一个能跑的 skill。适合正在用 AI 编程工具但不满足于默认行为的同学也适合那些想在团队里沉淀一套“AI 工作法”的人。1. 先从根上理解AI Skills 到底是个什么东西1.1 用“给后厨递菜谱”来理解 Skills我经常用一句话解释 Skills它是一份结构化的“工作手册”让 AI 在遇到对应任务时知道按什么流程、用什么工具、产出什么格式。你可以把大语言模型想象成一个特别聪明但有点“脸皮薄”的新人厨师。你直接说“帮我做一道剁椒鱼头”他大概率能做得像模像样但每次都会自由发挥火候、摆盘、调料比例全看心情。如果你递给他一份写好的菜谱里面清楚标注了原料清单、步骤顺序、成品标准他就能稳定复现。Skills 就是这个菜谱。一个典型的 AI Skill在文件系统层面就是一个文件夹里面通常有一个SKILL.md文件记录“这个技能用来干什么、怎么干”还可以带上参考文档、脚本、模板等附属文件。AI 工具会在对话过程中根据用户需求自动判断要不要调用这个技能调用后按SKILL.md的指示去执行。1.2 它跟 Prompt 模板、插件有什么本质区别很多人第一次接触 Skills会把它和“ Prompt 模板”“插件”混在一起。我用一个表说清楚差异对比维度Prompt 模板插件 / MCP 工具AI Skills本质一段文本代码级扩展可调用外部服务结构化文档 可选脚本/资源稳定性每次都要模型重新理解结果飘确定性强但重、要改运行环境介于两者之间模型按手册执行是否可复用需要复制粘贴分散在各处可复用但开发成本高可复用文件夹即单元适合场景临时任务、一句话指令需要确定性工具调用沉淀团队经验、批量复用工作流一句话总结Prompt 是“口述”插件是“外挂机器”Skills 是“培训手册”。它的核心优势在于轻——不需要改代码、不需要注册服务就是一个文档驱动的协议任何会写 Markdown 的人都能做。1.3 为什么 2025 年 Skills 突然成了 AI 编程的标配过去我们觉得模型上下文窗口越来越大直接把背景资料一股脑塞给 AI 不就行了实际用过就明白窗口大不代表会用塞进去一堆无关信息反而会干扰判断。Skills 解决的是“知识可用性”问题把任务相关的操作说明、注意事项、判断规则整理好在需要的时刻才被触发不占用对话上下文也不会被遗忘。另一个原因是多智能体协作。现在 Claude Code、Codex 这类工具越来越强调 Agent 自主规划、自动执行每个 Agent 需要统一的“技能协议”才能互相读懂彼此的产出。Skills 恰好提供了一个轻量的公共约定一个文件夹、一个 Markdown 文件就能让你的 Agent“学会”一门手艺。所以你会看到 GitHub 上出现了大量 skills 仓库社区里也开始讨论“技能资产”的沉淀和管理可以说这已经成了 AI 工程实践里的一个新兴方向。2. 从 GitHub 手动安装 Skills最实用的完整流程2.1 动手前先搞懂三件事格式、路径、触发装 skills 之前得先把三个关键概念理清楚否则很容易出现“明明装了但 AI 就是不用”的情况。第一是格式。绝大多数社区 skills 遵循一套约定一个文件夹内至少有一个SKILL.md文件文件头部是 YAML frontmatter包含 name 和 description 字段正文部分写具体的操作流程、规则、注意事项。AI 工具就是靠解析 description 来判断“什么时候该用这个技能”。第二是路径。以 Claude Code 为例用户级 skills 一般放在~/.claude/skills目录下项目级 skills 放在当前项目的.claude/skills目录下Codex 也有类似约定通常放在~/.codex/skills或对应配置目录OpenCode 则常见于~/.config/opencode/skills。具体以你所用工具的最新文档为准但大思路一致找到一个“技能目录”把文件夹放进去。第三是触发。Skills 不是显式命令而是由模型根据对话内容自动判断是否调用。所以 description 写得好不好、路径放得对不对直接决定了触发率。我见到太多人装了一堆技能结果 AI 一次都没用过八成是 description 太差或者路径错了。2.2 手动安装五步走下面是我实际操作中验证过的一套流程以 Claude Code 为例其他工具换一下路径就行。第一步打开 GitHub搜索awesome claude skills、agent skills这类关键词或者直接找superpower skills这类知名项目。你会看到大量集合型仓库和单技能仓库。第二步进入某个仓库后先看它的目录结构确认是不是有skills/子目录或者多个技能文件夹。不要心急先扫一眼 README搞清楚作者约定的安装方式。第三步把仓库拉到本地。可以用 git clone也可以直接下载 ZIP 包git clone https://github.com/your-name/your-skill-repo.git我习惯先 clone 到临时目录再挑选需要的子目录复制过去而不是直接原地安装因为你往往只需要整个仓库里的某一个技能全塞进去会让 AI 的选择器“选择困难”。第四步把选中的技能文件夹复制到正确路径。假设我要安装一个叫latex-helper的技能mkdir -p ~/.claude/skills cp -r ~/tmp/your-skill-repo/skills/latex-helper ~/.claude/skills/注意复制后确认目录结构是~/.claude/skills/latex-helper/SKILL.md而不是~/.claude/skills/latex-helper/skills/latex-helper/SKILL.md。这种“套娃”错误是我见过最多的问题。第五步重启你的 AI 编程工具或者在工具里手动触发一次技能扫描不同工具入口不同有的在设置面板有的重启即自动加载。然后找一个真实任务测试而不是问“你有哪些技能”——这种问题模型不一定老实回答直接用真实需求测才靠谱。2.3 验证安装是否生效验证这一步千万别省。我会按顺序做三个检查先看文件系统确认路径没错find ~/.claude/skills -name SKILL.md再看工具日志或配置界面确认技能被加载。有的工具会在启动时输出加载了哪些 skills有的需要你打开命令面板查看。最后做一次实际测试。比如我装了一个“代码审查”技能就拿一段有明显问题的代码让它走一遍审查流程看它的输出是否符合SKILL.md里约定的格式。如果输出和普通回答没区别那基本可以断定技能没有触发赶紧回头查路径和 description。这里有个小技巧你可以在SKILL.md的正文里加一句固定输出标记比如“本报告由 code-review skill 生成”这样一看到标记就知道技能确实被调用成功了。3. 写一个自己的 SkillSKILL.md 拆解与模板实战3.1 最小可用 Skill 长什么样安装别人的技能只是第一步真正有价值的是写自己的技能。你不需要会写代码——一个纯文档型 Skill 就足以覆盖很多场景。先看一个最小可用的SKILL.md--- name: meeting-notes description: 根据会议录音转写文本生成结构化会议纪要适合项目复盘、周会、客户沟通等场景。输入是一段对话文本输出是包含结论、待办、风险三部分的纪要。 --- ## 任务目标 把用户提供的会议对话转成结构化纪要。 ## 处理步骤 1. 通读文本识别发言人角色。 2. 提取关键决策和结论。 3. 整理待办事项标注重负责人和截止时间若原文有。 4. 识别风险点用一句话概括风险内容。 ## 输出格式 - 会议结论三到五条每条不超过五十字。 - 待办事项表格展示列为“事项 / 负责人 / 截止时间”。 - 风险记录每条包含“风险描述 / 影响程度高/中/低/ 建议动作”。这段内容看起来简单但它已经定义了 AI 该在什么场景用、该怎么一步步做、最后输出什么结构。模型看到description里的关键词比如“会议纪要”“周会”“转录文本”就很容易在合适时机触发。3.2 写好 description 的 3 个技巧description 是整个 skill 的“触发命门”。我踩过不少坑总结出三个技巧第一写清楚“什么时候用”。不要写“这是一个有用的工具”这种空话要写“当用户提供会议录音转写文本并要求整理纪要时使用”。直接点出输入信号。模型是靠关键词和意图匹配的不是你写得越长越好。第二写清楚“输入是什么、输出是什么”。比如“输入是转录文本输出是结构化 md 文件”这让模型知道触发条件也提前锁定了产出格式避免自由发挥。第三加上“不适用”的反例。比如“当用户只是想闲聊会议内容时不要使用本技能”。反例能显著降低误触发率这一点很多人忽略。我给自己的每个技能都会加一句“若非以下情况请忽略本技能”。3.3 让 Skill 学会调脚本进阶玩法纯文档型 skill 覆盖知识性任务没问题但如果你想让它真正“干活”比如批量处理文件、调用 API、跑数据清洗就需要让 skill 调用外部脚本。做法很简单在 skill 文件夹下放一个scripts/子目录把 Python、Node 或 Shell 脚本放进去然后在SKILL.md正文里告诉模型“执行某个脚本时需要用什么命令、传什么参数”。## 工具调用 当需要计算数据集的统计指标时使用项目内脚本 python3 ~/.claude/skills/data-helper/scripts/stats.py --input 文件路径 --output 结果路径这里有个安全红线不要给模型任意执行命令的权限。我一般只会授权它执行技能目录内固定脚本并限制参数范围。具体做法是在脚本入口写白名单逻辑只允许处理当前工作目录下的文件禁止危险操作同时要求模型在执行前先打印命令由你确认。3.4 常见设计误区写 skills 最大的问题不是写不出来而是写得“让 AI 不会用”。我复盘过自己踩过的坑一是把SKILL.md写成长篇大论恨不得塞进整个项目文档。模型处理超长文档的成本很高而且重点会被淹没。正确做法是正文只写任务流程和关键约束详细参考内容放到references/子目录并按需引用。二是把 description 写成“营销文案”。比如“本技能可以大幅提升效率帮助你写出更好的代码”——模型听完完全不理解何时触发。正确做法是描述输入信号和场景而不是吹嘘效果。三是脚本没有错误处理。如果脚本一遇到非法输入就抛异常模型会被卡住它会尝试各种方式绕过问题最后可能直接放弃。我在脚本里都会加try/catch并输出友好错误让模型能拿到“可理解”的报错信息继续处理。四是忽略命名规范。文件夹名最好用短横线命名比如>