مهار بار اضافی مهارت‌ها و هزینهٔ توکن در گوگل آنتی‌گرویتی: کتابخانهٔ مجزای ابزارها برای هر پروژه

پایان ماه عسل با دستیارهای هوش مصنوعی و سقف توکن‌ها

محیط اصلی من برای برنامه‌نویسی با هوش مصنوعی، گوگل آنتی‌گرویتی (Google Antigravity 2.0) است. روزهای اولی که کار با ایجنت‌های مستقل را شروع می‌کنید، همه‌چیز شبیه جادو به نظر می‌رسد: هر قابلیت جالبی که در جامعهٔ توسعه‌دهندگان یا مارکت‌پلیس پیدا می‌کنید با یک کلیک نصب می‌کنید و تماشا می‌کنید که ایجنت چطور کارها را پیش می‌برد.

اما کمی که زمان می‌گذرد، واقعیت خود را نشان می‌دهد.

بعد از چند هفته متوجه شدم حدود ۶۰ مهارت (Skill) و ۱۳ پلاگین مختلف روی سیستمم نصب کرده‌ام؛ مجموعه‌های حجیمی مثل فلاتر (با ۲۴ مهارت)، ابزارهای توسعه‌دهندهٔ کروم (۷ مهارت)، افزونه‌های گوگل ورک‌اسپیس (۵ پلاگین مجزا)، پلاگین آهنگسازی ACE Studio (۴ مهارت)، ابزارهای Gemini API، ابزارهای اندروید و سوپرپاورز (۱۴ مهارت).

و دردسر اصلی اینجا بود: تک‌تک این ابزارها در تمام پروژه‌ها لود می‌شدند.

وقتی پروژهٔ وب‌سایت شخصی‌ام را که یک سایت ایستا و سبک با HTML و CSS خالص است باز می‌کردم، ایجنت در همان شروع کار با ۲۴ مهارت تخصصی فلاتر و الگوریتم‌های سنتز صدا روبه‌رو می‌شد.

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

طبق برآورد من، هر توضیح مهارت حدود ۵۰ تا ۱۰۰ توکن مصرف می‌کند؛ یعنی داشتن حدود ۱۲۰ مهارت فعال، پیش از آنکه من اولین خط پرامپت را تایپ کنم، بین ۶٬۰۰۰ تا ۱۲٬۰۰۰ توکن فضا می‌بلعید.

اما ضرر بزرگ‌تر از هزینهٔ توکن، سردرگمی ایجنت در انتخاب ابزار مناسب بود. وقتی ده‌ها توضیحِ تا حدی شبیه به هم در پنجرهٔ زمینه قرار می‌گیرند، احتمال اینکه ایجنت ابزاری نامربوط را انتخاب کند به شدت افزایش می‌یابد. فهرست شدن ابزارهای تست دارت و ویرایش صوت در یک پروژهٔ سادهٔ وب، برای مدل زبانی فقط نویز شناختی ایجاد می‌کرد.

پس از موفقیت این ساختار در آنتی‌گرویتی، همین الگو را روی کلود کد (Claude Code) هم پیاده کردم تا هر دو ابزار از یک کتابخانه و اسکریپت مشترک استفاده کنند؛ سپس با اضافه شدن یک مجموعهٔ ۲٬۷۵۰ مهارتی، معماری سیستم را با تفکیک کتابخانه از کاتالوگ و جستجوی درلحظه ارتقا دادم.

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

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

نتیجهٔ بررسی‌ها به دو دسته تقسیم شد:

• کاهش مصرف توکن: ابزارهای معتبر و موفقی وجود داشت. مهارت Caveman (توسعه‌داده‌شده توسط جولیوس بروسی) که پاسخ‌های ایجنت را فوق‌العاده فشرده و بدون تعارفات اضافی تنظیم می‌کند، بیش از ۷۵٬۰۰۰ ستاره در گیت‌هاب و ۳۰۰٬۰۰۰ نصب در رجیستری ابزارها داشت. علاوه بر آن، بستهٔ tokless ابزار Caveman را با چندین بهینه‌ساز دیگر یکپارچه کرده بود و مستقیماً از آنتی‌گرویتی پشتیبانی می‌کرد (~۲۷۰ ستاره و نگهداری فعال).
• مدیریت و تفکیک مهارت‌ها: در این بخش تقریباً هیچ راه‌حل جامعی وجود نداشت. نزدیک‌ترین موارد، مهارت filter از مجموعهٔ Agent Kits بود (با ۳ ستاره که فقط مهارت‌های پکیج خودش را فیلتر می‌کرد) و پروژه‌ای تجربی به نام skill router (با صفر ستاره که سعی می‌کرد ابزارها را انتخاب کند ولی هیچ مهارتی را غیرفعال نمی‌کرد و در نتیجه بار توکن را بیشتر هم می‌کرد). هیچ‌کدام پاسخگوی نیاز من نبودند.

تصمیم مشخص شد: استفاده از tokless برای کنترل پایهٔ توکن‌ها، و پیاده‌سازی یک الگوی سبک و برگشت‌پذیر برای اختصاص مهارت‌ها به تفکیک هر پروژه.

لایهٔ اول: جعبه‌ابزار صرفه‌جویی توکن (tokless)

قدم اول، اتصال و راه‌اندازی tokless در آنتی‌گرویتی بود. این ابزار با یک دستور، مجموعه‌ای هماهنگ از قوانین و ابزارها را اضافه می‌کند:

نکتهٔ مهم در سیستم‌عامل مک: معمای PATH برنامه‌ها

پس از نصب، ابزار بررسی سلامت (tokless doctor) اعلام کرد همه‌چیز بدون نقص است؛ با این حال، دو سرور بسیار مهم MCP یعنی codegraph و context-mode اصلاً در فهرست ابزارهای فعال ایجنت ظاهر نمی‌شدند.

دلیل ماجرا: هر دو ابزار اسکریپت‌های Node.js با هش‌بنگ #!/usr/bin/env node بودند. برنامهٔ Node در مسیر /usr/local/bin نصب بود. در حالی که محیط ترمینال مک متغیر PATH کامل کاربر را می‌شناسد، اپلیکیشن‌هایی که از طریق داک یا فایندر باز می‌شوند یک PATH حداقلی پیش‌فرض (/usr/bin:/bin:/usr/sbin:/sbin) دریافت می‌کنند؛ در نتیجه سرورهای MCP در پس‌زمینه بدون هیچ خطای واضحی کرش می‌کردند.

با یک دستور تست ایزوله مشکل فوراً آشکار شد:

env -i PATH=/usr/bin:/bin:/usr/sbin:/sbin ~/.local/bin/codegraph --version
# -> env: node: No such file or directory

راه حل: اضافه کردن صریح مسیرهای موردنیاز در بخش env.PATH تنظیمات سرورهای MCP در فایل mcp_config.json:

"env": {
  "PATH": "/usr/local/bin:~/.local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
}

همین وضعیت برای ابزار RTK در هوک ترمینال هم رخ می‌داد (command not found: rtk) که با افزودن عبارت export PATH="$HOME/.local/bin:/usr/local/bin:$PATH" به فایل ~/.zshenv برطرف شد.

نتیجهٔ تجربی: در مک، اگر دستوری داخل ترمینال کار می‌کند، اصلاً به این معنی نیست که داخل برنامه‌های گرافیکی هم کار خواهد کرد.

لایهٔ دوم: الگوی کتابخانه (The Library Pattern)

آنتی‌گرویتی نسخهٔ ۲.۰ قابلیت ارزنده‌ای برای مهارت‌ها و پلاگین‌های محلی دارد: مهارت‌های پوشهٔ <پروژه>/.agents/skills/ و پلاگین‌های پوشهٔ <پروژه>/.agents/plugins/ فقط وقتی لود می‌شوند که آن ورک‌اسپیس باز باشد.

ایدهٔ الگوی کتابخانه بسیار سرراست است: همهٔ مهارت‌ها و پلاگین‌های غیرضروری را به پوشه‌هایی منتقل کن که آنتی‌گرویتی آن‌ها را اسکن نمی‌کند، و فقط ابزارهای لازم هر پروژه را داخل پوشهٔ همان پروژه کپی کن.

~/skill-library/            ~60 skills (inactive, unscanned storage)
~/plugin-library/           11 plugins (inactive, unscanned storage)

