企业官网建设流程全解析

最近我的信息流几乎被同一个词刷屏了：Skills。从 Claude Agent Skills 到 Codex Skills，从 GitHub 上成堆的 skills 仓库到各种“打开新世界”的安装教程，这个看似普通的英文单词，正在成为 AI Agent 生态里最热的基础设施。老实说，我一开始也把它当成又一个营销概念，直到自己动手写了一个 skill、跑通了一条完整流程之后，才意识到这东西跟普通 prompt 的差距有多大。

这篇东西不打算复读官方文档。我花了几周时间把主流的 skills 方案都摸了一遍，包括 Claude 系的 Agent Skills、Codex 的 skills、以及社区里大量第三方分享的技能包，踩了不少坑，也总结出了不少规律。我会从第一性原理讲清楚 Skill 到底是什么、和 Prompt/插件差在哪，再手把手带你从零开发一个能用的 skill，最后把安装、下载、排查的完整路径给你铺平。适合的人群很明确：正在玩 Claude Code、Codex CLI 这类编码智能体的开发者，想把自己的工作流沉淀成可复用资产的产品经理和设计师，以及那些看到“skills 大全”“skills 下载平台”就心痒但不知道怎么入手的新手。读完你至少能独立完成一个 skill 的开发、安装和调优。

1. Agent Skills 到底是什么——先搞懂这个 Skill 不是你想的那个 Skill

1.1 Skill、Prompt 与 Plugin：三个容易混淆的概念

我第一次听到“Agent Skills”时，第一反应是“这不就是强化版 prompt 吗”。深入用下来才明白，这个理解偏差恰恰是很多人学不会 skill 开发的根源。

从第一性原理看，Skill 是介于 Prompt 和 Plugin 之间的一种新形态。Prompt 是静态的：你把指令写在文本里，交给模型执行，它没有任何自我管理能力，也不关心你应该在什么时机被调用。Plugin（或者说 MCP 工具）是外向的：它定义的是 Agent 可以调用的外部能力接口，比如读写数据库、调用 API，重点是“能连接什么”。而 Skill 是内向的：它封装的是“如何把一件事做好”的完整方法论，包含背景知识、操作步骤、质量标准、甚至配套脚本。

拿做饭来类比。Prompt 就像随手写在一张便签上的菜谱：“放油，炒菜，加盐，出锅”。它管用，但信息密度低，换个人可能做出完全不同的东西。Plugin 是厨房里的锅和灶，它们是工具，本身不知道怎么做菜。而 Skill 是一本完整的菜谱书：有食材清单、火候控制、翻锅时机、装盘标准、常见翻车案例。它把一位老师傅脑子里的隐性经验，变成了 Agent 可以直接照做的显性流程。

这个区别决定了 Skill 的核心价值：它不是让 Agent 多一个“能做什么”的工具，而是让 Agent 在特定任务上“做得像专家”。社区里那些被冠以“superpower skills”之名的东西，本质上就是把某个垂直领域的专家流程拆解、固化成技能包。这里有三层含义值得拎出来说：首先，Skill 是可检索的，Agent 会在每次对话前根据用户意图匹配技能描述；其次，Skill 是可执行的，它能带脚本、带模板、带校验工具；最后，Skill 是可共享的，一个写好的技能包可以像开源软件一样分发和复用。这三点是普通 prompt 永远做不到的。

1.2 Skill 的标准目录结构与运行机制

要理解 Agent 是怎么使用 Skill 的，先看它的文件结构。目前主流实现虽然细节不同，但骨架高度统一，一个标准的 skill 长这样：

my-skill/ ├── SKILL.md # 技能入口，包含元信息和操作指引 ├── scripts/ # 可执行脚本，通常用 bash 或 python 编写 ├── assets/ # 静态资源，比如模板文件、参考图片 └── references/ # 参考资料，比如领域知识、示例代码

SKILL.md是灵魂。它由两块组成：开头的 YAML frontmatter，用来声明技能的 name 和 description；后面的 Markdown 正文，用来写具体的执行流程、约束条件和输出格式。

