Production-grade tutorial | Codex CLI, IDE extension, repository skills, dynamic intent recognition, lifecycle hooks, and automated validation | November 2026<\/p>\n\n\n\n
This guide covers how to create, update, deploy, and test reusable Codex Skills, including two working examples:<\/p>\n\n\n\n
refactor<\/code> \u2014 an explicitly invoked skill for safe code refactoring.<\/li>\n\n\n\ndb-performance-review<\/code> \u2014 an implicitly discoverable skill for database performance analysis, with an optional lifecycle hook for automatic file-change checks.<\/li>\n<\/ul>\n\n\n\n1. First, understand the actual Codex architecture<\/h2>\n\n\n\n
Three distinctions are essential before writing any configuration.<\/p>\n\n\n\nFeature<\/th> Correct mechanism<\/th> Invocation<\/th><\/tr> Explicit reusable skill<\/td> SKILL.md<\/code><\/td>$refactor<\/code><\/td><\/tr>Automatic intent-based skill selection<\/td> SKILL.md<\/code> description<\/td>Codex chooses a relevant skill<\/td><\/tr> Actual custom slash command<\/td> Legacy custom prompt<\/td> \/prompts:refactor<\/code><\/td><\/tr>Repository-wide instructions<\/td> AGENTS.md<\/code><\/td>Loaded as project guidance<\/td><\/tr> Deterministic event interception<\/td> Codex lifecycle hooks<\/td> Events such as PostToolUse<\/code><\/td><\/tr>Deterministic CI enforcement<\/td> GitHub Actions or other CI<\/td> Push or pull request<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\nImportant corrections to the proposed architecture:<\/p>\n\n\n\n
Codex’s documented repository skill location is .agents\/skills\/<skill-name>\/SKILL.md<\/code>, not .codex\/skills\/<\/code>. The .codex\/<\/code> directory is useful for repository-specific Codex configuration and hooks.<\/p>\n\n\n\nSkills are explicitly invoked with $skill-name<\/code>, rather than automatically becoming \/skill-name<\/code> slash commands. The \/skills<\/code> interface helps discover skills. Legacy custom prompts still provide \/prompts:name<\/code>, but that mechanism is deprecated in favor of skills.<\/p>\n\n\n\nFinally, implicit skill recognition is model-directed, not a guaranteed filesystem event listener. To guarantee a particular validation command runs after a supported edit operation, use a hook or CI pipeline rather than relying on a skill description alone. ChatGPT Learn+2<\/p>\n\n\n\n
These distinctions determine the implementation below.<\/p>\n\n\n\n
2. Directory blueprint<\/h2>\n\n\n\n
Use this structure in the root of a Git repository:<\/p>\n\n\n\n
my-project\/\n\u251c\u2500\u2500 AGENTS.md\n\u2502\n\u251c\u2500\u2500 .agents\/\n\u2502 \u2514\u2500\u2500 skills\/\n\u2502 \u251c\u2500\u2500 refactor\/\n\u2502 \u2502 \u251c\u2500\u2500 SKILL.md\n\u2502 \u2502 \u2514\u2500\u2500 agents\/\n\u2502 \u2502 \u2514\u2500\u2500 openai.yaml\n\u2502 \u2502\n\u2502 \u2514\u2500\u2500 db-performance-review\/\n\u2502 \u251c\u2500\u2500 SKILL.md\n\u2502 \u2514\u2500\u2500 agents\/\n\u2502 \u2514\u2500\u2500 openai.yaml\n\u2502\n\u251c\u2500\u2500 .codex\/\n\u2502 \u251c\u2500\u2500 hooks.json\n\u2502 \u2514\u2500\u2500 hooks\/\n\u2502 \u2514\u2500\u2500 db_performance.py\n\u2502\n\u251c\u2500\u2500 .github\/\n\u2502 \u2514\u2500\u2500 workflows\/\n\u2502 \u2514\u2500\u2500 db-performance.yml\n\u2502\n\u2514\u2500\u2500 tests\/\n \u2514\u2500\u2500 test_db_performance.py<\/code><\/pre>\n\n\n\nThere are three configuration layers to understand:<\/p>\n\n\n\nLayer<\/th> Purpose<\/th><\/tr> ~\/.codex\/AGENTS.md<\/code><\/td>Global instructions for your local Codex environment<\/td><\/tr> my-project\/AGENTS.md<\/code><\/td>Repository-specific engineering standards and conventions<\/td><\/tr> my-project\/.agents\/skills\/<\/code><\/td>Reusable skills discoverable by Codex within the repository<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\nYou can also install personal skills at ~\/.agents\/skills\/<\/code>, or organization-managed skills at \/etc\/codex\/skills\/<\/code>. Codex discovers repository skills from the current working directory up through the repository root. ChatGPT Learn+1<\/p>\n\n\n\nStandard SKILL.md<\/code> blueprint<\/h3>\n\n\n\nThe minimum valid skill uses YAML frontmatter with two required fields:<\/p>\n\n\n\n
\n---\nname: example-skill\ndescription: Describe the task this skill performs and the circumstances in which Codex should select it.\n---\n\n# Example Skill\n\n## Instructions\n\n1. Inspect the relevant project files.\n2. Identify the requested changes.\n3. Apply the required workflow.\n4. Run the appropriate validations.\n5. Report changes, results, and limitations.\n<\/code><\/pre>\n\n\n\nname<\/code> is the skill identifier. description<\/code> is its primary discovery and intent-matching metadata. Instructions in the Markdown body become relevant after the skill is selected.<\/p>\n\n\n\nFor Codex-specific presentation and invocation policy, put optional configuration in agents\/openai.yaml<\/code>, not invented frontmatter keys such as hooks<\/code>, triggers<\/code>, on_file_change<\/code>, or file_patterns<\/code>.<\/p>\n\n\n\n3. Production-ready explicit skill: $refactor<\/code><\/h2>\n\n\n\nSave this source as .agents\/skills\/refactor\/SKILL.md<\/code>.<\/p>\n\n\n\n\n---\nname: refactor\ndescription: Safely refactor existing application code while preserving externally observable behavior, public APIs, and data contracts. Use only when the user explicitly requests the $refactor workflow to improve readability, modularity, maintainability, or complexity without changing features.\n---\n\n# Behavior-Preserving Refactor\n\n## Input contract\n\nAccept a file, module, function, folder, or explicitly\nidentified code region and optional goals.\n\nIf scope is ambiguous, inspect the current changes and ask\nfor a bounded target before touching unrelated code.\n\nTreat the user's requirements as the source of truth.\n\n## Procedure\n\n1. Inspect `AGENTS.md`, nested instructions, relevant files,\n nearby tests, and `git status --short`. Leave unrelated\n work untouched.\n\n2. State a concise refactor plan: target, invariants,\n proposed changes, and verification commands.\n\n3. Identify behavior contracts: return values, errors,\n side effects, API shape, serialization, persistence,\n concurrency, performance-critical paths, and security.\n\n4. Establish a baseline by running the narrowest available\n tests. Add characterization tests when appropriate.\n\n5. Apply the smallest coherent change. Prefer named helpers,\n clearer control flow, reduced duplication, and bounded\n functions over broad rewrites.\n\n6. Do not silently add dependencies, modify database schema,\n change public APIs, or alter runtime behavior.\n\n7. Re-run targeted tests, type checks, and linters.\n Compare against the baseline where possible.\n\n8. Review `git diff --check` and `git diff` for regressions,\n unrelated edits, secrets, and formatting churn.\n\n## Safety rules\n\n- Never delete, reset, or overwrite uncommitted user work.\n- Never run destructive commands without authorization.\n- Never claim successful testing when tests were not run.\n- Separate behavior changes from behavior-preserving work.\n- Never commit or push unless explicitly requested.\n\n## Output contract\n\nReturn four sections:\n\n- Scope: what changed and why.\n- Behavior preserved: key invariants.\n- Verification: commands, results, and tests not run.\n- Risks \/ follow-ups: remaining issues.\n<\/code><\/pre>\n\n\n\nNext, save .agents\/skills\/refactor\/agents\/openai.yaml<\/code>:<\/p>\n\n\n\n\ninterface:\n display_name: \"Refactor\"\n short_description: \"Safely refactor existing code without behavior changes\"\n default_prompt: \"Use $refactor to refactor the specified files while preserving behavior and verifying tests.\"\n\npolicy:\n allow_implicit_invocation: false\n<\/code><\/pre>\n\n\n\nThe documented allow_implicit_invocation: false<\/code> policy makes the skill explicit-only while retaining $refactor<\/code> invocation. Test this behavior against your installed CLI version because some releases have had explicit-skill discovery issues. ChatGPT Learn+1<\/p>\n\n\n\nExecute it in Codex<\/h3>\n\n\n\n
From the project root:<\/p>\n\n\n\n
codex<\/code><\/pre>\n\n\n\nThen enter this in the Codex conversation:<\/p>\n\n\n\n
$refactor Refactor src\/services\/userService.ts.\n\nGoals:\n- Reduce cyclomatic complexity.\n- Extract duplicated validation logic.\n- Preserve all public APIs and return values.\n- Keep the existing error behavior.\n- Run the relevant tests.\n- Show the final diff and verification results.<\/code><\/pre>\n\n\n\nExpected behavior: Codex resolves the named skill, follows its instructions, edits only the relevant files, runs supported tests, and reports the result. The outcome still depends on available tools, approvals, and repository state.<\/p>\n\n\n\n
4. Production-ready dynamic skill: db-performance-review<\/code><\/h2>\n\n\n\nUnlike $refactor<\/code>, this skill allows implicit invocation. Codex can select it when the user’s task involves SQL queries, Prisma schemas, migrations, indexes, or ORM operations.<\/p>\n\n\n\nSave as .agents\/skills\/db-performance-review\/SKILL.md<\/code>:<\/p>\n\n\n\n\n---\nname: db-performance-review\ndescription: Review database query, SQL migration, ORM query, or schema changes for performance regressions. Use when tasks involve editing or reviewing .sql or .prisma files, database schemas, indexes, query builders, ORM repositories, or data access paths; assess query plans, indexes, cardinality, locks, and migration safety.\n---\n\n# Database Performance Review\n\n## Input contract\n\nAccept a planned or completed change to SQL queries,\nmigration files, Prisma schemas, ORM query builders,\nor data access modules.\n\nDo not treat every code edit as database work.\n\n## Procedure\n\n1. Read repository instructions, schema, and query files.\n Determine the database engine and deployment context.\n\n2. Find changed database files using `git diff --name-only`,\n `git status --short`, and the user's specified scope.\n\n3. Run the repository's static checker, when available:\n\n `python3 .codex\/hooks\/db_performance.py --check-all`\n\n Treat this as an anti-pattern scan, not a performance\n benchmark.\n\n4. Inspect filters, joins, sorting, pagination, cardinality,\n returned columns, N+1 queries, and index coverage.\n\n5. For migrations, assess lock duration, backfills,\n uniqueness constraints, transactional behavior,\n deployment compatibility, and recovery strategy.\n\n6. When an authorized non-production database is available,\n inspect representative query plans with\n `EXPLAIN (FORMAT JSON)`.\n\n7. Run `EXPLAIN ANALYZE` only when separately authorized\n and safe. Do not analyze writes against production.\n\n8. Compare actual query plans and benchmarks against\n verified baselines whenever available.\n\n9. Propose minimal fixes, verify them, and distinguish\n demonstrated improvements from hypotheses.\n\n## Safety rules\n\n- Never print database credentials or customer records.\n- Never silently connect to a production database.\n- Never execute production migrations as part of a review.\n- Never invent performance metrics.\n- Never present static heuristics as proof of query speed.\n\n## Output contract\n\nReturn:\n\n- Changed paths\n- Findings and severity\n- Index and query-plan recommendations\n- Commands executed and actual results\n- Remaining risks and next actions\n<\/code><\/pre>\n\n\n\nSave as .agents\/skills\/db-performance-review\/agents\/openai.yaml<\/code>:<\/p>\n\n\n\n\ninterface:\n display_name: \"DB Performance Review\"\n short_description: \"Check database changes for query and schema risks\"\n default_prompt: \"Use $db-performance-review to inspect the changed SQL, ORM, and schema files for performance risks.\"\n\npolicy:\n allow_implicit_invocation: true\n<\/code><\/pre>\n\n\n\nTest implicit recognition<\/h3>\n\n\n\n
Enter this in a new Codex session, without referencing the skill by name:<\/p>\n\n\n\n
I modified prisma\/schema.prisma and two SQL queries.\nReview these changes for performance regressions,\nmissing indexes, migration risks, and expensive query patterns.<\/code><\/pre>\n\n\n\nCodex should consider the database review skill because the task matches its description. Whether it selects the skill is a model decision, not a guaranteed event. ChatGPT Learn<\/p>\n\n\n\n
5. Deterministic event automation with Codex hooks<\/h2>\n\n\n\n
For the stronger requirement \u2014 run a check when Codex updates a database-related file \u2014 use PostToolUse<\/code> hooks.<\/p>\n\n\n\nThe complete starter implements this sequence:<\/p>\n\n\n\n
SessionStart<\/p>\n\n\n\n
Record SHA-256 hashes of monitored database files<\/p>\n\n\n\n
Codex edits a SQL, Prisma, or database module<\/p>\n\n\n\n
Through a supported local tool<\/p>\n\n\n\n
PostToolUse<\/p>\n\n\n\n
Compare hashes and scan changed SQL files<\/p>\n\n\n\n
No flagged patterns<\/p>\n\n\n\n
Report clean static checks<\/p>\n\n\n\n
Potential issue<\/p>\n\n\n\n
Send findings to Codex for review<\/p>\n\n\n\n
Hook registration<\/h3>\n\n\n\n
Save as .codex\/hooks.json<\/code>:<\/p>\n\n\n\n\n{\n \"description\": \"Database change detection and static performance review for Codex local sessions.\",\n \"hooks\": {\n \"SessionStart\": [\n {\n \"matcher\": \"startup|resume|clear|compact|fork\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"python3 \\\"$(git rev-parse --show-toplevel)\/.codex\/hooks\/db_performance.py\\\" --seed\",\n \"timeout\": 30,\n \"statusMessage\": \"Initializing database change detection\"\n }\n ]\n }\n ],\n \"PostToolUse\": [\n {\n \"matcher\": \"Bash|apply_patch|Edit|Write\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"python3 \\\"$(git rev-parse --show-toplevel)\/.codex\/hooks\/db_performance.py\\\" --post\",\n \"timeout\": 45,\n \"statusMessage\": \"Checking database file changes\"\n }\n ]\n }\n ]\n }\n}\n<\/code><\/pre>\n\n\n\nThe matcher identifies supported tool operations, not filenames. The accompanying Python implementation checks which database-related files actually changed and sends feedback to Codex.<\/p>\n\n\n\n
The full db_performance.py<\/code> implementation (approximately 300 lines) is included in both downloadable packages. It includes SHA-256 snapshots, session-specific state, basic concurrency protection, file classification, SQL heuristics, and CI operation.<\/p>\n\n\n\nCodex hooks support events such as SessionStart<\/code>, PreToolUse<\/code>, and PostToolUse<\/code>, with tool-specific matchers and structured responses. They require an enabled, trusted, supported runtime. They do not monitor every external filesystem write. ChatGPT Learn+2<\/p>\n\n\n\n6. Deployment, testing, and deliverables<\/h2>\n\n\n\n
Complete 2026 Codex Skills guide<\/p>\n\n\n\n
1,200+ lines of Markdown containing the complete source files, architecture, installation steps, testing matrix, and troubleshooting reference.<\/p>\n\n\n\n
Download full Markdown guide<\/p>\n\n\n\n
Deployable repository starter kit<\/p>\n\n\n\n
Both skills, metadata, AGENTS.md, hooks, Python checker, tests, CI workflow, safe installer, and the guide.<\/p>\n\n\n\n
Download repository starter ZIP<\/p>\n\n\n\n
Individually validated skill packages<\/p>\n\n\n\n
For installing just one skill instead of the whole starter repository.<\/p>\n\n\n\n
Refactor skill ZIP<\/p>\n\n\n\n
Database Performance Review skill ZIP<\/p>\n\n\n\n
Quick deployment<\/h3>\n\n\n\n
Download and extract the starter ZIP to a temporary directory. Then run the included conflict-aware installer from that directory:<\/p>\n\n\n\n
python3 scripts\/install.py --repo \/absolute\/path\/to\/my-project<\/code><\/pre>\n\n\n\nIf your repository already has AGENTS.md<\/code>, use:<\/p>\n\n\n\npython3 scripts\/install.py \\\n --repo \/absolute\/path\/to\/my-project \\\n --skip-agents<\/code><\/pre>\n\n\n\nManually merge the relevant guidance into the existing AGENTS.md<\/code>. The installer refuses to overwrite differing existing files.<\/p>\n\n\n\nVerification commands<\/h3>\n\n\n\n
Run from the target repository root:<\/p>\n\n\n\n
# Validate hook configuration\npython3 -m json.tool .codex\/hooks.json\n\n# Compile the checker\npython3 -m py_compile .codex\/hooks\/db_performance.py\n\n# Run the unit test suite\npython3 -m unittest discover -s tests -v\n\n# Static database performance scan\npython3 .codex\/hooks\/db_performance.py --check-all\n\n# Strict scan, suitable for an enforcement gate\npython3 .codex\/hooks\/db_performance.py --check-all --strict\n\n# Check repository changes\ngit diff --check\ngit status --short<\/code><\/pre>\n\n\n\nNext, start Codex:<\/p>\n\n\n\n
codex<\/code><\/pre>\n\n\n\nUse \/skills<\/code> to check discovery, \/hooks<\/code> to inspect and trust the configured lifecycle hooks, and $refactor<\/code> to test explicit invocation.<\/p>\n\n\n\nTest matrix<\/h3>\n\n\n\nTest<\/th> Expected outcome<\/th><\/tr> Explicit $refactor<\/code><\/td>Refactor skill selected<\/td><\/tr> Natural-language database performance request<\/td> DB skill considered through intent matching<\/td><\/tr> Unrelated UI edit<\/td> No database-specific skill needed<\/td><\/tr> Codex changes .sql<\/code> file<\/td>PostToolUse detects the modified file<\/td><\/tr> Codex changes .prisma<\/code> file<\/td>Schema change detected<\/td><\/tr> Codex edits unrelated file<\/td> No DB change report<\/td><\/tr> SQL contains SELECT *<\/code><\/td>Static checker reports an advisory<\/td><\/tr> Pull request introduces a flagged pattern<\/td> Strict GitHub Actions check fails<\/td><\/tr> Restart after skill update<\/td> Updated skill discoverable<\/td><\/tr> Hook not trusted<\/td> Hook execution not assumed<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\nValidation results<\/h3>\n\n\n\n
4 of 4 local tests passed<\/p>\n\n\n\n
Both skill structures validated successfully.<\/p>\n\n\n\n
The hook JSON parsed successfully, the Python checker compiled, and the ZIP archive passed its integrity check. I also tested the installer in a disposable Git repository, including its refusal to overwrite an existing modified AGENTS.md<\/code>.<\/p>\n\n\n\nRemaining runtime verification: Codex CLI is not installed in this environment, so live skill invocation, model-driven intent matching, and hook trust\/execution have not been tested here. The Markdown guide provides the exact steps to complete those tests on your machine.<\/p>\n\n\n\n
The recommended production setup is to use skills for reusable agent behavior, AGENTS.md<\/code> for project policy, trusted lifecycle hooks for immediate local feedback, and CI for independent enforcement. That gives you both the convenience of intelligent skill selection and a reliable validation layer.<\/p>\n\n\n\nBehavior-Preserving Refactor<\/p>\n\n\n\n
Safely refactor existing application code while preserving externally observable behavior, public APIs, and data contracts. Use only when the user explicitly requests the $refactor workflow to improve readability, modularity, maintainability, or complexity without changing features.<\/p>\n\n\n\n
Try in chat<\/p>\n\n\n\n
Database Performance Review<\/p>\n\n\n\n
Review database query, SQL migration, ORM query, or schema changes for performance regressions. Use when tasks involve editing or reviewing .sql or .prisma files, database schemas, indexes, query builders, ORM repositories, or data access paths; assess query plans, indexes, cardinality, locks, and migration safety.<\/p>\n\n\n\n
Try in chat<\/p>\n","protected":false},"excerpt":{"rendered":"
Production-grade tutorial | Codex CLI, IDE extension, repository skills, dynamic intent recognition, lifecycle hooks, and automated validation | November 2026 […]<\/p>\n","protected":false},"author":4,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"class_list":["post-5840","post","type-post","status-publish","format-standard","hentry","category-uncategorized"],"_links":{"self":[{"href":"https:\/\/aiopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/5840","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/aiopsschool.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/aiopsschool.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/aiopsschool.com\/blog\/wp-json\/wp\/v2\/users\/4"}],"replies":[{"embeddable":true,"href":"https:\/\/aiopsschool.com\/blog\/wp-json\/wp\/v2\/comments?post=5840"}],"version-history":[{"count":1,"href":"https:\/\/aiopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/5840\/revisions"}],"predecessor-version":[{"id":5841,"href":"https:\/\/aiopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/5840\/revisions\/5841"}],"wp:attachment":[{"href":"https:\/\/aiopsschool.com\/blog\/wp-json\/wp\/v2\/media?parent=5840"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/aiopsschool.com\/blog\/wp-json\/wp\/v2\/categories?post=5840"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/aiopsschool.com\/blog\/wp-json\/wp\/v2\/tags?post=5840"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}