第 2 章：Skill 结构设计指南¶

本章目标： 掌握 Skill 的完整结构、学会编写规范的 SKILL.md、理解资源组织方式
预计阅读时间： 40 分钟
难度等级： ⭐⭐⭐☆☆（进阶）

📖 目录¶

Skill 标准结构
YAML 元数据详解
SKILL.md 编写规范
脚本资源设计
参考文档设计
资产文件设计
文件命名规范
完整案例
本章实践

Skill 标准结构¶

完整目录结构¶

skill-name/
├── SKILL.md                    # 必需：主文档
├── scripts/                    # 可选：脚本目录
│   ├── script1.py              # Python 脚本
│   ├── script2.sh              # Bash 脚本
│   └── utils/                  # 工具函数
│       └── helpers.py
├── references/                 # 可选：参考文档目录
│   ├── api-reference.md        # API 文档
│   ├── best-practices.md       # 最佳实践
│   └── troubleshooting.md      # 故障排查
├── assets/                     # 可选：资产目录
│   ├── template.docx           # 模板文件
│   ├── logo.png                # 图片
│   └── config-template.yaml    # 配置模板
└── tests/                      # 可选：测试目录（开发用，不打包）
    ├── test_script1.py
    └── fixtures/
        └── sample-input.pdf

各部分作用¶

部分	必需性	加载时机	占用上下文	用途
SKILL.md	必需	触发后加载	是 (~3000-5000 词)	核心指令和工作流
scripts/	可选	执行时（可不加载）	否	可执行代码
references/	可选	按需加载	是（仅加载时）	详细文档和参考
assets/	可选	使用时复制	否	模板和素材
tests/	可选	不打包	否	开发测试

最小可行 Skill¶

1 2	`minimal-skill/ └── SKILL.md # 只有这个也可以！`

示例：

---
name: hello-world
description: 简单的问候技能。当用户说"你好"、"打招呼"、"greeting"时使用
---

# Hello World Skill

当用户打招呼时，用友好的语气回应。

## 示例

用户："你好"
回应："你好！有什么我可以帮助你的吗？"

用户："Hello"
回应："Hello! How can I help you today?"

复杂 Skill 示例¶

pdf-master/
├── SKILL.md                      # 主文档（核心工作流）
├── scripts/
│   ├── extract_text.py           # 文本提取
│   ├── rotate.py                 # 旋转
│   ├── merge.py                  # 合并
│   ├── split.py                  # 拆分
│   └── compress.py               # 压缩
├── references/
│   ├── api-reference.md          # 完整 API 文档
│   ├── formats.md                # 支持的文件格式
│   ├── examples.md               # 使用示例
│   └── troubleshooting.md        # 故障排查
├── assets/
│   ├── templates/
│   │   ├── report.docx           # 报告模板
│   │   └── invoice.docx          # 发票模板
│   └── fonts/
│       └── custom.ttf            # 自定义字体
└── tests/
    ├── test_extract.py
    ├── test_rotate.py
    └── fixtures/
        └── sample.pdf

YAML 元数据详解¶

基本结构¶

---
name: skill-name
description: |
  Skill 描述，包含功能和触发场景
---

name 字段规范¶

规则：

✓ 只能使用小写字母、数字、连字符
✓ 长度 < 64 字符
✓ 使用动词 + 名词结构
✓ 按工具/领域命名空间（可选）

✗ 不能有大写字母
✗ 不能有空格
✗ 不能有下划线（用连字符）
✗ 不能过长

示例对比：

❌ 错误	✅ 正确	说明
`PDFTools`	`pdf-tools`	小写
`pdf_tools`	`pdf-tools`	连字符
`the-amazing-pdf-processor-skill`	`pdf-tools`	简洁
`pdf`	`pdf-tools`	描述性
`github-issue-tracker-pro-2026`	`gh-issues`	简洁 + 命名空间

命名空间示例：

gh-issues          # GitHub Issues 相关
gh-prs             # GitHub PRs 相关
linear-issues      # Linear Issues 相关
slack-notify       # Slack 通知相关
feishu-docs        # 飞书文档相关

description 字段规范¶

核心原则： description 是主要触发机制，必须清晰、全面、具体。

必须包含：

1
2
3

