Authoring Skills

You can author skills two ways: in the Wato UI, or programmatically over MCP. Both produce the same thing — a SKILL.md (and optional bundled files) saved as a draft you can then submit and publish.

Writing a good SKILL.md

A skill is frontmatter plus a Markdown body:

---
name: debug-connector
description: Use when diagnosing a failing MCP connector — auth errors, empty tool lists, or timeouts.
---

# Debug a connector

1. Confirm the connector is installed and approved for the team.
2. Run `mesh_search_tools` to check the tool is visible.
3. Inspect a recent trace to see the exact error.

• name — the slug: lowercase, alphanumeric with hyphens, up to 64 characters.
• description — the trigger. Write it as when to use this ("Use when…"), because that's what an agent matches against.
• Keep the body actionable: numbered steps, concrete tool names, and any guardrails.

In the UI

Go to Teams → [Team] → Setup → Skills.

• New skill — opens the editor: enter the name, description, the SKILL.md body, any bundled files, and optional required connectors/permissions. Saving creates a draft.
• Edit a skill — opens the same editor on the current version. Editing a published skill saves a new draft version (the published version keeps serving agents until you publish again).

The editor also has Submit for review and, with the right access, Publish — see Lifecycle.

Over MCP

Use wato_save_skill_draft with the full SKILL.md Markdown. The skill is matched to an existing one by id, slug, or the frontmatter name; if none matches, a new draft is created.

wato_save_skill_draft({
  "content": "---\nname: debug-connector\ndescription: Use when diagnosing a failing MCP connector.\n---\n\n# Debug a connector\n\n1. ...",
  "files": [
    { "path": "scripts/check.sh", "content": "#!/bin/bash\n..." }
  ],
  "submitForReview": false
})

Next