企业官网建设流程全解析

1. Skills到底补上了Prompt的哪块短板

1.1 提示词工程的终点，正是技能的起点

如果你最近和我一样被“skills”这个词刷屏——从Claude Code到Codex，从GitHub上的superpower skills到各种skills推荐帖——很容易产生一个困惑：这东西和写prompt有什么区别？我不就是在对话里多描述几句需求吗？

说实话，我以前也是这么想的。直到我连续折腾了大概半个月的Agent工作流，把同一个代码审查任务在三种工具里反复跑，才意识到根本差别在哪：prompt是一次性指令，而skill是一套可复用的操作手册。

想象一下，你让一个新同事“去把线上项目的代码质量看一下”。他可能会愣住：看什么？怎么看？标准是什么？输出什么格式？于是你得从头解释一遍。可如果是给一份写好的SOP，里面有步骤、有检查项、有验收标准、还配了一个统计脚本，他上手就能干活，而且每次干出来的活质量都稳定。

Skills干的就是这件事。它把完成某类任务的完整方法——指令、脚本、参考资料、输出规范——打包成一个可命名的“技能单位”。大模型Agent不再需要你每次重复灌注背景，它自己会根据任务描述去检索并加载对应的技能。

1.2 为什么现在才火起来

这个思路其实很早就有人提过，但真正形成生态是最近大模型Agent工具集体发力后的结果。

以前我们写提示词，是把“如何做”一股脑塞进上下文窗口里。可窗口越塞越满，有效信息反而被稀释。而且提示词的复用性极差——换个项目、换台机器、换个会话，全部归零，又得重新写一遍。

Agent普及之后，问题更明显了。一个Agent要执行复杂任务，光靠对话式引导根本稳不住。它会忘、会偏、会在某一步自作主张。于是各家开始把“稳定的执行逻辑”从对话中抽出来，做成独立的技能文件。Anthropic在前段时间公开了Agent Skills的格式约定，后续OpenAI的Codex、社区里的opencode等工具也快速跟进。

整个链条就通了：定义一个标准格式，让技能可以跨会话、跨项目、甚至跨工具复用。

1.3 一个技能包到底改变了什么

改变最直观的一点：能力沉淀。

以前我积累的“干活经验”全在聊天记录里，散落各处，无法系统调用。现在我把它们整理成一个个skill，比如“前端代码审查”“项目结构分析”“数据库索引诊断”——每个skill里有明确的步骤、检查清单和配套脚本。

Agent需要哪个，就自动加载哪个。命令也从原来的长篇提示词变成了一句极短的话：

npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y

一行命令，装好一套视频生成技能包，agent立刻会用了。这就是skills带来的实际体感变化：从“教它做”变成“给它装好能力”。

2. 拆开一个Skill看内部结构

2.1 标准目录布局

不管是大模型厂商官方的Agent Skills，还是GitHub上各种coding skills仓库，核心结构基本是一致的。一个标准的skill目录长这样：

my-skill/ ├── SKILL.md ├── scripts/ │ └── analyze.py └── resources/ └── templates/

别被这结构吓到，实际上核心只有一个文件：SKILL.md。这就是技能的“大脑”，所有让Agent理解“何时调用、怎么执行”的信息都写在这一个文件里。

scripts/目录放的是可执行脚本，处理那些纯文本指令搞不定的活儿——比如统计代码行数、扫描依赖版本、解析JSON数据。resources/目录放的是静态参考资料和模板，比如代码风格规范、报告模板。

如果说SKILL.md是操作手册，那scripts/就是工具箱，resources/是资料库。三样东西凑齐，一个技能才算真正完整。

2.2 frontmatter与description的艺术

打开SKILL.md，最上面是一段YAML格式的元信息，这是Agent判断“什么时候该用这个技能”的关键：

--- name: frontend-review description: 用于前端项目代码审查，分析组件设计、状态管理、样式规范等问题，输出结构化审查报告。当用户要求审查前端代码、检查React/Vue项目质量或做Code Review时使用。 ---

