从Vibe Coding到OpenSkills：AI编程技能体系化落地实战

1. 环境认知：Vibe Coding 为什么突然需要“体系化”

1.1 先聊聊 Vibe Coding 到底在解决什么问题

我最早接触 Vibe Coding 这个概念，是在 Karpathy 提出这个词前后。那会儿我团队里已经有好几个工程师在用 Claude Code 写代码了，但大家的状态基本是“把需求丢进去，功能出来了就用，没出来就换个说法再试”。效率确实高，但问题也很明显：同一个需求，上午写的效果和下午写的效果完全不一样；同一个项目，不同人用出来的结果差距巨大。

后来我才意识到，Vibe Coding 的本质不是“让 AI 写代码”，而是“让 AI 在足够明确的上下文里持续产出高质量代码”。这句话反过来想，就是大多数 Vibe Coding 翻车的场景——上下文太薄、标准太模糊、反馈太随机。你对着 AI 说一句“帮我写个登录页面”，它给你变出三个方案，每个都像那么回事，但每个都跟你的业务设计对不上。

这个问题靠“提示词工程”解决不了。你有几百条 prompt，每次还得手动选、手动塞；换个模型、换个工具、换个同事来用，效果立刻漂移。真正能扛住 Vibe Coding 规模化复制的东西，是把“AI 怎么工作”这件事实体化、文件化、版本化，变成项目里可以被自动调用的一块块能力。这就是 Skills 出现的大背景。

1.2 Skills 是 Vibe Coding 走向工程化的最小载体

Skills 这个词在 Claude Code 生态里出现以后，我第一反应是：这不就是“给 AI 写工作手册”嘛。你把某个领域的做法、禁忌、流程、示例写成一个文件夹，AI 在干活的时候发现场景匹配，就自动翻开这个手册照着执行。

和 prompt 相比，Skills 有几个特别实在的好处。第一，它是结构化的，有名字、有描述、有正文、有附加资源，AI 能自动识别什么时候该用，不需要你手动提醒。第二，它是可复用的，放在项目里到处都能被调，甚至可以跨项目分发。第三，它是可版本化的，改坏了能回滚，谁改的一清二楚。

但这里出现了一个新的问题：Skills 的格式并不统一。Claude 生态有自己的 Agent Skills 规范，社区里还有一堆各自定义的 scheme，你在 Claude 上写好的 Skill，换到另一个工具上几乎不能用。同一个团队的 Skill 散落在各处，有写在 Markdown 里的，有写成一个 Python 脚本的，有干脆存在 Notion 里当文档看的。

所以我开始认真研究 OpenSkills——它本质上是在给“Skills 怎么写、怎么组织、怎么发现、怎么复用”定一个统一游戏规则。这篇文章就是想把我在这个方向上的完整落地经验梳理出来，从原理到实操，从搭一个 Skill 到团队级治理，一次讲透。

2. 底层原理：Claude Skills 和 OpenSkills 的机制关系

2.1 Claude Code 的 Skills 是怎么工作的

先说 Claude 这边的机制。Claude Code 里，Skill 本质是一个目录，目录里必须有一个 SKILL.md 文件，这个文件头部有一个 YAML frontmatter，里面写 name、description、allowed-tools 这类元信息。正文部分就是给模型看的“工作手册”，告诉它在什么场景下做什么事、按什么步骤做、有什么禁忌。

这里最容易被新手忽略的是 description 字段。它不是给人看的，是给模型的“索引”。模型拿到用户请求后，会先把你项目里的所有 Skill 描述都过一遍，找到最匹配的那一个，然后再把描述对应的正文加载进来。换句话说，你的 Skill 本身写得再好，如果 description 写得模糊，模型根本不知道什么时候该调它，这个 Skill 就永远沉在水底。

