چیتشیت
مهارتهای ایجنت: شناسایی، فراخوانی، مسیریابی
Agent Skills: Discovery, Invocation, Routing
نوشتن، نصب، شناسایی، فراخوانی و مسیریابی بستههای SKILL.md. پروژههای اعتبارسنجها، کاتالوگها، مسیریاب و نصاب.
فهرست مطالب
چرخه حیات مهارت
گامبهگام- شناساییبستهها را در مکانهای پیکربندیشده پیدا میکند.
- اعتبارسنجیبستههای معیوب یا ناامن را پیش از ورود به کاتالوگ رد میکند.
- کاتالوگبندیفقط
nameوdescriptionرا نمایان میکند. - انتخابمشخص میکند آیا مهارت به درخواست مربوط است یا نه.
- فعالسازیبدنه را در کانتکست قابلمشاهده توسط مدل بارگذاری میکند.
- افشامراجع یا داراییها را فقط در صورت نیاز یک branch میخواند.
- اجرااز ابزارهای میزبان تحت مجوزها و قواعد ایزولاسیون میزبان استفاده میکند.
- راستیآزماییدستسازه را مستقل از ادعای مدل بررسی میکند.
نصب، فراخوانی، حذف
دستورها| دستور | کارکرد |
|---|---|
npx skills add rohitg00/ai-engineering-from-scratch --skill skill-contract-reviewer --full-depth | نصب بسته تودرتو همراه با مراجع، اسکریپت و دارایی |
/skill-contract-reviewer <request> | فراخوانی صریح در یک میزبان با سینتکس /skill-name |
/skills | انتخاب یک مهارت بر اساس نام در رابط Codex |
python3 <SKILL_ROOT>/scripts/check_skill.py <TARGET_ROOT>/my-first-skill | اجرای اعتبارسنج بستهبندیشده. نمایش argv، cwd و کد خروج |
npx skills remove skill-contract-reviewer | حذف بسته. استفاده از همان میزبان و دامنه |
python3 scripts/install_skills.py /tmp/aiefs-skills --phase 13 --type skill | کپی بستههای Phase 13 و نوشتن manifest.json |
python3 -m unittest discover -s code/tests -v | اجرای مجموعهتستهای یک درس |
اجرا و نمرهدهی پروژه
کار و کد| وظیفه | کد |
|---|---|
| ایجاد فضای کاری فراگیر | python3 scripts/project_test.py skill-router --init learning-artifacts/skill-router |
| نمرهدهی به یک مرحله | python3 scripts/project_test.py skill-router --stage 1 --path learning-artifacts/skill-router |
| مسیریابی درخواست نمونه | node learning-artifacts/skill-router/cli.ts projects/skill-router/examples/skills projects/skill-router/examples/request.json |
| اجرای آزمایشی (dry run) نصب | node learning-artifacts/skill-installer/cli.ts inspect projects/skill-installer/examples/orchard-release.json codex |
| نصب واقعی | cli.ts install bundle.json agent root expected-source-digest |
| ساخت اعتبارسنج | rustc --edition=2021 learning-artifacts/skill-validator/cli.rs -o learning-artifacts/skill-validator/validator |
| اعتبارسنجی و بارگذاری در 2000 کاراکتر | validator projects/skill-validator/examples/orchard-release 2000 --activate references/restore.md |
| بررسی راهحل مرجع | python3 scripts/project_test.py skill-validator --all --solution --strict |
اعتبارسنجی، کاتالوگبندی، افشا، مسیریابی (درسها)
کدpython
report = validate_skill_text(text, directory_name, allowed_runtime_extensions=())
select_primitives(task) # code، skill، hook، subagent، tool
candidates = (*discover_scope(Scope("project", project_root)),
*discover_scope(Scope("user", user_root))) # فقط فرزندان مستقیم
catalog = build_catalog(candidates, precedence=("project", "user"),
budget=CatalogBudget(max_entries=10, max_catalog_chars=2_000))
body = load_skill_body(selected, candidates) # سطح 2
reference = load_reference(selected, "references/format.md") # سطح 3
validate_reference(skill_directory, reference) # مسدودسازی پیمایش مسیر و فرار (traversal & escape)
route_request(skills, request, adapter) # واجد شرایط بودن پیش از رتبهبندی
build_invocation_matrix(policy) # نمای انسان بر اساس مدل
مسیریاب و نصاب (پروژهها)
کدts
const skills = await loadCatalog(root); // SKILL.md بههمراه routing.json
rank(skills, query, files); // کلیدواژه 2، مسیر 3
plan(skills, selected, allowed); // وابستگیها در ابتدا
route(skills, query, files, allowed, margin = 1); // ready، no-match، ambiguous، blocked
safePath(name); // رد کردن ..، مسیر مطلق، :C، بکاسلش
const files = translate(bundle, agent); // هدر کوتیشندار جدید، همان بدنه
const expected = digest(bundle.files); // SHA-256 جفتهای مرتبشده
await install(root, bundle, agent, expectedDigest); // تغییر نام مرحلهای همراه با پشتیبان
فراخوانی توسط انسان و مدل
مقایسه| عامل | مشترک | فقط انسان | فقط مدل | غیرفعال |
|---|---|---|---|---|
| انسان میتواند فراخوانی کند | بله | بله | خیر | خیر |
| مدل میتواند فراخوانی کند | بله | خیر | بله | خیر |
| یک فیلد میزبان | پیشفرض | disable-model-invocation: true | user-invocable: false | تعریفنشده |
| مثال | برنامهریزی تست | آمادهسازی انتشار | راهنمای نگارش داخلی | بسته منسوخشده |
محدودیتها و پیشفرضها
پیشفرضها| تنظیم | پیشفرض | نکته |
|---|---|---|
`name` length | 64 | کلمات با حروف کوچک متصل با خط تیره |
`description` length | 1024 | بیان چیستی و زمان اجرا |
`compatibility` length | 500 | فیلد اصلی اختیاری |
max_description_chars | 240 | CatalogBudget به ازای هر ورودی |
max_catalog_chars | 8_000 | مجموع CatalogBudget |
max_chars | 12_000 | بارگذاریهای بدنه و مرجع |
model_threshold | 0.2 | کف انتخاب ضمنی |
Router `margin` | 1 | شکاف امتیازی کمتر، مبهم (ambiguous) است |
خرابیها و راهحلها
عیبیابیno-match- علت
- هیچ کلیدواژه یا مسیری امتیاز نگرفت
- راهحل
- افزودن
keywordsیاpathsدر routing.json
ambiguous- علت
- تفاضل دو امتیاز برتر کمتر از
marginاست - راهحل
- مرزهای تریگر را مجزا و تفکیک کنید
blockedبا خطایpermission denied- علت
- مهارت یا یک وابستگی به مجوزهای بیشتری نیاز دارد
- راهحل
- مجوز دهید یا مسیر دیگری انتخاب کنید
unsupported YAML syntax- علت
- تگ، نام مستعار (alias)، چندخطی یا مقدار جریان کاری (flow)
- راهحل
- استفاده از اسکالر ساده یا داخل دابل کوتیشن
integrity mismatch- علت
- دایجست بسته با دایجست مورد انتظار تفاوت دارد
- راهحل
- اجرای
inspectو مقایسهیsource_digest
modified installation- علت
- تغییر یک فایل ردیابیشده از زمان نصب
- راهحل
- انتقال ویرایش به بستهی سورس
عدم دسترسی به مهارت پس از نصب
- علت
- میزبان کاتالوگ خود را بازخوانی نکرده است
- راهحل
- آغاز یک نشست جدید یا اسکن مجدد، سپس تلاش دوباره
مدل هرگز مهارت را انتخاب نمیکند
- علت
- توضیحات مبهم یا برش به دلیل بودجه
- راهحل
- بررسی لاگ شناسایی و حجم کاتالوگ
قواعد نگارش
نکتههاnameباید با پوشهی والد یکسان باشد.- توضیحات: یک عبارت برای قابلیت، یک عبارت برای مرز تریگر.
- افزودن مرز منفی هنگام اشتراک کلمات دو مهارت. تست نمونههای منفی دشوار.
- ابتدا فیلتر بر اساس واجد شرایط بودن، سپس رتبهبندی. انصراف در صورت نبود امتیاز قوی کافی.
- آرگومانهای خام را درون دستورات شل درونریزی نکنید.
- نامگذاری مهارت وابسته و طرح پشتیبان. توقف در صورت عدم دسترسی.
پرسشها
پرسش و پاسخ- مهارت یا هوک؟
- هوک برای اجرای حتمی هر رویداد؛ مهارت برای قضاوت مدل.
- مهارت یا ابزار MCP؟
- ابزار برای قابلیت خارجی تیپبندیشده؛ مهارت برای روال و فرایند.
- آیا نام صریح خطمشیها را دور میزند؟
- خیر. همچنان از تمام گیتها عبور میکند.
- آیا مسیریاب مهارت را اجرا میکند؟
- خیر. فقط طرحها و توضیحات را صادر میکند.
- آیا نصب موفق، فعالسازی را اثبات میکند؟
- خیر. ایجنت باید آن را شناسایی کند.