Improve/skill review optimization

ANDES/SKILL.md

@@ -1,23 +1,31 @@
 ---
 name: andes
-description: Progressive-disclosure workflow for ANDES studies. Use when the user asks to run ANDES through PowerMCP for power flow, small-signal stability, or time-domain simulation, and when the agent should expose base-case steps before advanced dynamic analysis.
+description: "Sets up and runs ANDES power-flow cases, performs small-signal stability eigenvalue analysis, and executes time-domain transient simulations via PowerMCP. Use when the user asks to run load flow, eigenvalue analysis, transient stability, dynamic simulation, or voltage stability studies through ANDES, and when the agent should validate the base case before advancing to dynamic analysis."
 ---
 
 # ANDES workflow
 
 Expose ANDES tools in stages. Do not jump into dynamics until the base case is loaded, solved, and understood.
 
 ## Default tool ladder
-1. `run_power_flow(file_path)` to load the case and solve the steady-state point.
-2. `get_system_info()` to summarize buses, generators, dynamic states, and controls.
-3. `run_eigenvalue_analysis(file_path)` to screen oscillatory modes and poor damping.
-4. `run_time_domain_simulation(step_size, t_end)` only after the disturbance and success criteria are explicit.
+1. `run_power_flow(file_path)` — load the case and solve the steady-state point.
+2. `get_system_info()` — summarize buses, generators, dynamic states, and controls.
+3. `run_eigenvalue_analysis(file_path)` — screen oscillatory modes and poor damping.
+4. `run_time_domain_simulation(step_size, t_end)` — only after the disturbance and success criteria are explicit.
+
+**Example sequence:**
+```
+run_power_flow("ieee14.xlsx")          → base case solved, 14 buses, 5 generators
+get_system_info()                      → lists dynamic models, governor and exciter types
+run_eigenvalue_analysis("ieee14.xlsx") → dominant mode 0.42 Hz, damping 3.1 % — flagged
+run_time_domain_simulation(0.01, 10.0) → generator trip at t=1 s, monitor rotor angles
+```
 
 ## Working rules
 - Re-run the base power flow after any model or dispatch change before dynamic work.
 - State the disturbance, clearing time, monitored channels, and pass or fail criteria before time-domain runs.
 - Treat eigenvalue results as screening. Confirm critical cases in time domain.
-- Hand off to `dynamic-stability-mitigation` when damping, angle stability, or voltage recovery is unacceptable.
+- Hand off to [dynamic-stability-mitigation](../dynamic-stability-mitigation/SKILL.md) when damping, angle stability, or voltage recovery is unacceptable.
 
 ## Deliver
 - The case used and whether the base case solved.

PyPSA/SKILL.md

@@ -8,25 +8,33 @@ description: Progressive-disclosure workflow for PyPSA studies. Use when the use
 Start by creating or loading a named network handle. Use network inspection before optimization, and use operational optimization before investment optimization.
 
 ## Default tool ladder
-1. `load_network(file_path)` or `create_network(...)` to create the active network handle.
-2. `get_network_info(network_name)` and `get_component_details(...)` to understand topology, assets, and time series.
-3. `run_power_flow(network_name, linear=False)` for feasibility checks.
-4. `optimize_network(network_name, ...)` for dispatch or operational studies.
-5. `optimize_investment(network_name, ...)` for expansion questions.
-6. `import_from_csv_folder(...)` or `export_to_csv_folder(...)` once the network state is worth moving.
+1. `load_network(file_path)` or `create_network(...)` — create the active network handle.
+2. `get_network_info(network_name)` and `get_component_details(...)` — understand topology, assets, and time series.
+3. `run_power_flow(network_name, linear=False)` — feasibility checks.
+4. `optimize_network(network_name, ...)` — dispatch or operational studies.
+5. `optimize_investment(network_name, ...)` — expansion questions.
+6. `import_from_csv_folder(...)` or `export_to_csv_folder(...)` — once the network state is worth moving.
+
+**Example sequence:**
+```
+load_network("case39.nc")                         → network "case39" active, 39 buses
+get_network_info("case39")                        → 10 generators, 46 lines, 19 loads
+run_power_flow("case39", linear=False)            → converged, max line loading 87 %
+optimize_network("case39", solver_name="highs")   → dispatch cost $48,200/h
+```
 
 ## Working rules
 - Do not jump straight into expansion optimization when a dispatch study can answer the question.
 - Use AC or DC power flow to sanity-check a network before relying on optimization outputs.
 - Treat PyPSA as a planning and scheduling engine, not the final authority on detailed reactive mitigation.
