jd-writing

name: jd-writing description: "This skill should be used when the user asks to write a JD, create a job description, draft job posting, JD for [role], job spec, role description, write a role profile, help me define a role, or needs to create, rewrite, or improve a job description for any function or level."

Job Description Writing

Purpose

Create compelling, candidate-centric job descriptions that attract the right people and feed downstream sourcing artifacts (personas, search strings, outreach). A JD is not a legal document or internal req — it's the first impression a candidate has of the role and the company.

Input Routing

This skill works from multiple starting points:

Always check talent-sourcing.local.md for company context before drafting.

Writing Process

Step 1: Gather Context

Read all available inputs:

• roles/[role-name]/brief.md — intake notes, HM preferences, team structure
• .claude/talent-sourcing.local.md — company identity, EVP, compensation philosophy, AI operating principles
• .claude/data/market/ — relevant market data if available

If the input is sparse, ask clarifying questions. Focus on the gaps that matter most:

Must-know before writing:

• What problem does this person solve? (not "what tasks do they do")
• What does success look like in 6-12 months?
• What level of seniority and scope?
• Who do they report to and work with?
• Location/remote policy

Good-to-know:

• Team size and stage (building from scratch vs. joining established team)
• Budget/comp range (even approximate)
• Why the role is open (growth, backfill, new function)
• What's the hiring manager's biggest worry about this hire?

Step 2: Decompose the Role

Break the role into searchable, readable components before writing:

Step 3: Draft the JD

Use the universal JD structure below. Write candidate-centric by default — lead with what the candidate gets, not what the company needs.

Tone decision framework:

Step 4: Adapt by Role Family

Each section of the JD shifts emphasis depending on the role family. Use the adaptation table:

Step 5: Inclusive Language Review

Run through each category before finalizing. This is an active editing pass, not a passive checklist.

Scan for and fix:

• Gendered language — he/she to they, "manpower" to "team", "chairman" to "chair". Check pronouns in example scenarios.
• Age-coded terms — remove "digital native", "energetic", "young team", "recent graduate" (unless truly entry-level). Remove "seasoned" or "veteran" (use specific experience instead).
• Ability-coded terms — remove unnecessary physical requirements ("stand for long periods" when the role is desk-based). Avoid "strong" as a catch-all.
• Culture-coded terms — remove "ninja", "rockstar", "guru", "work hard play hard", "culture fit". Replace with specific behavioral expectations.
• Requirement inflation — degree required? Would equivalent experience work? Years of experience exceed the technology's age? Specific tool when the skill is transferable?
• Exclusionary framing — "must be" vs "ideally has", "required" vs "preferred". Count must-haves: if more than 5, some are nice-to-haves in disguise.

For the full reference with examples and alternatives, see references/inclusive-language.md.

Step 6: Sensitive Information Review

JDs are public documents. Strip anything a competitor, customer, or journalist shouldn't see. Scan every section for:

• Financial metrics — deal sizes/ACV, revenue, ARR, margins, contract values (use "mid-market" or "enterprise" instead of exact figures)
• Pricing signals — anything that lets a competitor reverse-engineer packaging or discounting
• Internal targets — pipeline coverage ratios, conversion targets, quota numbers, OKRs
• Headcount plans — exact growth projections ("scaling from 40 to 450") unless already public (press releases, funding announcements)
• Strategic timing — fundraising plans, M&A, unreleased products
• Customer details — named contracts with values, unless the customer relationship is already public

Rule of thumb: If the data point would be useful in a competitor's sales deck or a journalist's article, remove it. Keep the signal (category, scale, motion) while removing the number.

When in doubt, flag the line for the user rather than publishing it.

Step 7: Stop-Slop Pass

Run the stop-slop skill rules against the final draft:

