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

نحوه استفاده از مهارت‌های عامل هوش مصنوعی (با Gemini CLI و مهارت‌های عامل برای Firebase)

۱. مقدمه

عکس روی جلد آزمایشگاه مهارت‌های مامورین

در این آزمایشگاه، شما یاد خواهید گرفت که چگونه مهارت‌های عامل (Agent Skills) را ایجاد کنید تا LLMها به دانش و گردش‌های کاری سفارشی دسترسی داشته باشند. شما آن را به عنوان یک مهارت محلی ایجاد خواهید کرد که از طریق Gemini CLI قابل دسترسی است.

کاری که انجام خواهید داد

مهارت‌های عامل خودتان را برای چیزهای مورد علاقه‌تان ایجاد کنید.
از Gemini CLI برای بررسی مهارت خود استفاده کنید.
مهارت‌های رسمی Agent را برای Firebase نصب کنید و از آنها برای ساخت و استقرار یک برنامه استفاده کنید.

آنچه یاد خواهید گرفت

چگونه یک مهارت را ساختارمند کنیم.
نحوه نوشتن فایل SKILL.md .
نحوه استفاده از مهارت‌های محلی با Gemini CLI.

۲. راه‌اندازی پروژه

اگر از قبل حساب گوگل ندارید، باید یک حساب گوگل ایجاد کنید .
- به جای حساب کاری یا تحصیلی از حساب شخصی استفاده کنید. حساب‌های کاری و تحصیلی ممکن است محدودیت‌هایی داشته باشند که مانع از فعال کردن APIهای مورد نیاز برای این آزمایشگاه توسط شما شود.
وارد کنسول ابری گوگل شوید.
فعال کردن پرداخت در کنسول ابری
- تکمیل این آزمایشگاه باید کمتر از ۱ دلار آمریکا از طریق منابع ابری هزینه داشته باشد.
- شما می‌توانید مراحل انتهای این آزمایش را برای حذف منابع دنبال کنید تا از هزینه‌های بیشتر جلوگیری شود.
- کاربران جدید واجد شرایط استفاده از دوره آزمایشی رایگان ۳۰۰ دلاری هستند.
یک پروژه جدید ایجاد کنید یا از یک پروژه موجود دوباره استفاده کنید.
- اگر در مورد سهمیه پروژه خطایی مشاهده کردید، از یک پروژه موجود دوباره استفاده کنید یا یک پروژه موجود را حذف کنید تا یک پروژه جدید ایجاد شود.

۳. ویرایشگر Cloud Shell را باز کنید

برای دسترسی مستقیم به ویرایشگر Cloud Shell ، روی این لینک کلیک کنید.
اگر امروز در هر مرحله‌ای از شما خواسته شد که مجوز دهید، برای ادامه روی تأیید کلیک کنید.
اگر ترمینال در پایین صفحه نمایش داده نشد، آن را باز کنید:
- روی مشاهده کلیک کنید
- روی ترمینال کلیک کنید
در ترمینال، پروژه خود را با این دستور تنظیم کنید:
- قالب:
```
gcloud config set project [PROJECT_ID]
```
- مثال:
```
gcloud config set project lab-project-id-example
```
- اگر نمی‌توانید شناسه پروژه خود را به خاطر بیاورید:
  - شما می‌توانید تمام شناسه‌های پروژه خود را با دستور زیر فهرست کنید:
```
gcloud projects list | awk '/PROJECT_ID/{print $2}'
```
شما باید این پیام را ببینید:
```
Updated property [core/project].
```
اگر یک WARNING مشاهده کردید و از شما پرسیده شد Do you want to continue (Y/n)? احتمالاً شناسه پروژه را اشتباه وارد کرده‌اید. n را فشار دهید، Enter را بزنید و دوباره سعی کنید دستور gcloud config set project اجرا کنید.

۴. مهارت «چیزهای مورد علاقه» خود را ایجاد کنید

