AlexJSully · Sep 27, 2026 · Sep 27, 2026 · Sep 27, 2026 · AlexJSully · Sep 27, 2026
@@ -5,6 +5,7 @@ paths:
     - '.claude/skills/*/README.md'
     - '.claude/skills/*/SKILL.md'
     - '.claude/skills/*/agents/*.md'
+    - '.claude/skills/*/agents/openai.yaml'
     - '.claude/skills/*/assets/*.md'
     - '.claude/skills/*/references/*.md'
     - '.github/prompts/*.prompt.md'
@@ -61,6 +62,8 @@ An illustrative link, such as `[config.py](../src/config.py)` inside an example
 
 A skill directory is a plugin root in two ways. In the repository holding it, a `.claude-plugin/plugin.json` inside it makes Claude Code load it as `<name>@skills-dir` on the next session, with no marketplace and no install step, and that manifest is what turns the files in `agents/` into agents a run can delegate to. Everywhere else, the marketplace at [`.claude-plugin/marketplace.json`](../../.claude-plugin/marketplace.json) lists it with a `source` of `./.claude/skills/<name>`, and VS Code and Claude Code install the directory as a plugin whose root `SKILL.md` is its one skill and whose `agents/` they find by default, manifest or not. Without either route the files in `agents/` stay ordinary files, which is what each `SKILL.md` already treats as the default when it tells the run to open one and follow it: `agents/` is a host extension, not part of the Agent Skills specification, which defines `references/`, `assets/`, and `scripts/` and nothing else.
 
+**Codex reads one file in `agents/`, and it is not an agent.** Codex takes agent roles only from `.toml` files in its own configuration ([`agent-roles/src/loader.rs`](https://github.com/openai/codex/blob/main/codex-rs/agent-roles/src/loader.rs)), so it treats no `agents/*.md` as an agent definition, and its skill loader reads `agents/openai.yaml` and no other file there, for display metadata, tool dependencies, and invocation policy ([`loader/metadata.rs`](https://github.com/openai/codex/blob/main/codex-rs/ext/skills/src/loader/metadata.rs)). The `audit-docs` copy, [`agents/openai.yaml`](../skills/audit-docs/agents/openai.yaml), sets `policy.allow_implicit_invocation: false`. Codex's [skill catalogue prompt](https://github.com/openai/codex/blob/main/codex-rs/ext/skills/src/catalog_prompt.rs) tells the model it must use any skill whose description matches the task, and a description as broad as that skill's would otherwise pull a full audit, with its in-code pass, into ordinary feature work. The skill still runs when invoked by name. Claude Code documents an agent as a Markdown file, and `claude plugin validate` passes with the YAML file present.
+
 **The manifest is an optimization, never a dependency.** Every bundled procedure is written to be run by opening its file, and each `SKILL.md` says so before it mentions delegating, because a skill that tells an agent to delegate to something the host never registered has no documented fallback: the call fails and the run improvises. An improvised prompt carries none of the scope bound or evidence bar written inside the procedure, which is the whole reason the file exists.
 
 Consequences to know before editing a skill, its manifest, or the marketplace:

@@ -49,7 +49,7 @@ const MAX_PROMPT_CHARS_BY_FILE = { 'audit-docs.prompt.md': 36_000 };
 /**
  * Directories a skill may bundle. The specification defines `references/`, `assets/`, and
  * `scripts/`; `agents/` is a host extension, read only where a host loads the directory as a
- * plugin, and inert everywhere else.
+ * plugin, or by Codex for its `agents/openai.yaml` metadata file, and inert everywhere else.
  */
 const BUNDLE_DIRS = ['references', 'agents', 'assets', 'scripts'];
 

@@ -12,7 +12,7 @@ Audits a project's documentation against its code and corrects what has drifted,
 
 ## Usage
 
-Invoke the skill by name, for example `/audit-docs`, optionally followed by the paths or area to audit. Without one, it works from the active pull request, then uncommitted changes, then the component the surrounding task concerns, and only then the whole documentation set.
+Invoke the skill by name, for example `/audit-docs`, optionally followed by the paths or area to audit. Without one, it works from the active pull request, then uncommitted changes, then the files the surrounding task named or edited, and only then the whole documentation set. It edits only files inside that scope: a file it opens to check a claim stays untouched, and on a pull request the in-code pass covers the changed files plus files they reference directly, never another package or workspace.
 
 - `/audit-docs`
 - `/audit-docs docs/api`

@@ -0,0 +1,3 @@
+# Read by Codex alone: the skill loads when invoked by name as $audit-docs, never on a description match.
+policy:
+    allow_implicit_invocation: false
@@ -21,7 +21,7 @@ Report every public or exported symbol that carries no documentation comment, an
 
 **Public means whatever the language in front of you means by it.** Read the project's own spelling rather than assuming one. The forms differ: an `export` or `pub` keyword; a `public` access modifier; a capitalized identifier at package level; a name listed in a module's exported-names collection; a name that merely lacks a leading underscore; a symbol re-exported through an entry-point file while its defining file is internal. Where a language offers no marker at all, treat what the entry-point file re-exports as the surface.
 
-State the rule `SKILL.md` already carries and do not soften it: on a public surface, being obvious is not a defect and being absent is. A symbol whose behaviour is plain from its name still lands in this list, because the comment is written for a reader meeting it for the first time.
+State the rule `SKILL.md` already carries and do not soften it: on a public surface, being obvious is not a defect and being absent is. A symbol whose behaviour is plain from its name still lands in this list, because the comment is written for a reader meeting it for the first time. That comment is one sentence by default, so an entry here asks the caller for a sentence, not a paragraph.
 
 ## List two: comments the implementation contradicts
 

@@ -44,7 +44,7 @@ Sources that could not be resolved this run: [name each one and what you used in
 
 - Corrected `[document]`: [the statement that contradicted the code] replaced with [the statement the code supports], from `[symbol]` in `[file]`.
 - Deleted [section] from `[document]`: [describes a removed feature / duplicated in `[document]` / cannot be corrected].
-- Split `[document]` into `[overview document]` and `[depth document]`: [it mixed a brief overview with deep reference/how-to/explanation content], filed by [the sibling or precedent that decided each directory].
+- Split `[document]`, kept at its path as the overview, adding `[depth document]`: [it mixed a brief overview with deep reference/how-to/explanation content], filed by [the sibling or precedent that decided the depth document's directory].
 - Created `[new document]`: [why no existing document was a home for it], filed as [tutorial / how-to guide / reference / explanation].
 - Oriented `[document]`: [the acronym, term of art, prerequisite, or missing statement of subject that stopped a first-time reader] introduced at [where].