企业官网建设流程全解析

1. 从“skills”这个热词说起：它到底在解决什么问题

最近半年，不管是在技术社区还是开发者群聊里，“skills”这个词出现的频率高得离谱。你随便翻翻热搜词列表就能看到：claude code skills、codex skills、agent skills测试、好用的skills、skills开发、写论文的skills……一大堆。很多人第一次看到会懵——skills不是“技能”吗？怎么跟代码、AI、agent扯上关系了？

我刚开始接触的时候也犯嘀咕。后来用多了才明白，这里的skills指的是一套给AI编程助手（比如Claude Code、Codex这类工具）用的可复用能力包。你可以把它理解成给AI装的“插件”或者“技能卡”：AI本身是个通用大脑，但你要它干具体的活——比如按你团队的规范写React组件、自动生成数据库迁移脚本、或者把一段自然语言需求转成单元测试——光靠默认能力不够稳定。skills就是把这些特定场景下的操作流程、约束条件、输出格式打包成一个独立模块，让AI在需要的时候调用。

这玩意儿解决的核心痛点是一致性和可复用性。没有skills的时候，你每次让AI写代码都得把要求重复一遍：“用TypeScript、用函数式组件、样式用tailwind、错误处理要加try-catch……”说多了烦，而且AI偶尔会漏掉一两条。有了skills，你把这些规则写进一个文件里，AI每次执行相关任务时自动加载，输出质量立刻稳定下来。

适合谁看？三类人：一是日常用Claude Code或Codex写代码的开发者，想提升AI输出的可控性；二是团队技术负责人，想把团队规范固化到AI工作流里；三是对agent开发感兴趣的人，想理解skills的底层机制然后自己写。不管你是刚装好Claude Code的新手，还是已经在用Codex接入DeepSeek的老手，下面这些内容都能直接抄作业。

2. skills的核心机制与方案选型逻辑

2.1 skills的本质：给AI的“操作手册”而不是“知识库”

很多人容易把skills和RAG（检索增强生成）搞混。我一开始也以为skills就是往向量数据库里塞文档，让AI去查。实际用下来发现完全不是一回事。

RAG解决的是“AI不知道某个事实”的问题——比如你问它公司内部API的返回格式，它没学过，你得把文档喂给它。而skills解决的是“AI知道怎么做但做得不够好”的问题。举个例子：AI肯定知道怎么写Python函数，但它不知道你们团队要求所有函数必须加类型注解、必须用logging而不是print、异常必须包装成自定义错误类。这些规则不是知识，是操作规范。skills就是把这些规范写成AI能理解的指令集，在特定任务触发时注入到上下文里。

从实现上看，一个skill通常包含三部分：触发条件（什么时候用这个skill）、执行指令（具体步骤和约束）、输出模板（期望的格式）。有些高级的skill还会附带脚本或工具调用，比如自动运行lint检查。

2.2 为什么选skills而不是直接写prompt

你可能会问：我直接在对话里把要求说清楚不就行了？干嘛还要搞个skill文件？

我实测下来的感受是：短对话可以，长项目不行。当你一个会话要处理十几个文件、来回几十轮对话时，上下文窗口会被大量无关信息占满，你最开始说的那些规范早就被挤到边缘了，AI很容易“忘记”。skills的机制是在需要的时候才加载，不占用常驻上下文，而且可以跨会话复用。

另一个原因是团队协作。你把规范写在prompt里，只有你自己用。写成skill文件放到项目仓库里，团队所有人（以及所有人的AI助手）都能用同一套标准。新人入职第一天，装好Claude Code，skills自动生效，写出来的代码风格跟老员工一致。这个价值比省几句打字时间大得多。

2.3 Claude Code与Codex的skills生态差异

目前skills主要围绕两个工具生态：Anthropic的Claude Code和OpenAI的Codex。两者思路相似但细节不同。