我见过很多人把 SKILL.md 写成了“技术方案文档”，洋洋洒洒五千字，但描述里只写了“代码审查”，没有任何触发场景和关键词。结果就是在实际使用中，Claude 经常漏掉这个技能，还是用默认方式处理 code review。后来我把描述改成“当用户在 Pull Request 中要求审查 Python 代码，或提到‘帮我检查这段代码有没有安全隐患’时使用”，触发率一下就上来了。

另一个关键点是 allowed-tools。Skill 可以声明自己需要哪些工具权限。比如代码审查 Skill 需要能读文件、运行命令，你就在这个字段里声明 bash、grep、read。这其实是一种安全边界，防止 Skill 在运行中干了超出预期的事。

2.2 从 Agent Skills 到 OpenSkills：格式统一的演进逻辑

Anthropic 后来发布了官方的 Agent Skills 规范，定义了 SKILL.md 的结构，还给了 building blocks（公共资源）这类概念。这套规范的好处是清晰、直接，你照着写就能得到一个可以被 Claude Code 正确加载的 Skill。

但如果你同时用多个 AI 编程工具，或者想跟整个行业共享技能包，只认 Claude 的规范就不够了。OpenSkills 是在这个背景下出现的：它希望定义一套跨工具、跨模型的 Skills 标准。你可以把它理解成“USB 接口”——不管你是 Windows、macOS 还是 Linux，只要设备支持这个接口标准，插上去就能用。

在 OpenSkills 的视角里，一个 Skill 包通常包含：

• SKILL.md：技能主体，核心指令和元信息
• 可选的辅助文件：脚本、模板、JSON Schema、示例代码
• 一个明确的目录结构：让工具能自动发现和加载

它跟 Claude 的 Agent Skills 格式在精神上是相通的，只是在几个地方做了更严格的约定，比如命名规范、资源文件放置规则、描述怎么写更容易被各种模型理解。这种“多一层抽象”的做法，短期看是增加了学习成本，长期看是在为你省掉“换工具就要重写一遍技能”的巨大成本。

2.3 为什么团队落地一定要选 OpenSkills 而不是直接写 Claude Skills

我踩过一个大坑。最开始团队里有人用 Claude 官方规范写了一批 Skill，在 Claude Code 里跑得很顺。后来团队引入了别的 AI 工具做代码摘要和文档生成，想复用这批 Skill，结果发现格式完全不兼容，脚本里的资源引用方式也都是 Claude 特定的，根本没法迁移。那批 Skill 最后等于废了大半。

如果你们团队从第一天就按 OpenSkills 的约定组织技能包，情况就不一样。你在写每个 Skill 时会更注意：资源路径是不是相对路径？描述里是不是用了太多 Claude 特有的语气？辅助脚本是不是可以独立运行而不依赖某个特定模型？这些约束会让你的 Skill 更健康、更可移植。

所以我的判断是：个人玩 Vibe Coding，直接用 Claude 官方规范够用了；但如果你想在团队里把 Vibe Coding 做成一个可持续的工程体系，OpenSkills 是更值得投入的方向。

3. 落地方法论：把模糊需求变成可执行的 Skill 定义

3.1 先做技能盘点，再动手写文件

很多团队一听到 OpenSkills，第一反应是“赶紧写几个 Skill 跑起来”。这其实是本末倒置。你不清楚自己要沉淀什么能力，写出来的 Skill 十有八九是“把 AI 说明书抄了一遍”，既没有业务属性，也没有复用价值。

正确做法是先做技能盘点。把你们项目里反复出现的工作流列出来，然后问三个问题：这件事是不是每周都发生？是不是每次都依赖某个人的经验？AI 能不能通过学习规则帮我做掉大部分？三个问题都是“是”，这就是一个值得做成 Skill 的点。

举我的实际例子。我们团队每周要做一次线上环境的依赖安全检查，流程很固定：拉版本清单、比对已知漏洞库、圈出高危项、写报告。这活以前是一名高级工程师在干，但规则极其稳定。我们就把它做成一个叫做 dependency_security_audit 的 Skill，把比对逻辑、高危判定标准、报告模板全写进 SKILL.md。从那以后，这个任务基本就不再占用高级工程师的时间，初级工程师只要会读报告就够。

