Skip to content
Docs | Val Town

Agent instructions

AGENTS.md

Section titled “AGENTS.md”

Townie and our MCP server support the AGENTS.md convention (learn more) for providing instructions and preferences to your agent. We support AGENTS.md:

  1. Per user
  2. Per org
  3. Per val

Below we’ll walk through how to create and agent instructions, and how Townie and other agents reference them. You can also ask Townie or your agent to create their own instructions!

Per user

Section titled “Per user”

User-based agent instructions live in an AGENTS.md file within a <username>/.config val in your account. Visit val.town/settings/preferences > Agent Instructions to create this val, or create it manually. If you already have a .config val, settings will link to it.

Whenever you are chatting with Townie or another agent using our MCP server, your agent instructions will always be in context.

Per org

Section titled “Per org”

Org-based agent instructions live in an AGENTS.md file within a <org>/.config val in your org’s account. Visit val.town/orgs/ORG/settings/preferences > Agent Instructions to create this val, or create it manually. If your org already has a .config val, settings will link to it.

When you are chatting with Townie and your org’s val is attached as context, the agent instructions for that org will be available in context (in addition to your user-based instructions). When working with our MCP server, your agent will be instructed to read your org’s agent instructions, if they exist.

Per val

Section titled “Per val”

You can create an AGENTS.md file at the root of any val. Townie will automatically read those agent instructions if a val is attached as context. When working with our MCP server, your agent will be instructed to read your val’s agent instructions, if they exist, the same way it would read any other file.

Example

Section titled “Example”

Here’s what your personal agent instructions might look like.

I'm a software engineer with experience in React, TypeScript, HTML/CSS, Node, SQL, etc.


- I prefer vanilla CSS in `.css` files
- I prefer JSX over vanilla HTML
- I prefer Hono for routing
- Always work incrementally, writing code then running code piecemeal

Custom skills

Section titled “Custom skills”

The Val Town plugin ships with platform skills for things like using OAuth, SQLite, and blob storage. You can create your own custom skills that Townie and our MCP server will automatically pick up on and use in the appropriate scenario. Unlike agent instructions, which are always in context, skills are discoverable by agents only when relevant to the task at hand.

Creating a skill

Section titled “Creating a skill”

In any val:

  1. Create a skills/ directory

  2. Create a <name>/ subdir

  3. Create a SKILL.md file with name and description metadata, plus the skill itself

You may choose to centralize your skills in one val (like .config) or colocate skills across multiple vals. For example, you could expose a design skill in any val, like skills/design/SKILL.md:

---
name: design
description: Use when designing the UI/UX of a website or frontend tool. Use when writing CSS and making design decisions.
triggers: [CSS, design, frontend, website]
---


- Headings should be set in a sans serif typeface
- Body text should be set in a neutral, serif typeface

Frontmatter

Section titled “Frontmatter”
  • name: typically matches the subdir name slug
  • description: helps the agent decide when the skill is relevant
  • triggers: (optional) is a list of keywords to tip off the agent

The description field enables skill discovery, i.e. tells your agent when to use it. The more specific the better, including key terms that should trigger use (which you can also enumerate in triggers). Always write in third person. Read more tips on Claude’s docs.

Skills without frontmatter will be silently skipped, so Townie/MCP will not be able to access them.

Remixing skills

Section titled “Remixing skills”

To adopt another user’s skills, simply remix the val and customize the SKILL.md file. It is trivially easy to remix a skill into your account, and customizing skills is powerful because you can personalize them based on your specific knowledge and preferences.