$35
This skill has one audience: the decision-maker (CTO, tech lead, team manager, architect, or anyone evaluating whether to adopt a project and/or invest resources into its community). Every section is written to help a decision-maker form a complete picture — not just "should we use this?" but also "should we invest people into contributing to this community, and what's the expected return?"
This skill requires companion skills to be installed and available. Each one is invoked automatically during analysis:
| Skill | When used | What happens without it |
|---|---|---|
read-arxiv-paper | technical.md §Research & Papers — when the project links to arXiv/DOI papers, this skill is invoked to produce a structured paper summary instead of a bare URL | Papers are listed as plain links only; no summary or key-takeaways |
translate | Phase 3b — translates all 8 English report files to Chinese (zh/) | Output is English only; Chinese translation cannot be fulfilled |
document-skills:pdf | Phase 4 — generates a PDF report from Chinese markdown files |
| PDF generation unavailable; Phase 4 must be skipped |
document-skills:pptx | Phase 5 — generates a PPTX slide deck from Chinese markdown files | PPTX generation unavailable; Phase 5 must be skipped |
document-skills:pdf and document-skills:pptx are optional — only checked if the user requests
PDF/PPTX output (see Pre-execution Consultation below).
Installation: Skills are installed via Claude Code settings or the skill marketplace. If a skill is missing, the dependency check (Phase 0 below) will tell the user exactly what to install before analysis begins.
The workflow has five explicit phases. Each phase persists its output locally so that re-runs skip completed work and reduce API calls and token usage.
Phase 0: Dependency check + Pre-execution consultation (PDF / PPTX preference)
Phase 1: Data Collection → saves to ./cache/{owner}-{repo}/raw/
Phase 2: Analysis → saves to ./cache/{owner}-{repo}/analysis/
Phase 3: Report Generation → writes to ./reports/{owner}-{repo}/ (en/ + zh/ + introduction.md)
Phase 4: PDF Generation → ./reports/{owner}-{repo}/report_zh.pdf [optional, independent]
Phase 5: PPTX Generation → ./reports/{owner}-{repo}/slides_zh.pptx [optional, independent]
Phases 4 and 5 are independent of each other and of Phase 3 — each can be re-run individually after a failure without re-running the others.
Before checking any skills or running any analysis, ask the user:
After analysis completes, do you need any of the following output formats?
(Both are generated from the Chinese Markdown reports.)
[1] PDF report (report_zh.pdf)
[2] PowerPoint slide deck (slides_zh.pptx)
[3] Both
[4] Neither — Markdown reports only
Please reply with a number or describe your preference.
Record the user's answer as WANT_PDF (true/false) and WANT_PPTX (true/false).
These flags control which dependencies to check and which phases to execute.
Skip this question if:
Check whether the always-required skills are available (look in the Skill tool
description in your system context):
| Skill | Required for | Install command |
|---|---|---|
read-arxiv-paper | Phase 1 (paper summaries) | npx skills add https://github.com/sunqb/ccsdk --skill read-arxiv-paper |
translate | Phase 3b (Chinese translation) | npx skills add https://github.com/sunqb/ccsdk --skill translate |
For each missing required skill, stop and tell the user:
⚠️ Missing dependency: the `<skill-name>` skill is not installed.
This skill is needed for: <purpose from table above>.
Install it with:
npx skills add https://github.com/sunqb/ccsdk --skill <skill-name>
Once installed, restart the session and try again.
Degraded-mode exception (user says "proceed anyway"):
read-arxiv-paper → list paper URLs only; add > ⚠️ read-arxiv-paper skill not installed.translate → English only; add > ⚠️ translate skill not installed — English only.Only perform this check if WANT_PDF=true or WANT_PPTX=true:
| Flag | Skill needed | Install command |
|---|---|---|
WANT_PDF=true | document-skills:pdf | npx skills add https://github.com/sunqb/ccsdk --skill document-skills:pdf |
WANT_PPTX=true | document-skills:pptx | npx skills add https://github.com/sunqb/ccsdk --skill document-skills:pptx |
If a required optional skill is missing:
⚠️ Missing dependency: the `<skill-name>` skill is not installed.
This skill is needed to generate <PDF/PPTX> output (Phase <4/5>).
Install it with:
npx skills add https://github.com/sunqb/ccsdk --skill <skill-name>
You can:
[1] Install it now, then restart the session and re-run
[2] Skip <PDF/PPTX> generation and continue with markdown only
[3] Run Phases 1–3 now, then install the skill later and run Phase <4/5> separately
If the user chooses option [2] or [3], set the corresponding flag to false and continue.
Cache check first: Before running the script, check whether a fresh cache exists.
OWNER_REPO="owner-reponame" # e.g. vllm-project-llm-compressor
META="./cache/$OWNER_REPO/meta.json"
meta.json exists and is < 7 days old → the script will use cached API responses
(shows [CACHE HIT]). Still run the script to get any refreshed sections and to
confirm CACHE_DIR and LOCAL_REPO_PATH.meta.json missing or stale → full data fetch (all [CACHE MISS]).--force to bypass all caches and re-fetch everything.Run the script:
ANALYZER=$(find ~/.claude -name analyze_repo.py 2>/dev/null | head -1)
# Normal run (uses cache if fresh):
python "$ANALYZER" <github-url-or-owner/repo>
# Specify custom cache location:
python "$ANALYZER" --cache-dir ./cache <github-url>
# Force full re-fetch (ignore all caches):
python "$ANALYZER" --force <github-url>
# Change cache max age (default: 7 days):
python "$ANALYZER" --max-age 14 <github-url>
First run: install dependencies once with
pip install -r scripts/requirements.txt(requiresrequestsandrich)
Note: The script saves the repo clone to
./cache/{owner}-{repo}/repo/— it persists between runs. Do NOT delete this directory manually unless you want a full re-clone.
Script output ends with:
CACHE_DIR=./cache/{owner}-{reponame}
RAW_DIR=./cache/{owner}-{reponame}/raw
LOCAL_REPO_PATH=./cache/{owner}-{reponame}/repo
FETCHED_AT=2026-03-10T12:00:00Z
Cache directory layout (created automatically by the script):
./cache/{owner}-{reponame}/
├── meta.json ← fetch metadata + timestamps
├── repo/ ← persistent git clone (updated each run)
├── raw/ ← raw API responses (per-source cache files)
│ ├── github_repo.json
│ ├── github_org.json
│ ├── github_contributors.json
│ ├── github_releases.json
│ ├── github_prs_open.json
│ ├── github_issues_closed.json
│ ├── github_dependents.txt
│ ├── pypi_stats.txt
│ ├── npm_stats.txt
│ ├── clone_meta.txt
│ ├── git_stats.txt
│ ├── contributor_orgs.txt
│ ├── pr_merge_times.json
│ ├── good_first_issues.json
│ ├── docker_stats.txt
│ ├── homebrew_stats.txt
│ ├── conda_stats.txt
│ ├── depsdev.txt
│ ├── stackoverflow.txt
│ ├── hackernews.json
│ ├── devto.json
│ ├── openssf.txt
│ ├── osv.txt
│ ├── nvd.txt
│ ├── cncf.txt
│ └── asf.txt
└── analysis/ ← Claude's analysis notes (Phase 2 output)
├── background.md
├── adoption.md
├── competitive.md
├── momentum.md
├── risk.md
├── technical.md
└── investment.md
If the script fails:
GITHUB_TOKEN to ~/.config/github-analyzer/config; re-run.gh repo view <owner>/<repo>.N/A (unavailable — {date}); continue.python "$ANALYZER" <url> --force 2>&1 | head -100pip install -r scripts/requirements.txtWhat the script collects (13 sections, all cached individually):
| Section | Data source | Cache file |
|---|---|---|
| 1 | GitHub repo metadata | raw/github_repo.json |
| 2 | Org/owner info + funding | raw/github_org.json |
| 3 | Contributors + bus factor | raw/github_contributors.json |
| 4 | Releases, PRs, issues | raw/github_releases.json etc. |
| 5 | PyPI, npm downloads | raw/pypi_stats.txt, raw/npm_stats.txt |
| 6 | Local files (README, CHANGELOG, CI) | repo/ (persistent clone) |
| 7 | Git stats | raw/git_stats.txt |
| 8 | Community signals (org diversity, PR times, GFI) | raw/contributor_orgs.txt etc. |
| 9 | Docker Hub, Homebrew, conda, deps.dev | raw/docker_stats.txt etc. |
| 10 | Stack Overflow, HN, Dev.to, Google Trends | raw/stackoverflow.txt etc. |
| 11 | OpenSSF Scorecard, OSV, NVD CVEs | raw/openssf.txt etc. |
| 12 | CNCF, Apache Foundation status | raw/cncf.txt, raw/asf.txt |
| 13 | Crunchbase, YouTube (manual/optional) | (stdout only — manual steps) |
read-arxiv-paper for referenced papersWhen the script output lists arXiv paper links (Section 6b):
./knowledge/summary_*.md — read it if so.read-arxiv-paper skill with the arXiv URL.technical.md §Research & Papers.Only invoke for arXiv links. For ACL/NeurIPS/other proceedings, include URL+title only.
Goal: Transform raw collected data into structured analysis notes, one per report section.
Analysis notes are saved to ./cache/{owner}-{repo}/analysis/ so re-runs skip completed sections.
For each of the 7 analysis sections (background → adoption → competitive → momentum → risk → technical → investment), follow this decision tree:
1. Does ./cache/{owner}-{repo}/analysis/{section}.md exist?
│
├─ YES → Is the raw data that feeds this section newer than the analysis note?
│ │
│ ├─ NO (analysis is current) → READ from cache, skip re-analysis ✓
│ └─ YES (raw data was refreshed) → RE-ANALYZE and overwrite cache
│
└─ NO → ANALYZE from raw data and SAVE to analysis cache
How to check if raw data is newer: Compare the mtime of the relevant raw cache files
against the analysis note file. If meta.json's fetched_at timestamp is after the
analysis note's modification time, re-analyze. Otherwise, use the cached note.
Practical check (run this before each section):
ANALYSIS_NOTE="./cache/{owner}-{repo}/analysis/{section}.md"
META="./cache/{owner}-{repo}/meta.json"
if [ -f "$ANALYSIS_NOTE" ] && [ "$ANALYSIS_NOTE" -nt "$META" ]; then
echo "Analysis cache is current — reading from cache"
else
echo "Need to (re-)analyze this section"
fi
Analysis note format — save as markdown to ./cache/{owner}-{repo}/analysis/{section}.md:
# Analysis Note: {Section Name} — {owner}/{repo}
> Generated: {YYYY-MM-DD} | Data from: {fetched_at from meta.json}
## Key Facts
[Bullet points of concrete facts extracted from raw data]
## Signals
[What the data signals — positive/negative/neutral]
## Assessment
[1-3 sentence synthesis: what does this mean for the decision-maker?]
Section → raw files mapping (which raw files to read for each section):
| Section | Raw files to read |
|---|---|
background.md | github_repo.json, github_org.json + local FUNDING.yml, LICENSE, CODEOWNERS |
adoption.md | github_dependents.txt, pypi_stats.txt, npm_stats.txt, docker_stats.txt + local ADOPTERS.md |
competitive.md | github_repo.json (topics, description), stackoverflow.json, hackernews.json + README competitive section |
momentum.md | github_releases.json, github_prs_open.json, github_contributors.json, hackernews.json, devto.json |
risk.md | github_contributors.json, openssf.txt, osv.txt, nvd.txt + local CHANGELOG.md |
technical.md | github_repo.json + local README.md, architecture files, examples/, CITATION.cff |
investment.md | contributor_orgs.txt, pr_merge_times.json, good_first_issues.json + local CONTRIBUTING.md, GOVERNANCE.md, CODEOWNERS |
Read raw files using the Read tool — paths are $RAW_DIR/{filename} (from script output).
For local repo files, use $LOCAL_REPO_PATH/{filename}.
Do NOT re-run the script to read data. Use the cached raw files directly.
Decide which sections to analyze based on user intent:
| User asks | Analyze sections |
|---|---|
| "Analyze X" / "full report on X" | All 7 sections (default) |
| "Should we adopt X?" / "evaluate X" | background + adoption + risk |
| "Who backs X?" / "is it corporate?" | background |
| "How widely used is X?" | adoption |
| "X vs Y" / "alternatives to X" | competitive |
| "Is X growing?" / "still active?" | momentum |
| "Risk of using X?" / "is it maintained?" | risk |
| "How does X work?" / "architecture?" | technical |
| "Should we contribute to X?" / "invest?" | investment + background |
| "How open is X's community?" | investment |
| "Trending repos" / "what's popular" | Chat only — no files written |
Read references/analysis_guide.md for detailed guidance on each section's content.
Default behavior: If user intent is unspecified, always produce the full report (all 7 analysis sections + index.md). Every section contributes to a complete decision-maker picture.
Skip Phases 1-3 entirely. Use gh CLI or GitHub search API directly:
gh api "search/repositories?q=created:>$(date -v-7d +%Y-%m-%d 2>/dev/null || date -d '7 days ago' +%Y-%m-%d)&sort=stars&order=desc&per_page=10" \
| jq '[.items[] | {rank: (. | input_line_number), name: .full_name, stars: .stargazers_count, description: .description, language: .language}]'
Output as ranked table in chat. No files are written.
Goal: Produce the final structured report files from analysis notes. Phase 3 is idempotent — if a report file already exists and the analysis note hasn't changed, skip that file (or prompt the user if they want to regenerate it).
Re-run behavior:
For each en/{section}.md:
- If file exists AND analysis note hasn't changed → SKIP (already current)
- If file missing OR analysis note is newer → WRITE (generate/regenerate)
en/)Write all 8 files to ./reports/{owner}-{reponame}/en/. Order: 7 dimension files first
(background → adoption → competitive → momentum → risk → technical → investment), then index.md last.
Use the Write tool for every file. Read the analysis note from
./cache/{owner}-{repo}/analysis/{section}.md as the primary source for content.
index.md structure:
# {Project Name} — Analysis Report
> **Source**: {github-url} | **Analyzed**: {YYYY-MM-DD}
## Decision Brief
[Full Decision Brief — see analysis_guide.md §Decision Brief]
## Key Metrics
| Metric | Value |
|--------|-------|
| Stars | ... |
| Weekly downloads (PyPI/npm) | ... |
| License | ... |
| Backed by | ... |
| Last pushed | ... |
| GitHub dependents | ... |
| External contributor ratio | ... |
| External PR merge time (median) | ... |
| Good first issues (open) | ... |
## Contents
| Section | Summary | File |
|---------|---------|------|
| Organizational Background | [one sentence] | [background.md](./background.md) |
| Real-World Adoption | [one sentence] | [adoption.md](./adoption.md) |
| Competitive Landscape | [one sentence] | [competitive.md](./competitive.md) |
| Momentum & Trajectory | [one sentence] | [momentum.md](./momentum.md) |
| Risk Assessment | [one sentence] | [risk.md](./risk.md) |
| Technical Details | [one sentence] | [technical.md](./technical.md) |
| Community Investment | [one sentence] | [investment.md](./investment.md) |
zh/) via translate skillAfter all 8 English files are written, invoke the translate skill for each file.
Check if the zh/ file already exists and is current before translating:
For each en/{section}.md:
- If zh/{section}.md exists AND is newer than en/{section}.md → SKIP
- Otherwise → translate and write
For each file (background → adoption → competitive → momentum → risk → technical → investment → index):
en/<file>.md.translate skill: target_language=zh, translation_style=professional,
retain_format=true, auto_humanize=true.zh/<file>.md.Translation rules:
introduction.mdAfter both en/ and zh/ are complete, write the entry-point file:
./reports/{owner}-{reponame}/introduction.md
# {Project Name} — Analysis Report
> {one-sentence verdict in English from index.md Decision Brief}
📖 [Read in English](./en/index.md)
---
# {Project Name} — Analysis Report (Chinese)
> {Chinese translation of the one-sentence verdict above}
📖 [Read in Chinese](./zh/index.md)
Tell the user:
Markdown reports generated:
Entry point: ./reports/{owner}-{reponame}/introduction.md
English: ./reports/{owner}-{reponame}/en/index.md
Chinese: ./reports/{owner}-{reponame}/zh/index.md
Cache: ./cache/{owner}-{reponame}/
Then proceed to Phase 4 and/or Phase 5 if the user requested PDF/PPTX.
Do NOT repeat the full report in chat. A brief 3-5 sentence summary is sufficient.
Prerequisite: WANT_PDF=true AND document-skills:pdf skill is installed.
Skip entirely if WANT_PDF=false.
Re-run behavior: Phase 4 is independent — it can be re-run after a failure without
re-running Phases 1–3. If report_zh.pdf already exists and none of the zh/*.md files
are newer than the PDF, ask the user whether to regenerate.
Source files (in order):
./reports/{owner}-{reponame}/zh/index.md
./reports/{owner}-{reponame}/zh/background.md
./reports/{owner}-{reponame}/zh/adoption.md
./reports/{owner}-{reponame}/zh/competitive.md
./reports/{owner}-{reponame}/zh/momentum.md
./reports/{owner}-{reponame}/zh/risk.md
./reports/{owner}-{reponame}/zh/technical.md
./reports/{owner}-{reponame}/zh/investment.md
Output file: ./reports/{owner}-{reponame}/report_zh.pdf
Execution:
zh/*.md files exist. If any are missing, tell the user to run
Phase 3 first.document-skills:pdf skill with the ordered list of source files and the output path.✅ PDF generated: ./reports/{owner}-{reponame}/report_zh.pdf
❌ PDF generation failed: <error message>
Troubleshooting:
- Confirm the document-skills:pdf skill is correctly installed
- Verify source files exist: ./reports/{owner}-{reponame}/zh/
- Re-run Phase 4 only: tell me "regenerate PDF" — no need to re-run the full analysis
Prerequisite: WANT_PPTX=true AND document-skills:pptx skill is installed.
Skip entirely if WANT_PPTX=false.
Re-run behavior: Phase 5 is independent — it can be re-run after a failure without
re-running Phases 1–4. If slides_zh.pptx already exists and none of the zh/*.md files
are newer than the PPTX, ask the user whether to regenerate.
Source files and slide mapping:
| Source file | Slide group | Notes |
|---|---|---|
zh/index.md | Cover + Decision Brief | Decision Brief → 2–3 summary slides |
zh/background.md | Organizational Background | 1–2 slides |
zh/adoption.md | Real-World Adoption | 1–2 slides |
zh/competitive.md | Competitive Landscape | 1–2 slides (keep comparison table) |
zh/momentum.md | Momentum & Trajectory | 1 slide |
zh/risk.md | Risk Assessment | 1–2 slides |
zh/technical.md | Technical Details | 2–3 slides |
zh/investment.md | Community Investment | 2–3 slides (keep cost/return tables) |
Output file: ./reports/{owner}-{reponame}/slides_zh.pptx
Execution:
zh/*.md files exist. If any are missing, tell the user to run
Phase 3 first.document-skills:pptx skill with the ordered source files, slide mapping hints,
and the output path.✅ PPTX generated: ./reports/{owner}-{reponame}/slides_zh.pptx
❌ PPTX generation failed: <error message>
Troubleshooting:
- Confirm the document-skills:pptx skill is correctly installed
- Verify source files exist: ./reports/{owner}-{reponame}/zh/
- Re-run Phase 5 only: tell me "regenerate PPTX" — no need to re-run the full analysis
Tell the user a final summary of everything generated:
Analysis complete. All requested outputs generated:
📄 Markdown reports
Entry point: ./reports/{owner}-{reponame}/introduction.md
English: ./reports/{owner}-{reponame}/en/index.md
Chinese: ./reports/{owner}-{reponame}/zh/index.md
📑 PDF report ./reports/{owner}-{reponame}/report_zh.pdf ✅ / ⏭️ skipped
📊 PPTX slides ./reports/{owner}-{reponame}/slides_zh.pptx ✅ / ⏭️ skipped
Cache: ./cache/{owner}-{reponame}/
If a phase failed, show ❌ failed and remind the user they can retry that phase alone.
[CACHE HIT Nd] and skip the API call. Stale or new
sections show [CACHE MISS] and re-fetch.python "$ANALYZER" --force <url> bypasses all caches.python "$ANALYZER" --max-age 14 <url> extends the freshness window
to 14 days (useful for stable projects that rarely change).python "$ANALYZER" --cache-dir /path/to/cache <url> — useful
for teams sharing a mounted cache directory.rm -rf ./cache/{owner}-{reponame}/rm -rf ./cache/{owner}-{reponame}/analysis/GitHub Token (recommended): Raises rate limit from 60 to 5,000 req/hr. Token priority:
GITHUB_TOKEN environment variable~/.config/github-analyzer/config (primary config file)./config file next to the scriptgh CLI (if authenticated)Setup:
mkdir -p ~/.config/github-analyzer
# create config file:
# GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
# LIBRARIES_IO_KEY=xxx # optional — https://libraries.io/api
# YOUTUBE_API_KEY=xxx # optional — for automated tutorial stats
chmod 600 ~/.config/github-analyzer/config
No token / no gh CLI: Falls back to unauthenticated requests. Package registry APIs (PyPI, npm, Docker Hub, etc.) require no authentication regardless.
scorecard --repo=github.com/{owner}/{repo}