Writing effective Claude Code skills - a concrete case with Pile ou SaaS

The project: Pile ou SaaS

Pile ou SaaS is a WordPress showcase site for a motion design video service aimed at SaaS companies. The technical stack:

• WordPress 6.4 with a custom theme
• Tailwind CSS v4 for styling (npm compilation)
• ACF Pro (Advanced Custom Fields) for content management
• GSAP + ScrollTrigger for animations
• Lucide Icons (40+ pre-registered SVG icons)
• Two Custom Post Types: podcast_episode and article
• 7 page templates (home, pricing, method, contact, podcast, academy, bio)

This project is an excellent guinea pig for Claude Code skills, because it combines different technologies with strict conventions. Every time I ask Claude Code to work on it - add a section, create a template, change a style - it needs to know the project's specific context.

This is exactly what skills solve.

Why skills for a WordPress site?

Without a skill, here's what happens when I ask "add a new section to the homepage":

1. Claude Code creates raw HTML - not PHP with ACF functions
2. It uses generic CSS classes - not the project's Tailwind utilities
3. It forgets the GSAP animations (data-gsap="fade-up")
4. It doesn't know that icons go through get_lucide_icon()
5. It creates a file in the wrong place - not in template-home-pileousaas.php

Every intervention requires manual fixes. The benefit of AI is lost.

With a well-written skill, Claude Code knows these conventions from the start. It knows that fields come from ACF, that the CSS is Tailwind, that animations use GSAP. Result: directly usable code.

Skill 1: the WordPress template

The first skill I would create for Pile ou SaaS is a template generation skill. Applying Anthropic's best practices:

Concise - don't explain WordPress

Claude knows what WordPress, ACF, and Tailwind are. No need to remind it. The skill should contain only what's specific to this project:

---
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; ?>
```

This skill is ~40 lineslong. It contains nothing Claude already knows (what a Custom Post Type is, how PHP works). It only contains what Claude can't guess: naming conventions, the palette, animation attributes.

Degrees of freedom: medium

The minimal template gives the structure, but Claude is free to adapt the content of each section. This is Anthropic's "open field" - there's a preferred pattern, but context determines the details.

Skill 2: the Tailwind design system

The second skill captures the project's design system . Pile ou SaaS uses Tailwind v4 with a specific configuration in 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`

Why a separate skill from the template? Because Anthropic's best practices recommend progressive disclosure. When Claude edits a template, it loads the templates skill. When it works on styling, it loads the design skill. The two aren't loaded at the same time - this saves context.

Skill 3: GSAP animations

Animations in Pile ou SaaS aren't hardcoded in each PHP file - they're declarative via data-gsap attributes and initialized in src/js/main.js. This pattern is invisible to Claude if it isn't told:

---
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 `

This skill is a "narrow bridge" - low freedom. Animations must use exactly the defined data-gsap attributes, not alternatives. Too much freedom here would create visual inconsistencies.

Organization: progressive disclosure in practice

For Pile ou SaaS, the skill structure would look like:

.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)

The fourth skill (pileousaas-acf.md) would contain the ACF field structure - which field groups exist, which subfields to use for each section. It's the largest, but it's only loaded when Claude creates or edits content.

The key point: at the start of a Claude Code session, only the name and description of these 4 skills are loaded into context. That's about ~200 tokens. The full content is only read when a skill is relevant to the task at hand.

The description: the critical factor

Anthropic insists: the description is what makes a skill trigger or not. Among potentially 100+ skills, Claude only uses the description to choose. Two common mistakes:

The formula: "[What it does]. Use when [specific trigger]." - always in third person.

Validation loops for WordPress

Anthropic's best practices recommend action → validation → correctionloops. For a WordPress project, this translates to:

## 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

This workflow prevents Claude from declaring "it's done" before the code compiles and the Tailwind classes are generated. Without this loop, it's common to end up with valid PHP code... with Tailwind classes that don't exist in the compiled CSS.

The iteration cycle: how to refine

Anthropic recommends developing a skill with two instances of Claude. In practice, for Pile ou SaaS:

1. Session 1 - I ask Claude Code to "add a testimonials section to the homepage" without a skill. I note everything I need to fix: wrong classes, no ACF, no animation, wrong file location
2. I create the skill from these corrections - this is exactly the information Claude didn't have
3. Session 2 - I ask for the same thing with the skill loaded. I check: does it use the right classes? The right ACF pattern? The GSAP attributes?
4. I refine - if Claude still misses something, I add the missing rule to the skill

This process takes 2-3 iterations to converge. After that, every new section, every new template is generated directly in the right format.

What this changes in practice

For a project like Pile ou SaaS, skills transform the workflow:

The gain isn't marginal. On a project with 7 page templates, dozens of ACF sections, and a specific design system, it's the difference between using Claude Code as a generic assistant and using it as a developer who knows the project.

Rules to remember

1. Conciseness - don't explain what Claude already knows. Only project-specific context has value
2. Third-person description - "[What it does]. Use when [trigger]."
3. Calibrated degrees of freedom - strict for animations (narrow bridge), flexible for section content (open field)
4. Progressive disclosure - one skill per domain (templates, design, animations, ACF), not a single monolithic file
5. Validation loops - check PHP syntax and Tailwind compilation before declaring "done"
6. Iterate with the real project - the skill gets refined by observing what Claude gets wrong, not by anticipating