المهارات

explain-diff-html: مهارة Claude Code لتحويل PR وdiff البرمجي إلى صفحة HTML شرح من صفحة واحدة

الخيار الأنسب عندما تريد داخل Claude Code تحويل PR أو diff برمجي إلى صفحة HTML مكتفية ذاتيًا للشرح؛ وقبل الاستخدام تحتاج بيئة POSIX shell (Linux/macOS أو WSL/Git Bash) وgit، وشرح PR يتطلب gh مُصادقًا، وتُحفظ الصفحات المُولّدة في code-explanations داخل المجلد المنزلي.

Official source · explain-diff-html

Install

git clone https://github.com/malav2110/explain-diff-html.git ~/.claude/skills/explain-diff-html

لمن يصلح

  • يصلح لمن يريد فهم تغيير برمجي بسرعة داخل Claude Code: مثل الانتقال للعمل على مستودع غير مألوف، أو مراجعة PR لأحدهم، أو ترك شرح قابل للمشاركة للزملاء عن «ماذا غيّرت هذه التغييرات ولماذا».
  • يحوّل تغييرات الكود إلى صفحة HTML تعليمية مكتفية ذاتيًا من صفحة واحدة، تُكتب خارج المستودع ولا تلمس كودك.
  • الحالات غير المناسبة: العمل خارج Claude Code، أو الحاجة إلى PowerShell أو cmd.exe (غير مدعومين رسميًا؛ يتطلب shell متوافقًا مع POSIX)، أو الرغبة في تعديل الكود أو التراجع عنه مباشرة ( فهو يولّد صفحات شرح فقط). كل تشغيل يحتاج git؛ وشرح pull request يتطلب gh مُصادقًا (تحقق بـ gh auth status)؛ والصفحات التي ترسم مخططات Mermaid تُحمّل مكتبة الرسم من CDN فتحتاج اتصالًا بالشبكة. ما عدا ذلك، أي اعتماديات أو قيود لم يذكرها المطوّر الرسمي لا نخمّن عنها هنا.

أول تجربة في 3 دقائق

المتطلبات المسبقة: تثبيت Claude Code، وبيئة Linux أو macOS أو WSL / Git Bash على Windows، ووجود git على جهازك.

التثبيت: استنسخ المستودع إلى مجلد skills العام لـ Claude Code (المسار الرسمي الرئيسي):

git clone https://github.com/malav2110/explain-diff-html.git \
  ~/.claude/skills/explain-diff-html

إذا أردت استخدامه في مشروع واحد فقط، فالتعليمات الرسمية تقول باستنساخه إلى <your-repo>/.claude/skills/explain-diff-html بدلًا من ذلك.

يُنصح للمهمة الأولى باختيار محاولة قراءة فقط منخفضة المخاطر: أرسل في Claude Code جملة بلغة طبيعية مثل "explain PR 1234" (موجهة إلى PR في مستودع عام لا تملك صلاحية الدمج فيه وتكتفي بالمتابعة عن بُعد). لا يحتاج هذا الإجراء أي خطوات إضافية غير gh، لكن تأكد أولًا من نجاح gh auth status.

إشارة النجاح: يكتب الـ skill صفحة الشرح إلى مجلد code-explanations في مجلد منزلك، باسم ملف على شكل YYYY-MM-DD-<KEY>-explanation.html، ثم يبلّغك بالمسار. رؤية هذا المسار وملف HTML المُولّد تعني اكتمال العملية. ملاحظة: صفحة شرح الكود فقط يمكن فتحها دون اتصال؛ أما إذا احتوت صفحة Mermaid لمخططات حالات أو تسلسل وما شابه، فيلزم الاتصال بالشبكة لعرض الرسومات.

ذكرت الوثائق الرسمية فقط أن أمره يعمل على POSIX shell، ولم تذكر ما إذا كان يقرأ أو يكتب ملفات أخرى، أو ما الأوامر الداخلية ينفذها، أو أي نقاط شبكية يصل إليها؛ هذه سلوكيات غير معروفة.

حالات الاستخدام

الحالة الأولى: فهم PR. السيناريو: تريد الاطلاع على تغييرات في مستودع مفتوح المصدر غير مألوف لك. قل في Claude Code: "explain PR 1234". يسير الـ skill في مسار شرح PR الخاص به ويولّد صفحة HTML واحدة تشرح التدفق المنطقي للتغيير. النتيجة المتوقعة صفحة باسم تاريخي داخل $HOME/code-explanations؛ بشرط أن يكون gh مُصادقًا. أما احتواء الصفحة على مخططات Mermaid أم لا فيتوقف على التغيير نفسه، وعند وجودها يلزم اتصال بالشبكة لفتح الصفحة.

الحالة الثانية: فهم diff محلي. السيناريو: أتممت أو سحبتَ commit في مستودعك للتو وتريد شرحه لفريقك بوضوح. استخدم لغة طبيعية في Claude Code لتطلب منه شرح هذا التغيير. المؤكد أنه سيُخرج صفحة HTML تعليمية مكتفية ذاتيًا من النوع نفسه، في مجلد code-explanations ذاته مع الإبلاغ عن المسار؛ ولم تدرج الوثائق الرسمية صيغة أمر محددة لحالة diff المحلي، لذا فالمؤكد ينتهي عند «وصف التغيير بجملة بلغة طبيعية»، وعبارات الاستدعاء الدقيقة يُرجع فيها إلى README الخاص بالمستودع.

حدود الاستخدام

  • الملفات والشبكة: يكتب ملف HTML المُولّد إلى $HOME/code-explanations (بوضع مقصود خارج المستودع) ولا يكتب شيئًا داخل مستودعك؛ وعند احتواء الصفحة على مخططات Mermaid تُحمّل مكتبة الرسم من CDN ويلزم اتصال بالشبكة. ما عدا ذلك، لم تذكر الوثائق الرسمية ما إذا كان يقرأ أو يكتب ملفات أخرى أو ما الأوامر ينفذها.
  • نقاط التحقق: شغّل gh auth status للتأكد من المصادقة قبل شرح PR؛ وأمر التوليد نفسه ينشئ ملف HTML جديدًا، فمن يهتم بظهور ملفات جديدة ينبغي أن يعي ذلك قبل البدء.
  • بيئة التشغيل: يعمل مباشرة على Linux وmacOS، وعلى Windows يلزم WSL أو Git Bash؛ وPowerShell وcmd.exe غير مدعومين صراحةً. كل تشغيل يحتاج git؛ وسيناريو PR يحتاج gh مُصادقًا؛ والتحقق من مخططات Mermaid يحتاج node عبر npx.
  • القيود الرسمية: الإخراج يُكتب دائمًا إلى مجلد code-explanations في المجلد المنزلي؛ والصفحة مكتفية ذاتيًا وقابلة للفتح دون اتصال عدا CDN الخاص بـ Mermaid.
  • معلومات غير مؤكدة: لم تذكر الوثائق الرسمية لغات النصوص التي يدعمها، ولا ما إذا كان يعمل مع وكلاء آخرين غير Claude Code؛ فاعتمد على أحدث وثائق المستودع في ذلك ولا تستنتج من قوائم العملاء.