### What is the type of issue? - Documentation is missing ### What is the issue? `docs/skills.md` in this repo is currently a three-line redirect: > # Skills > > For information about skills, refer to [this documentation](https://developers.openai.com/codex/skills). The linked external page describes the Agent Skills format, but neither page shows a complete, runnable end-to-end install of a third-party skill — what the directory looks like on disk, what env vars to declare, what bins are r

docs: add a runnable third-party Agent Skill install example

Open 💬 7 comments Opened May 23, 2026 by zhengyanglsun

What is the type of issue?

Documentation is missing

What is the issue?

docs/skills.md in this repo is currently a three-line redirect:

# Skills For information about skills, refer to this documentation.

The linked external page describes the Agent Skills format, but neither page shows a complete, runnable end-to-end install of a third-party skill — what the directory looks like on disk, what env vars to declare, what bins are required, and how to verify that the skill actually loaded.

The practical result: a user coming to Codex CLI with "someone else published a skill I want to install" has to assemble the workflow from multiple pages, and may not realize Agent Skills is an open, portable format with skills already published by third parties.

A concrete community example available today

iflow-search is an Agent-Skills-format skill that bundles a single SKILL.md (bilingual EN/zh) plus three small bash scripts:

scripts/web_search.sh — keyword web search
scripts/image_search.sh — keyword image search
scripts/web_fetch.sh — URL to cleaned markdown content

Requirements declared in the skill's SKILL.md:

env: IFLOW_API_KEY
bins: bash, curl

iFlow's own skill landing page (<https://platform.iflow.cn/docs/skill>) lists Codex CLI as one of its supported installer targets, so this is a public, low-risk reference example — not an endorsement request.

Suggested doc shape

A short addition to docs/skills.md (or a new sibling page linked from it) showing:

Where Codex CLI looks for installable Agent Skills, and the on-disk layout it expects.
A worked install of one real community skill, using whatever install path Codex CLI's docs recommend.
Required env-var setup, set in the shell before launching Codex CLI (env-only — never as a CLI flag, never committed):

~~~bash
echo 'export IFLOW_API_KEY="YOUR_IFLOW_API_KEY"' >> ~/.zshrc
source ~/.zshrc

use the equivalent rc file if you use bash or another shell

~~~

YOUR_IFLOW_API_KEY is a placeholder; users get a real key from <https://platform.iflow.cn/profile?tab=apiKey>.

