Repo Trend

repo-trend Skill

You discover, rank, evaluate, and track GitHub repositories. You orchestrate gh CLI calls, compute composite scores, manage persistent state in JSON files, and present results conversationally. No Python — you are the orchestrator.

这个 Skill 做什么 / 不做什么

路由 (Routing)

Architecture

User: "find me trending AI Agent repos"
       │
       ▼
You (Claude) — parse intent, formulate queries, run gh CLI, compute scores, manage state
       │
       ├─► gh search repos (2 queries: established + emerging)
       │       │
       │       ▼  deduplicated list + hotness scores
       │
       ├─► Tier 1: Present ranked summary table (hotness, stage badges)
       │
       ├─► [on demand] gh api repos/{o}/{r} → topics, metadata
       ├─► [on demand] gh api repos/{o}/{r}/readme → README content
       ├─► [on demand] gh api repos/{o}/{r}/contributors → top contributors
       │
       ├─► Tier 2: Full checklist evaluation (numeric scores)
       ├─► Tier 3: Claude semantic deep analysis (qualitative narrative)
       │
       ├─► output/tracked_repos.json  ⟷  persistent state with diff tracking
       └─► state/watches.json         ⟷  saved search configurations

Quick Reference

1. Query Construction

Translating Natural Language to GitHub Search Syntax

When the user asks to discover repos, construct a GitHub search query from their intent:

1. Extract the domain/topic — "AI Agent" → ai agent, "Rust CLI tools" → rust cli, "MCP servers" → mcp server
2. Apply explicit modifiers if provided — "Python only" → add language:python, "stars > 500" → adjust threshold
3. Use the keyword form — join keywords with spaces. GitHub search treats spaces as AND.

Defaults & Clarifying

Apply these unless the user overrides:

Ask at most one clarifying question before searching, and only when genuinely ambiguous (e.g., "AI Agent frameworks, or any AI repo?"). If clear, search immediately.

2. Discovery Flow (Two-Query Strategy)

Step 1: Compute Cutoff Date

Calculate CUTOFF = today minus 3 months, formatted as YYYY-MM-DD.

Step 2: Run Query A (Established Quality)

gh search repos "<keyword query> stars:>100" \
  --sort stars \
  --limit 20 \
  --json createdAt,stargazersCount,language,license,description,fullName,url,updatedAt,pushedAt,forksCount,openIssuesCount,isArchived,isFork,homepage,watchersCount

This finds the most-starred repos matching the domain — established quality.

Step 3: Run Query B (Emerging / Recently Active)

gh search repos "<keyword query> pushed:>$CUTOFF stars:>100" \
  --sort updated \
  --limit 20 \
  --json createdAt,stargazersCount,language,license,description,fullName,url,updatedAt,pushedAt,forksCount,openIssuesCount,isArchived,isFork,homepage,watchersCount

This finds repos that are actively being worked on — emerging signal.

Step 4: Merge and Filter

1. Parse both JSON arrays
2. Deduplicate by fullName — if a repo appears in both, keep the entry with higher stargazersCount
3. Filter out: isArchived: true, isFork: true (unless user explicitly wants forks)
4. Quality filter for Query B results: repos from Query B with stars below the default threshold (100) are noise — drop them. If a Query B repo has < 200 stars, only keep it if its velocity is exceptional (> 30 stars/day) or it appears in both queries.
5. You now have a merged candidate list (up to 40 repos before dedup, typically 15-25 after filtering)

Step 5: Compute Hotness Scores

For each repo in the merged list:

days_since_creation = max(1, (today - createdAt).days)
days_since_push    = max(0, (today - pushedAt).days)

velocity = stargazersCount / days_since_creation
recency  = 1.0 / (1.0 + days_since_push / 90)
hotness  = log2(stargazersCount + 1) * velocity * recency * log2(forksCount + 1)

