docs: add bilingual OptSkills walkthrough

skills/optskills/README.md

@@ -1,5 +1,7 @@
 # OptSkills
 
+[中文](README.zh-CN.md)
+
 OptSkills is a standalone thin entrypoint to 103 released OptSkills
 problem-archetype cards. It helps an agent select a card, formulate the
 user's actual operations-research problem, solve it when the environment
@@ -11,17 +13,19 @@ The library contains 93 NanoCO cards and 10 learned-only cards. It includes no
 cluster duplicate and no `ingredients.json`. The selected cards and their
 relative paths are listed in `skill_library/index.json`.
 
-## Installation
+## Install with a coding agent
+
+Give this prompt to your coding agent:
 
-Clone `VeryMath/AI4Math-Optimization`, then link only `skills/optskills` into
-the agent's skill directory:
+> Install `skills/optskills` from the GitHub repository
+> `VeryMath/AI4Math-Optimization`. Install only this standalone Skill. Detect
+> the skill directory used by the current coding agent, link or copy the
+> package there, and verify that `optskills` is discoverable. Report the
+> installed path, whether a restart is needed, and one test prompt.
 
-```bash
-git clone https://github.com/VeryMath/AI4Math-Optimization.git
-cd AI4Math-Optimization
-mkdir -p ~/.codex/skills
-ln -s "$PWD/skills/optskills" ~/.codex/skills/optskills
-```
+The coding agent should clone or update the repository, locate the correct
+skill directory for its environment, install the package, and verify
+discovery. The user does not need to choose a local directory first.
 
 ## Quick start
 
@@ -31,6 +35,9 @@ Use this prompt:
 > `skill_library/index.json`, formulate my problem, solve it if possible, and
 > check the key constraints.
 
+See [Solving an assignment problem with OptSkills](assignment-problem-example.md)
+for a complete walkthrough.
+
 ## Updates
 
 Use this prompt only when an upstream update is wanted:

skills/optskills/README.zh-CN.md

@@ -1,5 +1,7 @@
 # OptSkills
 
+[English](README.md)
+
 OptSkills 是一个独立的薄入口，连接 103 张已发布的 OptSkills
 问题原型卡片。它帮助智能体选择卡片、为用户的实际运筹问题建模、在环境允许时求解，并如实报告已检查的内容。
 
@@ -9,17 +11,17 @@ OptSkills 是一个独立的薄入口，连接 103 张已发布的 OptSkills
 cluster 卡片，也不包含 `ingredients.json`。选中的卡片及其相对路径列在
 `skill_library/index.json` 中。
 
-## 安装
+## 让 Coding Agent 安装
+
+把下面的提示词发给 Coding Agent：
 
-克隆 `VeryMath/AI4Math-Optimization`，然后只把 `skills/optskills`
-链接到智能体的技能目录：
+> 请从 GitHub 仓库 `VeryMath/AI4Math-Optimization` 安装
+> `skills/optskills`。只安装这个独立 Skill，自动判断当前 Coding Agent
+> 的技能目录，完成链接或复制并验证能否发现 `optskills`。最后告诉我安装
+> 路径、是否需要重启，并给出一个测试提示词。
 
-```bash
-git clone https://github.com/VeryMath/AI4Math-Optimization.git
-cd AI4Math-Optimization
-mkdir -p ~/.codex/skills
-ln -s "$PWD/skills/optskills" ~/.codex/skills/optskills
-```
+Coding Agent 应负责克隆或更新仓库、找到当前环境的技能目录、完成安装并
+验证发现结果。用户不需要先判断应使用哪个本地目录。
 
 ## 快速开始
 
@@ -28,6 +30,8 @@ ln -s "$PWD/skills/optskills" ~/.codex/skills/optskills
 > 阅读 `SKILL.md`，通过 `skill_library/index.json` 选择相关的 OptSkills
 > 卡片，为我的问题建模，在可以时求解，并检查关键约束。
 
+完整过程见[用 OptSkills 求解一个指派问题](assignment-problem-example.zh-CN.md)。
+
 ## 更新
 
 只有需要上游更新时才使用下面的提示：

skills/optskills/assignment-problem-example.md

