Skip to main content

​
Skill Recommendation Engine

The Skill Recommendation Engine provides a unified interface for skill suggestions by combining local auto-generated skills, external community skills from Skills.sh, and hybrid recommendations when local patterns match external skills.

​
Installation

import {
  createSkillRecommendationEngine,
  createExternalSkillLoader,
  createProactiveDiscovery,
} from 'auto-skill';

​
Usage

​
Basic Example

import {
  createExternalSkillLoader,
  createProactiveDiscovery,
  createSkillRecommendationEngine,
  type DetectedPattern,
} from 'auto-skill';

// Initialize components
const loader = createExternalSkillLoader({
  githubToken: process.env.GITHUB_TOKEN,
});

const discovery = createProactiveDiscovery(loader);

const engine = createSkillRecommendationEngine(loader, discovery, {
  graduationThreshold: 0.7, // Recommend graduation at 70% confidence
});

await loader.start();

try {
  // Example pattern
  const pattern: DetectedPattern = {
    id: 'pattern-xyz789',
    toolSequence: ['Read', 'Edit', 'Bash'],
    occurrenceCount: 3,
    confidence: 0.75,
    sessionIds: ['session-3'],
    firstSeen: new Date(Date.now() - 2 * 24 * 60 * 60 * 1000).toISOString(),
    lastSeen: new Date().toISOString(),
    successRate: 1.0,
    suggestedName: 'nextjs-deployment',
    suggestedDescription: 'Deploy Next.js app',
    sessionContext: {
      primary_intent: 'implement',
      problem_domains: ['nextjs', 'vercel'],
      workflow_type: 'deployment',
    },
  };

  // Get unified recommendations
  const recommendations = await engine.recommendForPattern(pattern);

  for (const rec of recommendations) {
    console.log(`📋 Type: ${rec.type.toUpperCase()}`);
    console.log(`   Action: ${rec.action}`);
    console.log(`   Confidence: ${Math.round(rec.confidence * 100)}%`);
    console.log(`   Reason: ${rec.reason}`);
    
    if (rec.externalSkill) {
      console.log(`   External: ${rec.externalSkill.title}`);
    }
    
    if (rec.localPattern) {
      console.log(`   Local: ${rec.localPattern.suggestedName}`);
    }
  }
} finally {
  await loader.stop();
}

​
API Reference

​
createSkillRecommendationEngine(loader, discovery, options?)

Factory function to create a Skill Recommendation Engine.
​
loader
ExternalSkillLoader
required
An instance of ExternalSkillLoader for searching external skills.
​
discovery
ProactiveSkillDiscovery
required
An instance of ProactiveSkillDiscovery for context-aware recommendations.
​
options
object
Configuration options.
​
options.graduationThreshold
number
default:"0.7"
Confidence threshold (0-1) for recommending skill graduation from external to local.
​
engine
SkillRecommendationEngine
An instance of the Skill Recommendation Engine.

​
recommendForPattern(pattern)

Generate unified recommendations for a detected pattern.
​
pattern
DetectedPattern
required
A detected workflow pattern to analyze.
​
recommendations
UnifiedRecommendation[]
Array of unified recommendations sorted by confidence.

​
loadExternalSkill(source, skillId)

Load full content for an external skill.
​
source
string
required
Repository source in owner/repo format.
​
skillId
string
required
Skill ID to load.
​
skill
ExternalSkill | null
The loaded skill with full content, or null if not found.

​
searchSkills(query, limit?)

Search for skills by query (manual discovery).
​
query
string
required
Search query string.
​
limit
number
default:"10"
Maximum number of results to return.
​
skills
ExternalSkill[]
Array of matching skills.

​
Types

​
UnifiedRecommendation

Combined recommendation from local and external sources.
​
UnifiedRecommendation
object
​
type
'local' | 'external' | 'hybrid'
Type of recommendation:
  • local: Generate a new skill from pattern
  • external: Use a community skill
  • hybrid: Local pattern matches external skill
​
externalSkill
ExternalSkill
External skill (present if type is "external" or "hybrid").
​
localPattern
DetectedPattern
Local pattern (present if type is "local" or "hybrid").
​
reason
string
Human-readable explanation for this recommendation.
​
confidence
number
Confidence score between 0 and 1.
​
action
'load' | 'generate' | 'graduate'
Suggested action:
  • load: Load the external skill
  • generate: Generate a new local skill
  • graduate: Adopt external skill as local

​
Recommendation Types

​
Local Recommendations

Generated when no high-confidence external skills exist: 
{
  type: 'local',
  localPattern: pattern,
  reason: 'No community skill found for this pattern. Generate a custom skill.',
  confidence: pattern.confidence,
  action: 'generate',
}

