feat(skills): default-on global skills with session merging and auto system prompt injection

- AgentConfig::default() now initializes skill_registry with built-in skills
- build_session forks the agent-level registry so session skills never pollute global state
- Session-level skill_dirs and skill_registry are merged on top of the global registry
- Skill directory listing is always injected into the system prompt automatically
- Add SkillRegistry::fork() for isolated per-session copies
- Add SessionOptions::skill_dirs / with_skill_dirs() for lazy per-session skill loading
- Fix with_skills_from_dir() fallback to use SkillRegistry::new() (not with_builtins)
- Bump version to 0.9.2

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: ZhiXiao-Lin

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "a3s-code-cli"
-version = "0.9.1"
+version = "0.9.2"
 edition = "2021"
 authors = ["A3S Lab Team"]
 license = "MIT"

cli/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "a3s-code-core"
-version = "0.9.1"
+version = "0.9.2"
 edition = "2021"
 authors = ["A3S Lab Team"]
 license = "MIT"

core/Cargo.toml

@@ -1,83 +1,14 @@
-//! # Basic Send — Non-Streaming Agent Execution
-//!
-//! The simplest possible A3S Code example: create an agent from config,
-//! bind to a workspace, send a prompt, and print the result.
-//!
-//! ```bash
-//! cd crates/code
-//! cargo run --example 01_basic_send
-//! ```
-
-use a3s_code_core::Agent;
-use std::path::PathBuf;
-use tempfile::TempDir;
-
-fn find_config() -> PathBuf {
-    if let Ok(p) = std::env::var("A3S_CONFIG") {
-        return PathBuf::from(p);
-    }
-    let home = dirs::home_dir().expect("no home dir");
-    let home_cfg = home.join(".a3s/config.hcl");
-    if home_cfg.exists() {
-        return home_cfg;
-    }
-    // Project root
-    let project_cfg = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../.a3s/config.hcl");
-    if project_cfg.exists() {
-        return project_cfg;
-    }
-    panic!("Config not found. Create ~/.a3s/config.hcl or set A3S_CONFIG");
-}
+use a3s_code_core::{Agent, SessionOptions};
 
 #[tokio::main]
 async fn main() -> anyhow::Result<()> {
-    tracing_subscriber::fmt()
-        .with_env_filter("a3s_code_core=info")
-        .init();
-
-    let config = find_config();
-    println!("Config: {}", config.display());
-
-    // 1. Create agent from config
-    let agent = Agent::new(config.to_str().unwrap()).await?;
-    println!("Agent created ✓");
+    let agent = Agent::new("/Users/roylin/Desktop/ai-lab/a3s/.a3s/config.hcl").await?;
 
-    // 2. Create a temp workspace
-    let workspace = TempDir::new()?;
-    let session = agent.session(workspace.path().to_str().unwrap(), None)?;
-    println!("Session bound to: {}\n", workspace.path().display());
-
-    // 3. Send a prompt (non-streaming)
-    let result = session
-        .send(
-            "Create a file called hello.rs with a main function that prints 'Hello, A3S!'.\n\
-             Then read the file back and confirm it looks correct.",
-            None,
-        )
-        .await?;
-
-    println!("─── Result ───");
-    println!("Text:       {}", truncate(&result.text, 200));
-    println!("Tool calls: {}", result.tool_calls_count);
-    println!("Tokens:     {} total", result.usage.total_tokens);
-
-    // 4. Verify the file
-    let hello = workspace.path().join("hello.rs");
-    if hello.exists() {
-        println!(
-            "\n✓ hello.rs created ({} bytes)",
-            std::fs::metadata(&hello)?.len()
-        );
-    }
+    let opts = SessionOptions::new().with_permissive_policy();
+    let session = agent.session("/tmp", Some(opts))?;
 
+    let result = session.send("List the files in the current directory.", None).await?;
+    println!("{}", result.text);
+    println!("Tokens: {}", result.usage.total_tokens);
     Ok(())
 }
-
-fn truncate(s: &str, max: usize) -> String {
-    let s = s.trim();
-    if s.len() <= max {
-        s.to_string()
-    } else {
-        format!("{}…", &s[..max])
-    }
-}

core/examples/01_basic_send.rs

