From 69e0d1c8c6034f92f247a94c92c129d8a0264b8f Mon Sep 17 00:00:00 2001
From: kev1n77 <fmy077@outlook.com>
Date: Tue, 8 Sep 2026 22:59:30 +0800
Subject: [PATCH] fix(skills): align discovery, source selection, and picker
 behavior

---
 .../ui/src/components/Listbox/Listbox.tsx     |   6 +-
 .../opencode-config-assets-adapter-design.md  |   7 +
 .../technical/tauri-command-map.json          |   4 +-
 src/apps/desktop/AGENTS.md                    |   2 +
 src/apps/desktop/src/api/skill_api.rs         |  73 +-
 src/crates/assembly/core/AGENTS.md            |   6 +
 .../tools/implementations/skill_tool.rs       |  64 +-
 .../tools/implementations/skills/mod.rs       |   2 +-
 .../tools/implementations/skills/registry.rs  | 619 ++++++++---------
 .../skills/registry/discovery.rs              | 645 ++++++++++++++++++
 .../tools/implementations/skills/types.rs     |   2 +-
 .../execution/agent-runtime/src/prompt.rs     |   1 +
 .../execution/agent-runtime/src/skills/mod.rs |   2 +-
 .../agent-runtime/src/skills/types.rs         |  32 +
 .../skill_contracts.rs                        |  18 +
 .../src/app/scenes/skills/SkillsScene.scss    |  10 +
 .../src/app/scenes/skills/SkillsScene.tsx     |  11 +-
 .../skills/hooks/useInstalledSkills.test.tsx  |  16 +-
 .../scenes/skills/hooks/useInstalledSkills.ts |  14 +-
 .../components/ChatContextPicker.scss         |  32 +
 .../components/ChatContextPicker.tsx          |  23 +-
 .../ChatContextPickerOverlay.test.tsx         |  23 +-
 .../src/flow_chat/components/ChatInput.tsx    |  43 +-
 .../components/RichTextInput.test.tsx         |  14 +-
 .../flow_chat/components/RichTextInput.tsx    |  10 +-
 .../hooks/useResolvedModeSkills.test.tsx      |   6 +-
 .../flow_chat/hooks/useResolvedModeSkills.ts  |  15 +-
 .../flow_chat/utils/chatInputQuickSkills.ts   |   2 +-
 .../utils/skillPromptReference.test.ts        |  17 +
 .../flow_chat/utils/skillPromptReference.ts   |  26 +-
 .../api/service-api/ConfigAPI.test.ts         |  23 +
 .../api/service-api/ConfigAPI.ts              |  35 +
 .../src/infrastructure/config/types/index.ts  |  13 +
 src/web-ui/src/locales/en-US/flow-chat.json   |   2 +
 .../src/locales/en-US/scenes/skills.json      |   4 +-
 src/web-ui/src/locales/zh-CN/flow-chat.json   |   2 +
 .../src/locales/zh-CN/scenes/skills.json      |   4 +-
 src/web-ui/src/locales/zh-TW/flow-chat.json   |   2 +
 .../src/locales/zh-TW/scenes/skills.json      |   4 +-
 39 files changed, 1413 insertions(+), 421 deletions(-)
 create mode 100644 src/crates/assembly/core/src/agentic/tools/implementations/skills/registry/discovery.rs

