How to Write SKILL.md Files in Claude for Non-Coding Work (With a Real Test)
A practical breakdown of the 4 blocks inside a SKILL.md file that get clean client and business work in one turn. If you have hit Claude's 5-hour session limit halfway through an afternoon of ordinary work, there is a
A practical breakdown of the 4 blocks inside a SKILL.md file that get clean client and business work in one turn.
If you have hit Claude's 5-hour session limit halfway through an afternoon of ordinary work, there is a good chance the problem was not the size of your project. It was the number of messages it took to get a usable draft.
Watch how most of us use Claude when we are in a hurry. We paste rough notes from a client call and ask for a proposal. Claude comes back with 900 words of polite corporate filler and a single flat price. So we send a second message asking for three pricing tiers. Then a third message asking it to sound less stiff. Then a fifth message reminding it to list what is out of scope so we do not get stuck doing free revisions.
By message ten, every single correction has been re-read into the context window on every turn. You spent twenty minutes babysitting a chat box and burned five times more session tokens than the job actually needed.
Developers solved this months ago for code by moving repeatable instructions into small SKILL.md files. Yet almost every public SKILL.md catalog is still packed with React, SQL, and Docker tools, while the everyday work that eats up most people's week (scoping client proposals, turning messy call notes into action lists, stress-testing a launch plan) gets left in scratchpad prompts.
Over the past few weeks I moved my own non-coding business tasks into portable SKILL.md files that work across Claude Code, Claude Cowork, and plain Claude Projects. Here is how the file format actually works under the hood, the four blocks every reliable skill needs, and an unedited test run from a 24-word prompt.
If you would rather have the files than build them, I keep mine here: https://livefree1.gumroad.com/l/chpvtb
How Claude actually reads a SKILL.md file
A skill is just a folder with a lowercase hyphenated name containing a plain Markdown file named SKILL.md:
skills/
client-proposal-scope-builder/
SKILL.md
meeting-transcript-to-action/
SKILL.md
premortem-blindspot-finder/
SKILL.md
What makes SKILL.md smarter than pasting a giant mega-prompt into every chat is how Claude loads it.
At the start of a session in Claude Code or Claude Cowork, Claude does not read the entire body of every skill you have installed. It only scans the short YAML header (name and description) at the top of each file. When your request matches one of those descriptions, Claude pulls that single SKILL.md file into context, follows its rules, and leaves the rest of your skills untouched.
If you use standard Claude on the web or phone instead of the terminal, the exact same SKILL.md file drops straight into the Project Knowledge panel inside a Claude Project (or can be pasted into any chat window when you need it).
The 4 blocks that make a SKILL.md file work on the first try
Early on, half of the skill files I wrote still gave me mushy, generic answers. Fixing them came down to stripping out vague wishes ("be clear and persuasive") and building every SKILL.md out of four specific parts.
1. The YAML trigger header
The top of every SKILL.md starts and ends with three dashes (---) and holds two required fields: name and description.
Because Claude decides whether to load your skill based purely on those two lines, write the description around two things: what the output looks like, and the exact moment in your workday when Claude should use it.
Bad description:
Helps write better proposals for clients.
Working description:
Turns rough discovery notes into a clear 1-to-2 page proposal with 3 options and scope protection. Use right after a client call or inquiry to send a clean, fast proposal while momentum is high.
2. A short intake guard
When you hand an AI model incomplete notes, its default instinct is to guess the missing numbers so it looks helpful. In real client or strategy work, made-up timelines and imaginary prices are worse than useless.
Right under the header, add a 3-line intake check telling Claude which two or three facts must be present before it starts writing. If you forgot to mention your base price or target timeline, Claude stops and asks you one short question instead of inventing a number.
3. A numbered execution sequence
Long paragraphs of instructions invite the model to cherry-pick whichever rules feel easiest. A short numbered sequence forces a consistent build order every single time.
For example, in my proposal skill, the sequence never changes:
- Open with the client's situation and goal in plain words so they see you actually listened on the call.
- Present three priced options (
1xEssential,1.5xRecommended Complete, and2.2xFast-Track / Done-for-You) so the client compares how to work with you rather than whether to hire you. - Add an explicit Included vs. Out-of-Scope section (revision cap, hosting, third-party tools) to stop unpaid scope creep before it starts.
- Close with milestone dates, deposit terms, and a one-line reply to accept, followed by a calm cover email.
4. A falsifiable quality gate
Telling Claude to "sound human" fails because you cannot point to a sentence and prove objectively whether the rule was followed. Good rules are falsifiable: you can check pass or fail in five seconds by eye.
At the bottom of every SKILL.md, I include three hard checks:
- Ban specific dead-giveaway filler words (
delve,tapestry,landscape,game-changer,seamless,leverage,crucial,foster,moreover). - Ban the classic AI contrast tic ("It is not just X, it is Y").
- Require concrete numbers, dates, or named deliverables in every bullet instead of general advice.
A complete copy-pasteable SKILL.md file
Here is the full plain-text SKILL.md file for the client proposal workflow so you can inspect or copy it directly:
---
name: client-proposal-scope-builder
description: "Turns rough discovery notes into a clear 1-to-2 page proposal with 3 options and scope protection. Use right after a client call or inquiry to send a clean, fast proposal while momentum is high."
---
CLIENT PROPOSAL & SCOPE BUILDER
WHEN TO USE THIS SKILL
Paste your messy call notes, client email, or project idea to produce a ready-to-send proposal in 5 minutes.
STEP 1: FAST INTAKE CHECK
Ask for (if not already in notes): (1) what the client actually wants achieved, (2) rough timeline, and (3) your target price for the standard option.
STEP 2: EXECUTION PROTOCOL
Write in plain, direct human English (grade 7-9 clarity, concrete numbers, zero corporate cliches). Execute in order:
1. Open with SITUATION & GOAL in the client's own words to prove you listened before talking about deliverables.
2. Present 3 CLEAN OPTIONS (Option 1: Essential / Core fix at 1x price, Option 2: Recommended Complete Outcome at ~1.5x price, Option 3: Fast-Track / Full Done-For-You at ~2.2x price) so the client compares how to work with you rather than whether to hire you.
3. Write explicit SCOPE BOUNDARIES ('What Is Included vs. Out of Scope') including revision cap, turnaround window, and what counts as an add-on to prevent unpaid scope creep.
4. Close with TIMELINE, PAYMENT TERMS, AND 1-STEP ACCEPTANCE so they can say yes today.
STEP 3: REQUIRED OUTPUT FORMAT
Deliver the result cleanly using this exact structure:
1) READY-TO-SEND PROPOSAL DOCUMENT and 2) SHORT COVER EMAIL to send alongside the proposal.
QUALITY GATE (VERIFY BEFORE RETURNING)
- Zero dead-giveaway AI words (delve, tapestry, landscape, game-changer, seamless, leverage, crucial, foster, moreover).
- Zero "Not just X, it's Y" phrasing or empty cheerleading.
- Every recommendation uses concrete actions, real numbers, or clear dates rather than vague advice.
Testing it on a real 24-word note
To test how little input a structured SKILL.md file actually needs, I ran that skill on a single 24-word note:
Client: Karim owns a boutique cafe, wants a 3-page website with menu + WhatsApp table booking ready in 2 weeks. My standard price is $800.
In one turn (about fifteen seconds, zero follow-up edits), here is what came back:
- Three distinct packages priced cleanly from the
$800anchor: Essential Website ($800) with 3 pages, mobile layout, WhatsApp click-to-chat button, and 2 revision rounds; Complete Cafe Website ($1,200, Recommended) adding categorized food photography, Google Maps, custom pre-filled WhatsApp message, and 3 revision rounds; and Premium Done-for-You ($1,760) adding priority scheduling, image optimization, Google Business Profile link setup, and a recorded handover walkthrough. - An automatic Out of Scope block protecting the builder from the exact traps cafe clients usually assume are free: live table-availability databases, online payment processing, food photography, domain and hosting renewals, and post-launch maintenance.
- A day-by-day 14-day schedule (
Days 1-2kickoff,Days 3-6structure,Days 7-10build,Days 11-12revisions,Days 13-14handover), a50% / 50%payment split, and a calm 6-sentence cover email with zero "I hope this email finds you well" filler.
How to install or adapt 3 open-source examples
If you want to test this setup without writing your first SKILL.md from a blank screen, I put three of my everyday non-coding business skills into a free MIT-licensed GitHub starter repository (client-proposal-scope-builder, meeting-transcript-to-action, and premortem-blindspot-finder):
https://github.com/joekurt120/claude-work-skills
If you use Claude Code, Cursor, Codex, or Windsurf, you can install all three in one command with the open skills CLI:
npx skills add joekurt120/claude-work-skills
And if you never touch a terminal, just open the skills/ folder on GitHub, grab whichever SKILL.md file matches a job you repeat every week, and drop it into a Claude Project. Swap my steps for the rules you normally find yourself typing on message four or five of a messy chat, and see how much quieter your sessions get.
Want the files instead of building them?
I keep the skill files I actually use, plus the context file and the writing rules file, in one pack here:
https://livefree1.gumroad.com/l/chpvtb
The launch checklist is free if you just want somewhere to start:
Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.