运行机制值得多说两句。当用户发起一个任务时，Agent 会在上下文窗口里扫描所有可用 Skill 的 frontmatter，根据 description 与当前任务的语义相似度做检索，然后只把命中的 Skill 正文加载进上下文。这是一个典型的“渐进式披露”设计：一个技能包可能有几千行内容，但 Agent 不会全量读入，只会按需加载命中的那部分。

检索到技能之后，Agent 会按照 SKILL.md 里的指引逐步执行，需要处理数据或跑验证时可以调用scripts/下的脚本。这个设计把大模型的推理能力和传统脚本的确定性执行能力缝合在了一起。模型负责判断“该怎么做”，脚本负责把“做得对不对”落到实打实的结果上，彼此互补。

1.3 为什么各大厂商都在押注 Skills

站在 2025 年这个时间点回头看，各家厂商押注 Skills 并不是偶然，背后有几条非常实际的逻辑线。

第一是上下文窗口的瓶颈。模型的上下文再大也是有限的，你不可能把一个专家库全塞进去。Skill 的渐进式披露机制让 Agent 可以用很小的默认上下文维持大量可调用能力，只在需要时“翻出”对应那本手册。

第二是能力的确定性。模型单独跑复杂流程容易发散，但把流程拆成“模型做判断 + 脚本做执行”的模式后，关键步骤有了确定性保障。比如让技能里的 Python 脚本去验证代码格式、检查数据完整性，这事比让模型凭感觉判断靠谱得多。

第三是生态锁定效应。Skill 格式一旦成为事实标准，开发者沉淀的技能资产就会围绕着某个 Agent 框架越积越多，迁移成本随之拉高。所以 Anthropic、OpenAI 甚至一批第三方客户端都在积极拥抱这个格式，大家都明白，谁掌握了技能市场，谁就掌握了 Agent 生态的上游。

2. 从 0 到 1 开发第一个 Skill——完整实操记录

2.1 环境准备与项目初始化

动手之前先把环境准备好。我用的是两套主流方案：Claude 系和 Codex CLI，两者对 Skill 的支持都在持续迭代中，但底层逻辑一致。

Claude 系目前支持多种加载方式：桌面客户端可以在设置里指定一个全局技能目录，通常是~/.claude/skills/；项目级开发则把技能放在当前项目的.claude/skills/目录下；如果你走 API 路线，SDK 里也有专门的 skills 参数用来挂载技能包。Codex CLI 的思路类似，默认读取~/.codex/skills/目录。还有像 Reasonix 这类图形化客户端，也在各自的设置面板里加了 skills 管理入口，本质上都是帮你往这些目录里放文件夹。

我建议新手先用一个独立测试项目练手，别一上来就往全局目录里塞。原因很简单：项目级目录的加载链路更短，出了问题容易定位，而且你在项目里改技能配置，可以立即通过对话验证，不需要反复重启客户端。初始化命令就是最朴素的创建目录：

mkdir -p ~/.codex/skills/changelog-generator/{scripts,references}

我在本地建了一个叫changelog-generator的技能，功能是读取 git 提交记录自动生成规范化的 CHANGELOG。这个需求足够简单，又能完整覆盖 Skill 开发的全部环节，很适合作为第一个练手项目。

2.2 写 SKILL.md 的正确姿势

技能包的地基是SKILL.md。很多新手在这一步栽跟头，不是因为不会写 Markdown，而是不理解 frontmatter 里的 description 字段有多关键。

Description 是 Agent 唯一用来判断“这个技能该不该被调用”的依据。写得太宽泛，比如“生成变更日志”，Agent 会在各种不相关的场景下激活它，浪费上下文还干扰主任务；写得太窄，比如“仅用于 node 项目且只处理 semantic-release 的 git 日志”，Agent 又会漏召。我实践下来比较稳的写法是：点明任务类型、描述适用场景、带上输入输出格式提示。下面是我那个技能的 frontmatter：

--- name: changelog-generator description: 根据 git 提交历史生成或更新 CHANGELOG.md。适用于需要向用户交付版本变更记录的场景，输入是 git 仓库目录，输出是规范化的 Markdown 格式变更日志，包含功能新增、Bug 修复、破坏性变更三个分类。 ---