3.2 Skill 设计五层模型

我在实际带队过程中，总结了一套 Skill 设计五层模型，照着这个思路设计基本不会跑偏。

第一层是场景层。先定义这个 Skill 在什么场景下被调用，触发条件是什么。这一层直接对应 SKILL.md 的 description 字段，一定要写清楚。

第二层是标准层。回答一个问题：这件事“做得好”的标准是什么？比如代码审查 Skill，你的标准可能是“必须检查 PII 泄露、必须识别硬编码密钥、必须给出修改建议而不是直接改代码”。标准不写清楚，AI 就会发挥创意。

第三层是流程层。把完成这件事的步骤用序列写出来，先做什么、再做什么、什么条件下中止。AI 特别擅长按流程执行，但它没有能力在没有流程的时候自己发明一个合理的流程。

第四层是资源层。哪些脚本、模板、数据表是执行这个 Skill 必需要的？放到 Skill 的附属目录里，用相对路径引用。

第五层是边界层。什么东西绝对不能做？比如安全审查 Skill 只负责检测，不负责自动修复；报告 Skill 只产英文报告，不产出中文。边界越明确，误操作越少。

3.3 SKILL.md 的 frontmatter 怎么写才算合格

SKILL.md 头部那一块 YAML 是整个 Skill 的“门面”。我建议至少包含这些字段：

description 我单独强调一下。别写“This skill helps with code review”这种废话，要写“Use this skill when the user asks to review Python code in a pull request, including checking security issues, code style, and maintainability. Trigger words: code review, check security, 检查这段代码”。模型的理解能力比你想象中好，你把触发场景描述得越具体，它在需要的时候拉出来用的概率越高。

3.4 OpenSkills 里的目录约定与命名的坑

OpenSkills 对目录结构的约定，我理解下来核心就几条：每个 Skill 一个独立目录；目录名和 name 字段保持一致；SKILL.md 放在根目录；辅助资源放子目录用相对路径引用。

命名上踩过一个很典型的坑：有人把 Skill 名字起得特别诗意，比如 “guardian-angel-reviewer”，还觉得自己很酷。结果模型触发没问题，但人在维护时根本看不懂这是干嘛的。我现在的命名规范是“领域-动作”结构，比如 python-code-review、dependency-audit、api-doc-generator，一眼就知道这个 Skill 管什么。

4. 实战演示：45 分钟从零搭出一个可用的代码审查 Skill

4.1 场景设定和准备

我拿团队里最常用的“Python 代码审查”Skill 来做演示。目标很简单：当用户丢来一段 Python 代码或提到 code review 时，Claude 自动加载这个 Skill，按我们团队的标准做一次结构化审查。

准备工作只需要一个空目录，假设叫 python-code-review。你可以在任意路径下创建它，然后开始搭骨架。

bash复制mkdir python-code-review
cd python-code-review
touch SKILL.md
mkdir scripts
touch scripts/scan_secrets.py

4.2 编写 SKILL.md 正面示例

下面是这个 Skill 的完整 SKILL.md 示例，我会把关键字段逐行说明。

yaml复制---
name: python-code-review
description: Use when the user asks to review, check, or audit Python code, especially in pull requests or before merging. This includes identifying security issues, hardcoded secrets, exception handling problems, and maintainability concerns. Trigger on phrases like "review code", "帮我审查代码", "check this PR", "code audit".
version: 1.2.0
allowed-tools:
  - read
  - grep
  - bash
metadata:
  owner: dev-platform-team
  maintenance: monthly
---

这一段的重点在 description。能触发它的场景我都写进去了，还加了两句英文关键词和几个常见中文表述。这里有个面试官提示：description 不是写给人看的，是写给模型的索引系统看的；太短会导致该触发时不触发。

正文部分我习惯按“角色定义 -> 审查标准 -> 执行流程 -> 输出格式 -> 边界”的结构组织，这样模型在一个 Skill 内就能拿到全部上下文，不需要东拼西凑。

