Structures work requests to AI (role, context, task, format, example) so the output is reliable and review-ready.
What it does
You ask for something, it comes back generic. You rephrase it, it comes back generic in a different way. After the fourth try you give up and write it yourself, which is what you were trying to avoid.
The problem is usually that the request is one long sentence, so when the answer is wrong there is nothing to fix. With this skill active, the assistant rebuilds your request as five labelled parts: who it should act as, the handful of facts that actually change the answer, the one job, the exact shape you want back, and one example of good. Then a bad result stops being a mystery. Too long is the format part. Wrong facts is the context part. Odd tone is the role part. You edit that one part and run it again.
You end up with a request that works, and a saved version where you swap this week's facts and reuse the rest.
You end up with a five-part request that works twice in a row, saved with a note on what to swap next time.
When to reach for it
Use it when the output matters or repeats: the weekly update, the client email, the summary someone else will act on, anything you have already rephrased three times.
Skip it for casual questions and one-off curiosity, where building structure costs more than just asking. It is also not a fix for missing information - if you have not decided who the output is for, no amount of structure will save it.
---
name: prompting-for-work
description: Rebuilds a vague work request into five labelled parts - role, context, task, format, example - so the output comes back usable, and teaches the user to repair a bad result by editing one part instead of rewriting the whole thing. Use when someone keeps getting generic or wrong output and is rephrasing the same request over and over.
---
# Prompting for Work
You turn "it gave me something generic again" into output someone can actually send. The fix is almost never a better sentence. It is a request built out of parts, where a bad result points at the part that is wrong.
## Workflow
1. **Hear the real task.** Get it in the user's own words, and find out who the output is for.
2. **Write the one-line job:** produce X for Y so they can Z. If a slot is empty, ask.
3. **Build the five parts.** Role, context, task, format, example.
4. **Run it once and judge only two things:** is anything wrong, and is anything missing.
5. **Repair the part that failed.** Never start over.
6. **Run it a second time** on a different set of facts.
7. **Save it as a template** once it works twice, with a note on what to swap.
```text
Prompting checklist
[ ] Task stated as: produce X for Y so they can Z
[ ] Audience named - not "for work", an actual reader
[ ] Context holds only facts that change the answer
[ ] Format names shape, length and tone in countable terms
[ ] Example included if one exists anywhere
[ ] First run judged on wrong / missing only
[ ] Repair applied to one part, not the whole prompt
[ ] Second run on different facts before calling it a template
[ ] Saved with a swap note
```
## Step 2: the one-line job
Before any prompt gets written, fill this in:
> Produce **[X, the thing]** for **[Y, the person who reads it]** so they can **[Z, what they do next]**.
An empty slot is a question, not a guess. The Z slot is the one people skip and the one that changes the output most, because "so my VP can forward it to her boss unchanged" and "so I remember what I did" produce two different documents from identical facts.
If the user cannot name Y, stop and ask. Audience is the single largest lever in the whole request, and every part below depends on it.
## Step 3: the five parts
Each part answers a different question, and each failure mode maps to exactly one part. That mapping is the reason for the structure.
### Role
Who the assistant should be while doing this. One line, specific enough to change vocabulary and priorities.
- Weak: "You are a helpful assistant."
- Works: "You are an experienced HR manager who has written a hundred of these and knows what a tribunal would make of the wording."
Skip the role when the task has no professional stance to take, like summarising a page. Do not invent expertise the task does not need.
### Context
The three to six facts that change the answer. Not background. Not everything you know.
The test for every line: **if this were different, would the output be different?** If no, cut it.
- Keep: the deadline slipped by two weeks, the client already complained once, the budget is fixed.
- Cut: the project history, the org chart, how you feel about it.
Long context does not fail more gently than short context. It fails differently, by burying the three facts that mattered in twenty that did not.
### Task
The one-line job from step 2, verbatim. One task per prompt. "And while you're at it" is a second prompt.
### Format
The shape of the output, in terms you could count or check.
- Weak: "Keep it short and professional."
- Works: "Subject line, then three sections labelled Done, Risk, Next. Under 120 words total. No exclamation marks. No closing paragraph."
Say what you do not want if there is a habit you keep having to delete. "No bullet points" and "do not restate the question" are legitimate format instructions.
### Example
One sample of what good looks like beats any three adjectives. A rough one is fine. Last month's version is ideal.
If none exists, give a fragment: the first two lines the way they should read, or a single bullet in the right shape. Failing that, name a thing the user has seen: "like a doctor's discharge note, not like a press release."
## Step 4: judging the first run
Only two questions. Answer them in this order, and resist the urge to react to tone before checking facts.
1. **Is anything wrong?** A fact, a number, a name, an implied claim that is not true.
2. **Is anything missing?** Something the reader needs that is absent.
Everything else, including "I don't love it", is a format or role problem and gets handled in the repair step. Do not accept a result because it reads well. Read it as the person it is going to.
## Step 5: repairing one part
This is the habit worth teaching, and the one people never arrive with.
| What went wrong | Which part to edit |
|---|---|
| Facts wrong or invented | Context - the fact was missing or unclear |
| Too long, too short, wrong shape | Format |
| Right facts, wrong emphasis | Task - the Z slot is probably wrong |
| Tone off, too casual or too corporate | Role, then Example |
| Reads like a template | Example - add one, or a better one |
| Confidently wrong about something | Context - add the correction as a stated fact |
| Answered a slightly different question | Task - it is doing two jobs, split it |
Edit that one part, rerun, compare. Rewriting the whole prompt after a bad result destroys the information you just bought, because you can no longer tell which change helped.
## Step 6 and 7: proving it and saving it
One good result can be luck. Run the prompt again with a different week's facts before you call it a template. If the second run needs hand-editing in the same place, that place is a missing format instruction.
Then save it with a swap note:
> **Swap each time:** the Context block. **Leave alone:** role, format, example. **If the output drifts:** the example is stale, replace it with last week's approved version.
## Example
**Weak request:** "Write a status update about the project."
**One-line job:** produce a weekly status update for my VP so she can forward it to her boss unchanged.
**Built prompt:**
```text
Role: You are a project lead writing upward to an executive who has ten of these to read.
Context:
- Migration is two weeks late; vendor API access slipped, not our build.
- New date is 14 March, and I am confident in it.
- No budget impact.
- Her boss has asked about this project twice.
Task: Write my weekly status update for my VP so she can forward it to her boss unchanged.
Format: Subject line, then three short sections labelled Done, Risk, Next.
Under 120 words. No exclamation marks. No closing paragraph.
Example of the tone I want:
"Subject: Migration - two weeks late, new date 14 March
Done: Read replicas complete and verified."
```
**First run came back at 190 words with a closing paragraph.** Format problem, not a bad model. Add "Hard limit 120 words. Do not write a closing paragraph." Rerun. It lands at 112 words.
**Notice what was not done:** the prompt was not rewritten, the role was not touched, and the context was not expanded. One part failed, one part got edited.
## Rules
- One prompt, one task. A second request in the same prompt degrades both.
- Never pad context with background that would not change the answer.
- If the user cannot say who the output is for, stop and ask. Do not guess an audience.
- Keep the user's own vocabulary in the prompt. Their words carry intent that your paraphrase loses.
- Examples beat adjectives. Ask for one before adding a third describing word.
- Do not add "be creative" or "think step by step" as decoration. Add an instruction only when you can say what it changes.
- Never let a prompt ask for facts the user has not supplied. That is an invitation to invent them.
## Edge cases
- **The user does not know what good looks like.** Ask for a bad example instead. "Show me one you rejected" defines the target from the other side, and people find it easier.
- **The task is genuinely creative** and a format spec would strangle it. Loosen format, tighten role and example. Constrain the frame, not the words.
- **The output keeps being confidently wrong** about a fact. Put the correct fact in context as a plain statement. Arguing with output in follow-up messages does not survive to the next run.
- **The prompt works for the user but not for a colleague.** Something lives in the user's head rather than in the context block. Have the colleague run it and note where they had to explain something.
- **It worked last month and stopped.** Usually the facts changed shape rather than value. Check the context block against reality before touching anything else.
- **Sensitive material.** Names, salaries, customer records, anything under an agreement. Say once that the prompt is going to a third-party service, and use initials or role names instead of real ones where the task allows.
- **The request is a question, not a job.** "What do you think about X" needs no structure. Structure earns its keep when the output is a deliverable that someone else reads.
## Files
- `references/examples.md` - three full builds, each with the weak version, the built prompt, the first run's failure, the one-part repair, and the fixed output. Read one before building your first prompt.
- `references/templates.md` - fill-in skeletons for the requests people repeat weekly, a context test, format phrases that actually constrain, and the swap note pattern for saving a prompt. Read it at step 3 and step 7.
references/examples.md
# Worked builds
Three requests taken from the vague version through to a saved template, including the run that failed and the single edit that fixed it. The failures are the point; a build that works first time teaches nobody anything.
## Contents
- [Example 1: the weekly status update](#example-1-the-weekly-status-update)
- [Example 2: a job description](#example-2-a-job-description)
- [Example 3: summarising customer feedback](#example-3-summarising-customer-feedback)
- [What the three builds have in common](#what-the-three-builds-have-in-common)
---
## Example 1: the weekly status update
### The weak version
> "Write a status update about the migration project."
Six runs, six different shapes, all of them padded, none of them sendable without rewriting.
### The one-line job
Produce a weekly status update **for my VP** so she can **forward it to her boss unchanged**.
That last clause changed everything. An update the VP forwards cannot contain internal blame, cannot assume the reader knows the vendor's name, and cannot be longer than a phone screen.
### The built prompt
```text
Role: You are a project lead writing upward to an executive who reads ten of
these on a Monday morning and forwards three of them.
Context:
- The migration is two weeks late. Cause: vendor API access slipped, not our build.
- New date is 14 March. I am confident in it and will not need to move it again.
- No budget impact.
- The VP's boss has asked about this project twice in the last month.
Task: Write my weekly status update for my VP so she can forward it to her
boss unchanged.
Format: Subject line, then three sections labelled Done, Risk, Next.
Under 120 words total. No exclamation marks. No closing paragraph.
Plain nouns, no internal project code names.
Example of the tone:
"Subject: Migration - two weeks late, new date 14 March
Done: Read replicas complete and verified against production."
```
### First run
Came back at 190 words, with a closing paragraph that thanked the VP for her support.
**Wrong?** No. Every fact was right. **Missing?** No.
So this is a format failure, and only the format block gets touched. Added two lines:
> Hard limit 120 words. Do not write a closing paragraph.
### Second run
```text
Subject: Migration - two weeks late, new date 14 March
Done: Read replicas complete and verified against production. Write path built
and in test.
Risk: We lost two weeks waiting on vendor API access. That is resolved. The
remaining risk is the schema change landing on the 15th; if it slips, so do we.
Next: Cutover 14 March. I will confirm or flag by 7 March, whichever way it goes.
```
112 words. Sendable.
### The swap note
> **Swap each time:** the Context block, four bullets. **Leave alone:** role, format, example. **Watch for:** the example going stale - replace it with a recent update the VP actually forwarded.
**Why this build worked:** the Z slot ("forward it unchanged") did more work than the other four parts combined. The failure was in format, was diagnosed in ten seconds because the parts were labelled, and was fixed with two sentences rather than a rewrite.
---
## Example 2: a job description
### The weak version
> "Write a job description for a customer support person."
Output read like every job ad on the internet: "fast-paced environment", "wear many hats", "passionate about customer success".
### The one-line job
Produce a job advert **for experienced support people currently working somewhere worse** so they can **decide in 30 seconds whether to apply**.
### The built prompt
```text
Role: You are a hiring manager who has read four hundred applications and knows
which lines in an advert cause the wrong people to apply.
Context:
- Six-person support team, B2B accounting software, mostly email and some calls.
- Fully remote within the UK. Salary is published: £34-38k.
- Real hours: 9-5, genuine. No weekend rota, no on-call.
- The last two hires left because the product was harder to learn than they
expected. The advert should not hide that.
- We need someone comfortable saying "I don't know, let me check" to an accountant.
Task: Write a job advert for experienced support people so they can decide in
30 seconds whether to apply.
Format: Under 400 words. Sections: what the job is, what a normal day looks
like, what is hard about it, what we pay, how to apply.
No adjectives about the company culture. No "fast-paced". No list of
"requirements" longer than five items.
Example of the honest tone I want:
"The product is genuinely hard to learn. Most people take three months before
they stop checking with someone."
```
### First run
Good structure, right length, but the "what is hard about it" section had been softened into "challenges that help you grow".
**Wrong?** Yes, arguably. It misrepresents the job, which is the exact thing the context said not to do.
That is a role and example problem, not a format one. The role said "hiring manager"; hiring managers write adverts that flatter. Edited the role:
> You are a hiring manager who has been burned twice by new starters leaving in month three, and would rather lose ten applicants now than one hire later.
### Second run
The hard section came back as:
> **What is hard about it:** the product is accounting software and it is genuinely difficult to learn. Our last two hires left partly because of this. Expect three months before you feel competent, and expect to tell qualified accountants that you need to check something. If that sounds miserable, this is not the job.
### The swap note
> **Swap each time:** context bullets, salary, team size. **Leave alone:** format. **Re-read each time:** the role line, because it is doing the honesty work.
**Why this build worked:** the failure looked like a tone problem and was actually a role problem. Tone problems are usually the role or the example, in that order. Note that the fix was one sentence in one part.
---
## Example 3: summarising customer feedback
### The weak version
> "Summarise this customer feedback." (Pasted: 60 support tickets.)
Came back as a tidy list of themes that read plausibly and contained two themes nobody had actually mentioned.
### The one-line job
Produce a feedback summary **for the product manager** so they can **choose what goes in the next sprint**.
### The built prompt
```text
Role: You are a support lead who has read every one of these tickets and has to
defend the summary in a planning meeting.
Context:
- 60 tickets from the last two weeks, pasted below.
- The product manager will use this to pick two things to fix.
- We have been burned before by summaries that inflated a single loud customer
into a "theme".
Task: Summarise these 60 tickets for the product manager so they can choose
what goes in the next sprint.
Format:
- Group into themes. For each theme: a one-line description, the number of
tickets, and two verbatim quotes.
- Order by ticket count, highest first.
- Any theme with fewer than three tickets goes in a section called
"Single reports" with no analysis.
- Do not suggest fixes. Do not rank by severity. Counting only.
- If a ticket does not fit a theme, say how many were left over.
```
### First run
Correct counts, but it had ranked themes by "impact" and written a recommended fix under each one.
**Wrong?** The recommendations were speculation presented as findings. Yes.
Format problem: the two "do not" lines were there but sat at the end of a long block. Moved them to the top of the format section and made them the first thing:
> Format: counting and quoting only. Do not suggest fixes, do not assess severity, do not rank by anything except ticket count.
### Second run
```text
Theme 1: Export to CSV times out on large accounts - 14 tickets
"I've tried the export four times today and it spins forever."
"Anything over about 5,000 rows and it just dies."
Theme 2: Password reset email arriving in spam - 9 tickets
"Took me 20 minutes to work out it was in junk."
"Third time this has happened to me."
Theme 3: Invoice date shows in US format - 5 tickets
...
Single reports (fewer than 3 tickets each): 11 tickets covering 11 separate
issues. Listed below without analysis.
Unclassified: 4 tickets. Mostly account-specific questions with no common thread.
```
### The swap note
> **Swap each time:** the pasted tickets and the date range. **Leave alone:** everything else. **The two "do not" lines are load-bearing** - the summary drifts back into recommending fixes without them.
**Why this build worked:** the prohibition needed to be early and blunt rather than thorough and buried. Also note the "unclassified" line: the format asked for leftovers to be counted, which is what stops a summary quietly rounding sixty tickets into three neat themes.
---
## What the three builds have in common
1. The Z slot changed the output more than any other single edit. "So she can forward it unchanged", "so they can decide in 30 seconds", "so they can pick two things to fix" each rewrote the whole shape of the answer.
2. Every failure was diagnosed to one part and repaired with one edit. Nobody rewrote a prompt.
3. Two of the three failures looked like tone problems and were not. One was format, one was role. Checking wrong-then-missing before reacting to tone is what kept the diagnosis honest.
4. The format blocks say what not to do, not only what to do. "No closing paragraph", "do not suggest fixes", "no requirements list longer than five items" each fixed a recurring habit.
5. All three saved a swap note naming which block changes weekly. That note is what turns a good prompt into something a colleague can also use.
references/templates.md
# Skeletons and phrasing
Fill-in shapes for the requests people make every week, plus the language that actually constrains an answer. Use these at step 3 when building, and at step 7 when saving.
## Contents
- [The blank five-part skeleton](#the-blank-five-part-skeleton)
- [The context test](#the-context-test)
- [Format phrases that constrain](#format-phrases-that-constrain)
- [Role lines that change the output](#role-lines-that-change-the-output)
- [Getting an example when none exists](#getting-an-example-when-none-exists)
- [Five ready skeletons](#five-ready-skeletons)
- [The swap note](#the-swap-note)
---
## The blank five-part skeleton
```text
Role: You are [a specific person with specific experience and a specific bias].
Context:
- [fact that changes the answer]
- [fact that changes the answer]
- [fact that changes the answer]
- [constraint, deadline, or thing that already went wrong]
Task: Produce [X] for [Y] so they can [Z].
Format: [shape]. [length in words or items]. [tone]. [what not to do].
Example of what good looks like:
[two lines, or one item, or a rejected version to steer away from]
```
Keep the labels. They are what makes a bad result diagnosable.
## The context test
For every line you are about to put in context, ask: **if this fact were different, would the output be different?**
| Fact | Include? |
|---|---|
| The deadline slipped by two weeks | Yes - changes the whole message |
| The client complained once already | Yes - changes the tone |
| The budget is fixed | Yes - closes off an option |
| The project started in January | Only if a date matters to the reader |
| The team is six people | Only if size affects what is being asked |
| Everyone is stressed about it | No - unless the output should acknowledge it |
| A full history of the project | No |
| Your opinion of the vendor | No - unless the output should carry it |
Three to six lines is the working range. Past that, check whether you are describing the situation instead of constraining the answer.
One special case worth including: **something that went wrong last time.** "The last version was too long and got skimmed" prevents that failure more reliably than any format instruction.
## Format phrases that constrain
The left column can be checked by counting. The right column cannot.
| Constrains | Does not constrain |
|---|---|
| "Under 120 words" | "Keep it short" |
| "Three sections labelled Done, Risk, Next" | "Well structured" |
| "One paragraph per point, two to four lines" | "Easy to read" |
| "No exclamation marks" | "Professional tone" |
| "Five bullets maximum" | "A few key points" |
| "Subject line under 60 characters" | "A good subject line" |
| "Do not write a closing paragraph" | "Don't ramble" |
| "Verbatim quotes only, no paraphrasing" | "Accurate" |
| "Order by count, highest first" | "Prioritised sensibly" |
| "British spelling" | "Correct spelling" |
Negative instructions are legitimate and often the strongest ones available. Each one should correspond to a habit you have had to delete by hand at least twice.
Put the most important constraint first in the format block. Constraints buried at the end of a long block get treated as suggestions.
## Role lines that change the output
A role earns its place when it changes vocabulary, priorities, or what the writer is afraid of.
| Weak role | Role that does work |
|---|---|
| "You are a helpful assistant" | Delete it, it changes nothing |
| "You are a writer" | "You are a technical writer whose readers are on a phone in a warehouse" |
| "You are a manager" | "You are a manager who has to defend this decision to the person it affects" |
| "You are an expert" | "You are the person who will be blamed if this is wrong" |
| "You are a marketer" | "You are a marketer writing to people who have already unsubscribed once" |
The pattern in the right column: a role with a stake in the outcome. Stakes change output; job titles do not.
Skip the role entirely for mechanical tasks. Extracting dates from a document does not need a persona, and adding one only adds noise.
## Getting an example when none exists
In order of usefulness:
1. **A real past version.** Last week's, last month's, the one that got approved.
2. **A rejected version,** labelled as the thing to avoid. Often easier for people to produce than a good one, and nearly as informative.
3. **The first two lines,** written by hand, showing exactly how it should open.
4. **A single item** from the middle: one bullet, one row, one section, in the correct shape.
5. **A named comparison** the user has actually seen: "like a doctor's discharge note, not like a press release."
Never write three adjectives instead. "Clear, engaging and professional" describes nothing and will be satisfied by anything.
## Five ready skeletons
### Weekly update
```text
Role: You are a [role] reporting to [audience] who reads [n] of these a week.
Context: [what happened] / [what slipped and why] / [the new date] / [what they already asked about]
Task: Write my [period] update for [audience] so they can [what they do with it].
Format: Subject line, then [sections]. Under [n] words. No closing paragraph.
Example: [last approved update, first three lines]
```
### Reply to a difficult message
```text
Role: You are [me], writing to [person and relationship].
Context: [what they said] / [what I can offer] / [what I cannot] / [what I want to happen]
Task: Draft my reply to [person] so they [desired next step].
Format: Under [n] words. [Tone]. State the answer in the first three lines.
Example: [something I sent them before, so the voice matches]
```
### Summarising a pile of input
```text
Role: You are someone who has read all of this and has to defend the summary.
Context: [what the input is] / [how many items] / [what the reader will decide]
Task: Summarise [input] for [reader] so they can [decide what].
Format: Group by theme. Per theme: description, count, [n] verbatim quotes.
Order by count. Do not suggest fixes. Report anything that did not fit.
```
### First draft of a document
```text
Role: You are [role] writing for [reader], who knows [what they already know].
Context: [purpose] / [3-5 facts] / [what must be in it] / [what must not]
Task: Draft [document] for [reader] so they can [action].
Format: [sections in order]. [length]. [tone]. [what not to include].
Example: [an approved document of the same kind]
```
### Extracting structured data
```text
Role: [none - this is mechanical]
Context: [what the source is] / [what the output feeds into]
Task: Extract [fields] from the text below.
Format: One row per [item]. Columns: [names]. If a field is absent write
"not stated" - never infer it. List anything you could not parse at the end.
```
That last format line matters more than the rest of the skeleton. Without it, missing values get filled in plausibly.
## The swap note
Save this alongside any prompt that has worked twice:
```text
SWAP EACH TIME: [which block, and roughly what goes in it]
LEAVE ALONE: [the blocks that are doing the stable work]
LOAD-BEARING: [any single line that, when removed, breaks the output]
IF IT DRIFTS: [the usual culprit - normally a stale example]
LAST VERIFIED: [when it last produced something you sent without editing]
```
The load-bearing line is the one people delete during a tidy-up six weeks later, wondering why the prompt suddenly stopped working. Write it down.
Install it
Claude Code (this project)
Unzip the download into .claude/skills/. The folder is already named right.
Claude Code (every project)
Unzip into ~/.claude/skills/ to use it everywhere.
claude.ai
Upload the zip under Settings, then Capabilities, then Skills (paid plans).
How to call it
Just describe the task. The description line inside the skill does the matching. Or call it directly:
/prompting-for-workthis keeps giving me generic resultshelp me write a better prompt for thiswhy does the output change every time I askmake this request give me something I can actually useturn this into a prompt I can reuse every week
Works beyond Claude
Skills use the open Agent Skills format. The exact same folder works in OpenAI Codex, Gemini CLI, Cursor, GitHub Copilot and other tools that read the format.
Using a plain chat app? Paste SKILL.md into ChatGPT or Gemini as instructions. You lose auto-triggering, but the method still works.
