my-skill/
├── SKILL.md          # 必须：指令 + 元数据
├── scripts/          # 可选：可执行脚本
├── references/       # 可选：参考文档
└── assets/           # 可选：模板、资源

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

# 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
...

启动时加载        → 激活时加载         → 按需加载
(~100 tokens)      (< 5000 tokens)       (as needed)
     │                   │                    │
     ▼                   ▼                    ▼
 name + description   SKILL.md 全文      scripts/、references/

---
name: pptx
description: "Presentation creation, editing, and analysis. When Claude needs to work with presentations (.pptx files) for: (1) Creating new presentations, (2) Modifying or editing content, (3) Working with layouts, (4) Adding comments or speaker notes, or any other presentation tasks"
license: Proprietary. LICENSE.txt has complete terms
---

PPTX 操作
    │
    ├── 读取/分析 ──────────────────────────────────────┐
    │   ├── 文本提取 → markitdown                        │
    │   └── 原始 XML → unpack.py                        │
    │                                                    │
    ├── 创建新 PPT（无模板）─────────────────────────────┤
    │   └── html2pptx 工作流                             │
    │       1. 创建 HTML 文件                            │
    │       2. 用 html2pptx.js 转换                      │
    │       3. 生成缩略图验证                            │
    │                                                    │
    ├── 创建新 PPT（有模板）─────────────────────────────┤
    │   └── 模板工作流                                   │
    │       1. 提取模板文本 + 创建缩略图                  │
    │       2. 分析模板，保存 inventory                   │
    │       3. 创建大纲，选择模板                         │
    │       4. rearrange.py 重排页面                     │
    │       5. inventory.py 提取文本                     │
    │       6. 生成替换 JSON                             │
    │       7. replace.py 应用替换                       │
    │                                                    │
    └── 编辑现有 PPT ───────────────────────────────────┘
        └── OOXML 工作流
            1. unpack.py 解包
            2. 编辑 XML
            3. validate.py 验证
            4. pack.py 打包

### Workflow
1. **MANDATORY - READ ENTIRE FILE**: Read [`html2pptx.md`](html2pptx.md) completely...
2. Create an HTML file for each slide with proper dimensions...
3. Create and run a JavaScript file using the [`html2pptx.js`](scripts/html2pptx.js) library...
4. **Visual validation**: Generate thumbnails and inspect for layout issues...

#### Color Palette Selection

**Choosing colors creatively**:
- **Think beyond defaults**: What colors genuinely match this specific topic?
- **Consider multiple angles**: Topic, industry, mood, energy level...

