Compétences internes de Claude : Modules personnalisés qui étendent Claude

Plateforme de développement Claude (API)

Les compétences de Claude sont également accessibles via l'API Claude. Dans cette section, nous examinerons comment reproduire l'interface de l'application Claude via l'API Claude.

Étape 1 : Conditions préalables

Veuillez commencer par installer toutes les dépendances d'exécution :

• Anthropic pour l'API Claude Messages

• pandas et openpyxl pour lire les feuilles de temps à partir d'Excel

• reportlab pour générer localement une facture PDF de secours 

!pip -q install anthropic pandas openpyxl reportlab

Toutes les dépendances sont désormais installées.  Ensuite, nous pouvons configurer notre clé API.

Étape 2 : Veuillez configurer votre clé API.

Avant de pouvoir appeler l'API Messages, nous devons procéder à l'authentification. anthropic.Client Cette étape permet de créer une autorisation unique et réutilisable avec la clé API. 

import os, json, sys, re
import anthropic
from datetime import datetime, timedelta
API_KEY = "YOUR_ANTHROPIC_API_KEY"
client = anthropic.Client(api_key=API_KEY)

Veuillez vous connecter à Anthropic Console et localiser l'onglet Clés API sous Paramètres. Veuillez cliquer sur « » (Créer une clé), puis copiez votre clé API Anthropic.

Source : API Anthropic

Remarque : Si vous utilisez un bloc-notes privé à des fins personnelles, veuillez ajouter votre clé API. Dans le cas contraire, veuillez utiliser une variable d'environnement sécurisée afin que votre clé ne soit pas exposée dans le bloc-notes ou les journaux.

Le code ci-dessus initialise le client SDK Anthropic et configure l'environnement. L'objet client est ensuite réutilisé pour tous les appels API Messages suivants.

Étape 3 : Pré-traitement des données

Dans cette étape, nous allons transformer notre feuille d'timesheet.xlsxs en un objet JSON propre et prévisible que la compétence peut utiliser. Cela permet de simplifier la logique en aval et d'éviter une analyse syntaxique fragile.

def load_invoice_from_timesheet(excel_path):
    import pandas as pd
    df = pd.read_excel(excel_path)
    df.columns = df.columns.str.strip()  
    invoice_period = "2025-10"
    if 'Date' in df.columns:
        first_date = str(df['Date'].iloc[0])
        date_match = re.search(r'(\d{2})\s+(\w+)\s+(\d{4})', first_date)
        if date_match:
            month_name = date_match.group(2)
            year = date_match.group(3)
            month_num = datetime.strptime(month_name[:3], '%b').month
            invoice_period = f"{year}-{month_num:02d}"   
    article_col = next((col for col in df.columns if 'article' in col.lower() and 'name' in col.lower()), None)
    amount_col = next((col for col in df.columns if 'amount' in col.lower()), None)
    topic_col = next((col for col in df.columns if 'topic' in col.lower()), None)
    line_items = []
    timesheet_articles = []
    
    for idx, row in df.iterrows():
        if pd.isna(row.get(article_col)) or row.get(article_col) == '':
            continue    
        article_name = str(row[article_col]).strip()
        amount = row.get(amount_col, 0) 
        if isinstance(amount, str):
            amount = float(amount.replace('$', '').replace(',', '').strip())
        line_items.append({
            "title": article_name,
            "rate_type": "flat",
            "qty": 1,
            "rate": float(amount)
        })  
        timesheet_articles.append({
            "title": article_name,
            "topic": str(row.get(topic_col, 'N/A')) if topic_col else 'N/A'
        })
    return {
        "client_name": "Client",
        "billing_contact": "billing@example.com",
        "invoice_period": invoice_period,
        "currency": "USD",
        "payment_terms": "Net-30",
        "line_items": line_items,
        "discount_pct": 0.0,
        "tax_pct": 0.0,
        "timesheet": timesheet_articles
    }

La fonction load_invoice_from_timesheet convertit un fichier Excel téléchargé en une charge utile JSON normalisée de facture.

• Il lit le fichier Excel à l'aide de pandas et normalise les en-têtes de colonnes.

• Le code déduit ensuite l'adresse invoice_period à partir de la première ligne Date (si elle existe) à l'aide d'une expression régulière et d'une analyse du mois.

• Il détecte enfin les noms des colonnes pour le titre de l'article, le montant et le sujet sans tenir compte de la casse.

• Cela génère deux structures :

• line_items: Ceci est utilisé pour le calcul de la facturation (tarif forfaitaire par article dans ce cas).

• timesheet: Liste plate des entrées d'{title, topic} s pour une annexe facultative.

• L'expression régulière (\d{2})\s+(\w+)\s+(\d{4}) attend des formats tels que 01 Oct 2025. Veuillez l'ajuster si votre feuille utilise un autre format.

