Skip to content

Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.

fix: quote SKILL.md's description so the frontmatter is valid strict YAML (#161)

Shogo Kajiyamad97bebe664dc
diff --git a/SKILL.md b/SKILL.md
index 58d9150..8fba2e3 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -1,6 +1,6 @@
---
name: ffmpeg-skill
-description: Edit video and audio with local FFmpeg from natural-language requests: cut, trim, join, resize/reframe (9:16, 1:1), speed change, captions and subtitles (SRT/ASS, animated, karaoke), logos and text overlays, lower-thirds and titles, silence removal, multicam and external-mic sync, loudness normalisation, HDR/Dolby Vision to SDR, LUTs, background music with ducking, platform exports (YouTube, Reels, TikTok, X), compliance checks, scene detection and highlight reels, contact sheets to inspect results, and whole-edit project files. Use this skill whenever the user mentions a video or audio file (mp4, mov, mkv, wav, m4a), footage, a clip, captions, subtitles, a reel or short, YouTube/Instagram/TikTok delivery, LUFS, sync, transcoding, ffmpeg, or asks to make something "60 seconds", "vertical", "louder", "captioned" — even when they do not say "edit". Python 3.9 standard library only, no cloud, no API keys.
+description: 'Edit video and audio with local FFmpeg from natural-language requests: cut, trim, join, resize/reframe (9:16, 1:1), speed change, captions and subtitles (SRT/ASS, animated, karaoke), logos and text overlays, lower-thirds and titles, silence removal, multicam and external-mic sync, loudness normalisation, HDR/Dolby Vision to SDR, LUTs, background music with ducking, platform exports (YouTube, Reels, TikTok, X), compliance checks, scene detection and highlight reels, contact sheets to inspect results, and whole-edit project files. Use this skill whenever the user mentions a video or audio file (mp4, mov, mkv, wav, m4a), footage, a clip, captions, subtitles, a reel or short, YouTube/Instagram/TikTok delivery, LUFS, sync, transcoding, ffmpeg, or asks to make something "60 seconds", "vertical", "louder", "captioned" — even when they do not say "edit". Python 3.9 standard library only, no cloud, no API keys.'
---
# ffmpeg-skill
diff --git a/scripts/_contract.py b/scripts/_contract.py
index 69f9eaf..79008d3 100644
--- a/scripts/_contract.py
+++ b/scripts/_contract.py
@@ -421,7 +421,14 @@ def skill_description() -> str:
try:
text = (ROOT / "SKILL.md").read_text(encoding="utf-8")
m = re.search(r"^description:\s*(.+)$", text, re.M)
- return m.group(1).strip() if m else ""
+ value = m.group(1).strip() if m else ""
+ # The scalar is single-quoted in SKILL.md: unquoted, the ": " inside the text ("...
+ # requests: cut, trim ...") is a new mapping key to a strict YAML parser and the whole
+ # frontmatter fails to load (GitHub's renderer reported it; npx skills add and Claude
+ # Code's loader parse it strictly). '' is the only escape inside a YAML single-quoted scalar.
+ if len(value) >= 2 and value[0] == value[-1] == "'":
+ value = value[1:-1].replace("''", "'")
+ return value
except OSError:
return ""
diff --git a/tests/test_contract.py b/tests/test_contract.py
index 078f66c..e695493 100644
--- a/tests/test_contract.py
+++ b/tests/test_contract.py
@@ -721,6 +721,29 @@ class ContractTests(unittest.TestCase):
self.assertGreaterEqual(major, 5, "the real ffmpeg on PATH must parse to a sane version")
self.assertIn(_common.drawtext_boxborderw(9, 16), ("16", "9|16"))
+ def test_skill_frontmatter_is_strict_yaml(self):
+ """The description used to be an unquoted scalar containing ": " ("...natural-language
+ requests: cut, trim, ..."), which a strict YAML parser reads as a second mapping key and
+ rejects ("mapping values are not allowed here", line 3 column 83) -- GitHub's own renderer
+ flagged it, and any installer that parses the frontmatter strictly would lose the one
+ field agents discover the skill by. Pinned without PyYAML: every frontmatter line must be
+ `key: value` where a value containing ": " or starting with a YAML indicator is quoted,
+ and the quoted description must round-trip through the contract's reader."""
+ text = (ROOT / "SKILL.md").read_text(encoding="utf-8")
+ fm = text.split("---\n", 2)[1].rstrip("\n").split("\n")
+ for line in fm:
+ key, sep, value = line.partition(": ")
+ self.assertTrue(sep and re.fullmatch(r"[a-z_-]+", key), line)
+ quoted = len(value) >= 2 and value[0] == value[-1] and value[0] in "'\""
+ if ": " in value or value[:1] in "[{&*!|>%@`#":
+ self.assertTrue(quoted, f"{key}: needs quoting for a strict YAML parser: {value[:60]}")
+ if quoted and value[0] == "'":
+ self.assertNotRegex(value[1:-1], r"(?<!')'(?!')", f"{key}: a lone ' inside a single-quoted scalar")
+ desc = _contract.skill_description()
+ self.assertTrue(desc.startswith("Edit video and audio"), desc[:40])
+ self.assertNotIn("'", desc[:1] + desc[-1:], "the contract must expose the unquoted text")
+ self.assertEqual(desc, self.contract["skill"]["description"])
+
def test_bt709_tags_go_through_encoder_vui_from_ffmpeg_7_1(self):
"""FFmpeg 7.1 added colourspace negotiation to libavfilter and feeds the output options
-colorspace/-color_primaries/-color_trc into the graph's constraints: on a source with