الوحدة 6 — إنشاء أوامرك الخاصّة: skills من الألف إلى الياء

طافت الوحدات السابقة بالأوامر المُقدَّمة. تُعلِّم هذه الوحدة كيف تُضيف أوامرك: skills. منذ v2.1.199، الأوامر المخصَّصة وskills هي الشيء نفسه. ملفّ .claude/skills/deploy/SKILL.md وملفّ .claude/commands/deploy.md كلاهما يُنشئ /deploy؛ الصيغة القديمة تبقى مدعومة، لكنّ الجديدة تُضيف مجلّد ملفّات مساعدة، وfrontmatter أغنى، وإمكانيّة أن يُقرِّر Claude استدعاء skill لوحده. خلافًا لـCLAUDE.md، لا يُحمَّل جسم skill إلّا حين تُستدعى: مادّة مرجعيّة طويلة لا تُكلّف شيئًا تقريبًا ما دمنا لم نستعملها.

تشريح skill

skill مجلّد يحوي على الأقلّ ملفّ SKILL.md. اسم المجلّد يُصبح الأمر الذي نكتبه: .claude/skills/deploy/SKILL.md يُنشئ /deploy. يمكن للمجلّد أن يحوي ملفّات أخرى (سكربتات، مواصفات، أمثلة) يقرأها Claude عند الطلب. ملفّ SKILL.md جزآن: frontmatter YAML بين --- يصف skill (يستعمله Claude لتقرير تحميلها لوحده)، ومحتوى Markdown هو prompt المُرسَل إلى Claude حين تُستدعى skill. لا يُقرأ frontmatter إلّا إن كان --- أوّل سطر مطلقًا؛ وإلّا يعامل Claude Code كامل الملفّ كجسم.

---
description: Résume les changements non commités et signale ce qui est risqué. Utiliser quand l'utilisateur demande « qu'est-ce qui a changé ? » ou veut un message de commit.
---

## Changements en cours
!`git diff HEAD`

## Instructions
Résume en deux ou trois puces, puis liste les risques : gestion d'erreur absente, valeurs codées en dur, tests à mettre à jour. Si le diff est vide, dis-le.

السطر !`git diff HEAD` حقن ديناميكيّ: يُنفِّذ Claude Code أمر shell قبل الإرسال، ويستبدل مخرجه بالـplaceholder. يستقبل النموذج diff الحيّ، لا الأمر.

النطاقات: أين نُسجّل skill

سبعة مواقع تتعايش:

الموقع	المسار	تُحمَّل في
مؤسّسة	.claude/skills/<nom>/SKILL.md في الإعدادات المُدارة	الأجهزة التي تنشرها المؤسّسة
شخصيّة	~/.claude/skills/<nom>/SKILL.md	كلّ مشاريع الجهاز
مشروع	.claude/skills/<nom>/SKILL.md	كلّ جلسات المستودع
مُدمَجة	<sous-dossier>/.claude/skills/<nom>/SKILL.md	الجلسات المُطلَقة في/تحت <sous-dossier>، وإلّا حين يمسّ Claude ملفًّا في هذا المسار
مجلّد مُضاف	.claude/skills/<nom>/SKILL.md في مجلّد --add-dir	فقط هذه الجلسة
plugin	<plugin>/skills/<nom>/SKILL.md	حيث يكون plugin فعّالًا، تحت /<plugin>:<nom>
حساب claude.ai	skills المُفعَّلة على جانب claude.ai	Cowork والجلسات السحابيّة (الوحدة 15)

الأسبقيّة في التسمية المكرَّرة: مؤسّسة ← شخصيّة ← مشروع. ملفّ .claude/commands/ يتنازل أمام skill بالاسم نفسه. skill من plugin تُلحَق ببادئة. الاسم synced محجوز. skill المستودع تنطبق في -p حتّى في مجلّد غير موثوق: أعد قراءة allowed-tools قبل أيّ claude في المستودع.

المرجع الكامل لـfrontmatter

كلّ الحقول اختياريّة؛ description فقط مُوصى بها. Booléens: yes/no/on/off/1/0 علاوةً على true/false (v2.1.218+).