正文部分我按三个层次写。第一层是执行流程：先跑git log --oneline -30拿到最近提交，再按 conventional commits 规范把提交归类到新增、修复、破坏性变更里。第二层是输出模板：给出 CHANGELOG 的 Markdown 结构，包括版本号、日期、三类清单的格式。第三层是质量红线：明确告诉模型哪些情况必须标注破坏性变更，哪些提交应该被过滤掉。这样模型拿到技能后，每一个动作都有标准可依。

2.3 脚本与资源文件的最佳实践

SKILL.md 解决“怎么做”的问题，scripts 目录解决“怎么保证做对”的问题。我的建议是：凡是能通过脚本确定性完成的工作，就不要让模型自由发挥。

写脚本有几个实操要点。第一，脚本入口尽量用命令行参数接收输入，而不是依赖标准输入流。原因很实际：Agent 调用脚本时走的是 shell 命令，参数传递比交互式输入可靠得多。第二，一个脚本只做一件事，宁可拆成三五个小脚本，也不写一个能做所有事的上帝脚本，这样 Agent 可以根据 SKILL.md 的指引按需调用。第三，涉及路径的地方统一用相对当前技能目录的路径，避免 Agent 在不同工作目录下调用脚本时路径失效。

我给自己技能写了个归类脚本，用来校验模型生成的 CHANGELOG 分类是否正确：

#!/usr/bin/env python3 import re, sys def classify(commit_msg): if re.match(r'^feat', commit_msg): return 'Feature' if re.match(r'^fix', commit_msg): return 'Bugfix' if re.match(r'^break', commit_msg) or 'BREAKING' in commit_msg: return 'Breaking' return 'Other' if __name__ == '__main__': msgs = [line.strip() for line in sys.argv[1:]] for m in msgs: print(f"{classify(m)}\t{m}")

脚本不算复杂，但它让 Agent 在输出结果前可以先跑一遍校验：生成完 CHANGELOG 后，把每条提交喂给脚本，看分类是否匹配。这个模式是 Skill 相对 Prompt 最大的优势——确定性校验闭环。

2.4 开发期最容易踩的坑

第一个坑是SKILL.md 的 YAML frontmatter 写错。缩进用了 Tab、冒号后没加空格、description 中英文混合导致编码异常，都会让技能静默失效。我遇到过最隐蔽的一次，是文件被编辑器保存成了带 BOM 的 UTF-8，Agent 直接读不出元信息，整个技能形同虚设。

第二个坑是脚本没有可执行权限。在 Linux 和 macOS 下，Agent 调用脚本走的是直接执行路径，chmod +x这一步忘了，Agent 就会在日志里报 permission denied。Windows 上还要特别注意换行符，CRLF 会导致 shebang 失效。

第三个坑是description 写得太宽泛导致技能被误调用。我之前给一个前端代码审查技能写了“审查代码质量”，结果每次对话只要提到代码，Agent 就把整个技能加载进来，占了大量上下文还什么都不做。后来把描述改成“审查 React 组件的可访问性与渲染性能，适用于提交 PR 前的代码自查”，误调用直接消失。

3. Skills 的获取与安装——市场、下载与版本管理

3.1 现在到底该去哪里找 Skills

社区里很多人在问“skills 下载平台有哪些”“skills 大全哪里找”。我整理了一下现在主要的分发渠道，各有优劣。

官方渠道是最稳妥的起点。Anthropic 官方发布了一批维护良好的 skills，覆盖了 PDF 处理、PPT 生成、文档问答等常见场景，质量稳定、兼容性有保障。Codex 的官方技能包也类似，直接看对应的官方文档就能找到入口。官方技能的优点是格式规范、文档齐全，缺点是有时候太“通用”，不够贴合你的具体工作流。

GitHub 是社区技能的主阵地。搜索awesome-claude-skills、skills-marketplace这类聚合仓库，一次能找到几百个技能。GitHub 上的技能质量参差不齐，但好处是能看到源码、提交记录和 issue，你在用之前就能判断这个技能是不是有人在维护。判断方法后面我会细说。