diff --git a/design-system/packages/ui/src/components/Listbox/Listbox.tsx b/design-system/packages/ui/src/components/Listbox/Listbox.tsx
index 3732f58337..c9ff848abd 100644
--- a/design-system/packages/ui/src/components/Listbox/Listbox.tsx
+++ b/design-system/packages/ui/src/components/Listbox/Listbox.tsx
@@ -215,6 +215,7 @@ export const ListboxOption = forwardRef<HTMLButtonElement, ListboxOptionProps>(
     metadata,
     selected = false,
     tabIndex = -1,
+    title,
     value,
     ...props
   }, ref) {
@@ -234,6 +235,7 @@ export const ListboxOption = forwardRef<HTMLButtonElement, ListboxOptionProps>(
         ref={ref}
         role="option"
         tabIndex={tabIndex}
+        title={title}
         type="button"
       >
         {leading !== undefined && leading !== null && (
@@ -242,7 +244,7 @@ export const ListboxOption = forwardRef<HTMLButtonElement, ListboxOptionProps>(
           </span>
         )}
         <span className={styles.content} data-openbitfun-part="content">
-          <OverflowText className={styles.label} data-openbitfun-part="label" marqueeActive={active}>{children}</OverflowText>
+          <OverflowText title={title === "" ? "" : undefined} className={styles.label} data-openbitfun-part="label" marqueeActive={active}>{children}</OverflowText>
           {description !== undefined && description !== null && (
             <span className={styles.description} data-openbitfun-part="description">
               {description}
@@ -250,7 +252,7 @@ export const ListboxOption = forwardRef<HTMLButtonElement, ListboxOptionProps>(
           )}
         </span>
         {metadata !== undefined && metadata !== null && (
-          <OverflowText className={styles.metadata} data-openbitfun-part="metadata" marqueeActive={active}>{metadata}</OverflowText>
+          <OverflowText title={title === "" ? "" : undefined} className={styles.metadata} data-openbitfun-part="metadata" marqueeActive={active}>{metadata}</OverflowText>
         )}
         <span aria-hidden="true" className={styles.indicator} data-openbitfun-part="indicator">
           {indicator ?? (selected ? <Icon name="check-line" /> : null)}
diff --git a/docs/architecture/extensions/opencode-config-assets-adapter-design.md b/docs/architecture/extensions/opencode-config-assets-adapter-design.md
index dca4de2287..25631f78d1 100644
--- a/docs/architecture/extensions/opencode-config-assets-adapter-design.md
+++ b/docs/architecture/extensions/opencode-config-assets-adapter-design.md
@@ -243,6 +243,13 @@ watcher；用户通过统一的 `/reload instructions`（或默认 `/reload`）
 
 ### 5.2 Agents、Modes 与 Skills
 
+标准 Skill 根使用有界递归发现（包括 Codex 的 `.system` 等容器目录），遇到 `SKILL.md` 后将该目录视为包边界，不继续收集其示例中的 Skill。
+本地扫描跟随目录链接并按规范路径防环；远程扫描通过 workspace filesystem 跟随链接，以深度和目录预算终止循环。远程项目根与本地项目根采用相同的项目优先、用户次之顺序。
+直接子目录保留原有 `scope::source-slot::directory` key；嵌套目录以根内 POSIX 相对路径作为末段，避免不同容器内同名目录冲突。
+按名称的默认选择维持现有覆盖规则；Web UI 的 `@` 技能选择器只显示当前模式按覆盖规则选出的名称赢家；显式选择以 `[$scope::source-slot::relative/path]` 调用精确 key，仍受全局、模式和作者的用户调用可见性约束。
+扫描诊断与可用清单分别返回。Desktop 现有列表命令通过可选 `includeDiagnostics` 返回报告；参数缺省仍返回数组，新客户端接受旧主机的数组并标明诊断不可用。单个目录或文件失败不清空已发现技能。
+
+
 兼容定义进入现有 Agent 归属模块，而不是新建 OpenCode Agent Runtime。当前已实现范围按是否能保持行为等价划分：
 
 - 可等价映射并激活：名称、description、生产 V1 `prompt/disable` 与 Core V2 `system/disabled` 安全子集、`primary|subagent|all`、隐藏状态、
diff --git a/docs/interactive-capabilities/technical/tauri-command-map.json b/docs/interactive-capabilities/technical/tauri-command-map.json
index 76a539eb14..ba54fcf874 100644
--- a/docs/interactive-capabilities/technical/tauri-command-map.json
+++ b/docs/interactive-capabilities/technical/tauri-command-map.json
@@ -3410,7 +3410,7 @@
       "visibility": "documented",
       "rustPath": "get_mode_skill_configs",
       "sourceFile": "src/apps/desktop/src/api/skill_api.rs",
-      "signature": "fn get_mode_skill_configs( state: State<'_, AppState>, mode_id: String, force_refresh: Option<bool>, workspace_path: Option<String>, ) -> Result<Value, String>",
+      "signature": "fn get_mode_skill_configs( state: State<'_, AppState>, mode_id: String, force_refresh: Option<bool>, include_diagnostics: Option<bool>, workspace_path: Option<String>, ) -> Result<Value, String>",
       "remoteWorkspacePolicy": "LegacyUnaudited"
     },
     {
@@ -3810,7 +3810,7 @@
       "visibility": "documented",
       "rustPath": "get_skill_configs",
       "sourceFile": "src/apps/desktop/src/api/skill_api.rs",
-      "signature": "fn get_skill_configs( state: State<'_, AppState>, force_refresh: Option<bool>, workspace_path: Option<String>, ) -> Result<Value, String>",
+      "signature": "fn get_skill_configs( state: State<'_, AppState>, force_refresh: Option<bool>, include_diagnostics: Option<bool>, workspace_path: Option<String>, ) -> Result<Value, String>",
       "remoteWorkspacePolicy": "LegacyUnaudited"
     },
     {
diff --git a/src/apps/desktop/AGENTS.md b/src/apps/desktop/AGENTS.md
index 9bd77d5bfa..9e7e379d2d 100644
--- a/src/apps/desktop/AGENTS.md
+++ b/src/apps/desktop/AGENTS.md
@@ -97,6 +97,8 @@ The `devtools` Cargo feature exists for debugging UI/UX in the desktop app. When
 cargo check -p openbitfun-desktop && cargo test -p openbitfun-desktop
 ```
 
+For skill discovery response compatibility and timeouts, use
+`cargo test -p openbitfun-desktop --lib api::skill_api::tests`.
 For staged application-update cache and signature behavior, use
 `cargo test -p openbitfun-desktop --lib api::update_api::tests`.
 For peer system-info response compatibility, run
diff --git a/src/apps/desktop/src/api/skill_api.rs b/src/apps/desktop/src/api/skill_api.rs
index f3fb56641c..0cc9622872 100644
--- a/src/apps/desktop/src/api/skill_api.rs
+++ b/src/apps/desktop/src/api/skill_api.rs
@@ -24,7 +24,7 @@ use openbitfun_core::agentic::tools::implementations::skills::mode_overrides::{
 };
 use openbitfun_core::agentic::tools::implementations::skills::{
     resolver::resolve_skill_default_enabled_for_mode, ModeSkillInfo, SkillData, SkillInfo,
-    SkillLocation, SkillRegistry,
+    SkillLocation, SkillRegistry, SkillScanReport,
 };
 use openbitfun_core::agentic::workspace::RemoteWorkspaceFs;
 use openbitfun_core::infrastructure::get_path_manager_arc;
@@ -229,6 +229,18 @@ async fn get_all_skills_for_workspace_input(
     registry: &SkillRegistry,
     workspace_path: Option<&str>,
 ) -> Result<Vec<SkillInfo>, String> {
+    Ok(
+        get_skill_scan_report_for_workspace_input(state, registry, workspace_path)
+            .await?
+            .skills,
+    )
+}
+
+async fn get_skill_scan_report_for_workspace_input(
+    state: &State<'_, AppState>,
+    registry: &SkillRegistry,
+    workspace_path: Option<&str>,
+) -> Result<SkillScanReport, String> {
     if let Some((remote_root, entry)) = resolve_remote_workspace(state, workspace_path).await? {
         await_remote_skill_discovery(
             async {
@@ -238,7 +250,7 @@ async fn get_all_skills_for_workspace_input(
                     .map_err(|e| format!("Remote file service not available: {}", e))?;
                 let remote_workspace_fs = RemoteWorkspaceFs::new(entry.connection_id, remote_fs);
                 Ok(registry
-                    .get_all_skills_for_remote_workspace(&remote_workspace_fs, &remote_root)
+                    .get_skill_scan_report_for_remote_workspace(&remote_workspace_fs, &remote_root)
                     .await)
             },
             REMOTE_SKILL_DISCOVERY_TIMEOUT,
@@ -246,17 +258,19 @@ async fn get_all_skills_for_workspace_input(
         .await
     } else {
         Ok(registry
-            .get_all_skills_for_workspace(workspace_root_from_input(workspace_path).as_deref())
+            .get_skill_scan_report_for_workspace(
+                workspace_root_from_input(workspace_path).as_deref(),
+            )
             .await)
     }
 }
 
-async fn get_mode_skill_infos_for_workspace_input(
+async fn get_mode_skill_scan_report_for_workspace_input(
     state: &State<'_, AppState>,
     registry: &SkillRegistry,
     mode_id: &str,
     workspace_path: Option<&str>,
-) -> Result<Vec<ModeSkillInfo>, String> {
+) -> Result<SkillScanReport<ModeSkillInfo>, String> {
     if let Some((remote_root, entry)) = resolve_remote_workspace(state, workspace_path).await? {
         await_remote_skill_discovery(
             async {
@@ -267,7 +281,7 @@ async fn get_mode_skill_infos_for_workspace_input(
                 let remote_workspace_fs =
                     RemoteWorkspaceFs::new(entry.connection_id.clone(), remote_fs.clone());
                 Ok(registry
-                    .get_mode_skill_infos_for_remote_workspace(
+                    .get_mode_skill_scan_report_for_remote_workspace(
                         &remote_workspace_fs,
                         &remote_root,
                         mode_id,
@@ -279,18 +293,29 @@ async fn get_mode_skill_infos_for_workspace_input(
         .await
     } else if let Some(workspace_root) = workspace_root_from_input(workspace_path) {
         Ok(registry
-            .get_mode_skill_infos_for_workspace(Some(&workspace_root), mode_id)
+            .get_mode_skill_scan_report_for_workspace(Some(&workspace_root), mode_id)
             .await)
     } else {
         // Mode-scoped built-in and user-level skills should still be available even
         // when no project workspace is open. In that case there are simply no
         // project-level overrides to apply.
         Ok(registry
-            .get_mode_skill_infos_for_workspace(None, mode_id)
+            .get_mode_skill_scan_report_for_workspace(None, mode_id)
             .await)
     }
 }
 
+fn serialize_skill_scan_response<T: Serialize>(
+    report: SkillScanReport<T>,
+    include_diagnostics: bool,
+) -> Result<Value, serde_json::Error> {
+    if include_diagnostics {
+        serde_json::to_value(report)
+    } else {
+        serde_json::to_value(report.skills)
+    }
+}
+
 fn normalize_skill_key_list(keys: Vec<String>) -> Vec<String> {
     let mut seen = HashSet::new();
     let mut normalized = Vec::new();
@@ -526,6 +551,7 @@ async fn clear_project_mode_skill_selection_remote(
 pub async fn get_skill_configs(
     state: State<'_, AppState>,
     force_refresh: Option<bool>,
+    include_diagnostics: Option<bool>,
     workspace_path: Option<String>,
 ) -> Result<Value, String> {
     let registry = SkillRegistry::global();
@@ -535,9 +561,10 @@ pub async fn get_skill_configs(
     }
 
     let all_skills =
-        get_all_skills_for_workspace_input(&state, registry, workspace_path.as_deref()).await?;
+        get_skill_scan_report_for_workspace_input(&state, registry, workspace_path.as_deref())
+            .await?;
 
-    serde_json::to_value(all_skills)
+    serialize_skill_scan_response(all_skills, include_diagnostics.unwrap_or(false))
         .map_err(|e| format!("Failed to serialize skill configs: {}", e))
 }
 
@@ -591,6 +618,7 @@ pub async fn get_mode_skill_configs(
     state: State<'_, AppState>,
     mode_id: String,
     force_refresh: Option<bool>,
+    include_diagnostics: Option<bool>,
     workspace_path: Option<String>,
 ) -> Result<Value, String> {
     let registry = SkillRegistry::global();
@@ -599,7 +627,7 @@ pub async fn get_mode_skill_configs(
         registry.refresh().await;
     }
 
-    let mode_skill_infos = get_mode_skill_infos_for_workspace_input(
+    let mode_skill_infos = get_mode_skill_scan_report_for_workspace_input(
         &state,
         registry,
         &mode_id,
@@ -607,7 +635,7 @@ pub async fn get_mode_skill_configs(
     )
     .await?;
 
-    serde_json::to_value(mode_skill_infos)
+    serialize_skill_scan_response(mode_skill_infos, include_diagnostics.unwrap_or(false))
         .map_err(|e| format!("Failed to serialize mode skill configs: {}", e))
 }
 
@@ -1086,6 +1114,27 @@ mod tests {
     use std::future;
     use tokio::time::Duration;
 
+    #[test]
+    fn skill_scan_response_preserves_legacy_arrays_and_opt_in_diagnostics() {
+        let report = super::SkillScanReport {
+            skills: vec!["existing"],
+            diagnostics: vec![
+                openbitfun_core::agentic::tools::implementations::skills::SkillScanDiagnostic {
+                    path: "/remote/denied".into(),
+                    source_id: "codex".into(),
+                    message: "permission denied".into(),
+                },
+            ],
+        };
+        assert_eq!(
+            super::serialize_skill_scan_response(report.clone(), false).unwrap(),
+            serde_json::json!(["existing"])
+        );
+        let value = super::serialize_skill_scan_response(report, true).unwrap();
+        assert_eq!(value["skills"], serde_json::json!(["existing"]));
+        assert_eq!(value["diagnostics"][0]["sourceId"], "codex");
+    }
+
     #[tokio::test]
     async fn remote_skill_discovery_returns_before_the_deadline() {
         let result =
diff --git a/src/crates/assembly/core/AGENTS.md b/src/crates/assembly/core/AGENTS.md
index 9d3d45130c..989d63d59e 100644
--- a/src/crates/assembly/core/AGENTS.md
+++ b/src/crates/assembly/core/AGENTS.md
@@ -238,6 +238,12 @@ Skill discovery, installation provenance, and local/remote registry regressions:
 cargo test --locked -p openbitfun-core --no-default-features --features agent-runtime,git --lib agentic::tools::implementations::skills::
 ```
 
+For configured OpenCode discovery and explicit skill loading, include their owner feature and tool tests:
+
+```bash
+cargo test --locked -p openbitfun-core --no-default-features --features agent-runtime,git,external-sources --lib agentic::tools::implementations::skill
+```
+
 Detached Dispatch controller, target query compatibility, and managed-baseline checks:
 
 ```bash
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/skill_tool.rs b/src/crates/assembly/core/src/agentic/tools/implementations/skill_tool.rs
index b88aed4ce6..763e0a35d1 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/skill_tool.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/skill_tool.rs
@@ -39,7 +39,8 @@ How to use skills:
   - `command: "user::openbitfun-system::ppt-design"` - invoke a specific built-in skill by stable key
 
 Important:
-- Only use skills listed in the current skill listing's <available_skills> section, unless a trusted host task explicitly supplies an exact stable key or the user's message contains an exact `[$skill-name]` invocation
+- Only use skills listed in the current skill listing's <available_skills> section, unless a trusted host task explicitly supplies an exact stable key or the user's message contains an exact `[$skill-name]` or `[$scope::source::directory]` invocation
+- For an exact stable-key invocation, pass that key unchanged as `command`; never replace it with a same-named skill from another source
 - Do not invoke a skill that is already running
 </skills_instructions>"#
             .to_string()
@@ -232,7 +233,8 @@ impl Tool for SkillTool {
 
         // Find and load skill through registry
         let registry = get_skill_registry();
-        let use_stable_key = skill_name.split("::").count() == 3;
+        let use_stable_key =
+            skill_name.starts_with("user::") || skill_name.starts_with("project::");
         let mut skill_data = if context.is_remote() {
             if let Some(ws_fs) = context.ws_fs() {
                 let root = context
@@ -506,6 +508,64 @@ Use the remote project skill.
         assert_eq!(schema["required"], json!(["command"]));
     }
 
+    #[tokio::test]
+    async fn stable_key_loads_a_shadowed_nested_skill_without_changing_name_resolution() {
+        let temp = tempfile::tempdir().unwrap();
+        for (directory, body) in [
+            (".openbitfun/skills/same", "default body"),
+            (".codex/skills/nested/same", "chosen body"),
+        ] {
+            let path = temp.path().join(directory);
+            fs::create_dir_all(&path).unwrap();
+            fs::write(
+                path.join("SKILL.md"),
+                format!(
+                    "---\nname: source-collision-regression\ndescription: fixture\n---\n{body}\n"
+                ),
+            )
+            .unwrap();
+        }
+        let context = local_context(temp.path().to_path_buf());
+        for (command, expected) in [
+            ("source-collision-regression", "default body"),
+            ("project::codex::nested/same", "chosen body"),
+        ] {
+            let results = SkillTool::new()
+                .call_impl(&json!({ "command": command }), &context)
+                .await
+                .unwrap();
+            let ToolResult::Result { data, .. } = &results[0] else {
+                panic!("expected skill result")
+            };
+            assert_eq!(data["content"].as_str().unwrap().trim(), expected);
+        }
+        use crate::agentic::tools::implementations::skills::mode_overrides::{
+            load_project_mode_skills_document_local, save_project_mode_skills_document_local,
+            set_mode_skill_disabled_in_document,
+        };
+        let mut document = load_project_mode_skills_document_local(temp.path())
+            .await
+            .unwrap();
+        set_mode_skill_disabled_in_document(
+            &mut document,
+            "agent",
+            "project::codex::nested/same",
+            true,
+        )
+        .unwrap();
+        save_project_mode_skills_document_local(temp.path(), &document)
+            .await
+            .unwrap();
+        assert!(SkillRegistry::global()
+            .find_and_load_skill_by_key_for_workspace(
+                "project::codex::nested/same",
+                Some(temp.path()),
+                Some("agent")
+            )
+            .await
+            .is_err());
+    }
+
     #[tokio::test]
     async fn skill_call_expands_arguments_in_loaded_prompt() {
         let temp = tempfile::tempdir().expect("tempdir");
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/skills/mod.rs b/src/crates/assembly/core/src/agentic/tools/implementations/skills/mod.rs
index 964d25e389..3eba9e1981 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/skills/mod.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/skills/mod.rs
@@ -15,7 +15,7 @@ pub mod types;
 pub use registry::SkillRegistry;
 pub use types::{
     render_loaded_skill_for_assistant, ModeSkillInfo, ModeSkillStateReason, SkillData, SkillInfo,
-    SkillLocation,
+    SkillLocation, SkillScanDiagnostic, SkillScanReport,
 };
 
 /// Get global Skill registry instance
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/skills/registry.rs b/src/crates/assembly/core/src/agentic/tools/implementations/skills/registry.rs
index b673c38b96..e884f21f3f 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/skills/registry.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/skills/registry.rs
@@ -9,7 +9,9 @@ use super::mode_overrides::{
 };
 #[cfg(feature = "file-watch")]
 use super::source_cache::{LocalSkillWatchMonitor, LocalSkillWatchRoot, VersionedSnapshotCache};
-use super::types::{ModeSkillInfo, SkillData, SkillInfo, SkillLocation};
+use super::types::{
+    ModeSkillInfo, SkillData, SkillInfo, SkillLocation, SkillScanDiagnostic, SkillScanReport,
+};
 use crate::agentic::workspace::WorkspaceFileSystem;
 #[cfg(feature = "external-sources")]
 use crate::external_sources::{
@@ -19,13 +21,14 @@ use crate::infrastructure::get_path_manager_arc;
 use crate::util::errors::{OpenBitFunError, OpenBitFunResult};
 use futures::{stream, StreamExt};
 use log::{debug, error, warn};
+#[cfg(feature = "external-sources")]
+use openbitfun_agent_runtime::skills::normalize_local_skill_dir_name;
 use openbitfun_agent_runtime::skills::{
     annotate_shadowed_skills, build_mode_skill_infos, filter_candidates_for_mode,
     filter_implicitly_invocable_skills, filter_user_invocable_skills, is_skill_globally_enabled,
-    normalize_local_skill_dir_name, normalize_remote_skill_dir_name, normalize_skill_keys,
-    resolve_default_hidden_builtin_for_explicit_invocation, resolve_user_config_skill_root,
-    resolve_visible_skills, sort_skill_candidates_by_dir, sort_skills,
-    ExplicitSkillInvocationResolution, SkillCandidate, OPENBITFUN_SKILL_SOURCE_ID,
+    normalize_skill_keys, resolve_default_hidden_builtin_for_explicit_invocation,
+    resolve_user_config_skill_root, resolve_visible_skills, sort_skill_candidates_by_dir,
+    sort_skills, ExplicitSkillInvocationResolution, SkillCandidate, OPENBITFUN_SKILL_SOURCE_ID,
     OPENBITFUN_SKILL_SOURCE_LABEL, OPENBITFUN_SYSTEM_SKILL_DIR, OPENBITFUN_SYSTEM_SKILL_SLOT,
     OPENBITFUN_USER_SKILL_SLOT, PROJECT_SKILL_KEY_PREFIX, PROJECT_SKILL_ROOTS,
     USER_CONFIG_SKILL_ROOTS, USER_HOME_SKILL_ROOTS, USER_SKILL_KEY_PREFIX,
@@ -46,6 +49,8 @@ use std::path::{Path, PathBuf};
 use std::sync::OnceLock;
 use tokio::fs;
 
+mod discovery;
+
 #[cfg(feature = "external-sources")]
 const MAX_OPENCODE_CONFIGURED_SKILL_ROOTS: usize = 64;
 #[cfg(feature = "external-sources")]
@@ -168,6 +173,7 @@ struct RemoteSkillRootEntry {
 #[derive(Debug, Clone)]
 struct UserSkillSources {
     standard: Vec<SkillCandidate>,
+    diagnostics: Vec<SkillScanDiagnostic>,
     #[cfg(feature = "file-watch")]
     cacheable: bool,
     #[cfg(feature = "file-watch")]
@@ -176,9 +182,28 @@ struct UserSkillSources {
 
 struct LocalSkillScan {
     candidates: Vec<SkillCandidate>,
+    diagnostics: Vec<SkillScanDiagnostic>,
     cacheable: bool,
 }
 
+#[derive(Default)]
+struct SkillCandidateScan {
+    candidates: Vec<SkillCandidate>,
+    diagnostics: Vec<SkillScanDiagnostic>,
+}
+
+impl SkillCandidateScan {
+    fn into_candidates(self) -> Vec<SkillCandidate> {
+        for diagnostic in &self.diagnostics {
+            warn!(
+                "Skill discovery incomplete: path={}, source={}, error={}",
+                diagnostic.path, diagnostic.source_id, diagnostic.message
+            );
+        }
+        self.candidates
+    }
+}
+
 async fn local_source_path_is_cacheable(path: &Path) -> bool {
     match fs::symlink_metadata(path).await {
         Ok(metadata) => !is_symlink_or_reparse(&metadata),
@@ -562,21 +587,24 @@ impl SkillRegistry {
             .collect()
     }
 
-    async fn apply_local_openai_policy(skill_data: &mut SkillData, skill_dir: &Path) -> bool {
+    async fn apply_local_openai_policy(
+        skill_data: &mut SkillData,
+        skill_dir: &Path,
+    ) -> (bool, Option<String>) {
         let agents_dir = skill_dir.join("agents");
         let policy_path = agents_dir.join("openai.yaml");
         let cacheable = local_source_path_is_cacheable(&agents_dir).await
             && local_source_path_is_cacheable(&policy_path).await;
         let content = match fs::read_to_string(&policy_path).await {
             Ok(content) => content,
-            Err(error) if error.kind() == std::io::ErrorKind::NotFound => return cacheable,
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => return (cacheable, None),
             Err(error) => {
                 warn!(
                     "Failed to read optional skill policy {}: {}",
                     policy_path.display(),
                     error
                 );
-                return false;
+                return (false, Some(error.to_string()));
             }
         };
 
@@ -586,8 +614,9 @@ impl SkillRegistry {
                 policy_path.display(),
                 error
             );
+            return (cacheable, Some(error.to_string()));
         }
-        cacheable
+        (cacheable, None)
     }
 
     #[cfg(feature = "external-sources")]
@@ -667,7 +696,7 @@ impl SkillRegistry {
         skill_data: &mut SkillData,
         fs: &dyn WorkspaceFileSystem,
         skill_dir: &str,
-    ) {
+    ) -> Option<String> {
         let policy_path = format!("{}/agents/openai.yaml", skill_dir.trim_end_matches('/'));
         let is_file = match fs.is_file(&policy_path).await {
             Ok(is_file) => is_file,
@@ -676,11 +705,11 @@ impl SkillRegistry {
                     "Failed to inspect optional remote skill policy {}: {}",
                     policy_path, error
                 );
-                return;
+                return Some(error.to_string());
             }
         };
         if !is_file {
-            return;
+            return None;
         }
 
         let content = match fs.read_file_text(&policy_path).await {
@@ -690,7 +719,7 @@ impl SkillRegistry {
                     "Failed to read optional remote skill policy {}: {}",
                     policy_path, error
                 );
-                return;
+                return Some(error.to_string());
             }
         };
         if let Err(error) = skill_data.apply_openai_yaml_policy(&content) {
@@ -698,7 +727,9 @@ impl SkillRegistry {
                 "Ignoring invalid optional remote skill policy {}: {}",
                 policy_path, error
             );
+            return Some(error.to_string());
         }
+        None
     }
 
     fn get_project_skill_roots(workspace_path: &Path) -> Vec<SkillRootEntry> {
@@ -847,180 +878,6 @@ impl SkillRegistry {
         Self::scan_skills_in_dir_with_status(entry).await.candidates
     }
 
-    async fn scan_skills_in_dir_with_status(entry: &SkillRootEntry) -> LocalSkillScan {
-        let mut skills = Vec::new();
-        let root_cacheable = local_source_path_is_cacheable(&entry.path).await;
-        match fs::metadata(&entry.path).await {
-            Ok(metadata) if metadata.is_dir() => {}
-            Ok(_) => {
-                return LocalSkillScan {
-                    candidates: skills,
-                    cacheable: root_cacheable,
-                };
-            }
-            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
-                return LocalSkillScan {
-                    candidates: skills,
-                    cacheable: root_cacheable,
-                };
-            }
-            Err(error) => {
-                debug!(
-                    "Failed to inspect Skill root {}: {}",
-                    entry.path.display(),
-                    error
-                );
-                return LocalSkillScan {
-                    candidates: skills,
-                    cacheable: false,
-                };
-            }
-        }
-
-        let mut read_dir = match fs::read_dir(&entry.path).await {
-            Ok(read_dir) => read_dir,
-            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
-                return LocalSkillScan {
-                    candidates: skills,
-                    cacheable: root_cacheable,
-                };
-            }
-            Err(error) => {
-                debug!(
-                    "Failed to read Skill root {}: {}",
-                    entry.path.display(),
-                    error
-                );
-                return LocalSkillScan {
-                    candidates: skills,
-                    cacheable: false,
-                };
-            }
-        };
-        let mut cacheable = root_cacheable;
-        let installation_sources = if let Some(lock_path) = skill_installation_lock_path(entry) {
-            cacheable &= local_source_path_is_cacheable(&lock_path).await;
-            match fs::read_to_string(&lock_path).await {
-                Ok(content) => parse_skill_installation_sources(&content),
-                Err(error) => {
-                    if error.kind() != std::io::ErrorKind::NotFound {
-                        warn!(
-                            "Failed to read skill installation provenance {}: {}",
-                            lock_path.display(),
-                            error
-                        );
-                        cacheable = false;
-                    }
-                    HashMap::new()
-                }
-            }
-        } else {
-            HashMap::new()
-        };
-
-        loop {
-            let item = match read_dir.next_entry().await {
-                Ok(Some(item)) => item,
-                Ok(None) => break,
-                Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
-                    skills.clear();
-                    break;
-                }
-                Err(error) => {
-                    debug!(
-                        "Failed while reading Skill root {}: {}",
-                        entry.path.display(),
-                        error
-                    );
-                    cacheable = false;
-                    break;
-                }
-            };
-            let path = item.path();
-            cacheable &= local_source_path_is_cacheable(&path).await;
-            match fs::metadata(&path).await {
-                Ok(metadata) if metadata.is_dir() => {}
-                Ok(_) => continue,
-                Err(error) if error.kind() == std::io::ErrorKind::NotFound => continue,
-                Err(error) => {
-                    debug!(
-                        "Failed to inspect Skill entry {}: {}",
-                        path.display(),
-                        error
-                    );
-                    cacheable = false;
-                    continue;
-                }
-            }
-
-            let Some(dir_name) = normalize_local_skill_dir_name(&path) else {
-                continue;
-            };
-
-            if entry.slot == OPENBITFUN_USER_SKILL_SLOT && dir_name == OPENBITFUN_SYSTEM_SKILL_DIR {
-                continue;
-            }
-
-            let skill_md_path = path.join("SKILL.md");
-            cacheable &= local_source_path_is_cacheable(&skill_md_path).await;
-            match fs::metadata(&skill_md_path).await {
-                Ok(metadata) if metadata.is_file() => {}
-                Ok(_) => continue,
-                Err(error) if error.kind() == std::io::ErrorKind::NotFound => continue,
-                Err(error) => {
-                    debug!("Failed to inspect {}: {}", skill_md_path.display(), error);
-                    cacheable = false;
-                    continue;
-                }
-            }
-
-            match fs::read_to_string(&skill_md_path).await {
-                Ok(content) => match Self::parse_skill_markdown(
-                    path.to_string_lossy().to_string(),
-                    &content,
-                    entry.level,
-                    false,
-                    entry.slot,
-                ) {
-                    Ok(mut skill_data) => {
-                        cacheable &= Self::apply_local_openai_policy(&mut skill_data, &path).await;
-                        skill_data.dir_name = dir_name;
-                        let key_prefix = match entry.level {
-                            SkillLocation::User => USER_SKILL_KEY_PREFIX,
-                            SkillLocation::Project => PROJECT_SKILL_KEY_PREFIX,
-                        };
-                        let mut candidate = SkillCandidate::from_data(
-                            skill_data,
-                            entry.slot,
-                            entry.source_id,
-                            entry.source_label,
-                            key_prefix,
-                            entry.priority,
-                            entry.is_builtin,
-                        );
-                        candidate.info.installation_source =
-                            installation_sources.get(&candidate.info.name).cloned();
-                        skills.push(candidate);
-                    }
-                    Err(error) => {
-                        error!("Failed to parse SKILL.md in {}: {}", path.display(), error);
-                    }
-                },
-                Err(error) => {
-                    debug!("Failed to read {}: {}", skill_md_path.display(), error);
-                    if error.kind() != std::io::ErrorKind::NotFound {
-                        cacheable = false;
-                    }
-                }
-            }
-        }
-
-        LocalSkillScan {
-            candidates: sort_skill_candidates_by_dir(skills),
-            cacheable,
-        }
-    }
-
     async fn scan_user_skill_sources() -> UserSkillSources {
         #[cfg(feature = "file-watch")]
         let mut cacheable = match ensure_builtin_skills_installed().await {
@@ -1036,6 +893,7 @@ impl SkillRegistry {
         }
 
         let mut standard = Vec::new();
+        let mut diagnostics = Vec::new();
         for entry in Self::get_user_skill_roots() {
             let mut scan = Self::scan_skills_in_dir_with_status(&entry).await;
             #[cfg(feature = "file-watch")]
@@ -1045,10 +903,12 @@ impl SkillRegistry {
             #[cfg(not(feature = "file-watch"))]
             let _ = scan.cacheable;
             standard.append(&mut scan.candidates);
+            diagnostics.append(&mut scan.diagnostics);
         }
 
         UserSkillSources {
             standard,
+            diagnostics,
             #[cfg(feature = "file-watch")]
             cacheable,
             #[cfg(feature = "file-watch")]
@@ -1081,12 +941,23 @@ impl SkillRegistry {
         &self,
         workspace_root: Option<&Path>,
     ) -> Vec<SkillCandidate> {
+        self.scan_skill_candidates_with_diagnostics_for_workspace(workspace_root)
+            .await
+            .into_candidates()
+    }
+
+    async fn scan_skill_candidates_with_diagnostics_for_workspace(
+        &self,
+        workspace_root: Option<&Path>,
+    ) -> SkillCandidateScan {
         let mut user_sources = self.user_skill_sources().await;
+        let mut diagnostics = std::mem::take(&mut user_sources.diagnostics);
         let mut standard = Vec::new();
         if let Some(workspace_root) = workspace_root {
             for entry in Self::get_project_skill_roots(workspace_root) {
-                let mut part = Self::scan_skills_in_dir(&entry).await;
-                standard.append(&mut part);
+                let mut part = Self::scan_skills_in_dir_with_status(&entry).await;
+                standard.append(&mut part.candidates);
+                diagnostics.append(&mut part.diagnostics);
             }
             for candidate in &mut user_sources.standard {
                 candidate.priority = candidate.priority.saturating_add(PROJECT_SKILL_ROOTS.len());
@@ -1103,7 +974,10 @@ impl SkillRegistry {
             // Discover and scan them once per request so scope and the 64-root cap
             // are applied to one coherent OpenCode configuration snapshot.
             let roots = opencode_configured_skill_roots(workspace_root);
-            let mut configured = Self::scan_configured_opencode_candidates(roots).await;
+            let configured_scan =
+                Self::scan_configured_opencode_candidates_with_diagnostics(roots).await;
+            diagnostics.extend(configured_scan.diagnostics);
+            let mut configured = configured_scan.candidates;
             let existing_paths = standard
                 .iter()
                 .map(canonical_candidate_path)
@@ -1113,15 +987,21 @@ impl SkillRegistry {
                 let path = canonical_candidate_path(candidate);
                 !existing_paths.contains(&path) && configured_paths.insert(path)
             });
-            return Self::merge_configured_opencode_candidates(
-                standard,
-                configured,
-                workspace_root.is_some(),
-            );
+            return SkillCandidateScan {
+                candidates: Self::merge_configured_opencode_candidates(
+                    standard,
+                    configured,
+                    workspace_root.is_some(),
+                ),
+                diagnostics,
+            };
         }
 
         #[cfg(not(feature = "external-sources"))]
-        standard
+        SkillCandidateScan {
+            candidates: standard,
+            diagnostics,
+        }
     }
 
     #[cfg(feature = "external-sources")]
@@ -1185,6 +1065,15 @@ impl SkillRegistry {
     async fn scan_configured_opencode_candidates(
         roots: Vec<LocalConfiguredSkillRootContribution>,
     ) -> Vec<SkillCandidate> {
+        Self::scan_configured_opencode_candidates_with_diagnostics(roots)
+            .await
+            .into_candidates()
+    }
+
+    #[cfg(feature = "external-sources")]
+    async fn scan_configured_opencode_candidates_with_diagnostics(
+        roots: Vec<LocalConfiguredSkillRootContribution>,
+    ) -> SkillCandidateScan {
         let mut roots = roots;
         roots.sort_by_key(|root| root.precedence);
         let roots = roots
@@ -1215,6 +1104,7 @@ impl SkillRegistry {
         let mut project_root_index = 0usize;
         let mut user_root_index = 0usize;
         let mut candidates = Vec::new();
+        let mut diagnostics = Vec::new();
 
         for root in roots {
             let root_path = root.path.clone();
@@ -1234,6 +1124,11 @@ impl SkillRegistry {
             {
                 Ok(Ok(files)) => files,
                 Ok(Err(error)) => {
+                    diagnostics.push(discovery::diagnostic(
+                        root.path.to_string_lossy(),
+                        "opencode",
+                        &error,
+                    ));
                     warn!(
                         "Skipping configured OpenCode skill root {}: {}",
                         root.path.display(),
@@ -1242,6 +1137,11 @@ impl SkillRegistry {
                     continue;
                 }
                 Err(error) => {
+                    diagnostics.push(discovery::diagnostic(
+                        root.path.to_string_lossy(),
+                        "opencode",
+                        &error,
+                    ));
                     warn!(
                         "Configured OpenCode skill scan failed for {}: {}",
                         root.path.display(),
@@ -1269,6 +1169,11 @@ impl SkillRegistry {
                 {
                     Ok(Ok(BoundedTextRead::Content(content))) => content,
                     Ok(Ok(BoundedTextRead::TooLarge)) => {
+                        diagnostics.push(discovery::diagnostic(
+                            skill_md_path.to_string_lossy(),
+                            "opencode",
+                            "SKILL.md exceeds the discovery size limit",
+                        ));
                         warn!(
                             "Skipping configured OpenCode skill file above the {} byte limit: {}",
                             MAX_OPENCODE_CONFIGURED_SKILL_BYTES,
@@ -1277,6 +1182,11 @@ impl SkillRegistry {
                         continue;
                     }
                     Ok(Ok(BoundedTextRead::InvalidUtf8)) => {
+                        diagnostics.push(discovery::diagnostic(
+                            skill_md_path.to_string_lossy(),
+                            "opencode",
+                            "SKILL.md is not valid UTF-8",
+                        ));
                         warn!(
                             "Skipping configured OpenCode skill file that is not valid UTF-8: {}",
                             skill_md_path.display()
@@ -1284,10 +1194,20 @@ impl SkillRegistry {
                         continue;
                     }
                     Ok(Err(error)) => {
+                        diagnostics.push(discovery::diagnostic(
+                            skill_md_path.to_string_lossy(),
+                            "opencode",
+                            &error,
+                        ));
                         debug!("Failed to read {}: {}", skill_md_path.display(), error);
                         continue;
                     }
                     Err(error) => {
+                        diagnostics.push(discovery::diagnostic(
+                            skill_md_path.to_string_lossy(),
+                            "opencode",
+                            &error,
+                        ));
                         warn!(
                             "Configured OpenCode skill read failed for {}: {}",
                             skill_md_path.display(),
@@ -1319,6 +1239,11 @@ impl SkillRegistry {
                 ) {
                     Ok(skill_data) => skill_data,
                     Err(error) => {
+                        diagnostics.push(discovery::diagnostic(
+                            skill_md_path.to_string_lossy(),
+                            "opencode",
+                            &error,
+                        ));
                         error!(
                             "Failed to parse configured OpenCode SKILL.md in {}: {}",
                             canonical_skill_dir.display(),
@@ -1367,123 +1292,19 @@ impl SkillRegistry {
         candidates.sort_by_key(|candidate| candidate.priority);
         let mut seen_paths = HashSet::new();
         candidates.retain(|candidate| seen_paths.insert(candidate.info.path.clone()));
-        sort_skill_candidates_by_dir(candidates)
+        SkillCandidateScan {
+            candidates: sort_skill_candidates_by_dir(candidates),
+            diagnostics,
+        }
     }
 
     async fn scan_remote_project_skills(
         fs: &dyn WorkspaceFileSystem,
         remote_root: &str,
     ) -> Vec<SkillCandidate> {
-        let root = remote_root.trim_end_matches('/');
-        // Finish directory discovery before scanning files, so the two bounded
-        // stages cannot multiply the number of simultaneous SFTP operations.
-        // `buffered` preserves source precedence and sorted directory order even
-        // when responses complete in a different order.
-        let root_scans = PROJECT_SKILL_ROOTS
-            .iter()
-            .enumerate()
-            .map(|(priority, spec)| async move {
-                let path = format!("{}/{}/{}", root, spec.parent, spec.subdir);
-                let entry = RemoteSkillRootEntry {
-                    path,
-                    slot: spec.slot,
-                    source_id: spec.source_id,
-                    source_label: spec.source_label,
-                    priority,
-                };
-                let mut items = if fs.is_dir(&entry.path).await.unwrap_or(false) {
-                    fs.read_dir(&entry.path).await.unwrap_or_default()
-                } else {
-                    Vec::new()
-                };
-                sort_remote_dir_entries(&mut items);
-                (entry, items)
-            })
-            .collect::<Vec<_>>();
-        let roots = stream::iter(root_scans)
-            .buffered(REMOTE_SKILL_SCAN_CONCURRENCY)
-            .collect::<Vec<_>>()
-            .await;
-
-        let installation_sources = if roots
-            .iter()
-            .any(|(entry, items)| entry.slot == "agents" && !items.is_empty())
-        {
-            match fs.read_file_text(&format!("{root}/skills-lock.json")).await {
-                Ok(content) => parse_skill_installation_sources(&content),
-                Err(error) => {
-                    debug!(
-                        "Remote skill installation provenance unavailable for {}: {}",
-                        root, error
-                    );
-                    HashMap::new()
-                }
-            }
-        } else {
-            HashMap::new()
-        };
-
-        let directories = roots.iter().flat_map(|(entry, items)| {
-            items
-                .iter()
-                .filter(|item| item.is_dir && !item.is_symlink)
-                .map(move |item| (entry, item))
-        });
-        let skill_scans = directories
-            .map(|(entry, item)| {
-                let installation_sources = &installation_sources;
-                async move {
-                    let dir_name = normalize_remote_skill_dir_name(&item.path)?;
-                    let skill_md_path = format!("{}/SKILL.md", item.path.trim_end_matches('/'));
-                    if !fs.is_file(&skill_md_path).await.unwrap_or(false) {
-                        return None;
-                    }
-                    let content = match fs.read_file_text(&skill_md_path).await {
-                        Ok(content) => content,
-                        Err(error) => {
-                            debug!("Failed to read {}: {}", skill_md_path, error);
-                            return None;
-                        }
-                    };
-                    let mut skill_data = match Self::parse_skill_markdown(
-                        item.path.clone(),
-                        &content,
-                        SkillLocation::Project,
-                        false,
-                        entry.slot,
-                    ) {
-                        Ok(data) => data,
-                        Err(error) => {
-                            error!("Failed to parse SKILL.md in {}: {}", item.path, error);
-                            return None;
-                        }
-                    };
-                    Self::apply_remote_openai_policy(&mut skill_data, fs, &item.path).await;
-                    skill_data.dir_name = dir_name;
-                    let mut candidate = SkillCandidate::from_data(
-                        skill_data,
-                        entry.slot,
-                        entry.source_id,
-                        entry.source_label,
-                        PROJECT_SKILL_KEY_PREFIX,
-                        entry.priority,
-                        false,
-                    );
-                    if entry.slot == "agents" {
-                        candidate.info.installation_source =
-                            installation_sources.get(&candidate.info.name).cloned();
-                    }
-                    Some(candidate)
-                }
-            })
-            .collect::<Vec<_>>();
-        stream::iter(skill_scans)
-            .buffered(REMOTE_SKILL_SCAN_CONCURRENCY)
-            .collect::<Vec<_>>()
+        Self::scan_remote_project_skills_with_diagnostics(fs, remote_root)
             .await
-            .into_iter()
-            .flatten()
-            .collect()
+            .into_candidates()
     }
 
     async fn scan_skill_candidates_for_remote_workspace(
@@ -1491,12 +1312,33 @@ impl SkillRegistry {
         fs: &dyn WorkspaceFileSystem,
         remote_root: &str,
     ) -> Vec<SkillCandidate> {
-        let (mut skills, project_skills) = tokio::join!(
-            self.scan_skill_candidates_for_workspace(None),
-            Self::scan_remote_project_skills(fs, remote_root),
+        self.scan_skill_candidates_with_diagnostics_for_remote_workspace(fs, remote_root)
+            .await
+            .into_candidates()
+    }
+
+    async fn scan_skill_candidates_with_diagnostics_for_remote_workspace(
+        &self,
+        fs: &dyn WorkspaceFileSystem,
+        remote_root: &str,
+    ) -> SkillCandidateScan {
+        let (user, project) = tokio::join!(
+            self.scan_skill_candidates_with_diagnostics_for_workspace(None),
+            Self::scan_remote_project_skills_with_diagnostics(fs, remote_root),
         );
-        skills.extend(project_skills);
-        skills
+        Self::merge_remote_skill_scans(user, project)
+    }
+
+    fn merge_remote_skill_scans(
+        mut user: SkillCandidateScan,
+        mut project: SkillCandidateScan,
+    ) -> SkillCandidateScan {
+        for candidate in &mut user.candidates {
+            candidate.priority = candidate.priority.saturating_add(PROJECT_SKILL_ROOTS.len());
+        }
+        project.candidates.append(&mut user.candidates);
+        project.diagnostics.append(&mut user.diagnostics);
+        project
     }
 
     async fn apply_mode_filters_for_workspace(
@@ -1681,6 +1523,33 @@ impl SkillRegistry {
         self.get_all_skills_for_workspace(None).await
     }
 
+    pub async fn get_skill_scan_report_for_workspace(
+        &self,
+        workspace_root: Option<&Path>,
+    ) -> SkillScanReport {
+        let scan = self
+            .scan_skill_candidates_with_diagnostics_for_workspace(workspace_root)
+            .await;
+        SkillScanReport {
+            skills: sort_skills(annotate_shadowed_skills(scan.candidates)),
+            diagnostics: scan.diagnostics,
+        }
+    }
+
+    pub async fn get_skill_scan_report_for_remote_workspace(
+        &self,
+        fs: &dyn WorkspaceFileSystem,
+        remote_root: &str,
+    ) -> SkillScanReport {
+        let scan = self
+            .scan_skill_candidates_with_diagnostics_for_remote_workspace(fs, remote_root)
+            .await;
+        SkillScanReport {
+            skills: sort_skills(annotate_shadowed_skills(scan.candidates)),
+            diagnostics: scan.diagnostics,
+        }
+    }
+
     pub async fn get_all_skills_for_workspace(
         &self,
         workspace_root: Option<&Path>,
@@ -1772,9 +1641,20 @@ impl SkillRegistry {
         workspace_root: Option<&Path>,
         mode_id: &str,
     ) -> Vec<ModeSkillInfo> {
-        let candidates = self
-            .scan_skill_candidates_for_workspace(workspace_root)
+        self.get_mode_skill_scan_report_for_workspace(workspace_root, mode_id)
+            .await
+            .skills
+    }
+
+    pub async fn get_mode_skill_scan_report_for_workspace(
+        &self,
+        workspace_root: Option<&Path>,
+        mode_id: &str,
+    ) -> SkillScanReport<ModeSkillInfo> {
+        let scan = self
+            .scan_skill_candidates_with_diagnostics_for_workspace(workspace_root)
             .await;
+        let candidates = scan.candidates;
         let all_skills = sort_skills(annotate_shadowed_skills(candidates.clone()));
         let user_overrides = load_user_mode_skill_overrides(mode_id)
             .await
@@ -1794,14 +1674,17 @@ impl SkillRegistry {
         );
         let resolved = resolve_visible_skills(filtered);
 
-        build_mode_skill_infos(
-            all_skills,
-            resolved,
-            mode_id,
-            &user_overrides,
-            &disabled_project,
-            &globally_disabled_user_skills,
-        )
+        SkillScanReport {
+            skills: build_mode_skill_infos(
+                all_skills,
+                resolved,
+                mode_id,
+                &user_overrides,
+                &disabled_project,
+                &globally_disabled_user_skills,
+            ),
+            diagnostics: scan.diagnostics,
+        }
     }
 
     pub async fn get_mode_skill_infos_for_remote_workspace(
@@ -1810,9 +1693,21 @@ impl SkillRegistry {
         remote_root: &str,
         mode_id: &str,
     ) -> Vec<ModeSkillInfo> {
-        let candidates = self
-            .scan_skill_candidates_for_remote_workspace(fs, remote_root)
+        self.get_mode_skill_scan_report_for_remote_workspace(fs, remote_root, mode_id)
+            .await
+            .skills
+    }
+
+    pub async fn get_mode_skill_scan_report_for_remote_workspace(
+        &self,
+        fs: &dyn WorkspaceFileSystem,
+        remote_root: &str,
+        mode_id: &str,
+    ) -> SkillScanReport<ModeSkillInfo> {
+        let scan = self
+            .scan_skill_candidates_with_diagnostics_for_remote_workspace(fs, remote_root)
             .await;
+        let candidates = scan.candidates;
         let all_skills = sort_skills(annotate_shadowed_skills(candidates.clone()));
         let user_overrides = load_user_mode_skill_overrides(mode_id)
             .await
@@ -1829,14 +1724,17 @@ impl SkillRegistry {
         );
         let resolved = resolve_visible_skills(filtered);
 
-        build_mode_skill_infos(
-            all_skills,
-            resolved,
-            mode_id,
-            &user_overrides,
-            &disabled_project,
-            &globally_disabled_user_skills,
-        )
+        SkillScanReport {
+            skills: build_mode_skill_infos(
+                all_skills,
+                resolved,
+                mode_id,
+                &user_overrides,
+                &disabled_project,
+                &globally_disabled_user_skills,
+            ),
+            diagnostics: scan.diagnostics,
+        }
     }
 
     pub async fn find_skill_by_key_for_workspace(
@@ -2014,11 +1912,21 @@ impl SkillRegistry {
         workspace_root: Option<&Path>,
         agent_type: Option<&str>,
     ) -> Vec<String> {
-        self.get_implicitly_invocable_skills_for_workspace(workspace_root, agent_type)
-            .await
-            .into_iter()
-            .map(|skill| skill.to_xml_desc())
-            .collect()
+        let scan = self
+            .scan_skill_candidates_with_diagnostics_for_workspace(workspace_root)
+            .await;
+        let filtered = self
+            .apply_mode_filters_for_workspace(scan.candidates, workspace_root, agent_type)
+            .await;
+        let mut xml: Vec<_> = filter_implicitly_invocable_skills_for_agent(
+            sort_skills(resolve_visible_skills(filtered)),
+            agent_type,
+        )
+        .into_iter()
+        .map(|skill| skill.to_xml_desc())
+        .collect();
+        xml.extend(scan.diagnostics.iter().map(SkillScanDiagnostic::to_xml));
+        xml
     }
 
     pub async fn get_resolved_skills_xml_for_remote_workspace(
@@ -2027,11 +1935,21 @@ impl SkillRegistry {
         remote_root: &str,
         agent_type: Option<&str>,
     ) -> Vec<String> {
-        self.get_implicitly_invocable_skills_for_remote_workspace(fs, remote_root, agent_type)
-            .await
-            .into_iter()
-            .map(|skill| skill.to_xml_desc())
-            .collect()
+        let scan = self
+            .scan_skill_candidates_with_diagnostics_for_remote_workspace(fs, remote_root)
+            .await;
+        let filtered = self
+            .apply_mode_filters_for_remote_workspace(scan.candidates, fs, remote_root, agent_type)
+            .await;
+        let mut xml: Vec<_> = filter_implicitly_invocable_skills_for_agent(
+            sort_skills(resolve_visible_skills(filtered)),
+            agent_type,
+        )
+        .into_iter()
+        .map(|skill| skill.to_xml_desc())
+        .collect();
+        xml.extend(scan.diagnostics.iter().map(SkillScanDiagnostic::to_xml));
+        xml
     }
 
     async fn read_skill_md_for_remote_merge(
@@ -2438,6 +2356,9 @@ mod remote_scan_tests {
             anyhow::bail!("read-only fixture")
         }
         async fn exists(&self, path: &str) -> anyhow::Result<bool> {
+            if path.ends_with("skills-lock.json") {
+                return Ok(self.installation_lock.is_some());
+            }
             self.is_file(path).await
         }
         async fn is_file(&self, path: &str) -> anyhow::Result<bool> {
@@ -2478,7 +2399,7 @@ mod remote_scan_tests {
             ..Default::default()
         };
         let skills = SkillRegistry::scan_remote_project_skills(&fs, "/remote/project/").await;
-        assert_eq!(skills.len(), 36);
+        assert_eq!(skills.len(), 39);
         let installed = skills
             .iter()
             .filter(|skill| skill.info.installation_source.is_some())
@@ -2493,7 +2414,7 @@ mod remote_scan_tests {
 
         fs.installation_lock = Some("invalid remote lock".into());
         let skills = SkillRegistry::scan_remote_project_skills(&fs, "/remote/project/").await;
-        assert_eq!(skills.len(), 36);
+        assert_eq!(skills.len(), 39);
         assert!(skills
             .iter()
             .all(|skill| skill.info.installation_source.is_none()));
@@ -2510,22 +2431,22 @@ mod remote_scan_tests {
             fs.calls.load(Ordering::SeqCst),
             fs.peak.load(Ordering::SeqCst)
         );
-        assert_eq!(skills.len(), 24);
-        for group in skills.chunks(12) {
+        assert_eq!(skills.len(), 26);
+        for group in skills.chunks(13) {
             assert_eq!(
                 group
                     .iter()
                     .map(|skill| skill.info.name.clone())
                     .collect::<Vec<_>>(),
-                (0..12)
+                (0..13)
                     .map(|index| format!("skill-{index:02}"))
                     .collect::<Vec<_>>()
             );
             assert!(!group[0].info.allow_implicit_invocation);
             assert!(group[1].info.allow_implicit_invocation);
         }
-        assert!(skills[0].priority < skills[12].priority);
-        assert_eq!(fs.calls.load(Ordering::SeqCst), 82);
+        assert!(skills[0].priority < skills[13].priority);
+        assert!(fs.calls.load(Ordering::SeqCst) <= 100);
         assert_eq!(fs.active.load(Ordering::SeqCst), 0);
         assert!(fs.peak.load(Ordering::SeqCst) > 1);
         assert!(fs.peak.load(Ordering::SeqCst) <= super::REMOTE_SKILL_SCAN_CONCURRENCY);
@@ -2534,7 +2455,7 @@ mod remote_scan_tests {
         // precedence and invocation policy, without involving user-global skills.
         let local_root = tempfile::tempdir().unwrap();
         for parent in [".openbitfun", ".codex"] {
-            for index in 0..12 {
+            for index in 0..13 {
                 let name = format!("skill-{index:02}");
                 let dir = local_root.path().join(parent).join("skills").join(&name);
                 std::fs::create_dir_all(&dir).unwrap();
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/skills/registry/discovery.rs b/src/crates/assembly/core/src/agentic/tools/implementations/skills/registry/discovery.rs
new file mode 100644
index 0000000000..084e81d67e
--- /dev/null
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/skills/registry/discovery.rs
@@ -0,0 +1,645 @@
+//! Standard skill-root traversal. Keep the logical path in stable keys and
+//! follow linked skill directories on the filesystem that owns each root.
+use super::*;
+use std::collections::VecDeque;
+use tokio::io::AsyncReadExt;
+
+const MAX_SCAN_DEPTH: usize = 32;
+const MAX_SCAN_DIRECTORIES: usize = 4096;
+const MAX_DIRECTORY_ENTRIES: usize = 8192;
+const MAX_SKILL_BYTES: usize = 1024 * 1024;
+
+pub(super) fn diagnostic(
+    path: impl Into<String>,
+    source_id: &str,
+    message: impl ToString,
+) -> SkillScanDiagnostic {
+    SkillScanDiagnostic {
+        path: path.into(),
+        source_id: source_id.into(),
+        message: message.to_string(),
+    }
+}
+
+fn set_nested_key(candidate: &mut SkillCandidate, relative_dir: &str) {
+    // Direct children keep their existing persisted keys. Nested siblings with
+    // the same leaf directory name must not acquire the same key.
+    candidate.info.key = format!(
+        "{}::{}::{}",
+        candidate.info.level.as_str(),
+        candidate.info.source_slot,
+        relative_dir
+    );
+}
+
+impl SkillRegistry {
+    pub(super) async fn scan_remote_project_skills_with_diagnostics(
+        fs: &dyn WorkspaceFileSystem,
+        remote_root: &str,
+    ) -> SkillCandidateScan {
+        let root = remote_root.trim_end_matches('/');
+        let roots = PROJECT_SKILL_ROOTS
+            .iter()
+            .enumerate()
+            .map(|(priority, spec)| async move {
+                let entry = RemoteSkillRootEntry {
+                    path: format!("{}/{}/{}", root, spec.parent, spec.subdir),
+                    slot: spec.slot,
+                    source_id: spec.source_id,
+                    source_label: spec.source_label,
+                    priority,
+                };
+                Self::scan_remote_skill_root(fs, &entry, root).await
+            })
+            .collect::<Vec<_>>();
+        let scans = stream::iter(roots)
+            .buffered(REMOTE_SKILL_SCAN_CONCURRENCY)
+            .collect::<Vec<_>>()
+            .await;
+        let mut result = SkillCandidateScan::default();
+        for mut scan in scans {
+            result.candidates.append(&mut scan.candidates);
+            result.diagnostics.append(&mut scan.diagnostics);
+        }
+        result
+    }
+
+    async fn scan_remote_skill_root(
+        fs: &dyn WorkspaceFileSystem,
+        entry: &RemoteSkillRootEntry,
+        workspace_root: &str,
+    ) -> SkillCandidateScan {
+        let mut scan = SkillCandidateScan::default();
+        match fs.is_dir(&entry.path).await {
+            Ok(true) => {}
+            Ok(false) => return scan,
+            Err(error) => {
+                scan.diagnostics
+                    .push(diagnostic(&entry.path, entry.source_id, error));
+                return scan;
+            }
+        }
+        let mut installation_sources = HashMap::new();
+        if entry.slot == "agents" {
+            let lock_path = format!("{workspace_root}/skills-lock.json");
+            match fs.exists(&lock_path).await {
+                Ok(true) => match fs.read_file_text(&lock_path).await {
+                    Ok(content) => {
+                        installation_sources = parse_skill_installation_sources(&content)
+                    }
+                    Err(error) => {
+                        scan.diagnostics
+                            .push(diagnostic(&lock_path, entry.source_id, error))
+                    }
+                },
+                Ok(false) => {}
+                Err(error) => scan
+                    .diagnostics
+                    .push(diagnostic(&lock_path, entry.source_id, error)),
+            }
+        }
+
+        let mut pending = VecDeque::from([(entry.path.clone(), 0usize)]);
+        let mut visited = HashSet::new();
+        while let Some((path, depth)) = pending.pop_front() {
+            if !visited.insert(path.clone()) {
+                continue;
+            }
+            if visited.len() > MAX_SCAN_DIRECTORIES || depth > MAX_SCAN_DEPTH {
+                scan.diagnostics.push(diagnostic(
+                    &path,
+                    entry.source_id,
+                    "Skill directory traversal limit reached (possibly a symbolic-link cycle)",
+                ));
+                if visited.len() > MAX_SCAN_DIRECTORIES {
+                    break;
+                }
+                continue;
+            }
+            if depth > 0 {
+                let skill_md = format!("{path}/SKILL.md");
+                match fs.is_file(&skill_md).await {
+                    Ok(true) => {
+                        match fs.read_file_text_bounded(&skill_md, MAX_SKILL_BYTES).await {
+                            Ok(Some(content)) => match Self::parse_skill_markdown(
+                                path.clone(),
+                                &content,
+                                SkillLocation::Project,
+                                false,
+                                entry.slot,
+                            ) {
+                                Ok(mut data) => {
+                                    if let Some(error) =
+                                        Self::apply_remote_openai_policy(&mut data, fs, &path).await
+                                    {
+                                        scan.diagnostics.push(diagnostic(
+                                            format!("{path}/agents/openai.yaml"),
+                                            entry.source_id,
+                                            error,
+                                        ));
+                                    }
+                                    let mut candidate = SkillCandidate::from_data(
+                                        data,
+                                        entry.slot,
+                                        entry.source_id,
+                                        entry.source_label,
+                                        PROJECT_SKILL_KEY_PREFIX,
+                                        entry.priority,
+                                        false,
+                                    );
+                                    set_nested_key(
+                                        &mut candidate,
+                                        path.strip_prefix(&format!("{}/", entry.path))
+                                            .expect("discovered child"),
+                                    );
+                                    candidate.info.installation_source =
+                                        installation_sources.get(&candidate.info.name).cloned();
+                                    scan.candidates.push(candidate);
+                                }
+                                Err(error) => scan.diagnostics.push(diagnostic(
+                                    &skill_md,
+                                    entry.source_id,
+                                    error,
+                                )),
+                            },
+                            Ok(None) => scan.diagnostics.push(diagnostic(
+                                &skill_md,
+                                entry.source_id,
+                                "SKILL.md exceeds the discovery size limit",
+                            )),
+                            Err(error) => {
+                                scan.diagnostics
+                                    .push(diagnostic(&skill_md, entry.source_id, error))
+                            }
+                        }
+                        continue;
+                    }
+                    Ok(false) => {}
+                    Err(error) => {
+                        scan.diagnostics
+                            .push(diagnostic(&skill_md, entry.source_id, error));
+                        continue;
+                    }
+                }
+            }
+            let mut children = match fs.read_dir_bounded(&path, MAX_DIRECTORY_ENTRIES + 1).await {
+                Ok(children) => children,
+                Err(error) => {
+                    scan.diagnostics
+                        .push(diagnostic(&path, entry.source_id, error));
+                    continue;
+                }
+            };
+            if children.len() > MAX_DIRECTORY_ENTRIES {
+                scan.diagnostics.push(diagnostic(
+                    &path,
+                    entry.source_id,
+                    "Skill directory entry limit reached",
+                ));
+                children.truncate(MAX_DIRECTORY_ENTRIES);
+            }
+            sort_remote_dir_entries(&mut children);
+            for child in children {
+                if child.name.is_empty()
+                    || child.name == "."
+                    || child.name == ".."
+                    || child.name.contains('/')
+                    || child.name.contains('\0')
+                {
+                    scan.diagnostics.push(diagnostic(
+                        &path,
+                        entry.source_id,
+                        "Invalid child name returned by workspace filesystem",
+                    ));
+                    continue;
+                }
+                let child_path = format!("{path}/{}", child.name);
+                let is_dir = if child.is_symlink {
+                    match fs.is_dir(&child_path).await {
+                        Ok(is_dir) => is_dir,
+                        Err(error) => {
+                            scan.diagnostics
+                                .push(diagnostic(&child_path, entry.source_id, error));
+                            false
+                        }
+                    }
+                } else {
+                    child.is_dir
+                };
+                if is_dir {
+                    if pending.len() + visited.len() >= MAX_SCAN_DIRECTORIES {
+                        scan.diagnostics.push(diagnostic(
+                            &path,
+                            entry.source_id,
+                            "Skill directory traversal limit reached",
+                        ));
+                        break;
+                    }
+                    pending.push_back((child_path, depth + 1));
+                }
+            }
+        }
+        scan.candidates = sort_skill_candidates_by_dir(scan.candidates);
+        scan
+    }
+
+    pub(super) async fn scan_skills_in_dir_with_status(entry: &SkillRootEntry) -> LocalSkillScan {
+        let mut scan = LocalSkillScan {
+            candidates: Vec::new(),
+            diagnostics: Vec::new(),
+            cacheable: local_source_path_is_cacheable(&entry.path).await,
+        };
+        match fs::metadata(&entry.path).await {
+            Ok(meta) if meta.is_dir() => {}
+            Ok(_) => {
+                scan.diagnostics.push(diagnostic(
+                    entry.path.to_string_lossy(),
+                    entry.source_id,
+                    "Skill root is not a directory",
+                ));
+                scan.cacheable = false;
+                return scan;
+            }
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => return scan,
+            Err(error) => {
+                scan.diagnostics.push(diagnostic(
+                    entry.path.to_string_lossy(),
+                    entry.source_id,
+                    error,
+                ));
+                scan.cacheable = false;
+                return scan;
+            }
+        }
+
+        let installation_sources = if let Some(lock_path) = skill_installation_lock_path(entry) {
+            scan.cacheable &= local_source_path_is_cacheable(&lock_path).await;
+            match fs::read_to_string(&lock_path).await {
+                Ok(content) => parse_skill_installation_sources(&content),
+                Err(error) => {
+                    if error.kind() != std::io::ErrorKind::NotFound {
+                        scan.diagnostics.push(diagnostic(
+                            lock_path.to_string_lossy(),
+                            entry.source_id,
+                            error,
+                        ));
+                        scan.cacheable = false;
+                    }
+                    HashMap::new()
+                }
+            }
+        } else {
+            HashMap::new()
+        };
+
+        let mut pending = VecDeque::from([(entry.path.clone(), 0usize)]);
+        let mut visited = HashSet::new();
+        while let Some((path, depth)) = pending.pop_front() {
+            scan.cacheable &= local_source_path_is_cacheable(&path).await;
+            let canonical = match fs::canonicalize(&path).await {
+                Ok(path) => path,
+                Err(error) => {
+                    scan.diagnostics.push(diagnostic(
+                        path.to_string_lossy(),
+                        entry.source_id,
+                        error,
+                    ));
+                    scan.cacheable = false;
+                    continue;
+                }
+            };
+            if !visited.insert(canonical) {
+                continue;
+            }
+            if visited.len() > MAX_SCAN_DIRECTORIES || depth > MAX_SCAN_DEPTH {
+                scan.diagnostics.push(diagnostic(
+                    path.to_string_lossy(),
+                    entry.source_id,
+                    "Skill directory traversal limit reached",
+                ));
+                scan.cacheable = false;
+                if visited.len() > MAX_SCAN_DIRECTORIES {
+                    break;
+                }
+                continue;
+            }
+
+            if depth > 0 {
+                let skill_md = path.join("SKILL.md");
+                scan.cacheable &= local_source_path_is_cacheable(&skill_md).await;
+                match fs::File::open(&skill_md).await {
+                    Ok(file) => {
+                        let mut content = String::new();
+                        let read = file
+                            .take((MAX_SKILL_BYTES + 1) as u64)
+                            .read_to_string(&mut content)
+                            .await;
+                        if let Err(error) = read {
+                            scan.diagnostics.push(diagnostic(
+                                skill_md.to_string_lossy(),
+                                entry.source_id,
+                                error,
+                            ));
+                            scan.cacheable = false;
+                        } else if content.len() > MAX_SKILL_BYTES {
+                            scan.diagnostics.push(diagnostic(
+                                skill_md.to_string_lossy(),
+                                entry.source_id,
+                                "SKILL.md exceeds the discovery size limit",
+                            ));
+                        } else {
+                            match Self::parse_skill_markdown(
+                                path.to_string_lossy().into_owned(),
+                                &content,
+                                entry.level,
+                                false,
+                                entry.slot,
+                            ) {
+                                Ok(mut data) => {
+                                    let (cacheable, policy_error) =
+                                        Self::apply_local_openai_policy(&mut data, &path).await;
+                                    scan.cacheable &= cacheable;
+                                    if let Some(error) = policy_error {
+                                        scan.diagnostics.push(diagnostic(
+                                            path.join("agents/openai.yaml").to_string_lossy(),
+                                            entry.source_id,
+                                            error,
+                                        ));
+                                    }
+                                    let mut candidate = SkillCandidate::from_data(
+                                        data,
+                                        entry.slot,
+                                        entry.source_id,
+                                        entry.source_label,
+                                        entry.level.as_str(),
+                                        entry.priority,
+                                        entry.is_builtin,
+                                    );
+                                    let relative_dir = path
+                                        .strip_prefix(&entry.path)
+                                        .expect("discovered child")
+                                        .components()
+                                        .map(|component| component.as_os_str().to_string_lossy())
+                                        .collect::<Vec<_>>()
+                                        .join("/");
+                                    set_nested_key(&mut candidate, &relative_dir);
+                                    candidate.info.installation_source =
+                                        installation_sources.get(&candidate.info.name).cloned();
+                                    scan.candidates.push(candidate);
+                                }
+                                Err(error) => scan.diagnostics.push(diagnostic(
+                                    skill_md.to_string_lossy(),
+                                    entry.source_id,
+                                    error,
+                                )),
+                            }
+                        }
+                        // A skill is a package boundary; its reference examples
+                        // and scripts are not independent installed skills.
+                        continue;
+                    }
+                    Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
+                    Err(error) => {
+                        scan.diagnostics.push(diagnostic(
+                            skill_md.to_string_lossy(),
+                            entry.source_id,
+                            error,
+                        ));
+                        scan.cacheable = false;
+                        continue;
+                    }
+                }
+            }
+
+            let mut entries = match fs::read_dir(&path).await {
+                Ok(entries) => entries,
+                Err(error) => {
+                    scan.diagnostics.push(diagnostic(
+                        path.to_string_lossy(),
+                        entry.source_id,
+                        error,
+                    ));
+                    scan.cacheable = false;
+                    continue;
+                }
+            };
+            let mut children = Vec::new();
+            let mut count = 0;
+            loop {
+                let child = match entries.next_entry().await {
+                    Ok(Some(child)) => child,
+                    Ok(None) => break,
+                    Err(error) => {
+                        scan.diagnostics.push(diagnostic(
+                            path.to_string_lossy(),
+                            entry.source_id,
+                            error,
+                        ));
+                        scan.cacheable = false;
+                        break;
+                    }
+                };
+                count += 1;
+                if count > MAX_DIRECTORY_ENTRIES {
+                    scan.diagnostics.push(diagnostic(
+                        path.to_string_lossy(),
+                        entry.source_id,
+                        "Skill directory entry limit reached",
+                    ));
+                    scan.cacheable = false;
+                    break;
+                }
+                let child_path = child.path();
+                if depth == 0
+                    && entry.slot == OPENBITFUN_USER_SKILL_SLOT
+                    && child.file_name() == OPENBITFUN_SYSTEM_SKILL_DIR
+                {
+                    continue;
+                }
+                scan.cacheable &= local_source_path_is_cacheable(&child_path).await;
+                match fs::metadata(&child_path).await {
+                    Ok(meta) if meta.is_dir() => children.push(child_path),
+                    Ok(_) => {}
+                    Err(error) => {
+                        scan.diagnostics.push(diagnostic(
+                            child_path.to_string_lossy(),
+                            entry.source_id,
+                            error,
+                        ));
+                        scan.cacheable = false;
+                    }
+                }
+            }
+            children.sort();
+            for child in children {
+                if pending.len() + visited.len() >= MAX_SCAN_DIRECTORIES {
+                    scan.diagnostics.push(diagnostic(
+                        path.to_string_lossy(),
+                        entry.source_id,
+                        "Skill directory traversal limit reached",
+                    ));
+                    scan.cacheable = false;
+                    break;
+                }
+                pending.push_back((child, depth + 1));
+            }
+        }
+        scan.candidates = sort_skill_candidates_by_dir(scan.candidates);
+        scan
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::agentic::workspace::WorkspaceDirEntry;
+    use async_trait::async_trait;
+
+    fn markdown(name: &str) -> String {
+        format!("---\nname: {name}\ndescription: fixture\n---\n{name} body\n")
+    }
+
+    #[tokio::test]
+    async fn nested_local_skills_keep_distinct_keys_and_partial_failures() {
+        let temp = tempfile::tempdir().unwrap();
+        for path in [
+            ".system/shared",
+            "interactive/shared",
+            "direct",
+            "direct/examples/ignored",
+            "broken",
+        ] {
+            std::fs::create_dir_all(temp.path().join(path)).unwrap();
+            std::fs::write(
+                temp.path().join(path).join("SKILL.md"),
+                if path == "broken" {
+                    "invalid".into()
+                } else {
+                    markdown("shared")
+                },
+            )
+            .unwrap();
+        }
+        let entry = SkillRootEntry {
+            path: temp.path().to_path_buf(),
+            level: SkillLocation::User,
+            slot: "home.codex",
+            source_id: "codex",
+            source_label: "Codex",
+            priority: 0,
+            is_builtin: false,
+        };
+        let scan = SkillRegistry::scan_skills_in_dir_with_status(&entry).await;
+        let keys: HashSet<_> = scan
+            .candidates
+            .iter()
+            .map(|item| item.info.key.as_str())
+            .collect();
+        assert_eq!(
+            keys,
+            HashSet::from([
+                "user::home.codex::.system/shared",
+                "user::home.codex::interactive/shared",
+                "user::home.codex::direct"
+            ])
+        );
+        assert_eq!(scan.diagnostics.len(), 1);
+        assert!(
+            scan.diagnostics[0].path.ends_with("broken\\SKILL.md")
+                || scan.diagnostics[0].path.ends_with("broken/SKILL.md")
+        );
+    }
+
+    struct RemoteFixture;
+    #[async_trait]
+    impl WorkspaceFileSystem for RemoteFixture {
+        async fn read_file(&self, path: &str) -> anyhow::Result<Vec<u8>> {
+            Ok(self.read_file_text(path).await?.into_bytes())
+        }
+        async fn read_file_text(&self, path: &str) -> anyhow::Result<String> {
+            if path.ends_with("/bad/SKILL.md") {
+                return Ok("invalid".into());
+            }
+            if path.ends_with("/shared/SKILL.md") {
+                return Ok(markdown("shared"));
+            }
+            anyhow::bail!("missing fixture file")
+        }
+        async fn write_file(&self, _: &str, _: &[u8]) -> anyhow::Result<()> {
+            anyhow::bail!("read-only fixture")
+        }
+        async fn exists(&self, path: &str) -> anyhow::Result<bool> {
+            self.is_file(path).await
+        }
+        async fn is_file(&self, path: &str) -> anyhow::Result<bool> {
+            Ok(path.ends_with("/shared/SKILL.md") || path.ends_with("/bad/SKILL.md"))
+        }
+        async fn is_dir(&self, path: &str) -> anyhow::Result<bool> {
+            Ok(path.starts_with("/remote/.codex/skills"))
+        }
+        async fn read_dir(&self, path: &str) -> anyhow::Result<Vec<WorkspaceDirEntry>> {
+            if path.ends_with("/unreadable") {
+                anyhow::bail!("permission denied");
+            }
+            let names = if path == "/remote/.codex/skills" {
+                vec![".system", "linked", "bad", "unreadable", "loop"]
+            } else if path.ends_with("/loop") {
+                vec!["loop"]
+            } else {
+                vec!["shared"]
+            };
+            Ok(names
+                .into_iter()
+                .map(|name| WorkspaceDirEntry {
+                    name: name.into(),
+                    path: format!("{path}/{name}"),
+                    is_dir: name != "linked",
+                    is_symlink: name == "linked" || name == "loop",
+                    modified: None,
+                })
+                .collect())
+        }
+    }
+
+    #[tokio::test]
+    async fn remote_nested_links_errors_cycles_and_project_priority() {
+        let scan =
+            SkillRegistry::scan_remote_project_skills_with_diagnostics(&RemoteFixture, "/remote")
+                .await;
+        assert_eq!(scan.candidates.len(), 2);
+        assert!(scan
+            .candidates
+            .iter()
+            .any(|item| item.info.key == "project::codex::linked/shared"));
+        assert!(scan
+            .candidates
+            .iter()
+            .any(|item| item.info.key == "project::codex::.system/shared"));
+        assert!(scan
+            .diagnostics
+            .iter()
+            .any(|item| item.message.contains("permission denied")));
+        assert!(scan
+            .diagnostics
+            .iter()
+            .any(|item| item.path.ends_with("/bad/SKILL.md")));
+        assert!(scan
+            .diagnostics
+            .iter()
+            .any(|item| item.message.contains("traversal limit")));
+        let mut user_candidate = scan.candidates[0].clone();
+        user_candidate.info.key = "user::home.claude::shared".into();
+        user_candidate.info.level = SkillLocation::User;
+        user_candidate.priority = 0;
+        let merged = SkillRegistry::merge_remote_skill_scans(
+            SkillCandidateScan {
+                candidates: vec![user_candidate],
+                diagnostics: vec![],
+            },
+            scan,
+        );
+        let resolved = resolve_visible_skills(merged.candidates);
+        assert_eq!(resolved.len(), 1);
+        assert_eq!(resolved[0].level, SkillLocation::Project);
+    }
+}
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/skills/types.rs b/src/crates/assembly/core/src/agentic/tools/implementations/skills/types.rs
index 3ba120f93f..ac8d1b88c7 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/skills/types.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/skills/types.rs
@@ -4,5 +4,5 @@
 
 pub use openbitfun_agent_runtime::skills::{
     render_loaded_skill_for_assistant, ModeSkillInfo, ModeSkillStateReason, SkillData, SkillInfo,
-    SkillLocation, SkillParseError,
+    SkillLocation, SkillParseError, SkillScanDiagnostic, SkillScanReport,
 };
diff --git a/src/crates/execution/agent-runtime/src/prompt.rs b/src/crates/execution/agent-runtime/src/prompt.rs
index 8a04ba09f6..02714bb8ab 100644
--- a/src/crates/execution/agent-runtime/src/prompt.rs
+++ b/src/crates/execution/agent-runtime/src/prompt.rs
@@ -6,6 +6,7 @@ use serde::{Deserialize, Serialize};
 const SKILL_LISTING_TITLE: &str = "# Skill Listing";
 const SKILL_LISTING_GUIDANCE: &str = r#"A skill is a set of instructions provided through a `SKILL.md` source.
 If the user names a skill (with `[$SkillName]` or plain text) OR the task clearly matches a skill's description shown below, you must use that skill for that turn. Multiple mentions mean use them all. Do not carry skills across turns unless re-mentioned.
+An explicit `[$scope::source::directory]` reference selects an exact installed skill. Pass the complete stable key to the Skill tool unchanged, even when another source has the same skill name. If that key is missing or disabled, report the error instead of substituting a same-named skill.
 Below is the list of skills that can be used with the Skill tool. Each entry includes a name and description"#;
 const AGENT_LISTING_TITLE: &str = "# Agent Listing";
 const AGENT_LISTING_GUIDANCE: &str = "Available subagent types for the Task tool:";
diff --git a/src/crates/execution/agent-runtime/src/skills/mod.rs b/src/crates/execution/agent-runtime/src/skills/mod.rs
index fad7e3c1c6..055a45dae7 100644
--- a/src/crates/execution/agent-runtime/src/skills/mod.rs
+++ b/src/crates/execution/agent-runtime/src/skills/mod.rs
@@ -44,5 +44,5 @@ pub use selection::{
 };
 pub use types::{
     render_loaded_skill_for_assistant, ModeSkillInfo, ModeSkillStateReason, SkillData, SkillInfo,
-    SkillLocation, SkillParseError,
+    SkillLocation, SkillParseError, SkillScanDiagnostic, SkillScanReport,
 };
diff --git a/src/crates/execution/agent-runtime/src/skills/types.rs b/src/crates/execution/agent-runtime/src/skills/types.rs
index 3782242eae..07fb4aadd8 100644
--- a/src/crates/execution/agent-runtime/src/skills/types.rs
+++ b/src/crates/execution/agent-runtime/src/skills/types.rs
@@ -7,6 +7,38 @@ use std::path::Path;
 const CLAUDE_DESCRIPTION_MAX_CHARS: usize = 1536;
 const CLAUDE_ARGUMENT_NAMES_MAX: usize = 32;
 
+/// A discovery problem is separate from the usable skill inventory.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct SkillScanDiagnostic {
+    pub path: String,
+    pub source_id: String,
+    pub message: String,
+}
+
+impl SkillScanDiagnostic {
+    pub fn to_xml(&self) -> String {
+        let text = format!(
+            "Skill discovery incomplete at {} ({}): {}",
+            self.path, self.source_id, self.message
+        );
+        let escaped = text
+            .replace('&', "&amp;")
+            .replace('<', "&lt;")
+            .replace('>', "&gt;");
+        format!("<skill_discovery_warning>{escaped}</skill_discovery_warning>")
+    }
+}
+
+/// Opt-in report; legacy list consumers continue to receive the skills array.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SkillScanReport<T = SkillInfo> {
+    pub skills: Vec<T>,
+    #[serde(default)]
+    pub diagnostics: Vec<SkillScanDiagnostic>,
+}
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub(crate) enum SkillSourceDialect {
     AgentSkills,
diff --git a/src/crates/execution/agent-runtime/tests/agent_definition_contracts/skill_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_definition_contracts/skill_contracts.rs
index 884f8dd467..cfd44bfc06 100644
--- a/src/crates/execution/agent-runtime/tests/agent_definition_contracts/skill_contracts.rs
+++ b/src/crates/execution/agent-runtime/tests/agent_definition_contracts/skill_contracts.rs
@@ -1153,3 +1153,21 @@ fn explicit_invocation_reaches_default_hidden_agent_browser() {
         }
     }
 }
+
+#[test]
+fn skill_scan_reports_tolerate_older_shapes_and_escape_diagnostics() {
+    use openbitfun_agent_runtime::skills::{SkillScanDiagnostic, SkillScanReport};
+    let legacy = serde_json::json!({"skills": ["pdf"]});
+    let report: SkillScanReport<String> = serde_json::from_value(legacy.clone()).unwrap();
+    assert!(report.diagnostics.is_empty());
+    let roundtrip: SkillScanReport<String> =
+        serde_json::from_value(serde_json::to_value(report).unwrap()).unwrap();
+    assert_eq!(roundtrip.skills, vec!["pdf"]);
+    let diagnostic = SkillScanDiagnostic {
+        path: "/remote/<path>".into(),
+        source_id: "codex".into(),
+        message: "read & parse failed".into(),
+    };
+    assert!(diagnostic.to_xml().contains("&lt;path&gt;"));
+    assert!(diagnostic.to_xml().contains("read &amp; parse failed"));
+}
diff --git a/src/web-ui/src/app/scenes/skills/SkillsScene.scss b/src/web-ui/src/app/scenes/skills/SkillsScene.scss
index 093e7f83c6..a45618f52a 100644
--- a/src/web-ui/src/app/scenes/skills/SkillsScene.scss
+++ b/src/web-ui/src/app/scenes/skills/SkillsScene.scss
@@ -1083,3 +1083,13 @@ $skills-installed-columns: minmax(200px, 1fr) minmax(90px, 0.24fr) minmax(110px,
 .skills-main > .skills-main__empty {
   margin: var(--openbitfun-space-4) var(--openbitfun-space-6);
 }
+
+.skills-main__diagnostics {
+  padding: 8px 12px;
+  max-height: 160px;
+  overflow: auto;
+  overflow-wrap: anywhere;
+  font-size: var(--openbitfun-type-flow-support-font-size);
+
+  summary { cursor: pointer; }
+}
diff --git a/src/web-ui/src/app/scenes/skills/SkillsScene.tsx b/src/web-ui/src/app/scenes/skills/SkillsScene.tsx
index f449fefbe9..66e4e2ffeb 100644
--- a/src/web-ui/src/app/scenes/skills/SkillsScene.tsx
+++ b/src/web-ui/src/app/scenes/skills/SkillsScene.tsx
@@ -459,7 +459,14 @@ const SkillsScene: React.FC = () => {
                       </div>
                     )}
 
-                    {!installed.loading && !installed.error && installedFiltered.length === 0 && (
+                    {!installed.loading && !installed.error && (
+                      installed.diagnostics.length > 0 ? <details className="skills-main__diagnostics">
+                        <summary>{t('list.scanIncomplete')}</summary>
+                        {installed.diagnostics.map((item, index) => <p key={index}>{item.path}: {item.message}</p>)}
+                      </details> : !installed.diagnosticsAvailable && <p role="status">{t('list.diagnosticsUnavailable')}</p>
+                    )}
+
+                    {!installed.loading && !installed.error && installedFiltered.length === 0 && installed.diagnostics.length === 0 && (
                       <div className="skills-main__empty" data-testid="skill-list-empty" data-openbitfun-scene="skills" data-openbitfun-part="empty">
                         <Icon glyph={Package} size="lg" />
                         <span>
@@ -522,7 +529,7 @@ const SkillsScene: React.FC = () => {
                                   <OverflowText behavior="marquee" title="">{skill.name}</OverflowText>
                                 </span>
                                 {skill.description?.trim() && (
-                                  <OverflowText lines={2} className="skills-card__desc" data-testid="skill-list-item-description" data-openbitfun-scene="skills" data-openbitfun-part="installedCardDescription">{skill.description}</OverflowText>
+                                  <OverflowText lines={2} title="" className="skills-card__desc" data-testid="skill-list-item-description" data-openbitfun-scene="skills" data-openbitfun-part="installedCardDescription">{skill.description}</OverflowText>
                                 )}
                                 <div className="skills-card__status-badges">
                                   {skill.isBuiltin && (
diff --git a/src/web-ui/src/app/scenes/skills/hooks/useInstalledSkills.test.tsx b/src/web-ui/src/app/scenes/skills/hooks/useInstalledSkills.test.tsx
index 9f7b55fe23..3c2e9e2c55 100644
--- a/src/web-ui/src/app/scenes/skills/hooks/useInstalledSkills.test.tsx
+++ b/src/web-ui/src/app/scenes/skills/hooks/useInstalledSkills.test.tsx
@@ -8,6 +8,7 @@ import { useInstalledSkills } from './useInstalledSkills';
 import type { InstalledFilter } from '../skillsSceneStore';
 
 const getSkillConfigsMock = vi.hoisted(() => vi.fn());
+const diagnosticsMock = vi.hoisted(() => ({ items: [] as Array<{path: string; sourceId: string; message: string}> }));
 const getGlobalSkillSettingsMock = vi.hoisted(() => vi.fn());
 const setGlobalSkillDisabledMock = vi.hoisted(() => vi.fn());
 const deleteSkillMock = vi.hoisted(() => vi.fn());
@@ -24,7 +25,7 @@ vi.mock('react-i18next', () => ({
 }));
 vi.mock('@/infrastructure/api', () => ({
   configAPI: {
-    getSkillConfigs: getSkillConfigsMock,
+    getSkillScanReport: async (...args: unknown[]) => ({ skills: await getSkillConfigsMock(...args), diagnostics: diagnosticsMock.items, diagnosticsAvailable: true }),
     getGlobalSkillSettings: getGlobalSkillSettingsMock,
     setGlobalSkillDisabled: setGlobalSkillDisabledMock,
     validateSkillPath: validateSkillPathMock,
@@ -80,6 +81,7 @@ describe('useInstalledSkills', () => {
     notificationMocks.warning.mockReset();
     notificationMocks.error.mockReset();
     currentInstalled = null;
+    diagnosticsMock.items = [];
   });
 
   afterEach(async () => {
@@ -88,7 +90,17 @@ describe('useInstalledSkills', () => {
     vi.useRealTimers();
   });
 
-  it('does not query desktop skill configuration during a remote connection', async () => {
+  it('preserves available skills alongside discovery failures', async () => {
+    const skills = [{ key: 'user::codex::good', name: 'good', sourceId: 'codex', level: 'user', path: '/skills/good' }];
+    getSkillConfigsMock.mockResolvedValue(skills);
+    diagnosticsMock.items = [{ path: '/skills/bad/SKILL.md', sourceId: 'codex', message: 'missing description' }];
+    await act(async () => root.render(<Harness enabled />));
+    expect(currentInstalled?.skills).toEqual(skills);
+    expect(currentInstalled?.diagnostics).toEqual(diagnosticsMock.items);
+    expect(currentInstalled?.error).toBeNull();
+  });
+
+  it('does not query desktop skill configuration during a remote connection' , async () => {
     await act(async () => {
       root.render(<Harness enabled={false} />);
       await Promise.resolve();
diff --git a/src/web-ui/src/app/scenes/skills/hooks/useInstalledSkills.ts b/src/web-ui/src/app/scenes/skills/hooks/useInstalledSkills.ts
index 44118a4a19..d8cfc18f44 100644
--- a/src/web-ui/src/app/scenes/skills/hooks/useInstalledSkills.ts
+++ b/src/web-ui/src/app/scenes/skills/hooks/useInstalledSkills.ts
@@ -2,7 +2,7 @@ import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } fr
 import { open } from '@tauri-apps/plugin-dialog';
 import { useTranslation } from 'react-i18next';
 import { configAPI } from '@/infrastructure/api';
-import type { SkillInfo, SkillLevel, SkillValidationResult } from '@/infrastructure/config/types';
+import type { SkillInfo, SkillLevel, SkillValidationResult, SkillScanDiagnostic } from '@/infrastructure/config/types';
 import { canDeleteSkill, getSkillSourceId, getSkillSourceLabel } from '@/infrastructure/config/skillSourcePresentation';
 import { useWorkspaceManagerSync } from '@/infrastructure/hooks/useWorkspaceManagerSync';
 import { useNotification } from '@/shared/notification-system';
@@ -33,6 +33,8 @@ export function useInstalledSkills({
   const { workspacePath, hasWorkspace, isRemoteWorkspace } = useWorkspaceManagerSync();
 
   const [skills, setSkills] = useState<SkillInfo[]>([]);
+  const [diagnostics, setDiagnostics] = useState<SkillScanDiagnostic[]>([]);
+  const [diagnosticsAvailable, setDiagnosticsAvailable] = useState(true);
   const [globallyDisabledSkillKeys, setGloballyDisabledSkillKeys] = useState<Set<string>>(new Set());
   const [savingGlobalSkillKey, setSavingGlobalSkillKey] = useState<string | null>(null);
   const [loading, setLoading] = useState(true);
@@ -77,7 +79,7 @@ export function useInstalledSkills({
       setLoading(true);
       setError(null);
       const [list, globalSettings] = await Promise.all([
-        configAPI.getSkillConfigs({
+        configAPI.getSkillScanReport({
           forceRefresh,
           workspacePath: workspacePath || undefined,
         }),
@@ -86,7 +88,9 @@ export function useInstalledSkills({
       if (requestId !== loadRequestIdRef.current || !capabilityIsCurrent(capabilityEpoch)) {
         return;
       }
-      setSkills(list);
+      setSkills(list.skills);
+      setDiagnostics(list.diagnostics);
+      setDiagnosticsAvailable(list.diagnosticsAvailable);
       setGloballyDisabledSkillKeys(new Set(globalSettings.globallyDisabledUserSkillKeys));
     } catch (err) {
       if (requestId !== loadRequestIdRef.current || !capabilityIsCurrent(capabilityEpoch)) {
@@ -109,6 +113,8 @@ export function useInstalledSkills({
     setIsAdding(false);
     if (!enabled) {
       setSkills([]);
+      setDiagnostics([]);
+      setDiagnosticsAvailable(true);
       setGloballyDisabledSkillKeys(new Set());
       setSavingGlobalSkillKey(null);
       setError(null);
@@ -357,6 +363,8 @@ export function useInstalledSkills({
 
   return {
     skills,
+    diagnostics,
+    diagnosticsAvailable,
     globallyDisabledSkillKeys,
     savingGlobalSkillKey,
     filteredSkills,
diff --git a/src/web-ui/src/flow_chat/components/ChatContextPicker.scss b/src/web-ui/src/flow_chat/components/ChatContextPicker.scss
index 12cc65f345..d236e9f190 100644
--- a/src/web-ui/src/flow_chat/components/ChatContextPicker.scss
+++ b/src/web-ui/src/flow_chat/components/ChatContextPicker.scss
@@ -141,6 +141,28 @@
 
   &__skill-description {
     inline-size: 100%;
+    // This picker uses a visible ellipsis instead of the shared resting fade.
+    -webkit-mask-image: none;
+    mask-image: none;
+  }
+
+  &__skill-option:not(:hover):not(:focus-visible) &__skill-description > [data-overflow-content] {
+    display: block;
+    min-inline-size: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    // Virtual selection alone must not start the marquee on initial opening.
+    animation: none;
+    transform: none;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    &__skill-description > [data-overflow-content] {
+      display: block;
+      min-inline-size: 0;
+      overflow: hidden;
+      text-overflow: ellipsis;
+    }
   }
   
   &__footer {
@@ -177,3 +199,13 @@
     animation: none;
   }
 }
+
+.chat-context-picker__diagnostics {
+  padding: 8px 12px;
+  max-height: 160px;
+  overflow: auto;
+  overflow-wrap: anywhere;
+  font-size: var(--openbitfun-type-flow-support-font-size);
+
+  summary { cursor: pointer; }
+}
diff --git a/src/web-ui/src/flow_chat/components/ChatContextPicker.tsx b/src/web-ui/src/flow_chat/components/ChatContextPicker.tsx
index 4b615488e3..79973147d3 100644
--- a/src/web-ui/src/flow_chat/components/ChatContextPicker.tsx
+++ b/src/web-ui/src/flow_chat/components/ChatContextPicker.tsx
@@ -39,6 +39,7 @@ import {
   workspaceReferenceItems,
   type FileItem,
 } from './workspaceReferenceItems';
+import type { SkillScanDiagnostic } from '@/infrastructure/config/types';
 import './ChatContextPicker.scss';
 
 const log = createLogger('ChatContextPicker');
@@ -64,6 +65,8 @@ export interface ChatContextPickerProps {
   skills?: readonly ContextPickerSkill[];
   skillsLoading?: boolean;
   skillsLoadFailed?: boolean;
+  skillDiagnostics?: readonly SkillScanDiagnostic[];
+  skillDiagnosticsAvailable?: boolean;
   onRetrySkills?: () => void;
   onSelectSkill?: (skill: ContextPickerSkill) => void;
   onAddImage?: () => void;
@@ -74,6 +77,8 @@ export interface ContextPickerSkill {
   name: string;
   description?: string;
   argumentHint?: string | null;
+  /** Winner selected by the host registry after source precedence and mode policy. */
+  selectedForRuntime?: boolean;
 }
 
 export type ChatContextPickerEntryView = 'sources' | 'files';
@@ -127,6 +132,8 @@ export const ChatContextPicker: React.FC<ChatContextPickerProps> = ({
   skills = [],
   skillsLoading = false,
   skillsLoadFailed = false,
+  skillDiagnostics = [],
+  skillDiagnosticsAvailable = true,
   onRetrySkills,
   onSelectSkill,
   onAddImage,
@@ -444,8 +451,8 @@ export const ChatContextPicker: React.FC<ChatContextPickerProps> = ({
     return skills
       .filter(skill => {
         const normalizedName = skill.name.trim().toLocaleLowerCase();
-        if (!normalizedName || seenNames.has(normalizedName)) return false;
-        seenNames.add(normalizedName);
+        if (skill.selectedForRuntime === false || !normalizedName || seenNames.has(skill.name)) return false;
+        seenNames.add(skill.name);
         if (!normalizedSearchQuery) return true;
         return [skill.name, skill.description, skill.argumentHint]
           .filter((value): value is string => Boolean(value?.trim()))
@@ -828,6 +835,7 @@ export const ChatContextPicker: React.FC<ChatContextPickerProps> = ({
                 <ListboxOption data-overflow-trigger
                   active={index === selectedIndex}
                   className={skill ? 'chat-context-picker__skill-option' : undefined}
+                  title={skill ? '' : undefined}
                   key={key}
                   data-index={index}
                   data-openbitfun-context-kind={selection.kind === 'source' || selection.kind === 'action'
@@ -849,7 +857,7 @@ export const ChatContextPicker: React.FC<ChatContextPickerProps> = ({
                           : file?.isDirectory
                             ? <Icon name="folder" size="lg" aria-hidden="true" />
                             : <File aria-hidden="true" />}
-                  metadata={skill && index === selectedIndex && skillDescription
+                  metadata={skill && skillDescription
                     ? (
                         <OverflowText
                           aria-label={skillDescription}
@@ -857,8 +865,7 @@ export const ChatContextPicker: React.FC<ChatContextPickerProps> = ({
                           className="chat-context-picker__skill-description"
                           data-openbitfun-component="chat-context-picker"
                           data-openbitfun-part="skillDescription"
-                          marqueeActive
-                          title={skillDescription}
+                          title=""
                         >
                           {skillDescription}
                         </OverflowText>
@@ -896,6 +903,12 @@ export const ChatContextPicker: React.FC<ChatContextPickerProps> = ({
         )}
         </Listbox>
       </div>
+      {(view === 'skills' || isSearchMode) && !skillsLoading && !skillsLoadFailed && (
+        skillDiagnostics.length > 0 ? <details className="chat-context-picker__diagnostics">
+          <summary>{t('contextPicker.skillsIncomplete')}</summary>
+          {skillDiagnostics.map((item, index) => <p key={index}>{item.path}: {item.message}</p>)}
+        </details> : !skillDiagnosticsAvailable && <p role="status">{t('contextPicker.skillsDiagnosticsUnavailable')}</p>
+      )}
       <div data-openbitfun-component="chat-context-picker" data-openbitfun-part="footer" className="chat-context-picker__footer">
         <span><KeyHint>↑</KeyHint><KeyHint>↓</KeyHint> {t('contextPicker.navHint')}</span>
         {!isSearchMode && (view === 'sources' || view === 'files') && (
diff --git a/src/web-ui/src/flow_chat/components/ChatContextPickerOverlay.test.tsx b/src/web-ui/src/flow_chat/components/ChatContextPickerOverlay.test.tsx
index 142c83c250..60af2d04ed 100644
--- a/src/web-ui/src/flow_chat/components/ChatContextPickerOverlay.test.tsx
+++ b/src/web-ui/src/flow_chat/components/ChatContextPickerOverlay.test.tsx
@@ -97,6 +97,17 @@ const option = (kind: string) => document.querySelector<HTMLElement>(
 );
 
 describe('ChatContextPicker overlay', () => {
+  it('shows only the runtime winner for a name without exposing its key', async () => {
+    const chosen = vi.fn();
+    const skills = [{ name: 'pdf', key: 'user::codex::pdf', selectedForRuntime: false }, { name: 'pdf', key: 'project::codex::pdf', selectedForRuntime: true }];
+    await act(async () => root.render(<Harness searchQuery="pdf" skills={skills} onSelectSkill={chosen} />));
+    const options = document.querySelectorAll<HTMLElement>('[data-openbitfun-context-kind="skill"]');
+    expect(options).toHaveLength(1);
+    expect(options[0].textContent).toBe('pdf');
+    await act(async () => options[0].click());
+    expect(chosen).toHaveBeenCalledWith(skills[1]);
+  });
+
   let container: HTMLDivElement;
   let root: Root;
 
@@ -290,9 +301,13 @@ describe('ChatContextPicker overlay', () => {
       .toBeNull();
     expect(skillOptions[0]?.querySelector('[data-openbitfun-part="metadata"]')?.textContent)
       .toBe('Work with PDFs');
-    expect(skillOptions[0]?.querySelector('[data-overflow-behavior="marquee"][data-marquee-active="true"]')
-      ?.getAttribute('data-marquee-active')).toBe('true');
-    expect(skillOptions[1]?.querySelector('[data-openbitfun-part="metadata"]')).toBeNull();
+    const description = skillOptions[0]?.querySelector('[data-openbitfun-part="skillDescription"]');
+    expect(description?.getAttribute('data-marquee-active')).toBeNull();
+    expect(description?.getAttribute('title')).toBe('');
+    expect(skillOptions[0]?.getAttribute('title')).toBe('');
+    expect(skillOptions[0]?.querySelector('[data-openbitfun-part="label"]')?.getAttribute('title')).toBe('');
+    expect(skillOptions[1]?.querySelector('[data-openbitfun-part="metadata"]')?.textContent)
+      .toBe('Build presentations');
     expect(workspaceAPI.getDirectoryChildren).not.toHaveBeenCalled();
 
     await act(async () => {
@@ -303,7 +318,7 @@ describe('ChatContextPicker overlay', () => {
       }));
     });
 
-    expect(skillOptions[0]?.querySelector('[data-openbitfun-part="metadata"]')).toBeNull();
+    expect(skillOptions[0]?.querySelector('[data-openbitfun-part="metadata"]')?.textContent).toBe('Work with PDFs');
     expect(skillOptions[1]?.querySelector('[data-openbitfun-part="metadata"]')?.textContent)
       .toBe('Build presentations');
 
diff --git a/src/web-ui/src/flow_chat/components/ChatInput.tsx b/src/web-ui/src/flow_chat/components/ChatInput.tsx
index ed7e528ba2..76715c5c10 100644
--- a/src/web-ui/src/flow_chat/components/ChatInput.tsx
+++ b/src/web-ui/src/flow_chat/components/ChatInput.tsx
@@ -1482,6 +1482,8 @@ export const ChatInput: React.FC<ChatInputProps> = ({
     loading: resolvedModeSkillsLoading,
     hasLoaded: resolvedModeSkillsLoaded,
     failed: resolvedModeSkillsLoadFailed,
+    diagnostics: resolvedSkillDiagnostics,
+    diagnosticsAvailable: resolvedSkillDiagnosticsAvailable,
     retry: retryResolvedModeSkills,
   } = useResolvedModeSkills({
     enabled: isSceneActive && canUseSkillsForTarget && (
@@ -1494,12 +1496,26 @@ export const ChatInput: React.FC<ChatInputProps> = ({
     modeId: effectiveSendAgentType,
     workspacePath: targetWorkspacePath,
   });
+  const skillReferenceNames = useMemo(
+    () => Object.fromEntries(resolvedModeSkills.map(skill => [skill.key, skill.name])),
+    [resolvedModeSkills],
+  );
   const userInvocableSkills = useMemo(
     // Management keeps the full catalog; invocation surfaces apply both runtime and author visibility.
     () => resolvedModeSkills.filter(isSkillAvailableForUserInvocation),
     [resolvedModeSkills]
   );
 
+  const duplicateSkillNames = useMemo(() => {
+    const seen = new Set<string>();
+    const duplicates = new Set<string>();
+    for (const skill of userInvocableSkills) {
+      if (seen.has(skill.name)) duplicates.add(skill.name);
+      seen.add(skill.name);
+    }
+    return duplicates;
+  }, [userInvocableSkills]);
+
   const quickSkillShortcuts = useMemo(
     () => canUseSkillsForTarget
       ? resolveChatInputQuickSkillShortcuts(resolvedModeSkills)
@@ -3184,12 +3200,12 @@ export const ChatInput: React.FC<ChatInputProps> = ({
     }
 
     const q = (slashCommandState.query || '').trim().toLowerCase();
-    const seenNames = new Set<string>();
+    const seenKeys = new Set<string>();
     return userInvocableSkills
       .filter(skill => {
         const normalizedName = skill.name.trim();
         const normalizedNameKey = normalizedName.toLowerCase();
-        if (!normalizedName || seenNames.has(normalizedNameKey)) {
+        if (!normalizedName || seenKeys.has(skill.key)) {
           return false;
         }
         if (!isSlashAddressableSkillName(normalizedName)) {
@@ -3201,7 +3217,7 @@ export const ChatInput: React.FC<ChatInputProps> = ({
           normalizedNameKey.includes(q) ||
           skill.description.toLowerCase().includes(q);
         if (matches) {
-          seenNames.add(normalizedNameKey);
+          seenKeys.add(skill.key);
         }
         return matches;
       })
@@ -3209,7 +3225,7 @@ export const ChatInput: React.FC<ChatInputProps> = ({
         kind: 'skill' as const,
         id: skill.key,
         command: `/${skill.name}`,
-        label: [skill.argumentHint?.trim(), skill.description || skill.name]
+        label: [duplicateSkillNames.has(skill.name) ? skill.key : undefined, skill.argumentHint?.trim(), skill.description || skill.name]
           .filter(Boolean)
           .join(' — '),
         skillName: skill.name,
@@ -3221,7 +3237,7 @@ export const ChatInput: React.FC<ChatInputProps> = ({
         const bExact = bName === q ? 0 : bName.startsWith(q) ? 1 : 2;
         return aExact - bExact || aName.localeCompare(bName);
       });
-  }, [canUseSkillsForTarget, slashCommandState.query, userInvocableSkills]);
+  }, [canUseSkillsForTarget, duplicateSkillNames, slashCommandState.query, userInvocableSkills]);
 
   const resolveTypedMcpPromptCommand = useCallback((text: string): SlashMcpPromptItem | null => {
     const trimmed = text.trim();
@@ -5187,14 +5203,14 @@ export const ChatInput: React.FC<ChatInputProps> = ({
     const replaceInlineTrigger = getRichTextTriggerController()?.replaceActiveInlineTrigger;
 
     if (inlineTriggerState.isActive) {
-      replaceInlineTrigger?.(`[$${item.skillName}]`);
+      replaceInlineTrigger?.(createSkillPromptReferenceToken(item.skillName, item.id));
       setQueuedInput(null);
       setSlashCommandState({ isActive: false, kind: 'all', query: '', selectedIndex: 0 });
       window.setTimeout(() => richTextInputRef.current?.focus(), 0);
       return;
     }
 
-    const next = replaceLeadingSlashCommandWithSkillToken(inputState.value, item.skillName);
+    const next = replaceLeadingSlashCommandWithSkillToken(inputState.value, item.skillName, item.id);
     dispatchInput({ type: 'SET_VALUE', payload: next });
     inputValueRef.current = next;
     setQueuedInput(null);
@@ -5554,13 +5570,13 @@ export const ChatInput: React.FC<ChatInputProps> = ({
     [dispatchInput, focusRichTextInputSoon, getRichTextTriggerController, inputState.value]
   );
 
-  const insertSkillIntoInput = useCallback((skillName: string) => {
-    insertInlineReferenceIntoInput(createSkillPromptReferenceToken(skillName));
+  const insertSkillIntoInput = useCallback((skillName: string, skillKey?: string) => {
+    insertInlineReferenceIntoInput(createSkillPromptReferenceToken(skillName, skillKey));
   }, [insertInlineReferenceIntoInput]);
 
   const selectContextSkill = useCallback((skill: ContextPickerSkill) => {
     getRichTextTriggerController()?.replaceActiveContextTrigger?.(
-      createSkillPromptReferenceToken(skill.name),
+      createSkillPromptReferenceToken(skill.name, skill.key),
     );
     setQueuedInput(null);
     focusRichTextInputSoon();
@@ -6010,6 +6026,7 @@ export const ChatInput: React.FC<ChatInputProps> = ({
                 onLargePaste={createLargePastePlaceholder}
                 onPasteFiles={handleClipboardFiles}
                 pendingLargePastes={pendingLargePastes}
+                skillReferenceNames={skillReferenceNames}
                 onUpdateLargePaste={updateLargePaste}
                 onRemoveLargePaste={removeLargePaste}
                 onKeyDown={handleKeyDown}
@@ -6039,6 +6056,8 @@ export const ChatInput: React.FC<ChatInputProps> = ({
                 skills={canUseSkillsForTarget ? userInvocableSkills : []}
                 skillsLoading={resolvedModeSkillsLoading}
                 skillsLoadFailed={resolvedModeSkillsLoadFailed}
+                skillDiagnostics={resolvedSkillDiagnostics}
+                skillDiagnosticsAvailable={resolvedSkillDiagnosticsAvailable}
                 onRetrySkills={retryResolvedModeSkills}
                 onSelectSkill={canUseSkillsForTarget ? selectContextSkill : undefined}
                 onAddImage={!isAcpTargetSession ? handleContextPickerAddImage : undefined}
@@ -6471,10 +6490,10 @@ export const ChatInput: React.FC<ChatInputProps> = ({
                                   leading={<Icon name="spark" size="xs" aria-hidden />}
                                   onClick={event => {
                                     event.stopPropagation();
-                                    insertSkillIntoInput(skill.name);
+                                    insertSkillIntoInput(skill.name, skill.key);
                                   }}
                                 >
-                                  {[skill.name, skill.argumentHint?.trim()].filter(Boolean).join(' ')}
+                                  {[skill.name, duplicateSkillNames.has(skill.name) ? `(${skill.key})` : undefined, skill.argumentHint?.trim()].filter(Boolean).join(' ')}
                                 </MenuItem>
                               ))
                             )}
diff --git a/src/web-ui/src/flow_chat/components/RichTextInput.test.tsx b/src/web-ui/src/flow_chat/components/RichTextInput.test.tsx
index c9ce192c18..79a7b734c1 100644
--- a/src/web-ui/src/flow_chat/components/RichTextInput.test.tsx
+++ b/src/web-ui/src/flow_chat/components/RichTextInput.test.tsx
@@ -315,7 +315,19 @@ describeWithJsdom('RichTextInput external sync', () => {
     expect(editor.firstChild).not.toBe(originalTextNode);
   });
 
-  it('renders externally inserted skill tokens as inline pills', async () => {
+  it('shows the declared skill name while keeping its exact source token', async () => {
+    await act(async () => root.render(<RichTextInput
+      value="[$project::codex::nested/folder]"
+      skillReferenceNames={{ 'project::codex::nested/folder': 'Declared skill name' }}
+      onChange={() => {}} contexts={emptyContexts} onRemoveContext={() => {}}
+    />));
+    const pill = container.querySelector<HTMLElement>('[data-inline-token-type="skill-ref"]');
+    expect(pill?.dataset.tagFormat).toBe('[$project::codex::nested/folder]');
+    expect(pill?.textContent).toContain('Declared skill name');
+    expect(pill?.title).toBe('');
+  });
+
+  it('renders externally inserted skill tokens as inline pills' , async () => {
     const harnessRef = createRef<HarnessHandle>();
     const editor = await renderHarness(harnessRef);
 
diff --git a/src/web-ui/src/flow_chat/components/RichTextInput.tsx b/src/web-ui/src/flow_chat/components/RichTextInput.tsx
index 6774f75333..9bd50202e4 100644
--- a/src/web-ui/src/flow_chat/components/RichTextInput.tsx
+++ b/src/web-ui/src/flow_chat/components/RichTextInput.tsx
@@ -106,6 +106,7 @@ export interface RichTextInputProps
   onLargePaste?: (text: string) => string | null;
   onPasteFiles?: (paste: ClipboardFilePaste) => void | Promise<void>;
   pendingLargePastes?: Record<string, string>;
+  skillReferenceNames?: Readonly<Record<string, string>>;
   onUpdateLargePaste?: (placeholder: string, text: string) => string;
   onRemoveLargePaste?: (placeholder: string) => void;
   onKeyDown?: (e: React.KeyboardEvent) => void;
@@ -225,6 +226,7 @@ export const RichTextInput = React.forwardRef<HTMLDivElement, RichTextInputProps
   onLargePaste,
   onPasteFiles,
   pendingLargePastes = EMPTY_PENDING_LARGE_PASTES,
+  skillReferenceNames,
   onUpdateLargePaste,
   onRemoveLargePaste,
   onKeyDown,
@@ -517,11 +519,11 @@ export const RichTextInput = React.forwardRef<HTMLDivElement, RichTextInputProps
           token,
           contextType: 'skill-reference',
           inlineTokenType: 'skill-ref',
-          title: `Skill: ${payload.skillName}`,
-          displayText: payload.skillName,
+          title: '',
+          displayText: (payload.skillKey && skillReferenceNames?.[payload.skillKey]) || payload.skillName,
         })
       : null;
-  }, [createSkillStyledReferenceElement]);
+  }, [createSkillStyledReferenceElement, skillReferenceNames]);
 
   const createAdditionalModeReferenceElement = useCallback((token: string): HTMLSpanElement | null => {
     const payload = parseAdditionalModePromptReferenceToken(token);
@@ -605,7 +607,7 @@ export const RichTextInput = React.forwardRef<HTMLDivElement, RichTextInputProps
             kind: 'inline-token',
             token,
             tokenType: 'skill',
-            label: skill.skillName,
+            label: element.querySelector('[data-openbitfun-part="tagText"]')?.textContent || skill.skillName,
           });
           return;
         }
diff --git a/src/web-ui/src/flow_chat/hooks/useResolvedModeSkills.test.tsx b/src/web-ui/src/flow_chat/hooks/useResolvedModeSkills.test.tsx
index b73d10b937..586aa1130c 100644
--- a/src/web-ui/src/flow_chat/hooks/useResolvedModeSkills.test.tsx
+++ b/src/web-ui/src/flow_chat/hooks/useResolvedModeSkills.test.tsx
@@ -7,7 +7,7 @@ import { configAPI } from '@/infrastructure/api/service-api/ConfigAPI';
 import { useResolvedModeSkills } from './useResolvedModeSkills';
 
 vi.mock('@/infrastructure/api/service-api/ConfigAPI', () => ({
-  configAPI: { getModeSkillConfigs: vi.fn() },
+  configAPI: { getModeSkillScanReport: vi.fn() },
 }));
 vi.mock('@/shared/utils/logger', () => ({ createLogger: () => ({ error: vi.fn() }) }));
 
@@ -39,10 +39,10 @@ describe('useResolvedModeSkills', () => {
     root = createRoot(container);
     props = { enabled: true, surfaceEpoch: 1, modeId: 'agent', workspacePath: '/project' };
     requests.length = 0;
-    vi.mocked(configAPI.getModeSkillConfigs).mockReset().mockImplementation(() => {
+    vi.mocked(configAPI.getModeSkillScanReport).mockReset().mockImplementation(() => {
       const request = deferred();
       requests.push(request);
-      return request.promise;
+      return request.promise.then(skills => ({ skills, diagnostics: [], diagnosticsAvailable: true }));
     });
   });
   afterEach(async () => { await act(async () => root.unmount()); });
diff --git a/src/web-ui/src/flow_chat/hooks/useResolvedModeSkills.ts b/src/web-ui/src/flow_chat/hooks/useResolvedModeSkills.ts
index 72baab3a14..1e0d32d96c 100644
--- a/src/web-ui/src/flow_chat/hooks/useResolvedModeSkills.ts
+++ b/src/web-ui/src/flow_chat/hooks/useResolvedModeSkills.ts
@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { configAPI } from '@/infrastructure/api/service-api/ConfigAPI';
-import type { ModeSkillInfo } from '@/infrastructure/config/types';
+import type { ModeSkillInfo, SkillScanDiagnostic } from '@/infrastructure/config/types';
 import { createLogger } from '@/shared/utils/logger';
 
 const log = createLogger('useResolvedModeSkills');
@@ -11,6 +11,8 @@ type Snapshot = {
   skills: ModeSkillInfo[] | null;
   loading: boolean;
   failed: boolean;
+  diagnostics?: SkillScanDiagnostic[];
+  diagnosticsAvailable?: boolean;
 };
 
 export function useResolvedModeSkills({
@@ -49,10 +51,15 @@ export function useResolvedModeSkills({
     entry.loading = true;
     entry.failed = false;
     setSnapshot({ ...entry });
-    void configAPI.getModeSkillConfigs({ modeId, workspacePath: workspacePath || undefined })
-      .then(skills => { entry.skills = skills; })
+    void configAPI.getModeSkillScanReport({ modeId, workspacePath: workspacePath || undefined })
+      .then(report => {
+        entry.skills = report.skills;
+        entry.diagnostics = report.diagnostics;
+        entry.diagnosticsAvailable = report.diagnosticsAvailable;
+      })
       .catch(err => {
         entry.skills = null;
+        entry.diagnostics = [];
         entry.failed = true;
         log.error('Failed to load mode-resolved skills for chat input', { err, modeId, workspacePath });
       })
@@ -66,6 +73,8 @@ export function useResolvedModeSkills({
   const current = snapshot?.key === key ? snapshot : null;
   return {
     skills: current?.skills ?? EMPTY_SKILLS,
+    diagnostics: current?.diagnostics ?? [],
+    diagnosticsAvailable: current?.diagnosticsAvailable ?? true,
     loading: current?.loading ?? enabled,
     hasLoaded: current?.skills != null,
     failed: current?.failed ?? false,
diff --git a/src/web-ui/src/flow_chat/utils/chatInputQuickSkills.ts b/src/web-ui/src/flow_chat/utils/chatInputQuickSkills.ts
index 72957bd031..308d680229 100644
--- a/src/web-ui/src/flow_chat/utils/chatInputQuickSkills.ts
+++ b/src/web-ui/src/flow_chat/utils/chatInputQuickSkills.ts
@@ -22,7 +22,7 @@ export function resolveChatInputQuickSkillShortcuts<
   const availableSkillsByName = new Map<string, TSkill>();
 
   for (const skill of skills) {
-    if (!isSkillAvailableForUserInvocation(skill)) continue;
+    if (!skill.selectedForRuntime || !isSkillAvailableForUserInvocation(skill)) continue;
 
     const normalizedName = skill.name.trim().toLowerCase();
     if (normalizedName && !availableSkillsByName.has(normalizedName)) {
diff --git a/src/web-ui/src/flow_chat/utils/skillPromptReference.test.ts b/src/web-ui/src/flow_chat/utils/skillPromptReference.test.ts
index 6d5a40343a..a6107a6b28 100644
--- a/src/web-ui/src/flow_chat/utils/skillPromptReference.test.ts
+++ b/src/web-ui/src/flow_chat/utils/skillPromptReference.test.ts
@@ -10,6 +10,23 @@ import {
 } from './skillPromptReference';
 
 describe('skillPromptReference', () => {
+  it('preserves exact nested source identity alongside legacy name tokens', () => {
+    const key = 'project::codex::.system/pdf';
+    const token = createSkillPromptReferenceToken('pdf', key);
+    expect(token).toBe('[$project::codex::.system/pdf]');
+    expect(parseSkillPromptReferenceToken(token)).toEqual({ skillName: 'pdf', skillKey: key });
+    expect(replaceLeadingSlashCommandWithSkillToken('/pdf read', 'pdf', key)).toBe(`${token} read`);
+    expect(getSkillPromptReferenceMatches(`Use [$pdf] and ${token}`)).toHaveLength(2);
+  });
+
+  it('allows enabled shadowed sources while respecting global, mode and author disabling', () => {
+    const skill = { selectedForRuntime: false, effectiveEnabled: true, globallyEnabled: true, allowUserInvocation: true };
+    expect(isSkillAvailableForUserInvocation(skill)).toBe(true);
+    expect(isSkillAvailableForUserInvocation({ ...skill, effectiveEnabled: false })).toBe(false);
+    expect(isSkillAvailableForUserInvocation({ ...skill, globallyEnabled: false })).toBe(false);
+    expect(isSkillAvailableForUserInvocation({ ...skill, allowUserInvocation: false })).toBe(false);
+  });
+
   it('creates and parses skill prompt tokens', () => {
     const token = createSkillPromptReferenceToken('pdf');
 
diff --git a/src/web-ui/src/flow_chat/utils/skillPromptReference.ts b/src/web-ui/src/flow_chat/utils/skillPromptReference.ts
index 4ed27f1bd8..9cf92085b6 100644
--- a/src/web-ui/src/flow_chat/utils/skillPromptReference.ts
+++ b/src/web-ui/src/flow_chat/utils/skillPromptReference.ts
@@ -4,10 +4,11 @@ const SLASH_ADDRESSABLE_SKILL_NAME_PATTERN = /^[A-Za-z][\w:-]*$/;
 
 export interface SkillPromptReferenceTokenPayload {
   skillName: string;
+  skillKey?: string;
 }
 
-export function createSkillPromptReferenceToken(skillName: string): string {
-  return `[$${skillName.trim()}]`;
+export function createSkillPromptReferenceToken(skillName: string, skillKey?: string): string {
+  return `[$${skillKey?.trim() || skillName.trim()}]`;
 }
 
 export function parseSkillPromptReferenceToken(
@@ -18,7 +19,10 @@ export function parseSkillPromptReferenceToken(
   if (!skillName) {
     return null;
   }
-  return { skillName };
+  const key = skillName.match(/^(user|project)::([^:]+)::(.+)$/);
+  return key
+    ? { skillName: key[3].split('/').pop() || key[3], skillKey: skillName }
+    : { skillName };
 }
 
 export function getSkillPromptReferenceMatches(text: string): Array<{
@@ -55,8 +59,9 @@ export function getSkillPromptReferenceMatches(text: string): Array<{
 export function appendSkillPromptReferenceToken(
   text: string,
   skillName: string,
+  skillKey?: string,
 ): string {
-  const token = createSkillPromptReferenceToken(skillName);
+  const token = createSkillPromptReferenceToken(skillName, skillKey);
   const trimmed = text.trimEnd();
   return trimmed ? `${trimmed} ${token}` : token;
 }
@@ -64,13 +69,14 @@ export function appendSkillPromptReferenceToken(
 export function replaceLeadingSlashCommandWithSkillToken(
   text: string,
   skillName: string,
+  skillKey?: string,
 ): string {
-  const token = createSkillPromptReferenceToken(skillName);
+  const token = createSkillPromptReferenceToken(skillName, skillKey);
   if (!text.trimStart().startsWith('/')) {
-    return appendSkillPromptReferenceToken(text, skillName);
+    return appendSkillPromptReferenceToken(text, skillName, skillKey);
   }
 
-  return text.replace(LEADING_SLASH_COMMAND_PATTERN, `${'$1'}${token}`);
+  return text.replace(LEADING_SLASH_COMMAND_PATTERN, (_match, whitespace: string) => `${whitespace}${token}`);
 }
 
 export function isSlashAddressableSkillName(skillName: string): boolean {
@@ -79,7 +85,11 @@ export function isSlashAddressableSkillName(skillName: string): boolean {
 
 export function isSkillAvailableForUserInvocation(skill: {
   selectedForRuntime: boolean;
+  effectiveEnabled?: boolean;
+  globallyEnabled?: boolean;
   allowUserInvocation?: boolean;
 }): boolean {
-  return skill.selectedForRuntime && skill.allowUserInvocation !== false;
+  return (skill.effectiveEnabled ?? skill.selectedForRuntime)
+    && skill.globallyEnabled !== false
+    && skill.allowUserInvocation !== false;
 }
diff --git a/src/web-ui/src/infrastructure/api/service-api/ConfigAPI.test.ts b/src/web-ui/src/infrastructure/api/service-api/ConfigAPI.test.ts
index 7170555685..61e53c6130 100644
--- a/src/web-ui/src/infrastructure/api/service-api/ConfigAPI.test.ts
+++ b/src/web-ui/src/infrastructure/api/service-api/ConfigAPI.test.ts
@@ -168,3 +168,26 @@ describe('ConfigAPI batch config reads', () => {
     await expect(configAPI.importConfig({})).rejects.toThrow('Configuration import was not confirmed');
   });
 });
+
+
+describe('skill scan response compatibility', () => {
+  it('accepts legacy arrays and marks diagnostics as unavailable', async () => {
+    invokeMock.mockResolvedValueOnce([{ key: 'user::codex::pdf', name: 'pdf' }]);
+    const report = await new ConfigAPI().getSkillScanReport();
+    expect(report.skills).toHaveLength(1);
+    expect(report.diagnosticsAvailable).toBe(false);
+    expect(report.diagnostics).toEqual([]);
+  });
+
+  it('preserves partial inventories and diagnostics from new hosts', async () => {
+    const value = { skills: [{ key: 'project::codex::pdf' }], diagnostics: [{ path: '/remote/denied', sourceId: 'codex', message: 'permission denied' }] };
+    invokeMock.mockResolvedValueOnce(value);
+    expect(await new ConfigAPI().getModeSkillScanReport({ modeId: 'agent', workspacePath: '/remote' }))
+      .toEqual({ ...value, diagnosticsAvailable: true });
+  });
+
+  it('rejects malformed responses rather than presenting an empty inventory', async () => {
+    invokeMock.mockResolvedValueOnce({ invalid: true });
+    await expect(new ConfigAPI().getSkillScanReport()).rejects.toThrow();
+  });
+});
diff --git a/src/web-ui/src/infrastructure/api/service-api/ConfigAPI.ts b/src/web-ui/src/infrastructure/api/service-api/ConfigAPI.ts
index 6b96b3651e..918868672b 100644
--- a/src/web-ui/src/infrastructure/api/service-api/ConfigAPI.ts
+++ b/src/web-ui/src/infrastructure/api/service-api/ConfigAPI.ts
@@ -10,6 +10,7 @@ import type {
   RuntimeLoggingInfo,
   ConfigValidationResult,
   SkillInfo,
+  SkillScanReport,
   SkillLevel,
   SkillMarketDownloadResult,
   SkillMarketItem,
@@ -27,6 +28,16 @@ export interface GetSkillConfigsParams {
   workspacePath?: string;
 }
 
+function normalizeSkillScanReport<T>(response: T[] | Omit<SkillScanReport<T>, 'diagnosticsAvailable'>): SkillScanReport<T> {
+  if (Array.isArray(response)) {
+    return { skills: response, diagnostics: [], diagnosticsAvailable: false };
+  }
+  if (!response || !Array.isArray(response.skills) || !Array.isArray(response.diagnostics)) {
+    throw new Error('Invalid Skill discovery response');
+  }
+  return { ...response, diagnosticsAvailable: true };
+}
+
 export interface GetModeSkillConfigsParams {
   modeId: string;
   forceRefresh?: boolean;
@@ -388,6 +399,30 @@ export class ConfigAPI {
     }
   }
 
+  async getSkillScanReport({ forceRefresh, workspacePath }: GetSkillConfigsParams = {}): Promise<SkillScanReport> {
+    try {
+      const response = await api.invoke<SkillInfo[] | Omit<SkillScanReport, 'diagnosticsAvailable'>>(
+        'get_skill_configs', { forceRefresh, workspacePath, includeDiagnostics: true },
+        { timeout: SKILL_CONFIG_REQUEST_TIMEOUT_MS },
+      );
+      return normalizeSkillScanReport(response);
+    } catch (error) {
+      throw createTauriCommandError('get_skill_configs', error, { forceRefresh, workspacePath });
+    }
+  }
+
+  async getModeSkillScanReport({ modeId, forceRefresh, workspacePath }: GetModeSkillConfigsParams): Promise<SkillScanReport<ModeSkillInfo>> {
+    try {
+      const response = await api.invoke<ModeSkillInfo[] | Omit<SkillScanReport<ModeSkillInfo>, 'diagnosticsAvailable'>>(
+        'get_mode_skill_configs', { modeId, forceRefresh, workspacePath, includeDiagnostics: true },
+        { timeout: SKILL_CONFIG_REQUEST_TIMEOUT_MS },
+      );
+      return normalizeSkillScanReport(response);
+    } catch (error) {
+      throw createTauriCommandError('get_mode_skill_configs', error, { modeId, forceRefresh, workspacePath });
+    }
+  }
+
   async getGlobalSkillSettings(): Promise<GlobalSkillSettings> {
     try {
       return await api.invoke('get_global_skill_settings');
diff --git a/src/web-ui/src/infrastructure/config/types/index.ts b/src/web-ui/src/infrastructure/config/types/index.ts
index 7a5718529c..babc1c401e 100644
--- a/src/web-ui/src/infrastructure/config/types/index.ts
+++ b/src/web-ui/src/infrastructure/config/types/index.ts
@@ -449,6 +449,19 @@ export interface GlobalSkillSettings {
   globallyDisabledUserSkillKeys: string[];
 }
 
+export interface SkillScanDiagnostic {
+  path: string;
+  sourceId: string;
+  message: string;
+}
+
+export interface SkillScanReport<T = SkillInfo> {
+  skills: T[];
+  diagnostics: SkillScanDiagnostic[];
+  /** False when an older host returns the legacy array instead of diagnostics. */
+  diagnosticsAvailable: boolean;
+}
+
 export interface SkillMarketItem {
   id: string;
   name: string;
diff --git a/src/web-ui/src/locales/en-US/flow-chat.json b/src/web-ui/src/locales/en-US/flow-chat.json
index 6200245a52..80ea9bc463 100644
--- a/src/web-ui/src/locales/en-US/flow-chat.json
+++ b/src/web-ui/src/locales/en-US/flow-chat.json
@@ -968,6 +968,8 @@
     "currentStatus": "Current status: {{status}}"
   },
   "contextPicker": {
+    "skillsIncomplete": "Some skills could not be scanned. Available skills are still listed.",
+    "skillsDiagnosticsUnavailable": "This host does not report skill scan diagnostics.",
     "menuTitle": "Choose context",
     "searchResults": "Search Results",
     "loading": "Loading...",
diff --git a/src/web-ui/src/locales/en-US/scenes/skills.json b/src/web-ui/src/locales/en-US/scenes/skills.json
index a22a2c4b79..4df1f60781 100644
--- a/src/web-ui/src/locales/en-US/scenes/skills.json
+++ b/src/web-ui/src/locales/en-US/scenes/skills.json
@@ -241,7 +241,9 @@
       "globalEnabled": "Available to agents",
       "globalDisabled": "Globally disabled",
       "globalToggleLabel": "Toggle global availability for {{name}}"
-    }
+    },
+    "scanIncomplete": "Some skills could not be scanned. Available skills are still listed.",
+    "diagnosticsUnavailable": "This host does not report skill scan diagnostics."
   },
   "deleteModal": {
     "title": "Confirm Delete",
diff --git a/src/web-ui/src/locales/zh-CN/flow-chat.json b/src/web-ui/src/locales/zh-CN/flow-chat.json
index a105baeade..e555f80223 100644
--- a/src/web-ui/src/locales/zh-CN/flow-chat.json
+++ b/src/web-ui/src/locales/zh-CN/flow-chat.json
@@ -968,6 +968,8 @@
     "currentStatus": "当前状态: {{status}}"
   },
   "contextPicker": {
+    "skillsIncomplete": "部分技能扫描失败，已成功读取的技能仍可使用。",
+    "skillsDiagnosticsUnavailable": "当前主机不提供技能扫描诊断。",
     "menuTitle": "选择上下文",
     "searchResults": "搜索结果",
     "loading": "加载中...",
diff --git a/src/web-ui/src/locales/zh-CN/scenes/skills.json b/src/web-ui/src/locales/zh-CN/scenes/skills.json
index b0fb337709..b423fa0946 100644
--- a/src/web-ui/src/locales/zh-CN/scenes/skills.json
+++ b/src/web-ui/src/locales/zh-CN/scenes/skills.json
@@ -241,7 +241,9 @@
       "globalEnabled": "智能体可用",
       "globalDisabled": "已全局禁用",
       "globalToggleLabel": "切换 {{name}} 的全局可用状态"
-    }
+    },
+    "scanIncomplete": "部分技能扫描失败，已成功读取的技能仍可使用。",
+    "diagnosticsUnavailable": "当前主机不提供技能扫描诊断。"
   },
   "deleteModal": {
     "title": "确认删除",
diff --git a/src/web-ui/src/locales/zh-TW/flow-chat.json b/src/web-ui/src/locales/zh-TW/flow-chat.json
index 3135d804a8..a16e01d75d 100644
--- a/src/web-ui/src/locales/zh-TW/flow-chat.json
+++ b/src/web-ui/src/locales/zh-TW/flow-chat.json
@@ -968,6 +968,8 @@
     "currentStatus": "目前狀態: {{status}}"
   },
   "contextPicker": {
+    "skillsIncomplete": "部分技能掃描失敗，已成功讀取的技能仍可使用。",
+    "skillsDiagnosticsUnavailable": "目前主機不提供技能掃描診斷。",
     "menuTitle": "選擇上下文",
     "searchResults": "搜尋結果",
     "loading": "載入中...",
diff --git a/src/web-ui/src/locales/zh-TW/scenes/skills.json b/src/web-ui/src/locales/zh-TW/scenes/skills.json
index 8321dc5775..755dd26066 100644
--- a/src/web-ui/src/locales/zh-TW/scenes/skills.json
+++ b/src/web-ui/src/locales/zh-TW/scenes/skills.json
@@ -241,7 +241,9 @@
       "globalEnabled": "智能體可用",
       "globalDisabled": "已全域停用",
       "globalToggleLabel": "切換 {{name}} 的全域可用狀態"
-    }
+    },
+    "scanIncomplete": "部分技能掃描失敗，已成功讀取的技能仍可使用。",
+    "diagnosticsUnavailable": "目前主機不提供技能掃描診斷。"
   },
   "deleteModal": {
     "title": "確認刪除",