skill-authoring

# 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: - Starts with `---` as the **first bytes** — no leading blank line, no BOM. - A closing `---` line follows, then the body. The body must be non-empty. - The block between the fences parses as a YAML mapping. - `name` is present — it is the upsert key. `BuiltinSkillSeedService` skips any SKILL.md with no `name`. - `description` is present — a single line. If the frontmatter regex fails to match, the parser treats the whole file as body with an empty `name`, and a builtin skill is silently skipped at seed time. A loadable skill ALWAYS has well-formed frontmatter. ## Size & Naming Limits - **Skill content:** ≤ 100,000 chars (`MAX_CONTENT_CHARS`, ~25k tokens) — enforced by `skill_manage` for custom skills. Builtin skills aren't hard-checked but should obey the same ceiling. - **Name:** must match `^[a-z0-9][a-z0-9._-]{0,63}$` — lowercase letters and digits plus `-` `_` `.`, starting with a letter or digit, ≤ 64 chars. `skill_manage` lowercases the name before validating. - **Description:** keep it to one line. Peer skills run 40-70 chars — a tight trigger phrase, not a paragraph. - **Peer skills** in `resources/skills/` sit at 6-15k chars. Aim for that range; past ~20k, split detail into `references/*.md`. ## Peer-Matched Frontmatter Every shipped skill follows this shape: ```yaml --- name: my-skill-name description: 'One line: what it does and when it fires.' version: 1.0.0 tags: - short - descriptive - tags author: ported --- ``` Fields `BuiltinSkillSeedService` projects onto the `mate_skill` row: | Field | Effect | Default if absent | |---|---|---| | `name` | upsert key, skill identity | — (required) | | `description` | shown in skill lists | empty | | `version` | `mate_skill.version` | `1.0.0` | | `icon` | emoji, or a `/skill-assets/...` path | `🛠️` | | `author` | attribution | `MateClaw` | | `tags` | YAML list or CSV string | skill name | | `nameZh` / `nameEn` | bilingual display names | none | | `optional: true` | seeds the skill **disabled** — user opts in from the Skills page | `false` (enabled) | | `dependencies.tools` | required tool ids → `config_json.requiredTools` | none | | `platforms` | e.g. `[linux, macos, windows]` | none | `version` / `author` / `tags` are not validator-enforced, but every peer carries them — omitting makes the skill look half-finished. Use `optional: true` for heavyweight skills (paid CLI dependencies, external OAuth, niche integrations) so they ship dark and the user activates them deliberately. ## Skill Structure Shipped skills follow roughly: ``` # <Title> ## Overview — one or two paragraphs: what and why. ## When to Use — bulleted triggers, plus a "Don't use for:" counter-trigger. ## <Topic sections> — quick-reference tables, exact commands, concrete recipes (mvn test, paths under mateclaw-server/, etc.). ## Common Pitfalls — numbered mistakes paired with their fixes. ## Verification Checklist — checkbox list of post-action checks. ``` Not every section is mandatory, but `Overview` + `When to Use` + an actionable body + `Common Pitfalls` is the minimum for the skill to read like a peer. ## Directory Placement ``` mateclaw-server/src/main/resources/skills/<skill-name>/SKILL.md ``` The `skills/` tree is **flat** — no category subdirectories. The seed glob `classpath*:skills/*/SKILL.md` matches exactly one level deep, so a skill nested under a category directory would never be scanned. The directory name SHOULD equal the frontmatter `name`. Supporting files go in `references/` and `scripts/` subdirectories (see below). ## Builtin Workflow (in-repo) 1. **Survey peers:** `ls mateclaw-server/src/main/resources/skills/` and read 2-3 SKILL.md files close to your topic — match tone and structure. 2. **Create** `skills/<name>/SKILL.md` with the file tools. 3. **Validate** that the frontmatter parses — see the checklist below. 4. **Restart the server.** `BuiltinSkillSeedService` seeds the new row only at startup; a running server will not see it. The service also skips re-seeding when no SKILL.md's size/mtime changed, so rebuilding the JAR is what makes a change land. 5. **Commit** the new `skills/<name>/` directory. No SQL seed change is needed — the SKILL.md is the source of truth and obsoletes per-skill `INSERT INTO mate_skill`. ## Custom Workflow (skill_manage) Agents and users create runtime skills with the `skill_manage` tool — actions `create | edit | patch | delete`: - `create` — a new skill from full SKILL.md content. Rejects a duplicate name. - `edit` — a full-content rewrite of a custom skill. - `patch` — find-and-replace one section (`oldText` → `newText`). - `delete` — uninstall (logical delete plus workspace archive). Notes: - Every write is **security-scanned** (`SkillSecurityService`) before saving — dangerous patterns are rejected with the reason. Builtin SKILL.md files are NOT scanned; they are trusted committed source. - `edit` / `patch` / `delete` **refuse builtin skills** ("cannot edit builtin skill"). To change a builtin skill, edit the resource file and restart. - A custom skill is live immediately — the tool re-runs the resolver pipeline — so no restart is needed. ## Supporting Files Beyond `SKILL.md`, a skill directory may carry: - `references/*.md` — long-form material the body links to. Use this to keep SKILL.md under ~20k chars. - `scripts/*` — executable helpers a skill invokes. - `templates/`, `assets/` — used by some bundled skills (HTML templates, images, etc.). `SkillFileAccessPolicy` only resolves runtime paths under `references/` and `scripts/`, and rejects `..` traversal or absolute paths — keep runtime-read files in those two directories. ## Common Pitfalls 1. **Leading whitespace before `---`.** The frontmatter regex anchors on `^---`; a blank line or BOM makes the whole file parse as body with an empty `name`, and a builtin skill is silently skipped. 2. **Expecting a running server to see a new builtin skill.** `BuiltinSkillSeedService` seeds only at startup. Restart — or, for a quick iteration, create a custom skill via `skill_manage`, which is live immediately. 3. **Trying to `skill_manage edit` a builtin skill.** It is refused. Builtin skills are committed source — edit the file and restart. 4. **Adding an `INSERT INTO mate_skill` for a new builtin skill.** Unnecessary and discouraged — the SKILL.md is the source of truth and the seed service upserts by `name`. 5. **Generic description.** "Debug things" is weak. A peer description names the *trigger* — "4-phase root cause debugging: understand bugs before fixing." beats "Debug things." 6. **Naming an external project or internal RFC in the skill body.** Describe the function objectively. Shipped content states *what* it does, not where the idea came from — `author: ported` is the neutral attribution for an adapted skill. 7. **Skill content over 100k chars.** `skill_manage` rejects it outright; split detail into `references/`. 8. **Mismatched directory and `name`.** The upsert keys on the frontmatter `name`, but a directory that disagrees confuses everyone reading the tree. Keep them equal. ## Verification Checklist - [ ] File at `mateclaw-server/src/main/resources/skills/<name>/SKILL.md` (builtin); the directory name equals the frontmatter `name` - [ ] Frontmatter starts at byte 0 with `---`, closes with a `---` line, and the body is non-empty - [ ] `name` matches `^[a-z0-9][a-z0-9._-]{0,63}$`; `description` is a single line - [ ] `version`, `tags`, `author` present (peer-matched shape) - [ ] Total file ≤ 100,000 chars (aim 6-15k; split into `references/` past ~20k) - [ ] Structure: `# Title` → `## Overview` → `## When to Use` → actionable body → `## Common Pitfalls` → `## Verification Checklist` - [ ] No external project names or RFC numbers in the body - [ ] Builtin: server restarted so `BuiltinSkillSeedService` seeds the row; the new `skills/<name>/` directory is committed - [ ] Custom: created via `skill_manage`, security scan reported PASSED