~/.agents/skills/           Global skills: only "project-starter"
~/.gemini/config/plugins/   Global plugins: "superpowers", "google-developer-knowledge"

<project>/.agents/skills/   This project's specific skills
<project>/.agents/plugins/  This project's specific plugins

نتیجه: مهارت‌های عمومی کاربر از حدود ۶۰ به ۱ مهارت (project-starter) کاهش یافت. پلاگین‌های فعال سراسری از ۱۳ به ۲ پلاگین رسید. حالا یک پروژهٔ معمولی فقط بین ۲ تا ۵ مهارت و ۰ تا ۲ پلاگین با خود حمل می‌کند. به عنوان مثال، در پروژهٔ وب‌سایت من فقط دو مهارت wrangler و web-perf به همراه پلاگین chrome-devtools-plugin فعال هستند.

امنیت ساختاری: تمامی جابه‌جایی‌ها در فایل .moved.json ذخیره می‌شوند. اگر روزی بخواهم به وضعیت اولیه برگردم، یک دستور ساده همهٔ فایل‌ها را به محل اولیه‌شان برمی‌گرداند. همچنین قبل از هر تغییری، از فایل تنظیمات آنتی‌گرویتی بک‌آپ تهیه می‌شود.

لایهٔ سوم: مهارت راه‌اندازی پروژه (project-starter)

برای اینکه مدیریت این ساختار نیازی به جابه‌جایی دستی فایل‌ها نداشته باشد، مهارتی به نام project-starter نوشتم که همراه با یک اسکریپت پایتون کار می‌کند.

هر بار که به ایجنت می‌گویم «یک پروژهٔ جدید بساز» یا «بررسی کن این پروژه چه ابزارهایی کم دارد»، گفتگویی هدفمند شکل می‌گیرد:

1. بررسی کتابخانه: ایجنت لیست مهارت‌ها و پلاگین‌های موجود در کتابخانه را می‌خواند.
2. حداکثر ۳ سؤال کوتاه: فقط سؤالاتی می‌پرسد که در انتخاب ابزار مؤثر هستند (نوع خروجی، بستر هاستینگ، استفاده از مدل‌های هوش مصنوعی مانند جمینای).
3. ارائهٔ پیشنهاد حداقلی: فهرستی دقیق از ابزارهای لازم همراه با دلیل یک‌خطی، و مهم‌تر از آن، ابزارهایی که آگاهانه کنار گذاشته شده‌اند را ارائه می‌دهد.
4. تأیید و ساخت: پس از موافقت، پوشهٔ پروژه ساخته شده و فقط ابزارهای مشخص‌شده داخل .agents/ کپی می‌شوند.

نمونهٔ واقعی از یک پیشنهاد

برای یک وب‌اپلیکیشن ضبط صوت تحت کلاینت با API جمینای روی کلودفلر:

• مهارت‌های اضافه‌شده: wrangler (برای دیپلوی روی کلودفلر)، web-perf (تحلیل عملکرد Web Audio).
• پلاگین‌های اضافه‌شده: chrome-devtools-plugin (دیباگ مرورگر)، gemini-api (طراحی پرامپت‌ها).
• موارد کنارگذاشته‌شده: workers-best-practices (چون روت‌های پیچیدهٔ سرورلس نداشتیم)، gsheets (خروجی محلی بود).
• حذف همپوشانی: مهارت tdd را اضافه نکردم، چون پلاگین سراسری superpowers مهارت توسعهٔ آزمون‌محور را پوشش می‌دهد. داشتن دو مهارت مشابه برای یک کار فقط هدر دادن توکن است و باعث دودلی ایجنت می‌شود.

همین سیستم با فرمان audit می‌تواند کدهای یک مخزن موجود را بررسی کند (مثلاً شناسایی pubspec.yaml برای فلاتر یا وابستگی‌های جمینای) و ابزارهای جامانده را پیشنهاد دهد.

لایهٔ چهارم: به‌روز نگه‌داشتن پلاگین‌های کتابخانه

وقتی پلاگین‌ها را از دایرکتوری سراسری خارج می‌کنید، یک چالش جدید پیش می‌آید: آنتی‌گرویتی دیگر آن‌ها را به طور خودکار آپدیت نمی‌کند.