الحقل	الأثر
name	الاسم المعروض. افتراضًا، اسم المجلّد. لا يُغيّر الأمر الذي نكتبه، إلّا داخل plugin حيث يستبدل name المقطع الأخير.
description	ما تفعله skill ومتى تُستعمل. سقف مشترك مع when_to_use: 1 536 حرفًا.
when_to_use	سياق إضافيّ: عبارات مُطلِقة، أمثلة.
argument-hint	مساعدة للإكمال التلقائيّ: [fichier] [format].
arguments	قائمة مسمّاة للاستبدال $nom. سلسلة أو قائمة YAML.
disable-model-invocation	true يمنع Claude من تحميل skill لوحده (ومن إطلاقها عبر مهمّة مجدولة).
user-invocable	false يُخفي من قائمة /: يعمل الاستدعاء بواسطة Claude فقط.
allowed-tools	أدوات مسموح بها دون تأكيد خلال التور. يُلغى المنح في الرسالة التالية.
disallowed-tools	أدوات مُزالة من البركة خلال التور. لا يمكنه إزالة EndConversation إن بقيت أدوات أخرى.
model	نموذج لمدّة التور؛ القيم نفسها كـ/model، أو inherit.
effort	جهد للتور: low، medium، high، xhigh، max.
context	fork يُشغّل skill داخل وكيل فرعيّ معزول.
agent	نوع الوكيل الفرعيّ حين context: fork: Explore، Plan، general-purpose أو وكيل فرعيّ من .claude/agents/.
background	مع context: fork، false يحجب التور. الافتراضيّ true. v2.1.218+.
hooks	hooks مُسجَّلة عند الاستدعاء، فعّالة للجلسة.
paths	أنماط glob تحدّ الاستدعاء التلقائيّ بالملفّات المطابقة.
shell	bash (افتراضيّ) أو powershell للأوامر المحقونة.
metadata	خريطة YAML حرّة لأدواتك الخاصّة.
license, compatibility	حقول معيار Agent Skills، مقبولة بلا أثر.

خارج Claude Code (رفع claude.ai، Skills API، package_skill.py)، تُقبل فقط name وdescription وlicense وcompatibility وmetadata وallowed-tools؛ الباقي امتدادات Claude Code.

الوسائط: $ARGUMENTS، $0/$1، $nom

تستقبل skill ما يلي اسمها على السطر. أربع صيغ placeholder: $ARGUMENTS (المجموع كسلسلة واحدة — بلا placeholder، يُلصقها Claude Code في نهاية skill بصيغة ARGUMENTS: <valeur>)، $ARGUMENTS[N] (نفاذ مفهرَس base 0)، $N (اختصار مكافئ، $0، $1)، و$nom (وسيط مسمّى مُصرَّح في arguments: [issue, branche]، $issue يأخذ الأوّل).

القيم متعدّدة الكلمات تُوضع بين علامتَي تنصيص (/migrer "SearchBar" JavaScript TypeScript). placeholder مفهرَس بلا وسيط يبقى دون تغيير؛ ومسمّى بلا قيمة يصبح سلسلة فارغة. وسيط يحوي $1 أو $ARGUMENTS يُدرَج حرفيًّا دون توسيع جديد. لـ$ حرفيّ، نُخلِّصه: \$1.00.

الحقن الديناميكيّ ومراجع الملفّ

