| 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:
| Input Available | Action |
|---|
brief.md exists | Extract role requirements, HM preferences, team context |
| Raw HM requirements dump | Parse into structured components, ask clarifying questions for gaps |
| Existing JD to rewrite | Analyze against quality standards, rewrite weak sections |
| Role title only | Ask focused questions: level, scope, team, impact, key requirements |
talent-sourcing.local.md | Pull company name, EVP, culture signals, comp philosophy |
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:
| Component | Question to Answer |
|---|
| Title | What would the right candidate search for? Use market-standard titles, not internal jargon. |
| Level | Junior / Mid / Senior / Staff / Principal / Director / VP? Map to clear scope indicators. |
| Scope | Individual contributor or people leader? How much autonomy? Decision-making authority? |
| Team | Who do they work with daily? What's the team's mission? |
| Impact | What changes because this person exists? What doesn't happen without them? |
| Growth | Where does this role lead in 2-3 years? |
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:
| Context | Lean toward |
|---|
| Competitive talent market, passive candidates | Candidate-centric (default) |
| Employer brand is strong, high inbound volume | Balanced |
| Exec/leadership hire | Balanced to company-centric (mission-first) |
outreach_tone in config is professional-warm | |
Step 4: Adapt by Role Family
Each section of the JD shifts emphasis depending on the role family. Use the adaptation table:
| Section | Engineering | Data/ML | Product | Design | GTM/Sales | Ops/Finance |
|---|
| The Opportunity | Technical challenge, scale, stack | Data problems, model impact, research vs. applied | Product scope, user impact, market | Design maturity, user research, craft | Market, quota, territory, growth | Process impact, scale, transformation |
| What You'll Do | Systems built, problems solved | Pipelines, models, experiments | Decisions owned, roadmap scope | Experiences shaped, research led | Revenue driven, relationships built | Operations improved, risks managed |
| What You'll Bring | Skills + tools, not years | Techniques + domain, not degrees | Judgment + track record, not titles | Portfolio + process, not tools | Results + methodology, not tenure | Expertise + frameworks, not certifications |
| What We Offer | Tech stack, engineering culture, ownership | Data infrastructure, research culture, publication | Product influence, customer access, autonomy | Design system, research budget, craft culture | Comp plan, territory quality, enablement | Career path, exposure, influence scope |
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):
- Title, salary, location — decides whether they keep reading
- Personal benefits — "why is this better than where I am now?"
- Role clarity — what they'll actually do (outcomes, not tasks)
- Fit assessment — can I do this? (requirements)
- 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:
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.
