Créer un nouveau skill

Ce tutoriel explique comment créer un skill custom et l'intégrer au framework.

Qu'est-ce qu'un skill ?

Un skill est une commande /slash qui encapsule un workflow réutilisable. Il contient :

• Un frontmatter YAML (nom, description, outils)
• Des instructions étape par étape
• Des flags optionnels
• Des gates entre les étapes

Étape 1 : Définir le besoin

Avant de créer un skill, répondez à ces questions :

Question	Exemple
Quand l'utiliser ?	"Quand je dois créer un endpoint API"
Quoi automatise-t-il ?	"Créer model + schema + service + router + test"
Combien de steps ?	5 étapes
Quels outils sont nécessaires ?	Read, Write, Edit, Bash, Glob, Grep

Étape 2 : Créer la structure

mkdir -p framework/skills/api-endpoint

Étape 3 : Écrire le SKILL.md

---
name: api-endpoint
description: |
  Créer un endpoint API complet avec model, schema, service, router et tests.
  Utiliser quand : ajouter un nouvel endpoint, créer un CRUD.
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
---

# /api-endpoint

Créer un endpoint API complet en suivant les patterns du projet.

## Usage

\`\`\`bash
/api-endpoint create users CRUD
/api-endpoint -t create products with search
\`\`\`

## Flags

| Flag | Description |
|------|-------------|
| \`-t\` | Inclure les tests |

## Pipeline

### Step 01 — Analyser les patterns existants

<persona>architect (exploration mode)</persona>

1. Explorer les routers existants pour identifier les conventions
2. Identifier le pattern utilisé (router → service → repository → model)
3. Lister les dépendances nécessaires

<gate>Patterns identifiés → type \`next\`</gate>

### Step 02 — Créer le model et schema

<persona>developer</persona>

1. Créer le model (SQLAlchemy / Prisma / etc.)
2. Créer les schemas de validation (Pydantic / Zod / etc.)
3. Suivre les conventions détectées au step 01

<gate>Model et schema compilent → type \`next\`</gate>

### Step 03 — Créer le service

<persona>developer</persona>

1. Créer le service avec les opérations CRUD
2. Implémenter la logique métier
3. Gérer les erreurs proprement

<gate>Service compile → type \`next\`</gate>

### Step 04 — Créer le router

<persona>developer</persona>

1. Créer le router avec les endpoints
2. Connecter au service
3. Ajouter la validation des entrées

<gate>Endpoints accessibles → type \`next\`</gate>

### Step 05 — Tests (si flag -t)

<persona>developer (test mode)</persona>

1. Écrire les tests pour chaque endpoint
2. Tester les cas nominaux et les edge cases
3. Vérifier que tous les tests passent

Étape 4 : Ajouter un REFERENCE.md (optionnel)

Si le skill est complexe, créez un REFERENCE.md avec :

• Templates de sortie pour chaque step
• Edge cases et situations spéciales
• Exemples détaillés

# Référence : /api-endpoint

## Template Model

\`\`\`python
class {Name}(Base):
    __tablename__ = "{name}s"

    id: Mapped[int] = mapped_column(primary_key=True)
    created_at: Mapped[datetime] = mapped_column(default=func.now())
    # ... champs spécifiques
\`\`\`

## Template Router

\`\`\`python
router = APIRouter(prefix="/{name}s", tags=["{name}s"])

@router.get("/", response_model=list[{Name}Response])
async def list_{name}s(service: {Name}Service = Depends()):
    return await service.list_all()
\`\`\`

Étape 5 : Référencer dans CLAUDE.md

Ajoutez le skill à la liste dans votre CLAUDE.md :

## Skills disponibles
- `/api-endpoint` — Créer un endpoint API complet (model → schema → service → router → tests)

Étape 6 : Tester

Invoquez votre skill :

/api-endpoint create users CRUD

Vérifiez que :

• [ ] Le frontmatter est détecté (l'IA propose le skill au bon moment)
• [ ] Chaque step produit le bon output
• [ ] Les gates fonctionnent (l'IA attend next)
• [ ] Les flags modifient le comportement

Raccourci

Utilisez le skill /create-skill pour générer automatiquement la structure :

/create-skill api-endpoint

Bonnes pratiques

Keep it lean

Le SKILL.md doit rester sous 5000 tokens. Si c'est plus long, découpez en step files séparés dans un dossier steps/.

Un skill = un objectif

Ne mettez pas 3 workflows différents dans un seul skill. Créez 3 skills distincts et un workflow qui les orchestre.

Testez avant de partager

Un skill non testé va frustrer vos collègues. Invoquez-le au moins 2-3 fois sur des cas différents avant de le publier.