openai / openai/codex

Bundled openai-docs Skill should respect explicit offline instructions

Open Beginner friendly
#43,164 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug skills
Dominant language
Rust
Stars
125k
Forks
19.4k
PR merge metrics
PR metrics pending

Description

Environment and source

  • Codex desktop: 26.901.20858 (build 7658)
  • Codex CLI: 0.153.0-alpha.5
  • macOS: 26.6.2 (25G83)
  • Source path: codex-rs/skills/src/assets/samples/openai-docs/SKILL.md
  • Current source commit inspected: 6af345407d9c2a568da9d01b6c4b81a9e61495c0

The installed .system/openai-docs/SKILL.md is byte-for-byte identical to this
source path at commit a5082373f18119dc5d3eb993267c97f37880935d
(SHA-256 7cb8fa1b2a0c635b5c61ffe1da7b8594a7ea0fce5b71e8d523e2025d88b2a05e).
Current main changed the bundled model-migration reference but retains the
online-first rule described below. The deprecated openai/skills copies and
the Cursor repository copy are different bytes and are not used as provenance
for this report.

Reproduction

  1. Start a Codex task that explicitly prohibits network access and asks for
    local implementation, analysis, or testing involving OpenAI documentation.
  2. Invoke the bundled openai-docs Skill.
  3. Read its required first action and exception.

The Skill requires official online search and page retrieval before local or
repository inspection. Its only stated exception is a broad, manual-first Codex
setup or orientation request. It does not define a path for an explicit
offline-only request.

This is a contract-level reproduction. No additional model run was used to
claim measured runtime impact.

Expected behavior

When active instructions explicitly disallow network access, the Skill should:

  • avoid search, fetch, and requests to relax the offline constraint;
  • use supplied or local material with source identity and As-of;
  • avoid presenting cached material as current;
  • mark only a claim or action that needs current information as UNKNOWN or
    HOLD; and
  • continue independent authorized offline work.

When network access is allowed, the existing official-domain docs-first order
should remain unchanged.

Proposed minimal change

In SKILL.md:

  1. Scope the existing “First substantive action” to cases where network access
    is allowed.
  2. Add one explicit offline-boundary paragraph with the behavior above.
  3. Rename the current “Only exception” to a manual-first exception that applies
    when network access is allowed.
  4. Scope the official-domain search boundary to network-allowed work.

The prepared source diff changes one file: 5 insertions and 3 deletions.

Static validation cases

Case Expected result
Explicit offline + supplied API snapshot Use the snapshot with source/As-of; no network request or permission question
Explicit offline + current price/latest model required Mark that current claim UNKNOWN; do not present cached data as current
Offline implementation + one current-spec dependency Hold only the dependent claim/action and continue independent offline work
Network-authorized current API question Preserve official docs-first search and page retrieval
Unexpected network failure without an offline instruction Do not misclassify it as an explicit offline request; existing failure handling still applies

Validation

  • Skill quick_validate.py — PASS
  • git diff --check — PASS
  • Manual static evaluation of the five cases above — consistent with the
    proposed branch text
  • just fmt and just test -p codex-skills — not run because the isolated host
    has no just or Rust toolchain; no dependency was installed

Issue #24239 concerns a missing default Docs MCP configuration and is related to
the same Skill but does not cover explicit offline instructions.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with codex-rs/skills/src/assets/samples/openai-docs/SKILL.md and read the existing first-action, exception, and official-domain search instructions. Use quick_validate.py and the five static cases in the issue to check the wording. Done means explicit offline requests avoid network guidance while network-authorized work keeps the docs-first order.

Written by the indexing model from the issue text.

Assessment

Domain
ai-infra-agents, documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
88/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.