1. 核心功能（做什么）
2. 触发场景（何时使用）
3. 典型用例（用户会说什么）

结构模板：

description: |
  [核心功能概述]。当用户需要：
  (1) [场景 1]，
  (2) [场景 2]，
  (3) [场景 3]，
  或 [其他触发条件] 时使用

示例对比：

❌ 模糊描述：

description: 处理 PDF 文件

✅ 清晰描述：

description: |
  PDF 文件创建、编辑、分析。当用户需要：
  (1) 从 PDF 提取文本或表格，
  (2) 编辑、旋转、合并 PDF，
  (3) 分析 PDF 内容并生成摘要，
  (4) 转换 PDF 为其他格式，
  (5) 填写 PDF 表单时使用

❌ 缺少触发场景：

description: 代码审查工具，帮助审查代码质量

✅ 包含触发场景：

description: |
  代码审查：检查代码质量、安全问题、最佳实践。
  当用户需要：
  (1) 审查 Pull Request 代码，
  (2) 检查安全漏洞，
  (3) 验证代码规范遵守情况，
  (4) 生成审查报告时使用

完整元数据示例¶

示例 1：简单 Skill

---
name: weather
description: |
  获取天气信息。当用户询问天气、温度、天气预报，
  或需要查询特定城市的当前天气或未来预报时使用
---

示例 2：中等复杂度 Skill

---
name: github-issues
description: |
  GitHub Issues 管理：创建、查询、更新 Issue。
  当用户需要：
  (1) 创建新的 Issue 报告 Bug 或功能请求，
  (2) 搜索和筛选 Issues，
  (3) 更新 Issue 状态、标签、分配，
  (4) 关联 PR 和 Issue 时使用
---

示例 3：复杂 Skill

---
name: data-analysis
description: |
  数据分析：数据清洗、统计分析、可视化。
  当用户需要：
  (1) 清洗和预处理数据（处理缺失值、异常值），
  (2) 进行描述性统计分析，
  (3) 创建数据可视化（图表、图形），
  (4) 探索数据关系和相关性，
  (5) 生成数据分析报告时使用

  支持格式：CSV、Excel、JSON、SQL 数据库
---

常见错误¶

错误 1：在 description 中写"何时不使用"

❌ 错误：
description: |
  PDF 处理工具。注意：不处理加密 PDF，
  不处理扫描版 PDF，不处理超大文件...

✅ 正确：
description: |
  PDF 文件处理：提取文本、编辑、分析。
  当用户需要处理 PDF 文件时使用

# 在 SKILL.md 主体中说明限制：
## 限制
- 不支持加密 PDF
- 不支持扫描版（需要 OCR）
- 文件上限：100MB

错误 2：描述过于技术化

❌ 错误：
description: |
  使用 pdfplumber 和 pypdf 库实现 PDF 处理，
  支持 Python 3.8+，依赖 requirements.txt...

✅ 正确：
description: |
  PDF 文件处理：提取文本、编辑、分析。
  当用户需要处理 PDF 文件时使用

错误 3：添加额外字段

❌ 错误：
---
name: pdf-tools
description: PDF 处理
version: 1.0.0
author: John Doe
license: MIT
---

✅ 正确：
---
name: pdf-tools
description: PDF 文件处理：提取文本、编辑、分析...
---

# 其他信息放在 SKILL.md 主体末尾

SKILL.md 编写规范¶

标准结构¶

# [Skill 名称]

[1-2 句简短介绍]

## 快速开始

[最常用场景的简明示例]

## 核心功能

### 功能 1

[说明 + 示例]

### 功能 2

[说明 + 示例]

## 高级用法

[链接到参考文档]

## 限制与注意事项

[重要限制、边界情况]

## 故障排查

[常见问题和解决方案]

## 相关资源

- [参考文档 1](references/doc1.md)
- [参考文档 2](references/doc2.md)
- [脚本 1](scripts/script1.py)

各章节详解¶

1. 标题和介绍¶

要求： - 标题与 name 一致或更友好 - 介绍 1-2 句，说明核心用途

示例：

1
2
3

# PDF Tools

快速处理 PDF 文件：提取文本、编辑、合并、转换。

2. 快速开始¶

目的： 让用户/Agent 最快上手

