企业官网建设流程全解析

最近是不是经常刷到“skills”这个词？不是GitHub个人主页那个绿格子技能墙，而是AI编程领域里真正在改变使用方式的新东西——给Claude Code、Codex、OpenCode这些编程Agent装上一个个“技能包”，让它们在某些专业场景下表现得像换了一个人。我最早是从“superpower skills”这个仓库开始接触的，后来陆续在几个项目里手动装过GitHub上的skills，也踩了不少坑，今天这篇就把整个来龙去脉和实操过程讲透。

这篇文章不是单纯介绍某个工具，而是把skills从“是什么、为什么火”一直讲到“怎么装、怎么写、怎么调试”，全程拿我实际跑过的案例说话。内容覆盖Claude Code手动安装第三方skills的完整步骤、SKILL.md文件的结构与写作要点、自己开发skill的完整流程、常用skill源推荐，以及我最头疼的几个报错和排查思路。适合正在使用或准备上手Claude Code、Codex、opencode的开发者，也适合想把自己工作流沉淀成skills的人。

1. 先把skills这层窗户纸捅破

1.1 一个skill到底长什么样

我刚开始接触时也以为这是个很高深的东西，后来拆开一个真实仓库才发现，它本质上就是一个带固定结构的文件夹：

my-skill/ ├── SKILL.md # 核心描述文件，AI主要靠读它理解技能 ├── reference/ # 参考资料、模板、示例，触类旁通用 ├── scripts/ # 可执行的辅助脚本 └── assets/ # 图片、数据文件等静态资源

任何以目录形式存在的“技能”，只要里面有SKILL.md，就能被支持skills机制的Agent识别。我的第一个反应是：“这跟配置文件有什么区别？”后来在实战中才明白，区别非常大。

传统配置文件描述的是“系统应该怎么运行”，而SKILL.md描述的是“当AI遇到某一类问题时，它应该按照什么思维流程去处理”。前者是规则，后者是工作方法。举个容易理解的例子：普通提示词是告诉AI“你会写论文”，而一个论文写作类的skill则是告诉AI“拿到题目先拆解需求，再列提纲，每章控制在多少字，论证要有数据支撑，最后必须附上参考文献列表”——这是一种可以反复调用、跨项目复用的行为模式。

1.2 它跟插件、MCP有什么区别

很多人问过我这个事：skills跟插件到底什么关系？其实我也是用一遍才真正分清的。用一个装修队的比喻可能更直观。

• MCP类似“工具箱里的电钻、水平仪”：提供的是外部能力接口。比如让AI能查数据库、能操纵浏览器、能读本地文件，这是“连接真实世界”的部分。
• Plugin/插件类似“施工规范手册”：告诉AI哪些场景下可以使用这些工具，以及用之前要做什么检查。
• Skill则更接近“老师傅带徒弟时的口头禅”：面对特定活儿，告诉AI应该按什么顺序、用什么思路、避免什么坑去做。

放在实际项目中，一个完整的方案往往是“MCP提供能力，Plugin控制权限，Skill决定思维”。我试过只装一个优秀的模型而不装任何skills，遇到复杂任务时，AI还是会陷入“该问的不问、该验证的不验证”的毛病。而装上了合适的skills之后，它会把任务当成“按流程干活”而不是“自由发挥”。

1.3 什么时候别用skill

这里要泼一盆冷水。有一个很常见的误区，以为skill越多越好、越强大越好，结果装了几十个之后，Agent反而变笨了。原因很简单：大部分编程Agent会通过description对场景做“语义路由”，也就是说每次任务它都要在脑子里过一遍自己有哪些skill、哪个匹配度最高。技能库太杂太乱，路由就会不稳定，甚至会选中一个风格完全冲突的skill。

我现在养成了一个筛选规则：如果一个工作流我用提示词就能稳定描述清楚，就别硬做成skill；如果它需要“多轮决策、分支判断、结构化的流程”，才值得沉淀成skill。换句话说，skill是为了把复杂流程固化成模板，不是为了多装东西而装。

2. 手动安装GitHub上的skills，保姆级步骤

2.1 先分清你怎么装、装到哪

很多教程让你直接用Claude Code内置的“/install-skill”命令，但实际使用中你会发现，有些GitHub仓库并没有适配官方市场的目录规范，或者你根本不想让某个第三方仓库直接获得安装权限。这时候手动安装反而是最可靠、最可控的方式。

