Add Codex session repair skill and cross-platform docs

.github/workflows/validate-skills.yml

@@ -0,0 +1,31 @@
+name: Validate skills
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install validator dependency
+        run: python -m pip install --disable-pip-version-check pyyaml
+      - name: Validate skill metadata
+        run: |
+          python - <<'PY'
+          import pathlib, subprocess, sys
+          validator = pathlib.Path.home() / '.agents' / 'skills' / 'skill-creator' / 'scripts' / 'quick_validate.py'
+          root = pathlib.Path('codex-cross-provider-session-repair')
+          if validator.exists():
+              subprocess.check_call([sys.executable, str(validator), str(root)])
+          else:
+              text = (root / 'SKILL.md').read_text(encoding='utf-8')
+              assert text.startswith('---\n') and '\nname: codex-cross-provider-session-repair\n' in text
+          PY
+      - name: Run offline tests
+        run: python -m unittest discover -s codex-cross-provider-session-repair/tests -v

README.md

@@ -0,0 +1,128 @@
+<div align="center">
+
+# WardLu Skills
+
+Focused, versioned, open-source skills for agent workflows.
+
+[![Validate skills](https://github.com/WardLu/skills/actions/workflows/validate-skills.yml/badge.svg)](https://github.com/WardLu/skills/actions/workflows/validate-skills.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+[English](README.md) · [简体中文](codex-cross-provider-session-repair/README.zh-CN.md) · [Issues](https://github.com/WardLu/skills/issues)
+
+</div>
+
+> Small, composable skills for repeatable work — with explicit safety boundaries, offline tests, and releaseable versions.
+
+## What this repository is
+
+This repository is a collection of self-contained skills for AI agents and developer workflows. Each skill lives in its own kebab-case directory and includes its instructions, scripts, tests, documentation, license, and version metadata. Individual skills may target one agent or work across several agents; their compatibility is documented in each skill's README and `SKILL.md`.
+
+The first skill in the collection is Codex-specific: it helps recover an old Codex Desktop conversation after a provider switch, import, or fork.
+
+| Skill | Purpose | Version | Documentation |
+| --- | --- | --- | --- |
+| [`codex-cross-provider-session-repair`](codex-cross-provider-session-repair/) | Diagnose and repair provider mismatches and remote compaction `404 Item with id 'rs_...' not found` errors without deleting the Codex home. | `0.2.0` | [English](codex-cross-provider-session-repair/README.md) · [简体中文](codex-cross-provider-session-repair/README.zh-CN.md) |
+
+## Install
+
+### Recommended: `npx skills`
+
+Install a skill globally for a supported agent. The example below installs the current Codex-specific skill:
+
+~~~bash
+npx skills add WardLu/skills --skill codex-cross-provider-session-repair --global --agent codex --yes
+~~~
+
+The command works on Windows, macOS, and Linux with Node.js/npm installed. The `skills` CLI installs the selected `SKILL.md` bundle and keeps the skill manageable through the same tool:
+
+~~~bash
+npx skills list
+npx skills update codex-cross-provider-session-repair
+npx skills remove codex-cross-provider-session-repair
+~~~
+
+To install the full collection, omit `--skill`. For another skill, replace the skill name; for another supported agent, replace `--agent codex` with that agent name. This repository must be merged to `main` before the `WardLu/skills` command can resolve the new skill.
+
+### Manual installation for the current Codex skill
+
+Windows PowerShell:
+
+~~~powershell
+git clone https://github.com/WardLu/skills.git
+Set-Location .\skills\codex-cross-provider-session-repair
+.\scripts\install.ps1 -Destination "$env:USERPROFILE\.codex\skills"
+~~~
+
+macOS/Linux:
+
+~~~bash
+git clone https://github.com/WardLu/skills.git
+cd skills/codex-cross-provider-session-repair
+./scripts/install.sh "$HOME/.codex/skills"
+~~~
+
+Restart the target agent after installing or upgrading so the new skill metadata is loaded.
+
+## Current skill: platform support
+
+The current session-repair skill targets Codex Desktop and supports:
+
+| Platform | Codex home fallback | Installer | Runtime |
+| --- | --- | --- | --- |
+| Windows | `%USERPROFILE%\.codex` | `scripts/install.ps1` | Python 3.9+ standard library |
+| macOS | `~/.codex` | `scripts/install.sh` | Python 3.9+ standard library |
+| Linux | `~/.codex` | `scripts/install.sh` | Python 3.9+ standard library |
+
+Set `CODEX_HOME` when Codex uses a non-default home. The repair scripts do not require third-party Python packages. Future skills may document a different compatibility matrix.
+
+## Safety-first workflow
+
+For the session repair skill:
+
+1. Stop Codex Desktop completely, including its tray process.
+2. Run a dry-run diagnosis with the exact session UUID.
+3. Review the provider and stale-reasoning findings.
+4. Apply only the smallest target-scoped repair; backups are created before writes.
+5. Relaunch Codex and send a short smoke-test prompt before resuming the original task.
+
+The skill preserves visible messages and tool history. It does not delete the whole Codex home, refresh expired credentials, or recover records that the remote service never persisted.
+
+## Repository layout
+
+~~~text
+.
+├── .github/workflows/validate-skills.yml
+├── codex-cross-provider-session-repair/
+│   ├── SKILL.md
+│   ├── README.md
+│   ├── README.zh-CN.md
+│   ├── scripts/
+│   ├── tests/
+│   ├── evals/
+│   ├── VERSION
+│   ├── CHANGELOG.md
+│   ├── SECURITY.md
+│   └── LICENSE
+├── LICENSE
+└── README.md
+~~~
+
+## Development and releases
+
+From a skill directory:
+
+~~~bash
+python -m unittest discover -s tests -v
+python scripts/repair.py --help
+python scripts/package.py --output ./dist
+~~~
+
+Skills follow [Semantic Versioning](https://semver.org/). The canonical version is stored in `VERSION` and mirrored in `SKILL.md`. User-visible changes should update `CHANGELOG.md`; release tags use `vMAJOR.MINOR.PATCH`.
+
+See the contribution rules in [`codex-cross-provider-session-repair/CONTRIBUTING.md`](codex-cross-provider-session-repair/CONTRIBUTING.md).
+
+## Security and license
+
+Do not commit real user data, session logs, backups, tokens, or API keys. For the current Codex-specific skill, read [`SECURITY.md`](codex-cross-provider-session-repair/SECURITY.md) before filing a bug with diagnostic data.
+
+This collection and its skills are released under the [MIT License](LICENSE).

codex-cross-provider-session-repair/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+*.skill
+*.bak-*
+evals/*-workspace/

codex-cross-provider-session-repair/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this skill are documented here.
+
+## [Unreleased]
+
+### Changed
+
+- Clarified that the repository is a general-purpose agent skills collection; the current session-repair skill is specifically for Codex Desktop.
+- Simplified the root README language navigation label.
+
+## [0.2.0] - 2026-08-01
+
+### Added
+
+- Bilingual English and Simplified Chinese README documentation with quick navigation links.
+- `npx skills` installation, listing, update, and removal instructions.
+- Explicit Windows, macOS, and Linux support matrix and platform installer guidance.
+- Executable POSIX helper scripts for macOS/Linux installations.
+
+## [0.1.0] - 2026-08-01
+
+### Added
+
+- Read-only diagnostics across `config.toml`, session JSONL, root `state_5.sqlite`, and `logs_2.sqlite`.
+- Target-only provider repair with SQLite and JSONL backups.
+- One-pass cleanup for repeated non-persisted `response_item` reasoning records.
+- Windows and POSIX installers, offline tests, eval prompts, and MIT licensing.

codex-cross-provider-session-repair/CONTRIBUTING.md

@@ -0,0 +1,10 @@
+# Contributing
+
+1. Create a feature branch from `main`.
+2. Keep the repair target-scoped and backup-first.
+3. Add or update an offline test for every behavior change.
+4. Run `python -m unittest discover -s tests -v` and the skill validator before opening a pull request.
+5. Update `VERSION` and `CHANGELOG.md` for user-visible changes.
+6. Keep `README.md` and `README.zh-CN.md` structurally synchronized, including install and upgrade commands.
+
+Never use real Codex homes, tokens, or unredacted session files in tests or commits. Synthetic JSONL and SQLite fixtures are sufficient.

codex-cross-provider-session-repair/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ward Lu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

codex-cross-provider-session-repair/README.md

@@ -0,0 +1,148 @@
+# Codex Cross-Provider Session Repair
+
+[![Validate skills](https://github.com/WardLu/skills/actions/workflows/validate-skills.yml/badge.svg)](https://github.com/WardLu/skills/actions/workflows/validate-skills.yml) [![Version 0.2.0](https://img.shields.io/badge/version-0.2.0-2563eb.svg)](VERSION) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+`codex-cross-provider-session-repair` is a small, backup-first Codex Skill for recovering an old Codex Desktop conversation after a provider switch, import, or fork.
+
+[简体中文](README.zh-CN.md) · [Install](#install) · [Usage](#usage) · [Development](#development) · [Versioning and upgrades](#versioning-and-upgrades) · [Security](SECURITY.md) · [Changelog](CHANGELOG.md)
+
+It addresses two failure modes that look similar in the UI:
+
+1. the saved session or its root `state_5.sqlite` thread row still points at an unavailable provider; and
+2. remote context compaction returns `404 Item with id 'rs_...' not found` because local reasoning items were sent with `store=false` and were never persisted by the service.
+
+The repair is session-scoped. It never performs a global provider replacement or deletes the Codex home.
+
+## Install
+
+### Recommended: `npx skills`
+
+After this repository is merged to `main`, install only this skill globally for Codex:
+
+```bash
+npx skills add WardLu/skills --skill codex-cross-provider-session-repair --global --agent codex --yes
+```
+
+The same command works on Windows, macOS, and Linux. It requires Node.js/npm (for `npx`). To install the whole collection, omit `--skill`; to target another supported agent, replace `--agent codex` with that agent name.
+
+Useful lifecycle commands:
+
+```bash
+npx skills list
+npx skills update codex-cross-provider-session-repair
+npx skills remove codex-cross-provider-session-repair
+```
+
+To install directly from the skill directory instead of selecting it from the collection:
+
+```bash
+npx skills add https://github.com/WardLu/skills/tree/main/codex-cross-provider-session-repair --global --agent codex --yes
+```
+
+The `skills` CLI installs the `SKILL.md` bundle for the selected agent; the bundled Python repair script remains available inside the installed skill directory.
+
+### Manual installation
+
+Clone the skills collection and run the installer from this directory:
+
+```powershell
+git clone https://github.com/WardLu/skills.git
+Set-Location .\skills\codex-cross-provider-session-repair
+.\scripts\install.ps1
+```
+
+The default destination is `%USERPROFILE%\.agents\skills`. For a Codex installation that reads `%USERPROFILE%\.codex\skills`, pass it explicitly:
+
+```powershell
+.\scripts\install.ps1 -Destination "$env:USERPROFILE\.codex\skills"
+```
+
+On macOS/Linux:
+
+```bash
+git clone https://github.com/WardLu/skills.git
+cd skills/codex-cross-provider-session-repair
+./scripts/install.sh
+```
+
+The platform matrix is:
+
+| Platform | Codex home discovery | Installer |
+| --- | --- | --- |
+| Windows | `CODEX_HOME`, then `%USERPROFILE%\\.codex` | `scripts/install.ps1` |
+| macOS | `CODEX_HOME`, then `~/.codex` | `scripts/install.sh` |
+| Linux | `CODEX_HOME`, then `~/.codex` | `scripts/install.sh` |
+
+The repair logic uses Python 3.9+ standard-library modules only (`json`, `sqlite3`, `pathlib`, and `shutil`), so no platform-specific Python packages are required.
+
+Restart the client after installing or upgrading a skill so its metadata is reloaded.
+
+## Usage
+
+Give Codex the affected session UUID and the visible error. The skill should diagnose first and ask you to quit Codex Desktop before applying a repair.
+
+For a direct, read-only diagnostic:
+
+```powershell
+python .\scripts\repair.py `
+  --session-id 019fb8f5-5fcc-74c0-8341-61f83f2126ce `
+  --codex-home "$env:USERPROFILE\.codex"
+```
+
+For a repeated remote-compaction 404 where the report maps stale IDs to local reasoning records:
+
+```powershell
+python .\scripts\repair.py `
+  --session-id 019fb8f5-5fcc-74c0-8341-61f83f2126ce `
+  --codex-home "$env:USERPROFILE\.codex" `
+  --remove-reasoning all --apply
+```
+
+For a provider mismatch, pass the known current provider and opt into the target-only database/session update:
+
+```powershell
+python .\scripts\repair.py `
+  --session-id <UUID> `
+  --codex-home "$env:USERPROFILE\.codex" `
+  --provider custom --fix-provider --apply
+```
+
+The command is dry-run unless `--apply` is present. Every apply run creates a timestamped JSONL backup. A database backup is created only when the target `threads.model_provider` row changes; WAL/SHM sidecars are copied alongside it.
+
+After applying, fully quit Codex Desktop—including the tray process—and relaunch it. A page refresh does not unload the cached rollout. Test with a short confirmation prompt before resuming the original project task.
+
+To build a portable `.skill` archive without extra dependencies:
+
+```bash
+python scripts/package.py --output ./dist
+```
+
+## Development
+
+The repair tool has no third-party runtime dependencies:
+
+```bash
+python -m unittest discover -s tests -v
+python scripts/repair.py --help
+```
+
+The `evals/evals.json` file contains realistic trigger and behavior prompts. The `evals` directory is intentionally excluded from distributable `.skill` packages by the standard skill packager.
+
+## Versioning and upgrades
+
+This skill follows Semantic Versioning. The canonical version is in `VERSION` and mirrored in `SKILL.md` metadata.
+
+```bash
+git pull --ff-only origin main
+git fetch --tags
+```
+
+Install the checked-out version again after pulling. Releases should be tagged `vMAJOR.MINOR.PATCH`, with a `CHANGELOG.md` entry and a GitHub release. Backward-incompatible changes include changing the default repair scope or the meaning of `--remove-reasoning all`.
+
+## Scope and limitations
+
+This skill repairs local Codex session state. It cannot recover an item that the remote service never persisted, refresh an expired login token, fix a provider outage, or repair a corrupt SQLite database with no usable backup. It deliberately preserves visible history rather than trying to regenerate missing model traces.
+
+## License
+
+MIT. See [LICENSE](LICENSE).