Skills custom, SDK Anthropic et vision

Pourquoi ce module

Jour 3 du tronc commun. On passe de l'utilisateur avancé au créateur : packager vos procédures récurrentes en skills réutilisables, exploiter les SDK Anthropic (intégration applicative et construction d'agents), et la vision multimodale (images, PDF natif).

Une skill remplace le copier-coller éternel de la même checklist : son corps ne se charge que quand elle sert, donc une longue procédure ne coûte presque rien tant qu'on ne l'invoque pas.

Objectifs pédagogiques

À l'issue de ce module, vous serez capable de :

1. Concevoir une skill : SKILL.md, frontmatter, fichiers de support
2. Contrôler l'invocation (vous, Claude, ou les deux) et l'exécution en sous-agent
3. Distinguer les deux SDK : Messages API (@anthropic-ai/sdk) vs Agent SDK (@anthropic-ai/claude-agent-sdk)
4. Exploiter streaming, tool use et structured output via le SDK
5. Utiliser la vision : images et PDF natif, extraction structurée

Plan détaillé

1. Skills : principe et standard ouvert
2. Où vivent les skills (perso / projet / plugin)
3. Anatomie : frontmatter + contenu + fichiers de support
4. Contrôle d'invocation, sous-agent, contexte dynamique
5. Skills bundled & fusion commandes → skills
6. Plugins : packaging et gestion en CLI
7. Les deux SDK : Messages API vs Agent SDK
8. Tool use et structured output
9. Vision multimodale (images, PDF natif)
10. Atelier : coder une skill + un script d'extraction

Skills : principe et standard ouvert

Une skill est un dossier contenant un SKILL.md (instructions). Claude la charge automatiquement quand elle est pertinente (d'après sa description), ou vous l'invoquez directement avec /<nom> — et depuis la v2.1.199, on peut empiler jusqu'à 5 skills en tête de prompt (/audit-seo /humanize réécris cette page) : toutes les skills en préfixe sont chargées, pas seulement la première. Les skills Claude Code suivent le standard ouvert Agent Skills (agentskills.io), interopérable entre outils, que Claude Code étend (contrôle d'invocation, exécution en sous-agent, injection de contexte dynamique).

💡 La skill montrée ici (/veille-formation) est un exemple réel : elle récupère les nouveautés Claude Code et propose des mises à jour de ce cursus.

ℹ️ Les commandes custom ont fusionné dans les skills. .claude/commands/deploy.md et .claude/skills/deploy/SKILL.md créent tous deux /deploy. Vos anciens .claude/commands/ continuent de marcher ; les skills ajoutent les fichiers de support et le frontmatter.

Où vivent les skills

Les dossiers de skills sont surveillés : ajouter/éditer une skill prend effet dans la session courante, sans redémarrage (sauf création d'un dossier skills/ qui n'existait pas au démarrage). En monorepo, les skills se chargent depuis .claude/skills/ jusqu'à la racine + à la demande dans les sous-dossiers.

📁 Skills imbriqués (v2.1.178). Les skills placées dans des dossiers .claude/skills/ des répertoires imbriqués du projet (ex. packages/api/.claude/skills/audit/SKILL.md) se chargent désormais quand vous travaillez sur des fichiers dans ce répertoire. La découverte récursive de skills dans des sous-dossiers imbriqués au sein d'un même .claude/skills/ (ex. .claude/skills/audit/sub/SKILL.md) n'est pas supportée en v2.1.178 et reste une demande de fonctionnalité ouverte.

Anatomie : frontmatter + contenu + fichiers de support

Un SKILL.md = frontmatter YAML (entre ---) + contenu markdown (les instructions). Le nom du dossier devient la commande ; la description aide Claude à décider quand charger la skill.

---
name: summarize-changes
description: Résume les changements non commités et signale ce qui est risqué
---

