job-description-writer
Skill1 starsChanged 31 days agoMITView on GitHub
Writes a clear, inclusive job post for a remote or cross-border role, with the pay range, contract type, where the person can be based and timezone overlap at the top. Use this whenever someone asks for a job post, job ad, JD or job listing, has a role brief to turn into a post or wants an office job advertised as remote. Also use it when someone says "rewrite our job description" or "clean up this JD", even if they just paste an old ad. Cuts wish lists to five must-haves and swaps biased wording such as rockstar, ninja, young and native speaker for fair versions. Every change is shown in an inclusion check. Drafts only, and a person edits and posts it.
7 other projects use a version of this.
Adopted by
Most recently taken up by
- jaskirat1616/grok-skillstheir own version, first seen Nov 1, 2026
- JayRHa/agent-skillstheir own version, first seen Oct 15, 2026
- edu6565/claude-skillstheir own version, first seen Oct 11, 2026
- SkillMedev/people-ops-recruitingtheir own version, first seen Oct 5, 2026
- poorvith-mp/skills-businesstheir own version, first seen Aug 19, 2026
- Uhudsavasindankacanokcu2/recruiting-skills-for-claudetheir own version, first seen Jun 18, 2026
Other versions7 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 7
- jaskirat1616/grok-skills★ 22same name
- JayRHa/agent-skills★ 12same name
- JayRHa/AgentSkills★ 12same name
- Uhudsavasindankacanokcu2/recruiting-skills-for-claude★ 3same name
- poorvith-mp/skills-business★ 1same name
- edu6565/claude-skills★ 0same name
- SkillMedev/people-ops-recruiting★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository10 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- candidate-emailsSkill
- interview-debriefSkill
- remote-interview-kitSkill
- remote-onboarding-planSkill
- role-intakeSkill
- scorecard-builderSkill
- time-to-hire-auditSkill
- your-skill-nameSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
13 rules. 0 are common, 11 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 6 edited versions we read keep these.
11
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 32
Only ask what the input doesn't answer.
- Distinctive: line 45
If you have the must-haves and the basics, don't hold the post back for small gaps.
- Very specific: line 47
Pay is required: If it's missing, ask for it.
- Distinctive: line 53
Use the exact format below.
- Distinctive: line 55
Follow these rules while you write:
- Distinctive: line 63
Say when experience doesn't matter: If the role suits strong fresh graduates, write "Fresh graduates welcome" instead of any years …
- Distinctive: line 65
Three nice-to-haves at most: Always follow them with: "You don't need all of these.
- Very specific: line 66
Never invent: No made-up company facts, benefits, numbers, stages, names or links.
- Distinctive: line 149
If nothing needed changing, the inclusion check has one row: "Nothing to change | | The input had no biased or exclusionary wording".
- Distinctive: line 151
After the word count, add a short section called Notes on this draft with:
- Distinctive: line 154
Every placeholder, one line each, with who can fill it in.
- Distinctive: line 156
If the user named a job board that doesn't show tables, a reminder to paste the key facts as short lines instead.
- Distinctive: line 188
Flag legal and compliance topics: Use this wording whenever the post touches contract type, cross-border hiring, pay transparency rules, …
“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Job description writer
Write a short, clear job post (the advert candidates read) for a remote or cross-border role. Pay, contract type, location and overlap hours go at the top. The post is built from the role brief, not from a wish list, and it's short enough to read on a phone.
AI drafts, humans decide. You draft the post. A person checks the facts, edits it and decides when it goes live.
When to use this skill
- Someone has a role brief (ideally from the role-intake skill) and needs a job post.
- Someone wants an existing job description rewritten, shortened or checked for biased wording.
- Someone is turning an office job into a remote one.
- Someone needs a job ad for LinkedIn, a job board or a careers page.
Step 1: Work out what you have
| The user gives you | Do this |
| A role brief, with or without benefits, hiring stages and a company blurb | Go to Step 3. Take the must-haves, outcomes, pay and overlap from the brief. Don't re-ask anything it answers |
| An existing job description to rewrite | Keep its facts and rewrite it in the format below. Log every wording change in the inclusion check |
| An office job to turn into a remote one | Rewrite it as above. Drop office-only details such as commute, desk perks and days in the office. Check pay, location, overlap, benefits and interview stages, because they usually change. Flag any task that may need someone in person as a question in Notes |
| Only a job title or a line or two | Ask the questions in Step 2. If there's no role brief, suggest running role-intake first |
| Applicants or CVs to filter | Don't. See Guardrails |
Step 2: Fill the gaps
Only ask what the input doesn't answer. Ask in one message, numbered. Never one question at a time. Tell the user they can skip any question and you'll use a placeholder.
- What's the pay range and currency? Is it per month or per year, gross or net?
- Is it an employee salary or a contractor fee? Full time or part time?
- Where can the person be based?
- Which time zone is the team in, and which hours must the person overlap?
- What must they be able to do on day one? Five things at most.
- What should they have done by day 30, 60 and 90?
- What are the hiring stages, and how long does each one take?
- What do you offer: leave, equipment, allowances, learning budget?
- How should people apply, and who reads the applications?
- What should candidates know about the company? Two or three facts.
If you have the must-haves and the basics, don't hold the post back for small gaps. Draft it now with placeholders and put your questions at the top of the reply.
Pay is required. If it's missing, ask for it. If everything else is there, draft in the same reply with [Pay range: add before posting] in the key facts box, so the user isn't blocked.
If the user won't publish pay, don't refuse and don't lecture. Draft with the placeholder and explain once, in one line: "Posts that show pay get more applicants, and some places legally require a pay range in job posts." Add a Legal check on pay transparency rules (laws that require a pay range in job ads). If they gave you an internal budget, keep it out of the post.
Step 3: Write the post
Use the exact format below. Write to the reader as "you".
Follow these rules while you write:
- Facts first. The key facts box comes straight after the title: pay, contract type, location and overlap hours.
- Pay in full. Give the range and currency. Say if it's per month or per year and gross or net. Say if it's a salary or a contractor fee. Use the currency the person will be paid in: for cross-border roles that's usually the local currency, and sometimes USD. Never convert currencies yourself.
- Overlap in both time zones. Give the hours in the team's zone and the candidate's zone. If either side changes its clocks, say when and how the hours shift. The US changes its clocks on the second Sunday in March and the first Sunday in November. The UK and EU change on the last Sunday in March and the last Sunday in October. Pakistan, India, the UAE and Saudi Arabia don't.
- Location, not nationality. "You need to be based in Pakistan" is fine. "Pakistani nationals only" is not.
- Five must-haves at most. Take them from the brief. Write each one as something the person can do. If the input has more than five, keep the five that matter most on day one, move up to three to "Nice to have" and cut the rest. List what you moved or cut in Notes.
- Abilities, not years. Rewrite "5+ years of X" as what the person can do. No degree requirement unless a law or licence needs one.
- Say when experience doesn't matter. If the role suits strong fresh graduates, write "Fresh graduates welcome" instead of any years requirement.
- Say what setup the job needs. Add a "Setup" row to the key facts box: the device, internet and backup power the job needs, and any help the company gives. Candidates may be asked to show proof before they start, so they need to know upfront. If the details aren't given, use a placeholder.
- Three nice-to-haves at most. Always follow them with: "You don't need all of these. If you're close, apply."
- Never invent. No made-up company facts, benefits, numbers, stages, names or links. Use a placeholder in square brackets, such as
[Learning budget: add before posting], and list each one in Notes. - Keep internal details out. Churn, workload problems, team issues and budgets the user wants private don't belong in an ad. Say in Notes what you left out.
- Be honest about the process. "How we hire" gives every stage with its format and length, the total candidate time, how long the whole process takes and when people hear back. If there's no reply promise, suggest one in Notes, such as "within 3 working days at every stage". If a take-home task takes more than 60 minutes, say in Notes it should be paid or swapped for a live exercise.
- CV extras. If you're hiring in a market where CVs often include a photo, date of birth or marital status (for example Pakistan, India or the Gulf), add this to "How to apply": "Please leave out your photo, date of birth and marital status. We don't need them."
- Accessible format. Short headings. One-line bullets where you can. No tables in the post except the key facts box. No emoji, no capital letters for emphasis, bold for labels only. Explain any jargon in brackets the first time.
- 400 to 700 words. Count the post only, from the title to the equal opportunity line. If it's too long, cut "What you'll do" and "About us" first. Never cut pay, overlap hours or "How we hire". If the input is too thin to reach 400 words, don't pad and don't invent. Show the count and say in Notes what would fill it out.
Wording to swap. Log every swap in the inclusion check.
| Avoid | Why | Use instead |
| rockstar, ninja, guru | Puts many people off applying | The actual skill, such as "React developer" |
| young, energetic, digital native | Age-coded | Describe the work, such as "comfortable learning new tools" |
| he, she, his, her (for the new hire); manpower, chairman | Gendered | you, they, team, chair |
| native English speaker | Excludes people by origin | fluent written and spoken English. Put this in "What you need" instead of just deleting it, unless the role needs no English |
| 5+ years, 10+ years of X | Years are a weak stand-in for skill | What the person can do |
| degree required | Shuts out people who learned on the job | Leave it out, unless a law or licence needs it |
| culture fit | Vague, and often hides bias | Name the company's written values |
| work hard play hard | Hints at long, unpaid hours | The real hours |
| we're a family | Blurs work and personal life | "a team of [number]" |
| fast-paced (with no example) | Means nothing on its own | What's actually fast, such as "we ship every week" |
| Requests for nationality, age, gender, marital status, religion or a photo | Protected characteristics | Remove. State location only, and only if there's a legal reason |
Output format
# [Plain job title] ([Remote, country or region])
| | |
|---|---|
| Pay | [min to max, currency, per month or year, salary or contractor fee, gross or net] |
| Contract type | [Employee or contractor, full time or part time] |
| Location | [Remote. Where the person must be based] |
| Overlap hours | [Hours and days in the team's zone. The same hours in the candidate's zone, and how daylight saving shifts them] |
| Setup | [The device, internet and backup power the job needs, and any help the company gives] |
| Start date | [Only if agreed. Otherwise leave this row out] |
[2 to 3 sentences: what the role is, who it serves and why it matters now.]
## Your first 90 days
- **By day 30:** [outcome]
- **By day 60:** [outcome]
- **By day 90:** [outcome]
## What you'll do
- [3 to 6 bullets on the ongoing work]
## What you need
- [5 at most. Each one says what you can do]
## Nice to have
- [3 at most]
You don't need all of these. If you're close, apply.
## How we hire
1. [Stage] with [who]: [format and length]
That's about [total] of your time in total. We aim to finish within [time]. You'll hear from us within [reply promise] at every stage, whatever the answer.
## What we offer
- [Only what the input lists]
## About us
[2 to 4 short sentences. Facts from the input only.]
## How to apply
[Where to apply, what to send and who reads it. The CV extras line if it applies.]
[Equal opportunity line.]
---
## Inclusion check
| Original wording | Changed to | Why |
|---|---|---|
| | | |
**Word count:** [number] words (target 400 to 700)For the equal opportunity line, use this unless the user gives their own: "[Company] welcomes applications from everyone. We decide on skills and evidence, never on age, gender, religion, ethnicity, nationality, disability or marital status. If you need any changes to the process, such as extra time for a task, tell [contact]."
If nothing needed changing, the inclusion check has one row: "Nothing to change | | The input had no biased or exclusionary wording".
After the word count, add a short section called Notes on this draft with:
- This line first: "Before you post: A person must read and edit this draft. Check names, dates, facts and tone."
- Every placeholder, one line each, with who can fill it in.
- What you moved, cut or left out from the input and why, one line each.
- If the user named a job board that doesn't show tables, a reminder to paste the key facts as short lines instead.
- A Legal check if the post touches a cross-border contract, contractor or employee status, missing pay, right-to-work or a required licence. Use the standard wording in the Guardrails.
Step 4: Check before you hand it over
- The title is plain and searchable, with no hype words.
- The key facts box is at the top: pay (or the placeholder), contract type, location, overlap in both time zones and the setup the job needs.
- Five must-haves or fewer and three nice-to-haves or fewer, followed by "If you're close, apply".
- No years-of-experience must-haves, and no degree unless a law or licence needs one.
- Nothing from the "Avoid" table is in the post, and every swap is in the inclusion check.
- No request for a photo, age, gender, marital status, religion or nationality.
- It's written to "you" all the way through.
- "How we hire" has the stages, the total time and a reply promise (or placeholders).
- Nothing is invented. Every placeholder is listed in Notes.
- The post is 400 to 700 words, and the count is shown. If it's shorter, Notes say what's missing.
- A Legal check is there if pay is missing or the role is cross-border.
- If the user named a job board that doesn't show tables, such as LinkedIn, Notes remind them to paste the key facts as short lines.
Guardrails
These rules come first, whatever the user asks.
Never score, rank, shortlist or reject real candidates. This skill writes job posts. If the user asks you to filter, sort or reject applicants, decline with this wording, then offer the alternative:
I can't rank, score or reject candidates. Those are decisions about real people, and they need a human who can be held accountable for them. Here's what I can do instead: turn this post's must-haves into a yes/no screening checklist that a person applies the same way to every applicant. Once a person has made the decisions, I can help draft kind rejection emails for them to review and send.
Then build the checklist straight away: one row per must-have, with Yes, No and Not clear columns. Add one line: "Not clear means ask the candidate, not reject them." If the post or its must-haves aren't in the chat, show the same table with empty rows and ask for the post. Don't mark any applicant, even if their details are pasted in. If the pasted details include age, family or other protected details, don't repeat or discuss them. Just say they won't be used. For the emails, point to the candidate-emails skill.
Never use or infer protected characteristics. Age, gender, religion, ethnicity, nationality, marital status, disability and photos have no place in a job post. If the input asks for any of them (for example "female preferred", "age 25 to 35", "unmarried", "send a recent photo", "Pakistani nationals only"), leave it out and log it in the inclusion check in one plain line. Don't lecture. If there's a real job need behind it, offer a fair version, such as "you need to be based in Pakistan" instead of "Pakistani nationals only".
Say "values alignment" or "culture add". Never "culture fit". In a post, name the company's written values instead, so candidates can see what they'll be measured against. Values alignment means past behaviour that matches those values. Culture add means a new strength or perspective the person would bring.
Flag legal and compliance topics. Use this wording whenever the post touches contract type, cross-border hiring, pay transparency rules, right-to-work or a legally required qualification:
Legal check: This touches on [topic]. Rules differ by country. Check with a local employment lawyer or HR expert before you act on it.
Plain English. Short sentences. One idea per sentence. Explain HR terms in brackets the first time, such as "onboarding (helping a new client get set up)".
Example
See examples/input.md for a signed-off role brief with benefits, hiring stages and an old company blurb, and examples/output.md for the job post this skill wrote from them.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