برای حل این مسئله سه راه را امتحان کردم که به بن‌بست رسیدند:

1. ابزار ترمینال (CLI): دستور agy plugin install با خطای «مارکت‌پلیس ناشناخته» مواجه می‌شد. ابزار خط فرمان این ساختار را پارس می‌کرد اما به بک‌اند مارکت‌پلیس متصل نبود.
2. رابط کاربری برنامه: در بخش پلاگین‌ها هیچ شماره نسخه‌ای درج نشده و دکمه‌ای برای آپدیت وجود ندارد.
3. نصب مجدد از طریق CLI: به همان علت اول غیرممکن بود.

راهکاری که جواب داد: بررسی کش محلی اپلیکیشن نشان داد که خود آنتی‌گرویتی یک کپی از کاتالوگ مارکت‌پلیس رسمی را روی دیسک ذخیره می‌کند. هر ورودی شامل آخرین نسخه، آدرس دانلود و چک‌سام SHA-256 است.

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

• نسخهٔ پلاگین‌های کتابخانه را با کاتالوگ کش‌شده مقایسه می‌کند.
• اگر نسخهٔ جدیدتری وجود داشته باشد، آن را دانلود می‌کند، چک‌سام را اعتبارسنجی می‌کند، نسخهٔ قبلی را در پوشهٔ بک‌آپ نگه می‌دارد، و کپی‌های موجود در پروژه‌های فعال را نوسازی می‌کند.
• در طول کار هیچ تداخلی با تنظیمات زندهٔ برنامه ایجاد نمی‌کند و با اتمام آپدیت، یک اعلان در مک نمایش می‌دهد.

گسترش ساختار به کلود کد (Claude Code)

پس از استقرار پایدار این ساختار در آنتی‌گرویتی، نوبت به کلود کد (Claude Code) رسید. در کلود کد، ۳۸ مهارت به صورت سراسری در مسیر ~/.claude/skills نصب داشتم؛ همان بستهٔ عمومی گردش کار توسعه که قبلاً در کتابخانهٔ آنتی‌گرویتی هم داشتم (چون ابتدای کار آن‌ها را هم‌زمان در هر دو ابزار نصب کرده بودم). همچنین یک پلاگین به صورت عمومی برای همهٔ پروژه‌ها فعال بود، به علاوهٔ مهارت‌ها و یک پلاگین که از حساب کاربری‌ام در claude.ai همگام می‌شدند. هیچ ابزار صرفه‌جویی توکنی هم هنوز به آن متصل نبود.

به‌جای ایجاد یک سیستم موازی، ساختار را طوری توسعه دادم که هر دو ابزار از یک مرجع مشترک استفاده کنند:

1. اتصال ابزارهای مدیریت توکن: با اجرای یک فرمان (tokless --agents claude)، بستهٔ tokless را به کلود کد وصل کردم. دقیقاً همان ترکیب آنتی‌گرویتی در اینجا هم فعال شد: لحن فشردهٔ Caveman، اصول Ponytail برای کدنویسی حداقلی، اصول کارپاتی، فیلتر خروجی شل RTK، ایندکس کُد CodeGraph، سندباکس Context-Mode و ثبت تاریخچه در ProjectMem.
2. یک کتابخانهٔ مشترک به‌جای دو کتابخانه: قبل از انتقال هر مهارت کلود کد، اسکریپت آن را با نسخهٔ موجود در کتابخانه فایل‌به‌فایل مقایسه می‌کند:
   • محتوای یکسان: به پوشهٔ بک‌آپ منتقل می‌شود تا در کتابخانه نسخهٔ تکراری ایجاد نشود.
   • محتوای متفاوت: با پسوند claude- (مثلاً <name>-claude) به کتابخانه اضافه می‌شود تا هیچ تغییری از بین نرود.
   • مهارت جدید: مستقیماً به ~/skill-library/ اضافه می‌شود.
   مهارت‌های همگام‌شده از claude.ai دست‌نخورده باقی می‌مانند، زیرا مدیریت آن‌ها در تنظیمات همان سرویس انجام می‌شود.
