企业官网建设流程全解析

先说个我最近的真实感触：过去一年里，我调模型的方式变了很多。以前拿到一个任务，第一反应是“怎么把 prompt 写得再长一点、再细一点”，后来发现提示词写一万个字，模型该不会的还是不会——它只是听懂了你在说什么，并不知道该怎么一步步把事做完。直到我开始系统性接触 Agent Skills 这套思路之后，一个很明显的转变是：我不再“教模型说人话”，而是直接给模型一套可以执行的工具流和方法论。项目标题里的“skills”不是什么玄学，也不是单纯的“能力提升清单”，而是大模型编程和智能体时代里，一个正在快速成为标配的工程单元：把高频任务沉淀成可复用的技能包，让模型拿到任务后直接调用，而不是每次从零开始摸索。

这篇文章想把这件事讲透：skills 到底是什么、为什么现在所有主流 Agent 工程都在往这个方向走、一个合格的技能包长什么样，以及怎么从零开发、安装、调试一套自己的 skills。我会尽量用自己的实操过程说明白，而不是甩概念。适合正在用 Claude Code、Codex、OpenCode 这类工具做开发，或者想把自己手里的重复性工作“技能化”的人参考。

1. 项目整体设计与思路拆解

1.1 “skills”到底是什么：不是提示词，而是一个可执行的工作单元

先做个比喻。普通 prompt 相当于你给实习生口头交代了一句“把这个表格整理好”，实习生怎么做、按什么标准做、遇到格式问题怎么办，全靠他自己的悟性。而 skills 相当于你直接甩给他一本 SOP 手册：里面写了整理表格的每一步流程、用什么工具、输出成什么格式、中间遇到异常怎么兜底。模型拿到 skill 之后，不是在“理解”你的意图，而是在“执行”一套已经被验证过的方法论。

所以核心差异在于：prompt 是指令，skills 是能力封装。一个 skill 往往包含一套规定好的目录结构，里面既有给模型读的指导文档（通常叫 SKILL.md 或类似命名），也有可以直接执行的小脚本、参考模板、示例数据。模型在对话中一旦判断当前任务命中了某个 skill 的描述范围，就会自动把这个技能包“加载”进来，按里面的流程走，而不是自由发挥。

这就能解释为什么“superpower skills”“mattpocook skills”这些开源仓库会火——它们本质上不是一堆提示词模板，而是把“如何做技术方案评审”“如何做代码重构”“如何做流程图绘制”这类高频动作，固化成了模型可以反复调用、一致性极高的技能模块。你装上之后，相当于给模型加了一堆“职业技能证书”，它遇到对应场景就知道按专业套路出牌。

1.2 为什么提示词正在让位给技能包：从“说清楚”到“教它做”

我这两年最深的体会是，模型的上下文窗口再大，也扛不住你把所有方法论塞进一次对话里。如果每次任务都要在 prompt 里把行业规范、操作步骤、输出格式写一遍，第一是 prompt 本身会变得巨长，浪费 token；第二是模型很容易“记了后面忘前面”，尤其是步骤一多、规则一细，执行起来就开始走样。

skills 解决的正是这个问题：把方法论从上下文里剥离出来，沉淀成独立文件。模型需要的时候再去读，不需要的时候完全不占用上下文；而且同一套方法论可以被反复加载，保证每次执行的标准一致。说白了，这是把“经验”变成了“代码资产”，而不是靠聊天记录维系。

另外还有一个很现实的点：提示词是“私有”的，很难分享。你写了一个特别牛的 prompt，发到群里别人复制过去，效果可能大打折扣，因为每个人对话时的状态、模型版本、上下文都不一样。但技能包不一样，它自带完整目录、脚本和说明，只要是同一套 Agent 工具，装上去就能复现相同能力。这也是为什么 GitHub 上 skills 仓库的 star 涨得飞快——因为它们天然适合做开源生态。

1.3 主流生态盘点：不同 Agent 里的 skills 有什么差异

现在几乎每个主流 Agent 编程工具都在做自己的技能体系，但底层逻辑是相通的：目录 + 描述文件 + 可执行资源。我用下来，几个热门的生态差异主要在于安装方式和可自定义程度：

