Skip to content
BranchesTags

Repository files navigation

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 sol_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-5.6 Sol with medium reasoning as the primary model;
  • GPT-5.6 Luna with xhigh reasoning as the default subagent;
  • automatic approvals 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-5.6-sol"
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
│   ├── luna-implementer.toml
│   ├── pr-changelog.toml
│   ├── sol-implementer.toml
│   └── sol-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 sol_implementer; narrow mechanical work to luna_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. sol_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/luna-implementer.toml luna_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/sol-implementer.toml sol_implementer GPT-5.6 Sol, medium Inherits the invoking workspace permissions
agents/sol-verifier.toml sol_verifier GPT-5.6 Sol, medium workspace-safe

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/sol-verifier.toml
        ↓ copy
~/.codex/agents/sol-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:

  1. resolves the repository directory;
  2. creates ~/.codex/skills if necessary;
  3. creates ~/.codex/agents if necessary;
  4. copies every repository skill into ~/.codex/skills;
  5. copies every repository custom agent into ~/.codex/agents;
  6. replaces only entries whose names exist in this repository;
  7. 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/sol-verifier.toml

Synchronize:

./sync-skills.sh

Then commit:

git diff
git add agents/sol-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

  1. Merge one or more Conventional Commits into main.
  2. The Release Please GitHub Actions workflow opens or updates a release PR.
  3. Review the proposed version and generated changelog in that PR.
  4. Merge the release PR when the changes should be published.
  5. 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.

About

My Codex skills, custom agents and agents.md

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages