AgentSkillsCN

codex-sdk-research

首先检查 node_modules 中已安装的 .d.ts 类型定义，随后克隆并搜索 github.com/openai/codex 仓库，以获取源码与相关文档，从而深入探究 @openai/codex-sdk API。当您对 Codex SDK 的 API 表面、数据类型、响应格式、线程与运行任务，或 Codex SDK 的行为调试等问题存疑时，可使用此技能进行解答。

SKILL.md
--- frontmatter
name: codex-sdk-research
description: Investigate the @openai/codex-sdk API by first inspecting installed .d.ts typings in node_modules, then cloning and searching the github.com/openai/codex repo for source/docs. Use for questions about Codex SDK API surface, types, response formats, threads/runs, or debugging codex-sdk behavior.

Codex SDK Research

Workflow

Follow the stages in order. Treat stage 1 as the source of truth for the installed API, and stage 2 for implementation details and docs.

Stage 1: Inspect installed .d.ts in node_modules

  1. •Locate the installed package and version.
    • •npm ls @openai/codex-sdk
    • •node -p "require.resolve('@openai/codex-sdk/package.json')"
  2. •Open the package.json and record:
    • •version
    • •types / typings
    • •exports entries (especially any types fields)
  3. •Find all .d.ts files under the package root and skim the entrypoint first.
    • •rg --files -g '*.d.ts' <pkg-root>
    • •Open the main .d.ts referenced by types or exports
  4. •Map the public API surface:
    • •Identify exported classes/functions/types and their signatures.
    • •Note any JSDoc comments or deprecation markers.
    • •Track key types related to the question (e.g., threads, runs, response formats, schemas).
  5. •If something is missing or unclear, search within .d.ts files:
    • •rg -n "export|interface|type|class|enum" <pkg-root>
    • •rg -n "Thread|Run|outputSchema|response_format|schema" <pkg-root>

Stage 1.5: Locate Codex session rollouts (debugging)

When debugging Codex CLI behavior, locate the session JSONL rollouts stored under the Codex home directory (~/.codex by default or $CODEX_HOME if set):

  • •Latest rollout file (by mtime):
    • •ls -t "${CODEX_HOME:-$HOME/.codex}"/sessions/*/*/*/rollout-*.jsonl | head -n 1
  • •Grep for a conversation id (if known):
    • •rg -n "<conversation-id>" "${CODEX_HOME:-$HOME/.codex}"/sessions/*/*/*/rollout-*.jsonl

Stage 2: Clone repo and inspect source/docs

  1. •Clone the repo if it is not already present.
    • •git clone https://github.com/openai/codex ~/repos/codex
  2. •If you know the installed SDK version, try to align tags/commits:
    • •git -C ~/repos/codex tag --list | rg <version>
    • •git -C ~/repos/codex checkout <tag-or-commit>
  3. •Search for implementation and docs related to the question:
    • •rg -n "codex-sdk|sdk|Thread|Run|outputSchema|response_format" ~/repos/codex
    • •Check README, docs/, and any JS/TS packages or SDK folders.
  4. •Use source to confirm behavior, defaults, and error handling that are not explicit in .d.ts.

Output

  • •State the installed SDK version and where the typings were found.
  • •Summarize the relevant public API from .d.ts (signatures, types, expected inputs/outputs).
  • •Add implementation/doc details from the repo (if needed) and call out any version mismatch.
  • •If unsure, say what is missing and which file you would inspect next.