@@ -157,7 +157,7 @@ impl Default for AgentConfig {
             planning_enabled: false,
             goal_tracking: false,
             hook_engine: None,
-            skill_registry: None,
+            skill_registry: Some(Arc::new(crate::skills::SkillRegistry::with_builtins())),
             max_parse_retries: 2,
             tool_timeout_ms: None,
             circuit_breaker_threshold: 3,
@@ -2708,6 +2708,11 @@ mod tests {
         assert_eq!(config.max_tool_rounds, MAX_TOOL_ROUNDS);
         assert!(config.permission_checker.is_none());
         assert!(config.context_providers.is_empty());
+        // Built-in skills are always present by default
+        let registry = config.skill_registry.expect("skill_registry must be Some by default");
+        assert!(registry.len() >= 7, "expected at least 7 built-in skills");
+        assert!(registry.get("code-search").is_some());
+        assert!(registry.get("find-bugs").is_some());
     }
 
     // ========================================================================

core/src/agent.rs

@@ -77,6 +77,9 @@ pub struct SessionOptions {
     pub planning_enabled: bool,
     /// Enable goal tracking
     pub goal_tracking: bool,
+    /// Extra directories to scan for skill files (*.md).
+    /// Merged with any global `skill_dirs` from [`CodeConfig`].
+    pub skill_dirs: Vec<PathBuf>,
     /// Optional skill registry for instruction injection
     pub skill_registry: Option<Arc<crate::skills::SkillRegistry>>,
     /// Optional memory store for long-term memory persistence
@@ -138,6 +141,7 @@ impl std::fmt::Debug for SessionOptions {
         f.debug_struct("SessionOptions")
             .field("model", &self.model)
             .field("agent_dirs", &self.agent_dirs)
+            .field("skill_dirs", &self.skill_dirs)
             .field("queue_config", &self.queue_config)
             .field("security_provider", &self.security_provider.is_some())
             .field("context_providers", &self.context_providers.len())
@@ -278,7 +282,14 @@ impl SessionOptions {
         self
     }
 
-    /// Load skills from a directory
+    /// Add skill directories to scan for skill files (*.md).
+    /// Merged with any global `skill_dirs` from [`CodeConfig`] at session build time.
+    pub fn with_skill_dirs(mut self, dirs: impl IntoIterator<Item = impl Into<PathBuf>>) -> Self {
+        self.skill_dirs.extend(dirs.into_iter().map(Into::into));
+        self
+    }
+
+    /// Load skills from a directory (eager — scans immediately into a registry).
     pub fn with_skills_from_dir(mut self, dir: impl AsRef<std::path::Path>) -> Self {
         let registry = self
             .skill_registry
@@ -503,7 +514,19 @@ impl Agent {
     /// Auto-detects: file path (.hcl/.json) vs inline JSON vs inline HCL.
     pub async fn new(config_source: impl Into<String>) -> Result<Self> {
         let source = config_source.into();
-        let path = Path::new(&source);
+
+        // Expand leading `~/` to the user's home directory
+        let expanded = if source.starts_with("~/") {
+            if let Some(home) = std::env::var_os("HOME") {
+                format!("{}/{}", home.to_string_lossy(), &source[2..])
+            } else {
+                source.clone()
+            }
+        } else {
+            source.clone()
+        };
+
+        let path = Path::new(&expanded);
 
         let config = if path.extension().is_some() && path.exists() {
             CodeConfig::from_file(path)
@@ -538,11 +561,26 @@ impl Agent {
             ..AgentConfig::default()
         };
 
-        Ok(Agent {
+        let mut agent = Agent {
             llm_client,
             code_config: config,
             config: agent_config,
-        })
+        };
+
+        // Always initialize the skill registry with built-in skills, then load any user-defined dirs
+        let registry = Arc::new(crate::skills::SkillRegistry::with_builtins());
+        for dir in &agent.code_config.skill_dirs.clone() {
+            if let Err(e) = registry.load_from_dir(dir) {
+                tracing::warn!(
+                    dir = %dir.display(),
+                    error = %e,
+                    "Failed to load skills from directory — skipping"
+                );
+            }
+        }
+        agent.config.skill_registry = Some(registry);
+
+        Ok(agent)
     }
 
     /// Bind to a workspace directory, returning an [`AgentSession`].
@@ -694,16 +732,41 @@ impl Agent {
             .clone()
             .unwrap_or_else(|| self.config.prompt_slots.clone());
 
-        // Append skill instructions to the extra slot
-        if let Some(ref registry) = opts.skill_registry {
-            let skill_prompt = registry.to_system_prompt();
-            if !skill_prompt.is_empty() {
-                prompt_slots.extra = match prompt_slots.extra {
-                    Some(existing) => Some(format!("{}\n\n{}", existing, skill_prompt)),
-                    None => Some(skill_prompt),
-                };
+        // Build effective skill registry: fork the agent-level registry (builtins + global
+        // skill_dirs), then layer session-level skills on top. Forking ensures session skills
+        // never pollute the shared agent-level registry.
+        let base_registry = self
+            .config
+            .skill_registry
+            .as_deref()
+            .map(|r| r.fork())
+            .unwrap_or_else(crate::skills::SkillRegistry::with_builtins);
+        // Merge explicit session registry on top of the fork
+        if let Some(ref r) = opts.skill_registry {
+            for skill in r.all() {
+                base_registry.register_unchecked(skill);
+            }
+        }
+        // Load session-level skill dirs
+        for dir in &opts.skill_dirs {
+            if let Err(e) = base_registry.load_from_dir(dir) {
+                tracing::warn!(
+                    dir = %dir.display(),
+                    error = %e,
+                    "Failed to load session skill dir — skipping"
+                );
             }
         }
+        let effective_registry = Arc::new(base_registry);
+
+        // Append skill directory listing to the extra prompt slot
+        let skill_prompt = effective_registry.to_system_prompt();
+        if !skill_prompt.is_empty() {
+            prompt_slots.extra = match prompt_slots.extra {
+                Some(existing) => Some(format!("{}\n\n{}", existing, skill_prompt)),
+                None => Some(skill_prompt),
+            };
+        }
 
         // Resolve memory store: explicit store takes priority, then file_memory_dir
         let mut init_warning: Option<String> = None;
@@ -751,7 +814,7 @@ impl Agent {
             context_providers: opts.context_providers.clone(),
             planning_enabled: opts.planning_enabled,
             goal_tracking: opts.goal_tracking,
-            skill_registry: opts.skill_registry.clone(),
+            skill_registry: Some(effective_registry),
             max_parse_retries: opts.max_parse_retries.unwrap_or(base.max_parse_retries),
             tool_timeout_ms: opts.tool_timeout_ms.or(base.tool_timeout_ms),
             circuit_breaker_threshold: opts
@@ -850,6 +913,32 @@ impl Agent {
             .clone()
             .unwrap_or_else(|| uuid::Uuid::new_v4().to_string());
 
+        // Resolve session store: explicit opts store > config sessions_dir > None
+        let session_store = if opts.session_store.is_some() {
+            opts.session_store.clone()
+        } else if let Some(ref dir) = self.code_config.sessions_dir {
+            match tokio::runtime::Handle::try_current() {
+                Ok(handle) => {
+                    let dir = dir.clone();
+                    match tokio::task::block_in_place(|| {
+                        handle.block_on(crate::store::FileSessionStore::new(dir))
+                    }) {
+                        Ok(store) => Some(Arc::new(store) as Arc<dyn crate::store::SessionStore>),
+                        Err(e) => {
+                            tracing::warn!("Failed to create session store from sessions_dir: {}", e);
+                            None
+                        }
+                    }
+                }
+                Err(_) => {
+                    tracing::warn!("No async runtime for sessions_dir store — persistence disabled");
+                    None
+                }
+            }
+        } else {
+            None
+        };
+
         Ok(AgentSession {
             llm_client,
             tool_executor,
@@ -860,7 +949,7 @@ impl Agent {
             session_id,
             history: RwLock::new(Vec::new()),
             command_queue,
-            session_store: opts.session_store.clone(),
+            session_store,
             auto_save: opts.auto_save,
             hook_engine: Arc::new(crate::hooks::HookEngine::new()),
             init_warning,

core/src/agent_api.rs

@@ -125,6 +125,33 @@ pub struct ProviderConfig {
     pub models: Vec<ModelConfig>,
 }
 
+/// Apply model capability flags to an LlmConfig.
+///
+/// - `temperature = false` → omit temperature (model ignores it, e.g. o1)
+/// - `reasoning = true` + `thinking_budget` set → pass budget to client
+/// - `limit.output > 0` → use as max_tokens
+fn apply_model_caps(mut config: LlmConfig, model: &ModelConfig, thinking_budget: Option<usize>) -> LlmConfig {
+    // reasoning=true + thinking_budget set → pass budget to client (Anthropic only)
+    if model.reasoning {
+        if let Some(budget) = thinking_budget {
+            config = config.with_thinking_budget(budget);
+        }
+    }
+
+    // limit.output > 0 → use as max_tokens cap
+    if model.limit.output > 0 {
+        config = config.with_max_tokens(model.limit.output as usize);
+    }
+
+    // temperature=false models (e.g. o1) must not receive a temperature param.
+    // Store the flag so the LLM client can gate it at call time.
+    if !model.temperature {
+        config.disable_temperature = true;
+    }
+
+    config
+}
+
 impl ProviderConfig {
     /// Find a model by ID
     pub fn find_model(&self, model_id: &str) -> Option<&ModelConfig> {
@@ -387,6 +414,7 @@ impl CodeConfig {
         if let Some(url) = base_url {
             config = config.with_base_url(url);
         }
+        config = apply_model_caps(config, model, self.thinking_budget);
         Some(config)
     }
 
@@ -403,6 +431,7 @@ impl CodeConfig {
         if let Some(url) = base_url {
             config = config.with_base_url(url);
         }
+        config = apply_model_caps(config, model, self.thinking_budget);
         Some(config)
     }