markdown复制# Python Code Review Skill

你就是一名有十年一线经验的 Python 资深审查者，工作是帮助团队在代码合并前发现真实风险。

## 审查标准

每段代码必须从以下四个维度依次检查：

1. 安全性：是否包含硬编码密钥、SQL 注入风险、任意文件读取、不安全的反序列化。
2. 正确性：是否有异常被静默吞掉、边界条件未处理、并发写入冲突。
3. 性能：是否有不必要的循环内重复计算、N+1 查询、明显可并行化却没有并行的逻辑。
4. 可维护性：命名是否清晰、函数是否过长、是否有明显可抽取的复用逻辑。

## 执行流程

1. 先用 grep 或 read 读取目标代码文件；
2. 运行 scripts/scan_secrets.py 做一次密钥扫描；
3. 按上述四个维度逐段分析；
4. 生成结构化审查报告。

## 输出格式

按以下 Markdown 结构输出，每个问题都要给出文件路径、行号、问题级别和修复建议：

- 风险摘要（高/中/低各几条）
- 安全发现
- 正确性问题
- 性能建议
- 可维护性建议
- 修改建议总结

## 边界

- 你只负责发现和报告，不负责直接修改代码，除非用户明确要求；
- 不确定的问题必须标注“需要人工确认”，绝对不能猜测；
- 不使用未在 allowed-tools 中声明的工具。

正文里的“边界”字段很多人会漏。你没有边界，模型就会替你做决定，把你的交出去前需要人来判断的事情自动“拍板”。一旦拍错板，锅还得你来背。

4.3 定义辅助脚本 scan_secrets.py

SKILL.md 只解决“指路”问题，真正执行重复检测动作，靠的是一个可以独立运行的 Python 脚本。这样就算未来换一个完全不认识 SKILL.md 的工具，只要这个脚本存在，核心检测能力就不会丢。

python复制#!/usr/bin/env python3
import re
import sys
import json

SECRET_PATTERNS = [
    (r'(?i)(api_key|apikey|secret|password|token)\s*[:=]\s*["\'][^"\']+["\']', "possible credential"),
    (r'AKIA[0-9A-Z]{16}', "AWS access key"),
    (r'ghp_[A-Za-z0-9]{36}', "GitHub personal access token"),
]

def scan_file(path: str) -> list:
    findings = []
    try:
        with open(path, "r", encoding="utf-8", errors="ignore") as f:
            for line_no, line in enumerate(f, start=1):
                for pattern, desc in SECRET_PATTERNS:
                    if re.search(pattern, line):
                        findings.append({
                            "file": path,
                            "line": line_no,
                            "desc": desc,
                            "snippet": line.strip()[:120],
                        })
    except Exception as exc:
        findings.append({"file": path, "line": 0, "desc": f"read error: {exc}"})
    return findings

if __name__ == "__main__":
    for path in sys.argv[1:]:
        for f in scan_file(path):
            print(json.dumps(f, ensure_ascii=False))

这个脚本不复杂，但定位很清晰：它是一道“机械闸门”，用正则扫出硬编码密钥和 token。真正的语义判断，比如有没有 SQL 注入，那还是交给模型理解。脚本和模型分工，正好是在最合适的位置用最合适的手段。

4.4 本地验证与调试：一个最容易翻车的环节

SKILL.md 写完、脚本写完，你以为就完了？还早。Skill 不像普通代码有明确的语法错误提示，它的问题是“加载了但不生效”或“生效了但行为不符合预期”，这两种问题都特别隐蔽。

我的调试方法是三步走。第一步，直接在 Claude Code 中问它“你能干什么”，看它有没有把你新加的 Skill 列出来。列不出来，大概率是目录放错了或者 frontmatter 有格式问题。第二步，故意触发它，比如丢一段带有硬编码密钥的 Python 代码，要求审查。看它有没有自动调用 scan_secrets.py。第三步，人工核对输出报告，看是不是严格按标准里的四个维度走的，有没有加戏。

