Verify External API Docs

Verify External API Docs

Purpose

Keep the main coding thread clean while verifying external technical facts from the internet.

This skill is for moments when implementation quality depends on checking documentation instead of guessing.

Use when

Use this skill when the task involves code that depends on behavior outside the current repository, especially:

• third-party library APIs
• framework APIs
• language or standard library behavior
• CLI flags or command syntax
• config schema or supported options
• migration or deprecation checks
• version-sensitive usage

This includes cases where the user does not explicitly say "check docs", but the task clearly requires verification.

Typical hidden triggers inside a coding task:

• refactoring to a different library API
• replacing one function/class with another
• updating old code to a newer major version
• fixing an error caused by incorrect parameters or unsupported options
• checking whether a proposed API actually exists
• confirming exact signature/defaults before modifying code

Do not use when

Do not use this skill for:

• repository-internal APIs that can be verified from local code
• generic exploratory browsing
• choosing between libraries or comparing products at a high level
• package installation instructions unless directly needed for the code change
• architecture discussions that do not require exact external facts
• local codebase exploration

Inputs

Expected inputs:

• current coding task
• the relevant file, call site, error, or refactor target
• the external library, language feature, framework, CLI, or config topic to verify

Optional inputs:

• repo dependency files to infer likely version
• current failing code snippet
• target replacement API or migration direction

Outputs

The skill should produce:

1. a compact verification memo from the subagent
2. the minimal verified facts needed for the current task
3. the applied coding decision in the main thread

The final result should stay concise and should not paste large docs into the main context.

Constraints

• Prefer primary sources: official docs, language specs, official repositories, official release notes, and maintainer-authored migration guides.
• Use secondary sources only when no stronger source exists, and mark that clearly.
• Do not dump long excerpts from documentation into the main thread.
• Keep one subagent per distinct external topic; do not recurse further.
• Anchor to the likely installed version when repository context makes that possible.
• If the docs remain ambiguous, report ambiguity instead of guessing.

Procedure

1. Detect uncertainty that depends on external docs. Trigger this skill when the task would otherwise require guessing an API, parameter, option, behavior, or version detail.

2. Infer likely version before research when possible. Check nearby project files such as:

   • package manifests
   • lockfiles
   • pyproject.toml / requirements.txt
   • go.mod
   • Cargo.toml
   • pom.xml
   • relevant config files Do this only to narrow the research target.

3. Spawn a documentation subagent. Prefer the custom agent docs-researcher if available at ~/.codex/agents/docs-researcher.toml. If that custom agent is unavailable, use one bounded research subagent with the same contract. For multiple unrelated libraries or APIs, spawn one subagent per topic and wait for all results.

4. Subagent instructions. Ask the subagent to:

   • prioritize official documentation and primary sources
   • verify exact signatures, parameters, supported options, and semantics
   • identify version-specific differences
   • return only a compact memo

5. Keep the subagent return format small. Require this format:

   • Topic checked
   • Likely version or version caveat
   • Verified answer
   • Exact API details
   • Minimal example
   • Sources
   • Uncertainty or conflicts

6. Use the verified result in the main task. After the subagent returns:

   • continue the refactor, fix, or implementation
   • avoid re-explaining the whole docs page
   • surface only the facts necessary for the code decision

7. Handle uncertainty honestly. If the docs are ambiguous, conflicting, or version-mismatched:

   • say so clearly
   • choose the safest implementation path
   • prefer conservative changes over speculative API usage

Decision rules

When to trigger implicitly

Trigger when external correctness matters more than speed and the answer is likely version-sensitive or easy to hallucinate.

When not to trigger

Do not trigger if the answer is already available from local repository code or if the task does not depend on exact external behavior.

Version rule

If the repository version is visible, anchor the research to that version first. If not, mention the ambiguity explicitly.

Source quality rule

Prefer:

1. official docs
2. official repo docs, release notes, or migration guides
3. maintainer-authored material

Use blogs or forum answers only when no stronger source exists.

Definition of done

• External facts were verified from the strongest available sources rather than guessed.
• The memo stayed compact and focused on the exact coding decision.
• Version caveats are explicit when relevant.
• The main thread contains only the necessary verified facts, not a documentation dump.
• The resulting code decision is traceable back to the verified memo.

Final response behavior

In the main thread, return only a compact summary such as:

• what was verified
• what exact API or behavior is correct
• what code decision follows from that
• any version caveat that affects the change

Do not flood the main thread with documentation text.

Positive examples

Use this skill for tasks like:

• "refactor this to pathlib"
• "move this code to pydantic v2"
• "replace requests usage with httpx"
• "fix this unsupported keyword argument error"
• "update this React hook usage"
• "check whether this pandas parameter still exists"
• "see why this SQLAlchemy option fails after upgrade"

Negative examples

Do not use this skill for:

• "explain this repository architecture"
• "find where this local helper is defined"
• "compare 5 web frameworks for a new project"
• "install poetry on this machine"
• "write a high-level design doc"