手动装之前，先搞清楚目录放哪。以Claude Code为例，当前版本同时兼容两种存放方式：

~/.claude/skills/ # 传统技能目录 ~/.claude/plugins/ # 新版插件目录，可以再嵌套skills/

大多数把“skills”作为核心功能的仓库，比如anthropics/skills这个官方示例库，都会在README里给一个目标目录。如果没有明说，就默认放到~/.claude/skills/<skill名称>/。Codex、OpenCode各自有自己的配置目录，后面会提到。

注意：目录名强烈建议用英文小写加短横线，不要带空格和中文。这样后续agent解析文件路径时会少掉很多麻烦。

2.2 完整的安装五步

我把常用的手动安装过程整理成了五步，每一步都用我踩过坑的版本写出来。

第一步，找到并且看清楚仓库结构。不要急着clone整个仓库。先在GitHub页面上看一下目录树，判断它的顶层是不是一个规范skill目录。如果整个仓库就是“一个skill一个子目录”，那要装的是里面的子目录，不是仓库本身。

第二步，下载目标内容。两种方式任选：

# 方式A：浅克隆整个仓库，再拷贝目标目录 git clone --depth 1 https://github.com/example/skill-repo.git ~/tmp/skill-repo # 方式B：直接用svn或者GitHub的Download ZIP下载压缩包后本地解压

我实际更推荐方式B，尤其当网络访问不稳定时，压缩包一次性下载比git克隆更省心。下载后把对应文件夹拷贝到技能目录。

第三步，确认命名。拷贝完成后，检查路径是否类似这样：

~/.claude/skills/code-review-master/SKILL.md

这里最容易踩的坑是：下载解压后文件夹名字常常带-master或-main后缀，比如code-review-main。Agent解析技能名时会拿文件夹名当skill的内部ID，所以最好把文件夹改成一个干净且有意义的名字，比如code-review。

第四步，做一次静态检查。用编辑器打开SKILL.md，确认YAML头部的name字段和实际文件夹名一致。如果不一致，后续在路由时可能出现“明明装了，Agent却不认识它”的诡异现象。

第五步，重启会话或执行一次刷新指令。以Claude Code为例，重启会话最稳妥，然后问它一句“你现在有哪些skills”，它会扫描目录并列出所有可用的技能。如果列表里没有刚装的，说明目录或格式有问题。

2.3 装完怎么验证真的生效

装完并不等于一定能用。手动安装的验证通常分三层。

第一层，确认能被发现。打开Claude Code后，注意观察Agent在收到任务时会不会主动“复习”对应skill。很多Agent会在日志里打出“Loaded skill: xxx”之类的记录，看到这个基本就稳了。

第二层，确认能按流程走。直接用一句测试指令触发它。比如装的是“code-review”类skill，就给一段有明显错误的代码，问它要怎么走审查流程。如果输出里带上了skill内定义的步骤编号或专属模板，说明生效了。

第三层，确认没有覆盖冲突。如果同时装了多个类似功能的skill，比如两个都叫“数学建模”，Agent可能会在模型里混乱。安装阶段就尽量避免重复功能的技能。

这里分享一个我自己的检验技巧：在SKILL.md里加一个差值很小的特殊标记，比如在最后加一句“本流程结束前必须复述校验码01A2”。验证时只要看它有没有输出校验码，就能判断它到底有没有完整地执行整个skill流程，而不是只凭大概记忆随便输出。

3. SKILL.md到底怎么写，拆开看

3.1 frontmatter是路由命根子

任何一个SKILL.md，不管内容多复杂，头部的YAML frontmatter都是最重要的。拿我的一个“数学建模题目拆解”skill为例：

--- name: math-modeling description: 当用户给出数学建模竞赛题目、要求建立数学模型、或者需要优化建模方案时使用。侧重问题拆解、模型选型与论文结构组织。 when to use: 适用于建模竞赛、课题研究中的数学建模部分，不适合纯粹的代码调试任务。 ---

name是内部ID；description决定了Agent在什么时间、什么触发词下会想到这个skill。这一点极其关键——很多人的skill写得很好，但description写得太泛，比如“帮助用户解决问题”，结果Agent根本不会在恰当时候调用它。

我在写description时总结出一个公式：触发场景 + 典型任务 + 明确的排除项。必须说清楚“什么时候应该用”，也要说清楚“什么时候不该用”。

