drizzle-team / drizzle-team/drizzle-orm
[FEATURE]: Ship drizzle-kit agent skills as one router skill instead of ~8 top-level skills
- Dominant language
- TypeScript
- Stars
- 35.8k
- Forks
- 1.6k
- Avg merge
- 2d 7h
- Merged PRs (30d)
- 4
Description
**Scope:** this targets the `1.0.0-rc.4` line specifically — the agent skills don't exist on `main`. They were introduced in #5691 (output modes + typed SDK + first skills) and the catalog was expanded to its current 8 in #5920. This feedback is about how that catalog is packaged before it stabilizes.
`drizzle-kit/skills/` currently ships 8 separate top-level skills: `drizzle`, `drizzle-generate`, `drizzle-hints`, `drizzle-migrations`, `drizzle-output-modes`, `drizzle-pull`, `drizzle-push`, `drizzle-responses-and-errors`.
Every installed skill's `name` + `description` is loaded into the context window of **every** coding-agent session, whether or not the session touches drizzle-kit. Installing the full bundle means 8 name/description pairs sit in context on unrelated work — pure overhead.
### Proposal: one umbrella "router" skill for drizzle-kit
Ship a single drizzle-kit skill (e.g. `drizzle-kit`) whose description is the only thing ever preloaded, e.g.:
> Use when working with Drizzle Kit — running `drizzle-kit `, editing `drizzle.config.ts`, or handling its output. Loads task-specific instructions from the library authors.
The skill body is a routing table mapping context → instruction file, and the agent reads only the relevant file on demand:
| Working on... | Read |
|---|---|
| Generating migrations | `generate.md` |
| Pushing schema | `push.md` |
| Pulling / introspection | `pull.md` |
| Migration workflow | `migrations.md` |
| Output modes | `output-modes.md` |
| Resolving hints | `hints.md` |
| Responses & errors | `responses-and-errors.md` |
The current per-command skills become plain files under the umbrella (not independently installed skills). This is a drizzle-kit-scoped concern — Drizzle ORM (query/schema) instructions, if any, stay their own separate skill and aren't pulled into drizzle-kit work.
### Why this is better
- **Context cost is paid once, and only when relevant.** Unrelated sessions never load drizzle-kit instructions at all. Drizzle-kit sessions load one description, then pull only the files they need — instead of 8 descriptions always resident.
- **Scales cleanly.** Adding a new command adds a table row + a file, not another top-level skill competing for context in every session.
- **Simpler install.** One skill to install/version instead of 8.
- **Matches the model's actual flow.** It already narrows "I'm doing a drizzle-kit migration" → reads the migration instructions; the router makes that the explicit structure.
The existing `drizzle` skill (staleness check + surface selection) already acts as a natural entry point and could absorb the routing table.
### Trade-off
The one thing lost: today the installer (the `skills` CLI) detects the multiple skills in the repo and prompts the user to pick which to install — per-skill granularity. Folding them into one router removes that choice; you install the whole bundle or nothing. In practice that granularity doesn't seem necessary here — these files are small and cohesive, so shipping them together and letting a user trim/edit within the single skill is simpler than maintaining 8 independently-installable units.
Contributor guide
Assessment
This issue has not been assessed yet.