Lessons from building Claude Code: How we use skills

Claude · article · 2026-06-03 Reader 🖥️

practical · lessons-learned engineering post / prescriptive taxonomy, written by a Claude Code team member (Thariq Shihipar) from internal usage at Anthropic (hundreds of skills in active use) — Structured as a practitioner field guide: an empirically-derived taxonomy (nine categories from cataloging Anthropic's own skills) followed by a list of discrete authoring tips, a distribution model, and a measurement mechanism. The categorization is grounded in real internal data; almost every individual tip is asserted from experience with no disclosed metric or before/after comparison.

Structure

Key terms

• skill Agent Skills
  A folder of instructions, scripts, and resources an agent can discover, explore and manipulate — explicitly not 'just markdown files.'
• Gotchas section
  A specific part of a skill built up over time from Claude's actual observed failure points ('this field is called @request_id in the gateway and trace_id in billing') — described as the highest-signal content in any skill.
• progressive disclosure Progressive Disclosure
  Treating the entire skill filesystem — not just SKILL.md — as context engineering: pointing to references/, assets/, and scripts/ that Claude reads only when needed rather than front-loading everything.
• railroading
  Writing skill instructions so specific/prescriptive that Claude loses the flexibility to adapt to the actual situation.
• description field (for the model, not for humans)
  The SKILL.md frontmatter field Claude Code scans at session start across every installed skill to decide whether a skill applies to the current request — a trigger condition, not a summary.
• on-demand hooks
  Hooks bundled inside a skill that activate only when that skill is invoked and only for the session's duration (e.g. /careful blocking rm -rf only when explicitly turned on) — as opposed to always-on hooks.
• ${CLAUDE_PLUGIN_DATA}
  An environment variable giving a stable directory a skill can use to persist data (logs, JSON, SQLite) across invocations, enabling skills to 'remember' past runs.
• plugin marketplace
  A Claude Code Plugin marketplace where skills are uploaded and users opt in to install them, contrasted with checking skills directly into a repo's ./.claude/skills.

Propositions

• explicitSkills are folders of instructions, scripts, and resources that agents discover and use, not merely markdown files — treating them as folders (with progressive disclosure across their contents) is central to what makes them effective.conf: high
• explicitAnthropic's internal skills cluster into nine categories (library/API reference, product verification, data fetching/analysis, business process automation, code scaffolding/templates, code quality/review, CI/CD and deployment, runbooks, infrastructure operations); skills that straddle several categories instead of fitting cleanly into one confuse the agent.conf: medium
• explicitVerification skills (testing/checking that code actually works) have had the most measurable impact on Claude's output quality of any skill category internally, to the point that it can be worth dedicating an engineer-week to making them excellent.conf: medium
• explicitA skill should not restate what Claude would already do by default (it already knows how to code and can read the codebase); a skill's value comes from pushing the agent out of its normal default way of thinking.conf: high
• explicitThe highest-signal content in any skill is its 'Gotchas' section, built up incrementally from Claude's actual observed failure points rather than designed upfront.conf: high
  refinesAgent Skills · p7 — Osmani's anti-rationalization tables are pre-written rebuttals to specific model rationalizations; this doc's broader 'gotchas section' generalizes the same underlying pattern (externalizing hard-won, failure-derived knowledge into the skill) beyond just rationalization-countering to any non-obvious operational fact.
• explicitThe entire skill filesystem — SKILL.md plus references/, assets/, and scripts/ — should be treated as a deliberate form of context engineering and progressive disclosure: point Claude to files, and it will read them at the appropriate time rather than needing everything loaded up front.conf: high
  extendsAgent Skills · p11 — Osmani's post asserts progressive disclosure is necessary at scale because every token degrades performance; this doc gives the concrete mechanism (treat the whole skill folder — references/, assets/, scripts/ — as context engineering, pointed to from SKILL.md and read on demand).
  supportsSoftware Teaming in the Age of AI with James Herr and Woody Zuill · p7 — Zuill/Herr independently report that moving detail out of one long instructions file into small on-demand skills files keeps context around half-full and produces more consistent output — this doc corroborates the same practice from Anthropic's internal skills-authoring experience.
• explicitSkill instructions should avoid being overly specific or prescriptive ('railroading'), because skills are reused across many situations and over-constraining Claude removes its ability to adapt to the actual case in front of it.conf: high
• explicitdevelopedA skill's frontmatter description field functions as a trigger condition scanned across every installed skill at session start to decide whether a request should invoke it — it is not a human-facing summary, and should be written accordingly (including explicit trigger words).conf: high
  extends ←Kafka App? There's a Skill for That · p7 — Real-world evidence that description-based trigger matching (p8's mechanism) under-covers actual request phrasing; Etsy extends it with enumerated multi-vocabulary entry points and repository-level file-touch routing as an additional trigger layer.
