Skip to main content

​
Proactive Discovery

The Proactive Discovery module analyzes workflow context and proactively suggests relevant skills from external sources BEFORE the user asks. It triggers based on pattern detection, file context, tool usage, and user intent.

​
Installation

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

​
Usage

​
Basic Example

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

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

const discovery = createProactiveDiscovery(loader);

await loader.start();

try {
  // Simulate a detected pattern
  const pattern: DetectedPattern = {
    id: 'pattern-abc123',
    toolSequence: ['Read', 'Grep', 'Edit', 'Bash'],
    occurrenceCount: 5,
    confidence: 0.85,
    sessionIds: ['session-1', 'session-2'],
    firstSeen: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString(),
    lastSeen: new Date().toISOString(),
    successRate: 0.9,
    suggestedName: 'react-test-workflow',
    suggestedDescription: 'Workflow for testing React components',
    
    // Context hints
    sessionContext: {
      primary_intent: 'test',
      problem_domains: ['react', 'typescript'],
      workflow_type: 'TDD',
      tool_success_rate: 0.9,
    },
    
    codeContext: {
      primary_languages: ['typescript'],
      analyzed_files: 10,
    },
  };

  // Get recommendations
  const recommendations = await discovery.discoverForPattern(pattern);

  console.log(`Found ${recommendations.length} recommendations:\n`);

  for (const rec of recommendations) {
    console.log(`🎯 ${rec.skill.title}`);
    console.log(`   Confidence: ${Math.round(rec.confidence * 100)}%`);
    console.log(`   Reason: ${rec.reason}`);
    console.log(`   Trigger: ${rec.trigger}`);
    console.log(`   URL: ${rec.skill.skillsShUrl}`);
  }
} finally {
  await loader.stop();
}

​
API Reference

​
createProactiveDiscovery(loader)

Factory function to create a Proactive Discovery instance.
​
loader
ExternalSkillLoader
required
An instance of ExternalSkillLoader for searching external skills.
​
discovery
ProactiveSkillDiscovery
An instance of the Proactive Discovery service.

​
discoverForPattern(pattern)

Analyze a detected pattern and recommend relevant external skills.
​
pattern
DetectedPattern
required
A detected workflow pattern with context information.
​
recommendations
SkillRecommendation[]
Array of skill recommendations with reasoning and confidence scores.

​
clearCache()

Clear the internal recommendation cache. 
discovery.clearCache();

​
Types

​
WorkflowContext

Context extracted from the current session.
​
WorkflowContext
object
​
frameworks
string[]
Detected frameworks (e.g., ["react", "nextjs", "vue"]).
​
languages
string[]
Detected languages (e.g., ["typescript", "python", "rust"]).
​
tools
string[]
Tool sequence being used.
​
intent
string | null
User intent: "debug", "implement", "test", "refactor", etc.
​
fileExtensions
string[]
File extensions being modified.
​
imports
string[]
Import/require statements detected in code.

​
SkillRecommendation

A skill recommendation with reasoning.
​
SkillRecommendation
object
​
skill
ExternalSkill
The recommended external skill.
​
reason
string
Human-readable explanation for why this skill is recommended.
​
confidence
number
Confidence score between 0 and 1.
​
trigger
'pattern' | 'context' | 'tool-sequence' | 'framework'
What triggered this recommendation.

​
Triggers

Proactive Discovery automatically triggers on:
  1. Pattern Detection: Repetitive tool sequences (3+ occurrences)
  2. Framework Context: Detected frameworks like React, Next.js, Vue
  3. Tool Sequences: Specific tool combinations (e.g., Read + Grep + Edit)
  4. User Intent: Debugging, testing, implementing, refactoring

​
Context Extraction

The discovery engine extracts context from:
  • Session Context: Primary intent, problem domains, workflow type
  • Code Context: Languages, file paths, imports
  • Tool Usage: Tool sequences and success rates
