Menu
Use when the user wants to persist a preference, skill, or knowledge. Use when it would aid future val development to store a memory of how best to build something.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use when a val needs to ship JavaScript that runs in the browser — React apps, vanilla DOM scripts, canvas/games, htmx/Alpine, or any client-side module beyond a single inline snippet. Explains how Val Town serves transpiled .ts/.tsx/.jsx modules with no build step, how the browser resolves their imports, and how to load third-party deps.
Use when building an HTTP val — a web endpoint, API route, webhook receiver, or any val that responds to HTTP requests. Covers the handler signature, Hono usage, the endpoint URL, CORS behavior, redirects, and Val Town-specific limitations.
Use when a val needs simple key/value persistence — JSON documents, cached responses, uploaded files, or binary assets. Covers the std/blob API, listing and deleting keys, account-global or val scoping, and storage limits.
Use when a val needs to require login with a Val Town account — gating routes behind authentication, identifying the current user, building user-specific dashboards. Covers std/oauth's `oauthMiddleware` and `getOAuthUserData`, the auto-managed `/auth/*` routes, and session behavior. For third-party OAuth providers (Google, GitHub, etc.) see the `third-party-integrations` skill instead.
Use when a val sends email, receives email, or is triggered by an incoming email. Covers email-type vals (the Email handler shape, attachment limits, the assigned val email address) and sending mail via std/email.
Use when a val needs to store structured or relational data. Covers the std/sqlite API, parameterized queries, transactions, and the val-scoped vs organization-scoped database distinction.
| name | create-skill |
| description | Use when the user wants to persist a preference, skill, or knowledge. Use when it would aid future val development to store a memory of how best to build something. |
| triggers | ["skill","preference","knowledge","memory"] |
Skills in Val Town instruct Townie and other AI agents using the Val Town MCP server how to write idiomatic vals that respect a user's preferences and knowledge.
In any val, a user can create a /skills/<name>/SKILL.md file, e.g. /skills/design/SKILL.md.
Townie and the Val Town MCP server index skills with that directory/file structure across all of a user's vals.
A user may choose to centralize their skills in one val or co-locate skills across multiple vals.
A skill markdown file must have frontmatter:
name: kebab-case name of the skill; contains lowercase letters, numbers, and hyphensdescription: helps the agent decide when the skill is relevant. A good skill description is critical for agent discoverytriggers: (optional) is a list of keywords to tip off the agentThe description and triggers fields enable skill discovery, i.e. tells the user's AI agent (e.g. Claude Code, Codex, Cursor) when to use it.
The more specific the better, including key terms that should trigger use (which can also be enumerated in triggers).
Skills without frontmatter will be silently skipped, so Townie/MCP will not be able to access them.
The Claude Platform Docs offer skill authoring best practices, including:
---
name: design
description: Use when styling a val's UI. Use for frontend vals that return JSX or HTML
triggers: [css, styling, layout, theme]
---
- Use `.css` files, avoid inline styles and Tailwind
- Locate React components in a `/components` directory, one component per file
- Use a sans-serif web-native font stack, no external fonts
- ...
A new skill can be created by remixing another user’s skill and customizing the SKILL.md file.
There is a remix button in the val.town UI, and a remix_val tool in the Val Town MCP server to do so.