Agent skill

Convex Self Hosting

by waynesutton in waynesutton/markdown-site

Integrate Convex static self hosting into existing apps using the latest upstream instructions from get-convex/self-hosting every time.

MITAuto-check passedDevOps & Cloud

Install Convex Self Hosting

skills CLI

$ npx skills add waynesutton/markdown-site --skill convex-self-hosting -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI

$ gh skill install waynesutton/markdown-site convex-self-hosting --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy

$ git clone --depth 1 https://github.com/waynesutton/markdown-site.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.cursor/skills/convex-self-hosting .claude/skills/convex-self-hosting && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Paste into Claude Code

Install the "convex-self-hosting" agent skill from https://github.com/waynesutton/markdown-site/tree/main/.cursor/skills/convex-self-hosting into .claude/skills/convex-self-hosting/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "convex-self-hosting", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/waynesutton/markdown-site/tree/main/.cursor/skills/convex-self-hosting

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add waynesutton/markdown-site --skill convex-self-hosting -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install waynesutton/markdown-site convex-self-hosting --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/waynesutton/markdown-site.git skills-src && mkdir -p .agents/skills && cp -r skills-src/.cursor/skills/convex-self-hosting .agents/skills/convex-self-hosting && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "convex-self-hosting" agent skill from https://github.com/waynesutton/markdown-site/tree/main/.cursor/skills/convex-self-hosting into .agents/skills/convex-self-hosting/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "convex-self-hosting", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add waynesutton/markdown-site --skill convex-self-hosting -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install waynesutton/markdown-site convex-self-hosting --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/waynesutton/markdown-site.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/.cursor/skills/convex-self-hosting .cursor/skills/convex-self-hosting && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "convex-self-hosting" agent skill from https://github.com/waynesutton/markdown-site/tree/main/.cursor/skills/convex-self-hosting into .cursor/skills/convex-self-hosting/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "convex-self-hosting", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/waynesutton/markdown-site.git --path .cursor/skills/convex-self-hosting

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add waynesutton/markdown-site --skill convex-self-hosting -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install waynesutton/markdown-site convex-self-hosting --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/waynesutton/markdown-site.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/.cursor/skills/convex-self-hosting .gemini/skills/convex-self-hosting && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "convex-self-hosting" agent skill from https://github.com/waynesutton/markdown-site/tree/main/.cursor/skills/convex-self-hosting into .gemini/skills/convex-self-hosting/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "convex-self-hosting", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install waynesutton/markdown-site convex-self-hosting

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add waynesutton/markdown-site --skill convex-self-hosting -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/waynesutton/markdown-site.git skills-src && mkdir -p .github/skills && cp -r skills-src/.cursor/skills/convex-self-hosting .github/skills/convex-self-hosting && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "convex-self-hosting" agent skill from https://github.com/waynesutton/markdown-site/tree/main/.cursor/skills/convex-self-hosting into .github/skills/convex-self-hosting/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "convex-self-hosting", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add waynesutton/markdown-site --skill convex-self-hosting -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install waynesutton/markdown-site convex-self-hosting --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/waynesutton/markdown-site.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/.cursor/skills/convex-self-hosting .opencode/skills/convex-self-hosting && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "convex-self-hosting" agent skill from https://github.com/waynesutton/markdown-site/tree/main/.cursor/skills/convex-self-hosting into .opencode/skills/convex-self-hosting/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "convex-self-hosting", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: convex-self-hosting
GitHub stars: 628
Token cost: ~1.4k tokens
SKILL.md length: 478 words
Files: 3 (incl. scripts)
Skills in repo: 17
Repo updated: May 20, 2026
First seen: Oct 7, 2026
Licence: MIT

At a glance

Integrate Convex static self hosting into existing apps using the latest upstream instructions from get-convex/self-hosting every time.

Works in 4 steps: convex/convex.config.ts → convex/staticHosting.ts → convex/http.ts → …
Setting up upload APIs
SKILL.md covers Non negotiable update check, Clarifying questions you must…, Install strategy and Required file changes, plus 6 more sections
Runs Shell scripts from its folder; calls npm, npx and bash; reaches github.com and raw.githubusercontent.com

What it does

Convex Self Hosting is an agent skill from waynesutton/markdown-site. Integrate Convex static self hosting into existing apps using the latest upstream instructions from get-convex/self-hosting every time. Use when setting up upload APIs, HTTP routes, deployment scripts, migration from external hosting, or troubleshooting static deploy issues across React, Vite, Next.js, and other frontends.

