How to Create a Skill for Claude Code from Scratch: Practical Guide with Real Examples

Updated: March 2026

You've probably already heard about Claude Code skills. Maybe you've read something about them, maybe you've seen someone using them, but you haven't quite figured out why it's worth your time.

Short answer: because you stop repeating the same instructions every time and start having an assistant that really knows you.

If you want to start with concrete examples before building your own, read the 8 skills I use in daily workflow - including ones to avoid. Once you've built your first skill, follow the best practices to refine and maintain it over time.

In this article I explain how to build them, with examples from my real workflow, including mistakes I made and ones you should avoid.

What Claude Code Skills Are

A Claude Code skill is a markdown file with structured instructions that Claude executes on request, invoking it with /skill-name from the CLI. It lets you save a set of behaviors, formats, and contexts you'd otherwise rewrite every session. It's not a plugin, not an API: it's portable textual configuration.

There are two types:

• Global skills: available in all projects, useful for recurring personal tasks (branding, quotes, communications)
• Project skills: specific to a technology or client, activated only in relevant context

The key word is context persistence: the skill ensures Claude already knows you before you speak.

Skills vs MCP: What's the Difference and When to Use Each

One of the most frequent questions is: when use a skill and when use an MCP (Model Context Protocol)?

The line is blurring. Today for daily use, CLI skills are more efficient than MCPs in most cases. I built an MCP for VTENext CRM that exposes APIs in natural language, and it makes sense in that context. But for personalizing your workflow, skills beat MCPs in efficiency. My prediction is CLI skills will replace many MCPs in common use cases soon.

When It's Worth Creating a Skill

The answer I've arrived at after months of use: when you feel the need to instruct your personal assistant, meaning someone who actually knows you.

The practical signal is simpler: if you find yourself repeating the same instructions to Claude three times or more, that's a skill you haven't written yet.

It's not about automating for the sake of it. It's about not wasting context (and time) re-explaining every time who you are, how you work, what format you want, what constraints you have.

How I Started: From Branding to Quotes

The first skill I built was about Castaldo Solutions branding: fonts, colors, tone of voice, target, tagline. Everything Claude needs to produce coherent communications without specifying it every session.

The savings were already concrete: every prompt for DALL-E or LinkedIn post started with the right context, without starting from scratch.

But the real value jump came with the quote skill.

Client quotes always follow the same structure: a Word document with defined sections and precise formatting. Before the skill, I either had to start from a manual template or re-explain to Claude how I wanted the file each time. With the skill, Claude keeps the document base code and applies it automatically to every new quote. Just pass client data and project context. That was when I understood how powerful the tool is.

Estimated savings: every hour spent building a skill saves at least ten hours short-term.

How to Build a Skill in 3 Steps

Step 1: Define the Output First

What assets should the skill produce? In what format? With what constraints? If you're not clear on this, instructions will be vague and output inconsistent. It's exactly like when you instruct a collaborator: if you don't know what you want, you can't explain it.

Step 2: Write Instructions Without Contradictions

Every rule must be consistent with the others. If you write "always use formal tone" and then "use the informal you", you're already creating confusion. Re-read the skill as if you had to interpret it yourself, without added context.

Step 3: Test, Measure Tokens, Iterate

This is the step almost everyone skips. A poorly built skill doesn't just produce bad output: it erodes conversation context, accelerating context rot (see next section). Test the output, verify how many tokens the skill uses, remove everything not strictly necessary.

Average time: 1 hour for a working skill with clear ideas. 3+ hours with iterations and refinements.

How to Use the skill-creator to Build Skills Quickly

The most efficient way to build a skill from scratch is using the skill-creator built into Claude Code, which leverages cowork mode.

Here's how it works:

1. Describe to Claude the skill you want to build
2. Claude starts a multi-agent process: creates 3 separate agents with different approaches
3. Compares the results and asks for feedback on what works
4. In 2 iteration cycles, you get a complete skill packaged as an installable .skill file

You're not a spectator: you're an active part of the process. The result reflects exactly how you work, not a generic template. This is the recommended way for starters.

What Context Rot Is and How Poorly Built Skills Accelerate It

Context rot is the progressive degradation of AI conversation quality as context fills up.

Technical definition: every Claude session has a limited context window (the active "memory" of conversation). As it approaches the limit, older information gets compressed or loses influence on responses. Claude starts forgetting initial instructions, produces less coherent output, and quality noticeably degrades even within a single work session.

Poorly built skills accelerate this significantly. If a skill is full of redundant information, unnecessary assets, or verbose instructions, each invocation consumes context you don't recover.

The practical rule: every piece of information in a skill must earn its place. If you can remove it without losing output quality, remove it.

Measure tokens before and after each revision. It's not a technical detail: it's the difference between a skill that works for a full session and one that degrades after twenty minutes.

Skills for Companies: Not Just Personal Use

Skills aren't just a tool for solo workers.

At Castaldo Solutions we're building them for all clients joining our AI Adoption programs. It's not about delivering a tool: it's about transferring a way of working. The skill becomes a client asset, something they carry with them over time and that can evolve with their workflow.

AI isn't "used", it's configured. And skills are one of the most direct tools to do it.

Frequently Asked Questions About Claude Code Skills

What do I need to create a Claude Code skill? Just a text editor and Claude Code installed. The skill is a markdown file you save in ~/.claude/skills/ (global) or in .claude/skills/ inside the project (local). No extra installation, no server.

Do Claude Code skills work with other AI models? Skills in Claude Code format are specific to Claude. But the concept has been adopted by other tools: OpenAI introduced similar structures in ChatGPT and Codex CLI, mirroring the Anthropic format.

How much context does a skill consume? Depends on file size. A well-built skill weighs 500-2,000 tokens. Poorly optimized skills can exceed 5,000 tokens per invocation, accelerating context rot even in the first hours.

Can I share or install skills created by others? Yes. Skills can be distributed as installable .skill files, just like packages. Castaldo Solutions distributes them to clients in AI Adoption programs as assets configured to their specific workflow.

What's the difference between a skill and a CLAUDE.md? The CLAUDE.md file provides persistent project context to Claude in every conversation. A skill is an active command: invoked explicitly with /skill-name and contains operational instructions for a specific output. The two tools complement each other.

Where to Start: The Advice

If I had to give you one piece of advice: open the skill-creator and describe what you do every day.

You don't need a detailed plan, you don't need to understand everything first. Start with an activity you do often and build your first skill around that. The building process will teach you more than any guide.

Want to understand if your company is ready to adopt these tools structurally? Start with a conversation with us.

Book a free pre-assessment