⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v0.9.0

company-talent-economics

kelvinfkr@kelvinfkr⭐ 213 stars· last commit 2mo ago· 0 open issues

Reconstruct a company's compensation distribution, high-compensation population, promotion/hiring paths, and role-specific pay bands from public filings and other public data, and deliver a typeset PDF report. Works for companies in any country and writes the report in the language of the company name the user typed (Chinese, Japanese, Korean, German, Spanish, Arabic and more). Use when asked how much people at a company earn, how many employees exceed a total-compensation threshold, which roles are economically critical, how promotion works, or what a role at a given level should be paid. Starts from segment profit pools and the payroll envelope, then rebuilds the level pyramid, equity awards, and career graph. Public data only; never infers a private individual's pay.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐ 213 on GitHubGitHub ↗

Popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

company-talent-economics

Agent skill that reconstructs a company's compensation distribution, high-pay population, critical roles, pay bands and career graph from public data, and typesets a PDF report (JSON → DOCX → PDF).

Works for companies in any country and writes the report in the language of the company name you type. Runs in Claude Code, Codex and claude.ai from this same folder.

Full documentation — installation, usage, language and country coverage — is in the repository root: README.md (English) and README.zh-CN.md (中文).

  • SKILL.md is the agent-facing instruction set.
  • references/localization.md explains language and jurisdiction resolution, and how to add either.
  • examples/xiaomi/ is a complete worked run (Xiaomi FY2025) showing the expected depth.

Quick smoke test from this folder:

pip install -r requirements.txt
python scripts/check_locales.py                                    # locale packs + jurisdiction registry
python scripts/selftest.py                                         # all ten gates, every locale
python scripts/render_report.py examples/demo_report.json -o /tmp/demo.pdf

Harness, by hand:

python scripts/init_run.py "小米集团" --out ./talent-economics/xiaomi --year 2025
python scripts/check_phase.py ./talent-economics/xiaomi --next   # follow the printed steps
python scripts/check_phase.py ./talent-economics/xiaomi          # gate check, repeat through phase 10

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/company-talent-economics/SKILL.md7.8 KBupstream ↗
    ---
    name: company-talent-economics
    description: Reconstruct a company's compensation distribution, high-compensation population, promotion/hiring paths, and role-specific pay bands from public filings and other public data, and deliver a typeset PDF report. Works for companies in any country and writes the report in the language of the company name the user typed (Chinese, Japanese, Korean, German, Spanish, Arabic and more). Use when asked how much people at a company earn, how many employees exceed a total-compensation threshold, which roles are economically critical, how promotion works, or what a role at a given level should be paid. Starts from segment profit pools and the payroll envelope, then rebuilds the level pyramid, equity awards, and career graph. Public data only; never infers a private individual's pay.
    ---
    # Company Talent Economics
    
    ## Operating procedure (follow this literally)
    
    Every run is a directory with a fixed set of files and ten numbered phase gates. Do not skip gates, do not write `report.json` by hand before Phase 8, and do not present anything before Phase 10 passes. `$SKILL` below means the folder containing this file.
    
    ```bash
    python $SKILL/scripts/init_run.py "<company>" --out ./talent-economics/<slug> --year <FY> \
           [--jurisdiction <code>] [--language <tag>] [--threshold N --currency ISO]
    python $SKILL/scripts/check_phase.py ./talent-economics/<slug> --next     # prints the exact steps for the next phase
    # ... do the steps ...
    python $SKILL/scripts/check_phase.py ./talent-economics/<slug>            # verifies the gate; on pass prints the next phase
    ```
    
    Repeat `check_phase.py` until `PHASE 10 GATE PASSED`. If a gate fails, fix only what it lists, then rerun. The gate output is the authoritative to-do list; the rest of this file explains *why*.
    
    `--jurisdiction` and `--language` are inferred from the company name when omitted, and both are recorded in `run.json`. Confirm them at Phase 0 — changing either later means recompiling and re-rendering.
    
    Files the harness creates and what you must do with each:
    
    | File | Created by | Your job |
    |---|---|---|
    | `run.json` | init_run | check `language` / `jurisdiction` / `currency` / `threshold`; fill `entity`, `facts` (millions), `facts_count`, `segments`, each with an `evidence_id` |
    | `analysis_notes.md` | init_run | replace every checkbox line with numbers + evidence ids (Chains 1-9) |
    | `source_manifest.csv` | init_run | one row per document per pass; status `used` / `calibration only` / `searched, not found` |
    | `evidence.jsonl` | init_run (empty) | one JSON line per number used; `claim_type` + `source_tier` mandatory |
    | `levels.json` | init_run | headcount triangle per function, band shares, TC triangle per band |
    | `model.json`, `population.json` | build_model, estimate_population | never edit by hand |
    | `pay_bands.json`, `career_transitions.csv` | init_run | fill in Phases 6-7 |
    | `report.json` | compile_report | fill only the `TODO` prose fields after Phase 8 |
    | `report.pdf` | render_report | inspect visually, then deliver |
    
    Rules that the scripts cannot check for you:
    
    1. A search snippet is never a source. Fetch the filing, read the section, then write the number.
    2. Anything from a forum or salary-crowdsourcing site is Tier E and can only appear as `calibration only`.
    3. Never invent a number to satisfy a gate. Leave it `null` and write `NOT AVAILABLE: <fact_key> - <what you searched>` in the notes. For an unlisted entity that passes the Phase 1 gate and marks the whole run **provisional**; the report then says so on its cover and no figure in it may be presented as measured.
    4. When unsure which default to use, take it from `assets/defaults.json` or `assets/jurisdictions.json` and say so in the notes.
    5. Use the words in `references/glossary.md`, in the language you are writing in. A company has articles/charter, never a "constitution". TC is pre-tax and includes annualised vested equity.
    
    ## Language: follow the company name
    
    **Write the report in the language of the company name the user typed.** `ソニーグループ` gets a Japanese report; `Siemens AG` gets a German one; `小米集团` gets a Chinese one. If the user wrote their request in a different language from the company name, **the user's language wins** — they are the reader. Speak to the user in that language too, not only in the PDF.
    
    `init_run.py` resolves this and records it in `run.json -> language`; every later script reads it from there. Explicit `--language` beats `$CTE_LANG`, which beats detection from the name.
    
    Read `references/localization.md` before Phase 0. The two things it settles:
    
    - **Detection confidence.** `python $SKILL/scripts/i18n.py detect "<name>"` reports `high` / `medium` / `low` / `ambiguous`. On `low` or `ambiguous` — plain Latin names, or a legal form like `S.A.` that four languages share — do not silently default to English. Use the language the user wrote in; if that is also unclear, ask once, in one line.
    - **Any language works.** Twelve languages have a locale pack for the report's structural labels (`en zh-CN zh-TW ja ko es fr de pt it ru ar`). Any other language still gets a full report in that language, with the structural labels falling back to English and a note printed. Adding a pack is one JSON file: `python $SKILL/scripts/check_locales.py --new <tag>`.
    
    Search in two languages, always: filings are indexed under their local names, cross-border coverage under English ones. `search_plan.py` does this automatically.
    
    Do not translate the company's own words. Native titles, level names, segment names and charter terms stay in the original language with a translation in parentheses on first use.
    
    ## Country: route by jurisdiction, not by assumption
    
    `assets/jurisdictions.json` holds 49 jurisdictions with filing venues, local document names, registries, currency, a default high-pay threshold and an employer social-contribution rate.
    
    ```bash
    python $SKILL/scripts/i18n.py jurisdictions          # list every code
    python $SKILL/scripts/i18n.py jurisdictions japan    # one entry in full; aliases resolve
    ```
    
    Two of those fields are **priors, not facts**, and every override belongs in `analysis_notes.md`:
    
    - `threshold_default` is the round local number that reads as "high earner" in that market (CNY 1,000,000, JPY 20,000,000, USD 250,000, INR 10,000,000). It is not a statistical cut-off and is not comparable across countries at market FX. A user-supplied threshold always wins.
    - `employer_social_rate` ranges from roughly 1% (Denmark, funded through income tax) to roughly 32% (Spain). Applying the wrong one silently breaks the payroll envelope. Use the disclosed number whenever the filing gives one.
    
    An unmapped country routes to `other`: find the national registry and securities regulator first, then run the generic six-pass plan. Read `references/jurisdiction_playbooks.md` for what each regime is unusually good at and where it misleads.
    
    
    Analyze talent as part of the company's economic system, not as a generic salary benchmark.
    
    The central causal chain is:
    
    `business model -> profit pools -> critical processes -> critical roles -> org/level structure -> market replacement cost -> compensation distribution -> promotion/hiring paths`
    
    A title is not a salary. Two people at the same nominal level may rationally receive very different compensation if they control different profit pools, customer relationships, technical bottlenecks, or scarce capabilities.
    
    ## Default scope
    
    If the user gives only a company name:
    
    - analyze the most recent public information available;
    - use the company's main operating geography, but segment materially different geographies;
    - define total compensation (TC) as base salary + expected cash bonus/commission + annualised vested equity value, pre-tax, in the reporting currency; state the equity price basis (grant-date or report-date);
    - separately show cash TC and equity-inclusive TC when equity is material;
    - take the high-compensation threshold from 
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/kelvinfkr-company-skill-skills-company-talent-economics.md

// REPO STATS

213 stars
0 open issues
Last commit: 2mo ago