企业官网建设流程全解析

看到"skills"这个词最近在多个技术社区里被反复提及，从"前端开发skills"到"codex skills"再到"claude agent skills: a first principles deep dive"，我就知道这波AI Agent的技能热潮已经挡不住了。我在实际使用Claude Code和Codex跑项目的过程中，确实被Skills这种新范式震撼到了——它不是简单的提示词封装，而是把模型从"每次都要重新教一遍"的状态，解放成"看一眼就能自动进入工作流"的状态。这篇文章就把我这几周折腾Skills的完整心得、底层原理和踩坑记录都摊开讲，希望能帮你少走点弯路，真正把这项能力变成自己的"超级技能"。

1. Skills不是普通提示词：它到底改变了什么

先说个我自己的例子。我长期维护一个前端项目，代码规范、提交格式、测试覆盖率要求都写在一个几千字的文档里。以前用Claude Code干活，每次开新会话都得把那套规范重新粘贴一遍，模型倒是听话，可一旦项目复杂度上去，规范文档占用的上下文太长，真正干活的"注意力"就被挤掉了。后来我把这套规范做成了项目里的一个Skill，变化是质的：模型在需要修改代码时，会主动去加载这个技能包，按里面的流程一步步执行，而我只需要在关键决策点给个方向就行。

很多人会问，这不就是把提示词写进文件里吗？还真不是。区别至少有三个方面。

第一，注入时机完全不同。提示词是一上来就把所有规则塞进上下文，无论这轮对话用不用得上，模型都得背着这堆信息；Skills则是懒加载机制，平时只是"知道有这个技能存在"，只有当任务场景匹配时，系统才会把完整的技能正文加载进上下文。这相当于把"随身携带百科全书"改成了"需要查哪页再翻哪页"。

第二，描述与内容的分离设计。每个Skill都有独立的描述信息，这段描述是模型的"检索索引"，决定它什么时候该启用这个技能。也就是说，模型先读的是技能的"简历"，觉得应聘者合适，才把"完整作品集"拿出来看。这就让技能的触发变得非常精准——描述写得好的Skill，几乎不会误触发，也不会漏触发。

第三，可维护性和复用性。提示词是写一次用一次的消耗品，Skills则是可以反复迭代的资产。我改造前端规范Skill的时候，只需要改那个SKILL.md文件里对应的章节，下一次调用自动就是新逻辑，不需要在旧会话里翻了半天再补一句"前一个规则作废"。

顺着这个思路往下走，"superpower skills"、"skills大全"这些热词背后其实是在说一件事：大家已经不再满足于"这个模型聪明不聪明"，而是开始通过Skills把聪明用在刀刃上——让模型在正确的时间、用正确的方法、做正确的事情。这也是为什么我看完社区里那些号称"打开新世界"的反馈后，会觉得眼下的Skills生态，本质上是在给AI做"职业培训"，让通用模型变成某一领域的熟练工。

2. 底层机制拆解：Claude与Codex是如何把技能喂给模型的

要真正用好Skills，光知道"它很神奇"是不够的，还得理解各家实现机制上的差异。目前主流的两套体系，一套是Claude这边的Agent Skills，一套是OpenAI Codex引入的Skills机制，两者思路有交集，但实现细节差别很大。

Claude的Agent Skills走的是文件系统探测 + 按需加载的路子。你会在项目或全局目录下看到一个SKILL.md文件，它通常放在skills/或者./claude/skills/这样的约定目录里。当模型开始干活时，它并不会一次性把所有SKILL.md都读进来，而是在理解用户请求后，根据每个Skill的description字段去判断"这个任务是不是该用这个技能"。一旦命中，系统就把整个SKILL.md丢进上下文，里面可以包含详细的步骤、示例代码、验收标准，甚至还能引用同目录下的脚本和资源文件。

我实际测试下来，Claude对Skill体量的容忍度极高。一个SKILL.md写到3000行都没有问题，因为它只有在被调用时才会占用上下文，平时只是个"档案条目"。

再来看Codex这边，它的Skill机制更偏向检索型。Codex通过AGENTS.md文件体系管理项目知识，而Skills部分则类似一个检索库，系统根据任务关键词去匹配技能内容，匹配到之后把相应段落注入到上下文中。这套设计的好处是它能处理数量巨大的技能集合——假如你往仓库里塞了上百个技能文档，Claude的"看简历"模式会先挑花眼，而Codex的检索模式可以快速定位。