-- Hand off infeasibility, curtailment, and reserve issues to `operations-planning-mitigation`.
+- Hand off infeasibility, curtailment, and reserve issues to [operations-planning-mitigation](../operations-planning-mitigation/SKILL.md).
 
 ## Local assets in this repo
-- `PyPSA/case39.nc` for a ready test network.
-- `PyPSA/scripts/network_analysis.py` for inspection.
-- `PyPSA/scripts/optimization_analysis.py` for OPF result review.
-- `PyPSA/scripts/expansion_analysis.py` for capacity expansion studies.
-- `PyPSA/scripts/contingency_analysis.py` for local N-1 screening outside PowerMCP.
+- [`PyPSA/case39.nc`](case39.nc) — ready test network.
+- [`PyPSA/scripts/network_analysis.py`](scripts/network_analysis.py) — inspection.
+- [`PyPSA/scripts/optimization_analysis.py`](scripts/optimization_analysis.py) — OPF result review.
+- [`PyPSA/scripts/expansion_analysis.py`](scripts/expansion_analysis.py) — capacity expansion studies.
+- [`PyPSA/scripts/contingency_analysis.py`](scripts/contingency_analysis.py) — local N-1 screening outside PowerMCP.
 
 ## Deliver
 - The network handle and study type.

contingency-mitigation/SKILL.md

@@ -1,19 +1,22 @@
 ---
 name: contingency-mitigation
-description: Senior power-engineer playbook for contingency violations. Use when N-1 or N-2 studies reveal voltage or thermal problems and the agent needs to move from ranking contingencies to identifying preventive or corrective actions.
+description: "Senior power-engineer playbook for contingency violations. Use when N-1 or N-2 security analysis reveals voltage or thermal problems, transmission constraints, branch overloads, or power-flow violations, and the agent needs to move from ranking contingencies to identifying preventive or corrective actions such as generator redispatch, capacitor bank switching, topology changes, load curtailment, or remedial action schemes."
 ---
 
 # Contingency mitigation
 
 Start with a solved base case and a ranked list of critical contingencies.
 
 ## Preferred action order
-1. Verify the contingency definitions, monitored elements, and limits.
-2. Group critical contingencies by common corridor, interface, or weak area.
-3. Apply preventive actions first: redispatch, shunts, tap changes, or topology changes that help multiple contingencies.
-4. Evaluate corrective actions next: post-contingency switching, redispatch, or RAS schemes with explicit triggers.
-5. Use load shedding only as a last-resort action and state that clearly.
-6. For recurring problems, recommend reinforcement or a revised operating guide.
+1. **Verify** the contingency definitions, monitored elements, and limits.
+2. **Group** critical contingencies by common corridor, interface, or weak area.
+3. **Apply preventive actions** first: generator redispatch, shunt/capacitor switching, tap changes, or topology changes that help multiple contingencies.
+4. **Evaluate corrective actions** next: post-contingency switching, redispatch, or RAS schemes with explicit triggers.
+5. **Re-run** the full monitored set after any candidate fix. If violations remain, return to step 3 with updated rankings.
+6. Use load shedding only as a last-resort action and state that clearly.
+7. For recurring problems, recommend reinforcement or a revised operating guide.
+
+**Example:** N-1 loss of Line X–Y causes thermal overload on Line A–B (108 % rating) and voltage dip at Bus C (0.91 pu). Grouping reveals both violations share the same east-west corridor. Redispatching 60 MW from G1 to G4 clears the thermal violation; switching in the 50 Mvar capacitor bank at Bus C restores voltage to 0.97 pu. Re-running all monitored contingencies confirms no new violations.
 
 ## Working rules
 - Do not trust contingency results from a bad base case.

