The paper "Lessons from building Claude Code: How we use skills" details Anthropic's experience in building and scaling hundreds of internal "skills" for Claude Code, defining them as flexible, discoverable folders of instructions, scripts, and resources designed to enhance agent accuracy and efficiency. Unlike mere markdown files, skills are structured directories capable of containing scripts, assets, data, and configuration options, including dynamic hooks for advanced functionality.

The core methodology revolves around how Claude Code agents discover, interpret, and execute these skills. When initiating a session, Claude constructs a listing of available skills based on their descriptions, which serve as triggers for the model. The internal structure of a skill, centered around a SKILL.md file, leverages "progressive disclosure." This means that while SKILL.md provides primary instructions, it can direct Claude to other files within the skill's folder (e.g., stuck-jobs.md, references/api.md, assets/templates) for more detailed information or specific scenarios. This hierarchical file system allows Claude to selectively access relevant context as needed, preventing information overload while ensuring comprehensive guidance.

Key technical aspects and best practices for skill development include:

• Structured Content: Skills are not just text; they integrate code, data, and configurations. The inclusion of executable scripts and libraries within a skill allows Claude to compose complex operations rather than regenerating boilerplate code.
• Persistent Memory: Skills can maintain state and "remember" past executions by storing data (e.g., text logs, JSON files, SQLite databases) within a stable directory accessible via the ${CLAUDE_PLUGIN_DATA} environment variable. This enables consistency and reflection across multiple invocations.
• Dynamic Hooks: Skills can register temporary, "on-demand" hooks, such as PreToolUse matchers. These hooks modify Claude's behavior only when a specific skill is active, enabling highly opinionated guardrails (e.g., blocking rm -rf when in a 'careful' mode) without constantly constraining the agent.
• Gotchas: A critical element is the "Gotchas" section within a skill, which documents common failure points and edge cases. This empirically derived information refines Claude's understanding and improves its performance over time.
• Model-Centric Descriptions: Skill descriptions are optimized for the model's triggering mechanism, including keywords (e.g., "babysit") that help Claude decide when to invoke a skill.
• Setup Configuration: Skills can incorporate config.json files to store user-specific context. If setup is incomplete, the agent can use tools like AskUserQuestion to prompt the user for necessary information.

Anthropic categorized their internal skills into nine distinct types, which serves as a framework for skill development:

1. Library and API reference: Explains correct usage of internal/external libraries, CLIs, SDKs, often with code snippets and gotchas.
2. Product verification: Describes testing/verification procedures, often paired with external tools like Playwright or tmux, enabling measurable quality improvements (e.g., signup-flow-driver, checkout-verifier).
3. Data fetching and analysis: Connects to data and monitoring stacks, providing credentials, dashboard IDs, and common workflow instructions (e.g., funnel-query, grafana).
4. Business process and team automation: Automates repetitive workflows, potentially relying on other skills (e.g., standup-post, $create-<ticket-system>-ticket$).
5. Code scaffolding and templates: Generates boilerplate code for specific functions or frameworks, useful for natural language requirements (e.g., $new-<framework>-workflow$, create-app).
6. Code quality and review: Enforces code standards and assists with code reviews, sometimes using deterministic scripts (e.g., adversarial-review, code-style).
7. CI/CD and deployment: Facilitates fetching, pushing, and deploying code, referencing other skills for data collection (e.g., babysit-pr, $deploy-<service>$).
8. Runbooks: Guides multi-tool investigations based on symptoms (e.g., alerts, errors) to produce structured reports (e.g., $<service>-debugging$, log-correlator).
9. Infrastructure operations: Performs routine maintenance and operational procedures, especially those involving destructive actions (e.g., $<resource>-orphans$, cost-investigation).

Skills can be distributed by checking them into a repository (./.claude/skills) or via an internal plugin marketplace. While direct dependency management is not natively built, skills can reference each other by name, allowing Claude to invoke them if installed. Skill effectiveness is measured using PreToolUse hooks to log usage, enabling identification of popular or under-triggered skills. The paper concludes by emphasizing the iterative nature of skill development, where initial simple versions evolve through continuous refinement based on Claude's interaction with real-world edge cases.