Chapitre 9.5 — Atelier : une skill pour TaskFlow

⏱️ TL;DR — On écrit new-feature, une skill de projet (versionnée dans .claude/skills/) qui scaffolde une nouvelle feature TaskFlow au bon gabarit (queries/actions/schema/components + tests), selon les conventions du CLAUDE.md. Description riche en déclencheurs, SKILL.md prescriptif, un template en ressource. On la teste : « ajoute une entité Projet » → scaffolde-t-elle correctement ? La skill devient une convention exécutable, partagée par tout le repo.

🎯 Objectifs

• Écrire une skill de projet complète.
• Soigner la description (déclencheurs) et les étapes prescriptives.
• Utiliser une ressource (template) via progressive disclosure.
• Tester le déclenchement et le résultat.

Pourquoi cette skill

Sur TaskFlow, créer une feature suit toujours le même gabarit (le triptyque queries/actions/schema + composants + tests, cf. src/features/CLAUDE.md). C’est un workflow répétable → cas d’école pour une skill (9.2). Encodée, elle garantit que chaque nouvelle feature naît conforme, sans qu’on redise le gabarit.

Le SKILL.md

Fichier .claude/skills/new-feature/SKILL.md :

---
name: new-feature
description: >
  Scaffolde une nouvelle feature TaskFlow au gabarit standard
  (queries.ts, actions.ts, schema.ts, components/) + tests Vitest, selon le
  CLAUDE.md du projet. Utiliser quand on démarre une feature ou qu'on dit
  « nouvelle feature », « ajoute une entité », « scaffolde <X> ».
---
 
# Scaffolder une feature TaskFlow
 
Quand on te demande une nouvelle feature `<nom>` :
 
1. Crée `src/features/<nom>/` avec :
   - `schema.ts` — schéma(s) Zod de l'entité (voir reference/TEMPLATE.md).
   - `queries.ts` — lectures (fonctions pures autour de Prisma). Aucun effet de bord.
   - `actions.ts` — mutations en **server actions**, qui valident via le schéma Zod
     avant d'écrire et revalident la liste après.
   - `components/` — UI de la feature, composants d'UI importés depuis `@/components/ui`.
2. Ajoute les tests Vitest des actions (create/update/delete) et du schéma.
3. Respecte le CLAUDE.md : `any` interdit, alias `@/`, tokens (pas de couleur en dur),
   erreurs typées. Suis le style de `src/components/ui/button.tsx` pour tout composant.
4. Ne crée PAS de route tant que ce n'est pas demandé. Ne modifie pas d'autres features.
5. Termine par : `npm run typecheck` + `npm test` (les hooks les imposeront de toute façon).
 
Pour la structure détaillée d'un fichier, voir `reference/TEMPLATE.md`.

Points de méthode :

• Description : dit quoi + quand, avec les déclencheurs réels (« nouvelle feature », « ajoute une entité »). C’est ce qui la fera s’activer au bon moment (9.2).
• Étapes prescriptives et tranchables, calquées sur le contrat des features (3.5) — pas de blabla.
• Bornes explicites (« pas de route sans demande », « ne modifie pas d’autres features ») : la skill ne déborde pas.
• Ressource reference/TEMPLATE.md : le détail (squelettes de fichiers) en niveau 3 (progressive disclosure), pour garder le SKILL.md court.

La ressource

.claude/skills/new-feature/reference/TEMPLATE.md contient les squelettes concrets (un schema.ts type, une action type avec validation + revalidation, un test type). Elle n’est chargée que si la skill en a besoin — le SKILL.md reste léger.

Le test

Une skill non testée ne vaut rien (9.2). Deux vérifications :

1. Déclenchement : « ajoute une entité Projet à TaskFlow » → la skill s’active-t-elle ? Si non, enrichis les déclencheurs de la description.
2. Résultat : le scaffold respecte-t-il le gabarit (triptyque + tests) et les conventions (no-any, tokens, @/) ? Si un écart apparaît, resserre les étapes ou pointe plus fort le fichier-modèle.

⚠️ Piège — Écrire la skill puis ne jamais la re-tester après avoir changé les conventions du projet. Une skill est du code de workflow : si le gabarit des features évolue, la skill doit suivre (comme la mémoire, elle peut devenir périmée — 3.4). Traite-la comme un artefact vivant, pas comme un acquis figé.

Ce qu’on a gagné

• Une convention exécutable : le gabarit des features n’est plus seulement décrit (CLAUDE.md), il est appliqué d’une commande.
• Versionnée : tout contributeur du repo (toi, agent, collègue) scaffolde à l’identique.
• Composable avec le reste : elle produit du code que les hooks (P7) formatent/testent, que l’agent reviewer (P8) relira, que la boucle qualité (P11) validera.

🧭 Sur TaskFlow — Le fil rouge a maintenant sa propre skill. Combinée aux hooks (P7) et à l’agent reviewer (P8), TaskFlow dispose d’un outillage maison cohérent. Si on multipliait les projets Next.js identiques, on empaquetterait tout ça en plugin (9.4). Pour l’instant, local et versionné : parfait.

✏️ Exercices

Exercice 1 — Ta skill de workflow. Identifie un workflow que tu répètes sur un vrai projet (scaffolder un module, générer des tests d’un type). Écris-en la skill (description à déclencheurs + étapes prescriptives + une ressource). Teste le déclenchement.

Exercice 2 — Composition. Vérifie que le code produit par ta skill est bien pris en charge par tes hooks (formaté/testé, P7) et relisible par un agent reviewer (P8). Les briques coopèrent-elles ?

🧠 Quiz de révision

Fin de la Partie 9. Tu sais choisir, écrire et distribuer des skills. On connecte maintenant Claude Code au monde extérieur : Partie 10 — MCP, commandes, plugins & output styles.