很多人在写description时容易犯一个错误：写得太虚。

比如写“这是一个强大的前端审查技能”，Agent看了毫无感觉。它不知道什么时候该触发你。你要把触发场景写进description里——用户说什么话、面对什么类型任务时，这个技能最合适。这样Agent才能在合适的时机把它加载出来。

从我实测的经验看，description写得越具体，技能被正确调用的概率越高。这一条直接决定了你的skill是“装了等于没装”还是“一钓一个准”。

2.3 SKILL.md正文的写法要点

frontmatter下面是正文，这部分是Agent执行任务的“剧本”。和想象中不同，正文不应该是大段的散文描述，而应该是步骤化的操作指令。

我总结过一套比较稳妥的写法：

1. 先写目标：用两三句话说清这个技能要达成什么结果。
2. 再写执行步骤：把任务拆成原子步骤，每一步都写清楚“做什么、怎么做、做到什么程度算完成”。
3. 附上验收清单：任务完成后必须逐条核对，防止Agent漏步骤。
4. 标注边界：哪些情况不该用这个技能、哪些数据源不可信、哪些操作需要人工确认。

这就像给Agent一份“作业要求+评分标准”。有评分标准在，它输出的结果才稳定，不会自由发挥。

2.4 scripts与resources：为什么Skill需要“手脚”

纯文本指令最大的问题是：大模型的输出有随机性。让它“统计一下项目里每个目录的文件数量”，它可能真的会去数，但更可能说出一串差不多的数字。

这时候就需要脚本兜底。

我习惯在skill里放一个Python脚本，用确定性的代码完成统计、解析、校验这类工作，然后把结构化结果交给Agent去分析和呈现。脚本输出格式要稳定，最好是JSON或固定字段的文本，这样Agent才能准确读取。

resources/目录则适合放那些“每次执行都要参考但不该写进正文”的内容，比如一个项目的编码规范、一份报告模板。正文里只需要写一句“读取resources/templates/下的报告模板并填充”，既节省了上下文，又保持了流程清晰。

3. 从Claude Code到Codex：主流Agent的Skills挂载方式

3.1 Claude Code：目录即技能

目前生态最完整的当属Claude Code。它的skills挂载逻辑很直观：一个目录就是一个技能。

全局技能放在~/.claude/skills/下，对所有项目生效；项目级技能放在.claude/skills/下，只对当前仓库生效。你把包含SKILL.md的目录丢进去，重启Claude Code，技能就注册成功了。

除了目录挂载，还可以在CLAUDE.md里用@路径的方式直接引用某个技能目录。这种方式适合那种“只在特定项目里临时用一下”的技能，不需要复制到全局目录，整个项目团队共享一份配置，谁clone下来都能用。

3.2 一行命令安装远程技能包

现在社区里最流行的安装方式是npx skills add。以文章开头那条命令为例：

npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y

各项参数的作用：

这个命令背后做的事情很简单：拉取GitHub仓库，解析里面的技能目录，复制到目标Agent的技能目录下。原理不复杂，但把这层封装出来之后，安装门槛确实低了很多。

很多人问“npx skills怎么源码安装skill”，其实核心就是两条：git clone下来，然后把技能目录复制到对应的skills目录。有install.sh或者Makefile的仓库，优先按仓库说明操作，没有就直接手拷。

3.3 Codex与opencode的Skills形态

OpenAI Codex对skills的处理方式稍有不同，它更倾向于用一个skills.md文件把一组技能集中管理起来，每个技能以Markdown卡片的形式声明。好处是文件数量少、便于阅读，坏处是复杂技能的可执行脚本不太好塞进去。

opencode这类社区Agent走的则是Claude Code类似的“目录即技能”路线。社区里已经有不少针对opencode设计的skills集合，本质上和Claude Code的技能包没有太大区别，只是安装时指定的--agent参数不同。

给个对比表，快速理解：