when to use可以写得更口语化，甚至带一些风格化的提示，比如“当用户给出的是一个题目而不是一段报错时，请优先考虑本技能”。它的作用不是给用户看的，是给Agent做语义匹配用的。

3.2 正文部分：流程化而不是话痨化

正文是整个SKILL.md的主体，我强烈建议用“流程步骤 + 边界条件 + 校验点”三段式结构来写，不要写成一篇散文。

## 任务流程 1. 先复述用户给出的题目，标注出所有已知条件与未知量。 2. 建立数据与变量清单，检查是否有遗漏指标。 3. 选择至少三种候选模型，并对比适用条件。 4. 输出推荐模型，说明理由，附上简化假设。 5. 论文结构建议：提出问题→数据探索→模型构建→结果验证→结论。 6. 最后生成一份“下一步操作清单”，供用户继续往下走。 ## 边界条件 - 如果题目中缺少关键数据，不要自行编造，必须向用户询问。 - 如果涉及随机过程，优先考虑蒙特卡洛模拟类方法。 - 如果发现模型复杂度远超竞赛需要，主动建议简化。 ## 校验点 - 在最终回复末尾，检查是否包含“推荐模型”和“数据缺失项”两个必需小节。 - 如果步骤超过8步，每步控制在150字以内说明，避免冗长。

这里有一个关键认知：SKILL.md不是在给AI讲“知识”，而是在给AI定“工作节奏”。它本身就是给模型看的提示词，只不过用了一种高度结构化的形式，让每个调用它的模型都能按同一个节奏走，从而保证输出质量稳定。

3.3 为什么这么写能提升稳定性

我之前也试过把很多背景知识、微调经验直接塞进SKILL.md，结果Agent每次调用时都要解析大量上下文，反而导致关键指令被稀释。后来才意识到：模型在调用skill时，通常会优先读取frontmatter来做路由判断，进入详细流程前还会做一次“是否真的适用”的确认。

所以SKILL.md应该控制篇幅，尽量在200行以内，把最核心的流程和边界写清楚，参考资料、示例模板放reference/目录，通过相对路径去引用，而不是一股脑全塞在正文里。这就像做饭时把调料放厨房，而不是把所有瓶瓶罐罐都堆在餐桌上。

4. 自己开发一个skill的完整流程

4.1 第一步：把“擅长的事情”拆成步骤

很多人一上来就想写一个大而全的skill，比如“写论文”“做数据分析”，这些主题太宽泛，写出来的SKILL.md往往空而无物。我的做法是先记录自己真正做这件事时的最少必要步骤。

比如这段时间整理团队代码评审流程，我先把平时的评审行为记录下来：拉取变更、检查关键文件、优先看危险操作、类与接口的兼容性、异常处理是否完整、有没有安全硬编码。这些步骤拆出来之后，skill的骨架就已经成型了。

你完全可以这样操作：下周无论做什么，刻意记录自己处理任务时“先做什么、再做什么、卡住了怎么办”，一周后把这些碎片整理成流程，就是一个不错的skill雏形。

4.2 第二步：写初版，先让技巧大于文采

初版SKILL.md不需要太完美，我把重点放在“可执行”而不是“可读”。上面那个数学建模的例子其实就是我的初版，你会发现里面没有多少华丽的修辞，都是指令式的短句。

写完初版之后，别急着发布，直接扔给Agent实测。我用的是“模拟任务测试法”：构造10个会触发该skill的问题，依次交给Agent，看它有多少次能按照定义好的步骤走完全程。如果命中率低于8成，说明步骤描述还有歧义，得继续改。

这一步最关键的是：分析Agent为什么没有按流程走。一般情况下出问题的总是frontmatter里的description写得不够具体，模型压根没意识到该调用这个skill。

4.3 第三步：迭代与沉淀

Skill写完之后不是一劳永逸。我最近维护的几个skill基本都会在每次实际使用后补一两句话，把“这次遇到的问题”变成“下次的校验点”。举一个具体例子，我早期写的代码审计类skill，最初没有“敏感信息检查”步骤，直到某次真在日志文件里发现硬编码密钥，之后就立刻把这个步骤加进去了。

Skill的成长应该是渐进式的。每用一次，就在对应步骤下补一行“如果出现xx情况，应该yyy”。时间久了，这个文件就是你把隐性经验显性化的过程，价值甚至超过当初装的那些第三方技能。

5. 值得关注的skills来源与推荐清单

5.1 公开来源速查表

