Écrire des skills Claude Code efficaces - cas concret avec Pile ou SaaS

Le projet : Pile ou SaaS

Pile ou SaaS est un site vitrine WordPress pour un service de vidéo motion design destine aux entreprises SaaS. Le stack technique :

• WordPress 6.4 avec un thème custom
• Tailwind CSS v4 pour le style (compilation npm)
• ACF Pro (Advanced Custom Fields) pour la gestion de contenu
• GSAP + ScrollTrigger pour les animations
• Lucide Icons (40+ icônes SVG pré-enregistrées)
• Deux Custom Post Types : podcast_episode et article
• 7 page templates (home, tarifs, méthode, contact, podcast, academy, bio)

Ce projet est un excellent cobaye pour les skills Claude Code, parce qu'il combine des technologies différentes avec des conventions strictes. Chaque fois que je demande à Claude Code d'intervenir dessus - ajouter une section, créer un template, modifier un style - il doit connaitre le contexte spécifique du projet.

C'est exactement ce que résolvent les skills.

Pourquoi des skills pour un site WordPress ?

Sans skill, voici ce qui se passe quand je demande "ajoute une nouvelle section sur la homepage" :

1. Claude Code crée du HTML brut - pas du PHP avec les fonctions ACF
2. Il utilise des classes CSS génériques - pas les utilitaires Tailwind du projet
3. Il oublie les animations GSAP (data-gsap="fade-up")
4. Il ne sait pas que les icônes passent par get_lucide_icon()
5. Il crée un fichier au mauvais endroit - pas dans template-home-pileousaas.php

Chaque intervention demande des corrections manuelles. On perd le bénéfice de l'IA.

Avec un skill bien écrit, Claude Code connait ces conventions des le départ. Il sait que les champs viennent d'ACF, que le CSS est du Tailwind, que les animations utilisent GSAP. Résultat : du code directement utilisable.

Skill 1 : le template WordPress

Le premier skill que je créerais pour Pile ou SaaS est un skill de génération de templates. En appliquant les best practices d'Anthropic :

Concis - ne pas expliquer WordPress

Claude sait ce qu'est WordPress, ACF, Tailwind. Inutile de le lui rappeler. Le skill doit contenir uniquement ce qui est spécifique à ce projet :

---
name: pileousaas-templates
description: Generates WordPress page templates for the
  Pile ou SaaS theme. Use when creating new pages,
  sections, or modifying existing templates in the
  Pile_ou_SaaS theme.
---

# Pile ou SaaS - Templates WordPress

## Structure de fichier

Nom : `template-{slug}-pileousaas.php`
Emplacement : `wp-content/themes/Pile_ou_SaaS/`

## Conventions

- Champs ACF : `get_field('section_nom')` et `get_sub_field()`
- CSS : classes Tailwind v4 uniquement, pas de CSS inline
- Icones : `get_lucide_icon('nom', 'classes-tw')`
- Animations : `data-gsap="fade-up|fade-down|scale"`
- Containers : `<section class="section-padding">`
  → `<div class="container-custom">`
