چیت‌شیت

مهارت‌های ایجنت: شناسایی، فراخوانی، مسیریابی

Agent Skills: Discovery, Invocation, Routing

نوشتن، نصب، شناسایی، فراخوانی و مسیریابی بسته‌های SKILL.md. پروژه‌های اعتبارسنج‌ها، کاتالوگ‌ها، مسیریاب و نصاب.

  • ۱۰ بخش
  • ۳ درس مرتبط
  • کد و دستورها عیناً از دوره‌ی اصلی
فهرست مطالب
  1. چرخه حیات مهارت
  2. نصب، فراخوانی، حذف
  3. اجرا و نمره‌دهی پروژه
  4. اعتبارسنجی، کاتالوگ‌بندی، افشا، مسیریابی (درس‌ها)
  5. مسیریاب و نصاب (پروژه‌ها)
  6. فراخوانی توسط انسان و مدل
  7. محدودیت‌ها و پیش‌فرض‌ها
  8. خرابی‌ها و راه‌حل‌ها
  9. قواعد نگارش
  10. پرسش‌ها

چرخه حیات مهارت

گام‌به‌گام
  1. شناساییبسته‌ها را در مکان‌های پیکربندی‌شده پیدا می‌کند.
  2. اعتبارسنجیبسته‌های معیوب یا ناامن را پیش از ورود به کاتالوگ رد می‌کند.
  3. کاتالوگ‌بندیفقط name و description را نمایان می‌کند.
  4. انتخابمشخص می‌کند آیا مهارت به درخواست مربوط است یا نه.
  5. فعال‌سازیبدنه را در کانتکست قابل‌مشاهده توسط مدل بارگذاری می‌کند.
  6. افشامراجع یا دارایی‌ها را فقط در صورت نیاز یک branch می‌خواند.
  7. اجرااز ابزارهای میزبان تحت مجوزها و قواعد ایزولاسیون میزبان استفاده می‌کند.
  8. راستی‌آزماییدست‌سازه را مستقل از ادعای مدل بررسی می‌کند.

نصب، فراخوانی، حذف

دستورها
دستورکارکرد
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: trueuser-invocable: falseتعریف‌نشده
مثالبرنامه‌ریزی تستآماده‌سازی انتشارراهنمای نگارش داخلیبسته منسوخ‌شده

محدودیت‌ها و پیش‌فرض‌ها

پیش‌فرض‌ها
تنظیمپیش‌فرضنکته
`name` length64کلمات با حروف کوچک متصل با خط تیره
`description` length1024بیان چیستی و زمان اجرا
`compatibility` length500فیلد اصلی اختیاری
max_description_chars240CatalogBudget به ازای هر ورودی
max_catalog_chars8_000مجموع CatalogBudget
max_chars12_000بارگذاری‌های بدنه و مرجع
model_threshold0.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؟
ابزار برای قابلیت خارجی تیپ‌بندی‌شده؛ مهارت برای روال و فرایند.
آیا نام صریح خط‌مشی‌ها را دور می‌زند؟
خیر. همچنان از تمام گیت‌ها عبور می‌کند.
آیا مسیریاب مهارت را اجرا می‌کند؟
خیر. فقط طرح‌ها و توضیحات را صادر می‌کند.
آیا نصب موفق، فعال‌سازی را اثبات می‌کند؟
خیر. ایجنت باید آن را شناسایی کند.