How to verify the skill is loaded (whatever Codex CLI's equivalent of a "list installed skills" surface is).

Notes and scope guardrails

Framing should be "community / third-party skill example," not an official endorsement.
This is strictly about the user-installable Agent Skills surface — not a request related to provider/model integrations of any kind.
No real API key is included anywhere in this issue, and any suggested doc copy should use the YOUR_IFLOW_API_KEY placeholder only.
Not requesting a PR invite — flagging the doc gap and offering an example that already exists, in case the team finds it useful. Happy to share additional verification artifacts (install transcript, sample SKILL.md frontmatter, etc.) in the thread if helpful.

Where did you find it?

<https://github.com/openai/codex/blob/main/docs/skills.md>
<https://developers.openai.com/codex/skills>

View original on GitHub ↗

7 Comments

yui-stingray · 1 month ago

I checked current openai/codex@7d47056; docs/skills.md is still just the three-line redirect to the external skills docs. The closest bundled implementation pieces are in the system skill-installer skill:

codex-rs/skills/src/assets/samples/skill-installer/scripts/install-skill-from-github.py
codex-rs/skills/src/assets/samples/skill-installer/scripts/list-skills.py

I have not verified a specific third-party repo install here, so I would avoid naming one as tested unless the docs change includes that verification. A minimal docs shape could be a short sibling page linked from docs/skills.md that shows one tested third-party install walkthrough plus a verification step using the list script / installed-skill surface. Keeping the redirect page small and linking out would avoid duplicating the full external skills spec while still giving CLI users a runnable path.

zhengyanglsun · 1 month ago

Thanks for the careful framing — agreed on not naming a specific third-party skill as "tested on Codex" without verifying the runtime path.

I ran a clean-environment install check using Codex's bundled skill-installer scripts with one public third-party Agent-Skills-format repo:

install-skill-from-github.py --repo iflow-ai/iflow-skills --path skills/iflow-search --method download succeeds with no GITHUB_TOKEN and no skill-specific env vars; it installs SKILL.md plus the bundled scripts under $CODEX_HOME/skills/iflow-search/.
list-skills.py --repo iflow-ai/iflow-skills --path skills then reports iflow-search (already installed).
Re-running the install errors cleanly with Destination already exists, so the no-overwrite path is also clear.

I did not exercise the installed skill's network calls from inside a Codex session, so I would avoid any "tested on Codex" framing for the skill itself. The safer wording is only that this is a format-validated third-party install example using the bundled installer/list scripts.

The sibling-page shape you suggested sounds right to me:

Keep docs/skills.md as a short redirect / entry point.
Add a short sibling page focused on installing a third-party Agent Skill with the bundled installer.
Include one install-skill-from-github.py command.
Include one list-skills.py verification command.
Note that Codex may need to be restarted to pick up newly installed skills.
Mention that some skills require env vars set in the shell before launching Codex, using placeholders only and linking to the skill's own SKILL.md as the source of truth.

Happy to share the full install transcript if useful. Not asking for a PR invite — just confirming that the install/list path is concrete enough for a minimal docs example.

SylvainWinning · 1 month ago

Thanks for the existing investigation and the clean-environment install check above. I think this is now concrete enough to frame as a docs-only MVP, while still avoiding any third-party endorsement claim.

Suggested acceptance criteria:

Keep docs/skills.md as the short entry point and link to a focused “Install a third-party Agent Skill” page or section.
Show one public GitHub-directory install using the bundled skill-installer path.
Show one verification step using the bundled list/installed-skill surface.
Use placeholder-only environment variable examples, and make the skill’s own SKILL.md the source of truth for required env vars/binaries.
State that Codex may need to be restarted if a newly installed skill does not appear.
Avoid claiming the third-party skill’s runtime behavior is tested unless that exact runtime verification is included.

This keeps the proposal small: document the install/list path that Codex already ships, help users understand the open Agent Skills format, and avoid expanding the scope into plugin registry or provider endorsement decisions.

zhengyanglsun · 1 month ago

Thanks — I mapped this into a very small docs-only MVP shape and it seems to fit the acceptance criteria above.

Proposed patch shape:

keep docs/skills.md as the short entry point;
add one sibling page, tentatively docs/skills-install-example.md;
add one link from docs/skills.md to that page;
show one public GitHub-directory install using the bundled skill-installer scripts:
install-skill-from-github.py --repo iflow-ai/iflow-skills --path skills/iflow-search --method download
show one verification step using the bundled list surface:
list-skills.py --repo iflow-ai/iflow-skills --path skills
expected output includes iflow-search (already installed);
mention that Codex may need to be restarted if the newly installed skill does not appear;
keep env-var examples placeholder-only and point readers to the skill's own SKILL.md as the source of truth for required env vars / binaries;
explicitly state that this verifies only the install/list path, not runtime behavior of the third-party skill inside Codex;
avoid endorsement, plugin registry, provider, SDK, npm/PyPI, or package-manager scope.

I have a draft ready in that shape, but given the repo's contributing guidance around invitation-only external PRs, I don't want to open a PR without maintainer confirmation.

Would a small docs-only PR following the outline above be welcome, or would you prefer the patch text to stay in this issue for now?

WoojinAhn · 1 month ago

One additional data point for the install-example docs:

On codex-cli 0.133.0, bundled system skills are present under:

~/.codex/skills/.system/

and the bundled skill-installer guidance installs into:

${CODEX_HOME:-$HOME/.codex}/skills/<skill-name>

The public skills docs currently describe .agents/skills locations for repo/user/admin discovery. That may be the intended standard authoring/discovery path, but it is easy for users to confuse it with the managed install path used by the current CLI.

A third-party install example should probably clarify the distinction, or explicitly say which path is verified for the CLI version used in the example.

zhengyanglsun · 1 month ago

Thanks @WoojinAhn — that distinction is important, and I folded it into the draft.

I updated the proposed page so it is scoped explicitly to the current CLI-managed installer destination:

${CODEX_HOME:-$HOME/.codex}/skills/<skill-name>/

It also calls out the bundled system-skills directory you observed on codex-cli 0.133.0:

~/.codex/skills/.system/

And it keeps the general .agents/skills/ repo / user / admin discovery locations out of scope, linking to the public Agent Skills docs instead of duplicating or replacing them.

The updated docs-only MVP shape is now:

keep docs/skills.md as the short entry point;
add one sibling page for the CLI-managed third-party install/list path;
show one install-skill-from-github.py command;
show one list-skills.py verification command;
mention restarting Codex if the newly installed skill does not appear;
use placeholder-only env-var examples and defer required env vars / bins to the skill's own SKILL.md;
explicitly state that this verifies only the install/list path, not runtime behavior inside Codex;
avoid endorsement, plugin registry, provider, SDK, npm/PyPI, or package-manager scope.

The previous question still stands: given the repo's invitation-only contribution policy, would a small docs-only PR following this shape be welcome, or should the patch text stay in this issue for now?

zhengyanglsun · 1 month ago

Friendly bump on the remaining decision: would maintainers welcome a small docs-only PR following the scoped proposal above, or would you prefer that the example text remain in this issue?

Happy to proceed either way once there is guidance.