就我自己的使用习惯来说，如果只是日常编码分析，Claude Code 的 skills 体系最成熟；如果是要在开源项目里共享技能包，用仓库目录方式（比如.claude/skills）跟着项目走是最不容易踩坑的选择，因为技能跟代码放在一起，人换了、机器换了也不会丢。

2. 技能包的核心结构与实操细节

2.1 一个标准技能包的目录长什么样

如果你没打开过真实的 skills 仓库，很容易以为它就是一个 Markdown 文件。实际上一个合格技能包的目录结构大致是这样的：

my-skill/ ├── SKILL.md ├── scripts/ │ ├── generate_structure.py │ └── analyze.py ├── assets/ │ ├── template_report.md │ └── example.json └── requirements.txt

其中 SKILL.md 是技能包的大脑，scripts 里放的是可执行脚本，assets 里是参考素材。之所以建议这样拆，是因为模型在大多数情况下只需要先读 SKILL.md 就能判断“这个技能适不适用于当前任务”，只有当确定要执行时才去调用脚本和模板，这样既省 token 又保证响应快。

SKILL.md 本身的格式，业内比较通行的做法是带 YAML frontmatter：

--- name: structure-diagram description: 根据用户提供的文档或代码仓库，生成结构化的架构图/思维导图。仅在用户需要梳理结构、画图时使用。 ---

name 字段是技能的唯一标识，description 字段是模型判断“要不要调用这个技能”的核心依据。很多人写 description 时容易写得特别宽泛，比如“帮助用户解决各种问题”，这等于没写。好的描述应该包含触发场景、使用条件和明显的排除条件。

2.2 SKILL.md 正文怎么写才能让模型真正执行

正文部分是技能的“操作手册”，可以分为几个小节：先讲前置条件，再讲操作步骤，最后给一个可参考的输入输出示例。我常用的一个模板结构是：

• 目标说明：这个技能用来完成什么任务，产出什么结果。
• 前置检查：执行前需要确认哪些信息，缺了怎么办。
• 执行步骤：按序号彻底写明每一步操作，不要省略中间的判断逻辑。
• 输出格式：明确最终交付物的格式，比如 Markdown 报告、JSON 文件或代码仓库结构。
• 示例：给一个完整的输入到输出示例，模型会照着这个示例调整自己的执行方式。

这里有个实操细节：不要只在文档里写“自动生成图表”这种命令式描述，而要写“先读取输入文件的目录结构，提取主要模块，再按模块关系输出为 mermaid 代码块，最后整理成层级清单”。模型对“具体怎么做”的遵循程度，远高于对“结果是什么”的遵循程度。每一步越细，执行偏差越小。

2.3 脚本与资源：给模型装上一双“能干活的手”

很多 skill 牛逼的地方不只是文档写得好，而是配套脚本真的能落地执行。比如一个“代码仓库分析”技能，SKILL.md 只负责告诉模型分析思路，真正统计函数数量、圈复杂度、依赖关系的工作，则由 scripts/analyze.py 完成。模型只需运行脚本、读输出结果，再结合 SKILL.md 里的分析框架生成报告。

这种“文档决策 + 脚本执行”的组合，就是我理解中“superpower skills”特别像超能力的原因：模型本身不能直接数代码行数，但给它一个 Python 脚本，它就能瞬间完成数万行代码的统计和分析。技能包本质上是在给模型扩展感知和操作能力，而不是仅仅教它思考。

写脚本时有三点建议。第一，脚本入口最好用命令行参数接收输入路径，避免硬编码；第二，脚本输出尽量用 JSON 或结构化文本，方便模型直接读取引用；第三，如果是 Python 脚本，在 requirements.txt 里固定依赖版本，避免不同环境执行结果不一致。

2.4 技能的安装与激活：让 Agent 知道“什么时候拿出来用”

技能的安装方式因工具而异，但原则上有两种：一种是放到全局用户目录，比如 Claude Code 的~/.claude/skills/，这样所有项目都能用；另一种是放到项目目录下的隐藏文件夹里，比如.claude/skills/，这样只有进入这个项目才会激活相关技能。

