Lessons from building Claude Code: How we use skills
Post del blog di Anthropic / claude.com di Thariq Shihipar (Member of Technical Staff, team Claude Code), pubblicato il 3 giugno 2026, che sintetizza l'esperienza interna di Anthropic nella progettazione e nell'uso delle Skills. Tesi di inquadramento: una Skill non è un semplice file markdown ma una cartella (istruzioni + script + risorse + configurazione + hook) che l'agente esplora e manipola; « You should think of the entire file system as a form of context engineering and progressive disclosure. » L'articolo apporta due contributi strutturanti. (A) Una tassonomia di 9 categorie di skill osservate in Anthropic: (1) Library/API Reference (documentazione per librerie/CLI interne con gotchas — es. billing-lib, internal-platform-cli, sandbox-proxy); (2) Product Verification (test/verifica tramite Playwright o tmux — signup-flow-driver, checkout-verifier, tmux-cli-driver); (3) Data Fetching & Analysis (accesso a stack di dati/monitoraggio — funnel-query, cohort-compare, grafana, datadog); (4) Business Process Automation (workflow ripetitivi — standup-post, weekly-recap, create-<ticket>-ticket); (5) Code Scaffolding (boilerplate di 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 (diagnostica multi-tool — <service>-debugging, oncall-runner, log-correlator); (9) Infrastructure Operations (manutenzione con guardrail — <resource>-orphans, cost-investigation). (B) Un insieme di best practice: non ripetere l'ovvio (« Claude already knows how to code and can read your codebase » → puntare su ciò che contraddice il comportamento predefinito); curare la sezione Gotchas (« the highest-signal content in any skill »); progressive disclosure tramite l'albero dei file (indirizzare verso file di riferimento a seconda della situazione anziché caricare tutto in anticipo); descrizioni scritte per il modello (« the description field is not a summary, it's a description of when to trigger this skill »); flussi di setup (configurazione in config.json, altrimenti richiesta tramite AskUserQuestion); memoria persistente (log append-only / JSON tramite la variabile ${CLAUDE_PLUGIN_DATA}); script helper (« lets Claude spend its turns on composition… rather than reconstructing boilerplate »); hooks conditionnels (attivati solo per la durata della skill — es. un hook di sicurezza che blocca comandi distruttivi). Distribuzione in Anthropic: le skill sono conservate in ./.claude/skills, condivise informalmente via Slack in una cartella sandbox, poi promosse tramite PR nel marketplace interno una volta acquisita trazione; misurazione dell'utilizzo tramite un hook PreToolUse che registra le invocazioni (rivelando le skill popolari rispetto a quelle sottoutilizzate).
Pubblicato il 3 giugno 2026 sul blog di Anthropic da Thariq Shihipar (team Claude Code), questo articolo sintetizza l'esperienza interna dell'azienda sull'uso delle Skills. L'inquadramento iniziale corregge una visione riduttiva: una Skill non è un file markdown isolato ma una cartella che riunisce istruzioni, script, risorse, configurazione e hook, che l'agente esplora e manipola. La massima strutturante: « You should think of the entire file system as a form of context engineering and progressive disclosure. »
L'articolo propone anzitutto una tassonomia di nove categorie di skill osservate in Anthropic, illustrate con nomi reali: (1) Library/API Reference (documentazione per librerie/CLI interne con gotchas); (2) Product Verification (test tramite Playwright/tmux); (3) Data Fetching & Analysis (grafana, datadog, pattern di query); (4) Business Process Automation (standup, recap, ticket); (5) Code Scaffolding (boilerplate, migrazioni); (6) Code Quality & Review (adversarial-review, code-style); (7) CI/CD & Deployment (babysit-pr, deploy); (8) Runbooks (diagnostica multi-tool per sintomo); (9) Infrastructure Operations (manutenzione con guardrail).
You should think of the entire file system as a form of context engineering and progressive disclosure.
— **Thariq Shihipar** , claude.com
Segue un corpus di best practice. La prima è l'anti-ridondanza: « Claude already knows how to code and can read your codebase » — occorre documentare ciò che contraddice il comportamento predefinito, non l'ovvio. Il contenuto più prezioso è la sezione Gotchas (« the highest-signal content in any skill »), alimentata da punti di fallimento effettivamente incontrati. La progressive disclosure opera tramite l'albero dei file: Claude viene indirizzato verso il file di riferimento corretto a seconda della situazione. Le descrizioni devono essere scritte per il modello, non per l'umano: « the description field is not a summary, it's a description of when to trigger this skill. » Per la configurazione, un flusso di setup memorizza i parametri (config.json) o interroga l'utente tramite AskUserQuestion. La memoria persistente passa da log append-only/JSON nella directory stabile ${CLAUDE_PLUGIN_DATA}. Gli script helper liberano il ragionamento del modello: « lets Claude spend its turns on composition… rather than reconstructing boilerplate. » Infine, gli hooks conditionnels (es. bloccare comandi distruttivi) sono attivati solo per la durata della skill.
Sul versante della distribuzione, Anthropic conserva le proprie skill in ./.claude/skills; emergono in una cartella sandbox condivisa via Slack, acquisiscono trazione, e vengono poi promosse tramite PR in un marketplace interno. L'utilizzo viene misurato da un hook PreToolUse che registra le invocazioni, rivelando le skill popolari e quelle da rivedere. Una guida operativa direttamente riutilizzabile per scrivere, distribuire e misurare le skill su scala organizzativa.
Punti chiave
Data / fonte.3 giugno 2026, blog claude.com (Anthropic). Autore: Thariq Shihipar (team Claude Code, @trq212). Seguito diretto della sua fiche [[shihipar-claude-code-html-unreasonable-effectiveness-markdown-2026-05-10]].
Inquadramento chiave. una Skill = una cartella (istruzioni + script + risorse + configurazione + hook), non un singolo file .md. « The entire file system as a form of context engineering and progressive disclosure. » ### Le 9 categorie di skill (tassonomia Anthropic) | # | Categoria | Scopo | Esempi citati | |---|-----------|----------|----------------| | 1 | Library/API Reference | Documentazione per librerie/CLI interne + gotchas | billing-lib, internal-platform-cli, sandbox-proxy | | 2 | Product Verification | Test/verifica (Playwright, tmux) | signup-flow-driver, checkout-verifier, tmux-cli-driver | | 3 | Data Fetching & Analysis | Accesso a dati/monitoraggio + pattern di query | funnel-query, cohort-compare, grafana, datadog | | 4 | Business Process Automation | Workflow ripetitivi | standup-post, weekly-recap, create-<ticket>-ticket | | 5 | Code Scaffolding | Boilerplate di framework | new-migration, create-app, new-<framework>-workflow | | 6 | Code Quality & Review | Stile + review | adversarial-review, code-style, testing-practices | | 7 | CI/CD & Deployment | Build / push / deploy | babysit-pr, deploy-<service>, cherry-pick-prod | | 8 | Runbooks | Diagnostica multi-tool per sintomo | <service>-debugging, oncall-runner, log-correlator | | 9 | Infrastructure Operations | Manutenzione + guardrail | <resource>-orphans, dependency-management, cost-investigation | ### Best practice (checklist)
Anti-ridondanza.« Claude already knows how to code » → documentare solo ciò che contraddice l'approccio predefinito del modello.
Sezione Gotchas. = contenuto a massimo segnale; costruirla a partire da punti di fallimento reali (es. incoerenze nella denominazione dei campi, tabelle append-only).
Progressive disclosure. indirizzare Claude verso file di riferimento a seconda della situazione, anziché caricare tutto in anticipo.
Flessibilità. fornire le informazioni necessarie senza vincolare eccessivamente — lasciare che l'agente si adatti.
Flusso di setup. memorizzare la configurazione (config.json); in sua assenza, interrogare l'utente tramite AskUserQuestion.
Descrizione = trigger. scrivere per il routing del modello, con frasi di attivazione — « not a summary, it's a description of when to trigger this skill ».
Memoria. log append-only / JSON, directory stabile tramite ${CLAUDE_PLUGIN_DATA} → l'agente ricorda le esecuzioni passate.
Script helper. fornire librerie/funzioni → l'agente dedica i propri turni alla composizione, non alla ricostruzione del boilerplate.
Hooks conditionnels. attivati solo durante l'invocazione della skill e per la durata della sessione (es. un hook che blocca comandi distruttivi) — utili nel contesto, indesiderabili in modalità always-on. ### Distribuzione e misurazione (in Anthropic)
Skill conservate in ./.claude/skills (repo) o tramite un marketplace di plugin interno.
Ciclo organico. cartella sandbox → condivisione informale su Slack → trazione → PR verso il marketplace.
Misurazione dell'utilizzo.hook PreToolUse che registra le invocazioni → identifica le skill popolari rispetto a quelle sottoutilizzate. ### Da valorizzare in incarichi / presentazioni
Griglia di mappatura pronta all'uso. verificare le skill di un team rispetto alle 9 categorie (copre sviluppo + dati + ops + processi), individuare le lacune.
Il tris Gotchas / progressive disclosure / description-as-trigger = regole auree per scrivere skill, da integrare in una linea guida aziendale di skill-writing.
Converge con l'harness engineering (Böckeler, livello 5 della scala Every [[taylor-entis-every-eight-levels-ai-adoption-2026-06-02]]) e con le fiche sulle Skills (Anthropic Agent Skills, Willison, Vincent Superpowers, Lattice). Contributo specifico: feedback d'uso su scala aziendale + meccanica di distribuzione/misurazione.
Affermazioni attribuite
la sezione Gotchas è il contenuto a più alto segnale di una skill
— Thariq Shihipar
Il grafo di conoscenza estratto da questa fiche — 12 entità, 15 relazioni.
In questo grafo :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