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.
Python agent-skillsai-agentsaudio-processingcaptionsclaude-codecodexcoding-agentcursorffmpegloudness-normalizationmcpmcp-servermodel-context-protocolpythonsubtitlestranscodingvideovideo-editingvideo-processingwhisper
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.mdindex 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.pyindex 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 sthis document changes; the skill version comes from package.json."""import argparse+import functoolsimport importlib.utilimport jsonimport 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+# ----------------------------------------------------------------------------- environmentdef 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.pyindex 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]