• Les colonnes/valeurs manquantes sont gérées en ignorant les lignes vides, ou vous pouvez étendre le code pour qu'il échoue rapidement si nécessaire.

Notre contribution est désormais prête. Ensuite, nous ferons appel à la compétence Claude via l'API pour transformer la feuille de temps traitée en une facture modifiable.

Étape 4 : Fonctions d'assistance

Dans cette section, nous définissons deux fonctions d'aide qui simulent l'exécution de l'outil demandé par Claude lors d'une exécution de compétence. 

def execute_bash_tool(command):
    try:
        dangerous = ['rm -rf /', 'sudo', 'chmod', 'mkfs', '> /dev/']
        if any(d in command for d in dangerous):
            return f"Error: Command blocked for safety: {command}"
        result = subprocess.run(
            command, 
            shell=True, 
            capture_output=True, 
            text=True, 
            timeout=30,
            cwd=tempfile.gettempdir()
        )    
        output = result.stdout if result.stdout else result.stderr
        return output if output else "Command executed successfully"
    except subprocess.TimeoutExpired:
        return "Error: Command timed out"
    except Exception as e:
        return f"Error executing command: {str(e)}"
def execute_text_editor_tool(params):
    try:
        command = params.get('command')
        path = params.get('path')   
        if command == 'create':
            file_text = params.get('file_text', '')
            os.makedirs(os.path.dirname(path) if os.path.dirname(path) else '.', exist_ok=True)
            with open(path, 'w') as f:
                f.write(file_text)
            return f"File created: {path}"
        elif command == 'view':
            if os.path.exists(path):
                with open(path, 'r') as f:
                    content = f.read()
                return content[:1000] 
            return f"Error: File not found: {path}"   
        elif command == 'str_replace':
            if os.path.exists(path):
                with open(path, 'r') as f:
                    content = f.read()
                old_str = params.get('old_str', '')
                new_str = params.get('new_str', '')
                content = content.replace(old_str, new_str)
                with open(path, 'w') as f:
                    f.write(content)
                return f"File updated: {path}"
            return f"Error: File not found: {path}"    
        return f"Unknown command: {command}"
    except Exception as e:
        return f"Error: {str(e)}"

La fonction execute_bash_tool simule un outil bash sécurisé pour les actions basées sur les compétences. Il bloque d'abord les modèles dangereux tels que rm -rf /, sudo, chmod, mkfs, etc., comme une porte de sécurité, et exécute la commande avec subprocess.run() dans le répertoire temporaire du système d'exploitation avec un délai d'expiration imposé de 30 secondes.

La fonction ` execute_text_editor_tool ` fournit une interface minimale d'édition de texte utilisée par Skills. Il prend en charge trois commandes, à savoir « create » (pour créer un nouveau fichier avec l'file_text), « view » (pour renvoyer jusqu'à 1 000 caractères d'un fichier) et « str_replace » (pour l'new_str in place). Il crée également automatiquement des dossiers parents pour create, vérifie l'existence des fichiers pour view et str_replace, et enregistre les mises à jour sur le disque.

Ces assistants vous permettent de réaliser localement une boucle d'utilisation d'outils avec des garde-fous. Désormais, Skill peut demander des modifications de fichiers ou des actions shell pendant la génération des factures sans compromettre la sécurité de votre système.

Étape 5 : Veuillez invoquer la compétence via l'API. 

Cette étape permet la génération de factures de bout en bout via l'API Claude Messages. Il envoie une requête structurée, active l'utilisation des outils, effectue des itérations sur tous les appels d'outils demandés par Claude et, enfin, collecte tous les fichiers PDF générés à partir des répertoires de travail et temporaires.

def generate_invoice_with_claude(invoice): 
    user_text = f"""Generate a professional PDF invoice with the following data:
Client: {invoice['client_name']}
Period: {invoice['invoice_period']}
Currency: {invoice['currency']}
Payment Terms: {invoice['payment_terms']}
Line Items:
{json.dumps(invoice['line_items'], indent=2)}
Timesheet Articles:
{json.dumps(invoice['timesheet'], indent=2)}
Please create a professional PDF invoice with:
1. Invoice header with invoice number (INV-{invoice['invoice_period'].replace('-', '')}-001)
2. Client billing information
3. Line items table with amounts
4. Subtotal and total calculations
5. Timesheet section showing all articles and topics
Save the PDF as: invoice_{invoice['client_name'].lower()}_{invoice['invoice_period']}.pdf
""" 
    tools = [
        {"type": "bash_20250124", "name": "bash"},
        {"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}
    ]
    messages = [{"role": "user", "content": user_text}]
    iteration = 0
    max_iterations = 15   
    while iteration < max_iterations:
        iteration += 1
        response = client.messages.create(
            model="claude-sonnet-4-20250514",
            max_tokens=8192,
            tools=tools,
            messages=messages
        )   
        messages.append({"role": "assistant", "content": response.content}) 
        if response.stop_reason == "end_turn":
            break     
        if response.stop_reason == "tool_use":
            tool_results = []    
            for block in response.content:
                if block.type == "tool_use":
                    tool_name = block.name
                    tool_input = block.input
                    if tool_name == "bash":
                        result = execute_bash_tool(tool_input.get('command', ''))
                    elif tool_name == "str_replace_based_edit_tool":
                        result = execute_text_editor_tool(tool_input)
                    else:
                        result = f"Unknown tool: {tool_name}" 
                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": result
                    })
            messages.append({"role": "user", "content": tool_results})
        else:
            break
    pdf_files = []
    for file in os.listdir('.'):
        if file.endswith('.pdf') and 'invoice' in file.lower():
            pdf_files.append(file)
    for file in os.listdir(tempfile.gettempdir()):
        if file.endswith('.pdf') and 'invoice' in file.lower():
            temp_path = os.path.join(tempfile.gettempdir(), file)
            import shutil
            dest_path = os.path.join('.', file)
            shutil.copy2(temp_path, dest_path)
            pdf_files.append(file)   
    return pdf_files
