Aller au contenu

Anthropic — Taxonomie et best practices des skills Claude Code

Resume

Article officiel Anthropic documentant les lecons apprises sur les skills Claude Code, base sur des centaines de skills en usage interne. Propose une taxonomie en 9 types (Library Reference, Product Verification, Data Fetching, Business Process, Code Scaffolding, Code Quality, CI/CD, Runbooks, Infrastructure Ops) et des best practices de creation : section Gotchas iterative, progressive disclosure via le filesystem, on-demand hooks, mesure d'usage par PreToolUse hook, description comme trigger (pas comme resume).

Analyse critique

C'est le document de reference sur les skills. Pas du marketing — des patterns concrets issus d'un usage interne massif. La taxonomie en 9 types est le premier framework formel pour organiser un catalogue de skills.

Les 9 types et leur mapping ProbatioVault :

Type Description Equivalent PV
1. Library & API Reference Gotchas, edge cases, snippets d'une lib interne .claude/rules/ (learnings, integrations)
2. Product Verification Test E2E avec Playwright, tmux, assertions programmatiques /gov-accept (step 7), /forge
3. Data Fetching & Analysis Connexion aux stacks data/monitoring, dashboards /gitlab, /jira, /morning
4. Business Process Automatisation workflows repetitifs (standup, tickets) /morning, /gov-status, /gov-lord
5. Code Scaffolding Boilerplate framework avec conventions /gov-impl templates, /gov-index
6. Code Quality & Review Review adversariale, code style, testing practices /gov-gate, /codex:review, /simplify
7. CI/CD & Deployment Babysit PR, deploy, cherry-pick /forge
8. Runbooks Symptome → investigation → rapport structure Pas d'equivalent direct
9. Infrastructure Ops Maintenance, orphans cleanup, cost investigation Pas d'equivalent direct

Best practices les plus actionnables :

  • Gotchas section = le contenu le plus utile d'un skill. Construite iterativement depuis les echecs reels. Correspond a notre pattern learnings.jsonl → injection dans les prompts.
  • Progressive disclosure : un skill est un dossier, pas un fichier. References, scripts, assets charges a la demande par Claude. On fait deja ca partiellement (/gov-gate charge templates + contracts) mais pas systematiquement.
  • "Don't State the Obvious" : se concentrer sur ce qui pousse Claude hors de sa pensee par defaut. Le skill frontend-design d'Anthropic a ete construit pour eviter les "Inter font + purple gradients" classiques.
  • "Avoid Railroading" : donner l'info, pas les etapes exactes. Laisser Claude adapter. Nos skills sont souvent tres prescriptifs (etapes numerotees) — a reconsiderer pour les skills non-critiques.
  • On-demand hooks : hooks actives seulement quand le skill est invoque. Exemples : /careful bloque rm -rf/DROP TABLE/force-push. /freeze bloque les edits hors d'un repertoire specifique. Directement applicable a nos operations prod.
  • Description = trigger : pas un resume, c'est ce que Claude scanne pour decider d'invoquer. Nos descriptions de skills sont souvent trop longues.
  • Memory via fichiers : standups.log, config.json dans ${CLAUDE_PLUGIN_DATA}. On fait deja ca avec .gov-local.json et veille-state.json.
  • Mesure d'usage : PreToolUse hook pour logger chaque invocation de skill. Permet de detecter les skills sous-utilises ou sous-triggeres. On ne fait pas ca — TODO.
  • Composabilite : referencer d'autres skills par nom, Claude les invoque si installes. Nos skills se composent deja (/gov appelle /gov-step, /gov-gate, etc.).
  • Marketplace interne : sandbox → traction → PR vers marketplace. Curation avant release. Pattern applicable si on voulait partager nos skills hors ProbatioVault.

Pertinence ProbatioVault

Impact fort. Ce framework s'applique directement a notre catalogue de ~50 skills.

Gaps identifies dans notre couverture :

Type manquant Ce qu'on pourrait faire
Runbooks (type 8) Skills de diagnostic : symptome pipeline rouge → investigation → rapport. Aujourd'hui c'est manuel.
Infrastructure Ops (type 9) Skills de maintenance : cleanup sessions orphelines, audit dependances, cost monitoring.

Ameliorations immediates :

  • Ajouter une section Gotchas a chaque skill existant, alimentee par les learnings pertinents
  • On-demand hooks : creer /careful et /freeze pour les operations sensibles (prod, infra)
  • Mesure d'usage : implementer un PreToolUse hook qui logge les invocations de skills dans un JSONL. Permettrait de savoir quels skills sont reellement utilises vs installes mais ignores
  • Auditer les descriptions : verifier que chaque description est un trigger, pas un resume
  • disable-model-invocation (via @thismacapital) : flag frontmatter qui empeche Claude de charger le skill automatiquement en contexte. Si true, le skill n'est invocable que manuellement (/mon-skill). Avec ~50 skills, le YAML de chaque skill est charge en contexte au demarrage — ca peut representer des milliers de tokens inutiles. Identifier les skills rarement auto-invoques et les passer en disable-model-invocation: true.
  • Progressive disclosure : migrer les skills les plus lourds (ex: /gov-gate, /gov-impl) vers une structure dossier avec references chargees a la demande