Content
86%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A well-structured body: executable examples, exact tool names and endpoints, dual MCP/direct-API workflows, and an excellent reference bundle with task-based navigation. The main improvements are removing the triple-duplicated task mapping and adding failed-status handling to the polling workflow.
Suggestions
Collapse the overlapping "Tool Selection" table, "Quick Reference" table, and "Reference Files" list into a single task-to-tool/reference mapping to remove the repeated task rows.
Add one line to the workflow for the failed case, e.g. "If status is `failed`, inspect the error in the response and fix the prompt/config before regenerating", to close the error-recovery gap in polling.
In Best Practices, trim the editorializing ("The difference between mediocre and professional results depends entirely on prompt quality") to just the directive to always use the prompt optimizer.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly tables and terse directives with no concept explanations (assumes Claude knows what APIs and videos are), but the task-to-tool mapping is repeated across three sections — "Tool Selection", "Quick Reference", and "Reference Files" — so not every token earns its place. Not 3 because there is no unnecessary explanation or padding, only redundant re-listing. | 4 / 5 |
Actionability | The curl example is complete and copy-paste ready (auth header, JSON body, real endpoint), MCP tool names are exact (`mcp__heygen__generate_video_agent`, `mcp__heygen__get_video`), config parameters are named (duration_sec, orientation, avatar_id), and both the MCP and direct-API paths give concrete executable steps. The common cases are covered without pseudocode. | 5 / 5 |
Workflow Clarity | "Default Workflow" gives clear numbered sequences for both paths, with step 3 ("poll status and get the download URL") acting as a completion checkpoint. Not 5 because there is no error-recovery guidance — nothing says what to do when the poll returns a failed status or how to retry; not 3 because the sequence is explicit and polling is a stated checkpoint rather than an implicit one. | 4 / 5 |
Progressive Disclosure | SKILL.md is a lean overview and all nine referenced files exist as substantive documents (200-500 lines each) organized into "Core Workflow" vs "Foundation" groups with read-when guidance. The "Quick Reference" table maps each task to the exact reference chain to read, and cross-links between reference files are lateral one-level-deep, not pointer chains. | 5 / 5 |
Total | 18 / 20 Passed |