企业官网建设流程全解析

1. 从“skills”这个热词说起：它到底是什么

最近半年，不管是在技术社区、开发者群聊还是各类工具讨论区，“skills”这个词出现的频率高得离谱。很多人第一次看到“skills”这个词，脑子里浮现的是招聘网站上的“技能要求”，但在当下的语境里，它指的是一套可插拔、可复用、面向智能体（Agent）的能力模块。你可以把它理解成给一个通用大脑装上的“专业插件”——装上“写论文”的skills，它就懂学术写作的规范；装上“分镜设计”的skills，它就能按镜头语言输出脚本；装上“自动挖洞”的skills，它就能按安全测试的套路去跑流程。

我最初接触这个概念的时候，也以为不过是又一个新瓶装旧酒的营销词。但真正动手把几个skills跑通之后，我发现它解决的是一个非常实际的问题：通用模型什么都能聊，但什么都聊不深。你让它写一段前端代码，它能写，但不符合你团队的目录规范和组件拆分习惯；你让它做一次代码审查，它能看，但抓不住你们业务里那些约定俗成的坑。skills的价值就在于，把这些“约定俗成”和“专业套路”固化下来，变成可分发、可安装、可版本管理的模块。

这篇文章适合三类人看：第一类是刚听说skills、想知道它到底能干什么的开发者；第二类是已经在用各类智能体工具、但还没系统整理过自己skills库的进阶用户；第三类是想自己动手写skills、把它当成团队内部知识沉淀手段的工程师。我会从整体设计思路讲到具体实操，再到踩过的坑，尽量把我知道的都倒出来。

需要先说明一点：skills这个概念在不同平台上的实现细节有差异，比如Google Cloud生态下的Agent Skills、Claude体系的agent skills、以及codex相关的skills，它们在目录结构、加载方式、依赖管理上各有各的规矩。但底层的设计哲学是相通的——用声明式的描述告诉智能体“在什么场景下该做什么事”。理解了这一层，具体平台的差异就只是语法问题。

2. 整体设计思路：为什么是skills而不是别的方案

2.1 从“提示词工程”到“能力模块化”的演进逻辑

早两年大家解决“让模型干专业活”的办法是写超长提示词。我见过最夸张的一个系统提示词写了八千多字，把代码规范、输出格式、异常处理全塞进去。这种做法在单次任务里能用，但问题很快暴露出来：提示词越长，模型对其中某一条的注意力就越弱，而且这些提示词没法复用——换个项目就得重写一遍。

skills的思路完全不同。它把“能力”从“提示词”里抽出来，变成一个独立的文件或目录。这个目录里通常包含几样东西：一份描述文件（说明这个skill是干什么的、什么时候触发）、若干参考文档（具体的规范、示例、模板）、以及可选的脚本或工具配置。智能体在运行时，根据当前任务去匹配对应的skill，只加载需要的那部分内容。这就好比以前是把整本百科全书塞给一个人让他背下来，现在是给他一个索引，需要查哪页翻哪页。

这个设计带来的直接好处是上下文利用率大幅提升。我实测过一个对比：同一个代码生成任务，用传统长提示词的方式，模型在生成到第三十个文件的时候就开始偏离规范；换成skills方式，因为每次只加载当前任务相关的规范片段，到第五十个文件依然稳定。原因不复杂——上下文窗口是有限资源，你塞进去的无关信息越多，真正重要的信息被“稀释”得就越厉害。

2.2 skills、MCP与npx之间的关系梳理

热词里出现了“claude mcpservers npx”和“npx playwright install失败”，这几个词经常和skills一起被提到，但它们的定位完全不同，我见过不少人把它们混为一谈。

MCP（Model Context Protocol）解决的是“智能体怎么和外部工具通信”的问题。它定义了一套标准协议，让智能体可以调用数据库、文件系统、浏览器等外部资源。你可以把MCP理解成“插座标准”，有了它，不同品牌的电器都能插到同一个插座上。

