Redactor de descripciones de puesto con Claude

---
name: jd-writer
description: Interview a hiring manager about a new role and produce a structured, skills-based, jurisdiction-aware job description draft ready for recruiter review. Use this skill at the moment a role is opened, before any sourcing or posting.
---

# JD writer

## When to invoke

Whenever a hiring manager has decided to open a role and you need a usable JD within the same working day. Take a role title plus level, the manager's intake notes, and the target jurisdiction as input, then produce a structured Markdown JD that a recruiter can edit and post.

Do NOT invoke this skill for:

- Auto-publishing a JD to a careers site or job board without recruiter review
- Roles that include compensation in jurisdictions that require pay-range audits (NYC §8-1402, CA SB 1162, CO Equal Pay Act) before public posting — produce the draft, but route it to compliance, not the publishing API
- Internal-mobility postings (different voice, different EEO requirements, use the mobility-template skill instead)
- Backfills where the prior JD is still accurate (just refresh the prior JD's `last_reviewed` date — don't redraft)

## Inputs

- Required: `role` — title plus level (e.g. `Senior Backend Engineer`, `Director of Marketing Operations`). Title alone is insufficient.
- Required: `intake_notes` — free-text notes from the hiring-manager intake call. The skill interviews against these, not from a blank canvas.
- Required: `jurisdiction` — primary posting jurisdiction (e.g. `US-NY`, `US-CA`, `US-CO`, `EU-DE`, `UK`). Drives the compliance footer.
- Optional: `comparables` — paths or URLs to 1-3 comparable JDs, internal or external. The skill uses these for voice and structure calibration.
- Optional: `icp_candidate` — short description of the target candidate shape (years of experience band, prior-company patterns, motion). Used to tune must-have vs nice-to-have language.
- Optional: `pay_range` — min/max in local currency. Required if `jurisdiction` matches a pay-transparency state.
- Optional: `comp_philosophy` — one paragraph on equity, bonus, benefits. Reused across roles so usually loaded once.

## Reference files

Always read the following from `references/` before drafting. They contain the user's role-family templates, biased-language blocklist, and jurisdiction matrix. Without them the draft is generic.

- `references/1-role-family-templates.md` — JD scaffolds per role family (engineering, sales, marketing, ops, leadership). Replace contents with your team's actual scaffolds.
- `references/2-biased-language-blocklist.md` — terms to flag and the neutral substitutions to suggest. Replace contents with your team's actual blocklist; the defaults are a starting point.
- `references/3-jurisdiction-matrix.md` — per-jurisdiction compliance requirements (pay disclosure, EEO statement, accommodation language, application-data restrictions). Replace contents with your team's legal-reviewed matrix.

## Method

Run these five sub-tasks in order. Do not parallelize — the bias screen must run on the actual draft, and the jurisdiction check must run on the actual compensation language.

### 1. Interview against the intake notes

Read the intake notes, then ask the hiring manager 5-8 targeted clarifying questions. Topic order: scope and ownership, success at 12 months as a measurable outcome, the team context, must-have vs nice-to-have skills articulated as observable behaviors, the realistic day-to-day, the parts of the role that are hardest. Why intake-notes-first rather than template-first: starting from the template biases toward generic responsibilities; starting from the manager's own framing surfaces what makes this role specific to this team at this moment.

### 2. Map to the role-family scaffold

Match the role to the closest scaffold in `references/1-role-family-templates.md`. Use the scaffold for section order and headers, not for content. Why a scaffold rather than a free form: recruiters and candidates skim JDs in a predictable pattern; consistent structure raises completion rate on application forms.

### 3. Draft skills-based requirements

Convert each "must have" into an observable skill or outcome statement, not a credential. "5+ years at FAANG" becomes "designed and operated distributed systems at over 10M requests per day." "CS degree required" becomes "demonstrable systems-design fluency, by interview or portfolio, degree not required." Why skills-based: credential-laden requirements shrink the candidate pool by 40-60% without raising hire quality, per public BCG and Burning Glass studies. The skill should refuse to write "X years experience required" without a specific outcome justification.

### 4. Bias-screening pass

Run the entire draft against `references/2-biased-language-blocklist.md`. Flag every match and propose a neutral substitution. Common categories: gendered terms (rockstar, ninja, aggressive), age-coded terms (digital native, recent graduate, energetic), ableist defaults (must be able to stand for 8 hours when role is desk-based), culture-fit framings that proxy for in-group preference. Why a separate pass rather than inline screening: bias terms cluster in revisions, not first drafts — post-draft screening catches them more reliably than during-draft self-monitoring.

### 5. Jurisdiction-and-compliance check

