پرش به مطلب اصلی

مهارت‌ها و ابزارها

مهارت‌های مشترک در .agents/skills/ قرار دارند. همین منابع را ویرایش کنید و سپس yarn ai-workflow:sync را اجرا کنید تا .claude/skills/ برای Claude Code تولید شود. Codex مهارت‌ها را مستقیماً در .agents/skills/ پیدا می‌کند.

پرامپت‌های مشترک نقش‌ها در .agents/roles/*.md قرار دارند. این یک قالب منبع مخصوص همین مخزن است، نه مسیر بومی کشف ایجنت‌ها. scripts/ai-workflow-files.mjs این منابع را به فایل‌های مخصوص هر اپ که در ادامه آمده‌اند تبدیل می‌کند؛ yarn ai-workflow:sync آن‌ها را می‌نویسد. فایل‌های تولیدشده را در کنار منابعشان کامیت کنید تا یک چک‌اوت تازه، بدون اینکه ابتدا مولدی اجرا شود، پیکربندی بومی را داشته باشد. پس از حذف یک منبع، خروجی‌های تولیدشده و منسوخ آن را صراحتاً حذف کنید؛ اعتبارسنج آن‌ها را گزارش می‌کند و فایل‌ها را بی‌سروصدا پاک نمی‌کند.

مسیرهای بومی کشف​

در تاریخ 2026-09-12 با مستندات رسمی تطبیق داده شده است:

اپدستورالعمل‌های پروژهمهارت‌هایی که این مخزن استفاده می‌کندایجنت‌های سفارشی که این مخزن استفاده می‌کند
CodexAGENTS.md.agents/skills/<name>/SKILL.md.codex/agents/<name>.toml تولیدشده
Claude CodeCLAUDE.md فایل @AGENTS.md را ایمپورت می‌کند.claude/skills/<name>/SKILL.md تولیدشده.claude/agents/<name>.md تولیدشده

منابع: مهارت‌های Codex، زیرایجنت‌های Codex، حافظه Claude، مهارت‌های Claude، زیرایجنت‌های Claude.

پوشه‌های بومی ایجنت‌ها را با .agents/roles جایگزین نکنید و فرض نکنید Claude پوشه .agents/skills را کشف می‌کند. Claude همچنان می‌تواند فایلی را که در آنجا به آن ارجاع داده شده، به‌عنوان کانتکست عادی پروژه بخواند.

پوشه‌های AI از طریق .gitattributes از پایان خط LF استفاده می‌کنند تا متن تولیدشده در همه پلتفرم‌ها یکسان بماند. دارایی‌های پشتیبان مهارت‌ها بایت‌به‌بایت کپی می‌شوند.

مهارت‌ها​

مهارتهدف
commitساخت کامیت‌های محلی مجاز و محدود به دامنه کار
commit-format، issue-formatپیشنهاد قالب، در صورت درخواست
make-closed-issueساخت یک issue مجاز، یک کامیت محدود به دامنه کار و یک PR
review-and-merge-prدسته‌بندی بازخوردهای PR؛ اصلاح، انتشار یا ادغام فقط در دامنه درخواست‌شده
fix-merge-conflictsحل تعارض‌ها و راستی‌آزمایی نتیجه ادغام
releaseآماده‌سازی متن انتشار نسخه و انجام گام‌های مجاز انتشار
code-quality-reviewبازبینی دیف‌های غیربدیهی یا دغدغه‌ای کیفی که صراحتاً درخواست شده است
retroتبدیل اشتباهات اثبات‌شده به بررسی‌ها یا راهنمایی‌های متمرکزی که از تکرارشان جلوگیری کنند
refactor-pass، deslopپاکسازی درخواست‌شده روی تغییرات موجود
debug-agentاشکال‌زدایی مبتنی بر شواهد، با ابزارگذاری در صورت نیاز
you-might-not-need-an-effectبازبینی متمرکز effect/memo
vercel-react-best-practicesراهنمای کاربردی کارایی React؛ قواعد مخصوص Next.js یا سرور را برای این کلاینت Vite کنار بگذارید
translateتولید ترجمه‌ها و سپس اعمال نگاشت‌ها از طریق یک نویسنده واحد
playwright-cli، inspect-elementsراستی‌آزمایی مرورگری و نگاشت DOM به کد منبع
profile-browsingپروفایل‌گیری محدود مرورگر و React
test-apkراستی‌آزمایی پوشش Android همراهی که در اختیار گذاشته شده
impeccable، improve-threejsطراحی محدود رابط کاربری و بازبینی رندر Three.js
implement-planاجرای یک برنامه با واگذاری اختیاری و محدود
readmeنگهداری مستندات راستی‌آزمایی‌شده پروژه
context7بازیابی مستندات کتابخانه متناسب با نسخه
find-skillsیافتن مهارت‌های بیشتر، فقط در صورت درخواست صریح

نقش‌ها و مدل‌ها​

نقش‌های سفارشی browser-check، profiler، test-apk، translator و reviewer را نگه دارید. برای پیاده‌سازی معمولی و کشف کد از نقش داخلی worker/general-purpose یا explorer در هارنس استفاده کنید. والد معیارهای پذیرش و مالکیت را تعیین می‌کند؛ بررسی‌های سنگین را یک مالک اجرا می‌کند.

فایل‌های ایجنت Codex شامل name، description و developer_instructions هستند. .codex/config.toml با max_concurrent_threads_per_session تعداد فرزندان همزمان را به چهار محدود می‌کند. فراداده مشترک نقش‌ها شامل نام، توضیح و حالت اختیاری sandbox است و عمداً هیچ فیلدی برای مدل ندارد.

فیلدهای مدل و استدلال را از مهارت‌ها و ایجنت‌های سفارشیِ کامیت‌شده کنار بگذارید. این کار اجازه می‌دهد انتخاب‌های زمان فراخوانی، پیش‌فرض‌های کاربر و ارث‌بری از والد طبق ترتیب اولویتی که هر اپ مستند کرده اعمال شوند. نام‌های مستعار خانواده مدل در Claude نگهداری نسخه‌ها را کم می‌کنند اما همچنان یک خانواده را انتخاب می‌کنند. در صورت نیاز، چنین انتخاب‌هایی را در تنظیمات کاربر یا نشست نگه دارید. ارث‌بری تضمین نمی‌کند که بهترین مدل فعلی خودکار انتخاب شود. نام مستعاری مثل latest از خودتان نسازید و پژوهش درباره کاتالوگ مدل‌ها را به وظایف روزمره اضافه نکنید. انتخاب مدل در Codex و انتخاب مدل در Claude را ببینید.

sandbox-mode: read-only به sandbox در Codex نگاشت می‌شود. در Claude، فهرست ابزارها و دستورالعمل‌های نقش، گردش کار بازبینی را محدود می‌کنند، اما دسترسی به Bash یک sandbox در سطح سیستم‌عامل نیست.

فرانت‌متر مهارت‌های مشترک، هر جا مناسب باشد، برای گردش‌های کاری که کاربر فرا می‌خواند از disable-model-invocation: true استفاده می‌کند. تنظیم متناظر Codex در agents/openai.yaml و به شکل policy.allow_implicit_invocation: false قرار دارد؛ اعتبارسنج هر دو را الزامی می‌داند. فراداده فراخوانی مکمل قواعد صریح مجوز است؛ درخواست بازبینی هرگز صرفاً به این دلیل که مهارتی گام‌های انتشار دارد، مجوز انتشار نمی‌دهد.

بررسی‌ها و کشف​

  • yarn ai-workflow:sync خروجی‌های سازگاری را با استفاده از js-yaml و smol-toml نصب‌شده بازتولید می‌کند.
  • yarn ai-workflow:check منابع، فرانت‌متر و پیکربندی‌ها را پارس می‌کند و خروجی‌های تولیدشده، فراداده فراخوانی، جای فیلدهای مدل و سیم‌کشی هوکی را که فقط قالب‌بندی می‌کند بررسی می‌کند. این فرمان شناسه‌های مدل را با کاتالوگ یک ارائه‌دهنده تطبیق نمی‌دهد.
  • yarn ai-workflow:test فیکسچرهای مجزای Node را برای محموله‌های هوک و تولید و اعتبارسنجی گردش کار اجرا می‌کند.
  • پس از ارتقای یک اپلیکیشن ایجنت، کشف مهارت‌ها و نقش‌ها را در همان اپلیکیشن راستی‌آزمایی کنید. بررسی‌های نحو و برابری جای بررسی بارگذار را نمی‌گیرند. اگر نشستی موجود هنوز کاتالوگ قدیمی را نگه داشته، اپلیکیشن را دوباره بارگذاری کنید.
  • هوک‌ها به اعتماد پروژه و بازبینی هوک در هارنس نیاز دارند؛ برای موفق شدن یک بررسی، اعتماد را دور نزنید. hooks-setup.md را ببینید.

نگهداری دستورالعمل‌های مفید​

از راهنمای OpenAI درباره مهارت‌ها و پرامپت‌ها (بازبینی‌شده در 2026-09-12) پیروی کنید: توضیحات را دقیق نگه دارید، جزئیات را فقط وقتی مرتبط‌اند بارگذاری کنید و دامنه‌ای را که کاربر درخواست کرده حفظ کنید. مهارت‌های مشترک به مدل‌های مختلفی خدمت می‌کنند؛ قیدهای ثابت مخصوص پروژه را حفظ کنید و در عین حال انتخاب‌های روزمره پیاده‌سازی را آزاد بگذارید.

هدف مهارت، مرزهای تصمیم‌گیری و قیدهای ضروری آن را در SKILL.md نگه دارید. فرمان‌ها یا نمونه‌های مفصلِ مخصوص یک حالت را به‌عنوان ارجاع‌های اختیاری پیوند دهید. شرایط فعال‌سازی را در ابتدای توضیحات کوتاه بیاورید؛ صرفِ تطابق یک کلیدواژه نباید دامنه وظیفه را گسترش دهد. فراداده فراخوانی موجود را حفظ کنید، مگر آنکه عمداً در حال تغییر رفتار آن باشید.

پس از تغییری اساسی در دستورالعمل‌ها، چند درخواست نمونه کوچک و بزرگ را امتحان کنید. بررسی کنید کدام مهارت‌ها یا ارجاع‌ها انتخاب شدند، آیا اقدامات در دامنه ماندند، آیا راستی‌آزمایی با تغییر متناسب بود و آیا کار مجاز کامل شد. آزمون‌های شِما و فیکسچر درستی ابزارها را ثابت می‌کنند، نه کیفیت تصمیم‌گیری ایجنت را.

ابزارها و مالکیت مرورگر​

کاتالوگ موجود مهارت‌ها و ابزارها و CLIهای نصب‌شده پروژه را ترجیح دهید. برای GitHub از gh، برای راستی‌آزمایی مرورگری از playwright-cli، و وقتی رفتار کتابخانه اهمیت دارد از مستندات رسمی و مخصوص نسخه استفاده کنید. از نصب مهارت‌های تکراری یا دریافت بسته‌ای پین‌نشده صرفاً برای اجرای یک قالب‌بند موجود پرهیز کنید.

سربار MCP به هارنس بستگی دارد: بارگذاری تأخیری ابزارها می‌تواند از بارگذاری همه شِماها در همان ابتدا جلوگیری کند. به جای اینکه خود MCP را منسوخ بدانید، یکپارچه‌سازی‌ها را مرتبط نگه دارید. CLIهایی که اکنون انتخاب شده‌اند برای تکرارپذیری و کنترل منابع همچنان مفیدند.

همه نشست‌های مرورگر از ./scripts/pw-session.sh استفاده می‌کنند که در کل ماشین فقط یک مرورگر فعال را مجاز می‌داند. به‌طور پیش‌فرض از یک نشست تازه و ایزوله استفاده کنید. دسترسی به مرورگر شخصیِ فعلی کاربر به مجوز صریح نیاز دارد؛ همان مجوز را در گام‌های بعدی هم به کار ببرید. مرورگرها و viewportها را بر اساس رفتار متأثر انتخاب کنید، موتورهای انتخاب‌شده را پشت سر هم اجرا کنید، در پاکسازی دقیقاً همان نشست نام‌دار را ببندید و هرگز از close-all/kill-all استفاده نکنید. مهارت playwright-cli و verification.md را ببینید.