Writing your first Claude Skill takes 25 minutes if you know the structure. I’ve shipped 638 skills indexed in the public bank on 500k.io, plus another 50 or so private ones for the agency factory. The pattern below is the exact one I use for a new skill on a Tuesday morning. No engineering background required. If you can write a clear how-to document, you can write a Claude Skill.

If you want the strategic backdrop on why skills matter, read Why Claude Skills Are the Next App Store first. This article is the hands-on tutorial.

What you actually need before starting

Three prerequisites. Skip any of them and you’ll waste an hour.

  1. Claude Code installed and working. If you haven’t done this yet, see Claude Code first 30 days first.
  2. A specific repeatable workflow you do at least once a week. Not “research things.” Something concrete: “audit a blog post against my voice rules and score it 0-100” or “extract speaker quotes from a meeting transcript into Markdown bullets.”
  3. 15 minutes of focused writing time. Not 90. Skills are short by design.

That’s the entry bar. No engineering, no coding, no API setup. Just Markdown and clear thinking.

What is a Claude Skill, in one paragraph?

A Claude Skill is a packaged Markdown file (SKILL.md) plus optional supporting files inside a folder Claude Code can read. The skill encodes a specific reusable capability — a workflow, a methodology, a quality check, a content pattern. When you invoke the skill (or when Claude Code recognizes a relevant task), the agent reads the SKILL.md, internalizes the embedded instructions, and executes against your local context.

Same Claude model. Different injected context. That’s the whole magic.

The 5-step process

This is the workflow I run for every new skill. 25 minutes total.

Step 1 — Pick the workflow (5 minutes)

The hardest step. Most founders pick workflows that are too generic and end up with useless skills. The filter I use:

  • Specific task, not category. “SEO audit” is a category. “Run a 12-point GEO audit on a single URL and output a 0-100 score” is a task.
  • Repeatable across instances. You’ll use it on 5+ different inputs over time.
  • Defined output. You know exactly what “done” looks like.
  • Encodes expertise. Generic LLM behavior won’t suffice — the skill adds something the base model wouldn’t do unprompted.

Examples of workflows that pass the filter:

  • “Audit a Claude Code project for missing CLAUDE.md sections”
  • “Convert a meeting transcript into 5-7 quotable speaker insights”
  • “Score a blog post draft against the 500k.io voice bible (0-100)”
  • “Generate a TCPA-compliant landing page for US lead-gen”
  • “Extract pricing tiers from a competitor’s pricing page into a comparison table”

Examples that fail the filter (too generic):

  • “Research things”
  • “Write a blog post”
  • “Help with marketing”
  • “Improve my code”

If your workflow fits in one specific sentence with concrete output, you’re ready for step 2.

Step 2 — Scaffold the folder (2 minutes)

Skills are folders, not files. Inside Claude Code project root:

mkdir -p .claude/skills/your-skill-name
cd .claude/skills/your-skill-name
touch SKILL.md

Or for a global skill (available across all your Claude Code projects):

mkdir -p ~/.claude/skills/your-skill-name
cd ~/.claude/skills/your-skill-name
touch SKILL.md

That’s it. The folder is the skill. SKILL.md is the brief. Optional: add templates/, scripts/, references/ subdirectories if your skill needs supporting files.

Naming convention: kebab-case, descriptive, narrow. voice-bible-scorer not scorer. tcpa-compliance-audit not compliance.

Step 3 — Write the YAML frontmatter (3 minutes)

The frontmatter tells Claude Code what the skill is and when to invoke it.

---
name: voice-bible-scorer
description: Audits a blog post draft against the 500k.io voice bible and outputs a 0-100 score with specific revision recommendations.
trigger:
  - "score this article"
  - "voice check"
  - "audit against voice bible"
inputs:
  - draft_path: path to the .mdx file to audit
outputs:
  - score: 0-100
  - violations: list of specific banned-phrase matches
  - recommendations: 3-5 prioritized revisions
---

Required fields:

  • name — kebab-case identifier
  • description — 1-2 sentences. This is what Claude Code reads to decide if the skill is relevant.

Recommended fields:

  • trigger — natural-language phrases that should invoke this skill
  • inputs — what the skill expects to receive
  • outputs — what the skill produces

The description field is the most important. Claude Code uses it for skill selection. If the description is vague, the skill won’t get invoked. Be specific.

Step 4 — Write the body (10 minutes)

The body is where the methodology lives. I use a 5-section template.

## Purpose

[2-3 sentences. What this skill does and why it exists.]

## Inputs

[List of what the skill expects. File paths, URLs, raw text, etc.]

## Process

[Step-by-step instructions. Numbered. Concrete.]

1. Read the input file
2. Check for [specific pattern]
3. Apply [methodology]
4. Generate [output format]

## Output format

[Exactly what the skill produces. Use a code block if the output has structure.]