Note: log2(forksCount + 1) correctly handles repos with 0 forks — zero forks means zero community engagement multiplier, which is intentional.

Step 6: Classify Lifecycle Stage

if   velocity > 80  → accelerating
elif velocity > 50  → emerging
elif velocity > 20  → mainstream
else                → declining

Step 7: Rank and Present

Sort by hotness descending. Read output/tracked_repos.json and join any prior evaluation data (tags, tier scores, verdicts) onto the matching repos.

3. Tier 1 Summary Table

Present results as a ranked table. Format exactly:

| Rank | Repo | Stars | Velocity | Forks | Language | Stage | Hotness | Known? |
|------|------|-------|----------|-------|----------|-------|---------|--------|
| 1 | owner/repo | 5.2k | 87.3 | 420 | Python | 🔥 accelerating | 341.2 | ★ eval'd |
| 2 | owner/repo2 | 12k | 23.1 | 1.8k | TypeScript | 📈 emerging | 198.7 | new |
| 3 | owner/repo3 | 350 | 52.8 | 85 | Rust | 📈 emerging | 156.3 | new |
| ... | ... | ... | ... | ... | ... | ... | ... | ... |

Stage icons: 🔥 accelerating, 📈 emerging, 📊 mainstream, 📉 declining Known column: "★ eval'd" if prior evaluation exists, "tracked" if seen before, "new" if first discovery

After the Table

Always follow with: "Deep dive on any of these? Say a number, repo name, or 'compare top 3'. Or say 'track these' to save for later."

4. Tier 2 Full Checklist

When the user asks to deep-dive on specific repos:

Step 1: Fetch Detailed Metadata

For each repo:

gh api repos/{owner}/{repo} --jq '{topics, stargazers_count, forks_count, subscribers_count, open_issues_count, created_at, updated_at, pushed_at, language, license: .license.spdx_id, description, size, archived, fork, homepage, default_branch, has_issues, has_wiki, has_pages, has_discussions}'

Step 2: Fetch README

gh api repos/{owner}/{repo}/readme -H 'Accept: application/vnd.github.raw'

If README exceeds ~10,000 chars, read the first 300 lines for scoring and note the truncation.

Step 3: Fetch Contributors

gh api repos/{owner}/{repo}/contributors --jq '.[:5] | .[] | {login, contributions}'

Step 4: Score Each Dimension

See references/repo-scout/eval.md for the full scoring rubric. Score across 7 weighted dimensions (Topic Alignment, README Substance, README Structure, Contributor Diversity, Issue Health, Release Cadence, Stars Growth), then compute:

tier2_score = sum(dimension_score * weight) * 10   # normalized 0-10

5. Tier 3 Deep Analysis (Claude Semantic Reasoning)

Run after Tier 2 or when the user directly asks for strategic evaluation.

Process

1. Read the README (focus on first 300 lines; skim rest if needed)
2. Read the detailed metadata from Tier 2
3. Read recent issues if relevant: gh api repos/{owner}/{repo}/issues --jq '.[:5] | .[] | {title, state, updated_at}'
4. Apply Claude reasoning across all dimensions in references/repo-scout/eval.md Tier 3 section

AI Agent Domain Specific Checks

When evaluating in the AI Agent space, additionally check for:

• MCP server/client integration
• Multi-agent coordination patterns
• State persistence / checkpointing
• Local LLM support (Ollama, llama.cpp)
• Tool calling / function calling
• Observability (tracing, logging)
• Model agnosticism (multiple LLM providers)

Output Format

## Deep Analysis: owner/repo

**Verdict: Consider / Watch / Pass**

### Summary
2-3 sentence overview.

### Strengths
- Bullet points of what it does well

### Concerns
- Bullet points of risks and red flags

### Who Should Use It
Target audience and use case fit.

### Key Takeaway
One actionable recommendation for the user.

6. State Management

Reading State

