Claude Code Skills 与 OpenSkills：从入门到上手技术指南

任侠
AI技术
-475分钟前
4热度
0评论

[隐藏]

本文面向已经在用或准备使用 AI 编码助手（如 Claude Code、Cursor、Windsurf 等）的工程师与团队，系统介绍：

Claude Code Skills 是什么、能解决什么问题、如何编写自己的 SKILL.md
OpenSkills 是什么、如何把 Claude 的技能体系推广到“所有” AI 编码代理
从 0 到 1 的实践路径：从安装、配置到团队级最佳实践

一、为什么要关心 “Skills”？

传统使用 AI 编码助手的方式是“临时对话 + 即兴提示词”：
每次让模型做代码审查、写测试、做安全检查，都要重新解释背景、标准和流程，效率不稳定、可复用性差。

Claude Code 的 Skills 提供了一种结构化方式：

把“某件事怎么做”写成一个 可版本控制的 Markdown 文件（SKILL.md），让 AI 自动在合适的时候调用它，而不是每次都重新手写 prompt。[2]

而 OpenSkills 则解决了另外一个关键问题：

让这种 Skill 格式成为“通用标准”，任何支持命令行 / Bash 的 AI 代理（Claude Code、Cursor、Windsurf、Aider、Codex CLI 等）都能加载并共享同一套技能库。[1][4][5]

二、Claude Code Skills 入门：把“提示词”升级为“技能”

2.1 Skills 是什么？

官方定义：Skill 是一个教 Claude 做某件具体事情的 Markdown 文件，例如：

按团队规范做 PR 代码审查
按统一模板生成 Git 提交信息
按既定流程处理 PDF / Web 抓取 / 安全扫描

核心特点：[2][10]

文件化：一个技能就是一个目录，至少包含一个 SKILL.md
结构化元数据：通过 YAML front matter 描述 name、description、权限、模型等
渐进式披露：主文件只给高层指引，需要时再加载详细文档或脚本
自动发现与调用：Claude 会根据 description 自动决定是否使用技能

2.2 SKILL.md 标准格式

一个最小可用的 SKILL.md：

---
name: git-commit-message
description: 基于 git diff 自动生成符合团队规范的提交信息
---
# Git 提交信息生成器

## 使用说明

1. 在项目根目录执行：`git diff --staged`
2. 把输出粘贴给我，我会生成：
   - 不超过 50 字符的标题
   - 必要时的多行详细描述
   - 涉及模块 / 组件列表

Front matter 关键字段解释（节选）[2]：

字段	是否必需	作用
`name`	是	技能名，只能用小写字母、数字、连字符，需与目录名一致
`description`	是	这一技能做什么、什么时候用，Claude 靠它来“选技能”
`allowed-tools`	否	限制技能执行时可以动用哪些工具（如 Read、Bash、Grep 等）
`model`	否	该技能激活时用哪个模型，不写则用当前会话模型
`context`	否	设为 `fork` 时：在独立子代理上下文中执行，不污染主对话
`agent`	否	当 `context: fork` 时选择子代理类型（如 Explore、Plan 等）
`hooks`	否	技能生命周期钩子：PreToolUse、PostToolUse、Stop 等
`user-invocable`	否	是否出现在斜杠命令菜单，默认 `true`

2.3 多文件技能与“渐进式披露”

对复杂场景（如 PDF 处理、数据分析），推荐用多文件结构组织知识：[2]

pdf-processing/
├── SKILL.md          # 概览、使用说明、快速开始
├── REFERENCE.md      # 详细 API 文档
├── FORMS.md          # 表单字段映射与填充说明
└── scripts/
    ├── extract_text.py
    └── fill_form.py

在 SKILL.md 中只给出关键指引与入口：

## 附加资源

- API 细节见 [REFERENCE.md](REFERENCE.md)
- 表单示例与字段映射见 [FORMS.md](FORMS.md)

## 运行脚本

提取文本示例：

python scripts/extract_text.py input.pdf output.txt

这样 Claude 只有在确有需要时才会打开 REFERENCE.md 等长文档，避免一次性把所有文档塞进上下文。

2.4 动态变量与会话感知

Skills 支持两个常用替换变量：[2]

$ARGUMENTS：技能被调用时传入的参数整体
${CLAUDE_SESSION_ID}：当前会话 ID，可用于日志文件名等

