concepts/customization.md Codex Docs, 2026-05-02 06:45 UTC → 2026-05-14 07:00 UTC

42Codex can load guidance from multiple locations: a global file in your Codex home directory (for you as a developer) and repo-specific files that teams can check in. Files closer to the working directory take precedence.42Codex can load guidance from multiple locations: a global file in your Codex home directory (for you as a developer) and repo-specific files that teams can check in. Files closer to the working directory take precedence.

43Use the global file to shape how Codex communicates with you (for example, review style, verbosity, and defaults), and keep repo files focused on team and codebase rules.43Use the global file to shape how Codex communicates with you (for example, review style, verbosity, and defaults), and keep repo files focused on team and codebase rules.

44 44 

45- ~/.codex/45<FileTree

46 46 class="mt-4"

47 - AGENTS.md Global (for you as a developer)47 tree={[

48- repo-root/48 {

49 49 name: "~/.codex/",

50 - AGENTS.md repo-specific (for your team)50 open: true,

51 children: [

52 { name: "AGENTS.md", comment: "Global (for you as a developer)" },

53 ],

54 },

55 {

56 name: "repo-root/",

57 open: true,

58 children: [

59 { name: "AGENTS.md", comment: "repo-specific (for your team)" },

60 ],

61 },

62 ]}

63/>

51 64 

52[Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md)65[Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md)

53 66 

65 78 

66A skill is typically a `SKILL.md` file plus optional scripts, references, and assets.79A skill is typically a `SKILL.md` file plus optional scripts, references, and assets.

67 80 

68- my-skill/81<FileTree

69 82 class="mt-4"

70 - SKILL.md Required: instructions + metadata83 tree={[

71 - scripts/ Optional: executable code84 {

72 - references/ Optional: documentation85 name: "my-skill/",

73 - assets/ Optional: templates, resources86 open: true,

87 children: [

88 { name: "SKILL.md", comment: "Required: instructions + metadata" },

89 { name: "scripts/", comment: "Optional: executable code" },

90 { name: "references/", comment: "Optional: documentation" },

91 { name: "assets/", comment: "Optional: templates, resources" },

92 ],

93 },

94 ]}

95/>

74 96 

75The skill directory can include a `scripts/` folder with CLI scripts that Codex invokes as part of the workflow (for example, seed data or run validations). When the workflow needs external systems (issue trackers, design tools, docs servers), pair the skill with [MCP](https://developers.openai.com/codex/mcp).97The skill directory can include a `scripts/` folder with CLI scripts that Codex invokes as part of the workflow (for example, seed data or run validations). When the workflow needs external systems (issue trackers, design tools, docs servers), pair the skill with [MCP](https://developers.openai.com/codex/mcp).

76 98