Authoring MateClaw Skills

Overview

A skill is a SKILL.md file, YAML frontmatter plus a markdown body of reusable instructions. There are two places a SKILL.md can live, and they have different creation paths:

1. Builtin (in-repo): mateclaw-server/src/main/resources/skills/<name>/SKILL.md, committed, shipped inside the server JAR. On every startup BuiltinSkillSeedService scans classpath*:skills/*/SKILL.md, parses each frontmatter, and upserts a row into mate_skill keyed by name. The SKILL.md is the single source of truth, no SQL seed entry is required.
2. Custom (runtime): created by an agent or user through the skill_manage tool. Stored as a mate_skill row with skill_type=custom and exported to the workspace at ~/.mateclaw/skills/<name>/. Not committed; lives per-installation.

This skill covers both. Note that skill_manage does NOT write into the in-repo skills/ tree, builtin skills are authored by writing the file directly and restarting.

When to Use

• You're adding a reusable workflow that should ship with MateClaw → builtin.
• You're editing an existing builtin skill under mateclaw-server/src/main/resources/skills/.
• An agent finished a complex task and wants to persist the approach → custom, via skill_manage.
• You're reviewing a SKILL.md for correct frontmatter and structure.

Don't use for: recording a one-off tip discovered while using a skill (that belongs in record_lesson / a per-skill LESSONS.md) or cross-skill memory notes (remember). This skill is about writing the skill document itself.

Required Frontmatter

The frontmatter is parsed by SkillFrontmatterParser: a regex (^---\s*\n(.*?)\n---\s*\n(.*)$) splits the fenced block, then SnakeYAML loads it as a mapping. Hard requirements: