How I built a zero-config CLI that scans any project and installs only the AI agent skills that match — covering the architecture, the gotchas, and what I'd build next.

skills.sh hosts 90,000+ skills for AI coding agents like Claude Code. Picking the right ones for your project is manual: you scroll, you guess, you npx skills add one at a time, and you end up with a ~/.claude/skills/ either bloated or empty.

I wanted to type one command in any project directory and have the right skills installed. So I built skillgrab.

npx skillgrab

That's it. It scans your project, detects your stack, and installs matching skills.

The shape

Three steps, zero config:

npx skillgrab
  ├─ Scan files (package.json, requirements.txt, pubspec.yaml,
  │              go.mod, Dockerfile, README, …)
  ├─ Search skills.sh + validate against GitHub
  └─ Multi-select picker → npx skills add

A typical run on a Next.js + Supabase + Stripe SaaS surfaces ~10 ranked skills. Trusted owners (Anthropic, Vercel, Supabase, Stripe, Clerk, OpenAI, …) get a star and a popularity boost. Stale entries from the search API get dropped before the user sees them. One clone per repo. One ✓ per skill.

Architecture

project dir
    │
    ▼
┌─ detect/  ────────────────────┐
│   node.ts    package.json     │
│   python.ts  requirements.txt │
│   mobile.ts  pubspec.yaml     │
│   backend.ts go.mod, Cargo…   │
│   infra.ts   Dockerfile, …    │
│   context.ts README/docs      │
└─────────────┬─────────────────┘
              ▼
   skills.sh /api/search (live)
              │
              ▼
   rank: trusted boost + log10(installs)
              │
              ▼
   dedupe by skill name
              │
              ▼
   GitHub trees API validation
   (drop stale slugs)
              │
              ▼
   @clack/prompts multi-select
              │
              ▼
   npx skills add (grouped by repo)

Each detector is a tiny pure function: (rootDir) => Signal[]. The CLI runs them in parallel, dedupes by key, and feeds the resulting signals into the registry layer. The registry queries skills.sh's JSON API per signal, scores results, and gates them through GitHub validation. The install step groups by source repo so a single clone covers N skills.

Five gotchas that took me longer than they should have

1. skills.sh is a Next.js SPA

The first version of skillgrab tried to scrape /search?q=.... Returned 0 results every time. The HTML payload is just a bootstrap loader; results render client-side. The actual JSON endpoint is /api/search?q=..., which I found by curl-ing what looked like API paths until one returned JSON. Lesson: when a SPA has a search box, there's almost always a private JSON endpoint behind it.

2. The curated fallback was a footgun

When the API returned nothing, I fell back to a hand-written map of tech → owner/repo slugs. I'd guessed half of them. npx skills add growth/skills tried to clone github.com/growth/skills.git (404). Skills.sh's installer turns slugs into git clones, so a wrong slug doesn't fail gracefully — it errors out mid-flow. Removed the curated fallback entirely. If the API is down, return []. Better silent than wrong.

3. --skill a,b,c is one literal name

skills.sh's CLI accepts --skill <name>. I assumed the plural form <skills> in the help meant comma-separated. It does not. It treats "a,b,c" as one filename to match. So when I asked it to install copywriting,social-content,content-strategy from a repo that had all three, it said "no matching skills found" — and listed all three in the available list right below. The fix: repeated flags. --skill a --skill b --skill c. One clone, three installs.

4. The search API returns skillIds that don't exist

skills.sh's search uses fuzzy matching. Sometimes it returns slugs like apify/agent-skills/apify-content-analytics — a plausible-sounding skill, but the apify repo only has 4 skills, none of them named that. The slug came from substring matches against READMEs, not from real skill manifests. So skillgrab now validates each candidate before committing it to the install plan: HEAD the GitHub trees API for the repo, check if <skillId>/SKILL.md exists. If not, drop it.

5. Plugin-structured repos hide skills under nested folders

Validating naive paths like <owner>/<repo>/<skillId>/SKILL.md only covered flat repos. anthropics/knowledge-work-plugins puts skills under <plugin>/skills/<id>/SKILL.md — sales/skills/draft-outreach/SKILL.md, bio-research/skills/instrument-data-to-allotrope/SKILL.md. The validator now fetches the recursive tree once per repo (cached) and checks if any path ends with <skillId>/SKILL.md. Works for both shapes. Honors GITHUB_TOKEN to bypass the 60/hr unauth limit.

What I'd build next

• A --watch mode that re-scans on package.json changes.

• Per-language refinements: Rails versions, Go module categories, Astro vs SvelteKit etc.

• A skillgrab list command that just shows the plan as JSON, for piping into other tools.

• An MCP server wrapper, so coding agents can call skillgrab via MCP instead of shell.

Try it

cd ~/your-project
npx skillgrab --dry-run

PRs welcome — especially new stack detectors. Each detector lives in src/detect/ and is ~50 lines.

• Repo: github.com/briascoi/skillgrab

• Landing: briascoi.github.io/skillgrab

• npm: npmjs.com/package/skillgrab