Finding signal on Twitter is more difficult than it used to be. We curate the best tweets on topics like AI, startups, and product development every weekday so you can focus on what matters.
Aakash Gupta@aakashgupta · May 12, 2026 · 11 min read
Originally published by @aakashgupta on X. Tech Twitter preserves the original source alongside this readable edition.
Before you dive in
• Master Claude Skills: Learn 7 laws of effective skill design, testing strategies, and deployment across all surfaces
Best for builders who want practical takeaways. 11 min read.
Skills are one of the highest alpha things you can do in AI right now.
I’ve been talking to you about Skills since way before they were cool. My very first edition was on skills way back in October. Since then, I’ve also shipped 6 of my favorite skills for free and a free Claude Setup Skill.
What I haven’t shown you is rigorous testing of what makes a good vs bad skill, and how to improve your own existing skills.
That’s what today’s piece is about:
Why Skills Matter
How to Deploy Your Skills Everywhere
The 7 Laws of Great Tests from 75 Tests
How to Improve your Pre-Existing Skills
1. Why Claude Skills Matter
The 2023 to 2026 meta (“most effective tactic available”) was a prompt library. The 2026 meta is a skill library.
A prompt is text. A skill is behavior.
You have to remember a prompt exists. You have to find the right one. You have to paste it. You re-paste it next session because Claude doesn’t carry state. When you improve a prompt, the old version is still sitting in three other folders. When a teammate uses your prompt, they’re running a version that drifted six edits ago.
A skill is a reusable workflow you install once. Claude loads it automatically when the context matches, without you asking. It knows which files to read first. It knows what the output should look like. It knows what it shouldn’t touch. Standards encoded once apply across every session and every teammate.
The three types of prompt users, and why skills beat all of them
The one-liner user. Types “create tickets from this PRD” and hopes for the best. Claude invents the template, the format, and the detail level on the fly. Output changes every session. The skill user types the same thing, and the skill enforces the format, the acceptance criteria structure, the effort estimates, and the dependency map every time.
The mega-prompt user. Pastes 800 words at the top of every session. Encodes real standards but burns context tokens before the work starts, drifts with small errors every time it’s re-pasted, and can’t be handed to a teammate as a workflow. The skill user gets the same standards loaded only when relevant, never re-pasted, and shareable as a folder.
We doomscroll, you upskill
Get the 10 tweets shaping how builders think today.
Newsletter
We doomscroll, you upskill
Get the 10 tweets shaping how builders think today.
The structured prompt library user. Has a folder of well-written prompts organized by use case. Better than the first two and still losing to skills on three things: the prompt user has to remember which prompt to invoke, the skill user gets it auto-loaded by description match. The prompt user manually versions across tools, the skill user has one source of truth. The prompt user’s library breaks when switching from Claude to Cursor, the skill user’s library ports.
The skill user wins in every comparison because skills move the work from you to the system. You stop being the router. You stop being the version controller. You stop being the standards enforcer.
When to use a skill vs a prompt
Use a skill when you’d paste the same instructions twice, when the workflow has non-negotiable standards (output format, approval gates, source-of-truth files), when Claude needs to read context before generating, or when you want a teammate to run it identically without a Loom video explaining it.
Leave it as a prompt for one-off questions, exploratory conversations where the prompt is the work itself, simple lookups Claude can answer directly, or tasks that change shape every time.
The test: if you’d paste the same instructions twice, it belongs in a skill.
2. How to Deploy Claude Skills Across Every Surface
The skill architecture is coalescing across Claude, Cursor, Copilot, and Codex.
Make sure you deploy every skill across all the tools you use. Especially all 3 Claude tools. Here’s a quick refresher on how to do that:
Surface 1 - Claude Chat at Claude.ai
Settings, Customize, Skills. Upload the ZIP, toggle on. Type naturally or use /skill-name to force-load.
Surface 2 - Claude Code (terminal)
Personal skills go in ~/.claude/skills/skill-name/ and are active in every project. Project skills go in .claude/skills/skill-name/ inside a specific repo. Commit the folder and everyone who clones the repo gets the same skills automatically. This is the only surface where your skill ships with the codebase, so it’s where engineering standards belong.
Surface 3 - Cowork
Highest leverage for anything document-heavy. The skill reads your actual files, not pasted snippets. Type two words, get output that references your real context. This is the surface where a document too long to paste becomes a two-word command.
Skills also work in Claude for Excel and Claude for PowerPoint.
3. The 7 Laws of a Great Claude Skill
I’ve been using skills every day since October. But over the past week I went further and ran 3 tests on 25 of my top skills across work and personal use cases, trying different skill constructions to see what actually works.
The result is 7 laws of what makes a good skill:
Law 1 - The description is the routing layer
Claude scans every installed skill’s description at the start of a session. The full instructions, the output format, none of it loads until Claude decides the skill is relevant. That decision happens from the description alone.
I sent 10 prompts at a recipe planner skill. The description had 37 characters: “Suggest recipes from what’s in fridge.” Most prompts didn’t trigger it.
A good description is third person, states what the skill does and when to use it in the first sentence, includes trigger phrases a real user would type, and names at least one clear boundary.
The recipe planner skill I tested had a 37-character description. I sent 10 prompts that should have triggered it: “what can I make tonight,” “I don’t want to go grocery shopping,” “help me use up what’s in my fridge.” Most missed.
37 characters is not enough surface for Claude to recognize what the skill does. So the skill stays invisible.
Here’s the same skill with a description Claude can route on:
Law 2 - Every “Do not use for X” needs a “Use /Y instead.”
Most skill writers say when to use a skill. Almost no one says when not to.
When you exclude something without a pointer, Claude still has to pick something. It loads the closest match. The output is wrong format, wrong skill, delivered confidently.
The fix is in the description, not the body. In the body, an exclusion fires after the wrong skill has already loaded. In the description, it fires at routing time.
“Do NOT use for X” is advisory. “Do NOT use for X, use /Y instead” routes correctly.
Law 3 - Write commands, not requests
Every line in the body should be imperative. “Read the target file. Check for X. Output as Y.” Not “Could you take a look and maybe check for any issues?”
The code reviewer skill I tested opened with: “Hey! When the user asks for a code review, it would be great if you could go through their diff carefully and give them helpful, kind feedback.” Claude matched the energy exactly. The output was friendly, vague, and structured like a message from a thoughtful colleague. No severity ratings. No file and line references:
Switch the body to commands: “Check the diff. Flag every issue with severity (Critical/High/Medium/Low). Reference file path and line number for each. Do not soften.”
Same Claude. Same diff. Different output, because the instructions stopped asking nicely.
Law 4 - Build a read-first table, not just a read-first note.
The biggest single improvement across all 25 skills wasn’t a new rule. It was replacing one vague sentence with one specific table.
The debugger I tested had no read-first step at all. Hand it an error, get a competent-sounding generic analysis. Probable root causes. Suggested fixes. All pulled from training data. None of it touching my actual codebase, error logs, or recent commits.
The fix is three columns: Source, Path, What to extract.
That table tells Claude which directory, which search terms, what to pull out. That’s an instruction. ‘Check the relevant files’ is a label.
Law 5 - Without a template, Claude will invent one.
I ran my daily-plan skill three mornings in a row with the same prompt. Monday: bullet list by time block. Tuesday: narrative paragraph. Wednesday: numbered list with headers.
Same skill. Same prompt. Three different structures.
The instructions were clear. But there was no template and no example. Claude invented a new format every session because I never showed it what done looked like.
The fix is an output template that specifies the exact structure, plus a worked example that shows Claude what a complete output looks like. Rules describe a target. An example shows Claude what hitting it looks like.
Law 6 - One worked example beats five rules.
The commit message skill I tested had 12 rules. Comprehensive. Clear. And inconsistent across three consecutive runs with the same input.
“Concise” means something different every session. There was nothing concrete to pattern-match against.
I added two worked input/output examples and got identical structure across all three runs. Claude is an excellent pattern matcher. Give it a target, not a description of what the target looks like.
If you’re writing more rules than examples, flip the ratio.
Law 7 - Keep skills scoped and short.
Once a skill loads, every line competes with the conversation history for Claude’s attention. The longer the skill, the higher the chance Claude starts ignoring instructions toward the bottom.
I tested a fitness coaching skill that was 724 lines long. Genuinely good content. Training philosophy, injury history, deload protocols. And buried at line 700: the safety rules.
The safety rules never fired.
Move critical rules to the top, before everything else. Move background content to a references folder. Claude won’t read it until it’s needed.
4. How to Improve Your Existing Claude Skills: The Audit + Eval Loop to Steal
I’ve put together all of those laws into an easy Audit Checklist for you:
Description:
Over 100 characters?
3+ phrases a real user would type?
Written in third person?
What it does and when to use it in the first 250 characters?
At least one “Do not use for X, use /Y” boundary?
Body:
Instructions use imperative verbs?
Output format specified with a template or worked example?
Read-first table with Source, Path, and What to extract?
Critical rules in the first 100 lines?
Under 500 lines?
Automate It
The checklist is worth knowing. But you don’t have to memorize it. Send this prompt to a chat with your skill:
Use the advice in this article: <paste the article text> to improve the skill <name>.
The checklist gets you to a decent skill. This next prompt gets you to a hardened one. It sets 10 sub-agents loose on your skill, grades the outputs as a hard grader, and rewrites the skill across three rounds based on what broke. I’ve run it on every skill in my library. It surfaces failure modes I’d have never caught by hand.
Paste this into a chat with your skill loaded:
Set off 10 sub-agents that each use this skill with a realistic input (5 representing typical inputs and 5 representing edge cases). Print the input and output to a folder for proof of work. Then grade the output as a hard grader based on the intent of the skill. Then come back with the main grader and make the changes from all 10. Then print the outputs for a second round and grade them. Take all the feedback from 10 agents. Then have the main agent improve the skill and go for a third time get final clean up.
Run it once and you’ll watch Claude find holes you didn’t know your skill had. Run it on your top three skills this week. That’s the highest-leverage hour you’ll spend in Claude all month.
If you’ve just ctrl+a, ctrl+c, ctrl+v’d this into your Claude, it should pick up both prompts.
If you’re a PM, I wrote a version of this specifically for you over at Product Growth. It has a skill file to improve your skills, a skill file to create skills, plus an additional 3 laws for internal knowledge work.
Final Words
Optimize. Your. Skills. Nothing is more powerful than skills in this era.