​
External Recommendations

Community skills with medium confidence (below graduation threshold): 
{
  type: 'external',
  externalSkill: skill,
  reason: 'Detected React usage with development intent',
  confidence: 0.6,
  action: 'load',
}

​
Hybrid Recommendations

High-confidence external skills matching local patterns (ready for graduation): 
{
  type: 'hybrid',
  externalSkill: skill,
  localPattern: pattern,
  reason: 'Your workflow matches the community skill "React Testing". Consider using it instead of generating a new skill.',
  confidence: 0.85,
  action: 'graduate',
}

​
Graduation Workflow

The engine recommends graduating external skills to local when:
  1. Confidence >= graduationThreshold (default: 0.7)
  2. Local pattern matches external skill workflow
  3. High community adoption (install count)
const engine = createSkillRecommendationEngine(loader, discovery, {
  graduationThreshold: 0.8, // Higher threshold = more selective
});

const recommendations = await engine.recommendForPattern(pattern);

for (const rec of recommendations) {
  if (rec.action === 'graduate') {
    console.log(`Ready to graduate: ${rec.externalSkill?.title}`);
    console.log(`Confidence: ${Math.round(rec.confidence * 100)}%`);
    
    // Load full content for graduation
    const fullSkill = await engine.loadExternalSkill(
      rec.externalSkill!.source,
      rec.externalSkill!.id
    );
    
    if (fullSkill?.content) {
      // Save to local skills directory
      // (implementation depends on your setup)
    }
  }
}

​
Advanced Usage

// Search for skills without a detected pattern
const skills = await engine.searchSkills('vercel deployment', 5);

console.log(`Found ${skills.length} skills:`);

for (const skill of skills) {
  console.log(`- ${skill.title} (${skill.installCount} installs)`);
  console.log(`  ${skill.skillsShUrl}`);
}

​
Loading Specific Skills

// Load a specific skill by source and ID
const skill = await engine.loadExternalSkill(
  'vercel/next-skills',
  'deployment-workflow'
);

if (skill?.content) {
  console.log('Full SKILL.md content:');
  console.log(skill.content);
} else {
  console.log('Skill not found');
}

​
Custom Graduation Logic

const recommendations = await engine.recommendForPattern(pattern);

for (const rec of recommendations) {
  // Custom graduation criteria
  const shouldGraduate = 
    rec.type === 'hybrid' &&
    rec.confidence >= 0.75 &&
    rec.externalSkill!.installCount >= 100;
  
  if (shouldGraduate) {
    console.log(`Graduating: ${rec.externalSkill?.title}`);
    // Implement graduation logic
  }
}

​
Integration Example

import {
  createExternalSkillLoader,
  createProactiveDiscovery,
  createSkillRecommendationEngine,
  type DetectedPattern,
} from 'auto-skill';

class SkillManager {
  private engine: ReturnType<typeof createSkillRecommendationEngine>;
  private loader: ReturnType<typeof createExternalSkillLoader>;
  
  constructor() {
    this.loader = createExternalSkillLoader({
      githubToken: process.env.GITHUB_TOKEN,
    });
    
    const discovery = createProactiveDiscovery(this.loader);
    
    this.engine = createSkillRecommendationEngine(this.loader, discovery, {
      graduationThreshold: 0.75,
    });
  }
  
  async start() {
    await this.loader.start();
  }
  
  async stop() {
    await this.loader.stop();
  }
  
  async analyzePattern(pattern: DetectedPattern) {
    const recommendations = await this.engine.recommendForPattern(pattern);
    
    return {
      shouldGenerate: recommendations.some(r => r.action === 'generate'),
      shouldLoad: recommendations.filter(r => r.action === 'load'),
      shouldGraduate: recommendations.filter(r => r.action === 'graduate'),
      allRecommendations: recommendations,
    };
  }
  
  async searchCommunitySkills(query: string) {
    return this.engine.searchSkills(query);
  }
}

// Usage
const manager = new SkillManager();
await manager.start();

try {
  const result = await manager.analyzePattern(myPattern);
  
  if (result.shouldGraduate.length > 0) {
    console.log('Ready to graduate:', result.shouldGraduate[0].externalSkill?.title);
  }
} finally {
  await manager.stop();
}

​
Best Practices

  1. Set appropriate graduation threshold: Balance between adopting community skills and generating custom ones
  2. Cache recommendations: Results are expensive to compute, cache when possible
  3. Handle errors gracefully: External API calls may fail
  4. Review before graduation: Always review external skills before adopting
  5. Track adoption metrics: Monitor which skills are actually used

Build docs developers (and LLMs) love

Get started for freeTalk to us