• explicitSkills can carry persistent memory (append-only logs, JSON, or SQLite) stored via a stable directory (${CLAUDE_PLUGIN_DATA}), letting Claude read its own history from past invocations of the same skill and detect what changed since last time.conf: high
• explicitGiving Claude pre-written scripts and helper functions inside a skill lets it spend its reasoning turns on composing and deciding what to do next, rather than reconstructing boilerplate code from scratch each time.conf: high
• explicitHooks scoped to activate only while a specific skill is invoked ('on-demand hooks') let a team apply strict, opinionated guardrails (blocking rm -rf, force-push, DROP TABLE) only in the contexts where they're actually needed, since having such constraints always-on would be too restrictive for general use.conf: high
• explicitFor small teams working across few repos, checking skills into the repo (./.claude/skills) is sufficient; but every checked-in skill adds a small, permanent tax to the model's context, so at scale an internal plugin marketplace with opt-in installation becomes the better distribution model.conf: high
• explicitcontestedAnthropic curates its internal skills marketplace organically and bottom-up rather than through a centralized gatekeeping team: a skill starts in a sandbox folder, gains traction by word of mouth, and only then gets promoted into the marketplace via a PR from the skill's own owner.conf: high
  contradicts ←Zero to Agent in 30 Minutes: Build a Supply Chain for Agent Context with Maxim Salnikov · p8 — Recommends the opposite governance model from Anthropic's own internal practice: a private registry gated by enforced approval policies, versus Anthropic's organic, bottom-up curation with no centralized gatekeeping team. A real tension in the corpus between two vendors' prescriptions for the same problem.
• explicitSkill-to-skill dependency and composition currently works only informally — by referencing another skill by name in an instruction and relying on the model to invoke it if that skill happens to be installed — because no formal dependency-management mechanism is built into skills or marketplaces yet.conf: high
  extendsNew Skills! v1.1 brings /wayfinder, /research, /implement, /to-spec, /to-tickets · p11 — Wayfinder's proposition frames codified, versioned skills as a better distribution unit for engineering practice than ad-hoc prompting; this doc adds an important caveat that same optimistic framing omits — skill-to-skill composition and dependency management is still informal and unmanaged, a real limitation on 'skills as a distribution unit.'
• explicitdevelopedSkill usage across a company can be measured with a PreToolUse hook that logs invocations, giving visibility into which skills are popular versus under-triggering relative to expectations.conf: high
  extends ←Kafka App? There's a Skill for That · p8 — Both use a hook that fires on skill invocation to measure usage; Etsy's version adds a second signal (whether invocation reached a completed PR) and routes it through an existing company-wide event pipeline (Kafka + BigQuery) rather than a bespoke log.
• implicitcontestedSkill quality is driven more by iterative refinement from real failures encountered over time than by upfront design — most of Anthropic's best skills 'began as a few lines and a single gotcha' and improved as people kept adding to them.conf: medium
  contradicts ←agent-skills/docs/comparison.md at main · addyosmani/agent-skills · GitHub · p11 — This comparison's breadth-favoring recommendation logic (more phases/mechanisms = the stronger 'reach for X' case) is in tension with Anthropic's internal finding that skill quality comes from iterative, failure-driven refinement of a few lines rather than broader upfront lifecycle design.

Arguments