结构：

## 快速开始

### 最简单的用法

[最简示例]

### 典型工作流

1. [步骤 1]
2. [步骤 2]
3. [步骤 3]

示例：

## 快速开始

### 提取 PDF 文本

```python
import pdfplumber

with pdfplumber.open('document.pdf') as pdf:
    text = pdf.pages[0].extract_text()
    print(text)

典型工作流¶

上传 PDF 文件
说"提取这个 PDF 的文本"

获取结构化输出

#### 3. 核心功能

**组织方式：**

**按功能分组：**
```markdown
## 核心功能

### 文本提取

从 PDF 提取纯文本、保留格式、提取表格。

```python
# 提取文本
text = page.extract_text()

# 提取表格
tables = page.extract_tables()

编辑操作¶

旋转、裁剪、合并、拆分。

# 旋转
page.rotate(90)

# 合并
pdf_writer.add_page(page)

格式转换¶

PDF ↔ Word、PDF ↔ 图片、PDF ↔ HTML。

**按场景分组：**
```markdown
## 核心功能

### 场景 1：阅读 PDF

提取文本、生成摘要、翻译内容。

### 场景 2：编辑 PDF

旋转页面、合并文件、添加水印。

### 场景 3：转换格式

转为 Word、转为图片、转为 HTML。

4. 高级用法¶

目的： 引导到详细文档，保持 SKILL.md 简洁

示例：

## 高级用法

### 批量处理

处理多个 PDF 文件，见 [批量处理指南](references/batch-processing.md)

### 自定义配置

自定义提取规则、输出格式，见 [配置指南](references/configuration.md)

### API 集成

通过 API 调用本 Skill，见 [API 文档](references/api.md)

5. 限制与注意事项¶

目的： 管理预期，避免误用

示例：

## 限制与注意事项

### 不支持的功能

- ❌ 加密 PDF 处理（需要先解密）
- ❌ 扫描版 PDF（需要 OCR，使用 ocr-skill）
- ❌ 手写内容识别

### 文件限制

- 最大文件大小：100MB
- 最大页数：1000 页
- 支持 PDF 版本：1.4-1.7

### 性能考虑

- 大文件处理可能需要较长时间
- 建议批量处理时每次 < 10 个文件

6. 故障排查¶

目的： 自助解决问题

结构：

## 故障排查

### 问题 1：[问题描述]

**症状：** [表现]
**原因：** [原因]
**解决：** [解决方案]

### 问题 2：[问题描述]

**症状：** [表现]
**原因：** [原因]
**解决：** [解决方案]

示例：

## 故障排查

### 无法打开 PDF 文件

**症状：** 报错 "File cannot be opened"
**原因：** 文件加密或损坏
**解决：** 
1. 确认文件未加密
2. 尝试用 PDF 阅读器打开验证
3. 重新下载文件

### 提取的文本乱码

**症状：** 提取的文本是乱码
**原因：** 字体编码问题或扫描版
**解决：**
1. 确认是文本型 PDF（不是扫描版）
2. 尝试指定编码：`extract_text(encoding='utf-8')`
3. 扫描版使用 ocr-skill

7. 相关资源¶

目的： 导航到所有资源文件

示例：

## 相关资源

### 脚本

- [extract_text.py](scripts/extract_text.py) - 文本提取
- [rotate_pdf.py](scripts/rotate_pdf.py) - 旋转 PDF
- [merge_pdfs.py](scripts/merge_pdfs.py) - 合并 PDF

### 参考文档

- [API 完整参考](references/api-reference.md)
- [最佳实践](references/best-practices.md)
- [使用示例](references/examples.md)

### 模板

- [报告模板](assets/templates/report.docx)
- [发票模板](assets/templates/invoice.docx)

写作风格¶

语态：

✓ 使用祈使句/不定式
✓ 简洁直接
✓ 避免冗长解释

❌ "你应该使用 pdfplumber 库来..."
✅ "使用 pdfplumber：`import pdfplumber`"

❌ "如果你想提取文本，那么可以..."
✅ "提取文本：`page.extract_text()`"

代码示例：

✓ 完整可运行
✓ 有注释（必要时）
✓ 展示常见用法
✓ 避免过度简化

