# Skill Authoring

Author SKILL.md skills: frontmatter, validator limits, structure.

- Repository: https://github.com/mateaix/mateclaw (1176 stars)
- Category: Engineering
- License: Apache-2.0
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add mateaix/mateclaw --skill skill-authoring -g -a claude-code -y`
Codex: `npx skills add mateaix/mateclaw --skill skill-authoring -g -a codex -y`
Cursor: `npx skills add mateaix/mateclaw --skill skill-authoring -g -a cursor -y`
Gemini CLI: `npx skills add mateaix/mateclaw --skill skill-authoring -g -a gemini-cli -y`

## Description

Author SKILL.md skills: frontmatter, validator limits, structure.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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:

The rest: https://github.com/mateaix/mateclaw/blob/HEAD/mateclaw-server/src/main/resources/skills/skill-authoring/SKILL.md