Claude Skills主文件编写技巧分析

基于的技巧总结，将md文件翻译成了中文以便更好理解。

zss偶然之见

810人浏览 · 2026-01-12 23:30:44

zss偶然之见 · 2026-01-12 23:30:44 发布

基于 skills/pptx/SKILL.md 的技巧总结，将md文件翻译成了中文以便更好理解。

1. YAML 前置元数据 (Frontmatter)

文件开头使用 YAML 定义技能的基本信息，便于 Claude Code 自动识别和索引。

---
name: pptx
description: "演示文稿创建、编辑和分析。当 Claude 需要处理演示文稿时使用..."
license: Proprietary. LICENSE.txt has complete terms
---

技巧要点：

name：简洁的技能标识符
description：完整说明使用场景，避免误用
license：明确版权声明

2. 强制阅读机制 (Critical Pattern)

使用「强制 + 警告」双重强调，确保 Claude 不会跳过重要文档。

**强制 - 阅读整个文件**：完全从头到尾阅读 [`html2pptx.md`](html2pptx.md)。
**永远不要在阅读此文件时设置任何范围限制。**

技巧要点：

使用「强制」关键词引起重视
明确禁止范围限制（"永远不要"）
提供具体文档链接

3. 分层的指令结构

使用 Markdown 标题形成清晰的导航层级：

# PPTX 创建、编辑和分析

## 概述

## 读取和分析内容

### 文本提取

### 原始 XML 访问

层级规范：

层级	用途	示例
`#`	技能名称/主标题	`# PPTX 创建、编辑和分析`
`##`	主要章节	`## 概述`、`## 工作流程`
`###`	子章节	`### 文本提取`、`### 原始 XML 访问`
`####`	更细的分类（谨慎使用）

4. 约束条件明确化

用勾选符号和粗体强调关键要求，便于快速扫描。

**要求：**
- ✅ 在编写代码之前陈述你的内容知情的设计方法
- ✅ 只使用 Web 安全字体：Arial、Helvetica、Times New Roman...
- ✅ 通过大小、权重和颜色创建清晰的视觉层次
- ✅ 确保可读性：强对比度、适当大小的文本、干净的排列
- ✅ 保持一致：跨幻灯片重复模式、间距和视觉语言

技巧要点：

使用 ✅ 符号增加视觉吸引力
约束条件按重要性排序
每个要求简洁明确

5. 丰富的示例库

提供具体、可直接使用的示例选项。

5.1 配色方案示例

**调色板示例**（用这些激发创造力 - 选择一个、调整或创建你自己的）：

1. **经典蓝色**：深海军蓝（#1C2833）、板岩灰色（#2E4053）、银色（#AAB7B8）、灰白色（#F4F6F6）
2. **蓝绿色和珊瑚色**：蓝绿色（#5EA8A7）、深蓝绿色（#277884）、珊瑚色（#FE4447）、白色（#FFFFFF）
3. **大胆红色**：红色（#C0392B）、亮红色（#E74C3C）、橙色（#F39C12）...

5.2 视觉细节选项

**几何图案：**
- 对角线部分分隔符而不是水平的
- 不对称列宽（30/70、40/60、25/75）
- 旋转文本标题 90° 或 270°
- 图像的圆形/六边形框架

技巧要点：

提供具体数值（如颜色代码、比例）
按类别分组
鼓励创造性调整（"选择一个、调整或创建你自己的"）

6. 命令与代码块分离

每个命令都有注释说明用途，降低使用门槛。

# 将文档转换为 markdown
python -m markitdown path-to-file.pptx

# 解包演示文稿
python ooxml/scripts/unpack.py <office_file> <output_dir>

# 创建缩略图网格
python scripts/thumbnail.py template.pptx

技巧要点：

使用 # 注释解释命令用途
用 <> 表示可变参数
保持命令格式一致

7. 错误处理前置

预先展示可能的错误，帮助用户预防问题。

示例验证错误：

