diff --git a/crates/sharing/src/lib.rs b/crates/sharing/src/lib.rs
index 2e94a4a..7f8cffd 100644
--- a/crates/sharing/src/lib.rs
+++ b/crates/sharing/src/lib.rs
@@ -30,6 +30,17 @@ impl BundleAsset {
     }
 }
 
+fn read_bundle_text_asset(path: &Path) -> Result<String> {
+    let bytes =
+        std::fs::read(path).with_context(|| format!("read bundle asset '{}'", path.display()))?;
+    String::from_utf8(bytes).map_err(|_| {
+        anyhow::anyhow!(
+            ".a7bundle v1 only supports text assets; binary or non-UTF-8 file detected: {}",
+            path.display()
+        )
+    })
+}
+
 /// A portable bundle of skills and/or workflows.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Bundle {
@@ -185,7 +196,7 @@ impl BundleBuilder {
                     if path.extension().and_then(|e| e.to_str()) != Some("md") {
                         continue;
                     }
-                    let content = std::fs::read_to_string(&path)?;
+                    let content = read_bundle_text_asset(&path)?;
                     let stem = path
                         .file_stem()
                         .and_then(|s| s.to_str())
@@ -215,7 +226,7 @@ impl BundleBuilder {
                 if !manifest.is_file() {
                     continue;
                 }
-                let manifest_content = std::fs::read_to_string(&manifest)?;
+                let manifest_content = read_bundle_text_asset(&manifest)?;
                 let package_name = path
                     .file_name()
                     .and_then(|s| s.to_str())
@@ -274,7 +285,7 @@ impl BundleBuilder {
                 if rel.is_empty() {
                     continue;
                 }
-                let content = std::fs::read_to_string(&path)?;
+                let content = read_bundle_text_asset(&path)?;
                 if seen.insert(rel.clone()) {
                     assets.push(BundleAsset::new(rel, content));
                 }
@@ -409,7 +420,7 @@ impl BundleBuilder {
                                 if !package_file.is_file() {
                                     continue;
                                 }
-                                let package_content = std::fs::read_to_string(&package_file)?;
+                                let package_content = read_bundle_text_asset(&package_file)?;
                                 seen.insert(rel_file.clone());
                                 assets.push(BundleAsset::new(rel_file, package_content));
                             }
@@ -432,9 +443,15 @@ impl BundleBuilder {
                             consumed = true;
                             break;
                         }
-                        let content = std::fs::read_to_string(&flat_file)?;
+                        let content = read_bundle_text_asset(&flat_file)?;
                         seen.insert(rel_file.clone());
                         assets.push(BundleAsset::new(rel_file, content));
+                        maybe_collect_flat_tool_dependency_dir(
+                            &flat_file,
+                            tools_dir,
+                            &mut assets,
+                            &mut seen,
+                        )?;
                         consumed = true;
                         break;
                     }
@@ -457,9 +474,15 @@ impl BundleBuilder {
                                 consumed = true;
                                 break 'ext_search;
                             }
-                            let content = std::fs::read_to_string(&candidate)?;
+                            let content = read_bundle_text_asset(&candidate)?;
                             seen.insert(rel_file.clone());
                             assets.push(BundleAsset::new(rel_file, content));
+                            maybe_collect_flat_tool_dependency_dir(
+                                &candidate,
+                                tools_dir,
+                                &mut assets,
+                                &mut seen,
+                            )?;
                             consumed = true;
                             break 'ext_search;
                         }
@@ -478,7 +501,7 @@ impl BundleBuilder {
                         if seen.contains(&rel_file) {
                             break;
                         }
-                        let content = std::fs::read_to_string(&flat_script)?;
+                        let content = read_bundle_text_asset(&flat_script)?;
                         seen.insert(rel_file.clone());
                         assets.push(BundleAsset::new(rel_file, content));
                         break;
@@ -497,7 +520,7 @@ impl BundleBuilder {
                         if !path.is_file() {
                             continue;
                         }
-                        let content = std::fs::read_to_string(&path)?;
+                        let content = read_bundle_text_asset(&path)?;
                         seen.insert(rel_norm.clone());
                         assets.push(BundleAsset::new(rel_norm.clone(), content));
                         break;
@@ -513,9 +536,15 @@ impl BundleBuilder {
                     if !path.is_file() {
                         continue;
                     }
-                    let content = std::fs::read_to_string(&path)?;
+                    let content = read_bundle_text_asset(&path)?;
                     seen.insert(rel_norm.clone());
                     assets.push(BundleAsset::new(rel_norm.clone(), content));
+                    maybe_collect_flat_tool_dependency_dir(
+                        &path,
+                        tools_dir,
+                        &mut assets,
+                        &mut seen,
+                    )?;
                     // If this file is inside a manifest-based tool package (tools/<name>/...),
                     // include sibling package files for dependency closure.
                     if let Some(package_name) = rel_norm.split('/').next() {
@@ -536,7 +565,7 @@ impl BundleBuilder {
                                     if !package_file.is_file() {
                                         continue;
                                     }
-                                    let package_content = std::fs::read_to_string(&package_file)?;
+                                    let package_content = read_bundle_text_asset(&package_file)?;
                                     seen.insert(rel_file.clone());
                                     assets.push(BundleAsset::new(rel_file, package_content));
                                 }
@@ -588,7 +617,7 @@ impl BundleBuilder {
                         if !package_file.is_file() {
                             continue;
                         }
-                        let content = std::fs::read_to_string(&package_file)?;
+                        let content = read_bundle_text_asset(&package_file)?;
                         seen.insert(rel_file.clone());
                         assets.push(BundleAsset::new(rel_file, content));
                     }
@@ -602,8 +631,14 @@ impl BundleBuilder {
                     if rel.is_empty() || !seen.insert(rel.clone()) {
                         continue;
                     }
-                    let content = std::fs::read_to_string(&path)?;
+                    let content = read_bundle_text_asset(&path)?;
                     assets.push(BundleAsset::new(rel, content));
+                    maybe_collect_flat_tool_dependency_dir(
+                        &path,
+                        tools_dir,
+                        &mut assets,
+                        &mut seen,
+                    )?;
                 }
             }
         }
@@ -624,7 +659,7 @@ impl BundleBuilder {
                 if !path.is_file() {
                     continue;
                 }
-                let content = std::fs::read_to_string(&path)?;
+                let content = read_bundle_text_asset(&path)?;
                 assets.push(BundleAsset::new(rel_norm, content));
             }
         }
@@ -694,7 +729,7 @@ impl BundleBuilder {
                 if filename.is_empty() || !seen.insert(filename.clone()) {
                     continue;
                 }
-                let content = std::fs::read_to_string(&path)?;
+                let content = read_bundle_text_asset(&path)?;
                 assets.push(BundleAsset::new(filename, content));
             }
         }
@@ -715,7 +750,7 @@ impl BundleBuilder {
                     if path.extension().and_then(|e| e.to_str()) != Some("md") {
                         continue;
                     }
-                    let content = std::fs::read_to_string(&path)?;
+                    let content = read_bundle_text_asset(&path)?;
                     let Some(trigger) = parse_frontmatter_value(&content, "trigger") else {
                         continue;
                     };
@@ -735,7 +770,7 @@ impl BundleBuilder {
                 if !manifest.is_file() {
                     continue;
                 }
-                let manifest_content = std::fs::read_to_string(&manifest)?;
+                let manifest_content = read_bundle_text_asset(&manifest)?;
                 let Some(trigger) = parse_frontmatter_value(&manifest_content, "trigger") else {
                     continue;
                 };
@@ -932,7 +967,7 @@ fn collect_files_recursive(
         if rel.is_empty() || !seen.insert(rel.clone()) {
             continue;
         }
-        let content = std::fs::read_to_string(&path)?;
+        let content = read_bundle_text_asset(&path)?;
         out.push(BundleAsset::new(rel, content));
     }
     Ok(())
@@ -945,7 +980,13 @@ fn collect_files_recursive_paths(
 ) -> Result<()> {
     for entry in std::fs::read_dir(root)?.flatten() {
         let path = entry.path();
-        if path.is_dir() {
+        let Ok(meta) = std::fs::symlink_metadata(&path) else {
+            continue;
+        };
+        if meta.file_type().is_symlink() {
+            continue;
+        }
+        if meta.is_dir() {
             collect_files_recursive_paths(&path, base_dir, out)?;
             continue;
         }
@@ -962,6 +1003,51 @@ fn collect_files_recursive_paths(
     Ok(())
 }
 
+fn collect_flat_tool_sibling_dir_assets(
+    sibling_dir: &Path,
+    tools_dir: &Path,
+    assets: &mut Vec<BundleAsset>,
+    seen: &mut HashSet<String>,
+) -> Result<()> {
+    let Ok(meta) = std::fs::symlink_metadata(sibling_dir) else {
+        return Ok(());
+    };
+    if meta.file_type().is_symlink() || !meta.is_dir() {
+        return Ok(());
+    }
+    let mut sibling_files = Vec::new();
+    collect_files_recursive_paths(sibling_dir, tools_dir, &mut sibling_files)?;
+    for rel_file in sibling_files {
+        if seen.contains(&rel_file) {
+            continue;
+        }
+        let sibling_file = tools_dir.join(&rel_file);
+        if !sibling_file.is_file() {
+            continue;
+        }
+        let sibling_content = read_bundle_text_asset(&sibling_file)?;
+        seen.insert(rel_file.clone());
+        assets.push(BundleAsset::new(rel_file, sibling_content));
+    }
+    Ok(())
+}
+
+fn maybe_collect_flat_tool_dependency_dir(
+    tool_file: &Path,
+    tools_dir: &Path,
+    assets: &mut Vec<BundleAsset>,
+    seen: &mut HashSet<String>,
+) -> Result<()> {
+    let Some(stem) = tool_file.file_stem().and_then(|s| s.to_str()) else {
+        return Ok(());
+    };
+    if stem.is_empty() {
+        return Ok(());
+    }
+    let sibling_dir = tool_file.parent().unwrap_or(tools_dir).join(stem);
+    collect_flat_tool_sibling_dir_assets(&sibling_dir, tools_dir, assets, seen)
+}
+
 fn has_tool_manifest(dir: &Path) -> bool {
     [
         "TOOL.yaml",
@@ -1638,6 +1724,193 @@ mod tests {
         assert_eq!(bundle.tools[0].filename, "quick-tool.py");
     }
 
+    #[test]
+    fn builder_flat_tool_export_includes_same_stem_dependency_dir() {
+        let dir = tempfile::tempdir().unwrap();
+        let skills_dir = dir.path().join("skills");
+        let workflows_dir = dir.path().join("workflows");
+        let tools_dir = dir.path().join("tools");
+        std::fs::create_dir_all(&skills_dir).unwrap();
+        std::fs::create_dir_all(&workflows_dir).unwrap();
+        std::fs::create_dir_all(tools_dir.join("main_test").join("relatedfiles")).unwrap();
+
+        std::fs::write(
+            skills_dir.join("plain.md"),
+            "---\nname: plain\ndescription: d\ntrigger: /plain\nmodel: codex\n---\nNo refs\n",
+        )
+        .unwrap();
+        std::fs::write(tools_dir.join("main_test.py"), "print('ok')\n").unwrap();
+        std::fs::write(
+            tools_dir
+                .join("main_test")
+                .join("relatedfiles")
+                .join("helper.txt"),
+            "helper\n",
+        )
+        .unwrap();
+
+        let builder = BundleBuilder::new([&skills_dir], [&workflows_dir]);
+        let bundle = builder
+            .build(&["plain"], &["__none__"], &["__none__"], &["main_test.py"])
+            .unwrap();
+
+        let filenames: HashSet<String> = bundle
+            .tools
+            .iter()
+            .map(|asset| asset.filename.clone())
+            .collect();
+        assert!(filenames.contains("main_test.py"));
+        assert!(filenames.contains("main_test/relatedfiles/helper.txt"));
+    }
+
+    #[test]
+    fn builder_flat_tool_export_uses_colocated_dependency_dir_for_nested_tool() {
+        let dir = tempfile::tempdir().unwrap();
+        let skills_dir = dir.path().join("skills");
+        let workflows_dir = dir.path().join("workflows");
+        let tools_dir = dir.path().join("tools");
+        std::fs::create_dir_all(&skills_dir).unwrap();
+        std::fs::create_dir_all(&workflows_dir).unwrap();
+        std::fs::create_dir_all(tools_dir.join("ml").join("infer").join("related")).unwrap();
+
+        std::fs::write(
+            skills_dir.join("plain.md"),
+            "---
+name: plain
+description: d
+trigger: /plain
+model: codex
+---
+No refs
+",
+        )
+        .unwrap();
+        std::fs::write(
+            tools_dir.join("ml").join("infer.py"),
+            "print('ok')
+",
+        )
+        .unwrap();
+        std::fs::write(
+            tools_dir
+                .join("ml")
+                .join("infer")
+                .join("related")
+                .join("helper.txt"),
+            "helper
+",
+        )
+        .unwrap();
+
+        let builder = BundleBuilder::new([&skills_dir], [&workflows_dir]);
+        let bundle = builder
+            .build(&["plain"], &["__none__"], &["__none__"], &["ml/infer.py"])
+            .unwrap();
+
+        let filenames: HashSet<String> = bundle
+            .tools
+            .iter()
+            .map(|asset| asset.filename.clone())
+            .collect();
+        assert!(filenames.contains("ml/infer.py"));
+        assert!(filenames.contains("ml/infer/related/helper.txt"));
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn builder_flat_tool_export_skips_symlinked_dependency_files() {
+        use std::os::unix::fs::symlink;
+
+        let dir = tempfile::tempdir().unwrap();
+        let skills_dir = dir.path().join("skills");
+        let workflows_dir = dir.path().join("workflows");
+        let tools_dir = dir.path().join("tools");
+        let outside = dir.path().join("outside.txt");
+        std::fs::create_dir_all(&skills_dir).unwrap();
+        std::fs::create_dir_all(&workflows_dir).unwrap();
+        std::fs::create_dir_all(tools_dir.join("sample_tool")).unwrap();
+        std::fs::write(
+            &outside, "secret
+",
+        )
+        .unwrap();
+
+        std::fs::write(
+            skills_dir.join("plain.md"),
+            "---
+name: plain
+description: d
+trigger: /plain
+model: codex
+---
+No refs
+",
+        )
+        .unwrap();
+        std::fs::write(
+            tools_dir.join("sample_tool.py"),
+            "print('ok')
+",
+        )
+        .unwrap();
+        symlink(
+            &outside,
+            tools_dir.join("sample_tool").join("outside-link.txt"),
+        )
+        .unwrap();
+
+        let builder = BundleBuilder::new([&skills_dir], [&workflows_dir]);
+        let bundle = builder
+            .build(
+                &["plain"],
+                &["__none__"],
+                &["__none__"],
+                &["sample_tool.py"],
+            )
+            .unwrap();
+
+        let filenames: HashSet<String> = bundle
+            .tools
+            .iter()
+            .map(|asset| asset.filename.clone())
+            .collect();
+        assert!(filenames.contains("sample_tool.py"));
+        assert!(!filenames.contains("sample_tool/outside-link.txt"));
+    }
+
+    #[test]
+    fn builder_rejects_binary_tool_assets_with_clear_error() {
+        let dir = tempfile::tempdir().unwrap();
+        let skills_dir = dir.path().join("skills");
+        let workflows_dir = dir.path().join("workflows");
+        let tools_dir = dir.path().join("tools");
+        let package_dir = tools_dir.join("binpack");
+        std::fs::create_dir_all(&skills_dir).unwrap();
+        std::fs::create_dir_all(&workflows_dir).unwrap();
+        std::fs::create_dir_all(&package_dir).unwrap();
+
+        std::fs::write(
+            skills_dir.join("plain.md"),
+            "---\nname: plain\ndescription: d\ntrigger: /plain\nmodel: codex\n---\nNo refs\n",
+        )
+        .unwrap();
+        std::fs::write(
+            package_dir.join("TOOL.yaml"),
+            "name: binpack\ndescription: test\nruntime: shell\nentrypoint: run.sh\n",
+        )
+        .unwrap();
+        std::fs::write(package_dir.join("run.sh"), "#!/usr/bin/env sh\necho ok\n").unwrap();
+        std::fs::write(package_dir.join("helper.bin"), [0_u8, 159, 146, 150]).unwrap();
+
+        let builder = BundleBuilder::new([&skills_dir], [&workflows_dir]);
+        let err = builder
+            .build(&["__none__"], &["__none__"], &["__none__"], &["binpack"])
+            .expect_err("binary payload should be rejected clearly");
+        let msg = err.to_string();
+        assert!(msg.contains(".a7bundle v1 only supports text assets"));
+        assert!(msg.contains("helper.bin"));
+    }
+
     #[test]
     fn builder_tools_only_selection_exports_scripts_without_skills_or_workflows() {
         let dir = tempfile::tempdir().unwrap();
diff --git a/crates/web/frontend/src/composables/useApi.js b/crates/web/frontend/src/composables/useApi.js
index 539b728..4b2a95d 100644
--- a/crates/web/frontend/src/composables/useApi.js
+++ b/crates/web/frontend/src/composables/useApi.js
@@ -53,7 +53,22 @@ export function useApi() {
       const suffix = qs.toString() ? `?${qs.toString()}` : ''
       return fetchJson(`/api/skills/detail/${encodeURIComponent(trigger)}${suffix}`)
     },
-    importSkill: (url) => fetchJson('/api/skills/import', { method: 'POST', body: JSON.stringify({ url }) }),
+    importSkill: (url, opts = {}) =>
+      fetchJson('/api/skills/import', {
+        method: 'POST',
+        body: JSON.stringify({
+          url,
+          conflict_action: opts.conflict_action,
+          alias_trigger: opts.alias_trigger,
+        }),
+      }),
+    previewSkillImport: (url) =>
+      fetchJson('/api/skills/preview', { method: 'POST', body: JSON.stringify({ url }) }),
+    discoverSkills: (q, sources = [], limit = 12) =>
+      fetchJson('/api/skills/discover', {
+        method: 'POST',
+        body: JSON.stringify({ q, sources, limit }),
+      }),
     deleteSkill: (trigger) => fetchJson(`/api/skills/${encodeURIComponent(trigger.replace(/^\//, ''))}`, { method: 'DELETE' }),
     getRegistry: () => fetchJson('/api/skill-registry'),
 
diff --git a/crates/web/frontend/src/views/SharingView.vue b/crates/web/frontend/src/views/SharingView.vue
index 14f03c2..f4df9af 100644
--- a/crates/web/frontend/src/views/SharingView.vue
+++ b/crates/web/frontend/src/views/SharingView.vue
@@ -39,7 +39,13 @@ const allPersonasSelected = computed(
 // API paths: tools/ml/infer.py → bundle key: ml/infer.py
 //            scripts/train.py  → bundle key: scripts/train.py
 function apiPathToBundleKey(path) {
-    return path.startsWith("tools/") ? path.slice("tools/".length) : path;
+    const normalized = String(path || "").replace(/^\.?\/*/, "");
+    const withoutAgentHome = normalized.startsWith(".agent007/")
+        ? normalized.slice(".agent007/".length)
+        : normalized;
+    return withoutAgentHome.startsWith("tools/")
+        ? withoutAgentHome.slice("tools/".length)
+        : withoutAgentHome;
 }
 
 const allTools = computed(() => {
diff --git a/crates/web/frontend/src/views/SkillsView.vue b/crates/web/frontend/src/views/SkillsView.vue
index 9883afa..581ffbd 100644
--- a/crates/web/frontend/src/views/SkillsView.vue
+++ b/crates/web/frontend/src/views/SkillsView.vue
@@ -9,12 +9,29 @@ const activeTab = ref('installed')
 const showForm = ref(false)
 const editingTrigger = ref(null) // null = creating, string = editing existing
 const importUrl = ref('')
+const browseStatus = ref(null)
 const importStatus = ref(null)
 const searchQuery = ref('')
+const discoverQuery = ref('')
+const discoverSourcesText = ref('')
+const discoverResults = ref([])
+const discovering = ref(false)
+const previewLoading = ref(false)
+const previewError = ref(null)
+const previewOpen = ref(false)
+const previewData = ref(null)
+const previewMode = ref('replace')
+const previewAliasTrigger = ref('')
 const toast = ref(null)
 const promotingTrigger = ref(null)
 const deletingTrigger = ref(null)
 
+const DEFAULT_DISCOVER_SOURCES = [
+  'https://github.com/openai/skills/tree/main/skills',
+  'https://github.com/anthropics/skills/tree/main/skills',
+  'https://github.com/vercel-labs/agent-skills/tree/main/skills',
+]
+
 let toastTimer = null
 function showToast(message, type = 'success') {
   clearTimeout(toastTimer)
@@ -86,7 +103,10 @@ const form = ref({
   template: '',
 })
 
-onMounted(loadSkills)
+onMounted(async () => {
+  loadDiscoverSources()
+  await loadSkills()
+})
 
 async function loadSkills() {
   const data = await api.listSkills()
@@ -105,7 +125,39 @@ async function loadRegistry() {
 
 function switchTab(tab) {
   activeTab.value = tab
-  if (tab === 'browse') loadRegistry()
+  if (tab === 'browse') {
+    importStatus.value = null
+    loadRegistry()
+  } else if (tab === 'import') {
+    browseStatus.value = null
+  }
+}
+
+function loadDiscoverSources() {
+  try {
+    const saved = localStorage.getItem('agent007.skillDiscoverSources')
+    if (saved) {
+      const parsed = JSON.parse(saved)
+      if (Array.isArray(parsed) && parsed.length) {
+        discoverSourcesText.value = parsed.join('\n')
+        return
+      }
+    }
+  } catch {}
+  discoverSourcesText.value = DEFAULT_DISCOVER_SOURCES.join('\n')
+}
+
+function normalizedDiscoverSources() {
+  return discoverSourcesText.value
+    .split('\n')
+    .map(v => v.trim())
+    .filter(Boolean)
+}
+
+function saveDiscoverSources() {
+  try {
+    localStorage.setItem('agent007.skillDiscoverSources', JSON.stringify(normalizedDiscoverSources()))
+  } catch {}
 }
 
 const categoryOrder = ['dev', 'code', 'project', 'meta', 'custom']
@@ -274,14 +326,14 @@ async function saveSkill() {
 
 async function installFromRegistry(item) {
   if (!item.url) return
-  importStatus.value = { type: 'loading', message: `Installing ${item.name}...` }
+  browseStatus.value = { type: 'loading', message: `Installing ${item.name}...` }
   try {
     await api.importSkill(item.url)
-    importStatus.value = { type: 'success', message: `${item.name} installed!` }
+    browseStatus.value = { type: 'success', message: `${item.name} installed!` }
     await loadSkills()
-    setTimeout(() => importStatus.value = null, 3000)
+    setTimeout(() => browseStatus.value = null, 3000)
   } catch (e) {
-    importStatus.value = { type: 'error', message: e.message }
+    browseStatus.value = { type: 'error', message: e.message }
   }
 }
 
@@ -298,6 +350,76 @@ async function importFromUrl() {
     importStatus.value = { type: 'error', message: e.message }
   }
 }
+
+async function runDiscoverSearch() {
+  if (!discoverQuery.value.trim()) return
+  const sources = normalizedDiscoverSources()
+  if (!sources.length) {
+    browseStatus.value = { type: 'error', message: 'Add at least one GitHub source URL' }
+    return
+  }
+  saveDiscoverSources()
+  discovering.value = true
+  browseStatus.value = null
+  try {
+    const result = await api.discoverSkills(discoverQuery.value.trim(), sources, 16)
+    discoverResults.value = Array.isArray(result?.results) ? result.results : []
+  } catch (e) {
+    browseStatus.value = { type: 'error', message: e.message || 'Discover failed' }
+    discoverResults.value = []
+  } finally {
+    discovering.value = false
+  }
+}
+
+async function openPreview(url, installMode = 'preview') {
+  previewOpen.value = true
+  previewLoading.value = true
+  previewError.value = null
+  previewData.value = null
+  previewMode.value = 'replace'
+  previewAliasTrigger.value = ''
+  try {
+    previewData.value = await api.previewSkillImport(url)
+    if (installMode === 'install' && previewData.value?.conflict) {
+      previewMode.value = 'replace'
+      previewAliasTrigger.value = `${previewData.value.trigger}-alt`
+    }
+  } catch (e) {
+    previewError.value = e.message || 'Preview failed'
+  } finally {
+    previewLoading.value = false
+  }
+}
+
+async function installFromPreview() {
+  if (!previewData.value?.url) return
+  browseStatus.value = { type: 'loading', message: `Installing ${previewData.value.name || previewData.value.trigger}...` }
+  try {
+    const opts = {}
+    if (previewData.value?.conflict) {
+      opts.conflict_action = previewMode.value
+      if (previewMode.value === 'alias') {
+        opts.alias_trigger = previewAliasTrigger.value.trim()
+      }
+    }
+    const result = await api.importSkill(previewData.value.url, opts)
+    if (result?.skipped) {
+      browseStatus.value = { type: 'success', message: `Kept existing ${result.trigger}` }
+    } else {
+      browseStatus.value = { type: 'success', message: `Installed ${result?.trigger || previewData.value.trigger}` }
+    }
+    previewOpen.value = false
+    previewData.value = null
+    await loadSkills()
+    if (discoverQuery.value.trim()) {
+      await runDiscoverSearch()
+    }
+    setTimeout(() => browseStatus.value = null, 3000)
+  } catch (e) {
+    browseStatus.value = { type: 'error', message: e.message || 'Install failed' }
+  }
+}
 </script>
 
 <template>
@@ -445,12 +567,20 @@ async function importFromUrl() {
 
       <!-- Tab: Browse Registry -->
       <div v-if="activeTab === 'browse'" class="space-y-4">
+        <div v-if="browseStatus" class="alert alert-sm" :class="{
+          'alert-info': browseStatus.type === 'loading',
+          'alert-success': browseStatus.type === 'success',
+          'alert-error': browseStatus.type === 'error',
+        }">
+          <span class="font-mono text-xs">{{ browseStatus.message }}</span>
+        </div>
+
         <div class="flex items-center gap-3 flex-wrap">
           <div class="form-control flex-1 min-w-48">
             <input
               v-model="searchQuery"
               class="input input-sm input-bordered w-full font-mono"
-              placeholder="Filter local registry…"
+              placeholder="Filter curated registry…"
             />
           </div>
           <div class="flex items-center gap-1.5 text-xs font-mono text-base-content/40">
@@ -458,7 +588,7 @@ async function importFromUrl() {
             <button
               class="btn btn-xs btn-ghost font-mono border border-base-300"
               @click="$emit('navigate-external', 'extensions')"
-              title="Browse npm MCP packages and GitHub extensions"
+              title="Browse npm MCP packages and GitHub extensions. Skill search here is currently curated registry only."
             >⊞ Extensions →</button>
           </div>
         </div>
@@ -499,6 +629,69 @@ async function importFromUrl() {
             </div>
           </div>
         </div>
+
+        <div class="pt-4">
+          <div class="flex items-center gap-2 mb-3">
+            <div class="flex-1 h-px bg-base-content/10"></div>
+            <span class="text-[10px] font-mono font-bold uppercase tracking-widest text-base-content/35">discover across GitHub sources</span>
+            <div class="flex-1 h-px bg-base-content/10"></div>
+          </div>
+
+          <div class="grid grid-cols-1 xl:grid-cols-[1.3fr_0.9fr] gap-3 mb-3">
+            <div class="space-y-2">
+              <input
+                v-model="discoverQuery"
+                class="input input-sm input-bordered w-full font-mono"
+                placeholder="Search trigger, name, or description (for example: frontend-designer)"
+                @keyup.enter="runDiscoverSearch"
+              />
+              <div class="text-[10px] font-mono text-base-content/35">Uses built-in defaults for OpenAI, Anthropic, and Vercel if you leave custom sources empty. Duplicate variants are preserved by source.</div>
+            </div>
+            <div class="space-y-2">
+              <textarea
+                v-model="discoverSourcesText"
+                class="textarea textarea-bordered textarea-sm w-full font-mono min-h-[110px]"
+                placeholder="One GitHub repo/tree URL per line"
+              ></textarea>
+              <div class="flex justify-between items-center">
+                <div class="text-[10px] font-mono text-base-content/35">Use repo root, tree, or package URLs to add community or internal sources on top of the defaults.</div>
+                <button class="btn btn-sm btn-primary font-mono text-xs" :class="{ 'loading': discovering }" @click="runDiscoverSearch">
+                  {{ discovering ? 'searching' : 'search' }}
+                </button>
+              </div>
+            </div>
+          </div>
+
+          <div v-if="!discoverResults.length && !discovering" class="text-[11px] font-mono text-base-content/35 py-2">
+            No discovery results yet. Add one or more source URLs, search, then preview before install.
+          </div>
+
+          <div class="grid grid-cols-1 md:grid-cols-2 xl:grid-cols-3 2xl:grid-cols-4 gap-3">
+            <div
+              v-for="item in discoverResults"
+              :key="`${item.url}:${item.trigger}`"
+              class="bg-base-200 border border-base-300 rounded-lg p-4 border-l-2 border-l-info/40 min-h-[190px]"
+            >
+              <div class="flex items-start justify-between gap-3">
+                <div class="flex-1 min-w-0">
+                  <div class="font-mono text-sm font-semibold break-words leading-snug">{{ item.name }}</div>
+                  <div class="text-[11px] font-mono text-base-content/45 mt-1 break-words leading-relaxed max-h-[3.6rem] overflow-hidden">{{ item.description }}</div>
+                  <div class="flex gap-1.5 mt-2 flex-wrap">
+                    <span class="text-[10px] font-mono px-1.5 py-0.5 rounded border border-primary/30 text-primary/70">{{ item.trigger }}</span>
+                    <span class="text-[10px] font-mono px-1.5 py-0.5 rounded border border-base-content/20 text-base-content/55 break-all">{{ item.repo }}</span>
+                    <span v-if="item.version" class="text-[10px] font-mono text-base-content/35">v{{ item.version }}</span>
+                    <span v-if="item.installed" class="text-[10px] font-mono text-warning">conflict</span>
+                  </div>
+                  <div class="mt-2 text-[10px] font-mono text-base-content/35 truncate" :title="item.path">{{ item.path }}</div>
+                </div>
+                <div class="flex flex-col gap-1 shrink-0">
+                  <button class="btn btn-xs btn-ghost font-mono text-[10px]" @click="openPreview(item.url)">preview</button>
+                  <button class="btn btn-xs btn-primary font-mono text-[10px]" @click="openPreview(item.url, 'install')">install</button>
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
       </div>
 
       <!-- Tab: Import -->
@@ -548,6 +741,81 @@ Use &#123;&#123;args&#125;&#125; for input and &#123;&#123;task&#125;&#125; for
       </div>
     </div>
 
+    <dialog :open="previewOpen" class="modal" :class="{ 'modal-open': previewOpen }">
+      <div class="modal-box max-w-3xl bg-base-100 border border-base-300 rounded-lg p-0 overflow-hidden">
+        <div class="flex items-center justify-between px-5 py-3 bg-base-200 border-b border-base-300">
+          <span class="text-[11px] font-mono font-bold uppercase tracking-widest text-base-content/50">
+            {{ previewData?.trigger || 'skill preview' }}
+          </span>
+          <button class="btn btn-ghost btn-xs font-mono text-base-content/40 hover:text-base-content px-1" @click="previewOpen = false">✕</button>
+        </div>
+        <div class="p-5 space-y-4">
+          <div v-if="previewLoading" class="text-[11px] font-mono text-base-content/45">Loading preview…</div>
+          <div v-else-if="previewError" class="alert alert-error alert-sm">
+            <span class="font-mono text-xs">{{ previewError }}</span>
+          </div>
+          <template v-else-if="previewData">
+            <div>
+              <div class="flex items-center gap-2 flex-wrap">
+                <div class="font-mono text-sm font-semibold">{{ previewData.name }}</div>
+                <span class="text-[10px] font-mono px-1.5 py-0.5 rounded border border-primary/30 text-primary/70">{{ previewData.trigger }}</span>
+                <span v-if="previewData.version" class="text-[10px] font-mono text-base-content/35">v{{ previewData.version }}</span>
+                <span v-if="previewData.category" class="text-[10px] font-mono text-base-content/35">{{ previewData.category }}</span>
+              </div>
+              <div class="text-[11px] font-mono text-base-content/45 mt-1">{{ previewData.description }}</div>
+            </div>
+
+            <div v-if="previewData.conflict" class="border border-warning/30 bg-warning/5 rounded-lg p-3 space-y-2">
+              <div class="text-[10px] font-mono font-bold uppercase tracking-widest text-warning">trigger conflict</div>
+              <div class="text-[11px] font-mono text-base-content/55">
+                Installed variants already exist for <code class="bg-base-200 px-1 rounded">{{ previewData.conflict.trigger }}</code>.
+              </div>
+              <div class="space-y-1">
+                <div
+                  v-for="variant in previewData.conflict.variants"
+                  :key="`${variant.path}:${variant.source}`"
+                  class="text-[10px] font-mono text-base-content/45"
+                >
+                  {{ variant.source }} · {{ variant.name }}<span v-if="variant.version"> · v{{ variant.version }}</span>
+                </div>
+              </div>
+              <div class="flex gap-3 flex-wrap pt-1">
+                <label class="label cursor-pointer gap-2 font-mono text-[11px]"><input v-model="previewMode" type="radio" class="radio radio-xs" value="replace" /> replace</label>
+                <label class="label cursor-pointer gap-2 font-mono text-[11px]"><input v-model="previewMode" type="radio" class="radio radio-xs" value="alias" /> alias</label>
+                <label class="label cursor-pointer gap-2 font-mono text-[11px]"><input v-model="previewMode" type="radio" class="radio radio-xs" value="keep_existing" /> keep existing</label>
+              </div>
+              <input
+                v-if="previewMode === 'alias'"
+                v-model="previewAliasTrigger"
+                class="input input-sm input-bordered w-full font-mono"
+                placeholder="/frontend-designer-alt"
+              />
+            </div>
+
+            <div v-if="previewData.package && previewData.files?.length" class="space-y-2">
+              <div class="text-[10px] font-mono font-bold uppercase tracking-widest text-base-content/35">package files</div>
+              <div class="max-h-28 overflow-auto rounded border border-base-300 bg-base-200 p-2 text-[10px] font-mono text-base-content/50">
+                <div v-for="file in previewData.files" :key="file">{{ file }}</div>
+              </div>
+            </div>
+
+            <div class="space-y-2">
+              <div class="text-[10px] font-mono font-bold uppercase tracking-widest text-base-content/35">prompt preview</div>
+              <pre class="bg-base-200 border border-base-300 rounded-lg p-3 overflow-auto max-h-80 text-[11px] font-mono text-base-content/70 whitespace-pre-wrap">{{ previewData.body }}</pre>
+            </div>
+          </template>
+        </div>
+        <div class="flex items-center justify-end gap-2 px-5 py-3 bg-base-200 border-t border-base-300">
+          <button class="btn btn-sm btn-ghost font-mono text-xs" @click="previewOpen = false">close</button>
+          <button
+            v-if="previewData && !previewLoading && !previewError"
+            class="btn btn-sm btn-primary font-mono text-xs"
+            @click="installFromPreview"
+          >install</button>
+        </div>
+      </div>
+    </dialog>
+
     <!-- Create / Edit modal -->
     <dialog :open="showForm" class="modal" :class="{ 'modal-open': showForm }">
       <div class="modal-box max-w-2xl bg-base-100 border border-base-300 rounded-lg p-0 overflow-hidden">
diff --git a/crates/web/src/api.rs b/crates/web/src/api.rs
index abab794..d5efb4d 100644
--- a/crates/web/src/api.rs
+++ b/crates/web/src/api.rs
@@ -2545,6 +2545,36 @@ pub async fn skill_get_handler(
 #[derive(Deserialize)]
 pub struct SkillImportRequest {
     pub url: String,
+    #[serde(default)]
+    pub conflict_action: Option<String>,
+    #[serde(default)]
+    pub alias_trigger: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct SkillPreviewRequest {
+    pub url: String,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct SkillDiscoverRequest {
+    pub q: String,
+    #[serde(default)]
+    pub sources: Vec<String>,
+    #[serde(default = "default_skill_discover_limit")]
+    pub limit: usize,
+}
+
+fn default_skill_discover_limit() -> usize {
+    12
+}
+
+fn default_skill_discovery_sources() -> Vec<String> {
+    vec![
+        "https://github.com/openai/skills/tree/main/skills".to_string(),
+        "https://github.com/anthropics/skills/tree/main/skills".to_string(),
+        "https://github.com/vercel-labs/agent-skills/tree/main/skills".to_string(),
+    ]
 }
 
 pub async fn skill_import_handler(
@@ -2562,7 +2592,11 @@ pub async fn skill_import_handler(
         }
     };
 
-    let client = match reqwest::Client::builder().user_agent("agent007").build() {
+    let client = match reqwest::Client::builder()
+        .user_agent("agent007")
+        .timeout(std::time::Duration::from_secs(20))
+        .build()
+    {
         Ok(client) => client,
         Err(e) => {
             return (
@@ -2573,7 +2607,7 @@ pub async fn skill_import_handler(
         }
     };
 
-    let imported = match fetch_imported_skill(&client, source, &payload.url).await {
+    let mut imported = match fetch_imported_skill(&client, source, &payload.url).await {
         Ok(imported) => imported,
         Err(e) => {
             return (
@@ -2584,6 +2618,77 @@ pub async fn skill_import_handler(
         }
     };
 
+    let conflict_action = payload
+        .conflict_action
+        .as_deref()
+        .map(|value| value.trim().to_ascii_lowercase());
+    let alias_trigger = payload
+        .alias_trigger
+        .as_deref()
+        .map(normalize_skill_trigger);
+
+    let existing_conflict = installed_skill_conflict_info(&imported.trigger);
+    if existing_conflict.is_some() {
+        match conflict_action.as_deref() {
+            None | Some("") => {
+                return (
+                    StatusCode::CONFLICT,
+                    Json(serde_json::json!({
+                        "error": format!("skill trigger {} already exists", imported.trigger),
+                        "conflict": existing_conflict,
+                    })),
+                )
+                    .into_response()
+            }
+            Some("keep_existing") => {
+                return Json(serde_json::json!({
+                    "ok": true,
+                    "skipped": true,
+                    "trigger": imported.trigger,
+                    "conflict": existing_conflict,
+                }))
+                .into_response()
+            }
+            Some("alias") => {
+                let Some(alias_trigger) = alias_trigger.clone() else {
+                    return (
+                        StatusCode::BAD_REQUEST,
+                        Json(serde_json::json!({ "error": "alias_trigger is required when conflict_action=alias" })),
+                    )
+                        .into_response();
+                };
+                if installed_skill_conflict_info(&alias_trigger).is_some() {
+                    return (
+                        StatusCode::CONFLICT,
+                        Json(serde_json::json!({
+                            "error": format!("alias trigger {} already exists", alias_trigger),
+                            "conflict": installed_skill_conflict_info(&alias_trigger),
+                        })),
+                    )
+                        .into_response();
+                }
+                match rewrite_imported_skill_trigger(imported, &alias_trigger) {
+                    Ok(rewritten) => imported = rewritten,
+                    Err(e) => {
+                        return (
+                            StatusCode::BAD_REQUEST,
+                            Json(serde_json::json!({ "error": e.to_string() })),
+                        )
+                            .into_response()
+                    }
+                }
+            }
+            Some("replace") => {}
+            Some(other) => return (
+                StatusCode::BAD_REQUEST,
+                Json(
+                    serde_json::json!({ "error": format!("unsupported conflict_action: {other}") }),
+                ),
+            )
+                .into_response(),
+        }
+    }
+
     let skills_dir = agent007_write_home().join("skills");
     let _ = std::fs::create_dir_all(&skills_dir);
 
@@ -2603,16 +2708,328 @@ pub async fn skill_import_handler(
 }
 
 pub async fn skill_registry_handler() -> impl IntoResponse {
-    let registry_url =
-        "https://raw.githubusercontent.com/danieldear/agent007/main/docs/registry.json";
-    let client = reqwest::Client::new();
-    match client.get(registry_url).send().await {
-        Ok(resp) if resp.status().is_success() => match resp.json::<serde_json::Value>().await {
-            Ok(val) => Json(val).into_response(),
-            Err(_) => Json(serde_json::json!([])).into_response(),
-        },
-        _ => Json(serde_json::json!([])).into_response(),
+    const FALLBACK_REGISTRY_JSON: &str = include_str!("../../../docs/registry.json");
+
+    let fallback = serde_json::from_str::<serde_json::Value>(FALLBACK_REGISTRY_JSON)
+        .unwrap_or_else(|_| serde_json::json!([]));
+    Json(fallback).into_response()
+}
+
+fn installed_skill_conflict_info(trigger: &str) -> Option<SkillConflictInfo> {
+    let global_dir = agent007_global_home().join("skills");
+    let mut variants = Vec::new();
+    for dir in skills_search_dirs() {
+        let source = if dir == global_dir {
+            "global"
+        } else {
+            "project"
+        };
+        for skill in load_skills_from_dir(&dir) {
+            if skill.trigger() != trigger {
+                continue;
+            }
+            variants.push(serde_json::json!({
+                "source": source,
+                "name": skill.name(),
+                "version": skill.version(),
+                "path": skill.entry_path().display().to_string(),
+            }));
+        }
+    }
+    if variants.is_empty() {
+        None
+    } else {
+        Some(SkillConflictInfo {
+            trigger: trigger.to_string(),
+            variants,
+        })
+    }
+}
+
+pub async fn skill_preview_handler(
+    State(_state): State<AppState>,
+    Json(payload): Json<SkillPreviewRequest>,
+) -> impl IntoResponse {
+    let source = match parse_skill_import_source(&payload.url) {
+        Ok(source) => source,
+        Err(e) => {
+            return (
+                StatusCode::BAD_REQUEST,
+                Json(serde_json::json!({ "error": e.to_string() })),
+            )
+                .into_response()
+        }
+    };
+
+    let client = match reqwest::Client::builder()
+        .user_agent("agent007")
+        .timeout(std::time::Duration::from_secs(20))
+        .build()
+    {
+        Ok(client) => client,
+        Err(e) => {
+            return (
+                StatusCode::INTERNAL_SERVER_ERROR,
+                Json(serde_json::json!({ "error": e.to_string() })),
+            )
+                .into_response()
+        }
+    };
+
+    let imported = match fetch_imported_skill(&client, source, &payload.url).await {
+        Ok(imported) => imported,
+        Err(e) => {
+            return (
+                StatusCode::BAD_GATEWAY,
+                Json(serde_json::json!({ "error": e.to_string() })),
+            )
+                .into_response()
+        }
+    };
+
+    let (content, files, package) = match &imported.storage {
+        ImportedSkillStorage::Flat { content, .. } => (content.clone(), Vec::new(), false),
+        ImportedSkillStorage::Package { files, .. } => {
+            let skill_content = files
+                .iter()
+                .find(|(relative, _)| relative.eq_ignore_ascii_case("SKILL.md"))
+                .map(|(_, content)| content.clone())
+                .unwrap_or_default();
+            let file_list = files.iter().map(|(relative, _)| relative.clone()).collect();
+            (skill_content, file_list, true)
+        }
+    };
+
+    let fallback_slug = fallback_skill_slug_from_url(&payload.url);
+    let summary = match extract_skill_manifest_summary(&content, &fallback_slug, &payload.url) {
+        Some(summary) => summary,
+        None => {
+            return (
+                StatusCode::BAD_REQUEST,
+                Json(serde_json::json!({ "error": "preview source does not look like a skill manifest" })),
+            )
+                .into_response()
+        }
+    };
+    let conflict = installed_skill_conflict_info(&summary.trigger);
+
+    Json(serde_json::json!({
+        "name": summary.name,
+        "trigger": summary.trigger,
+        "description": summary.description,
+        "model": summary.model,
+        "category": summary.category,
+        "version": summary.version,
+        "body": summary.body,
+        "url": payload.url,
+        "package": package,
+        "files": files,
+        "conflict": conflict,
+    }))
+    .into_response()
+}
+
+pub async fn skill_discover_handler(
+    State(_state): State<AppState>,
+    Json(payload): Json<SkillDiscoverRequest>,
+) -> impl IntoResponse {
+    let query = payload.q.trim().to_string();
+    if query.is_empty() {
+        return (
+            StatusCode::BAD_REQUEST,
+            Json(serde_json::json!({ "error": "query is required" })),
+        )
+            .into_response();
+    }
+
+    let client = match reqwest::Client::builder()
+        .user_agent("agent007")
+        .timeout(std::time::Duration::from_secs(20))
+        .build()
+    {
+        Ok(client) => client,
+        Err(e) => {
+            return (
+                StatusCode::INTERNAL_SERVER_ERROR,
+                Json(serde_json::json!({ "error": e.to_string() })),
+            )
+                .into_response()
+        }
+    };
+
+    let limit = payload.limit.clamp(1, 50);
+    let tokens = query_tokens(&query);
+    let mut results = Vec::new();
+    let mut seen_urls = std::collections::BTreeSet::new();
+
+    let sources = if payload.sources.is_empty() {
+        default_skill_discovery_sources()
+    } else {
+        payload.sources.clone()
+    };
+
+    for source_url in &sources {
+        let source = match parse_skill_discovery_source(source_url) {
+            Ok(source) => source,
+            Err(e) => {
+                return (
+                    StatusCode::BAD_REQUEST,
+                    Json(serde_json::json!({ "error": format!("{source_url}: {e}") })),
+                )
+                    .into_response()
+            }
+        };
+
+        let tree_url =
+            github_tree_api_url(&source.owner, &source.repo, source.reference.as_deref());
+        let response = match client.get(&tree_url).send().await {
+            Ok(response) => response,
+            Err(e) => {
+                return (
+                    StatusCode::BAD_GATEWAY,
+                    Json(serde_json::json!({ "error": format!("failed to query GitHub tree for {}: {e}", source.source_url) })),
+                )
+                    .into_response()
+            }
+        };
+        if !response.status().is_success() {
+            return (
+                StatusCode::BAD_GATEWAY,
+                Json(serde_json::json!({ "error": format!("GitHub tree fetch failed — HTTP {} for {}", response.status(), source.source_url) })),
+            )
+                .into_response();
+        }
+        let tree: GitHubTreeResponse = match response.json().await {
+            Ok(tree) => tree,
+            Err(e) => {
+                return (
+                    StatusCode::BAD_GATEWAY,
+                    Json(serde_json::json!({ "error": format!("failed to parse GitHub tree response for {}: {e}", source.source_url) })),
+                )
+                    .into_response()
+            }
+        };
+        if tree.truncated {
+            return (
+                StatusCode::BAD_GATEWAY,
+                Json(serde_json::json!({ "error": format!("GitHub tree response was truncated for {}; narrow the source path", source.source_url) })),
+            )
+                .into_response();
+        }
+
+        let prefix = source.path.trim_matches('/').to_string();
+        let query_lc = query.to_ascii_lowercase();
+        let mut candidates: Vec<String> = tree
+            .tree
+            .into_iter()
+            .filter(|entry| entry.kind == "blob")
+            .filter(|entry| entry.path.ends_with(".md") || entry.path.ends_with(".MD"))
+            .filter(|entry| {
+                if prefix.is_empty() {
+                    true
+                } else {
+                    entry.path == prefix || entry.path.starts_with(&(prefix.clone() + "/"))
+                }
+            })
+            .filter(|entry| is_discoverable_skill_markdown_path(&entry.path, &prefix))
+            .map(|entry| entry.path)
+            .collect();
+        candidates.sort();
+        let mut source_matches: Vec<(i32, SkillDiscoverResult)> = Vec::new();
+
+        for path in candidates {
+            let is_package = FsPath::new(&path)
+                .file_name()
+                .and_then(|name| name.to_str())
+                .map(|name| name.eq_ignore_ascii_case("SKILL.md"))
+                .unwrap_or(false);
+            let file_url = github_raw_file_url(
+                &source.owner,
+                &source.repo,
+                source.reference.as_deref(),
+                &path,
+            );
+            let content = match fetch_text_async(&client, &file_url).await {
+                Ok(content) => content,
+                Err(_) => continue,
+            };
+            if !is_package && !has_skill_like_frontmatter(&content) {
+                continue;
+            }
+            let fallback_slug = fallback_skill_slug_from_url(&file_url);
+            let Some(summary) = extract_skill_manifest_summary(&content, &fallback_slug, &file_url)
+            else {
+                continue;
+            };
+            let Some(score) =
+                skill_summary_match_score(&summary, &path, &source, &query_lc, &tokens)
+            else {
+                continue;
+            };
+            let install_url = if is_package {
+                github_tree_html_url(
+                    &source.owner,
+                    &source.repo,
+                    source.reference.as_deref(),
+                    FsPath::new(&path)
+                        .parent()
+                        .map(|parent| parent.to_string_lossy().to_string())
+                        .unwrap_or_default()
+                        .as_str(),
+                )
+            } else {
+                github_blob_html_url(
+                    &source.owner,
+                    &source.repo,
+                    source.reference.as_deref(),
+                    &path,
+                )
+            };
+
+            if !seen_urls.insert(install_url.clone()) {
+                continue;
+            }
+
+            let conflict = installed_skill_conflict_info(&summary.trigger);
+            source_matches.push((
+                score,
+                SkillDiscoverResult {
+                    name: summary.name,
+                    trigger: summary.trigger.clone(),
+                    description: summary.description,
+                    repo: format!("{}/{}", source.owner, source.repo),
+                    reference: source
+                        .reference
+                        .clone()
+                        .unwrap_or_else(|| "HEAD".to_string()),
+                    path: path.clone(),
+                    url: install_url,
+                    source_url: source.source_url.clone(),
+                    package: is_package,
+                    trust: "public".to_string(),
+                    version: summary.version,
+                    category: summary.category,
+                    model: summary.model,
+                    installed: conflict.is_some(),
+                    conflict,
+                },
+            ));
+        }
+
+        source_matches.sort_by(|a, b| b.0.cmp(&a.0).then_with(|| a.1.name.cmp(&b.1.name)));
+        for (_, result) in source_matches {
+            if results.len() >= limit {
+                break;
+            }
+            results.push(result);
+        }
+
+        if results.len() >= limit {
+            break;
+        }
     }
+
+    Json(serde_json::json!({ "results": results })).into_response()
 }
 
 #[derive(Debug)]
@@ -2657,6 +3074,9 @@ struct SkillImportFrontmatter {
     trigger: Option<String>,
     name: Option<String>,
     description: Option<String>,
+    model: Option<String>,
+    category: Option<String>,
+    version: Option<String>,
 }
 
 #[derive(Debug, Deserialize)]
@@ -2667,6 +3087,68 @@ struct GitHubContentEntry {
     download_url: Option<String>,
 }
 
+#[derive(Debug, Deserialize)]
+struct GitHubTreeResponse {
+    tree: Vec<GitHubTreeEntry>,
+    truncated: bool,
+}
+
+#[derive(Debug, Deserialize)]
+struct GitHubTreeEntry {
+    path: String,
+    #[serde(rename = "type")]
+    kind: String,
+}
+
+#[derive(Debug, Clone)]
+struct SkillManifestSummary {
+    trigger: String,
+    name: String,
+    description: String,
+    model: Option<String>,
+    category: Option<String>,
+    version: Option<String>,
+    body: String,
+}
+
+#[derive(Debug, Clone)]
+struct SkillDiscoverSource {
+    owner: String,
+    repo: String,
+    reference: Option<String>,
+    path: String,
+    source_url: String,
+}
+
+#[derive(Debug, Clone, Serialize)]
+struct SkillConflictInfo {
+    trigger: String,
+    variants: Vec<Value>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+struct SkillDiscoverResult {
+    name: String,
+    trigger: String,
+    description: String,
+    repo: String,
+    reference: String,
+    path: String,
+    url: String,
+    source_url: String,
+    package: bool,
+    trust: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    version: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    category: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    model: Option<String>,
+    installed: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    conflict: Option<SkillConflictInfo>,
+}
+
 fn parse_skill_import_source(url: &str) -> anyhow::Result<SkillImportSourceKind> {
     let url = url.trim();
 
@@ -2731,6 +3213,260 @@ fn parse_skill_import_source(url: &str) -> anyhow::Result<SkillImportSourceKind>
     ))
 }
 
+fn parse_skill_discovery_source(url: &str) -> anyhow::Result<SkillDiscoverSource> {
+    match parse_skill_import_source(url)? {
+        SkillImportSourceKind::GitHubDir {
+            owner,
+            repo,
+            reference,
+            path,
+        } => Ok(SkillDiscoverSource {
+            owner,
+            repo,
+            reference,
+            path,
+            source_url: url.trim().to_string(),
+        }),
+        SkillImportSourceKind::GitHubFile {
+            owner,
+            repo,
+            reference,
+            path,
+        } => Ok(SkillDiscoverSource {
+            owner,
+            repo,
+            reference,
+            path: FsPath::new(&path)
+                .parent()
+                .map(|parent| parent.to_string_lossy().to_string())
+                .unwrap_or_default(),
+            source_url: url.trim().to_string(),
+        }),
+        SkillImportSourceKind::DirectFile { .. } => Err(anyhow::anyhow!(
+            "discovery sources must be GitHub repository, tree, or package URLs"
+        )),
+    }
+}
+
+fn is_discoverable_skill_markdown_path(path: &str, source_prefix: &str) -> bool {
+    let normalized = path.replace('\\', "/");
+    let lower = normalized.to_ascii_lowercase();
+    if lower.contains("/references/")
+        || lower.contains("/reference/")
+        || lower.contains("/examples/")
+        || lower.contains("/example/")
+        || lower.contains("/assets/")
+        || lower.contains("/docs/")
+        || lower.ends_with("/readme.md")
+        || lower == "readme.md"
+    {
+        return false;
+    }
+    if !source_prefix.trim().is_empty() {
+        return lower.ends_with("/skill.md")
+            || lower == "skill.md"
+            || looks_like_flat_skill_markdown_path(&lower);
+    }
+    lower.ends_with("/skill.md")
+        || lower == "skill.md"
+        || looks_like_flat_skill_markdown_path(&lower)
+}
+
+fn looks_like_flat_skill_markdown_path(lower: &str) -> bool {
+    if let Some(rest) = lower.strip_prefix("skills/") {
+        return !rest.contains('/') && rest.ends_with(".md");
+    }
+    if let Some((_, rest)) = lower.split_once("/.codex/skills/") {
+        return !rest.contains('/') && rest.ends_with(".md");
+    }
+    if let Some((_, rest)) = lower.split_once("/.claude/") {
+        return !rest.contains('/') && rest.ends_with(".md");
+    }
+    false
+}
+
+fn has_skill_like_frontmatter(content: &str) -> bool {
+    let parts: Vec<&str> = content.splitn(3, "---").collect();
+    if parts.len() < 3 {
+        return false;
+    }
+    match serde_yaml::from_str::<SkillImportFrontmatter>(parts[1]) {
+        Ok(frontmatter) => frontmatter.trigger.is_some() || frontmatter.name.is_some(),
+        Err(_) => false,
+    }
+}
+
+fn extract_skill_manifest_summary(
+    content: &str,
+    fallback_slug: &str,
+    original_url: &str,
+) -> Option<SkillManifestSummary> {
+    let url_trigger = format!("/{fallback_slug}");
+    let fallback_name = fallback_slug
+        .split('-')
+        .map(|w| {
+            let mut c = w.chars();
+            match c.next() {
+                None => String::new(),
+                Some(f) => f.to_uppercase().collect::<String>() + c.as_str(),
+            }
+        })
+        .collect::<Vec<_>>()
+        .join(" ");
+    let parts: Vec<&str> = content.splitn(3, "---").collect();
+    if parts.len() < 3 {
+        return Some(SkillManifestSummary {
+            trigger: url_trigger,
+            name: fallback_name,
+            description: format!("Imported from {original_url}"),
+            model: None,
+            category: None,
+            version: None,
+            body: content.trim().to_string(),
+        });
+    }
+    let frontmatter = serde_yaml::from_str::<SkillImportFrontmatter>(parts[1]).ok();
+    let frontmatter = frontmatter.unwrap_or(SkillImportFrontmatter {
+        trigger: None,
+        name: None,
+        description: None,
+        model: None,
+        category: None,
+        version: None,
+    });
+    Some(SkillManifestSummary {
+        trigger: frontmatter.trigger.unwrap_or(url_trigger),
+        name: frontmatter.name.unwrap_or(fallback_name),
+        description: frontmatter
+            .description
+            .unwrap_or_else(|| format!("Imported from {original_url}")),
+        model: frontmatter.model,
+        category: frontmatter.category,
+        version: frontmatter.version,
+        body: parts[2].trim_start_matches('\n').to_string(),
+    })
+}
+
+fn skill_summary_match_score(
+    summary: &SkillManifestSummary,
+    path: &str,
+    source: &SkillDiscoverSource,
+    query_lc: &str,
+    tokens: &[String],
+) -> Option<i32> {
+    let name = summary.name.to_ascii_lowercase();
+    let trigger = summary.trigger.to_ascii_lowercase();
+    let description = summary.description.to_ascii_lowercase();
+    let path_lc = path.to_ascii_lowercase();
+    let repo = format!("{}/{}", source.owner, source.repo).to_ascii_lowercase();
+    let body = summary.body.to_ascii_lowercase();
+    let metadata = [
+        name.as_str(),
+        trigger.as_str(),
+        description.as_str(),
+        path_lc.as_str(),
+        repo.as_str(),
+    ]
+    .join(" ");
+    let combined = format!("{metadata}\n{body}");
+    let combined_tokens = query_tokens(&combined);
+    let short_exact_query = tokens.len() == 1 && query_lc.len() <= 2;
+
+    let phrase_in_name = field_matches_query(&name, query_lc, short_exact_query);
+    let phrase_in_trigger = field_matches_query(&trigger, query_lc, short_exact_query);
+    let phrase_in_description = field_matches_query(&description, query_lc, short_exact_query);
+    let phrase_in_path = field_matches_query(&path_lc, query_lc, short_exact_query);
+    let phrase_in_repo = field_matches_query(&repo, query_lc, short_exact_query);
+    let phrase_in_body = field_matches_query(&body, query_lc, short_exact_query);
+
+    let token_hits = tokens
+        .iter()
+        .filter(|token| combined_tokens.iter().any(|candidate| candidate == *token))
+        .count() as i32;
+    let all_tokens_match = !tokens.is_empty() && token_hits as usize == tokens.len();
+    let any_token_match = token_hits > 0;
+    let phrase_match = phrase_in_name
+        || phrase_in_trigger
+        || phrase_in_description
+        || phrase_in_path
+        || phrase_in_repo
+        || phrase_in_body;
+
+    if !phrase_match && !any_token_match {
+        return None;
+    }
+
+    let mut score = 0;
+    if phrase_in_name || phrase_in_trigger {
+        score += 140;
+    }
+    if phrase_in_description {
+        score += 110;
+    }
+    if phrase_in_path {
+        score += 90;
+    }
+    if phrase_in_repo {
+        score += 70;
+    }
+    if phrase_in_body {
+        score += 60;
+    }
+    if all_tokens_match {
+        score += 50;
+    } else {
+        score += token_hits * 15;
+    }
+    if summary.model.is_some() {
+        score += 2;
+    }
+    if summary.version.is_some() {
+        score += 1;
+    }
+
+    Some(score)
+}
+
+fn field_matches_query(field: &str, query_lc: &str, exact_token_only: bool) -> bool {
+    if exact_token_only {
+        return query_tokens(field).iter().any(|token| token == query_lc);
+    }
+    field.contains(query_lc)
+}
+
+fn query_tokens(query: &str) -> Vec<String> {
+    query
+        .split(|c: char| !(c.is_ascii_alphanumeric() || c == '-' || c == '_'))
+        .map(|token| token.trim().to_ascii_lowercase())
+        .filter(|token| token.len() >= 2)
+        .collect()
+}
+
+fn github_tree_api_url(owner: &str, repo: &str, reference: Option<&str>) -> String {
+    let reference = reference.unwrap_or("HEAD");
+    format!("https://api.github.com/repos/{owner}/{repo}/git/trees/{reference}?recursive=1")
+}
+
+fn github_blob_html_url(owner: &str, repo: &str, reference: Option<&str>, path: &str) -> String {
+    let reference = reference.unwrap_or("HEAD");
+    format!(
+        "https://github.com/{owner}/{repo}/blob/{reference}/{}",
+        path.trim_start_matches('/')
+    )
+}
+
+fn github_tree_html_url(owner: &str, repo: &str, reference: Option<&str>, path: &str) -> String {
+    let reference = reference.unwrap_or("HEAD");
+    if path.trim().is_empty() {
+        format!("https://github.com/{owner}/{repo}/tree/{reference}")
+    } else {
+        format!(
+            "https://github.com/{owner}/{repo}/tree/{reference}/{}",
+            path.trim_start_matches('/')
+        )
+    }
+}
+
 async fn fetch_imported_skill(
     client: &reqwest::Client,
     source: SkillImportSourceKind,
@@ -2893,6 +3629,49 @@ async fn fetch_text_async(client: &reqwest::Client, url: &str) -> anyhow::Result
         .map_err(|e| anyhow::anyhow!("failed to read response body: {e}"))
 }
 
+fn rewrite_imported_skill_trigger(
+    mut imported: ImportedSkill,
+    new_trigger: &str,
+) -> anyhow::Result<ImportedSkill> {
+    match &mut imported.storage {
+        ImportedSkillStorage::Flat { filename, content } => {
+            *content = rewrite_skill_trigger_in_content(content, new_trigger)?;
+            *filename = format!("{}.md", sanitize_skill_slug(new_trigger, "imported-skill"));
+        }
+        ImportedSkillStorage::Package {
+            package_name,
+            files,
+        } => {
+            let skill_index = files
+                .iter()
+                .position(|(relative, _)| relative.eq_ignore_ascii_case("SKILL.md"))
+                .ok_or_else(|| anyhow::anyhow!("package is missing SKILL.md"))?;
+            files[skill_index].1 =
+                rewrite_skill_trigger_in_content(&files[skill_index].1, new_trigger)?;
+            *package_name = sanitize_skill_slug(new_trigger, "imported-skill");
+        }
+    }
+    imported.trigger = new_trigger.to_string();
+    Ok(imported)
+}
+
+fn rewrite_skill_trigger_in_content(content: &str, new_trigger: &str) -> anyhow::Result<String> {
+    let parts: Vec<&str> = content.splitn(3, "---").collect();
+    if parts.len() < 3 {
+        anyhow::bail!("skill content is missing YAML frontmatter");
+    }
+    let mut frontmatter: serde_yaml::Mapping = serde_yaml::from_str(parts[1])
+        .map_err(|e| anyhow::anyhow!("failed to parse skill frontmatter: {e}"))?;
+    frontmatter.insert(
+        serde_yaml::Value::String("trigger".to_string()),
+        serde_yaml::Value::String(new_trigger.to_string()),
+    );
+    let yaml = serde_yaml::to_string(&frontmatter)
+        .map_err(|e| anyhow::anyhow!("failed to serialize skill frontmatter: {e}"))?;
+    let yaml = yaml.strip_prefix("---\n").unwrap_or(yaml.as_str());
+    Ok(format!("---\n{}---\n{}", yaml, parts[2]))
+}
+
 fn write_imported_skill(
     skills_dir: &FsPath,
     imported: ImportedSkill,
@@ -2975,6 +3754,9 @@ fn normalize_skill_manifest_content(
                     trigger: None,
                     name: None,
                     description: None,
+                    model: None,
+                    category: None,
+                    version: None,
                 },
                 content.to_string(),
                 false,
@@ -2986,6 +3768,9 @@ fn normalize_skill_manifest_content(
                 trigger: None,
                 name: None,
                 description: None,
+                model: None,
+                category: None,
+                version: None,
             },
             content.to_string(),
             false,
@@ -4317,6 +5102,55 @@ fn list_package_files(package_dir: &FsPath) -> Vec<String> {
     files
 }
 
+const MAX_SKILL_ASSOCIATION_SCAN_FILES: usize = 32;
+const MAX_SKILL_ASSOCIATION_SCAN_BYTES: u64 = 128 * 1024;
+
+fn is_skill_association_scan_candidate(path: &FsPath) -> bool {
+    let Some(ext) = path.extension().and_then(|ext| ext.to_str()) else {
+        return false;
+    };
+    matches!(
+        &*ext.to_ascii_lowercase(),
+        "md" | "markdown"
+            | "txt"
+            | "yaml"
+            | "yml"
+            | "toml"
+            | "json"
+            | "py"
+            | "sh"
+            | "js"
+            | "ts"
+            | "jsx"
+            | "tsx"
+            | "rs"
+    )
+}
+
+fn package_association_file_paths(package_dir: &FsPath) -> Vec<std::path::PathBuf> {
+    let mut out = Vec::new();
+    for rel in list_package_files(package_dir) {
+        if out.len() >= MAX_SKILL_ASSOCIATION_SCAN_FILES {
+            break;
+        }
+        let path = package_dir.join(&rel);
+        let Ok(meta) = std::fs::symlink_metadata(&path) else {
+            continue;
+        };
+        if !meta.is_file() || meta.file_type().is_symlink() {
+            continue;
+        }
+        if meta.len() > MAX_SKILL_ASSOCIATION_SCAN_BYTES {
+            continue;
+        }
+        if !is_skill_association_scan_candidate(&path) {
+            continue;
+        }
+        out.push(path);
+    }
+    out
+}
+
 #[derive(Debug, Default, Clone)]
 struct AssociatedAssets {
     tools: std::collections::BTreeSet<String>,
@@ -4404,6 +5238,7 @@ fn collect_association_from_ref(reference: &str, assets: &mut AssociatedAssets)
     if let Some(idx) = normalized.find(".agent007/") {
         let nested = &normalized[idx + ".agent007/".len()..];
         collect_association_from_ref(nested, assets);
+        return;
     }
 
     if let Some(idx) = normalized.find("tools/") {
@@ -4441,8 +5276,10 @@ fn skill_associations(skill: &agent007_skills::Skill) -> AssociatedAssets {
     let mut assets = AssociatedAssets::default();
     extract_associations_from_text(skill.template(), &mut assets);
     if skill.is_package() {
-        for file in list_package_files(skill.entry_path()) {
-            collect_association_from_ref(&file, &mut assets);
+        for path in package_association_file_paths(skill.entry_path()) {
+            if let Ok(content) = std::fs::read_to_string(&path) {
+                extract_associations_from_text(&content, &mut assets);
+            }
         }
     }
     assets
@@ -5088,8 +5925,8 @@ pub async fn etr_cache_clear_handler(State(state): State<AppState>) -> impl Into
 #[cfg(test)]
 mod tests {
     use super::{
-        collect_association_from_ref, parse_bundle_selection, tool_reference_keys,
-        EXTERNAL_WORKFLOW_CONTROL_ERROR,
+        collect_association_from_ref, load_skills_from_dir, parse_bundle_selection,
+        skill_associations, tool_reference_keys, EXTERNAL_WORKFLOW_CONTROL_ERROR,
     };
     use crate::server::WebServer;
     use axum::http::StatusCode;
@@ -5139,6 +5976,59 @@ mod tests {
         assert!(items.is_empty());
     }
 
+    #[test]
+    fn package_association_file_paths_skip_large_and_non_text_files() {
+        let dir = tempfile::tempdir().unwrap();
+        std::fs::write(
+            dir.path().join("small.md"),
+            "Use tools/demo.py
+",
+        )
+        .unwrap();
+        std::fs::write(
+            dir.path().join("large.md"),
+            "x".repeat((super::MAX_SKILL_ASSOCIATION_SCAN_BYTES as usize) + 1),
+        )
+        .unwrap();
+        std::fs::write(dir.path().join("helper.bin"), [0_u8, 159, 146, 150]).unwrap();
+
+        let files = super::package_association_file_paths(dir.path());
+        let names: std::collections::BTreeSet<String> = files
+            .iter()
+            .filter_map(|path| {
+                path.file_name()
+                    .and_then(|name| name.to_str())
+                    .map(str::to_string)
+            })
+            .collect();
+
+        assert!(names.contains("small.md"));
+        assert!(!names.contains("large.md"));
+        assert!(!names.contains("helper.bin"));
+    }
+
+    #[test]
+    fn package_skill_helper_files_do_not_become_ghost_script_refs() {
+        let dir = tempfile::tempdir().unwrap();
+        let skills_dir = dir.path().join(".agent007").join("skills");
+        let package_dir = skills_dir.join("pkg-skill");
+        std::fs::create_dir_all(&package_dir).unwrap();
+        std::fs::write(
+            package_dir.join("SKILL.md"),
+            "---\nname: pkg\ndescription: test\ntrigger: /pkg\nmodel: codex\n---\nUse {{args}}\n",
+        )
+        .unwrap();
+        std::fs::write(package_dir.join("ftm_engine.py"), "print('helper')\n").unwrap();
+
+        let skills = load_skills_from_dir(&skills_dir);
+        assert_eq!(skills.len(), 1);
+        let associations = skill_associations(&skills[0]);
+        assert!(
+            associations.scripts.is_empty(),
+            "package helper files should not be exposed as unresolved script refs"
+        );
+    }
+
     #[tokio::test]
     async fn api_tool_import_quarantine_approve_and_test_flow() {
         let _guard = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
@@ -5230,6 +6120,27 @@ mod tests {
         assert!(assets.tools.iter().any(|tool| tool == "project-setup"));
     }
 
+    #[test]
+    fn collect_association_normalizes_hidden_agent007_tool_paths() {
+        let mut assets = super::AssociatedAssets::default();
+        collect_association_from_ref(".agent007/tools/ftm_engine.py", &mut assets);
+        assert!(assets
+            .tools
+            .iter()
+            .any(|tool| tool == "tools/ftm_engine.py"));
+        assert!(assets
+            .scripts
+            .iter()
+            .any(|tool| tool == "tools/ftm_engine.py"));
+        assert!(
+            !assets
+                .scripts
+                .iter()
+                .any(|tool| tool == ".agent007/tools/ftm_engine.py"),
+            "hidden agent007-prefixed tool path should not survive as ghost script ref"
+        );
+    }
+
     #[tokio::test]
     async fn api_run_accepts_task() {
         let _guard = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
@@ -6504,4 +7415,165 @@ requires_approval = true
         .unwrap();
         assert_eq!(relative, "assets/example.txt");
     }
+
+    #[test]
+    fn parse_skill_discovery_source_from_blob_uses_parent_path() {
+        let parsed = super::parse_skill_discovery_source(
+            "https://github.com/example/repo/blob/main/skills/review-skill/SKILL.md",
+        )
+        .unwrap();
+        assert_eq!(parsed.owner, "example");
+        assert_eq!(parsed.repo, "repo");
+        assert_eq!(parsed.reference.as_deref(), Some("main"));
+        assert_eq!(parsed.path, "skills/review-skill");
+    }
+
+    #[test]
+    fn rewrite_imported_skill_trigger_updates_flat_skill_manifest() {
+        let imported = super::ImportedSkill {
+            trigger: "/old-skill".to_string(),
+            storage: super::ImportedSkillStorage::Flat {
+                filename: "old-skill.md".to_string(),
+                content:
+                    "---\nname: Old Skill\ntrigger: /old-skill\ndescription: Example\n---\nbody"
+                        .to_string(),
+            },
+        };
+        let rewritten = super::rewrite_imported_skill_trigger(imported, "/new-skill").unwrap();
+        assert_eq!(rewritten.trigger, "/new-skill");
+        match rewritten.storage {
+            super::ImportedSkillStorage::Flat { filename, content } => {
+                assert_eq!(filename, "new-skill.md");
+                assert!(content.contains("trigger: /new-skill"));
+            }
+            _ => panic!("expected flat skill"),
+        }
+    }
+
+    #[test]
+    fn extract_skill_manifest_summary_synthesizes_missing_trigger() {
+        let summary = super::extract_skill_manifest_summary(
+            "---\nname: External Skill\ndescription: Test external skill\n---\nBody text",
+            "external-skill",
+            "https://example.com/skills/external-skill/SKILL.md",
+        )
+        .expect("summary should be synthesized");
+        assert_eq!(summary.trigger, "/external-skill");
+        assert_eq!(summary.name, "External Skill");
+        assert_eq!(summary.description, "Test external skill");
+        assert_eq!(summary.body, "Body text");
+    }
+
+    #[test]
+    fn skill_summary_match_score_matches_body_tokens() {
+        let summary = super::SkillManifestSummary {
+            trigger: "/senior-ml-engineer".to_string(),
+            name: "Senior ML Engineer".to_string(),
+            description: "Production ML systems skill".to_string(),
+            model: None,
+            category: Some("ml".to_string()),
+            version: None,
+            body: "Use when you need an ML engineer for model deployment, MLOps, and training pipelines.".to_string(),
+        };
+        let source = super::SkillDiscoverSource {
+            owner: "anthropics".to_string(),
+            repo: "skills".to_string(),
+            reference: Some("main".to_string()),
+            path: "skills".to_string(),
+            source_url: "https://github.com/anthropics/skills/tree/main/skills".to_string(),
+        };
+        let tokens = super::query_tokens("ml engineer");
+        let score = super::skill_summary_match_score(
+            &summary,
+            "skills/senior-ml-engineer/SKILL.md",
+            &source,
+            "ml engineer",
+            &tokens,
+        );
+        assert!(
+            score.is_some(),
+            "body/token matching should find ML engineer"
+        );
+    }
+
+    #[test]
+    fn skill_summary_match_score_rejects_unrelated_query() {
+        let summary = super::SkillManifestSummary {
+            trigger: "/frontend-designer".to_string(),
+            name: "Frontend Designer".to_string(),
+            description: "UI polish and interface design".to_string(),
+            model: None,
+            category: Some("frontend".to_string()),
+            version: None,
+            body: "Craft polished layouts and improve CSS architecture.".to_string(),
+        };
+        let source = super::SkillDiscoverSource {
+            owner: "openai".to_string(),
+            repo: "skills".to_string(),
+            reference: Some("main".to_string()),
+            path: "skills".to_string(),
+            source_url: "https://github.com/openai/skills/tree/main/skills".to_string(),
+        };
+        let tokens = super::query_tokens("ml engineer");
+        let score = super::skill_summary_match_score(
+            &summary,
+            "skills/frontend-designer/SKILL.md",
+            &source,
+            "ml engineer",
+            &tokens,
+        );
+        assert!(score.is_none(), "unrelated skills should not match");
+    }
+
+    #[test]
+    fn skill_summary_match_score_does_not_match_ml_inside_yaml_or_toml() {
+        let summary = super::SkillManifestSummary {
+            trigger: "/openai-yaml".to_string(),
+            name: "OpenAI YAML".to_string(),
+            description: "Schema reference".to_string(),
+            model: None,
+            category: None,
+            version: None,
+            body: "YAML reference for config files.".to_string(),
+        };
+        let source = super::SkillDiscoverSource {
+            owner: "openai".to_string(),
+            repo: "skills".to_string(),
+            reference: Some("main".to_string()),
+            path: "skills".to_string(),
+            source_url: "https://github.com/openai/skills/tree/main/skills".to_string(),
+        };
+        let tokens = super::query_tokens("ml");
+        let score = super::skill_summary_match_score(
+            &summary,
+            "skills/openai_yaml.md",
+            &source,
+            "ml",
+            &tokens,
+        );
+        assert!(
+            score.is_none(),
+            "short token matching should not match YAML/TOML substrings"
+        );
+    }
+
+    #[test]
+    fn discoverable_skill_path_excludes_references_examples_and_docs() {
+        assert!(!super::is_discoverable_skill_markdown_path(
+            "skills/.curated/netlify-deploy/references/netlify-toml.md",
+            "",
+        ));
+        assert!(!super::is_discoverable_skill_markdown_path(
+            "skills/foo/examples/example.md",
+            "",
+        ));
+        assert!(super::is_discoverable_skill_markdown_path(
+            "skills/frontend-design/SKILL.md",
+            "",
+        ));
+        assert!(super::is_discoverable_skill_markdown_path(
+            "skills/review.md",
+            ""
+        ));
+    }
 }
diff --git a/crates/web/src/server.rs b/crates/web/src/server.rs
index 56f30b7..4012ee0 100644
--- a/crates/web/src/server.rs
+++ b/crates/web/src/server.rs
@@ -144,6 +144,8 @@ impl WebServer {
             )
             .route("/api/skills/run", post(api::skills_run_handler))
             .route("/api/skills/import", post(api::skill_import_handler))
+            .route("/api/skills/preview", post(api::skill_preview_handler))
+            .route("/api/skills/discover", post(api::skill_discover_handler))
             .route("/api/skills/generate", post(api::skill_generate_handler))
             .route("/api/skills/detail/{trigger}", get(api::skill_get_handler))
             .route("/api/skill-registry", get(api::skill_registry_handler))
diff --git a/docs/a7bundle-v2.md b/docs/a7bundle-v2.md
new file mode 100644
index 0000000..712a2f7
--- /dev/null
+++ b/docs/a7bundle-v2.md
@@ -0,0 +1,294 @@
+# .a7bundle v2 design
+
+## Goals
+
+- Replace JSON-only `.a7bundle` v1 with a compressed, binary-safe format.
+- Preserve backward compatibility for importing existing v1 bundles.
+- Make bundle contents self-describing, integrity-checked, and portable for P2P sharing.
+- Track artifact versions at save/edit time instead of only at export time.
+
+## Non-goals
+
+- Full signing / trust framework in v2 initial rollout.
+- Content-addressed storage or remote registry protocol.
+- Automatic semantic version inference from prompt or code meaning.
+
+## Problems in v1
+
+```ascii
+v1
+├─ single JSON blob
+├─ content stored as UTF-8 strings only
+├─ weak support for nested dependency trees
+├─ no safe binary payload transport
+├─ large exports due to uncompressed text
+└─ artifact versioning not first-class
+```
+
+## Format overview
+
+`.a7bundle` remains the user-facing extension, but v2 changes the internal container.
+
+```ascii
+.a7bundle v2
+└─ tar.zst archive
+   ├─ manifest.json
+   ├─ skills/
+   ├─ workflows/
+   ├─ personas/
+   ├─ tools/
+   ├─ scripts/
+   └─ assets/
+```
+
+## Manifest schema
+
+```json
+{
+  "bundle_format_version": 2,
+  "bundle_version": 1,
+  "created_at": "2026-05-13T17:30:00Z",
+  "created_by": "agent007 0.3.1",
+  "source_project": "agent007",
+  "entries": [
+    {
+      "path": "skills/review-skill/SKILL.md",
+      "kind": "skill",
+      "artifact_id": "skill:review-skill",
+      "version": "1.2.0",
+      "sha256": "...",
+      "size_bytes": 1823,
+      "executable": false,
+      "media_type": "text/markdown",
+      "encoding": "utf-8",
+      "dependency_group": "skill:review-skill"
+    }
+  ],
+  "dependency_groups": [
+    {
+      "id": "tool:main_test.py",
+      "members": [
+        "tools/main_test.py",
+        "tools/main_test/relatedfiles/helper.txt"
+      ]
+    }
+  ],
+  "unresolved_references": [],
+  "compat": {
+    "imported_from_v1": false
+  }
+}
+```
+
+## Entry rules
+
+Each entry must carry:
+
+- `path`
+- `kind` (`skill`, `workflow`, `persona`, `tool`, `script`, `asset`)
+- `artifact_id`
+- `version`
+- `sha256`
+- `size_bytes`
+- `executable`
+- `media_type`
+- `encoding`
+
+Notes:
+
+- `encoding` is required: use `utf-8` for text assets and `binary` for raw assets.
+- `executable` preserves tool/script executability on import.
+- `dependency_group` ties flat files to sibling support trees.
+
+## Artifact identity
+
+Every managed artifact should have a stable identity model:
+
+```ascii
+artifact identity
+├─ artifact_id
+├─ name
+├─ kind
+├─ version
+├─ created_at
+├─ updated_at
+├─ last_modified_by
+└─ sha256
+```
+
+## Version layers
+
+```ascii
+version layers
+├─ bundle_format_version
+│  └─ schema/container compatibility
+├─ bundle_version
+│  └─ packaging revision of one exported bundle
+└─ artifact version
+   ├─ skill version
+   ├─ workflow version
+   ├─ persona version
+   ├─ tool version
+   └─ script/package version
+```
+
+## Version bump rules
+
+### Artifact version
+
+Artifact version changes on **real persisted content change**.
+
+```ascii
+create
+└─ assign initial version (recommended: 1.0.0 or 0.1.0)
+
+edit + save from dashboard
+└─ bump artifact version
+
+edit + save from hosted LLM
+└─ bump artifact version
+
+CLI save/update
+└─ bump artifact version
+
+save with no content change
+└─ no version bump
+```
+
+Recommended semantics:
+
+- patch = content/prompt/config fix
+- minor = backward-compatible feature expansion
+- major = breaking contract/schema/behavior change
+
+### Import rules
+
+```ascii
+import new artifact
+└─ preserve imported artifact version
+
+import overwrite existing artifact
+├─ if incoming content differs
+│  └─ replace local artifact and preserve incoming version
+└─ if content is identical
+   └─ keep version unchanged
+```
+
+Also record local metadata:
+
+- `imported_at`
+- `imported_from`
+- `imported_bundle_version`
+
+### Export rules
+
+```ascii
+export
+├─ preserve artifact versions exactly
+├─ assign or increment bundle_version
+└─ regenerate manifest hashes
+```
+
+## Dependency closure rules
+
+v2 export should include:
+
+```ascii
+for selected artifact
+├─ explicit file/package itself
+├─ manifest-declared package members
+├─ flat-tool sibling dependency directory (same stem)
+├─ recursively referenced scripts/tools when resolvable
+└─ dependency_groups metadata for reconstruction / preview
+```
+
+## Binary handling
+
+v2 must support raw binary payloads.
+
+```ascii
+binary policy
+├─ store as raw archive entries
+├─ hash raw bytes, not decoded text
+├─ preserve executable bit where relevant
+└─ never force UTF-8 decoding for bundle transport
+```
+
+v1 behavior remains:
+
+```ascii
+v1
+└─ reject binary/non-UTF8 clearly
+```
+
+## Compatibility plan
+
+### Read path
+
+- Importer must detect:
+  - v1 JSON bundle
+  - v2 tar.zst bundle
+- v1 remains importable.
+- v2 becomes the default export format.
+
+### Write path
+
+```ascii
+phase 1
+├─ keep v1 importer
+└─ add v2 exporter/importer
+
+phase 2
+├─ export v2 by default
+└─ keep v1 import only
+
+phase 3
+└─ optionally add v1 export only behind explicit compatibility flag
+```
+
+## UI / API implications
+
+Dashboard should expose:
+
+```ascii
+artifact metadata
+├─ current version
+├─ last modified time
+├─ last modified by
+├─ source scope
+└─ dependency summary
+```
+
+Export preview should show:
+
+```ascii
+bundle preview
+├─ bundle format version
+├─ bundle version
+├─ artifact versions
+├─ binary assets present
+├─ dependency groups
+└─ unresolved refs (if any)
+```
+
+## Suggested implementation order
+
+```ascii
+1. introduce artifact metadata model
+2. bump versions on dashboard/LLM/CLI save paths
+3. add v2 manifest structs
+4. add tar.zst writer/reader
+5. add raw-byte bundle asset support
+6. wire export preview to show version/dependency metadata
+7. keep v1 import compatibility
+8. add future signing/provenance later
+```
+
+## Success criteria
+
+- Export/import supports text and binary assets safely.
+- Flat tool files can bring sibling dependency trees.
+- `.a7bundle` is smaller and self-contained.
+- Each saved artifact carries a meaningful version.
+- Import/export preserves artifact versions correctly.
+- v1 bundles still import successfully.
diff --git a/docs/registry.json b/docs/registry.json
index 8ab0966..566fce0 100644
--- a/docs/registry.json
+++ b/docs/registry.json
@@ -1,29 +1,22 @@
 [
   {
-    "name": "Code Reviewer",
-    "trigger": "/code-review",
-    "description": "Full code review with actionable feedback on bugs, security, and design",
-    "category": "code",
+    "name": "Brainstorm",
+    "trigger": "/brainstorm",
+    "description": "Free-form ideation \u2014 explores a problem space, generates 3\u20135 distinct approaches with trade-offs, and produces a structured ideation document. Use before invoking the architect or PRD workflow.",
+    "category": "project",
     "author": "agent007",
-    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/skills/code-review.md",
+    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/crates/cli/skills/brainstorm.md",
+    "version": "1.1.0",
     "stars": 0
   },
   {
-    "name": "Test Generator",
-    "trigger": "/code-test-gen",
-    "description": "Generate comprehensive test suites with edge cases and mocking",
+    "name": "Documentation Writer",
+    "trigger": "/code-document",
+    "description": "Generate API docs, architecture docs, and inline documentation",
     "category": "code",
     "author": "agent007",
-    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/skills/code-test-gen.md",
-    "stars": 0
-  },
-  {
-    "name": "Security Auditor",
-    "trigger": "/code-security-audit",
-    "description": "Security audit covering OWASP Top 10, secrets, dependencies, and threat modeling",
-    "category": "security",
-    "author": "agent007",
-    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/skills/code-security-audit.md",
+    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/crates/cli/skills/code-document.md",
+    "version": "1.1.0",
     "stars": 0
   },
   {
@@ -32,7 +25,8 @@
     "description": "Profile analysis and performance optimization suggestions",
     "category": "code",
     "author": "agent007",
-    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/skills/code-optimize.md",
+    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/crates/cli/skills/code-optimize.md",
+    "version": "1.1.0",
     "stars": 0
   },
   {
@@ -41,106 +35,128 @@
     "description": "Identify code smells and propose targeted improvements",
     "category": "code",
     "author": "agent007",
-    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/skills/code-refactor.md",
+    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/crates/cli/skills/code-refactor.md",
+    "version": "1.1.0",
     "stars": 0
   },
   {
-    "name": "PR Reviewer",
-    "trigger": "/dev-pr-review",
-    "description": "Thorough pull request review with actionable feedback",
-    "category": "devops",
+    "name": "Security Auditor",
+    "trigger": "/code-security-audit",
+    "description": "Security audit covering OWASP, dependencies, and threat modeling",
+    "category": "code",
     "author": "agent007",
-    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/skills/dev-pr-review.md",
+    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/crates/cli/skills/code-security-audit.md",
+    "version": "1.1.0",
     "stars": 0
   },
   {
-    "name": "TDD Coach",
-    "trigger": "/dev-tdd",
-    "description": "Test-driven development cycle: red-green-refactor with coaching",
+    "name": "Test Generator",
+    "trigger": "/code-test-gen",
+    "description": "Generate comprehensive test suites with edge cases",
     "category": "code",
     "author": "agent007",
-    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/skills/dev-tdd.md",
+    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/crates/cli/skills/code-test-gen.md",
+    "version": "1.1.0",
+    "stars": 0
+  },
+  {
+    "name": "Architect",
+    "trigger": "/dev-architect",
+    "description": "Design system architecture from requirements",
+    "category": "dev",
+    "author": "agent007",
+    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/crates/cli/skills/dev-architect.md",
+    "version": "1.1.0",
     "stars": 0
   },
   {
     "name": "Debugger",
     "trigger": "/dev-debug",
     "description": "Systematic debugging with hypothesis-driven investigation",
-    "category": "code",
+    "category": "dev",
     "author": "agent007",
-    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/skills/dev-debug.md",
+    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/crates/cli/skills/dev-debug.md",
+    "version": "1.1.0",
     "stars": 0
   },
   {
-    "name": "Architect",
-    "trigger": "/dev-architect",
-    "description": "Design system architecture from requirements with diagrams",
-    "category": "architecture",
+    "name": "PR Reviewer",
+    "trigger": "/dev-pr-review",
+    "description": "Thorough pull request review with actionable feedback",
+    "category": "dev",
     "author": "agent007",
-    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/skills/dev-architect.md",
+    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/crates/cli/skills/dev-pr-review.md",
+    "version": "1.1.0",
     "stars": 0
   },
   {
-    "name": "Documentation Writer",
-    "trigger": "/code-document",
-    "description": "Generate API docs, architecture docs, and inline documentation",
-    "category": "docs",
+    "name": "TDD Coach",
+    "trigger": "/dev-tdd",
+    "description": "Test-driven development cycle (red-green-refactor)",
+    "category": "dev",
     "author": "agent007",
-    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/skills/code-document.md",
+    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/crates/cli/skills/dev-tdd.md",
+    "version": "1.1.0",
     "stars": 0
   },
   {
-    "name": "Project Planner",
-    "trigger": "/project-plan",
-    "description": "Break features into tasks with estimates and dependencies",
-    "category": "project",
+    "name": "Codebase Analyzer",
+    "trigger": "/meta-analyze-codebase",
+    "description": "Analyze codebase for tech stack, patterns, and architecture",
+    "category": "meta",
     "author": "agent007",
-    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/skills/project-plan.md",
+    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/crates/cli/skills/meta-analyze-codebase.md",
+    "version": "1.1.0",
     "stars": 0
   },
   {
-    "name": "PRD Writer",
-    "trigger": "/project-prd",
-    "description": "Product requirements document with user stories and constraints",
-    "category": "project",
+    "name": "Agent Creator",
+    "trigger": "/meta-create-agent",
+    "description": "Guided wizard to create a custom agent persona",
+    "category": "meta",
     "author": "agent007",
-    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/skills/project-prd.md",
+    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/crates/cli/skills/meta-create-agent.md",
+    "version": "1.1.0",
     "stars": 0
   },
   {
     "name": "Changelog Generator",
     "trigger": "/project-changelog",
     "description": "Generate changelogs grouped by type from git history",
-    "category": "devops",
+    "category": "project",
     "author": "agent007",
-    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/skills/project-changelog.md",
+    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/crates/cli/skills/project-changelog.md",
+    "version": "1.1.0",
     "stars": 0
   },
   {
-    "name": "Release Manager",
-    "trigger": "/project-release",
-    "description": "Version strategy, release notes, and rollback planning",
-    "category": "devops",
+    "name": "Project Planner",
+    "trigger": "/project-plan",
+    "description": "Break features into tasks with estimates and dependencies",
+    "category": "project",
     "author": "agent007",
-    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/skills/project-release.md",
+    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/crates/cli/skills/project-plan.md",
+    "version": "1.1.0",
     "stars": 0
   },
   {
-    "name": "Frontend Designer",
-    "trigger": "/frontend-designer",
-    "description": "Create distinctive, production-grade frontend interfaces with high design quality",
-    "category": "frontend",
+    "name": "PRD Writer",
+    "trigger": "/project-prd",
+    "description": "Product requirements document with user stories and constraints",
+    "category": "project",
     "author": "agent007",
-    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/skills/Frontend_Designer.md",
+    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/crates/cli/skills/project-prd.md",
+    "version": "1.1.0",
     "stars": 0
   },
   {
-    "name": "Codebase Analyzer",
-    "trigger": "/meta-analyze-codebase",
-    "description": "Analyze codebase for tech stack, patterns, and architecture",
-    "category": "architecture",
+    "name": "Release Manager",
+    "trigger": "/project-release",
+    "description": "Version strategy, release notes, and rollback planning",
+    "category": "project",
     "author": "agent007",
-    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/skills/meta-analyze-codebase.md",
+    "url": "https://raw.githubusercontent.com/danieldear/agent007/main/crates/cli/skills/project-release.md",
+    "version": "1.1.0",
     "stars": 0
   }
 ]