skills解决的是“智能体在特定场景下该遵循什么流程和规范”的问题。它是知识层面的东西，不直接操作外部资源，而是告诉智能体“遇到这类任务，你应该按这个步骤来、注意这些点”。

npx则是Node.js生态里的包执行工具，很多skills的分发和安装依赖它。比如你想装一个playwright相关的skill，可能需要先跑npx playwright install来装浏览器依赖。热词里“npx playwright install失败”之所以高频出现，就是因为这个环节容易因为网络、权限、版本问题卡住。

三者关系可以这样理解：MCP是管道，skills是操作手册，npx是工具箱里的扳手。管道通了、手册有了、扳手能用，整个流程才跑得顺。

2.3 为什么现在值得投入时间学skills

我的判断是，skills正在从“极客玩具”变成“团队基础设施”。原因有三点。

第一，知识沉淀的颗粒度变细了。以前团队沉淀知识靠wiki、靠文档，但文档是给人看的，智能体读不懂。skills是同时给人看也给智能体看的，一份写好的skill，新人能当规范读，智能体能当指令执行，一份投入两份产出。

第二，分发成本在快速下降。热词里“skills下载平台有哪些”“skills大全”“skills安装包下载”这些搜索词说明，已经有人在整理和分发skills了。虽然目前还没有形成特别统一的官方市场，但GitHub上已经有不少高质量的skills仓库，社区也在自发整理索引。

第三，跨平台兼容性在改善。早期不同平台的skills格式互不兼容，现在虽然还有差异，但核心结构（描述文件+参考文档+可选脚本）已经趋于一致。这意味着你写一个skill，稍作调整就能在多个平台上用。

3. 核心细节解析：一个skill到底由什么构成

3.1 描述文件：skill的“身份证”和“触发开关”

描述文件是整个skill的入口，通常是一个Markdown文件（常见命名如SKILL.md）或者YAML/JSON配置。它最重要的作用是告诉智能体：我是谁、我什么时候该被激活、激活后该怎么做。

我拆过十几个不同来源的skills，发现写得好的描述文件都有几个共同特征。首先是触发条件写得具体。差的写法是“当用户需要写代码时使用”，好的写法是“当用户要求生成React组件、且项目使用TypeScript和函数式组件时使用”。后者把技术栈、组件类型都限定了，智能体匹配的准确率会高很多。

其次是能力边界写得清楚。一个skill不可能包打天下，明确写出“本skill不处理样式文件、不处理测试文件”，反而能让智能体在遇到边界外任务时主动去寻找其他skill，而不是硬着头皮瞎编。

第三是输出格式有明确约定。比如要求“所有代码块必须标注语言类型”“文件路径必须使用相对路径”“每个函数必须附带JSDoc注释”。这些约定越具体，输出的一致性就越高。

提示：描述文件里的触发条件不要写得太宽泛，否则会导致skill被频繁误触发，反而干扰正常任务。我一般建议一个skill只覆盖一类明确的任务场景。

3.2 参考文档：把“隐性知识”变成“显性规范”

参考文档是skill的肉。描述文件告诉智能体“该做什么”，参考文档告诉它“具体怎么做”。这部分内容的质量，直接决定skill的实用价值。

我见过两种极端的参考文档。一种是“什么都往里塞”，把团队所有规范、所有历史案例、所有模板全堆进去，结果文件几千行，智能体加载后反而抓不住重点。另一种是“惜字如金”，只写几句原则性的话，智能体看了等于没看。

我的经验是，参考文档应该按任务类型拆分，而不是按知识类型拆分。比如一个前端开发的skill，不要写成“HTML规范.md”“CSS规范.md”“JS规范.md”，而是写成“新建页面.md”“修改组件.md”“处理表单.md”。每个文档对应一类具体任务，里面把这类任务涉及的规范、示例、注意事项集中写清楚。这样智能体在接到具体任务时，只需要加载对应的那一份文档，上下文利用率最高。

