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

本文面向已经在用或准备使用 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]

1. 当前项目 .agent/skills/
2. 用户目录 ~/.agent/skills/
3. 当前项目 .claude/skills/
4. 用户目录 ~/.claude/skills/

这意味着：

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

4.4 自建技能库与协作开发

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

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

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

1. 团队成员统一通过：

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。

1. 在任意代码仓库根目录创建：

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

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

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

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

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

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

1. 全局安装 OpenSkills：[1]

npm install -g openskills

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

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

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

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

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

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

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

建议分三步：

1. 盘点可标准化的场景

- PR 审查 checklist
- 安全扫描流程
- 前端组件规范 / 设计系统使用规范
- 日志与监控埋点标准
2. 为每类场景设计一个 Skill

- 一个场景 = 一个目录 + 一个 SKILL.md
- 把“何时用”“怎么做”“注意事项”写清楚
- 可以在 SKILL.md 中引用团队文档链接或本仓库的 docs/*.md
3. 建立技能仓库 + 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 "ci@example.com"
          git commit -am "chore: update AGENTS.md"
          git push

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

---

七、实践建议总结

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

1. 先用现成技能短平快见效

- 从官方技能库 / awesome-claude-skills / superpowers 等社区集合中挑几个高价值技能安装。
- 熟悉 SKILL.md 的结构与写法。[10]
2. 很快开始写第一个“团队自定义技能”

- 选一个“你们已经有文档或隐性规范”的场景（如 PR 代码审查）。
- 把它翻译成 SKILL.md，加入必要示例和反例。
3. 引入 OpenSkills 统一安装和版本管理

- 团队建一个 company/skills 仓库，所有技能都在这里维护。
- 使用 openskills install + openskills sync，并纳入 CI 流程。
4. 逐步体系化：把“团队知识”转成“团队技能库”

- 安全、性能、架构决策、风格规范等都可以成为技能。
- 通过 context: fork、allowed-tools、hooks 等进阶特性，建立规范、安全的自动化工作流。

长期来看，**技能系统会变成你团队的“AI 操作系统”**：

项目规范、最佳实践、领域知识，都通过 SKILL.md 与 OpenSkills 连接到各种 AI 编码工具上，真正做到“知识一次建模、处处使用”。

---

References

[1] numman-ali/openskills: Universal skills loader for AI coding agents. https://github.com/numman-ali/openskills

[2] Agent Skills - Claude Code Docs. https://code.claude.com/docs/en/skills

[3] How to Use Claude Code: A Guide to Slash Commands, Agents, Skills, and Plug-Ins. https://www.producttalk.org/how-to-use-claude-code-features/

[4] OpenSkills: Enabling AI Agents to Share Skill Libraries. https://ai-engineering-trend.medium.com/openskills-enabling-ai-agents-to-share-skill-libraries-b5c8734ac5d5

[5] OpenSkills brings the Claude skills system to all AI dev tools. https://github.com/numman-ali/openskills（及相关介绍链接）

[6] Slash commands - Claude Code Docs. https://code.claude.com/docs/en/slash-commands

[7] Understanding Claude Code: Skills vs Commands. https://www.youngleaders.tech/p/claude-skills-commands-subagents-plugins

[8] Claude Skills and CLAUDE.md: a practical 2026 guide. https://www.gend.co/blog/claude-skills-claude-md-guide

[9] CLAUDE.md, skills, subagents explained. https://alexop.dev/posts/claude-code-customization-guide-claudemd-skills-subagents/

[10] travisvn/awesome-claude-skills. https://github.com/travisvn/awesome-claude-skills