错误：替换 JSON 中的无效形状：

在 'slide-0' 上找不到 'shape-99'。可用形状：shape-0、shape-1、shape-4
清单中找不到 'slide-999' 幻灯片

错误：替换文本使这些形状中的溢出变得更糟：

slide-0/shape-2：溢出变得更糟 1.25"（原来是 0.00"，现在是 1.25"）

技巧要点：

展示真实错误信息
包含解决方案提示（如"可用形状"列表）
按严重程度分组

8. JSON Schema 嵌入式说明

通过实际 JSON 示例说明数据结构，比纯文字描述更直观。

{
  "slide-0": {
    "shape-0": {
      "placeholder_type": "TITLE",
      "left": 1.5,
      "top": 2.0,
      "width": 7.5,
      "height": 1.2,
      "paragraphs": [
        {
          "text": "段落文本",
          "bullet": true,
          "level": 0,
          "alignment": "CENTER",
          "font_name": "Arial",
          "font_size": 14.0
        }
      ]
    }
  }
}

技巧要点：

包含完整字段和示例值
关键字段加注释说明
展示嵌套结构

9. 工具依赖项清单

明确列出所需工具，便于环境配置。

**依赖项**

必需的依赖项（应该已经安装）：

- **markitdown**：`pip install "markitdown[pptx]"`（用于从演示文稿提取文本）
- **pptxgenjs**：`npm install -g pptxgenjs`（用于通过 html2pptx 创建演示文稿）
- **playwright**：`npm install -g playwright`（用于 html2pptx 中的 HTML 渲染）
- **react-icons**：`npm install -g react-icons react react-dom`（用于图标）
- **sharp**：`npm install -g sharp`（用于 SVG 光栅化和图像处理）

技巧要点：

按功能分组
提供完整的安装命令
简要说明每个工具的用途

10. 跨文件交叉引用

使用相对路径和锚点链接，将多个相关文档串联成知识网络。

1. **强制 - 阅读整个文件**：完全从头到尾阅读 [`html2pptx.md`](html2pptx.md)。
2. 参阅[创建缩略图网格](#creating-thumbnail-grids)部分了解更多详情
3. 阅读 `template-content.md`：阅读整个文件以理解模板演示文稿的内容

引用类型：

类型	语法	用途
文件链接	`[html2pptx.md](html2pptx.md)`	引用同目录其他文件
锚点链接	`[创建缩略图网格](#creating-thumbnail-grids)`	引用本文档内章节
代码引用	`scripts/rearrange.py`	引用脚本工具

11. 零索引警告

对容易出错的技术细节进行特别强调。

**重要：幻灯片是 0 索引的（第一张幻灯片 = 0，最后一张幻灯片 = 计数-1）**

# 映射：大纲中的幻灯片号 -> 模板幻灯片索引
template_mapping = [
    0,   # 使用幻灯片 0（标题/封面）
    34,  # 使用幻灯片 34（B1：标题和正文）
    50,  # 使用幻灯片 50（E1：引号）
]

12. 工作流程编号

对多步骤任务进行编号，确保执行顺序正确。

### 工作流程

1. **强制 - 阅读整个文件**：...
2. 解包演示文稿：`python ooxml/scripts/unpack.py <office_file> <output_dir>`
3. 编辑 XML 文件（主要是 `ppt/slides/slide{N}.xml` 和相关文件）
4. **关键**：每次编辑后立即验证并修复任何验证错误...
5. 打包最终演示文稿：`python ooxml/scripts/pack.py <input_directory> <office_file>`

13. 交互式示例展示

展示用户可能执行的命令和预期输出。

# 基本用法
python scripts/thumbnail.py presentation.pptx

# 组合选项：自定义名称、列
python scripts/thumbnail.py template.pptx analysis --cols 4

# 特定范围的 PDF 转换
pdftoppm -jpeg -r 150 -f 2 -l 5 template.pdf slide  # 只转换第 2-5 页