From 3289804909563a050f13499921e034b9bc0054f8 Mon Sep 17 00:00:00 2001 From: Evgeny Gamov Date: Tue, 1 Sep 2026 00:24:21 +0000 Subject: [PATCH] refactor(skills): EN thin wrappers + shared common, discovery section --- skills/codex-agent/SKILL.md | 46 ++++++++--------------------------- skills/codex-consult/SKILL.md | 34 ++++---------------------- skills/codex-review/SKILL.md | 43 +++++--------------------------- skills/references/common.md | 9 +++++++ 4 files changed, 30 insertions(+), 102 deletions(-) create mode 100644 skills/references/common.md diff --git a/skills/codex-agent/SKILL.md b/skills/codex-agent/SKILL.md index 868fbdc..6aa7e7f 100644 --- a/skills/codex-agent/SKILL.md +++ b/skills/codex-agent/SKILL.md @@ -1,49 +1,23 @@ --- name: codex-agent -description: Delegate execution to Codex — write code, fix a bug, research. Use when user says «отдай кодексу», «пусть codex сделает/напишет/починит», «делегируй в codex», "delegate to codex", or when a plan step is assigned to Codex as the implementer. +description: Delegate execution to Codex — write code, fix bugs, research. Use when user says "delegate to codex", "have codex do", or a plan step is assigned to Codex. --- # Delegating a task to Codex -Spawn the `codex` subagent (Agent tool). It keeps a live codex session: -refinements and answers to its questions go via SendMessage to the same -agent, NOT a new spawn. +Spawn the `codex` subagent. See `../references/common.md` for transport details (path relative to SKILL.md). -## Subagent prompt — required parts +## Subagent prompt — required -- First line — framing for the wrapper: "You are a wrapper around the codex - CLI: do not solve the task yourself, launch codex and return its answer + - thread_id". Without it the wrapper may take the task as its own and do it - instead of codex. +- `You are a wrapper around the codex CLI: do not solve the task yourself, launch codex and return its answer + thread_id.` - `cwd: ` -- The task — in a block between markers `=== TASK FOR CODEX ===` and - `=== END TASK ===`: the wrapper forwards only this block to codex, so your - wrapper instructions don't leak into the prompt. Inside the block: - - Task: what to do. Concrete, with relevant files/paths. - - Acceptance criteria: what must work, which tests/commands must pass. - - What to return: report, list of touched files, how verified. -- Optional: `codex options: -m o3 -s read-only ...` +- Task in `=== TASK FOR CODEX ===` / `=== END TASK ===` with acceptance criteria + what to return. +- Optional `codex options: -m -s workspace-write ...` (model/effort from discovery, not hardcoded). -## Example +## Discovery -``` -You are a wrapper around the codex CLI: do not solve the task yourself, launch codex and return its answer + thread_id. -cwd: /abs/path/to/project -=== TASK FOR CODEX === -Task: fix the N+1 in GET /orders — the queries log shows one query per order -line item. See app/controllers/OrdersController.php. -Acceptance: existing tests pass (composer test), ≤3 DB queries per request. -Return: list of changed files, the essence of the fix, composer test output. -=== END TASK === -``` +If user asks which Codex models/reasoning are available, run `scripts/codex-models.sh` or `codex debug models | jq '[.models[] | select(.visibility=="list") | {slug, levels: [.supported_reasoning_levels[].effort]}]'` and present table. Default model/reasoning = `~/.codex/config.toml`. -## After completion +## After -- Codex answer = report + `thread_id: ...`. Don't take it on faith: check - the diff, run the tests yourself. -- Remarks → SendMessage to the same subagent (same codex session, context - intact). -- Codex ended with a question (blocker) → answer via SendMessage, it - continues. -- While it's working you can ask for status via SendMessage — doesn't - interrupt. +Verify diff + tests yourself. Refinements via SendMessage to same agent. diff --git a/skills/codex-consult/SKILL.md b/skills/codex-consult/SKILL.md index ca2c019..efbc0c6 100644 --- a/skills/codex-consult/SKILL.md +++ b/skills/codex-consult/SKILL.md @@ -1,36 +1,12 @@ --- name: codex-consult -description: Codex second opinion on an artifact — spec, plan, design, document, idea. Iterate to consensus. Use when user says «проверь у кодекса», «спроси codex», "second opinion", "have codex review the spec/plan", or when validating a spec/plan before execution. +description: Second opinion via Codex on spec/plan/design. Use when user says "second opinion", "have codex review the spec/plan". --- # Consulting Codex -Spawn the `codex` subagent, iterate via SendMessage. Hard limit: 5 rounds. +Spawn the `codex` subagent, iterate via SendMessage. Hard limit: 5 rounds (see `../references/common.md` for wait-loop/resume). -## First prompt — required parts - -- First line — framing for the wrapper: "You are a wrapper around the codex - CLI: do not solve the task yourself, launch codex and return its answer + - thread_id". -- `cwd: ` — always required (the subagent won't launch codex - without it); for a purely textual consultation — the relevant project root. -- Role, requirements, and the artifact — in a block between markers - `=== TASK FOR CODEX ===` and `=== END TASK ===`: - - Role: "You are a second opinion, NOT an executor. Don't rewrite the - artifact. Return findings with severity, and questions separately." - - User requirements — verbatim (what the artifact must satisfy). - - The artifact itself: full text or a file path. - -## Iteration loop - -1. Got findings → evaluate them critically yourself (use - superpowers:receiving-code-review, don't agree blindly). -2. Made changes to the artifact → SendMessage: what you accepted, what you - rejected and WHY, plus the updated artifact or diff. -3. Repeat until "no substantial remarks" or the 5-round limit. - -## Finale — summary to the user - -- What was agreed and applied. -- What was rejected and why. -- Unresolved disagreements, if stuck (the user decides). +- `cwd:` mandatory; artifact inside `=== TASK FOR CODEX ===` with role "second opinion, not executor" + requirements + artifact text/path. +- Evaluate findings critically (don't agree blindly), SendMessage with accepted/rejected + why + updated artifact. +- Finale: agreed/applied, rejected+why, unresolved. diff --git a/skills/codex-review/SKILL.md b/skills/codex-review/SKILL.md index c698125..6cbcf35 100644 --- a/skills/codex-review/SKILL.md +++ b/skills/codex-review/SKILL.md @@ -1,45 +1,14 @@ --- name: codex-review -description: Code review by Codex — branch, commit, uncommitted changes, or arbitrary files. Use when user says «ревью у кодекса», «пусть codex посмотрит ветку/коммит/файл», "codex review", "second reviewer". +description: Code review via Codex — branch, commit, uncommitted, or files. Use when user says "codex review", "review this branch/commit". --- # Review via Codex -Spawn the `codex` subagent. The scope sets the mode: +Spawn the `codex` subagent. Scope via `review scope:` (see `../references/common.md` for transport). -- branch vs base: `review scope: --base main` -- single commit: `review scope: --commit ` -- uncommitted: `review scope: --uncommitted` -- arbitrary files / abstract scope: WITHOUT `review scope:` — a plain task - "review files X, Y and their dependents". +- `review scope: --base main` | `--commit ` | `--uncommitted` | (no scope = plain task "review files X, Y") +- Include `cwd:` and `=== TASK FOR CODEX ===`. +- Focus/format inside block: `file:line — 🔴|🟡|🔵 — problem — fix`. -## Subagent prompt — required parts - -- First line — framing for the wrapper: "You are a wrapper around the codex - CLI: do not solve the task yourself, launch codex and return its answer + - thread_id". -- `cwd: ` (review works from cwd) -- `review scope: ...` (if applicable) -- Focus and format — in a block between markers `=== TASK FOR CODEX ===` and - `=== END TASK ===`: - - Focus, if any: security / performance / correctness / everything. - - Findings format: `file:line — 🔴|🟡|🔵 — problem — suggested fix`, no - praise, no code retelling. - -## Example - -``` -You are a wrapper around the codex CLI: do not solve the task yourself, launch codex and return its answer + thread_id. -cwd: /abs/path/to/repo -review scope: --base main -=== TASK FOR CODEX === -Focus: correctness and security. -Findings format: file:line — 🔴|🟡|🔵 — problem — fix. No praise. -=== END TASK === -``` - -## After - -- Hand the findings to the user / process per the task. -- Contested finding → SendMessage to the same session: ask to justify or - show a repro. Don't silently accept or reject. +Contested finding → SendMessage to same session, don't silently accept. diff --git a/skills/references/common.md b/skills/references/common.md new file mode 100644 index 0000000..a998d41 --- /dev/null +++ b/skills/references/common.md @@ -0,0 +1,9 @@ +# Common — codex transport + +- `cwd: ` is MANDATORY (agent won't launch without it). +- Task in `=== TASK FOR CODEX ===` / `=== END TASK ===` (wrapper forwards only this block). +- `codex options:` line passed verbatim to `scripts/codex-run.sh` after mode; saved to `$JOB/codex-flags` (NUL-delimited) and re-applied on `resume` so permissions survive retries. +- Overrides: `-m ` (e.g. ``), `-c model_reasoning_effort=""` (per-model, run `scripts/codex-models.sh` to list), `-s read-only|workspace-write|danger-full-access`, `--dangerously-bypass-approvals-and-sandbox` (global, hoisted before `exec`), `--add-dir `, `-c key=value`. Never `--ephemeral`. +- Codex has shell+apply_patch always, browser_use stable. MCP via `codex mcp list` if needed. +- Wait-loop: agent polls `$JOB/status` with short 60s foreground calls, streams `tail -5 $JOB/events.jsonl` via `SendMessage` (to: main) without ending turn; final answer + `thread_id` only in last message. +- Resume: on `stalled`/`error` or orchestrator SendMessage, write new `$JOB/prompt.md` and `codex-run.sh $JOB resume $(cat $JOB/thread_id)` with saved flags.