Agent skill

codex-setup

Initialize sd0x-dev-flow infrastructure for Codex CLI and other non-Claude agents. Generates AGENTS.md, installs git hooks, copies runner scripts. Use when setting up a new project or after updating skills.

View SKILL.md on GitHub Repository
Stars 139
Forks 18

Install this agent skill to your Project

npx add-skill https://github.com/sd0xdev/sd0x-dev-flow/tree/main/skills/codex-setup

SKILL.md

Codex Setup

Trigger

  • Keywords: codex setup, codex init, agents.md, setup codex, initialize codex, codex doctor, codex sync
  • After: npx skills add sd0xdev/sd0x-dev-flow

Subcommands

Command Purpose
init First-time setup: generate AGENTS.md + install hooks + copy scripts
doctor Verify installation integrity (files exist + hash match)
sync Re-generate AGENTS.md + update hooks/scripts after skill update

Default (no subcommand): init

init

Phase 1: Detect Host Context

  1. Find repo root: git rev-parse --show-toplevel
  2. Read package.json if present → extract name, scripts.test
  3. Read .claude/CLAUDE.md or CLAUDE.md → extract test command pattern
  4. Detect plugin root: find scripts/build-codex-artifacts.js relative to this skill

Phase 2: Generate AGENTS.md Kernel

bash
node <plugin-root>/scripts/build-codex-artifacts.js \
  --project-dir <repo-root> \
  --output <repo-root>/AGENTS.md

If the file already exists, warn and ask before overwriting.

Verify output:

  • File exists and is non-empty
  • Size ≤ 24 KiB (wc -c < AGENTS.md ≤ 24576)
  • No unresolved placeholders ({PROJECT_NAME}, {VERSION}, {TEST_COMMAND})

Phase 3: Multi-Mode Hook Install

Install commit-msg and pre-push git hooks using priority-ordered detection:

Priority Condition Action
1 .husky/ directory exists Append sourcing to Husky hooks
2 git config core.hooksPath is set Install to that path
3 .git/hooks/ is writable Direct write
4 Fallback Write to .githooks/ + print git config core.hooksPath .githooks

Source scripts from plugin:

  • commit-msg-guard.sh → commit-msg hook
  • pre-push-gate.sh → pre-push hook

Phase 4: Copy Runner Scripts

Copy these scripts to the host project:

Source Target
scripts/precommit-runner.js .sd0x/scripts/precommit-runner.js
scripts/verify-runner.js .sd0x/scripts/verify-runner.js
scripts/lib/utils.js .sd0x/scripts/lib/utils.js

Ensure target directories exist (mkdir -p).

Phase 5: Write State File

Write .sd0x/install-state.json to repo root:

json
{
  "sd0x_version": "<from plugin.json>",
  "agents_md_hash": "<git hash-object AGENTS.md>",
  "agents_md_size": <bytes>,
  "hooks_installed": {
    "commit-msg": { "hash": "<sha1>", "mode": "<husky|hooksPath|direct|fallback>" },
    "pre-push": { "hash": "<sha1>", "mode": "<mode>" }
  },
  "scripts_installed": {
    "precommit-runner.js": "<sha1>",
    "verify-runner.js": "<sha1>"
  },
  "generated_at": "<ISO8601>"
}

Sandbox Adaptation

Codex sandbox Behavior
workspace-write / danger-full-access Execute all phases automatically
read-only Output command list for manual execution

Detect sandbox: if mkdir -p or file write fails, switch to read-only output mode.

doctor

Checks

Check Method Pass Fail
AGENTS.md exists test -f AGENTS.md File found Missing
AGENTS.md hash match Compare git hash-object vs state file Match Drift detected
AGENTS.md size ≤ 24 KiB wc -c ≤ 24576 Oversized
Hooks installed Check hook files exist in detected mode Present Missing
Scripts installed Check .sd0x/scripts/ files exist Present Missing
Version match Compare state sd0x_version vs current plugin Match Update available

Output a summary table with pass/fail status for each check.

sync

  1. Re-run build-codex-artifacts.js → overwrite AGENTS.md
  2. Re-copy hook scripts (overwrite if changed)
  3. Re-copy runner scripts (overwrite if changed)
  4. Update .sd0x/install-state.json with new hashes

References

  • references/agents-kernel.md — AGENTS.md kernel template

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

sd0xdev/sd0x-dev-flow

runbook

Generate and update feature release runbooks from existing docs and codebase. Use when: creating operational runbook, release handbook, deployment checklist, pre-release preparation. Not for: incident response (v2), code review (use codex-code-review), architecture design (use architecture).

139 18
Explore
sd0xdev/sd0x-dev-flow

ask

Context-aware Q&A with auto context gathering. Use when: user has a quick question about codebase, git history, rules, docs, or skills during development. Not for: code changes (use feature-dev), code review (use codex-review-fast), deep research (use deep-research), full code trace (use code-explore). Output: structured answer with source attribution.

139 18
Explore
sd0xdev/sd0x-dev-flow

project-brief

Convert a technical spec into a PM/CTO-readable executive summary. Simplify technical details, focus on business value.

139 18
Explore
sd0xdev/sd0x-dev-flow

codex-test-gen

Generate unit tests for specified functions using Codex MCP

139 18
Explore
sd0xdev/sd0x-dev-flow

bug-fix

Bug fix workflow. Use when: fixing bugs, resolving issues, regression fixes. Not for: new features (use feature-dev), understanding code (use code-explore). Output: fix + regression test + review gate.

139 18
Explore
sd0xdev/sd0x-dev-flow

skill-health-check

Validate skill quality against routing, progressive loading, and verification criteria. Use when: auditing skills, checking skill health, reviewing skill design. Not for: code review (use codex-code-review) or doc review (use doc-review). Output: health report with per-skill ratings + Gate.

139 18
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results