❌ 不完整：
```python
import pdfplumber
# ... 省略 ...

✅ 完整：

import pdfplumber

with pdfplumber.open('file.pdf') as pdf:
    page = pdf.pages[0]
    text = page.extract_text()
    print(text)

1	`格式规范：`

✓ 使用 Markdown 语法 ✓ 代码块标注语言 ✓ 链接使用相对路径 ✓ 列表层次清晰

---

## 脚本资源设计

### 何时使用脚本

**适合场景：**

✓ 同一代码反复重写 ✓ 需要确定性执行 ✓ 复杂但可参数化 ✓ 性能关键路径 ✓ 需要测试验证

1	`不适合场景：`

✗ 简单一行命令 ✗ 需要灵活调整 ✗ 探索性任务 ✗ 一次性操作

1
2
3

### 脚本组织

**目录结构：**

scripts/ ├── core/ # 核心功能 │ ├── extract.py │ ├── transform.py │ └── export.py ├── utils/ # 工具函数 │ ├── validators.py │ └── formatters.py ├── cli/ # 命令行接口 │ └── main.py └── tests/ # 测试（不打包） ├── test_extract.py └── test_transform.py

### 脚本模板

**Python 脚本模板：**
```python
#!/usr/bin/env python3
"""
[脚本名称]

[简短描述]

使用示例：
    python script_name.py <input> <output> [options]

参数：
    input   - 输入文件路径
    output  - 输出文件路径
    options - 可选参数
"""

import sys
import argparse
from pathlib import Path


def main():
    parser = argparse.ArgumentParser(description='[描述]')
    parser.add_argument('input', help='输入文件')
    parser.add_argument('output', help='输出文件')
    parser.add_argument('--option', default='value', help='选项')

    args = parser.parse_args()

    # 验证输入
    input_path = Path(args.input)
    if not input_path.exists():
        print(f"Error: Input file not found: {input_path}")
        sys.exit(1)

    # 处理
    try:
        result = process(args.input, args.output, args.option)
        print(f"Success: {result}")
    except Exception as e:
        print(f"Error: {e}")
        sys.exit(1)


def process(input_path, output_path, option):
    """处理函数"""
    # 实现逻辑
    return "处理完成"


if __name__ == '__main__':
    main()

Bash 脚本模板：

#!/bin/bash
#
# [脚本名称]
#
# [简短描述]
#
# 使用示例：
#   ./script_name.sh <input> <output>
#

set -e  # 遇到错误立即退出

