Automatic prompt handling
The user can write an @skills: reference directly instead of instructing Codex to invoke a separate CLI for each use.
Yes,
but. Executive verdict
but. Executive verdict
Upstream is the engine; the plugin is the Codex adapter.
The upstream project already implements most of the difficult and reusable functionality: reference parsing, GitHub resolution, caching, saving, autotrigger rules, collection limits, and a command-line client.
The local plugin is therefore not a competing implementation. Its durable value is Codex-specific packaging, hook integration, workspace lifecycle handling, conversational management, and additional safety limits.
Bottom line: the plugin is optional for basic manual use,
but recommended when the desired experience is “paste an
@skills: reference into Codex and have it resolve automatically.”
Responsibility boundary
How the pieces fit together
The two repositories occupy adjacent layers. Eliminating the plugin would not eliminate the protocol, but it would remove Codex’s automatic bridge to it.
Layer 1 · Upstream
Protocol engine
Parses IDs, resolves local and GitHub skills, caches content, saves snapshots, and evaluates triggers.
Layer 2 · This repository
Codex adapter
Bundles the engine, exposes $atskills, applies safety guards, and translates Codex hook events.
Layer 3 · Codex
Task lifecycle
Receives resolved skill metadata on prompt submission and restores local workspace metadata on session start.
Capability matrix
What exists where
| Capability | Upstream atskills | atskills-codex | Assessment |
|---|---|---|---|
@skills: path grammar and parsing |
Implemented as protocol core. | Consumes the upstream implementation. | Upstream owns |
| Local and GitHub skill resolution | Implemented with Git-backed materialization and caching. | Calls the bundled upstream resolver through guarded wrappers. | Upstream owns |
| Save, install, uninstall, provenance | Protocol primitives and reference CLI exist upstream. | Adds Codex-oriented commands, confirmation rules, state indexing, and size limits. | Adapted |
| Automatic resolution in a Codex user prompt | Documented as a host responsibility. | UserPromptSubmit finds and resolves references automatically. |
Plugin value |
| Session restoration | Provides the index builder; the host must decide when to splice it into context. | SessionStart restores bounded local metadata after startup, resume, clear, or compaction. |
Plugin value |
| Codex installation and discovery | No Codex plugin manifest or marketplace entry. | Includes .codex-plugin/plugin.json and a repository marketplace. |
Plugin value |
Interactive /skills UI and native @ completion |
Reference UI and host integration patterns are provided. | Not added to Codex; management is conversational through $atskills. |
Not equivalent |
| Self-contained runtime | Source and built artifacts exist, but the named npm package is not currently published. | Pins and bundles the upstream runtime plus its ignore dependency. |
Useful today |
Why retain the adapter
Material benefits inside Codex
Lifecycle awareness
The plugin participates in prompt submission and session restoration, including resume, clear, and context compaction events.
Stable distribution
A Codex manifest and marketplace make the integration installable as one unit rather than a per-workspace clone and manual setup.
Safety boundary
Resolved paths must stay within approved roots, symlinks are rejected, skill bodies are not injected by hooks, and skill files are never executed.
Bounded context
The adapter caps references, hook metadata, individual skill files, and saved snapshots to prevent accidental or hostile context expansion.
Conversational management
The bundled $atskills skill gives Codex explicit workflows for listing, saving, installing, inspecting, and removing skills.
Caveats and maintenance risk
What the plugin does not fully solve
Remote-only autotriggers are partial
Session startup deliberately performs no network resolution. A remote-only
installed reference can be restored as metadata telling Codex to use
@skills:<id> when needed, but it is not eagerly materialized
into a readable local skill at session start.
No native autocomplete or management UI
The integration recognizes references after submission. It does not extend
Codex’s @ dropdown or reproduce upstream’s interactive
/skills interface.
Some wrapper logic overlaps upstream
State and command wrappers intentionally add Codex policy, but they also increase the surface that must remain aligned with upstream behavior.
Vendoring creates an update obligation
The snapshot is reproducible and integrity-checked, but upstream fixes only arrive after the pinned revision, generated runtime, notices, and tests are refreshed together.