create-skill

在 Cursor 中创建 Skills

本技能将指导你为 Cursor 创建高效的 Agent Skills。Skill 是用于教会 Agent 如何执行特定任务的 Markdown 文件，例如按照团队标准审查 PR、按首选格式生成提交消息、查询数据库架构，或处理任何专门的工作流。

开始之前：收集需求

创建 Skill 之前，请向用户收集以下关键信息：

1. 用途和范围：此 Skill 应帮助完成哪项具体任务或工作流？
2. 目标位置：应创建个人 Skill（~/.cursor/skills/）还是项目 Skill（.cursor/skills/）？
3. 触发场景：Agent 应在什么情况下自动应用此 Skill？
4. 关键领域知识：Agent 需要哪些它原本并不了解的专业信息？
5. 输出格式偏好：是否需要遵循特定模板、格式或风格？
6. 现有范例：是否有可供参考的现有范例或惯例？

根据上下文推断

如果有先前的对话上下文，请根据讨论内容推断 Skill。你可以根据对话中出现的工作流、模式或领域知识创建 Skill。

收集更多信息

如果需要澄清，请在可用时使用 AskQuestion 工具：

Example AskQuestion usage:
- "Where should this skill be stored?" with options like ["Personal (~/.cursor/skills/)", "Project (.cursor/skills/)"]
- "Should this skill include executable scripts?" with options like ["Yes", "No"]

如果 AskQuestion 工具不可用，请通过对话询问这些问题。

---

Skill 文件结构

目录布局

Skill 以目录形式存储，其中包含一个 SKILL.md 文件：

skill-name/
├── SKILL.md              # Required - main instructions
├── reference.md          # Optional - detailed documentation
├── examples.md           # Optional - usage examples
└── scripts/              # Optional - utility scripts
    ├── validate.py
    └── helper.sh

存储位置

类型	路径	范围
个人	~/.cursor/skills/skill-name/	可用于你的所有项目
项目	.cursor/skills/skill-name/	与所有使用此代码库的人共享

重要：切勿在 ~/.cursor/skills-cursor/ 中创建 Skill。此目录专用于 Cursor 内置的内部 Skill，由系统自动管理。

SKILL.md 结构

每个 Skill 都需要一个包含 YAML 前置内容和 Markdown 正文的 SKILL.md 文件：

---
name: your-skill-name
description: Brief description of what this skill does and when to use it
---

# Your Skill Name

## Instructions
Clear, step-by-step guidance for the agent.

## Examples
Concrete examples of using this skill.

必需的元数据字段

字段	要求	用途
name	最多 64 个字符，只能包含小写字母、数字和连字符	Skill 的唯一标识符
description	最多 1024 个字符，不得为空	帮助 Agent 判断何时应用此 Skill

---

编写有效的描述

描述对于发现 Skill 至关重要。Agent 会根据描述判断何时应用你的 Skill。

描述最佳实践

1. 使用第三人称（描述会注入系统提示词）：

   • ✅ 推荐："处理 Excel 文件并生成报告"
   • ❌ 避免："我可以帮你处理 Excel 文件"
   • ❌ 避免："你可以用它来处理 Excel 文件"

2. 具体描述并包含触发词：

   • ✅ 推荐："从 PDF 文件中提取文本和表格、填写表单、合并文档。在处理 PDF 文件或用户提到 PDF、表单或文档提取时使用。"
   • ❌ 太笼统："帮助处理文档"

3. 同时说明做什么和何时使用：

   • 做什么：Skill 能做什么（具体能力）
   • 何时使用：Agent 应在什么情况下使用它（触发场景）

描述示例

# PDF Processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

# Excel Analysis
description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.

# Git Commit Helper
description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.

# Code Review
description: Review code for quality, security, and best practices following team standards. Use when reviewing pull requests, code changes, or when the user asks for a code review.

---

核心编写原则

1. 简洁是关键

上下文窗口由对话历史、其他技能和请求共享。每个 token 都在争夺空间。

