معرفی مهارت: hook-development — اتوماسیون رویدادمحور برای Claude Code

خلاصه. مهارت hook-development از مخزن anthropics/claude-plugins-official مرجع رسمی برای ساخت هوک‌های رویدادمحور در Claude Code است. این مهارت ۹ رویداد چرخه‌حیات، یک API هوک مبتنی بر prompt که از LLM برای تصمیم‌گیری زمینه‌محور استفاده می‌کند، و قوانین تفکیک مسیر ${CLAUDE_PLUGIN_ROOT} را که اسکریپت‌های شما را قابل‌حمل نگه می‌دارد، مستند می‌کند. این مهارت در مرحله بازبینی خودکار ما ۸۹ از ۱۰۰ امتیاز گرفت — بالاترین در کل کاتالوگ تا کنون.

در این صفحه

1. hook-development چیست؟
2. چه زمانی باید از آن استفاده کرد؟
3. چطور آن را نصب می‌کنیم؟
4. Claude Code چه رویدادهایی صادر می‌کند؟
5. الگوی هوک مبتنی بر prompt چیست؟
6. مسیرهای ${CLAUDE_PLUGIN_ROOT} چگونه تفکیک می‌شوند؟
7. اشتباهات رایج کدام‌اند؟
8. مهارت‌های مرتبط
9. پرسش‌های متداول

hook-development چیست؟

hook-development یک مهارت Claude است که به ایجنت می‌آموزد چگونه برای پلاگین‌های Claude Code هوک‌های رویدادمحور بنویسد. هوک‌ها اسکریپت‌های کوتاه (یا پرامپت‌های LLM) هستند که در پاسخ به رویدادهای خاص چرخه‌حیات اجرا می‌شوند — وقتی ابزاری در حال اجرا شدن است، وقتی نشست شروع می‌شود، وقتی ایجنت متوقف می‌شود — و می‌توانند رویداد را اعتبارسنجی، تغییر یا مسدود کنند. این مهارت ۹ نوع رویداد را با نمونه‌های اجرایی JSON، دو فرمت پیکربندی (پلاگین hooks.json در برابر تنظیمات کاربر .claude/settings.json) و قوانین تفکیک مسیر ${CLAUDE_PLUGIN_ROOT} ارائه می‌دهد.

نویسنده آن Anthropic است و در anthropics/claude-plugins-official در کنار حدود دو دوجین مهارت رسمی دیگر (نوشتن PDF، اتصال Slack، تحلیل codeql) عرضه می‌شود — اما hook-development همان مهارتی است که Claude Code را از یک چت‌بات به یک محیط اجرای برنامه‌پذیر تبدیل می‌کند.

چه زمانی باید از آن استفاده کرد؟

هر بار که می‌خواهید یک هوک را با دست بنویسید، به سراغ hook-development بروید. این مهارت زیر هزار توکن بارگذاری می‌شود و شما را از کشف دوباره فرمت در هر شش هفته نجات می‌دهد. تریگرهای مشخصی که پوشش می‌دهد، با بازنویسی از توضیحات رسمی:

• «مسدود کردن دستورات خطرناک» — جلوی rm -rf، git push --force و سایر عملیات مخرب را قبل از اجرا بگیرید.
• «اعتبارسنجی استفاده از ابزار» — آرگومان‌ها را قبل از اجرا با یک سیاست بسنجید.
• «افزودن context هنگام شروع نشست» — قراردادهای پروژه، مسیر سکرت‌ها، یا اطلاعات runtime را در هر گفتگوی جدید بارگذاری کنید.
• «اعمال استانداردهای تکمیل» — ایجنت را وادار کنید قبل از اعلام پایان، linterها را دوباره اجرا کند.
• «واکنش به نتایج ابزار» — فایل‌ها را پس از نوشتن خودکار format کنید، اعلان‌های Slack را پس از deploy ارسال کنید.

اگر از Claude Code بدون نوشتن پلاگین استفاده می‌کنید، به این مهارت نیاز ندارید. اما اگر در حال نوشتن پلاگین هستید و هرگز یک قطعه JSON از README کسی در GitHub کپی نکرده‌اید و امیدوار به کارش نبوده‌اید، به آن نیاز دارید.

چطور آن را نصب می‌کنیم؟

SkillHub CLI هر مهارت کاتالوگ را با یک فرمان در ~/.claude/skills/ نصب می‌کند. برای hook-development:

npx skillhub install anthropics/claude-plugins-official/hook-development
npx skillhub list | grep hook-development

اگر ترجیح می‌دهید روی یک commit مشخص pin کنید، منبع مهارت در anthropics/claude-plugins-official در GitHub موجود است. راهنمای شروع کار با SkillHub چرخه کامل نصب، از جمله نحوه حذف تمیز یک مهارت، را پوشش می‌دهد.

