چطور با npx skills اسکیل نصب کنیم و از خطای -g فرار کنیم؟

npx skills با پرچم -g خطا می‌دهد و پیش از همان خطا ۵۵ پوشه در خانه‌ی شما می‌سازد. ریشه‌اش در جدول ایجنت‌های خود پروژه است: Eve و PromptScript مسیر سراسری ندارند. راه درست یا دادن -a است یا برداشتن -g. اندازه‌های زیر روی یک خانه‌ی کاملاً تازه اندازه گرفته شده‌اند.

این خط فرمان چه چیزی نصب می‌کند

پروژه‌ی vercel-labs/skills خودش را «the open agent skills tool» معرفی می‌کند. یک بسته‌ی npm به نام skills که بدون npm install و فقط با npx اجرا می‌شود[1][4].

لحظه‌ی خواندن: ۱۷ مهر ۱۴۰۵. ریپو ۳۳٬۴۴۹ ستاره و ۲٬۸۶۱ فورک دارد، آخرین push همان روز ساعت ۱۷:۴۳ به وقت UTC بوده و مجوزش MIT است[1].

جدول پشتیبانی ۶۸ سطر دارد و روی هم ۷۹ شناسه‌ی ایجنت می‌دهند، چون چند سطر شناسه‌های هم‌خانواده را در یک سلول جمع کرده‌اند. تیتر README چهار نام را می‌شمارد و می‌گوید «and 75 more»، که با همان ۷۹ شناسه جور درمی‌آید[2].

چرا نصب سراسری شکست خورد

روش گفته‌شده در README یک فرمان است. همان فرمان در حالت سراسری روی این ماشین شکست خورد. در یک خانه‌ی کاملاً تازه این را اجرا کردم:

# نصب سراسری یعنی در خانه، نه در پوشه‌ی پروژه
$ npx -y skills@latest add vercel-labs/agent-skills -s web-design-guidelines -g -y --json
[
  {
    "name": "web-design-guidelines",
    "status": "failed",
    "error": "Eve does not support global skill installation"
  }
]

کد خروج ۱ است و خطا از جنس انکار درخواست است، نه انکار وجود اسکیل. دلیلش در جدول ایجنت‌ها نوشته شده است: ردیف Eve ستون مسیر سراسری را N/A (project-only) پر کرده و همین برای PromptScript هم تکرار شده[2]. پس نصب سراسری برای این دو ایجنت از نظر ساختاری ممکن نیست.

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

# چند مسیر برای همان یک اسکیل ساخته شده است؟
$ find . -path ./.npm -prune -o -name 'web-design-guidelines' -print | wc -l
55

# و آیا هر ایجنت کپی مستقل دارد یا همه یک کپی را می‌بینند؟
$ ls -la .claude/skills/ .agents/skills/
.claude/skills:
lrwxrwxrwx web-design-guidelines -> ../../.agents/skills/web-design-guidelines

.agents/skills:
drwxr-xr-x web-design-guidelines

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

این پدیده به یک نام محدود نیست. آزمایش جداگانه با متغیر HERMES_HOME خطای PromptScript does not support global skill installation داد و بدون هیچ متغیر محیطی خطای Eve. یعنی تشخیص خودکار ایجنتِ در حال اجرا به آن اندازه هم قابل اتکا نیست که مبنای یک نصب سراسری باشد.

دو راه درست برای نصب

راه اول این است که نام ایجنت را خودتان بدهید. همان فرمان با یک تفاوت کوچک موفق می‌شود:

# تنها تفاوت با فرمان شکست‌خورده: -a claude-code اضافه شد
$ npx -y skills@latest add vercel-labs/agent-skills -s web-design-guidelines -g -y -a claude-code --json
[
  {
    "name": "web-design-guidelines",
    "status": "installed",
    "source": "vercel-labs/agent-skills",
    "hash": "a6a44d5498f7e8f68289902f3dedfc6f38ae0cee1e96527c80724cf27f727c2a",
    "scope": "global",
    "agents": [ "Claude Code" ],
    "mode": "copy"
  }
]

مقدار mode اینجا copy است، یعنی هر ایجنت کپی مستقل خودش را می‌گیرد. پرچم --copy همین حالت را برای وقتی اجباری می‌کند که سیستم شما پیوند نمادین را پشتیبانی نمی‌کند[2].

راه دوم این است که -g را بردارید. در حالت پروژه‌ای محدودیت project-only دیگر معنا ندارد و همان اسکیل برای بیست‌وپنج ایجنت از جمله Eve و PromptScript نصب می‌شود:

# در پوشه‌ی پروژه و بدون -g
$ npx -y skills@latest add vercel-labs/agent-skills -s web-design-guidelines -y --json
  "scope": "project",
  "agents": [ "Amp", "Claude Code", "Codex", "Eve", "PromptScript", ... ],
  "mode": "symlink"

$ cat skills-lock.json
{
  "version": 1,
  "skills": {
    "web-design-guidelines": {
      "source": "vercel-labs/agent-skills",
      "skillPath": "skills/web-design-guidelines/SKILL.md",
      "computedHash": "a6a44d5498f7e8f68289902f3dedfc6f38ae0cee1e96527c80724cf27f727c2a"
    }
  }
}

تله‌ی نام پوشه

