Claude Code skills: custom reusable workflows explained

A Claude Code skill is a markdown file that packages a reusable set of instructions. When the agent reads it, it knows how to do a specific job.

The concept is simple. The leverage is large.

Why skills exist

Claude Code’s default instructions are general-purpose. It knows how to code, how to read files, how to run commands. But it doesn’t know:

• Which API you use for email and what the endpoint is
• Your code style preferences
• The specific workflow your business follows for a recurring task
• What credentials to use for which services

You could explain all of this in every conversation. Or you could write a skill once and load it when needed.

Two flavors: CLAUDE.md and skill files

Claude Code supports two places for custom instructions:

CLAUDE.md (Always-loaded context)

A file at the root of your project (or globally at ~/.claude/CLAUDE.md) that Claude Code reads automatically at the start of every session.

Use it for:

• Project-specific context (“This is a Next.js project using TypeScript and Tailwind”)
• Standing instructions (“Always run tests before committing”)
• Important conventions (“API routes live in /app/api/, not /pages/api/“)

# My Project, Claude Context

## Stack
- Next.js 14 (App Router)
- TypeScript
- Tailwind CSS
- Prisma ORM with PostgreSQL

## Conventions
- Components in /components, pages in /app
- Use server components by default, client components only when needed
- All database queries go through /lib/db.ts
- Run `npm test` before marking any task complete

## Credentials
API keys are in .env.local. Never commit this file.

Skill Files (On-demand capabilities)

Markdown files that you ask the agent to read for specific tasks. Stored in ~/.agents/skills/ or any path you reference.

Use them for:

• API integrations with specific credentials and endpoints
• Complex workflows with multiple steps
• Voice/style guides
• Domain knowledge the agent needs for a specific job

Building a skill

Template:

---
name: skill-name
description: One-line description of what this skill does
---

# Skill Name

## Purpose
What this skill is for in one paragraph.

## Authentication
How to authenticate with any services this skill uses.
[Exact commands to load credentials]

## Workflow
Step-by-step instructions for the task.

1. Do X
2. Then do Y
3. Save output to Z

## API Reference
[Specific endpoints, parameters, expected responses]

## Rules
- What to always do
- What to never do
- Edge cases and how to handle them

## Output Format
What the final output should look like.

Real skill examples

SEO Keyword Research Skill

---
name: seo-research
description: Keyword research via Ahrefs API
---

# SEO Research Skill

## Authentication
```bash
source ~/.agents/.env
AHREFS_KEY=$(echo $AHREFS_API_KEY)

Keyword Overview

Pull volume and difficulty for a list of keywords:

curl -s -H "Authorization: Bearer $AHREFS_KEY" \
  "https://api.ahrefs.com/v3/keywords-explorer/overview?keywords=KEYWORD1,KEYWORD2&select=keyword,volume,difficulty&country=us&date=$(date +%Y-%m-%d)"

Rules

• Only target keywords with KD < 30 for a new site (DR 0-10)
• Volume threshold: >100/month to be worth targeting
• Group keywords by topic cluster, not just alphabetically

Output Format

Return a markdown table with: keyword, volume, KD, content cluster, recommended article title.

### Writing Voice Skill

```markdown
---
name: writing-voice
description: Cat's voice for founder.codes content
---

# Writing Voice

## Core Style
Write like explaining something to a smart friend at a coffee shop.
Short sentences. Contractions. Specific examples.

## Never Use
- Em dashes (, )
- "Additionally", "furthermore", "moreover"
- "Leverage", "utilize", "showcase", "underscore"
- "In today's [anything]..."
- Lists of exactly three things for dramatic effect

## Always Do
- Lead with the specific outcome or failure, not context
- Give real numbers when available ($400/mo, not "significant savings")
- Show the work: actual configs, real output, file paths
- End with a specific next action, not a summary

## Format
- H2s for major sections, H3s sparingly
- Short paragraphs (2-3 sentences)
- No bullet lists with more than 5 items
- No bold on every other word

Loading skills at runtime

Tell Claude Code to read a skill before a task:

Read your SEO research skill at ~/.agents/skills/seo-research/SKILL.md, then find keyword opportunities for "OpenClaw tutorials"

Or reference it in your CLAUDE.md:

## Available Skills
When doing SEO work: read ~/.agents/skills/seo-research/SKILL.md
When writing content: read ~/.agents/skills/writing-voice/SKILL.md
When working with email: read ~/.agents/skills/sendfox/SKILL.md

Then you can say “do SEO research on X using your skill” and it knows where to find it.

The skill library worth building

Start here, these skills compound quickly:

1. Writing voice, your content style
2. Your primary API integration, whatever you call most (email platform, analytics, etc.)
3. Content review checklist, what makes something ready to publish
4. Output formats, how you want reports and summaries formatted

Each skill takes 30-60 minutes to write the first time and saves that time on every future use.

---

Related: Claude Code Tutorial | OpenClaw Setup | The .agents Folder