Build in Public: My first Claude Code Skill
I've become a Claude Code nerd. It's better that Claude Desktop and learning it is a journey to high quality AI coding agents which can build your software for you while you sleep.
This post is the start of my journey. I'm only a couple of weeks ahead of that now and I'm already building the new Dear Agency Founder website with a coding agent.
Setup
Ok here's the scary bit...
If you have a Pro plan then you have access to Claude Code.
You have to open the terminal and run a command. Ask Claude Desktop how to do it and then once Claude Code is running on the command line you basically ask it to do everything techy for you.
Less scary bit, get yourself a way to view all the files on your machine (including hidden folders, because that's where CC operates).
A code editor works, I use Cursor. Editors will have AI skills. Ignore these for now. Claude is doing the AI stuff.
Again, just ask Claude to help you set this up. And let's go!
Creating a Skill
There's loads to learn about the basics of Claude Code but I think skills are the quickest route to value. They're the thing that made it click for me. A skill is basically a set of instructions in markdown that tell Claude how to do a specific task, and once you've got one set up, you can reuse it over and over.
Claude can easily create its own skills, but do yourself a favour and build one by hand first. You'll understand the mechanics much better, and it honestly takes about 15 minutes.
Where Claude Code lives
Claude Code runs in your terminal. It's not a separate app with a window you click around in. You open your terminal, type claude, and it starts up right there in whatever folder you're in, with full access to your files.
That's important because unlike the Claude desktop app or the web interface, Claude Code works with your file system. It can read, create, and edit files directly. It's this file access that makes skills possible, because a skill is just a set of files that Claude reads when it starts up.
Global vs project skills
There are two places you can put skills:
Global skills are stored in ~/.claude/skills/ in your home directory. These are available no matter what project you're working in. Good for general-purpose skills you want everywhere.
Project skills are stored in .claude/skills/ inside a specific project folder. These only work when you're running Claude Code from that project. Good for project-specific workflows, and because they live in the project folder you can share them with your team.
Project skills are what I’m making in this article.
Project skills take priority over global skills with the same name, so you can override a global skill for a specific project if you need to.
For this guide we're going to use project skills.
Starting a project
To get going you need a project folder. You can create one yourself or just ask Claude Code to do it for you. Open your terminal, run claude, and tell it to create a folder and set up the project:
Create a new project folder called learn_cc and set up the .claude directory with a skills folder inside it. Navigate to that folder.
It'll create the .claude/ directory inside it, which is where your skills, commands, and project settings live.
You won't see the .claude folder in Finder by default because folders starting with a dot are hidden, but it's there, and it's where all the magic happens.
You will see it if you open that folder in your code editor.
Basic anatomy of a Skill
At its simplest, a skill has four parts:
Name is what Claude uses to identify the skill. It comes from the folder name and the name field in the skill file. This is also what shows up when you type /skills in Claude Code.
Description tells Claude when to use the skill. Claude reads all skill descriptions when it starts up and uses them to decide which skill is relevant to what you're asking. A good description is specific, like "Convert a newsletter into an article" rather than something vague like "help with content".
Instructions are the actual steps you want Claude to follow. This is the meat of the skill. You write these in plain markdown, and Claude follows them when the skill is triggered.
Supporting context is anything else Claude might need to do the job well. Templates, examples, reference files. These sit alongside the skill file in the same folder.
This is a basic setup. You can add much more, but these four things are all you need to get started.
Here's what a basic SKILL.md file looks like:
---
name: newsletter-to-article
description: Convert the newsletter into an article. Use when asked to convert to an article.
---
# Instructions here
The name and description sit between the --- markers at the top [this is called frontmatter]. The instructions go below.
I also use a template file to format the conversion. I could just include this template in the SKILL.md file if I wanted, but I want to show that your skill folder can be a collection of files.
File title: <title>-article.md #Replace <title> with name for the article in lowercase with hyphens for spaces
---
title: <title>
tags: # Replace with the generated list
- tag-1
- tag-2
---
<article body>
Then I copy in a markdown version of one of my Dear Agency Founder newsletters and we're ready to roll. Here's what the project folder looks like at this point:
learn_cc/
├── .claude/
│ └── skills/
│ └── newsletter-to-article/
│ ├── SKILL.md
│ └── template.md
└── 2026-01-17-the-three-seats-of-marketing.md
Running the skill
When Claude starts up it looks at all the skills it has registered. It only reads the name and description at first, then reads the full instructions when it decides a skill is relevant. For a new skill to be recognised you need to stop the current session and start a new one:
/exit
claude
Now type /skills to check it's been picked up.
Then just ask Claude to do the conversion:
Convert @[2026-01-17-the-three-seats-of-marketing.md](http://2026-01-17-the-three-seats-of-marketing.md) to an article
The @ will open an autocomplete for you to reference a file. Since this setup only has one file Claude would probably guess, but using @ means you can be explicit about which file you want it to work with.
And that's it. The result is my newsletter converted into an article, using the template and instructions from the skill.
I like it
Of course this could have been done using the Claude desktop app. In fact I think that's one of the great things about Claude Code. You could literally drag and drop the Skill and Template markdown files into any LLM and it would know what to do.
Having a hidden folder is a bit techy but everything else is completely human readable. There's no special syntax to learn, no config files to wrestle with. It's just markdown files in folders. And once you've built one skill, building the next one takes about two minutes.
A project set up, an intro to how skills work, and I've built one that actually does something useful.
Nice.