3. پلاگین‌های محلی به ازای هر پروژه: کلود کد برخلاف آنتی‌گرویتی، قابلیت داخلی برای نصب پلاگین در سطح پروژه دارد (claude plugin install <plugin> --scope project). پلاگینی که پیش‌تر در همهٔ نشست‌ها لود می‌شد، اکنون منحصراً در پروژه‌های نیازمند به آن نصب است. همچنین چون کلود کد به‌روزرسانی پلاگین‌هایش را خودکار انجام می‌دهد، نیازی به طراحی فرآیند آپدیت مجزا نبود.
4. دستیار آغازگر مشترک (project-starter): همان اسکریپت starter.py به هر دو ابزار سرویس می‌دهد. پروژه‌های آنتی‌گرویتی در پوشهٔ اختصاصی خود قرار دارند و مسیر .agents/skills/ را می‌گیرند؛ پروژه‌های کلود کد در دایرکتوری ~/code هستند و مسیر .claude/skills/ دریافت می‌کنند. هر ابزار یک فایل راهنمای کوتاه دارد که ایجنت را به اسکریپت و کتابخانهٔ مشترک هدایت می‌کند.

اولین نتیجهٔ ثبت‌شده: در نشست‌های اولیه، ابزار RTK که خروجی ترمینال را پیش از رسیدن به مدل فشرده می‌کند، آمار خود را نشان داد: در ۳۸ دستور اجرا شده، ۸٫۴ هزار توکن ورودی خوانده شد و ۳٫۸ هزار توکن صرفه‌جویی گردید (کاهش **۴۵ درصدی**). هرچند این آمار یک نمونهٔ اولیهٔ محدود است و منحصراً خروجی‌های ترمینال را اندازه می‌گیرد نه کل نشست را، اما یک ارزیابی تجربی واقعی است، نه حدس و گمان.

مدیریت ۲٬۷۵۰ مهارت: تفاوت کتابخانه و کاتالوگ

با داشتن یک کتابخانهٔ مشترک حدوداً ۶۰ مهارتی، تصمیم گرفتم یک مجموعهٔ بزرگ اجتماعی را هم به سیستم بیاورم: مجموعهٔ Agentic Awesome Skills (در github.com/sickn33/agentic-awesome-skills) که حدود ۲٬۷۵۰ راهنما (SKILL.md) در حوزه‌های مهندسی نرم‌افزار، امنیت و زیرساخت دارد و سطح ریسک هر مهارت (از جمله ابزارهای تست نفوذ) در آن مشخص است.

اضافه شدن این حجم بلافاصله فرض اولیهٔ طراحی من را به چالش کشید.

اسکریپت project-starter در اصل با خواندن نام و توضیحات تمام مهارت‌های کتابخانه، پیشنهاد ابزار می‌داد. خواندن ۶۰ توضیح کوتاه توکن ناچیزی می‌خواست؛ اما برای ۲٬۷۵۰ مهارت، این کار طبق برآورد من هر بار حدود ۱۵۰٬۰۰۰ توکن فضا می‌گرفت—دقیقاً برعکس هدف بهینه‌سازی توکن.

برای مهار این مقیاس بدون از دست دادن دسترسی به ابزارها، یک تفکیک معماری میان کتابخانه و کاتالوگ ایجاد کردم:

• کتابخانهٔ گلچین‌شده (حدود ۶۰ مهارت): ابزارهای برگزیده و مطمئنی که شخصاً استفاده می‌کنم. در گفتگوها متن کامل توضیحاتشان خوانده می‌شود و در موارد هم‌نام، همیشه اولویت دارند.
• کاتالوگ غیرفعال (۲٬۷۵۰ مهارت): در یک پوشهٔ مجزا (~/skill-catalog/) خارج از دید هر دو ایجنت ذخیره می‌شود. چون ایجنت‌ها هیچ‌وقت کل آن را اسکن یا لیست نمی‌کنند، در نشست‌های عادی هزینهٔ آن دقیقاً صفر توکن است.
• جستجوی سریع کلیدواژه‌ای: به‌جای خواندن همه چیز، ایجنت از دستور search <keywords> استفاده می‌کند. اسکریپت با بررسی نام، دسته‌بندی و توضیحات، فقط ۲۵ نتیجهٔ برتر را از کل کتابخانه و کاتالوگ برمی‌گرداند. ایجنت بر اساس استک پروژه، ۲ تا ۴ جستجوی دقیق انجام می‌دهد. در آزمایش‌های من روی یک کاتالوگ شبیه‌سازی‌شده با این حجم، هر جستجو حدود ۰٫۱۵ ثانیه زمان برد.
• اولویت و تفکیک نام: اگر مهارتی در هر دو جا وجود داشته باشد، نسخهٔ کتابخانه انتخاب می‌شود. در صورت نیاز به نسخهٔ کاتالوگ، ایجنت می‌تواند صریحاً نام آن را به فرم source:name درخواست کند.
• فیلترهای ایمنی: ابزارهای تست نفوذ و امنیتی حساس از نتایج جستجوی پیش‌فرض حذف شده‌اند مگر اینکه کاربر مشخصاً آن‌ها را بخواهد.
• همگام‌سازی بالادستی: دستور catalog-update کاتالوگ را با ریپازیتوری گیت‌هاب همگام می‌کند (به عنوان یک منبع صرفاً خواندنی؛ نسخه‌های کپی‌شده در پروژه‌ها دست‌نخورده می‌مانند و تغییرات محلی کاتالوگ بازنویسی می‌شود؛ هر مهارتی که نیاز به شخصی‌سازی دارد، ابتدا باید به کتابخانه کپی شود).

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

بهینه‌سازی‌های تکمیلی جریان کار

با بلوغ سیستم در مواجهه با دو ایجنت مختلف و هزاران ابزار، فرآیندهای کاری را استاندارد کردم:

• سه گردش کار شفاف برای ایجنت: راهنمای سیستم سه جریان پیش‌بینی‌پذیر را تعریف می‌کند: ساخت پروژهٔ جدید (Flow A)، ارزیابی مخزن موجود (Flow B)، و نصب پلاگین‌های تکمیلی (Flow C). هر پیشنهاد فرمت ثابتی دارد: بیان دلیل یک‌خطی برای هر ابزار پیشنهادی، همراه با فهرست اقلامی که بررسی شدند اما کنار گذاشته شدند.
• قاعدهٔ منع همپوشانی ابزارها: ایجنت هیچ مهارتی را که قبلاً توسط پلاگین‌های سراسری پوشش داده شده پیشنهاد نمی‌دهد (مثلاً عدم افزودن مهارت مجزای TDD وقتی پلاگین Superpowers خودش توسعهٔ آزمون‌محور را دارد).
• ممیزی هوشمند از روی فایل‌های پروژه: دستور audit با بررسی امضاهای کد—مانند pubspec.yaml برای فلاتر، یا package.json و فایل‌های HTML برای DevTools—ابزارهای متناسب را به طور خودکار پیدا می‌کند.

درس‌هایی که آموختم

