support external skill sources (#981)

packages/client/src/api/hermes/skills.ts

@@ -1,6 +1,6 @@
 import { request } from '../client'
 
-export type SkillSource = 'builtin' | 'hub' | 'local'
+export type SkillSource = 'builtin' | 'hub' | 'local' | 'external'
 
 export interface SkillInfo {
   name: string

packages/client/src/components/hermes/skills/SkillList.vue

@@ -289,6 +289,10 @@ async function handleToggle(category: string, skillName: string, newEnabled: boo
     background: #66bb6a;
 }
 
+.dot-external {
+    background: #f59e0b;
+}
+
 .skill-info {
     flex: 1;
     min-width: 0;

packages/client/src/i18n/locales/de.ts

@@ -423,6 +423,7 @@ jobTriggered: 'Job ausgelost',
       builtin: 'Integriert',
       hub: 'Hub',
       local: 'Lokal',
+      external: 'Extern',
     },
   },
 

packages/client/src/i18n/locales/en.ts

@@ -518,6 +518,7 @@ export default {
       builtin: 'Builtin',
       hub: 'Hub',
       local: 'Local',
+      external: 'External',
     },
   },
 

packages/client/src/i18n/locales/es.ts

@@ -423,6 +423,7 @@ jobTriggered: 'Job ejecutado',
       builtin: 'Integrado',
       hub: 'Hub',
       local: 'Local',
+      external: 'Externo',
     },
   },
 

packages/client/src/i18n/locales/fr.ts

@@ -423,6 +423,7 @@ jobTriggered: 'Job declenche',
       builtin: 'Intégré',
       hub: 'Hub',
       local: 'Local',
+      external: 'Externe',
     },
   },
 

packages/client/src/i18n/locales/ja.ts

@@ -423,6 +423,7 @@ export default {
       builtin: '組み込み',
       hub: 'Hub',
       local: 'ローカル',
+      external: '外部',
     },
   },
 

packages/client/src/i18n/locales/ko.ts

@@ -423,6 +423,7 @@ export default {
       builtin: '내장',
       hub: 'Hub',
       local: '로컬',
+      external: '외부',
     },
   },
 

packages/client/src/i18n/locales/pt.ts

@@ -423,6 +423,7 @@ jobTriggered: 'Job acionado',
       builtin: 'Integrado',
       hub: 'Hub',
       local: 'Local',
+      external: 'Externo',
     },
   },
 

packages/client/src/i18n/locales/zh-TW.ts

@@ -518,6 +518,7 @@ export default {
       builtin: '內建',
       hub: 'Hub 安裝',
       local: '本地安裝',
+      external: '外部目錄',
     },
   },
 

packages/client/src/i18n/locales/zh.ts

@@ -518,6 +518,7 @@ export default {
       builtin: '内置',
       hub: 'Hub 安装',
       local: '本地安装',
+      external: '外部目录',
     },
   },
 

packages/client/src/views/hermes/SkillsView.vue

