matheuristics

matheuristics is a skill for Claude Code from hajibabaie/combinatorial-optimization-skills. It costs 146 tokens per session (11,790 once invoked), scanned A, original, MIT.

A guide to matheuristics, which combine a mathematical optimization solver with a faster trial-and-improvement search. It focuses on mixed-integer programming, a method for problems with both numeric and yes/no or whole-number decisions.

In plain words
What is it for?
Use it to build fix-and-optimize, relax-and-fix, destroy-and-repair, local-branching, proximity-search, and solution-polishing loops. It also covers how to divide the time budget among solver calls.
Why use it?
It helps when solving the complete model cannot reach a good answer within the available time. It provides a way to use exact solver calls only where they help and compare the result fairly with simpler methods.

Skill for Claude Code

Written for Claude Code: shipped in a Claude Code plugin. Also seen: positional $N argument.

Part of the combinatorial-optimization plugin — 76 skills shipped together

Good fit Use it to build fix-and-optimize, relax-and-fix, destroy-and-repair, local-branching, proximity-search, and solution-polishing loops. It also covers how to divide the time budget among solver calls.

Compare 6 skills from other repositories ↓
Install with agentmods
npx agentmods add skills/hajibabaie/combinatorial-optimization-skills/matheuristics
Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

Any agent
npx skills add hajibabaie/combinatorial-optimization-skills --skill matheuristics
Clone the repo
git clone --depth 1 https://github.com/hajibabaie/combinatorial-optimization-skills

Made for: Claude Code.

Or install combinatorial-optimization, the plugin that ships this one along with the rest of its 76 skills.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

agentmods badge for matheuristics

