ChrisPulman · ChrisPulman · May 9, 2026 · May 9, 2026
diff --git a/.mcp/install.md b/.mcp/install.md
@@ -19,14 +19,22 @@ Suggested stdio config after NuGet publication:
     "codex-computer-run": {
       "command": "dnx",
       "args": [
-        "CP.CodexComputerRun.Mcp.Server@0.*",
+        "CP.CodexComputerRun.Mcp.Server@1.*",
         "--yes"
       ]
     }
   }
 }
 ```
 
+Bundled Codex Skill install:
+
+```powershell
+codex-computer-run-mcp-server --install-codex-skill
+```
+
+The server also auto-installs the bundled `codex-computer-run` skill on startup when `CODEX_HOME` is set or `%USERPROFILE%\.codex` already exists. Existing skill files are left untouched unless the installer is run with `--force`.
+
 Alternative source-run config for development:
 
 ```json

diff --git a/.mcp/server.json b/.mcp/server.json
@@ -2,14 +2,14 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.chrispulman/codex-computer-run-mcp-server",
   "title": "Codex Computer Run MCP Server",
-  "description": "Windows-only MCP server for Codex desktop control: screenshots, mouse, keyboard, clipboard paste, cursor position, and visible window discovery.",
-  "version": "0.1.0",
+  "description": "Windows-only MCP server for Codex desktop control: screenshots, mouse, keyboard, clipboard paste, cursor position, visible window discovery, and a bundled Codex Skill.",
+  "version": "1.0.0",
   "packages": [
     {
       "registryType": "nuget",
       "registryBaseUrl": "https://api.nuget.org/v3/index.json",
       "identifier": "CP.CodexComputerRun.Mcp.Server",
-      "version": "0.1.0",
+      "version": "1.0.0",
       "runtimeHint": "dnx",
       "transport": {
         "type": "stdio"

diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@
 <!-- mcp-name: io.github.chrispulman/codex-computer-run-mcp-server -->
 
 Codex Computer Run MCP Server gives Codex and other MCP-capable agents direct control over a signed-in Windows desktop session.
-It exposes focused tools for screenshots, mouse movement, clicks, scrolling, keyboard shortcuts, Unicode paste, cursor position, and visible window discovery.
+It exposes focused tools for screenshots, mouse movement, clicks, scrolling, keyboard shortcuts, Unicode paste, cursor position, and visible window discovery, plus a bundled Codex Skill for safe desktop-use workflows.
 
 It is implemented in C# on `net10.0` using `ModelContextProtocol` `1.2.0`.
 The package targets plain `net10.0` so it can be distributed as a .NET tool; all desktop operations remain Windows-only through runtime guards and Win32 interop.
@@ -12,9 +12,9 @@ The package targets plain `net10.0` so it can be distributed as a .NET tool; all
 
 Click to install in your preferred environment:
 
-[![VS Code - Install Codex Computer Run MCP](https://img.shields.io/badge/VS_Code-Install_Codex_Computer_Run_MCP-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=codex-computer-run-mcp-server&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22dnx%22%2C%22args%22%3A%5B%22CP.CodexComputerRun.Mcp.Server%400.%2A%22%2C%22--yes%22%5D%7D)
-[![VS Code Insiders - Install Codex Computer Run MCP](https://img.shields.io/badge/VS_Code_Insiders-Install_Codex_Computer_Run_MCP-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=codex-computer-run-mcp-server&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22dnx%22%2C%22args%22%3A%5B%22CP.CodexComputerRun.Mcp.Server%400.%2A%22%2C%22--yes%22%5D%7D&quality=insiders)
-[![Visual Studio - Install Codex Computer Run MCP](https://img.shields.io/badge/Visual_Studio-Install_Codex_Computer_Run_MCP-5C2D91?style=flat-square&logo=visualstudio&logoColor=white)](https://vs-open.link/mcp-install?%7B%22name%22%3A%22CP.CodexComputerRun.Mcp.Server%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22dnx%22%2C%22args%22%3A%5B%22CP.CodexComputerRun.Mcp.Server%400.%2A%22%2C%22--yes%22%5D%7D)
+[![VS Code - Install Codex Computer Run MCP](https://img.shields.io/badge/VS_Code-Install_Codex_Computer_Run_MCP-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=codex-computer-run-mcp-server&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22dnx%22%2C%22args%22%3A%5B%22CP.CodexComputerRun.Mcp.Server%401.%2A%22%2C%22--yes%22%5D%7D)
+[![VS Code Insiders - Install Codex Computer Run MCP](https://img.shields.io/badge/VS_Code_Insiders-Install_Codex_Computer_Run_MCP-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=codex-computer-run-mcp-server&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22dnx%22%2C%22args%22%3A%5B%22CP.CodexComputerRun.Mcp.Server%401.%2A%22%2C%22--yes%22%5D%7D&quality=insiders)
+[![Visual Studio - Install Codex Computer Run MCP](https://img.shields.io/badge/Visual_Studio-Install_Codex_Computer_Run_MCP-5C2D91?style=flat-square&logo=visualstudio&logoColor=white)](https://vs-open.link/mcp-install?%7B%22name%22%3A%22CP.CodexComputerRun.Mcp.Server%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22dnx%22%2C%22args%22%3A%5B%22CP.CodexComputerRun.Mcp.Server%401.%2A%22%2C%22--yes%22%5D%7D)
 
 Note:
 - These install links are prepared for the intended NuGet package identity `CP.CodexComputerRun.Mcp.Server`.
@@ -60,6 +60,40 @@ When this server is active, agents should follow this operating protocol:
 5. Prefer `type_text` for text entry because it uses Unicode clipboard paste and is faster and more reliable than simulated per-character typing.
 6. Keep screenshots small in conversation by setting `include_image` to `false` when only dimensions or a saved path are needed.
 
+## Codex Skill
+
+The repository and NuGet package include a Codex Skill at `skills/codex-computer-run`. The skill teaches Codex the observation-first workflow, safety rules, and exact MCP tool names for this server.
+
+When the packaged server starts, it tries to install the skill into the current Codex installation if `CODEX_HOME` is set or `%USERPROFILE%\.codex` already exists. Existing skill files are not overwritten during automatic install.
+
+Manual install from a globally installed tool:
+
+```powershell
+dotnet tool install --global CP.CodexComputerRun.Mcp.Server --version 1.*
+codex-computer-run-mcp-server --install-codex-skill
+```
+
+Manual install from source:
+
+```powershell
+dotnet run --project .\src\CodexComputerRunMCPServer\CodexComputerRunMCPServer.csproj -- --install-codex-skill
+```
+
+Set `CODEX_HOME` first if Codex uses a non-default location:
+
+```powershell
+$env:CODEX_HOME = "C:\Users\you\.codex"
+codex-computer-run-mcp-server --install-codex-skill
+```
+
+To refresh an existing installed copy with the packaged skill files, add `--force`.
+
+Use the skill in Codex by asking for it explicitly, for example:
+
+```text
+Use $codex-computer-run to list visible windows, take a screenshot, and confirm the active desktop state.
+```
+
 ## Available MCP Tools
 
 ### `screenshot`
@@ -195,6 +229,9 @@ src/
 .mcp/
 |-- server.json                         # MCP registry/package metadata
 `-- install.md                          # Manual MCP install snippets
+
+skills/
+`-- codex-computer-run/                 # Codex Skill bundled into the NuGet package
 ```
 
 ## Configuration
@@ -226,6 +263,22 @@ Published executable:
 }
 ```
 
+NuGet package through `dnx`:
+
+```json
+{
+  "mcpServers": {
+    "codex-computer-run": {
+      "command": "dnx",
+      "args": [
+        "CP.CodexComputerRun.Mcp.Server@1.*",
+        "--yes"
+      ]
+    }
+  }
+}
+```
+
 Development source run:
 
 ```json
@@ -253,6 +306,7 @@ No. They are optional convenience snippets for MCP clients that import JSON conf
 Required or primary MCP/Codex files are:
 - `.mcp/server.json` for MCP package metadata.
 - `.mcp/install.md` for install notes.
+- `skills/codex-computer-run` for the bundled Codex Skill.
 - `.codex/config.toml` for this local Codex workspace.
 - `.mcp.json` only if your client reads repository-local MCP JSON configuration.
 
@@ -282,8 +336,9 @@ dotnet test .\src\CodexComputerRunMCPServer.Tests\CodexComputerRunMCPServer.Test
 ```
 
 Current verification:
-- 23 TUnit tests passed.
-- Coverage: 100% line coverage, 98.44% branch coverage for testable code.
+- 32 TUnit tests passed.
+- Coverage: 91.56% line coverage, 79.03% branch coverage for testable code.
+- NuGet package verification confirms `skills/codex-computer-run/SKILL.md` and `skills/codex-computer-run/agents/openai.yaml` are bundled.
 - Native Win32 P/Invoke shims are excluded from coverage and verified through the service boundary plus live MCP tool discovery.
 
 ## Publish

diff --git a/skills/codex-computer-run/SKILL.md b/skills/codex-computer-run/SKILL.md
@@ -0,0 +1,61 @@
+---
+name: codex-computer-run
+description: Use this skill when Codex needs to operate or inspect a signed-in Windows desktop through the Codex Computer Run MCP server, including screenshots, visible window discovery, cursor position checks, mouse movement, clicking, scrolling, keyboard shortcuts, single-key presses, or Unicode text paste into focused applications.
+---
+
+# Codex Computer Run
+
+## Overview
+
+Use the Codex Computer Run MCP server as an observation-first control layer for a real Windows desktop session. Its tools affect the active machine, so inspect context before acting and verify after actions that can change state.
+
+## Tool Discovery
+
+- Prefer the `mcp__codex_computer_run__` namespace when available.
+- If tools are deferred, search for `ComputerRun`, `codex computer run`, or `desktop screenshot mouse keyboard` and choose the namespace that exposes the complete tool set.
+- Expect these tools: `screenshot`, `list_windows`, `cursor_position`, `move_mouse`, `click`, `scroll`, `press_key`, `hotkey`, and `type_text`.
+- If the MCP tools are unavailable, state that the Computer Run server is not configured in the current session instead of simulating desktop interaction with unrelated shell commands.
+
+## Operating Protocol
+
+1. Observe before acting:
+   - Use `list_windows` to identify visible applications and likely targets.
+   - Use `screenshot` when visual layout, coordinates, or UI state matters.
+   - Use `cursor_position` before relying on the current pointer location.
+2. Plan in absolute Windows virtual-screen coordinates:
+   - Treat coordinates as desktop coordinates, not browser or app-relative coordinates.
+   - Read screenshot metadata for `left`, `top`, `width`, and `height`; multi-monitor layouts can have negative `left` or `top` values.
+   - Move or click only when the target application and coordinates are known.
+3. Act with the narrowest tool:
+   - Use `move_mouse` for hover or to position before a click.
+   - Use `click` for buttons, menus, tabs, selections, and context menus.
+   - Use `scroll` for pages, lists, combo boxes, and scrollable panes.
+   - Use `press_key` for one key such as `enter`, `tab`, `escape`, `f5`, arrows, or a single character.
+   - Use `hotkey` for shortcuts such as `ctrl+l`, `ctrl+shift+p`, `alt+tab`, or `ctrl+shift+escape`.
+   - Use `type_text` for text entry; it pastes Unicode through the clipboard and is faster and more reliable than repeated key presses.
+4. Verify after meaningful actions:
+   - Use `screenshot` after navigation, clicks, scrolls, or text entry when the resulting state matters.
+   - Use `list_windows` again after task switching or launching apps.
+
+## Screenshots
+
+- Use `screenshot` with `include_image: true` when the model needs to inspect the pixels.
+- Use `include_image: false` with a `path` when only dimensions, a saved artifact, or later local inspection is needed.
+- Save screenshots to an explicit temporary or workspace path when they may be referenced in the final answer.
+
+## Safety Rules
+
+- Remember that mouse, keyboard, and clipboard actions affect the user's signed-in desktop.
+- Do not perform destructive UI actions, submit forms, send messages, make purchases, delete files, or change account/security settings unless the user explicitly asked for that exact outcome.
+- Confirm the intended foreground app with `list_windows` or `screenshot` before typing or pressing shortcuts that could affect the wrong application.
+- Treat `type_text` as clipboard-changing; use it only when pasting into the focused target is intended.
+- Keep delays short but use the optional `delay` parameter after actions that trigger UI transitions.
+
+## Quick Checks
+
+For a non-destructive connectivity test:
+
+1. Call `list_windows` with a small limit and confirm visible window metadata is returned.
+2. Call `cursor_position` and confirm JSON coordinates are returned.
+3. Call `screenshot` with a saved `path` and `include_image: false`; confirm screenshot metadata includes the saved path and virtual desktop bounds.
+4. Optionally move the cursor by a small, reversible amount with `move_mouse`, then call `cursor_position` again to confirm the new coordinates.
diff --git a/skills/codex-computer-run/agents/openai.yaml b/skills/codex-computer-run/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+  display_name: "Codex Computer Run"
+  short_description: "Control the Windows desktop through MCP"
+  default_prompt: "Use $codex-computer-run to inspect the desktop, list windows, and interact with Windows UI safely."