Skill 从入门到精通——第三章 Skills 使用及管理

学习目标：从零创建你的第一个智能体 Skill ，并在 Anthropic Code 中体验其运行效果。掌握 Skills 的实际使用方法，能够独立使用、定制和部署、管理 Skills。

Skills（技能） 是一套存放指令、脚本与资源的文件夹，智能体在执行任务时会自动发现并动态加载这些内容，从而提升在专业任务上的表现。你可以将其理解为智能体的专业操作手册，让它在特定领域具备专业能力—— 例如在设计网站时，自动遵循对应公司的品牌规范。

Agent Skills 格式最初由 Anthropic 设计并以开放标准发布，现已被 Claude、Cursor、VS Code、OpenAI Codex、GitHub、openClaw、Hermes Agent 等主流 AI 工具与平台广泛支持，成为当前智能体开发的通用标准。

这意味着，你只需编写一份 Skills 配置，即可无缝适配所有支持 Agent Skills 规范的平台与工具。

本章将带你：

1. 完成 Claude Code 环境搭建。

2. 编写第一个自定义 Skill、测试并验证技能运行效果。

3. 安装 Anthropic 官方 Skill 仓库，掌握Claude code 中技能管理（启用、禁用、更新、卸载）

4. 掌握 Skill 统一管理。

Claude Code 是 Anthropic 官方推出的命令行 AI 助手，原生完美支持 Agent Skills 标准，是学习、开发与调试技能的首选工具。它不仅具备强大的代码编写能力，还能协助完成所有可通过命令行操作的任务：文档撰写、项目构建、文件检索、主题调研等。

本章所有 Skill 的开发、调试与验证均基于 Claude Code 进行。你也可以在其它支持 Skill 规范的工具中使用，差异主要体现在技能安装目录、触发方式命令上。

一、环境准备与 Claude Code 安装

1.1 环境准备

1）系统要求

• 操作系统：macOS 13+ / Ubuntu 20.04+ / Debian 11+ / Windows 10+（推荐 WSL2）
• 内存：≥8GB（推荐 16GB+）
• 存储：SSD ≥10GB 可用空间
• 网络：可正常访问 Anthropic API（或国内）

2）软件安装

Node.js（v18.0+）（可选，2026 年官方推出原生安装器，无需 Node.js，支持自动后台更新 ）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# macOS（Homebrew）
brew install node

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# Windows（WSL）
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

验证：

1
2

node -v  # ≥v18.0
npm -v

Git（2.23+）（可选，拉取gihub项目需要）

1
2
3
4
5
6
7
8

# macOS
brew install git

# Ubuntu/Debian
sudo apt install git

# Windows 
https://git-scm.com/install/windows  #下载后运行安装

1.2 安装 Claude Code

方式 1：官方一键脚本（推荐，无 Node 依赖）

macOS / Linux / WSL2

1

curl -fsSL https://claude.ai/install.sh | bash

Homebrew（macOS/Linux）

1

brew install --cask claude-code

Windows（原生 PowerShell）

1
2
3
4
5
6

# 以下安装方式二选一
# 方式一：PowerShell 原生安装（官方推荐）
irm https://claude.ai/install.ps1 | iex

# 方式二：WinGet（更稳定，有进度条）
winget install Anthropic.ClaudeCode

注意：部分用户反馈 PowerShell 原生安装脚本可能长时间无响应（无进度条、无状态提示），若 5 分钟无反应，建议直接改用 winget 。安装后需新开一个 PowerShell 窗口再执行 claude 命令。

方式 2：npm 全局安装（适合前端 / Node 开发者）

如果原生安装器不可用，需先安装 Node.js 18+：

1
2
3
4
5

# 国内用户配置镜像加速
npm config set registry https://registry.npmmirror.com

# 全局安装 Claude Code
npm install -g @anthropic-ai/claude-code

验证安装

1
2
3

# 检查 Claude Code 版本
claude --version
# 预期输出：2.1.116 (Claude Code)

1.3 认证配置（核心步骤）

提供两种接入方案，可根据网络环境选择：

• 能访问 Claude 官网（国内需科学上网） → 推荐方案 1
• 国内访问受限 → 使用 方案 2

一、认证方案1（需可访问Claude官网，国内需科学上网）

Claude Code 需要 API Key 或 Claude.ai 账户登录。

方式 1：配置API Key

从 console.anthropic.com 获取 API Key（格式 sk-ant-...），然后通过以下任一方式配置：

环境变量（临时）:

1
2
3
4
5

# macOS / Linux
export ANTHROPIC_API_KEY="sk-ant-你的密钥"

# Windows PowerShell
$env:ANTHROPIC_API_KEY="sk-ant-你的密钥"