Analyse `git diff` et produis :
1. Un résumé par zone (frontend / backend / migrations)
2. Une liste des points risqués (secrets, suppressions, ruptures d'API)
3. Une suggestion de message de commit conventionnel

Contenu « tâche » à invoquer manuellement (déploiement, commit…) : ajouter disable-model-invocation: true pour empêcher Claude de la déclencher seul.

---
name: deploy
description: Déploie l'application en production
disable-model-invocation: true
---

Pour les skills complexes, on éclate en plusieurs fichiers (le SKILL.md reste focalisé et référence des STAGES.md / RULES.md / EXAMPLES.md). Claude Code permet aussi d'exécuter une skill en sous-agent (isolation de contexte) et d'injecter du contexte dynamique (ex. pousser le git diff réel dans le prompt avant lecture).

Skills bundled

Claude Code embarque des skills disponibles partout : /code-review, /batch, /debug, /loop, /claude-api. Contrairement aux commandes internes (/help, /compact) à logique fixe, ce sont des skills prompt-based que Claude orchestre avec ses outils.

🙈 Les masquer au modèle — disableBundledSkills (v2.1.169). Ce setting cache les skills bundled au modèle : il ne les voit plus et ne les déclenche plus automatiquement. Utile quand vos skills projet couvrent déjà le besoin (et qu'on veut éviter que Claude parte sur /code-review au lieu de votre revue maison), ou pour réduire le bruit de sélection dans un contexte très cadré.

Plugins : packaging et gestion en CLI

Un plugin empaquète des skills (et hooks, MCP, agents) pour les distribuer d'un bloc. Les commandes pratiques :

🔗 La distribution publique et la monétisation d'un plugin/skill sont traitées en approfondissement M14 (marketplace).

Les deux SDK : ne pas les confondre

⚠️ Renommage 2026 : le « Claude Code SDK » est devenu le Claude Agent SDK (@anthropic-ai/claude-code → @anthropic-ai/claude-agent-sdk), pour refléter qu'il sert à bâtir des agents au-delà du code. Pour une simple intégration d'API (vision, tool use), c'est le Messages API SDK qu'il vous faut.

Streaming + tool use + structured output (Messages API SDK)

from anthropic import Anthropic
client = Anthropic()

with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Résume ce ticket…"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="")

• Tool use : déclarer des outils (JSON Schema), gérer le round-trip multi-tour.
• Structured output : imposer un schéma de sortie pour un JSON exploitable directement.
• Retry : backoff exponentiel, gestion des rate limits, idempotency keys.

Vision multimodale (images, PDF natif)

L'API accepte des images (base64 ou URL) et des PDF nativement (multi-pages, mise en page, OCR intégré) — pas besoin de pré-OCR externe pour la plupart des documents.

client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {"type": "document", "source": {"type": "base64",
             "media_type": "application/pdf", "data": pdf_b64}},
            {"type": "text", "text": "Extrais les lignes de facture en JSON {numero, date, ht, tva, ttc}."},
        ],
    }],
)

Cas pratique : extraction structurée (factures, contrats) avec validation par JSON Schema. Approfondissement dans M12 (multimodal avancé).

Atelier (150 min, 2 temps) : skill + extraction

Atelier 3a (90 min) — concevoir et coder /audit-prompts : une skill qui lit un prompt source, analyse sa structure (XML, few-shot, CoT), et propose un refactor.

• SKILL.md avec frontmatter (name, description).
• Découpage multi-fichiers si besoin (STAGES / RULES).
• Tester l'invocation directe et automatique.

Atelier 3b (60 min) — script SDK ou skill qui extrait des données d'une image / d'un PDF : appel vision + sortie JSON validée + gestion d'erreurs/retry.

Livrable : une skill custom fonctionnelle + un script d'extraction vision testé.

Pour aller plus loin

• 📖 Claude Code — Skills
• 📖 Agent SDK — Overview
• 🔗 agentskills.io — standard ouvert Agent Skills
• 📖 Vision (API Anthropic)
• 🎯 Tronc commun : J2 (hooks/CI) ← → J4 (MCP, sub-agents) · approfondissement : M12 (multimodal)