Compétences

Compétences vs outils

Il est utile d'être clair sur la différence, car les deux résolvent des problèmes différents :

• Les outils connectent Claude à des données et des actions. « Recherchez cette section de code », « envoyez cet e-mail » — Claude appelle l'outil, et quelque chose d'autre s'exécute.
• Les Compétences enseignent à Claude une procédure. « Générez le rapport de statut quotidien en suivant ce modèle » — c'est un guide que Claude lit et suit, ce qui implique parfois d'exécuter lui-même des scripts intégrés.

Une façon simple de s'en souvenir : les outils concernent ce que Claude peut faire, tandis que les Compétences concernent comment vous voulez que ce soit fait.



Une dernière chose à savoir : les Compétences ne se chargent pas entièrement dans le contexte au démarrage. Seuls le nom et la description se chargent d'abord. Lorsque votre agent décide qu'une Compétence est pertinente, il charge alors la Compétence complète dans le contexte. Cela permet de garder votre contexte léger même lorsque de nombreuses Compétences sont disponibles.

Téléchargement d'une Compétence

Les Compétences sont téléchargées une fois dans votre espace de travail, puis référencées par ID. Vous pouvez les télécharger directement sur la Claude Platform, ou le faire de manière programmatique :

skill = client.skills.create(
    display_name="Status Report Generator",
    files=files_from_dir("status-report-skill"),  # folder containing SKILL.md
)

print(skill.id)  # reference this ID in future requests

Pour cet exemple, je veux un générateur de rapport de statut. Toutes les règles qui définissent un bon rapport de statut — sections, ton, façon de résumer, façon de gérer les blocages — résident dans une Compétence empaquetée à l'avance. Le journal d'activité lui-même n'est qu'une chaîne de caractères transmise au moment de la requête.

Attacher une Compétence à une requête

Les Compétences s'attachent à une requête via la configuration du conteneur — un tableau skills à l'intérieur du conteneur, où chaque entrée nomme un skill_id et une version. Voici l'appel complet pour le générateur de rapport de statut :

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    container={
        "skills": [
            {
                "type": "custom",
                "skill_id": skill.id,
                "version": "latest",
            }
        ]
    },
    tools=[
        {
            "type": "code_execution_20250825",
            "name": "code_execution",
        }
    ],
    messages=[
        {
            "role": "user",
            "content": f"Generate the daily status report from this activity log:\n\n{activity_log}",
        }
    ],
)

Quelques points à souligner :

• Nous appelons le client.messages.create standard, sans en-tête bêta. Les Compétences sont disponibles en version générale sur l'API Claude, donc l'en-tête bêta skills-2025-10-02 n'est plus requis ; les requêtes qui l'envoient encore continuent de fonctionner sans changement.
• container.skills est l'endroit où la Compétence s'attache. C'est une liste, vous pouvez donc superposer plusieurs Compétences sur un même appel.
• L'exécution de code est également activée ici. C'est requis : sur l'API, les Compétences s'exécutent à l'intérieur du conteneur de l'outil d'exécution de code, ce qui permet aux procédures des Compétences d'effectuer un travail réel — comme exécuter des scripts dans un terminal.

Exécution

Le résultat est un rapport de statut formaté exactement comme la Compétence indique de le formater. Sections, ton, gestion des blocages — tout cela provient du fichier SKILL.md que vous avez téléchargé. Le prompt utilisateur est une seule ligne ; la procédure réside dans la Compétence.



Dans une application de production, c'est ainsi qu'une équipe standardise les résultats sur l'ensemble d'une fonctionnalité. Avec ce point de terminaison de rapport de statut quotidien, chaque chef de projet obtient la même structure, le même ton, les mêmes sections, dans le même ordre — sans que personne n'ait à copier-coller un modèle dans un prompt.



Récapitulatif

• Les Compétences empaquettent vos procédures. Un fichier SKILL.md (ainsi que tous les scripts et ressources) enseigne à Claude comment vous voulez que quelque chose soit fait.
• Outils vs Compétences : les outils concernent ce que Claude peut faire ; les Compétences concernent comment vous voulez que ce soit fait.
• Les Compétences se chargent progressivement. Seuls le nom et la description se chargent au démarrage ; la Compétence complète se charge dans le contexte lorsque l'agent décide de l'utiliser.
• Téléchargez une fois avec client.skills.create, puis attachez avec container.skills sur n'importe quel appel messages.create — une liste, vous pouvez donc superposer plusieurs Compétences.
• Associez-la à l'exécution de code lorsque la procédure de la Compétence doit effectuer un travail réel.
• Utilisez une Compétence lorsque le comment compte autant que le quoi.