Quartz 5

Lessons from Building Claude Code: How Anthropic Uses Skills

Properties1
tagsclaude-code, llm, agentic-workflow

3 min read

Summary

An internal lessons-learned post from Anthropic on how they use Claude Code skills across hundreds of active internal skills. Skills are not just markdown files — they’re folders containing scripts, assets, data, and configuration that agents can explore and manipulate. The post catalogs 9 skill categories (Library/API Reference, Product Verification, Data Fetching, Business Process Automation, Code Scaffolding, Code Quality, CI/CD, Runbooks, Infrastructure Operations) and offers detailed guidance on writing effective skills: gotchas sections, progressive disclosure via file system, avoiding railroading, on-demand hooks.

Anthropic 關於 Claude Code Skills 內部使用心得的分享，涵蓋數百個活躍技能。Skills 不只是 Markdown 檔案，而是含有腳本、資產、資料的資料夾。文章整理了 9 個技能分類與撰寫最佳實踐，包括 Gotchas 區塊、漸進式揭露、避免過度約束代理人、按需掛鉤等。

Key Points

  • Skills are folders, not just markdown files: can include scripts, reference code, templates, config.json for setup, and data files
  • 9 categories: Library/API Reference, Product Verification (Playwright, tmux), Data Fetching/Analysis, Business Process Automation, Code Scaffolding, Code Quality/Review, CI/CD, Runbooks, Infrastructure Operations
  • “Gotchas section” is the highest-signal content: built from real failure points, updated over time as Claude hits new edge cases
  • Progressive disclosure: tell Claude what files exist in the skill; it reads them at appropriate times rather than front-loading everything
  • Description field is for the model, not humans — it’s what Claude scans to decide whether to trigger the skill
  • On-demand hooks: skills can activate session-scoped hooks (e.g., /careful blocks dangerous commands only when explicitly invoked)
  • Data storage: use ${CLAUDE_PLUGIN_DATA} stable folder per plugin; data in skill directory may be deleted on upgrade
  • Plugin marketplace pattern: skills check into GitHub, gain traction organically via Slack, then PR into marketplace

Insights

The verification skills category is the most underappreciated — spending a week making verification skills excellent dramatically improves output quality throughout the agent loop. The observation that “the description field is what Claude scans to decide if there’s a skill for this request” reframes skill description writing as trigger engineering, not documentation. The composability point (skills can reference other skills by name if both are installed) enables skill layering without native dependency management.

Connections

Raw Excerpt

A common misconception we hear about skills is that they are “just markdown files”, but the most interesting part of skills is that they’re not just text files. They’re folders that can include scripts, assets, data, etc. that the agent can discover, explore and manipulate.

Graph View

Backlinks