Claude Code Isn’t Broken. You Just Haven’t Sharpened It.
The “Cool Tool” Trap
“I tried Claude Code! It’s so cool!” — there are hundreds of posts like this.
Most of those authors will say “it doesn’t really work” three months later.
The reason is simple. They feed raw prompts into a raw Claude Code setup and accept raw results. That’s like complaining a knife doesn’t cut when you’ve never sharpened it.
Claude Code’s performance is determined by what you put into it. It’s not a tool problem. It’s a sharpening problem.
Skills Are Folders, Not Markdown Files
Recently, Thariq — an engineer at Anthropic — published a breakdown of how they design Skills internally. He categorized their battle-tested Skills into nine types:
- Library & API Reference
- Product Verification
- Data Fetching & Analysis
- Business Process & Team Automation
- Code Scaffolding & Templates
- Code Quality & Review
- CI/CD & Deployment
- Runbooks
- Infrastructure Operations
Here’s the most overlooked fact: Skills are not “just markdown files.” They’re folders.
Scripts, assets, templates, config files — all bundled into a single “capability package.” Claude explores the folder contents and reads only what it needs, when it needs it. This is called Progressive Disclosure.
You put helper functions and query templates inside the Skills folder. Claude assembles scripts on the fly. All you have to do is ask “What happened on Tuesday?”
The Highest-Value Section Is Gotchas
The most practical line in Thariq’s entire article:
The highest-signal content in any skill is the Gotchas section.
Gotchas: a list of failure patterns Claude repeatedly hits when using that skill.
For a design skill: “Don’t pick Inter.” “Don’t use purple gradients.” “Question Tailwind’s default blue.” For a blog writing skill: “No em dashes in Japanese — they look AI-generated.” “No self-introductions in the opening.” “Replace adjectives with verbs.”
You don’t need to write these perfectly from day one. You can’t.
Just add one line every time Claude fails. That’s it.
Three months later, that Skill becomes a mine map of every mistake you’ve already stepped on. Eliminating repeat failures saves several back-and-forth exchanges per session.
Description Is a Trigger, Not a Summary
Another small tweak that compounds over time.
When Claude Code starts a session, it scans every available Skill’s description to decide: “Is there a skill for this request?”
The description field isn’t a summary. It’s a trigger condition.
Bad: “A skill that generates PPTX files.” Good: “Use when the user mentions slides, presentations, decks, or requests PPTX creation or editing.”
The first version leaves Claude guessing. The second fires instantly when someone says “make me a deck.”
This looks trivial. But in a workflow where Skills fire ten times a day, trigger accuracy directly determines output quality.
Tools Are Meant to Be Sharpened, Not Just Used
By now, you’ve probably noticed something.
None of this requires advanced programming skills. Add one line to Gotchas. Rewrite a description. Drop a script into a folder. Set up a hookify rule to block destructive operations. Each takes minutes.
The only question is whether you do it or not.
Thariq closes his article with this:
Most of ours began as a few lines and a single gotcha, and got better because people kept adding to them as Claude hit new edge cases.
They started with a few lines and one gotcha. They grew the Skills by adding to them every time Claude hit a new edge case.
Tools aren’t meant to be used. They’re meant to be sharpened. And the sharper they get, the better they cut.
The Best Work Still Requires a Human
But after everything I’ve written here, there’s one thing left to say.
No matter how sharp the tool, deciding what to build with it is still a human job.
You can fill all nine Skill categories. Accumulate a hundred lines of Gotchas. Wire up On Demand Hooks as safety nets. All of that gives you a razor-sharp blade.
But what do you cut with it? Who do you cook for? Why does it matter?
The most valuable thing in the age of AI is not tool performance. It’s the human judgment that takes a sharpened tool and does something extraordinary with it.
Sharpening is a necessary condition, not a sufficient one. Taking the sharpest tools and doing the best work — that remains the most valuable thing only a human can do.