配置文件（永久）

创建配置文件，用于持久化 Claude 相关环境变量与语言设置：

• macOS / Linux：~/.claude/settings.json
• Windows：%USERPROFILE%\.claude\settings.json

写入以下配置内容：

1
2
3
4
5
6
7
8

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-你的密钥",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com",
    "API_TIMEOUT_MS": "300000"
  },
  "language": "简体中文"
}

方式 2：Claude.ai 登录（需海外网络）

1

claude login

浏览器会自动打开认证页面。需要 Claude Pro/Max 订阅。

二、认证方案2（国内使用方案）

由于 Anthropic 官方 API 在国内访问受限，可使用以下两种方式：

1. 使用第三方的API代理平台访问 Anthropic 官方模型。
2. 接入兼容 Anthropic API 的其它模型。

方式1：第三方 API 代理平台

在 settings.json 中 ，修改 ANTHROPIC_BASE_URL 为中转地址及配置密钥。

• macOS / Linux：~/.claude/settings.json
• Windows：%USERPROFILE%\.claude\settings.json

配置内容如下：

1
2
3
4
5
6
7

{
  "env": {
    "ANTHROPIC_API_KEY": "你的中转平台密钥",
    "ANTHROPIC_BASE_URL": "https://你的中转地址/v1",
    "ANTHROPIC_MODEL": "claude-sonnet-4-6"
  }
}

方式2：接入兼容 Anthropic API 的其它模型

Claude Code 支持通过兼容 Anthropic API 格式接入其它模型。

创建并编辑配置文件settings.json ：

• macOS/Linux: ~/.claude/settings.json
• Windows: %USERPROFILE%\.claude\settings.json

以下接入模型，只需要配置一个即可。

接入DeepSeek模型

API Key 获取入口：https://platform.deepseek.com/api_keys

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "你的 DeepSeek API Key",
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-chat",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-reasoner",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-chat",
    "API_TIMEOUT_MS": "300000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

配置说明：

• ANTHROPIC_AUTH_TOKEN：填写 DeepSeek API Key
• ANTHROPIC_BASE_URL：DeepSeek 提供的 Claude 兼容接口地址
• ANTHROPIC_DEFAULT_SONNET_MODEL：通用对话模型
• ANTHROPIC_DEFAULT_OPUS_MODEL：深度思考 / 推理模型
• ANTHROPIC_DEFAULT_HAIKU_MODEL：轻量模型
• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC：超时与关闭额外请求，保证国内使用更稳定。

接入智谱 模型

API Key 获取入口：https://open.bigmodel.cn/usercenter/apikeys

1
2
3
4
5
6
7
8
9

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "你的 智谱 API Key",
    "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-5"
  }
}

接入百炼 CodingPlan

获取入口：https://help.aliyun.com/zh/model-studio/coding-plan

1
2
3
4
5
6
7
8
9

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "你的 百炼 API Key",
    "ANTHROPIC_BASE_URL": "https://dashscope.aliyuncs.com/apps/anthropic",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "qwen3-max",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "qwen3-max",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "qwen3-coder-next"
  }
}

接入火山引擎 CodingPlan

获取入口：https://www.volcengine.com/activity/codingplan

1
2
3
4
5
6
7
8
9

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "你的 火山引擎 API Key",
    "ANTHROPIC_BASE_URL": "https://ark.cn-beijing.volces.com/api/coding",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "doubao-seed-2.0-pro",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "doubao-seed-2.0-code",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "minimax-m2.5"
  }
}

如果模型调用访问量比较大，建议购买模型服务商的CodingPlan服务，按月付费，防止token费用失控。

1.4 首次启动与使用

进入项目目录启动：

1
2

cd your-project
claude

首次启动会进入 初始化向导（选择主题、确认权限），之后即可使用。

启动成功后界面如下：

输入：“介绍下自己”

常用命令

二、Skill 存储位置与目录结构

Claude Code 会在启动时自动扫描（技能存储目录）并加载技能，无需手动引入或注册。但技能存储路径不规范、目录结构错误、文件名大小写不符合规范，都会直接导致技能无法被识别或加载失效。

1、技能存储级别与路径

Claude Code 的Skill 按使用范围分为 4 个级别，不同级别对应固定存储路径，且明确的同名技能优先级。

补充说明：

1. 企业级限制：仅官方 Claude Code 服务支持，第三方兼容 Anthropic API 的服务通常不提供该能力。
2. 路径符号：~ 为用户主目录，Windows 对应路径为：C:\Users\你的用户名\.claude\skills\。
3. 兼容路径：部分 Agent 开发框架使用的存储路径可能不相同，其它常见路径如：
   • 项目级：<project>/.agents/skills/
   • 个人级：~/.agents/skills/

