Un Claude Skill qui prend le niveau d’un poste, sa localisation géographique, et un export d’enquête de rémunération (Radford, Pave, Carta), et produit une recommandation de fourchette salariale structurée par composante (salaire de base, equity, bonus / OTE) avec le percentile nommé, la citation de l’enquête source, et les notes de calibration que le recruteur apporte à l’appel d’offre. Il remplace la jonglerie de feuilles de calcul et d’onglets ouverts par un document unique que le hiring manager et l’approbateur finance peuvent valider. Publie la fourchette publique (conforme NYC LL 32-A, CO/CA/WA pay-transparency) comme sortie distincte.
Quand utiliser
Vous publiez un nouveau poste et avez besoin d’une fourchette publique défendable (pas le vague « standard du marché », pas « 75e percentile » sans nommer l’enquête ni la géographie).
Vous préparez une offre et avez besoin de la fourchette que le hiring manager peut approuver sans une demi-journée d’aller-retour avec finance.
Vous auditez les fourchettes salariales existantes chaque trimestre et souhaitez une comparaison structurée de « ce que nous payons » vs. « ce que dit l’enquête » par famille de postes.
Quand NE PAS utiliser
Décisions salariales unilatérales en dehors d’une chaîne d’approbation validée. Le skill produit une recommandation. La philosophie de rémunération et la matrice d’approbation appartiennent aux RH / Finance / Comité de rémunération. Le skill les informe ; il ne les remplace pas.
Rémunération en equity pour les startups pré-Série B. Le benchmark equity à un stade très précoce dépend davantage de la cap table spécifique et du chemin de dilution que des données de marché. Les chiffres des enquêtes ne s’y appliquent pas.
Génération de scripts de négociation. Le skill produit une fourchette ; il ne rédige pas de langage de négociation. Un langage de négociation salariale auto-généré sonne froid et nuit à l’expérience candidat.
Décisions d’exception spécifiques à un candidat. « Peut-on offrir 15 % au-dessus de la fourchette pour ce candidat ? » est une question pour le hiring manager et la finance, pas pour le skill. Le skill informe en remontant la fourchette ; il n’approuve pas les exceptions.
Géographies où l’enquête a peu de données. Les enquêtes couvrent bien les États-Unis, l’UE et les principaux marchés APAC ; les données des marchés émergents (LatAm, Afrique, APAC secondaire) sont plus limitées. Le skill signale les géographies à faible effectif dans la sortie.
Configuration
Déposer le bundle. Placez apps/web/public/artifacts/compensation-benchmark-skill/SKILL.md dans votre répertoire de skills Claude Code.
Configurer la source d’enquête. Le skill lit les exports de Radford, Pave, Carta, ou un CSV personnalisé. Le schéma par source vit dans references/1-survey-source-schemas.md. Le skill n’appelle pas directement les API d’enquête — les exports passent par le chemin d’accès approuvé de votre analyste en rémunération.
Définir la philosophie de rémunération de l’entreprise. À quel percentile l’entreprise se positionne-t-elle (50e, 60e, 75e) ? Le salaire de base + equity vise-t-il un percentile cible, ou chaque composante est-elle calibrée séparément ? La philosophie vit dans references/2-comp-philosophy-template.md et constitue l’entrée contre laquelle le skill se calibre.
Configurer la sortie de la chaîne d’approbation. Le skill émet la fourchette publique comme sortie distincte (conforme NYC LL 32-A, CO/CA/WA pay-transparency). Connectez cette sortie à votre étape de publication d’offre d’emploi (description de poste Greenhouse / Ashby), ou copiez manuellement, selon le processus de votre équipe.
Exécution à blanc sur une offre clôturée. Benchmarkez un poste clôturé le trimestre dernier. Comparez la fourchette du skill avec l’offre réellement faite. Si l’écart est important, soit l’export d’enquête est hors cycle, soit le fichier de philosophie de l’entreprise ne correspond pas à la façon dont les offres sont réellement approuvées.
Ce que le skill fait réellement
Cinq étapes. L’ordre maintient les recherches d’enquête déterministes avant la calibration pilotée par le LLM, car laisser le modèle paraphraser les chiffres d’enquête introduit une dérive que le recruteur ne peut pas auditer.
Valider la définition du rôle. Vérifier que le niveau, la géographie et la fonction du rôle sont présents et correspondent aux valeurs dans l’export d’enquête. Arrêt sur les champs manquants ou ambigus (« Senior Engineer » sans niveau sur l’échelle de l’entreprise est ambigu).
Rechercher les percentiles d’enquête. Recherche déterministe, pas LLM. Pour chacun des salaires de base, equity (annualisé), et bonus / OTE, extraire les percentiles 25e / 50e / 60e / 75e / 90e de l’export d’enquête pour la cellule (niveau, géographie, fonction) correspondante. Si la cellule a moins que le seuil de taille d’échantillon documenté de l’enquête (varie par enquête : Radford typiquement 5+, Pave typiquement 10+), signaler faible-N et refuser de recommander une fourchette basée sur les percentiles — se replier sur une cellule plus large (niveau, fonction) sans géographie ou sur une géographie élargie (ex. « États-Unis entiers » plutôt que « Bay Area »).
Calibrer contre la philosophie de l’entreprise. Lire la philosophie de rémunération. Appliquer le percentile cible aux chiffres de l’enquête. La sortie est une fourchette structurée par composante :
Salaire de base : target_pct de l’enquête, avec une plage de ±10 % pour absorber la variation au niveau du candidat.
Equity : idem ; convertir en valeur dollar au prix d’exercice de l’entreprise pour les nouvelles attributions, documenter le calcul.
Bonus / OTE : target_pct sur l’OTE ; diviser base/variable selon le ratio de l’entreprise pour la fonction.
Composer la fourchette publique. Conformément aux exigences de transparence salariale NYC LL 32-A et CO/CA/WA, la publication publique nécessite une fourchette de salaire de base. Par défaut : « minimum du bord inférieur de la fourchette au maximum du bord supérieur, exprimé comme fourchette salariale unique. » Si le rôle chevauche des États américains avec des seuils de loi de transparence différents, la fourchette la plus large s’applique. Le skill émet cette information comme sortie distincte pour utilisation directe dans la description de poste.
Émettre le rapport de recommandation + enregistrement d’audit. Le rapport contient : les fourchettes par composante avec le percentile cité et l’enquête source, les notes de calibration, les avertissements faible-N ou données limitées, et la fourchette publique. L’enregistrement d’audit est une ligne JSONL : rôle, géographie, niveau, percentile ciblé, source d’enquête, date d’export, fourchette recommandée — pour l’audit d’équité salariale de l’entreprise plus tard dans l’année.
Réalité des coûts
Par rôle benchmarké, sur Claude Sonnet 4.6 :
Tokens LLM — typiquement 5 à 8 000 tokens en entrée (définition du rôle + lignes d’export d’enquête + philosophie + instructions du skill) et 1 à 2 000 tokens en sortie (rapport structuré). Environ 0,04 à 0,08 $ par rôle. Négligeable.
Coût d’accès aux enquêtes — les abonnements aux enquêtes eux-mêmes sont le coût contraignant (Radford, Pave, Carta vont de 15 000 à 80 000 $+ annuels selon la couverture). Le skill suppose que l’analyste en rémunération dispose déjà de l’accès ; il ne change pas ce calcul.
Temps recruteur / analyste en rémunération — le gain. Composer manuellement une recommandation de rémunération prend 30 à 90 minutes par rôle (recherche d’enquête + jonglerie de tableur + application de la philosophie + rédaction de la note de calibration). Le skill prend 5 à 10 minutes, vérification à blanc incluse.
Temps de configuration — 30 minutes une fois pour le fichier de philosophie et l’intégration de l’export d’enquête. Le fichier de philosophie est rarement révisé ; les exports d’enquête se rafraîchissent chaque trimestre.
Mesure de succès
Suivez trois chiffres, chaque trimestre :
Taux d’acceptation des offres dans les 3 semaines — une rémunération calibrée entraîne l’acceptation. En dessous de 60 % dans votre géographie, vous sous-payez ; au-dessus de 90 %, vous pourriez sur-payer. Les deux directions comptent ; le bon chiffre dépend de la philosophie de rémunération de l’entreprise (les startups à fort equity acceptent une base plus faible ; les entreprises en phase de croissance à forte base acceptent une base plus élevée).
Taux d’édition des fourchettes post-skill — part des fourchettes recommandées par le skill que le hiring manager ou la finance modifie avant approbation. Devrait se situer à 10 à 25 %. Au-dessus de 40 %, le fichier de philosophie ne reflète pas le comportement réel d’approbation ; en dessous de 5 %, la commission entérine (le mode d’échec contre lequel le skill est conçu).
Dérive d’audit d’équité salariale — lors de la revue annuelle d’équité salariale, les recommandations du skill corrèlent-elles avec les offres réelles faites ? Si l’audit fait apparaître des écarts d’équité que les recommandations du skill auraient comblés, le skill fait son travail ; si l’audit fait apparaître des écarts que les recommandations du skill auraient creusés, le fichier de philosophie ou la calibration est biaisé.
Par rapport aux alternatives
vs rapports Pave / Carta / Radford / Mercer directement. Les rapports sont les données sources ; le skill les compose en une recommandation par rôle. Choisissez les rapports seuls si votre analyste en rémunération y vit et que le recruteur ne consomme que « dites-moi le 75e ». Choisissez le skill si le recruteur a besoin de la note de calibration + fourchette publique + enregistrement d’audit sans l’analyste dans la boucle pour chaque rôle.
vs style ChatGPT « que devrais-je payer un senior engineer à New York ». Le chat générique retourne des données d’enquête paraphrasées sans piste d’audit ni source versionnée — ce n’est pas défendable lors d’un audit d’équité salariale. Le skill cite l’export d’enquête par nom et date.
vs modèles de feuilles de calcul. Les modèles fonctionnent jusqu’au moment où la philosophie de l’entreprise change ou que l’export d’enquête se rafraîchit ; ensuite, chaque modèle sauvegardé devient silencieusement obsolète. Le skill lit à partir des sources actuelles à chaque exécution.
vs aucun benchmark. La situation par défaut dans beaucoup de petites entreprises. Mode d’échec prévisible : les écarts d’équité salariale apparaissent lors de l’audit annuel, et le recruteur est tenu responsable d’offres individuelles qui correspondaient à la pratique normale de l’entreprise. Un benchmark défendable est l’intervention la moins coûteuse contre cela.
Points de vigilance
Obsolescence des exports d’enquête.Garde : le skill lit les métadonnées datées de l’export et avertit si l’export est antérieur à 6 mois. Les données d’enquête évoluent plus vite qu’annuellement ; le rafraîchissement trimestriel est le minimum.
Mauvaise correspondance géographique.Garde : le skill fait correspondre la géographie du rôle à la taxonomie géographique de l’enquête explicitement (« SF Bay Area » de Pave n’est pas la même cellule que « San Francisco MSA » de Radford). Si la correspondance est ambiguë, le skill s’arrête et demande au recruteur de lever l’ambiguïté plutôt que de choisir une valeur par défaut.
Cellule faible-N.Garde : le skill refuse de recommander une fourchette basée sur les percentiles lorsque la cellule d’enquête a moins de répondants que le seuil documenté de l’enquête. Il se replie sur une cellule plus large (fonction plus large, géographie plus large) et note le repli.
Dérive de la comparaison equity.Garde : les valeurs equity sont annualisées et converties au prix d’exercice actuel de l’entreprise. Le calcul de conversion est documenté dans le rapport. L’enregistrement d’audit stocke les valeurs brutes et converties afin que les audits futurs puissent les dériver à nouveau.
Fourchette publique trop étroite.Garde : si la fourchette publique est si étroite qu’elle fonctionne comme un seul chiffre, le skill avertit. Publier « 140 000 $-145 000 $ » est une violation de l’esprit (et probablement de la lettre) de NYC LL 32-A, qui exige une fourchette de « bonne foi ». Le skill applique une largeur de fourchette minimale par géographie.
Propagation des biais à travers la rémunération historique.Garde : si le fichier de philosophie de l’entreprise est calibré par « correspondre à ce que nous avons payé dans cette fourchette auparavant », le skill propage les écarts salariaux existants dans les données historiques. Le skill signale cela lorsque la correspondance de philosophie suit de près la rémunération historique plutôt que les percentiles d’enquête, et recommande à l’analyste en rémunération d’effectuer une vérification distincte d’équité salariale.
Stack
Le bundle du skill se trouve dans apps/web/public/artifacts/compensation-benchmark-skill/ et contient :
---
name: compensation-benchmark
description: Take a role's level/geography/function plus a comp-survey export (Radford, Pave, Carta, or custom CSV), and produce a structured pay-band recommendation per component (base, equity, OTE) with cited percentiles, calibration against the firm's philosophy, and a public-facing range compliant with NYC LL 32-A and CO/CA/WA pay-transparency requirements. Never approves an offer; never auto-publishes.
---
# Compensation benchmark
## When to invoke
Use this skill when a recruiter or comp analyst needs a per-role pay band based on a survey export and the firm's comp philosophy. Take a role definition, a survey export, and the philosophy file as input and return a structured benchmark report plus a public-facing range.
Do NOT invoke this skill for:
- **Unilateral comp decisions outside the firm's approval matrix.** The skill recommends; People Ops / Finance / Comp Committee approve.
- **Equity at pre-Series-B startups.** Survey data is too thin and firm-cap-table-specific at that stage.
- **Negotiation-script generation.** Different workflow.
- **Approving exception bands** ("can we go 15% above?"). The skill informs; the hiring manager and finance approve.
## Inputs
- Required: `role_definition` — JSON with `level` (firm's ladder, e.g. `L5`), `geography` (e.g. `San Francisco MSA`), `function` (e.g. `software-engineering`).
- Required: `survey_export` — path to a survey export. Schema must match one in `references/1-survey-source-schemas.md`.
- Required: `philosophy` — path to the firm's compensation philosophy file. See `references/2-comp-philosophy-template.md`.
- Optional: `candidate_signal` — free-text note about the candidate (current comp, competing offers, etc.). Used in the calibration note, NOT to skew the recommended band.
## Reference files
- `references/1-survey-source-schemas.md` — per-source schemas with field mapping.
- `references/2-comp-philosophy-template.md` — fillable philosophy file.
## Method
Five steps.
### 1. Validate the role definition
Confirm `level`, `geography`, `function` are present and match values in the survey export. If `level` is on the firm's ladder but the survey uses a different ladder, look up the mapping in the philosophy file. If no mapping exists, halt and ask the user to add it.
If `geography` is ambiguous (e.g. "Bay Area" — does that include South Bay, East Bay, North Bay, the entire MSA?), halt and ask the user to specify against the survey's geography taxonomy.
### 2. Look up survey percentiles
Deterministic lookup — do NOT paraphrase the survey. For each of `base_salary`, `equity_annualized`, `ote` (or `bonus` if non-sales), pull the 25th / 50th / 60th / 75th / 90th percentiles for the matched (level, geography, function) cell.
Check the cell's sample size. If it's below the survey's documented threshold (Radford 5+, Pave 10+, Carta 15+ for equity, custom CSV per the schema's `min_sample_size` field), flag low-N. Fall back to a broader cell:
- First fallback: same level, same function, broader geography (e.g. US-wide).
- Second fallback: same level, same function, all geographies.
Document the fallback chain in the report. Do NOT silently fall back without surfacing.
### 3. Calibrate against firm philosophy
Read the philosophy file. The philosophy specifies the target percentile per component (e.g. base at 60th percentile, equity at 75th percentile, OTE at 50th percentile for sales).
For each component, compute:
- Recommended midpoint = survey's `target_percentile` for the cell
- Band width = midpoint × ±10% (default; configurable per component in the philosophy)
- Lower edge = midpoint × 0.9, upper edge = midpoint × 1.1
If the philosophy specifies a different band-width policy (e.g. wider band for senior roles where individual variance is larger), use that instead.
For equity: convert annualized survey value to dollar grant size at the firm's current strike price. Document the math in the report (`grant_value = annualized_value × vesting_period / strike_price`).
### 4. Compose the public-facing range
Compute the public-facing base salary range:
- Lower edge of public range = lower edge of base band
- Upper edge of public range = upper edge of base band
- Format: e.g. `$170,000-$210,000 USD per year`
Validate band width against the geography's pay-transparency requirements:
- NYC (LL 32-A): "good faith" range required; band narrower than ~15% width raises legal exposure.
- CO (Equal Pay for Equal Work Act): range required, no specific width threshold but functional good-faith requirement.
- CA (SB 1162): range required for postings if the role is to be performed in CA.
- WA (Pay Transparency Act): range required.
If the role straddles multiple jurisdictions, the broadest range applies. If the range is below 15% width, emit a warning (the band is at the edge of "good faith" — consider widening before publishing).
### 5. Emit the report + audit record
Write the report to stdout (or the calling environment's report destination). Append one JSONL line to `audit/<YYYY-MM>.jsonl` with: `role`, `geography`, `level`, `function`, `survey_source`, `survey_export_date`, `philosophy_version`, `target_percentiles`, `recommended_bands`, `public_range`, `low_n_flag`, `fallback_chain` (if any).
The audit record supports the firm's annual pay-equity audit. No PII; this is about the band, not about a specific candidate.
## Output format
```markdown
# Comp benchmark — {role} — {level} — {geography}
Generated: {ISO timestamp} · Skill v1.0 · Model: claude-sonnet-4-6
Survey: {Radford 2026-Q2 / Pave 2026-04 / etc.} · Philosophy: {firm-philosophy.json v3}
{LOW-N WARNING if any component fell back}
## Recommended bands
### Base salary (target: 60th percentile)
- Survey 60th percentile: $185,000
- Recommended band: $166,500 - $203,500
- Calibration note: Tight band (±10%); widen to ±15% for cross-level candidates.
### Equity (target: 75th percentile, 4-year vest)
- Survey 75th percentile annualized value: $90,000
- Total grant value: $360,000 over 4 years
- At firm strike $5.20: 69,231 shares
- Recommended band: 62,300 - 76,200 shares (±10%)
### Cash bonus (target: 50th percentile)
- Survey 50th percentile: $20,000 (annual target)
- Recommended band: $18,000 - $22,000
## Public-facing range (NYC LL 32-A / CO/CA/WA compliant)
`$166,500 - $203,500 USD per year, plus equity grant and target bonus`
Band width: 22% — within "good faith" thresholds.
## Provenance
- Survey: Radford Q2-2026 (export dated 2026-04-15)
- Survey cell sample size: 42 (above Radford's 5+ threshold)
- Philosophy: firm-philosophy.json v3 (updated 2026-01-10)
- Geography mapping: San Francisco MSA matched directly in Radford taxonomy
- Audit record: `audit/2026-05.jsonl` line {N}
## Calibration notes
- The candidate signal noted "competing offer at top of band from peer-tier company" — this is informational; the recommended band did NOT shift in response. If an exception is needed, escalate to the comp committee with the competing offer details.
- This role's geography has a pay-equity gap of -3.2% vs. firm-wide for the same level (per last quarterly audit); recommended band is at the firm's stated philosophy. Audit will surface whether the gap closes.
```
## Watch-outs
- **Survey-export staleness.** *Guard:* warns at >6 months on the export's dated metadata.
- **Geography mis-mapping.** *Guard:* halts on ambiguous geography rather than defaulting.
- **Low-N cell.** *Guard:* refuses to use a low-N cell; falls back with the chain documented.
- **Equity drift.** *Guard:* conversion math documented in the report; raw and converted values both stored in audit.
- **Public range too tight.** *Guard:* warns at <15% band width per pay-transparency-law functional thresholds.
- **Historical-pay bias propagation.** *Guard:* if philosophy is calibrated against historical pay rather than survey percentile, flag and recommend a separate pay-equity check.
# Survey source schemas
The compensation-benchmark skill reads survey exports in one of three supported formats: Radford, Pave, Carta. A custom CSV schema is also supported for in-house surveys or for sources not on this list.
## Radford
Radford ships exports as CSV or XLSX. The skill reads the CSV form (re-export from XLSX if needed).
### Required columns
| Column | Type | Notes |
|---|---|---|
| `level_radford` | string | Radford ladder code (e.g. `P4`). The philosophy file maps this to firm levels. |
| `function_radford` | string | Radford function code (e.g. `Software Engineering`). |
| `geography_radford` | string | Radford geography (e.g. `San Francisco MSA`). |
| `sample_size` | integer | Number of survey respondents in this cell. Skill requires ≥5. |
| `base_salary_p25` | number | 25th percentile base salary, USD. |
| `base_salary_p50` | number | 50th percentile. |
| `base_salary_p60` | number | 60th percentile. |
| `base_salary_p75` | number | 75th percentile. |
| `base_salary_p90` | number | 90th percentile. |
| `equity_annual_p25` | number | 25th percentile annualized equity value, USD. |
| `equity_annual_p50` | number | ... |
| `equity_annual_p60` | number | ... |
| `equity_annual_p75` | number | ... |
| `equity_annual_p90` | number | ... |
| `bonus_target_p50` | number | Target annual cash bonus, USD. (Radford reports target, not actual.) |
### Notes
- Radford's `level` codes (P1-P8 for IC, M1-M5 for management) need a firm-level mapping in the philosophy file. The mapping lives once, used everywhere.
- Geography taxonomy: Radford uses MSAs (e.g. `San Francisco MSA`, `New York MSA`) plus international country/city combos. The skill matches by exact string; "Bay Area" does not match `San Francisco MSA`.
- Sample size <5 → low-N flag. Radford itself suppresses cells below 3.
## Pave
Pave exports as CSV via the API or via UI download.
### Required columns
| Column | Type | Notes |
|---|---|---|
| `level_pave` | string | Pave's level normalization (e.g. `Senior IC`). |
| `function_pave` | string | Pave's function (e.g. `Engineering - Software`). |
| `location` | string | Pave's location string. |
| `n_employees` | integer | Number of employees in the cell. |
| `base_p25`, `base_p50`, `base_p75`, `base_p90` | number | Base salary percentiles. (Pave does not publish p60.) |
| `equity_p25`, `equity_p50`, `equity_p75`, `equity_p90` | number | Annualized equity in USD. |
| `total_comp_p50`, `total_comp_p75` | number | Total comp percentiles, useful for OTE calibration. |
### Notes
- Pave uses its own level normalization across firms; mapping to firm levels lives in the philosophy file.
- Pave's coverage is strongest for tech in the US and EU; APAC and emerging-market data is thinner.
- Sample size <10 → low-N flag (Pave's own threshold).
- `total_comp_p50` includes base + bonus + equity at the median. Useful for the public-range sanity check.
## Carta
Carta's compensation product exports in two flavors: cash-comp report (similar to Pave) and equity-comp report (cap-table-aware).
### Required columns (cash report)
| Column | Type | Notes |
|---|---|---|
| `role` | string | Carta's normalized role label. |
| `seniority` | string | `Junior`, `Mid`, `Senior`, `Staff`, `Principal`. |
| `location` | string | Carta's location string. |
| `n_companies`, `n_employees` | integer | Cell sample sizes (both required). |
| `base_p50`, `base_p75` | number | Base salary percentiles. |
| `total_cash_p50`, `total_cash_p75` | number | Base + bonus. |
### Required columns (equity report)
| Column | Type | Notes |
|---|---|---|
| `role` | string | Same as cash report. |
| `seniority` | string | Same. |
| `location` | string | Same. |
| `company_stage` | string | `Seed`, `Series A`, `Series B`, etc. |
| `equity_pct_p25`, `equity_pct_p50`, `equity_pct_p75`, `equity_pct_p90` | number | Equity as percentage of fully diluted shares outstanding. |
### Notes
- Carta's coverage is strongest for early-stage US startups. For mid-stage and public-company benchmarking, Radford or Pave are stronger.
- Equity reported as `equity_pct_p*` (percent of company), not dollar value. The skill converts using the firm's most recent valuation.
- Sample sizes <15 for equity → low-N flag (equity is more variance-heavy than cash).
## Custom CSV
For in-house surveys or sources not on the list above. The skill reads any CSV with the following minimum columns:
| Column | Type | Required | Notes |
|---|---|---|---|
| `level` | string | yes | Whatever ladder; must map to firm ladder via philosophy file. |
| `function` | string | yes | Whatever taxonomy; must match role definition. |
| `geography` | string | yes | Free-text or coded; must match exactly. |
| `sample_size` | integer | yes | Used for low-N flag. |
| `base_p50` | number | yes | Median base salary, USD. |
| `base_p25`, `base_p75`, `base_p90` | number | recommended | More percentiles enable wider band-targeting options. |
| `equity_value_p50` | number | for equity-bearing roles | Annualized equity value, USD. |
| `bonus_p50` or `ote_p50` | number | for sales / variable-comp roles | Target. |
| `min_sample_size` | integer | yes | The threshold below which the skill flags low-N. Set per-survey based on the survey methodology. |
### Notes
- Custom CSVs are useful for mid-cycle re-benchmarks against a peer cohort (your own team's data plus a few comparable firms) or for in-house comp-committee internal reviews.
- The `min_sample_size` field is critical — without it the skill cannot calibrate the low-N threshold and falls back to a conservative default (15).
## Adding a new survey source
To add a new source:
1. Document the source's export schema in this file with the same shape as the entries above.
2. Update the skill's source detector to recognize the new format (filename pattern, header pattern, or both).
3. Add the source's documented sample-size threshold.
4. If the source uses a different geography or level taxonomy, document the mapping in the philosophy file.
## Refresh cadence
Survey data shifts faster than yearly. The benchmark skill warns at >6 months on the export's dated metadata; that's the floor. Quarterly refresh is the operating norm for serious comp programs.
For Radford: Q1, Q2, Q3, Q4 standard cycles.
For Pave: monthly refresh available via API.
For Carta: quarterly equity reports, monthly cash updates available.
# Compensation philosophy file template
The compensation-benchmark skill calibrates survey data against the firm's compensation philosophy. This file is the philosophy. Copy the JSON below to `philosophy.json` (or wherever your skill config points), fill it in, and version it in git.
The philosophy is rarely revised — usually annually at most, often less. When it changes, every benchmark recommendation post-change uses the new philosophy. The skill captures the philosophy version in the audit record so future audits can reproduce the recommendation.
## JSON shape
```json
{
"philosophy_version": "2026.1",
"effective_from": "2026-01-10",
"approver": "Comp Committee minutes 2026-01-08",
"target_percentiles": {
"engineering": {
"base": 60,
"equity": 75,
"bonus_or_ote": 50
},
"sales": {
"base": 50,
"equity": 50,
"bonus_or_ote": 75
},
"go_to_market_other": {
"base": 60,
"equity": 60,
"bonus_or_ote": 60
},
"g_and_a": {
"base": 60,
"equity": 50,
"bonus_or_ote": 50
}
},
"band_widths_pct": {
"default": 10,
"by_level": {
"junior": 8,
"senior": 12,
"staff": 15,
"principal": 18,
"executive": 25
}
},
"level_mapping": {
"firm_to_radford": {
"L3": "P3",
"L4": "P4",
"L5": "P4",
"L6": "P5",
"L7": "P6",
"L8": "P7"
},
"firm_to_pave": {
"L3": "Mid IC",
"L4": "Senior IC",
"L5": "Senior IC",
"L6": "Staff IC",
"L7": "Principal IC",
"L8": "Senior Principal IC"
}
},
"geography_adjustments": {
"remote_us": 0,
"remote_intl": -15,
"san_francisco_msa": 0,
"new_york_msa": 0,
"seattle_msa": -3,
"austin_msa": -10,
"london": -8,
"toronto": -12,
"remote_latam": -35
},
"current_strike_price_usd": 5.20,
"vesting_period_years": 4,
"equity_grant_type": "RSU",
"exception_band": {
"max_above_top": 15,
"approval_required": "comp_committee"
},
"public_range_policy": {
"minimum_band_width_pct": 15,
"include_equity_target_dollar": true,
"include_bonus_target_dollar": true
},
"pay_equity_audit_cadence_months": 12,
"last_pay_equity_audit": "2026-02-15"
}
```
## Field-by-field
### `philosophy_version`, `effective_from`, `approver`
Versioning. The skill captures `philosophy_version` in the audit record so the recommendation is reproducible against a specific version of this file. `effective_from` is the date the philosophy applies to NEW recommendations — recommendations made before that date used the prior philosophy. `approver` cites the approval source (Comp Committee minutes, board resolution, etc.).
### `target_percentiles`
Per function family, the target percentile per component. The most common patterns:
- **Engineering**: 60th base, 75th equity (founder-friendly equity to attract IC talent), 50th bonus.
- **Sales**: 50th base, 50th equity, 75th OTE (the variable comp is the lever).
- **G&A**: 60th base across components (predictable, market-rate).
If the firm's strategy is "we pay top of market across the board," set everything to 75th. If the firm's strategy is "we pay base at market and over-index on equity," set base to 50th and equity to 75th-90th.
### `band_widths_pct`
The recommended band width as a percentage of the midpoint. Default 10% (recommended midpoint ±10%). Per-level overrides absorb the wider individual variance at senior levels.
If a single number is too rigid, the skill respects the per-level overrides.
### `level_mapping`
Mapping from the firm's internal ladder to each survey's ladder. The skill cannot infer this — it has to be specified per survey the firm uses. If a level mapping is missing, the skill halts and asks the user to add it.
This is the single most-edited part of the philosophy; it's also the most consequential, because the wrong mapping shifts every recommendation by a percentile-band.
### `geography_adjustments`
Per-geography multiplier. `0` means use the survey's value for that geography directly. `-15` means apply a 15% reduction (e.g. for `remote_intl`). The adjustments must be defensible — random adjustments here are how pay-equity gaps creep in.
If the firm has a published location-based pay policy, this section should match it line-for-line.
### `current_strike_price_usd`, `vesting_period_years`, `equity_grant_type`
Used for converting annualized survey equity values to grant size. Strike price is the most-recent 409A or option-grant strike. Vesting is typically 4 years. Grant type matters for tax framing but not for the band math.
### `exception_band`
When the skill is asked about a band-exception ("can we offer above the top?"), the philosophy says how high (`max_above_top: 15` means up to 15% above the top of the recommended band) and who approves. The skill itself does NOT approve exceptions; it surfaces the policy.
### `public_range_policy`
Compliance posture for NYC LL 32-A, CO/CA/WA pay-transparency requirements. `minimum_band_width_pct: 15` is the firm's "good faith" floor — the skill warns if a recommended band falls below this width.
### `pay_equity_audit_cadence_months`, `last_pay_equity_audit`
For the audit-record metadata. The skill notes the cadence and last audit so the recommendation can be flagged if the firm is overdue for an equity audit.
## When to revise the philosophy
- **Strategy shift** — the firm decides to over-index on equity vs. cash. Update target percentiles.
- **New geography** — opening a new region. Add to `geography_adjustments` based on local market data.
- **New survey added** — add a level mapping for the new survey.
- **Pay-equity audit findings** — if the audit surfaces gaps, the philosophy may need revision (band widths, geography adjustments).
Each revision bumps `philosophy_version`. Old audit records remain interpretable against their respective version.
## What the philosophy is NOT
- It is NOT a candidate-by-candidate negotiation guide.
- It is NOT a one-time setup; it evolves with the firm.
- It is NOT confidential to the recruiter — the philosophy should be visible to every hiring manager, ideally documented internally for transparency.
