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