Codex Skills

Personal Codex skills, custom agents, and global instructions tracked in Git.

This repository is the source of truth for:

custom skills;
custom agents;
global AGENTS.md.

Installation

Clone the repository:

mkdir -p ~/workspace

git clone git@github.com:rphlmr/codex.git ~/workspace/codex
cd ~/workspace/codex

Make the management scripts executable:

chmod +x sync-skills.sh sync-agents-md.sh update-config.sh

Preview the recommended Codex configuration, then consent to applying it:

./update-config.sh

The updater uses a pinned TOML patcher through npx, preserves existing values and formatting, displays an exact diff, and changes ~/.codex/config.toml only after an interactive confirmation. If the file already exists, it also creates a timestamped backup. Run ./update-config.sh --dry-run to preview without being prompted. After applying changes, restart Codex to ensure the new settings are loaded.

Synchronize skills, custom agents, and global instructions:

./sync-skills.sh
./sync-agents-md.sh

The resulting layout is:

                   Git repository
                         │
                  ~/workspace/codex
                         │
          ┌──────────────┼──────────────┐
          │              │              │
       skills/         agents/       AGENTS.md
          │              │              │
         copy           copy            copy
          │              │              │
          ▼              ▼              ▼
~/.codex/skills/* ~/.codex/agents/* ~/.codex/AGENTS.md

Important

Codex configuration

The verifier custom agent requires a permission profile named workspace-safe. Define [permissions.workspace-safe] in ~/.codex/config.toml before using $verify-implementation; custom permission profile names must have a matching table. The updater above can add missing recommendations without replacing machine-specific choices.

The example below provides the required profile plus optional companion defaults for models, agents, features, and top-level permissions.

It configures:

GPT-6 Astra with medium reasoning as the primary model;
GPT-5.6 Luna with xhigh reasoning as the default subagent;
approval prompts disabled;
workspace-scoped permissions;
protection for common secret and credential files;
network access restricted to explicitly allowed development domains;

#:schema https://developers.openai.com/codex/config-schema.json

model = "gpt-6-astra"
model_reasoning_effort = "medium"
personality = "pragmatic"
approval_policy = "never"
default_permissions = "workspace-safe"

[agents]
default_subagent_model = "gpt-5.6-luna"
default_subagent_reasoning_effort = "xhigh"

[features]
network_proxy = true
js_repl = false
prevent_idle_sleep = true

[permissions.workspace-safe]
extends = ":workspace"

[permissions.workspace-safe.filesystem.":workspace_roots"]
"**/.env.p*" = "deny"
"**/.env.s*" = "deny"
"**/.env.d*" = "deny"

# Private keys / certificates
"**/*.key" = "deny"
"**/*.pem" = "deny"
"**/*.p12" = "deny"
"**/*.pfx" = "deny"
"**/*.jks" = "deny"
"**/*.keystore" = "deny"

# SSH material accidentally stored in a repo
"**/id_rsa" = "deny"
"**/id_ed25519" = "deny"
"**/id_ecdsa" = "deny"
"**/id_dsa" = "deny"

# Common secret directories
"**/.ssh/**" = "deny"
"**/certs/**" = "deny"
"**/certificates/**" = "deny"
"**/secrets/**" = "deny"

[permissions.workspace-safe.network]
enabled = true
allow_local_binding = true

[permissions.workspace-safe.network.domains]
"localhost" = "allow"
"127.0.0.1" = "allow"

# npm / Yarn / pnpm / Bun / Deno npm: imports
"**.npmjs.org" = "allow"

# Pull-request package previews
"pkg.pr.new" = "allow"
"**.pkg.pr.new" = "allow"

# Deno / JSR packages
"**.jsr.io" = "allow"

# Node distributions / tooling that downloads Node
"**.nodejs.org" = "allow"

# Bun installer / Bun binaries
"**.bun.sh" = "allow"

# Playwright browser downloads
"**.playwright.dev" = "allow"

# Chromium / browser artifacts used by some tooling
"**.googleapis.com" = "allow"

"github.com" = "allow"
"**.github.com" = "allow"
"**.githubusercontent.com" = "allow"

"gitlab.com" = "allow"
"**.gitlab.com" = "allow"
"**.gitlab.io" = "allow"

"pypi.org" = "allow"
"**.pypi.org" = "allow"
"files.pythonhosted.org" = "allow"

Restart Codex after changing the configuration to ensure all new settings, including permission profiles, are loaded. With approval_policy = "never", a missing domain or filesystem permission fails immediately instead of presenting an approval prompt.

The complete example is also stored in recommended-config.toml, which is the updater's source configuration.

Repository structure

.
├── AGENTS.md
├── agents/
│   ├── commit-message.toml
│   ├── future-architect.toml
│   ├── implementer.toml
│   ├── light-implementer.toml
│   ├── pr-changelog.toml
│   └── verifier.toml
├── skills/
│   ├── commit-message/
│   │   ├── SKILL.md
│   │   └── agents/
│   │       └── openai.yaml
│   ├── final-implementation-plan/
│   ├── future-architect-mode/
│   ├── implement-plan/
│   ├── pr-changelog/
│   ├── session-handoff/
│   └── verify-implementation/
├── scripts/
│   └── update-config.mjs
├── recommended-config.toml
├── update-config.sh
├── sync-skills.sh
├── sync-agents-md.sh
└── README.md

Included workflows

Skill	Purpose	Custom agent
`commit-message`	Generate one Conventional Commit message from the staged diff.	`commit_message`
`final-implementation-plan`	Finalize a completed Plan mode result into a self-contained implementation handoff.	None
`future-architect-mode`	Independently review an idea, design, architecture, or implementation plan.	`future_architect`
`implement-plan`	Execute a complete approved plan with one implementation agent.	Routes contract-heavy work to `implementer`; narrow mechanical work to `light_implementer`
`pr-changelog`	Generate PR/MR text, review prep, release notes, or a changelog from committed branch changes.	`pr_changelog`
`session-handoff`	Create a self-contained prompt for continuing established work in a fresh Codex session.	None
`verify-implementation`	Independently verify completed work against the approved plan and acceptance criteria.	`verifier`

The repository provides these custom agents:

Definition	Agent name	Model and reasoning	Permissions
`agents/commit-message.toml`	`commit_message`	GPT-5.6 Luna, low	Read-only
`agents/future-architect.toml`	`future_architect`	GPT-5.6 Sol, medium	Read-only
`agents/implementer.toml`	`implementer`	GPT-5.6 Sol, medium	Inherits the invoking workspace permissions
`agents/light-implementer.toml`	`light_implementer`	GPT-5.6 Luna, xhigh	Inherits the invoking workspace permissions
`agents/pr-changelog.toml`	`pr_changelog`	GPT-5.6 Luna, medium	Read-only
`agents/verifier.toml`	`verifier`	GPT-5.6 Sol, medium	`workspace-safe`

The main execution roles use model-agnostic identifiers: implementer and verifier. Their configured model is GPT-5.6 Sol. light_implementer uses GPT-5.6 Luna for narrow mechanical tasks.

GPT-6 Astra migration

Reviewed against OpenAI's GPT-6 Astra guidance on September 5, 2026. The Codex configuration reference and custom-agent documentation define the configuration fields and per-agent model overrides used here.

Model settings

The recommended primary model is gpt-6-astra with medium reasoning. The architecture advisor, contract-heavy implementer, and independent verifier remain on gpt-5.6-sol with medium reasoning. Luna handles mechanical implementation and text workflows. These per-agent choices are independent of the primary model and are preserved by the prompt cleanup.

OpenAI currently positions Astra as the flagship model for complex reasoning and coding, Terra as the balanced intelligence/cost tier, and Luna as the cost-sensitive, high-volume tier. There is no separate Astra light model, so this setup keeps Luna for the intentionally cheaper mechanical path instead of using Astra at a lower reasoning effort.

These are Codex configuration files, not a Responses API client. API features such as async tool definitions and configuration_update input items are not new TOML settings to add here. Permission profiles, network restrictions, and approval policy remain unchanged.

Existing installations

update-config.sh adds missing settings but deliberately preserves existing values. Running it does not replace an existing primary model selection.

Confirm that GPT-6 Astra is available in your Codex account and installation. Keep a backup of ~/.codex/config.toml, then change its existing top-level model value to "gpt-6-astra". Keep model_reasoning_effort = "medium" for these defaults; do not append a duplicate key. Check any selected profile or command-line model override as well.
After pulling this revision, run ./sync-skills.sh and ./sync-agents-md.sh from this repository. The first command updates the custom-agent files and removes the retired sol-implementer.toml and sol-verifier.toml copies from ~/.codex/agents.
Restart Codex and confirm the active model. The sync scripts do not modify your main configuration, and changing only its model does not replace a custom agent's explicit model selection.

Prompt and skill maintenance

