Split DeveloperInstructions into individual fragments.

.codex/skills/code-review-context/SKILL.md

@@ -10,3 +10,4 @@ Codex maintains a context (history of messages) that is sent to the model in inf
 3. No unbounded items - everything injected in the model context must have a bounded size and a hard cap. 
 4. No items larger than 10K tokens.
 5. Highlight new individual items that can cross >1k tokens as P0. These need an additional manual review.
+6. All injected fragments must be defined as structs in `core/context` and implement ContextualUserFragment trait

codex-rs/core-skills/src/lib.rs

@@ -22,8 +22,8 @@ pub use model::SkillLoadOutcome;
 pub use model::SkillMetadata;
 pub use model::SkillPolicy;
 pub use model::filter_skill_load_outcome_for_product;
-pub use render::RenderedSkillsSection;
+pub use render::AvailableSkills;
 pub use render::SkillMetadataBudget;
 pub use render::SkillRenderReport;
+pub use render::build_available_skills;
 pub use render::default_skill_metadata_budget;
-pub use render::render_skills_section;

codex-rs/core-skills/src/render.rs

@@ -3,8 +3,6 @@ use codex_otel::SessionTelemetry;
 use codex_otel::THREAD_SKILLS_ENABLED_TOTAL_METRIC;
 use codex_otel::THREAD_SKILLS_KEPT_TOTAL_METRIC;
 use codex_otel::THREAD_SKILLS_TRUNCATED_METRIC;
-use codex_protocol::protocol::SKILLS_INSTRUCTIONS_CLOSE_TAG;
-use codex_protocol::protocol::SKILLS_INSTRUCTIONS_OPEN_TAG;
 use codex_protocol::protocol::SkillScope;
 use codex_utils_output_truncation::approx_token_count;
 
@@ -48,8 +46,8 @@ pub enum SkillRenderSideEffects<'a> {
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub struct RenderedSkillsSection {
-    pub text: String,
+pub struct AvailableSkills {
+    pub skill_lines: Vec<String>,
     pub report: SkillRenderReport,
     pub emit_warning: bool,
 }
@@ -71,11 +69,11 @@ pub fn default_skill_metadata_budget(context_window: Option<i64>) -> SkillMetada
         ))
 }
 