@@ -0,0 +1,166 @@
+# Solving an assignment problem with OptSkills
+
+[中文](assignment-problem-example.zh-CN.md)
+
+This walkthrough shows one complete OptSkills use: ask a coding agent to
+install the standalone Skill, describe an optimization problem in natural
+language, select a released archetype card, formulate and solve the model, and
+check the returned objective and constraints.
+
+## Ask a coding agent to install it
+
+Give this prompt to Codex, Claude Code, OpenCode, or another coding agent that
+supports Skills:
+
+```text
+Install skills/optskills from the GitHub repository
+VeryMath/AI4Math-Optimization. Install only this standalone Skill. Detect the
+skill directory used by the current coding agent, link or copy the package,
+and verify that a new session can discover optskills. Report:
+1. where the repository is stored;
+2. where the Skill is installed;
+3. whether discovery was verified;
+4. whether a restart or new conversation is needed;
+5. one prompt I can use to test it.
+If the destination already exists, do not overwrite it immediately. First
+check whether it comes from the same repository and explain what should happen.
+```
+
+The coding agent chooses the installation location from the discovery rules of
+its current environment. Installation means more than copying files: it should
+also confirm that a new session can see a Skill named `optskills`.
+
+## Submit the problem
+
+After installation, start a new conversation and enter:
+
+```text
+Use OptSkills to solve this assignment problem.
+
+Five virtual machines must be assigned to five physical servers. Every virtual
+machine must use exactly one server, and every server must receive exactly one
+virtual machine. Rows in this cost matrix are virtual machines and columns are
+servers:
+
+[[28, 15, 51, 19, 72],
+ [46, 44, 24, 14, 55],
+ [14, 18, 35, 61, 30],
+ [34, 41, 26, 50, 37],
+ [40, 53, 15, 62, 15]]
+
+Minimize the total assignment cost. Report the selected Skill, mathematical
+model, solver status, assignment, objective, and constraint checks. If no
+solver is available, identify the missing dependency instead of claiming that
+the problem was solved.
+```
+
+The data come from the public OptSkills record `AP_easy_1`.
+
+## How OptSkills handles it
+
+The agent first makes the package's lightweight upstream commit comparison. A
+matching version is silent. A failed lookup or newer version produces one short
+note and does not download the full upstream project during this task.
+
+The agent then reads `skill_library/index.json`. The one-to-one assignment,
+linear cost objective, and two families of exact-one constraints lead it to:
+
+```text
+skill_id: assignment_problem_solver
+path: skill_library/assignment_problem_solver.md
+```
+
+It loads this relevant card rather than all 103 cards.
+
+## Formulate the model
+
+Let the virtual-machine and server sets be
+
+$$
+I=J=\{1,2,3,4,5\}.
+$$
+
+Set $x_{ij}=1$ when virtual machine $i$ is assigned to server $j$, and set it
+to zero otherwise. Let $c_{ij}$ be the corresponding cost. The model is
+
+$$
+\min \sum_{i\in I}\sum_{j\in J}c_{ij}x_{ij},
+$$
+
+subject to
+
+$$
+\sum_{j\in J}x_{ij}=1\qquad \forall i\in I,
+$$
+
+$$
+\sum_{i\in I}x_{ij}=1\qquad \forall j\in J,
+$$
+
+and
+
+$$
+x_{ij}\in\{0,1\}.
+$$
+
+The first constraints assign every virtual machine exactly once. The second
+constraints use every server exactly once.
+
+## Solver result
+
+In the OR-Tools CP-SAT environment used for repository validation, the solver
+returned `OPTIMAL` with this assignment:
+
+| Virtual machine | Server | Cost |
+| --- | --- | ---: |
+| 1 | 2 | 15 |
+| 2 | 4 | 14 |
+| 3 | 1 | 14 |
+| 4 | 3 | 26 |
+| 5 | 5 | 15 |
+
+The total cost is
+
+$$
+15+14+14+26+15=84.
+$$
+
+## Check the result
+
+The agent should independently check the returned assignment instead of only
+repeating the solver's objective field:
+
+- solver status is `OPTIMAL`;
+- all five virtual-machine assignment counts equal 1;
+- all five server usage counts equal 1;
+- the recomputed total cost is 84;
+- the recomputed result equals the solver objective.
+
+Only after these checks can it report that this instance was solved and its
+constraints were verified.
+
+## If no solver is available
+
+OptSkills does not bundle OR-Tools, Pyomo, HiGHS, or a commercial solver. If a
+suitable solver is absent, the agent can still report the selected card,
+mathematical model, and solver code. It must distinguish “model formulated”
+from “solver executed” and ask before installing a new dependency.
+
+## Try another problem
+
+After one installation, a new conversation can use prompts such as:
+
+```text
+Use OptSkills to formulate a minimum-cost flow problem with arc capacities and
+unit transportation costs. After solving it, check every node balance and arc
+capacity.
+```
+
+```text
+Use OptSkills to formulate a flow-shop scheduling problem for multiple jobs and
+machines. Minimize makespan and check operation order and machine non-overlap.
+```
+
+For each task, report the selected card, formulated model, whether a solver was
+actually executed, objective check, constraint check, and remaining limitations
+as separate results.