Bonnes pratiques de création de Skills

## Extraire le texte d'un PDF

Utilisez pdfplumber pour l'extraction de texte :

```python
import pdfplumber

with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

## Extraire le texte d'un PDF

PDF (Portable Document Format) est un format de fichier courant qui contient
du texte, des images et d'autres contenus. Pour extraire du texte d'un PDF, vous devrez
utiliser une bibliothèque. Il existe de nombreuses bibliothèques disponibles pour le traitement des PDF, mais nous
recommandons pdfplumber car elle est facile à utiliser et gère bien la plupart des cas.
D'abord, vous devrez l'installer en utilisant pip. Ensuite, vous pouvez utiliser le code ci-dessous...

## Processus d'examen du code

1. Analyser la structure et l'organisation du code
2. Vérifier les bugs potentiels ou les cas limites
3. Suggérer des améliorations pour la lisibilité et la maintenabilité
4. Vérifier le respect des conventions du projet

## Générer un rapport

Utilisez ce modèle et personnalisez-le selon vos besoins :

```python
def generate_report(data, format="markdown", include_charts=True):
    # Traiter les données
    # Générer la sortie au format spécifié
    # Inclure optionnellement des visualisations
```

## Migration de base de données

Exécutez exactement ce script :

```bash
python scripts/migrate.py --verify --backup
```

Ne modifiez pas la commande et n'ajoutez pas de drapeaux supplémentaires.

description: Extrait le texte et les tableaux des fichiers PDF, remplit les formulaires, fusionne les documents. À utiliser lors du travail avec des fichiers PDF ou lorsque l'utilisateur mentionne les PDF, les formulaires ou l'extraction de documents.

description: Analyse les feuilles de calcul Excel, crée des tableaux croisés dynamiques, génère des graphiques. À utiliser lors de l'analyse de fichiers Excel, de feuilles de calcul, de données tabulaires ou de fichiers .xlsx.

description: Génère des messages de validation descriptifs en analysant les diffs git. À utiliser lorsque l'utilisateur demande de l'aide pour rédiger des messages de validation ou pour examiner les modifications en attente.

description: Aide avec les documents

description: Traite les données

description: Fait des choses avec les fichiers

pdf/
├── SKILL.md              # Instructions principales (chargées lorsque déclenchées)
├── FORMS.md              # Guide de remplissage de formulaires (chargé selon les besoins)
├── reference.md          # Référence API (chargée selon les besoins)
├── examples.md           # Exemples d'utilisation (chargés selon les besoins)
└── scripts/
    ├── analyze_form.py   # Script utilitaire (exécuté, non chargé)
    ├── fill_form.py      # Script de remplissage de formulaires
    └── validate.py       # Script de validation

---
name: pdf-processing
description: Extrait le texte et les tableaux des fichiers PDF, remplit les formulaires et fusionne les documents. À utiliser lors du travail avec des fichiers PDF ou lorsque l'utilisateur mentionne les PDF, les formulaires ou l'extraction de documents.
---

# Traitement PDF

## Démarrage rapide

Extrayez le texte avec pdfplumber :
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

## Fonctionnalités avancées

**Remplissage de formulaires** : Consultez [FORMS.md](FORMS.md) pour le guide complet
**Référence API** : Consultez [REFERENCE.md](REFERENCE.md) pour toutes les méthodes
**Exemples** : Consultez [EXAMPLES.md](EXAMPLES.md) pour les modèles courants

bigquery-skill/
├── SKILL.md (aperçu et navigation)
└── reference/
    ├── finance.md (revenus, métriques de facturation)
    ├── sales.md (opportunités, pipeline)
    ├── product.md (utilisation API, fonctionnalités)
    └── marketing.md (campagnes, attribution)

# Traitement DOCX

## Créer des documents

Utilisez docx-js pour les nouveaux documents. Consultez [DOCX-JS.md](DOCX-JS.md).

## Éditer des documents

Pour les modifications simples, modifiez directement le XML.

**Pour les modifications suivies** : Consultez [REDLINING.md](REDLINING.md)
**Pour les détails OOXML** : Consultez [OOXML.md](OOXML.md)

# SKILL.md
Consultez [advanced.md](advanced.md)...

# advanced.md
Consultez [details.md](details.md)...

# details.md
Voici l'information réelle...

# SKILL.md

**Utilisation de base** : [instructions dans SKILL.md]
**Fonctionnalités avancées** : Consultez [advanced.md](advanced.md)
**Référence API** : Consultez [reference.md](reference.md)
**Exemples** : Consultez [examples.md](examples.md)

# Référence API

## Contenu
- Authentification et configuration
- Méthodes principales (créer, lire, mettre à jour, supprimer)
- Fonctionnalités avancées (opérations par lot, webhooks)
- Modèles de gestion des erreurs
- Exemples de code

## Authentification et configuration
...

## Méthodes principales
...

## Flux de travail de synthèse de recherche

Copiez cette liste de contrôle et suivez votre progression :

```
Progression de la recherche :
- [ ] Étape 1 : Lire tous les documents sources
- [ ] Étape 2 : Identifier les thèmes clés
- [ ] Étape 3 : Recouper les affirmations
- [ ] Étape 4 : Créer un résumé structuré
- [ ] Étape 5 : Vérifier les citations
```

**Étape 1 : Lire tous les documents sources**

Examinez chaque document du répertoire `sources/`. Notez les arguments principaux et les preuves à l'appui.

**Étape 2 : Identifier les thèmes clés**

Recherchez des modèles dans les sources. Quels thèmes apparaissent à plusieurs reprises ? Où les sources sont-elles d'accord ou en désaccord ?

**Étape 3 : Recouper les affirmations**

Pour chaque affirmation majeure, vérifiez qu'elle apparaît dans le matériel source. Notez quelle source soutient chaque point.

**Étape 4 : Créer un résumé structuré**

Organisez les résultats par thème. Incluez :
- Affirmation principale
- Preuves à l'appui des sources
- Points de vue conflictuels (le cas échéant)

**Étape 5 : Vérifier les citations**

Vérifiez que chaque affirmation référence le document source correct. Si les citations sont incomplètes, retournez à l'étape 3.

## Flux de travail de remplissage de formulaire PDF

Copiez cette liste de contrôle et cochez les éléments au fur et à mesure que vous les complétez :

```
Progression de la tâche :
- [ ] Étape 1 : Analyser le formulaire (exécuter analyze_form.py)
- [ ] Étape 2 : Créer un mappage de champs (éditer fields.json)
- [ ] Étape 3 : Valider le mappage (exécuter validate_fields.py)
- [ ] Étape 4 : Remplir le formulaire (exécuter fill_form.py)
- [ ] Étape 5 : Vérifier la sortie (exécuter verify_output.py)
```

**Étape 1 : Analyser le formulaire**

Exécutez : `python scripts/analyze_form.py input.pdf`

Cela extrait les champs du formulaire et leurs emplacements, en les enregistrant dans `fields.json`.

**Étape 2 : Créer un mappage de champs**

Éditez `fields.json` pour ajouter des valeurs pour chaque champ.

**Étape 3 : Valider le mappage**

Exécutez : `python scripts/validate_fields.py fields.json`

Corrigez les erreurs de validation avant de continuer.

**Étape 4 : Remplir le formulaire**

Exécutez : `python scripts/fill_form.py input.pdf fields.json output.pdf`

**Étape 5 : Vérifier la sortie**

Exécutez : `python scripts/verify_output.py output.pdf`

Si la vérification échoue, retournez à l'étape 2.

## Processus d'examen du contenu

1. Rédigez votre contenu en suivant les directives du STYLE_GUIDE.md
2. Examinez par rapport à la liste de contrôle :
   - Vérifier la cohérence de la terminologie
   - Vérifier que les exemples suivent le format standard
   - Confirmer que toutes les sections requises sont présentes
3. Si des problèmes sont trouvés :
   - Notez chaque problème avec une référence de section spécifique
   - Révisez le contenu
   - Examinez à nouveau la liste de contrôle
4. Procédez uniquement lorsque toutes les exigences sont satisfaites
5. Finalisez et enregistrez le document

## Processus d'édition de document

1. Effectuez vos modifications dans `word/document.xml`
2. **Validez immédiatement** : `python ooxml/scripts/validate.py unpacked_dir/`
3. Si la validation échoue :
   - Examinez attentivement le message d'erreur
   - Corrigez les problèmes dans le XML
   - Exécutez à nouveau la validation
4. **Procédez uniquement lorsque la validation réussit**
5. Reconstruisez : `python ooxml/scripts/pack.py unpacked_dir/ output.docx`
6. Testez le document de sortie

Si vous faites cela avant août 2025, utilisez l'ancienne API.
Après août 2025, utilisez la nouvelle API.

## Méthode actuelle

Utilisez le point de terminaison de l'API v2 : `api.example.com/v2/messages`

## Anciens modèles

<details>
<summary>API v1 héritée (dépréciée 2025-08)</summary>

L'API v1 utilisait : `api.example.com/v1/messages`

Ce point de terminaison n'est plus pris en charge.
</details>

## Structure du rapport

UTILISEZ TOUJOURS cette structure de modèle exacte :

```markdown
# [Titre de l'analyse]