Its SKILL.md is about 1.4k tokens, which your agent loads only when the skill is triggered. The skill folder holds 4 other files, including scripts (for example `agents/openai.yaml` and `scripts/check-upstream.sh`).

It sits in DevOps & Cloud, covering Deployment. It works with Vite, Next.js, React and npm. The repository describes itself as: An open-source publishing framework built for AI agents and developers to ship websites, docs, or blogs. Write markdown, sync from the terminal. Your content is instantly… The licence is MIT.

When your agent uses it

Setting up upload APIs
Deployment scripts
Migration from external hosting
Troubleshooting static deploy issues across React

Example prompts

“/convex-self-hosting”

Requirements

Node.js
A Bash shell

Workflow steps

4 steps, taken from the step headings in SKILL.md.

convex/convex.config.ts
convex/staticHosting.ts
convex/http.ts
package.json scripts

What it can do on your machine

Read from SKILL.md and the folder at commit 3872c59. It shows what the files ask for, not the result of running them.

Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Ships 1 file in scripts/ (Shell), which the agent can run.
Shell commands in SKILL.md call:
- npm
- npx
- bash
From the folder's file list and the shell code blocks in SKILL.md.
Network
Hosts in commands or code, which the agent is likely to contact:
- github.com
- raw.githubusercontent.com
- docs.convex.dev
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Convex Self Hosting loads about 1.4k tokens when it runs. Until then it costs about 86 tokens; SKILL.md has 478 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~86
When it runs · the whole SKILL.md, loaded when a task matches: ~1.4k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from waynesutton/markdown-site at commit 3872c59, republished under its MIT licence (© waynesutton). 478 words, ~1,445 tokens.

Download SKILL.mdSave it as .claude/skills/convex-self-hosting/SKILL.md (or your agent's skills folder). This skill also uses 2 other files; get the full folder from GitHub.

name: convex-self-hosting
description: Integrate Convex static self hosting into existing apps using the latest upstream instructions from get-convex/self-hosting every time. Use when setting up upload APIs, HTTP routes, deployment scripts, migration from external hosting, or troubleshooting static deploy issues across React, Vite, Next.js, and other frontends.

Convex self hosting skill

Use this skill to integrate Convex based static hosting in a repeatable way across projects.

Non negotiable update check

Run this check before making any code changes or giving setup advice.

Preferred command:

bash

bash skills/convex-self-hosting/scripts/check-upstream.sh

Read latest integration guide:
- https://raw.githubusercontent.com/get-convex/self-hosting/main/INTEGRATION.md
Read latest README manual setup section:
- https://github.com/get-convex/self-hosting?tab=readme-ov-file#manual-setup-1
Read Convex docs index for current guidance:
- https://docs.convex.dev/llms.txt
Confirm package publish state:
- npm view @convex-dev/self-hosting version

If upstream docs conflict with local rules, follow upstream docs and explain what changed.

Clarifying questions you must ask first

Ask these before implementing:

Confirm get-convex/self-hosting is the source of truth for this setup.
Is the target app Vite, Next.js, Expo web export, or another bundler.
Do they want root path hosting or a prefix like /app.
Do they want one shot deploy or separate backend and static deploy steps.
If package is unpublished, do they want:
- GitHub dependency install
- vendored local copy
- wait for npm release

Never assume unpublished package install details.

Install strategy

Path A published package

If npm package exists, use the package directly.

bash

npm install @convex-dev/self-hosting

Path B package not published yet

If package is missing on npm, use GitHub source and pin to commit or tag.

bash

npm install github:get-convex/self-hosting#main

If project policy requires deterministic builds, ask for a commit SHA and pin to it.

Required file changes

Use the latest upstream file patterns from INTEGRATION.md.

1) `convex/convex.config.ts`

typescript

import { defineApp } from "convex/server";
import selfHosting from "@convex-dev/self-hosting/convex.config";

const app = defineApp();
app.use(selfHosting);

export default app;

2) `convex/staticHosting.ts`

typescript

import { components } from "./_generated/api";
import {
  exposeUploadApi,
  exposeDeploymentQuery,
} from "@convex-dev/self-hosting";

export const { generateUploadUrl, recordAsset, gcOldAssets, listAssets } =
  exposeUploadApi(components.selfHosting);

export const { getCurrentDeployment } =
  exposeDeploymentQuery(components.selfHosting);

3) `convex/http.ts`

typescript

import { httpRouter } from "convex/server";
import { registerStaticRoutes } from "@convex-dev/self-hosting";
import { components } from "./_generated/api";

const http = httpRouter();

