# shihipar-claude-code-lessons-building-skills-2026-06-03

## Veille

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). Seguito diretto della fiche [[shihipar-claude-code-html-unreasonable-effectiveness-markdown-2026-05-10]] (stesso autore) e complemento concreto alle fiche sulle Skills di Anthropic/Willison/Vincent e all'*harness engineering*.

## Titre Article

Lessons from building Claude Code: How we use skills

## Date

2026-06-03

## URL

https://claude.com/blog/lessons-from-building-claude-code-how-we-use-skills

## Keywords

skills, Claude Code, Anthropic, resoconto di esperienza interna, cartella skill, context engineering, progressive disclosure, nove categorie di skill, library API reference, product verification, data fetching analysis, business process automation, code scaffolding, code quality review, CI/CD deployment, runbooks, infrastructure operations, gotchas, sezione gotchas, Claude already knows how to code, description as trigger, description field is not a summary, flusso di setup, config.json, AskUserQuestion, memoria persistente, log append-only, CLAUDE_PLUGIN_DATA, script helper, composizione vs boilerplate, hooks conditionnels, security hook, PreToolUse hook, misurazione utilizzo skill, marketplace interno, .claude/skills, distribuzione basata su PR, Slack sandbox, Playwright, tmux, grafana, datadog, adversarial-review, babysit-pr, oncall-runner, Thariq Shihipar, trq212

## Authors

**Thariq Shihipar** (Member of Technical Staff chez Anthropic, équipe **Claude Code** ; @trq212 / @trq sur X, thariqs.github.io), pour le blog **claude.com**. Même auteur que la fiche *Using Claude Code: The Unreasonable Effectiveness of HTML* (2026-05-10). Publié le **3 juin 2026**.

## Ton

**Profilo**: Testimonianza di un praticante-ingegnere (*builder-to-builder*), prima persona plurale (*« how we use skills »*, *« we use a PreToolUse hook »*), rivolta a un pubblico tecnico esperto — ingegneri e power user che costruiscono le proprie skill. Registro **didattico-prescrittivo, denso e operativo**, livello tecnico **elevato** (variabili d'ambiente, hook, alberi di file, convenzioni di denominazione).

**Stile**: Prosa ingegneristica strutturata in due blocchi — una **tassonomia** (9 categorie con nomi reali di skill Anthropic come esempi) seguita da un elenco pratico di **best practice**. L'autorevolezza deriva da una posizione di **insider**: ciò che il team che ha costruito Claude Code osserva *dall'interno*. Ogni consiglio è ancorato a un riscontro concreto (*« common failure points that Claude runs into »*) piuttosto che a una generalità. Onestà sullo scopo reale degli oggetti (il campo `description` serve al routing del modello, non all'umano).

**Aforismi chiave**:
- ***« Claude already knows how to code and can read your codebase. »*** (anti-ridondanza: documentare solo ciò che contraddice il comportamento predefinito).
- ***« The highest-signal content in any skill is the Gotchas section. »***
- ***« You should think of the entire file system as a form of context engineering and progressive disclosure. »***
- ***« The description field is not a summary, it's a description of when to trigger this skill. »***
- ***« Giving Claude scripts and libraries lets Claude spend its turns on composition, deciding what to do next rather than reconstructing boilerplate. »***

**Metafore / framework all'opera**:
- ***Il file system come context engineering*** — l'albero dei file di una skill = meccanismo di progressive disclosure, non un semplice contenitore di istruzioni.
- ***La descrizione come trigger, non come riassunto*** — riorienta la scrittura verso il routing del modello.
- ***I turni del modello come risorsa scarsa*** — gli script helper risparmiano ragionamento per la composizione di alto livello.
- ***Il ciclo di vita organico delle skill*** — da una cartella sandbox condivisa su Slack alla promozione tramite PR nel marketplace, misurato da hook di utilizzo.

**Posizione epistemica**: testimonianza di autorità interna (Anthropic / team Claude Code), ricca di esempi nominati; prescrittiva ma fondata sull'osservazione empirica dell'uso su scala aziendale. Da soppesare come resoconto di esperienza di un fornitore (non uno studio indipendente), ma con forte credibilità sul "come" operativo.

**Autorevolezza**: (a) **insider Anthropic** sullo strumento di riferimento; (b) **tassonomia immediatamente riutilizzabile** (9 categorie che coprono l'intero SDLC + ops); (c) **esempi concreti** di nomi reali di skill; (d) consigli **testati su scala** (marketplace + misurazione interna dell'utilizzo).

## Pense-betes

- **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**.

## RésuméDe400mots

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).

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.

## GrapheDeConnaissance

- Thariq Shihipar —publie→ Lessons from building Claude Code: How we use skills (DOCUMENT, 0.97)
- Anthropic —publie→ Lessons from building Claude Code: How we use skills (DOCUMENT, 0.97)
- Thariq Shihipar —fait_partie_de→ équipe Claude Code (ORGANISATION, 0.95)
- Skill —est_instance_de→ dossier d'instructions scripts et ressources (CONCEPT, 0.95)
- Skill —est_instance_de→ progressive disclosure (METHODOLOGIE, 0.93)
- Anthropic —utilise→ taxonomie 9 catégories de skills (CONCEPT, 0.92)
- Thariq Shihipar —affirme_que→ la section Gotchas est le contenu à plus fort signal d'une skill (AFFIRMATION, 0.93)
- champ description —permet→ Skill (CONCEPT, 0.94)
- helper scripts —permet→ de consacrer les turns du modèle à la composition (CONCEPT, 0.9)
- CLAUDE_PLUGIN_DATA —permet→ un répertoire stable de mémoire persistante (CONCEPT, 0.9)
- hooks conditionnels —s_applique_à→ Skill (CONCEPT, 0.9)
- Anthropic —utilise→ un marketplace interne par PR pour distribuer les skills (METHODOLOGIE, 0.88)
- hook PreToolUse —mesure→ l'usage des skills (CONCEPT, 0.9)
- Thariq Shihipar —recommande→ ne pas documenter ce que Claude sait déjà (AFFIRMATION, 0.92)
- AskUserQuestion —permet→ Skill (CONCEPT, 0.85)

---
Canonical: https://www.thekb.eu/it/fiches/shihipar-claude-code-lessons-building-skills-2026-06-03/