Valtown

Agent plugins for Val Town

Installs the Val Town MCP server and Skills for Claude Code, Codex, and Cursor.

Skills are markdown files with platform guidance for building on Val Town. Used by Val Town's own tools (Townie, the MCP server) and by AI coding agents. Skills include HTTP vals, crons, SQLite, email, OAuth, frontend, and API integrations.

Install

Installing the plugin makes platform skills available to your agent and registers the hosted Val Town MCP server (https://api.val.town/v3/mcp). On first use of an MCP tool, the agent runs the OAuth flow in your browser.

1. Claude Code
2. Codex
3. Cursor

Claude Code

Install the Val Town plugin by running:

claude plugin install valtown@claude-plugins-official

Codex

codex CLI

First, run:

codex plugin marketplace add val-town/plugins

Then fire up codex and run:

/plugins

Search for Val Town, hit install, and it'll take you through the OAuth path.

Codex desktop app

1. Click "Plugins" in the sidebar
2. In the dropdown that says "Built by OpenAI" click "Add more +"
3. Copy-paste https://github.com/val-town/plugins and select "Add marketplace"

Cursor

In Cursor, run:

/add-plugin valtown

Or in Cursor Settings, copy-paste https://github.com/val-town/plugins in the search box and select "Add to Cursor."

Contributing

Authoring skills

Skills live in plugin/skills/<name>/SKILL.md with YAML frontmatter:

---
name: http-endpoints
description: Use when building an HTTP val — a web endpoint, API route, webhook...
triggers: [http, endpoint, webhook, api, request, response]
---

# HTTP Endpoints

...guide body...

• name (required) — must match the directory name; lowercase, hyphens, ≤64 chars.
• description (required) — written as "Use when…"; this is how Claude decides to load the skill. ≤1024 chars.
• triggers (optional) — keyword hints that boost searchSkills ranking; ignored by Claude Code's native loader.

Keep content audience-neutral: only platform knowledge true for every consumer. No product-flow or chat-only advice.

Then build:

npm install
npm run build   # generate src/generated/skills.ts, then tsc
npm test        # build + smoke tests