agentleFS
asgard-ai-platformasgard-ai-platform/skills/algo-rec-hybrid/SKILL.md

algo-rec-hybrid

Skill238 starsChanged 6 months agoMITView on GitHub

Design hybrid recommendation systems combining multiple strategies for improved accuracy. Use this skill when the user needs to overcome single-method limitations, combine collaborative and content-based filtering, or build a production recommendation pipeline — even if they say 'combine recommendation approaches', 'best recommendation architecture', or 'cold start plus personalization'.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 4 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When you have a single clean data source (start with the matching single method first)

    line 23
  2. Distinctive:

    When system simplicity is more important than marginal accuracy gains

    line 24
  3. Distinctive:

    Switching hybrid: Use CF when sufficient data exists.

    line 42
  4. Distinctive:

    Feature augmentation: Use one method's output as input features for another (e.g., CF embeddings as content features).

    line 46

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Hybrid Recommendation System

Overview

Hybrid recommendation combines multiple strategies (CF, content-based, knowledge-based) to overcome individual method limitations. Common architectures: weighted, switching, cascade, feature augmentation, and meta-level. Complexity varies by architecture.

When to Use

Trigger conditions:

  • Building a production recommendation system that must handle cold start AND personalization
  • Single methods have known weaknesses for your use case
  • Need to balance accuracy, diversity, and coverage

When NOT to use:

  • When you have a single clean data source (start with the matching single method first)
  • When system simplicity is more important than marginal accuracy gains

Algorithm

IRON LAW: Hybrid Adds Value ONLY With Complementary Strengths
Combining two systems with the SAME weakness amplifies the weakness.
CF fails on cold start + content-based fails on cold start = hybrid
STILL fails on cold start. Choose components that cover each other's gaps.

Phase 1: Input Validation

Identify available data: interaction history (for CF), item features (for content-based), contextual signals (time, device, location). Map data to method capabilities. Gate: At least two complementary data sources available.

Phase 2: Core Algorithm

Weighted hybrid: Score = α × CF_score + β × CB_score. Tune weights via cross-validation.

Switching hybrid: Use CF when sufficient data exists; switch to content-based for cold start items/users.

Cascade hybrid: First stage filters (e.g., content-based), second stage ranks (e.g., CF) within filtered set.

Feature augmentation: Use one method's output as input features for another (e.g., CF embeddings as content features).

Phase 3: Verification

A/B test hybrid vs individual components. Measure: accuracy (NDCG, precision@K), coverage (% of catalog recommended), diversity (intra-list diversity). Gate: Hybrid outperforms best individual component on primary metric.

Phase 4: Output

Return recommendations with source attribution for explainability.

Output Format

{
  "recommendations": [{"item_id": "789", "score": 0.91, "sources": {"cf": 0.85, "content": 0.95}, "method": "weighted"}],
  "metadata": {"architecture": "weighted", "weights": {"cf": 0.6, "content": 0.4}, "coverage": 0.78}
}

Examples

Sample I/O

Input: New user with 2 interactions + rich item feature catalog Expected: Switching hybrid: content-based recommendations (insufficient CF data), transitioning to CF as interactions accumulate

Edge Cases

InputExpectedWhy
Completely new user + new itemFall back to popularityNo data for either method
Methods disagree stronglyDepends on architectureWeighted averages; cascade defers to second stage
One component returns emptyOther component takes overGraceful degradation

Gotchas

  • Complexity cost: Each added component increases latency, maintenance, and debugging difficulty. Start simple, add complexity only when justified by metrics.
  • Weight tuning: Static weights degrade over time. Retune periodically or use learned weights (e.g., a meta-model that predicts which component performs best per context).
  • Evaluation is harder: You must evaluate the hybrid AND each component individually to understand contribution and detect regressions.
  • Feature leakage: In feature augmentation, ensure the augmenting model's predictions don't leak test-set information during training.
  • Diminishing returns: Going from one method to two gives the biggest lift. Adding a third rarely justifies the complexity.

References

  • For architecture selection decision guide, see references/architecture-selection.md
  • For A/B testing recommendation systems, see references/ab-testing-recs.md

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.