Lessons from building Claude Code: How we use skills
Article de blog Anthropic / claude.com signé Thariq Shihipar (Member of Technical Staff, équipe Claude Code), publié le 3 juin 2026, qui capitalise le retour d'expérience interne d'Anthropic sur la conception et l'usage des Skills. Thèse de cadrage : une Skill n'est pas un simple fichier markdown mais un dossier (instructions + scripts + ressources + config + hooks) que l'agent découvre et manipule ; « You should think of the entire file system as a form of context engineering and progressive disclosure. » L'article propose deux apports structurants. (A) Une taxonomie de 9 catégories de skills observées chez Anthropic : (1) Library/API Reference (doc de libs/CLI internes avec gotchas — ex. billing-lib, internal-platform-cli, sandbox-proxy) ; (2) Product Verification (test/vérif via Playwright ou tmux — signup-flow-driver, checkout-verifier, tmux-cli-driver) ; (3) Data Fetching & Analysis (accès stacks data/monitoring — funnel-query, cohort-compare, grafana, datadog) ; (4) Business Process Automation (workflows répétitifs — standup-post, weekly-recap, create-<ticket>-ticket) ; (5) Code Scaffolding (boilerplate framework — new-migration, create-app) ; (6) Code Quality & Review (adversarial-review, code-style, testing-practices) ; (7) CI/CD & Deployment (babysit-pr, deploy-<service>, cherry-pick-prod) ; (8) Runbooks (diagnostic multi-outils — <service>-debugging, oncall-runner, log-correlator) ; (9) Infrastructure Operations (maintenance avec garde-fous — <resource>-orphans, cost-investigation). (B) Un jeu de bonnes pratiques : ne pas redire l'évident (« Claude already knows how to code and can read your codebase » → cibler ce qui contredit le comportement par défaut) ; soigner la section Gotchas (« the highest-signal content in any skill ») ; progressive disclosure via l'arborescence (pointer vers des fichiers de référence selon la situation plutôt que tout charger d'emblée) ; descriptions pensées pour le modèle (« the description field is not a summary, it's a description of when to trigger this skill ») ; setup flows (config dans config.json, sinon demander via AskUserQuestion) ; mémoire persistante (logs append-only / JSON via la variable ${CLAUDE_PLUGIN_DATA}) ; helper scripts (« lets Claude spend its turns on composition… rather than reconstructing boilerplate ») ; hooks conditionnels (activés seulement le temps de la skill — ex. hook de sécurité bloquant les commandes destructrices). Distribution chez Anthropic : skills rangées dans ./.claude/skills, partage informel via Slack dans un dossier sandbox, puis promotion par PR vers le marketplace interne quand elles gagnent en traction ; mesure d'usage via un hook PreToolUse qui logue les invocations (révèle les skills populaires et celles sous-utilisées).
Par **Thariq Shihipar**// Source claude.com ↗/Lecture 2 min/.md/
Publié le 3 juin 2026 sur le blog d'Anthropic par Thariq Shihipar (équipe Claude Code), cet article distille le retour d'expérience interne de l'entreprise sur l'usage des Skills. Le cadrage initial corrige une vision réductrice : une Skill n'est pas un fichier markdown isolé mais un dossier réunissant instructions, scripts, ressources, configuration et hooks, que l'agent explore et manipule. La maxime structurante : « You should think of the entire file system as a form of context engineering and progressive disclosure. »
L'article apporte d'abord une taxonomie de neuf catégories de skills observées chez Anthropic, illustrées par des noms réels : (1) Library/API Reference (doc de libs/CLI internes avec gotchas) ; (2) Product Verification (test via Playwright/tmux) ; (3) Data Fetching & Analysis (grafana, datadog, requêtes type) ; (4) Business Process Automation (standup, recaps, tickets) ; (5) Code Scaffolding (boilerplate, migrations) ; (6) Code Quality & Review (adversarial-review, code-style) ; (7) CI/CD & Deployment (babysit-pr, deploy) ; (8) Runbooks (diagnostic multi-outils par symptôme) ; (9) Infrastructure Operations (maintenance avec garde-fous).
You should think of the entire file system as a form of context engineering and progressive disclosure.
— **Thariq Shihipar** , claude.com
Vient ensuite un corpus de bonnes pratiques. La première est l'anti-redondance : « Claude already knows how to code and can read your codebase » — il faut documenter ce qui contredit le comportement par défaut, pas l'évident. Le contenu le plus précieux est la section Gotchas (« the highest-signal content in any skill »), nourrie des points d'échec réellement rencontrés. La progressive disclosure s'opère via l'arborescence : on oriente Claude vers le bon fichier de référence selon la situation. Les descriptions doivent être pensées pour le modèle, pas l'humain : « the description field is not a summary, it's a description of when to trigger this skill. » Pour la configuration, un setup flow stocke les paramètres (config.json) ou interroge l'utilisateur via AskUserQuestion. La mémoire persistante passe par des logs append-only/JSON dans le répertoire stable ${CLAUDE_PLUGIN_DATA}. Les helper scripts libèrent le raisonnement du modèle : « lets Claude spend its turns on composition… rather than reconstructing boilerplate. » Enfin, des hooks conditionnels (ex. blocage de commandes destructrices) ne s'activent que le temps de la skill.
Côté distribution, Anthropic range ses skills dans ./.claude/skills ; elles émergent dans un dossier sandbox partagé via Slack, gagnent en traction, puis sont promues par PR vers un marketplace interne. L'usage est mesuré par un hook PreToolUse qui logue les invocations, révélant les skills populaires et celles à retravailler. Un guide opérationnel directement réutilisable pour rédiger, distribuer et mesurer des skills à l'échelle d'une organisation.
À retenir
Date / source.3 juin 2026, blog claude.com (Anthropic). Auteur : Thariq Shihipar (équipe Claude Code, @trq212). Suite directe de sa fiche [[shihipar-claude-code-html-unreasonable-effectiveness-markdown-2026-05-10]].
Anti-redondance.« Claude already knows how to code » → ne documenter que ce qui contredit l'approche par défaut du modèle.
Section Gotchas. = contenu le plus à fort signal ; la construire à partir des points d'échec réels (ex. incohérences de nommage de champs, tables append-only).
Progressive disclosure. pointer Claude vers des fichiers de référence selon la situation, plutôt que tout charger d'emblée.
Flexibilité. donner l'info nécessaire sans sur-contraindre — laisser l'agent s'adapter.
Setup flow. stocker la config (config.json) ; si manquante, demander à l'utilisateur via AskUserQuestion.
Description = trigger. rédiger pour le routage du modèle, avec phrases d'activation — « not a summary, it's a description of when to trigger this skill ».
Mémoire. logs append-only / JSON, répertoire stable via ${CLAUDE_PLUGIN_DATA} → l'agent se souvient des exécutions passées.
Helper scripts. fournir libs/fonctions → l'agent dépense ses turns en composition, pas en reconstruction de boilerplate.
Hooks conditionnels. activés seulement pendant l'invocation de la skill et pour la durée de la session (ex. hook bloquant les commandes destructrices) — utiles en contexte, indésirables en always-on. ### Distribution & mesure (chez Anthropic)
Skills rangées dans ./.claude/skills (repo) ou via marketplace de plugins interne.
Cycle organique. dossier sandbox → partage informel Slack → traction → PR vers le marketplace.
Mesure d'usage. hook PreToolUse qui logue les invocations → repère skills populaires vs sous-utilisées. ### À mobiliser en mission / présentation
Grille de cartographie. clé en main : auditer les skills d'une équipe par les 9 catégories (couvre dev + data + ops + process), repérer les trous.
Le triptyque Gotchas / progressive disclosure / description-as-trigger = règles d'or de rédaction de skills, à intégrer dans une skill-writing guideline cabinet.
Converge avec le harness engineering (Böckeler, niveau 5 de l'échelle Every [[taylor-entis-every-eight-levels-ai-adoption-2026-06-02]]) et avec les fiches Skills (Anthropic Agent Skills, Willison, Vincent Superpowers, Lattice). Apport spécifique : le REX d'usage à l'échelle entreprise + la mécanique de distribution/mesure.
Affirmations attribuées
la section Gotchas est le contenu à plus fort signal d'une skill
— Thariq Shihipar
Le graphe de connaissance extrait de cette fiche — 12 entités, 15 relations.
Dans ce graphe :Thariq Shihipar · Anthropic · Lessons from building Claude Code: How we use skills · Skill · taxonomie 9 catégories de skills · section Gotchas · progressive disclosure · champ description · CLAUDE_PLUGIN_DATA · hooks conditionnels · hook PreToolUse · marketplace interne Anthropic