默认假设：Agent 已经很聪明。只添加它尚不了解的上下文。

审视每条信息：

• “Agent 真的需要这段说明吗？”
• “可以假设 Agent 已经知道这点吗？”
• “这段内容值得占用这么多 token 吗？”

好（简洁）：

## Extract PDF text

Use pdfplumber for text extraction:

\`\`\`python
import pdfplumber

with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
\`\`\`

差（冗长）：

## Extract PDF text

PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you'll need to
use a library. There are many libraries available for PDF processing, but we
recommend pdfplumber because it's easy to use and handles most cases well...

2. 将 SKILL.md 控制在 500 行以内

为了获得最佳性能，主 SKILL.md 文件应简洁明了。使用渐进式披露来呈现详细内容。

3. 渐进式披露

将基本信息放在 SKILL.md 中；将详细参考资料放在单独的文件中，只有在需要时才让 Agent 读取。

# PDF Processing

## Quick start
[Essential instructions here]

## Additional resources
- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)

参考资料保持一层深度——从 SKILL.md 直接链接到参考文件。层级过深的引用可能导致内容无法完整读取。

4. 设置恰当的自由度

根据任务的脆弱程度调整具体程度：

自由度	适用场景	示例
高（文本说明）	有多种有效方法，且取决于上下文	代码审查指南
中（伪代码／模板）	有首选模式，但允许适当变化	报告生成
低（具体脚本）	操作脆弱，且一致性至关重要	数据库迁移

---

常见模式

模板模式

提供输出格式模板：

## Report structure

Use this template:

\`\`\`markdown
# [Analysis Title]

## Executive summary
[One-paragraph overview of key findings]

## Key findings
- Finding 1 with supporting data
- Finding 2 with supporting data

## Recommendations
1. Specific actionable recommendation
2. Specific actionable recommendation
\`\`\`

示例模式

适用于输出质量取决于示例的技能：

## Commit message format

**Example 1:**
Input: Added user authentication with JWT tokens
Output:
\`\`\`
feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware
\`\`\`

**Example 2:**
Input: Fixed bug where dates displayed incorrectly
Output:
\`\`\`
fix(reports): correct date formatting in timezone conversion

Use UTC timestamps consistently across report generation
\`\`\`

工作流模式

将复杂操作拆分为清晰的步骤，并配上检查清单：

## Form filling workflow

Copy this checklist and track progress:

\`\`\`
Task Progress:
- [ ] Step 1: Analyze the form
- [ ] Step 2: Create field mapping
- [ ] Step 3: Validate mapping
- [ ] Step 4: Fill the form
- [ ] Step 5: Verify output
\`\`\`

**Step 1: Analyze the form**
Run: \`python scripts/analyze_form.py input.pdf\`
...

条件工作流模式

引导用户逐步完成决策：

## Document modification workflow

1. Determine the modification type:

   **Creating new content?** → Follow "Creation workflow" below
   **Editing existing content?** → Follow "Editing workflow" below

2. Creation workflow:
   - Use docx-js library
   - Build document from scratch
   ...

反馈循环模式

对于质量要求高的任务，实施验证循环：

## Document editing process

1. Make your edits
2. **Validate immediately**: \`python scripts/validate.py output/\`
3. If validation fails:
   - Review the error message
   - Fix the issues
   - Run validation again
4. **Only proceed when validation passes**

---

实用脚本

预制脚本比生成代码更有优势：

• 比生成的代码更可靠
• 节省 token（上下文中无需放入代码）
• 节省时间（无需生成代码）
• 确保每次使用时保持一致

## Utility scripts

**analyze_form.py**: Extract all form fields from PDF
\`\`\`bash
python scripts/analyze_form.py input.pdf > fields.json
\`\`\`

**validate.py**: Check for errors
\`\`\`bash
python scripts/validate.py fields.json
# Returns: "OK" or lists conflicts
\`\`\`

明确说明 Agent 应该执行脚本（最常见），还是将其作为参考来阅读。

---

应避免的反模式

1. Windows 风格的路径

• ✅ 使用：scripts/helper.py
• ❌ 避免：scripts\helper.py

2. 选项过多

# Bad - confusing
"You can use pypdf, or pdfplumber, or PyMuPDF, or..."

# Good - provide a default with escape hatch
"Use pdfplumber for text extraction.
For scanned PDFs requiring OCR, use pdf2image with pytesseract instead."

3. 时效性信息

# Bad - will become outdated
"If you're doing this before August 2025, use the old API."

# Good - use an "old patterns" section
## Current method
Use the v2 API endpoint.

## Old patterns (deprecated)
<details>
<summary>Legacy v1 API</summary>
...
</details>

4. 术语不一致

选择一个术语并始终使用：

• ✅ 始终使用“API endpoint”（不要混用“URL”“route”“path”）
• ✅ 始终使用“field”（不要混用“box”“element”“control”）

5. 技能名称含糊

• ✅ 好：processing-pdfs、analyzing-spreadsheets
• ❌ 避免：helper、utils、tools

---

技能创建工作流

帮助用户创建技能时，请遵循以下流程：

阶段 1：了解需求

收集以下信息：

1. 技能的用途和主要使用场景
2. 存储位置（个人还是项目）
3. 触发场景
4. 任何具体要求或限制
5. 可供参考的现有示例或模式

如果可以使用 AskQuestion 工具，请用它高效、结构化地收集信息。否则，通过对话询问。

阶段 2：设计

1. 起草技能名称（小写、以连字符分隔，最多 64 个字符）
2. 编写具体的第三人称描述
3. 拟定所需的主要章节
4. 确定是否需要支持文件或脚本

阶段 3：实施

1. 创建目录结构
2. 编写带有 frontmatter 的 SKILL.md 文件
3. 创建所需的支持性参考文件
4. 按需创建实用脚本

阶段 4：验证

1. 确认 SKILL.md 不超过 500 行
2. 检查描述是否具体，并包含触发词
3. 确保全文术语一致
4. 确认所有文件引用都只深入一层
5. 测试是否能够发现并应用该技能

---

完整示例

以下是结构良好的技能的完整示例：

目录结构：

code-review/
├── SKILL.md
├── STANDARDS.md
└── examples.md

SKILL.md：

---
name: code-review
description: Review code for quality, security, and maintainability following team standards. Use when reviewing pull requests, examining code changes, or when the user asks for a code review.
---

# Code Review

## Quick Start

When reviewing code:

1. Check for correctness and potential bugs
2. Verify security best practices
3. Assess code readability and maintainability
4. Ensure tests are adequate

## Review Checklist

- [ ] Logic is correct and handles edge cases
- [ ] No security vulnerabilities (SQL injection, XSS, etc.)
- [ ] Code follows project style conventions
- [ ] Functions are appropriately sized and focused
- [ ] Error handling is comprehensive
- [ ] Tests cover the changes

## Providing Feedback

Format feedback as:
- 🔴 **Critical**: Must fix before merge
- 🟡 **Suggestion**: Consider improving
- 🟢 **Nice to have**: Optional enhancement

## Additional Resources

- For detailed coding standards, see [STANDARDS.md](STANDARDS.md)
- For example reviews, see [examples.md](examples.md)

---

总结检查清单

完成技能前，请确认：

核心质量

• 描述具体，并包含关键术语
• 描述同时说明内容和适用时机
• 使用第三人称撰写
• SKILL.md 正文不超过 500 行
• 全文术语一致
• 示例具体，而非抽象

结构

• 文件引用只深入一层
• 适当使用渐进式披露
• 工作流步骤清晰
• 不含时效性信息

如果包含脚本

• 脚本用于解决问题，而不是推卸责任
• 记录所需的软件包
• 明确说明错误处理，且便于理解
• 不使用 Windows 风格的路径