第三方分享站是最近冒出来的新模式。有些社区把技能包打包成可下载的资源站，类似于软件下载站的定位，热度很高。但我要提醒一句：这类的审核水平不一，过期、格式错误、甚至夹带恶意脚本的情况我都见过。下载安装包的优先级，永远是官方大于 GitHub 源码仓库，最后才考虑打包站。

3.2 Claude 系 Agent 的 Skill 安装流程

安装技能本质上就是把技能文件夹放到 Agent 能扫到的目录。流程分三步：

第一步，确定安装位置。想全局生效，放到~/.claude/skills/；只想在某个项目里用，放到项目根目录的.claude/skills/。第二步，把下载或克隆的技能文件夹整体拷进去，注意不要多套一层目录，要让SKILL.md直接位于技能文件夹的根目录下。第三步，验证安装结果。

验证这一步最重要。Claude 桌面客户端和 Claude Code 都支持查看已加载技能的命令，你可以用类似/skills之类的指令列出当前会话内可用的技能列表。如果列表里出现了你的技能，说明安装成功。接着发一条触发该技能的任务，观察 Agent 是否真的调用了它。这里有个细节：安装新技能后最好重启一下客户端或新开会话，Agent 的技能索引通常只在会话初始化时刷新，连续对话中途注入的技能不会被感知到。

3.3 Codex CLI 的 Skills 安装方式

Codex CLI 的安装逻辑跟 Claude 系非常像，默认读取~/.codex/skills/目录。你可以用软链接把一个仓库里的技能目录指过来，这样拉取更新时不用重复拷贝：

ln -s ~/workspace/codex-skills/pdf-expert ~/.codex/skills/pdf-expert

Codex 对技能目录的命名同样敏感，文件夹名和SKILL.md里的 name 字段最好保持一致，避免索引错乱。安装完成后，直接在会话里触发对应场景，观察它的执行轨迹里有没有出现技能相关的步骤。Codex 的日志输出比较详细，你能看到它具体读了哪个文件、哪段指引，这对排查非常有用。

在团队协作场景里，我推荐直接把技能目录放进 git 仓库管理。项目组成员克隆代码后，每个人本地的~/.codex/skills/都可以通过初始化脚本自动挂载，技能版本跟着代码库走，不再出现“我机器上是新版、你机器上是旧版”的混乱。

3.4 下载技能的避坑指南与版本更新

网上“skills 安装包下载”的热度很高，但这是一片名副其实的雷区。我的经验是，拿到任何一个技能包，先做三件事。

第一，检查结构完整性。SKILL.md必须在根目录，缺失这个文件意味着技能无法被识别；scripts 目录可有可无，但一旦存在，脚本必须能通过基础语法检查。第二，通读 frontmatter 和 README，确认技能的授权协议和适用性，有些技能包明确写了只支持特定框架的特定版本，强行安装就是给自己埋雷。第三，搜索rm -rf、curl | bash这类危险模式，不排除有恶意技能借机在本地执行破坏性命令。开源社区总体是可信的，但“先验证再执行”这条底线不能丢。

版本更新方面，GitHub 仓库的技能可以直接git pull更新；从打包站下载的就没有什么好办法了，只能定期回源站点看更新记录。我的建议是：核心常用技能尽量从 GitHub 获取并固定一个版本号，更新前先看 changelog，不要盲目追新。技能包也是软件，新版本可能引入兼容性回归，稳定反而比新鲜更重要。

4. 高频实战场景拆解——前端、论文、分镜与安全检测

4.1 前端开发 Skills：把团队规范固化进 Agent

“前端开发 skills”是搜索热度最高的方向之一，原因很直白：前端项目规范多、重复劳动多、审查点多，这些东西天然适合固化成技能。我见过最好的一个前端审查类技能，把一整个团队半年踩过的坑浓缩进了 SKILL.md。

