job_description_writing v1.0.0

name: job_description_writing description: Write and rewrite job descriptions that attract the right applicants: frame the role by outcomes in the first year instead of task lists, cut requirements to true deal-breakers, define essential functions, and run an inclusive language audit before posting. Use when drafting a new job description or job posting, rewriting or shortening an existing one, reviewing requirements for inflation, checking a posting for coded or exclusionary language, or adding pay range and accommodation details.

Job Description Writing

Purpose

Turn a hiring manager's notes, an old posting, or a blank page into a job description a qualified stranger can judge themselves against honestly. The core method is outcome framing: define what the hire must deliver, let that decide the requirements, then audit the language so the posting does not screen out the people it wants.

Workflow

1. Get the raw material. Interview the hiring manager and, if the role exists today, one person doing it. Ask: why does this role exist, what breaks without it, what does the hire own, how will you know at 90 days that it is working, which requirements would actually cause a rejection. Check the answers against salary surveys or the Occupational Outlook Handbook when scope or level is unclear (SHRM job analysis practice).

1. Write the outcome frame first, before any task list. Three lines: success at 90 days, at 6 months, at 12 months. Each line is observable: a shipped thing, a number moved, a decision owned, a queue cleared. If the manager cannot name outcomes, the role is not ready to post. Send back the gaps as questions instead of inventing scope.

1. Convert tasks to owned outcomes. Rewrite each duty as verb, scope, outcome. "Manage social accounts" becomes "Plan and publish the weekly content calendar for three channels, growing qualified inbound demos from content". Cap the list at five to seven bullets. Duties that fit none of the outcomes from step 2 are marginal duties: cut them or group them into one honest line.

1. Build requirements from the outcomes, then run the necessity test. Every Required item must pass: the hire fails without it in the first 90 days, it cannot be taught in that window, and it is not a proxy. Years, degrees, and named tools are usually proxies. Write the outcome and accept equivalents: "2 to 4 years of work like this, or equivalent experience shown another way", "Python, or a similar language you can transfer from". Move everything else to Preferred, and label transferable experience as counting. Aim for eight or fewer Required bullets. Full test in references/language-audit.md.

1. Define essential functions separately from requirements. Essential functions are the fundamental duties of the job, the reason the position exists, per EEOC guidance under the ADA. Note frequency or time share, the consequence of not performing each one, and whether it could be reassigned. A written description prepared before hiring is evidence of essential functions, so write this section from the real job, not from habit. State physical demands only when they are essential, with exact weight, distance, or frequency, and pair the section with "with or without reasonable accommodation". Requirements are attributes a person brings; functions are what the job does. Do not mix them.

1. Add the practical block. Pay range, location and remote terms, schedule, travel, on-call. Pay disclosure is legally required in a growing set of US states and some cities, with different employer-size thresholds and start dates, and remote postings can trigger the law of the state the work can be performed from. Verify the current rule for every location the posting covers with the state labor agency before publishing, and include a range in good faith even where it is not required. State the unattractive parts plainly: a posting that hides them buys early turnover.

1. Run the language audit. First the linter, then the human checklist:

• python3 ~/workspace/skills/job-description-writing/bin/jd_lint.py <draft.md>
• Work through references/language-audit.md: gender-coded and age-coded words, origin-coded phrases, hype titles, vague traits rewritten as behavior, pronouns in second person ("you") where possible. Gendered wording research (Gaucher, Friesen, and Kay, 2011) found masculine-coded ads lowered appeal and sense of belonging for women, and readers did not notice the wording doing it. That is why the audit runs on every posting, not only on ones that look biased. Age preferences in job notices are generally unlawful under the ADEA outside a rare bona fide occupational qualification, so age-coded phrasing is a legal risk, not a style choice.

1. Close the loop. Have the hiring manager and a current job holder read the final draft against one question: is this the real job, at this level, on this team? Add the disclaimer that other duties may be assigned, date the document, and record who approved it. Re-run the audit on every repost: requirements creep back in each cycle.

Start from assets/job-description-template.md for new postings.

Worked example

Raw manager note: "Need a rockstar support rep, young and energetic, native English speaker, must have 5 years Zendesk, bachelor's required, team player who thrives in a fast-paced environment."

Rewritten:

• Why this role exists: "Our two-person support team carries a 400 ticket weekly backlog. This hire owns the queue so first response stays under 4 business hours."
• Success at 90 days: "Clears tickets at the team's quality bar with a first response under 4 hours on 95 percent of tickets."
• Required: "Written English clear enough for customer-facing replies (we test this with a short exercise, any background counts). Experience handling a high-volume ticket queue, in Zendesk or a similar tool. Two or more years in a customer-facing role, or equivalent experience."
• Cut and why: "rockstar" and "young and energetic" were coded filler, "native speaker" became the actual skill tested, 5 years of one tool became transferable queue experience, the degree failed the necessity test.

Output Contract

Deliver, in this order:

1. The finished description using the template sections: title, why this role exists, what success looks like, what you will own, essential functions, required, preferred, pay and practical details, how to apply, equal opportunity line.
2. An audit note, separate from the posting: requirement cuts and moves with the reason for each, coded-language fixes, the pay transparency check done for the posting locations, and any outcome gaps the hiring manager still owes.
3. The linter output, or a note that it ran clean, with the human checklist items confirmed by name.

Operating Rules

• Never invent outcomes, pay, headcount, or requirements the manager did not supply. Mark unknowns as open questions in the audit note.
• Never quote a pay law, threshold, or statistic you have not verified in this session. Laws change yearly; name the jurisdiction checked and the date.
• Requirements that screen out a protected group must be job-related and consistent with business necessity, or they come out. Flag legal questions for counsel instead of deciding them.
• Write in second person and active voice. No hype titles, no personality traits as requirements, no requirement listed twice in different words to pad the list.
• One standard market title per posting, the title candidates actually search.
• This skill writes the internal description and the public posting from the same source. If the two diverge, stop and reconcile them; a posting that promises a different job than the description is a defect.