مهارت‌های عامل، دایرکتوری‌هایی هستند که حداقل حاوی یک فایل SKILL.md هستند که دستورالعمل‌ها و دانش را در اختیار یک عامل هوش مصنوعی قرار می‌دهند. در این بخش، شما مهارتی ایجاد خواهید کرد که به Gemini CLI در مورد چیزهای مورد علاقه‌تان آموزش می‌دهد.

یک دایرکتوری برای این آزمایشگاه ایجاد کنید و به داخل آن بروید:
```
mkdir ~/agent-skills-lab && cd ~/agent-skills-lab
```
یک دایرکتوری برای مهارت پروژه خود ایجاد کنید:
```
mkdir -p ~/agent-skills-lab/.agents/skills/my-favorite-things
```
یک فایل SKILL.md جدید برای مهارت خود ایجاد و باز کنید:
```
cloudshell edit ~/agent-skills-lab/.agents/skills/my-favorite-things/SKILL.md
```
دستور cloudshell edit فایل SKILL.md را در ویرایشگر بالای ترمینال باز می‌کند.

محتوای زیر را به فایل SKILL.md اضافه کنید:

---
name: my-favorite-things
description: Provides personal information about my favorite color, food, and programming language. Use this skill when the user asks questions about my personal preferences or favorite things.
---

# Knowledge

- **Favorite Color:** Blue
- **Favorite Food:** Pizza
- **Favorite Programming Language:** Python

If asked about one of my favorite things, please respond with the information provided above.

تنها با یک فایل SKILL.md ، شما اولین مهارت خود را ایجاد کرده‌اید! وقت آن است که از این مهارت در Gemini CLI استفاده کنید.

۵. از مهارت خود در Gemini CLI استفاده کنید

حالا که با موفقیت یک مهارت ایجاد کرده‌اید، توسط Gemini CLI قابل شناسایی است زیرا در دایرکتوری .agents/skills قرار دارد.

اجرای رابط خط فرمان Gemini:
```
gemini
```
باید ببینید که رابط خط فرمان Gemini مهارت جدید را تشخیص می‌دهد. ممکن است لازم باشد برای پذیرش برخی از تنظیمات پیش‌فرض، Enter فشار دهید.

از دوقلوها بخواهید مهارت‌های موجود در متن خود را فهرست کنند.
```
/skills
```
شما باید my-favorite-things در لیست مهارت‌های موجود ببینید.
از جوزا درباره رنگ مورد علاقه‌تان بپرسید:
```
What is my favorite color?
```
رابط خط فرمان Gemini باید از مهارت my-favorite-things برای پاسخ به سوال شما استفاده کند. در صورت درخواست، به Gemini CLI اجازه دهید از این مهارت استفاده کند.

خروجی باید نشان دهد که Gemini CLI از مهارت شما استفاده کرده و با چیزی مانند "آبی" یا "رنگ مورد علاقه من آبی است" پاسخ داده است.

شما موفق شدید! شما با موفقیت یک مهارت ایجاد کردید و آن را با استفاده از Gemini CLI آزمایش کردید.

وقتی آماده پایان دادن به جلسه خود شدید، عبارت /quit را تایپ کرده و سپس Enter را فشار دهید تا از Gemini CLI خارج شوید.

۶. (اختیاری) ساخت و استقرار یک برنامه در Firebase Hosting

علاوه بر ایجاد مهارت‌های خودتان، می‌توانید مهارت‌های ایجاد شده توسط دیگران را نصب کنید. این نشان دهنده استفاده از مهارت‌های قابل حمل است - ماژول‌های مستقلی از دانش، دستورالعمل‌ها و گردش‌های کاری که می‌توانند به راحتی به اشتراک گذاشته شوند و دوباره استفاده شوند.

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

حالا از Agent Skills for Firebase برای ایجاد یک برنامه وب "To Do" با احراز هویت کاربر و یک پایگاه داده استفاده کنید و آن را در Firebase Hosting مستقر کنید.

پروژه خود را تنظیم کنید

