مهارتها و ابزارها
مهارتهای مشترک در .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 با مستندات رسمی تطبیق داده شده است:
| اپ | دستورالعملهای پروژه | مهارتهایی که این مخزن استفاده میکند | ایجنتهای سفارشی که این مخزن استفاده میکند |
|---|---|---|---|
| Codex | AGENTS.md | .agents/skills/<name>/SKILL.md | .codex/agents/<name>.toml تولیدشده |
| Claude Code | CLAUDE.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 را ببینید.