این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

نوشتن مهارت‌های ضد جاذبه گوگل

۱. مقدمه

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

در این آزمایشگاه کد، ابتدا در مورد مهارت‌های عامل (Agent Skills)، یک قالب سبک و باز برای گسترش قابلیت‌های عامل هوش مصنوعی با دانش و گردش‌های کاری تخصصی، خواهیم آموخت. شما قادر خواهید بود مهارت‌های عامل، مزایای آنها و نحوه ساخت آنها را بیاموزید. سپس چندین مهارت عامل از قالب‌بندی Git، مولد قالب، داربست کد ابزار و موارد دیگر را خواهید ساخت که همگی در Antigravity قابل استفاده هستند.

پیش‌نیازها:

ضد جاذبه نصب و پیکربندی شد.
آشنایی اولیه با Google Antigravity. توصیه می‌شود Codelab: شروع کار با Google Antigravity را تکمیل کنید.

۲. چرا مهارت‌ها

عامل‌های هوش مصنوعی مدرن از شنوندگان ساده به استدلال‌کنندگان پیچیده‌ای تکامل یافته‌اند که با سیستم‌های فایل محلی و ابزارهای خارجی (از طریق سرورهای MCP ) ادغام می‌شوند. با این حال، بارگذاری بی‌هدف یک عامل با کل پایگاه‌های کد و صدها ابزار منجر به اشباع متن و "انباشت ابزار" می‌شود. حتی با وجود پنجره‌های متن بزرگ، تخلیه ۴۰ تا ۵۰ هزار توکن از ابزارهای استفاده نشده در حافظه فعال باعث تأخیر زیاد، اتلاف مالی و "پوسیدگی متن" می‌شود، که در آن مدل توسط داده‌های نامربوط گیج می‌شود.

راه حل: مهارت‌های عامل

برای حل این مشکل، شرکت آنتروپیک (Anthropic) با معرفی مهارت‌های عامل (Agent Skills )، معماری را از بارگذاری یکپارچه‌ی زمینه (monolithic context loading) به افشای پیش‌رونده (progressive Disclosure ) تغییر داد. به جای اینکه مدل را مجبور به "به خاطر سپردن" هر گردش کار خاص (مانند انتقال پایگاه داده یا ممیزی‌های امنیتی) در ابتدای یک جلسه کند، این قابلیت‌ها در واحدهای ماژولار و قابل کشف بسته‌بندی می‌شوند.

چگونه کار می‌کند؟

این مدل در ابتدا فقط در معرض یک «منوی» سبک از فراداده‌ها قرار می‌گیرد. این مدل دانش رویه‌های سنگین (دستورالعمل‌ها و اسکریپت‌ها) را فقط زمانی بارگذاری می‌کند که قصد کاربر به طور خاص با یک مهارت مطابقت داشته باشد. این تضمین می‌کند که توسعه‌دهنده‌ای که درخواست بازسازی میان‌افزار احراز هویت را دارد، بدون بارگذاری خطوط لوله CSS نامرتبط، زمینه امنیتی را دریافت می‌کند و زمینه را سبک، سریع و مقرون به صرفه نگه می‌دارد.

۳. مهارت‌های عامل و ضدجاذبه

در اکوسیستم Antigravity، مهارت‌ها به عنوان ماژول‌های آموزشی تخصصی عمل می‌کنند که شکاف بین مدل‌های عمومی و زمینه خاص شما را پر می‌کنند. آن‌ها به عامل اجازه می‌دهند تا مجموعه‌ای از دستورالعمل‌ها و پروتکل‌های تعریف‌شده - مانند استانداردهای مهاجرت پایگاه داده یا بررسی‌های امنیتی - را تنها زمانی که یک کار مرتبط درخواست می‌شود، "مجهز" کند. با بارگذاری پویای این پروتکل‌های اجرایی، مهارت‌ها به طور مؤثر هوش مصنوعی را از یک برنامه‌نویس عمومی به یک متخصص تبدیل می‌کنند که به شدت به بهترین شیوه‌ها و استانداردهای ایمنی مدون سازمان پایبند است.

مهارت در ضد جاذبه چیست؟

در زمینه Google Antigravity، یک Skill یک بسته مبتنی بر دایرکتوری است که شامل یک فایل تعریف ( SKILL.md ) و دارایی‌های پشتیبانی اختیاری (اسکریپت‌ها، منابع، قالب‌ها) می‌باشد.

این مکانیزمی برای گسترش قابلیت‌ها بر اساس تقاضا است.