2、嵌套目录自动识别（Monorepo 专属支持）

Claude Code 支持子目录嵌套技能识别，完美适配单体多仓（monorepo） 项目架构。

当你编辑子目录文件时，系统会自动向上 / 向下扫描该目录下的 .claude/skills/：

• 示例：编辑 packages/frontend/xxx.js时，系统会同时识别 packages/frontend/.claude/skills/ 中的技能；
• 作用：每个子包 / 模块可拥有独立专属技能，互不干扰。

3、标准 Skill 目录结构

一个完整的 Skill 最小单元 = 一个文件夹 + 一个 SKILL.md 配置文件：

1
2
3
4
5

你的项目根目录/
└── .claude/            # 固定配置根目录
    └── skills/         # 固定技能总目录
        └── 技能名称/   # 技能文件夹（英文小写+短横线命名）
            └── SKILL.md  # ✅ 唯一必选入口文件（固定文件名，大小写不可修改）            

一个完整Skill的目录包含必选文件和可选文件，标准结构如下：

1
2
3
4
5
6
7

my-first-skill/          # Skill目录（名称自定义，遵循命名规范）
├── SKILL.md            # 必选：Skill入口文件，定义元数据和核心指令
├── reference.md        # 可选：参考文档，拆分复杂说明
├── examples/           # 可选：示例文件夹，存放使用示例
│   └── sample.md       # 可选：示例文件
└── scripts/            # 可选：脚本文件夹，存放可执行脚本
    └── helper.py       # 可选：辅助脚本，处理精确计算、格式转换等

关键规则:

1. Skill目录名：仅允许小写字母、数字、连字符（-），最长64字符，避免使用特殊符号和中文，示例：hello-world-skill；

2. SKILL.md：唯一必需文件，定义技能核心逻辑、触发规则、元数据；

3. 扩展文件：reference.md、/references、/examples、/scripts 均为可选，需要在 SKILL.md 中主动引用， 才会加载使用；

4. 编码要求：所有文件统一使用 UTF-8 编码，避免中文乱码

4、加载机制总结

1. Claude Code 启动时自动扫描所有级别技能路径，无需手动配置；
2. 同名技能按 企业级 → 个人级 → 项目级 优先级覆盖；
3. 最小结构即可运行，复杂技能可按需扩展附属文件（如：模板、示例、脚本）；
4. Monorepo 项目可使用嵌套 .claude/skills/ 实现子包独立技能。

三、实战：创建第一个自定义 Skill

本节从零开始创建一个「智能随机选择器」Skill。该技能可实现抛硬币、随机生成数字、从多个选项中抽签等功能，无任何代码文件和附件文件，适合作为入门的 Skill 实例。

3.1 创建目录文件

1. 新建一个空文件夹作为测试项目，如test-randmon-picker。
2. 在项目内创建层级目录：.claude/skills/random-picker/
3. 在 random-picker 文件夹中新建文件：SKILL.md

最终目录结构：

1
2
3
4
5

test-randmon-picker/
└── .claude/
    └── skills/
        └── random-picker/
            └── SKILL.md

3.2 编写 SKILL.md 配置（直接复制）

SKILL.md 是技能的核心配置文件，支持 YAML 头部声明 + Markdown 指令 / 脚本，是行业通用格式。

编写SKILL.md内容如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

---
name: random-picker
description: 随机选择工具，可实现抛硬币（正面/反面）、随机生成1~N的数字、从用户提供的多个选项中随机抽取一个，适用于所有需要随机决策的场景，无需额外配置，直接运行即可。
version: 1.0.0               # 技能版本（可选）
author:  Tiny     		     # 作者（可选）
---

# 智能随机选择器 - 执行指令
本技能支持3种核心功能，根据用户需求自动选择对应命令，跨平台兼容（Mac/Linux 用 bash 命令，Windows 用 PowerShell 命令），执行后返回结果。

## 功能1：抛硬币（正面/反面）
### 适用场景：用户需要抛硬币做决策
### 执行命令
- Mac/Linux（bash/zsh 终端）：
```bash
echo $((RANDOM % 2)) | awk '{if($0==0) print "正面"} else print "反面"}'
```
- Windows（PowerShell）：
```powershell
Get-Random -InputObject "正面","反面"
```

## 功能2：生成1~N的随机数
### 适用场景：用户需要生成指定范围内的随机数（如1~10、1~100）
### 执行命令
- Mac/Linux（bash/zsh 终端）：
```bash
echo $((RANDOM % <max> + 1))
```
- Windows（PowerShell）：
```powershell
Get-Random -Minimum 1 -Maximum ([int]<max> + 1)
```
### 替换规则：将 <max> 替换为用户指定的最大数字（如用户要1~10，替换为10）