Look up the `jurisdiction` value in `references/3-jurisdiction-matrix.md`. Insert the required pay-range disclosure, EEO statement, accommodation language, and any application-data restrictions verbatim from the matrix. If the jurisdiction requires a pay range and `pay_range` was not supplied, emit a TODO block in place of the comp section and surface the missing input at the top of the output.

## Output format

```markdown
# {Role title} — {Level}

> Draft generated by jd-writer skill on {YYYY-MM-DD}. Recruiter review
> required before posting. Jurisdiction: {jurisdiction}.

## About the role

Two to three sentences on what the role does and why it matters to the
team's twelve-month plan. Names the team and the closest collaborators.

## What you'll do

- {Outcome-framed responsibility 1}
- {Outcome-framed responsibility 2}
- {Outcome-framed responsibility 3}
- {Outcome-framed responsibility 4}
- {Outcome-framed responsibility 5}

## What we're looking for — must have

- {Observable skill or outcome 1}
- {Observable skill or outcome 2}
- {Observable skill or outcome 3}

## What we're looking for — nice to have

- {Observable skill or outcome 1}
- {Observable skill or outcome 2}

## About the team

One paragraph: team mission, who the role works with day to day, what
the team is shipping in the next two quarters.

## Compensation and benefits

- Salary range: {currency min}–{currency max} (per
  {jurisdiction} pay-transparency requirements)
- Equity: {band}
- Bonus: {structure}
- Benefits: {summary linking to benefits page}
- Location: {remote / hybrid / on-site} — {office locations or remote
  regions}

## Equal employment opportunity

{Verbatim EEO statement from references/3-jurisdiction-matrix.md for
the target jurisdiction.}

## Accommodations

{Verbatim accommodation statement from
references/3-jurisdiction-matrix.md.}

## How to apply

Apply via {URL}. Application deadline: {date or rolling}. Expected
process: {N stages, named, with rough timing}.
```

## Watch-outs

- **Gendered or coded language slips back in during edits.** The bias-screening pass is run on the first draft; if the recruiter rewrites a section, the pass should be rerun. Guard: the skill emits a "rerun-bias-screen" hint as the last line of every output, and refuses to mark a JD `bias_checked: true` without an explicit re-screen call.
- **Unrealistic must-haves balloon when the manager is a domain expert.** Engineers writing engineering JDs tend to list every tool they personally use as a must-have. Guard: the skill caps must-haves at five and forces anything beyond that into nice-to-have, with the manager's explicit override required to exceed the cap.
- **Pay-range omission in regulated jurisdictions.** Posting without a range in NYC, CA, CO, WA, IL (eff. 2025) triggers per-violation fines. Guard: when `jurisdiction` matches the regulated list and `pay_range` is missing, the skill replaces the comp section with a blocking TODO and refuses to emit a "ready-to-post" status.
- **Voice mismatch with employer brand.** Generic Claude defaults read as generic JDs. Guard: the skill requires at least one comparable JD in `comparables` and refuses to draft without it; the comparable is used as the voice anchor, not just for structure.
- **Length creep.** Job descriptions over 600 words get skim-read; hire-quality drops as length grows. Guard: the skill targets 400 words for individual-contributor roles, 550 for leadership, and emits a word-count footer with a warning above the cap.

# Role-family JD scaffolds — TEMPLATE

> Replace the contents of this file with your team's actual scaffolds.
> The jd-writer skill reads this file on every run and uses it for
> section ORDER, not for section CONTENT — content comes from the
> hiring-manager interview. Without your real scaffolds, every JD reads
> the same.

Each scaffold lists section headers in the order recruiters expect to see them for that role family. Add or remove sections per family — the defaults below are starting points.

## Engineering (IC)

1. About the role
2. What you'll do
3. What we're looking for — must have
4. What we're looking for — nice to have
5. Tech stack you'll work with
6. About the team
7. Compensation and benefits
8. Equal employment opportunity
9. Accommodations
10. How to apply

Notes: Tech stack section sits before "About the team" because engineers skim for it first. Cap must-haves at five. Avoid version numbers (Python 3.11+) — they age the JD fast.

## Engineering (leadership: EM, director, VP)

1. About the role
2. What success looks like in 12 months
3. What you'll do
4. What we're looking for — must have
5. What we're looking for — nice to have
6. About the team and org context
7. Compensation and benefits
8. Equal employment opportunity
9. Accommodations
10. How to apply

Notes: Lead with the 12-month outcome, not the responsibilities — senior candidates evaluate on scope and mandate before tactics. "About the team" expands to org context (reports up, dotted lines, peer functions).

## Sales (IC: AE, AM, SDR)

