ویرگول
ورودثبت نام
آرش فدائی
آرش فدائیتوسعه‌دهنده ارشد وب و متخصص PHP
آرش فدائی
آرش فدائی
خواندن ۵ دقیقه·۳ ماه پیش

چگونه در Cursor یک Skill تعریف کنیم؟

Skill چیست؟

Skill یک راهنمای Markdown است که Agent می‌تواند آن را پیدا کرده و در صورت نیاز اجرا کند.

Skillها کاربردهای مختلفی دارند، از جمله:

  • Workflowهای پروژه: مانند /article، چک‌لیست Deploy یا Release Notes

  • فرآیندهای مربوط به ابزارها: مانند Figma MCP، اسکریپت‌های CLI یا APIهای داخلی

  • استانداردهای تیم: مانند قوانین Commit، Code Review و بررسی‌های امنیتی

Skillها معمولاً در یکی از این مسیرها قرار می‌گیرند:

.cursor/skills/

در این حالت Skill داخل خود پروژه قرار دارد و همراه Repository با سایر اعضای تیم به اشتراک گذاشته می‌شود.

یا در Personal Cursor Skills Directory قرار می‌گیرند که در پروژه‌های مختلف برای خود شما قابل استفاده هستند.


ساختار فایل SKILL.md

هر Skill به یک YAML Frontmatter در ابتدای فایل و مجموعه‌ای از دستورالعمل‌ها نیاز دارد.

برای مثال:

--- name: blog-pro-content-automation description: >- Draft-first English content automation for Blog Pro via WordPress REST API. Use when the user runs /article, /prompt, /tutorial, or asks to create drafts. --- # Blog Pro Content Automation Hard rules: 1. Default status is always draft. 2. Never publish unless the user runs /publish-now. ## Workflow 1. Generate English JSON 2. Validate with the CLI 3. Create a WordPress draft

در ادامه اجزای اصلی را بررسی می‌کنیم.


name

نام Skill یک شناسه کوتاه و با فرمت kebab-case است.

بهتر است نام آن پایدار و مشخص باشد، چون ممکن است فایل‌ها یا مستندات دیگر پروژه به آن ارجاع دهند.

برای مثال:

name: blog-pro-content-automation

یا:

name: my-release-checklist

description

description در واقع نقش Trigger یا محرک Skill را دارد.

Cursor از این توضیحات استفاده می‌کند تا تشخیص دهد چه زمانی باید Skill موردنظر را فعال کند.

بنابراین Description باید مشخص کند:

  • این Skill چه کاری انجام می‌دهد؟

  • چه زمانی باید استفاده شود؟

  • کاربر معمولاً چه عبارت‌ها یا Commandهایی را وارد می‌کند؟

برای مثال:

description: >- Run the project release checklist before tagging a version. Use when the user says release, ship, tag, or prepare a production deploy.

این توضیح بسیار بهتر از یک عبارت کلی مانند «کمک به Release پروژه» است.


آموزش مرحله‌به‌مرحله: اولین Skill خود را بسازید

مرحله ۱: ساخت پوشه

ابتدا پوشه مربوط به Skill را ایجاد کنید:

mkdir -p .cursor/skills/my-release-checklist

ساختار پروژه شما در این مرحله چیزی شبیه این خواهد بود:

.cursor/ └── skills/ └── my-release-checklist/

مرحله ۲: ایجاد SKILL.md

حالا داخل پوشه Skill یک فایل به نام SKILL.md ایجاد کنید.

محتوای اولیه می‌تواند به شکل زیر باشد:

--- name: my-release-checklist description: >- Run the project release checklist before tagging a version. Use when the user says release, ship, tag, or prepare a production deploy. --- # Release checklist 1. Confirm main is green. 2. Update CHANGELOG. 3. Bump version in package/theme metadata. 4. Do not push tags unless the user asks.

در این مثال، Skill به Cursor می‌گوید قبل از آماده‌سازی Release چه مراحلی باید انجام شود.


مرحله ۳: Description را دقیق بنویسید

یکی از مهم‌ترین بخش‌های یک Skill، Description آن است.

ضعیف:

Helps with releases.

این توضیح بیش از حد کلی است و اطلاعات کافی برای تشخیص زمان استفاده از Skill به Cursor نمی‌دهد.

قوی:

Run the project release checklist before tagging a version. Use when the user says release, ship, tag, or prepare a production deploy.

در این نسخه مشخص شده:

  • Skill چه کاری انجام می‌دهد.

  • چه زمانی باید فعال شود.

  • چه عباراتی می‌توانند باعث فعال شدن آن شوند.


مرحله ۴: قوانین قابل اجرا بنویسید

قوانین Skill باید Actionable باشند؛ یعنی Agent بتواند بر اساس آن‌ها یک اقدام مشخص انجام دهد.

به‌جای جملات کلی، از فعل و Constraint استفاده کنید.

