Skills 使用指南与最佳实践

从安装到自定义，全面掌握 Skills 的使用方法

本章概览

在不同平台安装和使用 Skills
创建自定义 Skills 的完整流程
企业级部署最佳实践
常见问题与解决方案

1. 安装与配置

1.1 在 Claude Code 中使用

Claude Code 是 Anthropic 官方的 CLI 工具，提供最完整的 Skills 支持。

添加官方 Skills 市场

bash

# 添加 Anthropic Skills 市场
/plugin marketplace add anthropics/skills

浏览和安装

bash

# 方法 1：交互式浏览
1. 选择 "Browse and install plugins"
2. 选择 "anthropic-agent-skills"
3. 选择 "document-skills" 或 "example-skills"
4. 选择 "Install now"

# 方法 2：直接安装
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

使用 Skills

安装后，只需自然语言提及即可：

"使用 PDF skill 提取 contract.pdf 中的表单字段"
"帮我用 algorithmic-art 创建一个流场艺术"
"用 docx skill 编辑这份合同，添加修订标记"

1.2 在 Claude.ai 中使用

付费用户可以直接使用官方 Skills。

启用 Skills

登录 Claude.ai
进入设置
在 Skills 部分启用所需的 Skills

上传自定义 Skills

参考官方指南：Using skills in Claude

1.3 通过 API 使用

python

# 参考 Skills API Quickstart
# https://docs.claude.com/en/api/skills-guide#creating-a-skill

import anthropic

client = anthropic.Anthropic()

# 创建带 Skills 的对话
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    skills=["pdf", "docx"],  # 启用的 Skills
    messages=[
        {"role": "user", "content": "提取 report.pdf 中的表格数据"}
    ]
)

2. 创建自定义 Skills

2.1 快速开始

最简 Skill 结构

my-skill/
└── SKILL.md

SKILL.md 模板

markdown

---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---

# My Skill Name

[Add your instructions here that Claude will follow when this skill is active]

## Examples
- Example usage 1
- Example usage 2

## Guidelines
- Guideline 1
- Guideline 2

2.2 完整创建流程

Step 1：明确需求

问自己：

这个 Skill 解决什么问题？
什么话应该触发这个 Skill？
需要什么资源？（脚本、参考、素材）

Step 2：初始化项目

bash

# 使用官方脚本（如果使用 skill-creator）
scripts/init_skill.py my-skill --path ./skills

# 或手动创建
mkdir -p my-skill/{scripts,references,assets}
touch my-skill/SKILL.md

Step 3：编写 SKILL.md

Frontmatter（关键）

yaml

---
name: my-skill
description: |
  [功能描述] 这个 Skill 做什么

  Use when:
  - [触发条件 1]
  - [触发条件 2]
  - [触发条件 3]

  Keywords: [关键词1], [关键词2], [关键词3]
---

技巧：description 是 Claude 判断何时使用 Skill 的唯一依据，要清晰、完整。

Body

markdown

# Skill 名称

## 概述
简要说明 Skill 的用途和范围

## 工作流程
### 步骤 1: ...
### 步骤 2: ...

## 示例
[具体示例]

## 注意事项
[重要限制和警告]

Step 4：添加资源（可选）

scripts/

python

# scripts/process_data.py
def process(input_path, output_path):
    # 可靠、可测试的代码
    pass

if __name__ == "__main__":
    import sys
    process(sys.argv[1], sys.argv[2])

references/

markdown

# references/api_docs.md

## API 端点

### GET /users
获取用户列表

**参数**:
- `page`: 页码
- `limit`: 每页数量

**响应**:
```json
{
  "users": [...],
  "total": 100
}


##### assets/

assets/ ├── template.docx # 文档模板 ├── logo.png # 品牌资源 └── config.json # 配置文件


#### Step 5：测试

```bash
# 在 Claude Code 中测试
# 1. 将 Skill 文件夹放到可访问的位置
# 2. 使用自然语言触发
# 3. 观察是否正确加载和执行

Step 6：打包分发

bash

# 使用官方打包脚本
scripts/package_skill.py my-skill ./dist

# 输出: my-skill.skill (zip 格式)

2.3 高级技巧

渐进式加载