Reviewed against Rethinking skills and prompts for GPT-6 Astra on September 12, 2026. Keep skill descriptions focused on selection, shared instructions on meaningful constraints, and conditional detail in references loaded only when needed. Preserve the contracts needed by the Sol and Luna agents as well as the primary Astra session.

This pass shortens skill descriptions, consolidates repeated instructions, and moves verification failure routing into a conditional reference. It preserves invocation policies, agent assignments, approval boundaries, and output contracts. Structural validation checks packaging; it does not establish model quality or latency improvements. The representative tasks below remain manual behavioral checks.

Workflow adjustments

Global instructions distinguish already-authorized actions from decisions that still need approval, make skill conflicts traceable, and bound validation by acceptance criteria and concrete evidence. They also specify concise writing and explicit delegation boundaries. The one-executor implementation workflow and opt-in, advisory architecture review remain intact.

After migration, use representative tasks to check behavior: a review-only request must not edit files; $implement-plan must use its single selected executor; required validation must finish without unrelated repeated suites; and a request to create a PR must not stop for duplicate authorization or merge it without permission. These are manual acceptance checks, not automated model evaluation results.

Source of truth

Always edit files in this repository.

Canonical paths:

~/workspace/codex/AGENTS.md
~/workspace/codex/agents/*
~/workspace/codex/skills/*

The copies under ~/.codex are generated from this repository and should not be treated as canonical.

What is synchronized

Skills

Repository skills live under:

./skills/

sync-skills.sh copies them into:

~/.codex/skills/

Example:

~/workspace/codex/skills/commit-message
        ↓ copy
~/.codex/skills/commit-message

Only skills present in this repository are replaced.

Codex-managed content such as:

~/.codex/skills/.system

is left untouched.

Custom agents

Custom agent definitions live under:

./agents/

sync-skills.sh also copies them into:

~/.codex/agents/

Example:

~/workspace/codex/agents/verifier.toml
        ↓ copy
~/.codex/agents/verifier.toml

Global `AGENTS.md`

The canonical global instructions live at:

./AGENTS.md

sync-agents-md.sh copies them into:

~/.codex/AGENTS.md

`sync-skills.sh`

sync-skills.sh synchronizes both:

skills/* → ~/.codex/skills/*
agents/* → ~/.codex/agents/*

It copies files and directories rather than using symlinks.

This means Codex always works with normal local files under ~/.codex.

Behavior

The script:

resolves the repository directory;
creates ~/.codex/skills if necessary;
creates ~/.codex/agents if necessary;
copies every repository skill into ~/.codex/skills;
removes retired repository-managed agent filenames;
copies every repository custom agent into ~/.codex/agents;
replaces only entries whose names exist in this repository;
leaves unrelated Codex files untouched.

For example, if the repository contains:

skills/commit-message
skills/pr-changelog

the script may replace:

~/.codex/skills/commit-message
~/.codex/skills/pr-changelog

but it does not remove:

~/.codex/skills/.system

or other unrelated entries.

`sync-agents-md.sh`

sync-agents-md.sh synchronizes:

./AGENTS.md
        ↓
~/.codex/AGENTS.md

The script copies only when the contents differ.

Typical workflow

Update a skill

Edit the repository version:

$EDITOR skills/commit-message/SKILL.md

Then synchronize:

./sync-skills.sh

Review and commit:

git diff
git add skills/commit-message
git commit

Update a custom agent

Edit:

$EDITOR agents/verifier.toml

Synchronize:

./sync-skills.sh

Then commit:

git diff
git add agents/verifier.toml
git commit

Update global instructions

Edit:

$EDITOR AGENTS.md

Synchronize:

./sync-agents-md.sh

Then commit:

git diff
git add AGENTS.md
git commit

Adding a new skill

Create a new directory under:

skills/

For example:

skills/future-architect-mode/
├── SKILL.md
└── agents/
    └── openai.yaml

Then run:

./sync-skills.sh

The skill is copied to:

~/.codex/skills/future-architect-mode

Commit it:

git add skills/future-architect-mode
git commit

Adding a new custom agent

Create:

agents/new-agent.toml

Then run:

./sync-skills.sh

The agent is copied to:

~/.codex/agents/new-agent.toml

Commit it:

git add agents/new-agent.toml
git commit

Updating another machine

Record the current revision and pull the latest changes:

cd ~/workspace/codex
previous_revision="$(git rev-parse HEAD)"
git pull --ff-only

Review the release notes and the commits received by the pull:

cat CHANGELOG.md
git log --oneline "$previous_revision..HEAD"
git diff --stat "$previous_revision..HEAD"

Then synchronize:

./sync-skills.sh
./sync-agents-md.sh

Run the review commands before performing another Git operation that changes HEAD. If the pull reports that the repository is already up to date, the log and diff are empty.

Versioning and releases

Releases are automated by Release Please. It uses Conventional Commits merged into main to maintain CHANGELOG.md, update version.txt, propose the next Semantic Version, create the Git tag, and publish the GitHub Release.

Use these commit types for user-visible changes:

fix: proposes a patch release;
feat: proposes a minor release;
feat!: or a BREAKING CHANGE: footer proposes a breaking release.

Before v1.0.0, breaking changes increment the minor version. Other commit types, such as docs:, test:, and chore:, do not trigger a release by themselves.

Do not edit release entries in CHANGELOG.md or versions in version.txt manually. Release Please owns both files.

Automated release flow

Merge one or more Conventional Commits into main.
The Release Please GitHub Actions workflow opens or updates a release PR.
Review the proposed version and generated changelog in that PR.
Merge the release PR when the changes should be published.
The workflow creates the vX.Y.Z tag and corresponding GitHub Release.

The repository is bootstrapped at 0.0.0, so the first merged feat: change proposes v0.1.0.

One-time GitHub configuration

In the repository, open Settings → Actions → General. Under Workflow permissions, enable Read and write permissions and allow GitHub Actions to create pull requests. The workflow uses the repository-provided GITHUB_TOKEN; no custom secret is required.

If branch or tag protection rules are enabled, they must also allow the GitHub Actions bot to create the release PR and version tag.

New machine

The installation procedure is the same as the initial setup.

Clone the repository:

mkdir -p ~/workspace

git clone git@github.com:rphlmr/codex.git ~/workspace/codex
cd ~/workspace/codex

Make the scripts executable:

chmod +x sync-skills.sh sync-agents-md.sh update-config.sh

Then synchronize:

./sync-skills.sh
./sync-agents-md.sh

Copy semantics

Synchronization is intentionally one-way:

repository
    ↓
~/.codex

Changes made directly under:

~/.codex/skills
~/.codex/agents
~/.codex/AGENTS.md

may be overwritten the next time the corresponding sync script runs.

If you modify something directly under ~/.codex and want to keep it, copy the change back into the repository before synchronizing again.

Repository scope

This repository manages:

~/.codex/AGENTS.md
~/.codex/agents/*
~/.codex/skills/*

The interactive updater can merge missing recommendations into:

~/.codex/config.toml

Existing configuration values remain authoritative, so the optional companion configuration can still be maintained independently per machine. Unlike the one-way synchronization scripts, update-config.sh previews its changes and requires consent before writing.

Navigation Menu

Repository files navigation

Codex Skills

Installation

Codex configuration

Repository structure

Included workflows

GPT-6 Astra migration

Model settings

Existing installations

Prompt and skill maintenance

Workflow adjustments

Source of truth

What is synchronized

Skills

Custom agents

Global `AGENTS.md`

`sync-skills.sh`

Behavior

`sync-agents-md.sh`

Typical workflow

Update a skill

Update a custom agent

Update global instructions

Adding a new skill

Adding a new custom agent

Updating another machine

Versioning and releases

Automated release flow

One-time GitHub configuration

New machine

Copy semantics

Repository scope

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.agents/skills/release-commit-message		.agents/skills/release-commit-message
.github/workflows		.github/workflows
agents		agents
scripts		scripts
skills		skills
.gitignore		.gitignore
.release-please-manifest.json		.release-please-manifest.json
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
README.md		README.md
recommended-config.toml		recommended-config.toml
release-please-config.json		release-please-config.json
sync-agents-md.sh		sync-agents-md.sh
sync-skills.sh		sync-skills.sh
update-config.sh		update-config.sh
version.txt		version.txt

Latest commit

History

Folders and files

Repository files navigation

Codex Skills

Installation

Codex configuration

Repository structure

Included workflows

GPT-6 Astra migration

Model settings

Existing installations

Prompt and skill maintenance

Workflow adjustments

Source of truth

What is synchronized

Skills

Custom agents

Global AGENTS.md

sync-skills.sh

Behavior

sync-agents-md.sh

Typical workflow

Update a skill

Update a custom agent

Update global instructions

Adding a new skill

Adding a new custom agent

Updating another machine

Versioning and releases

Automated release flow

One-time GitHub configuration

New machine

Copy semantics

Repository scope

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Global `AGENTS.md`

`sync-skills.sh`

`sync-agents-md.sh`