# Project Recommender

> Recommends open-source projects based on user profile and search history

- Skill: `rotinom0/project-recommender` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add rotinom0/project-recommender`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rotinom0/project-recommender/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: rotinoM0 (https://skillmd.com/u/rotinom0)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rotinom0/project-recommender

---


# Project Recommender Skill

Recommends open-source projects compatible with the user's profile, informed by past search history.

## When to use
- User asks to find projects to contribute to
- User wants project recommendations based on their skills
- User asks "what should I work on?"

## Workflow
1. Load user profile from `CLAUDE.md` and `01-user-profile.md`
2. If GitHub username is set, analyze existing repos and contributions to avoid recommending known projects
3. **Load search history** from `project_scraper/search_history.json`:
   - Extract learned preferences (liked/disliked patterns)
   - Identify skill evolution (new interests emerging)
   - Avoid recently recommended repos
4. Search configured sources (GitHub, Awesome lists)
5. Score each project against evaluation criteria
6. **Apply history-based adjustments** to scores
7. Present ranked recommendations with fit analysis
8. For user-selected projects, identify contribution opportunities
9. Log the search and update history with user feedback

## GitHub-aware recommendations

When the user has a GitHub username in their profile:
- **Exclude owned repos** from recommendations (they already know their own projects)
- **Exclude repos they contribute to** (already engaged)
- **Boost languages** found in their repos but not in their stated skills (implicit expertise)
- **Cross-reference starred repos** to identify ecosystem preferences
- **Suggest complementary projects**: if user has React repos, recommend projects in the React ecosystem they don't yet know

## History-aware recommendations

The search history acts as the agent's long-term memory:

### Preference learning
- If user liked 3 projects with minimal APIs → boost "lightweight" and "minimal" in future scores
- If user disliked projects with complex build setups → penalize "monorepo" or "ejected" patterns
- If user consistently picks TypeScript over JavaScript → boost TypeScript variants

### Skill evolution
- If user starts searching for a language they previously said they don't know → note the interest growth
- If search queries shift from "frontend" to "full-stack" → update inferred career direction
- If user explores a new ecosystem repeatedly → add it to inferred secondary skills

### Avoidance patterns
- Never recommend a repo the user already saw and rejected (check `user_feedback.disliked`)
- Don't re-recommend the same repo within 7 searches (unless user asks)
- If user rejected a category (e.g., "no WordPress plugins"), filter entire category

### Query refinement
- If past "React" queries returned too many boilerplates → add "production" or "used by" filter
- If past "Python" queries returned ML-only results → diversify with "web", "cli", "automation"
- If user liked projects with good first issues → prioritize repos with that label

## Scoring criteria
- **Skills match** (0-100): overlap between project stack and user skills (boosted by GitHub repo evidence and history patterns)
- **Activity level** (0-100): recency of commits, issue response time
- **Community health** (0-100): README quality, CONTRIBUTING.md, issue labels
- **Learning potential** (0-100): exposure to new technologies, documentation quality
- **Contribution opportunity** (0-100): open `good first issue`, unassigned issues

## Score adjustments from history

| Signal | Adjustment |
|--------|-----------|
| User liked similar stack | +10 skills match |
| User disliked similar stack | -15 skills match |
| User liked project size/complexity | +5 activity/learning |
| User rejected project size/complexity | -10 activity/learning |
| User explored this topic before | +5 contribution opportunity |
| User explicitly rejected this category | -50 overall (skip) |