```json
{
  "score": 87,
  "violations": ["delve into", "leverage"],
  "recommendations": ["..."]
}

Examples

[1-3 concrete examples of input → output.]

Example 1

Input: [sample article path] Output: [sample scorecard]


The Process section is where the methodology gets encoded. This is the part nobody else can copy easily — it's your expertise. Spend the most time here.

### Step 5 — Test against three real tasks (5 minutes)

The validation step most skill authors skip. Don't.

Run the skill against three real inputs in a fresh Claude Code session:

```bash
claude
> Use the voice-bible-scorer skill on /path/to/draft-article.mdx

Validation gates:

  • Did Claude Code recognize the skill from natural language?
  • Did the output match the format you specified?
  • Did the methodology produce useful results?

If 2 of 3 tasks succeed cleanly, ship the skill. If 1 of 3 or fewer, iterate the Process section before promoting.

A complete worked example

Here’s a real skill from my private bank, lightly edited. It scores founder-economics articles against the 500k.io voice bible.

File: .claude/skills/voice-bible-scorer/SKILL.md

---
name: voice-bible-scorer
description: Audits a blog post draft against the 500k.io voice bible and outputs a 0-100 score with specific revision recommendations. Use when reviewing any draft before publish.
trigger:
  - "score this article"
  - "voice check"
  - "audit against voice bible"
inputs:
  - draft_path: path to the .mdx or .md file to audit
outputs:
  - score: integer 0-100
  - violations: list of banned-phrase matches with line numbers
  - recommendations: 3-5 prioritized revisions
---

## Purpose

Score founder-economics article drafts against the 500k.io voice
bible. Catches AI-tone words, vague claims, missing structure, and
flags the highest-leverage revisions before publish.

## Inputs

A path to a single .mdx or .md file. The file should be a draft
article in the 500k.io content/blog/ structure.

## Process

1. Read the file at draft_path.
2. Run banned-phrase grep against the voice bible blocklist:
   - "delve into", "leverage", "robust", "comprehensive"
   - "navigate the landscape", "ever-evolving", "in the realm of"
   - "in conclusion", "to summarize", "as we've explored"
   - "moreover", "furthermore", "indeed"
   For each match, record the line number and surrounding sentence.