@@ -139,6 +139,9 @@ function handlePinToggled(name: string, pinned: boolean) {
         <button class="legend-item" :class="{ active: sourceFilter === 'local' }" @click="toggleFilter('local')">
           <span class="legend-dot dot-local" />{{ t('skills.source.local') }}
         </button>
+        <button class="legend-item" :class="{ active: sourceFilter === 'external' }" @click="toggleFilter('external')">
+          <span class="legend-dot dot-external" />{{ t('skills.source.external') }}
+        </button>
         <button class="legend-item" :class="{ active: sourceFilter === 'modified' }" @click="toggleFilter('modified')">
           <span class="modified-icon">✎</span>{{ t('skills.modified') }}
         </button>
@@ -250,6 +253,7 @@ function handlePinToggled(name: string, pinned: boolean) {
 .legend-dot.dot-builtin { background: #888; }
 .legend-dot.dot-hub { background: #4a90d9; }
 .legend-dot.dot-local { background: #66bb6a; }
+.legend-dot.dot-external { background: #f59e0b; }
 
 .modified-icon {
   font-size: 11px;

packages/server/src/controllers/hermes/skills.ts

@@ -1,10 +1,12 @@
-import { mkdir, readdir, readFile, writeFile } from 'fs/promises'
+import { mkdir, readdir, readFile, stat, writeFile } from 'fs/promises'
+import { homedir } from 'os'
 import { join, resolve } from 'path'
 import { createHash } from 'crypto'
 import {
   readConfigYamlForProfile, updateConfigYamlForProfile,
   safeReadFile, extractDescription, listFilesRecursive,
 } from '../../services/config-helpers'
+import type { SkillSource } from '../../services/config-helpers'
 import { isPathWithin } from '../../services/hermes/hermes-path'
 import { getActiveProfileName, getProfileDir } from '../../services/hermes/hermes-profile'
 import { getSkillUsageStatsFromDb } from '../../db/hermes/sessions-db'
@@ -21,6 +23,45 @@ function requestSkillsDir(ctx: any): string {
   return join(requestProfileDir(ctx), 'skills')
 }
 
+function expandConfiguredPath(value: string): string {
+  const expandedEnv = value.replace(/\$\{([^}]+)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (_match, braced, bare) => {
+    return process.env[braced || bare] || ''
+  })
+  if (expandedEnv === '~') return homedir()
+  if (expandedEnv.startsWith('~/')) return join(homedir(), expandedEnv.slice(2))
+  return expandedEnv
+}
+
+async function resolveExternalSkillsDirs(config: Record<string, any>, localSkillsDir: string): Promise<string[]> {
+  const rawDirs = config.skills?.external_dirs
+  const entries = typeof rawDirs === 'string'
+    ? [rawDirs]
+    : Array.isArray(rawDirs)
+      ? rawDirs
+      : []
+  const localResolved = resolve(localSkillsDir)
+  const seen = new Set<string>()
+  const dirs: string[] = []
+
+  for (const rawEntry of entries) {
+    const entry = String(rawEntry || '').trim()
+    if (!entry) continue
+    const expanded = expandConfiguredPath(entry)
+    const resolved = resolve(expanded)
+    if (resolved === localResolved || seen.has(resolved)) continue
+    try {
+      const info = await stat(resolved)
+      if (!info.isDirectory()) continue
+    } catch {
+      continue
+    }
+    seen.add(resolved)
+    dirs.push(resolved)
+  }
+
+  return dirs
+}
+
 /** Read bundled manifest as a name→hash map from ~/.hermes/skills/.bundled_manifest */
 function readBundledManifest(manifestContent: string | null): Map<string, string> {
   const map = new Map<string, string>()
@@ -75,7 +116,7 @@ function getSkillSource(
   dirName: string,
   bundledManifest: Map<string, string>,
   hubNames: Set<string>,
-): 'builtin' | 'hub' | 'local' {
+): SkillSource {
   if (bundledManifest.has(dirName)) return 'builtin'
   if (hubNames.has(dirName)) return 'hub'
   return 'local'
@@ -122,6 +163,31 @@ async function findSkillDirByName(rootDir: string, skillName: string): Promise<s
   return null
 }
 
+async function findSkillDirInRoot(rootDir: string, category: string, skillName: string): Promise<string | null> {
+  if (category === 'misc') {
+    const skillDir = join(rootDir, skillName)
+    const skillMd = await safeReadFile(join(skillDir, 'SKILL.md'))
+    return skillMd !== null ? skillDir : null
+  }
+  return findSkillDirByName(join(rootDir, category), skillName)
+}
+
+async function resolveSkillDirFromConfig(
+  config: Record<string, any>,
+  localSkillsDir: string,
+  category: string,
+  skillName: string,
+): Promise<string | null> {
+  const localSkillDir = await findSkillDirInRoot(localSkillsDir, category, skillName)
+  if (localSkillDir) return localSkillDir
+
+  for (const externalDir of await resolveExternalSkillsDirs(config, localSkillsDir)) {
+    const externalSkillDir = await findSkillDirInRoot(externalDir, category, skillName)
+    if (externalSkillDir) return externalSkillDir
+  }
+  return null
+}
+
 /**
  * Scan for skills at different directory depths.
  *
@@ -248,6 +314,59 @@ async function scanSkillsDir(skillsDir: string, bundledManifest: Map<string, str
   return categories
 }
 
+async function scanExternalSkillsDir(skillsDir: string, disabledList: string[], usageStats: Map<string, UsageStats>) {
+  return scanSkillsDir(skillsDir, new Map(), new Set(), disabledList, usageStats).then(categories =>
+    categories.map(category => ({
+      ...category,
+      skills: category.skills.map((skill: any) => ({
+        ...skill,
+        source: 'external' as SkillSource,
+        modified: undefined,
+      })),
+    })),
+  )
+}
+
+function collectSkillNames(categories: any[]): Set<string> {
+  const names = new Set<string>()
+  for (const category of categories) {
+    for (const skill of category.skills || []) {
+      if (skill?.name) names.add(skill.name)
+    }
+  }
+  return names
+}
+
+function mergeExternalCategories(categories: any[], externalCategories: any[]): any[] {
+  const byName = new Map<string, any>()
+  for (const category of categories) {
+    byName.set(category.name, { ...category, skills: [...category.skills] })
+  }
+
+  const seenSkills = collectSkillNames(categories)
+  for (const externalCategory of externalCategories) {
+    const target = byName.get(externalCategory.name) || {
+      name: externalCategory.name,
+      description: externalCategory.description,
+      skills: [],
+    }
+    for (const skill of externalCategory.skills || []) {
+      if (seenSkills.has(skill.name)) continue
+      seenSkills.add(skill.name)
+      target.skills.push(skill)
+    }
+    if (target.skills.length > 0) byName.set(target.name, target)
+  }
+
+  const merged = [...byName.values()]
+    .filter(category => category.skills.length > 0)
+    .sort((a, b) => a.name.localeCompare(b.name))
+  for (const category of merged) {
+    category.skills.sort((a: any, b: any) => a.name.localeCompare(b.name))
+  }
+  return merged
+}
+
 export async function list(ctx: any) {
   const skillsDir = requestSkillsDir(ctx)
   try {
@@ -260,7 +379,11 @@ export async function list(ctx: any) {
     const usageStats = readUsageStats(await safeReadFile(join(skillsDir, '.usage.json')))
 
     // Scan all skills (supports both two-level and three-level directory structures)
-    const categories = await scanSkillsDir(skillsDir, bundledManifest, hubNames, disabledList, usageStats)
+    let categories = await scanSkillsDir(skillsDir, bundledManifest, hubNames, disabledList, usageStats)
+    for (const externalDir of await resolveExternalSkillsDirs(config, skillsDir)) {
+      const externalCategories = await scanExternalSkillsDir(externalDir, disabledList, usageStats)
+      categories = mergeExternalCategories(categories, externalCategories)
+    }
 
     // Read archived skills from .archive/
     const archived: any[] = []
@@ -329,24 +452,10 @@ export async function toggle(ctx: any) {
 
 export async function listFiles(ctx: any) {
   const { category, skill } = ctx.params
-  const profileDir = requestProfileDir(ctx)
-  const profileSkillsDir = join(profileDir, 'skills')
-  const skillsDir = join(profileSkillsDir, category)
-  if (category === 'misc') {
-    const skillDir = join(profileSkillsDir, skill)
-    try {
-      const allFiles = await listFilesRecursive(skillDir, '')
-      const files = allFiles.filter((f: any) => f.path !== 'SKILL.md')
-      ctx.body = { files }
-    } catch (err: any) {
-      ctx.status = 500
-      ctx.body = { error: err.message }
-    }
-    return
-  }
-  // Recursively find the actual skill directory (supports nested sub-categories like mlops/evaluation/lm-evaluation-harness)
+  const profileSkillsDir = requestSkillsDir(ctx)
   try {
-    const skillDir = await findSkillDirByName(skillsDir, skill)
+    const config = await readConfigYamlForProfile(requestedProfile(ctx))
+    const skillDir = await resolveSkillDirFromConfig(config, profileSkillsDir, category, skill)
     if (!skillDir) {
       ctx.status = 404
       ctx.body = { error: 'Skill not found' }
@@ -363,7 +472,7 @@ export async function listFiles(ctx: any) {
 
 export async function readFile_(ctx: any) {
   const filePath = (ctx.params as any).path
-  const profileSkillsDir = join(requestProfileDir(ctx), 'skills')
+  const profileSkillsDir = requestSkillsDir(ctx)
   // Handle 'misc' category: real skill dir is skills/<skill>, not skills/misc/<skill>
   let realPath = filePath
   if (filePath.startsWith('misc/')) {
@@ -384,8 +493,8 @@ export async function readFile_(ctx: any) {
       const category = parts[0]
       const skillName = parts[1]
       const restPath = parts.slice(2).join('/')
-      const catDir = join(profileSkillsDir, category)
-      const skillDir = await findSkillDirByName(catDir, skillName)
+      const config = await readConfigYamlForProfile(requestedProfile(ctx))
+      const skillDir = await resolveSkillDirFromConfig(config, profileSkillsDir, category, skillName)
       if (skillDir) {
         const resolvedPath = resolve(join(skillDir, restPath))
         if (isPathWithin(resolvedPath, skillDir)) {

packages/server/src/services/config-helpers.ts

@@ -43,7 +43,7 @@ export const PROVIDER_ENV_MAP: Record<string, { api_key_env: string; base_url_en
 
 // --- Types ---
 
-export type SkillSource = 'builtin' | 'hub' | 'local'
+export type SkillSource = 'builtin' | 'hub' | 'local' | 'external'
 
 export interface SkillInfo {
   name: string