بر اساس تقاضا : برخلاف System Prompt (که همیشه بارگذاری می‌شود)، یک Skill فقط زمانی در context عامل بارگذاری می‌شود که عامل تشخیص دهد به درخواست فعلی کاربر مرتبط است. این کار پنجره context را بهینه می‌کند و از حواس‌پرتی عامل توسط دستورالعمل‌های نامربوط جلوگیری می‌کند. در پروژه‌های بزرگ با ده‌ها ابزار، این بارگذاری انتخابی برای عملکرد و دقت استدلال بسیار مهم است.
گسترش قابلیت : مهارت‌ها می‌توانند کاری بیش از آموزش انجام دهند؛ آن‌ها می‌توانند اجرا کنند. با بسته‌بندی اسکریپت‌های پایتون یا بش، یک مهارت می‌تواند به عامل توانایی انجام اقدامات پیچیده و چند مرحله‌ای را در دستگاه محلی یا شبکه‌های خارجی بدون نیاز به اجرای دستی دستورات توسط کاربر بدهد. این امر عامل را از یک تولیدکننده متن به یک کاربر ابزار تبدیل می‌کند.

مهارت‌ها در مقابل اکوسیستم (ابزارها، قوانین و گردش‌های کاری)

در حالی که پروتکل زمینه مدل (MCP) به عنوان "دست‌های" عامل عمل می‌کند - و اتصالات پایدار و قدرتمندی را با سیستم‌های خارجی مانند GitHub یا PostgreSQL فراهم می‌کند - مهارت‌ها به عنوان "مغز" عمل می‌کنند که آنها را هدایت می‌کنند.

MCP زیرساخت stateful را مدیریت می‌کند، در حالی که Skills تعاریف سبک و زودگذر وظایف هستند که روش‌شناسی استفاده از آن ابزارها را بسته‌بندی می‌کنند. این رویکرد بدون سرور به عامل‌ها اجازه می‌دهد تا وظایف ad-hoc (مانند ایجاد گزارش تغییرات یا مهاجرت‌ها) را بدون سربار عملیاتی اجرای فرآیندهای مداوم اجرا کنند، زمینه را فقط زمانی که وظیفه فعال است بارگذاری کنند و بلافاصله پس از آن آن را آزاد کنند.

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

۴. ایجاد مهارت‌ها

ایجاد یک مهارت در Antigravity از یک ساختار دایرکتوری و فرمت فایل خاص پیروی می‌کند. این استانداردسازی تضمین می‌کند که مهارت‌ها قابل حمل هستند و عامل می‌تواند آنها را به طور قابل اعتمادی تجزیه و اجرا کند. طراحی عمداً ساده است و با تکیه بر فرمت‌های شناخته شده‌ای مانند Markdown و YAML، موانع ورود را برای توسعه‌دهندگانی که مایل به گسترش قابلیت‌های IDE خود هستند، کاهش می‌دهد.

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

یک فهرست مهارت معمولی به این شکل است:

my-skill/
├── SKILL.md # The definition file
├── scripts/ # [Optional] Python, Bash, or Node scripts
     ├── run.py
     └── util.sh
├── references/ # [Optional] Documentation or templates
     └── api-docs.md
└── assets/ # [Optional] Static assets (images, logos)

این ساختار به طور مؤثر دغدغه‌ها را از هم جدا می‌کند. منطق ( scripts ) از دستورالعمل ( SKILL.md ) و دانش ( references ) جدا شده است، که منعکس کننده شیوه‌های استاندارد مهندسی نرم‌افزار است.

فایل تعریف SKILL.md

فایل SKILL.md مغز متفکر مهارت است. این فایل به عامل می‌گوید که مهارت چیست، چه زمانی از آن استفاده کند و چگونه آن را اجرا کند.

از دو بخش تشکیل شده است:

فرانت‌متر YAML
بدنه‌ی مارک‌داون.

فرانت‌متر YAML

این لایه، لایه فراداده است. این تنها بخشی از مهارت است که توسط روتر سطح بالای عامل، فهرست‌بندی می‌شود. وقتی کاربری درخواستی ارسال می‌کند، عامل، درخواست را از نظر معنایی با فیلدهای توضیحات تمام مهارت‌های موجود مطابقت می‌دهد.

---
name: database-inspector
description: Use this skill when the user asks to query the database, check table schemas, or inspect user data in the local PostgreSQL instance.
---

فیلدهای کلیدی:

name : این مورد اجباری نیست. باید در محدوده‌ی مورد نظر منحصر به فرد باشد. حروف کوچک و خط فاصله مجاز است (مثلاً postgres-query ، pr-reviewer ). اگر ارائه نشود، به طور پیش‌فرض نام دایرکتوری در نظر گرفته می‌شود.
توضیحات : این فیلد اجباری و مهم‌ترین فیلد است. این فیلد به عنوان «عبارت محرک» عمل می‌کند. این فیلد باید به اندازه کافی توصیفی باشد تا LLM بتواند ارتباط معنایی را تشخیص دهد. توضیحات مبهمی مانند «ابزارهای پایگاه داده» کافی نیست. توضیحات دقیقی مانند «اجرای کوئری‌های SQL فقط خواندنی در پایگاه داده محلی PostgreSQL برای بازیابی داده‌های کاربر یا تراکنش. استفاده از این برای اشکال‌زدایی وضعیت داده‌ها» تضمین می‌کند که مهارت به درستی انتخاب شده است.

بدنه‌ی مارک‌داون

