The best agent skills are the ones already written, audited, and picked for you. SkillRanger is an author-curated library of agent skills — hand-crafted, pre-audited, static instructions — plus a router that scans your repository and selects the small set your project actually needs, showing the full plan before anything is written.
npx -y skillranger@latest setupRun that one command inside your project. SkillRanger requires Node.js 20 or newer. The setup flow takes about 30 seconds and works like this:
- Scan — detects your repository's stack (
Detected:types, languages, frameworks, styling, testing). - Recommend — selects a small compatible skill set (
Selected N skills:), not a dump of everything that exists. - Plan — shows exactly which files would be written or updated (
Planned changes:). Nothing is touched yet. - Audit — prints a computed risk level and finding count for every recommended skill (
Audit summary:). - Install — after you confirm, writes the reviewed instructions, adds a managed block to your
AGENTS.md, and records checksums inskillranger.lock.json.
To script the same flow, pass --yes with an intent. Interactively, setup asks you to confirm the target agents, scope, and install mode. In an interactive terminal, setup ends with a single line pointing to the repository; it stays quiet in CI.
For a repo-scoped setup, SkillRanger creates or updates:
.agents/skills/<skill>/— repository-local skill packages;AGENTS.md— a bounded, marker-delimited SkillRanger-managed context block;skillranger.lock.json— installed versions, checksums, targets, and audit metadata.
Installed skills are static instructions. SkillRanger does not invoke a model itself, execute skill scripts, or silently modify your application code.
Good agent skills take real work: research your stack, write the instructions, test them, keep them updated. Without SkillRanger that work lands on you — or the project settles for whatever skill a blog post happened to paste.
SkillRanger flips it: the skills are already written, audited, and picked for you. The problems it removes:
- Curating skills is someone else's job. The library is hand-crafted and pre-audited — you get a maintained, versioned skill set without maintaining it yourself.
- Copy-pasted skills rot. The skill you pasted from a blog post has no version, no checksum, and no update path. Months later your agent still follows instructions written for an old API, and nobody knows.
- Install-all lists bloat your repo. Dumping forty skills into the project makes every agent read more context than it needs. The right two skills for your stack get lost in the noise.
- Trust is granted before review. In most install flows the plan is the install. You never see what will be written, and no one checks the skill for credential access, destructive commands, or prompt-injection patterns before it lands in the context your agent trusts most.
SkillRanger exists to make the review step the default instead of an exception: recommend a small set, audit it, show the plan, then write.
| SkillRanger | Manual copying | Git submodule | Static curated collections | |
|---|---|---|---|---|
| Who curates the skills | Author-curated library, maintained by SkillRanger | You | The upstream repo | Third parties, browse by hand |
| Versioning | Lockfile-pinned installs (skillranger.lock.json) |
None — paste and forget | Upstream commit recorded; git submodule update syncs to it |
Whatever upstream does |
| Integrity checks | SHA-256 checksums recorded and verified | None | Git hash integrity | None stated |
| Relevance to your repo | Selected from detected stack + your intent | Whatever you pick | A fixed repo, not per-project selection | Browse and pick by hand |
| Audit before install | Static security audit per skill, shown in the plan | None | None | None (see below) |
| Multiple agent targets | Codex, Claude Code, Cursor, OpenCode, Gemini CLI, MCP hosts | Copy per agent by hand | One checkout; per-agent mapping is manual | Per collection |
| Review before writing | Full plan and audit summary before confirm | None | None | None |
Best when:
- SkillRanger — you want the skills already written for you, auto-selected for your stack.
- Manual copying — you need one or two files and want no tooling at all.
- Git submodule — your priority is exact synchronization with an upstream repo.
- Static curated collection — your priority is browsing and choosing skills by hand.
Third-party notes: git submodule tracks a recorded upstream commit and updates the working tree to match it (git-scm.com/docs/git-submodule, checked 2026-08-12). Curated collections such as anthropics/skills present skills for manual browsing and are described as demonstration and educational material — "always test skills thoroughly in your own environment before relying on them" (github.com/anthropics/skills README, checked 2026-08-12); they do not audit before install.
Where SkillRanger is not the best choice: it currently ships frontend skills — backend and other directions are on the way — so a backend-only project will get few or no recommendations. Skills are instructions, not code: the host agent still does the work. And if you never install curated instructions into your agent's context, you do not need SkillRanger at all.
Repository + task
│
▼
Detect stack and project context
│
▼
Select a small compatible skill set
│
▼
Audit and preview installation
│
▼
Install reviewed instructions and lockfile metadata
│
▼
Your agent reads the selected instructions and performs the task
Repo-local setup is supported for Codex, Claude Code, Cursor, OpenCode, Gemini CLI, and Model Context Protocol hosts through the stdio MCP server. One install can target several agents at once (--target codex,claude-code).
SkillRanger ships with 18 author-curated, pre-audited, instruction-only skills — frontend today, more directions on the way: framework reviews (Next.js App Router, React), component and Tailwind polish, visual design, UX, interaction, motion, accessibility, performance, testing strategy, Playwright debugging, release audits, and agent-context bootstrap.
The full table of skill IDs, categories, and purposes is in docs/bundled-skills.md.
- Bundled local registry — packages ship with the distribution; normal recommendation never fetches arbitrary remote skills.
- Static instructions — skills are text, not scripts; nothing executes during installation.
- Explicit writes — CLI installs can be previewed with
--dry-run; interactive setup always shows the plan before writing. - Integrity tracking — installed files are hashed and recorded in
skillranger.lock.json;skillranger verifychecks them. - Host-managed execution — the host owns model calls and code changes; SkillRanger validates what a model proposes and refuses ineligible or unsafe skills.
The full threat model lives in docs/SECURITY.md.
SkillRanger runs as a stdio MCP server so a host agent can analyze projects, recommend and audit skills, discover the audited catalog, propose a skill set for a task, preview or confirm installations, and serve the installed instructions:
{
"mcpServers": {
"skillranger": {
"command": "npx",
"args": ["-y", "skillranger@latest", "mcp"]
}
}
}When a host model proposes skills for a task, SkillRanger validates the proposal against catalog, audit, and compatibility rules before composing the final set — a model cannot add arbitrary skills or bypass an audit gate. Host configuration for Claude Code, Cursor, and other clients: docs/mcp-host-config.md.
Just tell your agent to use SkillRanger: through the MCP server it picks the best skills for your task from the audited catalog — no hunting through collections, no setup ritual.
docs/bundled-skills.md— the full bundled skill catalogdocs/cli-reference.md— every command and flagdocs/model-assisted-routing.md— catalog-assisted routing for hostsdocs/workflow-runtime.md— persisted runs, evidence, and recoverydocs/verification-engine.md— evidence and verification gatesdocs/design-rule-library.md— frontend design rules and recipesdocs/REGISTRY.md— skill package metadata and registry designdocs/ARCHITECTURE.md— system architecturedocs/SECURITY.md— threat model
git clone https://github.com/Narek-Khachikyan/SkillRanger.git
cd SkillRanger
pnpm install
pnpm build
pnpm check
pnpm test
pnpm release:checkContributions are welcome — see CONTRIBUTING.md for environment setup, how to create a skill package, and the PR gates.
Distributed under the MIT License.