Split DeveloperInstructions into individual fragments. (#18813)

Split DeveloperInstructions into individual fragments.

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:"));
     }
 }