fix: surface skill loading errors to users instead of silently dropping them

When skills fail validation during discovery (missing frontmatter fields,
name/directory mismatch, invalid name format, bad description length),
the errors were only logged to console.error() with no user-facing feedback.

This change:
- Adds SkillLoadWarning type to track failed skills with reasons
- Collects warnings in SkillsManager during discoverSkills()
- Exposes warnings via getLoadWarnings() method
- Sends warnings to webview alongside skills metadata
- Displays collapsible warning banner in Skills Settings UI
- Adds 7 new tests for warning collection behavior

Fixes #12194

Author: xk

packages/types/src/skills.ts

@@ -20,6 +20,22 @@ export interface SkillMetadata {
 	modeSlugs?: string[]
 }
 
+/**
+ * Warning emitted when a skill fails to load during discovery.
+ * Collected by SkillsManager and surfaced to the UI so users know
+ * which skills were skipped and why.
+ */
+export interface SkillLoadWarning {
+	/** Directory name of the skill that failed to load */
+	skillName: string
+	/** Absolute path to the skill directory */
+	path: string
+	/** Whether this was a global or project skill */
+	source: "global" | "project"
+	/** Human-readable reason the skill was skipped */
+	reason: string
+}
+
 /**
  * Skill name validation constants per agentskills.io specification:
  * https://agentskills.io/specification

packages/types/src/vscode-extension-host.ts

@@ -20,7 +20,7 @@ import type { GitCommit } from "./git.js"
 import type { McpServer } from "./mcp.js"
 import type { ModelRecord, RouterModels } from "./model.js"
 import type { OpenAiCodexRateLimitInfo } from "./providers/openai-codex-rate-limits.js"
-import type { SkillMetadata } from "./skills.js"
+import type { SkillMetadata, SkillLoadWarning } from "./skills.js"
 import type { WorktreeIncludeStatus } from "./worktree.js"
 
 /**
@@ -180,6 +180,7 @@ export interface ExtensionMessage {
 	organizationId?: string | null // For organizationSwitchResult
 	tools?: SerializedCustomToolDefinition[] // For customToolsResult
 	skills?: SkillMetadata[] // For skills response
+	skillLoadWarnings?: SkillLoadWarning[] // For skill load warnings
 	modes?: { slug: string; name: string }[] // For modes response
 	aggregatedCosts?: {
 		// For taskWithAggregatedCosts response

src/core/webview/skillsMessageHandler.ts

@@ -1,6 +1,6 @@
 import * as vscode from "vscode"
 
-import type { SkillMetadata, WebviewMessage } from "@roo-code/types"
+import type { SkillMetadata, SkillLoadWarning, WebviewMessage } from "@roo-code/types"
 
 import type { ClineProvider } from "./ClineProvider"
 import { openFile } from "../../integrations/misc/open-file"
@@ -16,7 +16,8 @@ export async function handleRequestSkills(provider: ClineProvider): Promise<Skil
 		const skillsManager = provider.getSkillsManager()
 		if (skillsManager) {
 			const skills = skillsManager.getSkillsMetadata()
-			await provider.postMessageToWebview({ type: "skills", skills })
+			const skillLoadWarnings = skillsManager.getLoadWarnings()
+			await provider.postMessageToWebview({ type: "skills", skills, skillLoadWarnings })
 			return skills
 		} else {
 			await provider.postMessageToWebview({ type: "skills", skills: [] })

src/services/skills/SkillsManager.ts

@@ -12,14 +12,16 @@ import {
 	validateSkillName as validateSkillNameShared,
 	SkillNameValidationError,
 	SKILL_NAME_MAX_LENGTH,
+	SkillLoadWarning,
 } from "@roo-code/types"
 import { t } from "../../i18n"
 
 // Re-export for convenience
-export type { SkillMetadata, SkillContent }
+export type { SkillMetadata, SkillContent, SkillLoadWarning }
 
 export class SkillsManager {
 	private skills: Map<string, SkillMetadata> = new Map()
+	private loadWarnings: SkillLoadWarning[] = []
 	private providerRef: WeakRef<ClineProvider>
 	private disposables: vscode.Disposable[] = []
 	private isDisposed = false
@@ -42,6 +44,7 @@ export class SkillsManager {
 	 */
 	async discoverSkills(): Promise<void> {
 		this.skills.clear()
+		this.loadWarnings = []
 		const skillsDirs = await this.getSkillsDirectories()
 
 		for (const { dir, source, mode } of skillsDirs) {
@@ -98,6 +101,8 @@ export class SkillsManager {
 		const skillMdPath = path.join(skillDir, "SKILL.md")
 		if (!(await fileExists(skillMdPath))) return
 
+		const effectiveSkillName = skillName || path.basename(skillDir)
+
 		try {
 			const fileContent = await fs.readFile(skillMdPath, "utf-8")
 
@@ -106,27 +111,34 @@ export class SkillsManager {
 
 			// Validate required fields (only name and description for now)
 			if (!frontmatter.name || typeof frontmatter.name !== "string") {
-				console.error(`Skill at ${skillDir} is missing required 'name' field`)
+				const reason = `Missing required 'name' field in frontmatter`
+				console.error(`Skill at ${skillDir}: ${reason}`)
+				this.loadWarnings.push({ skillName: effectiveSkillName, path: skillDir, source, reason })
 				return
 			}
 			if (!frontmatter.description || typeof frontmatter.description !== "string") {
-				console.error(`Skill at ${skillDir} is missing required 'description' field`)
+				const reason = `Missing required 'description' field in frontmatter`
+				console.error(`Skill at ${skillDir}: ${reason}`)
+				this.loadWarnings.push({ skillName: effectiveSkillName, path: skillDir, source, reason })
 				return
 			}
 
 			// Validate that frontmatter name matches the skill name (directory name or symlink name)
 			// Per the Agent Skills spec: "name field must match the parent directory name"
-			const effectiveSkillName = skillName || path.basename(skillDir)
 			if (frontmatter.name !== effectiveSkillName) {
-				console.error(`Skill name "${frontmatter.name}" doesn't match directory "${effectiveSkillName}"`)
+				const reason = `Frontmatter name "${frontmatter.name}" doesn't match directory name "${effectiveSkillName}"`
+				console.error(`Skill at ${skillDir}: ${reason}`)
+				this.loadWarnings.push({ skillName: effectiveSkillName, path: skillDir, source, reason })
 				return
 			}
 
 			// Validate skill name per agentskills.io spec using shared validation
 			const nameValidation = validateSkillNameShared(effectiveSkillName)
 			if (!nameValidation.valid) {
 				const errorMessage = this.getSkillNameErrorMessage(effectiveSkillName, nameValidation.error!)
-				console.error(`Skill name "${effectiveSkillName}" is invalid: ${errorMessage}`)
+				const reason = `Invalid skill name: ${errorMessage}`
+				console.error(`Skill "${effectiveSkillName}": ${reason}`)
+				this.loadWarnings.push({ skillName: effectiveSkillName, path: skillDir, source, reason })
 				return
 			}
 
@@ -135,9 +147,9 @@ export class SkillsManager {
 			// - non-empty (after trimming)
 			const description = frontmatter.description.trim()
 			if (description.length < 1 || description.length > 1024) {
-				console.error(
-					`Skill "${effectiveSkillName}" has an invalid description length: must be 1-1024 characters (got ${description.length})`,
-				)
+				const reason = `Invalid description length: must be 1-1024 characters (got ${description.length})`
+				console.error(`Skill "${effectiveSkillName}": ${reason}`)
+				this.loadWarnings.push({ skillName: effectiveSkillName, path: skillDir, source, reason })
 				return
 			}
 
@@ -171,7 +183,9 @@ export class SkillsManager {
 				modeSlugs, // New: array of mode slugs, undefined = any mode
 			})
 		} catch (error) {
-			console.error(`Failed to load skill at ${skillDir}:`, error)
+			const reason = `Failed to load skill: ${error instanceof Error ? error.message : String(error)}`
+			console.error(`Skill at ${skillDir}: ${reason}`)
+			this.loadWarnings.push({ skillName: effectiveSkillName, path: skillDir, source, reason })
 		}
 	}
 
@@ -258,6 +272,14 @@ export class SkillsManager {
 		return Array.from(this.skills.values())
 	}
 
+	/**
+	 * Get warnings collected during the last skill discovery.
+	 * Returns skills that failed to load with their specific error reasons.
+	 */
+	getLoadWarnings(): SkillLoadWarning[] {
+		return [...this.loadWarnings]
+	}
+
 	async getSkillContent(name: string, currentMode?: string): Promise<SkillContent | null> {
 		// If mode is provided, try to find the best matching skill
 		let skill: SkillMetadata | undefined
@@ -715,5 +737,6 @@ Add your skill instructions here.
 		this.disposables.forEach((d) => d.dispose())
 		this.disposables = []
 		this.skills.clear()
+		this.loadWarnings = []
 	}
 }