我整理了一张对比表，方便你直观感受差异：

注意一个容易迷惑的地方：MCP（Model Context Protocol）和Skills的关系。很多人把二者对立起来，其实它们是搭档。MCP解决的是"模型如何调用外部工具和实时数据"，比如查数据库、调接口、读文件；Skills解决的是"模型如何组织行为和思考步骤"，比如按规范走完一段代码审查流程。我的经验是，可以先做一个Skill来定义流程，然后在SKILL.md里写明"执行过程中调用某某MCP工具获取数据"，两者协同效率最高。

另外，Skill的加载时机和上下文预算也有讲究。Claude在模型判断"这个任务要用技能A"之后，会暂停当前推理，先把A的正文加载进来，再继续推理。这看起来多了一步，但实测下来对响应速度的影响很小，原因是模型的上下文窗口足够大，一次加载几百行技能文本也就几秒钟的事。真正需要担心的是另一个问题：如果技能描述写得太过宽泛，导致模型在无关任务上也频繁触发加载，那既浪费token又会打断思路。这个坑后面专门讲。

3. 手写第一个SKILL.md：从零构建专属技能包的完整过程

理论说完了，直接上手。我习惯把技能分成两类：一类是全局技能，放在~/.claude/skills/下，任何项目都能用；另一类是项目级技能，放在项目的.claude/skills/下，只有这个项目能访问。这个区分很关键——全局技能放通用方法论（代码审查、周报写作），项目级技能放业务上下文（这个项目的部署流程、接口签名规范）。

下面以一个最常用的场景——"前端代码审查"Skill为例，带你走一遍完整创建过程。

第一步，创建目录结构。我用zsh做示例：

mkdir -p ~/.claude/skills/frontend-code-review touch ~/.claude/skills/frontend-code-review/SKILL.md

这里有个命名习惯：目录名建议用短横线连接的英文，比如frontend-code-review，不要用中文或空格，否则部分工具解析路径会出问题。

第二步，写SKILL.md的YAML frontmatter。这部分是技能的"门面"，一定要认真写。

--- name: frontend-code-review description: 对前端代码进行系统性审查，检查React组件性能、样式规范、可访问性、依赖安全等维度，输出结构化评审报告。适用于代码提交后的Review场景。 ---

description就是前面说的"简历"，它决定了模型认不认得这个技能。我写description的经验是：至少包含三要素——这个技能干什么、在什么场景用、它和别的技能有什么区别。如果你发现两个技能的description描述重叠，模型就很容易混淆，触发错误的那个。比如你还有个"代码重构"技能，那就要在description里明确写"本技能只做审查与报告输出，不直接修改代码"，避免模型把评审当成重构来执行。

第三步，写正文。这是核心，结构上我推荐包含四块内容：适用边界、执行流程、评审维度、输出模板。

# 前端代码审查技能 ## 适用边界 - 仅用于审查代码质量，不自动修改代码 - 覆盖语言：TypeScript / JavaScript / React / Vue - 不适用于后端代码、数据库脚本 ## 执行流程 1. 读取待审查文件的完整内容 2. 逐文件进行静态分析，重点关注性能瓶颈和状态管理 3. 检查样式代码是否违反项目Prettier/ESLint配置 4. 检查可访问性：图片是否缺失alt、交互元素是否有键盘支持 5. 汇总所有发现，形成分级报告 ## 评审维度清单 - 性能：React使用memo/useMemo的必要性、大数据列表是否虚拟化 - 状态：是否直接修改props、副作用是否放在合适的生命周期 - 样式：是否使用魔法数字、类名是否符合BEM规范 - 安全：是否存在XSS风险（dangerouslySetInnerHTML滥用） - 依赖：是否有已知漏洞版本（参考npm audit结果） ## 输出模板 对每个问题输出： - 严重级别：Critical / Warning / Suggestion - 文件与行号 - 问题描述与实际代码片段 - 修复建议（可执行的具体改动描述）

第四步，测试加载。在Claude Code里输入/skills，如果能列出frontend-code-review这个名字，说明目录和frontmatter解析成功。然后随便写一行带Bug的React组件，再输入"帮我对这个组件做代码审查"，看看模型是否自动加载了技能并按照流程输出。如果你发现模型回答得像一个普通工程师发散评价，而不是按模板给报告，八成是description写得不到位，或者技能正文的指令不够结构化。

