feat: experimental support for skills.md

codex-rs/Cargo.toml

@@ -178,6 +178,7 @@ seccompiler = "0.5.0"
 sentry = "0.34.0"
 serde = "1"
 serde_json = "1"
+serde_yaml = "0.9"
 serde_with = "3.16"
 serial_test = "3.2.0"
 sha1 = "0.10.6"

codex-rs/cli/src/main.rs

@@ -358,6 +358,15 @@ struct FeatureToggles {
     /// Disable a feature (repeatable). Equivalent to `-c features.<name>=false`.
     #[arg(long = "disable", value_name = "FEATURE", action = clap::ArgAction::Append, global = true)]
     disable: Vec<String>,
+
+    /// [experimental] Enable skills loading/injection.
+    #[arg(
+        long = "enable-skills",
+        default_value_t = false,
+        global = true,
+        hide = true
+    )]
+    enable_skills: bool,
 }
 
 impl FeatureToggles {
@@ -371,6 +380,9 @@ impl FeatureToggles {
             Self::validate_feature(feature)?;
             v.push(format!("features.{feature}=false"));
         }
+        if self.enable_skills {
+            v.push("features.skills=true".to_string());
+        }
         Ok(v)
     }
 
@@ -922,6 +934,7 @@ mod tests {
         let toggles = FeatureToggles {
             enable: vec!["web_search_request".to_string()],
             disable: vec!["unified_exec".to_string()],
+            enable_skills: false,
         };
         let overrides = toggles.to_overrides().expect("valid features");
         assert_eq!(
@@ -938,6 +951,7 @@ mod tests {
         let toggles = FeatureToggles {
             enable: vec!["does_not_exist".to_string()],
             disable: Vec::new(),
+            enable_skills: false,
         };
         let err = toggles
             .to_overrides()

codex-rs/core/Cargo.toml

@@ -52,6 +52,7 @@ regex-lite = { workspace = true }
 reqwest = { workspace = true, features = ["json", "stream"] }
 serde = { workspace = true, features = ["derive"] }
 serde_json = { workspace = true }
+serde_yaml = { workspace = true }
 sha1 = { workspace = true }
 sha2 = { workspace = true }
 shlex = { workspace = true }

codex-rs/core/src/features.rs

@@ -51,6 +51,8 @@ pub enum Feature {
     ShellTool,
     /// Allow model to call multiple tools in parallel (only for models supporting it).
     ParallelToolCalls,
+    /// Experimental skills injection (CLI flag-driven).
+    Skills,
 }
 
 impl Feature {
@@ -326,4 +328,10 @@ pub const FEATURES: &[FeatureSpec] = &[
         stage: Stage::Stable,
         default_enabled: true,
     },
+    FeatureSpec {
+        id: Feature::Skills,
+        key: "skills",
+        stage: Stage::Experimental,
+        default_enabled: false,
+    },
 ];

codex-rs/core/src/lib.rs

@@ -72,6 +72,7 @@ mod rollout;
 pub(crate) mod safety;
 pub mod seatbelt;
 pub mod shell;
+pub mod skills;
 pub mod spawn;
 pub mod terminal;
 mod tools;

codex-rs/core/src/project_doc.rs

@@ -14,6 +14,9 @@
 //! 3.  We do **not** walk past the Git root.
 
 use crate::config::Config;
+use crate::features::Feature;
+use crate::skills::load_skills;
+use crate::skills::render_skills_section;
 use dunce::canonicalize as normalize_path;
 use std::path::PathBuf;
 use tokio::io::AsyncReadExt;
@@ -31,18 +34,37 @@ const PROJECT_DOC_SEPARATOR: &str = "\n\n--- project-doc ---\n\n";
 /// Combines `Config::instructions` and `AGENTS.md` (if present) into a single
 /// string of instructions.
 pub(crate) async fn get_user_instructions(config: &Config) -> Option<String> {
-    match read_project_docs(config).await {
-        Ok(Some(project_doc)) => match &config.user_instructions {
-            Some(original_instructions) => Some(format!(
-                "{original_instructions}{PROJECT_DOC_SEPARATOR}{project_doc}"
-            )),
-            None => Some(project_doc),
-        },
-        Ok(None) => config.user_instructions.clone(),
+    let skills_section = if config.features.enabled(Feature::Skills) {
+        let skills_outcome = load_skills(config);
+        for err in &skills_outcome.errors {
+            error!(
+                "failed to load skill {}: {}",
+                err.path.display(),
+                err.message
+            );
+        }
+        render_skills_section(&skills_outcome.skills)
+    } else {
+        None
+    };
+
+    let project_docs = match read_project_docs(config).await {
+        Ok(docs) => docs,
         Err(e) => {
             error!("error trying to find project doc: {e:#}");
-            config.user_instructions.clone()
+            return config.user_instructions.clone();
         }
+    };
+
+    let combined_project_docs = merge_project_docs_with_skills(project_docs, skills_section);
+
+    match (config.user_instructions.clone(), combined_project_docs) {
+        (Some(instructions), Some(project_doc)) => Some(format!(
+            "{instructions}{PROJECT_DOC_SEPARATOR}{project_doc}"
+        )),
+        (Some(instructions), None) => Some(instructions),
+        (None, Some(project_doc)) => Some(project_doc),
+        (None, None) => None,
     }
 }
 
@@ -195,12 +217,25 @@ fn candidate_filenames<'a>(config: &'a Config) -> Vec<&'a str> {
     names
 }
 
+fn merge_project_docs_with_skills(
+    project_doc: Option<String>,
+    skills_section: Option<String>,
+) -> Option<String> {
+    match (project_doc, skills_section) {
+        (Some(doc), Some(skills)) => Some(format!("{doc}\n\n{skills}")),
+        (Some(doc), None) => Some(doc),
+        (None, Some(skills)) => Some(skills),
+        (None, None) => None,
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
     use crate::config::ConfigOverrides;
     use crate::config::ConfigToml;
     use std::fs;
+    use std::path::PathBuf;
     use tempfile::TempDir;
 
     /// Helper that returns a `Config` pointing at `root` and using `limit` as
@@ -219,6 +254,7 @@ mod tests {
 
         config.cwd = root.path().to_path_buf();
         config.project_doc_max_bytes = limit;
+        config.features.enable(Feature::Skills);
 
         config.user_instructions = instructions.map(ToOwned::to_owned);
         config
@@ -447,4 +483,58 @@ mod tests {
                 .eq(DEFAULT_PROJECT_DOC_FILENAME)
         );
     }
+
+    #[tokio::test]
+    async fn skills_are_appended_to_project_doc() {
+        let tmp = tempfile::tempdir().expect("tempdir");
+        fs::write(tmp.path().join("AGENTS.md"), "base doc").unwrap();
+
+        let cfg = make_config(&tmp, 4096, None);
+        create_skill(
+            cfg.codex_home.clone(),
+            "pdf-processing",
+            "extract from pdfs",
+        );
+
+        let res = get_user_instructions(&cfg)
+            .await
+            .expect("instructions expected");
+        let expected_path = dunce::canonicalize(
+            cfg.codex_home
+                .join("skills/pdf-processing/SKILL.md")
+                .as_path(),
+        )
+        .unwrap_or_else(|_| cfg.codex_home.join("skills/pdf-processing/SKILL.md"));
+        let expected_path_str = expected_path.to_string_lossy().replace('\\', "/");
+        let expected = format!(
+            "base doc\n\n## Skills\nThese skills are discovered at startup from ~/.codex/skills; each entry shows name, description, and file path so you can open the source for full instructions. Content is not inlined to keep context lean.\n- pdf-processing: extract from pdfs (file: {expected_path_str})"
+        );
+        assert_eq!(res, expected);
+    }
+
+    #[tokio::test]
+    async fn skills_render_without_project_doc() {
+        let tmp = tempfile::tempdir().expect("tempdir");
+        let cfg = make_config(&tmp, 4096, None);
+        create_skill(cfg.codex_home.clone(), "linting", "run clippy");
+
+        let res = get_user_instructions(&cfg)
+            .await
+            .expect("instructions expected");
+        let expected_path =
+            dunce::canonicalize(cfg.codex_home.join("skills/linting/SKILL.md").as_path())
+                .unwrap_or_else(|_| cfg.codex_home.join("skills/linting/SKILL.md"));
+        let expected_path_str = expected_path.to_string_lossy().replace('\\', "/");
+        let expected = format!(
+            "## Skills\nThese skills are discovered at startup from ~/.codex/skills; each entry shows name, description, and file path so you can open the source for full instructions. Content is not inlined to keep context lean.\n- linting: run clippy (file: {expected_path_str})"
+        );
+        assert_eq!(res, expected);
+    }
+
+    fn create_skill(codex_home: PathBuf, name: &str, description: &str) {
+        let skill_dir = codex_home.join(format!("skills/{name}"));
+        fs::create_dir_all(&skill_dir).unwrap();
+        let content = format!("---\nname: {name}\ndescription: {description}\n---\n\n# Body\n");
+        fs::write(skill_dir.join("SKILL.md"), content).unwrap();
+    }
 }