选哪个工具不重要，重要的是理解一个共同点：skills的本质都是“结构化目录+说明文件”，理解了这个，哪个工具都能上手。

4. 社区热门的Skills包长什么样

4.1 Superpowers：把工程方法打包

最近社区里讨论度很高的一组技能包是Superpowers（superpower skills）。它的思路很有意思：不只是解决单个任务，而是把一整套软件工程方法论打包进技能里。

比如它会定义一个“编码前先拆解任务”的技能，Agent在执行开发任务前，先输出任务拆解清单，逐条确认后再动手。还会定义“写代码后必须自查”的技能，让Agent对自己生成的内容做一轮审查，减少低级错误。

这种“方法论型技能包”最大的价值不是解决了某个具体问题，而是改变了Agent的工作习惯。很多人装完Superpowers后体感“Agent变聪明了”，其实是工作流程被流程化、被约束了。

4.2 前端与编码类Skills

开发者日常最需要的就是编码类技能。

前端开发skills是其中最热门的品类。典型的技能内容包括：分析项目的依赖版本和兼容性、审查组件拆分是否合理、检查状态管理方案是否合适、定位样式覆盖问题等。

拿我见过的一个前端审查技能来说，它的SKILL.md里写清楚了审查顺序：先看依赖配置文件，再看组件结构，最后看状态管理和样式。每一步都有对应的检查项，比如“Hooks是否按规范放在组件顶部”“样式是否使用了硬编码像素值”。Agent照单执行下来，产出的审查报告质量相当稳定。

如果你平时用TypeScript比较多，关注一下Matt Pocock开的那个skills集合，它把TS类型体操、泛型设计那些容易出错的点做成了检查清单技能，挂在Codex或者Claude Code里都合适。

4.3 垂直应用型Skills：视频、数学建模、安全研究

除了编码类，垂直领域的技能包也在快速丰富。

视频生成方向的vidmuse-skills是典型代表，它把分镜设计、提示词组织、素材整理这一套流程封装成技能，前文那条npx skills add命令装的就是这类技能。

数学建模skills在竞赛群体里很受欢迎。它通常涵盖三块：选题分析、模型选型建议、论文结构模板。Agent拿到赛题后，会自动按技能里的流程走一遍：先拆解问题类型，再推荐可用的数学模型，最后生成带有标准章节的报告框架。

还有安全研究方向的技能包，做渗透测试相关工作的朋友会关注。需要强调一句：这类技能包的使用场景应该是授权范围内的安全评估和教学研究，任何时候都不应该被用于未授权的测试。

4.4 怎么从一堆Skills里选出靠谱的

GitHub上技能包越来越多，挑选时我一般看四个维度：

一个连README都写不清楚的技能包，里面的SKILL.md大概率也写不好。反过来，如果一个技能包的示例输出很清晰、还有维护日志，那这个作者多半是真的在用的，可信度就高很多。

5. 从零开发一个自己的Skill

5.1 需求定义：选一个“你重复最多”的任务

不要一上来就想着做一套“万能技能包”，没有意义。最值得做的是你自己工作中重复次数最多的那件事。

我做的第一个技能是“项目代码结构分析”。起因是我经常要接手不熟悉的老项目，每次都要花时间梳理目录、找入口文件、定位模块关系。这活重复、机械、又有固定套路，非常适合技能化。

需求定义阶段我列了几个问题：

• 这个任务的输入是什么？（项目路径、目标目录）
• 输出是什么？（一份结构说明文档）
• 中间步骤有哪些？（列目录、读配置文件、找入口、分析依赖）
• 哪些环节需要脚本辅助？（文件统计、依赖解析）

这四个问题想清楚，技能的骨架基本就出来了。

5.2 写入SKILL.md：让Agent一眼看懂何时调用

我的SKILL.md长这样：

--- name: project-structure-analysis description: 分析一个项目或目录的整体结构，识别技术栈、入口文件、模块划分和依赖关系。当用户要求分析项目结构、快速了解代码库、接手新项目时使用。 ---

