Job Descriptions skill for Codex

A good job description lets a qualified candidate decide in two minutes whether to apply, and lets an unqualified one decide not to. It names the real work and outcomes, keeps requirements to what is truly needed on day one, states pay where law or policy requires, and contains nothing that screens people out for reasons unrelated to the job.

Employment law differs by jurisdiction. Flag pay-transparency, accommodation and equal-opportunity wording for HR or employment counsel to confirm before the posting goes live; publishing to job boards is outward-facing and needs the user’s go-ahead.

Inputs to collect

• Hiring manager’s answer to: “What will this person have achieved after 6 and 12 months that makes the hire a success?”
• Team, reporting line, and who they work with most
• Level in the company’s career ladder (read it if the repo or folder has one)
• Location model: on-site, hybrid (days per week), remote (which countries or time zones; payroll and legal entities limit this)
• Compensation range, equity, and key benefits; visa sponsorship yes/no
• Interview stages and expected timeline (see technical-interviews)
• Company boilerplate: mission paragraph, EEO statement, accommodations contact

If the outcomes question has no answer, stop and ask; a description written without it becomes a generic list of skills.

Structure

# <Standard title>, <Level or specialty> (<Location model>)

<2-3 sentences: what the team does, why this role exists now, what success looks like.>

## What you will do
- <Outcome-oriented responsibility: verb + object + why it matters>  (5-7 bullets)

## In your first year you will
- <3 concrete outcomes, e.g. "Ship the self-serve billing migration with the payments team">

## What you need
- <Must-have, observable, needed on day one>  (4-6 bullets max)

## Nice to have
- <Learnable on the job, or bonus>  (0-4 bullets)

## Compensation and benefits
<Range and currency, how level within range is set, equity, key benefits>

## How we hire
<Stages, who you meet, rough timeline, how to request accommodations>

<EEO / non-discrimination statement>

Writing rules

• Title: use the term candidates search for (“Senior Backend Engineer”, “Customer Success Manager”), not internal names (“Platform Wizard”, “Member of Technical Staff III”) unless that is industry standard. Put level in the title when the company uses levels.
• Requirements describe capability, not proxies. “Has designed and operated a service handling payments in production” beats “7+ years of experience”. If years are used, give a range and say it is a guide.
• Separate must from nice. Every must-have should be something you would reject a candidate for lacking. Long must-have lists deter qualified applicants, particularly from under-represented groups.
• Degree requirements: only when legally or practically required; otherwise “degree or equivalent experience”.
• Specific tech: list the stack as context (“we use Go, Postgres and Kafka”) rather than requiring every item.
• Plain language, second person, active verbs. Aim for under 700 words of body text.

Inclusive language check

Avoid	Why	Use instead
rockstar, ninja, guru, hero	Vague, coded as young and male	expert, experienced, specialist
aggressive, dominant, competitive	Gender-coded; deters many applicants	ambitious, driven, motivated
young, energetic, digital native, recent graduate (as requirement)	Age discrimination risk	early-career (only for genuinely entry-level programmes)
native English speaker	National origin discrimination risk	fluent / professional working proficiency in English
must lift 50 lbs, must stand all day (for desk jobs)	Excludes disabled candidates without job need	only list physical requirements that are essential, with accommodation offered
culture fit	Invites similarity bias	values you can describe, e.g. “writes things down”, “gives direct feedback”
he/she, guys	Gendered	you, they, everyone
“work hard, play hard”, “family”	Signals long hours, blurred boundaries	describe actual working hours and flexibility

Also check: no requirement to share salary history (banned in many jurisdictions), no age or graduation-year questions, and that benefits language covers all family types.

Pay transparency

Many jurisdictions require a good-faith pay range in postings, including Colorado, California, Washington, New York State and New York City, Illinois and several other US states, and the EU Pay Transparency Directive (member states must transpose it by June 2026) requires pay information to applicants and bans asking for pay history. Rules on which postings are covered (including remote roles open to those locations) differ, so:

• Default to including a range for every posting; it is required in many places and improves applicant quality everywhere.
• Use the range the company would actually pay for this level and location, not a stretched one. Write the currency and period (“USD 150,000-180,000 per year base”).
• State what else is offered (bonus, equity, benefits) where the law asks for it.
• Flag for HR to confirm current requirements for every location the role is open to.

Structured data for job boards

Postings on a company careers site appear in Google’s job search when marked up with schema.org JobPosting. Generate it alongside the posting if the site is in the repo:

{
  "@context": "https://schema.org",
  "@type": "JobPosting",
  "title": "Senior Backend Engineer",
  "description": "<p>HTML of the full posting</p>",
  "datePosted": "2026-10-28",
  "validThrough": "2026-12-31T23:59",
  "employmentType": "FULL_TIME",
  "hiringOrganization": { "@type": "Organization", "name": "Example Co", "sameAs": "https://example.com" },
  "jobLocationType": "TELECOMMUTE",
  "applicantLocationRequirements": { "@type": "Country", "name": "USA" },
  "baseSalary": {
    "@type": "MonetaryAmount", "currency": "USD",
    "value": { "@type": "QuantitativeValue", "minValue": 150000, "maxValue": 180000, "unitText": "YEAR" }
  }
}

For on-site roles use jobLocation with a Place and PostalAddress instead of the remote fields. Validate with Google’s Rich Results Test (needs network).

Auditing an existing posting

1. Read it as a candidate: can you tell what you would do in week one and month six?
2. Count must-haves; flag any above six and any that are proxies (years, degrees, specific schools, specific companies).
3. Run the inclusive-language table over the text; quote each hit with a replacement.
4. Check pay range, location rules, accommodation statement and EEO statement.
5. Check consistency with the career ladder level and the interview loop: anything the loop tests should appear in the requirements, and vice versa.

Gotchas

• Copying the last person’s job description hires a replacement for the old role, not the role the team needs now. Start from outcomes every time.
• Remote postings that say “anywhere” when payroll only exists in two countries waste everyone’s time. Name the countries or time zones.
• Inflated titles to attract candidates create levelling problems at offer time. Match the ladder.
• A range so wide it is meaningless (“$80k-$250k”) may not satisfy good-faith requirements and erodes trust.
• AI-generated filler (“fast-paced, dynamic environment”, “passionate about excellence”) says nothing. Replace each with a concrete fact or delete it.

Output

1. The posting (markdown), ready for the ATS
2. Change log if rewriting: <each removed or changed phrase and why>
3. Checks: must-haves <= 6 | pay range present | location rules stated | accommodations
   and EEO statement present | inclusive-language hits resolved
4. For HR / counsel to confirm: <pay transparency for listed locations, legal statements>