markdown

# SKILL.md

## 基本用法
[简短说明]

## 高级功能

### 功能 A
见 [feature_a.md](references/feature_a.md)

### 功能 B
见 [feature_b.md](references/feature_b.md)

Claude 只在需要时加载 references/ 中的文件。

条件分支

markdown

## 工作流程

根据任务类型选择路径：

### 创建新文档
1. 使用 [create.md](references/create.md)

### 编辑现有文档
1. 使用 [edit.md](references/edit.md)

### 分析文档
1. 使用 [analyze.md](references/analyze.md)

脚本封装

python

# scripts/with_validation.py
"""
使用方法: python with_validation.py input.xlsx output.xlsx

自动验证并修复 Excel 公式错误
"""
import sys
from openpyxl import load_workbook

def validate_and_fix(input_path, output_path):
    wb = load_workbook(input_path)
    # 验证逻辑
    wb.save(output_path)
    print(f"✓ 保存到 {output_path}")

if __name__ == "__main__":
    if len(sys.argv) != 3:
        print(__doc__)
        sys.exit(1)
    validate_and_fix(sys.argv[1], sys.argv[2])

3. 企业级最佳实践

3.1 组织 Skills 库

company-skills/
├── brand/
│   └── brand-guidelines/
├── workflows/
│   ├── contract-review/
│   ├── report-generation/
│   └── data-analysis/
├── integrations/
│   ├── salesforce-mcp/
│   └── jira-mcp/
└── templates/
    ├── presentation/
    └── document/

3.2 版本控制

bash

# 使用 Git 管理 Skills
cd company-skills
git init
git add .
git commit -m "Initial skills library"

# 版本标签
git tag -a v1.0.0 -m "First stable release"

3.3 协作开发

markdown

# CONTRIBUTING.md

## 创建新 Skill

1. Fork 仓库
2. 创建分支: `git checkout -b skill/my-new-skill`
3. 使用模板创建 Skill
4. 测试
5. 提交 PR

## 代码审查清单

- [ ] SKILL.md 有正确的 frontmatter
- [ ] description 清晰描述功能和触发条件
- [ ] 脚本经过测试
- [ ] 无敏感信息

3.4 安全考虑

敏感信息处理

yaml

# ❌ 不要在 Skill 中硬编码
api_key: "sk-abc123..."

# ✓ 使用环境变量
# SKILL.md 中说明需要的环境变量
## 配置
设置以下环境变量：
- `API_KEY`: 你的 API 密钥

权限控制

markdown

## 使用前提

此 Skill 需要以下权限：
- 读取 /data 目录
- 写入 /output 目录
- 网络访问 api.example.com

请确保在安全的环境中使用。

3.5 监控和反馈

markdown

## 反馈收集

使用此 Skill 时：
1. 记录成功/失败案例
2. 收集用户反馈
3. 定期审查和改进

## 版本更新日志

### v1.1.0
- 添加批量处理功能
- 修复表格提取 bug

### v1.0.0
- 初始版本

4. 常见问题与解决方案

4.1 Skill 未被触发

问题：用户使用了相关关键词，但 Skill 未激活

解决方案：

检查 description 是否包含触发关键词
确保描述清晰列出使用场景
添加更多关键词变体

yaml

# 改进前
description: Process PDF files

# 改进后
description: |
  Comprehensive PDF manipulation toolkit for extracting text,
  tables, creating new PDFs, merging/splitting documents, and
  handling forms. Use when Claude needs to fill in a PDF form
  or programmatically process, generate, or analyze PDF documents.

  Keywords: PDF, 表单, 文档, 提取, 合并, 拆分, 填写, 处理

4.2 上下文溢出

问题：Skill 内容太长，导致上下文不够

解决方案：

将详细内容移到 references/
保持 SKILL.md < 500 行
使用渐进式加载

markdown

# 改进前：一个巨大的 SKILL.md

# 改进后：
# SKILL.md
## 快速开始
[简短内容]

## 详细文档
- 功能 A: 见 [references/feature_a.md](references/feature_a.md)
- 功能 B: 见 [references/feature_b.md](references/feature_b.md)

4.3 脚本执行失败

问题：scripts/ 中的脚本运行出错

