Lessons from building Claude Code: How we use skills
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*.
**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**.