Skills -Claude

casterQ

990人浏览 · 2025-11-19 19:34:29

casterQ · 2025-11-19 19:34:29 发布

1. Agent Skills 定义

包含指令(instructions)、脚本(scripts)、资源(resources)的文件夹。

指令：md文件中的文字指令
脚本：python脚本或者bash命令
资源：参考资料
当 Claude 判定用户需求与某个 Skill 功能适配，就会加载阅读它的指令并执行脚本。
它是对 slash command 的一种约束和抽象，是对主agent执行某一特定任务的全方面指导。

SKILL 是一种理念，一种规范：
- 技术人员不要把它想的很简单(没有技术上的难点，但是理念很重要)
- 非技术人员也不要把它想的很复杂(没有技术上的门槛，只要理念正确)

2. Agent Skills 组成

2.1. Skill.md

Skill 的最核心指令文件，该文件必须以YAML前置元数据开头，其中包含：
必填的元数据(渐进式披露第一级)

name：名称
description：功能和使用时机
选填的元数据
allowed-tools：来限制当某个 SKILL 激活时 Claude 可以使用的工具。
license：适用于该技能的许可证文件名称
metadata：KV存储其他属性
version: 1.0.0
dependencies：python>=3.12

Markdown格式正文（渐进式披露第二级）

功能描述
执行步骤
技能示例
依赖文件夹内的子指令、脚本和资源等（渐进式披露第三级）
…

2.2. Script

大型语言模型在许多任务上表现出色，但某些操作更适合用传统代码执行，主要是为了保障执行确定性，并且能节省toke消耗和上下文空间。
下面的示例中，PDF SKILL 包含一个预先编写的Python脚本，该脚本可以读取PDF并提取所有表单字段。Claude无需将脚本或PDF加载到上下文中就能运行此脚本。
脚本的调用

2.3. resources

需要补充知识给 Claude 时再按需加载到上下文的参考资料

数据库表结构
API 规范
领域知识
…

3. Agent Skills 构造过程

让 Claude 不通过模型执行这个任务，观察它在哪些地方遇到困难或需要额外的背景信息等卡点，这些卡点就是后续构建 Skill 需要弥补的指令、脚本以及资源。
核心 SKILL.md 文件要按功能拆分多个并互相引用，按需加载以减少 token 消耗。
需要明确脚本是作为可执行工具还是参考文档，让 Claude 清楚是直接运行脚本还是将其读入上下文。
观察 Claude 如何使用你的技能，然后不断修正迭代你的 SKILL，来规避一些问题

意外的执行路径：避免 Skill 执行逻辑失控
对某些特定上下文的过度依赖：避免 Skill 适用范围过窄

name和description是Claude决定是否触发SKILL的关键
与Claude一起迭代你的SKILL：把Claude执行当前Skill的经验（成功方法、踩过的坑）转化为 Skill 的固化内容，让Skill从你觉得好用变成 Claude 觉得好用。

4. 简单 Skill 示例

pdf-processing/          # 技能根目录（以技能功能命名）
├── SKILL.md             # 【核心指令】Skill的入口文件定义基础信息、核心能力与使用指引
├── FORMS.md             # 【子指令】专门进行PDF表单处理
├── REFERENCE.md         # 【资源文件】API参考手册
└── scripts/             # 【脚本目录】
    ├── fill_form.py     # 【脚本1】PDF表单填写的脚本
    └── validate.py      # 【脚本2】PDF内容验证的脚本

SKILL.md:

---
name: pdf-processing
description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages.
---

# PDF Processing

## Quick start

Extract text:
```python
import pdfplumber
with pdfplumber.open("doc.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```python


For form filling, see [FORMS.md](FORMS.md).
For detailed API reference, see [REFERENCE.md](REFERENCE.md).

## Requirements
Packages must be installed in your environment:
```bash
pip install pypdf pdfplumber
```bash

5. 复杂 Skill 示例（官方 skill-creator 解析）

5.1. 目录结构

skill-creator/               #  技能根目录
├── SKILL.md                 # 【核心指令】
└── scripts/                 # 【脚本目录】
    ├── init_skill.py        # 【脚本1】模板化方式快速创建标准化的 **SKILL** 目录结构及配套文件并设置TODO供给后续用户填写修改
    ├── package_skill.py     # 【脚本1】调用validate.py校验然后ZIP打包
    └── quick_validate.py    # 【脚本2】校验SKILL.MD格式是否正确

5.2. SKILL.md 结构概述

元数据头：定义SKILL的名称，功能，使用时机
介绍SKILL是什么可以提供什么功能
- 特定领域工作的多步骤执行流程指导
- 与特定文件格式（如 PDF）或 API 交互的操作说明
- 企业专属私域知识、数据 schema、公司架构、业务信息等
- 用于复杂 / 重复任务的脚本、参考文档、模板等

SKILL技能组成结构

 技能名称/
 ├── SKILL.md （必填）
 │   ├── YAML 元数据（必填）
 │   │   ├── name: 技能名称（必填，需明确）
 │   │   └── description: 技能描述（必填，需说明适用场景）
 │   └── Markdown 说明文档（必填，含使用流程等核心信息）
 └── 捆绑资源（可选）
     ├── scripts/          - 可执行代码（Python/Bash 等）
     ├── references/       - 参考文档（按需加载到上下文的资料）
     └── assets/           - 输出时用到的文件（用于最终输出的模板、图标等）

以上各部分组成的详细介绍(作用、工作时机、示例、优势、注意事项)
渐进式披露原则介绍(三级)
创建的完整流程
6.1. 和claude串通知识，给他提供你要做的skill示例让他知道技能需求
6.2. 抽取可复用技能为脚本(PDF抽取表单)、模板（HTML模版）、参考文档
6.3. 使用 init_skill.py [skillname] [path] 脚本初始化SKILL（下面讲）
6.4. 编写SKILL（scripts、references、assets然后是更新SKILL.md）（记住不要依赖当前claude窗口已有的知识去认为另一个claude也有）
6.5. 使用 package_skill.py [path]打包SKILL (下面讲)
6.6. 迭代更新(你和claude一起不断完善SKILL)

5.3. init_skill.py 功能概述

四个木块的模版
title_case_skill_name(skill_name) 技能名字转化格式-分割
init_skill(skill_name, path)
3.1. 目录路径检查校验创建
3.2. 通过SKILL_TEMPLATE生成核心SKILL.md
3.3. 使用另外三个模板分别初始化scripts(example.py)、references(api_reference.md)、assets(example_asset.txt)
3.4. 输出init 成功信息以及用户TODO
- SKILL_TEMPLATE：补充技能功能和触发场景、1-2 句话概括技能核心能力、选择技能文档结构(工作流(顺序性workflow)、任务（功能点ABC）、指南（规范和要求）、能力（？）)、替换章节标题并补充核心内容
- EXAMPLE_SCRIPT：补充实际脚本