# 参数检查
if [ $# -lt 2 ]; then
    echo "Usage: $0 <input> <output>"
    exit 1
fi

INPUT="$1"
OUTPUT="$2"

# 验证输入
if [ ! -f "$INPUT" ]; then
    echo "Error: Input file not found: $INPUT"
    exit 1
fi

# 处理
echo "Processing $INPUT..."
# 处理命令

echo "Success: Output written to $OUTPUT"

脚本文档¶

在 SKILL.md 中说明：

### 可用脚本

#### extract_text.py

提取 PDF 文本内容。

**用法：**
```bash
python scripts/extract_text.py <input.pdf> <output.txt>

参数： - input.pdf - 输入 PDF 文件 - output.txt - 输出文本文件 - --page 1 - 指定页码（可选）

示例：

python scripts/extract_text.py document.pdf output.txt --page 1

### 脚本测试

**测试文件：**
```python
# tests/test_script.py
import unittest
from scripts.extract import process

class TestExtract(unittest.TestCase):

    def test_basic_extraction(self):
        """测试基本提取功能"""
        result = process('fixtures/sample.pdf', 'output.txt')
        self.assertTrue(result)

    def test_large_file(self):
        """测试大文件处理"""
        result = process('fixtures/large.pdf', 'output.txt')
        self.assertLess(process_time, 30)  # 30 秒内完成

    def test_encrypted_file(self):
        """测试加密文件处理"""
        with self.assertRaises(Exception):
            process('fixtures/encrypted.pdf', 'output.txt')

if __name__ == '__main__':
    unittest.main()

运行测试：

# 运行所有测试
python -m pytest tests/

# 运行单个测试
python -m pytest tests/test_script.py::TestClass::test_method

# 带覆盖率
python -m pytest --cov=scripts tests/

参考文档设计¶

何时使用参考文档¶

适合场景：

✓ 详细 API 文档
✓ 复杂教程
✓ 大量示例
✓ 背景知识
✓ 故障排查指南

组织原则：

✓ SKILL.md 保持简洁
✓ 详细内容放入 references/
✓ 使用清晰链接
✓ 避免信息重复

文档类型¶

类型 1：API 参考

# API 参考

## 函数列表

### function_name(params)

**描述：** [功能描述]

**参数：**
- `param1` (类型): 说明
- `param2` (类型): 说明

**返回值：** 类型和说明

**示例：**
```python
result = function_name(arg1, arg2)

错误处理： 可能的异常和解决方案

**类型 2：教程**
```markdown
# 教程：[主题]

## 前提条件

- [ ] 安装 X
- [ ] 配置 Y
- [ ] 准备 Z

## 步骤 1：[步骤名称]

详细说明...

## 步骤 2：[步骤名称]

详细说明...

## 验证

如何确认完成...

## 下一步

- [进阶主题](advanced.md)
- [相关教程](related.md)

类型 3：最佳实践

# 最佳实践

## 原则

1. [原则 1]
2. [原则 2]
3. [原则 3]

## 推荐模式

### 模式 1

```python
# 推荐做法

模式 2¶

# 推荐做法

避免的模式¶

❌ 不要这样做¶

# 反模式

✅ 应该这样做¶

# 正确做法

**类型 4：故障排查**
```markdown
# 故障排查

## 常见问题

### 问题 1

**症状：** ...
**原因：** ...
**解决：** ...

### 问题 2

**症状：** ...
**原因：** ...
**解决：** ...

## 诊断流程

开始 ↓ 检查 A ├─ 通过 → 检查 B └─ 失败 → 解决方案 A

## 获取帮助

如果以上方法无效：
1. 查看日志：`tail -f logs/app.log`
2. 搜索 Issues：[GitHub Issues 链接]
3. 提问：[社区链接]

文档结构¶

长文档结构（>100 行）：

# [文档标题]

## 目录

1. [概述](#概述)
2. [快速开始](#快速开始)
3. [详细说明](#详细说明)
4. [示例](#示例)
5. [故障排查](#故障排查)

---

## 概述

...

## 快速开始

...

短文档结构：

1
2
3

# [文档标题]

[直接开始内容]

链接规范¶

相对路径：

# 在 SKILL.md 中

✅ 正确：
- [API 参考](references/api.md)
- [示例](references/examples.md)
- [脚本](scripts/process.py)

❌ 错误：
- [API 参考](./references/api.md)  # 不需要 ./
- [API 参考](../references/api.md)  # 不要跳出 skill 目录
- [API 参考](/references/api.md)   # 不要用绝对路径

跨文档链接：

# 在 references/ 内的文档中

✅ 正确：
- [相关文档](./other-doc.md)  # 同目录
- [上级文档](../SKILL.md)     # 返回 SKILL.md
- [脚本](../scripts/script.py)

❌ 错误：
- [脚本](scripts/script.py)   # 缺少 ../

资产文件设计¶

何时使用资产¶

适合场景：

✓ 模板文件（文档、代码、配置）
✓ 示例数据
✓ 图片/图标/Logo
✓ 字体文件
✓ 预配置项目

不适合：

1
2
3

✗ 会频繁修改的内容
✗ 需要加载到上下文的内容
✗ 纯文本内容（应放在 references/）

资产类型¶

类型 1：文档模板

assets/templates/
├── report.docx           # 报告模板
├── invoice.docx          # 发票模板
├── contract.md           # 合同模板
└── presentation.pptx     # 演示模板

在 SKILL.md 中说明：

## 可用模板

### 报告模板

位置：`assets/templates/report.docx`

使用方法：
1. 复制模板：`cp assets/templates/report.docx output.docx`
2. 编辑内容
3. 保存

类型 2：代码模板

assets/templates/
├── python-package/       # Python 项目模板
│   ├── setup.py
│   ├── README.md
│   └── src/
├── react-app/           # React 项目模板
│   ├── package.json
│   ├── src/
│   └── public/
└── docker-compose.yml   # Docker 模板

类型 3：配置文件

assets/configs/
├── default.yaml          # 默认配置
├── production.yaml       # 生产配置
└── development.yaml      # 开发配置

类型 4：示例数据

assets/samples/
├── sample-input.csv      # 示例输入
├── sample-output.json    # 示例输出
└── test-data/            # 测试数据

资产使用模式¶

模式 1：复制 - 修改

## 使用模板

1. 复制模板：
```bash
cp assets/templates/report.docx my-report.docx

修改内容： [编辑说明]

验证： [验证步骤]

**模式 2：作为参考**
```markdown
## 参考示例

查看 `assets/samples/sample-output.json` 了解预期输出格式。

模式 3：程序化使用

## 自动化使用

脚本会自动使用 `assets/configs/default.yaml` 作为默认配置。

自定义配置：
```bash
python script.py --config assets/configs/custom.yaml

---

## 文件命名规范

### 通用规则

✓ 使用小写字母 ✓ 使用连字符分隔单词 ✓ 有意义的描述性名称 ✓ 包含文件类型后缀

✗ 避免大写字母 ✗ 避免空格（用连字符） ✗ 避免下划线（用连字符） ✗ 避免模糊名称

### 命名示例

| ❌ 错误 | ✅ 正确 | 说明 |
|--------|--------|------|
| `ExtractText.py` | `extract_text.py` | 小写 |
| `extract_text.py` | `extract-text.py` | 连字符（脚本可用下划线） |
| `api.md` | `api-reference.md` | 描述性 |
| `doc1.md` | `troubleshooting.md` | 有意义 |
| `test.py` | `test_extract.py` | 说明测试内容 |

### 各目录命名规范

**scripts/：**

{action}-{target}.{ext}

示例： - extract-text.py - rotate-pdf.py - merge-files.sh - validate-input.py

1	`references/：`

{topic}.{ext} 或 {topic}-{subtopic}.{ext}

示例： - api-reference.md - best-practices.md - troubleshooting.md - examples-advanced.md

1	`assets/：`

{type}-{name}.{ext}

示例： - template-report.docx - config-default.yaml - sample-input.csv - logo-company.png

1
2
3

### 版本控制

**不推荐在文件名中包含版本：**

❌ api-reference-v1.md ❌ api-reference-v2.md ❌ api-reference-2026.md

**推荐：**

✅ api-reference.md # 更新文件本身 ✅ 在文件内记录版本历史

**版本历史记录：**
```markdown
## 版本历史

### v1.1.0 (2026-03-26)
- 新增：XXX 功能
- 改进：YYY 性能

### v1.0.0 (2026-03-20)
- 初始版本

完整案例¶

案例：GitHub Issues Skill¶

目录结构：

gh-issues/
├── SKILL.md
├── scripts/
│   ├── create-issue.py
│   ├── search-issues.py
│   ├── update-issue.py
│   └── close-issue.py
├── references/
│   ├── api-reference.md
│   ├── labels-guide.md
│   └── templates.md
└── assets/
    └── templates/
        ├── bug-report.md
        └── feature-request.md

SKILL.md 内容：

---
name: gh-issues
description: |
  GitHub Issues 管理：创建、搜索、更新、关闭 Issue。
  当用户需要：
  (1) 创建新的 Issue 报告 Bug 或功能请求，
  (2) 搜索和筛选 Issues，
  (3) 更新 Issue 状态、标签、分配负责人，
  (4) 关闭或重新打开 Issue 时使用
---

# GitHub Issues Skill

管理 GitHub Issues 的完整工作流。

## 快速开始

### 创建 Issue

```bash
python scripts/create-issue.py \
  --repo owner/repo \
  --title "Bug: XXX" \
  --body "描述..." \
  --labels bug,critical

搜索 Issue¶

python scripts/search-issues.py \
  --repo owner/repo \
  --query "is:open is:bug"

核心功能¶

创建 Issue¶

使用 create-issue.py 创建新 Issue。

基本用法：

python scripts/create-issue.py --repo <owner/repo> --title "<标题>" --body "<描述>"

带标签和分配：

python scripts/create-issue.py \
  --repo owner/repo \
  --title "Feature: XXX" \
  --body "详细描述" \
  --labels enhancement \
  --assignee username

使用模板：

python scripts/create-issue.py \
  --repo owner/repo \
  --template assets/templates/bug-report.md \
  --title "Bug: XXX"

搜索 Issue¶

使用 search-issues.py 搜索 Issues。

基本搜索：

python scripts/search-issues.py --repo owner/repo --query "is:open"

高级搜索：

python scripts/search-issues.py \
  --repo owner/repo \
  --query "is:open label:bug priority:high" \
  --sort created \
  --order desc

更新 Issue¶

使用 update-issue.py 更新现有 Issue。

python scripts/update-issue.py \
  --repo owner/repo \
  --number 123 \
  --state open \
  --labels bug,critical \
  --assignee username

关闭 Issue¶

使用 close-issue.py 关闭 Issue。

python scripts/close-issue.py \
  --repo owner/repo \
  --number 123 \
  --comment "已修复，关闭"

高级用法¶

批量操作¶

批量处理多个 Issue，见批量操作指南

自定义标签¶

管理项目标签，见标签指南

Issue 模板¶

使用预定义模板，见模板参考

限制与注意事项¶

权限要求¶

需要 GitHub Token
创建/更新需要写权限
只读操作只需读权限

API 限制¶

每小时 5000 次请求（认证用户）
搜索查询有限制

故障排查¶

认证失败¶

症状： 401 Unauthorized 原因： Token 无效或过期 解决： 重新生成 GitHub Token

权限不足¶

症状： 403 Forbidden 原因： Token 权限不足 解决： 确保 Token 有 repo 权限

本章总结¶

核心要点¶

标准结构：
SKILL.md（必需）
scripts/（可选）
references/（可选）
assets/（可选）
YAML 元数据：
name: 小写、连字符、<64 字符
description: 功能 + 触发场景
SKILL.md 结构：
快速开始
核心功能
高级用法（链接）
限制与注意
故障排查
相关资源
资源设计：
脚本：可执行代码
参考：详细文档
资产：模板素材
命名规范：
小写、连字符
描述性名称

检查清单¶

创建 Skill 时检查：

□ name 符合规范（小写、连字符、<64 字符）
□ description 包含功能和触发场景
□ SKILL.md 结构完整
□ SKILL.md < 500 行
□ 脚本有文档说明
□ 参考文档组织清晰
□ 资产文件有用途说明
□ 所有链接正确
□ 通过 package_skill.py 验证

下一步¶

📖 阅读第 3 章：学习优秀案例
💻 实践：完成本章练习
🔨 动手：创建第一个完整 Skill

第 2 章完
下一章：第 3 章：经典 Skill 案例解析

第 2 章：Skill 结构设计指南¶

📖 目录¶

Skill 标准结构¶

完整目录结构¶

各部分作用¶

最小可行 Skill¶

复杂 Skill 示例¶

YAML 元数据详解¶

基本结构¶

name 字段规范¶

description 字段规范¶

完整元数据示例¶

常见错误¶

SKILL.md 编写规范¶

标准结构¶

各章节详解¶

1. 标题和介绍¶

2. 快速开始¶

典型工作流¶

编辑操作¶

格式转换¶

4. 高级用法¶

5. 限制与注意事项¶

6. 故障排查¶

7. 相关资源¶

写作风格¶

脚本文档¶

参考文档设计¶

何时使用参考文档¶

文档类型¶

模式 2¶

避免的模式¶

❌ 不要这样做¶

✅ 应该这样做¶

文档结构¶

链接规范¶

资产文件设计¶

何时使用资产¶

资产类型¶

资产使用模式¶

完整案例¶

案例：GitHub Issues Skill¶

搜索 Issue¶

核心功能¶

创建 Issue¶

搜索 Issue¶

更新 Issue¶

关闭 Issue¶

高级用法¶

批量操作¶

自定义标签¶

Issue 模板¶

限制与注意事项¶

权限要求¶

API 限制¶

故障排查¶

认证失败¶

权限不足¶

相关资源¶

脚本¶

参考文档¶

模板¶

练习 2：编写元数据¶

练习 3：编写 SKILL.md 大纲¶

练习 4：设计脚本接口¶

script2.py¶

本章总结¶

核心要点¶

检查清单¶

下一步¶