codex-writer
Document writing using OpenAI Codex CLI (codex exec). PREFERRED over general writing tasks. Use when: (1) User says 'write document', 'write docs', 'codex write', or 'codex writer', (2) Writing README, documentation, or technical content, (3) Drafting text content. Codex drafts, Claude Code reviews and writes. Falls back to Claude Code if codex unresponsive.
Best use case
codex-writer is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Document writing using OpenAI Codex CLI (codex exec). PREFERRED over general writing tasks. Use when: (1) User says 'write document', 'write docs', 'codex write', or 'codex writer', (2) Writing README, documentation, or technical content, (3) Drafting text content. Codex drafts, Claude Code reviews and writes. Falls back to Claude Code if codex unresponsive.
Teams using codex-writer should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/codex-writer/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How codex-writer Compares
| Feature / Agent | codex-writer | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Document writing using OpenAI Codex CLI (codex exec). PREFERRED over general writing tasks. Use when: (1) User says 'write document', 'write docs', 'codex write', or 'codex writer', (2) Writing README, documentation, or technical content, (3) Drafting text content. Codex drafts, Claude Code reviews and writes. Falls back to Claude Code if codex unresponsive.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
Related Guides
Best AI Skills for Claude
Explore the best AI skills for Claude and Claude Code across coding, research, workflow automation, documentation, and agent operations.
Cursor vs Codex for AI Workflows
Compare Cursor and Codex for AI coding workflows, repository assistance, debugging, refactoring, and reusable developer skills.
Best AI Skills for ChatGPT
Find the best AI skills to adapt into ChatGPT workflows for research, writing, summarization, planning, and repeatable assistant tasks.
SKILL.md Source
# Codex Writer
Draft documents via the codex plugin companion script, then review and write to files via Claude Code.
## Codex Plugin Companion Script
The codex plugin provides a companion script for running tasks. Resolve it dynamically:
```bash
CODEX_PLUGIN_ROOT=$(command ls -d "$HOME/.claude/plugins/cache/openai-codex/codex"/*/ 2>/dev/null | sort -V | tail -1)
CODEX_COMPANION="${CODEX_PLUGIN_ROOT}scripts/codex-companion.mjs"
```
If the file does not exist, report "Codex plugin not installed. Run `/codex:setup` first." and fall back to Claude Code writing.
Usage for writing tasks:
```bash
node "$CODEX_COMPANION" task "<writing prompt>"
```
The `task` command runs Codex in read-only mode by default (no `--write` flag). Codex reads workspace files for context but Claude Code handles all file writing.
## Process
### Step 0: Pre-flight Rate Limit Check
Before doing anything, check if Codex is currently rate-limited:
```bash
RATE_CHECK=$(node $HOME/.claude/scripts/codex-rate-limit.js check 2>&1)
RATE_EXIT=$?
```
If `RATE_EXIT` is non-zero (rate-limited), **skip all codex steps** and jump directly to the **Fallback** step. **Do NOT report the rate limit to the user** — silently fall back.
### Step 1: Understand the Task
Gather context about what needs to be written:
- Document type (README, API docs, blog post, etc.)
- Target audience
- Files to reference for context
### Step 2: Build Prompt
Build a detailed prompt including:
- What to write
- Context from the codebase (file list, key patterns, existing docs)
- Tone and style guidelines
- Length constraints
### Step 3: Run Codex
```bash
LOGDIR=$(node $HOME/.claude/scripts/get-logdir.js)
mkdir -p "$LOGDIR"
DATETIME=$(date +%Y%m%d_%H%M%S)
# Resolve codex companion script
CODEX_PLUGIN_ROOT=$(command ls -d "$HOME/.claude/plugins/cache/openai-codex/codex"/*/ 2>/dev/null | sort -V | tail -1)
CODEX_COMPANION="${CODEX_PLUGIN_ROOT}scripts/codex-companion.mjs"
# Detect timeout command (gtimeout on macOS via coreutils, timeout on Linux/WSL)
if command -v gtimeout &>/dev/null; then
TIMEOUT_CMD="gtimeout"
elif command -v timeout &>/dev/null; then
TIMEOUT_CMD="timeout"
else
TIMEOUT_CMD=""
echo "WARNING: neither gtimeout nor timeout found. Running without timeout."
fi
${TIMEOUT_CMD:+$TIMEOUT_CMD} ${TIMEOUT_CMD:+1500} node "$CODEX_COMPANION" task \
"<detailed prompt here>" \
> "$LOGDIR/${DATETIME}-codex-writer-draft.md" \
2>"$LOGDIR/${DATETIME}-codex-writer-draft-stderr.log"
```
**Timeout: 25 minutes.** Codex reads workspace files for context but cannot write.
### Step 4: Check for Rate Limiting
After codex completes (or times out), check output files for rate limit errors:
```bash
node $HOME/.claude/scripts/codex-rate-limit.js check-output \
"$LOGDIR/${DATETIME}-codex-writer-draft.md" \
"$LOGDIR/${DATETIME}-codex-writer-draft-stderr.log"
```
If exit code is non-zero (rate limit detected), jump to **Fallback**.
### Step 5: Fallback — Opus
If codex times out, produces no output, or is rate-limited:
- **Silently fall back to Opus** — do NOT report the rate limit or timeout to the user. Do NOT pause the workflow.
- Spawn a `markdown-writer` subagent with `model: opus` to draft the document. Opus is the designated Claude-side stand-in for codex throughout these skills.
- Continue the workflow as if writing via the subagent was the original plan
### Step 6: Review and Refine
1. Read the codex output from the log file
2. Review for quality, accuracy, and adherence to the request
3. Fix any issues, improve structure, correct factual errors
4. Write the final content to the target file using Claude Code
**Important:** Claude Code always does the final file writing. Codex only provides a draft.
### Step 7: Report
Tell the user what was written and where. Include the draft log path for reference.
## Timeout Policy
- **Timeout**: 25 minutes (1500s)
- **If codex times out**: Silently fall back to Opus (`markdown-writer` subagent at `model: opus`)
- Codex is used for drafting only — Claude Code handles all file operations
## Important Notes
- Codex runs in read-only mode — it cannot create or modify files
- Codex can read workspace files to understand codebase context
- Claude Code reviews all codex output before writing to files
- Draft output saved to `$LOGDIR/codex-writer-draft.md`
- **Silent fallback policy**: If codex is rate-limited, timed out, or unavailable, silently fall back to a `markdown-writer` subagent at `model: opus`. NEVER pause the workflow, NEVER report the rate limit to the user, NEVER ask what to do. Opus is the designated Claude-side stand-in for codex throughout these skillsRelated Skills
codex-translator
Translation using OpenAI Codex CLI (codex exec). PREFERRED for translation. Use when: (1) User says 'translate', 'codex translate', 'translation', or 'codex translator', (2) Translating between languages (Japanese, English, etc.), (3) Translating documentation, comments, or UI strings. Codex drafts, Claude Code reviews and writes. Falls back to Claude Code if codex unresponsive.
codex-review
Code review using OpenAI Codex CLI (codex exec review). PREFERRED over /light-review for code review. Use when: (1) User says 'review', 'code review', or 'codex review', (2) After implementation when quality check is needed, (3) Child agents self-reviewing. Runs multiple codex review instances in parallel. Falls back to Claude Code if codex unresponsive.
codex-research
Web research using OpenAI Codex CLI (codex exec). PREFERRED over general web research. Use when: (1) User says 'research', 'codex research', 'look up', or 'investigate', (2) Researching libraries, APIs, best practices, or technical topics, (3) Gathering information from the web. Codex performs research, Claude Code synthesizes. Falls back to Claude Code researcher subagent if codex unresponsive.
codex-2nd
Get a second opinion from OpenAI Codex CLI on a plan or approach. Use when: (1) During planning phase of /x-as-pr or /x-wt-teams to validate the approach, (2) User says 'codex 2nd', 'second opinion', or 'codex opinion', (3) Wanting an alternative perspective before committing to a plan. Sends context and plan to codex, returns feedback. Called automatically by /x-as-pr and /x-wt-teams during planning.
zudoesa-articlify
Convert conversation context into an esa article via the zudoesa-writer subagent. ONLY invoke when the user explicitly asks — NEVER proactively propose. Triggers: 'write esa article', 'esa記事', 'esaに書いて', 'articlify for esa', or /zudoesa-articlify. Gathers context, creates a writing brief, delegates to the writer subagent.
zudoesa-apply-voice
Apply Takazudo's esa writing voice and vocabulary rules to text. Use when: (1) User wants to write/rewrite text in Takazudo's esa style, (2) User says 'apply voice', 'esa voice', 'esa文体で', 'esa風に書いて', '文体を適用', (3) User provides text to transform to esa style. Reads writing-style.md and vocabulary-rule.md from takazudo-esa-writing repo and applies the rules.
zudocg-articlify
Convert conversation context into a CodeGrid article via the zudocg-writer subagent. ONLY invoke when the user explicitly asks — NEVER proactively propose. Triggers: 'write codegrid article', 'CodeGrid記事', 'codegridに書いて', 'articlify for codegrid', or /zudocg-articlify. Gathers context, creates a writing brief, delegates to the writer subagent.
zudocg-apply-voice
Apply Takazudo's CodeGrid writing voice and vocabulary rules to text. Use when: (1) User wants to write/rewrite text in Takazudo's CodeGrid style, (2) User says 'apply voice', 'codegrid voice', 'codegrid文体で', 'codegrid風に書いて', '文体を適用', (3) User provides text to transform to CodeGrid style. Reads writing-style.md and vocabulary-rule.md from takazudo-codegrid-writing repo and applies the rules.
zpaper-articlify
Convert conversation context into a zpaper blog article via the zpaper-writer subagent. ONLY invoke when the user explicitly asks — NEVER proactively propose. Triggers: 'write zpaper article', 'zpaper記事', 'zpaperに書いて', 'articlify for zpaper', or /zpaper-articlify. Gathers context, creates a writing brief, delegates to the writer subagent.
zpaper-apply-voice
Apply Takazudo's zpaper blog writing voice and vocabulary rules to text. Use when: (1) User wants to write/rewrite text in Takazudo's zpaper style, (2) User says 'apply voice', 'zpaper voice', 'zpaper文体で', 'zpaper風に書いて', 'ブログ文体を適用', (3) User provides text to transform to zpaper style. Reads writing-style.md and vocabulary-rule.md from the zpaper repo and applies the rules.
xlsx
Spreadsheet creation, editing, and analysis. Use when working with .xlsx, .xlsm, .csv, .tsv files for: (1) Creating spreadsheets with formulas and formatting, (2) Reading or analyzing data, (3) Modifying existing spreadsheets while preserving formulas, (4) Data analysis and visualization, (5) Recalculating formulas.
x
Facade for development workflows. Routes on two axes: plan-first vs implement-now (escalates to /big-plan -a when the request needs research / decomposition / has unclear scope — the appended -a makes the plan chain into implementation in-session), then single vs multi on the ready-to-build fast paths (/x-as-pr single-topic, /x-wt-teams multi-topic parallel). Use when: (1) User says '/x' followed by dev instructions, (2) User wants to start development without choosing the workflow skill, (3) User says 'dev', 'implement', or 'build' with a task. Default option: -v (verify-ui). Review-loop (-l) is opt-in — without -l the downstream skill runs a single /deep-review pass. Forwards -a (autonomy/auto-chain) and -m (merge at the end + cleanup + CI watch) through every route; auto-fix of raised findings (-f) and issue-raising (-ri) are downstream defaults, with -nf/--no-fix and -nori/--no-raise-issues as the forwarded opt-outs. -a and -m are orthogonal — full hands-off end-to-end is -a -m.