بدنه شامل دستورالعمل‌ها است. این «مهندسی سریع» است که در یک فایل ذخیره شده است. وقتی مهارت فعال می‌شود، این محتوا به پنجره زمینه عامل تزریق می‌شود.

بدن باید شامل موارد زیر باشد:

هدف: بیان واضحی از آنچه که مهارت به آن دست می‌یابد.
دستورالعمل: منطق گام به گام.
مثال‌ها: نمونه‌های مختصری از ورودی‌ها و خروجی‌ها برای هدایت عملکرد مدل.
محدودیت‌ها: قوانین «انجام ندهید» (مثلاً «درخواست‌های DELETE را اجرا نکنید»).

مثال بدنه SKILL.md:

Database Inspector

Goal
To safely query the local database and provide insights on the current data state.

Instructions
- Analyze the user's natural language request to understand the data need.
- Formulate a valid SQL query.
 - CRITICAL: Only SELECT statements are allowed.
- Use the script scripts/query_runner.py to execute the SQL.
 - Command: python scripts/query_runner.py "SELECT * FROM..."
- Present the results in a Markdown table.

Constraints
- Never output raw user passwords or API keys.
- If the query returns > 50 rows, summarize the data instead of listing it all.

ادغام اسکریپت

یکی از قدرتمندترین ویژگی‌های Skills، قابلیت واگذاری اجرا به اسکریپت‌ها است. این به عامل اجازه می‌دهد تا اقداماتی را انجام دهد که انجام مستقیم آنها برای یک LLM دشوار یا غیرممکن است (مانند اجرای دودویی، محاسبات ریاضی پیچیده یا تعامل با سیستم‌های قدیمی).

اسکریپت‌ها در زیرشاخه scripts/ قرار می‌گیرند. فایل SKILL.md با استفاده از مسیر نسبی به آنها ارجاع می‌دهد.

۵. مهارت‌های نویسندگی

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

می‌توانید مهارت‌ها را از مخزن گیت‌هاب اینجا دانلود کنید: https://github.com/rominirani/antigravity-skills .

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

استفاده از Antigravity یا رابط خط فرمان Antigravity

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

محدوده سراسری ( ~/.gemini/config/skills/ ): در تمام محصولات Antigravity (Antigravity، Antigravity IDE، Antigravity CLI) و پروژه‌ها موجود است. این مهارت‌ها در تمام پروژه‌های روی دستگاه کاربر موجود است. این برای ابزارهای عمومی مانند "Format JSON"، "Generate UUIDs"، "Review Code Style" یا ادغام با ابزارهای بهره‌وری شخصی مناسب است.
محدوده پروژه/فضای کاری ( <project-root>/.agents/skills/ ): این باعث می‌شود مهارت فقط در یک پروژه خاص در دسترس باشد. این برای اسکریپت‌های خاص پروژه، مانند استقرار در یک محیط خاص، مدیریت پایگاه داده برای آن برنامه یا تولید کد تکراری برای یک چارچوب اختصاصی، ایده‌آل است.

نصب مهارت‌ها در Antigravity یا Antigravity CLI

برای این آموزش، تنها کاری که باید انجام دهیم مراحل زیر است (شما هم می‌توانید به روش خودتان این کار را انجام دهید):

مرحله ۱ : یک git clone از https://github.com/rominirani/antigravity-skills ایجاد کنید

مرحله ۲ : اکنون بسته به اینکه از Antigravity یا Antigravity CLI استفاده می‌کنید، می‌توانید به پوشه antigravity-skills/skills_tutorial بروید.

مرحله ۳ : مجموعه‌ای از مهارت‌ها را خواهید یافت که در پوشه‌های مربوط به خود بسته‌بندی شده‌اند. ۴ پوشه زیر را کپی کنید:

git-commit-formatter
license-header-adder
database-schema-validator
json-to-pydantic

در پوشه مهارت‌های مورد نظر برای محصول (محدوده پروژه یا محدوده جهانی) قرار دهید.

مرحله ۴: اگر از Antigravity یا Antigravity CLI استفاده می‌کنید، آن را در <project-root>/.agents/skills/ (محدوده پروژه) کپی کنید.

اگر Antigravity را اجرا کرده‌اید، می‌توانید یک سوال ساده بپرسید « چه مهارت‌هایی در دسترس است؟ » و آن هم همین را پاسخ می‌دهد. می‌توانید ۴ مهارتی که در آنجا فهرست شده‌اند را ببینید. اگر مهارت‌های دیگری را در محیط خود نصب کرده باشید، ممکن است مهارت‌های دیگری هم داشته باشید.

۱۹۱۸۴۲a2a0d69597.png

به طور مشابه، اگر از Antigravity CLI استفاده می‌کنید، می‌توانید دستور /skills زیر را وارد کنید و باید 4 مهارت را فهرست کند. نمونه‌ای از آن در زیر نشان داده شده است:

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

سطح ۱: روتر پایه (git-commit-formatter)

بیایید این را به عنوان "سلام دنیای" مهارت‌ها در نظر بگیریم.