const pattern: DetectedPattern = {
  // ... other fields
  sessionContext: {
    primary_intent: 'test',           // Triggers testing-related skills
    problem_domains: ['react'],       // Triggers React skills
    workflow_type: 'TDD',             // Triggers TDD skills
  },
  codeContext: {
    primary_languages: ['typescript'], // Triggers TypeScript skills
    analyzed_files: 10,
  },
};

​
Query Generation

The system automatically generates search queries based on context:
  • Framework + Intent: "react testing", "nextjs debugging"
  • Tool-based: "code search patterns", "workflow automation"
  • Generic Intent: "testing best practices", "test-driven development"

​
Confidence Scoring

Confidence is calculated using: 
confidence = (installCount / 1000) * 0.5 + (relevanceScore / 100) * 0.5
Factors:
  • Install Count: Higher installs = higher confidence
  • Relevance Score: Match quality to search query
  • Capped at 1.0: Maximum confidence is 100%

​
Advanced Usage

​
Custom Context

const pattern: DetectedPattern = {
  id: 'custom-pattern',
  toolSequence: ['Bash', 'Task'],
  occurrenceCount: 3,
  confidence: 0.8,
  // ... other required fields
  sessionContext: {
    primary_intent: 'implement',
    problem_domains: ['api', 'graphql', 'authentication'],
    workflow_type: 'backend',
  },
};

const recommendations = await discovery.discoverForPattern(pattern);

​
Filtering Recommendations

const recommendations = await discovery.discoverForPattern(pattern);

// Filter by confidence
const highConfidence = recommendations.filter(r => r.confidence >= 0.7);

// Filter by trigger type
const frameworkBased = recommendations.filter(r => r.trigger === 'framework');

// Get top recommendation
const top = recommendations[0]; // Already sorted by confidence

​
Caching Behavior

Recommendations are cached per pattern ID: 
// First call - performs search
const recs1 = await discovery.discoverForPattern(pattern);

// Second call - returns cached results
const recs2 = await discovery.discoverForPattern(pattern);

// Clear cache to force refresh
discovery.clearCache();
const recs3 = await discovery.discoverForPattern(pattern);

​
Example: React Testing Workflow

Complete example from examples/proactive-discovery.ts: 
import {
  createExternalSkillLoader,
  createProactiveDiscovery,
  type DetectedPattern,
} from 'auto-skill';

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

const discovery = createProactiveDiscovery(loader);

await loader.start();

try {
  const pattern: DetectedPattern = {
    id: 'pattern-abc123',
    toolSequence: ['Read', 'Grep', 'Edit', 'Bash'],
    occurrenceCount: 5,
    confidence: 0.85,
    sessionIds: ['session-1', 'session-2'],
    firstSeen: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString(),
    lastSeen: new Date().toISOString(),
    successRate: 0.9,
    suggestedName: 'react-test-workflow',
    suggestedDescription: 'Workflow for testing React components',
    sessionContext: {
      primary_intent: 'test',
      problem_domains: ['react', 'typescript'],
      workflow_type: 'TDD',
      tool_success_rate: 0.9,
    },
    codeContext: {
      primary_languages: ['typescript'],
      analyzed_files: 10,
    },
    designPatterns: [],
    problemSolvingApproach: null,
    mentalContext: null,
  };

  const recommendations = await discovery.discoverForPattern(pattern);

  console.log(`Found ${recommendations.length} recommendations:\n`);

  for (const rec of recommendations) {
    console.log(`🎯 ${rec.skill.title}`);
    console.log(`   Confidence: ${Math.round(rec.confidence * 100)}%`);
    console.log(`   Reason: ${rec.reason}`);
    console.log(`   Trigger: ${rec.trigger}`);
    console.log(`   Installs: ${rec.skill.installCount}`);
    console.log(`   URL: ${rec.skill.skillsShUrl}`);
    console.log();
  }
} finally {
  await loader.stop();
}

Build docs developers (and LLMs) love

Get started for freeTalk to us