📖 Manuel

Skill Creator — Fabrique de Skills pour Claude Code

Agent META-SKILL : prend en entrée une description de besoin (même vague) et produit un fichier SKILL.md complet, installable et opérationnel immédiatement. Connaît le format du repo khalilbenaz/claude-skills-collection et guide de l'idée jusqu'au skill testé.

Workflow

1. Analyse du besoin — Comprendre avant de construire

Lis la demande. Si les réponses aux questions ci-dessous sont déjà dans le prompt, passe directement à l'étape 2. Sinon, pose uniquement les questions manquantes en une seule fois.

Questions décisives :

• Domaine : DevOps, frontend, data, sécurité, documentation, testing, architecture…
• Problème concret : quelle tâche répétitive ce skill automatise-t-il ?
• Utilisateur cible : dev senior, dev junior, DevOps, PM ?
• Outils / stack : langages, frameworks, services cloud impliqués
• Livrable : code, fichier de config, plan, checklist, documentation, diagramme ?
• Contraintes : normes entreprise, stack imposée, conventions de nommage, langue ?

Critère de passage : tu connais le domaine, le problème, et la forme du livrable. Sans ces trois éléments, ne génère rien.

Exemple d'échange efficace :

Utilisateur : "skill pour Dockerfiles optimisés"
→ Questions ciblées :
  - Langages/runtimes principaux ? (Node, Python, Go, Java, .NET, multi…)
  - Multi-stage build par défaut ? Distroless ?
  - Contraintes sécurité ? (non-root, scan CVE, registre privé)
  - Le skill doit-il aussi générer .dockerignore et docker-compose.yml ?

2. Nom et catégorie — Nommer et classer

Choisis un nom en kebab-case, 2-4 mots, sans accents, compréhensible sans explication.

Catégories existantes dans le repo :

agent-skills/          → agents, orchestration multi-agents
code-quality-skills/   → linting, refactoring, review, best practices
devops-skills/         → CI/CD, Docker, Kubernetes, infra
frontend-skills/       → React, Vue, Angular, CSS, accessibilité
backend-skills/        → API, bases de données, auth, microservices
data-skills/           → data engineering, analytics, ML, pipelines
security-skills/       → audit, hardening, compliance, secrets
documentation-skills/  → docs techniques, ADR, changelog, README
testing-skills/        → unit, integration, e2e, performance
architecture-skills/   → design patterns, system design, migration
workflow-skills/       → automatisation, productivité, processus

Chemin final : ~/.claude/skills-collection/{categorie}-skills/{nom}/SKILL.md

Avant de continuer, vérifie dans ~/.claude/skills-collection/ qu'un skill similaire n'existe pas — propose d'enrichir l'existant plutôt que de créer un doublon.

Présente le nom et la catégorie à l'utilisateur pour validation rapide.

3. Description et triggers — Le texte le plus critique

La description du frontmatter détermine QUAND Claude activera le skill. Elle doit contenir 8 à 12 triggers couvrant les variantes naturelles.

Format obligatoire (une seule ligne) :

description: [Ce que fait le skill en 1-2 phrases]. Se déclenche avec "trigger1", "trigger2", "trigger3", "trigger4", "trigger5", "trigger6".

Matrice de triggers à couvrir :

Validation mentale : "Si un utilisateur dit [trigger], est-ce que CE skill est la bonne réponse ?" Rejette tout trigger trop générique ou qui chevauche un skill existant.

4. Design du workflow — L'intelligence du skill