توسعه‌دهندگان اغلب پیام‌های commit را به صورت lazy می‌نویسند، مثلاً "wip"، "fix bug"، "updates". اعمال دستی "Conventional Commits" خسته‌کننده و اغلب فراموش می‌شود. بیایید مهارتی را پیاده‌سازی کنیم که مشخصات Conventional Commits را اعمال کند. با آموزش ساده‌ی قوانین به agent، به آن اجازه می‌دهیم که به عنوان مجری عمل کند.

git-commit-formatter/
└── SKILL.md  (Instructions only)

فایل SKILL.md در زیر نشان داده شده است:

---
name: git-commit-formatter
description: Formats git commit messages according to Conventional Commits specification. Use this when the user asks to commit changes or write a commit message.
---

Git Commit Formatter Skill

When writing a git commit message, you MUST follow the Conventional Commits specification.

Format
`<type>[optional scope]: <description>`

Allowed Types
- **feat**: A new feature
- **fix**: A bug fix
- **docs**: Documentation only changes
- **style**: Changes that do not affect the meaning of the code (white-space, formatting, etc)
- **refactor**: A code change that neither fixes a bug nor adds a feature
- **perf**: A code change that improves performance
- **test**: Adding missing tests or correcting existing tests
- **chore**: Changes to the build process or auxiliary tools and libraries such as documentation generation

Instructions
1. Analyze the changes to determine the primary `type`.
2. Identify the `scope` if applicable (e.g., specific component or file).
3. Write a concise `description` in an imperative mood (e.g., "add feature" not "added feature").
4. If there are breaking changes, add a footer starting with `BREAKING CHANGE:`.

Example
`feat(auth): implement login with google`

نحوه اجرای این مثال در Antigravity

مراحل زیر فرض می‌کنند که شما گیت را روی دستگاه محلی خود دارید و آن را به درستی راه‌اندازی کرده‌اید.

با فرض اینکه Antigravity یا Antigravity CLI را اجرا کرده‌اید، این مراحل را دنبال کنید:

مرحله ۱: راه‌اندازی یک مخزن آزمایشی گیت

از عامل بخواهید یک دایرکتوری تمیز و ایزوله برای آزمایش عملیات Git راه‌اندازی کند.

درخواست شما:

Create a folder named git_test in the workspace, initialize a git repository inside it, and create an initial file auth.py with def login(): pass. Stage this file and make an initial commit.

عامل، دایرکتوری را ایجاد می‌کند، مخزن را مقداردهی اولیه می‌کند، فایل را استیج می‌کند و آن را با پیامی مانند « initial commit » ثبت می‌کند.

مرحله ۲: ایجاد تغییر در کد

به عامل بگویید کد را اصلاح کند تا تغییری برای اعمال وجود داشته باشد.

درخواست شما:

In the git_test folder, modify auth.py to add Google Login functionality.

عامل، فایل را ویرایش می‌کند تا یک ویژگی جدید اضافه کند و آن را برای مرحله‌ی کامیت آماده کند.

مرحله ۳: تغییرات را مرحله‌بندی و ثبت کنید

با درخواست از عامل برای مرحله‌بندی تغییرات و ایجاد یک کامیت، مهارت git-commit-formatter را فعال کنید.

درخواست شما:

Stage the changes in the git_test folder and commit them. Make sure to format the commit message using the Conventional Commits skill.

عامل دستور git add auth.py اجرا می‌کند، diff را تجزیه و تحلیل می‌کند تا مشخص کند که یک ویژگی جدید به ماژول auth اضافه شده است، و یک پیام commit مرسوم مانند feat(auth): implement google login before run git commit فرموله می‌کند.

مرحله ۴: تأیید لاگ گیت

از عامل بخواهید تاریخچه گیت را بازیابی کند تا بتوانید تأیید کنید که کامیت قالب‌بندی‌شده با موفقیت ثبت شده است.

درخواست شما:

Show me the git log in the git_test folder.

عامل دستور git log -n 5 اجرا می‌کند و خروجی را که پیام کامیت قالب‌بندی شده را نشان می‌دهد، برمی‌گرداند.

سطح ۲: استفاده از دارایی (مجوز-سربرگ-افزودنی)

این الگوی «مرجع» است.

هر فایل منبع در یک پروژه شرکتی ممکن است به یک هدر مجوز آپاچی ۲.۰ با طول ۲۰ خط خاص نیاز داشته باشد. قرار دادن این متن ثابت مستقیماً در prompt (یا SKILL.md ) اتلاف وقت است. هر بار که skill ایندکس می‌شود، توکن‌ها را مصرف می‌کند و مدل ممکن است در متن قانونی "غلط املایی" پیدا کند. روش خوبی است که متن ثابت را به یک فایل متنی ساده در پوشه resources/ منتقل کنید. skill به agent دستور می‌دهد که این فایل را فقط در صورت نیاز بخواند.

فایل‌ها را در پوشه‌ی license-header-adder در دایرکتوری skills پیدا خواهید کرد.