## 功能3：从多个选项中随机选择
### 适用场景：用户提供多个选项（用逗号分隔），需要随机抽取一个
### 执行命令
- Mac/Linux（bash/zsh 终端）：
```bash
echo "<choices>" | tr ',' '\n' | shuf -n 1
```
- Windows（PowerShell）：
```powershell
"<choices>".Split(',') | Get-Random
```
### 替换规则：将 <choices> 替换为用户提供的选项（用英文逗号分隔，如“奶茶,咖啡,可乐”）

## 通用规则
1. 优先匹配用户需求，自动选择对应功能的命令，无需用户指定系统类型。
2. 替换参数时，严格按照用户要求，不添加额外字符。
3. 执行命令后，只返回最终结果，不解释命令含义、不输出多余内容。

3.3 测试验证 Skill 运行效果

第一步：进入项目目录

终端切换到你的测试项目根目录：

1

cd /test-randmon-picker   # test-randmon-picker替换为你的项目路径

第二步：启动 Claude Code 并加载技能

输入命令：

1

claude

进入交互界面后，输入命令查看已加载技能：

Claude Code 启动时自动扫描所有级别技能路径，无需手动配置。

• 项目级：<project>/.claude/skills/
• 个人级：~/.claude/skills/
• 插件级: <插件>/skills/

1

/skills

若输出：✅ random-picker，说明技能加载成功。

说明：Skill 编写完成后无需手动导入，Claude Code会自动扫描Skill存储目录，识别新创建的Skill，启动后即可直接使用。

第三步：发送指令测试

Skill 支持两种触发方式：

• 方式一：自动触发（根据description关键词)

  直接发送自然语言指令，Claude 会根据关键词自动匹配并运行技能。

• 方式二：手动触发（精准调用）

  格式：/技能名称 任务内容

  示例：/random-picker 抛硬币

注意：若Skill未启动，检查SKILL.md的元数据配置，确保user-invocable为true，且description关键词清晰。或者使用手动触发方式。

以下是3种功能的测试示例：

测试1：抛硬币

• 输入指令：抛硬币
• 预期结果：Claude 运行对应命令，返回「正面」或「反面」（随机）。

测试2：生成随机数

• 输入指令：帮我生成一个1~10的随机数（可替换为120、1100等）
• 预期结果：返回1到指定数字之间的随机整数（如7、15）。

测试3：随机选选项

• 输入指令：从奶茶,咖啡,可乐,果汁中随机选一个（选项可自定义，用英文逗号分隔）
• 预期结果：从提供的选项中随机返回一个（如咖啡、果汁）。

四、安装 Anthropic 官方 Skill 仓库

Anthropic 官方开源 Skills 示例仓库（GitHub 地址：https://github.com/anthropics/skills），涵盖文档办公、Web 开发、创意品牌及平台工具四大类别，共计 17 个 Skill 实现。这些技能集合不仅是 Claude 技能系统的官方示范库，同时也为开发者提供了可学习、可复用、可定制的参考模板，是新手入门学习Claude 技能开发的官方权威资料。

4.1 安装官方 Skill 仓库

Anthropic 官方提供两种技能安装方式：插件市场安装 和 手动 Git 安装。

方式 1：插件市场安装（推荐）

适合直接安装官方整包技能（包含 PDF/DOCX/XLSX 等文档处理能力），操作最简单、最稳定。

1. 启动 Claude Code

   1

   claude

2. 添加官方 Skills 市场

   1 2	# 注册官方技能市场 /plugin marketplace add anthropics/skills

   

3. 查看可安装的插件列表

   1	/plugin list

4. 安装官方技能包（含 pdf /docx/xlsx 等）

   1	/plugin install document-skills@anthropic-agent-skills

5. 重载插件（确保生效）

   1	/reload-plugins

   

6. 查看是否加载成功

   1

   /skills

   

方式 2：手动 Git 克隆安装（灵活可控）

适合只想安装单个技能、或需要自定义修改的场景。

1. 克隆官方仓库

   1 2	git clone https://github.com/anthropics/skills.git cd skills

2. 安装到用户全局路径（所有项目可用）

   全局技能会放在用户主目录下，所有 Claude Code 会话都能调用。

   1 2 3 4 5 6 7 8 9 10

   # 创建全局技能目录 Windows对应路径为：`C:\Users\你的用户名\.claude\skills\` mkdir -p ~/.claude/skills # 拷贝 单个技能（示例：pdf / docx / xlsx） cp -r skills/pdf ~/.claude/skills/ cp -r skills/docx ~/.claude/skills/ cp -r skills/xlsx ~/.claude/skills/ # 拷贝 全部技能（二选一执行即可） cp -r skills/* ~/.claude/skills/