这类技能的正确设计思路是“审查检查清单化”。拿 React 项目举例，技能里可以明确要求 Agent 逐个检查：组件的 props 是否做了类型定义、事件处理函数是否泄漏了依赖、列表渲染是否有稳定的 key、图片资源是否声明了宽高避免布局偏移。每一项都配上判断标准和修改建议，Agent 照着清单走一遍，相当于一个自动化的资深 Code Review 助理。

比起从零写代码，我更推荐把这类技能定位成“规范执行的裁判”。在 SKILL.md 里明确输出格式：问题文件路径、严重级别、问题描述、修改建议。这样不管模型多强，输出都是团队约定好的结构化格式，可以直接喂给后续的工单系统。

4.2 写论文的 Skills：Codex 在学术场景的正确姿势

“codex 写论文的 skills”这个热搜背后，是一大批把 AI 当作学术写作协作者的用户。学术写作的特点是结构高度模板化，从引言、方法、结果到讨论，每个章节都有约定俗成的逻辑要求和语言风格，非常适合用技能封装。

我给一个正在写期刊论文的朋友搭过一套写作技能，核心思路是分章节处理。技能里为每个章节单独写了指引和要求：引言部分必须包含研究空白、研究问题、贡献点三个要素；方法部分要按可复现的标准写清楚数据来源和处理流程；结果部分只陈述事实不展开解释；讨论部分要回扣引言中的研究问题。Agent 不需要一次生成全文，而是按照技能拆分的阶段，每轮只产出一个小节，配合模型自查，质量稳定得多。

这里有个非常关键的技巧：学术写作技能里一定要内置“反幻觉清单”。模型在写参考文献和实验数据时容易一本正经地编造，技能里要明确写死一条红线——所有引用文献必须来自用户提供的资料，任何无法确认来源的信息一律标注待核验。这一条能避免学术诚信层面的严重事故。

4.3 分镜与内容创作 Skills：把创意工作流模板化

“分镜 skills 下载”热度很高，但很多人下载了模板却做不出效果，问题不在技能本身，而在于不理解分镜技能的设计逻辑。分镜看起来是创意工作，但创意之外有大量结构化内容：景别、运镜、时长、台词、画面描述、转场方式，这些都是可以被模板约束的字段。

一个合格的分镜技能，应该把“讲故事”和“写表格”分开。SKILL.md 里先定义叙事框架：起承转合、情绪曲线、每场戏的核心信息；然后通过一个脚本把叙事输出成标准的分镜表，每一行都包含镜号、景别、画面内容、台词、预计时长。这样 Agent 的大脑负责创意，脚本负责格式，两者协作产出的分镜表可以直接交给拍摄团队使用。

内容创作类的技能普遍有个规律：它们不是在让 AI“替你创造”，而是在让 AI“按你的审美框架来组织内容”。在技能开发时，把自己的审美偏好、常用术语、格式习惯全部写进 SKILL.md 里，产出的稳定性和个人风格一致性会远超裸奔的对话式生成。

4.4 自动化安全检测的 Skills：一个需要边界意识的领域

“自动挖洞 skills”这个热搜我犹豫了很久要不要写，最后还是决定讲——因为自动化漏洞挖掘本来就是安全行业里一个正当且成熟的实践方向，国内外大量企业都在用自动化工具做安全自查。但这里有一条绝对不可逾越的红线：所有安全检测类技能只能用于你自己拥有或被明确授权测试的系统，未经授权对他人系统发起任何形式的主动检测，都是违法行为。

安全检测技能的合理用法，是把一套标准化的渗透测试流程固化下来。技能里定义好信息收集、端口服务识别、漏洞扫描、人工验证、报告生成五个阶段，前几个阶段让 Agent 调用脚本批量执行，人工验证阶段则明确要求测试人员参与。输出的报告模板包含漏洞等级、影响范围、复现步骤、修复建议，让安全团队拿到结果就能直接排期处置。

这类技能的 SKILL.md 编写有一个特殊要求：必须在最开头声明授权边界和合规声明，并且把扫描对象限制在用户明确提供的目标范围内。这不只是文案形式，更是让 Agent 在执行层面避开未授权目标的硬约束。技术本身是中性的，但使用边界必须清晰。

5. 常见问题排查与实操心得