用全局目录还是项目目录，取决于技能的通用程度。像“生成流程图”“做代码审查”这类通用技能，放全局目录比较省事；像“处理本公司特定数据格式”“梳理某个老项目的模块关系”这类强项目绑定的技能，放项目目录更合理，避免其他项目误触发。

安装命令方面，社区比较流行的是通过npx skills add 作者名/仓库名的方式一键安装，比如npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y这样的命令，-g表示全局安装，-y表示跳过确认。如果某个仓库不支持 npx 方式，也可以直接git clone之后手动把目录复制到技能目录下，两种方式本质一样，区别只是自动 vs 手动。

这里要提醒一个我踩过的坑：安装后如果发现模型完全无视新装的技能，首先检查目录层级是不是多套了一层。很多仓库 clone 下来之后是skills/xxx/SKILL.md结构，你要把xxx这个技能目录整体复制到技能根目录，而不是把skills整个文件夹复制过去。目录层级不对，Agent 是识别不到技能的。

3. 从零开发并发布一个自己的技能包

3.1 选题：什么样的任务值得被做成技能

不是所有任务都值得做技能包，太简单的不需要，太复杂的又不好固化。我一般用三个标准衡量：第一，这个任务你或你的团队每周都会遇到至少一次；第二，任务的执行流程相对稳定，中间步骤可标准化；第三，任务里有一部分“机械性操作”可以交给脚本，比如读取文件、统计结果、生成模板。

举个例子，我最近做了一个“技术方案评审”技能。触发场景是每次开完需求会，都要对新方案做一轮完整的评估。以前这个工作全靠人肉整理，后来我把评估流程固化成了技能：先读取方案文档，再按架构、性能、安全、可维护性四个维度逐项打分，最后生成统一格式的评审报告，报告里附上风险项和改进建议。实测下来，一个完整方案从阅读到产出报告，从原来的半小时缩短到了三分钟，而且格式比我自己手写的还统一。

3.2 动手写 SKILL.md：一个可直接复用的示例

直接上一份我实际用过的 SKILL.md 示例，目标是“生成文档结构图”：

--- name: doc-structure-diagram description: 根据项目文档或代码目录，生成结构层次的思维导图或架构图。适合用户要求梳理文档/目录结构、画出模块关系图时使用。 --- # 文档结构图生成指南 ## 目标 根据输入的项目路径或文档说明，生成一份清晰的层级结构图。 ## 前置检查 1. 确认输入的是一个目录路径或明确的文档清单。 2. 如果输入不明确，先询问用户需要梳理的范围。 3. 确认输出格式偏好（mermaid、markdown 列表、或图片）。 ## 执行步骤 1. 读取指定目录下的所有文件和子目录，忽略 .git、node_modules、dist 等依赖目录。 2. 按模块或功能对文件进行分组，不按物理路径机械展示。 3. 将分组结果整理为层级树，第一层是模块名，第二层是子模块，第三层是关键文件。 4. 生成 mermaid 代码块格式的 graph TD 图。 5. 如果用户需要，再输出一份可复制的 Markdown 层级清单。 ## 输出格式 - mermaid 图：以 ```mermaid 代码块包裹。 - 层级清单：使用嵌套无序列表。 ## 示例 输入：docs/ 目录 输出： ```mermaid graph TD A[docs] --> B[架构设计] A --> C[接口文档] B --> D[模块划分.md] C --> E[API列表.md]

