2.2 Skills 基础概念和结构

📚 SKILL.md：一切的核心

每个 Skill 的核心是一个 SKILL.md 文件，它就像 Skill 的"身份证 + 使用手册"。

最小化 Skill 示例

markdown

---
name: hello-skill
description: A simple greeting skill that says hello
---

# Hello Skill

When the user asks for a greeting, respond with "Hello from Hello Skill!"

就这么简单！ 这就是一个完整的 Skill。

🏗️ SKILL.md 结构详解

1. YAML Frontmatter（必需）

yaml

---
name: my-skill-name
description: What this skill does and when to use it
---

name 字段规则

规则	说明	示例
小写字母	只能用小写	✅ `ppt-generator` ❌ `PPT-Generator`
连字符	单词间用 `-`	✅ `pdf-merger` ❌ `pdf_merger`
最大长度	不超过 64 字符	✅ `company-brand-guidelines`
描述性	见名知意	✅ `excel-report` ❌ `tool-1`

description 字段规则

核心要点： 这是 Claude 决定是否使用 Skill 的关键！

markdown

# ❌ 糟糕的描述
description: Helps with documents

# ✅ 优秀的描述
description: Extract text and tables from PDFs, merge multiple PDFs into one. Use when working with PDF files.

优秀描述的公式：

功能说明 + 使用场景 = 好描述

"[做什么]. Use when [什么时候用]."

示例对比：

场景	糟糕描述	优秀描述
PPT 生成	"PowerPoint tool"	"Create branded PowerPoint presentations following company style guide. Use when generating slides or decks."
数据分析	"Data helper"	"Analyze CSV/Excel data, generate charts and summary statistics. Use for data analysis tasks."
PDF 处理	"PDF utility"	"Extract text from PDFs, merge documents, convert to other formats. Use when working with PDF files."

描述长度： 最多 1024 字符，建议 100-200 字符

2. 主体内容（Markdown）

markdown

# Skill Title

## Purpose
What this skill helps with

## Usage
How Claude should use it

## Examples
Concrete examples

## Templates
Reference files if needed

组织建议：

📝 清晰标题 - 用 # ## 分级
📋 列表格式 - 步骤用列表
💡 示例优先 - 具体例子比抽象描述好
🔗 引用文件 - 引用同文件夹中的其他文件

📂 Skill 文件夹结构

基础结构

my-skill/
└── SKILL.md    # 唯一必需文件

完整结构示例

pdf-processor/
├── SKILL.md              # 核心说明文件
├── process.py            # Python 处理脚本
├── merge.py              # PDF 合并脚本
├── templates/            # 模板文件夹
│   ├── output_template.pdf
│   └── watermark.png
├── reference/            # 参考资料
│   ├── pdf_standards.md
│   └── examples.md
└── README.md             # 可选：开发者文档

文件组织原则：

🎯 单一职责 - 一个 Skill 做一件事
📁 清晰分类 - 用子文件夹组织资源
📝 命名规范 - 文件名描述性强
🔗 路径引用 - 在 SKILL.md 中明确引用文件

📍 Skill 存储位置

三种存储位置

1. Personal Skills（个人技能）

bash

~/.claude/skills/
├── my-ppt-skill/
├── my-excel-skill/
└── my-brand-skill/

特点：

✅ 只有你能用
✅ 跨项目可用
✅ 个人定制化
❌ 团队无法访问

使用场景：

个人工作流
实验性 Skills
私人项目

2. Project Skills（项目技能）

bash

your-project/
├── .claude/
│   └── skills/
│       ├── team-ppt-skill/
│       └── project-data-skill/
├── src/
└── README.md

特点：

✅ 团队共享
✅ Git 版本控制
✅ 项目特定
❌ 需要提交到代码仓库

使用场景：

团队协作
项目标准化
公司规范

3. Plugin Skills（插件技能）

bash

# 通过 Claude Code 插件安装
# 插件自动管理 Skills

特点：

✅ 一键安装
✅ 自动更新
✅ 来自社区或官方
❌ 需要审核安全性

使用场景：

通用功能
官方 Skills
社区贡献

🔑 SKILL.md 核心元素详解

元素 1：清晰的指令

markdown

---
name: excel-report-generator
description: Generate Excel reports with charts and pivot tables. Use for data reporting tasks.
---

# Excel Report Generator

## When to Use
Use this skill when the user needs to:
- Create Excel spreadsheets with data
- Generate charts and visualizations
- Build pivot tables for analysis

## Process
1. Ask user for data source (CSV, JSON, or manual input)
2. Load data into pandas DataFrame
3. Create Excel file using openpyxl
4. Add charts based on data type
5. Save with descriptive filename