license-header-adder/
├── SKILL.md
└── resources/
   └── HEADER_TEMPLATE.txt  (The heavy text)

فایل SKILL.md در زیر نشان داده شده است:

---
name: license-header-adder
description: Adds the standard open-source license header to new source files. Use involves creating new code files that require copyright attribution.
---

# License Header Adder Skill

This skill ensures that all new source files have the correct copyright header.

## Instructions

1. **Read the Template**:
  First, read the content of the header template file located at `resources/HEADER_TEMPLATE.txt`.

2. **Prepend to File**:
  When creating a new file (e.g., `.py`, `.java`, `.js`, `.ts`, `.go`), prepend the `target_file` content with the template content.

3. **Modify Comment Syntax**:
  - For C-style languages (Java, JS, TS, C++), keep the `/* ... */` block as is.
  - For Python, Shell, or YAML, convert the block to use `#` comments.
  - For HTML/XML, use `<!-- ... -->`.

نحوه اجرای این مثال در Antigravity

با فرض اینکه Antigravity یا Antigravity CLI را اجرا کرده‌اید، این مراحل را دنبال کنید:

مرحله ۱: ایجاد فایل پایتون با کد نمونه

درخواست شما:

Create a new file my_script.py with the following python code:

def hello():
   print("Hello, World!")

