Codex Capability Advisor

中文说明 · Why it exists · Installation · CLI · Security & privacy

Codex Capability Advisor is a local capability-routing Skill and Python catalog layer for Codex task Agents. It inventories plugins, skills, apps, and MCP capabilities before a non-trivial task is routed. It is not a standalone Agent: the active main task Agent reads the Skill, queries local evidence, and owns the final routing and execution decision.

This is an independent community project. It is not an OpenAI product and is not affiliated with or endorsed by OpenAI.

Why this exists

Have you installed many Codex skills "for later," only to forget what you already have when a real project begins?

Have you ever searched for a new tool—or rebuilt a workflow from scratch—even though a suitable plugin was already installed?

When a new task arrives, do you know which capabilities are ready, which need to be combined, what is still missing, and whether an external candidate is safe to trust?

$capability-advisor helps Codex keep track of those capabilities for you. Describe what you want to accomplish, and it first inventories local plugins, skills, apps, and MCP tools; classifies the task as full, partial, gap, or blocked; and only guides privacy-preserving, read-only external discovery when a core gap remains.

You should not have to memorize every installed skill. Codex should know when it is relevant.

What it does

• Builds a local, evidence-backed capability catalog from Codex CLI output, manifests, SKILL.md files, MCP metadata, and cache metadata.
• Keeps installed, available, disabled, local, system, and cache-only states separate. Cached metadata never counts as proof of installation.
• Ranks bilingual task terms against the catalog while keeping relevance and runtime readiness separate.
• Routes a task as full, partial, gap, or blocked and asks Codex to read each selected skill's full instructions before use.
• Guides privacy-preserving, read-only external discovery only when a core capability gap remains.
• Requires explicit user confirmation before installation, enablement, authentication, payment, background services, third-party code execution, or external writes.

The bundled Python CLI creates and queries the local catalog. It does not browse the web or install third-party software. External discovery is a policy followed by Codex after local assessment.

Task and host boundary

• Within the same Codex home, a task Agent can load and use it when capability-advisor appears in that runtime's Available Skills. The main task Agent routes each logical task once and owns any later re-evaluation.
• The execution subagents reuse the shortlist and evidence handed off by the main task Agent; they do not independently rerun capability routing.
• Follow-ups in existing tasks reuse the prior decision unless the core goal or catalog state changes, or the user asks for a new assessment.
• In particular, remote Agents and other machines do not inherit this machine's catalog, session visibility, authentication, or runtime-readiness facts. Install the Skill and build a separate local catalog on each host.

Requirements

• Python 3.11 or newer; runtime code uses only the Python standard library.
• A local Codex installation with a working Codex CLI for live collection.
• macOS is the primary tested environment. Other platforms may work when their CLI and capability paths are discoverable, but are not currently guaranteed.

Install

Clone this repository, then copy only the skill package into your Codex skills directory:

git clone https://github.com/ymzhang10/codex-capability-advisor.git
cd codex-capability-advisor

codex_home="${CODEX_HOME:-$HOME/.codex}"
skill_target="$codex_home/skills/capability-advisor"

if [ -e "$skill_target" ]; then
  mv "$skill_target" "$skill_target.backup-$(date +%Y%m%d-%H%M%S)"
fi

mkdir -p "$codex_home/skills"
cp -R skills/capability-advisor "$skill_target"

Open a new Codex task so the skill list is refreshed. See Installation for validation and optional global routing.

Everyday use

You can invoke the skill explicitly:

Use $capability-advisor to assess which installed capabilities can handle this task,
identify any gaps, and do read-only external discovery only if a core gap remains.

For automatic routing, add the example capability-routing rule from the installation guide to your global AGENTS.md. Simple translation, formatting, time/date questions, one-line shell syntax, and single stable facts should bypass the advisor.

The local catalog CLI supports four commands:

advisor="${CODEX_HOME:-$HOME/.codex}/skills/capability-advisor/scripts/capability_catalog.py"

python3 "$advisor" status --json
python3 "$advisor" refresh
python3 "$advisor" query --term "视频字幕" --term "video subtitles" --json
python3 "$advisor" inventory --json

• status --json validates persisted artifacts without calling the live Codex CLI.
• status --live --json performs a live source comparison.
• refresh [--force] [--dry-run] collects current sources and safely publishes a new catalog when needed.
• query ranks matching candidates; repeated --term flags support Chinese and English.
• inventory lists machine-present capabilities by default; --all also shows available and cache-only entries.

Live status and refresh call the local Codex CLI. They do not install or authenticate anything themselves, but the underlying CLI may use network access depending on the installed Codex version and configuration.

See CLI reference for filters, result frames, and exit codes.

Generated local data

By default, the CLI writes:

• ${CODEX_HOME:-$HOME/.codex}/workspaces/capability-advisor/catalog.json
• ${CODEX_HOME:-$HOME/.codex}/workspaces/capability-advisor/catalog.md
• ${CODEX_HOME:-$HOME/.codex}/workspaces/capability-advisor/state.json
• $HOME/Codex-插件清单.md

These generated files are intentionally not included in this repository. Although secret values are filtered, a catalog can still contain capability names and local evidence paths. Treat it as local metadata and do not publish or attach it without reviewing and redacting it first.

Safety model

The advisor separates observation from inference, refuses to treat availability or cache presence as installation, and preserves unknown authentication or runtime health as unknown. Sensitive tasks must be reduced to abstract capability terms before any external search; local paths, filenames, record contents, account identifiers, and personal details must not be included in queries.

Read Security and privacy before using the catalog with sensitive projects.

Development

bash scripts/validate.sh

The test suite covers CLI fallback, catalog state classification, namespace identity, version handling, metadata privacy, artifact integrity, refresh behavior, and query ordering. See Contributing and Architecture.

Scope and limitations

• No background daemon, scheduler, database, UI, or automatic marketplace updater.
• No automatic installation, enablement, authentication, payment, or external write.
• Runtime session visibility is a session-level cross-check, not persisted installation proof.
• A catalog is a snapshot. Use status and refresh it when stale, damaged, or changed.
• MCP or app declarations do not prove authentication, reachability, tool visibility, or callability.

License

MIT. See NOTICE for project attribution and trademark clarification.