create-skill

Cursor でのスキルの作成

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

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

スキルを作成する前に、ユーザーから次の重要な情報を集めてください。

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

ユーザーの文言をそのまま使う

ユーザーがスキルに使用する正確な文言を提示した場合は、それを尊重し、SKILL.md に一字一句そのまま使用してください（同じ言葉、同じ順序）。言い換えたり、表現を和らげたり、内容を追加したりせず、依頼されていない見出しや説明も加えないでください。

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

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

追加情報を集める

確認が必要な場合は、利用可能であれば 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
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 に設定し、明示的に名前を指定した場合にのみスキルが読み込まれるようにしてください。エージェントが周囲のコンテキストから自動的に呼び出す必要がある場合に限り、この項目を省略してください。

必須のメタデータフィールド

フィールド	要件	目的
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 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. フロントマター付きの SKILL.md ファイルを書く
3. 必要な参考ファイルを作成する
4. 必要に応じてユーティリティスクリプトを作成する

フェーズ 4：検証

1. SKILL.md が 500 行未満であることを確認する
2. 説明が具体的で、起動条件を示す用語を含んでいることを確認する
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)

---

まとめチェックリスト

スキルを完成させる前に、以下を確認してください。

基本的な品質

• 説明が具体的で、重要なキーワードが含まれている
• 説明に WHAT と WHEN の両方が含まれている
• 三人称で記述されている
• SKILL.md の本文が 500 行未満である
• 用語が全体を通して統一されている
• 例が抽象的ではなく、具体的である

構成

• ファイル参照が 1 階層にとどまっている
• 必要に応じて段階的開示が使われている
• ワークフローの手順が明確である
• 時間の経過で古くなる情報がない

スクリプトを含める場合

• スクリプトが問題を解決しており、丸投げしていない
• 必要なパッケージが記載されている
• エラー処理が明確で、役立つ内容になっている
• Windows 形式のパスを使用していない