-pub fn render_skills_section(
+pub fn build_available_skills(
     skills: &[SkillMetadata],
     budget: SkillMetadataBudget,
     side_effects: SkillRenderSideEffects<'_>,
-) -> Option<RenderedSkillsSection> {
+) -> Option<AvailableSkills> {
     if skills.is_empty() {
         let _ = record_skill_render_side_effects(
             side_effects,
@@ -93,39 +91,8 @@ pub fn render_skills_section(
         report.included_count,
         report.omitted_count > 0,
     );
-    let mut lines: Vec<String> = Vec::new();
-    lines.push("## Skills".to_string());
-    lines.push("A skill is a set of local instructions to follow that is stored in a `SKILL.md` file. Below is the list of skills that can be used. Each entry includes a name, description, and file path so you can open the source for full instructions when using a specific skill.".to_string());
-    lines.push("### Available skills".to_string());
-    if !skill_lines.is_empty() {
-        lines.extend(skill_lines);
-    }
-
-    lines.push("### How to use skills".to_string());
-    lines.push(
-        r###"- Discovery: The list above is the skills available in this session (name + description + file path). Skill bodies live on disk at the listed paths.
-- Trigger rules: If the user names a skill (with `$SkillName` or plain text) OR the task clearly matches a skill's description shown above, you must use that skill for that turn. Multiple mentions mean use them all. Do not carry skills across turns unless re-mentioned.
-- Missing/blocked: If a named skill isn't in the list or the path can't be read, say so briefly and continue with the best fallback.
-- How to use a skill (progressive disclosure):
-  1) After deciding to use a skill, open its `SKILL.md`. Read only enough to follow the workflow.
-  2) When `SKILL.md` references relative paths (e.g., `scripts/foo.py`), resolve them relative to the skill directory listed above first, and only consider other paths if needed.
-  3) If `SKILL.md` points to extra folders such as `references/`, load only the specific files needed for the request; don't bulk-load everything.
-  4) If `scripts/` exist, prefer running or patching them instead of retyping large code blocks.
-  5) If `assets/` or templates exist, reuse them instead of recreating from scratch.
-- Coordination and sequencing:
-  - If multiple skills apply, choose the minimal set that covers the request and state the order you'll use them.
-  - Announce which skill(s) you're using and why (one short line). If you skip an obvious skill, say why.
-- Context hygiene:
-  - Keep context small: summarize long sections instead of pasting them; only load extra files when needed.
-  - Avoid deep reference-chasing: prefer opening only files directly linked from `SKILL.md` unless you're blocked.
-  - When variants exist (frameworks, providers, domains), pick only the relevant reference file(s) and note that choice.
-- Safety and fallback: If a skill can't be applied cleanly (missing files, unclear instructions), state the issue, pick the next-best approach, and continue."###
-            .to_string(),
-    );
-
-    let body = lines.join("\n");
-    Some(RenderedSkillsSection {
-        text: format!("{SKILLS_INSTRUCTIONS_OPEN_TAG}\n{body}\n{SKILLS_INSTRUCTIONS_CLOSE_TAG}"),
+    Some(AvailableSkills {
+        skill_lines,
         report,
         emit_warning,
     })
@@ -274,7 +241,7 @@ mod tests {
             .cost(&format!("{}\n", render_skill_line(&admin)));
         let budget = SkillMetadataBudget::Characters(system_cost + admin_cost);
 
-        let rendered = render_skills_section(
+        let rendered = build_available_skills(
             &[system, user, repo, admin],
             budget,
             SkillRenderSideEffects::None,
@@ -284,10 +251,11 @@ mod tests {
         assert_eq!(rendered.report.included_count, 2);
         assert_eq!(rendered.report.omitted_count, 2);
         assert!(!rendered.emit_warning);
-        assert!(rendered.text.contains("- system-skill:"));
-        assert!(rendered.text.contains("- admin-skill:"));
-        assert!(!rendered.text.contains("- repo-skill:"));
-        assert!(!rendered.text.contains("- user-skill:"));
+        let rendered_text = rendered.skill_lines.join("\n");
+        assert!(rendered_text.contains("- system-skill:"));
+        assert!(rendered_text.contains("- admin-skill:"));
+        assert!(!rendered_text.contains("- repo-skill:"));
+        assert!(!rendered_text.contains("- user-skill:"));
     }
 
     #[test]
@@ -300,13 +268,14 @@ mod tests {
         let budget = SkillMetadataBudget::Characters(repo_cost);
 
         let rendered =
-            render_skills_section(&[oversized, repo], budget, SkillRenderSideEffects::None)
+            build_available_skills(&[oversized, repo], budget, SkillRenderSideEffects::None)
                 .expect("skills render");
 
         assert_eq!(rendered.report.included_count, 1);
         assert_eq!(rendered.report.omitted_count, 1);
         assert!(!rendered.emit_warning);
-        assert!(!rendered.text.contains("- oversized-system-skill:"));
-        assert!(rendered.text.contains("- repo-skill:"));
+        let rendered_text = rendered.skill_lines.join("\n");
+        assert!(!rendered_text.contains("- oversized-system-skill:"));
+        assert!(rendered_text.contains("- repo-skill:"));
     }
 }

codex-rs/core/src/apps/mod.rs

@@ -1,3 +1,2 @@
+#[cfg(test)]
 mod render;
-
-pub(crate) use render::render_apps_section;

codex-rs/core/src/apps/render.rs

@@ -1,22 +1,11 @@
+use crate::context::AppsInstructions;
+use crate::context::ContextualUserFragment;
 use codex_app_server_protocol::AppInfo;
-use codex_mcp::CODEX_APPS_MCP_SERVER_NAME;
 use codex_protocol::protocol::APPS_INSTRUCTIONS_CLOSE_TAG;
 use codex_protocol::protocol::APPS_INSTRUCTIONS_OPEN_TAG;
 
 pub(crate) fn render_apps_section(connectors: &[AppInfo]) -> Option<String> {
-    if !connectors
-        .iter()
-        .any(|connector| connector.is_accessible && connector.is_enabled)
-    {
-        return None;
-    }
-
-    let body = format!(
-        "## Apps (Connectors)\nApps (Connectors) can be explicitly triggered in user messages in the format `[$app-name](app://{{connector_id}})`. Apps can also be implicitly triggered as long as the context suggests usage of available apps.\nAn app is equivalent to a set of MCP tools within the `{CODEX_APPS_MCP_SERVER_NAME}` MCP.\nAn installed app's MCP tools are either provided to you already, or can be lazy-loaded through the `tool_search` tool. If `tool_search` is available, the apps that are searchable by `tools_search` will be listed by it.\nDo not additionally call list_mcp_resources or list_mcp_resource_templates for apps."
-    );
-    Some(format!(
-        "{APPS_INSTRUCTIONS_OPEN_TAG}\n{body}\n{APPS_INSTRUCTIONS_CLOSE_TAG}"
-    ))
+    AppsInstructions::from_connectors(connectors).map(|instructions| instructions.render())
 }
 
 #[cfg(test)]

codex-rs/core/src/context/approved_command_prefix_saved.rs

@@ -0,0 +1,24 @@
+use super::ContextualUserFragment;
+
+#[derive(Debug, Clone, PartialEq)]
+pub(crate) struct ApprovedCommandPrefixSaved {
+    prefixes: String,
+}
+
+impl ApprovedCommandPrefixSaved {
+    pub(crate) fn new(prefixes: impl Into<String>) -> Self {
+        Self {
+            prefixes: prefixes.into(),
+        }
+    }
+}
+
+impl ContextualUserFragment for ApprovedCommandPrefixSaved {
+    const ROLE: &'static str = "developer";
+    const START_MARKER: &'static str = "";
+    const END_MARKER: &'static str = "";
+
+    fn body(&self) -> String {
+        format!("Approved command prefix saved:\n{}", self.prefixes)
+    }
+}

codex-rs/core/src/context/apps_instructions.rs

@@ -0,0 +1,30 @@
+use codex_app_server_protocol::AppInfo;
+use codex_mcp::CODEX_APPS_MCP_SERVER_NAME;
+use codex_protocol::protocol::APPS_INSTRUCTIONS_CLOSE_TAG;
+use codex_protocol::protocol::APPS_INSTRUCTIONS_OPEN_TAG;
+
+use super::ContextualUserFragment;
+
+#[derive(Debug, Clone, PartialEq)]
+pub(crate) struct AppsInstructions;
+
+impl AppsInstructions {
+    pub(crate) fn from_connectors(connectors: &[AppInfo]) -> Option<Self> {
+        connectors
+            .iter()
+            .any(|connector| connector.is_accessible && connector.is_enabled)
+            .then_some(Self)
+    }
+}
+
+impl ContextualUserFragment for AppsInstructions {
+    const ROLE: &'static str = "developer";
+    const START_MARKER: &'static str = APPS_INSTRUCTIONS_OPEN_TAG;
+    const END_MARKER: &'static str = APPS_INSTRUCTIONS_CLOSE_TAG;
+
+    fn body(&self) -> String {
+        format!(
+            "\n## Apps (Connectors)\nApps (Connectors) can be explicitly triggered in user messages in the format `[$app-name](app://{{connector_id}})`. Apps can also be implicitly triggered as long as the context suggests usage of available apps.\nAn app is equivalent to a set of MCP tools within the `{CODEX_APPS_MCP_SERVER_NAME}` MCP.\nAn installed app's MCP tools are either provided to you already, or can be lazy-loaded through the `tool_search` tool. If `tool_search` is available, the apps that are searchable by `tools_search` will be listed by it.\nDo not additionally call list_mcp_resources or list_mcp_resource_templates for apps.\n"
+        )
+    }
+}

codex-rs/core/src/context/available_plugins_instructions.rs

@@ -0,0 +1,58 @@
+use codex_plugin::PluginCapabilitySummary;
+use codex_protocol::protocol::PLUGINS_INSTRUCTIONS_CLOSE_TAG;
+use codex_protocol::protocol::PLUGINS_INSTRUCTIONS_OPEN_TAG;
+
+use super::ContextualUserFragment;
+
+#[derive(Debug, Clone, PartialEq)]
+pub(crate) struct AvailablePluginsInstructions {
+    plugins: Vec<PluginCapabilitySummary>,
+}
+
+impl AvailablePluginsInstructions {
+    pub(crate) fn from_plugins(plugins: &[PluginCapabilitySummary]) -> Option<Self> {
+        if plugins.is_empty() {
+            return None;
+        }
+
+        Some(Self {
+            plugins: plugins.to_vec(),
+        })
+    }
+}
+
+impl ContextualUserFragment for AvailablePluginsInstructions {
+    const ROLE: &'static str = "developer";
+    const START_MARKER: &'static str = PLUGINS_INSTRUCTIONS_OPEN_TAG;
+    const END_MARKER: &'static str = PLUGINS_INSTRUCTIONS_CLOSE_TAG;
+
+    fn body(&self) -> String {
+        let mut lines = vec![
+            "## Plugins".to_string(),
+            "A plugin is a local bundle of skills, MCP servers, and apps. Below is the list of plugins that are enabled and available in this session.".to_string(),
+            "### Available plugins".to_string(),
+        ];
+
+        lines.extend(
+            self.plugins
+                .iter()
+                .map(|plugin| match plugin.description.as_deref() {
+                    Some(description) => format!("- `{}`: {description}", plugin.display_name),
+                    None => format!("- `{}`", plugin.display_name),
+                }),
+        );
+
+        lines.push("### How to use plugins".to_string());
+        lines.push(
+            r###"- Discovery: The list above is the plugins available in this session.
+- Skill naming: If a plugin contributes skills, those skill entries are prefixed with `plugin_name:` in the Skills list.
+- Trigger rules: If the user explicitly names a plugin, prefer capabilities associated with that plugin for that turn.
+- Relationship to capabilities: Plugins are not invoked directly. Use their underlying skills, MCP tools, and app tools to help solve the task.
+- Preference: When a relevant plugin is available, prefer using capabilities associated with that plugin over standalone capabilities that provide similar functionality.
+- Missing/blocked: If the user requests a plugin that is not listed above, or the plugin does not have relevant callable capabilities for the task, say so briefly and continue with the best fallback."###
+                .to_string(),
+        );
+
+        format!("\n{}\n", lines.join("\n"))
+    }
+}

codex-rs/core/src/context/available_skills_instructions.rs

@@ -0,0 +1,56 @@
+use codex_core_skills::AvailableSkills;
+use codex_protocol::protocol::SKILLS_INSTRUCTIONS_CLOSE_TAG;
+use codex_protocol::protocol::SKILLS_INSTRUCTIONS_OPEN_TAG;
+
+use super::ContextualUserFragment;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct AvailableSkillsInstructions {
+    skill_lines: Vec<String>,
+}
+
+impl From<AvailableSkills> for AvailableSkillsInstructions {
+    fn from(available_skills: AvailableSkills) -> Self {
+        Self {
+            skill_lines: available_skills.skill_lines,
+        }
+    }
+}
+
+impl ContextualUserFragment for AvailableSkillsInstructions {
+    const ROLE: &'static str = "developer";
+    const START_MARKER: &'static str = SKILLS_INSTRUCTIONS_OPEN_TAG;
+    const END_MARKER: &'static str = SKILLS_INSTRUCTIONS_CLOSE_TAG;
+
+    fn body(&self) -> String {
+        let mut lines: Vec<String> = Vec::new();
+        lines.push("## Skills".to_string());
+        lines.push("A skill is a set of local instructions to follow that is stored in a `SKILL.md` file. Below is the list of skills that can be used. Each entry includes a name, description, and file path so you can open the source for full instructions when using a specific skill.".to_string());
+        lines.push("### Available skills".to_string());
+        lines.extend(self.skill_lines.iter().cloned());
+
+        lines.push("### How to use skills".to_string());
+        lines.push(
+            r###"- Discovery: The list above is the skills available in this session (name + description + file path). Skill bodies live on disk at the listed paths.
+- Trigger rules: If the user names a skill (with `$SkillName` or plain text) OR the task clearly matches a skill's description shown above, you must use that skill for that turn. Multiple mentions mean use them all. Do not carry skills across turns unless re-mentioned.
+- Missing/blocked: If a named skill isn't in the list or the path can't be read, say so briefly and continue with the best fallback.
+- How to use a skill (progressive disclosure):
+  1) After deciding to use a skill, open its `SKILL.md`. Read only enough to follow the workflow.
+  2) When `SKILL.md` references relative paths (e.g., `scripts/foo.py`), resolve them relative to the skill directory listed above first, and only consider other paths if needed.
+  3) If `SKILL.md` points to extra folders such as `references/`, load only the specific files needed for the request; don't bulk-load everything.
+  4) If `scripts/` exist, prefer running or patching them instead of retyping large code blocks.
+  5) If `assets/` or templates exist, reuse them instead of recreating from scratch.
+- Coordination and sequencing:
+  - If multiple skills apply, choose the minimal set that covers the request and state the order you'll use them.
+  - Announce which skill(s) you're using and why (one short line). If you skip an obvious skill, say why.
+- Context hygiene:
+  - Keep context small: summarize long sections instead of pasting them; only load extra files when needed.
+  - Avoid deep reference-chasing: prefer opening only files directly linked from `SKILL.md` unless you're blocked.
+  - When variants exist (frameworks, providers, domains), pick only the relevant reference file(s) and note that choice.
+- Safety and fallback: If a skill can't be applied cleanly (missing files, unclear instructions), state the issue, pick the next-best approach, and continue."###
+                .to_string(),
+        );
+
+        format!("\n{}\n", lines.join("\n"))
+    }
+}

