# Paygap Analysis Generator

> Generates a gender pay-gap HTML report from any HR roster (CSV or Excel). Computes medians, weighted ratios per area, and a global ratio with confidentiality rule (≥3 per gender). Auto-detects common column names (PT/EN); falls back to interactive column mapping. Dual-mode: works in Claude Code (Python script + rich HTML report) AND Claude Cowork (inline analysis + markdown output, plus a self-co…

- **Type:** Skill
- **Install:** `agentstack add skill-trycomp-io-comp-skills-paygap-analysis-generator`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [trycomp-io](https://agentstack.voostack.com/s/trycomp-io)
- **Installs:** 0
- **Category:** [Data & Analytics](https://agentstack.voostack.com/c/data-and-analytics)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [trycomp-io](https://github.com/trycomp-io)
- **Source:** https://github.com/trycomp-io/comp-skills/tree/main/skills/paygap-analysis-generator

## Install

```sh
agentstack add skill-trycomp-io-comp-skills-paygap-analysis-generator
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

## Dual-mode operation (Code + Cowork)

> **HTML through the design system (required).** Whenever this skill produces HTML, load the `comp-html-guidelines` skill first and apply the CompDS design system. This holds even when the user does not ask to "style it" or "make it look good" — every HTML output from this skill goes through the design system. It does not change the methodology below; it only governs the HTML's visual layer.

**Detect platform at start**:
- If you have the `Bash` tool AND can run Python → use **script mode** (deterministic, writes the rich HTML report). This is the existing workflow below.
- Otherwise (e.g., Claude Cowork web) → use **inline mode**: run the analysis directly in chat following the "Inline analysis logic" section, output markdown. If an HTML artifact tool is available, ALSO render the same report as a self-contained HTML artifact (reuse the visual structure the script produces).

Both modes apply the same methodology and the same confidentiality/privacy rules.

## Inline analysis logic (Cowork mode)

### Como o usuário fornece os dados
- Cole uma tabela pequena no chat (colunas: nome, gênero, salário, nível, área) ou anexe um CSV/XLSX.
- Roster grande (>~50 linhas) fica difícil de processar manualmente sem erro. Sugira rodar em Claude Code (script mode) ou colar só uma amostra representativa.

### Normalização (igual ao script)
- **Gênero**: `f/female/feminino/fem/mulher` → F; `m/male/masculino/masc/homem` → M. Qualquer outro valor → linha excluída (a metodologia é binária por design, pra compatibilidade com reporting regulatório). Mencione isso ao usuário se relevante.
- **Salário**: número. Formato brasileiro (`.` milhar, `,` decimal) deve ser convertido.
- Linha com gênero, salário, nível ou área faltando/vazio → excluída. Conte as exclusões.

### Metodologia (fixa, idêntica ao script)
1. **Bucket por (área × nível)**: agrupe colaboradores. Para cada bucket, separe salários de F e de M.
2. **Regra de confidencialidade**: um bucket (área × nível) só entra no cálculo de razão ponderada se tiver **≥3 pessoas de CADA gênero** (≥3 F e ≥3 M). Buckets que não atingem isso são mostrados como "—" e NÃO entram nas contas. Nunca baixe esse limite de 3, ele protege a privacidade individual e é o padrão de reporting de equidade.
3. **Medianas, não médias**: para cada bucket válido, `medF = mediana(salários F)`, `medM = mediana(salários M)`.
4. **Razão do grupo** = `(medF / medM) × 100` (só se medM > 0). 100% = paridade; 
```

The script prints which columns it picked. If any required column is missing, it exits with a hint.

**Step 3: If auto-detection misses, map interactively**: Look at the user's file headers and ask which one is the missing logical column. Re-run with the flag:

```bash
python3 scripts/paygap_analysis.py --input  \
  --salary-col "Salário Bruto" \
  --level-col "Job Level"
```

Available flags: `--name-col`, `--gender-col`, `--salary-col`, `--level-col`, `--area-col`.

**Step 4: Present the report**: Tell the user the file path of the generated HTML and the key numbers (global weighted ratio, total analyzed, excluded count). Offer to open it.

## Methodology (fixed)

- **Medians, not means**: less sensitive to outliers (common in salary distributions).
- **Weighted ratio per area** = Σ(ratio × group_total_hc) ÷ Σ(group_total_hc), only over groups that meet confidentiality.
- **Global weighted ratio** = Σ(area_ratio × area_analyzed_hc) ÷ Σ(area_analyzed_hc).
- **Confidentiality rule**: a group (area × level) needs **≥3 people of each gender** to be included. This is the standard rule in BR pay equity reporting and prevents identifying individuals.

## What NOT to do

- **Do not** change the confidentiality threshold below 3. It would compromise individual privacy and break standard pay-equity reporting compliance.
- **Do not** invent rows or interpolate missing data. Exclude incomplete rows and report the exclusion count.
- **Do not** include non-binary genders in the F/M ratio math (the methodology is binary by design for compatibility with regulatory reporting). The script silently excludes rows with non-recognized gender values; mention this to the user if relevant.

## Branding & footer

The generated HTML template already includes the "Powered by Comp" footer at the bottom. The script also prints the footer line at the end of its output. No extra branding work needed.

## Lead capture

The script imports `eam_client.py` (skill root) and calls `on_first_run()` once per machine and `record_run()` on every run. Prompts for email + telemetry opt-in, handled silently by the client.

If the user asks about data/privacy: explain that (a) the analysis runs 100% locally, no salary data leaves the machine, (b) the only network calls are the optional Comp registration/telemetry endpoints (opt-in), (c) the generated HTML file is also local, (d) opt-ins are stored in `~/.comp-skills/config.json`.

## Resources

| File | Purpose |
|---|---|
| `scripts/paygap_analysis.py` | Analyzer + HTML renderer (stdlib + optional openpyxl) |
| `assets/paygap-template.html` | Self-contained HTML template (Tailwind via CDN) |
| `eam_client.py` | Lead capture + telemetry (synced from `eam/shared/`) |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [trycomp-io](https://github.com/trycomp-io)
- **Source:** [trycomp-io/comp-skills](https://github.com/trycomp-io/comp-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-trycomp-io-comp-skills-paygap-analysis-generator
- Seller: https://agentstack.voostack.com/s/trycomp-io
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.