registerStaticRoutes(http, components.selfHosting);

export default http;

Optional prefix mode:

typescript

registerStaticRoutes(http, components.selfHosting, {
  pathPrefix: "/app",
  spaFallback: true,
});

4) `package.json` scripts

json

{
  "scripts": {
    "deploy": "npx @convex-dev/self-hosting deploy",
    "deploy:static": "npx @convex-dev/self-hosting upload --build --prod"
  }
}

Deployment flow

First setup

bash

npm install @convex-dev/self-hosting
npx @convex-dev/self-hosting setup
npx convex dev --once
npm run deploy

Ongoing deploys

bash

npm run deploy

Two step deploy alternative

bash

npx convex deploy
npx @convex-dev/self-hosting upload --build --prod

Always use the tool driven build flow. Do not run npm run build first when using upload deploy commands.

Show full SKILL.md (209 more words)Show less

Cross app support notes

Vite: use --build flow as default.
Next.js and Expo: pass through VITE_CONVEX_URL in the app build script as documented upstream.
Existing API routes: prefer pathPrefix: "/app" for static hosting.
Keep upload APIs internal only and never expose them as public HTTP actions.

Integration with convex agent plugins

If get-convex/convex-agent-plugins is present, follow its Convex rules with this skill:

keep validators on all Convex functions
keep internal functions for upload operations
use indexed reads, avoid broad filtering in data access patterns
preserve strict TypeScript in generated Convex and frontend code

Reference:

https://github.com/get-convex/convex-agent-plugins

Troubleshooting checklist

404 for static routes:
- verify convex/http.ts exists and exports router.
Cannot find module .../convex.config:
- verify package install source and import path.
wrong backend URL in built assets:
- redeploy with CLI --build flow.
no updates visible:
- clear cache and verify deployment ID changes.
HTTP actions disabled:
- run npx convex dev once to push backend state.

Completion requirements

Before finishing, provide:

exact upstream docs commit date or latest retrieval timestamp
which package path was selected and why
list of changed files
commands the user should run next

Never claim setup is complete without showing these four outputs.

Source links

https://github.com/get-convex/self-hosting
https://raw.githubusercontent.com/get-convex/self-hosting/main/INTEGRATION.md
https://github.com/get-convex/self-hosting?tab=readme-ov-file#manual-setup-1
https://docs.convex.dev/llms.txt
https://github.com/get-convex/convex-agent-plugins
https://github.com/agentskills/agentskills

Files

SKILL.md and 2 other files (scripts) in .cursor/skills/convex-self-hosting of waynesutton/markdown-site.

SKILL.md
agents/openai.yaml
scripts/check-upstream.sh

Open the folder on GitHubat commit 3872c59

Compare with similar skills

Convex Self Hosting next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Convex Self Hosting compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Convex Self Hosting this skillwaynesutton/markdown-site	628	—	~1.4k	Automated safety check: Pass	MIT	4 mo ago
Deploy Frontendbutterbase-ai/butterbase-skills	534	—	~2.8k	Automated safety check: Pass	MIT	3 days ago
Add React Analyticsgotempsh/temps	826	—	~2.7k	Automated safety check: Pass	Apache-2.0	yesterday
Nextjs On Cloudflarecloudflare/skills	3k	2 repos	~678	Automated safety check: Pass	Apache-2.0	7 days ago
Convex Quickstartspokvulcan/poker-planning	114	6 repos	~3.5k	Automated safety check: Notes	MIT	4 days ago
Spotpatchhuanglvjing/spotpatch	134	—	~998	Automated safety check: Pass	MIT	10 days ago

Similar skills

