AMPL experts support with Agentic AI

On demand expert knowledge for modeling, solver tuning, debugging, explainability, installation for Mathematical Optimization with AMPL. This repository includes Skills, Agents, and Rules for agentic tools like Claude Code, Codex, Cursor...

Layer	Question it answers	Activation	Location
Skills	How do I do this task?	Loaded on demand when `description` matches	skills/
Agents	Who handles this bounded, read-only job?	Delegated to a separate context, returns a report	agents/
Rules	What must always be true?	Always-on, every AMPL task	rules/

Knowledge consists in Markdown files for Skills, Agents, Rules, and also a References section pointing to official documentation sources to improve quality of replies and reduce hallucinations (internet connection is recommended when using this repo).

Install

This repo is laid out so agentic tools discover it automatically. Place it where your tool already looks:

Scope	Cursor	Claude Code	Codex
This project only	`.cursor/`	`.claude/`	`.codex/`
All projects (home)	`~/.cursor/`	`~/.claude/`	`~/.codex/`

# Project-local (from your AMPL project root) — pick one
git clone <this-repo-url> .cursor
git clone <this-repo-url> .claude
git clone <this-repo-url> .codex

# Or globally for every project
git clone <this-repo-url> ~/.cursor
git clone <this-repo-url> ~/.claude
git clone <this-repo-url> ~/.codex

Recommended: keep skills/, agents/, rules/, and references/ as separate folders under .cursor, .claude, or .codex (project or home). Most tools infer those paths correctly even if the layout is flatter, but the separated folders match how Cursor, Claude Code, and Codex discover content and avoid collisions with other config in the same directory.

If that folder already exists, clone elsewhere and copy (or symlink) skills/, agents/, rules/, and references/ into it.

That is enough. The repo root maps onto the tool folder, so:

skills/ — on-demand playbooks (ampl-installer, ampl-modeler, ampl-tuner, ampl-python, ampl-callbacks, ampl-energy, ampl-supply-chain)
agents/ — delegated specialists (ampl-debugger, ampl-explainer, ampl-supervisor)
rules/ — always-on constraints (verified solve, model structure, verified URLs, session hygiene, routing)
references/references.md — URL library the agent should open and fetch from before inventing AMPL syntax or solver options

The skill ↔ agent split is a packaging hint, not a hard law — move a file either way if your harness behaves better that way. Any single markdown file also works pasted or @-attached as a system prompt (portability note).

Tip: description-matching usually picks the right skill or agent, but naming it explicitly gives more reliable behavior — e.g. /ampl-tuner, @ampl-debugger, or "use the ampl-energy skill". Prefer an explicit call when the task is ambiguous or you want a specific specialist.

Smoke check: ask to install amplpy, build a unit-commitment model, debug an infeasible solve, or tune Gurobi options — the matching skill or agent should load, and it should consult references/references.md before inventing options.

Agents & Skills

Name	Type	Description
ampl-installer	skill	Install amplpy, AMPL modules (solvers), and license activation
ampl-modeler	skill	Model LP, MIP, MINLP, NLP, CP, and quadratic problems in AMPL
ampl-tuner	skill	Configure AMPL/MP solver options (gaps, time limits, IIS, algorithms)
ampl-python	skill	amplpy / Python integration — scripts, notebooks, data pipelines
ampl-callbacks	skill	Solver callbacks with ampls: lazy constraints, user cuts, Benders, custom stopping
ampl-energy	skill	Electric power and energy systems (UC, OPF, BESS, markets)
ampl-supply-chain	skill	Supply chain MIPs — network design, location, routing, inventory
ampl-debugger	agent	Diagnose infeasibility, unboundedness, IIS, and solve failures
ampl-explainer	agent	Explain models — variable-constraint linkage, logic, complexity
ampl-supervisor	agent	Review models and amplpy workflows for smells and best practices

Skills load on demand when their description matches. Agents are delegated to a separate (read-only) context and return a report. Skill frontmatter uses a single-line description; agent frontmatter uses a YAML block scalar.

Rules (always-on)

Rule	File
Never claim a solve outcome without a verified `solve_result`	ampl-verified-solve.md
`.mod` + `ampl.read()`; `ampl.eval()` only for short fragments	ampl-model-structure.md
Cite only verified URLs; fetch before inventing syntax/options	ampl-verified-references.md
amplpy session hygiene (one `AMPL()` per worker, `close()`, no committed UUIDs)	ampl-session-hygiene.md
Tie-breakers when more than one skill/agent plausibly matches	ampl-routing-disambiguation.md

Portability note

Skills and Agents (in the Claude/Cursor sense of on-demand-loaded vs. delegated-context files) are Claude/Cursor-native packaging, not a different file format. Every file in this repo is still plain markdown with name + description frontmatter and no tool/model lists — a harness with no skill or agent discovery can load any single file directly as a system prompt, exactly as the original flat agents/ layout worked. What changed is which files get auto-discovered and which get delegated; not the self-containment of the content itself.

Verified references

Canonical library: references/references.md — every URL cited anywhere in this repo is listed there (install, IDE, MP guide, solvers, Colab notebooks, MO-Book, complete alphabetical index §10). Add new links to that file when updating a skill, agent, or rule.

About this project

Beta repo to make the most of your optimization tools. Please, feel free to send suggestions to [email protected]

ampl-agents