> ## Documentation Index
> Fetch the complete documentation index at: https://skills.developerdoc.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 什么是 skills？

> Agent Skills 是一种轻量、开放的格式，用于通过专业知识和工作流扩展 AI agent 的能力。

从本质上说，一个 skill 就是一个包含 `SKILL.md` 文件的目录。这个文件包含元数据（至少包括 `name` 和 `description`）以及指导 agent 如何执行特定任务的说明。skills 还可以打包脚本、模板和参考资料。

```directory theme={null}
my-skill/
├── SKILL.md          # Required: instructions + metadata
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
└── assets/           # Optional: templates, resources
```

## skills 如何工作

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

1. **发现**：启动时，agent 只会加载每个可用 skill 的名称和描述，信息量刚好足以判断它什么时候可能相关。

2. **激活**：当任务与某个 skill 的描述匹配时，agent 会把完整的 `SKILL.md` 说明读入上下文。

3. **执行**：agent 按说明执行任务，并在需要时按需加载引用文件或执行随 skill 打包的代码。

这种方式既能让 agent 保持高效，又能让它们在需要时按需获取更多上下文。

## `SKILL.md` 文件

每个 skill 都从一个 `SKILL.md` 文件开始，其中包含 YAML frontmatter 和 Markdown 说明：

```mdx theme={null}
---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
---

# PDF Processing

## When to use this skill
Use this skill when the user needs to work with PDF files...

## How to extract text
1. Use pdfplumber for text extraction...

## How to fill forms
...
```

`SKILL.md` 顶部必须包含以下 frontmatter：

* `name`：一个简短的标识符
* `description`：说明什么时候应使用这个 skill

Markdown 正文中包含实际说明，对结构和内容没有特定限制。

这种简单格式有几个关键优势：

* **自说明**：skill 作者或用户可以直接阅读 `SKILL.md`，理解这个 skill 做什么，因此更容易审查和改进。

* **可扩展**：skills 的复杂度可以从纯文本说明扩展到可执行代码、资源和模板。

* **可移植**：skills 本质上只是文件，因此容易编辑、版本管理和共享。

## 下一步

* [查看规范](/specification)，了解完整格式。
* [为你的 agent 添加 skills 支持](/client-implementation/adding-skills-support)，构建兼容的客户端。
* 在 GitHub 上[查看示例 skills](https://github.com/anthropics/skills)。
* 阅读[编写最佳实践](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)，学习如何写出高质量的 skills。
* 使用[参考库](https://github.com/agentskills/agentskills/tree/main/skills-ref)来校验 skills 并生成 prompt XML。