ryasrk/dsh-awesome-skills

---

description: "Semantic vector search over a 6,097-skill local corpus (skills.sh top 100 + the a5c-ai/babysitter library), installed as a DeepSeek Harness bundle" kind: "package-reference"

dsh-awesome-skills

A DeepSeek Harness bundle that gives agents semantic access to a curated local skill corpus — the skills.sh top 100 (83 GitHub-hosted skills) plus the full a5c-ai/babysitter library (~2,100 skills) — 6,097 skills total — without ever putting that corpus into the per-turn model catalog.

Why

A skill directory that DeepSeek Harness discovers becomes a catalog entry, and every catalog entry is injected into the model's context on every turn. A large corpus there is a very large per-turn token bill for something almost never needed on a given turn.

This plugin inverts that. The corpus stays out of the catalog; a single small skill-router skill is installed instead, and it teaches the agent to search the corpus on demand.

The corpus

The corpus is organized by source, one directory per owner/repo, with each skill directory carrying its complete content — SKILL.md plus every reference file it points at (examples, templates, scripts):

skills/
├── a5c-ai/babysitter/            # ~2,100 skills (specializations + methodologies incl. the domains tree)
├── mattpocock/skills/            # 17 skills (tdd, grilling, code-review, ...)
├── microsoft/azure-skills/       # 20 skills (incl. microsoft-foundry: 191 files)
├── anthropics/skills/frontend-design/
├── vercel-labs/agent-skills/     # vercel-react-best-practices (62 rules)
├── obra/superpowers/             # brainstorming, systematic-debugging, ...
└── ...                           # 157 owner/repo groups, 6,097 skills, 17,600+ files

The 17 site-only entries on the skills.sh leaderboard (the open.feishu.cn lark suite and similar, which have no public repository) are excluded — there is nothing to fetch from.

Path	Contents
lib/	Compiled plugin host + search service + query.js CLI
skills/skills.json	Corpus index: name, path, description per skill
skills/vectors.f32	384-dim L2-normalized embeddings, one row per skill
model/	all-MiniLM-L6-v2, quantized ONNX + tokenizer

The index ships prebuilt and is committed. Skill bodies live in the canonical corpus directory (~/.dsh/awesome-skills/skills), referenced — not copied — by the package: search results return paths into it, so there is exactly one copy of the corpus on disk.

Install

dsh plugin --profile web add github:ryasrk/dsh-awesome-skills

The plugin mounts as a cordis bundle (see cordis.patch.yml) and, on apply, installs the bundled skill-router skill into ~/.agents/skills/skill-router. The bundled skill-router is refreshed on every apply — the shipped copy is the source of truth for its behaviour.

Model-facing tools

On hosts that expose the tools service, the plugin registers two tools that run in-process with host authority — the standard-permission-mode path to the corpus, since the agent needs no Bash or out-of-workspace Read:

• skills_search(query, k?) — the calibrated hybrid search; settings knobs (prio/blacklist/whitelist) apply.
• skills_read(path, file?) — one file from a hit's directory, guarded to the corpus root (no traversal), text extensions only, 64 KiB cap.

The skill-router skill teaches the tool-first flow and keeps the node lib/query.js CLI (JSON on stdin → JSON on stdout) as a shell-agnostic one-paragraph fallback for hosts without the tools service — it reads stdin and writes stdout, so no bash-specific syntax is required on any shell (bash, PowerShell, cmd).

Ranking

Three lanes are fused, then re-ranked over a candidate pool:

score = (1 - WEIGHT) * semantic + WEIGHT * lexical + GRAM_WEIGHT * char-3-gram

• Semantic — MiniLM cosine, brute force over all rows. Exact; no quantization drift.
• Lexical — IDF-weighted token overlap.
• Char 3-gram — script-agnostic, so CJK/Cyrillic queries and technical identifiers still discriminate.

WEIGHT 0.55, GRAM_WEIGHT 0.5, pool 1200. Re-checked on the shipped corpus with a 150-label canonical set: R@1 80%, R@3 93%.

Speed

Measured on the shipped 6,097-skill corpus (brute force still scores every row; the per-process model load dominates):

Path	Latency
Cold (model load)	~0.7s
Warm (query cache hit)	~0.6s

Derived caches (per-skill char grams, query embeddings) live next to the corpus and are keyed by a corpus fingerprint, so a corpus change invalidates them automatically.

Service surface

Other plugins and tools can use the search service directly:

const search = ctx.get('skills-search')
const hits = await search.search('set up end-to-end browser tests', 5)
const dir = search.skillDir(hits[0].path) // e.g. .../skills/mattpocock/skills/tdd

A hit's path is the subpath under the corpus root (owner/repo/skill), and every consumer joins corpusDir + path + /SKILL.md — the priority loader, the skill-router template, and the settings UI all share that one convention. Reference files live beside the SKILL.md, so a hit's directory is the whole playbook.

Configuration

All fields optional, via a cordis.patch.yml row:

Field	Default	Meaning
corpusDir	~/.dsh/awesome-skills/skills	Skill bodies (<path>/SKILL.md)
home	OS home (os.homedir())	Base home the router skill installs under (<home>/.agents)
agentsHome	<home>/.agents	Agents home whose skills/ root the harness reads; overrides $DSH_AGENTS_HOME
installSkillRouter	true	Install the router skill on apply

Environment: DSH_AWESOME_SKILLS_CORPUS (corpus), DSH_AWESOME_SKILLS_INDEX (index directory for the CLI), DSH_AGENTS_HOME (agents home; resolved the same way the harness skill provider does, so a relocated agents home still receives the router skill).

Rebuilding the index

The index ships prebuilt in skills/skills.json and skills/vectors.f32; a user never needs to rebuild it. Rebuilding after changing the corpus is a maintainer step done in the separate corpus-ingestion workspace (the walker lives there, not in this package) — it reads the corpus recursively and rewrites skills.json and vectors.f32, which are then copied back into this repo's skills/. If a deployed profile carries a stale index, re-sync this repo's lib/ and skills/ directories into the profile's installed copy.

A skill directory is any directory holding a SKILL.md; directories nested inside one (a sub-skill shipped as reference material) are not indexed separately. Regenerate the client bundle after pulling source changes: npx tsdown -c tsdown.client.ts, then run node scripts/preflight.mjs.

License

MIT