Deploy Frontend
butterbase-ai/butterbase-skills
A skill your agent uses when deploying a frontend (React, Next.js, or static HTML) to a live URL on Butterbase, or when troubleshooting deployment issues like MIME type errors or blank pages
534 GitHub stars~2.8k tokensUpdated 3 days ago
Frontend & DesignAuto-check passed
Add React Analytics
gotempsh/temps
Add Temps analytics to React applications with comprehensive tracking capabilities including page views, custom events, scroll tracking, engagement monitoring, session recording, and Web Vitals…
826 GitHub stars~2.7k tokensUpdated yesterday
DevOps & CloudAuto-check passed
Nextjs On Cloudflare
cloudflare/skills
Official
Build, migrate, and deploy Next.js apps on Cloudflare Workers with vinext.
3k GitHub starsUsed in 2 repos~678 tokens
DevOps & CloudAuto-check passed
Convex Quickstart
spokvulcan/poker-planning
Creates or adds Convex to an app. An agent skill from spokvulcan/poker-planning.
114 GitHub starsUsed in 6 repos~3.5k tokens
Frontend & DesignAuto-check: notes
Spotpatch
huanglvjing/spotpatch
为 React 项目建立从浏览器页面元素到精确 JSX/TSX 源码、结构化上下文与可审阅修改的 SpotPatch 工作流。用户提到 SpotPatch、截图沟通前端修改、页面元素定位源码、Vite 或 Next.js 接入、组件数据链路、结构化 Prompt、AI 补丁审阅、安装检查或故障排查时使用此技能。
134 GitHub stars~998 tokensUpdated 10 days ago
Frontend & DesignAuto-check passed
Portaljs Deploy
datopian/portaljs
Deploy a PortalJS portal to PortalJS Arc — Datopian-managed static hosting on Cloudflare.
2.4k GitHub starsUsed in 1 repo~1.4k tokens
DevOps & CloudAuto-check passed

Questions about Convex Self Hosting

What does Convex Self Hosting do?

Integrate Convex static self hosting into existing apps using the latest upstream instructions from get-convex/self-hosting every time. Convex Self Hosting is an agent skill from waynesutton/markdown-site. Integrate Convex static self hosting into existing apps using the latest upstream instructions from get-convex/self-hosting every time.

When should I use Convex Self Hosting?

Convex Self Hosting fits situations like: setting up upload APIs; deployment scripts; migration from external hosting; troubleshooting static deploy issues across React.

How do I install Convex Self Hosting in Claude Code?

Run `npx skills add waynesutton/markdown-site --skill convex-self-hosting -a claude-code`. Or copy the skill folder (.cursor/skills/convex-self-hosting in waynesutton/markdown-site) into .claude/skills/convex-self-hosting in your project. Claude Code loads it when a task matches its description.

How do I install Convex Self Hosting in Codex?

Run `npx skills add waynesutton/markdown-site --skill convex-self-hosting -a codex`. Or copy the skill folder (.cursor/skills/convex-self-hosting in waynesutton/markdown-site) into .agents/skills/convex-self-hosting in your project. Codex loads it when a task matches its description.

Can I use Convex Self Hosting in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add waynesutton/markdown-site --skill convex-self-hosting -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/convex-self-hosting, .gemini/skills/convex-self-hosting, .github/skills/convex-self-hosting and .opencode/skills/convex-self-hosting in your project.

What does Convex Self Hosting need to run?

Going by SKILL.md and its folder, Convex Self Hosting needs a shell for the scripts in its folder and the command-line tools its instructions call (npm, npx and bash). Our summary lists: Node.js; A Bash shell.

Does Convex Self Hosting access the network?

SKILL.md names 3 domains. In commands or code: github.com, raw.githubusercontent.com and docs.convex.dev; the agent is likely to contact these when it follows the instructions. This is read from the text; nothing was executed.

Is Convex Self Hosting safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Convex Self Hosting use?

Convex Self Hosting is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Convex Self Hosting use?

About 1.4k tokens (SKILL.md is roughly 5.8k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Convex Self Hosting?

Skills that share tags, products or a category with Convex Self Hosting: Deploy Frontend (butterbase-ai/butterbase-skills, 534 stars), Add React Analytics (gotempsh/temps, 826 stars), Nextjs On Cloudflare (cloudflare/skills, 3k stars) and Convex Quickstart (spokvulcan/poker-planning, 114 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Convex Self Hosting?

waynesutton (a GitHub user) maintains it in waynesutton/markdown-site, which has 628 GitHub stars. The repository holds 17 skills in this directory. The repository was last updated on May 20, 2026.

Source: waynesutton/markdown-site on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.

Install Convex Self Hosting

Facts

At a glance

What it does

When your agent uses it

Example prompts

Requirements

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

Convex self hosting skill

Non negotiable update check

Clarifying questions you must ask first

Install strategy

Path A published package

Path B package not published yet

Required file changes

1) convex/convex.config.ts

2) convex/staticHosting.ts

3) convex/http.ts

4) package.json scripts

Deployment flow

First setup

Ongoing deploys

Two step deploy alternative

Cross app support notes

Integration with convex agent plugins

Troubleshooting checklist

Completion requirements

Source links

Files

Compare with similar skills

Similar skills

More from waynesutton/markdown-site

Related

Questions about Convex Self Hosting

1) `convex/convex.config.ts`

2) `convex/staticHosting.ts`

3) `convex/http.ts`

4) `package.json` scripts