[MarkShawn2020]

Summary

Users on slow cross-border links (reported for skills add koubo-media-creator) hit "读取 Lovstudio Skills 目录失败：The operation was aborted due to timeout" before any entitlement check. Two GitHub-heavy steps stood between them and an installed Skill.

1. Catalog. 0.5.1 reads only api.github.com/.../contents/skills.yaml: about 741 KB of base64 JSON under a 15 s timeout, so links below about 50 KB/s fail. Reproduced through a 30 KB/s proxy: exits at 15 s with exactly the reported message.

• Read ${LOVSTUDIO_WEB_URL}/api/skills/catalog first (lovstudio/lovstudio-home#119, about 24 KB with only name, runtime_name, paid, depends_on).
• Fallbacks carried over from fix(skills): fall back to CDN mirrors when the catalog API is rate limited (0.5.1) #7, which was never merged and is superseded by this PR: the GitHub API with the raw media type (token from GITHUB_TOKEN / GH_TOKEN, sent only to api.github.com), then raw.githubusercontent.com, then jsDelivr. A response that is not a catalog counts as a failure, and nothing installs when every source fails. LOVSTUDIO_SKILLS_CATALOG_URL still replaces the whole chain.

2. Free Skills, including a paid Skill's free dependencies (koubo depends on branding-consistency, about 98 KB). They were installed with npx skills add https://github.com/lovstudio/skills.git, a full clone of 117.7 MB in 3,826 files at HEAD. skills kills a silent clone after 300 s, so links below about 280 KB/s would fail here next.

• git clone --depth 1 --filter=blob:none --sparse, then sparse-checkout set skills/<name>..., then npx skills add <local copy> --skill ..., the same way paid Skills already install. Each git step is retried up to three times, because blobs arrive over separate connections at checkout and testing hit a dropped one.
• Trade-off: npx skills update skips local-path installs, as it already does for paid Skills, so updating means running skills add again. skills add skills (every free Skill) keeps the full clone.

Verification

• npm test: 60 tests, 59 pass, 1 skipped (pre-existing), 0 fail. New tests cover the site-first catalog, site 503 → API fallback, the fix(skills): fall back to CDN mirrors when the catalog API is rate limited (0.5.1) #7 fallback cases, a partial sparse clone of a real local repository (an unselected 2 MB blob is not downloaded: .git stays under 1 MB, while the same fixture without --filter is 2.2 MB), git retries and error reporting, and mocked end-to-end runs for a free install from the sparse copy, a dropped blob fetch, and the site catalog path.
• Through a 30 KB/s proxy with a sandboxed HOME and HTTPS to GitHub:
  • 0.5.1, skills add koubo-media-creator: fails at 15 s with the reported error.
  • This branch, same command, catalog served by #119's handler on localhost: catalog in 1.5 s, then on to the account check.
  • This branch, skills add writing-style -g -y -a claude-code (two free dependencies), real GitHub and real skills@latest: exit 0 in 19 s, about 24 KB from the site and 490 KB from GitHub, three Skills copied into ~/.claude/skills.
• Not exercised: a paid download with a real VIP account. That code path is unchanged, and koubo's archive is about 111 KB from codeload.

Release

Deploy lovstudio/lovstudio-home#119 first, then merge this and run the "Publish npm" workflow. #7 can be closed once this merges.

🤖 Generated with Claude Code