صيغتان تحقنان محتوى خارجيًّا قبل الإرسال إلى Claude. سطر inline !`commande`: يُتعرَّف عليه فقط إن كان ! في بداية سطر أو بعد فراغ مباشرةً؛ يستبدل المخرج الـplaceholder ولا يُعاد مسحه. كتلة متعدّدة الأسطر ```! لعدّة أوامر. مراجع @fichier تُرفق ملفًّا بالسياق عند الاستدعاء، مفيدة لمشاركة قطعة اصطلاح بين عدّة skills.

يُستبدل متغيّران في الجسم وفي قواعد Bash لـallowed-tools: ${CLAUDE_SKILL_DIR} (مجلّد skill) و${CLAUDE_PROJECT_DIR} (جذر المشروع، v2.1.196+). الحيلة الكلاسيكيّة كتابة سكربت في مجلّد skill والموافقة المسبقة على تنفيذه: allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/gen.sh *) ثمّ استدعاء ${CLAUDE_SKILL_DIR}/scripts/gen.sh في الجسم. إن فشل أمر محقون، يُلغى الاستدعاء كاملًا — لا يرى Claude شيئًا. exit code 1 لأوامر البحث المذكورة في «Output limits» يُعامَل عاديًّا؛ أضف || true على الأوامر الأخرى المتوقَّع فيها exit غير صفريّ.

وكيل فرعيّ، أذونات، رؤية

context: fork يُشغّل skill داخل وكيل فرعيّ معزول. يصبح الجسم prompt؛ ولا يُنقَل سجلّ المحادثة. ثلاثة أسباب: مهمّة طويلة في الخلفيّة، لوحة أدوات مُقلَّصة (agent: Explore قراءة فقط)، مخرج ضخم يُراد احتواؤه. يعمل fork في الخلفيّة افتراضيًّا؛ background: false (v2.1.218+) يحجب التور. fork في الخلفيّة يكتب خارج checkpoints: /rewind لا يُلغي تحريراته، بل يجب المرور عبر git.

allowed-tools يُصرِّح بأدوات دون تأكيد خلال تور الاستدعاء (يُلغى المنح في الرسالة التالية)؛ disallowed-tools يحجب؛ disable-model-invocation: true يمنع Claude من تحميل skill لوحده (مفيد لأيّ أثر جانبيّ)؛ user-invocable: false يفعل العكس (مخفيّ من القائمة، يعمل الاستدعاء بواسطة Claude فقط). يُطبِّق ملفّ skillOverrides رؤية من الخارج: "on"، "name-only"، "user-invocable-only"، "off". تكتبها قائمة /skills لوحدها.

إعادة التحميل والتكرار

يُراقب Claude Code مجلّدات skills ويعتبر الإضافات والتعديلات والحذف دون إعادة تشغيل، إلّا في وضع bare. يفرض /reload-skills فحصًا جديدًا. أفضل انضباط للاختبار يبقى المقارنة A/B؛ plugin الرسميّ skill-creator يُؤتمِت الحلقة ويكتب evals.json في مجلّد skill.

للأوصاف ميزانيّة

يُحمِّل Claude Code قائمة skills في كلّ تور بميزانيّة 1 ٪ من نافذة النموذج. فوقها، تُقصَّر الأوصاف بدءًا بالأقلّ استدعاءً. ضع العبارة المفتاح في المقدّمة، وسقِّف مجموع description + when_to_use بـ1 536 حرفًا، ومرِّر skill ثانويّة إلى "name-only" في skillOverrides لإبقاء القائمة نافعة. يعرض /skill-doctor (v2.1.252+) كلفة كلّ skill.

الخيط الأحمر: ستّ skills لـKiosque

ستّ skills نكتبها في .claude/skills/ لـKiosque. لا واحدة تحتاج أدوات خارجيّة تتجاوز git وgh وpytest وruff وmake.

1. /commit — رسالة اصطلاحيّة انطلاقًا من diff مُفهرَس

---
description: Rédige un message de commit conventionnel à partir des changements indexés et propose de commiter. Utiliser après `git add` ou quand l'utilisateur demande « commit ».
argument-hint: "[portée]"
disable-model-invocation: true
allowed-tools: Bash(git diff --staged*) Bash(git status*) Bash(git commit *)
---

## Diff indexé
!`git diff --staged`

## Statut
!`git status --short`

## Instructions
Rédige un message **conventionnel** (`feat:`, `fix:`, `refactor:`, `test:`, `chore:`, `docs:`) en français, portée = $ARGUMENTS s'il est fourni, sinon déduite du chemin des fichiers.

- Titre : 72 caractères max, présent, impératif.
- Corps facultatif : seulement si le « pourquoi » n'est pas évident.
- Refuse et signale si le diff contient `.env` ou `secrets/`.

Exécute ensuite `git commit -m "<message>"`.

2. /revue [fichier] — إعادة قراءة قراءة فقط

---
description: Relit un fichier (ou le diff courant) à la recherche de bugs, d'oublis de tests et de violations de conventions. Lecture seule.
argument-hint: "[chemin]"
allowed-tools: Read Grep Glob Bash(git diff*)
disallowed-tools: Edit Write Bash(git commit*) Bash(git push*)
---

Cible : $ARGUMENTS (si vide, prends `git diff HEAD`).

## Diff de référence
!`git diff HEAD -- $ARGUMENTS`

## Instructions
Relis le code **en lecture seule** — n'édite rien. Cherche :

1. **Bugs** : condition inversée, mauvais type, off-by-one, gestion d'erreur absente.
2. **Sécurité** : injection SQL, secret en clair, absence de validation d'entrée.
3. **Conventions Kiosque** (voir `.claude/rules/api.md`) : noms de fonction en anglais, commentaires en français, `raise HTTPException` plutôt que `return` d'erreur.
4. **Tests manquants** : nouvelle branche non couverte, cas d'erreur non testé.

Rends un rapport en quatre sections (Bugs / Sécurité / Conventions / Tests), chaque item avec fichier, ligne, phrase.

3. /nouveau-endpoint <ressource> — route + schéma + test

---
description: Génère un endpoint FastAPI CRUD (route + schéma Pydantic + test pytest) pour une nouvelle ressource.
argument-hint: "<ressource-au-singulier>"
allowed-tools: Read Grep Glob Edit Write
---

Ressource cible : **$ARGUMENTS**.
@.claude/rules/api.md

Routes existantes :
!`ls app/routes/`

## Instructions
Crée : `app/schemas/$0.py` (Pydantic `Create`, `Read`, `Update`), `app/routes/$0.py` (`GET /$0s`, `GET /$0s/{id}`, `POST`, `PATCH`, `DELETE` ; SQLAlchemy via `Depends(get_db)`), `tests/test_$0.py` (un test heureux par endpoint, 404 sur `GET /$0s/{id}`, 422 sur `POST`). Enregistre le routeur dans `app/main.py` et lance `pytest tests/test_$0.py`.

4. /tests-cibles — pytest على الاختبارات المشمولة بالـdiff

---
description: Lance uniquement les tests pytest qui touchent aux fichiers du diff courant. Utiliser avant chaque commit pour un feedback rapide.
allowed-tools: Bash(git diff*) Bash(pytest*)
---

## Fichiers modifiés
!`git diff --name-only origin/main...HEAD`

## Instructions
Prends les fichiers de `tests/` modifiés, ajoute `tests/test_<module>.py` pour chaque `app/<module>.py` modifié, puis lance `pytest -x -q <fichiers>`. Si rien n'est ciblé, `pytest -x -q -k <mot-clé>` pour couvrir les tests indirects. Rapporte les échecs (test, ligne, assertion). Ne relance pas toute la suite — `make test` reste au clavier de l'utilisateur.

5. /doc-api — يُحدِّث docs/api.md انطلاقًا من المسارات

---
description: Régénère `docs/api.md` à partir des routes FastAPI de `app/routes/`. Utiliser après tout ajout ou modification d'endpoint.
allowed-tools: Read Grep Glob Edit Write Bash(rg *)
paths: app/routes/**
---

Routes :
!`rg -n "@(?:router|app)\.(get|post|patch|put|delete)" app/routes/`

## Instructions
Pour chaque endpoint : méthode, chemin, tag, résumé (docstring), schémas Pydantic d'entrée et sortie, codes de réponse. Écris `docs/api.md` : un tableau par tag `| Méthode | Chemin | Entrée | Sortie | Statuts |`, puis une section H3 par endpoint avec description française (reprends la docstring quand elle existe). Termine par « Généré par `/doc-api` — ne pas éditer à la main ».

6. /notes-de-version <tag> — وكيل فرعيّ forked

---
description: Rédige les notes de version markdown pour un tag Git à partir des commits depuis le tag précédent. Tourne dans un sous-agent séparé.
argument-hint: "<tag>"
context: fork
agent: Explore
background: true
allowed-tools: Bash(git log*) Bash(git tag*) Bash(git show*) Read Grep
---

Tag cible : **$ARGUMENTS**.

Tag précédent :
!`git describe --tags --abbrev=0 $ARGUMENTS^ 2>/dev/null || echo "(aucun tag antérieur)"`

Journal :
!`git log --pretty=format:"%h %s" $(git describe --tags --abbrev=0 $ARGUMENTS^ 2>/dev/null)..$ARGUMENTS`

## Instructions
Regroupe en quatre sections : **Nouveautés**, **Corrections**, **Améliorations internes**, **Documentation**. Ignore les commits de merge et de type `chore(deps)`. Une phrase par item, claire pour un utilisateur non technique (« Le module de paiement accepte un second prestataire »), pas le message brut. Retourne le markdown dans la conversation ; ne crée pas de fichier.

منذ v2.1.199، سطر واحد يُسلسل skills اثنتَين: /revue /commit paiements يُحمِّل الاثنتَين ويُمرِّر paiements كوسيط، مفيد حين يجب ألّا تحجب المراجعة شيئًا.

الخلاصة

• skill مجلّد .claude/skills/<nom>/SKILL.md: اسم المجلّد هو الأمر، وfrontmatter يصف skill، والجسم هو prompt.
• سبعة نطاقات، أسبقيّة مؤسّسة ← شخصيّة ← مشروع؛ ملفّ .claude/commands/<nom>.md يعمل دائمًا لكنّه يتنازل أمام skill بالاسم نفسه.
• الوسائط: $ARGUMENTS، $0/$1، $nom (عبر arguments:). حقن shell: !`cmd` أو كتلة ```!. المراجع: @fichier. متغيّرا ${CLAUDE_SKILL_DIR} و${CLAUDE_PROJECT_DIR} يُستبدلان في الجسم وفي allowed-tools.
• context: fork يُشغّل skill في وكيل فرعيّ معزول، في الخلفيّة افتراضيًّا (background: false لحجب التور).
• allowed-tools يُوافق مسبقًا للتور؛ disable-model-invocation يمنع Claude من التحميل لوحده؛ user-invocable: false يُخفي من القائمة؛ skillOverrides يُطبِّق رؤية في الإعدادات.
• /reload-skills يفرض الفحص ساخنًا؛ /skill-doctor (v2.1.252+) يعرض كلفة كلّ skill.

الوحدة التالية: الأذونات وأوضاع التنفيذ وsandbox وملفّات الإعدادات — وضع القواعد التي تدع Claude يعمل لوحده دون فتح ثغرة.