Claude Code的skills更偏向文件系统驱动。你可以在项目根目录建一个.claude/skills/文件夹，里面放Markdown格式的skill定义。Claude Code启动时会扫描这个目录，根据当前任务自动匹配。官方市场里也有大量现成的skills可以直接下载，比如claude 国内安装skills 官方市场这个热搜词就说明很多人卡在安装环节。

Codex的skills则更依赖配置文件。你需要在codex.config或者项目级的配置里声明skill的路径和触发规则。Codex接入DeepSeek之后，skills的加载逻辑会走本地模型，响应速度更快但需要自己调优。热搜里codex无法加载组织设置、codex is ignoring 1 unrecognized configuration setting这些问题，多半是配置文件格式或路径写错了。

选哪个？我的建议是：如果你主要用Claude Code写前端或全栈，优先用Claude Code的skills生态，现成资源多。如果你在用Codex配合本地模型（比如通过LM Studio），那Codex的skills更灵活，但需要自己折腾配置。

3. 手把手搭建你的第一个skill：从零到可用

3.1 环境准备：Claude Code与Codex的安装避坑

在写skill之前，得先把工具装好。热搜里claude code安装、codex安装教程、codex安装包这些词热度很高，说明安装环节卡了不少人。我把自己在Windows和Ubuntu上装的过程捋一遍。

Claude Code安装（Windows）：

1. 确保Node.js版本在18以上，用node -v检查。
2. 通过npm全局安装：npm install -g @anthropic-ai/claude-code。
3. 安装完成后运行claude命令，会提示你登录。如果你在VSCode里用，搜claude code for vs code插件，装好后在设置里填API key。
4. 常见坑：your organization has disabled claude subscription access for claude code这个报错，通常是因为你的账号类型不对，需要用个人账号或者让管理员开通权限。

Codex安装（Ubuntu）：

1. Codex现在主要通过codex命令行工具使用，安装方式看官网文档。
2. 如果你要接入DeepSeek，需要在配置里指定base_url和api_key。热搜里codex接入deepseek的教程很多，核心就是改~/.codex/config.json。
3. codex登录失败的话，检查网络和API key权限。codex无法加载组织设置一般是配置文件里的org_id写错了。

注意：安装过程中如果遇到cc switch local proxy failed while handling codex endpoint /responses这类报错，大概率是本地代理端口冲突。检查一下有没有其他程序占用了同一个端口，换个端口号试试。

3.2 编写一个“React组件生成”skill的完整过程

假设我们团队用React+TypeScript+Tailwind，要求所有组件必须：函数式、有Props类型定义、默认导出、样式用className、错误边界用try-catch包裹。我来写一个skill。

首先在项目根目录创建.claude/skills/react-component.md，内容如下：

--- name: react-component-generator description: 当用户要求创建新的React组件时触发 trigger: - "创建组件" - "新建React组件" - "generate component" --- # React组件生成规范 ## 必须遵守的规则 1. 使用函数式组件，禁止class组件 2. Props必须用TypeScript interface定义，命名格式为`[组件名]Props` 3. 组件必须默认导出 4. 样式统一使用Tailwind的className，禁止内联style 5. 所有可能抛错的操作必须用try-catch包裹，catch里用console.error记录 ## 输出模板 ```tsx import React from 'react'; interface ComponentNameProps { // props定义 } const ComponentName: React.FC<ComponentNameProps> = (props) => { try { return ( <div className="..."> {/* 组件内容 */} </div> ); } catch (error) { console.error('ComponentName error:', error); return <div className="text-red-500">组件加载失败</div>; } }; export default ComponentName;

示例

用户说“创建一个用户卡片组件，接收name和avatar两个prop”，你应该输出符合上述模板的完整代码。