这个过程中有一个特别妙的细节：Skills正文里还可以插入"示例对话"。我在技能末尾放了两组示例，一组是"好输出"的样子，一组是"坏输出"的样子。实测下来，这比任何抽象描述都管用，模型输出格式的稳定性直线提升。你可以理解为给模型看了"样板间"，它照着装修自然不容易跑偏。

4. 安装与选型实操：官方市场、社区仓库和离线部署的取舍

我猜你刷热搜时看到过"codex好用的skills"和"claude 国内安装skills 官方市场"这类词，说明你已经不满足于手写，想直接抄现成的作业。这个思路没错，但Skills的安装渠道比较分散，选不好容易装一堆垃圾技能。

目前的获取渠道主要有三类。

第一类是官方市场与官方仓库。Anthropic官方维护了Claude Skills的开源仓库和官方市场，里面的技能质量相对有保障，比如文档处理、数据分析这些基础技能，经过了比较充分的测试。不过官方市场的技能偏向通用场景，针对特定业务（比如你公司的私有协议解析）基本没有覆盖。安装方式很简单，在Claude Code的交互界面输入：

/plugin install 技能名称

或者直接在配置文件的skills路径下执行git clone。

第二类是社区仓库。GitHub上有大量打上awesome-claude-skills标签的聚合仓库，比如社区里传的"superpower skills"就是一套含几十个技能的高质量合集。下载这类技能包的时候，我建议重点看三样东西：仓库最近更新时间、README里的使用案例、以及SKILL.md的frontmatter是否规范。我见过不少把Prompt硬改成SKILL.md格式的"伪技能"，本质上只是换了个壳，描述写得含糊不清，实际用起来效果很差。

第三类是离线安装。"skills安装包下载"这个词条对应的就是这类需求。很多团队在生产环境里无法直连外部市场，需要在内网离线部署。方法也不复杂：在一台有网的机器上把这些Skills目录整个打包，传到内网机器后放到~/.claude/skills/下。这里有个隐藏的小问题——Skills引用的一些外部依赖（比如特定的Python脚本）打包时容易漏掉，所以我每次离线部署前会逐个检查技能目录里是否有requirements.txt、package.json等依赖清单，有的话一起打包并植入安装说明。

统计下来，我日常用的Skill数量长期保持在15个左右。曾经有一阵我见了技能就想装，很快就发现自己陷入了"技能膨胀"——模型每次权衡该用哪个技能都要犹豫半天，有些技能description互相踩踏，反而拖慢了响应速度。后来我立了一条规矩：一个技能如果在两周内没有被实际触发过，就该归档或者删掉。这跟打扫房间是一个道理，东西少了，每件才更管用。

另外提醒一个细节：安装完新技能后，最好重启一下Claude Code会话，让它重新扫描技能目录。有时候你明明放对了文件，但列表里就是不出现，十有八九是缓存没刷新。手动清缓存的方法是找到~/.claude/skills/_cache这类目录删掉，再重新打开工具。

5. 高频踩坑与兼容性排查：我走过的弯路你都别再走

Skills用起来顺手，但它毕竟是个新东西，坑也不少。我把自己踩过的、以及在社群里看别人踩过的高频问题整理了一下，按严重程度排个序。

先说一个最隐蔽的坑：技能目录的命名与frontmatter里的name不一致。有一次我把目录命名为code-review-ts，但frontmatter里的name写的是code-review，结果模型加载技能后，在对话里展示的技能名始终是目录名，而引用内容时却按frontmatter来，逻辑就乱了。后来我统一了规范：目录名、frontmatter的name字段、description里提到的技能自称，三者必须完全一致。

再一个坑是描述过于宽泛导致的误触发。我写过一个docx格式转换的技能，description写的是"处理常见文档格式"，结果模型帮用户写周报时也把这个技能加载进来了，白白占了不少上下文。后来我把description改成"仅将Markdown/HTML转换为Docx，不处理PDF与XLSX"，误触发率立刻降至零。这里的关键是，负向边界信息一定要写进description，"不做什么"有时候比"做什么"更能帮模型做判断。

还有一个容易忽略的实际问题：技能的版本管理。我一开始是把SKILL.md放在个人目录里随手改，改了几版之后完全记不清哪个版本的流程在生效。后来我引入了版本号机制，在frontmatter里加入version: 2.1.0这样的字段，同时在正文末尾维护变更日志。这么做还有个额外的好处：当Claude说"我找不到这个信息"的时候，你能快速确认是不是正在用旧版本的技能。