1. About the role
2. What you'll do
3. What we're looking for — must have
4. What we're looking for — nice to have
5. Quota, comp plan, and territory
6. About the team
7. Compensation and benefits
8. Equal employment opportunity
9. Accommodations
10. How to apply

Notes: Quota and territory sit above "About the team" because they're the deciding inputs for sales candidates. Comp section then expands the OTE math.

## Marketing (IC and leadership)

1. About the role
2. What you'll do
3. What we're looking for — must have
4. What we're looking for — nice to have
5. About the team and how marketing partners with sales/product
6. Compensation and benefits
7. Equal employment opportunity
8. Accommodations
9. How to apply

Notes: Always include the cross-functional partnership context — marketing candidates evaluate the partnership shape as much as the mandate.

## Operations (RevOps, MarketingOps, SalesOps, BizOps)

1. About the role
2. What you'll do
3. The systems you'll own
4. What we're looking for — must have
5. What we're looking for — nice to have
6. About the team
7. Compensation and benefits
8. Equal employment opportunity
9. Accommodations
10. How to apply

Notes: "Systems you'll own" (Salesforce, HubSpot, Marketo, dbt, etc.) is the deciding section for ops candidates. List the actual systems, not categories.

## Cross-family rules

- Every scaffold ends with EEO + accommodations + how-to-apply, in that order. The jurisdiction-matrix file supplies the verbatim language for the first two.
- "Compensation and benefits" is always present. The jurisdiction-matrix file decides whether the pay range is mandatory.
- "What we're looking for" is always split into must-have and nice-to-have. Combining them is the single most common source of candidate-pool shrinkage.

# Biased-language blocklist — TEMPLATE

> Replace the contents of this file with your team's actual blocklist.
> The defaults below are a starting point drawn from public bias-in-JD
> research (Gaucher et al. 2011, Textio 2023 benchmarks). The jd-writer
> skill flags every match found in a draft and suggests a neutral
> substitution.

Format: each row is `term | category | suggested substitution | reason`. The skill matches case-insensitively on whole words.

## Gendered terms

| Term | Category | Substitution | Reason |
|---|---|---|---|
| rockstar | masculine-coded | high-performing | clusters in male applicants per Gaucher |
| ninja | masculine-coded | skilled practitioner | same |
| guru | masculine-coded | expert | same |
| aggressive | masculine-coded | proactive / driven | same |
| dominant | masculine-coded | leading / strong | same |
| competitive | masculine-coded | results-oriented | same |
| nurturing | feminine-coded | supportive | same |
| sympathetic | feminine-coded | empathetic | same |
| loyal | feminine-coded | committed | same |

## Age-coded terms

| Term | Category | Substitution | Reason |
|---|---|---|---|
| digital native | age-coded (young) | comfortable with web tooling | proxies for under-30 |
| recent graduate | age-coded (young) | early-career | same |
| energetic | age-coded (young) | engaged | same |
| young | age-coded (young) | early-career | direct violation in US |
| seasoned | age-coded (older) | experienced | proxies for over-50 |
| mature | age-coded (older) | experienced | same |

## Ableist defaults

| Term | Category | Substitution | Reason |
|---|---|---|---|
| must be able to stand | ableist if desk-based | remove unless physical | ADA-relevant |
| must lift X lbs | ableist if desk-based | remove unless physical | ADA-relevant |
| see clearly / hear clearly | ableist | remove unless safety-critical | ADA-relevant |
| crazy hours | ableist + culture-flag | demanding workload (with hours stated) | same |

## Culture-fit proxies

| Term | Category | Substitution | Reason |
|---|---|---|---|
| culture fit | in-group proxy | values alignment with {specific value} | well-documented bias vector |
| we work hard, play hard | in-group proxy | remove or specify hours | same |
| family | in-group proxy | team | same |
| like-minded | in-group proxy | aligned on {specific principle} | same |
| native English speaker | nationality proxy | strong professional English | direct EEOC concern in US |

## Credential-laden defaults

| Term | Category | Substitution | Reason |
|---|---|---|---|
| Ivy League | credential proxy | strong undergraduate background | proxies for class |
| top-tier university | credential proxy | strong undergraduate background | same |
| FAANG | credential proxy | experience at scale (state the scale) | proxies for in-network |
| 10+ years experience | credential proxy | demonstrated outcome at this scope | shrinks pool 40-60% |

## Override mechanism

Some terms in this list are unavoidable in some roles (e.g. "must lift 50lbs" for a warehouse role). The skill accepts an inline override of the form `<!-- jd-writer:keep "<term>" reason="<reason>" -->` placed immediately above the line. The override and reason are preserved in the final draft for recruiter review.

## Last edited

