Skip to content
BSWEN
Blog

How to Write a Claude Code Skill That Actually Improves Output

Cowrie
Cowrie
Dev @ Bswen

Problem

When I open a random “Claude Code skill” file from the internet, I keep seeing the same opening line:

Generic skill files I find online
You are an expert full-stack developer with 20 years of experience in
React, Node.js, and TypeScript. Always write clean, maintainable code.

It does not change what Claude does. It does not stop the model from making the same mistake twice. It is not a skill. It is motivational wallpaper, and it costs me context tokens every time it loads.

A recent r/ClaudeAI thread (861 upvotes) made the same complaint. The top replies all said the same thing in different words: a good skill is a scar, not a resume. If the file does not stop the agent from repeating a specific mistake, it is not doing its job.

Architecture diagram comparing a fixed connector node (n8n LLM Node with templated prompt, single input and single output) against an autonomous subagent node (Claude Code step with a goal, a model loop, and tools such as filesystem, bash, and MCP)

That picture is the mental model I use. A skill is the node on the right. It has a goal, a loop, and tools it can call. The node on the left (a fixed prompt in and a fixed string out) is what most online “skills” are.

What a Useful Skill Actually Is

A useful Claude Code skill is a scar, not a resume. It encodes a specific correction, constraint, or repeatable procedure the model otherwise gets wrong or skips. It does not introduce the model to a profession, list adjectives, or restate things Claude already knows.

A skill earns its place when it can do at least one of these:

  • Force a correction Claude reliably skips (e.g., “no comments in code”, “verify in a browser before marking the task done”)
  • Bundle a script the model can execute (lint, test, image API call)
  • Encode a structural test plus the action to take if it passes or fails
  • Provide a tiny, opinionated procedure with the gotchas baked in
  • Pin a project-specific rule that is not derivable from the codebase (e.g., “always use src/components/Button, never a raw <button>”)

If a paragraph from the skill could be moved into the README and lose nothing, the skill was documentation in disguise.

Environment

  • Claude Code with skills enabled (Anthropic skills shipped in 2025)
  • Skills folder at .claude/skills/<name>/SKILL.md
  • Frontmatter fields used: name and description
  • A small set of helper scripts in .claude/skills/<name>/scripts/ where needed

What happened?

I started writing skills the way I saw them online. I copied the “expert senior engineer” pattern into a SKILL.md, gave it a description, and expected the model to act differently. It did not. The behavior was identical to a session with no skill loaded. The cost was not zero either, because that paragraph was sitting in the system context the whole time.

Here is what the bad shape looked like:

SKILL.md (do not write this)
---
name: senior-engineer
description: Be a senior engineer.
---


You are an expert full-stack developer with 20 years of experience
in React, Node.js, and TypeScript. Always write clean, maintainable
code.

The frontmatter has a trigger, but the body has no condition, no command, no script. There is nothing for the model to execute, and nothing for it to verify. I removed it.

How to solve it?

I tried four shapes that actually work. Each is short, atomic, and triggered by its own description.

Solution 1: Scar skill — “no comments, no trailing summary”

.claude/skills/no-comments-no-summary/SKILL.md
---
name: no-comments-no-summary
description: Use when finishing a code edit. Strips decorative
comments and the "I've made the changes..." paragraph at the end.
---


When you finish a code edit:


1. Remove all comments that do not explain a non-obvious constraint
   (regex, magic number, security boundary).
2. Do not add a closing summary like "I've updated the file to..."
   in your reply.
3. The reply should end on the diff or the command, not on prose.

Solution 2: Procedure skill — “verify in a browser”

.claude/skills/frontend-verify/SKILL.md
---
name: frontend-verify
description: Use when reporting a frontend task as done. Forces a
real browser check before marking complete.
---


Before reporting a frontend task as done, run all of these:


1. Start the dev server.
2. Open the affected route with the Playwright MCP tool.
3. Confirm the new component is visible, interactive, and styled at
   mobile and desktop widths.
4. Paste the screenshot paths into the final reply.


If any step fails, report the failure. Do not mark the task complete.

Solution 3: Test skill — “hardcoded value check”

.claude/skills/no-hardcoded-values/SKILL.md
---
name: no-hardcoded-values
description: Use when closing any task that produced config, env,
or constants.
---


Before closing, run the structural test:


1. Grep the diff for literal values matching
   `(\d+\.\d+\.\d+|sk-|api_key|localhost:\d{2,4})`.
2. If any match, move them to the appropriate config or env file
   and re-run the build.
3. If the build passes, append "hardcoded-value check: clean" to
   the reply.

The original poster mentioned a variant of this that caught a bug every other session. That is the right bar for a useful skill.

Solution 4: Project-specific rule skill

.claude/skills/use-button-component/SKILL.md
---
name: use-button-component
description: Use when generating or editing any JSX. Forbids raw
HTML button elements.
---


When you write JSX:


- Use `import Button from 'src/components/Button'` for any clickable
  element.
- Never emit a raw `<button>` or `<a>` in a component file.
- If a designer asks for a native element, ask first. Do not assume.

This one is too project-specific for the global skills folder, so I keep it in the repo under .claude/skills/ and let Claude Code discover it through the project.

The reason

I think the key reason the “expert engineer” pattern still spreads is that it looks like configuration. A new developer assumes Claude Code is a blank slate and that something has to go in the file. The opening line feels safe.

What the model actually does is match the skill’s description to the current task. If the description says “Be a senior engineer”, the match is weak and the body is irrelevant. If the description says “Use when finishing a code edit. Strips decorative comments”, the match is specific and the body has to be specific too. The frontmatter is the API; the body is the behavior.

A second reason: skills are loaded into context. Every line of fluff reduces the budget for real rules and real scripts. The Reddit thread put it bluntly. The cost of a bad skill is paid twice, once when it loads and again when the model still does the thing you wanted it to stop doing.

Common Mistakes

  • Opening a skill with “You are an expert…”. It changes nothing and burns tokens.
  • Restating general best practices the model already follows.
  • Treating a skill like a system prompt. Bleaveand in the thread said it best. Stop thinking of skills and start thinking of functions. Something atomic and repeatable.
  • Treating a skill as docs. If you could delete the file and put the paragraph in the README without losing anything, it was a doc all along.
  • Never updating the skill. When the model changes, the skill must change with it. If it does not, delete it.
  • Skills vs hooks vs slash commands. A skill is content the agent reads when it decides the trigger matches. A hook is a shell command the runtime fires. A slash command is something the user types. They are not interchangeable.
  • Skills vs CLAUDE.md. CLAUDE.md is always-loaded project context. Skills are on-demand. If a rule must always be on, it belongs in CLAUDE.md. If it only matters in a narrow situation, it is a skill.
  • Skill rot. A skill written against an older Claude model can become wallpaper when the model improves. Re-test skills against the current model every few months. Keep a one-line note in the file with the date it was last verified.

Summary

In this post, I showed how to write a Claude Code skill that earns its place. The key point is to treat a skill as a scar (a rule that prevents a specific mistake), a test (a structural check plus a response), or a procedure (a sequence of commands the agent can run). Drop the persona intros. If a paragraph could live in a README, keep it there instead. Update the skill when the model changes, or delete it.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: