skills

一句话定位

为 DeepSeek Harness 注入一份覆盖 Upstash 全家桶（Redis、QStash、Vector、Workflow、Box、Ratelimit、Search、CLI 以及免账号的临时 Redis）的 AI 技能包，并自动挂载 Upstash 官方 MCP 服务器，让代理既能读 SDK 文档又能直接调用 Upstash API。

核心能力

• 在 DSH 内注册一个名为 upstash 的技能来源（@deepseek-ai/dsh-skill-filesystem），技能根目录指向包自带的 skills/，与其他技能源互不覆盖
• 自动启动 @upstash/mcp-server@latest（通过 npx 拉取，stdio 传输），把 Upstash REST API 直接暴露给 DSH 代理：可建数据库、发 QStash 消息、查询向量、查 Search 索引等
• 暴露 /upstash-login <email> <api-key> 会话命令，把凭证写入 ~/.dsh/.credentials.yaml，写入后 MCP 即自动重连；凭证缺一就不会启动 MCP，但纯文档技能不受影响
• 监听宿主 credentials/updated 事件，凭证任一被 set / unset / 外部修改都会重新装配 MCP 子进程，并发重入通过任务队列串行化避免孤儿进程
• 提供 11 个子技能（Box JS/Py、CLI、QStash、RateLimit、Redis、Redis Start、Search、Vector、Workflow）+ 一个聚合的 upstash 总技能，技能描述写在 SKILL.md 的 frontmatter，DSH 代理可按当前问题按需加载

技术实现

• 语言: JavaScript（ESM，单文件 index.mjs）；构建脚本同样使用 Node ESM
• 关键依赖: @deepseek-ai/dsh-skill-filesystem（技能源）+ @deepseek-ai/dsh-mcp-client（通用 stdio MCP 客户端），二者均通过 import * as 由宿主解析；MCP 服务端 @upstash/mcp-server@latest 由 npx -y 在首次启动时拉取，不写进本包依赖
• 架构模式: DSH bundle。package.json#dsh.bundle.patch 指向 .dsh-plugin/cordis.patch.yml，后者在 profile 装配阶段插入一条 Loader；index.mjs 导出 name = "upstash"、inject = ["skills", "credentials", "commands"]，由宿主调用 apply(ctx) 完成自举
• 入口文件: .dsh-plugin/index.mjs（DSH 挂载入口）；技能源在 skills/upstash/SKILL.md；构建脚本 scripts/build.mjs 负责把各 skills/upstash-*/SKILL.md 聚合成 skills/upstash/SKILL.md，CI 用 scripts/check.mjs 在 diff 非空时失败

适用场景

希望用 DSH 代理直接搭建或调试 Upstash 全家桶应用的用户：让代理按自然语言读 SDK 文档、写 Redis / QStash / Vector / Workflow 代码，或通过自然语言直接对生产数据库做增删改查；也适合代理在没有正式凭证时先拿 upstash-redis-start 拿一个 3 天有效的临时 Redis 做短期记忆或会话历史。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:upstash/skills

配置项

本插件没有 Schema 配置项；凭证通过 /upstash-login 命令以人机会话形式写入，可写入的字段如下：

环境变量同名值会覆盖托管凭证：若 DSH 启动时 process.env 已存在 UPSTASH_EMAIL 或 UPSTASH_API_KEY，则托管凭证不可写、/upstash-login 会报错拒绝写入。

常见问题

Q: 装了之后代理能直接帮我建 Upstash Redis 数据库吗？

A: 能，但需先在会话里执行 /upstash-login <email> <api-key> 把凭证写入 ~/.dsh/.credentials.yaml，DSH 才会启动 MCP 子进程；未配凭证时技能仍可用，但只能走 HTTP/SKILL 文档路线，无法调用 Upstash API。

Q: 为什么 /upstash-login 提示某个变量无法写入？

A: 因为同名变量（UPSTASH_EMAIL 或 UPSTASH_API_KEY）已经从 DSH 启动环境继承，环境来源优先级高于托管凭证。需要先在启动环境里清掉它，再重试命令。

