drizzle-team / drizzle-team/drizzle-orm

[FEATURE]: Ship drizzle-kit agent skills as one router skill instead of ~8 top-level skills

Open
#5,990 2 comments 2 reactions 1 assignee Claimed by @dankochetov View on GitHub
drizzle/kit
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.