Narratives

• The frontend-design skill was built by an Anthropic engineer iterating directly with customers on improving Claude's design taste, explicitly steering it away from classic AI-generated design tells like the Inter font and purple gradients.
  → Illustrates 'don't state the obvious' — a good skill pushes Claude out of its default behavior rather than restating what it already knows.
• A standup-post skill keeps a standups.log with every post it has written, so the next run Claude reads its own history and can report only what changed since yesterday.
  → Illustrates the memory pattern for skills.
• A data-science skill provides a library of functions to fetch data from an event source; Claude composes these on the fly to answer ad hoc questions like 'What happened on Tuesday?'
  → Illustrates 'store scripts and generate code' — giving Claude composable primitives instead of asking it to reconstruct boilerplate.
• /careful blocks rm -rf, DROP TABLE, force-push and kubectl delete via a PreToolUse hook on Bash, but only when explicitly invoked — because having it always on 'would drive you insane'; /freeze blocks any Edit/Write outside a specific directory to stop Claude from 'fixing' unrelated code while debugging.
  → Illustrates on-demand, session-scoped hooks as opinionated but situational guardrails.
• Concrete gotcha examples quoted verbatim: the subscriptions table is append-only so the correct row is the highest version not the most recent created_at; a field is @request_id in the API gateway but trace_id in the billing service though they're the same value; staging returns HTTP 200 even when a Stripe webhook didn't actually process, so payment_events must be checked for the real state.
  → Grounds the abstract 'gotchas section' advice in real, specific, non-obvious failure knowledge — the kind of tacit knowledge a skill is meant to externalize.

Questions addressed

• ✅ What type of skills are worth making?
  The nine-category taxonomy derived from cataloging internal skills, used as a framework for identifying gaps in one's own skills library.
• ✅ How do you structure a skill?
  A cluster of concrete tips: don't restate the obvious, build a gotchas section, use the filesystem for progressive disclosure, avoid railroading, think through setup/config, write model-facing descriptions, add memory, store scripts, use on-demand hooks.
• ✅ When do you share skills with others?
  Check into the repo for small teams across few repos; move to an internal plugin marketplace as you scale, since every checked-in skill adds to model context.
• ⭕ How do you know whether a skill is actually working (i.e. improving output, not just firing)?
  Only usage-frequency (PreToolUse invocation logging) is described; whether a triggered skill actually improved output quality, defect rate, or rework is never addressed.
• ⭕ How do skills compose or depend on each other reliably?
  The post explicitly states this is 'not natively built into marketplaces or skills yet' — composition works only by informal by-name reference.
• ⭕ Does the same skill behave identically across different agent harnesses (Claude Code vs. other coding agents)?
  Never addressed — the entire post is scoped to Claude Code's own configuration options (frontmatter, hooks, ${CLAUDE_PLUGIN_DATA}) with no discussion of portability.

Gaps

• incompleteNo quantitative evidence is given anywhere in the piece. 'Measurable impact,' 'one of the most used extension points,' 'hundreds of them in active use,' and the nine-category catalog are all asserted without a single number, methodology note, or before/after comparison. A reader cannot tell whether 'measurable' means a rigorous eval or just an internal impression.
  Read next: Compare against extract-agent-skills-osmani#g1, which flags the identical evidentiary gap (26K GitHub stars as social proof, no defect-rate data) in a different skills-authoring post — this looks like a structural pattern across the whole skills-advocacy genre, not a one-off omission.
• incompleteThe nine-category taxonomy is offered as a tool for 'identifying gaps in your own skills library,' but gives no guidance for the case it explicitly flags as a failure mode: a skill that legitimately needs to touch two categories (e.g. a CI/CD skill that also needs data-fetching context to decide on a rollout). The advice is only 'the best skills fit cleanly into one' — with no procedure for splitting or resolving a straddling skill.
  Read next: Would benefit from the kind of decision-procedure critique already applied to extract-20-loop-design-patterns#g1 (a pattern catalog without selection criteria) — the same 'taxonomy without a decision procedure' gap recurs here.
