feat: add support for agent.md format (.agents/, .agent/) for agents and skills (#263)

This commit adds support for the https://agent.md/ specification format
alongside the traditional .cortex/ paths for discovering custom agents
and skills.

Changes:
- Custom agents are now searched in priority order:
  1. .agents/ (project, agent.md format)
  2. .agent/ (project, agent.md format)
  3. .cortex/agents/ (project, traditional)
  4. ~/.cortex/agents/ (global personal)
  5. ~/.config/cortex/agents/ (global config)

- Skills are now searched in priority order:
  1. ./SKILL.md (local)
  2. .agents/<skill>/ (project, agent.md format)
  3. .agent/<skill>/ (project, agent.md format)
  4. .cortex/skills/ (project, traditional)
  5. ~/.cortex/skills/ (personal)

- Updated help messages to reflect new directory options
- Updated tests to verify new path ordering
- First match wins for duplicates (project > personal)

Co-authored-by: Droid Agent <droid@factory.ai>

Author: echobt

cortex-agents/src/custom/loader.rs

@@ -29,18 +29,30 @@ impl CustomAgentLoader {
 
     /// Create a loader with default paths.
     ///
-    /// Default paths:
-    /// 1. `.cortex/agents/` (project-local)
-    /// 2. `~/.config/cortex/agents/` (global)
+    /// Default paths (in priority order):
+    /// 1. `.agents/` (project-local, https://agent.md/ compatible)
+    /// 2. `.agent/` (project-local, https://agent.md/ compatible)
+    /// 3. `.cortex/agents/` (project-local)
+    /// 4. `~/.cortex/agents/` (global personal)
+    /// 5. `~/.config/cortex/agents/` (global config)
     pub fn with_default_paths(project_root: Option<&Path>) -> Self {
         let mut loader = Self::new();
 
-        // Project-local agents
+        // Project-local agents (multiple formats supported)
         if let Some(root) = project_root {
+            // Support https://agent.md/ format (.agents/ and .agent/)
+            loader.search_paths.push(root.join(".agents"));
+            loader.search_paths.push(root.join(".agent"));
+            // Traditional .cortex/agents format
             loader.search_paths.push(root.join(".cortex/agents"));
         }
 
-        // Global agents
+        // Global personal agents from ~/.cortex/agents/
+        if let Some(home) = dirs::home_dir() {
+            loader.search_paths.push(home.join(".cortex/agents"));
+        }
+
+        // Global agents from config directory
         if let Some(config) = dirs::config_dir() {
             loader.search_paths.push(config.join("cortex/agents"));
         }
@@ -244,13 +256,31 @@ pub mod sync {
     }
 
     /// Get default search directories.
+    ///
+    /// Returns paths in priority order:
+    /// 1. `.agents/` (project-local, https://agent.md/ compatible)
+    /// 2. `.agent/` (project-local, https://agent.md/ compatible)
+    /// 3. `.cortex/agents/` (project-local)
+    /// 4. `~/.cortex/agents/` (global personal)
+    /// 5. `~/.config/cortex/agents/` (global config)
     pub fn default_search_dirs(project_root: Option<&Path>) -> Vec<PathBuf> {
         let mut dirs = Vec::new();
 
+        // Project-local agents (multiple formats supported)
         if let Some(root) = project_root {
+            // Support https://agent.md/ format (.agents/ and .agent/)
+            dirs.push(root.join(".agents"));
+            dirs.push(root.join(".agent"));
+            // Traditional .cortex/agents format
             dirs.push(root.join(".cortex/agents"));
         }
 
+        // Global personal agents from ~/.cortex/agents/
+        if let Some(home) = dirs::home_dir() {
+            dirs.push(home.join(".cortex/agents"));
+        }
+
+        // Global agents from config directory
         if let Some(config) = dirs::config_dir() {
             dirs.push(config.join("cortex/agents"));
         }
@@ -305,8 +335,14 @@ No closing delimiter"#;
         let loader = CustomAgentLoader::with_default_paths(Some(temp.path()));
 
         let paths = loader.search_paths();
-        assert!(!paths.is_empty());
-        assert!(paths[0].ends_with(".cortex/agents"));
+        // Should have at least 3 paths: .agents/, .agent/, .cortex/agents/
+        assert!(paths.len() >= 3);
+        // First path should be .agents/ (agent.md format)
+        assert!(paths[0].ends_with(".agents"));
+        // Second path should be .agent/ (agent.md format singular)
+        assert!(paths[1].ends_with(".agent"));
+        // Third path should be .cortex/agents/ (traditional format)
+        assert!(paths[2].ends_with(".cortex/agents"));
     }
 
     #[tokio::test]

cortex-cli/src/agent_cmd.rs

@@ -301,35 +301,62 @@ fn get_agents_dir() -> Result<PathBuf> {
     Ok(cortex_home.join("agents"))
 }
 
-/// Get the project agents directory path.
-fn get_project_agents_dir() -> Option<PathBuf> {
-    let cwd = std::env::current_dir().ok()?;
-    let project_dir = cwd.join(".cortex").join("agents");
-    if project_dir.exists() {
-        Some(project_dir)
-    } else {
-        None
-    }
+/// Get all project agents directories.
+///
+/// Returns directories in priority order:
+/// 1. `.agents/` (https://agent.md/ compatible)
+/// 2. `.agent/` (https://agent.md/ compatible)
+/// 3. `.cortex/agents/` (traditional format)
+fn get_project_agents_dirs() -> Vec<PathBuf> {
+    let cwd = match std::env::current_dir() {
+        Ok(p) => p,
+        Err(_) => return Vec::new(),
+    };
+
+    let candidates = [
+        cwd.join(".agents"),                // agent.md format
+        cwd.join(".agent"),                 // agent.md format (singular)
+        cwd.join(".cortex").join("agents"), // traditional format
+    ];
+
+    candidates.into_iter().filter(|p| p.exists()).collect()
 }
 
 /// Load all agents from various sources.
 fn load_all_agents() -> Result<Vec<AgentInfo>> {
     let mut agents = Vec::new();
+    let mut seen_names = std::collections::HashSet::new();
 
-    // Load built-in agents
-    agents.extend(load_builtin_agents());
+    // Load built-in agents first
+    for agent in load_builtin_agents() {
+        seen_names.insert(agent.name.clone());
+        agents.push(agent);
+    }
+
+    // Load project agents from multiple directories (.agents/, .agent/, .cortex/agents/)
+    // Project agents take precedence over personal agents
+    for project_dir in get_project_agents_dirs() {
+        if let Ok(project_agents) = load_agents_from_dir(&project_dir, AgentSource::Project) {
+            for agent in project_agents {
+                if !seen_names.contains(&agent.name) {
+                    seen_names.insert(agent.name.clone());
+                    agents.push(agent);
+                }
+            }
+        }
+    }
 
     // Load personal agents from ~/.cortex/agents/
     let personal_dir = get_agents_dir()?;
     if personal_dir.exists() {
-        let personal_agents = load_agents_from_dir(&personal_dir, AgentSource::Personal)?;
-        agents.extend(personal_agents);
-    }
-
-    // Load project agents from .cortex/agents/
-    if let Some(project_dir) = get_project_agents_dir() {
-        let project_agents = load_agents_from_dir(&project_dir, AgentSource::Project)?;
-        agents.extend(project_agents);
+        if let Ok(personal_agents) = load_agents_from_dir(&personal_dir, AgentSource::Personal) {
+            for agent in personal_agents {
+                if !seen_names.contains(&agent.name) {
+                    seen_names.insert(agent.name.clone());
+                    agents.push(agent);
+                }
+            }
+        }
     }
 
     Ok(agents)

cortex-engine/src/commands.rs

@@ -575,7 +575,11 @@ impl CommandHandler for SkillsCommand {
 
             if skills.is_empty() {
                 return Ok(CommandResult::success(
-                    "No skills installed.\n\nTo add skills:\n- Personal: ~/.cortex/skills/<skill-name>/SKILL.md\n- Project: .cortex/skills/<skill-name>/SKILL.md",
+                    "No skills installed.\n\nTo add skills:\n\
+                     - .agents/<skill-name>/SKILL.md (project, agent.md format)\n\
+                     - .agent/<skill-name>/SKILL.md (project, agent.md format)\n\
+                     - .cortex/skills/<skill-name>/SKILL.md (project)\n\
+                     - ~/.cortex/skills/<skill-name>/SKILL.md (personal)",
                 ));
             }
 

cortex-engine/src/skills.rs

@@ -122,7 +122,7 @@ impl Skill {
 pub enum SkillSource {
     /// Personal skill from ~/.cortex/skills/
     Personal,
-    /// Project skill from .cortex/skills/
+    /// Project skill from .cortex/skills/, .agents/, or .agent/
     Project,
     /// Plugin-provided skill
     Plugin,
@@ -144,22 +144,39 @@ pub struct SkillRegistry {
     skills: RwLock<HashMap<String, Skill>>,
     /// Personal skills directory (~/.cortex/skills/).
     personal_dir: PathBuf,
-    /// Project skills directory (.cortex/skills/).
-    project_dir: Option<PathBuf>,
+    /// Project skills directories (.agents/, .agent/, .cortex/skills/).
+    project_dirs: Vec<PathBuf>,
     /// Plugin skills directories.
     plugin_dirs: Vec<PathBuf>,
 }
 
 impl SkillRegistry {
     /// Create a new skill registry.
+    ///
+    /// Skills are searched in the following order:
+    /// 1. `.agents/` (project, https://agent.md/ compatible)
+    /// 2. `.agent/` (project, https://agent.md/ compatible)
+    /// 3. `.cortex/skills/` (project, traditional format)
+    /// 4. `~/.cortex/skills/` (personal)
+    /// 5. Plugin directories
     pub fn new(cortex_home: &Path, project_root: Option<&Path>) -> Self {
         let personal_dir = cortex_home.join("skills");
-        let project_dir = project_root.map(|p| p.join(".cortex").join("skills"));
+
+        // Support multiple project skill directories
+        let project_dirs = if let Some(root) = project_root {
+            vec![
+                root.join(".agents"),                // agent.md format
+                root.join(".agent"),                 // agent.md format (singular)
+                root.join(".cortex").join("skills"), // traditional format
+            ]
+        } else {
+            Vec::new()
+        };
 
         Self {
             skills: RwLock::new(HashMap::new()),
             personal_dir,
-            project_dir,
+            project_dirs,
             plugin_dirs: Vec::new(),
         }
     }
@@ -172,26 +189,43 @@ impl SkillRegistry {
     /// Scan and load all available skills.
     pub async fn scan(&self) -> Result<Vec<Skill>> {
         let mut all_skills = Vec::new();
+        let mut seen_names = std::collections::HashSet::new();
+
+        // Scan project skills first (from .agents/, .agent/, .cortex/skills/)
+        // Project skills take precedence
+        for project_dir in &self.project_dirs {
+            if project_dir.exists() {
+                let skills = self.scan_directory(project_dir, SkillSource::Project)?;
+                for skill in skills {
+                    if !seen_names.contains(&skill.metadata.name) {
+                        seen_names.insert(skill.metadata.name.clone());
+                        all_skills.push(skill);
+                    }
+                }
+            }
+        }
 
         // Scan personal skills
         if self.personal_dir.exists() {
             let skills = self.scan_directory(&self.personal_dir, SkillSource::Personal)?;
-            all_skills.extend(skills);
-        }
-
-        // Scan project skills
-        if let Some(ref project_dir) = self.project_dir
-            && project_dir.exists()
-        {
-            let skills = self.scan_directory(project_dir, SkillSource::Project)?;
-            all_skills.extend(skills);
+            for skill in skills {
+                if !seen_names.contains(&skill.metadata.name) {
+                    seen_names.insert(skill.metadata.name.clone());
+                    all_skills.push(skill);
+                }
+            }
         }
 
         // Scan plugin skills
         for plugin_dir in &self.plugin_dirs {
             if plugin_dir.exists() {
                 let skills = self.scan_directory(plugin_dir, SkillSource::Plugin)?;
-                all_skills.extend(skills);
+                for skill in skills {
+                    if !seen_names.contains(&skill.metadata.name) {
+                        seen_names.insert(skill.metadata.name.clone());
+                        all_skills.push(skill);
+                    }
+                }
             }
         }