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.

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.

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.