## Résumé exécutif
[Aperçu d'une phrase des résultats clés]

## Résultats clés
- Résultat 1 avec données de soutien
- Résultat 2 avec données de soutien
- Résultat 3 avec données de soutien

## Recommandations
1. Recommandation spécifique et exploitable
2. Recommandation spécifique et exploitable
```

## Structure du rapport

Voici un format par défaut sensé, mais utilisez votre meilleur jugement en fonction de l'analyse :

```markdown
# [Titre de l'analyse]

## Résumé exécutif
[Aperçu]

## Résultats clés
[Adaptez les sections en fonction de ce que vous découvrez]

## Recommandations
[Adaptez au contexte spécifique]
```

Ajustez les sections selon les besoins pour le type d'analyse spécifique.

## Format du message de validation

Générez des messages de validation en suivant ces exemples :

**Exemple 1 :**
Entrée : Ajout de l'authentification utilisateur avec des jetons JWT
Sortie :
```
feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware
```

**Exemple 2 :**
Entrée : Correction d'un bug où les dates s'affichaient incorrectement dans les rapports
Sortie :
```
fix(reports): correct date formatting in timezone conversion

Use UTC timestamps consistently across report generation
```

**Exemple 3 :**
Entrée : Mise à jour des dépendances et refactorisation de la gestion des erreurs
Sortie :
```
chore: update dependencies and refactor error handling

- Upgrade lodash to 4.17.21
- Standardize error response format across endpoints
```

Suivez ce style : type(scope): description brève, puis explication détaillée.

## Flux de travail de modification de document

1. Déterminez le type de modification :

   **Créer du nouveau contenu ?** → Suivez le « Flux de travail de création » ci-dessous
   **Éditer du contenu existant ?** → Suivez le « Flux de travail d'édition » ci-dessous

2. Flux de travail de création :
   - Utilisez la bibliothèque docx-js
   - Construisez le document à partir de zéro
   - Exportez au format .docx

3. Flux de travail d'édition :
   - Décompressez le document existant
   - Modifiez directement le XML
   - Validez après chaque modification
   - Recompressez une fois terminé

{
  "skills": ["pdf-processing"],
  "query": "Extrayez tout le texte de ce fichier PDF et enregistrez-le dans output.txt",
  "files": ["test-files/document.pdf"],
  "expected_behavior": [
    "Lit avec succès le fichier PDF en utilisant une bibliothèque appropriée de traitement PDF ou un outil de ligne de commande",
    "Extrait le contenu textuel de toutes les pages du document sans manquer aucune page",
    "Enregistre le texte extrait dans un fichier nommé output.txt dans un format clair et lisible"
  ]
}

**Mauvais exemple : Trop de choix** (confus) :
« Vous pouvez utiliser pypdf, ou pdfplumber, ou PyMuPDF, ou pdf2image, ou... »

**Bon exemple : Fournir une valeur par défaut** (avec échappatoire) :
« Utilisez pdfplumber pour l'extraction de texte :
```python
import pdfplumber
```

Pour les PDF numérisés nécessitant l'OCR, utilisez pdf2image avec pytesseract à la place. »

def process_file(path):
    """Traiter un fichier, le créer s'il n'existe pas."""
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        # Créer le fichier avec le contenu par défaut au lieu d'échouer
        print(f"Fichier {path} non trouvé, création par défaut")
        with open(path, 'w') as f:
            f.write('')
        return ''
    except PermissionError:
        # Fournir une alternative au lieu d'échouer
        print(f"Impossible d'accéder à {path}, utilisation de la valeur par défaut")
        return ''

def process_file(path):
    # Échouer simplement et laisser Claude comprendre
    return open(path).read()

# Les requêtes HTTP se terminent généralement en 30 secondes
# Un délai d'expiration plus long tient compte des connexions lentes
REQUEST_TIMEOUT = 30

# Trois tentatives équilibrent la fiabilité et la vitesse
# La plupart des défaillances intermittentes se résolvent à la deuxième tentative
MAX_RETRIES = 3

TIMEOUT = 47  # Pourquoi 47 ?
RETRIES = 5   # Pourquoi 5 ?

## Scripts utilitaires

**analyze_form.py** : Extraire tous les champs du formulaire du PDF

```bash
python scripts/analyze_form.py input.pdf > fields.json
```

Format de sortie :
```json
{
  "field_name": {"type": "text", "x": 100, "y": 200},
  "signature": {"type": "sig", "x": 150, "y": 500}
}
```

**validate_boxes.py** : Vérifier les boîtes de délimitation qui se chevauchent

```bash
python scripts/validate_boxes.py fields.json
# Retourne : « OK » ou liste les conflits
```

**fill_form.py** : Appliquer les valeurs de champ au PDF

```bash
python scripts/fill_form.py input.pdf fields.json output.pdf
```

## Analyse de la disposition du formulaire

1. Convertir le PDF en images :
   ```bash
   python scripts/pdf_to_images.py form.pdf
   ```

2. Analyser chaque image de page pour identifier les champs du formulaire
3. Claude peut voir les emplacements et les types de champs visuellement

bigquery-skill/
├── SKILL.md (aperçu, pointe vers les fichiers de référence)
└── reference/
    ├── finance.md (métriques de revenus)
    ├── sales.md (données de pipeline)
    └── product.md (analyse d'utilisation)

Utilisez l'outil BigQuery:bigquery_schema pour récupérer les schémas de table.
Utilisez l'outil GitHub:create_issue pour créer des problèmes.

**Mauvais exemple : Suppose l'installation** :
« Utilisez la bibliothèque pdf pour traiter le fichier. »

**Bon exemple : Explicite sur les dépendances** :
« Installez le package requis : `pip install pypdf`

Ensuite, utilisez-le :
```python
from pypdf import PdfReader
reader = PdfReader("file.pdf")
```"