diff --git a/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/skillReferenceProvider.ts b/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/skillReferenceProvider.ts
index 89b26c44a..e387e9351 100644
--- a/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/skillReferenceProvider.ts
+++ b/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/skillReferenceProvider.ts
@@ -75,7 +75,13 @@ export function useSkillReferenceProvider(): ReferenceProvider {
     requestedRef.current = true;
     void loadSkillCatalog()
       .then((items) => setSkills(items))
-      .catch(() => {
+      .catch((error) => {
+        // 失败不静默：一次瞬时失败下一次 `match` 会重试，但持续失败至少要在控制台留痕，
+        // 否则用户看到的是「敲 `$` 什么都没有」，排障时没有任何线索。
+        console.warn(
+          '[skill-reference] Skill 目录读取失败，下次触发重试',
+          error,
+        );
         requestedRef.current = false;
         setSkills([]);
       });
diff --git a/apps/ai-game-creator-shell/tests/referenceSourceProviders.test.ts b/apps/ai-game-creator-shell/tests/referenceSourceProviders.test.ts
index 980b36e26..6a2706c4c 100644
--- a/apps/ai-game-creator-shell/tests/referenceSourceProviders.test.ts
+++ b/apps/ai-game-creator-shell/tests/referenceSourceProviders.test.ts
@@ -64,6 +64,7 @@ const attachmentPart: DirectCodexUserContentPart = {
 
 afterEach(() => {
   cleanup();
+  vi.restoreAllMocks();
   window.__TAURI__ = undefined;
 });
 
@@ -373,7 +374,8 @@ describe('Skill provider', () => {
     expect(result.current.match?.('client-plugin')).toEqual([]);
   });
 
-  it('一次瞬时失败不锁死候选：下一次 `match` 还会重读目录', async () => {
+  it('一次瞬时失败不锁死候选：下一次 `match` 还会重读目录，并在控制台留痕', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
     const invoke = vi
       .fn(async (command: string) => {
         if (command === 'list_agc_skill_catalog') {
@@ -400,6 +402,11 @@ describe('Skill provider', () => {
       expect(result.current.match?.('')).toHaveLength(1);
     });
     expect(invoke).toHaveBeenCalledTimes(4);
+    // 读取失败不能静默：控制台要留下可排障的一条。
+    expect(warn).toHaveBeenCalledWith(
+      '[skill-reference] Skill 目录读取失败，下次触发重试',
+      expect.any(Error),
+    );
   });
 
   it('`toReference` / `refresh` / `mentionToken` 只认 Skill', async () => {