آنچه اتفاق افتاد (توضیح): عامل، یک ابزار نوشتن فایل (write_to_file) را برای ایجاد یک فایل جدید به نام my_script.py مستقیماً در دایرکتوری فضای کاری فعال شما فراخوانی کرد و تابع پایه پایتون را در آن نوشت. علاوه بر این، اعلان، مهارت license-header-adder را فعال کرد. عامل، فایل الگوی مجوز ( HEADER_TEMPLATE.txt ) را پیدا و خواند، سبک کامنت را از کامنت‌های بلوکی به سبک C (/* ... */) به کامنت‌های به سبک پایتون (#) تغییر داد و آن را با استفاده از ابزار replace_file_content به بالای فایل اضافه کرد.

مرحله ۲: تأیید محتوای فایل

به فایل my_script.py نگاهی بیندازید. در بالای آن هدر لایسنس قرار دارد.

سطح ۳: یادگیری با مثال (json-to-pydantic)

الگوی «چند شات».

تبدیل داده‌های آزاد (مانند پاسخ JSON API) به کد دقیق (مانند مدل‌های Pydantic) شامل ده‌ها تصمیم است. چگونه باید کلاس‌ها را نامگذاری کنیم؟ آیا باید Optional استفاده کنیم؟ snake_case یا camelCase ؟ نوشتن این ۵۰ قانون به زبان انگلیسی خسته‌کننده و مستعد خطا است.

LLMها موتورهای تطبیق الگو هستند.

نوشتن مهارت خود با یک مثال طلایی ( Input -> Output ) اغلب مؤثرتر از دستورالعمل‌های طولانی است.

به پوشه‌ی json-to-pydantic/ که حاوی فایل‌های مهارت است، مطابق شکل زیر بروید:

json-to-pydantic/
├── SKILL.md
└── examples/
   ├── input_data.json   (The Before State)
   └── output_model.py   (The After State)

فایل SKILL.md در زیر نشان داده شده است:

---
name: json-to-pydantic
description: Converts JSON data snippets into Python Pydantic data models.
---

# JSON to Pydantic Skill

This skill helps convert raw JSON data or API responses into structured, strongly-typed Python classes using Pydantic.

Instructions

1. **Analyze the Input**: Look at the JSON object provided by the user.
2. **Infer Types**:
  - `string` -> `str`
  - `number` -> `int` or `float`
  - `boolean` -> `bool`
  - `array` -> `List[Type]`
  - `null` -> `Optional[Type]`
  - Nested Objects -> Create a separate sub-class.
 
3. **Follow the Example**:
  Review `examples/` to see how to structure the output code. notice how nested dictionaries like `preferences` are extracted into their own class.
 
  - Input: `examples/input_data.json`
  - Output: `examples/output_model.py`

Style Guidelines
- Use `PascalCase` for class names.
- Use type hints (`List`, `Optional`) from `typing` module.
- If a field can be missing or null, default it to `None`.

در پوشه /examples ، فایل JSON و فایل خروجی یعنی فایل پایتون وجود دارد. هر دو در زیر نشان داده شده‌اند:

input_data.json

{
   "user_id": 12345,
   "username": "jdoe_88",
   "is_active": true,
   "preferences": {
       "theme": "dark",
       "notifications": [
           "email",
           "push"
       ]
   },
   "last_login": "2024-03-15T10:30:00Z",
   "meta_tags": null
}

خروجی_مدل.py

from pydantic import BaseModel, Field
from typing import List, Optional

class Preferences(BaseModel):
   theme: str
   notifications: List[str]

class User(BaseModel):
   user_id: int
   username: str
   is_active: bool
   preferences: Preferences
   last_login: Optional[str] = None
   meta_tags: Optional[List[str]] = None

نحوه اجرای این مثال در Antigravity

با فرض اینکه Antigravity یا Antigravity CLI را اجرا کرده‌اید، این مراحل را دنبال کنید:

مرحله ۱: ایجاد فایل JSON با داده‌های نمونه

از عامل بخواهید که یک فایل جدید product.json حاوی محتوای خام JSON ایجاد کند.

درخواست شما:

Create a new file product.json with the following JSON:

{
 "product": "Widget",
 "cost": 10.99,
 "stock": null
}

مرحله ۲: تبدیل JSON به مدل Pydantic

مهارت json-to-pydantic را فعال کنید تا داده‌های JSON را به یک کلاس Pydantic ساختاریافته تبدیل کنید.

درخواست شما:

Convert the JSON in product.json to a Pydantic model and save it to product_model.py.

مرحله ۳: خروجی را تأیید کنید

به فایل product_model.py نگاهی بیندازید. این فایل شامل مدل تکمیل‌شده‌ی Pydantic خواهد بود.

سطح ۴: منطق رویه‌ای (پایگاه داده-طرحواره-اعتبارسنج)

این الگوی «استفاده از ابزار» است.

اگر از یک LLM بپرسید «آیا این طرحواره امن است؟»، ممکن است بگوید همه چیز خوب است، حتی اگر یک کلید اصلی حیاتی وجود نداشته باشد، صرفاً به این دلیل که SQL درست به نظر می‌رسد.

بیایید این بررسی را به یک اسکریپت قطعی واگذار کنیم. مهارت database-schema-validator ما، عامل را برای اجرای اسکریپت پایتونی که نوشتیم، هدایت می‌کند. این اسکریپت، درستی دودویی (درست/غلط) را ارائه می‌دهد.

database-schema-validator/
├── SKILL.md
└── scripts/
   └── validate_schema.py  (The Validator)

فایل SKILL.md در زیر نشان داده شده است:

---
name: database-schema-validator
description: Validates SQL schema files for compliance with internal safety and naming policies.
---

# Database Schema Validator Skill

This skill ensures that all SQL files provided by the user comply with our strict database standards.

Policies Enforced
1. **Safety**: No `DROP TABLE` statements.
2. **Naming**: All tables must use `snake_case`.
3. **Structure**: Every table must have an `id` column as PRIMARY KEY.

Instructions

1. **Do not read the file manually** to check for errors. The rules are complex and easily missed by eye.
2. **Run the Validation Script**:
  Use the `run_command` tool to execute the python script provided in the `scripts/` folder against the user's file.
 
  `python scripts/validate_schema.py <path_to_user_file>`

3. **Interpret Output**:
  - If the script returns **exit code 0**: Tell the user the schema looks good.
  - If the script returns **exit code 1**: Report the specific error messages printed by the script to the user and suggest fixes.

فایل validate_schema.py در زیر نشان داده شده است:

import sys
import re

def validate_schema(filename):
   """
   Validates a SQL schema file against internal policy:
   1. Table names must be snake_case.
   2. Every table must have a primary key named 'id'.
   3. No 'DROP TABLE' statements allowed (safety).
   """
   try:
       with open(filename, 'r') as f:
           content = f.read()
          
       lines = content.split('\n')
       errors = []
      
       # Check 1: No DROP TABLE
       if re.search(r'DROP TABLE', content, re.IGNORECASE):
           errors.append("ERROR: 'DROP TABLE' statements are forbidden.")
          
       # Check 2 & 3: CREATE TABLE checks
       table_defs = re.finditer(r'CREATE TABLE\s+(?P<name>\w+)\s*\((?P<body>.*?)\);', content, re.DOTALL | re.IGNORECASE)
      
       for match in table_defs:
           table_name = match.group('name')
           body = match.group('body')
          
           # Snake case check
           if not re.match(r'^[a-z][a-z0-9_]*$', table_name):
               errors.append(f"ERROR: Table '{table_name}' must be snake_case.")
              
           # Primary key check
           if not re.search(r'\bid\b.*PRIMARY KEY', body, re.IGNORECASE):
               errors.append(f"ERROR: Table '{table_name}' is missing a primary key named 'id'.")

       if errors:
           for err in errors:
               print(err)
           sys.exit(1)
       else:
           print("Schema validation passed.")
           sys.exit(0)
          
   except FileNotFoundError:
       print(f"Error: File '{filename}' not found.")
       sys.exit(1)

if __name__ == "__main__":
   if len(sys.argv) != 2:
       print("Usage: python validate_schema.py <schema_file>")
       sys.exit(1)
      
   validate_schema(sys.argv[1])

نحوه اجرای این مثال در Antigravity

با فرض اینکه Antigravity یا Antigravity CLI را اجرا کرده‌اید، این مراحل را دنبال کنید:

مرحله ۱: ایجاد فایل JSON با داده‌های نمونه

از نماینده بخواهید فایل جدیدی bad_schema.sql ایجاد کند که شامل چندین مورد نقض خط‌مشی باشد.

درخواست شما:

Create a new file bad_schema.sql with the following SQL:

DROP TABLE IF EXISTS legacy_users;

CREATE TABLE userProfile (
    id INT PRIMARY KEY,
    bio TEXT
);

CREATE TABLE posts (
    title TEXT,
    content TEXT,
    created_at TIMESTAMP
);

CREATE TABLE comments (
    id INT PRIMARY KEY,
    post_id INT,
    body TEXT
);

فایل طرحواره فوق هر سه خط‌مشی را نقض می‌کند: از دستور DROP TABLE ممنوعه استفاده می‌کند، برای نام جدول userProfile camelCase استفاده می‌کند و کلید اصلی id را در جدول posts فراموش می‌کند.

مرحله 2: اعتبارسنجی طرحواره SQL

مهارت database-schema-validator را فعال کنید تا اسکریپت اعتبارسنج پایتون روی فایل شما اجرا شود.

درخواست شما:

Validate bad_schema.sql using the database-schema-validator skill.

مرحله ۳: خروجی را تأیید کنید

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

Suggested Fixes:

Remove the line DROP TABLE IF EXISTS legacy_users; as dropping tables is forbidden by safety policy.

Rename the table userProfile to use snake_case (e.g., user_profile).

Add a primary key column named id to the posts table definition.

۶. جعبه ابزار توسعه‌دهندگان (مهارت‌های رابط خط فرمان (CLI))

الگوی «عمل و چرخه حیات».

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

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

مهارت‌های رابط خط فرمان (Agent CLI) اتوماسیون ساده و توسعه‌دهنده‌محور را مستقیماً به ترمینال شما می‌آورد و شکاف بین کد خام و اجرای خودکار را پر می‌کند. در حالی که کیت توسعه عامل (ADK) بر چارچوب برنامه‌نویسی تمرکز دارد و SDKها، APIها و طرح‌های ساختاری را برای ساخت و هماهنگ‌سازی عامل‌های هوش مصنوعی در اختیار شما قرار می‌دهد، مهارت‌های رابط خط فرمان عامل، نیروی عملیاتی را فراهم می‌کند. این کیت به توسعه‌دهندگان اجازه می‌دهد تا عامل‌ها را به صورت محلی با حلقه‌های بازخورد سریع، داربست‌بندی، آزمایش و مستقر کنند و به طور کامل از سربار سنگین رابط کاربری عبور کنند.

به صورت اختیاری، وقتی به Google Cloud نگاشت می‌شود، مهارت‌های رابط خط فرمان (CLI) عامل به عنوان یک خط لوله مستقیم به زیرساخت‌های سطح سازمانی عمل می‌کنند. به جای کلیک کردن از طریق کنسول‌ها، می‌توانید از دستورات CLI برای بسته‌بندی فوری گردش‌های کاری عامل، مدیریت مجوزهای دسترسی و استقرار آنها در اکوسیستم‌های Google Cloud (مانند Vertex AI یا Cloud Run) استفاده کنید. این امر وظایف پیچیده معماری ابری را به دستورات ترمینال ساده و قابل تکرار تبدیل می‌کند و ادغام عامل‌های خودمختار را در خطوط لوله استقرار CI/CD موجود بسیار آسان‌تر می‌کند.

نحوه نصب

مطمئن شوید که Python 3.11+ ، Node.js و مدیر بسته uv را نصب کرده‌اید. سپس، دستور راه‌اندازی را در ترمینال خود اجرا کنید:

uvx google-agents-cli setup

این دستور، فایل باینری agents-cli را نصب می‌کند و مهارت‌های تخصصی آن را برای چارچوب‌بندی و ارزیابی در محیط دستیار کدنویسی شما ثبت می‌کند.

توجه: مهارت‌ها در پوشه ~/.agents/skills نصب می‌شوند که برای Antigravity قابل مشاهده است. اگر می‌خواهید این مهارت‌ها را در Antigravity CLI مشاهده کنید، باید آنها را به پوشه ~/.gemini/antigravity-cli/skills (محدوده سراسری) منتقل کنید.

شما می‌توانید با پرسیدن اینکه کدام مهارت‌ها در Antigravity بارگذاری شده‌اند، بررسی کنید. یک نمونه پاسخ برای مهارت‌های رابط خط فرمان (CLI) که اخیراً نصب کرده‌ایم، در زیر نشان داده شده است.

راهنمای گام به گام

پس از اتمام uvx google-agents-cli setup ، می‌توانید یک عامل هوش مصنوعی را به‌طور کامل روی دستگاه محلی خود راه‌اندازی، با آن تعامل و آزمایش کنید.

مرحله 1: چارچوب‌بندی و مقداردهی اولیه یک پروژه عامل جدید

دستور creation را اجرا کنید تا یک طرح‌بندی استاندارد ایجاد شود. پس از ایجاد، قبل از اجرای هرگونه وظیفه اجرایی، باید وابستگی‌های پروژه آن را نصب کنید.

# 1. Create a lightweight prototype project structure
agents-cli create weather-assistant --prototype --yes

# 2. Move into the directory and install required ADK dependencies
cd weather-assistant
agents-cli install

چه اتفاقی در پشت صحنه می‌افتد: این یک فضای کاری تمیز شامل app/agent.py (کد اصلی شما)، pyproject.toml (متادیتای بسته) و agents-cli-manifest.yaml (ردیاب پروژه) ایجاد می‌کند.

مرحله ۲: اجرای یک کوئری تست محلی

یک تست سریع و مستقیم خط فرمان را روی عامل خود اجرا کنید. اگر از ADC (اعتبارنامه‌های پیش‌فرض برنامه) گوگل کلود استفاده نمی‌کنید، مطمئن شوید که GEMINI_API_KEY خود را در ترمینال خود صادر کرده‌اید. می‌توانید کلید API Gemini را از اینجا دریافت کنید. پس از دریافت کلید، آن را از طریق دستور زیر در ترمینال خود صادر کنید:

export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

دستور زیر را در ترمینال خود وارد کنید:

agents-cli run "How are you?"

آنچه در پشت صحنه اتفاق می‌افتد: رابط خط فرمان (CLI) چرخه حیات کیت توسعه عامل (ADK) را به طور کامل در حافظه ترمینال شما مقداردهی اولیه می‌کند. این رابط به طور ایمن اعلان را از طریق اعتبارنامه‌های محلی شما هدایت می‌کند و پاسخ پخش زنده را مستقیماً به خط فرمان شما گزارش می‌دهد.

مرحله ۳: شروع زمین بازی تعاملی وب

برای تعامل بصری با نماینده خود، محیط کاربری مبتنی بر وب داخلی و محلی را راه‌اندازی کنید.

agents-cli playground

آنچه در پشت صحنه اتفاق می‌افتد: رابط خط فرمان (CLI) یک سرور رابط کاربری وب ADK را راه‌اندازی می‌کند که معمولاً از طریق http://localhost:8080 یا http://127.0.0.1:8000 قابل دسترسی است و قابلیت بارگذاری مجدد در حین کار (hot-reloading) را نیز ارائه می‌دهد. از رابط وب، برنامه را در منوی کشویی «انتخاب یک برنامه» در بالا انتخاب کنید و با عامل در رابط مکالمه‌ای در سمت راست برنامه وب تعامل داشته باشید.

۷. نصب مهارت‌های عامل با استفاده از مهارت‌های npx

npx skills یک ابزار خط فرمان است که توسط Vercel Labs توسعه داده شده و به عنوان مدیر بسته برای عامل‌های هوش مصنوعی (مانند Antigravity، Claude Code، GitHub Copilot، Cursor و Cline) عمل می‌کند. این رابط خط فرمان (CLI) برای اکوسیستم مهارت‌های عامل باز است.

اگر می‌خواهید مهارت‌های Agent را با استفاده از بسته npx skills دانلود و نصب کنید، توجه داشته باشید که این بسته، مهارت‌ها را در پوشه ~/.agents/skills قرار می‌دهد. اگرچه اشاره می‌کند که ابزارهایی مانند Antigravity مهارت‌ها را از این پوشه دریافت می‌کنند، لطفاً توجه داشته باشید که در زمان نوشتن این مطلب، Antigravity آنها را از این پوشه دریافت می‌کند اما Antigravity CLI این کار را نمی‌کند. همانطور که قبلاً ذکر شد، باید این مهارت‌های نصب شده در پوشه ~/.agents/skills را در پوشه‌های project یا global scope for skills در Antigravity CLI کپی کنید، یعنی

محدوده پروژه : واقع در <project-root>/.agent/skills/ .
محدوده سراسری : واقع در ~/.gemini/antigravity-cli/skills/ .

۸. تبریک

تبریک! شما با موفقیت از Google Antigravity برای ساخت اولین مهارت Agent خود استفاده کردید، آن را پیکربندی کردید و قابلیت‌های سفارشی به آن اضافه کردید.

شما همچنین موفق شدید مجموعه‌ای از مهارت‌های عامل (Agent Skills) را در هر دو محدوده پروژه و سراسری پیکربندی کنید و ابزارهای سفارشی‌سازی‌شده را به کار بگیرید!.

اکنون آماده‌اید تا Antigravity کارهای سنگین پروژه‌های شما را انجام دهد و به روش شما کدنویسی کند.

نشان 5 روزه Kaggle AI Agents خود را کسب کنید

آیا این آزمایشگاه را به عنوان بخشی از دوره آموزشی ۵ روزه «عوامل هوش مصنوعی: دوره فشرده کدنویسی وایب با گوگل» در Kaggle به پایان رسانده‌اید؟ نشان تکمیل دوره را دریافت کنید: نشان «عوامل هوش مصنوعی ۵ روزه» را دریافت کنید.

۹. اسناد مرجع

Codelab: شروع کار با Google Antigravity
سایت رسمی: https://antigravity.google/
مستندات: https://antigravity.google/docs
دانلود: https://antigravity.google/download
مستندات مهارت‌های ضدجاذبه: https://antigravity.google/docs/skills