Q: 凭证存放在哪里？会被写进会话日志吗？

A: 两条凭证写到 ~/.dsh/.credentials.yaml；/upstash-login 命令注册时设了 recordInput: false，命令行输入的 email/key 不会进入会话日志；MCP 子进程环境变量会被宿主的 scrub 规则剥离 /KEY|PASSWORD|SECRET|TOKEN/i 命名的继承字段，所以 API Key 必须由插件显式 env 注入。

Q: 不装 DSH 也能用这套技能吗？

A: 可以。仓库同时是 Agent Skills、Claude Code、Cursor、OpenAI Codex、Zed 五种插件形态；DSH 路径会顺带挂载 MCP，其他 Agent 路径只挂载 SKILL.md 文档，详见 README 中的各 Agent 安装小节。

Q: 改了一个子技能的 SKILL.md 后还要做什么？

A: 在仓库根目录跑 npm run build：scripts/build.mjs 会把所有子技能重组成 skills/upstash/ 下的合并技能并自动生成 SKILL.md；如果忘记 build，CI 的 npm run check 会因 git status 非空而失败。

Q: 这套技能里 upstash-redis-start 跟其他 Redis 技能有什么区别？

A: upstash-redis-start 不需要账号，一条 POST 到 https://upstash.com/start-redis 就能拿到一个 3 天有效的临时 Redis（带 endpoint + token），适合代理在拿不到正式凭证时做短期记忆/对话历史/工作队列；其余 Redis 技能针对的是已开通的 Upstash Redis。

Q: 为什么 DSH 安装时要带 --profile web？

A: 仓库的 DSH 入口是 .dsh-plugin/cordis.patch.yml + .dsh-plugin/index.mjs，只在引用它的 profile 启动时挂载；web 是 README 中演示用的 profile 名称，不指定 profile 的话装到默认配置中可能不生效。

上手难度

入门 — 安装一行命令即可；只要会发起 DSH 会话并执行 /upstash-login，其余都交由代理按 SKILL.md 描述自动选择。

已知问题与限制

• 首次装配 MCP 时 npx -y @upstash/mcp-server@latest 需要联网，且会下载新版本到本地缓存；离线环境下需要事先手动 npx 一次以填缓存，否则 MCP 不会启动（.dsh-plugin/index.mjs:64-74）
• /upstash-login 不能覆盖从启动环境继承的同名变量；若必须改用新值，需要先 unset 环境变量再重试命令（.dsh-plugin/index.mjs:111-118）
• 聚合技能 skills/upstash/ 是 scripts/build.mjs 自动生成的，禁止手改；改完子技能后未跑 npm run build 直接提交，CI 会拒绝合并（AGENTS.md:5-13 / scripts/build.mjs:9-16）
• MCP 子进程在凭证 set / unset 时通过 await fiber?.dispose() 整体回收再重启，期间对 MCP 的调用会短暂失败；由于 refresh() 通过 Promise 链串行化，两个凭证事件连发也不会产生孤儿进程，但首条命令的延迟会包含一次完整重启（.dsh-plugin/index.mjs:44-89）

A collection of skills for AI coding agents working with Upstash SDKs. Skills are packaged instructions and resources that extend agent capabilities.

This repo works as an Agent Skills repo, a Claude Code plugin, a Cursor plugin, an OpenAI Codex plugin, and a DeepSeek Harness bundle.

Available Skills

Installation

Claude Code Plugin

# Add the marketplace
/plugin marketplace add upstash/skills

# Install the plugin
/plugin install upstash@upstash

Cursor Plugin

We are waiting for this plugin to be accepted to the official Cursor Marketplace. Once listed, it can be installed from Customize in the Cursor sidebar.

OpenAI Codex Plugin

# Add the marketplace
codex plugin marketplace add upstash/skills

# Install the plugin
codex plugin add upstash@upstash

Zed

Zed loads Agent Skills from .agents/skills/ in a project and ~/.agents/skills/ globally, which is exactly where the Agent Skills CLI writes them:

# Available in every project
npx skills add upstash/skills --agent zed --global

# Or just this project
npx skills add upstash/skills --agent zed

The skills then show up in Zed's Agent Panel, and the agent can load them on its own or via /upstash. Zed's extension marketplace carries languages, themes, debuggers, snippets, and MCP servers, but has no channel for skills, so the CLI is the only way to install them. The Zed extension in zed-extension/ covers the MCP server instead.

Context7 CLI

npx ctx7 skills install upstash/skills

Agent Skills CLI

npx skills add upstash/skills

DeepSeek Harness

Installs the skills and the Upstash MCP server in one step. Requires pnpm on your PATH.

# Install into a profile (`web` is the one `dsh web` boots)
dsh plugin --profile web add github:upstash/skills

# Start the harness
dsh web

Then store your Upstash credentials from inside a session:

/upstash-login YOUR_EMAIL YOUR_API_KEY

Credentials are stored in ~/.dsh/.credentials.yaml and the MCP server connects as soon as both are set. The skills work without them.

MCP Server

For full access to Upstash APIs (create databases, publish messages, query vectors, etc.), you can also set up the @upstash/mcp-server:

claude mcp add upstash -- npx -y @upstash/mcp-server@latest --email YOUR_EMAIL --api-key YOUR_API_KEY

{
  "mcpServers": {
    "upstash": {
      "command": "npx",
      "args": ["-y", "@upstash/mcp-server@latest", "--email", "YOUR_EMAIL", "--api-key", "YOUR_API_KEY"]
    }
  }
}

{
  "context_servers": {
    "upstash": {
      "command": "npx",
      "args": ["-y", "@upstash/mcp-server@latest", "--email", "YOUR_EMAIL", "--api-key", "YOUR_API_KEY"]
    }
  }
}

Making changes

Updating an existing skill

1. Edit the files in the individual skill folder (e.g. skills/upstash-qstash-js/).
2. Run npm run build to regenerate skills/upstash/.
3. Commit both the source changes and the regenerated output.

Adding a new skill

1. Create a new folder under skills/ (e.g. skills/upstash-redis-js/).
2. Add a SKILL.md with the standard frontmatter (name and description) and any supporting files.
3. Run npm run build — the new skill will be picked up automatically.
4. Commit everything.

Changing the combined skill header

The frontmatter and introductory text for skills/upstash/SKILL.md comes from scripts/header.md. Edit that file, then run npm run build.

Updating the plugin version

When making a release, bump the version field in every manifest that carries one: plugin.json (the portable Agent Plugins manifest), .claude-plugin/plugin.json, .cursor-plugin/plugin.json, and .codex-plugin/plugin.json.

The Zed extension

zed-extension/ is a Zed MCP server extension that runs @upstash/mcp-server. It is a Rust crate compiled to WebAssembly, and it is only about the MCP server — Zed extensions cannot carry skills.

cd zed-extension
rustup target add wasm32-wasip2   # once
cargo build --release --target wasm32-wasip2

Test a local build with zed: install dev extension and point Zed at zed-extension/. Open Zed on a folder while testing — context servers are project-scoped, so with no project open (or one whose worktree fails to open) the server never starts and the panel sits on "Connecting Server..." until Zed's 60s timeout.

To publish or update it, open a PR against zed-industries/extensions that adds this repo as a submodule under extensions/mcp-server-upstash and an entry in extensions.toml:

[mcp-server-upstash]
submodule = "extensions/mcp-server-upstash"
path = "zed-extension"
version = "0.1.0"

The version there has to match version in zed-extension/extension.toml, so bump both together. zed-extension/LICENSE is a symlink to the repo's MIT license — Zed requires a license at the extension path, not just at the repo root, and rejects the PR in CI without one.

Zed plans to deprecate MCP server extensions in favor of the official MCP registry. If that lands, publishing @upstash/mcp-server to registry.modelcontextprotocol.io replaces this extension.

Scripts

CI

The GitHub Actions workflow (.github/workflows/check.yml) runs npm run check on every push and PR. If you forget to run npm run build before pushing, CI will fail.