示例：会话日志技能

---
name: session-logger
description: 记录当前会话的关键操作日志
---
请把以下内容追加写入 logs/${CLAUDE_SESSION_ID}.log：

$ARGUMENTS

三、从“命令”到“技能”：与 Slash Commands 的关系

Claude Code 还有一类“斜杠命令”（Slash Commands），本质是显式触发的快捷 Prompt，Skills 则是被动、自动触发的知识模块：[1][3][6][7]

简要区别：

能力	Slash Commands	Skills
触发方式	用户键入 `/xxx`	Claude 自动根据 description 选择
适合场景	个人快捷操作	团队标准、流程、体系化知识
文件位置	`.claude/commands/`	`.claude/skills/`
是否可编排	一般由用户显式调用	可被其他技能或代理自动使用

实践建议：

个人效率：先从少量 Slash Commands 入手（如 /format-doc、/gen-test）
团队协作：把稳定、共识化的做事方法沉淀成 Skills
在 Claude Code 文档和实践文章里，通常会建议：“命令是快捷键，Skills 是团队的 SOP（标准操作流程）”[1][9]

四、OpenSkills：让 Claude Skills 跑在“所有” AI 代理里

4.1 OpenSkills 是什么？

OpenSkills 是一个面向开发者的 通用技能加载器 CLI 工具：[1][4][5]

完全兼容 Claude Code 的 SKILL.md 规范（同样目录结构、元数据格式）
支持将技能安装到：
- Claude Code
- Cursor
- Windsurf
- Aider
- 各种基于 CLI 的本地 / 远程代理
支持从任何 Git 仓库（包括私有）加载技能
支持本地开发目录通过符号链接接入技能系统

一句话：“写一次 SKILL.md，所有 AI 编码工具通用。”

4.2 安装与快速上手

环境要求：Node.js 20.6+、Git。[1]

快速安装官方技能库（以 Anthropics/skills 为例）[1]：

# 项目本地安装（默认）
npx openskills install anthropics/skills

# 同步生成 AGENTS.md
npx openskills sync

安装位置默认是项目目录下，例如：

.claude/skills/（默认 Claude 目录）
或 .agent/skills/（universal 模式，适配多代理环境）

常用命令一览：[1]

命令	作用
`openskills install` / `npx openskills install`	安装技能（支持 Git 仓库 / 本地路径）
`openskills sync`	扫描技能并生成 AGENTS.md
`openskills list`	查看已安装技能
`openskills read`	读取某个技能内容
`openskills update`	更新技能到最新版本
`openskills remove`	卸载技能

4.3 通用模式（universal mode）与优先级

为了避免和 Claude 内置插件市场路径冲突，OpenSkills 提供“通用模式”：在 .agent/skills/ 下安装。[1][4][5]

# 安装到通用目录
npx openskills install anthropics/skills --universal

技能检索优先级大致为：[1]

当前项目 .agent/skills/
用户目录 ~/.agent/skills/
当前项目 .claude/skills/
用户目录 ~/.claude/skills/

这意味着：

团队可以在仓库里放一套“项目技能”（项目优先）
个人可以在主目录里放“个人技能”（当项目没覆盖时才用）

4.4 自建技能库与协作开发

OpenSkills 是“加载器”，你可以：

建一个团队技能仓库（如 company/skills）
结构如下：

company-skills/
├── git-commit-message/
│   └── SKILL.md
├── pr-review/
│   ├── SKILL.md
│   └── checklists.md
└── security-scan/
    ├── SKILL.md
    └── scripts/
        └── run_scan.sh

团队成员统一通过：

npx openskills install company/skills --universal
npx openskills sync

这样无论是 Claude Code、Cursor 还是其他代理，只要支持执行 Bash/CLI，都能共享这套 Skill 体系。[4][5]

五、从 0 到 1：实战路径示例

下面给出一个从入门到团队落地的分阶段建议，你可以按需裁剪。

阶段 1：个人入门（30–60 分钟）

目标：自己在 Claude Code 里跑通第一个 Skill。

mkdir -p .claude/skills/git-commit-message

写入最小版本 SKILL.md（见 2.2 示例）
打开 Claude Code，在该仓库会话中问：