## Output Format
- File name: `report_YYYY-MM-DD.xlsx`
- First sheet: Raw data
- Second sheet: Charts
- Third sheet: Summary

关键点：

✅ 明确"何时使用"
✅ 详细"操作步骤"
✅ 清晰"输出格式"

元素 2：引用支持文件

markdown

# PDF Processor Skill

## Templates
Use the template files in `templates/` folder:
- `output_template.pdf` - Standard output format
- `watermark.png` - Company watermark

## Scripts
Execute these scripts:
- `merge.py` - Merge multiple PDFs
- `extract.py` - Extract text and tables

## Usage Example
```python
# Run merge script
python merge.py input1.pdf input2.pdf --output merged.pdf


**引用方式：**
- 📁 相对路径：`templates/file.pdf`
- 🐍 脚本调用：`python script.py`
- 📝 示例代码：Markdown 代码块

---

### 元素 3：限制工具使用（安全）

```yaml
---
name: read-only-analyzer
description: Analyze files without modifying them
allowed-tools:
  - Read
  - Grep
  - Glob
---

# Read-Only File Analyzer

This skill can only read files, not write or edit.
Use for safe file analysis and reporting.

allowed-tools 用途：

🔒 安全限制 - 防止意外修改
📖 只读 Skills - 分析、审计类任务
🎯 专注功能 - 限制 Skill 范围

常用工具列表：

yaml

allowed-tools:
  - Read          # 读取文件
  - Write         # 写入文件
  - Edit          # 编辑文件
  - Bash          # 执行命令
  - Grep          # 搜索内容
  - Glob          # 文件查找
  - WebFetch      # 网络请求

🎨 Skill 命名最佳实践

命名模式

模式	示例	适用场景
`{action}-{object}`	`create-ppt`, `analyze-data`	动作导向
`{object}-{action}`	`ppt-creator`, `data-analyzer`	对象导向
`{company}-{function}`	`acme-branding`, `contoso-reports`	公司定制
`{tech}-{purpose}`	`excel-reports`, `pdf-merger`	技术特定

命名检查清单

[ ] 全小写
[ ] 用 - 连接单词
[ ] 64 字符以内
[ ] 描述性强
[ ] 与 description 一致
[ ] 不包含版本号（用 Git 管理版本）

📏 SKILL.md 长度指南

最小 Skill

markdown

---
name: simple-greeter
description: Simple greeting skill
---

Say hello to the user.

行数： 6 行 适用： 超简单任务

标准 Skill

markdown

---
name: pdf-processor
description: Process PDF files
---

# PDF Processor

## Purpose
Extract and merge PDFs

## Usage
1. Read PDF
2. Extract text
3. Merge if needed

## Scripts
- `process.py`

行数： 15-30 行 适用： 大多数场景

复杂 Skill

markdown

---
name: enterprise-reporting
description: Generate enterprise reports with branding
---

# Enterprise Reporting Skill

## Overview
[详细说明...]

## Brand Guidelines
[公司规范...]

## Templates
[10+ 个模板...]

## Process
[20+ 步骤...]

## Examples
[多个示例...]

## Troubleshooting
[常见问题...]

行数： 100+ 行 适用： 复杂企业场景

优化策略： 拆分为多个文件

enterprise-reporting/
├── SKILL.md             # 主文件（简洁）
├── brand-guidelines.md  # 品牌指南
├── templates.md         # 模板说明
└── examples/            # 示例文件夹

🔍 渐进式加载机制

三层信息架构

┌─────────────────────────────────────┐
│ Level 1: Metadata (启动时加载)      │
│ ┌─────────────────────────────────┐ │
│ │ name: pdf-processor             │ │
│ │ description: Process PDFs...    │ │
│ └─────────────────────────────────┘ │
└─────────────────────────────────────┘
          ↓ Claude 判断需要时
┌─────────────────────────────────────┐
│ Level 2: Core Instructions         │
│ ┌─────────────────────────────────┐ │
│ │ SKILL.md 主体内容               │ │
│ │ - Purpose                       │ │
│ │ - Usage steps                   │ │
│ └─────────────────────────────────┘ │
└─────────────────────────────────────┘
          ↓ 执行时按需加载
┌─────────────────────────────────────┐
│ Level 3: Supplementary Resources    │
│ ┌─────────────────────────────────┐ │
│ │ - templates/                    │ │
│ │ - scripts/                      │ │
│ │ - reference.md                  │ │
│ └─────────────────────────────────┘ │
└─────────────────────────────────────┘

好处：

⚡ 快速启动 - Level 1 只有几十字节
💾 节省内存 - 只加载需要的部分
🎯 精准加载 - 避免无关信息

🛠️ 完整 Skill 示例

示例：公司 PPT 模板 Skill

markdown