这个文件写好后，Claude Code在检测到“创建组件”相关指令时会自动加载。我实测下来，输出的一致性提升非常明显——以前十次有三次忘记加try-catch，现在基本不会漏。 ### 3.3 skill的触发条件怎么写才精准 触发条件是skill好不好用的关键。写得太宽，AI动不动就加载，浪费上下文；写得太窄，该用的时候不触发。 我的经验是：**用动词+名词的组合，避免单个关键词**。比如`trigger: ["创建组件"]`就比`trigger: ["组件"]`好，因为后者在讨论组件设计模式时也会误触发。 另外可以利用文件路径做触发。比如你写一个“数据库迁移”skill，可以设置`trigger_path: ["migrations/**"]`，这样只有当AI操作migrations目录下的文件时才加载。这个技巧在Codex里特别有用，因为Codex的配置文件支持glob模式。 还有一个进阶玩法：**条件触发**。比如“只有当用户明确说‘按团队规范’时才加载”。这适合那些约束特别严格、平时不想被干扰的skill。 ## 4. 实操全流程：从需求到skill落地 ### 4.1 需求分析：什么场景值得做成skill 不是所有事情都值得写成skill。我踩过的坑是：一开始兴奋，把什么都往skill里塞，结果维护成本比收益还高。后来总结了一个判断标准——**高频、有明确规范、容易出错**这三个条件同时满足才做。 高频：一周至少用三次。偶尔用一次的东西，直接写prompt就行。 有明确规范：规则能写清楚，不是“写得好一点”这种模糊要求。 容易出错：AI默认行为经常偏离你的期望，需要反复纠正。 举个例子：“写论文的skills”这个热搜词。写论文算高频吗？对研究生来说算。有明确规范吗？有——引用格式、章节结构、学术语气。容易出错吗？非常容易，AI经常编造参考文献。所以这个场景适合做skill。具体可以写一个“学术写作”skill，规定引用必须用真实可查的文献、禁止编造DOI、段落之间要有逻辑连接词。 ### 4.2 编写与调试：让skill真正生效 写完skill文件只是第一步，调试才是重头戏。我的流程是： 1. **最小化测试**：先写一个最简单的skill，只包含一条规则，看AI是否遵守。 2. **逐步加规则**：确认第一条生效后，再加第二条。每次加完都测试。 3. **边界测试**：故意给一些模糊指令，看AI会不会误触发或者漏触发。 4. **冲突测试**：同时加载两个skill，看规则冲突时AI怎么处理。 调试Claude Code的skill时，可以用`/skills`命令查看当前加载了哪些skill。Codex的话，在配置文件里加`debug: true`可以看到skill加载日志。 > 实操心得：skill文件里的规则不要超过7条。超过7条AI的遵守率会明显下降。如果确实有很多规则，拆成多个skill，用不同的触发条件区分。 ### 4.3 版本管理与团队共享 skill文件应该跟代码一起进Git仓库。我建议的目录结构是：

project/ ├── .claude/ │ └── skills/ │ ├── react-component.md │ ├── api-endpoint.md │ └── db-migration.md ├── src/ └── ...

