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).
By **Thariq Shihipar**// Source claude.com ↗/Reading 2 min/.md// Auto-verified translation
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).
You should think of the entire file system as a form of context engineering and progressive disclosure.
— **Thariq Shihipar** , claude.com
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.
Key takeaways
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.
Attributed claims
the Gotchas section is the highest-signal content of a skill
— Thariq Shihipar
The knowledge graph extracted from this fiche — 12 entities, 15 relations.
In this graph :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