Community研究与数据分析github.com

Suree33/agent-skills

https://agentskills.io 準拠

agent-skills 是什么?

agent-skills is a Codex agent skill that https://agentskills.io 準拠.

兼容平台~Claude Code✓Codex CLI~Cursor
npx skills add Suree33/agent-skills

Installed? Explore more 研究与数据分析 skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

ask-codex

Invokes OpenAI's coding agent Codex via codex exec (non-interactive mode) for design consultation, deep investigation, and code review.

Codex tends to be persistent in researching and raising accuracy, making it well-suited for second opinions and deep dives where precision is critical.

Codex starts cold every time and knows nothing about the current conversation, plan, or past findings. State your assumptions, intentions, constraints, and relevant files explicitly in the prompt each time (see "Task Statement Format" and examples below).

Prerequisites

  • The codex CLI must be installed and authenticated (codex --version to verify).
  • If authentication has expired, the user needs to set up Codex. Inform the user accordingly.

Before Execution

Before invoking Codex, briefly tell the user what you are consulting about. No need to wait for approval; after informing, proceed with execution.

Basic Invocation Pattern

Codex acts as a read-only senior reviewer, so use -s read-only as the default. Pass the prompt via stdin (codex exec -) to avoid shell escaping issues.

The core practices are two:

  1. Complete answer extraction (cat) within the same command that invokes Codex. $OUT from OUT=$(mktemp …) disappears in a subsequent shell invocation, so reading it later would lose the path. Using cat within the same command reliably retrieves the answer without any assumptions.
  2. Do not leak Codex's stdout/stderr to the context. Codex outputs progress logs, headers, warnings, hooks, trailing echoes, and tokens used to stderr, and the final message only to stdout and the -o file (everything about "what was done/thought" goes to stderr). Since you only want the conclusion, discard stdout and redirect stderr to a temporary file, displaying it only on failure. This way, the tool result contains only the final message from cat "$OUT", while error causes (e.g., authentication failure, invalid flags) are visible on failure.

Two canonical recipes are provided depending on the use case.

A. Short Consultation / Small Review (Foreground)

The answer (only the final message) is returned in the shell execution's tool result. No additional Read needed.

OUT=$(mktemp /tmp/codex_answer.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
printf '%s' "$PROMPT" | codex exec - -s read-only -C <DIR> -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
cat "$OUT"

B. Long-Running Invocation (Background)

codex exec can take several minutes; foreground execution may be terminated by the environment. For longer tasks such as deep investigations or code reviews via codex exec review, submit the task using your harness's background execution mechanism (the method is left to the harness side). Use either codex exec - (consultation/investigation) or codex exec review (diff review, described later) as the command body.

OUT=$(mktemp /tmp/codex_answer.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
printf '%s' "$PROMPT" | codex exec - -s read-only -C <DIR> -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
echo "=== ANSWER ==="; cat "$OUT"

Upon completion, the harness sends a completion notification containing the answer after === ANSWER === in its background output. Read that output (for long content, grep for === ANSWER === and subsequent content). Do not write your own polling loop with sleep/pgrep (the harness handles completion notification).

Flag Meanings

  • codex exec -: Read the prompt from stdin. Safely passes long text, code blocks, and special characters.
  • -s read-only: Permits read-only access only. Apply this by default in this skill (since it acts as an advisor/reviewer, no writes needed). Not the default of the CLI/config itself. For codex exec only; codex exec review does not support this flag (appending it causes an error).
  • -C <DIR>: The working root for codex exec. Points to the repository under investigation/review. Omitted if using the current directory. codex exec review does not have -C, so for reviews, cd <DIR> within the same command before calling (described later).
  • -o <FILE>: Write only the final message from Codex to this file. It is written only upon completion (empty during execution); do not read before completion. The canonical recipes use this as the answer source.
  • stdout: Codex also outputs the final message to stdout, but the canonical recipes take it from -o, so discard stdout with >/dev/null (to avoid duplication and save context).
  • stderr: Contains progress logs, headers, warnings, hooks, trailing echoes, tokens used, and errors (authentication expiration, invalid flags, repo check failures, etc.). Simply discarding with 2>/dev/null would make the cause invisible when cat "$OUT" is empty, so redirect to a temporary file ($ERR) and only cat "$ERR" on failure. On success, stderr stays out of the context; on failure, the cause is visible.
  • mktemp /tmp/codex_answer.XXXXXX.txt: The trailing XXXXXX is replaced with random characters, generating a unique path that doesn't collide. Even with multiple parallel invocations, each call uses a separate mktemp.

Usually Unnecessary Options

  • --skip-git-repo-check: Only needed when running outside a git repository. Do not add if inside a repo.
  • -s workspace-write: Only when you want Codex to edit. This skill's purpose (read-only reviewer) does not require it; in principle, do not use.

Model Specification

To use a specific model, add -m <MODEL> (e.g., -m gpt-5.5). If unspecified, follows Codex's configuration default. Do not specify unnecessarily; only when the user requests.

Web Search

If ~/.codex/config.toml has web_search = "live", Codex can use web search. Web search is a native Responses tool and is not blocked by -s read-only (which only restricts shell execution). To verify specific specifications of libraries, APIs, or CLIs, explicitly say "check official documentation via web search" in the prompt. There is no --search flag for codex exec; it is controlled by the web_search config.

Help

Display help with codex exec -h.

Task Statement Format

LLMs are good at following examples, so use the prompt bodies in the examples below as templates for good task statements. Focus each consultation on a single decision/review/plan/investigation and include the following in one prompt:

  • Intent, context, constraints: Since Codex starts cold, always write what you want, why, and the assumptions.
  • Relevant files: Show in-line with @path/to/file. If you want it to look at current changes, explicitly say "check the diff with git diff".
  • Focus points / alternative options to compare / risks to explore – be specific.
  • Specify the output format (ranked risks, tradeoff table, recommended plan changes, etc.).
  • State what to ignore (naming, formatting, etc.) to prevent scope creep.
  • If external specification verification is needed, explicitly say "check official documentation via web search".
  • For reviews, ask for intent → implementation: first check if the intent is sound, then examine the implementation.

Wrap the prompt body in single quotes like printf '%s' '...' to prevent shell interpretation of $ and backticks (use a different wrapping only if the body contains ASCII ').

Use Case Examples

1. Second Opinion / Multiple Option Comparison (Recipe A)

Seek a second opinion on a design/implementation decision. The more specifically you describe the options to compare, constraints, and output format, the better the quality.

OUT=$(mktemp /tmp/codex_answer.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
printf '%s' 'Intent: Decide on an auth token refresh mechanism. Currently, we check expiry on every API call and refresh synchronously (@src/auth/client.ts), causing double refresh under high concurrent requests.

Options to compare:
(1) Share a Promise during refresh to deduplicate
(2) Proactively update in the background before expiry
(3) Refresh once after receiving a 401 and retry

Constraints: Must work in both SSR and CSR. Prefer not to add new libraries.
Output: A tradeoff table with columns correctness / complexity / failure modes, recommend a default and fallback plan, and under what conditions to switch to another option. Ignore naming and formatting.' \
  | codex exec - -s read-only -C /path/to/repo -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
cat "$OUT"

2. Code Review

Key constraint: The scope flags (--uncommitted / --base / --commit) of codex exec review are incompatible with a custom instruction PROMPT (whether via stdin with - or positional argument). Confirmed in codex 0.142.4: using both results in error: the argument '--uncommitted' cannot be used with '[PROMPT]' and immediate failure. Therefore, split into two use cases.

2a. Review with Custom Focus (Recommended, primary use): Since scope flags and focus instructions cannot be combined, use codex exec - (Recipe A/B) instead of codex exec review, and specify the scope by having Codex check git diff etc. inside the prompt. -s read-only / -C / stdin work as usual, avoiding escaping issues.

OUT=$(mktemp /tmp/codex_answer.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
printf '%s' 'Intent: This change should only alter behavior when suppressing idle notification sounds, and should not affect the playback of user input request sounds. Check uncommitted changes using git diff (also git diff --cached and untracked if needed). First verify if it aligns with intent, then examine implementation.
Focus points: Inversion of conditions, default value changes, meaning mismatches between client/server.
Output: recommendation → findings with evidence → unverified assumptions, in that order. Ignore naming and formatting.' \
  | codex exec - -s read-only -C /path/to/repo -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
echo "=== ANSWER ==="; cat "$OUT"

2b. Plain Diff Review Without Custom Focus: If no custom instructions are needed, you can use the scope flags of codex exec review directly (no PROMPT, so the above constraint does not apply). Unlike codex exec, there is no -C or -s, so cd into the target repository first.

OUT=$(mktemp /tmp/codex_review.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
cd /path/to/repo || exit 1
codex exec review --uncommitted -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
echo "=== ANSWER ==="; cat "$OUT"

Scope flag substitutions (replace the above codex exec review … line; no PROMPT in any case):

codex exec review --uncommitted -o "$OUT" >/dev/null 2>"$ERR"   # Uncommitted (staged + unstaged + untracked)
codex exec review --base main   -o "$OUT" >/dev/null 2>"$ERR"   # Diff against base branch
codex exec review --commit <SHA> -o "$OUT" >/dev/null 2>"$ERR"  # Specific commit
  • For reviews with a specific focus, use 2a (codex exec - + git diff). Scope flags and custom instructions cannot be combined.
  • Execute reviews inside the target repository (no -C, so cd first). Running outside a repo is possible with --skip-git-repo-check, but pointless without a diff.

3. Plan / Migration Validation (Recipe B)

Stress-test a plan or migration procedure before implementation to identify gaps that should be resolved before starting. Have Codex verify the current code's contracts in read-only mode.

OUT=$(mktemp /tmp/codex_answer.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
printf '%s' 'Review the pre-implementation plan and list only the gaps that must be resolved before coding.
Plan: When event sync is rejected by the server, set repair_required, send a compact snapshot, and resume incremental events only after the server acknowledges a consistent sequence.
Related: @src/sync/event-syncer.ts @src/db/sync-state.ts @api/types.ts.
First read the current code to verify existing contracts before evaluating.
Focus points: Schema compatibility, snapshot size limits, boundary conditions of the resume sequence, backfill/migration impact, test coverage gaps.
Output: Only the necessary plan changes before starting + a one-line verdict on whether it is safe to implement as-is.' \
  | codex exec - -s read-only -C /path/to/repo -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
echo "=== ANSWER ==="; cat "$OUT"

4. Deep Investigation (Recipe B)

Persistent investigation of root causes for bugs, test failures, race conditions, stale caches, etc. Include a verifiable success condition to leverage Codex's deep-dive strengths. Use background execution as it may take time.

OUT=$(mktemp /tmp/codex_answer.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
printf '%s' 'Test TestBar in foo_test.go fails rarely in CI. Investigate the root cause.
Success condition: Identify the reproduction conditions and the cause at file:line, and propose a minimal fix.
If you suspect an external library, check its official documentation via web search.' \
  | codex exec - -s read-only -C /path/to/repo -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
echo "=== ANSWER ==="; cat "$OUT"

Handling Results

  • Communicate the key points from the answer (tool result for Recipe A, background output after completion for Recipe B) to the user. For long answers, summarize while quoting critical findings.
  • Codex may sometimes propose overly defensive suggestions (excessive backward compatibility considerations, etc.). Decide which suggestions to adopt and which to reject yourself. Do not take it at face value; incorporate only what makes sense.

相关技能