每个skill文件头部用YAML frontmatter写元信息（name、description、trigger），正文写具体规则。这样既方便AI解析，也方便人阅读。 团队共享时，在README里加一段说明：“本项目使用Claude Code skills，请确保你的Claude Code版本在1.2以上，启动时会自动加载`.claude/skills/`目录。”新人照着做就行。 如果团队用Codex，把skill路径写进`codex.config`的`skills_dir`字段。热搜里`idea设置plugin中插件仓库地址`、`idea使用skills`这些词说明很多人想在IDE里集成，目前VSCode的Claude Code插件支持最好，JetBrains系列还在完善中。 ## 5. 常见问题与排查技巧实录 ### 5.1 skill不生效的排查清单 | 现象 | 可能原因 | 解决方法 | |------|----------|----------| | AI完全不遵守skill规则 | skill文件路径不对 | 确认文件在`.claude/skills/`目录下，扩展名是`.md` | | 偶尔生效偶尔不生效 | 触发条件太模糊 | 把trigger改成更具体的动词+名词组合 | | 规则冲突导致输出混乱 | 多个skill同时加载 | 检查trigger是否有重叠，拆分或合并skill | | Codex报`unrecognized configuration setting` | 配置文件字段名拼写错误 | 对照官方文档检查字段名，注意大小写 | | Claude Code提示组织设置问题 | 账号权限不足 | 换个人账号或联系管理员开通 | ### 5.2 那些热搜词背后的真实问题 翻一遍热搜列表，我发现几个高频问题值得单独说。 `cc switch local proxy failed while handling codex endpoint /responses`——这个报错我遇到过。原因是Codex在本地起了个代理服务，但端口被占了。解决方法：在配置里改`proxy_port`，换个不常用的端口比如`34567`。 `codex is ignoring 1 unrecognized configuration setting`——Codex的配置文件对字段名很严格。比如你写了`skill_dir`但正确写法是`skills_dir`，它就会忽略并警告。仔细对照文档，一个字母都不能错。 `your organization has disabled claude subscription access for claude code`——这个跟账号类型有关。个人版一般没问题，企业版需要管理员在后台开通Claude Code权限。 `cursor 怎么设置初始化默认打开时 windows 而不是agents`——这是Cursor编辑器的设置问题，跟skills无关，但说明很多人同时在用多个AI工具，配置容易搞混。建议每个工具单独建一个配置文件，别混在一起。 ### 5.3 进阶技巧：让skill更智能 用了几个月之后，我摸索出几个让skill更好用的技巧。 **技巧一：用变量占位符**。在skill模板里用`{{component_name}}`这样的占位符，AI会自动替换成实际值。这样同一个skill可以适配不同组件。 **技巧二：加负面示例**。除了告诉AI“应该怎么做”，再告诉它“不要怎么做”。比如“不要使用any类型”“不要用index作为key”。负面示例对纠正AI的坏习惯特别有效。 **技巧三：定期清理**。项目迭代后，有些skill的规则可能过时了。我每个月会花十分钟过一遍所有skill，删掉不再适用的，合并重复的。保持skill库精简，AI的遵守率反而更高。 **技巧四：用skill组合**。比如“创建API端点”这个skill可以调用“数据库迁移”skill和“错误处理”skill。Claude Code支持skill之间的引用，在文件里写`@include db-migration`就行。这样规则可以分层复用，不用每个skill都重复写一遍。 ## 6. 从skills看AI编程工具的未来走向 我用了大半年skills，最大的感受是：**AI编程工具正在从“通用助手”变成“可编程平台”**。以前我们只能被动接受AI的输出，现在可以通过skills主动塑造它的行为。这个转变有点像从“用现成软件”到“自己写脚本”——掌控感完全不一样。 热搜里`agent skills测试`、`skills开发`、`人工智能skills`这些词越来越多，说明大家已经不满足于“能用”，开始追求“好用”和“可控”。`langchain deep agents`、`agentpoison: red-teaming llm agents via poisoning memory or knowledge ba`这些偏研究的方向也在探索skills的安全性和鲁棒性。可以预见，未来skills会像npm包一样，形成一个庞大的生态——有人专门写skill卖钱，有人开源共享，有人做skill市场。 对于普通开发者来说，现在正是学skills的好时机。门槛不高，一个Markdown文件就能起步；收益很直接，AI输出质量立刻提升。我建议你从自己最常重复的那条指令开始，把它写成skill，用一周试试。大概率你会像我一样，再也回不去了。 最后分享一个我最近在用的skill——**“代码审查”skill**。规则很简单：每次我让AI审查代码时，它必须按“安全性、性能、可读性、测试覆盖”四个维度逐条检查，每个问题必须给出具体行号和修改建议。以前AI审查就是泛泛说“看起来不错”，现在能揪出`useEffect`缺少依赖项、`async`函数没加`try-catch`这种实际问题。这个skill我放在GitHub上了，搜“code-review-skill”就能找到。你也可以根据自己的需求改，比如加上团队特有的lint规则。 写skill这件事，投入产出比高得离谱。花半小时写一个，后面几个月都受益。如果你还没开始，今天就可以动手。