---
name: acme-powerpoint
description: Create PowerPoint presentations following Acme Corp brand guidelines. Use when generating slides or decks.
allowed-tools:
  - Read
  - Write
  - Bash
---

# Acme PowerPoint Skill

## Purpose
Generate branded PowerPoint presentations that follow Acme Corp style guide.

## Brand Guidelines
- **Colors**:
  - Primary: #1E3A8A (Blue)
  - Accent: #F59E0B (Orange)
- **Fonts**:
  - Headings: Montserrat Bold
  - Body: Open Sans
- **Logo**: Always on top-right corner

## Template
Use `acme_template.pptx` as the base template.

## Process
1. Load template from `templates/acme_template.pptx`
2. Apply brand colors to charts
3. Insert Acme logo on each slide
4. Use approved fonts
5. Follow slide layouts:
   - Title slide: Logo + Title + Subtitle
   - Content slide: Title + Bullet points or charts
   - Closing slide: Contact information

## Script Usage
```python
python generate_ppt.py --title "Q4 Report" --slides 10

Output Format

Filename: ACME_[Title]_YYYY-MM-DD.pptx
Saved to: output/ folder

Examples

See examples/ folder for sample presentations.


**文件结构：**

acme-powerpoint/ ├── SKILL.md ├── generate_ppt.py ├── templates/ │ └── acme_template.pptx └── examples/ ├── q4_report.pptx └── sales_deck.pptx


---

## 📝 核心要点总结

### SKILL.md 必备元素

1. **YAML Frontmatter**
   - `name`：小写、连字符、描述性
   - `description`：功能 + 使用场景

2. **清晰指令**
   - 何时使用
   - 如何操作
   - 输出格式

3. **支持文件引用**
   - 模板
   - 脚本
   - 参考资料

### 组织原则

- 🎯 **单一职责** - 一个 Skill 一个功能
- 📁 **清晰结构** - 文件夹分类明确
- 📝 **渐进加载** - 分层组织内容
- 🔒 **安全限制** - 使用 `allowed-tools`

### 存储位置选择

- **Personal** → 个人使用
- **Project** → 团队共享
- **Plugin** → 通用功能

---

## 🎯 实践检查清单

创建 Skill 前，确认：

- [ ] 确定 Skill 的单一职责
- [ ] 选择合适的存储位置
- [ ] 设计清晰的 name
- [ ] 编写精准的 description
- [ ] 列出详细的使用步骤
- [ ] 准备支持文件（如需要）
- [ ] 考虑安全限制（allowed-tools）

---

**下一步：** [2.3 创建你的第一个 Skill](./2.3-创建你的第一个Skill.md) - 实战创建一个实用 Skill！

2.2 Skills 基础概念和结构 ​

📚 SKILL.md：一切的核心 ​

最小化 Skill 示例 ​

🏗️ SKILL.md 结构详解 ​

1. YAML Frontmatter（必需） ​

name 字段规则 ​

description 字段规则 ​

2. 主体内容（Markdown） ​

📂 Skill 文件夹结构 ​

基础结构 ​

完整结构示例 ​

📍 Skill 存储位置 ​

三种存储位置 ​

1. Personal Skills（个人技能） ​

2. Project Skills（项目技能） ​

3. Plugin Skills（插件技能） ​

🔑 SKILL.md 核心元素详解 ​

元素 1：清晰的指令 ​

元素 2：引用支持文件 ​

🎨 Skill 命名最佳实践 ​

命名模式 ​

命名检查清单 ​

📏 SKILL.md 长度指南 ​

最小 Skill ​

标准 Skill ​

复杂 Skill ​

🔍 渐进式加载机制 ​

三层信息架构 ​

🛠️ 完整 Skill 示例 ​

示例：公司 PPT 模板 Skill ​

Output Format ​

Examples ​

2.2 Skills 基础概念和结构

📚 SKILL.md：一切的核心

最小化 Skill 示例

🏗️ SKILL.md 结构详解

1. YAML Frontmatter（必需）

name 字段规则

description 字段规则

2. 主体内容（Markdown）

📂 Skill 文件夹结构

基础结构

完整结构示例

📍 Skill 存储位置

三种存储位置

1. Personal Skills（个人技能）

2. Project Skills（项目技能）

3. Plugin Skills（插件技能）

🔑 SKILL.md 核心元素详解

元素 1：清晰的指令

元素 2：引用支持文件

🎨 Skill 命名最佳实践

命名模式

命名检查清单

📏 SKILL.md 长度指南

最小 Skill

标准 Skill

复杂 Skill

🔍 渐进式加载机制

三层信息架构

🛠️ 完整 Skill 示例

示例：公司 PPT 模板 Skill

Output Format

Examples