{YYYY-MM-DD}

# Jurisdiction compliance matrix — TEMPLATE

> Replace the contents of this file with your team's legal-reviewed
> matrix. The defaults below reflect public legislation as of mid-2025
> but are not legal advice and will age. The jd-writer skill reads
> this file on every run and inserts the verbatim language for the
> target jurisdiction.

For each jurisdiction, the matrix supplies four blocks: pay-disclosure rule, EEO statement (verbatim), accommodation statement (verbatim), and application-data restrictions (e.g. salary-history ban). The skill copies the verbatim blocks into the JD output without paraphrasing.

## US-NY (New York City + New York State)

- **Pay disclosure**: Required. Must include good-faith minimum and maximum annual salary range for the role. NYC Local Law 32 / NY State S9427A.
- **EEO statement**: `{Company}` is an equal opportunity employer. All qualified applicants will receive consideration for employment without regard to race, color, religion, sex, sexual orientation, gender identity or expression, national origin, age, disability, marital status, veteran status, or any other characteristic protected by federal, state, or local law.
- **Accommodation statement**: `{Company}` is committed to providing reasonable accommodations to qualified individuals with disabilities. If you require an accommodation during the application or interview process, please contact `{accommodations email}`.
- **Application-data restrictions**: Salary-history inquiries prohibited. Do not include "What is your current salary?" on application forms.

## US-CA (California)

- **Pay disclosure**: Required for employers with 15+ employees. Must include pay scale (range). SB 1162.
- **EEO statement**: as US-NY, with the addition of "or any characteristic protected under California Fair Employment and Housing Act."
- **Accommodation statement**: as US-NY.
- **Application-data restrictions**: Salary-history inquiries prohibited (Labor Code §432.3). Ban-the-box: criminal-history inquiry only after conditional offer.

## US-CO (Colorado)

- **Pay disclosure**: Required. Must include hourly or salary compensation, a general description of bonuses/commissions, and a general description of benefits. Equal Pay for Equal Work Act.
- **EEO statement**: as US-NY.
- **Accommodation statement**: as US-NY.
- **Application-data restrictions**: Salary-history inquiries prohibited.

## US-WA (Washington)

- **Pay disclosure**: Required for employers with 15+ employees. Must include wage scale or salary range, and a general description of benefits and other compensation. RCW 49.58.110.
- **EEO statement**: as US-NY.
- **Accommodation statement**: as US-NY.
- **Application-data restrictions**: Salary-history inquiries prohibited.

## US-IL (Illinois, eff. 2025)

- **Pay disclosure**: Required for employers with 15+ employees. Must include pay scale and benefits. PA 103-0539.
- **EEO statement**: as US-NY.
- **Accommodation statement**: as US-NY.
- **Application-data restrictions**: Salary-history inquiries prohibited.

## US-other (federal floor)

- **Pay disclosure**: Not required by federal law. Recommended for consistency.
- **EEO statement**: as US-NY (federal characteristics only).
- **Accommodation statement**: as US-NY.
- **Application-data restrictions**: Federal floor only. Check state and city law before posting.

## EU-DE (Germany)

- **Pay disclosure**: Not required at posting. Required on request under Entgelttransparenzgesetz for employers with 200+ employees.
- **EEO statement**: `{Company}` ist Arbeitgeber, der Chancengleichheit fördert. Wir berücksichtigen alle qualifizierten Bewerber unabhängig von Rasse, Hautfarbe, Religion, Geschlecht, sexueller Orientierung, Geschlechtsidentität, nationaler Herkunft, Alter, Behinderung, Familienstand oder Veteranenstatus.
- **Accommodation statement**: as US-NY, German equivalent.
- **Application-data restrictions**: Photo and date-of-birth on application discouraged under AGG. Do not request.

## UK

- **Pay disclosure**: Not legally required at posting (consultation ongoing). Recommended.
- **EEO statement**: `{Company}` is committed to equal opportunities and welcomes applications from all sections of the community, regardless of age, disability, gender reassignment, marriage and civil partnership, pregnancy and maternity, race, religion or belief, sex, or sexual orientation.
- **Accommodation statement**: Reasonable adjustments available on request — contact `{accommodations email}`.
- **Application-data restrictions**: GDPR / UK GDPR compliance required for any data collected.

## Regulated-jurisdictions list

These jurisdictions require pay-range disclosure. The jd-writer skill treats this list as the trigger for the "pay-range missing" guard:

- US-NY
- US-CA
- US-CO
- US-WA
- US-IL

## Last edited

{YYYY-MM-DD} — review quarterly. This matrix is a starting point, not legal advice. Have employment counsel review before relying on it for posting.