codex-rs/core/src/context/collaboration_mode_instructions.rs

@@ -0,0 +1,32 @@
+use super::ContextualUserFragment;
+use codex_protocol::config_types::CollaborationMode;
+use codex_protocol::protocol::COLLABORATION_MODE_CLOSE_TAG;
+use codex_protocol::protocol::COLLABORATION_MODE_OPEN_TAG;
+
+#[derive(Debug, Clone, PartialEq)]
+pub(crate) struct CollaborationModeInstructions {
+    instructions: String,
+}
+
+impl CollaborationModeInstructions {
+    pub(crate) fn from_collaboration_mode(collaboration_mode: &CollaborationMode) -> Option<Self> {
+        collaboration_mode
+            .settings
+            .developer_instructions
+            .as_ref()
+            .filter(|instructions| !instructions.is_empty())
+            .map(|instructions| Self {
+                instructions: instructions.clone(),
+            })
+    }
+}
+
+impl ContextualUserFragment for CollaborationModeInstructions {
+    const ROLE: &'static str = "developer";
+    const START_MARKER: &'static str = COLLABORATION_MODE_OPEN_TAG;
+    const END_MARKER: &'static str = COLLABORATION_MODE_CLOSE_TAG;
+
+    fn body(&self) -> String {
+        self.instructions.clone()
+    }
+}

codex-rs/core/src/context/environment_context.rs

@@ -200,7 +200,7 @@ impl ContextualUserFragment for EnvironmentContext {
             lines.extend(subagents.lines().map(|line| format!("    {line}")));
             lines.push("  </subagents>".to_string());
         }
-        format!("\n{}", lines.join("\n"))
+        format!("\n{}\n", lines.join("\n"))
     }
 }