企业官网建设流程全解析

1. 为什么需要把分散的技能聚合起来

1.1 从一个真实痛点说起

如果你同时用多个 AI 编程助手，大概率经历过这种场景：在 Claude Code 里调好了一套代码审查的提示词模板，换到 Codex 里又得重新配一遍；在某个项目目录下写好的重构技能，换个项目就找不到了。技能文件散落在不同的隐藏目录、不同的配置路径下，时间一长自己都记不清哪个版本是最新的。

这不是个别现象。AI 编程助手这类工具，目前各家都有自己的技能/指令存放约定。Claude Code 习惯把自定义指令放在项目根目录的特定文件夹里，Codex 又有自己的一套约定，其他工具各有各的玩法。结果就是：同一个技能，你要在 N 个地方维护 N 份副本，改了一处忘了另一处，最后哪个都不对。

awesome-skills这个项目要解决的就是这件事——把散落在各处的 Claude Code、Codex 等 AI 编程助手的技能，用一个统一的仓库聚合起来，一处维护、多处复用。说白了，就是给技能做一个"中央仓库"，让不同工具都能从这里取用。

1.2 这个项目适合谁

先说清楚受众，免得你看到一半发现不是自己要的。

• 重度使用 AI 编程助手的开发者：你日常写代码离不开 Claude Code 或 Codex，已经积累了一批自定义技能，但管理起来很痛苦。
• 团队协作场景：团队里几个人用不同的 AI 工具，希望技能规范能统一，代码审查标准、提交信息格式这些能对齐。
• 技能收集爱好者：你喜欢折腾各种提示词和技能模板，想有个地方系统性地归档和分类。
• 刚入门的新手：你还没积累多少技能，但想看看别人是怎么组织技能的，直接抄一套成熟的结构。

如果你只是偶尔用一下 AI 助手，连自定义指令都没配过，那这个项目对你价值有限，可以先收藏，等需求起来了再回来看。

1.3 聚合的核心价值到底在哪

很多人第一反应是："不就是把文件挪到一个文件夹吗，有什么技术含量？" 如果只是简单挪文件，确实没含量。但真正做起来，难点在于不同工具的技能格式、元数据、触发机制都不一样。

举个具体的例子。Claude Code 的技能通常是一个带 frontmatter 的 Markdown 文件，里面用 YAML 描述技能名称、描述、触发条件；而 Codex 的技能组织方式可能是另一套结构，可能依赖不同的目录层级和命名约定。你要聚合，就得解决几个问题：

1. 格式归一化：把不同工具的技能描述统一成一种中间格式，或者至少能双向转换。
2. 元数据对齐：技能名称、描述、适用场景这些字段，各家的叫法可能不同，得做映射。
3. 分发机制：聚合之后，怎么让各个工具都能方便地读取到自己需要的那份。
4. 版本管理：技能更新了，怎么同步到各个使用点，怎么处理冲突。

awesome-skills的价值就在于它把上面这些脏活累活封装好了，你只需要按它的约定往里放技能，剩下的分发和适配它来处理。这才是"聚合"两个字的真正含义——不是物理上的堆叠，而是逻辑上的统一。

提示：判断一个聚合类项目值不值得用，关键看它有没有解决"格式差异"和"分发同步"这两个核心问题。只做文件堆叠的项目，用不了多久你就会放弃。

2. 核心设计思路与目录结构拆解

2.1 整体架构是怎么想的

一个靠谱的技能聚合项目，架构上通常分三层：存储层、适配层、分发层。我结合这类项目的常见实践，把awesome-skills的设计思路拆开讲。

存储层负责统一存放所有技能。这里的关键决策是：用什么样的目录结构来组织。常见做法是按"技能类别"分一级目录，按"具体技能"分二级目录，每个技能目录下放技能定义文件和相关资源。比如：

skills/ code-review/ SKILL.md examples/ refactor/ SKILL.md commit-message/ SKILL.md

这种结构的优势是清晰、可扩展。你想找一个代码审查相关的技能，直接进code-review目录就行，不用在一堆平铺的文件里翻。

适配层是项目的灵魂。它负责把存储层里的统一格式，转换成各个 AI 工具能识别的格式。这一层通常包含一组转换脚本或配置映射文件，告诉项目"Claude Code 需要什么样的 frontmatter 字段"、"Codex 需要什么样的目录布局"。

分发层负责把转换好的技能投放到正确的位置。可能是软链接，可能是复制，也可能是生成配置文件。这一层决定了你更新技能后，各个工具能不能自动感知到变化。