正文部分，我按照“目标-步骤-验收-边界”四段式组织。特别注意把步骤写成原子化的操作：

1. 使用scripts/scan_tree.py递归扫描目标目录，获取文件和目录树。
2. 读取package.json / requirements.txt / go.mod 等清单文件，识别技术栈。
3. 根据技术栈定位入口文件（如src/main.tsx、src/index.py）。
4. 输出包含目录结构、技术栈、入口说明、模块列表的Markdown文档。

每一条后面都补充了判断标准。比如“入口文件如何确定”“模块边界怎么划分”，这些琐碎但关键的细节，正是Agent最容易出错的地方。

5.3 编写辅助脚本：稳定输出比聪明更重要

脚本部分的经验是：不要让脚本做复杂判断，让它做确定性输出。

我写的扫描脚本只干两件事：递归列目录、提取关键配置文件的信息。输出固定为JSON结构：

#!/usr/bin/env python3 """扫描项目目录结构，输出JSON格式的树形结构""" import json import os import sys def scan_directory(path): result = { "name": os.path.basename(path) or path, "type": "directory", "children": [] } try: for entry in sorted(os.listdir(path)): if entry.startswith((".", "node_modules", "dist")): continue full_path = os.path.join(path, entry) if os.path.isdir(full_path): result["children"].append(scan_directory(full_path)) else: result["children"].append({"name": entry, "type": "file"}) except PermissionError: pass return result if __name__ == "__main__": if len(sys.argv) < 2: print(json.dumps({"error": "需要提供扫描路径"}, ensure_ascii=False)) sys.exit(1) print(json.dumps(scan_directory(sys.argv[1]), ensure_ascii=False, indent=2))

这里有几个细节是踩过坑之后才加上的：

• 忽略常见目录，防止node_modules把JSON撑爆。
• 输出必须ensure_ascii=False，避免中文路径变成乱码。
• 请求失败时输出error字段并设置非零退出码，Agent能感知到异常并决定是否需要人工介入。

脚本不追求面面俱到，能把Agent最不擅长的、最需要确定性的部分扛住，就已经完成了使命。

5.4 本地测试与版本迭代

技能写完不要急着发布。先在自己常用的Agent里跑几轮真实任务。

第一轮测试我踩了个很典型的坑：Agent调用了技能，但完全没执行脚本，直接自己读完SKILL.md就开始“分析”，输出结果当然漏洞百出。

原因出在SKILL.md里“使用scripts/scan_tree.py”这句话写得太温和。Agent认为这是可选项。改成“第一步必须执行scripts/scan_tree.py，如不执行则任务失败”，效果立刻好了。

这也验证了一个原则：skills的正文要用强制性语言描述必须步骤，把“可做可不做”的空间尽量压缩。技能的价值恰恰在于“稳定”，而不是“灵活”。

6. 开发与调优过程中踩过的坑

6.1 装完不生效：完整排查链路

这是最常见的坑，排除思路有固定套路。我总结成一条链路：

1. 检查目录位置是否放对。Claude Code认~/.claude/skills/和.claude/skills/，放错位置等于没装。Codex则是编辑skills.md文件。每个工具认的位置不一样，先去看对应文档。

2. 检查目录结构是否完整。技能目录下必须有一级SKILL.md文件，这个文件没写对，其他东西都白搭。

3. 检查frontmatter格式。YAML解析失败时，整个skill会被忽略。尤其注意description不能换行，缩进要用空格不要用Tab。

4. 重启Agent会话。大部分工具的技能列表是在会话启动时加载的，装完不重启，自然不生效。

5. 验证description是否触发。用测试语句直接试探：“请使用xxx技能”。如果直接点名能触发、自然描述不触发，说明description写得不够“像用户说话”。

这条链路走一遍，90%“装完不生效”的问题都能定位。

6.2 Agent调用了Skill却“答非所问”

如果说“不生效”是第一大坑，第二大坑就是“生效了但效果不理想”。

