Using Claude skills: shape the work with named workflows

What a skill actually is

A skill is a named workflow. You give it a name, a short description, and a body that tells Claude Code what to do when you call it. From then on, instead of writing the same long prompt every time, you call the skill and Claude Code executes the workflow. Skills can read files, call MCP tools, run shell commands you allow, and produce output in a shape you specified. They are the right shape for repeated work that is not quite a unix command but is too structured to keep rewriting.

The cleanest mental model is that a skill turns a recurring conversation into a button. The button does what you would have done in chat. The button is faster because it skips the setup. The button is more reliable because the prompt is committed and version controlled. Once you have a few skills you trust, your sessions get shorter, because the work that used to take a paragraph of prompting now takes three words.

When to reach for a skill

Reach for a skill when you notice you have written the same prompt three times. Or when a teammate asks how you do a specific task and your answer is half a page. Or when a project has a step that always needs the same shape of output and the shape matters. Those are the moments where a skill repays the setup cost. If you have not written the prompt twice yet, do not make it a skill. Premature skills are like premature abstractions. They lock in a shape before you know which shape is right.

• Generating release notes from a git log with your team voice and formatting rules
• Running a security review of new dependencies before they land in package json
• Producing a weekly status update from the current branch state and open PRs
• Writing an OpenAPI spec stub from a new route file with consistent naming conventions
• Drafting a PR description that follows your team template and checklist

Calling a skill

You call a skill by name inside a Claude Code session. The exact invocation depends on the version you are on, but the shape is consistent. You give the skill name and any arguments it needs. Claude Code runs the workflow, shows you what it is doing, asks for approval at the points that mutate state, and returns the output. There is no fundamental difference between calling a skill and asking Claude Code to do the same thing in chat, except that the skill version is reproducible and faster.

Pass arguments rather than embedding values. If your release note skill always pulls from the main branch, pass main as the argument rather than hard coding it in the skill body. The skill stays portable across branches, releases, and projects. The five seconds you save by hard coding cost you the next time you need to run the same skill against a different target. Arguments are the seam that lets a single well written skill serve many small variations.

Writing your first skill

Pick a workflow you actually run weekly. A release note generator is a great first skill because the inputs are clear, the output shape is well defined, and the cost of getting it wrong is small. Write the skill in plain language. Tell Claude Code what inputs to expect, what to do with them, and what shape the output should take. Save it where Claude Code can find it. Test it on a real example. Iterate until the output is the shape you want without manual cleanup.

1. 1Pick a workflow you have run at least three times in the last month
2. 2Write the prompt as you would in chat, including the structure of the output
3. 3Save it as a skill file with a clear name and a one line description
4. 4Call the skill on a real input and compare the output to what you would have written by hand
5. 5Edit the skill until the output is good enough that you no longer want to rewrite it

Sharing skills across projects

Some skills belong to one project. Others belong to you across every project. A skill that drafts a PR description in your team template is project specific. A skill that finds unused imports in a Next.js codebase travels with you. Keep these in different folders so you do not accidentally drag project conventions into a different repo. The club at claudecodeclub.ai keeps a shared library of skills that travel well, and the $9 a month is mostly the time you save not writing those from scratch.

When a skill becomes clutter

Not every skill earns its keep. The ones you wrote in a burst of enthusiasm and never called again should be archived. Delete is fine too. A list of fifty skills you can barely remember is worse than ten skills you trust. Once a quarter, scroll through your skill list, call the ones you have not touched in a month, and decide whether they still match how you work. The ones that no longer fit go. The ones that almost fit get a small edit so they fit again.

Skills and MCP together

Skills compose well with MCP servers. A skill that drafts a PR description can call the GitHub MCP to pull the existing PR template, read the diff, and produce a body that matches your team conventions. A skill that builds a weekly status update can call the GitHub MCP for open PRs, the Linear MCP for assigned tickets, and a Slack MCP to post the result. The combination is where skills feel less like prompts and more like small programs. The /guides/setting-up-mcp-servers guide covers the underlying setup.

Versioning skills

When you change a skill, write down what changed. Even a one line note in the commit message. Future you wants to know why the release note format shifted, why the status update suddenly grew a new section, why the security review now flags one more pattern. Skills are small enough that they feel disposable. Treat them with the same care as small libraries, because over a year the cumulative effect on your output is the same as switching a small library.

Naming skills so future you finds them

Skill names are an interface. Pick names that read like commands rather than essays. release notes from log is a good name. generate the release notes by reading the git log of recent commits is a description, not a name. Future you, scanning a list of skills at the end of a long week, wants the short name. Use the description field for the longer explanation. The split between name and description maps to the split between calling a skill and reading about a skill, and respecting that split keeps the library usable as it grows.

When a skill should be a script instead

Not every workflow belongs in a skill. If the work is deterministic, has no judgment involved, and just needs to run, it belongs in a shell script or a make target. A skill that always produces the same output for the same input is a script wearing a costume. The signal is when you stop reading the output before pasting it on. That means the skill is no longer adding judgment, it is just running. Move it to a script, save the model call, and use skills for the work that still benefits from a thoughtful agent in the loop.

Composing skills together

Once you have a few skills, you start composing them. A release skill that calls a notes skill that calls a diff summary skill. Each smaller skill stays focused on one job, and the bigger skill orchestrates. Composition keeps each skill testable. When something breaks, you only debug the one piece that broke, not the whole pipeline. Keep the composition shallow at first. Two levels deep is plenty for most workflows. Deeper composition is rarely worth the maintenance cost on a side project, but on a team product it can be a real edge.