文档内部的写法也有讲究。能用示例说明的，不要用文字描述。比如“按钮组件应该支持禁用状态”这句话，不如直接给一段带禁用状态的按钮代码示例。智能体对代码示例的理解和模仿能力，远强于对自然语言描述的理解。

3.3 脚本与工具配置：让skill从“会说”到“会做”

纯文档型的skill只能指导智能体“生成什么内容”，但有些任务需要实际执行操作——比如跑一次代码检查、生成一张图表、调用一个API。这时候就需要在skill里附带脚本或工具配置。

热词里“npx playwright install失败”就是一个典型场景。某个skill可能依赖playwright来做页面截图或自动化测试，安装说明里会写“先执行npx playwright install”。但实际执行时，可能因为Node版本不对、网络超时、系统缺少依赖库等原因失败。

我的做法是，在skill的脚本配置部分，把常见失败原因和排查步骤直接写进去。比如：

# 安装playwright浏览器依赖 # 如果失败，按以下顺序排查： # 1. 检查Node版本是否>=16：node -v # 2. 检查网络是否能访问npm registry：npm ping # 3. 尝试指定版本安装：npx playwright@latest install # 4. 如果提示缺少系统库，按提示安装对应依赖 npx playwright install

这样即使安装失败，智能体也能根据skill里的排查步骤引导用户解决问题，而不是直接报错卡住。

3.4 版本管理与依赖声明：容易被忽视但很关键

一个skill如果依赖特定版本的某个工具或库，一定要在描述文件里写清楚。我踩过的一个坑是：写了一个依赖某CLI工具v2版本的skill，结果在另一台机器上装的是v3版本，命令参数变了，整个skill跑不通。

现在我的习惯是在描述文件头部加一个依赖声明区块，格式大概是这样：

dependencies: node: ">=16.0.0" playwright: "^1.40.0" typescript: ">=5.0.0"

虽然不同平台对这个区块的解析方式不一样，但至少写清楚了对人对己都有好处。团队协作时，别人一看就知道该准备什么环境。

4. 实操过程：从零写一个可用的skill

4.1 环境准备与目录结构搭建

假设我们要写一个“前端组件生成”的skill，目标是在用户要求生成React组件时，按照团队规范输出代码。先建目录结构：

skills/ └── react-component-generator/ ├── SKILL.md ├── references/ │ ├── new-component.md │ ├── modify-component.md │ └── form-handling.md └── scripts/ └── lint-check.sh

这个结构里，SKILL.md是入口，references/放参考文档，scripts/放可选脚本。目录名用短横线连接的小写英文，这是社区比较通行的命名习惯，避免空格和特殊字符带来的路径问题。

环境方面，如果skill涉及Node工具，确保Node版本在16以上。可以用node -v确认。如果要用playwright之类的浏览器自动化工具，提前跑一次安装命令，把依赖装好。

4.2 编写SKILL.md：触发条件与能力描述

SKILL.md的内容我一般分四块写：概述、触发条件、能力范围、使用说明。下面是一个简化示例：

# React Component Generator ## 概述 本skill用于生成符合团队规范的React函数式组件，使用TypeScript和CSS Modules。 ## 触发条件 当用户提出以下类型请求时激活： - 新建React组件 - 修改现有组件结构 - 为组件添加表单处理逻辑 ## 能力范围 - 生成组件文件（.tsx） - 生成对应的样式文件（.module.css） - 生成类型定义 - 不处理路由配置、不处理状态管理库集成 ## 使用说明 1. 确认组件名称和存放路径 2. 根据任务类型加载references/下对应文档 3. 生成代码后运行scripts/lint-check.sh做基础检查

这个文件的关键在于触发条件要具体到任务类型，而不是笼统地说“前端开发”。能力范围里明确写出“不处理什么”，能有效防止智能体越界。

4.3 参考文档的写法：以“新建组件”为例

references/new-component.md是使用频率最高的文档，我通常按“规范说明+完整示例+常见错误”三段式来写。

规范说明部分列出硬性要求：组件必须用export function而非export default；Props类型必须单独定义并导出；样式必须用CSS Modules；每个组件文件不超过200行。

完整示例部分给一个可以直接抄的模板：

import styles from './Example.module.css'; export interface ExampleProps { title: string; onConfirm?: () => void; } export function Example({ title, onConfirm }: ExampleProps) { return ( <div className={styles.container}> <h2 className={styles.title}>{title}</h2> {onConfirm && ( <button className={styles.button} onClick={onConfirm}> 确认 </button> )} </div> ); }

常见错误部分列出新手容易犯的问题：忘记导出Props类型、用default export、样式类名用驼峰而非短横线、事件处理函数没加类型标注。这部分内容看似琐碎，但实际使用中能减少大量返工。

4.4 脚本的集成与调用方式

scripts/lint-check.sh是一个简单的检查脚本，用来在生成代码后做基础校验：

#!/bin/bash # 对生成的组件文件做基础检查 FILE=$1 if [ ! -f "$FILE" ]; then echo "文件不存在: $FILE" exit 1 fi # 检查是否使用了default export if grep -q "export default" "$FILE"; then echo "警告: 检测到default export，请改用命名导出" fi # 检查是否导出了Props接口 if ! grep -q "export interface.*Props" "$FILE"; then echo "警告: 未检测到导出的Props接口" fi echo "检查完成"

脚本的调用方式在SKILL.md里说明清楚，比如“生成代码后，对每个新建的.tsx文件执行bash scripts/lint-check.sh 文件路径”。这样智能体在完成任务后会自动跑一遍检查，把明显问题拦在前面。

注意：脚本里的检查规则不要写得太复杂，否则维护成本高，而且容易误报。我一般只放三到五条最关键的规则，剩下的交给正式的lint工具。

5. 常见问题与排查技巧实录

5.1 skill不触发或误触发怎么办

这是最高频的问题。表现是：明明任务匹配，skill没被加载；或者不相关的任务，skill反而被激活了。

排查思路分三步。第一步看触发条件是否太宽泛。如果描述文件里写的是“当用户需要写代码时”，那几乎所有编程相关任务都会触发，肯定乱套。改成“当用户要求生成React函数式组件且项目使用TypeScript时”，范围就收窄了。

第二步看是否有多个skill的触发条件重叠。如果两个skill都声称处理“组件生成”，智能体就不知道该选哪个。解决办法是在描述文件里加优先级标记，或者干脆合并成一个skill。

第三步看描述文件的格式是否符合平台要求。不同平台对SKILL.md的解析规则不一样，有的要求特定字段名，有的要求特定标题层级。我遇到过因为标题用了##而平台只认#导致skill完全不生效的情况。这个只能对照平台文档逐项检查。

5.2 依赖安装失败的典型场景与解决

热词里“npx playwright install失败”出现频率很高，我专门整理过这类问题的排查表：

我的经验是，把这张表直接写进skill的安装说明里，让智能体在遇到安装失败时能引导用户按表排查，而不是干等报错。

5.3 上下文超限与加载策略调整

当skill的参考文档太多太大时，智能体加载后可能超出上下文限制，导致后面的内容被截断。表现是：skill前半部分的要求执行了，后半部分的规范没生效。

解决办法有两个。一是拆分skill，把一个大的“前端开发skill”拆成“组件生成”“样式处理”“表单逻辑”三个独立skill，按需加载。二是优化文档结构，把最关键的规范放在文档最前面，详细示例和边缘情况放在后面。这样即使被截断，核心要求也能保住。

我实测下来，单个参考文档控制在500行以内比较稳妥。超过这个量级，就应该考虑拆分了。

5.4 跨平台兼容性问题的处理

同一个skill在不同平台上表现不一致，通常是因为描述文件的解析规则不同。比如有的平台认YAML frontmatter，有的平台认Markdown标题，有的平台两者都认但优先级不同。

