@boostecom/provider 0.0.1

package/docs/content/skills.mdx

@@ -0,0 +1,548 @@
+---
+title: Skills (Compétences)
+description: Créer et utiliser des compétences personnalisées avec Claude Code
+---
+
+# Skills - Compétences personnalisées
+
+Les Skills sont des outils personnalisés que vous pouvez définir pour étendre les capacités de Claude Code. Elles permettent d'ajouter des fonctionnalités spécifiques à votre domaine ou workflow.
+
+## Qu'est-ce qu'une Skill ?
+
+Une Skill est essentiellement un outil personnalisé défini via un fichier Markdown (`SKILL.md`) qui décrit :
+
+- **Ce que fait la skill** - Description et cas d'usage
+- **Comment l'utiliser** - Paramètres et syntaxe
+- **Exemples** - Démonstrations d'utilisation
+
+Claude lit ces définitions et peut invoquer vos skills durant une conversation.
+
+## Configuration des Skills
+
+Pour activer les Skills, vous devez configurer deux options :
+
+```typescript
+import { claudeCode } from '@boostecom/provider';
+
+const model = claudeCode('sonnet', {
+  settingSources: ['user', 'project'], // Charger les skills
+  allowedTools: ['Skill', 'Read', 'Write'], // 'Skill' requis
+});
+```
+
+<Note type="warning">
+  **Requis** : Les deux options sont nécessaires. Sans `settingSources`, les skills ne seront pas chargées. Sans `'Skill'` dans `allowedTools`, elles ne pourront pas être invoquées.
+</Note>
+
+## Emplacements des Skills
+
+### Skills utilisateur (globales)
+
+```
+~/.claude/skills/
+  ├── ma-skill/
+  │   └── SKILL.md
+  └── autre-skill/
+      └── SKILL.md
+```
+
+Disponibles pour tous vos projets.
+
+### Skills projet (locales)
+
+```
+.claude/skills/
+  ├── projet-skill/
+  │   └── SKILL.md
+  └── custom-tool/
+      └── SKILL.md
+```
+
+Disponibles uniquement dans le projet courant.
+
+## Créer une Skill
+
+### Structure du fichier SKILL.md
+
+```markdown title=".claude/skills/database-query/SKILL.md"
+# Database Query Skill
+
+Cette skill permet d'exécuter des requêtes SQL sur la base de données du projet.
+
+## Usage
+
+/database-query <query>
+
+## Paramètres
+
+- `query` (required) - La requête SQL à exécuter
+
+## Exemples
+
+/database-query SELECT * FROM users WHERE active = true
+/database-query SELECT COUNT(*) FROM orders WHERE status = 'pending'
+
+## Notes
+
+- Seules les requêtes SELECT sont autorisées
+- Les requêtes sont exécutées en lecture seule
+- Les résultats sont limités à 100 lignes
+```
+
+### Exemple : Skill de validation
+
+```markdown title=".claude/skills/validate-email/SKILL.md"
+# Validate Email Skill
+
+Valide une adresse email et vérifie son format, domaine, et disponibilité.
+
+## Usage
+
+/validate-email <email>
+
+## Paramètres
+
+- `email` (required) - L'adresse email à valider
+
+## Comportement
+
+1. Vérifie le format de l'email (RFC 5322)
+2. Vérifie que le domaine existe (DNS lookup)
+3. Retourne un résultat structuré avec :
+   - `valid`: boolean
+   - `format_ok`: boolean
+   - `domain_exists`: boolean
+   - `suggestions`: string[] (si invalide)
+
+## Exemples
+
+/validate-email user@example.com
+/validate-email invalid.email@
+
+## Limites
+
+- Ne vérifie pas si l'adresse existe réellement (SMTP)
+- Timeout de 5 secondes pour la vérification DNS
+```
+
+### Exemple : Skill de calcul métier
+
+```markdown title=".claude/skills/calculate-shipping/SKILL.md"
+# Calculate Shipping Skill
+
+Calcule les frais de port en fonction du poids, destination, et type d'envoi.
+
+## Usage
+
+/calculate-shipping <weight> <country> [express]
+
+## Paramètres
+
+- `weight` (required) - Poids en kilogrammes
+- `country` (required) - Code pays (ISO 3166-1 alpha-2)
+- `express` (optional) - Ajoutez "express" pour expédition rapide
+
+## Tarification
+
+### Standard
+- France (FR): 5€ + 0.50€/kg
+- Europe (EU): 10€ + 1€/kg
+- International: 20€ + 2€/kg
+
+### Express (×1.5)
+Tous les tarifs standard multipliés par 1.5
+
+## Exemples
+
+/calculate-shipping 2.5 FR
+  → 6.25€ (Standard France)
+
+/calculate-shipping 5 DE express
+  → 22.50€ (Express Allemagne)
+
+/calculate-shipping 10 US
+  → 40€ (Standard International)
+
+## Notes
+
+- Poids maximum: 30kg
+- Certains pays peuvent être restreints
+- Les tarifs sont TTC
+```
+
+## Utiliser les Skills
+
+Une fois configurées, utilisez les skills dans vos prompts :
+
+```typescript
+import { streamText } from 'ai';
+import { claudeCode } from '@boostecom/provider';
+
+const result = streamText({
+  model: claudeCode('sonnet', {
+    settingSources: ['user', 'project'],
+    allowedTools: ['Skill', 'Read', 'Write'],
+  }),
+  prompt: 'Valide cet email: user@example.com et dis-moi s\'il est correct',
+});
+
+for await (const chunk of result.textStream) {
+  process.stdout.write(chunk);
+}
+```
+
+Claude détectera automatiquement qu'il doit utiliser la skill `/validate-email` et l'invoquera.
+
+## Skills complexes avec scripts
+
+Pour des skills plus complexes, vous pouvez créer des scripts exécutables :
+
+### Structure avec script
+
+```
+.claude/skills/api-client/
+  ├── SKILL.md
+  └── execute.js
+```
+
+```markdown title=".claude/skills/api-client/SKILL.md"
+# API Client Skill
+
+Effectue des requêtes HTTP vers l'API du projet.
+
+## Usage
+
+/api-client <method> <endpoint> [body]
+
+## Paramètres
+
+- `method` - GET, POST, PUT, DELETE
+- `endpoint` - Chemin de l'endpoint (ex: /users)
+- `body` - Corps de la requête (JSON, optionnel)
+
+## Exemples
+
+/api-client GET /users
+/api-client POST /users {"name":"Alice","email":"alice@example.com"}
+/api-client DELETE /users/123
+
+## Implémentation
+
+Cette skill exécute le script `execute.js` dans son répertoire.
+```
+
+```javascript title=".claude/skills/api-client/execute.js"
+#!/usr/bin/env node
+
+const [method, endpoint, bodyJson] = process.argv.slice(2);
+const API_BASE_URL = process.env.API_BASE_URL || 'http://localhost:3000';
+
+async function makeRequest() {
+  const options = {
+    method: method.toUpperCase(),
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${process.env.API_TOKEN}`,
+    },
+  };
+
+  if (bodyJson) {
+    options.body = bodyJson;
+  }
+
+  try {
+    const response = await fetch(`${API_BASE_URL}${endpoint}`, options);
+    const data = await response.json();
+
+    console.log(JSON.stringify({
+      status: response.status,
+      ok: response.ok,
+      data,
+    }, null, 2));
+  } catch (error) {
+    console.error(JSON.stringify({
+      error: error.message,
+    }));
+    process.exit(1);
+  }
+}
+
+makeRequest();
+```
+
+```bash
+# Rendre le script exécutable
+chmod +x .claude/skills/api-client/execute.js
+```
+
+## Best Practices
+
+### 1. Documentation claire
+
+Documentez précisément le comportement attendu :
+
+```markdown
+## Comportement
+
+1. Valide les paramètres d'entrée
+2. Effectue l'opération demandée
+3. Retourne un résultat structuré
+4. Gère les erreurs avec messages explicites
+```
+
+### 2. Exemples concrets
+
+Fournissez plusieurs exemples couvrant différents cas :
+
+```markdown
+## Exemples
+
+### Cas nominal
+/ma-skill param1 param2
+
+### Avec paramètres optionnels
+/ma-skill param1 param2 --option value
+
+### Cas d'erreur attendu
+/ma-skill invalid-input
+  → Erreur : Format invalide
+```
+
+### 3. Gestion d'erreurs
+
+Anticipez et documentez les erreurs possibles :
+
+```markdown
+## Erreurs possibles
+
+- `INVALID_FORMAT` - Le format du paramètre est incorrect
+- `NOT_FOUND` - La ressource n'existe pas
+- `PERMISSION_DENIED` - Accès non autorisé
+- `TIMEOUT` - L'opération a dépassé le délai
+```
+
+### 4. Limites et contraintes
+
+Indiquez clairement les limitations :
+
+```markdown
+## Limites
+
+- Maximum 100 résultats par requête
+- Timeout de 30 secondes
+- Certaines opérations nécessitent des permissions spécifiques
+- Rate limit: 60 requêtes par minute
+```
+
+### 5. Sécurité
+
+Pour les skills sensibles, documentez les aspects sécurité :
+
+```markdown
+## Sécurité
+
+- Cette skill nécessite la variable d'environnement `API_SECRET_KEY`
+- Les données sont chiffrées en transit
+- Les logs ne contiennent jamais de données sensibles
+- Accès restreint aux utilisateurs authentifiés
+```
+
+## Validation automatique
+
+Le provider émet un warning si la configuration est incomplète :
+
+```typescript
+// ⚠️ Warning: 'Skill' in allowedTools but no settingSources
+const model = claudeCode('sonnet', {
+  allowedTools: ['Skill'], // 'Skill' présent
+  // Manque: settingSources
+});
+```
+
+Solution :
+
+```typescript
+const model = claudeCode('sonnet', {
+  allowedTools: ['Skill'],
+  settingSources: ['user', 'project'], // ✅ Ajouté
+});
+```
+
+## Debugging des Skills
+
+### Activer les logs verbeux
+
+```typescript
+const model = claudeCode('sonnet', {
+  verbose: true, // Voir les invocations de skills
+  settingSources: ['user', 'project'],
+  allowedTools: ['Skill'],
+});
+```
+
+### Observer les appels de skills
+
+```typescript
+const result = streamText({
+  model: claudeCode('sonnet', {
+    settingSources: ['user', 'project'],
+    allowedTools: ['Skill'],
+    hooks: {
+      PreToolUse: [{
+        matcher: 'Skill',
+        hooks: [
+          async (toolName, input) => {
+            console.log('🎯 Skill invoquée:', toolName);
+            console.log('📥 Input:', JSON.stringify(input, null, 2));
+          },
+        ],
+      }],
+      PostToolUse: [{
+        matcher: 'Skill',
+        hooks: [
+          async (toolName, input, result) => {
+            console.log('✅ Skill terminée:', toolName);
+            console.log('📤 Résultat:', JSON.stringify(result, null, 2));
+          },
+        ],
+      }],
+    },
+  }),
+  prompt: 'Utilise la skill pour vérifier cet email',
+});
+```
+
+## Exemples de Skills utiles
+
+### 1. Git Operations
+
+```markdown title=".claude/skills/git-status/SKILL.md"
+# Git Status Skill
+
+Affiche le statut Git du projet avec résumé structuré.
+
+## Usage
+
+/git-status
+
+## Retour
+
+Objet JSON avec :
+- `branch` : branche courante
+- `modified` : fichiers modifiés
+- `staged` : fichiers en staging
+- `untracked` : fichiers non suivis
+- `ahead` : commits en avance
+- `behind` : commits en retard
+
+## Exemple
+
+/git-status
+```
+
+### 2. Environment Checker
+
+```markdown title=".claude/skills/check-env/SKILL.md"
+# Environment Checker Skill
+
+Vérifie que toutes les variables d'environnement requises sont définies.
+
+## Usage
+
+/check-env [file]
+
+## Paramètres
+
+- `file` (optional) - Fichier à vérifier (défaut: .env.example)
+
+## Comportement
+
+1. Lit les variables requises du fichier
+2. Vérifie leur présence dans l'environnement
+3. Retourne la liste des variables manquantes
+
+## Exemple
+
+/check-env .env.example
+```
+
+### 3. Test Runner
+
+```markdown title=".claude/skills/run-tests/SKILL.md"
+# Test Runner Skill
+
+Exécute les tests du projet et retourne un résumé.
+
+## Usage
+
+/run-tests [pattern]
+
+## Paramètres
+
+- `pattern` (optional) - Pattern des tests à exécuter (ex: "auth/*")
+
+## Retour
+
+- `passed` : nombre de tests réussis
+- `failed` : nombre de tests échoués
+- `duration` : durée totale en ms
+- `failures` : détails des échecs
+
+## Exemples
+
+/run-tests
+/run-tests auth/*
+/run-tests components/Button.test.ts
+```
+
+## Partager vos Skills
+
+### Organisation en packages
+
+Pour partager des skills entre projets :
+
+```bash
+# Créer un package de skills
+mkdir my-claude-skills
+cd my-claude-skills
+
+# Structure
+skills/
+  ├── skill-1/
+  │   └── SKILL.md
+  └── skill-2/
+      └── SKILL.md
+package.json
+README.md
+```
+
+```json title="package.json"
+{
+  "name": "my-claude-skills",
+  "version": "1.0.0",
+  "description": "Collection de skills Claude personnalisées",
+  "files": ["skills/**/*"]
+}
+```
+
+### Installation
+
+```bash
+# Installer le package
+npm install my-claude-skills
+
+# Créer des liens symboliques
+ln -s node_modules/my-claude-skills/skills/* .claude/skills/
+```
+
+## Ressources
+
+- [Exemples de Skills](/docs/examples) - Voir les skills en action
+- [API Reference](/docs/api) - Configuration détaillée
+- [Agent Teams](/docs/agent-teams) - Combiner Skills avec des équipes d'agents
+
+## Prochaines étapes
+
+- [Best Practices](/docs/best-practices) - Optimisations et patterns
+- [Troubleshooting](/docs/troubleshooting) - Résoudre les problèmes courants
+- [Agent Teams](/docs/agent-teams) - Créer des équipes d'agents spécialisés