اگر هنوز در محیط خط فرمان Gemini هستید، برای خروج عبارت /quit را تایپ کنید.
یک دایرکتوری جدید برای پروژه خود ایجاد کنید و به داخل آن بروید:
```
mkdir ~/todo-app && cd ~/todo-app
```
با استفاده از حساب گوگل خود وارد فایربیس شوید. از آنجایی که در Cloud Shell هستید، از پرچم --no-localhost استفاده کنید:
```
firebase login --no-localhost
```
1. تعامل با دستورات CLI :
  - وقتی از شما پرسیده شد که Enable Gemini in Firebase features? )، Y (به معنای بله) را تایپ کنید و Enter فشار دهید.
  - وقتی از شما پرسیده شد Allow Firebase to collect CLI and Emulator Suite usage and error reporting information? Y (به معنای بله) را تایپ کنید و Enter را فشار دهید.
2. در مرورگر مجوز دهید :
  - یک URL در ترمینال مشاهده خواهید کرد. روی لینک کلیک کنید تا صفحه ورود در یک تب جدید مرورگر باز شود.
  - مرحله ۱ از ۳ (تأیید دستور) : روی بله، من همین الان این دستور را اجرا کردم کلیک کنید.
  - مرحله ۲ از ۳ (تأیید شناسه جلسه) : اطمینان حاصل کنید که شناسه جلسه با آنچه در ترمینال شما نشان داده شده است مطابقت دارد، سپس روی بله، این شناسه جلسه من است کلیک کنید.
  - مرحله ۳ از ۳ (کپی کردن کد) : برای کپی کردن کد مجوز در کلیپ‌بورد خود، روی کپی کلیک کنید.
3. ورود را تکمیل کنید :
  - به ترمینال Cloud Shell برگردید و کد مجوز را در قسمت ? Enter authorization code: prompt وارد کنید.
  - Enter فشار دهید.
شما باید یک پیام موفقیت‌آمیز ببینید: ✔ Success! Logged in as .

نصب مهارت‌های عامل برای فایربیس

اکنون که دایرکتوری پروژه خود را ایجاد کرده‌اید، باید Agent Skills for Firebase را درون آن نصب کنید.

شما می‌توانید مهارت‌های عامل (Agent Skills) برای فایربیس (Firebase) را با استفاده از خط فرمان مهارت‌ها (skills CLI) در ترمینال خود نصب کنید:

npx skills add firebase/agent-skills

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

firebase-basics
firebase-hosting-basics
firebase-auth-basics
firebase-firestore-enterprise-native-mode

انتخاب چهار مهارت فایربیس

برای درخواست‌های بعدی، می‌توانید با فشار دادن Enter پیش‌فرض‌ها را با خیال راحت بپذیرید.

این دستور، مهارت‌هایی از جمله firebase-basics و firebase-hosting-basics را دانلود و نصب می‌کند و آنها را برای استفاده در Gemini CLI در کنار مهارت my-favorite-things شما در دسترس قرار می‌دهد.

برای کسب اطلاعات بیشتر در مورد مهارت‌های عامل برای Firebase، به مهارت‌های موجود مراجعه کنید.

ایجاد و استقرار یک برنامه وب پایه

API های مورد نیاز پروژه خود را فعال کنید:

gcloud services enable \
  cloudresourcemanager.googleapis.com \
  firebase.googleapis.com

فعال کردن فایربیس در پروژه فعلی گوگل کلود شما:
```
firebase projects:addfirebase ${GOOGLE_CLOUD_PROJECT}
```
اجرای رابط خط فرمان Gemini:
```
gemini
```
از Gemini بخواهید یک index.html پایه ایجاد کند:
```
Generate an index.html file with the content "Hello Firebase Hosting" and
deploy the application to Firebase Hosting using the current Google Cloud
Project.
```
Gemini از شما می‌خواهد که index.html ایجاد و firebase اجرا کنید. برای اجازه دادن به آن، Enter فشار دهید. رابط خط فرمان Gemini باید از مهارت‌های عامل Firebase برای ایجاد و استقرار وب‌سایت شما استفاده کند. در صورت نیاز، عامل را با تأییدیه‌ها راهنمایی کنید.

