fix(learn): show all catalog skills to LLM for better recommendations

The pre-filter in buildLearnUserPrompt only showed skills matching the
project's detected languages/frameworks, silently dropping skills with
missing metadata or cross-domain relevance. Now all skills are shown
(matching first, then others, capped at 30) so the LLM can discover
non-obvious connections and rank the full catalog.

Author: igorcosta

src/skills/learnPrompts.ts

@@ -101,32 +101,51 @@ export function buildLearnUserPrompt(
     const skillWord = registrySkills.length === 1 ? 'community skill' : 'community skills';
     parts.push(`${registrySkills.length} ${skillWord} available.`);
 
-    // Show only skills that match the project's languages/frameworks
+    // Show all skills to the LLM so it can discover cross-domain relevance.
+    // Matching skills are listed first so the LLM prioritizes them.
     const projectLanguages = new Set(analysis.languages.map((l) => l.toLowerCase()));
     const projectFrameworks = new Set(analysis.frameworks.map((f) => f.toLowerCase()));
 
-    const relevant = registrySkills.filter((skill) => {
+    const matching: typeof registrySkills = [];
+    const other: typeof registrySkills = [];
+    for (const skill of registrySkills) {
       const skillLangs = (skill.languages ?? []).map((l) => l.toLowerCase());
       const skillFw = (skill.frameworks ?? []).map((f) => f.toLowerCase());
-      return (
+      const isMatch =
         skillLangs.some((l) => projectLanguages.has(l)) ||
-        skillFw.some((f) => projectFrameworks.has(f))
-      );
-    });
+        skillFw.some((f) => projectFrameworks.has(f));
+      (isMatch ? matching : other).push(skill);
+    }
+
+    // Combine: matching skills first, then others, capped at 30 total
+    const MAX_SKILLS = 30;
+    const combined = [...matching, ...other].slice(0, MAX_SKILLS);
 
-    if (relevant.length > 0) {
+    const formatSkill = (skill: GitHubCommunitySkill): string => {
+      const tags = skill.tags?.join(', ') ?? '';
+      const languages = skill.languages?.join(', ') ?? '';
+      const frameworks = skill.frameworks?.join(', ') ?? '';
+      return `- **${skill.id}**: ${skill.description} [category: ${skill.category}] [tags: ${tags}] [languages: ${languages}] [frameworks: ${frameworks}]`;
+    };
+
+    if (combined.length > 0) {
       parts.push('');
-      parts.push(`## Matching Skills (${relevant.length} match project stack)`);
-      for (const skill of relevant.slice(0, 15)) {
-        const tags = skill.tags?.join(', ') ?? '';
-        const languages = skill.languages?.join(', ') ?? '';
-        const frameworks = skill.frameworks?.join(', ') ?? '';
-        parts.push(
-          `- **${skill.id}**: ${skill.description} [category: ${skill.category}] [tags: ${tags}] [languages: ${languages}] [frameworks: ${frameworks}]`,
-        );
+      if (matching.length > 0) {
+        parts.push(`## Matching Skills (${matching.length} match project stack)`);
+        for (const skill of matching.slice(0, MAX_SKILLS)) {
+          parts.push(formatSkill(skill));
+        }
+      }
+      const otherToShow = combined.length - matching.length;
+      if (otherToShow > 0) {
+        parts.push('');
+        parts.push('## Other Skills');
+        for (const skill of other.slice(0, otherToShow)) {
+          parts.push(formatSkill(skill));
+        }
       }
-      if (relevant.length > 15) {
-        parts.push(`  ... and ${relevant.length - 15} more matching skills`);
+      if (registrySkills.length > MAX_SKILLS) {
+        parts.push(`  ... and ${registrySkills.length - MAX_SKILLS} more skills`);
       }
     }
 

tests/skills/learnPrompts.test.ts

@@ -199,10 +199,10 @@ describe('learnPrompts', () => {
   });
 
   describe('buildLearnUserPrompt registry handling', () => {
-    it('does not dump full registry when skills exceed threshold', () => {
+    it('caps skills at 30 and mentions overflow', () => {
       const analysis = makeAnalysis({ languages: ['typescript'], frameworks: ['react'] });
 
-      // Generate a large registry with no language/framework match
+      // Generate a large registry
       const manySkills = Array.from({ length: 50 }, (_, i) =>
         makeRegistrySkill({
           id: `skill-${i}`,
@@ -215,22 +215,29 @@ describe('learnPrompts', () => {
 
       const prompt = buildLearnUserPrompt(analysis, [], manySkills);
 
-      // Should mention find_agent_skills, not list all 50
+      // Should cap at 30 and mention overflow
       expect(prompt).toContain('find_agent_skills');
-      expect(prompt).not.toContain('skill-49');
+      expect(prompt).toContain('skill-0');
+      expect(prompt).toContain('skill-29');
+      expect(prompt).not.toContain('skill-30');
     });
 
-    it('shows matching skills filtered by project stack', () => {
+    it('lists matching skills first, then others', () => {
       const analysis = makeAnalysis({ languages: ['typescript'], frameworks: ['react'] });
 
       const skills = [
-        makeRegistrySkill({ id: 'ts-skill', languages: ['typescript'], frameworks: [] }),
         makeRegistrySkill({ id: 'ruby-skill', languages: ['ruby'], frameworks: ['rails'] }),
+        makeRegistrySkill({ id: 'ts-skill', languages: ['typescript'], frameworks: [] }),
       ];
 
       const prompt = buildLearnUserPrompt(analysis, [], skills);
+      // Both should be visible to the LLM
       expect(prompt).toContain('ts-skill');
-      expect(prompt).not.toContain('ruby-skill');
+      expect(prompt).toContain('ruby-skill');
+      // Matching skill should appear before non-matching (in "Matching Skills" section)
+      const tsIdx = prompt.indexOf('ts-skill');
+      const rubyIdx = prompt.indexOf('ruby-skill');
+      expect(tsIdx).toBeLessThan(rubyIdx);
     });
 
     it('includes registry count summary', () => {
@@ -248,6 +255,36 @@ describe('learnPrompts', () => {
       const prompt = buildLearnUserPrompt(analysis, [], skills);
       expect(prompt).toContain('find_agent_skills');
     });
+
+    it('includes skills with empty languages/frameworks (no metadata)', () => {
+      const analysis = makeAnalysis({ languages: ['typescript'], frameworks: ['react'] });
+
+      const skills = [
+        makeRegistrySkill({ id: 'error-handling', description: 'Error patterns', languages: [], frameworks: [], tags: ['patterns'] }),
+        makeRegistrySkill({ id: 'ts-skill', languages: ['typescript'], frameworks: [] }),
+      ];
+
+      const prompt = buildLearnUserPrompt(analysis, [], skills);
+      // Skills with no metadata should still appear — the LLM should decide relevance
+      expect(prompt).toContain('error-handling');
+      expect(prompt).toContain('ts-skill');
+    });
+
+    it('includes all skills when total count is within the limit', () => {
+      const analysis = makeAnalysis({ languages: ['typescript'], frameworks: ['react'] });
+
+      const skills = [
+        makeRegistrySkill({ id: 'ts-skill', languages: ['typescript'], frameworks: [] }),
+        makeRegistrySkill({ id: 'go-skill', languages: ['go'], frameworks: [] }),
+        makeRegistrySkill({ id: 'generic-skill', languages: [], frameworks: [] }),
+      ];
+
+      const prompt = buildLearnUserPrompt(analysis, [], skills);
+      // All 3 skills should be visible to the LLM for ranking
+      expect(prompt).toContain('ts-skill');
+      expect(prompt).toContain('go-skill');
+      expect(prompt).toContain('generic-skill');
+    });
   });
 
   describe('buildLearnGenerationSystemPrompt', () => {