agentleFS
osamabinjannatosamabinjannat/remote-hiring-skills/skills/job-description-writer/SKILL.md

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

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
  1. Distinctive:

    Only ask what the input doesn't answer.

    line 32
  2. Distinctive:

    If you have the must-haves and the basics, don't hold the post back for small gaps.

    line 45
  3. Very specific:

    Pay is required: If it's missing, ask for it.

    line 47
  4. Distinctive:

    Use the exact format below.

    line 53
  5. Distinctive:

    Follow these rules while you write:

    line 55
  6. Distinctive:

    Say when experience doesn't matter: If the role suits strong fresh graduates, write "Fresh graduates welcome" instead of any years …

    line 63
  7. Distinctive:

    Three nice-to-haves at most: Always follow them with: "You don't need all of these.

    line 65
  8. Very specific:

    Never invent: No made-up company facts, benefits, numbers, stages, names or links.

    line 66
  9. Distinctive:

    If nothing needed changing, the inclusion check has one row: "Nothing to change | | The input had no biased or exclusionary wording".

    line 149
  10. Distinctive:

    After the word count, add a short section called Notes on this draft with:

    line 151
  11. Distinctive:

    Every placeholder, one line each, with who can fill it in.

    line 154
  12. Distinctive:

    If the user named a job board that doesn't show tables, a reminder to paste the key facts as short lines instead.

    line 156
  13. Distinctive:

    Flag legal and compliance topics: Use this wording whenever the post touches contract type, cross-border hiring, pay transparency rules, …

    line 188

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 youDo this
A role brief, with or without benefits, hiring stages and a company blurbGo 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 rewriteKeep 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 oneRewrite 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 twoAsk the questions in Step 2. If there's no role brief, suggest running role-intake first
Applicants or CVs to filterDon'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.

  1. What's the pay range and currency? Is it per month or per year, gross or net?
  2. Is it an employee salary or a contractor fee? Full time or part time?
  3. Where can the person be based?
  4. Which time zone is the team in, and which hours must the person overlap?
  5. What must they be able to do on day one? Five things at most.
  6. What should they have done by day 30, 60 and 90?
  7. What are the hiring stages, and how long does each one take?
  8. What do you offer: leave, equipment, allowances, learning budget?
  9. How should people apply, and who reads the applications?
  10. 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.

AvoidWhyUse instead
rockstar, ninja, guruPuts many people off applyingThe actual skill, such as "React developer"
young, energetic, digital nativeAge-codedDescribe the work, such as "comfortable learning new tools"
he, she, his, her (for the new hire); manpower, chairmanGenderedyou, they, team, chair
native English speakerExcludes people by originfluent 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 XYears are a weak stand-in for skillWhat the person can do
degree requiredShuts out people who learned on the jobLeave it out, unless a law or licence needs it
culture fitVague, and often hides biasName the company's written values
work hard play hardHints at long, unpaid hoursThe real hours
we're a familyBlurs work and personal life"a team of [number]"
fast-paced (with no example)Means nothing on its ownWhat's actually fast, such as "we ship every week"
Requests for nationality, age, gender, marital status, religion or a photoProtected characteristicsRemove. 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.