第一次调试的时候，我发现在 SKILL.md 里写了一句“并尝试自己修复问题”，然后模型真的就把代码改了。这个问题诡异的地方在于“你觉得你写了边界，它还是会顺着流程走”。后来我把允许修改代码这个动作彻底从流程和边界两处同时抹掉，模型才彻底老实。这种你自己的指令内部有冲突的情况，AI 会倾向于执行“更积极的指令”，所以写的时候一定要自检一遍。

4.5 团队共享与版本管理

Skill 验证通过以后，不是放在个人目录里就完了。我们团队的做法是把所有 Skill 收进一个独立的 git 仓库，叫 skills 仓库，每个人本地开发、打 tag、发 PR，CI 里跑一个简单的“最小可用性检查”——至少解析 SKILL.md 的 frontmatter 是否合法、必须字段是否齐全。

仓库目录结构大概是：

text复制skills/
├── python-code-review/
│   ├── SKILL.md
│   └── scripts/scan_secrets.py
├── dependency-audit/
│   ├── SKILL.md
│   └── templates/report.md
└── README.md

前端同学把技能仓库 clone 下来之后，用环境变量或者软链接把它指到自己的 Claude Code 配置目录里，就能直接用。版本管理带来的最大好处，就是你可以像回滚代码一样回滚一个 Skill。有一次新人把扫描规则的正则写错，导致大量正常文件被标记为“疑似密钥”，我们直接回滚到上一个版本，一分钟解决问题，而不是半夜翻聊天记录去改。

5. 体系化落地的三个关键工程

5.1 建立 Skill 的质量门禁

团队里一旦 Skills 数量超过十个，你就会面临跟代码一样的问题：烂 Skill 污染好的 Skill。模型会在加载时看到一堆描述不清晰、逻辑混乱的 Skill，导致该触发的不触发，或者触发了但输出完全没法用。

所以我们给每个 Skill 上线前设了五个质量门禁，全部通过才能合进主分支：

一开始大家觉得繁琐，但坚持下来以后，Skill 的整体触发率和输出质量有了非常明显的提升。这套门禁的价值不在于“限制自由”，而是把写 Skill 从个人风格表演变成团队级工程实践。

5.2 Skill 的自动发现与分发机制

当 Skill 仓库大到一定程度，新的团队成员面对上百个 Skill，根本不知道该怎么找。这时候靠 README 手动索引已经不现实了。我们的做法是写一个简单的脚本，自动扫描所有 SKILL.md，把 name、description、version、owner 汇总成一个 index.json，生成的索引既可以帮助人快速检索，也可以在未来被其他工具读取。

这个脚本本身也就几十行 Python 的活，核心逻辑是遍历目录、解析 YAML、汇总字段、写索引文件：

bash复制python scripts/build_index.py

分发上面，我们目前是用 git 仓库加 tag 的方式。每个新版本打一个版本号 tag，团队成员按需求取用。将来如果团队规模扩大，可以考虑接入更自动化的分发渠道，但现阶段 git 已经足够稳定。

5.3 治理层面：Skill 的归属和生命周期

任何一个工程体系都会遇到同样的问题：谁来负责这个 Skill 的长期维护？Skill 没人维护，半年后项目上下文全变了，它里面的指令就过时了，甚至会产生误导。

我的建议比较朴素但有效：每个 Skill 必须在 metadata 里写 owner 和 maintenance 频率，owner 对 Skill 的质量负全责。每个月轮换一次，让不同的 owner 定期 review 自己名下的 Skill，检查描述是否准确、流程是否落后、脚本是否还能跑。如果连续两个周期都没有任何人使用某个 Skill，就要考虑下线停用。

我们团队依赖这个机制，把一个 Skill 数量从 20 多收敛到了 13 个，准确度反而提升了。少而精，永远比多而乱要好。

6. 常见问题与排查实录