3. Check structural gates:
   - TLDR box present at top? (-10 if missing)
   - FAQ section with 4+ Q&A? (-15 if missing)
   - At least 1 table? (-5 if missing)
   - Specific numbers in body (count at least 3)? (-10 if under 3)
   - 6+ internal links to /journal/* or pages? (-10 if under 6)
   - 3+ external citations with footnotes? (-10 if under 3)
4. Calculate score: 100 - sum(deductions).
5. Generate 3-5 prioritized recommendations from the highest-impact
   issues found.

## Output format

```json
{
  "score": 87,
  "violations": [
    {
      "phrase": "leverage",
      "line": 42,
      "sentence": "I leverage Claude Code to..."
    }
  ],
  "structural_issues": [
    "Only 4 internal links (need 6)",
    "FAQ has 3 Q&A (need 4+)"
  ],
  "recommendations": [
    "Replace 'leverage' on line 42 with 'use' or 'run with'",
    "Add 2 more internal links — candidates: /journal/honest-math-500k-solo-saas-18-months, /stack",
    "Expand FAQ to 4+ questions"
  ]
}

Examples

Example 1

Input: src/content/blog/draft-article.mdx
Output: { "score": 87, "violations": [...], ... }

That’s a complete skill. 80 lines. Took me about 22 minutes to write the first version. Now it runs every time I draft an article — saves me 15-20 minutes of manual voice-checking per article.

Five common mistakes (and the fixes)

I’ve watched founders ship bad skills and abandon the format. The pattern is repeatable.

Mistake 1: Description too vague

Bad: description: helps with content Good: description: Audits a blog post draft against the 500k.io voice bible and outputs a 0-100 score with specific revisions.

The description is the matchmaker. If it’s vague, Claude Code can’t tell when to invoke the skill.

Mistake 2: No examples

Skills without concrete input → output examples are 30% less likely to produce useful results, in my own anecdotal experience. Examples show Claude Code what “good” looks like. Add at least one.

Mistake 3: Generic process

“Analyze the input and produce a report” is not a process. “Run banned-phrase grep against blocklist X, check structural gates Y, calculate score Z” is. Specificity is the moat.

Mistake 4: Missing trigger phrases

Without trigger phrases, the skill only runs when explicitly invoked by name. With good trigger phrases, Claude Code can route natural-language requests to the right skill. Add 2-4 phrases per skill.

Mistake 5: Promoting before testing

Don’t put a skill in ~/.claude/skills/ (global) until you’ve tested it on 3+ real tasks in .claude/skills/ (project-local). Bad global skills pollute every project you touch.

Skill scope: project-local vs global

Two options for skill placement:

LocationScopeBest for
.claude/skills/Project-localVertical-specific, business-rule-encoded skills
~/.claude/skills/Global (all projects)Generic productivity, format conversions, audits

I run a hybrid:

  • 12 global skills (voice-bible-scorer, schema-validator, footnote-formatter, …)
  • 25-40 project-local skills per active project (TCPA-audit for upgradematch, content-cluster-router for 500k.io, …)

The discipline: nothing goes global until it’s been tested in 2+ projects. Premature globalization is the most common skill bloat I see.

What “good” looks like — quality gates

Before I promote a skill from draft to active use, it has to pass these gates:

  1. Description is specific — a stranger reading it knows exactly what the skill does
  2. Process is numbered and concrete — not “analyze,” but specific steps
  3. Output format is shown — code block with example structure
  4. At least 1 worked example — input and output side by side
  5. Tested on 3 real tasks — 2 of 3 must produce useful output
  6. Length 150-400 lines — under = too generic, over = padded
  7. Trigger phrases set — 2-4 natural-language invocations

A skill that passes 6 of 7 gates ships. Below that, iterate before use.

What I’d build first if starting today

If you’re new to Claude Skills and want to ship 5 useful ones in your first week, here’s the order I’d take:

  1. Voice / style auditor for your written content (catches AI-tone words)
  2. Footnote / citation formatter for converting research links to inline footnotes
  3. Schema validator for any structured data you publish (FAQ, Article)
  4. Internal-link suggester that reads an article and proposes 3-5 contextual links to existing content
  5. Daily summary generator that reads a folder of notes and produces a digest

Each is 25-40 minutes to write. Each saves 15-30 minutes per use. Break-even is 2 uses. After a month, you’ve saved 5-10 hours.

“The first Claude Skill I shipped saved me 3 hours in its first week. The second saved 5. By skill #20 the cumulative time savings were measured in days per month, not hours per week. The barrier is the first 25 minutes — write that first SKILL.md and the pattern unlocks.” — Maxime Le Morillon, building 500k.io in public

FAQ

Do I need to be a developer to write a Claude Skill?

No. The skill itself is a Markdown file with frontmatter. If you can write a clear how-to document, you can write a Claude Skill. The “engineering” is in supporting scripts — and most skills don’t need them.

Where do Claude Skills live?

In .claude/skills/ inside your Claude Code project, or ~/.claude/skills/ for global access. Each skill is a folder containing SKILL.md plus optional supporting files.

How is a Claude Skill different from a subagent?

Subagents are specialist personas Claude calls by name. Skills are reusable workflows or capabilities Claude invokes when relevant. Personas vs functions. Both useful.

How long should a SKILL.md file be?

150-400 lines for most skills. Mine average 280 lines. Under 100 lines often means too generic. Over 500 means padded.

Can I use the same skill across multiple projects?

Yes. Drop the skill folder in ~/.claude/skills/ for global access. Or keep it project-local if it has project-specific context. I run a hybrid.

What’s the most common Claude Skill mistake?

Writing skills that are too generic. “Write a blog post” is useless. “Write a 3000-word founder-economics article in Maxime’s voice with TLDR + FAQ + 6 internal links + 3 external citations” is useful. Specificity is the moat.

Going further

FAQ

Do I need to be a developer to write a Claude Skill?

No. The skill itself is a Markdown file with frontmatter. If you can write a clear how-to document, you can write a Claude Skill. The 'engineering' is in the supporting scripts — and most skills don't need them.

Where do Claude Skills live?

In .claude/skills/ inside your Claude Code project, or in a global ~/.claude/skills/ directory for cross-project access. Each skill is a folder containing SKILL.md plus optional supporting files (templates, scripts, reference data).

How is a Claude Skill different from a subagent?

Subagents (.claude/agents/) are specialist personas Claude calls by name — like a researcher, an editor, a reviewer. Skills (.claude/skills/) are reusable workflows or capabilities Claude invokes when relevant. Personas vs functions. Both useful, both stack.

How long should a SKILL.md file be?

150-400 lines for most skills. Longer is fine if the skill encodes deep methodology. Shorter than 100 lines often means the skill is too generic to be useful. Mine on 500k.io average 280 lines.

Can I use the same skill across multiple projects?

Yes. Drop the skill folder in ~/.claude/skills/ for global access from any Claude Code project. Or keep it project-local in .claude/skills/ if it has project-specific context. I run a hybrid — generic skills global, vertical-specific skills local.

What's the most common Claude Skill mistake?

Writing skills that are too generic. 'Write a blog post' is a useless skill. 'Write a 3000-word founder-economics article in Maxime's voice with TLDR + FAQ + 6 internal links + 3 external citations' is a useful skill. Specificity is the moat.