“请帮我为当前 staged 的变更生成一条规范的提交信息。”

Claude 会自动发现并使用 git-commit-message 这个技能（因为 description 匹配场景）。[2]

阶段 2：个人增强 + OpenSkills 引入（1–2 小时）

目标：把官方 / 社区技能库接入自己的工具链。

全局安装 OpenSkills：[1]

npm install -g openskills

安装官方技能集合或社区集合，例如：

# 官方技能
openskills install anthropics/skills --global

# 或者某个精选技能集（示例）
openskills install travisvn/awesome-claude-skills

在你的日常开发工具（Claude Code、Cursor 等）中用自然语言尝试触发这些技能，例如：

“请用 Trail of Bits 的技能帮我做一次静态安全分析。”[10]

阶段 3：团队化技能库（1 天～若干周）

目标：把“团队做事方法”沉淀成技能，并让所有 AI 代理统一使用。

建议分三步：

盘点可标准化的场景
- PR 审查 checklist
- 安全扫描流程
- 前端组件规范 / 设计系统使用规范
- 日志与监控埋点标准
为每类场景设计一个 Skill
- 一个场景 = 一个目录 + 一个 SKILL.md
- 把“何时用”“怎么做”“注意事项”写清楚
- 可以在 SKILL.md 中引用团队文档链接或本仓库的 docs/*.md
建立技能仓库 + OpenSkills 接入
- 把所有技能放在 company/skills 仓库
- 通过 openskills install company/skills --universal 安装给全员
- 把 openskills sync 加入 CI 或 pre-commit/pipeline 中，保证版本一致

六、典型高级用法与最佳实践

6.1 利用 `context: fork` 做“深度分析不污染主对话”

示例：代码质量深度分析技能：[2]

---
name: code-analysis
description: 对当前仓库代码进行全面质量分析并生成报告
context: fork
agent: Explore
---
在这个独立上下文中，请：
1. 扫描代码结构，列出模块和依赖关系
2. 分析复杂度和潜在技术债
3. 给出重构优先级建议

优势：

分析对话“跑偏”不会影响你在主窗口的当前任务
适合长流程任务：归档、评审、架构分析等

6.2 `allowed-tools` 做权限收敛与安全边界

比如只允许读文件、不允许改写：

---
name: reading-files-safely
description: 在只读模式下查看项目文件
allowed-tools:
  - Read
  - Grep
  - Glob
---

对敏感操作（如部署生产）则显式限制脚本与工具，并结合 hooks 做安全检查：

---
name: production-deploy
description: 部署到生产环境前需要严格校验
allowed-tools: Bash(ssh)
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh $TOOL_INPUT"
          once: true
user-invocable: false  # 禁止在聊天中直接“点一下就部署”
---

6.3 与 CI/CD 结合：自动同步技能版本

将 OpenSkills 融入流水线：每当技能仓库有新 Tag，就同步到各项目的 AGENTS.md。[1]

# .github/workflows/skills-sync.yml
name: Sync Skills

on:
  push:
    tags: ['v*.*.*']

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g openskills
      - run: openskills sync -y -o AGENTS.md
      - run: |
          git config user.name "CI Bot"
          git config user.email "[email protected]"
          git commit -am "chore: update AGENTS.md"
          git push

这样你的代理（Claude Code、Cursor 等）在拉代码时，自动获得最新技能组装信息。

七、实践建议总结

如果你刚准备落地 Claude Code Skills + OpenSkills，可以参考下面的路线：

先用现成技能短平快见效
- 从官方技能库 / awesome-claude-skills / superpowers 等社区集合中挑几个高价值技能安装。
- 熟悉 SKILL.md 的结构与写法。[10]
很快开始写第一个“团队自定义技能”
- 选一个“你们已经有文档或隐性规范”的场景（如 PR 代码审查）。
- 把它翻译成 SKILL.md，加入必要示例和反例。
引入 OpenSkills 统一安装和版本管理
- 团队建一个 company/skills 仓库，所有技能都在这里维护。
- 使用 openskills install + openskills sync，并纳入 CI 流程。
逐步体系化：把“团队知识”转成“团队技能库”
- 安全、性能、架构决策、风格规范等都可以成为技能。
- 通过 context: fork、allowed-tools、hooks 等进阶特性，建立规范、安全的自动化工作流。