skills注意点

一、什么是skills（https://claudecn.com/docs/agent-skills/）

skills包含三种类型的内容，每种数据都在不同的时间加载。

元数据：始终加载

• Skill 的 YAML frontmatter 提供发现信息
• Claude 在启动时加载此元数据并包含在系统提示中

指令（触发时加载）

• SKILL.md 主体包含过程知识：工作流、最佳实践和指导
• 当你请求与 Skill 描述匹配的内容时，Claude 通过 bash 从文件系统读取 SKILL.md
• 只有这时内容才进入上下文窗口

资源和代码（按需加载）

• 指令: 额外的 markdown 文件
• 代码: Claude 通过 bash 运行的可执行脚本
• 资源: 数据库模式、API 文档、模板或示例等参考材料

二、skill的结构

---
name: 你的 Skill 名称
description: 此 Skill 的简要描述以及何时使用它
---

# Skill Name

## 快速开始

### 基本用法
步骤 1：准备工作
步骤 2：执行任务

### 高级用法
步骤 1：配置选项
步骤 2：优化性能

## 最佳实践

### 性能优化
- 建议 1
- 建议 2

### 错误处理
- 常见错误及解决方案

必需字段: name 和 description

Frontmatter 限制:

• name: 最多 64 字符
• description: 最多 1024 字符

三、skill的编写技巧

描述示例

description: 处理财务报表

问题：

• 缺少触发场景描述
• 意图模糊
• 命中准确率低

修改

• 采用动作+触发时机的结构
• 什么时候用于什么

结构化指令

# Skill Name

## 快速开始

### 基本用法
步骤 1：准备工作
步骤 2：执行任务

### 高级用法
步骤 1：配置选项
步骤 2：优化性能

## 最佳实践

### 性能优化
- 建议 1
- 建议 2

### 错误处理
- 常见错误及解决方案

提供具体示例

包含可运行的代码

## 示例：提取 PDF 文本

```python
import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    for page in pdf.pages:
        text = page.extract_text()
        print(text)
```

**输出**：
```
Page 1 content here...
```

避免抽象描述：

## 示例
使用相关库读取 PDF 文件并提取内容。

复杂内容单独文件

pdf-skill/
├── SKILL.md          # 主指令（< 5k tokens）
├── FORMS.md          # 表单处理详细指南
├── MERGE.md          # PDF 合并指南
├── REFERENCE.md      # 完整 API 参考
└── scripts/
    └── utilities.py  # 实用脚本

何时使用脚本

使用脚本的场景：

• 确定性操作（文件格式转换、数据验证）
• 复杂算法（加密、压缩）
• 需要特定库的操作

使用指令的场景：

• 需要灵活判断的任务
• 上下文相关的决策
• 创意性工作

## 数据验证

使用验证脚本确保数据格式正确：

```bash
python scripts/validate.py data.json
```

脚本会检查：
- JSON 格式有效性
- 必需字段存在
- 数据类型正确

总结

编写高质量 Agent Skills 的关键：

1. 清晰的描述 - Claude 知道何时使用
2. 结构化内容 - 易于理解和导航
3. 具体示例 - 可直接使用的代码
4. 渐进式披露 - 从简单到复杂
5. 完善的文档 - 限制、错误、最佳实践

四、通过工具验证skill

通过skills-ref 进行验证skill

• YAML格式语法检查
• name匹配度验证
• 文件应用完整性检查

CLI

# Validate a skill
skills-ref validate path/to/skill

# Read skill properties (outputs JSON)
skills-ref read-properties path/to/skill

# Generate <available_skills> XML for agent prompts
skills-ref to-prompt path/to/skill-a path/to/skill-b

python API

from pathlib import Path
from skills_ref import validate, read_properties, to_prompt

# Validate a skill directory
problems = validate(Path("my-skill"))
if problems:
    print("Validation errors:", problems)

# Read skill properties
props = read_properties(Path("my-skill"))
print(f"Skill: {props.name} - {props.description}")

# Generate prompt for available skills
prompt = to_prompt([Path("skill-a"), Path("skill-b")])
print(prompt)