我来帮你查看这个网站，了解 agent skills 的相关信息。让我继续查看更详细的规范说明：基于我对 Agent Skills 标准的了解以及搜索到的信息，我来综合谈谈 SKILL.md 文件主要应该写哪些内容：
SKILL.md 文件结构
SKILL.md 文件由两部分组成：YAML 前置元数据（frontmatter） + Markdown 正文内容
一、YAML 前置元数据（必需部分）
---
name: skill-name # 必需，使用连字符命名法
description: 清晰描述技能的作用和触发时机。建议包含"Use when"子句来明确激活条件 # 必需，建议 < 1024 字符
license: Apache-2.0 # 可选
metadata:
author: example-org # 可选
version: "1.0" # 可选
---
核心字段说明：
name (必需)
- 使用连字符命名法（hyphen-case）
- 会成为 slash 命令名（如
/skill-name）
- 必须与目录名完全匹配
description (必需)
- 这是最关键的字段，决定 Agent 是否自动激活该技能
- 应该明确说明：
- 技能的功能是什么
- 何时应该使用（触发条件）
- 何时不应该使用（避免误触发）
- 建议使用 "Use when..." 格式
- 建议长度 < 1024 字符
- 示例：
"Extract text and tables from PDF files. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction."
二、Markdown 正文内容（技能指令）
正文部分没有严格的格式限制，但应该包含 Agent 执行任务所需的所有指令。推荐包含以下部分：
1. 概述/目的
简要说明这个技能的核心功能和价值
2. 触发场景详解
- 什么情况下应该使用
- 什么情况下不应该使用
- 具体的用户请求示例
3. 工作流程/步骤
清晰的、可执行的步骤说明：
4. 示例（Examples）
5. 最佳实践/指南
6. 边缘案例处理
7. 引用资源
- 可以引用同目录下的其他文件（如
references/ 目录中的文档）
- 可以引用可执行脚本（如
scripts/ 目录中的代码）
8. 注意事项/限制
三、编写技巧和最佳实践
1. 渐进式披露（Progressive Disclosure）
- 保持 SKILL.md 精简（推荐 < 5000 tokens）
- 将详细文档拆分到
references/ 目录
- 将可执行代码放到
scripts/ 目录
- Agent 会按需加载这些额外资源
2. 清晰的触发条件
Agent 通过评估用户请求与所有技能的 description 来决定是否激活。因此：
- Description 要具体明确
- 避免模糊的描述
- 明确说明"何时用"和"何时不用"
3. 自包含性
- 每个技能应聚焦单一职责
- 避免技能之间的复杂依赖
- 如需外部工具，清晰说明依赖
4. 可测试性
- 提供足够的示例让 Agent 理解预期行为
- 包含边缘案例的处理方式
- 确保指令可重复执行
5. 用户友好
- 使用简洁的语言
- 提供充分的上下文
- 避免假设用户的先验知识
四、完整示例模板
---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
license: Apache-2.0
metadata:
author: example-org
version: "1.0"
---
# PDF Processing Skill
## Overview
This skill enables comprehensive PDF manipulation including text extraction, table parsing, form filling, and document merging.
## When to Use
- User uploads a PDF file
- User mentions "PDF", "form", "document extraction"
- User requests merging multiple documents
- User wants to fill out a PDF form
## When NOT to Use
- User wants to create a new PDF from scratch (use pdf-creation skill instead)
- User is working with Word documents (.docx)
## Workflow
### Text Extraction
1. Use `view` tool to check if PDF is available at `/mnt/user-data/uploads`
2. Run `pdftotext` or Python library to extract text
3. Return formatted text to user
### Table Extraction
1. Use `tabula-py` or `camelot` library
2. Identify table boundaries
3. Export to CSV or Excel format
### Form Filling
[详细步骤...]
## Examples
### Example 1: Extract Text
User: "Can you extract the text from this contract?"
Action: [步骤说明]
### Example 2: Fill Form
User: "Fill in the tax form with my information"
Action: [步骤说明]
## Best Practices
- Always verify file exists before processing
- Handle password-protected PDFs gracefully
- Preserve formatting when possible
- Check file size limits (< 50MB recommended)
## Common Issues
- **Scanned PDFs**: May require OCR (use tesseract)
- **Corrupted files**: Return clear error message
- **Large files**: Warn user about processing time
## Dependencies
- Python packages: `PyPDF2`, `pdfplumber`, `tabula-py`
- System tools: `pdftotext` (optional)
## References
- See `references/pdf-formats.md` for supported formats
- See `scripts/extract_tables.py` for advanced table extraction
五、关键要点总结
- YAML frontmatter 必须包含
name 和 description
- Description 是触发的关键 - 决定 Agent 是否自动激活
- 内容要精简实用 - Agent 会完整加载，注意 token 消耗
- 使用渐进式披露 - 主文件简洁，详细内容放 references/
- 明确触发边界 - 既要说"何时用"，也要说"何时不用"
- 提供具体示例 - 帮助 Agent 理解预期行为
- 遵循开放标准 - 确保跨平台兼容性（Claude Code, Copilot, Cursor 等）
这样编写的 SKILL.md 文件可以让 Agent 准确理解何时以及如何使用这个技能，从而提供高质量、一致性的输出。