注意看这里的写法：我刻意把“忽略哪些目录”“按什么逻辑分组”“输出成什么格式”都写死了，模型执行时不需要自己判断，只要跟着流程走就行。这也是技能包和普通 prompt 最大的区别——它把不确定的“意图理解”变成了确定的“流程执行”。 ### 3.3 配套脚本：让技能真的能“跑起来” 拿生成结构图这个技能来说，如果只靠 SKILL.md，模型还是需要自己想办法列目录，虽然能完成，但在目录很大时容易漏文件。所以我写了一个 Python 脚本做目录扫描： ```python #!/usr/bin/env python3 import os import sys import json IGNORE_DIRS = {'.git', 'node_modules', 'dist', '__pycache__', '.next', '.venv'} def scan(path, prefix='', depth=0, max_depth=5): results = [] if depth > max_depth: return results try: entries = sorted(os.listdir(path)) except PermissionError: return results for entry in entries: full = os.path.join(path, entry) if entry in IGNORE_DIRS: continue if os.path.isdir(full): results.append({ 'name': entry, 'type': 'dir', 'path': full, 'children': scan(full, depth=depth+1) }) else: results.append({'name': entry, 'type': 'file', 'path': full}) return results if __name__ == '__main__': root = sys.argv[1] if len(sys.argv) > 1 else '.' output = scan(root) print(json.dumps(output, ensure_ascii=False, indent=2))

这个脚本输出的是 JSON，模型拿到之后可以直接读取，再按 SKILL.md 的分析逻辑进行分组和画图。整个过程里，模型负担最小，重复劳动全部交给脚本，即使目录里有上千个文件，也能在几秒内扫描完成。这也是我推荐“脚本能干的绝不靠模型生啃”的原因，稳定性和速度都高一个量级。

3.4 本地调试与发布：如何确认技能被正确加载

开发完技能后，第一件事不是发布，而是本地验证。我的习惯是先把技能目录复制到对应工具的全局技能目录，然后故意触发一个匹配描述的任务，观察模型输出里有没有出现技能相关内容，比如它主动读取了 SKILL.md，或者脚本被真实调用。

实际调试中比较头疼的一类问题是“技能装上了但模型就是不调用”，大概率是 description 写得不够具体。比如你写“用于生成结构图”，模型遇到用户说“帮我画一下我的项目架构”，不一定会联想到这个技能。但如果 description 写成“根据项目文档或代码目录，生成结构层次的思维导图或架构图。适合用户要求梳理文档/目录结构、画出模块关系图时使用”，命中率就高很多。description 里的触发词要和用户真实表达常见的说法对齐，这一点值得反复打磨。

发布方面，目前最常用的方式是推到 GitHub 仓库，然后用npx skills add 你的用户名/仓库名让别人安装。如果你希望技能被更多人搜到，仓库根目录要放一份清晰的 README，说明技能用途、适用场景、目录结构，并截图展示使用前后的效果对比。社区里的好技能包往往还有一个共同特征：附上了至少一个实际案例的执行过程，这比任何宣传都有说服力。

4. 好用的 skills 清单与实践组合

4.1 高频推荐的 skills 一览

这段时间我陆陆续续试了不少社区里的技能包，有些确实称得上“装完回不去”。整理一个简化版的清单，按使用频率排序：

这些技能包大多不需要额外配置，装上即可用，但要注意一点：不同的技能包之间可能有功能重叠，比如“代码仓库分析”和“代码审查”都会读项目代码，装多了之后模型可能搞不清该用哪个。我现在的处理方法是只保留一个“主力技能”覆盖同一类需求，减少冲突。

4.2 组合实践：把多个技能串成一条流水线

单个技能能解决单点问题，但真正体现 skills 威力的是把它们组合起来。举个例子，我处理一个陌生的前端项目时，会依次做三件事：先用“代码仓库分析”技能摸清整体结构，再用“流程图画图”技能把关键模块的调用关系画出来，最后用“技术方案评审”技能对当前架构做一轮诊断。

这么做的好处是，每个技能只专注自己最擅长的事，模型不需要在一个技能里塞太多目标，执行质量会稳定很多。而且技能和技能之间通过结构化文本衔接——分析技能输出 JSON，画图技能读取 JSON 画图，评审技能读取画图结果和报告模板生成结论——形成了一条完整的数据流。

这套组合实践给我的感觉，和“大模型 skills harness 深入理解”里提到的思路很像：技能不只是单独的原子操作，而是要纳入一个统一的调度框架里，让 Agent 根据任务自动编排调用顺序。你不用自己在 prompt 里写“先做 A 再做 B”，只要把每个技能的 description 写清楚，模型在推理时会自动选择合适的技能序列。