5.1 技能装好了，Agent 却不调用，怎么办

这是我在社区里看到最多的求助帖，九成原因是 description 与任务意图匹配不上。Agent 的技能检索本质上是语义匹配，如果你的技能描述里全是一些“生成”“处理”之类的通用词，它在具体任务场景下很可能检索不到。

排查顺序我建议这样：先确认技能目录和文件结构没问题，再用/skills之类的命令看技能是否已经被加载。如果已加载但不被调用，问题就出在描述上，把 description 改得更具象，加入它适用场景中的特有名词。比如面向分镜的技能，一定要出现“景别”“分镜表”“运镜”这些词，检索命中率会明显提升。

还有一种情况是技能确实调用了，但你没察觉。Agent 在推理过程中加载技能可能不会在最终回复里宣告，需要看执行日志才能确认。新手可以先看会话中的工具调用记录，确认模型是否读取过你的 SKILL.md。

5.2 技能被加载但执行结果不理想

技能被调用了，输出却一塌糊涂，这里大概率是 SKILL.md 正文的指令质量出了问题。指令太模糊是最大的元凶。比如写了“遵循最佳实践”，模型根本不知道你的最佳实践是什么；写成“检查所有图片是否添加 alt 属性并补全缺失文本”，模型就能精确执行。

解决方法是把 SKILL.md 里所有的“应该”变成“必须做什么、怎么做、做到什么标准”。我在写技能正文时有一套自己的标准句式：每个动作拆成三个要素——触发条件、执行步骤、验收标准。模板化地写下来，Agent 的执行稳定性会高很多。

另外不要忽视参照示例的力量。在 SKILL.md 里放一个“输入示例+期望输出示例”的对照，模型能更准确地对齐你的预期格式。这比在指令里反复强调“要规范”“要专业”有效得多。

5.3 多技能冲突与优先级处理

装了几十个技能之后，新的烦恼来了：多个技能同时命中同一次请求怎么办。我遇到过的情况是，一个“前端审查”技能和一个“代码规范”技能都会在代码审查类任务里被检索到，Agent 把它们全部加载后互相干扰。

目前主流 Agent 框架对技能冲突的仲裁都比较简单，基本靠语义相关性打分排序。所以我在技能命名和描述上刻意做了错位，让技能边界尽可能清晰，避免语义重叠。如果你的两个技能确实职能相近，更合理的方式是把它们合并成一个综合技能，用 SKILL.md 内部的子流程来区分不同任务场景，而不是让 Agent 面对两个并列的候选。

还有个实践心得：常用技能保持在十来个以内，太多的技能只会增加检索噪音。定期清理不用的技能，让 Agent 每次的候选池保持精简，整体响应质量和速度都会有改善。

5.4 排查问题速查表

这张表是我自己调试技能时最常用的检索清单，遇到问题先对照一遍，能省下大量靠猜的排查时间。

5.5 我几个比较深的体会

最后说几句个人感触比较深的话。第一，技能开发这件事，真正难的不是写代码，而是把你脑子里的隐性知识逼成显性文字。这个过程本身价值巨大，哪怕不为了 Agent，我在整理 SKILL.md 的时候也重新梳理了自己的工作流，发现了不少过去一直靠“感觉”做的事情。

第二，别迷信“技能越多越厉害”。我试过一次性装五十几个技能，结果 Agent 每次对话都在检索上浪费大量时间和上下文，执行效率反而比只装十个核心技能的时候差。技能和记忆一样，贵精不贵多。

第三，版本管理意识要早建立。技能是会进化的，我在本地维护了一套技能仓库，每个技能改动都走 git 提交，回滚和追踪问题都方便。等你的技能积累到一定数量，就会明白这个习惯有多重要。

根据我个人的实操经验，评价一个技能包好不好，标准只有两条：能否稳定地被正确的任务触发，能否按预期输出高质量结果。空有花哨的脚本和文档，却在真实任务里频频失灵，这种技能装再多也是负担。技术浪潮总会更迭，但把做事的方法论结构化、把经验沉淀成资产这个动作，无论什么时候做，都不会亏。