**Example color palettes** (use these to spark creativity):
1. **Classic Blue**: Deep navy (#1C2833), slate gray (#2E4053)...
2. **Teal & Coral**: Teal (#5EA8A7), deep teal (#277884)...

4. **Visual validation**: Generate thumbnails and inspect for layout issues
   - Create thumbnail grid: `python scripts/thumbnail.py output.pptx workspace/thumbnails --cols 4`
   - Read and carefully examine the thumbnail image for:
     - **Text cutoff**: Text being cut off by header bars, shapes, or slide edges
     - **Text overlap**: Text overlapping with other text or shapes
     - **Positioning issues**: Content too close to slide boundaries
   - If issues found, adjust HTML margins/spacing/colors and regenerate
   - Repeat until all slides are visually correct

1. **MANDATORY - READ ENTIRE FILE**: Read [`html2pptx.md`](html2pptx.md) completely from start to finish.

2. **Analyze template and save inventory to a file**:
   * Create and save a template inventory file at `template-inventory.md` containing:
     ```markdown
     # Template Inventory Analysis
     **Total Slides: [count]**
     **IMPORTANT: Slides are 0-indexed (first slide = 0, last slide = count-1)**

     ## [Category Name]
     - Slide 0: [Layout code if available] - Description/purpose
     - Slide 1: [Layout code] - Description/purpose
     ...
     ```

启动时：只加载 name + description（~100 tokens）
激活时：加载完整 SKILL.md（< 5000 tokens 推荐）
执行时：按需加载 scripts/、references/

my-first-skill/
└── SKILL.md

---
name: my-first-skill
description: A simple skill that helps with [specific task].
---

# My First Skill

## When to use
Use this skill when the user needs to...

## How to do it
1. Step one...
2. Step two...

## Example
[Provide a concrete example]

.claude/skills/diagram-render/
├── skill.md              # 指令文档
└── scripts/
    ├── render_diagram.py # 渲染脚本
    └── requirements.txt  # Python 依赖

# Diagram Render Skill

A skill for rendering diagrams from code blocks (PlantUML, Mermaid, Graphviz) to PNG/SVG images.

## When to Use

Use this skill when:
- Any task requires rendering diagrams from code to images
- Processing markdown files that contain diagram code blocks
- Converting PlantUML, Mermaid, or Graphviz scripts to PNG/SVG
- Generating visual documentation from code

## Supported Diagram Types

| Type | Code Block | Description |
|------|------------|-------------|
| PlantUML | \`\`\`plantuml | UML diagrams, mind maps, sequence diagrams |
| Mermaid | \`\`\`mermaid | Flowcharts, sequence diagrams, ER diagrams |
| Graphviz | \`\`\`dot | Directed/undirected graphs |

## Usage

\`\`\`bash
# 使用 uv 运行（推荐，自动处理依赖）
uv run .claude/skills/diagram-render/scripts/render_diagram.py plantuml \
    -i diagram.puml -o output.png

# 从 stdin 读取
echo '@startuml
Alice -> Bob: Hello
@enduml' | uv run render_diagram.py plantuml -o output.png
\`\`\`

# /// script
# requires-python = ">=3.9"
# dependencies = [
#     "requests>=2.28.0",
# ]
# ///

# 1. 提取 PlantUML 代码到临时文件
cat > /tmp/mindmap.puml << 'EOF'
@startmindmap
* Agent Skills
** 是什么
** 怎么用
@endmindmap
EOF

# 2. 调用渲染脚本
uv run .claude/skills/diagram-render/scripts/render_diagram.py plantuml \
    -i /tmp/mindmap.puml \
    -o content/images/agent_skills_mindmap.png \
    -v

# 3. 在文章中引用
# ![思维导图](../images/agent_skills_mindmap.png)

# 安装一个 skill 到所有支持的 agent
npx ai-agent-skills install frontend-design

# 只安装到 Cursor
npx ai-agent-skills install frontend-design --agent cursor

# 交互式浏览可用的 skills
npx ai-agent-skills browse

# 从 GitHub 仓库安装
npx ai-agent-skills install anthropics/skills/pdf

npx ai-agent-skills install diagram-render

@startmindmap
<style>
mindmapDiagram {
  .root {
    BackgroundColor #2C3E50
    FontColor white
    FontSize 16
  }
  .what {
    BackgroundColor #3498DB
    FontColor white
  }
  .structure {
    BackgroundColor #27AE60
    FontColor white
  }
  .principle {
    BackgroundColor #9B59B6
    FontColor white
  }
  .example {
    BackgroundColor #E74C3C
    FontColor white
  }
  .action {
    BackgroundColor #F39C12
    FontColor white
  }
}
</style>

*[#2C3E50] Agent Skills\n给 AI 装上技能包 <<root>>

left side

**[#3498DB] 是什么 <<what>>
*** 一个文件夹
****_ SKILL.md（必须）
****_ scripts/（可选）
****_ references/（可选）
****_ assets/（可选）
*** 开放标准
****_ Anthropic 发起
****_ 多产品支持
****_ GitHub 开源

**[#27AE60] 文件结构 <<structure>>
*** YAML Frontmatter
****_ name（必须）
****_ description（必须）
****_ license、metadata（可选）
*** Markdown Body
****_ 指令和说明
****_ 无格式限制
*** 渐进式加载
****_ 启动：name + description
****_ 激活：SKILL.md 全文
****_ 执行：按需加载资源

right side

**[#9B59B6] 设计原则 <<principle>>
*** 渐进式披露
****_ 控制 context 使用
****_ 主文件 < 500 行
*** 自文档化
****_ 人类可读
****_ 易于审计
*** 可移植性
****_ Git 版本控制
****_ 跨产品复用

**[#E74C3C] PPTX 案例 <<example>>
*** 多工作流设计
****_ 读取/分析
****_ 创建（无模板）
****_ 创建（有模板）
****_ 编辑
*** 设计亮点
****_ 分步骤指令
****_ 验证循环
****_ 中间产物模式

**[#F39C12] 行动建议 <<action>>
***_ 1. 从最小 Skill 开始
***_ 2. 用 skills-ref 验证
***_ 3. 参考官方示例
***_ 4. 在团队内分享复用
@endmindmap