مثلاً:

  • «همیشه Draft ایجاد کن و هرگز Publish نکن.»

  • «قبل از اجرای CLI، فایل workflow.md را بخوان.»

  • «اگر Duplicate Detection هشدار داد، متوقف شو و از کاربر سؤال کن.»

برای مثال:

Always create drafts, never publish.

یا:

Read workflow.md before calling the CLI.

از متن‌های انگیزشی یا توضیحات غیرضروری خودداری کنید.

Agent به Procedure و Constraint نیاز دارد، نه جملات انگیزشی.


مرحله ۵: به فایل‌های پشتیبان ارجاع دهید

بهتر است فایل SKILL.md بیش از حد طولانی نشود.

اگر دستورالعمل‌ها و جزئیات پروژه زیاد هستند، آن‌ها را در فایل‌های جداگانه قرار دهید.

برای مثال:

.cursor/skills/blog-pro-content-automation/ SKILL.md workflow.md content-types.md templates/

سپس داخل SKILL.md مشخص کنید Agent در هر مرحله باید کدام فایل را باز کند.

برای مثال:

Before generating content, read content-types.md. Before calling the WordPress CLI, read workflow.md.

این ساختار باعث می‌شود Skill اصلی کوتاه، قابل نگهداری و قابل فهم باقی بماند.


الگوهای مناسب برای ساخت Skill

چند الگوی کاربردی وجود دارد که می‌توانند کیفیت Skillهای شما را بهتر کنند.

۱. Command Map

یک جدول برای مشخص کردن Commandهای مختلف ایجاد کنید.

برای مثال:

Commandکاربرد/articleایجاد پیش‌نویس مقاله/promptایجاد محتوای Prompt/tutorialایجاد آموزش/publish-nowانتشار محتوا


۲. Hard Rules

قوانینی را که تحت هیچ شرایطی نباید نقض شوند، به‌صورت واضح و شماره‌گذاری‌شده بنویسید.

مثلاً:

1. Never publish automatically. 2. Always validate generated JSON. 3. Never overwrite existing content without confirmation.

۳. Short Path

مسیر اصلی انجام کار را کوتاه و مرحله‌به‌مرحله مشخص کنید.

مثلاً:

1. Read the content type. 2. Generate the content. 3. Validate the output. 4. Create a draft. 5. Return the draft ID.

۴. Failure Policy

مشخص کنید اگر مشکلی اتفاق افتاد Agent چه کاری باید انجام دهد.

مثلاً:

If authentication fails, stop and ask the user to reconnect WordPress.

یا:

If validation fails, do not create the draft.

۵. Output Format

مشخص کنید Agent در پایان کار دقیقاً چه اطلاعاتی را باید به کاربر نمایش دهد.

مثلاً:

At the end, report: - Content type - Draft ID - WordPress URL - Validation status

این کار باعث می‌شود خروجی Skillها همیشه قابل پیش‌بینی و یکدست باشد.


اشتباهات رایج

Description بیش از حد کلی

اگر Description مبهم باشد، ممکن است Skill در زمان مناسب فعال نشود.

قرار دادن کل مستندات شرکت در یک SKILL.md

فایل SKILL.md نباید تبدیل به یک Wiki چندصدصفحه‌ای شود.

دستورالعمل‌های مرتبط را در فایل‌های جداگانه نگهداری کنید.

وجود قوانین متناقض

برای مثال:

Always commit changes.

در حالی که جای دیگری نوشته‌اید:

Never commit unless the user asks.

این تضاد باعث رفتار غیرقابل پیش‌بینی Agent می‌شود.

ننوشتن نمونه‌هایی از عبارت‌های کاربر

اگر انتظار دارید Skill با عباراتی مثل:

release ship prepare production deploy

فعال شود، بهتر است این عبارات را در Description مشخص کنید.

ایجاد معماری جدید توسط Skill

Skill نباید صرفاً به این دلیل که Agent یک روش را بهتر می‌داند، معماری جدیدی برای پروژه ایجاد کند.

اولویت باید همیشه دنبال کردن ساختار و معماری موجود Repository باشد.


Skill خود را تست کنید

بعد از ساخت Skill، آن را آزمایش کنید.

۱. یک Chat جدید در پروژه باز کنید

بهتر است تست را در یک Session جدید انجام دهید.

۲. از عبارتی که در Description نوشته‌اید استفاده کنید

مثلاً:

Prepare the project for release.

۳. بررسی کنید Agent فایل SKILL.md را می‌خواند

قبل از اجرای Workflow، مطمئن شوید Cursor Skill مربوطه را پیدا کرده و دستورالعمل‌های آن را دنبال می‌کند.

۴. اگر Skill فعال نشد، Description را اصلاح کنید

Description را دقیق‌تر کنید و Triggerهای واقعی که کاربران استفاده می‌کنند به آن اضافه کنید.


skill
۰
۰
آرش فدائی
آرش فدائی
توسعه‌دهنده ارشد وب و متخصص PHP
شاید از این پست‌ها خوشتان بیاید