README.md
[![agentmods](https://agentmods.dev/badge/skills/hajibabaie/combinatorial-optimization-skills/matheuristics/github.svg)](https://agentmods.dev/skills/hajibabaie/combinatorial-optimization-skills/matheuristics)
Your own site
<a href="https://agentmods.dev/skills/hajibabaie/combinatorial-optimization-skills/matheuristics"><img src="https://agentmods.dev/badge/skills/hajibabaie/combinatorial-optimization-skills/matheuristics/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

agentmods 80×15 button for matheuristics

Your own site · 80×15
<a href="https://agentmods.dev/skills/hajibabaie/combinatorial-optimization-skills/matheuristics"><img src="https://agentmods.dev/badge/skills/hajibabaie/combinatorial-optimization-skills/matheuristics.svg" alt="Reviewed on agentmods" width="80" height="20"></a>
Per session 146 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 11,790 The whole file, excluding the scripts and references it only reads on demand.
Security scan A 0 findings. A grade says what 26 rules found in the file — not that it is safe.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5.1 $0.00146 $0.11790
Opus 5 $0.00073 $0.05895
Sonnet 5 $0.00029 $0.02358
Haiku 4.5 $0.00015 $0.01179

Measured 10d ago against content hash 48c8a16c0690, method: parsed. Prices are Anthropic first-party input rates as of 2026-09-10, from the pricing page.

Security

Grade A, and why

matheuristics scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 10d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

skills/matheuristics/SKILL.md · 727 lines

How it starts

The opening of the file, as written. The whole thing — 727 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Matheuristics

You are an expert in matheuristics — model-based heuristics that embed an exact MIP solver inside a heuristic search loop. This skill covers fix-and-optimize, relax-and-fix, MIP-based destroy-and-repair (LNS with exact repair), local branching, proximity search and polishing, and the discipline of budgeting solver calls inside the loop. The reference treatment is Maniezzo, Boschetti & Stützle (2021), "Matheuristics: Algorithms and Implementations"; for routing-flavored variants see Archetti & Speranza (2014), "A survey on matheuristics for routing problems." Use the framework below to take a user from "the full MIP stalls at a 5% gap" to a calibrated hybrid that beats both the plain solver and a plain heuristic at equal wall clock.

Initial Assessment

Establish these facts before writing any hybrid code:

  • Full-MIP baseline. Run the complete model with the whole time budget first. Record incumbent, bound, and gap over time. If the solver reaches an acceptable gap, stop — a matheuristic only earns its complexity when the full model stalls. The baseline is also the honesty check every result must be compared against at equal wall clock.
  • Where the difficulty lives. Does the solver struggle to find good incumbents (weak primal side) or to move the bound (weak dual side)? Matheuristics attack the primal side only; if the bound is the problem, look at formulation tightening and cuts instead.
  • Decision core. Which variables are the combinatorial "deciders" (usually binaries: setups, assignments, openings) and which are followers (continuous quantities that an LP determines once the binaries are set)? Fixing schemes fix only the deciders; followers always re-optimize.
  • Decomposition dimension. Is there a natural axis to slice the binaries — time periods, items, machines, regions, vehicles? Fix-and-optimize needs one; local branching and proximity search do not.
  • Feasible start. Does a feasible solution exist already (from a heuristic, from the solver's truncated run, from last week's plan)? If not, construction must be part of the method — relax-and-fix or a truncated MIP run.
  • Fixing feasibility. If part of an incumbent is fixed, does the subproblem stay feasible? Hard capacities, time windows, and inventory balances can make fixings dead-end. If so, plan soft feasibility: penalized slack/overtime variables in the model, kept expensive enough to be driven to zero.
  • Sub-MIP sizing. How many free binaries solve to optimality in 1–5 seconds on this model? Measure it: solve a few random windows of increasing size and log status and runtime. This number drives every window/radius parameter.
  • Total budget and split. How much wall clock per instance, and how should it split between construction, improvement, and a final polishing phase? Count solver calls: budget B with per-call limit tau gives roughly B/tau calls; window schemes must fit.
  • Persistent model. Can one model object live in memory for the whole run so fixing happens through variable bounds? Rebuilding the model per iteration is the most common self-inflicted slowdown.
  • Objective structure. Single objective or lexicographic? Penalty terms already present? Acceptance tests and cutoffs need a single comparable scalar.
  • Solver features available. Gurobi-class solvers expose Cutoff, MIPFocus, Start values, solution pools, and callbacks — all essential here. With CBC/HiGHS the same patterns work but per-call budgets must grow; see the library table.
  • Comparison protocol. Instance set, seeds per instance, and equal-budget reporting against the full MIP — fix these before tuning, exactly as for any metaheuristic.

Read the full file on GitHub · 727 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 10d ago First seen · 727 lines · 146 tokens per session scan A 48c8a16c0690

Subscribe to this mod's changes

matheuristics is a skill published in the GitHub repository hajibabaie/combinatorial-optimization-skills (7 stars, last pushed 2mo ago), licensed MIT. It adds 146 tokens to every session and 11,790 once invoked, about $0.0007 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

Related

Other skills, from other repositories

learn-from-fix

Capture Elixir/Ecto/LiveView lessons and Hex API rules. Use after corrections or when asked to document learning, record a lesson, prevent a fixed mistake, or remember package guidance with --library.

oliver-kriska/claude-elixir-phoenix · 46 tokens

phx-deps-audit

Audit Hex deps for supply-chain security risk — bidi chars, compile-time exec, maintainer changes, typosquats, CVEs. Use after mix deps.update, when checking if a package upgrade is safe, or reviewing mix.lock PR diffs.

oliver-kriska/claude-elixir-phoenix · 58 tokens

promote

Generate X/Twitter release promotion posts with ASCII tables and CodeSnap rendering. Use when writing release posts, promotion tweets, plugin announcements, or preparing social media content for new versions.

oliver-kriska/claude-elixir-phoenix · 39 tokens

release

CONTRIBUTOR TOOL - Cut a plugin release: bump plugin.json version, finalize CHANGELOG, update README if needed, gate on make ci, commit, tag vX.Y.Z, and create the GitHub release. Use when shipping a new plugin version. NOT distributed.

oliver-kriska/claude-elixir-phoenix · 60 tokens

session-deep-dive

Deep qualitative analysis of high-signal sessions. Spawns subagents with v2 template, synthesizes patterns, compares against known findings. Use after /session-scan.

oliver-kriska/claude-elixir-phoenix · 40 tokens

catchup

Summarize and review what changed while you were away. Use after a weekend, vacation, or flight to check missed PRs, git commits, Linear tickets, and meetings — one prioritized brief, not a firehose.

oliver-kriska/claude-elixir-phoenix · 48 tokens