mohios
← Back to field notes

What Claude Skills Are and Why They Matter

It's just a markdown file. That's the point.

Danny Holtschke
Danny Holtschke·March 2026 · 6 min read · AI Systems
Series: 3 of 4
Meta-Prompting 101Claude ProjectsSkillsKnowledge Base

A Claude skill is a markdown file (.md) containing a structured prompt that you attach to a Claude Project in Anthropic's Claude AI. That's it. The name makes it sound more complicated than it is.

You attach it to a project. Claude reads it. And now it can do a specific thing — not by guessing, but by following the expert instructions you baked into the file.

If you've read the first two articles in this series, you already have the method (meta-prompting) and the environment (Claude Projects with Soul & Context). Now you need the tools.

Why “Just a Markdown File” Is Powerful

Think about what happens without a skill file.

You open Claude and say: “Help me think through this decision.” Claude gives you something. It's fine. It's generic. It asks surface-level questions. It gives balanced, hedged answers. It doesn't push back. It doesn't know how you like to think.

Now imagine you've written a 1,500-word file called intellectual-sparring-partner.md. Inside it, you've defined two modes — exploration and sparring. You've specified what each mode looks like. You've told it how to detect which mode you need based on your language. You've given it communication rules: “direct and concise, no throat-clearing, match my energy, ask questions before assuming.”

You attach that file to your project. Now when you say “help me think through this decision,” the AI doesn't guess. It reads the skill, detects your mode, and responds the way you've trained it to.

Same AI. Same chat interface. Completely different experience.

The skill file is the difference between a stranger and a colleague who knows how you work.

What's Inside a Claude Skill File

Every skill I build follows the same structure. This comes directly from the meta-prompting method:

  1. PurposeOne paragraph. What is this skill for? When should it be used?
  2. Expert InstructionsThe core. The method, framework, and how-to-do-it-well section. Built using one of the four options from Article 1.
  3. PhasesHow the skill operates: context gathering, execution, refinement. Some are conversational, others produce specific output.
  4. Output FormatWhat the result should look like. Constraints on length, style, structure.
  5. Quality RulesWhat to avoid. What standards to maintain. The guardrails that keep output from drifting.
  6. Version HistoryWhen it was created, updated, and what changed. Skills improve over time.

Here's what the header of one of my skill files looks like:

skill-file.md
# Intellectual Thinking Partner
Version: 2.0
Created: 2026-02-11
Last Updated: 2026-02-16
Option Used: A + B (own method + best practices)
Client Origin: Mohios (general use)
Generalisable: Yes

That metadata isn't decoration. “Option Used: A + B” tells me this was built from my own method plus AI-generated best practices. “Client Origin: Mohios (general use)” means it wasn't built for a specific client — it's reusable across projects. “Generalisable: Yes” means I can share it, adapt it, or give it to someone else.

My Claude Skill Library

I currently have about a dozen skills. Some are thinking tools. Some are production tools. Some are project-specific. Here are a few:

Thinking skills
intellectual-sparring-partner.md — Two modes: exploration (build on ideas, find patterns, ask genuine questions) and sparring (challenge assumptions, stress-test logic, grade the idea). Detects which mode you need based on your language.
first-principles-thinking-coach.md — Guided decomposition. State the problem, surface assumptions, break each one down, rebuild from fundamentals. Socratic method — it doesn't give answers, it helps you think.
Production skills
linkedin-post-writer.md — Full content engine. Audience psychology, post structure, five post types, voice and formatting rules, three variants per draft with a component buffet for remixing. Over 3,000 words.
copywriting-fundamentals.md — Shared rules for tone, archetypes, and LinkedIn mechanics. Loaded alongside profile-specific writers so the voice stays consistent.
System skills (from the GTM project)
icp-signal-extractor.md — Run on interview transcripts. Extracts company profile, team signals, ICP fit assessment.
pain-language-miner.md — Pulls verbatim customer quotes by theme and persona. The exact words matter for messaging.
hypothesis-generator.md — Creates testable GTM statements with confidence scores and kill criteria.
truth-updater.md — Updates the “Current Truth” document based on accumulated evidence. Versions the beliefs so you can see what changed and why.
Thinking
sparring-partner.md

Two modes: exploration (build on ideas) and sparring (challenge assumptions, stress-test logic).

+
PurposeDual-mode intellectual partner
Expert InstructionsMode detection, questioning depth, energy matching
PhasesDetect mode → Engage → Push back or build → Synthesise
OutputDirect responses, no hedging, Socratic when needed
Quality RulesNever agree to be agreeable, match the user's energy
Version Historyv2.0, Feb 2026
Thinking
first-principles.md

Guided decomposition: surface assumptions, break to fundamentals, rebuild from truth.

+
PurposeSocratic first-principles coach
Expert InstructionsAssumption surfacing, decomposition method
PhasesState problem → Surface assumptions → Decompose → Rebuild → Reality-check
OutputQuestions, not answers
Quality RulesNever skip the decomposition step
Version Historyv1.3, Mar 2026
Production
linkedin-writer.md