我整理几个自己实际体验过、且相对靠谱的来源，不一定全，但足够你起步。

很多人问从哪里“下载skills”，其实根本没有一个官方统一市场，GitHub就是最大的源。你可以直接在GitHub搜“awesome skills claude”这种关键词，也能找到聚合列表。

5.2 superpower skills怎么用

热词里被问最多的“superpower skills”，确实值得单独讲一下。这个仓库和很多其他仓库不一样，它不是单个skill，而是一个包含多个子技能的大型集合，比如study、write、plan等。我第一次安装时就踩了坑：直接clone整个仓库到技能目录，结果Agent告诉我没有发现任何有效skill。原因是用它需要把仓库里单个子目录独立拷贝到skills目录，而不是把整个仓库当成一个skill。

正确的安装其实超简单：

git clone --depth 1 https://github.com/obra/superpowers.git ~/tmp/superpowers cp -r ~/tmp/superpowers/skills/study ~/.claude/skills/study cp -r ~/tmp/superpowers/skills/write ~/.claude/skills/write

装完后重点不是用，而是学它的写法。我翻过它的SKILL.md，里面的流程设计很考究，比如“study”技能不仅在教AI如何拆解概念，还要求AI把自己的理解画成知识图谱，这种强制输出结构的方法很值得借鉴。

5.3 数学建模与论文类推荐

针对热词里提到的“华为杯建模比赛”和“数学建模skills推荐”，我可以负责任地说，不要指望一个skill能帮你“自动建模”，但它能极大缩短你从读题到定思路的时间。

我目前常用的三个组合是：题目拆解类skill（把比赛题目转化成明确问题）、论文结构类skill（按竞赛论文模板指导写作）、代码检查类skill（避免常见的数值计算符号问题）。这三个配合起来，一套比赛初稿的产出效率能提升明显。

提醒：比赛类skill最大的风险是“格式固化导致内容雷同”。建议使用后手动打散模板痕迹，至少调整数据表格样式和章节顺序，不要让最终提交的论文看起来像同一台机器批量生产的。

6. 常见问题排查实录

6.1 装完不生效，Agent不认账

这是我遇到最多的一个问题。排查顺序固定为：先确认目录路径→再确认SKILL.md是否能被找到→再看frontmatter是否正确。

经常有人在~/.claude/skills/下放置了一个没有SKILL.md的文件夹，或者把SKILL.md放进了reference子目录，Agent自然扫不到。

标准做法是：每次手动安装后执行一次“扫描确认”。Claude Code里可以直接问“你现在有哪些skills”，如果列表里没有，再打开文件检查编码。

6.2 中文乱码和路径问题

SKILL.md里的中文在部分客户端会出现乱码，这种事我碰过两次。建议所有skill文件统一使用UTF-8无BOM格式保存，不要用系统记事本默认的编码保存。另外，如果skill文件夹路径中有中文目录名，部分Agent在bash环境下解析会莫名失败，整套技能直接失灵。

我在团队内部约定：英文名创建目录，中文内容统一放文件内，这样兼容性最好。

6.3 Skill和MCP互相干扰

一个容易被忽略的问题：一旦某个动作既匹配了MCP工具调用，又匹配了某个skill，Agent可能先调用MCP工具，把流程打乱之后才想起skill里定义的步骤，最终输出内容两边不靠。

遇到这种情况，我的处理方式是在skill的frontmatter里明确写“当本技能被触发时，优先执行SKILL.md内部流程，外部工具仅用于获取数据，不做决策”。说白了，就是在skill里给Agent划定权力边界。

6.4 团队协作时skill目录怎么管理

如果你不是一个人用，而是整个团队共享一套skill，别再把目录散落在各人电脑上了。我现在的做法是把skills放成一个独立Git仓库，客户端通过一个启动命令自动拉取同步。比如在Claude Code的配置里设置启动钩子：

cd ~/.claude && git pull origin main

这样每个人打开工具时，技能目录都自动更新到最新版。配合Git分支做技能“评审”，比让大家手动拷贝文件夹要稳得多。

我个人的最终体会是：skills的价值不在于“装得多”，而在于“写得准”。试着把一个你日常最熟练的工作流固化成SKILL.md，打磨一周再回头看，你会发现AI产出的可信度有明显的变化。现在每开始一个新项目，我第一件事就是建一个.skills目录，把当前项目需要的工作步骤写进去，哪怕只有十条。这个习惯，比任何热门技能库都好用。