def main():
    if len(sys.argv) < 2:
        print("Usage: python app.py <timesheet.xlsx>")
        sys.exit(1)    
    excel_file = sys.argv[1]  
    if not os.path.exists(excel_file):
        print(f"Error: File not found: {excel_file}")
        sys.exit(1)    
    try:
        invoice = load_invoice_from_timesheet(excel_file)
        pdf_files = generate_invoice_with_claude(invoice)    
        if pdf_files:
            for pdf in pdf_files:
                print(f"Invoice generated: {os.path.abspath(pdf)}")
        else:
            print("Error: No PDF file was generated.")     
    except Exception as e:
        print(f"Error: {e}")
        import traceback
        traceback.print_exc()
        sys.exit(1)
if __name__ == "__main__":
    main()

La fonction generate_invoice_with_claude envoie la facture normalisée à l'API Claude et gère l'exécution de la compétence de bout en bout. Voici ce que fait le code :

• user_text Il crée une structure claire qui intègre le client, la période, la devise, les conditions, les lignes et les entrées de feuille de temps, ainsi que des exigences de sortie explicites telles que l'en-tête, les tableaux, les totaux et le nom de fichier.

• Il permet ensuite l'exécution de l'outil en déclarant un bash_number et un text_editor_number avec une boucle de messages compatible avec l'outil qui envoie la demande, inspecte stop_reason et, lorsque tool_use est demandé, le transmet aux assistants locaux et renvoie tool_result des blocs pour poursuivre l'échange.

• Enfin, il s'arrête sur end_turn ou lorsque la limite de boucle est atteinte, puis analyse le répertoire de travail et le répertoire temporaire du système d'exploitation à la recherche de fichiers correspondant à invoice*.pdf. Il recopie tous les fichiers temporaires dans le dossier du projet et renvoie la liste des fichiers PDF détectés.

• La fonction main fournit une commande CLI simple : python app.py , qui valide le chemin d'accès saisi, puis exécute le pipeline : load_invoice_from_timesheet(...) pour créer la charge utile, et generate_invoice_with_claude(...) pour invoquer la compétence et collecter les fichiers PDF.

Une fois cela mis en place, l'appel API devrait générer un fichier PDF prêt à être utilisé par le client. Si aucun fichier n'apparaît, veuillez vérifier les journaux d'tool_result s et la configuration des compétences, puis réessayez avec une petite feuille de test.

Conclusion

Vous disposez désormais d'un générateur de factures automatique fonctionnel, optimisé par Claude Skills, et l'API est capable de transformer des feuilles de calcul brutes en factures prêtes à être envoyées aux clients. Cette démonstration met en avant les points forts de Skills, à savoir une configuration portable, une activation automatique, une exécution déterministe du code et des résultats cohérents dans l'application et l'API sans avoir à recréer les invites dans chaque thread. Claude Skills fournit des résultats cohérents dans différents contextes, qui sont des connaissances réutilisables dans le domaine et soutenues par du code. Bien que les compétences puissent exécuter du code, il est important de renforcer la sécurité en n'activant que les compétences fiables, en utilisant des contrôles au niveau de l'organisation et en examinant les mises à jour avant leur déploiement.

Pour approfondir vos connaissances, veuillez consulter la documentation sur les compétences d'Anthropic et la console pour la gestion des versions et les mises à niveau, puis commencez à créer plusieurs compétences afin de mettre en place des flux de travail de bout en bout.