Full content engine: audience psychology, five post types, three variants per draft.

+
PurposeLinkedIn post writer with voice consistency
Expert InstructionsAudience psychology, post archetypes, formatting rules
PhasesBrief → Draft 3 variants → Component buffet → Refine
OutputThree complete posts + remix components
Quality RulesNo corporate speak, match profile voice exactly
Version Historyv3.1, Mar 2026
Production
copywriting-fundamentals.md

Shared rules for tone, archetypes, and platform mechanics across all writing.

System
icp-signal-extractor.md

Run on interview transcripts. Extracts company profile, team signals, ICP fit.

+
PurposeExtract ICP signals from interview transcripts
Expert InstructionsSignal taxonomy, fit scoring model
PhasesIngest transcript → Extract signals → Score fit → Flag gaps
OutputStructured signal report with confidence scores
Quality RulesUse verbatim quotes, never infer what wasn't said
Version Historyv1.0, Feb 2026
System
pain-language-miner.md

Pulls verbatim customer quotes by theme and persona. The exact words matter.

System
hypothesis-generator.md

Creates testable GTM statements with confidence scores and kill criteria.

System
truth-updater.md

Updates the "Current Truth" document based on accumulated evidence.

Skills + Projects: How They Connect

Here's how everything fits together:

Soul
Who you are. How you think. Stable.
Context
What's happening now. Fluid.
Identity & Situation
Project Instructions
Read Soul. Read Context. Ask, don't assume. Then respond.
The Glue
sparring-partner.md
first-principles.md
linkedin-writer.md
icp-extractor.md
truth-updater.md
Skills (.md files)
Claude reads all layers before every conversation

Soul tells the AI who you are. Context tells it what's happening. Project Instructions tell it how to behave. Skills tell it what it can do.

Every conversation inside a project has access to all of these layers simultaneously. When I say “challenge this,” Claude reads my Soul (knows I want sparring mode), reads my Context (knows what I'm working on), reads the sparring partner skill (knows how to challenge properly), and responds accordingly.

The layers don't compete. They complement. Soul sets the personality. Context sets the situation. Skills set the capability.

Building vs. Borrowing Skills

Some skills are deeply personal. My sparring partner skill was built from my own decision-making approach across years of consulting. Nobody else's version would work the same way for me.

Other skills are highly transferable. A first principles thinking coach, a copywriting fundamentals guide, an interview extraction prompt — these can be shared, adapted, and reused.

This is one of the things I do for clients. I sit with them, extract their expertise through conversation, and build skills that capture how they actually work. Their objection handling. Their pricing logic. Their voice. Packaged as .md files that any AI tool can use.

The meta-prompt guide from Article 1 is itself a skill — a reusable prompt for creating other prompts. Skills that create skills. That's where it starts to compound.

Building Your First Claude Skill

If you're building your first skill:

Pick something you do repeatedly and explain well. Write out how you do it — the steps, the rules, the examples, the things to avoid. Structure it using the template above. Save it as a .md file. Attach it to your Claude Project.

Start with one. Use it for a week. Notice what's missing. Update it. Version it. The first version is never the best version — but it's infinitely better than no version.

Your skill library grows naturally from your work. Every project, every client, every repeated task is a candidate. Over time, you stop building from scratch and start assembling from parts.

That's when AI stops feeling like a tool and starts feeling like a team.

Frequently Asked Questions

What is a Claude skill?

A Claude skill is a markdown (.md) file with a structured prompt inside it. You attach it to a Claude Project, and it gives the AI a specific capability — like writing in your voice, running a thinking framework, or extracting data from transcripts.

What goes inside a Claude skill file?

Every skill file follows the same structure: Purpose (what the skill is for), Expert Instructions (the method and framework), Phases (context gathering, execution, refinement), Output Format (what the result looks like), Quality Rules (guardrails), and Version History.

How do Claude skills connect to Claude Projects?

Skills are one layer of a Claude Project setup. Soul tells the AI who you are, Context tells it what’s happening, Project Instructions tell it how to behave, and Skills tell it what it can do. Every conversation inside a project has access to all layers simultaneously.

How do I build my first Claude skill?

Pick something you do repeatedly and explain well. Write out the steps, rules, examples, and things to avoid. Structure it using the six-part template (Purpose, Expert Instructions, Phases, Output Format, Quality Rules, Version History). Save it as a .md file and attach it to your Claude Project.

Series: 3 of 4
Meta-Prompting 101Claude ProjectsSkillsKnowledge Base
Danny Holtschke
Danny Holtschke

Danny builds AI systems for NZ businesses that sound like the people who run them. Based in Auckland, working at the intersection of conversation and code.

LinkedInmohios.com

Want skills built from your expertise?

I sit with you, extract how you actually work, and package it as .md files that make AI sound like you — not the internet's average.

Start building →