6.1 为什么模型加载了我的 SKILL.md，但不调用它

排查顺序按下面来。先确认目录位置对不对，Claude Code 默认是找当前项目下的 .claude/skills 目录，你的 Skill 必须放在这里才可能被发现。再确认 SKILL.md 的 frontmatter 是否合法，YAML 格式有缩进错误、字段拼错，都会导致解析失败。最后检查 description 是否“可触发”，很多情况不是 Skill 坏了，而是你没在描述里写清楚触发场景。

我自己最常翻车的其实是第一种：在一个子目录下建了 Skill，却忘了放到 Claude Code 实际扫描的位置。这种问题非常隐蔽，因为你开的终端路径不对，你人觉得我建好了，但工具根本没看你建的那个目录。

6.2 模型找到了 Skill，但输出质量不如预期

Skill 被触发，恰恰说明它失效了，这是不少团队遇到的第二层问题。核心原因通常有两个。一个是正文里的指令不够具体，给模型的自由发挥空间太大；另一个是正文里没有“边界”，模型用主观臆想补全了缺失的部分。

高质量 Skill 的一个关键特征是“标准可枚举”。你把好/坏的定义一条条列出来，模型就有依可循。比如审查 Skill 里列清楚了四个维度，模型就会按维度输出，出来的报告结构和格式高度统一，质量自然就稳定。

6.3 同一个 Skill 在不同工具间表现不一致

这是 OpenSkills 要解决的痛点。同样的 SKILL.md，在 Claude 上用得很好，换到另一个工具上就完全不动；不是你的 Skill 写错了，是不同工具对描述的理解方式、对辅助脚本的调用机制有差异。

我的应对策略有两个。第一，辅助逻辑尽量用“能独立运行的最小脚本”，不要用某个工具特有的 API。第二，在正文里保持工具无关的表述，不说“Claude 可以这样做”，而是说“执行流程如下”。多工具兼容，不是在事后修，而是在写作时就回避特定工具的表达习惯。

6.4 一些不太容易察觉的设计反模式

我见过不少失败的 Skill，总结起来有几种典型反模式，遇到这些情况建议直接重构：

• 全能型 Skill，把“写代码”“审代码”“写文档”“部署”全塞进一个 SKILL.md，结果每个场景都做不好。Skill 要保持单一职责，宁可多建几个。
• 把业务机密写进 SKILL.md 然后同步到公开仓库，这种属于事故级别的错误。任何含敏感信息的 Skill，必须放在私有仓库，并在 CI 里加机密扫描。
• 只写“做什么”不写“不做什么”。模型边界缺失，迟早会给你搞出惊喜操作。

7. 最后说几句体感类的个人经验

Vibe Coding 发展到现在这个阶段，我觉得已经过了“靠感觉飞”的时代。最早大家把它当玩具，让它写写单页小工具、调调样式；现在团队真拿它写生产代码、管基础设施，如果还停留在临时聊天式编程，质量和风险都完全不可控。

我个人的体验是，Skills 体系化这件事，不是“大公司才需要”的繁文缛节，而是一个从 Vibe Coding 走向工程化的必经之路。哪怕是个人开发者，只有三五个项目，你也值得花一个下午把你反复做的事沉淀成 Skill。那个收益不是立竿见影的“效率翻倍”，而是你换项目、换模型、换工具的时候，能力还在，不用重新交学费。

OpenSkills 作为一套开放约定，给了我一个很好的抓手。它不强制你去用一个特定的平台，而是提供一种写技能的思考方式：面向场景、标准清晰、流程可执行、边界明确。这套思考方式，其实比任何一个具体工具都更值钱。

最后再分享一个小技巧：Seriously，写 Skill 的时候，把它当成是在给一个很聪明但不了解你们团队业务的新同事写交接文档，多想想对方会漏掉什么、会在哪里犯迷糊，你写出来的 SKILL.md 就差不了。好的 Skill 不是给 AI 看的，是给“下一任维护者”看的，顺便 AI 也读了而已。