Val Town

Val Town 的 Agent 插件

为 Claude Code、Codex 和 Cursor 安装 Val Town MCP 服务和 Skills。

Skills 是包含平台指南的 Markdown 文件，介绍如何基于 Val Town 构建。 Val Town 自有工具（Townie、MCP 服务）和 AI 编码 Agent 会使用这些文件。 Skills 涵盖 HTTP vals、定时任务、SQLite、电子邮件、OAuth、前端和 API 集成。

安装

安装插件后，Agent 即可使用平台 Skills，并注册托管的 Val Town MCP 服务（https://api.val.town/v3/mcp）。首次使用 MCP 工具时，Agent 会在浏览器中运行 OAuth 流程。

1. Claude Code
2. Codex
3. Cursor

Claude Code

运行以下命令安装 Val Town 插件：

claude plugin install valtown@claude-plugins-official

Codex

codex CLI

首先运行：

codex plugin marketplace add val-town/plugins

然后启动 codex 并运行：

/plugins

搜索 Val Town，点击安装，随后按提示完成 OAuth 流程。

Codex 桌面应用

1. 点击侧边栏中的“Plugins”
2. 在标有“Built by OpenAI”的下拉菜单中，点击“Add more +”
3. 复制粘贴 https://github.com/val-town/plugins，然后选择“Add marketplace”

Cursor

在 Cursor 中运行：

/add-plugin valtown

也可以在 Cursor Settings 中，将 https://github.com/val-town/plugins 复制粘贴到搜索框，然后选择“Add to Cursor”。

贡献

编写 Skills

Skills 位于 plugin/skills/<name>/SKILL.md 中，包含 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（必填）— 必须与目录名称一致；使用小写字母和连字符，长度不超过 64 个字符。
• description（必填）— 以“Use when…”的形式编写；Claude 会根据它决定何时加载该 Skill。长度不超过 1024 个字符。
• triggers（可选）— 用于提升 searchSkills 排名的关键词提示；Claude Code 的原生加载器会忽略此项。

内容应当不受受众限制：只包含对所有使用方都适用的平台知识。不要提供仅适用于特定产品流程或聊天的建议。

然后构建：

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

npm run generate 会根据我们的 schema 和 Claude Code 的 frontmatter 限制验证每个 Skill；无法在 Claude Code 中加载的 Skill 会导致构建失败。

与 Val Town monorepo 的关系

此软件包是 Skills 内容的唯一事实来源。Val Town 应用和 MCP 服务将其作为依赖使用，而不是各自维护副本。完整设计请参阅主仓库中的 docs/SKILLS_PLUGIN.md。

版本管理

此仓库使用 Changesets 发布。更多信息请参阅其文档。

• 对于每项应触发新版本的更改，请运行 npx @changesets/cli，并按照交互式提示填写更改说明。这将在 .changesets 目录中生成一个新的 changeset。
• 该目录中的每项更改都会触发 GitHub action release.yml 创建一个新的发布 PR。
• 合并发布 PR 后，此模块的新版本将自动发布。

配置

Claude Code

官方 Claude 插件市场从 .plugins/marketplace.json 获取内容。

Codex

Codex 会读取原生插件市场 .agents/plugins/marketplace.json（并在需要兼容时回退到 Claude 的 .claude-plugin/marketplace.json）。

Cursor

Cursor 会读取 .cursor-plugin/marketplace.json 和每个插件对应的 plugin/.cursor-plugin/plugin.json。