3. 或安装到项目路径（仅当前项目可用）

   1 2 3 4 5 6 7

   mkdir -p .claude/skills # 拷贝单个技能到当前项目 cp -r skills/pdf .claude/skills/ # 拷贝全部技能到当前项目 cp -r skills/* .claude/skills/

4. 重载技能并验证

   新版 Claude Code（v2.1.0+）：保存文件后自动重载，可直接验证。

   旧版：必须手动重载。

   1	/reload-plugins

   注意：Claude Code v2.1.0+ 支持 Skill 热重载——在 ~/.claude/skills 或 .claude/skills 中创建或修改 Skill 后，无需重启 Claude Code 即可立即使用 。

   查看已安装的技能列表：

   1	/skills list

4.2 Skill 查看与验证

1. 查看所有已加载技能

列出当前已安装并生效的全部技能：

1

/skills list

2. 验证单个技能是否可用

查看指定技能的帮助信息，判断是否正常加载：

1

/技能名称 help

示例：

1

/pdf help

• 显示帮助文档 → 技能加载正常
• 提示 Unknown command → 未安装或未重载生效

4.3 Skill 使用

1. 自然语言调用

Claude 根据任务描述自动匹配并加载对应 Skill。无需记忆命令，直接描述需求即可：

示例：

1
2

解析 project_spec.pdf 并提取核心需求总结
读取 data.xlsx 的 Sheet2，用透视表按季度汇总销售额

由模型自动判断意图，匹配并触发合适的 Skill 完成处理。

2. 斜杠命令（Claude Code 支持）

安装 skill 后，可通过 /skill-name 直接调用，支持参数传递。

示例：

1
2
3

/pdf 摘要总结 file.pdf
/xlsx 提取表格 file.xlsx
/mcp-builder 基于公司内部 REST API 创建一个 MCP server：支持查询用户列表和创建工单，用 FastMCP (Python) 实现，带错误重试

3. 明确指明使用具体的Skill来处理

当任务需要特定 Skill 的独有能力，或要避免 Claude 自动路由到不合适的 Skill 时，显式指名可确保行为可控。

示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

# 示例1：使用frontend-design技能生成数据看板
使用 frontend-design skill 设计一个数据看板界面，要求：
- 深色模式
- 卡片式布局
- 避免过度渐变与大圆角的“AI 风”设计

# 示例2：使用canvas-design技能生成会议海报
用 canvas-design skill 生成一张 1200×630 像素的会议海报，具体要求如下：
- 背景：采用算法生成的流动渐变网格（由perlin noise驱动，色调柔和）
- 主标题：使用粗体无衬线字体，居中对齐，颜色为 #1F1F1F（深灰）
- 底部：添加 16px 高的品牌色条，颜色为 #1F1F1F，无额外文字
- 输出格式：PNG，保留透明通道，便于后续叠加使用

# 示例3：使用algorithmic-art技能创建艺术图
用 algorithmic-art skill 编写一段 p5.js 脚本，实现以下效果：
- 生成 10 个随机分布的半透明圆形，半径范围 50-100px
- 色彩：采用 HSL 模式，色相范围 200-280（冷色调），饱和度 50%，透明度 60%
- 效果：给每个圆形添加 3px 的高斯模糊，增强层次感
- 输出：导出 1080×1080 像素的图片，适配 Instagram 方形图尺寸

使用 frontend-design skill 设计一个数据看板界面。演示如下：

生成结果（dashboard.html文件）：

五、Claude code 中 Skill 管理（启用 / 禁用 / 更新 / 卸载）

5.1 禁用单个技能

核心说明：通过claude code权限配置中的「deny」规则，可精确禁用指定单个Skill，实现精准权限管控。

1. 打开权限编辑器

   在Claude code操作界面输入以下命令，调出权限编辑窗口：

   1	/permissions

2. 在 deny 区域添加禁用的技能

   禁用单个Skill需在「deny」区域添加对应规则，语法及示例如下：

   • 精确匹配：Skill(技能名称)，仅禁用指定名称的单个Skill；

   • 前缀匹配：Skill(技能名称 *)，禁用所有以该名称为前缀的相关Skill（支持任意参数）。

   示例（禁用pdf技能）：

   1	Skill(document-skills:pdf)

   切换到Deny选项卡，添加规则：

   

   输入禁用的Skill：

   

   选择该禁用规则的生效范围（根据实际需求选择，如项目、用户全局等）；

   

3. 保存（Ctrl+S）并退出

   

注意事项：通过「/permissions」命令禁用的Skill，仅对 Claude 自动触发的场景生效；若用户手动输入「/技能名称」触发，该Skill仍可正常使用。