Testing a skill before you trust it

Run a new skill on three different real inputs before you decide it works. One input is not enough. The first run can pass on luck. The third run shows you whether the skill handles edge cases or whether you tuned it to a single example. If two of three runs produce the right shape and one does not, the skill is not ready. Tighten the prompt, name the failure case explicitly, and run again. The cost of testing is fifteen minutes. The cost of trusting an undertested skill is months of subtly wrong output.

Designing the output shape

The biggest reason a skill outperforms a chat prompt is that the output shape is fixed. You decide what good looks like once and the skill produces it every time. Be specific. A release note skill should not say produce release notes. It should say produce a heading line, a summary paragraph of two sentences, a bullet list of user facing changes, a separate bullet list of internal changes, and a footer with the deploy date. The more concrete the shape, the more consistent the output, and the less manual cleanup you do at the end.

If the output is going to be pasted into another tool, name the format that tool expects. Markdown for GitHub PRs, plain text with line breaks for Slack, HTML for a marketing email. Claude Code is good at producing whatever shape you specify, but it cannot read your mind about which shape you wanted. A one line note in the skill that says output in slack flavored markdown removes a whole class of small mistakes.

Skills as documentation

A skill is also documentation for how you do a thing. When you onboard a teammate, the skills folder is half of your handoff. They can read what each skill does, run it on their own input, and understand the workflow without you walking them through it. This is one of the quietly large benefits of writing skills. The act of capturing the workflow forces you to make it explicit, and explicit workflows are easier to teach.

Keep a short readme alongside the skills folder that lists the names and a one line description of each. Update it when you add or remove a skill. The readme is the index that makes the folder readable. Without it, a folder of fifteen skills is a folder of fifteen mystery files. With it, the folder is a small product your team can use without asking you which skill does what.

Skills versus CLAUDE.md instructions

CLAUDE.md files and skills solve different problems. CLAUDE.md is always-on context - project conventions, stack choices, things Claude Code should know for every single interaction. Skills are on-demand workflows - you call them when you want them and they do nothing when you do not. If a piece of guidance should apply to every session, it belongs in CLAUDE.md. If it should only apply when you explicitly request a specific kind of output, it belongs in a skill. The two complement each other and using both makes sessions both consistent and efficient.

One practical rule: if you find yourself writing the same instruction in both CLAUDE.md and in a skill, remove it from the skill and let CLAUDE.md carry it. Skills should add workflow-specific behavior on top of the baseline that CLAUDE.md establishes. Duplicating context wastes tokens and creates a maintenance problem when one version drifts from the other.

Parameterizing skills for different contexts

A skill that takes arguments is more powerful than a skill that has all values hard-coded. A release notes skill that accepts a branch name and a version tag can serve every release without modification. A PR description skill that accepts a JIRA ticket number can include the ticket in the output without you copying and pasting it. Arguments are the seam that turns a skill from a fixed template into a flexible tool.

1. 1Identify every value in the skill that changes between uses and replace it with a named argument
2. 2Document the arguments in the skill description so future callers know what to pass
3. 3Add a default value for arguments that rarely change so the common case stays concise
4. 4Validate inputs at the top of the skill if the skill will produce very different results on bad input
5. 5Test the skill with two or three different argument combinations before treating it as production ready

Skills for code review and quality gates

One of the highest value skill categories is code review assistance. A skill that reads a diff and checks it against your team's standards catches things that get missed in manual review. Not the logic - that still needs human eyes. The structural things. Are functions over a certain length. Are there hardcoded strings that should be constants. Does the new code add dependencies that were not in the brief. Are there missing tests for the new code paths.

A code review skill works well as the last step before opening a PR. Run it on the diff, read the output, address what is valid, and document what you decided to skip and why. The skill produces a consistent checklist pass that would otherwise depend on remembering to check each thing manually. Members at claudecodeclub.ai share review skill configurations for common stacks. The value of borrowing one over writing from scratch is that the borrowed version already covers the issues that have actually been missed in similar projects.

Skills as client deliverables

If you use Claude Code to do client work, skills are part of what you deliver. A client who gets a project handoff with a well-documented skills folder gets ongoing leverage from the tool, not just a finished product. The release notes skill runs after every deploy. The PR review skill runs before every merge. The status update skill runs before every client call. The handoff that includes the skills folder is more valuable than the handoff that does not, and the extra work to package the skills is small.

Price this accordingly. If your client's team will get ongoing productivity from the skills you wrote for them, that is part of the value you delivered. The $9 a month club at claudecodeclub.ai teaches this framing explicitly - the skills you build for yourself during the project become part of the productized service you can offer to the next client. The first time you write a skill takes the longest. The second client who needs the same category of workflow pays for the refinement, not the creation.

Keeping the skills library small and useful

The goal is a small library of skills you trust and reach for naturally, not a comprehensive collection of skills you might someday need. Aim for ten well-tested skills over fifty mediocre ones. Each skill in the library should have been called at least three times in real work before you treat it as stable. Skills that have never been called in production should be archived or deleted. The test is simple: can you name what each skill does and the last time you used it without looking it up? If yes, it belongs. If no, it is probably clutter.

The end state

After a few months of using skills well, your Claude Code sessions get quieter. Less prompting, more invocation. The work you used to type out lives in three or four trusted skills you call by name. The day to day becomes lighter, the output gets more consistent, and the cost of onboarding a teammate to your workflow drops because you can hand them the skills folder and they are most of the way there. Pair this guide with /guides/git-workflow-with-claude-code and the skill library starts to feel like its own product.