最后是兼容性问题。不同编码环境下，中文乱码是最常见的事——我发现部分工具在读取SKILL.md时，对UTF-8 with BOM和纯UTF-8的处理不一致，如果文件带BOM，frontmatter解析可能失败。我的做法是：所有SKILL.md一律用无BOM的UTF-8保存，并且用命令行确认编码格式：

file SKILL.md

如果输出中看到with BOM字样，就用sed -i '1s/^\xEF\xBB\xBF//' SKILL.md去掉它。

还有一个热词叫"自动挖洞skills"，其实只说明了一个现象：Skills的应用范畴已经远远超出了编程任务，连渗透测试社区都在做自己的技能包。但我不建议在这个方向上投入太多精力，一方面法律风险非常高，另一方面这类技能在模型侧本来就有安全过滤，实际跑起来效果也打折扣。做AI能力的正向应用，收益和持续性都强得多。

6. 让模型"带着方法论干活"：Skills在复杂任务中的实战价值

Skills最大的价值，其实是在那些步骤多、流程长、容错率低的任务里发光。我自己做数据迁移的时候感受特别深，那项工作需要把旧系统的MySQL表结构迁移到新的PostgreSQL数据库，涉及的步骤包括字段类型映射、约束定义、外键关系重建、还有基于业务规则的清洗逻辑。以前用Claude干这种活，我必须在每次对话里把步骤重新梳理一遍，中间一旦换了会话就得重新教。后来我直接把整个迁移流程写成了一个Skill：

--- name: db-migration-pgsql description: 将MySQL数据库迁移到PostgreSQL。处理表结构转换、字段类型映射、索引与约束重建、数据清洗规则。仅适用于关系型数据库，不适用于MongoDB等非关系型库。 ---

正文里记录了完整的工作流，甚至包括不同数据类型在MySQL和PostgreSQL之间的等效映射表。调用这个Skill之后，模型的行为方式立刻从"你说一步我做一步"变成了"按标准工作流推进，遇到偏离库标准的地方暂停确认"。这种体验用一句通俗的话说：原来你是在指挥一个实习生，现在你给实习生发了一本SOP手册，他只在真正拿不准的时候问你。

这个模式特别适合团队内部推广。比如你们团队有一个"发布上线检查单"，涵盖了构建、跑测试、打镜像、灰度发布、监控告警配置这些环节。把它做成Skill之后，任何成员发起"准备上线"的请求，模型都会严格按照这个Skill的流程走，该执行的命令执行，该确认的配置确认，遗漏一个步骤模型会主动提醒。

我后来还把这种方式延伸到了周报写作和数据分析上。周报Skill里我定义了固定的几个维度：本周产出、数据变化、风险事项、下周计划。模型每周自动按这个结构组织，我再补充具体细节就好。数据分析Skill里我规定了数据清洗的每一步必须记录操作日志，方便后续审计。这些听起来都是小事，但正是这些"小事"，把我从重复指挥模型的过程中解放出来了。

说到这我要特别提醒一下：不要指望一个Skill包治百病。我见过有人试图做一个"万能超级技能"，里面塞了开发、运维、写作、设计，结果模型每次面对任务都要做一轮极其纠结的筛选，响应速度肉眼可见地变慢。Skill的正确打开方式，是把它做成单一职责、内聚性强的小工具。十个职责清晰的小技能，远比一个包罗万象的巨无霸技能好用。

从"skills推荐"到"skills大全"再到"今天学会了skills，打开新世界"，搜热词的这批人里，不少人正处在从"被AI辅助"到"训练AI为自己所用"的转变节点上。Skills就是这座桥。我在实践中学到的最重要的一课是：真正厉害的Agent，不是模型本身厉害，而是你通过Skills让它做事的方式足够系统。这跟带团队一模一样——给成员足够清晰的流程和标准，他就能稳定交付；流程含糊，天才也得靠运气。

我最近在做的项目，已经习惯在开工之前先花十几分钟想一想："这个任务能不能沉淀成一个Skill？"如果答案是肯定的，那就先做技能，再做任务。短期看好像多花了时间，长期算下来，每一次同类任务都被加速，而且质量越来越稳定。这一开始只是我的个人习惯，后来变成了团队的工作方式，效果确实立竿见影。如果你也打算入坑Skills，建议你从自己的工作里挑一个高频、重复、步骤多的场景，花一个下午把技能写出来，跑通一次。相信你很快就会理解为什么大家都说"打开新世界"了。