5.2 恢复启用单个技能

核心说明：删除「deny」区域中对应的禁用规则，即可恢复该Skill的正常使用。

1. 再次打开权限

   1	/permissions

2. 删除 Skill(document-skills:pdf) 这一行

3. 保存

5.3 管理插件级技能（整包启用 / 禁用）

适用于通过 /plugin install 安装的整包技能。

1
2
3
4
5
6
7
8

# 查看已安装插件
/plugin list

# 禁用整个文档技能包（pdf/docx/xlsx 一起禁用）
/plugin disable document-skills@anthropic-agent-skills

# 重新启用
/plugin enable document-skills@anthropic-agent-skills

5.4 更新官方 Skills

插件方式更新

1

/plugin update document-skills@anthropic-agent-skills

手动 Git 方式更新

1
2
3
4
5

cd skills
git pull
# 重新覆盖到技能目录
cp -r skills/pdf ~/.claude/skills/
/skills reload

5.5 卸载技能

方式 A：插件卸载

1

/plugin uninstall document-skills@anthropic-agent-skills

方式 B：手动删除目录

1
2
3
4
5

# 删除全局技能
rm -rf ~/.claude/skills/pdf

# 删除项目技能
rm -rf .claude/skills/pdf

六、Skill 统一管理

6.1 为什么需要管理 Skill

随着社区技能数量呈爆发式增长，仅 Antigravity Awesome Skills 仓库就已收录 1000+ 各类通用与场景化技能。技能规模化普及的同时，开发者与团队在落地生产级 Agent 应用时，普遍面临一系列核心痛点：

• 技能发现难：如何从海量技能中找到适合自己项目的？
• 版本管理乱：第三方技能持续迭代更新，更新后如何维护升级，如何同步到团队？
• 环境一致性：本地开发、测试服务器、生产环境、团队成员电脑的技能集不统一，导致 Agent 执行结果差异。如何保证不同机器上的 Agent 使用相同的技能集？。
• 跨工具兼容：同一团队使用不同 Agent 工具时如何共享技能？

因此，系统化的 Skill 管理成为生产级 Agent 开发的必备能力。

当前行业主流 Skill 管理方案分为两类：手动管理Skill、npx skills 工具管理。下面详细介绍这两种方案。

6.2 Skill 的存储结构与规范

在深入管理方式前，先理解 Skill 在文件系统中的组织方式（文件存储规则、目录规范）。

1、技能存储目录

不同 Agent 工具默认技能存储目录存在差异：

规则说明：

• 个人级（全局）：存放在用户主目录下，对该用户所有项目生效。
• 项目级（局部）：存放于项目根目录下，仅对当前项目生效，可提交至代码仓库，适合团队协作。
• 加载规则：Agent 启动时会自动递归扫描指定目录，加载目录内的 SKILL.md 核心文件（技能的唯一标识文件）；加载优先级：项目级 > 个人级（同名技能优先使用项目级，便于团队定制覆盖全局技能）。

2、标准目录结构

1
2
3
4
5
6
7

# 技能标准结构
skills/
├── skill-name-1/        # 技能唯一目录名（单个技能结构，必须包含 SKILL.md）
│   └── SKILL.md          # 技能核心描述文件（必填）
├── skill-name-2/
│   ├── SKILL.md
│   └── utils.js          # 技能配套脚本/资源（可选）

6.3 手动管理 Skill

手动管理是最基础、最透明的方式，适合理解底层机制、定制化需求强或网络受限的场景。

1、手动安装 Skill

步骤 1：获取 Skill 源文件

从 GitHub 或其它源下载 Skill 文件。以安装 Vercel 的 React 最佳实践技能为例：

1
2
3
4
5

# 克隆技能仓库
git clone https://github.com/vercel-labs/agent-skills.git /tmp/agent-skills

# 查看可用技能
ls /tmp/agent-skills/skills/

步骤 2：复制到 Agent 技能目录

1
2
3
4
5
6
7

