skill-name/
├── SKILL.md          # 必需：指令 + 元数据
├── scripts/          # 可选：可执行代码
├── references/       # 可选：文档
└── assets/           # 可选：模板、资源

---
name: skill-name
description: A description of what this skill does and when to use it.
---

name: pdf-processing
name: data-analysis
name: code-review

name: PDF-Processing    # ❌ 大写字母
name: -pdf              # ❌ 以连字符开头
name: pdf--processing   # ❌ 连续连字符

description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.

description: 从 PDF 文件中提取文本和表格、填充 PDF 表单、合并多个 PDF 文档。当用户处理 PDF 文档或提及 PDF、表单、文档提取时使用。

description: Helps with PDFs.    # ❌ 太模糊
description: 帮助处理 PDF。      # ❌ 太模糊

---
name: pdf-processing
description: Extract text and tables from PDF files...
license: Apache-2.0
compatibility: Requires Python 3.10+, pdfplumber package
metadata:
  author: example-org
  version: "1.0"
---

# [Skill 名称]

> 版本: x.x | 更新: YYYY-MM-DD

## 概述
简要描述技能的用途和目标。

## 使用场景
说明何时激活此技能。

## 操作步骤
1. 步骤一
2. 步骤二
3. 步骤三

## 示例
### 输入示例

### 输出示例

## 边缘情况
列出常见问题和处理方式。

## 参考
引用相关文档或资源。

# ✅ 好的描述（英文）：具体、包含触发词
description: Review code for security vulnerabilities including SQL injection, XSS, and CSRF. Use when user asks for security audit, vulnerability scan, or security review.

# ✅ 好的描述（中文）：具体、包含触发词
description: 审查代码安全漏洞，包括 SQL 注入、XSS 和 CSRF。当用户要求安全审计、漏洞扫描或安全审查时使用。

# ❌ 差的描述：模糊、无触发词
description: Helps with code security.
description: 帮助处理代码安全。

See [the reference guide](references/REFERENCE.md) for details.

Run the extraction script:
```bash
scripts/extract.py

保持引用层级不超过一级（从 SKILL.md 到直接引用的文件）。

---

## 可选目录使用

### scripts/ - 可执行代码

包含 agent 可以运行的脚本：

| 要求 | 说明 |
|------|------|
| 自包含 | 或清晰文档化依赖 |
| 错误处理 | 包含有用的错误消息 |
| 边缘情况 | 优雅处理边界情况 |

支持的语言取决于 agent 实现，常见选项：Python、Bash、JavaScript。

### references/ - 额外文档

| 文件 | 用途 |
|------|------|
| `REFERENCE.md` | 详细技术参考 |
| `FORMS.md` | 表单模板或结构化数据格式 |
| 领域文件 | 如 `finance.md`, `legal.md` 等 |

保持单个参考文件聚焦，agent 按需加载。

### assets/ - 静态资源

| 类型 | 示例 |
|------|------|
| 模板 | 文档模板、配置模板 |
| 图片 | 图表、示例图 |
| 数据 | 查找表、schema |

---

## 常见模式

### 模式 1：编码规范 Skill

```markdown
---
name: java-spring-guidelines
description: Java and Spring Boot coding standards and best practices. Use when writing Java code, Spring Boot controllers, services, or mappers.
---

# Java/Spring Boot 编码规范

## 命名约定
### 类命名
| 类型 | 规则 | 示例 |
|-----|------|-----|
| Controller | `*Controller` | `ProductController` |
| Service 接口 | `I*Service` | `IProductService` |
...

---
name: git-workflow
description: Git workflow automation for branch management, commit creation, and pull requests. Use when user needs to create branches, commit code, or manage PRs.
---

## Git 工作流

### 创建分支
1. 从 main 分支创建功能分支
2. 使用命名约定：`feature/issue-description`
...

---
name: api-integration
description: Integration guide for external APIs including authentication, rate limiting, and error handling. Use when building API clients or integrating third-party services.
---

## API 集成指南

### 认证方式
- OAuth 2.0
- API Key
- JWT Bearer Token
...

skills-ref validate ./my-skill

# 前：模糊（英文）
description: Helps with database queries.

# 后：具体（英文）
description: Write efficient SQL queries, optimize database performance, and handle N+1 problems. Use when user mentions database, SQL, query optimization, or performance issues.

# 前：模糊（中文）
description: 帮助处理数据库查询。

# 后：具体（中文）
description: 编写高效的 SQL 查询、优化数据库性能、处理 N+1 问题。当用户提及数据库、SQL、查询优化或性能问题时使用。

description: PDF 文档处理：提取文本、填充表单、合并文档。Extract text, fill forms, merge PDF documents. 当用户提及 PDF/文档处理 或 mentions PDF/documents 时使用。

When working on Java/Spring code, you MUST consult the java-spring-guidelines skill FIRST before making any changes.

---
name: code-review-checklist
description: Code review checklist covering security, performance, and best practices. Use when user asks for code review, PR review, or quality checks.
metadata:
  author: dev-team
  version: "1.0"
---

# Code Review Checklist

> 版本: 1.0 | 更新: 2026-01-28

## 安全检查

- [ ] 无 SQL 注入风险（使用参数化查询）
- [ ] 无 XSS 漏洞（输入验证和输出编码）
- [ ] 敏感数据已脱敏
- [ ] 认证授权正确实现

## 何时使用

When user asks for:
- Code review / PR review
- Quality check / 代码审查
- Security audit / 安全审计

---
name: java-spring-guidelines
description: Java 和 Spring Boot 编码规范最佳实践。包括命名约定、依赖注入、日志规范、异常处理、Controller/Service/Mapper 层规范、缓存、事务控制、数据库设计等。当编写 Java 代码、Spring Boot 控制器、服务层或映射器时使用。
metadata:
  author: dev-team
  version: "1.0"
---

# Java/Spring Boot 编码规范

> 版本: 1.0 | 更新: 2026-01-28

## 命名约定

### 类命名
| 类型 | 规则 | 示例 |
|-----|------|-----|
| Controller | `*Controller` | `ProductController` |
| Service 接口 | `I*Service` | `IProductService` |
| Service 实现 | `*ServiceImpl` | `ProductServiceImpl` |
| Mapper | `*Mapper` | `ProductMapper` |

## 何时使用

当用户进行以下操作时激活此技能：
- 编写 Java / Spring Boot 代码
- 创建 Controller / Service / Mapper
- 提问：如何命名、怎么写日志、异常怎么处理
- 要求：代码规范、最佳实践