Claude Code skills: what Anthropic learned from using hundreds of them

Thariq from the Claude Code team wrote a long post in March 2026 about how Anthropic uses skills, the folders of instructions and scripts that Claude Code loads when a task needs them. He says hundreds of them are in use there.

What a skill is

A skill is a folder with a SKILL.md file in it. The file starts with a short frontmatter (a name and a description), followed by the instructions. The folder can also hold anything else the task needs: reference notes, scripts, templates, sample data.

A skill is not loaded all at once. When a session starts, Claude Code reads only the name and description of each skill. The body loads when the skill is used, and the other files only when the instructions point to them, so a long skill costs almost nothing until it is needed. A skill can also bring its own settings, such as hooks that switch on only after it is invoked.

Thariq's point is that people treat skills as "just markdown files" and miss the folder. In his words, "a skill is a folder, not just a markdown file." The skills that work best at Anthropic, he says, use the folder and the configuration on purpose.

Nine kinds of skills

When his team went through all of their skills, they found most fall into a few groups. A good skill sits clearly in one group; the confusing ones straddle several. His list:

1. Library and API reference. How to use an internal library or CLI correctly, with code snippets and a list of mistakes to avoid.
2. Product verification. How to check that the code works, often by driving a browser or a terminal with tools like Playwright or tmux.
3. Data fetching and analysis. How to reach your data and dashboards, which tables to join, which IDs to use.
4. Business process automation. Turning a repeated chore, such as a standup post or a weekly recap, into one command.
5. Code scaffolding. The boilerplate for a new service, migration or app, the way your team wants it.
6. Code quality and review. House style and review rules, sometimes run from a hook or a CI job.
7. CI/CD and deployment. Watching a pull request, retrying flaky CI, rolling out and rolling back.
8. Runbooks. Starting from a symptom, such as an alert or an error, and walking through the investigation to a short report.
9. Infrastructure operations. Routine maintenance, including risky clean-ups, with guardrails and a confirmation step.

He singles out verification. In his view it can be worth having an engineer spend a whole week on the verification skills alone, for example so that Claude records a video of what it tested, or checks the state with code at each step.

How to write a good skill

Skip what Claude already knows. Claude knows a lot about code and about your repository. A skill earns its place when it moves Claude away from its defaults. His example is Anthropic's frontend design skill, built to steer Claude away from common choices like the Inter font and purple gradients.

Keep a list of gotchas. He calls this the most valuable part of any skill: the places where Claude actually goes wrong when it uses the skill. The list grows each time Claude hits a new problem.

Use the folder. Put details in separate files and say in SKILL.md what each file holds, for example function signatures in references/api.md or an output template in assets/. Claude reads them when it needs them. The docs suggest keeping SKILL.md under 500 lines and moving reference material out.

Don't script every step. Skills get reused in many situations. Give Claude the information it needs and leave room to adapt, instead of a fixed sequence it must follow.

Plan the setup. If a skill needs something from the user, such as which Slack channel to post to, keep it in a config file inside the skill folder and have Claude ask when it is missing.

Write the description for the model. At the start of a session Claude sees a list of every skill with its description, and decides from that list whether a skill fits the request. So the description should say when to use the skill rather than summarise it. The docs add two limits: the description and the optional when_to_use text are cut at 1,536 characters in that list, and the whole list gets about 1% of the context window, so with many skills some descriptions get dropped.

Let the skill remember. A skill can keep a log, a JSON file or a small SQLite database, so the next run knows what happened last time. A standup skill that logs every post can tell what changed since yesterday. Files inside the skill folder can be replaced when the skill is updated; for skills in a plugin, Claude Code provides ${CLAUDE_PLUGIN_DATA}, a data folder that survives updates.

Ship code, not only text. Scripts and helper functions let Claude spend its turns deciding what to do instead of rewriting boilerplate. With a few data-fetching helpers in the skill, Claude can write a short script that combines them to answer something like "what happened on Tuesday?".

Use hooks that turn on only when needed. A skill can register hooks that start when the skill is invoked and stay on for the rest of the session. His examples are a "careful" skill that blocks commands like rm -rf, DROP TABLE or a force push while you work near production, and a "freeze" skill that blocks edits outside one folder while you debug. Neither is something you would want on all the time.

Sharing and measuring

There are two ways to share skills with a team. You can commit them to a repository under .claude/skills, or package them as plugins and publish them through a plugin marketplace: a repository with a marketplace.json file that people add once and then install plugins from.

Committing skills works for a small team with a few repositories. Every committed skill adds a little to the context of every session in that repository, though, so at a larger scale a marketplace lets each person install only what they use.

According to Thariq, Anthropic has no central team that picks skills. Someone puts a new skill in a sandbox folder, points people to it, and once it has users, moves it into the marketplace with a pull request. He warns that bad or duplicate skills are easy to make, so some review before release matters.

His post also mentions two practices that the Claude Code docs don't describe:

• Skills that use other skills. A skill can mention another skill by name, and Claude will use it if it is installed. There is no real dependency management for this yet.
• Measuring use. His team logs skill usage with a PreToolUse hook, which shows the popular skills and the ones that trigger less often than expected.

Limits

• The nine groups are one team's way of sorting its own skills, not an official taxonomy.
• Most of the tips come from Anthropic's internal use. How well they carry over depends on your codebase and on how many skills you have.
• The features mentioned here (skill folders, loading on demand, hooks in skills, the plugin data folder, marketplaces) are in the Claude Code docs. The rest is advice from one team.

Thariq ends by noting that most of their skills began as a few lines and one gotcha, and got better as people added to them each time Claude hit a new edge case.

Sources

• Thariq (@trq212), Lessons from Building Claude Code: How We Use Skills, X, 17 March 2026
• Claude Code docs: Skills, Plugins reference, Create a marketplace