Anthropic explains how to build skills for Claude Code and why teams need their own marketplace

Anthropic has published a detailed guide to skills for Claude Code: extensions that help the agent work better with code, data and internal processes. The company says it already uses hundreds of such skills and has learned in practice which ones genuinely improve output quality and which only bloat the context.

Which skills work

The guide's main thesis: a skill is not just a markdown file with instructions but a full folder with configs, scripts, templates, data and even hooks. That is why Anthropic advises first determining the type of skill and only then writing its contents.

According to the company, the best skills usually solve one clear task. Those that try to be a reference, an autopilot, a runbook and a code generator all at once tend to confuse the model more than help it.

• Reference guides for APIs, SDKs and internal libraries
• Skills for verifying a product through the browser, CLI and assertions
• Tools for analyzing data, metrics and monitoring
• Templates for scaffolding, tests and code review
• Skills for CI/CD, runbooks and infrastructure operations

Anthropic singles out verification and operational skills. In the first case, the agent does not just write code: it runs the scenario itself, checks the steps and records the result. In the second, it gets guardrails for sensitive actions such as cleaning up resources, deploying or triaging alerts. These skills are especially valuable where mistakes are costly: in production, payments, onboarding and internal platforms. These scenarios show most clearly whether a skill turns the model into a reliable working tool.

How to write a skill

Anthropic advises against spending space on obvious things Claude already knows about code and common practices. It is far more useful to build a section in the skill covering real "gotchas": typical failures, non-trivial edge cases and a team's local rules.

Another important principle is progressive disclosure of context through the file system. API details can go into references, templates into assets, and repeatable logic into scripts. That way the model reads only what the current step requires.

"The best way to understand skills is to start, experiment and see

what works for you."

The authors also recommend planning the initial setup in advance: for example, storing parameters in config.json and asking the user structured questions if the config is empty. The description field should be written not as a marketing summary but as a trigger condition for the model itself. For memory, you can use logs, JSON or SQLite, but persistent data is better kept in a stable directory such as `${CLAUDE_PLUGIN_DATA}`.

Anthropic also specifically promotes storing code and helper libraries inside skills rather than making the model reinvent boilerplate every time. To simplify this, the company even released Skill Creator.

How to share within a team

For distributing skills, Anthropic describes two basic approaches: keep them directly in the project repository, or package them as plugins for the Claude Code marketplace. The first is convenient for small teams and a couple of repositories, but it has a cost: every committed skill adds context for the model. When skills multiply, it makes more sense to move them to a separate internal catalog where teams choose what to install themselves. This matters especially when projects live in different codebases and teams have different needs.

At Anthropic, there is no single central group that manually approves all skills from the start. Usually, useful work first appears locally, is then shared via GitHub and Slack, and moves to the marketplace once organic demand appears. Usage can be measured with PreToolUse hooks, and dependencies between skills are for now handled with simple references by name. The idea is to grow the library gradually, without clogging the system with duplicates and poorly maintained extensions.

What this means

Anthropic's guide points to an important shift: the value of AI development tools increasingly lies not only in the model but in how a team packages its knowledge, checks and safe processes around it. For Claude Code users, this is a signal to invest not in "magic prompts" but in their own layer of skills, which makes the agent more predictable, more useful and closer to real work tasks in an engineering environment.