pandapower/SKILL.md

@@ -8,15 +8,15 @@ description: Progressive-disclosure workflow for pandapower studies. Use when th
 Start with the network model and a clean base-case solve. Use contingency analysis only after the steady-state case is credible.
 
 ## Default tool ladder
-1. `load_network(file_path)` or `create_empty_network()`
-2. `get_network_info()` to inspect buses, lines, transformers, generators, loads, and switches.
-3. `run_power_flow(...)` to establish the base operating point.
-4. `run_contingency_analysis(...)` only after the base case solves and the monitoring limits are clear.
+1. `load_network(file_path)` or `create_empty_network()` — load or create the network model.
+2. `get_network_info()` — inspect buses, lines, transformers, generators, loads, and switches.
+3. `run_power_flow(net)` — establish the base operating point. Check `net.res_bus.vm_pu` for voltage and `net.res_line.loading_percent` for thermal limits.
+4. `run_contingency_analysis(...)` — only after the base case solves and the monitoring limits are clear.
 
 ## Working rules
 - Do not run contingencies before checking the base-case voltages and loading.
 - Use pandapower for AC feasibility and fast screening, then escalate only when the question requires more.
-- Use `voltage-violation-mitigation`, `thermal-overload-mitigation`, or `contingency-mitigation` after violations are identified.
+- Use [voltage-violation-mitigation](../voltage-violation-mitigation/SKILL.md), [thermal-overload-mitigation](../thermal-overload-mitigation/SKILL.md), or [contingency-mitigation](../contingency-mitigation/SKILL.md) after violations are identified.
 
 ## Local assets in this repo
 - `pandapower/case39.json` for a ready test network.

thermal-overload-mitigation/SKILL.md

@@ -1,18 +1,21 @@
 ---
 name: thermal-overload-mitigation
-description: Senior power-engineer playbook for overloaded lines and transformers. Use when power-flow or contingency studies show loading above ratings and the agent needs an operationally credible sequence of redispatch, topology, and reinforcement actions.
+description: "Senior power-engineer playbook for thermal overloads on lines and transformers. Use when power-flow or contingency studies show branch loading above MVA ratings, N-1 violations, line rating exceedances, or congestion, and the agent needs an operationally credible sequence of generation redispatch, bus-splitting, phase-shifter adjustment, conductor upsizing, or load curtailment."
 ---
 
 # Thermal overload mitigation
 
 Start with the monitored element, the applicable rating, and the driving condition.
 
 ## Preferred action order
-1. Confirm the overload is real: correct rating set, correct outage state, and solved base case or contingency.
-2. Redispatch generation or transfer patterns to unload the corridor.
-3. Reconfigure topology or switching where operations permit.
-4. Use phase shifters, HVDC schedules, or transformer controls only when sensitivity evidence supports them.
-5. If the issue is persistent, move to reconductoring, uprating, or new facilities.
+1. **Confirm** the overload is real: correct rating set, correct outage state, and solved base case or contingency.
+2. **Redispatch** generation or transfer patterns to unload the corridor.
+3. **Reconfigure** topology or switching where operations permit (bus-splitting, line switching).
+4. **Adjust controls** — phase shifters, HVDC schedules, or transformer taps — only when sensitivity evidence supports them.
+5. **Reinforce** if the issue is persistent: reconductoring, uprating, or new facilities.
+6. After each action, re-solve and verify the overload is relieved. If not, proceed to the next step.
+
+**Example:** Line A–B loaded at 105 % of normal rating after N-1 loss of Line C–D. PTDF shows Generator G3 has −0.18 sensitivity. Redispatching 40 MW from G3 to G5 reduces loading to 94 % — verified by re-solving all monitored contingencies.
 
 ## Working rules
 - Separate normal-rating issues from emergency-rating issues.