وقتی کار نصب تمام شد، باید یک URL برای برنامه وب شما ارائه دهد. برای باز کردن لینک‌ها در ترمینال Cloud Shell Editor از ctrl+click (ویندوز) یا cmc+click (مک) استفاده کنید. به URL برنامه نصب شده خود مراجعه کنید!

اضافه کردن احراز هویت فایربیس

اگر Gemini CLI از قبل شروع نشده است، آن را اجرا کنید:
```
gemini
```
Gemini ممکن است سوالاتی مانند «آیا به این پوشه اعتماد دارید؟» بپرسد. برای پذیرش پیش‌فرض‌ها، Enter فشار دهید.
حالا، از Gemini بخواهید ورود به سیستم با گوگل را اضافه کند:
```
Generate HTML, CSS, and Javascript for a single page application.
It should use Google Sign-in with Firebase Authentication.
A user should be able to sign in with their Google Account.
Deploy when you are done and give the URL to the user.
```
ممکن است Gemini از شما بخواهد فایل‌هایی مانند index.html ، style.css و script.js را ایجاد یا به‌روزرسانی کند. به آن اجازه دهید این کار را انجام دهد. Gemini ممکن است از شما بخواهد در کنسول Firebase اقداماتی انجام دهید. اگر از CLI بخواهید، می‌تواند اکثر این کارها را انجام دهد، اما اگر نسخه قدیمی‌تری از Firebase CLI روی نمونه Cloud Shell شما نصب شده باشد، ممکن است انجام دستی مراحل (مانند فعال کردن Google OAuth) لازم باشد.

برای مشاهده‌ی آخرین تغییرات، ممکن است لازم باشد با استفاده از ctrl+shift+R (ویندوز) یا cmd+shift+R (مک) یک «تازه‌سازی سخت» (Hard Refresh) انجام دهید.

اضافه کردن کلود فایر استور

اگر Gemini CLI از قبل شروع نشده است، آن را اجرا کنید:
```
gemini
```
Gemini ممکن است سوالاتی مانند «آیا به این پوشه اعتماد دارید؟» بپرسد. برای پذیرش پیش‌فرض‌ها، Enter فشار دهید.

از Gemini بخواهید Firestore را برای ذخیره وظایف اضافه کند:

Update the application to save tasks in Cloud Firestore for the signed-in user.
A user should be able to add new tasks and see a list of their tasks.
Deploy when you are done and give the URL to the user.

جمینی فایل‌ها را به‌روزرسانی خواهد کرد. اجازه دهید این کار را انجام دهد.

اگر برنامه شما مطابق انتظار عمل نمی‌کند، برای رسیدن به عملکرد مورد انتظار، به کار با Gemini CLI ادامه دهید. مثال: shell Hide the task form when the user is logged out. Update the security rules so the user can see their TODOs.

برای اضافه کردن ویژگی‌هایی که می‌خواهید در برنامه جدید Firebase خود ببینید، به آزمایش با آزمایشگاه ادامه دهید.

۷. نتیجه‌گیری

تبریک! شما با موفقیت یک مهارت ایجاد کردید و یاد گرفتید که چگونه مهارت‌های اضافی را برای Gemini CLI نصب کنید.

(اختیاری) تمیز کردن

اگر می‌خواهید فضای ابری خود را پاک کنید، می‌توانید پروژه ابری خود را حذف کنید تا از هزینه‌های اضافی جلوگیری شود.

اگر مایلید، پروژه را حذف کنید:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

همچنین می‌توانید منابع غیرضروری را از دیسک Cloud Shell خود حذف کنید تا فضای بیشتری آزاد شود.

پوشه‌ی lab را حذف کنید (این کار هم مهارت و هم برنامه را حذف می‌کند):
```
rm -rf ~/agent-skills-lab
```
پوشه برنامه "To Do" را حذف کنید (اگر آن را در خارج از آن ایجاد کرده‌اید):
```
rm -rf ~/todo-app
```

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