Write Clear Copy v2 is a Codex skill for drafting, reviewing, and implementing reader-facing copy while preserving verified behavior, functional syntax, and project conventions. It treats copy as part of the product contract: wording should help a reader understand, decide, trust, or act without changing what the product does.
The skill routes work across eight focused references:
- Product UI, including controls, forms, errors, notifications, onboarding, and destructive actions
- CLI help, prompts, stdout, stderr, progress, errors, and machine-consumed output
- Authentication, consent, privacy, billing, accessibility, and localization
- Help content, developer documentation, procedures, API reference, and READMEs
- Repository descriptions, issues, pull requests, commits, changelogs, releases, and versioning
- Websites, product pages, pricing, positioning, and search-facing metadata
- Lifecycle email, support, announcements, incidents, and service notices
- Editorial structure, plain language, voice, and formulaic or AI-sounding prose
Use the skill when wording, information order, terminology, claims, voice, or a public text contract is a material outcome. It supports drafting, rewriting, review, broad audits, implementation in an authoritative source, and final editorial ownership.
Do not use it for code, layout, localization plumbing, analytics, or other mechanics when reader-facing wording is explicitly unchanged. Pair it with the skill that owns artifact construction, rendering, deployment, or application behavior when a task includes both copy and production work.
The shortest path is to ask Codex's skill installer to install the runtime directory from GitHub:
$skill-installer install https://github.com/LgcY-v2/write-clear-copy-v2/tree/main/skills/write-clear-copy-v2
To inspect the source and export the same runtime package yourself:
git clone https://github.com/LgcY-v2/write-clear-copy-v2.git
cd write-clear-copy-v2
python scripts/evaluate_cases.py export-runtime ../write-clear-copy-v2-runtimeThe export destination must be new and outside the source repository. Place the exported directory in a Codex skill location such as a repository's .agents/skills/write-clear-copy-v2 or the user-level $HOME/.agents/skills/write-clear-copy-v2. See OpenAI's skill documentation for supported scopes and discovery behavior.
Name the skill when you want to require it:
Use $write-clear-copy-v2 to audit the reader-facing copy in this repository and fix material issues.
Codex can also invoke it implicitly when a task matches the scope in its description.
Rewrite an error from verified behavior:
Use $write-clear-copy-v2 to rewrite this save error. The product knows only that saving failed, and retrying is safe. Preserve the existing message key.
Protect human and machine CLI contracts:
Use $write-clear-copy-v2 to improve the human status and authentication error. Keep STATUS=NOT_READY byte-for-byte, preserve stdout and stderr routing, and update the synchronized tests.
Finalize repository communication:
Use $write-clear-copy-v2 to align the README, changelog, migration note, and release copy with the implemented behavior. Report only checks that actually ran.
Only skills/write-clear-copy-v2/ is installed:
skills/write-clear-copy-v2/
├── SKILL.md
├── agents/openai.yaml
├── references/
│ └── eight routed copy guides
└── scripts/check_copy_contracts.py
SKILL.md owns routing, priorities, semantic constraints, and the working method. The references hold surface-specific guidance. check_copy_contracts.py is a conservative review aid for protected tokens such as placeholders, commands, paths, URLs, versions, and machine output.
The repository-root evals/ directory and the remaining scripts/ files are development-only. Runtime export excludes fixtures, rubrics, oracles, graders, and retained evidence.
Python 3.11 or later is recommended for development. From the repository root:
python -m pip install -r requirements-dev.txt
python scripts/run_official_skill_validator.py
python -m compileall -q scripts skills/write-clear-copy-v2/scripts evals/oracles
python scripts/test_skill_assets.py -v
python scripts/evaluate_cases.py export-runtime ../write-clear-copy-v2-runtimeThe validator wrapper downloads a hash-pinned copy of OpenAI's official quick_validate.py from the openai/codex repository. The deterministic suite covers the protected-token checker, manifest integrity, runtime isolation, workspace safety, external implementation oracles, declarative test ownership, trace-derived routing and pairing, signed evidence, and release-gate behavior.
The evaluation harness separates behavior, routing, implementation, and companion-skill pairing. The protocol describes blinded packets, runner-owned verification, raw event logs, signed artifacts, baselines, and the release gate.
Passing the official validator establishes basic skill structure and frontmatter validity. Passing compilation and the deterministic suite establishes that the checked source and harness mechanics behave as asserted. A matching runtime hash establishes the exact exported file set and bytes.
Those results do not demonstrate general writing quality, model performance, routing accuracy in an untested host, or the truth of a product claim supplied without evidence. Machinery tests are not a behavioral baseline. Model-level release claims require fresh, isolated blind runs with retained raw artifacts and complete gate results.
v0.1.0-rc.1 is the first public prerelease candidate. No retained blind model baseline is bundled, so this release makes no model-quality or routing-performance claim. The protected-token checker is intentionally conservative and cannot prove semantic equivalence. The skill cannot replace product evidence, legal approval, professional translation, accessibility testing, or rendered review where those are required.
The signed blind-evidence gate remains mandatory for a stable release or any model-performance claim. A 0.x candidate may ship without that evidence only when it passes the documented local gates, is marked as a prerelease, and retains these limitations.
The project is available under the MIT License.