Now liveThe Skillselion MCP - thousands of ranked skills, loaded into your agent mid-task. No install.Get it →
asgard-ai-platform avatar

Algo Hr Matching

  • 24 installs
  • 223 repo stars
  • Updated June 6, 2026
  • asgard-ai-platform/skills

algo-hr-matching is a skill that implements the Gale-Shapley stable matching algorithm for two-sided preference matching problems.

About

This skill implements the Gale-Shapley (deferred acceptance) algorithm for two-sided stable matching. A developer uses it to pair candidates to positions, students to schools, or any two-sided preference problem where no blocking pair should exist. It explains that the proposing side gets its best stable partner and verifies stability by confirming zero blocking pairs.

  • Implements Gale-Shapley deferred-acceptance stable matching
  • Runs in O(n squared) worst case, proposer-optimal
  • Verifies stability by checking for zero blocking pairs

Algo Hr Matching by the numbers

  • 24 all-time installs (skills.sh)
  • Ranked #1,170 of 2,064 Data Science & ML skills by installs in the Skillselion catalog
  • Data as of Aug 2, 2026 (Skillselion catalog sync)
At a glance

algo-hr-matching capabilities & compatibility

Free; no API keys required per the docs.

Capabilities
stable matching · gale shapley · assignment algorithm
Use cases
data analysis
Pricing
Free
From the docs

What algo-hr-matching says it does

Gale-Shapley (deferred acceptance) finds a stable matching between two equally-sized sets where no unmatched pair prefers each other over their current match.
SKILL.md
The Proposing Side Gets Their BEST Stable Partner
SKILL.md
npx skills add https://github.com/asgard-ai-platform/skills --skill algo-hr-matching

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

Listed on Skillselion
Installs24
repo stars223
Last updatedJune 6, 2026
Repositoryasgard-ai-platform/skills

What it does

Solve a two-sided preference matching problem with a stable assignment using Gale-Shapley.

Who is it for?

Two-sided matching where stability (no blocking pairs) is required, given ranked preferences.

Skip if: One-sided assignment (use Hungarian algorithm) or preferences based on scores rather than rankings.

When should I use this skill?

The user needs optimal job matching, stable assignment, or candidate-position pairing.

What you get

A stable matching with zero blocking pairs and confirmation of which side was proposer-optimal.

  • Stable matching with stability confirmation

By the numbers

  • O(n squared) worst-case runtime
  • verification gate: zero blocking pairs

Files

SKILL.mdMarkdownGitHub ↗

Gale-Shapley Stable Matching

Overview

Gale-Shapley (deferred acceptance) finds a stable matching between two equally-sized sets where no unmatched pair prefers each other over their current match. Runs in O(n²) worst case. Proposer-optimal: the proposing side gets their best stable partner.

When to Use

Trigger conditions:

  • Matching candidates to job positions based on mutual preferences
  • Assigning students to schools or residents to hospitals
  • Any two-sided matching where stability (no blocking pairs) is required

When NOT to use:

  • For one-sided assignment (use Hungarian algorithm)
  • When preferences are based on scores, not rankings (use optimization)

Algorithm

IRON LAW: The Proposing Side Gets Their BEST Stable Partner
Gale-Shapley is proposer-optimal and reviewer-pessimal. If employers
propose, they get their best stable match; candidates get their worst.
The CHOICE of who proposes determines which stable matching is found.

Phase 1: Input Validation

Collect: preference rankings from both sides. Each participant ranks all members of the other side. Gate: Complete preference lists, equal-sized groups (or handle unequal with dummy entries).

Phase 2: Core Algorithm

1. All proposers are "free" (unmatched) 2. While any proposer is free and hasn't proposed to everyone:

  • Free proposer proposes to their highest-ranked unproposed-to reviewer
  • Reviewer accepts if unmatched, or replaces current match if new proposer is preferred
  • Replaced proposer becomes free again

3. Terminate when all proposers are matched

Phase 3: Verification

Check stability: for every unmatched pair (a,b), verify that at least one of them prefers their current match over the other. No blocking pairs = stable. Gate: Zero blocking pairs found.

Phase 4: Output

Return matching with stability confirmation.

Output Format

{
  "matching": [{"proposer": "Candidate_A", "reviewer": "Company_X", "proposer_rank": 1, "reviewer_rank": 2}],
  "metadata": {"pairs": 10, "rounds": 23, "blocking_pairs": 0, "proposer_side": "candidates"}
}

Examples

Sample I/O

Input: 3 candidates, 3 companies, each with full preference rankings Expected: Stable matching with zero blocking pairs. Candidate-proposing gives candidate-optimal result.

Edge Cases

InputExpectedWhy
All prefer same #1Still terminates, stableRejected proposers move to next choice
Identical preferencesUnique stable matchingOnly one possibility
Unequal sidesSome unmatched on larger sideAdd dummy entries or use many-to-one variant

Gotchas

  • Proposer advantage: If candidates propose, they get better matches than if companies propose. This is a design choice with equity implications.
  • Incomplete preferences: If participants don't rank everyone, unmatched results are possible. Handle with acceptable-partner thresholds.
  • Many-to-one: Hospital-resident matching uses the many-to-one variant (each hospital has multiple slots). Use the Roth-Peranson extension.
  • Strategic manipulation: The reviewing side CAN benefit from misreporting preferences (truncating lists). The proposing side cannot — truthful reporting is dominant strategy for proposers.
  • Preference elicitation: Getting honest, complete rankings is hard in practice. People satisfice rather than fully rank all options.

References

  • For many-to-one matching (hospital-resident), see references/many-to-one.md
  • For strategic behavior analysis, see references/strategic-manipulation.md

Related skills

FAQ

Who gets the best match in Gale-Shapley?

The proposing side gets its best stable partner and the reviewing side its worst; the choice of proposer determines the outcome.

What if the two sides are unequal in size?

Some participants on the larger side stay unmatched; add dummy entries or use the many-to-one variant.

This week in AI coding

Five minutes, every Monday - the tools, releases and tactics for developers.

unsubscribe anytime.