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.

feat: contract --json gains per-tool examples, parsed from SKILL.md's own table (#267)

Shogo Kajiyamaf2cb47434aac
diff --git a/docs/contract.md b/docs/contract.md
index a7fb5ca..70a6637 100644
--- a/docs/contract.md
+++ b/docs/contract.md
@@ -120,6 +120,7 @@ One entry per tool under `tools`, sorted by id. Tool ids are stable:
| Field | Meaning |
|---|---|
| `id`, `name`, `version`, `executable` | `ffmpeg-skill/cut`, `cut`, skill version, `scripts/cut.py` |
+| `examples[]` | `{prompts[], command}` (1.20.0): SKILL.md's own "User says" / "Do" table rows for this tool, machine-readable — `prompts` is the row's phrasing(s), `command` the row's `Do` text with the markdown backticks stripped. Every tool has at least one; parsed from SKILL.md at read time, so it never drifts from the table a person reads |
| `role` | `analysis`, `analysis_and_execution`, `execution` or `verification` (see below) |
| `capabilities.required` | ffmpeg components the tool always needs |
| `capabilities.optional[]` | `{capability, when}`: needed only for that flag or input |
diff --git a/scripts/_contract.py b/scripts/_contract.py
index 5d5244e..bc45caa 100644
--- a/scripts/_contract.py
+++ b/scripts/_contract.py
@@ -18,6 +18,7 @@ The contract has its own version (CONTRACT_VERSION) that only changes when the s
this document changes; the skill version comes from package.json.
"""
import argparse
+import functools
import importlib.util
import json
import os
@@ -462,6 +463,43 @@ def output_schema(name: str, meta: Dict[str, Any]) -> Dict[str, Any]:
required = ["status", "output", "dry_run", "commands"]
return {"type": "object", "properties": props, "required": required, "additionalProperties": True}
[email protected]_cache(maxsize=1)
+def skill_examples() -> Dict[str, List[Dict[str, Any]]]:
+ """1.20.0: per-tool `examples`, parsed from SKILL.md's "User says" / "Do" table -- the
+ same facts that table already states, machine-readable instead of prose-only. A row
+ naming more than one tool (e.g. metadata.py's --auto-chapters row also names render.py)
+ attaches to each; a row naming none (prose only, no backtick command) attaches to none.
+ `prompts` is a list because a row often gives several phrasings ("cut from 1:20 to 2:05",
+ "trim the first 10 s") for the one `command`; `command` has the markdown backticks
+ stripped but otherwise keeps the row's own text (including "or"/"then" alternatives).
+ """
+ examples: Dict[str, List[Dict[str, Any]]] = {}
+ try:
+ lines = (ROOT / "SKILL.md").read_text(encoding="utf-8").splitlines()
+ except OSError:
+ return examples
+ in_table = False
+ esc_pipe = "\x00" # a markdown-escaped "\|" (a literal pipe inside a cell, e.g. broll's --audio b\|mix) is not a column separator
+ for line in lines:
+ if line.startswith("| User says"):
+ in_table = True
+ continue
+ if not in_table:
+ continue
+ if not line.startswith("|"):
+ break
+ if line.startswith("|---") or line.startswith("|-----"):
+ continue
+ cells = line.strip().strip("|").replace("\\|", esc_pipe).split("|")
+ if len(cells) != 2:
+ continue
+ prompt_cell, do = (c.replace(esc_pipe, "|").strip() for c in cells)
+ prompts = re.findall(r'"([^"]+)"', prompt_cell) or [prompt_cell.strip('"')]
+ command = re.sub(r"`([^`]*)`", r"\1", do)
+ for tool in dict.fromkeys(re.findall(r"`([a-z][a-z0-9_]*)\.py", do)):
+ examples.setdefault(tool, []).append({"prompts": prompts, "command": command})
+ return examples
+
# ----------------------------------------------------------------------------- environment
def skill_version() -> str:
@@ -1012,6 +1050,8 @@ def tool_spec(name: str, version: str) -> Dict[str, Any]:
"version": version,
"description": (parser.description or "").strip().splitlines()[0] if parser.description else "",
"executable": f"scripts/{name}.py",
+ # 1.20.0: SKILL.md's own request-table rows for this tool, machine-readable
+ "examples": skill_examples().get(name, []),
"role": meta["role"],
"capabilities": {"required": list(meta["required"]), "optional": _merge_optional(meta["optional"], CODEC_CAPS if "codec" in schema["properties"] else [])},
"inputs": list(meta["inputs"]),
diff --git a/tests/test_contract.py b/tests/test_contract.py
index cbebfc6..5bd18f8 100644
--- a/tests/test_contract.py
+++ b/tests/test_contract.py
@@ -276,6 +276,32 @@ class ContractTests(unittest.TestCase):
self.assertTrue(re.fullmatch(r"[a-z]+", t["name"]), t["id"])
self.assertEqual(ids, sorted(ids), "tools are listed in a stable, sorted order")
+ def test_examples_are_parsed_from_skill_md_and_cover_every_tool(self):
+ """1.20.0: contract --json's per-tool `examples` field is SKILL.md's own request table
+ (the "User says" / "Do" rows), machine-readable -- not a hand-maintained second copy.
+ Every one of the 42 tools is named in that table somewhere, so every tool has at least
+ one example; a row's markdown backticks are stripped from `command`, and a row with
+ several quoted phrasings ("cut from 1:20 to 2:05", "trim the first 10 s") becomes a
+ `prompts` list rather than one string."""
+ by_name = {t["name"]: t for t in self.contract["tools"]}
+ missing = [name for name, t in by_name.items() if not t.get("examples")]
+ self.assertEqual(missing, [], "every tool should have at least one SKILL.md example")
+ cut = next(e for e in by_name["cut"]["examples"] if "cut from 1:20 to 2:05" in e["prompts"])
+ self.assertEqual(cut, {"prompts": ["cut from 1:20 to 2:05", "trim the first 10 s"],
+ "command": "cut.py input.mp4 --start 1:20 --end 2:05"})
+ for t in self.contract["tools"]:
+ for ex in t["examples"]:
+ self.assertEqual(set(ex), {"prompts", "command"})
+ self.assertIsInstance(ex["prompts"], list)
+ self.assertTrue(ex["prompts"])
+ self.assertNotIn("`", ex["command"], "markdown backticks should be stripped")
+ self.assertIn(f"{t['name']}.py", ex["command"])
+ # a markdown-escaped "\|" inside a cell (broll's --audio b\|mix) is a literal pipe,
+ # not a column separator -- confirms the escaping doesn't silently drop the row
+ broll = by_name["broll"]["examples"][0]
+ self.assertIn("b|mix", broll["command"])
+ self.assertIn("B-roll over this bit", broll["prompts"])
+
def test_provides_covers_every_tool_with_the_dotted_capability_id(self):
provides = self.contract["provides"]
ids = [p["id"] for p in provides]