• uninformedEvery practice described (organic bottom-up marketplace curation with no centralized gatekeeping team, checking skills into repos vs. a plugin marketplace, hundreds of skills in active use) is drawn from a single organization — Anthropic — with mature internal platform tooling, a large engineering org, and presumably existing CI/CD and review discipline. The post never acknowledges that this governance model may only work because of scale and maturity most readers' orgs (or a solo practitioner) don't have.
  Read next: Parallels the Google-centrism gap already flagged in extract-agent-skills-google-backed-ai-coding#g3 — worth reading both together as instances of a recurring 'FAANG-scale practice presented as universal' gap in the skills-advocacy corpus.
• incompleteThe 'measuring skills' section describes only a PreToolUse usage-count hook — how often a skill fires — never whether the skill's output was actually good (defect rate, rework caused, correctness). Under-triggering is named as a problem to detect, but over-triggering / false-positive triggering (a skill's description matches too broadly and injects irrelevant context) is not discussed at all, despite the article's own earlier warning that every checked-in skill 'adds a little bit to the context of the model.'
  Read next: Cross-reference extract-agent-skills-osmani#g4 (cost of false enforcement / overhead-accuracy tradeoff) — a directly analogous gap about the cost side of skill triggering that this post also leaves open.
  closed byKafka App? There's a Skill for That — That gap complains the 'measuring skills' pattern (a PreToolUse usage-count hook) tracks only how often a skill fires, never whether its output was good. Etsy's telemetry pairs the invocation hook with a second, outcome-oriented signal — whether the invocation actually reached a completed pull request — moving one concrete step beyond raw usage-count toward outcome measurement, though it still stops short of defect-rate or rework tracking.
• illogicalThe piece simultaneously warns against writing skill instructions that are 'too specific' ('avoid railroading Claude') and recommends filling the gotchas section with declarative always-do-X rules ('the subscriptions table is append-only, use the highest version'). Both railroading and a gotcha are stylistically the same speech act — a specific, prescriptive instruction — but the post treats one as a failure mode and the other as the highest-signal content, without ever explaining the line an author should use to tell them apart.
  Read next: No corpus doc yet addresses this tension directly; worth testing against the anti-rationalization-table pattern in extract-agent-skills-osmani#p7, which is closer to a principled distinction (a gotcha rebuts a specific rationalization the model has been observed to make, vs. a railroading instruction pre-empts a choice the model hasn't yet needed to make).
• uninformedSkill-to-skill composition is acknowledged as working only informally today (reference another skill by name; 'the model will invoke them if they are installed'), but the post never discusses the failure modes this implies: what happens if the referenced skill isn't installed, or if two composed skills' instructions conflict. This leaves the same kind of router/dependency-reliability question open that extract-agent-skills-osmani#g2 raises about a different (custom, third-party) meta-skill router — except here there isn't even an explicit router to critique, just implicit trust that the model will sort it out.
  Read next: Read alongside extract-agent-skills-osmani#g2 and extract-skills-v1-1-wayfinder-flow-skills#p11 — the 'skills as a distribution unit for engineering practice' thesis these two other docs advance depends on composition actually being reliable, which this post concedes it isn't yet.

Related documents

• Software Teaming in the Age of AI with James Herr and Woody Zuill
• Alex Wang's Post
  Agent Skills Claude Code Hooks
• Audit your Agent files
  Agent Skills Hooks Progressive Disclosure
• Why AI agents need a Context Lake
  Agent Tool Management Context Engineering Platform Engineering
• Stop Using /init for AGENTS.md
  Agent Skills Context Engineering Progressive Disclosure
• Portal by Spotify cut my Claude Code token usage by 90%
  Claude Code Context Engineering Hooks
• Agent Skills: Google-Backed AI Coding Agent Workflow
  Agent Skills Context Engineering
• Agent Skills
  Agent Skills Progressive Disclosure
• AI Is Changing Software Engineering. The Fundamentals Still Matter.
  Context Engineering Platform Engineering
• The Anatomy of an Agent Harness
  Agent Tool Management Context Engineering