Claude Code چه رویدادهایی صادر می‌کند؟

Claude Code نُه نوع رویداد صادر می‌کند که هر کدام امضا و کاربرد متفاوتی دارند. این مهارت همه را با مثال فهرست می‌کند؛ این جدولی است که در روز اول کارتان آرزو می‌کنید داشته باشید:

بزرگ‌ترین بینش عملی این مهارت این است که کدام رویدادها API هوک مبتنی بر prompt (بخش بعد) را می‌پذیرند و کدام فقط فرمان قبول می‌کنند. PreToolUse، Stop، SubagentStop، و UserPromptSubmit هر دو را پشتیبانی می‌کنند؛ بقیه فقط فرمان.

الگوی هوک مبتنی بر prompt چیست؟

یک هوک مبتنی بر prompt هوکی است که بدنه آن یک دستورالعمل به زبان طبیعی است که در زمان اجرا توسط یک LLM ارزیابی می‌شود — به‌جای اجرای کد shell. این بخشی از سیستم هوک است که بیشتر تیم‌ها هنوز ندیده‌اند، و تغییر می‌دهد که هوک‌ها به چه دردی می‌خورند.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Inspect $TOOL_INPUT. If the command would touch files outside the current repo, exfiltrate secrets, or run as root, return blocked with a one-sentence reason. Otherwise return ok.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

همان هوک نوشته‌شده به‌صورت command یک اسکریپت bash شکننده از grepها و دستورات case خواهد بود. به‌صورت prompt، به فرمان‌هایی که هنگام نوشتن قاعده انتظارشان را نداشتید نیز تعمیم می‌یابد. این مهارت چهار نمونه کامل را شامل می‌شود — از جمله یکی که از prompt hook استفاده می‌کند تا اطمینان حاصل کند هر Stop پس از موفقیت تست‌ها رخ می‌دهد.

مسیرهای ${CLAUDE_PLUGIN_ROOT} چگونه تفکیک می‌شوند؟

${CLAUDE_PLUGIN_ROOT} در زمان اجرا به مسیر مطلق پلاگین نصب‌شده گسترش می‌یابد. این مهارت تأکید می‌کند چرا این مهم است: به‌جای مسیر hardcode شده "command": "${CLAUDE_PLUGIN_ROOT}/scripts/lint.sh" بنویسید، و همان هوک کار خواهد کرد چه پلاگین در ~/.claude/plugins/foo/ کلون شده باشد، چه در /opt/claude/plugins/foo/، چه در یک نصب containerized. بدون آن، هر نصب نیاز به بازنویسی مسیرها دارد؛ با آن، پلاگین‌ها قابل‌حمل می‌شوند.

اشتباهات رایج کدام‌اند؟

سه دامی که این مهارت آشکارا پرچم‌گذاری می‌کند:

1. سردرگمی فرمت. پلاگین hooks.json به wrapper {"hooks": {...}} نیاز دارد؛ تنظیمات کاربر .claude/settings.json رویدادها را مستقیم در سطح بالا قرار می‌دهد. مخلوط کردن آن‌ها بی‌سروصدا یک باگ «هوک هرگز فراخوانی نمی‌شود» تولید می‌کند که اشکال‌زدایی آن خسته‌کننده است.
2. گم‌کردن matcher. بدون "matcher": "Bash" روی یک هوک PreToolUse، آن روی هر ابزاری فراخوانی می‌شود — از جمله Read و Edit، که معمولاً منظور شما نبوده.
3. برخورد با هوک‌های prompt مانند assertion. آن‌ها قضاوت‌اند. می‌توانند اشتباه باشند. هوک‌های prompt پرریسک (PreToolUse روی Bash) را با یک سیستم ایمنی command deterministic جفت کنید برای مواردی که می‌توانید به‌صورت کد بیان کنید.

مهارت‌های مرتبط

اگر hook-development با گردش کار شما سازگار است، سه مهارت Pass-rated دیگر با آن جمع‌پذیرند:

• writing-skills — متامهارت از sickn33/antigravity-awesome-skills در نحوه نوشتن فایل‌های SKILL.md. هنگام عرضه پلاگینی که هر دو را در bundle دارد جفت کنید.
• codeql از trailofbits/skills — به‌عنوان یک هوک PostToolUse روی Write برای اسکن امنیتی نصب می‌شود.
• design-review از garrytan/gstack — تناسب طبیعی به‌عنوان یک هوک Stop برای هر پروژه‌ای که UI را لمس می‌کند.

بقیه کاتالوگ را در skills.palebluedot.live مرور کنید، یا اگر تازه با SkillHub آشنا می‌شوید، راهنمای شروع کار را بخوانید. آرشیو کامل معرفی مهارت بالاترین aiScoreها را همانطور که عرضه می‌شوند دنبال می‌کند.

پرسش‌های متداول