Unified Suggester
The Unified Suggester is the main discovery layer that integrates Mental Model (codebase semantic understanding), Skills.sh (external community skills), and Auto-Skill V2 (local pattern detection) to provide ranked skill suggestions with confidence scores and context.
Installation
import { createUnifiedSuggester } from 'auto-skill';
Usage
Basic Example
import { createUnifiedSuggester, type DetectedPattern } from 'auto-skill';
const suggester = createUnifiedSuggester({
projectPath: process.cwd(),
enableMental: true,
enableExternal: true,
});
// Get suggestions based on context
const suggestions = await suggester.suggestForContext({
detectedPatterns: [
{
id: 'pattern-1',
toolSequence: ['Read', 'Edit', 'Bash'],
occurrenceCount: 5,
confidence: 0.85,
// ... other fields
},
],
sessionContext: {
primary_intent: 'implement',
problem_domains: ['api', 'authentication'],
},
filePaths: ['src/api/auth.ts', 'src/middleware/jwt.ts'],
});
console.log(`Found ${suggestions.length} suggestions`);
for (const suggestion of suggestions) {
console.log(`${suggestion.name} (${Math.round(suggestion.confidence * 100)}%)`);
console.log(` Source: ${suggestion.source}`);
console.log(` ${suggestion.description}`);
}
API Reference
createUnifiedSuggester(options?)
Create a unified skill suggester that combines all discovery sources.
Configuration options.options.projectPath
string
default:"process.cwd()"
Path to the project directory.
Enable Mental Model integration for semantic codebase understanding.
Enable Skills.sh integration for external community skills.
Optional list of custom SkillProvider instances.
Suggester object exposing suggestion and tracking methods.
suggestForContext(params)
Suggest skills based on current context. Combines suggestions from local patterns (highest confidence), Mental model hints (medium confidence), and external skills (variable confidence based on adoption).
Context parameters for skill suggestions.Array of detected workflow patterns.
Session context including intent, domains, workflow type.
Array of file paths being modified.
Array of skill suggestions sorted by confidence (highest first).
suggestForFiles(filePaths, limit?)
Suggest skills based on file paths using the Mental model.
Array of file paths to analyze.
Maximum number of suggestions to return.
Array of skill suggestions sorted by confidence.
suggestForDomain(domainName, limit?)
Suggest skills for a specific Mental domain.
Name of the domain (e.g., “Payment”, “User”, “Authentication”).
Maximum number of suggestions to return.
Array of skill suggestions for the domain.
recordSkillUsage(skillName, skillSource, success)
Record that a skill was used and track adoption.
Name of the skill that was used.
Source of the skill: "local", "external", or "mental-hint".
Whether the skill usage was successful.
Returns true if the skill is ready to graduate to local, false otherwise.
getGraduationCandidates()
Get skills that are ready to graduate to local.
Array of skills eligible for graduation.
graduateSkill(skillId)
Graduate an external skill to local.
Skill identifier to graduate.
getAdoptionStats(minConfidence?)
Get adoption statistics for all tracked skills.
Minimum confidence threshold to include in results.
Array of skill adoption records sorted by confidence and usage.
Types
SkillSuggestion
A suggested skill with context and confidence.
Human-readable description.
source
'local' | 'external' | 'mental-hint'
Source of the suggestion:
local: From detected patternsexternal: From Skills.sh communitymental-hint: From Mental Model analysis
Confidence score between 0 and 1.
Mental Model context if source is "mental-hint".Entities this capability operates on.
Pattern match details if source is "local".Tool sequence that triggered this pattern.
Number of times pattern was detected.
Success rate of the pattern.
External skill metadata if source is "external".
Adoption tracking data if skill has been used.
Discovery Sources
The Unified Suggester combines three sources:
1. Local Patterns (Highest Confidence)
Skills generated from detected workflow patterns:
{
name: 'react-test-workflow',
description: 'Workflow for testing React components',
source: 'local',
confidence: 0.85,
patternMatch: {
toolSequence: ['Read', 'Grep', 'Edit', 'Bash'],
occurrences: 5,
successRate: 0.9,
},
}
2. Mental Model Hints (Medium Confidence)
Skills suggested by semantic codebase analysis:
{
name: 'payment-processing-skill',
description: 'Skill for Payment capability',
source: 'mental-hint',
confidence: 0.6,
mentalContext: {
domains: ['Payment', 'Billing'],
capability: 'ProcessPayment',
operatesOn: ['Order', 'Customer'],
},
}
3. External Skills (Variable Confidence)
Note: External skills integration was deprecated in v5.0. Use createExternalSkillLoader() + createProactiveDiscovery() instead for external skill discovery.
Adoption Tracking
Track skill usage and confidence evolution:
// Record skill usage
const readyToGraduate = suggester.recordSkillUsage(
'react-testing',
'external',
true // success
);
if (readyToGraduate) {
console.log('Skill is ready to graduate!');
}
// Get graduation candidates
const candidates = suggester.getGraduationCandidates();
for (const candidate of candidates) {
console.log(`${candidate.skillName}:`);
console.log(` Confidence: ${Math.round(candidate.currentConfidence * 100)}%`);
console.log(` Usage: ${candidate.usageCount}`);
console.log(` Success rate: ${Math.round((candidate.successCount / candidate.usageCount) * 100)}%`);
}
// Graduate a skill
if (candidates.length > 0) {
suggester.graduateSkill(candidates[0].skillId);
}
Graduation Criteria
Skills graduate from external to local when:
- Confidence >= 0.85
- Usage count >= 5
- Success rate >= 0.8 (80%)
const candidates = suggester.getGraduationCandidates();
for (const candidate of candidates) {
if (
candidate.currentConfidence >= 0.85 &&
candidate.usageCount >= 5 &&
candidate.successCount / candidate.usageCount >= 0.8
) {
suggester.graduateSkill(candidate.skillId);
}
}
Advanced Usage
File-Based Discovery
const suggester = createUnifiedSuggester({
projectPath: '/path/to/project',
enableMental: true,
});
// Suggest skills for specific files
const suggestions = suggester.suggestForFiles([
'src/api/payments.ts',
'src/services/stripe.ts',
'src/models/order.ts',
]);
console.log(`Found ${suggestions.length} suggestions for payment-related files`);
Domain-Specific Discovery
// Suggest skills for a specific domain
const paymentSkills = suggester.suggestForDomain('Payment', 5);
const userSkills = suggester.suggestForDomain('User', 5);
console.log('Payment skills:');
paymentSkills.forEach(s => console.log(`- ${s.name}`));
console.log('\nUser skills:');
userSkills.forEach(s => console.log(`- ${s.name}`));
Combined Context Discovery
const suggestions = await suggester.suggestForContext({
detectedPatterns: myPatterns,
sessionContext: {
primary_intent: 'implement',
problem_domains: ['authentication', 'api', 'security'],
workflow_type: 'backend',
},
filePaths: [
'src/auth/jwt.ts',
'src/middleware/auth.ts',
'src/api/routes.ts',
],
});
// Filter and categorize
const local = suggestions.filter(s => s.source === 'local');
const mental = suggestions.filter(s => s.source === 'mental-hint');
const external = suggestions.filter(s => s.source === 'external');
console.log(`Local: ${local.length}, Mental: ${mental.length}, External: ${external.length}`);
Adoption Statistics
// Get all adopted skills with at least 50% confidence
const adoptedSkills = suggester.getAdoptionStats(0.5);
console.log('Adoption Statistics:');
console.log(`Total skills tracked: ${adoptedSkills.length}`);
for (const skill of adoptedSkills) {
const successRate = skill.usageCount > 0
? Math.round((skill.successCount / skill.usageCount) * 100)
: 0;
console.log(`\n${skill.skillName}:`);
console.log(` Source: ${skill.source}`);
console.log(` Confidence: ${Math.round(skill.currentConfidence * 100)}%`);
console.log(` Usage: ${skill.usageCount} times`);
console.log(` Success rate: ${successRate}%`);
console.log(` Graduated: ${skill.graduatedToLocal ? 'Yes' : 'No'}`);
}
Integration Example
import { createUnifiedSuggester, type DetectedPattern } from 'auto-skill';
class SkillDiscoveryService {
private suggester: ReturnType<typeof createUnifiedSuggester>;
constructor(projectPath: string) {
this.suggester = createUnifiedSuggester({
projectPath,
enableMental: true,
enableExternal: true,
});
}
async discoverSkills(
patterns: DetectedPattern[],
context: Record<string, unknown>,
files: string[]
) {
const suggestions = await this.suggester.suggestForContext({
detectedPatterns: patterns,
sessionContext: context,
filePaths: files,
});
return {
highConfidence: suggestions.filter(s => s.confidence >= 0.7),
mediumConfidence: suggestions.filter(s => s.confidence >= 0.5 && s.confidence < 0.7),
lowConfidence: suggestions.filter(s => s.confidence < 0.5),
};
}
trackUsage(skillName: string, source: string, success: boolean) {
const readyToGraduate = this.suggester.recordSkillUsage(
skillName,
source,
success
);
if (readyToGraduate) {
console.log(`🎓 ${skillName} is ready to graduate!`);
// Optionally auto-graduate
const skillId = skillName.toLowerCase().replace(/\s/g, '-');
this.suggester.graduateSkill(skillId);
}
}
getReport() {
const candidates = this.suggester.getGraduationCandidates();
const stats = this.suggester.getAdoptionStats();
return {
totalSkills: stats.length,
graduationCandidates: candidates.length,
bySource: stats.reduce((acc, s) => {
acc[s.source] = (acc[s.source] || 0) + 1;
return acc;
}, {} as Record<string, number>),
};
}
}
// Usage
const service = new SkillDiscoveryService('/path/to/project');
const discovered = await service.discoverSkills(
myPatterns,
{ primary_intent: 'test' },
['src/components/Button.test.tsx']
);
console.log(`High confidence: ${discovered.highConfidence.length}`);
console.log(`Medium confidence: ${discovered.mediumConfidence.length}`);
const report = service.getReport();
console.log('Report:', report);
Best Practices
- Enable Mental Model: Provides valuable semantic context for large codebases
- Track all usage: Always call
recordSkillUsage() to improve confidence scores
- Review before graduation: Check graduation candidates before auto-graduating
- Use appropriate confidence thresholds: Different use cases require different thresholds
- Combine sources: Use all three discovery sources for comprehensive suggestions
- Filter by confidence: Present high-confidence suggestions first to users