create-skill

Cursor でのスキルの作成

このスキルでは、Cursor 向けの効果的なエージェントスキルを作成する方法を説明します。スキルは、チームの基準に沿った PR のレビュー、好みの形式でのコミットメッセージの生成、データベーススキーマの照会、その他の専門的なワークフローなど、特定のタスクの実行方法をエージェントに教える Markdown ファイルです。

始める前に：要件を収集する

スキルを作成する前に、ユーザーから次の重要な情報を収集します。

1. 目的と範囲：このスキルで支援する具体的なタスクやワークフローは何ですか？
2. 保存場所：個人用スキル（~/.cursor/skills/）とプロジェクト用スキル（.cursor/skills/）のどちらにしますか？
3. 適用する状況：エージェントがこのスキルを自動的に適用するのはどのようなときですか？
4. 重要なドメイン知識：エージェントがまだ知らない、必要な専門知識は何ですか？
5. 出力形式の希望：特定のテンプレート、形式、スタイルが必要ですか？
6. 既存のパターン：参考にする既存の例や規約はありますか？

コンテキストから推測する

以前の会話のコンテキストがある場合は、話し合った内容からスキルを推測します。会話の中で明らかになったワークフロー、パターン、ドメイン知識に基づいてスキルを作成できます。

追加情報を収集する

確認が必要な場合は、利用可能であれば 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.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/ にスキルを作成しないでください。このディレクトリは Cursor に組み込まれている内部スキル用に予約されており、システムによって自動的に管理されます。

SKILL.md の構成

各スキルには、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 文字。小文字、数字、ハイフンのみ使用可能	スキルの一意な識別子
description	最大 1024 文字。空欄不可	スキルを適用するタイミングをエージェントが判断するのに役立ちます

---

効果的な説明を書く

説明は、スキルの発見に不可欠です。エージェントは説明を使って、スキルを適用するかどうかを判断します。

説明を書く際のベストプラクティス

1. 三人称で書く（説明はシステムプロンプトに挿入されます）：

   • ✅ 推奨：「Excel ファイルを処理してレポートを生成します」
   • ❌ 避ける：「Excel ファイルの処理をお手伝いします」
   • ❌ 避ける：「Excel ファイルの処理に使用できます」

2. 具体的に書き、トリガーとなる用語を含める：

   • ✅ 推奨：「PDF ファイルからテキストと表を抽出し、フォームに入力して、文書を結合します。PDF ファイルを扱うときや、ユーザーが PDF、フォーム、文書の抽出について言及したときに使用します。」
   • ❌ 曖昧：「文書を支援します」

3. WHAT と WHEN の両方を含める：

   • WHAT：スキルでできること（具体的な機能）
   • WHEN：エージェントがスキルを使うべきとき（適用する状況）

説明の例

# 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. 簡潔さが重要です

コンテキストウィンドウは、会話履歴やほかのスキル、リクエストと共有されています。すべてのトークンが限られたスペースを取り合います。

デフォルトの前提：エージェントはすでに非常に高い知能を備えています。エージェントがすでに知っていることは、コンテキストに追加しないでください。

情報の一つひとつを吟味してください。

• 「この説明は本当にエージェントに必要ですか？」
• 「エージェントはこれを知っていると考えてよいですか？」
• 「この段落はトークンを使う価値がありますか？」

良い例（簡潔）：

## 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 には必須情報を記載し、詳細な参考資料は、必要に応じてエージェントが読む別ファイルに記載します。

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

参照先は1階層に保ちます。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
\`\`\`

エージェントがスクリプトを実行するのか（一般的）、それとも参考資料として読むのかを明確にしてください。

---

避けるべきアンチパターン

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. 用語の不統一

用語を1つ選び、全体を通して統一してください。

• ✅ 常に「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. フロントマター付きの SKILL.md ファイルを書く
3. 補助となる参照ファイルを作成する
4. 必要に応じてユーティリティスクリプトを作成する

フェーズ 4: 検証

1. SKILL.md が 500 行未満であることを検証する
2. description が具体的で、トリガーとなる用語が含まれていることを確認する
3. 用語が全体を通して一貫していることを確認する
4. すべてのファイル参照が 1 階層の深さであることを検証する
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)

---

まとめチェックリスト

スキルを完成させる前に、次を検証してください:

中核的な品質

• description が具体的で、重要な用語を含んでいる
• description に WHAT と WHEN の両方が含まれている
• 三人称で書かれている
• SKILL.md の本文が 500 行未満である
• 用語が全体を通して一貫している
• 例が抽象的ではなく具体的である

構造

• ファイル参照が 1 階層の深さである
• 段階的な開示が適切に使用されている
• ワークフローに明確な手順がある
• 時間に依存する情報がない

スクリプトを含める場合

• スクリプトが問題を先送りにせず解決する
• 必要なパッケージが文書化されている
• エラー処理が明示的で役立つ
• Windows 形式のパスがない