2.2 为什么选择 Markdown 加 frontmatter 作为统一格式

这是这类项目最常见也最合理的选择，原因有几个。

第一，Markdown 是 AI 编程助手领域的通用语言。Claude Code、Codex 以及大多数同类工具，技能定义本质上都是一段给模型看的自然语言指令，Markdown 天然适合承载这种内容。你写起来舒服，模型读起来也顺畅。

第二，frontmatter 提供了结构化的元数据。纯 Markdown 的问题是机器不好解析"这个技能叫什么、什么时候触发"。加上 YAML frontmatter 之后，就有了结构化的字段：

--- name: code-review description: 对代码变更进行系统性审查，覆盖安全、性能、可读性 trigger: 当用户请求代码审查或提交 PR 时 tools: [claude-code, codex] ---

第三，转换成本低。从 Markdown+frontmatter 转换到其他格式，比从某种私有格式转换要容易得多。因为 Markdown 的解析库遍地都是，YAML 也是。

注意：frontmatter 里的字段命名要尽量通用，别用某个工具特有的叫法。比如用trigger而不是claude_trigger，这样转换到其他工具时映射关系更清晰。

2.3 目录结构实战拆解

我把一个典型的聚合项目目录结构画出来，你对照着理解每一层的作用：

awesome-skills/ ├── skills/ # 技能存储层，所有技能的唯一真相来源 │ ├── code-review/ │ │ ├── SKILL.md # 技能主体，含 frontmatter │ │ └── assets/ # 该技能用到的模板、示例 │ ├── refactor/ │ └── commit-message/ ├── adapters/ # 适配层，各工具的转换规则 │ ├── claude-code.yaml │ ├── codex.yaml │ └── generic.yaml ├── scripts/ # 分发脚本 │ ├── install.sh │ └── sync.sh ├── config.yaml # 全局配置，指定各工具的技能目录 └── README.md

这个结构里，skills/是核心，你日常维护的就是这里。adapters/和scripts/是基础设施，配好之后基本不用动。config.yaml是你需要根据自己机器环境调整的地方，告诉项目各个工具的技能目录在哪。

我特别想强调skills/作为"唯一真相来源"这个设计。很多人的做法是直接在各个工具的技能目录里改，改完再手动同步，这就回到了分散管理的老路。正确的做法是：永远只改skills/里的内容，然后跑同步脚本。这样你永远知道最新版本在哪。

2.4 适配层的映射逻辑

适配层具体怎么工作，我用一个表格说明不同工具需要的字段差异，以及映射关系：

这张表是示意，实际字段名以各工具文档为准。核心思路是：在适配层做一次映射，而不是在每个技能文件里写多套字段。这样你新增一个技能，只需要按统一格式写一遍，适配层自动帮你转换。

这种设计的另一个好处是，将来如果某个工具改了字段名，你只需要改适配层的一个映射文件，所有技能自动跟着变，不用逐个技能去改。这就是"聚合"相对于"堆叠"的本质区别。

3. 技能文件的编写规范与实操要点

3.1 一个合格技能文件长什么样

技能文件的质量直接决定了 AI 助手能不能正确理解和使用它。我见过太多人写的技能文件，要么太笼统（"帮我审查代码"），要么太啰嗦（写了两千字还没说到重点）。一个好的技能文件，应该像一份精准的岗位说明书。

先看一个完整的示例：

--- name: code-review description: 对代码变更进行系统性审查，覆盖安全漏洞、性能问题、可读性和边界条件 trigger: 当用户请求代码审查、提交 PR 或要求检查代码质量时 tools: [claude-code, codex] version: 1.2.0 --- # 代码审查技能 ## 审查维度 按以下顺序逐项检查，每项都要给出具体行号和修改建议： 1. **安全**：检查注入风险、敏感信息硬编码、权限校验缺失 2. **性能**：识别不必要的循环嵌套、重复计算、大对象拷贝 3. **可读性**：命名是否表意、函数是否过长、注释是否必要 4. **边界条件**：空值、越界、并发、异常路径是否处理 ## 输出格式 对每个问题，按以下格式输出： - 位置：文件路径:行号 - 严重级别：高/中/低 - 问题描述：一句话说清 - 修改建议：给出可直接替换的代码 ## 注意事项 - 不要为了凑数而报告无关紧要的风格问题 - 严重级别为"高"的问题必须给出完整修复代码 - 如果代码整体质量良好，明确说明"未发现高优先级问题"

这个文件好在哪？它有明确的执行顺序、明确的输出格式、明确的边界约束。AI 助手拿到它，知道先干什么后干什么，知道输出成什么样，知道什么不该做。这才是可用的技能。