- Boutons : `.btn-primary` ou `.btn-outline`
- Couleurs : cream (#F4F0E4), blue (#5C73D9),
  blue-light (#9FA5F3), dark (#141414)

## Template minimal

```php
<?php
$section = get_field('section_nom');
if ($section): ?>
<section class="section-padding bg-cream">
  <div class="container-custom">
    <h2 class="text-4xl font-bold text-dark mb-6"
        data-gsap="fade-up">
      <?= esc_html($section['titre']) ?>
    </h2>
  </div>
</section>
<?php endif; ?>
```

Ce skill fait ~40 lignes. Il ne contient rien que Claude sait déjà (ce qu'est un Custom Post Type, comment fonctionne PHP). Il ne contient que ce que Claude ne peut pas deviner : les conventions de nommage, la palette, les attributs d'animation.

Degrés de liberté : moyen

Le template minimal donne la structure, mais Claude est libre d'adapter le contenu de chaque section. C'est le "champ ouvert" d'Anthropic - il y à un pattern préfère, mais le contexte détermine les détails.

Skill 2 : le design system Tailwind

Le deuxième skill capture le design system du projet. Pile ou SaaS utilise Tailwind v4 avec une configuration spécifique dans src/css/input.css :

---
name: pileousaas-design
description: Design system and Tailwind CSS conventions
  for the Pile ou SaaS WordPress theme. Use when styling
  components, creating layouts, or modifying visual design.
---

# Design System - Pile ou SaaS

## Palette (variables Tailwind v4)

| Token        | Hex       | Usage                    |
|-------------|-----------|--------------------------|
| cream       | #F4F0E4   | Fond principal           |
| blue        | #5C73D9   | CTA, liens, accents      |
| blue-light  | #9FA5F3   | Hover, badges            |
| dark        | #141414   | Texte, fonds sombres     |
| whatsapp    | #25D366   | Bouton WhatsApp          |

## Typographie

Font : Red Hat Text (Google Fonts)
Titres : `font-bold`, jamais `font-extrabold`
Corps : taille par defaut Tailwind

## Composants recurrents

- Section : `section.section-padding > div.container-custom`
- CTA primaire : `a.btn-primary`
- CTA secondaire : `a.btn-outline`
- Carte : `rounded-2xl bg-white shadow-lg p-8`
- Badge : `inline-block px-3 py-1 rounded-full
  bg-blue/10 text-blue text-sm font-semibold`

## Build

```bash
npm run dev    # watch mode
npm run build  # production (minifie)
```

Fichiers : `src/css/input.css` → `dist/output.css`

Pourquoi un skill séparé du template ? Parce que les best practices d'Anthropic recommandent la divulgation progressive. Quand Claude modifie un template, il charge le skill templates. Quand il travaille sur le style, il charge le skill design. Les deux ne sont pas charges en même temps - ça économise du contexte.

Skill 3 : les animations GSAP

Les animations dans Pile ou SaaS ne sont pas codées dans chaque fichier PHP - elles sont déclaratives via des attributs data-gsap et initialisées dans src/js/main.js. Ce pattern est invisible pour Claude si on ne le lui dit pas :

---
name: pileousaas-animations
description: GSAP animation system for Pile ou SaaS.
  Use when adding animations, scroll effects, or
  interactive elements to templates.
---

# Animations - Pile ou SaaS

GSAP 3.12.5 + ScrollTrigger, charges globalement.

## Attributs declaratifs

Ajouter sur n'importe quel element HTML :

| Attribut                        | Effet                        |
|--------------------------------|------------------------------|
| `data-gsap="fade"`            | Fondu d'opacite              |
| `data-gsap="fade-up"`         | Fondu + translation vers haut |
| `data-gsap="fade-down"`       | Fondu + translation vers bas  |
| `data-gsap="scale"`           | Fondu + zoom de 0.9 a 1      |

Declenchement : au scroll, quand l'element entre
dans le viewport (ScrollTrigger).

## Ne PAS faire

- Ne pas ajouter de `

Ce skill est "pont étroit" - basse liberté. Les animations doivent utiliser exactement les attributs data-gsap définis, pas des alternatives. Trop de liberté ici créerait des incohérences visuelles.

Organisation : la divulgation progressive en pratique

Pour Pile ou SaaS, la structure de skills ressemblerait a :

.claude/skills/
├── pileousaas-templates.md     # Conventions templates PHP
├── pileousaas-design.md        # Design system Tailwind
├── pileousaas-animations.md    # Systeme GSAP
└── pileousaas-acf.md           # Structures ACF (field groups)

Le quatrième skill (pileousaas-acf.md) contiendrait la structure des champs ACF - quels groupes de champs existent, quels sous-champs utiliser pour chaque section. C'est le plus volumineux, mais il n'est charge que quand Claude crée ou modifie du contenu.

Le point clé : au démarrage d'une session Claude Code, seuls les name et description de ces 4 skills sont charges dans le contexte. Ça représente ~200 tokens. Le contenu complet n'est lu que quand un skill est pertinent pour la tâche en cours.

La description : le facteur critique

Anthropic insiste : la description est ce qui fait qu'un skill se déclenche ou non. Parmi potentiellement 100+ skills, Claude utilise uniquement la description pour choisir. Deux erreurs courantes :

La formule : "[Ce que ça fait]. Use when [déclencheur spécifique]." - toujours en 3e personne.

Boucles de validation pour WordPress

Les best practices d'Anthropic recommandent des boucles action → validation → correction. Pour un projet WordPress, ça se traduit par :

## Workflow de creation de template

1. Creer le fichier `template-{slug}-pileousaas.php`
2. Verifier : `php -l template-{slug}-pileousaas.php`
   → Pas d'erreur de syntaxe PHP
3. Compiler Tailwind : `npm run build`
   → Verifier que les nouvelles classes sont dans dist/output.css
4. Tester dans le navigateur :
   → La section s'affiche correctement
   → Les animations GSAP se declenchent au scroll
   → Le contenu ACF s'affiche (pas de champs vides)
5. Si probleme, corriger et reprendre a l'etape 2

Ce workflow empêche Claude de déclarer "c'est fait" avant que le code compile et que les classes Tailwind soient générées. Sans cette boucle, il est courant d'avoir du code PHP valide... avec des classes Tailwind qui n'existent pas dans le CSS compile.

Le cycle d'itération : comment affiner

Anthropic recommandé de développer un skill avec deux instances de Claude. En pratique pour Pile ou SaaS :

1. Session 1 - je demande à Claude Code "ajoute une section témoignages sur la homepage" sans skill. Je note tout ce que je dois corriger : mauvaises classes, pas d'ACF, pas d'animation, mauvais emplacement du fichier
2. Je crée le skill à partir de ces corrections - ce sont exactement les infos que Claude n'avait pas
3. Session 2 - je demande la même chose avec le skill charge. J'observe : est-ce qu'il utilise les bonnes classes ? Le bon pattern ACF ? Les attributs GSAP ?
4. J'affine - si Claude oublie encore quelque chose, j'ajoute la règle manquante au skill

Ce processus prend 2-3 itérations pour converger. Après ça, chaque nouvelle section, chaque nouveau template est génère directement au bon format.

Ce que ça change concrètement

Pour un projet comme Pile ou SaaS, les skills transforment le workflow :

Le gain n'est pas marginal. Sur un projet avec 7 page templates, des dizaines de sections ACF, et un design system spécifique, c'est la différence entre utiliser Claude Code comme un assistant générique et l'utiliser comme un développeur qui connait le projet.

Les règles à retenir

1. Concision - ne pas expliquer ce que Claude sait déjà. Seul le contexte spécifique au projet a de la valeur
2. Description en 3e personne - "[Ce que ça fait]. Use when [déclencheur]."
3. Degrés de liberté calibres - strict pour les animations (pont étroit), flexible pour le contenu des sections (champ ouvert)
4. Divulgation progressive - un skill par domaine (templates, design, animations, ACF), pas un megatype fichier monolithique
5. Boucles de validation - vérifier la syntaxe PHP et la compilation Tailwind avant de déclarer "fini"
6. Iterer avec le projet réel - le skill s'affine en observant ce que Claude rate, pas en anticipant