At the start of a discovery session, read output/tracked_repos.json to get prior data. At the start of a watch operation, read state/watches.json.

Writing State After Discovery

After every discovery run, update output/tracked_repos.json:

1. For each repo in the current scan:
   • New (not in repos): create entry with first_seen snapshot, empty history, added_at = now
   • Existing (in repos): update last_seen, and check if a history entry is warranted
2. Generate a scan_id: scan_YYYYMMDD_HHMMSS
3. Update updated_at to now
4. Write the full JSON back

When to Append History

Only append a history entry when at least one of these triggers fires:

The change_reason field: use stars_grew, stars_dropped, hotness_changed, stage_changed, new_activity, or re_evaluated.

Diff Reporting

When the user asks "what changed?", compute from tracked_repos.json:

1. New since last scan: repos where added_at is after the previous scan's updated_at
2. Changed: repos with new history entries since the user's last check
3. Stage transitions: repos where first_seen.stage ≠ last_seen.stage
4. Stale warning: repos where last_seen.pushed_at is > 180 days ago

Report as:

### What's New
- **3 new repos** discovered: owner/a (Python, 520★), owner/b (Rust, 340★), owner/c (TypeScript, 1.2k★)
- **2 repos changed**: owner/d moved from emerging → accelerating, owner/e gained 45% more stars
- **1 repo stale**: owner/f — last pushed 202 days ago, may be abandoned

7. Watch Management

Creating a Watch

When the user says "track these" or "watch this search" after a discovery run:

1. Generate a watch ID: watch_NNN (find the next unused number)
2. Create the watch config:

   {
     "id": "watch_003",
     "label": "<user-friendly name — ask the user or derive from query>",
     "query": "<the original search query without thresholds>",
     "created_at": "<now ISO 8601>",
     "last_run": "<now ISO 8601>",
     "thresholds": { "min_stars": 100, "max_age_days": 90 },
     "language_filter": "",
     "topic_filter": "",
     "status": "active",
     "notes": ""
   }
   

3. Append to state/watches.json and write

Running Watches

When the user says "check my watches" or "re-scan":

1. Read state/watches.json
2. For each watch with status: "active", run the discovery flow (Section 2) using the watch's query + thresholds
3. Update last_run for each executed watch
4. Report diffs as in Section 6

Deactivating

"stop watching X" → find the watch by label or id, set status: "inactive", write back.

8. Rate Limits and Error Handling

Rate Limit Awareness

Pre-Flight Check

Before the first gh call in a session:

gh auth status

If this returns an error, tell the user to run gh auth login and stop.

During Operations

• Track how many search calls you make. Discovery uses exactly 2 search calls.
• For Tier 2, each repo uses 3 core API calls. 5 repos = 15 calls, well within 5,000/hr.
• If you encounter a 429 or 403 (rate limit), read any error message, wait the suggested time (or 60s for search, until reset for core), then retry once.
• If gh returns no results, verify the query syntax isn't the issue. Try a broader query before giving up.
• If a repo 404s (deleted or renamed), skip it silently and remove from tracking.

Token Budget

• gh search repos --limit 20 with ~14 JSON fields returns ~5-8KB of JSON. This is fine.
• READMEs can be very large. Read only the first 300 lines for Tier 3. If truncated, note it.
• If the discovery result list exceeds 30 repos after dedup, present only the top 20.

9. Reference Files

Read these when needed:

10. Troubleshooting

11. Conversational Flow

Discovery: 1. Run Query A+B → 2. Merge/filter/score → 3. Present Tier 1 table → 4. Update tracked_repos.json → 5. Ask "Deep dive on any?"

Deep Dive: 1. Fetch metadata/README/contributors → 2. Score → 3. Present Tier 2 breakdown → 4. Offer Tier 3 → 5. Update tracking

Watch: Save search to state/watches.json, confirm with label.

Diff: Read tracked_repos.json, report new/changed/stale repos, highlight stage transitions.