3.2 frontmatter 字段的填写技巧

frontmatter 是技能的"身份证"，填不好会导致技能无法被正确触发。几个关键字段的填写心得：

name用短横线连接的英文小写，别用中文，别用空格。因为很多工具会把它当文件名或标识符用，中文和空格容易出问题。比如code-review而不是代码审查。

description是最重要的字段，它决定了 AI 助手在什么场景下会想起这个技能。写法上要包含"做什么"和"什么时候用"两层信息。对比一下：

• 差的写法：代码审查
• 好的写法：对代码变更进行系统性审查，覆盖安全、性能、可读性和边界条件，适用于提交 PR 前的自查

好的写法里，"提交 PR 前的自查"就是触发场景，AI 助手看到用户说"帮我看看这个 PR"，就能匹配上。

trigger字段可以写得更具体，列出典型的触发语句。有些工具支持多个触发词，用列表形式：

trigger: - 代码审查 - review 一下 - 检查代码质量 - 提交前自查

tools字段声明这个技能适配哪些工具。如果你的技能只用了通用的自然语言指令，那可以适配所有工具；如果用了某个工具特有的语法（比如特定的变量占位符），就要明确标注，避免转换到其他工具时出错。

3.3 技能正文的写作原则

正文部分是把技能"教会"给 AI 助手的核心内容。我总结了几个实操原则。

原则一：用祈使句，别用描述句。你要的是 AI 去执行，所以直接写"检查 X"、"输出 Y"，而不是"这个技能会检查 X"。前者是命令，后者是说明，模型对命令的响应更直接。

原则二：给具体标准，别给模糊要求。"代码要写得好"是废话，"函数不超过 50 行、嵌套不超过 3 层"才是可执行的。凡是能用数字量化的，就量化。

原则三：用列表和分步骤，别用大段文字。AI 助手处理结构化内容比处理散文更可靠。一个技能正文如果是一大段没有分点的文字，模型很容易漏掉其中的要求。

原则四：明确输出格式。这是最容易被忽略但最重要的一点。你不告诉 AI 输出成什么样，它每次给你的格式都不一样，你就没法做后续处理。用模板或示例把输出格式固定下来。

实操心得：写技能正文时，把自己想象成在给一个聪明但完全不了解你项目背景的新同事写操作手册。他能力很强，但需要你把"做什么、怎么做、做成什么样"说清楚。这个心态能帮你写出高质量技能。

3.4 版本管理不能省

技能是要迭代的。今天你觉得审查维度是 4 个，明天可能发现漏了"日志规范"这一项。所以 frontmatter 里加version字段，正文里用注释记录变更历史，是很有必要的。

version: 1.2.0 changelog: - 1.2.0: 增加日志规范检查维度 - 1.1.0: 优化输出格式，增加严重级别 - 1.0.0: 初始版本

这样做的好处是，当某个技能表现不如预期时，你能快速定位是哪个版本引入的问题，也能回滚到之前的版本。聚合项目里技能多了之后，没有版本管理会非常混乱。

4. 从零搭建聚合工作流的完整实操

4.1 环境准备与初始化

假设你现在要从零开始，把手上散落的技能聚合起来。我按实际操作顺序走一遍。

第一步，创建聚合仓库。你可以用 Git 管理，方便版本追踪和团队共享：

mkdir awesome-skills cd awesome-skills git init mkdir -p skills adapters scripts

第二步，创建全局配置文件config.yaml，告诉项目各个工具的技能目录在哪：

tools: claude-code: skill_dir: ~/.claude/skills format: markdown-frontmatter codex: skill_dir: ~/.codex/skills format: markdown-frontmatter sync: mode: symlink # 可选 symlink 或 copy backup: true # 同步前备份原目录

这里mode选symlink还是copy是个关键决策。软链接的好处是改一处全局生效，不用重复同步；坏处是某些工具可能不跟随软链接，或者跨文件系统时软链接失效。复制的好处是兼容性好，坏处是每次改完都要重新同步。我的建议是先试软链接，不行再退回复制。

第三步，把你现有的技能文件收集起来。这一步最费时间，因为技能可能散落在各个项目的隐藏目录里。用find命令帮你找：

find ~ -type d -name "skills" 2>/dev/null find ~ -name "SKILL.md" 2>/dev/null

找到之后，按类别归入skills/目录。归类时别纠结，先粗分，用起来之后再调整。

4.2 编写适配器配置

适配器是连接统一格式和各工具的桥梁。以 Claude Code 为例，适配器配置大概长这样：

