From 66aeef8cba8394c077366efed022ad19236b1d5a Mon Sep 17 00:00:00 2001 From: Pete Millspaugh <73900714+pmillspaugh@users.noreply.github.com> Date: Wed, 1 Jul 2026 12:32:26 -0400 Subject: [PATCH 1/3] Create skill for creating skills --- plugin/skills/create-skill/SKILL.md | 37 +++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 plugin/skills/create-skill/SKILL.md diff --git a/plugin/skills/create-skill/SKILL.md b/plugin/skills/create-skill/SKILL.md new file mode 100644 index 0000000..9e092ab --- /dev/null +++ b/plugin/skills/create-skill/SKILL.md @@ -0,0 +1,37 @@ +--- +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. +--- + +In any val, a user can create a `/skills//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. +Any agent can make use of Val Town skills to write idiomatic vals and respect user preferences. +A user may chose to centralize their skills in one val or co-locate skills across multiple vals. + +## Frontmatter + +A skill markdown file must have frontmatter: + +1. `name`: typically matches the subdir name slug +2. `description`: helps the agent decide when the skill is relevant +3. `triggers`: (optional) is a list of keywords to tip off the agent + +The `description` and `trigger` 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. + +## Best practices + +The [Claude Platform Docs](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) offer skill authoring best practices, including: + +- Be concise. The context window is a public good +- Always write in third person +- Default assumption: AI agents are already very smart +- Be as specific as possible (e.g. code is better than plain english where possible) +- Improve skills based on usage and testing + +## Remixing skills + +To adopt another user’s skills, a user or AI agent can remix the val and customize 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. +It is trivially easy to remix a skill, and customizing skills is powerful because they can be personalized based on a user's specific knowledge and preferences. From 8b949633f7c9e2099782db09751c6091399804db Mon Sep 17 00:00:00 2001 From: Pete Millspaugh <73900714+pmillspaugh@users.noreply.github.com> Date: Wed, 1 Jul 2026 12:41:49 -0400 Subject: [PATCH 2/3] Add example, triggers, and one-line intro --- plugin/skills/create-skill/SKILL.md | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/plugin/skills/create-skill/SKILL.md b/plugin/skills/create-skill/SKILL.md index 9e092ab..9a84417 100644 --- a/plugin/skills/create-skill/SKILL.md +++ b/plugin/skills/create-skill/SKILL.md @@ -1,20 +1,22 @@ --- 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//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. -Any agent can make use of Val Town skills to write idiomatic vals and respect user preferences. -A user may chose to centralize their skills in one val or co-locate skills across multiple vals. +A user may choose to centralize their skills in one val or co-locate skills across multiple vals. ## Frontmatter A skill markdown file must have frontmatter: -1. `name`: typically matches the subdir name slug -2. `description`: helps the agent decide when the skill is relevant -3. `triggers`: (optional) is a list of keywords to tip off the agent +- `name`: typically matches the subdir name slug +- `description`: helps the agent decide when the skill is relevant. **A good skill description is critical for agent discovery** +- `triggers`: (optional) is a list of keywords to tip off the agent The `description` and `trigger` 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`). @@ -30,6 +32,21 @@ The [Claude Platform Docs](https://platform.claude.com/docs/en/agents-and-tools/ - Be as specific as possible (e.g. code is better than plain english where possible) - Improve skills based on usage and testing +## Example + +```md +--- +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 modules, not inline styles or Tailwind +- Locate React components in a `/components` directory, one component per file +- Use a sans-serif web-native font stack, no external fonts +- ... +``` + ## Remixing skills To adopt another user’s skills, a user or AI agent can remix the val and customize the `SKILL.md` file. From 1ffb961433aa8998b63dd8ee700139530f8b1635 Mon Sep 17 00:00:00 2001 From: Pete Millspaugh <73900714+pmillspaugh@users.noreply.github.com> Date: Wed, 1 Jul 2026 14:05:03 -0400 Subject: [PATCH 3/3] Address comments --- plugin/skills/create-skill/SKILL.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/plugin/skills/create-skill/SKILL.md b/plugin/skills/create-skill/SKILL.md index 9a84417..db91c0b 100644 --- a/plugin/skills/create-skill/SKILL.md +++ b/plugin/skills/create-skill/SKILL.md @@ -14,11 +14,11 @@ A user may choose to centralize their skills in one val or co-locate skills acro A skill markdown file must have frontmatter: -- `name`: typically matches the subdir name slug +- `name`: kebab-case name of the skill; contains lowercase letters, numbers, and hyphens - `description`: helps the agent decide when the skill is relevant. **A good skill description is critical for agent discovery** - `triggers`: (optional) is a list of keywords to tip off the agent -The `description` and `trigger` fields enable skill discovery, i.e. tells the user's AI agent (e.g. Claude Code, Codex, Cursor) when to use it. +The `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. @@ -41,14 +41,13 @@ description: Use when styling a val's UI. Use for frontend vals that return JSX triggers: [css, styling, layout, theme] --- -- Use CSS modules, not inline styles or Tailwind +- 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 - ... ``` -## Remixing skills +## Remixing -To adopt another user’s skills, a user or AI agent can remix the val and customize 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. -It is trivially easy to remix a skill, and customizing skills is powerful because they can be personalized based on a user's specific knowledge and preferences. +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.