microsoft · Yuge Zhang (ultmaster) · Aug 27, 2026 · Aug 27, 2026
diff --git a/README.md b/README.md
@@ -16,18 +16,33 @@
 - 🧩 **Train with real agent harnesses:** Agents interact with the model through the Agent Lightning v1.0 proxy with **ZERO changes**, while keeping tools, context, control flow, and environments in the loop.
 - ☸️ **Native Kubernetes support:** Run agents directly as Kubernetes Jobs without relying on external sandbox services.
 - 💻 **Full coding agent training example:** Using only **6K training samples**, an end-to-end Qwen3.5-9B workflow improves SWE-bench Verified from **41.8% to 56.4%**, a gain of **14.6 percentage points**. We release the full pipeline, including data cleaning, reward-hacking prevention, and training scripts.
+- 🛠️ **Agent optimization skill:** Give Claude Code, Codex, or GitHub Copilot an editable agent and a benchmark. The bundled [Agent Lightning skill](https://microsoft.github.io/agent-lightning/stable/10-agent-lightning-skill/) guides measured improvements to quality, cost, latency, and reliability.
+
+## ⚡ Agent Lightning Skill
+
+Agent Lightning also ships as a skill for coding agents. It helps a coding agent inspect an underperforming AI agent, test changes to prompts, tools, workflows, models, and other settings, and keep only improvements that hold up under evaluation.
+
+See [Optimize Agents with the Agent Lightning Skill](https://microsoft.github.io/agent-lightning/stable/10-agent-lightning-skill/) for a starter prompt, workflow, and benchmark results.
 
 ## ⚡ Installation
 
-The following is an example installation on a CUDA 13.0 machine:
+To install the Agent Lightning training framework on a CUDA 13.0 machine:
 
 ```bash
 cd <this-repo>
 uv sync
 bash scripts/setup_verl.sh 0.8.0 cu130
 ```
 
-See the [Installation Guide](https://microsoft.github.io/agent-lightning/stable/00-installation/) for details.
+The Agent Lightning skill installs separately from the training framework:
+
+```bash
+gh skill install microsoft/agent-lightning agent-lightning --agent claude-code
+gh skill install microsoft/agent-lightning agent-lightning --agent codex
+gh skill install microsoft/agent-lightning agent-lightning --agent github-copilot
+```
+
+See the [Installation Guide](https://microsoft.github.io/agent-lightning/stable/00-installation/) for details on both options.
 
 
 ## ⚡ Architecture
@@ -59,6 +74,7 @@ We evaluate Agent Lightning v1.0 across several practical training domains, incl
 | [Installation](https://microsoft.github.io/agent-lightning/stable/00-installation/) | Base environment and `verl` GPU stack |
 | [Quick Start](https://microsoft.github.io/agent-lightning/stable/01-quick-start/) | Local first run and end-to-end flow |
 | [Basics](https://microsoft.github.io/agent-lightning/stable/05-basics/) | Components, rollouts, events, and trajectories |
+| [Agent Lightning Skill](https://microsoft.github.io/agent-lightning/stable/10-agent-lightning-skill/) | Optimize an editable AI agent against a benchmark with a coding agent |
 | [Trainer Configuration](https://microsoft.github.io/agent-lightning/stable/20-trainer-configuration/) | `verl` integration and trace aggregation |
 | [API Gateway Configuration](https://microsoft.github.io/agent-lightning/stable/25-api-gateway-configuration/) | Gateway and model proxy settings |
 | [Controller Configuration](https://microsoft.github.io/agent-lightning/stable/30-controller-configuration/) | Local and Kubernetes runners |

diff --git a/docs/00-installation.md b/docs/00-installation.md
@@ -1,6 +1,10 @@
 # Installation
 
-This guide sets up a single-node environment for Agent Lightning v1.0. After completing it, you can run single-machine training jobs.
+This guide covers the Agent Lightning v1.0 training framework and the Agent Lightning skill for coding agents. They are installed separately and can be used independently.
+
+## Training Framework
+
+The following steps set up a single-node environment for Agent Lightning v1.0. After completing them, you can run single-machine training jobs.
 
 Before getting started, install `uv` and NVIDIA CUDA. We support CUDA `12.9` or `13.0`.
 
@@ -39,3 +43,15 @@ By default, all tasks upload logs and trajectories to Weights & Biases. Log in t
 ```bash
 uv run wandb login
 ```
+
+## Agent Lightning Skill
+
+Install the Agent Lightning skill directly from this repository for Claude Code, Codex, or GitHub Copilot:
+
+```bash
+gh skill install microsoft/agent-lightning agent-lightning --agent claude-code
+gh skill install microsoft/agent-lightning agent-lightning --agent codex
+gh skill install microsoft/agent-lightning agent-lightning --agent github-copilot
+```
+
+Choose the command for the coding agent you use. The skill does not require the training framework or its CUDA environment. See [Optimize Agents with the Agent Lightning Skill](10-agent-lightning-skill.md) for a starter prompt, workflow, and benchmark results.
diff --git a/docs/10-agent-lightning-skill.md b/docs/10-agent-lightning-skill.md
@@ -0,0 +1,34 @@
+# Optimize Agents with the Agent Lightning Skill
+
+Agent Lightning includes the [Agent Lightning Skill](https://github.com/microsoft/agent-lightning/tree/main/skills/agent-lightning) for Claude Code, Codex, and GitHub Copilot. Give a coding agent the source for an editable AI agent and a benchmark, and it can search for measured improvements to quality, cost, latency, and reliability without breaking the agent's deployment contract.
+
+The skill complements the Agent Lightning training framework. Use the skill when a coding agent can edit and evaluate the agent's implementation or configuration. Use the framework when you want to collect rollouts and train model weights with reinforcement learning.
+
+Install it by following the [Agent Lightning Skill installation instructions](00-installation.md#agent-lightning-skill).
+
+## Start an Optimization Run
+
+Open the workspace that contains the agent and its benchmark, then ask the coding agent to improve it. For example:
+
+> I've got an agent in this workspace, and it's underperforming on our benchmark. Raise its benchmark score while keeping any increase in per-run cost minimal. Buy score cheaply, and only pay more when it clearly earns its keep.
+
+The coding agent will use the skill to:
+
+- inspect the agent, benchmark, and deployment-visible inputs;
+- identify likely prompt, tool, workflow, model, routing, or recovery changes;
+- run controlled comparisons and account for noisy or stochastic results;
+- track both the one-time optimization budget and the final agent's per-run cost; and
+- leave a coherent, measured checkpoint that preserves the external interface.
+
+The workflow is most useful when the agent is editable, the benchmark is runnable, and the deployment contract is explicit. Held-out labels or training-only metadata should remain outside the deployed path.
+
+## Measured Results
+
+We evaluated the skill with Claude Code, Codex, and GitHub Copilot optimizing agents for SpreadsheetBench, OfficeQA, and ALFWorld. The results below average all three coding agents, the tested optimization budgets, and repeated runs. Parentheses show the percentage-point improvement over the original agent on held-out data. The starting-agent row is not shown in the table.
+
+| Method | SpreadsheetBench accuracy (%) | OfficeQA correctness (%) | ALFWorld success (%) |
+| :--- | ---: | ---: | ---: |
+| Coding agents without Agent Lightning | 62.9 (+37.3) | 54.1 (+22.3) | 88.6 (+31.6) |
+| **Coding agents with Agent Lightning** | **66.7 (+41.1)** | **54.5 (+22.7)** | **94.9 (+37.9)** |
+
+See the [full benchmark methodology and cost breakdowns](https://github.com/microsoft/agent-lightning/tree/main/skills#performance-breakdowns) for the tested budgets, baselines, repeated-run setup, and charts.
diff --git a/docs/README.md b/docs/README.md
@@ -22,6 +22,7 @@ For the legacy Agent Lightning releases earlier than v1.0, see the [`v0.x` code
 | [Installation](00-installation.md) | Set up the base environment and the tested `verl` GPU stack. |
 | [Quick Start](01-quick-start.md) | Run a local end-to-end rollout-driven training job. |
 | [Basics](05-basics.md) | Learn the core components, rollouts, events, and trajectories. |
+| [Agent Lightning Skill](10-agent-lightning-skill.md) | Use a coding agent to improve an editable AI agent against a benchmark. |
 
 ## Configuration
 

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -101,6 +101,7 @@ nav:
     - Installation: 00-installation.md
     - Quick Start: 01-quick-start.md
     - Basics: 05-basics.md
+    - Agent Lightning Skill: 10-agent-lightning-skill.md
     - Trainer Configuration: 20-trainer-configuration.md
     - API Gateway Configuration: 25-api-gateway-configuration.md
     - Controller Configuration: 30-controller-configuration.md