sayurinana/agent-aide

Fork 0

Files

sayurinana(vm) 0079bd5cd4 📃 docs: 暂存

2025-12-18 22:52:53 +08:00

10 KiB

Executable File

Raw Blame History

Claude Code 技能（Skills）指南

概述

Agent Skills（技能）是模块化的能力包，用于扩展 Claude 的功能。与斜杠命令不同，技能是由 Claude 根据用户请求自动激活的，而非用户显式调用。

核心特性

模型调用：Claude 根据任务上下文自主决定何时使用技能
可发现性：Claude 通过技能的 description 了解何时使用
可共享：通过 git 或插件在团队间分发
可组合：多个技能可以协同处理复杂任务

技能存储位置

类型	位置	适用场景
个人技能	`~/.claude/skills/`	个人工作流、实验性技能、跨所有项目可用
项目技能	`.claude/skills/`	团队工作流、项目特定专业知识、通过 git 自动共享
插件技能	插件 `skills/` 目录	通过插件安装自动可用

技能文件结构

基本结构

每个技能是一个包含 SKILL.md 文件的目录：

my-skill/
├── SKILL.md           # 必需：技能定义文件
├── FORMS.md           # 可选：专题文档
├── REFERENCE.md       # 可选：API 参考
└── scripts/           # 可选：辅助脚本
    └── helper.py

SKILL.md 文件格式

---
name: your-skill-name
description: 简要描述技能的功能和使用场景。当用户需要...时使用。
allowed-tools: Read, Grep, Glob    # 可选：限制可用工具
---

# 技能名称

## 说明
提供清晰的分步指导。

## 示例
展示具体的使用示例。

字段要求

字段	要求	限制
`name`	必需	小写字母、数字和连字符，最多 64 字符
`description`	必需	描述功能和使用时机，最多 1024 字符
`allowed-tools`	可选	逗号分隔的工具列表，限制技能可使用的工具

Description 编写指南

关键原则：description 是技能的主要发现机制，Claude 根据它决定何时使用技能。

必须包含的内容

技能做什么 - 核心功能描述
什么时候使用它 - 明确的触发条件
用户可能提到的关键词 - 帮助匹配用户请求

示例对比

❌ 太模糊：

description: Helps with documents

✅ 具体明确：

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

✅ 另一个好例子：

description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or analyzing tabular data in .xlsx format.

渐进式披露

技能使用渐进式披露来高效管理上下文：

SKILL.md 仅在技能被触发时加载
附加文件（如 FORMS.md、REFERENCE.md）仅在 Claude 需要时按需加载

这意味着你可以在技能目录中包含大量参考资料，而不会浪费上下文空间。

快速开始

创建个人技能

# 创建技能目录
mkdir -p ~/.claude/skills/commit-helper

# 创建 SKILL.md 文件
cat > ~/.claude/skills/commit-helper/SKILL.md << 'EOF'
---
name: commit-helper
description: 从 git diff 生成清晰的提交信息。当编写提交信息或审查暂存变更时使用。
---

# 提交信息生成器

## 说明

1. 运行 `git diff --staged` 查看变更
2. 我会建议一个提交信息，包含：
   - 50 字符以内的摘要
   - 详细描述
   - 受影响的组件

## 最佳实践

- 使用现在时态
- 说明"做了什么"和"为什么"，而非"怎么做"
EOF

创建项目技能

# 创建项目技能目录
mkdir -p .claude/skills/code-reviewer

# 创建 SKILL.md 文件
cat > .claude/skills/code-reviewer/SKILL.md << 'EOF'
---
name: code-reviewer
description: 审查代码的最佳实践和潜在问题。当审查代码、检查 PR 或分析代码质量时使用。
allowed-tools: Read, Grep, Glob
---

# 代码审查器

## 审查清单

1. 代码组织和结构
2. 错误处理
3. 性能考虑
4. 安全隐患
5. 测试覆盖率

## 说明

1. 使用 Read 工具查看目标文件
2. 使用 Grep 搜索模式
3. 使用 Glob 查找相关文件
4. 提供详细的代码质量反馈
EOF

技能工作原理

自动发现机制

Claude 自动发现三个位置的技能：

~/.claude/skills/（个人）
.claude/skills/（项目）
已安装插件的技能目录

查看可用技能

有哪些可用的技能？

或

列出所有可用的技能

智能激活

技能通过 description 匹配自动激活：

# 用户请求
帮我从这个 PDF 中提取文本

# Claude 自动激活匹配的技能（如 pdf-processing 技能）

工具限制

使用 allowed-tools 限制技能可以使用的工具：

---
name: safe-file-reader
description: 只读方式访问文件。当需要只读文件访问且不进行修改时使用。
allowed-tools: Read, Grep, Glob
---

适用场景：

只读技能（不应修改文件）
限定范围技能（仅数据分析，不写文件）
安全敏感工作流

实用示例

示例1：简单技能（单文件）

