| name | codex-onboarding |
| description | A guided first run of the nddev-builder toolkit — from zero to a working, checked Codex artifact in ordered steps. Use when new to nddev-builder, onboarding, or unsure which builder skill to start with. |
Codex Onboarding
Resolve every ../../scripts and ../../references path relative to this SKILL.md directory, never the caller working directory.
The fastest correct path from nothing to a working, validated Codex artifact.
Read $codex-builder-orientation once for the family map, pick a path below,
and let each step hand off to the focused creator, checker, or workflow skill.
The one thing to understand first
Choose the smallest native surface the task needs, because Codex validates
and loads each one differently:
AGENTS.md for durable repository guidance; a skill for a reusable
workflow; a plugin to distribute skills/hooks/MCP/apps; MCP or an app
for a live external capability; a hook for lifecycle enforcement; a
rule for outside-sandbox command policy; and a config/permission
profile for model and safety posture.- Codex has no first-class authored slash commands — a reusable command
workflow is authored as a skill.
- Custom-agent TOML is a standalone config-scope file
(
$CODEX_HOME/agents/<name>.toml or <repo>/.codex/agents/<name>.toml), not
a plugin-bundled component.
The family list, schemas, and current (Beta/experimental/under-development)
surfaces live in ../../references/codex-artifact-contracts.md and the two script
--help outputs — read them, never a frozen copy.
Path 1 — add one artifact to an existing repo or config
- Name the family (
skill, config, hook, mcp, agent, rule,
instructions, app, requirements).
- Author with the owning creator:
$codex-<family>-creator (for example
$codex-skill-creator). It stages a conservative skeleton.
- Complete the content, then validate with
$codex-<family>-checker (or
python3 ../../scripts/check_codex_artifact.py <family> <path>).
- Prove behavior with the runtime step in that family's contract, using a
temporary
HOME/CODEX_HOME — a static PASS proves shape only.
Path 2 — build a whole plugin from an idea
$codex-plugin-scaffolder — compose the bundle (manifest plus the skills,
hooks, MCP servers, and app mapping the idea needs) from intent.$codex-plugin-devtest — register through a temporary marketplace with
isolated CODEX_HOME and confirm discovery and install.$codex-release-review — gate the whole bundle for release readiness.$codex-plugin-publish — version, catalog, and publish when others install
it.
Path 3 — start or distribute a marketplace
$codex-marketplace-creator — scaffold the catalog (local, url,
git-subdir, or npm plugin sources via --source-type).- Add plugins with Path 2, then
$codex-release-review.
$codex-plugin-publish for distribution; register and inspect only with the
exact target-owned Codex CLI.
Golden rules (from day one)
- Read
$codex-builder-orientation first; author with exactly one owning skill
and defer to its description.
- A static generate or check proves shape only — always run the matching
checker and then the contract's runtime step in isolated state.
- Full
agent and config TOML validation needs Python 3.11+; on 3.10 the
checker fails closed rather than returning an unchecked PASS.
- Keep credentials, OAuth tokens, trust hashes, and machine-local paths out of
every artifact; reference secrets through the environment.
- English only. Never mix permission profiles with legacy
sandbox_mode in one
loaded layer.
Where to go deeper
$codex-builder-orientation for the full family map and ownership boundaries,
and ../../references/codex-artifact-contracts.md for every artifact's exact
contract, runtime check, and current maturity.