1. بررسی پیوندهای نمادین (Symlinks) قبل از جابه‌جایی فایل: در مک، مسیر ~/.gemini/config/skills در واقع یک میانبر به ~/.agents/skills بود. نسخهٔ اول اسکریپتم همهٔ مهارت‌ها را دو بار دید و متوقف شد. پیدا کردن مسیر واقعی فایل‌ها (realpath) قبل از اقدام و ثبت لاگ در هر مرحله این مشکل را حل کرد.
2. تست آزمایشی (Dry Run) شوخی‌بردار نیست: هر اسکریپتی که با جابه‌جایی فایل سر و کار دارد باید فلگ --dry-run داشته باشد و ابتدا روی پوشه‌های تستی اجرا شود.
3. به گزارش ابزارها کورکورانه اعتماد نکنید: دستور tokless doctor مسیری از فایل کانفیگ را چاپ می‌کرد که عملاً وجود خارجی نداشت، و ایجنت هم ادعا می‌کرد سرورهای گمشده «فقط موقع نیاز روشن می‌شوند» (که ساختار فنی سرورهای MCP اصلاً این‌طور نیست). بررسی مستقیم فایل‌ها و پروسه‌ها واقعیت را نشان داد.
4. مستندات رسمی همیشه با محصول نهایی یکی نیست: مستندات دستوراتی برای نصب از مارکت‌پلیس داشت که باینری فعلی CLI توانایی اجرایشان را نداشت. عملکرد واقعی ابزارها را همیشه در عمل بسنجید.
5. استفاده از داده‌های بومی خود پلتفرم: پیدا کردن کش کاتالوگ مارکت‌پلیس، یک کار ناممکن را به اسکریپتی تمیز و ۱۰۰ خطی تبدیل کرد.
6. مقایسه پیش از حذف تکراری‌ها: نام یکسان همیشه به معنای محتوای یکسان نیست. مقایسهٔ فایل‌به‌فایل پیش از جابه‌جایی، از بازنویسی اشتباه مهارت‌ها جلوگیری کرد و تفاوت‌ها را با پسوند claude- نجات داد.
7. مقیاس معماری را تغییر می‌دهد: الگویی که برای ۶۰ مورد عالی است (خواندن همه در پنجرهٔ زمینه)، برای ۲٬۷۵۰ مورد با شکست مواجه می‌شود. تفکیک کتابخانهٔ منتخب از کاتالوگ جستجوپذیر، هر دو را در هزینهٔ پایهٔ صفر فعال نگه داشت.
8. استفاده از توانمندی‌های بومی هر پلتفرم: پلاگین‌های محلی و آپدیت خودکار در کلود کد، نیمی از کارهای جانبی لازم در آنتی‌گرویتی را حذف کرد. قبل از ساخت سیستم‌های واسط، قابلیت‌های خود ابزار را بررسی کنید.
9. استناد به ارقام اندازه‌گیری‌شده: آمار واقعی ثبت‌شده توسط ابزار RTK (کاهش ۴۵ درصدی خروجی ترمینال) اعتباری تجربی ایجاد کرد که فراتر از هر تخمین تئوریک بود.

محدودیت‌ها و واقعیت‌ها

• محدودهٔ آمار خروجی ترمینال: رقم ۴۵ درصد صرفه‌جویی از یک نمونهٔ اولیهٔ محدود (۳۸ دستور) به دست آمده و صرفاً به فیلتر خروجی شل در RTK مربوط می‌شود، نه کل توکن‌های مصرفی نشست.
• برآورد توکن‌های کاتالوگ: رقم تقریبی ۱۵۰٬۰۰۰ توکن برای خواندن کل کاتالوگ بر اساس حجم کاراکترها و تراکم توکن توضیحات تخمین زده شده است.
• سرعت جستجوی شبیه‌سازی‌شده: زمان جستجوی ۰٫۱۵ ثانیه‌ای در آزمون‌های من روی کاتالوگ شبیه‌سازی‌شده ثبت شده است.
• مهارت‌های ارزیابی‌نشدهٔ کاتالوگ: مهارت‌های شخص ثالث تا قبل از بررسی دستی توسط کاربر ارزیابی‌نشده هستند؛ همیشه دستورالعمل‌های دریافتی از جامعه را با احتیاط کدهای اجرایی بررسی کنید.
• تخمینی بودن صرفه‌جویی کلی: میزان صرفه‌جویی در طول کار بسته به عمق گفتگو، فراخوانی ابزارها و پیچیدگی کد متغیر خواهد بود.
• تأخیر در کش کاتالوگ: به‌روزرسانی پلاگین‌های آنتی‌گرویتی متکی به تازه‌سازی کش داخلی برنامه است و ممکن است با کمی فاصله از نسخه‌های اصلی عمل کند.
• نصب مجدد توسط برنامه‌های دیگر: نرم‌افزارهای خارجی (مانند ACE Studio) ممکن است با هر به‌روزرسانی، پلاگین‌های اختصاصی خود را مجدداً سراسری نصب کنند.

منابع و پیوندها

• مخزن tokless: github.com/HoangP8/tokless
• مهارت Caveman: github.com/JuliusBrussee/caveman
• پلاگین Superpowers: github.com/obra/superpowers
• مجموعهٔ Agentic Awesome Skills: github.com/sickn33/agentic-awesome-skills
• مستندات پلاگین‌های Claude Code: code.claude.com/docs/en/plugins
• مستندات مهارت‌ها و پلاگین‌های گوگل آنتی‌گرویتی: راهنمای مهارت‌ها · راهنمای پلاگین‌ها