---
name: api-documenter
description: 为 API 端点生成文档。当需要记录 REST API、GraphQL 接口或函数签名时使用。
---

# API 文档生成器

## 说明

1. 分析代码中的 API 端点
2. 生成包含以下内容的文档：
   - 端点路径和方法
   - 请求参数
   - 响应格式
   - 示例请求

## 文档格式

使用 OpenAPI 3.0 规范格式。

示例2：带工具限制的技能

---
name: safe-file-reader
description: 只读方式访问文件。当需要只读文件访问且不进行修改时使用。
allowed-tools: Read, Grep, Glob
---

# 安全文件读取器

## 说明

此技能仅使用只读工具：
- Read：读取文件内容
- Grep：搜索文件内容
- Glob：查找文件

## 使用场景

- 代码审查（不修改）
- 日志分析
- 配置检查

示例3：多文件技能

目录结构：

pdf-processing/
├── SKILL.md
├── FORMS.md
├── REFERENCE.md
└── scripts/
    ├── fill_form.py
    └── validate.py

SKILL.md：

---
name: pdf-processing
description: 提取文本、填写表单、合并 PDF。当处理 PDF 文件、表单或文档提取时使用。需要 pypdf 和 pdfplumber 包。
---

# PDF 处理

## 快速开始

提取文本：
```python
import pdfplumber
with pdfplumber.open("doc.pdf") as pdf:
    text = pdf.pages[0].extract_text()

表单填写请参阅 FORMS.md。详细 API 参考请参阅 REFERENCE.md。

依赖

pip install pypdf pdfplumber


### 示例4：数据库操作技能

```yaml
---
name: db-migration-helper
description: 帮助创建和管理数据库迁移。当需要创建迁移脚本、修改数据库架构或执行数据迁移时使用。
---

# 数据库迁移助手

## 支持的数据库

- PostgreSQL
- MySQL
- SQLite

## 迁移流程

1. 分析当前架构
2. 生成迁移脚本
3. 验证迁移安全性
4. 提供回滚方案

## 最佳实践

- 始终创建回滚脚本
- 在测试环境先验证
- 大表修改分批进行

团队共享技能

方式1：通过 Git（项目技能）

# 添加到项目
mkdir -p .claude/skills/team-skill
# 创建 SKILL.md...

# 提交到仓库
git add .claude/skills/
git commit -m "添加团队技能"
git push

# 团队成员拉取后自动可用
git pull
claude  # 技能立即可用

方式2：通过插件（推荐）

创建包含 skills/ 目录的插件
将插件添加到市场
团队成员安装插件即可使用

管理技能

更新技能

# 编辑 SKILL.md
code ~/.claude/skills/my-skill/SKILL.md

# 重启 Claude Code 使更改生效

删除技能

# 删除个人技能
rm -rf ~/.claude/skills/my-skill

# 删除项目技能
rm -rf .claude/skills/my-skill
git commit -m "移除不再使用的技能"

故障排除

Claude 没有使用我的技能

检查1：Description 是否足够具体

包含 WHAT（做什么）和 WHEN（何时使用）
使用用户可能提到的具体关键词
避免模糊描述

检查2：YAML 语法是否有效

# 查看 frontmatter
cat .claude/skills/my-skill/SKILL.md | head -n 15

# 常见问题：
# - 缺少开头/结尾的 ---
# - 使用 Tab 而非空格
# - 特殊字符未加引号

检查3：文件路径是否正确

# 个人技能
ls ~/.claude/skills/*/SKILL.md

# 项目技能
ls .claude/skills/*/SKILL.md

检查4：使用调试模式

claude --debug

技能执行出错

检查依赖项是否已安装
确保脚本有执行权限：chmod +x scripts/*.py
使用正斜杠路径：scripts/helper.py ✅（而非 scripts\helper.py ❌）

技能与斜杠命令的区别

方面	Agent Skills	斜杠命令
调用方式	模型自动调用	用户显式调用（`/command`）
发现机制	基于 description	基于 `/` 前缀
复杂度	复杂能力包	简单提示
文件结构	目录 + SKILL.md + 资源	单个 .md 文件
适用场景	扩展 Claude 能力	快速重复任务

选择建议：

使用斜杠命令：快速、常用的提示（review、explain、optimize）
使用 Skills：包含脚本、跨文件知识、团队标准化的综合工作流

最佳实践

实践	说明
保持专注	一个技能解决一个能力（如"PDF 表单填充"而非"文档处理"）
清晰描述	包含具体触发条件，如"当处理 Excel 文件、电子表格时使用"
测试验证	技能是否在预期情况下激活？说明是否清晰？
版本记录	在 SKILL.md 中记录版本历史

# 我的技能

## 版本历史
- v2.0.0 (2025-10-01): 重大 API 变更
- v1.1.0 (2025-09-15): 添加新功能
- v1.0.0 (2025-09-01): 初始版本

10 KiB Executable File Raw Blame History Unescape Escape