# adapters/claude-code.yaml name: claude-code output_format: markdown-frontmatter field_mapping: name: name description: description trigger: when_to_use tools: allowed_tools frontmatter_template: | --- name: {{name}} description: {{description}} when_to_use: {{trigger}} allowed_tools: {{tools}} ---

这个配置告诉同步脚本：把统一格式里的trigger字段，写到 Claude Code 技能文件的when_to_use字段里。其他工具类似，只是字段映射不同。

写适配器的时候有个坑要注意：不同工具对 frontmatter 的解析严格程度不一样。有的工具遇到不认识的字段会报错，有的会忽略。所以适配器里最好只输出目标工具认识的字段，多余的字段在转换时过滤掉。

4.3 同步脚本的编写

同步脚本是分发层的核心。一个最小可用的同步脚本逻辑如下：

#!/bin/bash # scripts/sync.sh set -e CONFIG="config.yaml" SKILLS_DIR="skills" # 读取配置，遍历每个工具 for tool in $(yq '.tools | keys | .[]' "$CONFIG"); do skill_dir=$(yq ".tools.$tool.skill_dir" "$CONFIG") mode=$(yq '.sync.mode' "$CONFIG") echo "同步到 $tool: $skill_dir" # 备份 if [ "$(yq '.sync.backup' "$CONFIG")" = "true" ] && [ -d "$skill_dir" ]; then cp -r "$skill_dir" "${skill_dir}.bak.$(date +%s)" fi mkdir -p "$skill_dir" # 遍历技能，转换并投放 for skill_path in "$SKILLS_DIR"/*/; do skill_name=$(basename "$skill_path") target="$skill_dir/$skill_name" if [ "$mode" = "symlink" ]; then ln -sfn "$(pwd)/$skill_path" "$target" else cp -r "$skill_path" "$target" fi done done echo "同步完成"

这个脚本用了yq来解析 YAML，你需要先装它。脚本的逻辑很直白：读配置、备份、遍历技能、按模式投放。实际项目中你可能还需要加字段转换的逻辑，那部分可以用 Python 写，更灵活。

注意：同步脚本一定要有备份步骤。我第一次写这类脚本时没加备份，结果一次配置写错，把原有的技能目录覆盖了，损失了一批没提交到 Git 的技能。血的教训。

4.4 验证同步结果

同步跑完之后，别急着用，先验证。验证分三步：

第一步，检查文件是否到位。进到目标工具的技能目录，看看技能文件在不在，frontmatter 格式对不对。

第二步，检查软链接是否有效。如果是软链接模式，用ls -la看链接指向对不对，用cat看能不能读到内容。

第三步，实际调用测试。打开 AI 助手，用触发语句试一下，看技能能不能被正确识别和触发。这一步最关键，因为格式对不对最终要看工具认不认。

我建议写一个简单的验证脚本，把这三步自动化：

#!/bin/bash # scripts/verify.sh for skill_dir in $(yq '.tools[].skill_dir' config.yaml); do echo "验证 $skill_dir" for skill in "$skill_dir"/*/; do if [ -f "$skill/SKILL.md" ]; then echo " OK: $(basename $skill)" else echo " 缺失: $(basename $skill)" fi done done

跑一遍，哪些技能没同步成功一目了然。

5. 常见问题排查与避坑经验

5.1 技能不触发怎么办

这是最高频的问题。你明明写了技能，AI 助手就是不用。排查思路按以下顺序来：

先看 description 和 trigger 写得够不够具体。大部分不触发的原因是描述太笼统，模型匹配不上。把触发场景写具体，比如把"代码相关"改成"当用户请求代码审查、重构建议或提交信息生成时"。

再看 frontmatter 格式对不对。YAML 对缩进极其敏感，一个空格错了整个 frontmatter 就解析失败。用在线 YAML 校验工具过一遍，或者用python -c "import yaml; yaml.safe_load(open('SKILL.md').read().split('---')[1])"检查。

然后看技能目录位置对不对。不同工具扫描技能的目录不一样，确认你的config.yaml里配的路径和工具实际读取的路径一致。

最后看技能数量。有些工具对同时加载的技能数量有限制，技能太多会导致部分技能被忽略。如果是这个原因，把不常用的技能先移出去。

5.2 软链接失效的几种情况

软链接模式虽然方便，但坑也不少。我整理了几种常见情况和应对方法：

我的经验是：在同一个文件系统内、工具支持软链接的情况下用 symlink，否则一律用 copy。别为了省事强行用软链接，最后排查问题的时间远超同步的时间。