• Cut filler phrases and throat-clearing openers
• Break formulaic structures (don't start every bullet the same way)
• Vary rhythm — mix sentence lengths
• Remove anything that sounds like a pull-quote
• Trust the reader: state facts, skip softening

JD vs. Job Advert

A job description is an internal document — duties, qualifications, reporting lines. A job advert is candidate-facing marketing copy that sells the opportunity. This skill writes job adverts, not internal JDs. The distinction matters: internal JDs list what the company needs; job adverts show what the candidate gets.

When rewriting an existing JD, the transformation is usually: strip the internal framing, rewrite around candidate value, and front-load benefits.

Universal JD Structure

Every JD follows this structure. Sections can be reordered or renamed to match company style, but all components should be present.

Information priority (what candidates scan for, in order — per LinkedIn research):

1. Title, salary, location — decides whether they keep reading
2. Personal benefits — "why is this better than where I am now?"
3. Role clarity — what they'll actually do (outcomes, not tasks)
4. Fit assessment — can I do this? (requirements)
5. Response ease — how to apply

1. The Opportunity

The hook. 2-4 sentences answering: why does this role exist, and why should someone care?

Most candidates — especially passive ones — skim-read. Research (LinkedIn heatmap studies) shows they decide whether to keep reading within the first 2-3 lines. Front-load what matters: title, location, salary signal, and the hook.

• Lead with impact, not the company's need
• Name the problem space, not generic responsibilities
• Make it specific enough that the wrong candidate self-selects out

Hook techniques that work:

• Frustration hook — Name what's wrong with their current situation: "If you're tired of being the 'doer' in a rigid marketing machine, this is your chance to be the architect."
• Scale/problem hook — Show the challenge: "Our payments infrastructure processes $2B daily across 40 countries. You'll own the reliability layer."
• Honest-gap hook — Admit what's broken: "Our CFO has been building models in spreadsheets between board meetings. You'll build FP&A from scratch."
• Ownership hook — Lead with autonomy: "You'll decide what we charge, how we charge it, and build the systems behind it."

Bad: "We're looking for a talented engineer to join our growing team."

2. What You'll Do

5-8 outcomes, not tasks. Frame as "what changes because you're here" not "daily to-do list."

Rules:

• Start each bullet with an outcome verb (build, own, lead, design, ship), not a task verb (write, attend, update, maintain)
• Include scope signals: team size, budget, revenue, user count
• Show autonomy level: "you'll decide" vs "you'll contribute to"
• Max 8 bullets — if you need more, the role might be two roles

3. AI-First in [Function]

Required for every JD. QuoIntelligence is AI-native. Every role should signal how AI shapes the work in that function.

Title the section "AI-First in [Function]" (e.g., "AI-First in Marketing", "AI-First in Engineering"). Open with a one-line framing: AI is an operating principle here.

Rules:

• 3-5 principles specific to how AI applies to this role's function
• Pull company-level AI philosophy from talent-sourcing.local.md and adapt per function
• Be concrete: "You'll use AI tools to [specific task]" not "We value AI"
• Include product fluency expectation if the role touches customers or positioning
• Include data/measurement principle (decisions based on data, not gut)
• Include responsible AI use (accurate claims, defensible positioning)

What to avoid:

• Generic AI hype ("cutting-edge AI", "revolutionary technology")
• Implying AI replaces the person
• Buzzword stacking without concrete expectations
• More than 5 principles (diminishing returns; pick the ones that matter for this function)

4. What You'll Bring

Split into must-haves (3-5) and nice-to-haves (3-5). Frame as capabilities, not credentials.

Rules:

• Capabilities over credentials: "can design distributed systems" over "10 years Java experience"
• Evidence over claims: "have shipped production ML models" over "strong ML skills"
• Transferable skills over specific tools: "modern data orchestration" over "must know Airflow"
• Each must-have should be genuinely required — if you'd interview someone without it, it's a nice-to-have
• Always include AI fluency as a must-have: active use of AI tools in their function, ability to evaluate new ones critically. Adapt the framing per role family.
• Include one "unfair advantage" nice-to-have that reveals what would make someone exceptional

5. What We Offer

Team, culture, growth, comp philosophy. Be specific and honest.

Rules:

• Name concrete specifics, not generic perks ("20% time for open source" not "great engineering culture")
• Include comp philosophy or range if authorized (candidates filter on this; omitting it costs applicants)
• Mention team size, reporting structure, collaboration model
• Growth: where does this role lead? What will they learn?

6. About [Company]

Brief, honest, differentiated. 2-3 sentences max.

Rules:

• What you do, for whom, and why it matters — in plain language
• One differentiator that's actually true (not "we're innovative")
• Traction signal if available (revenue, users, funding, customers)
• Pull from talent-sourcing.local.md company context

7. How to Apply / The Process (Optional)

If included, set expectations: how many interview stages, timeline, what to prepare.

Quality Checklist

Before saving the JD, verify:

• The Opportunity section would make someone stop scrolling
• "What You'll Do" uses outcomes, not tasks
• Must-haves are genuinely required (would you reject a perfect candidate missing one?)
• No requirement inflation (years > technology age, degree when unnecessary)
• Inclusive language review completed (Step 5)
• Sensitive information review completed (Step 6)
• Stop-slop pass completed (Step 7)
• AI-First section included with function-specific principles
• Company-specific details pulled from config (not generic placeholders)
• Total length: 500-800 words (long enough to inform, short enough to read)
• A qualified candidate can tell within 30 seconds if this role is for them

Output

Save the completed JD to:

roles/[role-name]/jd.md

If the role directory doesn't exist, create it:

mkdir -p roles/[role-name]/candidates roles/[role-name]/reports

Reference Files

You are stongly encouraged to read the reference files

• references/anti-patterns.md — Before/after examples of common JD mistakes to avoid: vague requirements, task lists, requirement inflation, jargon, and more.
• references/inclusive-language.md — Comprehensive bias detection checklist organized by type: gendered, age-coded, ability-coded, culture-coded, and requirement inflation.
• references/jd-examples.md — Annotated examples of effective JD sections across role families, with margin notes explaining what works and why.