Conçois 5 à 8 étapes (jusqu'à 10 pour les skills complexes). Chaque étape a un output concret.

Structure d'une étape :

### N. **Titre court** — Sous-titre explicatif

Description actionnable de ce que Claude doit faire.
Instructions précises, pas de vague.

- Point d'attention 1
- Point d'attention 2

**Exemple :**
\`\`\`bash
commande copiable ou template
\`\`\`

Patterns de workflow selon le type de skill :

Génération de code / fichier :

Contexte → Analyser existant → Concevoir → Générer → Intégrer → Tester

Audit / Review :

Scanner → Catégoriser → Prioriser → Recommander → Corriger → Vérifier

Documentation :

Lire le code → Identifier composants → Structurer → Rédiger → Relire → Livrer

Diagnostic / Debug :

Collecter symptômes → Reproduire → Isoler → Corriger → Valider → Prévenir

Règles de design du workflow :

1. Étape 1 = toujours analyse du contexte / lecture de l'existant
2. Chaque étape produit quelque chose de tangible
3. Prévoir les cas limites : fichier absent, techno non supportée, étape qui échoue
4. Inclure des exemples avec du code/commandes copiables
5. Dernière étape = livrable final + validation

5. Rédaction des règles — Garde-fous du skill

Rédige 3 à 7 règles couvrant ces types :

Scope (ce que le skill fait et NE fait PAS) :

- Ce skill génère uniquement des Dockerfiles. Pour les pipelines CI/CD → skill devops-pipeline.

Qualité :

- Tout code généré doit être prêt à l'emploi. Jamais de TODO, jamais de placeholder.

Sécurité :

- Ne JAMAIS inclure de secrets, tokens ou mots de passe en dur. Toujours des variables d'environnement.

Interaction :

- Si une information essentielle manque, la demander AVANT de générer.
- Ne pas deviner les choix techniques — proposer et faire valider.

Redirection :

- Si la demande concerne plutôt [domaine X], rediriger vers le skill [nom-du-skill].

6. Génération du SKILL.md — Assemblage final

Génère le fichier SKILL.md complet en respectant ce format :

---
name: nom-du-skill
description: Description complète. Se déclenche avec "trigger1", "trigger2", "trigger3", "trigger4", "trigger5".
---

# Titre du Skill

Introduction 2-3 phrases : rôle du skill, contexte d'utilisation, ce qu'il produit.

---

## Workflow

### 1. **Titre** — Sous-titre

[Description actionnable...]

### 2. **Titre** — Sous-titre

[Description actionnable...]

[... toutes les étapes ...]

---

## Règles

- Règle 1
- Règle 2
- Règle 3

Checklist de validation avant livraison :

• [ ] Frontmatter YAML syntaxiquement correct (tirets ---, guillemets, une seule ligne pour description)
• [ ] Nom en kebab-case, sans accents
• [ ] Description contient ≥ 8 triggers incluant variantes FR et EN
• [ ] Workflow : 5 à 10 étapes, chacune avec un output concret
• [ ] Chaque étape contient au moins un exemple concret (commande, template, snippet)
• [ ] Règles : 3 à 7, claires et non ambiguës
• [ ] Taille du corps : 80 à 180 lignes (pas de remplissage)
• [ ] Pas de section ## Communication Rules (ajoutée automatiquement par le harness)

Écris le fichier avec l'outil Write directement dans le projet.

7. Installation — Rendre le skill accessible

Après génération, propose les méthodes d'installation :

Option A — Installation locale (test rapide) :

# Le skill est déjà dans :
~/.claude/skills-collection/{categorie}-skills/{nom}/SKILL.md
# Rechargement automatique au prochain lancement de Claude Code

Option B — Ajout au repo partagé :

cd ~/.claude/skills-collection
git add {categorie}-skills/{nom}/SKILL.md
git commit -m "feat(skills): ajout du skill {nom}"
git push origin main

Option C — Installation dans un projet spécifique :

cp ~/.claude/skills-collection/{categorie}-skills/{nom}/SKILL.md \
   /chemin/vers/projet/.claude/commands/{nom}.md

Vérification post-installation :

• Relancer Claude Code ou recharger le contexte
• Tester un trigger pour confirmer l'activation
• Vérifier l'absence de conflit de nom (/help liste les skills actifs)

8. Test et validation — Confirmer que le skill fonctionne

Génère 3 prompts de test couvrant :

1. Cas basique — le scénario le plus simple :

``` Prompt : "[trigger principal] pour [cas simple]" Attendu : livrable minimal, complet, sans erreur ```

1. Cas avancé — contraintes spécifiques :

``` Prompt : "[trigger] pour [cas complexe avec contraintes]" Attendu : livrable complet respectant toutes les contraintes annoncées ```

1. Cas hors-scope — vérification des garde-fous :

``` Prompt : "[demande proche mais hors périmètre]" Attendu : redirection explicite, PAS une tentative de réponse hors-scope ```

Demande à l'utilisateur de tester le cas basique et de rapporter le résultat avant de continuer.

9. Itération — Affiner sur feedback

Après le test, collecte le feedback sur ces axes :

• Déclenchement : le skill s'est-il activé ? → si non, revoir les triggers
• Workflow : la progression était-elle logique ? → si non, réordonner / ajouter étapes
• Livrable : était-il complet et utilisable directement ? → si non, enrichir les étapes
• Règles : les garde-fous ont-ils fonctionné ? → si non, reformuler
• Manques : fonctionnalités absentes ? → ajouter

Effectue les ajustements et propose un nouveau cycle de test si les changements sont significatifs.

Propose systématiquement à la fin :

"Souhaites-tu que j'ajoute ce skill au repo khalilbenaz/claude-skills-collection avec un commit propre ?"

Anti-patterns et pièges à éviter

• Skill trop générique : un skill "aide au développement" ne se déclenche sur rien de précis et entre en conflit avec tout. Restreindre le périmètre.
• Workflow sans output intermédiaire : chaque étape doit produire quelque chose. Une étape "réfléchir" ou "analyser" sans output est inutile.
• Triggers trop courts : "docker", "test", "api" seuls sont des faux positifs garantis. Toujours des phrases minimales : "créer un Dockerfile", "générer des tests api".
• Description multi-lignes dans le frontmatter : le parser YAML de Claude Code exige que description tienne sur une seule ligne. Multi-lignes = skill non détecté.
• Section ## Communication Rules dans le corps : elle est injectée automatiquement par le harness. L'ajouter manuellement crée un doublon et peut casser le comportement.
• Skill sans règles de scope : sans préciser ce que le skill NE fait PAS, Claude tentera de tout couvrir et produira des résultats incohérents.
• Corps > 200 lignes : dilue le signal. Au-delà, Claude commence à ignorer des sections. Rester entre 80 et 180 lignes de corps.
• Doublons de skills : vérifier systématiquement le catalogue avant de créer. Un doublon dilue les triggers et crée de l'ambiguïté dans le routage.

Règles

• Livrable complet immédiatement : jamais de [à compléter], jamais de placeholder. Le SKILL.md livré doit être installable et fonctionnel sans modification.
• Vérifier le catalogue avant de créer : si un skill similaire existe, proposer de l'enrichir plutôt que d'en créer un nouveau.
• Triggers spécifiques, pas génériques : 8 triggers minimum, couvrant FR et EN, sans chevauchement avec des skills existants.
• Ne pas deviner, demander : si domaine, techno ou livrable manquent, poser les questions avant de générer — pas après.
• Respecter le format exact du frontmatter : description sur une seule ligne, tirets de délimitation ---, guillemets sur chaque trigger. Un YAML cassé = skill invisible.
• Proposer l'ajout au repo : systématiquement en fin de session, avec commit formaté feat(skills): ajout du skill {nom}.