我的做法是写一份“最大公约数”版本的描述文件：用Markdown标题做主要结构，同时在文件头部加一段YAML frontmatter作为补充。这样无论平台认哪种格式，都能提取到关键信息。虽然看起来有点冗余，但兼容性最好。

另外，脚本部分尽量用跨平台的写法。比如shell脚本在Windows上可能跑不了，可以考虑用Node脚本替代，或者同时提供.sh和.js两个版本。

6. 进阶玩法：把skills变成团队知识资产

6.1 从个人使用到团队分发

个人用skills，怎么方便怎么来。但要在团队里推广，就得考虑分发和更新机制。我们团队现在的做法是建一个内部Git仓库，每个skill一个目录，用Git tag做版本管理。新人入职时，把仓库clone下来，按README配置好环境，就能直接用。

更新流程也走Git：有人改了skill，提PR，review通过后合并，其他人pull一下就能拿到最新版。这比在群里发文件靠谱得多，至少能追溯谁在什么时候改了什么。

6.2 用skills沉淀“踩坑经验”

skills最被低估的价值，是它可以承载那些“文档里不会写、但实际工作中一定会遇到”的经验。比如某个API在特定条件下会返回空数据、某个组件在低版本浏览器上有兼容问题、某个配置项改了之后需要重启服务才生效。

这些经验以前散落在聊天记录、代码注释、个人笔记里，新人来了得靠口口相传。现在把它们写进skill的“常见问题”部分，智能体在执行任务时会自动避开这些坑，新人也能通过阅读skill快速上手。

我现在的习惯是，每次踩到一个值得记录的坑，就顺手往对应skill的参考文档里加一条。积少成多，半年下来这些skill已经成了团队里最实用的“避坑指南”。

6.3 skills的测试与迭代节奏

skill写完之后不能就不管了。我的做法是每次用skill完成一个实际任务后，花两分钟回顾一下：输出是否符合预期、有没有触发不该触发的内容、有没有遗漏关键规范。如果有问题，当场改skill文件，而不是下次再说。

另外，我会定期（大概每月一次）把常用skill拿出来过一遍，删掉过时的规范、补充新的示例、调整触发条件。skills和代码一样，不维护就会腐烂。

提示：改skill的时候，建议在文件里加一个简单的变更记录，写清楚改了什么、为什么改。团队协作时这个记录能省很多沟通成本。

7. 我个人的一些实操体会

写了这么多，最后分享几个我实际用下来觉得最有价值的点。

第一个是skill的粒度宁小勿大。我一开始写了一个“全栈开发skill”，想把前后端规范全塞进去，结果触发条件怎么写都不对，加载后上下文也经常超限。后来拆成“前端组件”“API接口”“数据库操作”三个独立skill，每个都跑得很顺。粒度小，触发准，加载快，维护也简单。

第二个是示例代码比规范文字重要十倍。我试过只写规范不写示例，智能体生成的东西总是差那么点意思。后来每个规范后面都跟一段示例代码，输出质量立刻上了一个台阶。智能体对代码的模仿能力真的很强，给它一个好例子，比写十句“应该怎样”都管用。

第三个是不要追求一次写完美。我的第一个skill改了十几版才稳定下来。每次实际用的时候发现一个问题就改一点，慢慢就收敛了。一开始就想着写一个完美skill，大概率会卡在细节上迟迟发不出来，不如先写个能用的版本，边用边改。

第四个是把安装和排查步骤写进skill。热词里那么多“安装失败”的搜索，说明这是普遍痛点。与其让用户自己去搜解决方案，不如在skill里就把常见问题和排查命令列清楚。这个投入产出比很高，值得花时间做。

skills这个东西，说到底就是把“老师傅的经验”变成“可复制的模块”。它不神秘，也不复杂，但确实能解决实际问题。如果你还没开始用，建议从一个最小的场景入手，比如“生成符合规范的提交信息”或者“按模板写周报”，先跑通一个，找到感觉之后再扩展。