4.3 技能选择的避坑建议与安全提醒

社区里 skills 质量参差不齐，选型时我自己的几条原则提供给你参考：

• 优先选带脚本的技能，纯文档型技能离“可执行”还差口气。
• 看仓库的更新时间和 issue 反馈，超过半年没更新的技能很可能已经不适配最新工具版本。
• 先装到一个临时项目里测试，确认没问题再放到全局目录。
• 注意技能包的权限，有些技能脚本需要执行 shell 命令或访问外部 API，安装前扫一眼代码，避免给出过高的系统权限。

安全方面尤其值得多说一句：第三方技能包本质上是一段可执行的代码，它被模型调用时是以你的权限运行的。安装来源不明的技能前，至少检查一下 scripts 目录里有没有可疑的文件下载、环境变量读取或网络请求逻辑。我一般只在知名作者或高 star 仓库里选择技能包，并且定期清理不再使用的技能，尽量缩小攻击面。

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

5.1 技能不生效的六大原因

技能不生效是新手最容易遇到也最挫败的问题，我整理了一张速查表，基本都是我踩过的坑：

其中目录层级问题出现频率最高，我猜是因为很多 GitHub 仓库为了方便展示，会把技能统一放在skills/子目录下，而安装工具复制时容易搞混。判断方法很简单：打开技能目录，里面第一层应该是SKILL.md，如果看到的是skills/SKILL.md这种结构，那一定是多套了一层。

5.2 描述不触发与上下文过长的处理心得

除了技术性故障，技能使用还有两个经常被忽略的调优点，一个是描述触发，一个是上下文优化。

描述触发的问题，本质上是“模型怎么判断该不该调用技能”。不要指望模型会主动探索你的技能库，它只会根据当前对话和用户意图，机械地对比每个技能的 description。所以排查这类问题时，把用户原话复制下来，放到技能的 description 里看看能不能自然匹配上；匹配不上就去改描述，而不是去改模型。

上下文优化的问题也很典型。技能包加载后，SKILL.md 全文会进入模型上下文，如果技能文档写得又臭又长，反而挤占其他信息的空间。我的经验是 SKILL.md 控制在一千五百字以内，把细节尽量放到脚本和 assets 里，让模型“按需阅读”，而不是“全量背诵”。

5.3 踩坑实录：一次完整的排查过程

记录一次最近的实战排查，能帮你更好理解上面这些点。有次我在 Claude Code 里装了某个做数据分析的技能包，结果无论怎么问，模型都只用普通对话回答，完全不触发技能。

我先确认了技能目录结构没问题，又检查了依赖也齐全，排除了环境问题。最后翻开发布者的仓库，发现这个技能包最新版本要求的 Agent 版本比我现在的高，而更高版本里技能激活机制改成了“当用户明确提到统计、图表等词时才触发”。我升级工具版本后重新测试，技能就正常出来了。

这件事给我两个启发：一是技能包和工具版本之间是有耦合的，旧工具跑新技能经常有兼容性问题；二是排查问题时别只盯着技能本身，多看看工具更新日志。现在很多 Agent 工具迭代得非常快，一个月前的技能激活机制，一个月后可能就变了。

写在最后的个人体会

做了这么多技能包之后，我最大的感受是：skills 这个概念把一个很朴素的想法变成了工程现实——把经验沉淀下来，让机器替你执行。以前写技术博客、写文档，本质是把经验留给“人”看；而技能包把经验写成了“模型”能直接执行的格式，这是种完全不同的表达方式，更像是在培训一个永不疲倦的实习生。

现在我自己处理重复性任务时，已经很少写“一次性 prompt”了，基本都是打开终端，安装或调用对应的技能包，让 Agent 按部就班地完成任务。有时候想想，未来衡量一个工程师能力的重要标准，可能不再是他自己多会写代码，而是他能不能把自己的工作流程高效地封装成一套可复用的技能体系。如果你还没有动手做过自己的第一个技能包，建议今天就挑一个每周都会遇到的琐碎任务，花半小时把它固化成 SKILL.md，你会很快感受到这种“把经验变成资产”的乐趣。