5.3 多工具字段冲突的处理

当你把同一个技能同步到多个工具时，可能遇到字段冲突。比如 Claude Code 需要when_to_use字段，Codex 需要activation字段，而你的统一格式里只有一个trigger。适配器能解决大部分映射问题，但有些冲突是映射解决不了的。

比如某个工具要求技能必须有category字段，另一个工具不认这个字段还会报错。这时候有两个方案：

方案一：在适配器里做条件输出。根据目标工具，决定输出哪些字段。这需要在适配器配置里支持条件逻辑，稍微复杂一点但最干净。

方案二：在技能文件里用工具专属的 frontmatter 块。比如：

--- name: code-review description: ... trigger: ... claude-code: category: review codex: category: quality ---

适配器读取对应工具的专属块，合并到输出里。这个方案灵活，但技能文件会稍微臃肿。

我倾向于方案一，因为技能文件保持干净，复杂度都收敛在适配层。适配层本来就是干这个的。

5.4 技能更新的同步时机

技能更新后什么时候同步，也是个需要想清楚的问题。几种策略：

• 手动同步：改完技能手动跑sync.sh。简单可控，但容易忘。
• Git hook 自动同步：提交时自动触发同步。适合用 Git 管理的场景。
• 文件监听自动同步：用fswatch之类的工具监听skills/目录，有变化就同步。最省心，但可能同步过于频繁。

我的做法是Git hook + 手动兜底。平时靠 hook 自动同步，偶尔 hook 没触发就手动跑一下。文件监听我试过，改一个文件触发好几次同步，反而添乱，不推荐。

5.5 常见问题速查表

把上面这些整理成一张表，方便你遇到问题时快速定位：

实操心得：排查技能问题时，养成"从源到目标"逐层检查的习惯——先确认skills/里的源文件没问题，再确认适配器转换没问题，最后确认目标工具读取没问题。逐层排除，比东一榔头西一棒子高效得多。

6. 技能聚合之后的进阶玩法

6.1 技能组合与流水线

当你的技能库积累到一定规模，单个技能已经不够用了，可以考虑把技能组合成流水线。比如"提交前检查"这条流水线，可以串起三个技能：代码审查、提交信息生成、变更日志更新。

实现方式是在聚合项目里加一层"组合技能"的定义：

# skills/pipelines/pre-commit.yaml name: pre-commit description: 提交前的完整检查流水线 steps: - skill: code-review - skill: commit-message - skill: changelog-update

同步时，组合技能会被展开成各个工具能理解的顺序指令。这样你一句话就能触发一整套检查，不用逐个调用。

6.2 团队共享与权限控制

团队场景下，技能库需要区分"公共技能"和"个人技能"。公共技能所有人可见，个人技能只有自己用。实现方式是在skills/下分两个目录：

skills/ shared/ # 团队公共技能，提交到共享仓库 personal/ # 个人技能，不提交或提交到个人分支

同步脚本根据配置决定同步哪些。公共技能同步到所有团队成员的工具目录，个人技能只同步到自己的。这样既保证了团队规范统一，又保留了个性化空间。

6.3 技能效果追踪

技能用起来之后，怎么知道哪个技能好用、哪个需要改进？可以加一个简单的使用日志。在技能正文里要求 AI 助手在调用技能时输出一行标记，然后用脚本统计这些标记的出现频率。

## 调用标记 每次使用本技能时，在输出末尾附加一行： [SKILL:code-review]

统计脚本扫一遍日志，就能看出哪些技能被高频使用，哪些从来没用过。没用过的技能要么删掉，要么改进触发条件。这个反馈闭环能让你的技能库持续进化，而不是越堆越乱。

6.4 跨工具技能迁移的注意事项

最后说一个容易被忽略的点：技能从 A 工具迁移到 B 工具时，不只是字段名要换，技能的"语气"和"假设"也可能需要调整。不同工具对指令的理解风格有差异，有的更吃结构化列表，有的对自然语言描述响应更好。

我的做法是，迁移后一定做一次实际测试，观察输出质量。如果明显变差，就在适配器里针对该工具做一版微调后的正文。这听起来麻烦，但比技能迁移过去却不好用要强。

技能聚合这件事，说到底是在跟"分散"和"重复"作斗争。工具越多，这个斗争越有必要。把技能收敛到一个源、一套格式、一个同步流程，你花在维护上的时间会大幅下降，花在真正写代码上的时间自然就多了。我自己的技能库从散落各处到统一管理，前后折腾了大概两周，但之后每次新增技能的成本降到了原来的三分之一不到。这个投入产出比，值得。