در vercel-labs/agent-skills نام پوشه با نامی که CLI فهرست می‌کند یکی نیست. پوشه‌ی composition-patterns در گیت‌هاب، در سرآیند فایل خودش name: vercel-composition-patterns دارد و فهرست هم همان نام دوم را نشان می‌دهد[6]. مسیر واقعی فایل در ریپو skills/composition-patterns/SKILL.md است و همین مسیر در فایل قفل هم ثبت می‌شود[7]. با نام پوشه، نصب رد می‌شود:

# نام پوشه در گیت‌هاب
$ npx -y skills@latest add vercel-labs/agent-skills -s composition-patterns -y --json
[
  {
    "name": "composition-patterns",
    "status": "skipped",
    "reason": "No matching skill found in source"
  }
]

همین تله در پست اسکیل answer-me-with-html هم دیده می‌شود: آنجا نامی که در --skill آمده با نام پوشه‌ی مخزن یکی بود، پس نصب بی‌سروصدا رد می‌شد و skills ls آن را در فهرست خانه نشان می‌داد در حالی که در پروژه نبود. راه امن، خواندن فهرست با -l پیش از نصب است:

# فهرست اسکیل‌های موجود، بدون نصب چیزی
$ npx -y skills@latest add vercel-labs/agent-skills -l
◇  Found 9 skills

پست پیش‌پرواز یینگزاو از همین خط فرمان نصب استفاده می‌کرد و فایل قفل را در پوشه‌ی پروژه دید؛ آن قفل همان skills-lock.json نسخه‌ی ۱ است که اینجا اندازه گرفتیم.

سه فرمان دیگر که به کار می‌آیند

اگر فقط می‌خواهید یک بار یک اسکیل را امتحان کنید، skills use هیچ چیزی نصب نمی‌کند. متن کامل SKILL.md را روی خروجی می‌ریزد تا به هر ایجنتی که دارید لوله کنید:

# بدون نصب: فقط متن اسکیل، آماده‌ی لوله کردن به ایجنت
$ npx -y skills@latest use vercel-labs/agent-skills@web-design-guidelines -s web-design-guidelines
You are being given a Skill to execute for the user's next request.

Use the following SKILL.md as your instructions:

<SKILL.md>
---
name: web-design-guidelines
description: Review UI code for Web Interface Guidelines compliance.
...

خود اسکیل یک نکته‌ی دیگر دارد که در فهرست دیده نمی‌شود: قواعدش را هنگام اجرا از بیرون می‌خواند، نه از متن نصب‌شده. مسیر خواندن در خود SKILL.md نوشته شده و به فایل command.md در ریپوی web-interface-guidelines اشاره می‌کند[8]. پس اگر قواعد را تغییر دهید، نسخه‌ی نصب‌شده لازم نیست عوض شود؛ هر بار که اسکیل اجرا می‌شود تازه خوانده می‌شود.

پس پیش از نصب، همان بررسی امنیتی را نگاه کنید. در خروجی --json هر نصب یک بخش security دارد که نتیجه‌ی سه موتور را جدا گزارش می‌کند و لینک گزارش را هم می‌دهد. این مخزن در اجرای ما با وضعیت safe، بدون هشدار Socket و ریسک پایین Snyk برگشت[9]. این بررسی روی ریپوهایی که گیت‌هاب عمومی‌شان را تأیید کند انجام می‌شود[2].

سه فرمان پایانی کار روزمره را پوشش می‌دهند. فرمان skills ls -g فهرست سراسری را با مسیر هر اسکیل می‌دهد، skills update -g -y همه را با منبعشان به‌روز می‌کند و skills remove یک اسکیل را از ایجنت مشخص پاک می‌کند و ورودی‌اش را از فایل قفل هم برمی‌دارد.

در این اجرا، update پیام «GitHub API unavailable; checking via Git clone» داد و بعد «All global skills are up to date» نوشت. یعنی بدون توکن مسیر کلون git را می‌رود؛ اگر سرعت برایتان مهم است، GITHUB_TOKEN را در محیط بگذارید[2]. خود CLI هم تله‌متری می‌فرستد که با DO_NOT_TRACK=1 یا DISABLE_TELEMETRY=1 خاموش می‌شود. شمار مسئله‌های باز پروژه هم عدد خوبی برای سنجش بلوغ است و در زمان خواندن این پست روی صفحه‌ی مسئله‌ها دیده می‌شد[10].

منابع

1. مخزن vercel-labs/skills، خوانده‌شده در ۱۷ مهر ۱۴۰۵
2. README همان مخزن: جدول ایجنت‌ها، دامنه‌ها و روش‌های نصب
3. package.json: کمینه‌ی node و دو فرمان CLI
4. صفحه‌ی بسته‌ی skills روی npm
5. رجیستری npm: نسخه‌ی latest و شمار نسخه‌های منتشرشده
6. مخزن vercel-labs/agent-skills، منبع اسکیل نصب‌شده در این اجرا
7. پوشه‌ی اسکیل web-design-guidelines
8. قواعدی که خود اسکیل هنگام اجرا می‌خواند
9. گزارش بررسی امنیتی که در خروجی JSON به آن ارجاع داده شد
10. مسئله‌های باز مخزن vercel-labs/skills