← Claude
Brock Mesarich | AI for Non Techies
Anthropic Just Dropped Their Claude Skills Secrets (steal these)
⏱ 10 min video · 3 min read5 Jun 2026
TL;DR
Anthropic published an internal article revealing how their team uses Claude skills (previously called commands) at scale, with hundreds in active use. This video breaks down the key lessons — including common mistakes, folder structure best practices, and how to write descriptions that actually help Claude trigger the right skill at the right time.
Key points
1
Skills are folders, not just markdown files — they can include scripts, assets, data, and multiple sub-files that Claude can discover and use dynamically.
2
Anthropic identifies 9 skill categories (library/API references, product verification, data analysis, business automation, scaffolding, code quality, CD deployment, incident runbooks, infrastructure ops) and warns that skills trying to span multiple categories confuse the agent.
3
The 'gotchas' section is called the highest-signal content in any skill — it documents what Claude should NOT do based on real failure points, and should be updated over time.
4
Skill descriptions should be written for the model, not humans — they tell Claude WHEN to trigger that skill, not what the skill does for the user.
5
Avoid over-prescribing steps in a skill; giving Claude flexibility to adapt to a situation outperforms rigid step-by-step instructions.
Actionable insights
→
Add an 'avoid' markdown file inside your skill folder listing what Claude should never do — this gotchas approach is Anthropic's highest-priority skill content.
→
Rewrite your skill description fields immediately: they should describe WHEN to trigger the skill, not summarize what it does.
→
Use sub-files within skill folders for edge cases and troubleshooting so Claude can read them progressively rather than loading everything upfront.
→
Start new skills with just a few lines and a gotchas section, then iterate as Claude hits new edge cases — do not try to engineer the perfect skill from day one.
→
Share skills with teams by placing folders in the .claude/skills directory or packaging them as a plugin for bulk sharing.
Notable quotes
“The best skills cleanly fit into one. The ones that try to do too much straddle several and confuse the agent.”
“Think of this entire file system as a form of context engineering and progressive disclosure.”
“The description field is not a summary. It is a description of when to trigger this skill.”
Worth watching?
⏭️
Worth watching the full video?
The core value is fully captured here — skip the video unless you want to see the Claude Code interface walkthrough of the email drafter skill folder, which adds minor visual context.
Saved you some time? The creator still deserves a like.
Want this for your own channels?
Add the channels you follow. Every new video summarised and in your inbox the moment it drops. From £4/month.
Try it free