skills-detector is a CLI that fingerprints a project's tech stack — frameworks, languages, tooling, test setup — then queries skills.sh to find matching agent skill packages and writes a skills.json ready for skillman install.
Why I starred it
Agent skills (reusable sets of system-prompt rules packaged like npm modules) are still a young idea. The workflow friction is real: you have a Next.js + Prisma project and you want to pull in relevant skills, but you have to know what to search for. This tool automates that discovery step. It's a small scope, cleanly executed.
How it works
The entry point is src/cli.ts. When you run skills-detector, it calls detect() from src/index.ts, which orchestrates four parallel detector modules:
const frameworks = detectFrameworks(ctx);
const languages = detectLanguages(ctx);
const tools = detectTools(ctx);
const testing = detectTesting(ctx);Each detector receives a DetectionContext — the resolved cwd, a parsed PackageJson, and a merged allDependencies map (deps + devDeps combined). That last part matters: it avoids running Object.keys(pkg.dependencies) four separate times and means you never miss a tool that lives in devDependencies.
The detection strategy in src/detectors/frameworks.ts is pattern-based, not heuristic. Every framework gets a typed FrameworkPattern:
{
name: "nextjs",
configFiles: ["next.config.js", "next.config.ts", "next.config.mjs", "next.config.cjs"],
dependencies: ["next"],
}A match fires if either a config file exists on disk or the dependency appears in allDependencies. Config files take priority because they're more authoritative — you might have next in a monorepo root without the project itself being a Next.js app.
Language detection in src/detectors/languages.ts works differently. TypeScript is detected via tsconfig.json or the typescript dependency. JavaScript fires on the presence of package.json itself, which means every Node project gets tagged. That's intentional but worth knowing — JS is a fallback, not a signal.
After detection, the CLI does two things that aren't obvious from the README. First, it applies curated skills before any search. If it finds Next.js, it pre-loads three official Vercel skill refs without touching the network:
const CURATED_SKILLS: Record<string, string[]> = {
nextjs: [
"vercel-labs/next-skills@next-best-practices",
"vercel-labs/next-skills@next-upgrade",
"vercel-labs/agent-skills@vercel-react-best-practices",
],
react: ["vercel-labs/agent-skills@vercel-react-best-practices"],
turborepo: ["vercel/turborepo@turborepo"],
};
Second, it does smart term pruning before hitting the network. If any framework is detected, it drops typescript and javascript from the search terms — framework-specific skills are more useful than language-level ones. It also drops any term that already has a curated entry. The result is a short, meaningful list of search terms instead of a shotgun blast.
The search itself shells out to npx skills find <term> and parses the output. ANSI codes get stripped, then it regex-matches owner/repo@skill patterns. There's a isRelevantSkill() function in cli.ts that does word-boundary matching (so express doesn't match expression) plus an ecosystem filter — if a skill ref contains expo or react-native markers but the project doesn't use those, the result gets dropped.
The only runtime dependency is package-manager-detector (antfu's), which reads lockfiles to identify whether you're on npm, yarn, pnpm, bun, or deno. That shows up in the output and in skills.json but isn't used for filtering.
Using it
npm install -g skills-detector
# In a Next.js + Tailwind + Vitest project:
skills-detectorProject Analysis
Pkg Manager: pnpm
Frameworks: nextjs, react
Languages: typescript
Tools: tailwind
Testing: vitest
Search terms: tailwind, vitest
Curated skills:
vercel-labs/next-skills@next-best-practices
vercel-labs/next-skills@next-upgrade
vercel-labs/agent-skills@vercel-react-best-practices
vercel-labs/web-design-guidelines@web-design-guidelines
Searching for skills (top result per term)...
tailwind... (none)
vitest... (none)
Found 4 skills from 3 sources
Wrote /path/to/project/skills.jsonThe --skip-search flag skips the npx shell-outs entirely, which is useful in CI or offline environments. --json pipes clean JSON to stdout, making it composable with other tooling.
Programmatic usage is also exported cleanly:
import { detect } from 'skills-detector'
const result = await detect({ cwd: './my-project' })
// result.frameworks, result.tools, result.searchTerms, etc.
Rough edges
No tests. The package.json declares vitest as a devDependency and has a test script, but there are zero test files in the repo. For a detector that's meant to be trusted with stack fingerprinting, that's a gap — edge cases like monorepos, workspaces, or unusual config file locations are untested.
The network calls go through npx skills find, which means a first run can be slow if npx needs to pull the skills CLI. There's a 30-second timeout per search term, and terms are searched sequentially, not concurrently. A project with 10 search terms could wait several minutes on a cold cache.
The version is 0.0.1 with commit history only going back to January 2026. This is early software. The curated skills table only covers Next.js, React, and Turborepo — every other framework goes through the search path with variable results.
Detection coverage is broad on paper but shallow in practice. Ruby on Rails, Django, Spring — they're all in the patterns, but the skills ecosystem on skills.sh is still sparse for anything outside the JS/TS world.
Bottom line
Useful if you're already in the Vercel agent skills ecosystem and want to bootstrap skills.json without manually matching your stack to available skills. Too early to use in production pipelines — no tests, sequential network calls, and a skills registry that's thin outside JavaScript.