解决方案：

确保依赖已安装
添加错误处理
提供详细的错误信息

python

# 改进后的脚本
import sys

def main():
    try:
        # 检查依赖
        import pandas
    except ImportError:
        print("错误：缺少 pandas。请运行 `pip install pandas`")
        sys.exit(1)

    try:
        # 主逻辑
        process()
    except FileNotFoundError as e:
        print(f"错误：找不到文件 - {e}")
        sys.exit(1)
    except Exception as e:
        print(f"错误：{e}")
        sys.exit(1)

if __name__ == "__main__":
    main()

4.4 输出质量不稳定

问题：相同输入产生不同质量的输出

解决方案：

添加具体示例
使用检查清单
定义质量标准

markdown

## 输出要求

### 必须满足
- [ ] 所有公式无错误
- [ ] 格式与模板一致
- [ ] 数据源有标注

### 质量标准
- 专业级外观
- 无拼写错误
- 逻辑清晰

### 示例
[提供具体的好/坏示例对比]

5. 本章小结

关键要点

主题	要点
安装	Claude Code 最完整，claude.ai 直接可用
创建	六步流程：理解→规划→初始化→编辑→打包→迭代
企业	版本控制、协作开发、安全考虑
问题	description 是关键，渐进式加载防溢出

快速检查清单

创建 Skill 前检查：

[ ] name 唯一且符合规范（小写、连字符）
[ ] description 清晰列出功能和触发条件
[ ] SKILL.md < 500 行
[ ] 详细内容在 references/
[ ] 脚本经过测试
[ ] 无敏感信息硬编码

上一章：工作流类 Skills

下一章：总结与展望

Skills 使用指南与最佳实践 ​

本章概览 ​

1. 安装与配置 ​

1.1 在 Claude Code 中使用 ​

添加官方 Skills 市场 ​

浏览和安装 ​

使用 Skills ​

1.2 在 Claude.ai 中使用 ​

启用 Skills ​

上传自定义 Skills ​

1.3 通过 API 使用 ​

2. 创建自定义 Skills ​

2.1 快速开始 ​

最简 Skill 结构 ​

SKILL.md 模板 ​

2.2 完整创建流程 ​

Step 1：明确需求 ​

Step 2：初始化项目 ​

Step 3：编写 SKILL.md ​

Frontmatter（关键） ​

Body ​

Step 4：添加资源（可选） ​

scripts/ ​

references/ ​

Step 6：打包分发 ​

2.3 高级技巧 ​

渐进式加载 ​

条件分支 ​

脚本封装 ​

3. 企业级最佳实践 ​

3.1 组织 Skills 库 ​

3.2 版本控制 ​

3.3 协作开发 ​

3.4 安全考虑 ​

敏感信息处理 ​

权限控制 ​

3.5 监控和反馈 ​

4. 常见问题与解决方案 ​

4.1 Skill 未被触发 ​

4.2 上下文溢出 ​

4.3 脚本执行失败 ​

4.4 输出质量不稳定 ​

5. 本章小结 ​

关键要点 ​

快速检查清单 ​

Skills 使用指南与最佳实践

本章概览

1. 安装与配置

1.1 在 Claude Code 中使用

添加官方 Skills 市场

浏览和安装

使用 Skills

1.2 在 Claude.ai 中使用

启用 Skills

上传自定义 Skills

1.3 通过 API 使用

2. 创建自定义 Skills

2.1 快速开始

最简 Skill 结构

SKILL.md 模板

2.2 完整创建流程

Step 1：明确需求

Step 2：初始化项目

Step 3：编写 SKILL.md

Frontmatter（关键）

Body

Step 4：添加资源（可选）

scripts/

references/

Step 6：打包分发

2.3 高级技巧

渐进式加载

条件分支

脚本封装

3. 企业级最佳实践

3.1 组织 Skills 库

3.2 版本控制

3.3 协作开发

3.4 安全考虑

敏感信息处理

权限控制

3.5 监控和反馈

4. 常见问题与解决方案

4.1 Skill 未被触发

4.2 上下文溢出

4.3 脚本执行失败

4.4 输出质量不稳定

5. 本章小结

关键要点

快速检查清单