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

## Veille

Blog post from **Anthropic / claude.com** by **Thariq Shihipar** (Member of Technical Staff, Claude Code team), published on **June 3, 2026**, which distills Anthropic's **internal experience** on designing and using **Skills**. **Framing thesis**: a Skill is not a simple markdown file but a **folder** (instructions + scripts + resources + config + hooks) that the agent **discovers and manipulates**; *« You should think of the entire file system as a form of context engineering and progressive disclosure. »* The article makes two structuring contributions. **(A) A taxonomy of 9 skill categories** observed at Anthropic: (1) **Library/API Reference** (docs for internal libs/CLIs with *gotchas* — e.g. `billing-lib`, `internal-platform-cli`, `sandbox-proxy`); (2) **Product Verification** (testing/verification via Playwright or tmux — `signup-flow-driver`, `checkout-verifier`, `tmux-cli-driver`); (3) **Data Fetching & Analysis** (access to data/monitoring stacks — `funnel-query`, `cohort-compare`, `grafana`, `datadog`); (4) **Business Process Automation** (repetitive workflows — `standup-post`, `weekly-recap`, `create-<ticket>-ticket`); (5) **Code Scaffolding** (framework boilerplate — `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** (multi-tool diagnostics — `<service>-debugging`, `oncall-runner`, `log-correlator`); (9) **Infrastructure Operations** (maintenance with guardrails — `<resource>-orphans`, `cost-investigation`). **(B) A set of best practices**: don't restate the obvious (*« Claude already knows how to code and can read your codebase »* → target what **contradicts default behavior**); polish the **Gotchas section** (*« the highest-signal content in any skill »*); **progressive disclosure** via the file tree (point to reference files depending on the situation rather than loading everything upfront); **descriptions written for the model** (*« the description field is not a summary, it's a description of when to trigger this skill »*); **setup flows** (config in `config.json`, otherwise prompt via `AskUserQuestion`); **persistent memory** (append-only logs / JSON via the `${CLAUDE_PLUGIN_DATA}` variable); **helper scripts** (*« lets Claude spend its turns on composition… rather than reconstructing boilerplate »*); **hooks conditionnels** (enabled only for the duration of the skill — e.g. a security hook blocking destructive commands). **Distribution at Anthropic**: skills are stored in `./.claude/skills`, informally shared via Slack in a sandbox folder, then promoted via **PR** to the internal **marketplace** once they gain traction; **usage measurement** via a **hook PreToolUse** that logs invocations (revealing popular skills versus underused ones). Direct follow-up to the fiche [[shihipar-claude-code-html-unreasonable-effectiveness-markdown-2026-05-10]] (same author) and a concrete complement to the Skills fiches by Anthropic/Willison/Vincent and to *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, internal experience report, skill folder, context engineering, progressive disclosure, nine skill categories, library API reference, product verification, data fetching analysis, business process automation, code scaffolding, code quality review, CI/CD deployment, runbooks, infrastructure operations, gotchas, gotchas section, Claude already knows how to code, description as trigger, description field is not a summary, setup flow, config.json, AskUserQuestion, persistent memory, append-only logs, CLAUDE_PLUGIN_DATA, helper scripts, composition vs boilerplate, hooks conditionnels, security hook, PreToolUse hook, skills usage measurement, internal marketplace, .claude/skills, PR-based distribution, 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

**Profile**: Practitioner-engineer feedback (*builder-to-builder*), first-person plural (*« how we use skills »*, *« we use a PreToolUse hook »*), aimed at a knowledgeable technical audience — engineers and power users building their own skills. **Didactic-prescriptive, dense, and operational** register, **high** technical level (environment variables, hooks, file trees, naming conventions).

**Style**: Engineering prose structured in two blocks — a **taxonomy** (9 categories with real Anthropic skill names as examples) followed by an actionable **list of best practices**. Authority stems from an **insider** position: what the team that built Claude Code observes *from the inside*. Each piece of advice is anchored in a concrete finding (*« common failure points that Claude runs into »*) rather than a generality. Honesty about the real purpose of the objects (the `description` serves model routing, not the human).

**Key aphorisms**:
- ***« Claude already knows how to code and can read your codebase. »*** (anti-redundancy: only document what contradicts the default).
- ***« 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. »***

**Metaphors / frameworks at work**:
- ***The file system as context engineering*** — a skill's file tree = a progressive-disclosure mechanism, not a mere bag of instructions.
- ***The description as a trigger, not a summary*** — reorients writing toward model routing.
- ***The model's turns as a scarce resource*** — helper scripts save reasoning for high-level composition.
- ***The organic lifecycle of skills*** — from a sandbox folder shared on Slack to promotion via PR to the marketplace, measured by usage hooks.

**Epistemic position**: internal-authority testimony (Anthropic / Claude Code team), rich in named examples; prescriptive but grounded in empirical observation of usage at company scale. To be weighed as a vendor's own experience report (not an independent study), but with strong credibility on the operational "how."

**Authority**: (a) **Anthropic insider** on the reference tool; (b) **immediately reusable taxonomy** (9 categories covering the entire SDLC + ops); (c) **concrete examples** of real skill names; (d) advice **tested at scale** (marketplace + internal usage measurement).

## Pense-betes

- **Date / source**: **June 3, 2026**, **claude.com** blog (Anthropic). Author: **Thariq Shihipar** (Claude Code team, @trq212). Direct follow-up to his fiche [[shihipar-claude-code-html-unreasonable-effectiveness-markdown-2026-05-10]].
- **Key framing**: a Skill = **a folder** (instructions + scripts + resources + config + hooks), not a single .md file. *« The entire file system as a form of context engineering and progressive disclosure. »* ### The 9 skill categories (Anthropic taxonomy) | # | Category | Purpose | Cited examples | |---|-----------|----------|----------------| | 1 | **Library/API Reference** | Docs for internal libs/CLIs + gotchas | `billing-lib`, `internal-platform-cli`, `sandbox-proxy` | | 2 | **Product Verification** | Testing/verification (Playwright, tmux) | `signup-flow-driver`, `checkout-verifier`, `tmux-cli-driver` | | 3 | **Data Fetching & Analysis** | Access to data/monitoring + query patterns | `funnel-query`, `cohort-compare`, `grafana`, `datadog` | | 4 | **Business Process Automation** | Repetitive workflows | `standup-post`, `weekly-recap`, `create-<ticket>-ticket` | | 5 | **Code Scaffolding** | Framework boilerplate | `new-migration`, `create-app`, `new-<framework>-workflow` | | 6 | **Code Quality & Review** | Style + review | `adversarial-review`, `code-style`, `testing-practices` | | 7 | **CI/CD & Deployment** | Build / push / deploy | `babysit-pr`, `deploy-<service>`, `cherry-pick-prod` | | 8 | **Runbooks** | Multi-tool diagnostics by symptom | `<service>-debugging`, `oncall-runner`, `log-correlator` | | 9 | **Infrastructure Operations** | Maintenance + guardrails | `<resource>-orphans`, `dependency-management`, `cost-investigation` | ### Best practices (checklist)
- **Anti-redundancy**: *« Claude already knows how to code »* → only document what **contradicts the model's default approach**.
- **Gotchas section** = **highest-signal** content; build it from real failure points (e.g. field-naming inconsistencies, append-only tables).
- **Progressive disclosure**: point Claude to reference files depending on the situation, rather than loading everything upfront.
- **Flexibility**: give the necessary information without over-constraining — let the agent adapt.
- **Setup flow**: store the config (`config.json`); if missing, ask the user via **`AskUserQuestion`**.
- **Description = trigger**: write for **model routing**, with activation phrases — *« not a summary, it's a description of when to trigger this skill »*.
- **Memory**: append-only / JSON logs, stable directory via **`${CLAUDE_PLUGIN_DATA}`** → the agent remembers past runs.
- **Helper scripts**: provide libs/functions → the agent spends its *turns* on **composition**, not on rebuilding boilerplate.
- **Hooks conditionnels**: enabled **only** during the skill's invocation and for the duration of the session (e.g. a hook blocking destructive commands) — useful in context, undesirable *always-on*. ### Distribution & measurement (at Anthropic)
- Skills stored in **`./.claude/skills`** (repo) or via an internal plugin **marketplace**.
- **Organic cycle**: sandbox folder → informal Slack sharing → traction → **PR** to the marketplace.
- **Usage measurement**: **hook PreToolUse** that logs invocations → identifies popular skills vs. underused ones. ### To leverage in engagements / presentations
- **Ready-to-use mapping grid**: audit a team's skills against the **9 categories** (covers dev + data + ops + process), spot the gaps.
- The **Gotchas / progressive disclosure / description-as-trigger** triptych = golden rules for writing skills, worth integrating into a firm *skill-writing guideline*.
- Converges with *harness engineering* (Böckeler, level 5 of the Every scale [[taylor-entis-every-eight-levels-ai-adoption-2026-06-02]]) and with the Skills fiches (Anthropic *Agent Skills*, Willison, Vincent *Superpowers*, Lattice). Specific contribution: **enterprise-scale usage feedback** + the **distribution/measurement mechanics**.

## RésuméDe400mots

Published on **June 3, 2026** on Anthropic's blog by **Thariq Shihipar** (Claude Code team), this article distills the company's internal experience on using **Skills**. The initial framing corrects a reductive view: a Skill is not an isolated markdown file but a **folder** bringing together instructions, scripts, resources, configuration, and hooks, that the agent **explores and manipulates**. The structuring maxim: *« You should think of the entire file system as a form of context engineering and progressive disclosure. »*

The article first offers a **taxonomy of nine categories** of skills observed at Anthropic, illustrated with real names: **(1) Library/API Reference** (docs for internal libs/CLIs with gotchas); **(2) Product Verification** (testing via Playwright/tmux); **(3) Data Fetching & Analysis** (grafana, datadog, standard queries); **(4) Business Process Automation** (standups, recaps, tickets); **(5) Code Scaffolding** (boilerplate, migrations); **(6) Code Quality & Review** (`adversarial-review`, code-style); **(7) CI/CD & Deployment** (`babysit-pr`, deploy); **(8) Runbooks** (multi-tool diagnostics by symptom); **(9) Infrastructure Operations** (maintenance with guardrails).

Next comes a body of **best practices**. The first is **anti-redundancy**: *« Claude already knows how to code and can read your codebase »* — one must document what **contradicts default behavior**, not the obvious. The most valuable content is the **Gotchas section** (*« the highest-signal content in any skill »*), fed by actually encountered failure points. **Progressive disclosure** operates via the file tree: Claude is pointed to the right reference file depending on the situation. **Descriptions** must be written for the **model**, not the human: *« the description field is not a summary, it's a description of when to trigger this skill. »* For configuration, a **setup flow** stores parameters (`config.json`) or prompts the user via `AskUserQuestion`. **Persistent memory** goes through append-only/JSON logs in the stable `${CLAUDE_PLUGIN_DATA}` directory. **Helper scripts** free up the model's reasoning: *« lets Claude spend its turns on composition… rather than reconstructing boilerplate. »* Finally, **hooks conditionnels** (e.g. blocking destructive commands) are only enabled for the duration of the skill.

On the **distribution** side, Anthropic stores its skills in `./.claude/skills`; they emerge in a sandbox folder shared via Slack, gain traction, and are then promoted via **PR** to an internal marketplace. **Usage is measured** by a hook PreToolUse that logs invocations, revealing popular skills and those needing rework. An operational guide directly reusable for writing, distributing, and measuring skills at organizational scale.

## 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/en/fiches/shihipar-claude-code-lessons-building-skills-2026-06-03/