create-skill

在 Cursor 中创建 Skills

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

开始之前：收集需求

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

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

用户提供的原文

如果用户提供了要在 skill 中使用的确切措辞，请尊重并在 SKILL.md 中逐字使用（词语相同、顺序相同）。不要改述、弱化或扩展其内容，也不要在其周围添加未要求的标题或说明。

根据上下文推断

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

收集其他信息

如果需要澄清，请在可用时使用 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 文件结构

目录布局

Skills 以目录形式存储，其中包含一个 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/ 中创建 skills。此目录专供 Cursor 内置的内部 skills 使用，并由系统自动管理。

SKILL.md 结构

每个 skill 都需要一个带有 YAML frontmatter 和 Markdown 正文的 SKILL.md 文件：

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

# Your Skill Name

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

## Examples
Concrete examples of using this skill.

默认设置 disable-model-invocation: true，这样 skill 只会在被明确指定时加载。只有当 Agent 应根据上下文自动调用时，才省略此设置。

必需的元数据字段

字段	要求	用途
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. 简洁是关键

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

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

审视每一条信息：

• “Agent 真的需要这个解释吗？”
• “我可以假设 Agent 已经知道这个吗？”
• “这段内容值得占用这么多词元吗？”

好的（简洁）：

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

---

实用脚本

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

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

## 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 端点”（不要混用“URL”“路由”“路径”）
• ✅ 始终使用“字段”（不要混用“框”“元素”“控件”）

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 风格的路径