Codex Team Rollout skill for Codex

A rollout is done well when a new engineer gets the same project rules, skills and safety boundaries on day one without hand-copying config, guardrails that must hold are enforced rather than suggested, and the team can show whether Codex is helping.

Three layers, three owners

Layer	Lives in	Owner	Use it for
Repository	AGENTS.md, .agents/skills/, .codex/config.toml, .codex/rules/, .codex/hooks.json, .codex/agents/*.toml, .worktreeinclude	Repo maintainers, via PR review	Commands, conventions, shared workflows, project defaults
User	~/.codex/config.toml, ~/.codex/<profile>.config.toml, ~/.codex/AGENTS.md, ~/.agents/skills/	Each engineer	Personal model, editor, notification preferences
Enforced policy	requirements.toml via Agent Security (cloud), MDM, or /etc/codex/requirements.toml	Security / platform admins	Allowed approval policies, sandbox modes, permission profiles, web search modes, MCP allowlist, managed hooks and rules

Rules of placement:

• Anything every contributor needs to work correctly goes in the repo.
• Anything that must not be overridden goes in requirements, never only in repo config (users and CLI flags override project config; requirements constrain them).
• Repo config cannot grant workspace, model or connected-system access, and project .codex/ layers load only when the developer trusts the project.
• Project config ignores provider, base-URL, notify, otel and profile keys; set those per user or by managed config.

Workflow

- [ ] 1. Pick a pilot group and 2-3 representative repos
- [ ] 2. Write the repo layer for the pilot repos
- [ ] 3. Define guardrails and deliver them as requirements
- [ ] 4. Publish onboarding (install, sign-in, trust, first task)
- [ ] 5. Run the pilot for 2-4 weeks with explicit success criteria
- [ ] 6. Fix what the pilot exposed, then scale repo by repo
- [ ] 7. Review quarterly: skills, policy, model ids, usage

2. Repo layer

Minimum per repo:

AGENTS.md                      # commands, conventions, boundaries (keep it short)
.agents/skills/<workflow>/     # 2-5 team workflows: release, migration, review checklist
.codex/config.toml             # project defaults only
.codex/rules/default.rules     # forbid/prompt rules for dangerous commands
.worktreeinclude               # ignored files managed worktrees need (no secrets you can avoid)

# .codex/config.toml — project defaults (trusted projects only)
model_reasoning_effort = "medium"
[sandbox_workspace_write]
network_access = false

[mcp_servers.issue-tracker]
url = "https://mcp.internal.example.com/mcp"
enabled_tools = ["get_issue", "search_issues"]

Review these files like code: CODEOWNERS on AGENTS.md, .agents/, .codex/.

3. Guardrails as requirements

Decide each item explicitly and record the reason:

# requirements.toml (delivered via Agent Security, MDM, or /etc/codex/requirements.toml)
allowed_approval_policies = ["on-request"]             # blocks -a never
allowed_web_search_modes = ["cached"]                  # no live browsing
default_permissions = ":workspace"

[allowed_permission_profiles]
":read-only" = true
":workspace" = true                                    # omitted profiles, incl. full access, are denied

[mcp_servers.issue-tracker]
identity = { url = "https://mcp.internal.example.com/mcp" }   # only approved MCP servers enable

Legacy deployments that still use sandbox_mode can use allowed_sandbox_modes = ["read-only", "workspace-write"]. Requirements fall back to a compatible value and notify the user when local config conflicts. Exact keys and merge behaviour: check the requirements section of the configuration reference before shipping.

Separate decisions an admin owns elsewhere: who can use Codex locally or in the cloud (workspace permissions), which plugins are allowed, cloud environments and their secrets, and login restrictions (forced_login_method, forced_chatgpt_workspace_id, managed locally).

4. Onboarding doc (template)

# Codex at <Team>
1. Install: <approved install method>; check `codex --version` >= <min version>.
2. Sign in: `codex login` with your <workspace> ChatGPT account (not a personal one).
3. Trust only repos you work on; Codex asks on first launch.
4. First task: run `codex` in <repo>, ask "Summarize the instructions you loaded".
5. Shared skills: type `$` or `/skills` to see <list>.
6. Rules: never paste production secrets; never run with --yolo outside <sandbox env>.
7. Help: #codex-help; report bad behaviour with /feedback and a session id.

5. Pilot success criteria

Define before starting, e.g.: share of merged PRs with Codex-authored commits, review rework rate on those PRs, time-to-first-PR for new hires, number of guardrail denials and their causes, usage per engineer per week (workspace analytics or the Analytics API for Enterprise), and qualitative pain points. Collect failure transcripts: they are the input for AGENTS.md fixes and new skills.

6. Scale

• Template the repo layer (a starter PR per repo), then let each repo’s owners tailor it.
• Promote a skill to an org-wide location (/etc/codex/skills on managed machines, or a plugin) only after two repos use it unchanged.
• Pin a minimum Codex version; features such as permission profiles and per-profile files depend on it.

Gotchas

• Putting a guardrail only in .codex/config.toml: a CLI flag or user config overrides it, and untrusted checkouts skip it entirely.
• A 20 KB root AGENTS.md written by committee costs every session tokens and hides the rules that matter. Cap it and move detail into nested files or skills.
• Model ids retire; a model pinned in repo config, custom agents and CI breaks on the retirement date. Track them in one place.
• Hooks and rules from the repo run on developer machines; review them with the same care as CI scripts. New or changed hooks require trust before they run.
• Plugins are not available in the IDE extension; do not make a plugin the only way to get a workflow the IDE users need.
• Measure rework, not just volume: more Codex PRs that need heavy review is not success.

Verification

• A fresh machine following the onboarding doc gets the expected /status, /skills list, /mcp tools and /debug-config layers (including requirements).
• Attempting a forbidden setting (codex -a never, --sandbox danger-full-access) falls back or is refused with a notice.
• Pilot metrics are reported against the criteria set before the pilot.