skill-name/
├── SKILL.md          # 核心文件（必须）
├── scripts/          # 可执行脚本（可选）
├── references/       # 参考文档（可选）
└── assets/          # 资源文件（可选）

---
name: my-custom-skill
description: 描述这个Skill做什么，以及什么时候应该触发它
---

---
name: pdf-editor
description: PDF文档编辑和处理。当用户说"帮我旋转这个PDF"、"合并多个PDF"、"从PDF里提取文字"、"给PDF加水印"、"压缩PDF"时触发。
---

---
name: pdf-editor
description: 这个Skill可以编辑PDF文件，支持多种操作。
---

my-skill/
├── SKILL.md           # ✅ 必须
├── scripts/          # 可选
│   ├── do_something.py
│   └── helper.sh
├── references/       # 可选
│   ├── api_docs.md
│   └── schemas.md
└── assets/          # 可选
    ├── template.html
    └── logo.png

description: 当用户说"帮我XXX"、"做一下YYY"、"生成ZZZ"时触发。

description: PDF旋转和方向调整。当用户明确说"旋转"、"转方向"、"orientation"时触发。
# 主动排除：PDF内容识别（那是OCR Skill的事）

# ✅ 正确
Extract text from PDF using pdfplumber.
Run `python scripts/extract_text.py --input <file>`.

# ❌ 错误
This skill can be used to extract text. It uses pdfplumber library.
You might want to try extracting the text when working with PDFs.

# Skill Name

## 快速用法（最常用）
[最简单的调用方式]

## 进阶用法（备用）
[复杂场景]

## 配置选项
[可调整的参数]

## 注意事项
[容易出错的地方]

## 参考资料
- 详细内容：See [references/api.md](references/api.md)
- 示例：See [references/examples.md](references/examples.md)

# PDF Processing

## 基本用法
使用 pdfplumber 提取文本：[示例]

## 进阶用法
- 表单填写：See [references/forms.md](references/forms.md)
- API 参考：See [references/api.md](references/api.md)
- 更多示例：See [references/examples.md](references/examples.md)

references/
├── api.md          # API 文档
├── schemas.md      # 数据结构
├── examples.md      # 示例
└── policies.md      # 政策/规范

# API Reference

## 目录
- [create](#create) - 创建资源
- [update](#update) - 更新资源
- [delete](#delete) - 删除资源

## create
...

brand-skill/
├── SKILL.md
└── assets/
    ├── logo.png           # 直接复用
    ├── email-template.html # 直接复用
    └── colors.css         # 直接复用

mkdir -p pdf-rotate/{scripts,references,assets}
touch pdf-rotate/SKILL.md

---
name: pdf-rotate
description: PDF文档旋转和方向调整。当用户说"旋转PDF"、"PDF转方向"、"rotate PDF"、"PDF orientation"、"把PDF转90度"时触发。
---

# PDF Rotate

## 快速用法

使用 `scripts/rotate_pdf.py`：

```bash
python scripts/rotate_pdf.py --input <file.pdf> --angle 90 --output <output.pdf>

### 10.4 编写旋转脚本

```python
#!/usr/bin/env python3
"""PDF旋转脚本"""
import argparse
from pypdf import PdfReader, PdfWriter

def rotate_pdf(input_path, output_path, angle):
    reader = PdfReader(input_path)
    writer = PdfWriter()
    
    for page in reader.pages:
        page.rotate(90)  # 简单处理
        writer.add_page(page)
    
    with open(output_path, 'wb') as f:
        writer.write(f)

if __name__ == '__main__':
    parser = argparse.ArgumentParser()
    parser.add_argument('--input', required=True)
    parser.add_argument('--output')
    parser.add_argument('--angle', type=int, default=90)
    args = parser.parse_args()
    
    output = args.output or args.input.replace('.pdf', '_rotated.pdf')
    rotate_pdf(args.input, output, args.angle)

python scripts/package_skill.py pdf-rotate
# 生成 pdf-rotate.skill 文件

# 错误
description: 这个Skill用于处理PDF文件，可以旋转、合并、分割等。

# 正确
description: PDF旋转。当用户说"旋转PDF"、"PDF转方向"、"rotate PDF"时触发。

# 错误：正文写了 2000 行
# 包括所有API、所有示例、所有变体

# 正确：正文精简，详细内容放 references/

# 错误
name: My Custom Skill  # 包含空格和大写
name: my_custom_skill  # 下划线而非连字符

# 正确
name: my-custom-skill

# 错误：创建了这些
my-skill/
├── SKILL.md
├── README.md        # ❌ 不需要
├── CHANGELOG.md     # ❌ 不需要
├── INSTALL.md       # ❌ 不需要
└── ...

# 正确：只有必要的文件
my-skill/
├── SKILL.md
├── scripts/
└── references/