# 安装到个人级（对所有项目生效）
mkdir -p ~/.claude/skills/react-best-practices
cp /tmp/agent-skills/skills/react-best-practices/* ~/.claude/skills/react-best-practices/

# 或安装到项目级（仅当前项目）
mkdir -p .claude/skills/react-best-practices
cp /tmp/agent-skills/skills/react-best-practices/* .claude/skills/react-best-practices/

步骤 3：验证安装

在 Claude Code 中输入：

1

What skills are available?

或直接调用：

1

/react-best-practices

2、手动更新 Skill

1
2
3
4
5

# 进入技能仓库更新代码
cd /tmp/agent-skills && git pull

# 重新复制更新后的文件
cp /tmp/agent-skills/skills/react-best-practices/* ~/.claude/skills/react-best-practices/

3、手动删除 Skill

1
2
3
4
5

# 删除个人级技能
rm -rf ~/.claude/skills/react-best-practices

# 删除项目级技能
rm -rf .claude/skills/react-best-practices

4、手动创建自定义 Skill

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

mkdir -p ~/.claude/skills/my-custom-skill
cat > ~/.claude/skills/my-custom-skill/SKILL.md << 'EOF'
---
name: my-custom-skill
description: My team's custom coding conventions
---

# My Team Coding Conventions

## Import Order
1. React/Vue imports
2. Third-party libraries
3. Absolute project imports (@/)
4. Relative imports (./)

## Naming
- Components: PascalCase
- Hooks: useCamelCase
- Utilities: camelCase
EOF

5、手动管理的优缺点

6.4 npx skills 工具管理

npx skills 是 Vercel 官方维护的 CLI 工具，作为 Agent Skills 生态的包管理器，提供发现、安装、更新、删除的一站式能力 。

npx skills 是 Vercel 官方推出的 AI Agent 技能管理 CLI 工具，作为 Agent Skills 生态的包管理器，提供发现、安装、更新、删除的一站式能力 。让你的 AI 助手（Cursor、Claude、GitHub Copilot、Windsurf 等）瞬间拥有专业级能力（代码规范、性能优化、一键部署、审查等）。

简单的说，它就是 AI 技能的「应用商店 + 命令行管理器」。

6.4.1 环境准备

确保已安装 Node.js 20.6+ 和 npm/npx。

npx skills 是 Skills CLI 的调用方式，无需全局安装，直接通过 npx 调用：

1
2

# 查看使用帮助
npx skills -h

Skills CLI 支持 50+ 种主流 AI 助手或工具，包括 Claude Code、Cursor、Codex、OpenCode、Trae、Windsurf、GitHub Copilot、Gemini CLI 等。

6.4.2 核心命令详解

1、发现技能：npx skills find

1
2

# 按关键词搜索技能
npx skills find react performance

输出示例：

也可以直接访问可视化目录网站 skills.sh 进行浏览 。

1

skills.sh 是 Vercel 推出的开放 AI 智能体技能生态平台，相当于 AI Agent 界的 npm，用于一键安装、共享、管理可复用的 Agent 技能（Skills）。

2、安装技能：npx skills add

支持多种来源格式 ：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# GitHub 简写（推荐）
npx skills add vercel-labs/agent-skills --skill vercel-react-best-practices

# 安装仓库下的所有技能(会引导选择需要安装的skill、Agent工具及作用范围)
npx skills add vercel-labs/agent-skills

# 完整 URL
npx skills add https://github.com/microsoft/playwright-cli

# 本地路径（开发调试）
npx skills add ./my-local-skills

# 安装到指定 Agent（跨工具兼容）
npx skills add vercel-labs/agent-skills -a claude-code -g

常用选项：

• -s, --skill <skills...>：指定要安装的技能名称（可指定多个）
• -a, --agent <agents>：指定目标 AI 助手。
• -g, --global：全局安装（用户级别），默认是项目级别。
• -l, --list：仅列出可用技能，不实际安装。
• --copy：使用复制而非符号链接安装。
• -y, --yes：跳过所有确认提示。
• --all：安装所有技能到所有 Agent。

安装原理：npx skills 会自动将远程仓库中的 SKILL.md 及相关资源下载到对应 Agent 的技能目录（如： ~/.claude/skills/ 或 .claude/skills/），并创建 skills-lock.json 锁定版本 。

3、查看已安装技能：npx skills list

1
2
3

npx skills list  #查看项目 skill

npx skills list -g   #查看全局 skill

4、更新技能：npx skills update

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 检查所有已安装技能的更新
npx skills check

# 批量更新所有技能
npx skills update

# 更新全局
npx skills update -g

# 更新指定技能
npx skills update vercel-react-best-practices

5、删除技能：npx skills remove

1
2
3

# 删除指定技能
npx skills remove vercel-react-best-practices  # 项目级
npx skills remove vercel-react-best-practices -g  # 全局

6.4.3 可复现安装：Lockfile 机制

这是 npx skills 最强大的特性之一。安装项目级技能后，工具会在当前目录生成 skills-lock.json：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "version": 1,
  "skills": {
    "vercel-react-best-practices": {
      "source": "vercel-labs/agent-skills",
      "sourceType": "github",
      "skillPath": "skills/react-best-practices/SKILL.md",
      "computedHash": "ca7b0c0c6e5f2750043f7f0cd72d16ac4e2abc48f9b5500d047a4b77a2506212"
    }
  }
}

团队协作流程：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# 成员 A：安装所需技能并提交 lockfile。(安装范围选择项目级)
npx skills add vercel-labs/agent-skills --skill vercel-react-best-practices
git add skills-lock.json
git commit -m "chore: add agent skills"
git push

# 成员 B：克隆项目后一键恢复相同技能集
git clone <repo>
cd <repo>
npx skills install  # 根据 skills-lock.json 精确还原

这确保了团队内所有开发者、CI 环境、不同机器上的 Agent 都使用完全一致的 Skill 版本。

6.4.4 高级用法

6.4.4.1 全局安装与多 Agent 共享

npx skills 默认将技能安装到 ~/.agent/ 目录作为全局缓存，然后通过软链接（symlink）映射到具体 Agent 目录，节省磁盘空间 ：

1
2
3
4
5

# 查看全局缓存
ls ~/.agent/skills/

# 手动创建软链接给多个 Agent 共享
ln -s ~/.agent/skills/vercel-react-best-practices ~/.cursor/skills/vercel-react-best-practices

6.4.4.2 批量安装社区技能集

1
2
3
4

# 一次安装 Antigravity 社区的 1,234+ 个技能（按 Agent 过滤）
npx antigravity-awesome-skills --claude
npx antigravity-awesome-skills --cursor
npx antigravity-awesome-skills --gemini

6.4.5 npx skills 的优缺点

6.4.6 两种管理方式对比

6.5 生产环境最佳实践

6.5.1 项目级 Skill 优先

将 Skill 安装在项目目录（如：.claude/skills/）而非个人目录，并提交 skills-lock.json：

1
2
3
4
5
6

# 在项目根目录执行
npx skills add vercel-labs/agent-skills --skill vercel-react-best-practices

# 提交到 Git
git add .claude/skills/ skills-lock.json # 不要忽略 lockfile！
git commit -m "feat: add react performance review skill"

这样新成员克隆项目后即可获得完全一致的 Agent 能力。

6.5.2 区分 Skill 类型并设置调用权限

默认情况下，你和 Claude 都可以调用任意技能。你可以输入 /技能名称 手动调用；当对话场景匹配时，Claude 也可以自动加载并调用。如需精细化管控技能调用权限，可通过两项前置元数据配置限制：

• disable-model-invocation: true：仅支持用户手动调用，禁止模型自动触发。适用于存在副作用、需要控制执行时机的流程，例如 /commit（提交代码）、/deploy（部署）、/send-slack-message（发送消息）。避免 Claude 自行判断、擅自执行部署等高危操作。
• user-invocable: false：仅允许Claude 自动调用，关闭用户手动使用权限。适用于背景知识类、不适合作为指令手动执行的技能。例如 legacy-system-context 技能用于讲解老旧系统逻辑，Claude 在需要时自动引用即可，用户无需也无法手动调用。

根据 Skill 的用途设置合适的调用模式 ：

1
2
3
4
5
6
7
8

---
name: deploy-production
description: Deploy application to production environment
disable-model-invocation: true   # 仅用户可调用，防止 Agent 自动执行危险操作
allowed-tools: Bash(kubectl *, docker *)
---

# 这个 Skill 涉及生产部署，必须用户显式调用 /deploy-production

1
2
3
4
5
6
7

---
name: codebase-architecture
description: Internal architecture documentation and conventions
user-invocable: false            # 仅 Agent 自动调用，不显示在 / 菜单中
---

# 这个 Skill 作为背景知识，Agent 处理相关文件时自动加载

6.5.3 定期审计与更新

1
2
3
4
5
6

# 每月执行一次
npx skills check          # 查看可更新项
npx skills update         # 批量更新
npx skills list           # 检查是否有不再使用的技能，项目级
npx skills list  -g         # 检查是否有不再使用的技能，全局
npx skills remove <name>  # 清理废弃技能

6.5.4 安全注意事项

1. 审查 Skill 来源：安装前查看仓库的 Stars、维护者信誉、最近更新时间。优先使用经过 Agent Trust Hub 或 安全审计的技能。
2. 限制敏感操作：涉及部署、支付、数据删除的 Skill 务必设置 disable-model-invocation: true。

七、官方 Skill 资源库

补充学习资源

如您想要系统建立 AI Agent 全栈开发能力，从概念认知到企业级项目落地、线上迭代优化，可以参考《栖微 AI Agent 工程师实战成长营》专栏。专栏以六阶成长路径组织内容，配套实战源码与持续更新的前沿案例，补齐 Demo 到生产环境之间的工程化短板。

更多介绍：《栖微 AI Agent 工程师实战成长营》

Github 项目 ：https://github.com/tinyseeking/tidy-agent-practice

欢迎大家一起探讨智能体开发相关问题。