我之前写过一个“数据库索引诊断”技能，步骤写得也算清楚，但Agent执行结果总是偏离目标，该看执行计划不看，该测索引不测。

后来逐个环节对比，发现问题出在正文结构上：我把很多背景知识写在了步骤前面，Agent读了一大段背景，反而模糊了重点输出。

调整方案是：

• 文章最顶上用一句话写明“最终输出是一份诊断报告，包含xx、xx、xx三部分”。
• 步骤按“采集信息→执行分析→生成结论→输出报告”四段组织。
• 每步末尾标注前置条件和完成标准。

把“最终要交什么”放在最前面，Agent在执行过程中的每一步都会朝着这个终点靠拢。这是优化效果最明显的一次调整。

6.3 脚本与环境问题：timeout、路径与退出码

技能脚本出问题，比正文更隐蔽，因为报错信息不一定反馈得出来。我遇到过的典型情况：

有一回我在技能脚本里硬编码了一个Windows风格路径，当场没问题，过了几天在另一台部署环境上跑就报错。这个教训让我定了条规矩：技能脚本里不允许出现任何绝对路径，涉及路径的参数一律从命令参数传入。

6.4 上下文与性能权衡

最后说一个容易被忽略的问题——技能太多、正文太长。

每个技能平时并不会全部加载进上下文，Agent是根据任务描述动态调用的。但一旦被调用，该技能的全部正文和资源说明都会占住上下文窗口。如果某个技能正文有上万字，一次调用就吃掉大量上下文空间，影响Agent后续推理质量。

我的优化思路：

• SKILL.md正文只放执行流程和验收标准。
• 需要详细参考的内容丢进resources/目录，正文里写“读取resources/xx文件获取详细规则”。
• description里主动提示“本技能会调用外部脚本，需要较长上下文”，让使用者有预期。

还有一个小技巧：给正文按模块拆分，让Agent只在需要时读取具体模块，而不是一股脑加载全文。

7. Skills和Prompts的关系会怎么走

7.1 社区正在讨论什么

最近看到不少关于“rethinking skills and prompts”的讨论，甚至有人开始琢磨下一代模型该怎么把skills做进模型层。讨论核心绕不开一个问题：skills会不会取代prompts？

我的理解是：不会取代，但分工会更清晰。

Prompts负责的是这一次对话的意图，它灵活、即时、随用随抛；Skills负责的是一类任务的执行方法论，它稳定、可复用、有版本。两者本质上是不同粒度的东西。

7.2 我的判断：分工而不是替代

一个技能内部其实也离不开prompt——SKILL.md本身就是一段高度结构化的prompt，技能脚本文本、资源说明本质上也是prompt的一部分。

Skills真正改变的，是prompt的组织和传递方式。它让原本散落在对话里的任务执行知识，变成可以独立维护、安装、升级的模块。

这就好比一个厨师，以前手里攥着一堆菜谱便签（prompt），现在把常用菜的做法整理成了一本标准化菜谱库（skills），便签还在用，但核心做法沉淀进了菜谱。该手写笔记的时候还是写，但一日三餐的稳定性靠谱多了。

7.3 给新手的行动建议

如果你也想把skills用起来，我的建议是从“抄”开始。

先去GitHub找几个热门技能包装上跑体会，再从你重复度最高的任务里挑一个，照着前文的目录结构写个最简版本。不用追求完美，先让Agent能稳定执行，再逐步往里加细节。

我的体会是：技能库和代码库一样，需要持续维护。经常用的技能会越来越好用，不用的技能要及时删除，否则它会在Agent上下文里占着位置，还可能造成误调用。

我现在的日常已经离不开自己的技能库了。接手新项目、做代码审查、理清依赖关系，都是直接让Agent调用对应skill，效果比之前反复写prompt稳定太多。这套东西还在快速演进，但核心方法论不会变：把你要重复做的事情，沉淀成可复用的能力，然后交给Agent去执行。这件事越早做，后面的累积效应越明显。