| name | update-zskills |
| description | Maintain this Codex port of Z Skills by checking upstream changes, refreshing references/support assets, and preserving Codex-native wrappers. |
Codex Runtime Rules
These Z Skills are native Codex workflows derived from github.com/zeveck/zskills at commit 14dea81da487b2904ea7d69a27295f1869206cdf. They are invoked by natural language or by naming the skill; examples that look like slash commands are only shorthand for the skill name.
Use Codex behavior first:
- Read the current repository before acting. Prefer existing project scripts, config, and conventions over the upstream examples.
- Never use Claude-only tools or assumptions: no
CronCreate, CronList, CronDelete, Agent/Task tool syntax, allowed-tools, .claude/settings.json, or automatic Claude hooks.
- Use sub-agents only when the user explicitly asks for agents, parallel work, or delegation. For Z Skills landing gates, prefer a fresh independent verification context when it is available without violating the current Codex delegation policy; otherwise run inline, disclose lower assurance, and do not auto-land unless the user accepts it.
- For isolation, create git worktrees explicitly with normal
git worktree commands. Do not rely on an isolation: "worktree" parameter.
- Config lookup order is project
.agents/zskills-config.json first, then project zskills-config.json, then legacy .codex/zskills-config.json, then legacy .claude/zskills-config.json only if already present. Do not create new .claude runtime config for Codex.
- Scheduling is not automatic in Codex. If the user asks for recurring runs, explain the schedule and ask before installing any local cron/system scheduler. For normal turns, perform the requested work now.
- Helper assets live at project
.agents/zskills-support by default. Use project-local scripts/* first; fall back to $CODEX_HOME/zskills-support only for explicit global installs or legacy setups.
- Preserve Codex safety rules: do not revert unrelated work, stage files by name, avoid destructive git commands, and verify from actual diffs/tests.
Detailed upstream text is archived in references/upstream-claude-adapted.md for edge cases and future diffs. Load it only when the concise workflow below is insufficient.
Update Z Skills
Purpose
This is a Codex maintenance workflow for the installed port. It is not the upstream Claude Code installer.
Workflow
- Fetch or clone
github.com/zeveck/zskills-codex to a temporary location and record the distribution commit.
- Compare the distribution's
.agents/skills, .agents/zskills-support, .agents/zskills-config.json, and install docs against the installed Codex copy.
- Preserve project-local install metadata such as
.agents/README.md, updating it to the new zskills-codex commit after refresh.
- Refresh
references/upstream-claude-adapted.md for changed skills and refresh .agents/zskills-support assets in project-local installs, or $CODEX_HOME/zskills-support assets in explicit global installs.
- Keep Claude-only mechanics out of active Codex instructions: no
.claude/settings.json, no Claude hooks as runtime config, no Claude cron tools, no allowed-tools frontmatter.
- Re-run validation: frontmatter, skill count, reference existence, no temp paths, no Claude-only executable instructions in active wrappers, and line counts.
- Run or refresh the external runner canaries from
.agents/zskills-support/tests/runner/run.sh or $CODEX_HOME/zskills-support/tests/runner/run.sh: all, plus any slow/optional cases called out by the current runner plan. At minimum this must cover multi-chunk finish auto, direct unattended refusal, cherry-pick completion evidence, PR dry-run immutability, tracking/report gates, post-run invariants, no-progress blocking, stale worktree refusal, dirty artifact blocking, missing report/verifier markers, nonzero child exit, and timeout/idle-timeout stops.
- Run or refresh the broader Codex canary parity checklist: direct refusal/protection, cherry-pick landing, PR mode dry run, chunked
finish, tracking marker enforcement, report landing, final verification, CI fix cycle where feasible, and at least one failure-injection stop.
- Report changed skills, distribution commit, upstream provenance commit if changed, compatibility risks, runner canary result, broader canary result, and whether Codex should be restarted.
Project Setup Checks
When adapting a project to use Z Skills, ensure .zskills/tracking/ is ignored by git. Tracking markers are runtime gates, not source artifacts. Reports under reports/ are project artifacts unless the repository uses a different report convention.
Treat support scripts as Codex-native only after inspection confirms they do not require Claude hooks or .claude runtime state. Archive Claude-only behavior in references instead of exposing it as active Codex behavior.
The installed external runner is Codex-native support code, not upstream Claude runtime. When upstream refreshes support assets, preserve .agents/zskills-support/scripts/zskills-runner.sh or $CODEX_HOME/zskills-support/scripts/zskills-runner.sh and its tests unless deliberately updating them with equivalent or stronger canary coverage.
Do Not
Do not copy upstream update-zskills instructions directly into active Codex behavior. Do not create .claude project config for Codex unless the user explicitly wants legacy compatibility files.
Preserved Z Skills Invariants
- Preserve distribution provenance and commit ID.
- Preserve upstream Claude Z Skills provenance in archived references.
- Keep archived upstream references diffable.
- Refresh support assets without making Claude hooks active Codex runtime.
- Tell the user to restart Codex when skill metadata changes.
