codex-skills-kit

A reliability toolkit for serious OpenAI Codex work, shipped as a plugin and portable [Agent Skills](https://developers.openai.com/codex/skills).

Most prompt libraries stop at prompt. Real agent failures happen later: wrong worktree, shared index contamination, checks that never caught anything, build results presented as runtime proof, and finished sessions stranded on one disk.

This kit packages a production-tested operating loop for Codex:

prompt → isolate → execute → gate → verify → close → distill ↺

Each workflow lives in focused SKILL.md, loads through progressive disclosure, and carries only rules another Codex run needs to do work.

Skills

Together they cover work before, during, and after code generation.

codex-prompt task contract is checked into task-types.json. It maps every supported type to skill section, prompt template, worked example, and golden fixture under fixtures/golden-prompts/. CI catches drift between methodology and prompts users copy.

What changed in v0.3

v0.2 introduced task registry and golden prompt fixtures. v0.3 adds four reliability layers distilled from sustained production work:

• Execution context is part of proof. Local is not production, mock data is not live data, and build success is not browser pass.
• A gate must prove it can fail. Persistent checks ship known-bad fixture, known-good twin, and repeatable selftest.
• Shared Git state is contested state. Exact path staging, worktree isolation, remote durability, and explicit ownership replace cleanup-by-instinct.
• Closeout is an engineering phase. Docs, generated artifacts, evidence, commits, pushes, and residual risk are reconciled before session disappears.
• Retros update smallest authoritative artifact. Repeated workflow knowledge belongs in skills or executable gates, not ever-growing passive notes.

Project names, private infrastructure, and domain-specific rules were removed. Methods remain.

Install

Plugin package

Recommended path bundles all six skills:

codex plugin marketplace add TAKEOFF69/codex-skills-kit

Open /plugins, switch to Codex Skills Kit marketplace, install Codex Skills Kit, and start a new thread so Codex loads updated bundle.

For local clone:

codex plugin marketplace add ./path/to/codex-skills-kit

Individual skills

Install any skill directly from GitHub tree URL:

$skill-installer install https://github.com/TAKEOFF69/codex-skills-kit/tree/main/skills/codex-prompt
$skill-installer install https://github.com/TAKEOFF69/codex-skills-kit/tree/main/skills/git-under-contention
$skill-installer install https://github.com/TAKEOFF69/codex-skills-kit/tree/main/skills/gate-engineering
$skill-installer install https://github.com/TAKEOFF69/codex-skills-kit/tree/main/skills/verify-honestly
$skill-installer install https://github.com/TAKEOFF69/codex-skills-kit/tree/main/skills/session-close
$skill-installer install https://github.com/TAKEOFF69/codex-skills-kit/tree/main/skills/retro-distill

Or clone and copy selected folders into supported scope:

• Repo-scoped: ./.agents/skills/
• User-scoped: $HOME/.agents/skills/
• Installer default: $CODEX_HOME/skills, normally $HOME/.codex/skills

git clone https://github.com/TAKEOFF69/codex-skills-kit
cp -r codex-skills-kit/skills/verify-honestly .agents/skills/

Trigger skills implicitly with matching request or explicitly with $skill-name.

Core methodology

1. Define destination

Every delegated task starts with:

Goal: <what changes>
Success means: <observable criteria>
Stop when: <completion or safe stop condition>

Then it adds context, constraints, assumptions, invariant, risk gate, repository mismatch handling, and exact done-when evidence.

2. Preserve execution state

Parallel agents cannot treat checkout as private workspace. git-under-contention detects deterministic contention signals and enforces explicit ownership:

python skills/git-under-contention/scripts/contention_preflight.py --selftest
python skills/git-under-contention/scripts/contention_preflight.py --mine skills/my-skill

3. Make quality nets prove themselves

gate-engineering separates ordinary feature tests from standing repository gates:

seeded defect → observed red → fixed twin → observed green → corpus run

It also checks empty-set traps, mutable snapshots, read-path bypasses, and stale baselines.

4. Bound claims by evidence

verify-honestly uses five named levels:

code read → local tests → browser pass → live data check → production smoke

Highest applicable level is reported per shipped item with anything still deploy-gated or inaccessible.

5. Leave work durable and improve loop

session-close reconciles state, documentation, generated artifacts, verification, commits, pushes, and handoff. retro-distill promotes supported lessons into right active surface: prompt skill, workflow skill, executable gate, AGENTS.md, or project memory.

codex-prompt task types

See examples/ for full prompts on fictional Acme Notes project.

Repository structure

codex-skills-kit/
├── .codex-plugin/plugin.json
├── .agents/plugins/marketplace.json
├── AGENTS.md
├── skills/
│   ├── codex-prompt/
│   ├── gate-engineering/
│   ├── git-under-contention/
│   ├── retro-distill/
│   ├── session-close/
│   └── verify-honestly/
├── examples/
├── fixtures/golden-prompts/
├── task-types.json
├── scripts/validate_skills.py
├── CHANGELOG.md
└── .github/workflows/validate-skills.yml

Validate

python scripts/validate_skills.py --selftest
python scripts/validate_skills.py
python skills/git-under-contention/scripts/contention_preflight.py --selftest

Contributing

Contributions should prevent observed failure classes, remain project-neutral, and keep skill bodies concise. Validator covers skills, plugin metadata, task registry, golden fixtures, release metadata, links, and secret patterns. See CONTRIBUTING.md and AGENTS.md.

License

• Code and scripts: MIT
• Skill, example, and fixture content: CC BY 4.0

Use it, fork it, and adapt it to your stack. Attribution appreciated.