Recommendation Engine
Relevant source files
The following files were used as context for generating this wiki page:
The Recommendation Engine is a core module of SkillKit designed to match AI agent skills to specific project environments. It analyzes a project's technology stack—including languages, frameworks, and libraries—and cross-references them against a indexed catalog of skills to provide prioritized suggestions.
The engine provides features for project-aware matching, task-based search, and "freshness" checking to ensure installed skills remain compatible with evolving project dependencies. It operates by scoring skills across multiple weighted categories to ensure relevance and quality.
Sources: packages/core/src/recommend/index.ts:1-12, packages/core/src/recommend/engine.ts:14-17
Architecture and Core Components
The recommendation system consists of a centralized engine that interacts with a skill index and project profiles. It is designed to be consumed by various interfaces, including the Command Line Interface (CLI) and a Terminal User Interface (TUI).
The engine relies on a ProjectProfile which is derived from the project's context, including its detected stack and development patterns.
Sources: packages/core/src/recommend/engine.ts:14-36, packages/core/src/recommend/types.ts:79-92, packages/tui/src/hooks/useRecommend.ts:47-71
Scoring Logic and Weights
The RecommendationEngine calculates a score from 0 to 100 for every skill in the index. The total score is a sum of individual category weights, which can be customized via ScoringWeights.
Scoring Categories
| Category | Max Weight | Description |
|---|---|---|
| Framework | 40 | Matches based on project frameworks (e.g., React, Next.js). |
| Language | 20 | Matches based on programming languages (e.g., TypeScript, Python). |
| Library | 15 | Matches based on installed libraries (e.g., Tailwind, Zustand). |
| Tag | 10 | Relevance of skill tags to project type and patterns. |
| Popularity | 5 | Bonus based on skill downloads or stars. |
| Quality | 5 | Bonus based on verified status and quality metrics. |
| Freshness | 5 | Bonus for skills updated within the last year. |
Sources: packages/core/src/recommend/engine.ts:38-74, packages/core/src/recommend/types.ts:57-77
Version Compatibility and Warnings
Beyond scoring, the engine performs version checks. If a skill defines a minVersion for a technology, the engine compares it against the version detected in the project stack. If the project version is lower, a warning is generated.
Sources: packages/core/src/recommend/engine.ts:76-88, packages/core/src/recommend/engine.ts:285-303
Search and Inference System
The engine supports a task-based search that utilizes both direct matching and semantic inference. It maps common package names to general technology tags to improve discovery.
The TAG_TO_TECH mapping allows the engine to understand that a project with tailwindcss installed should be matched with skills tagged as styling or tailwind, even if the terms don't match exactly.
Sources: packages/core/src/recommend/engine.ts:383-463, packages/core/src/recommend/types.ts:161-236
Implementation Details
The Recommendation Flow
The CLI recommend command demonstrates the typical lifecycle of a recommendation request:
- Context Analysis: The
ContextManageranalyzes the project directory to create aProjectProfile. - Index Loading: The skill index is loaded from a local cache (usually
~/.skillkit/skill-index.json). - Scoring: The engine iterates through all skills, applying weights.
- Filtering: Results are filtered by
minScore,categories, andexcludeInstalledsettings.
Freshness Checking
The checkFreshness method evaluates installed skills to see if they target technologies that are significantly older than the versions currently used in the project. A skill is marked as outdated if it targets a version 2+ major versions behind the project's detected version.
Sources: packages/core/src/recommend/engine.ts:480-520, packages/core/src/recommend/types.ts:149-158
Data Structures
The recommendation engine uses several key TypeScript interfaces to manage data flow:
// From packages/core/src/recommend/types.ts
export interface ProjectProfile {
name: string;
type?: string;
stack: ProjectStack;
patterns?: {
components?: string;
stateManagement?: string;
apiStyle?: string;
styling?: string;
testing?: string;
};
installedSkills: string[];
excludedSkills: string[];
}
export interface ScoredSkill {
skill: SkillSummary;
score: number;
reasons: MatchReason[];
warnings: string[];
}
Sources: packages/core/src/recommend/types.ts:25-30, packages/core/src/recommend/types.ts:79-92
Conclusion
The Recommendation Engine provides a robust framework for personalizing the AI agent experience. By combining strict version checking with flexible semantic inference and weighted scoring, it ensures that developers are prompted with the most relevant methodologies and tools for their specific codebase. This automation reduces the friction of discovering and maintaining project-specific AI instructions across different coding agents.