Content
82%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.
The content is a strong, actionable conversion reference: executable YAML and SDK examples, complete mapping tables, and a sequenced checklist with several built-in validation notes. The main improvement opportunities are trimming a handful of explanatory asides and splitting the lookup tables into a referenced file so SKILL.md reads more like an overview.
Suggestions
Move the four resource-mapping tables (~50 lines) into a references/resource-mapping.md file and reference it from a short 'How to map resource types' pointer, keeping SKILL.md as a lean overview.
Tighten the wordy asides (e.g., the connection-name retrieval paragraph and the 'This mirrors how Dagster swaps resources' sentence) to direct instructions.
Add an explicit validate-and-recover step to the setup checklist (e.g., after creating a connection, verify it by listing connections and confirming the descriptive_name_NNNNN id and credential-store read succeeded before replacing placeholders).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with Orchestra-specific, non-obvious facts (5-digit suffix semantics, the <INTEGRATION>__<CONNECTION_ID>__<FIELD> naming scheme, credential-store read behavior) and assumes Dagster/YAML knowledge, but a few passages could be trimmed ("Read it back rather than asking someone to find it: connections are managed through ... as well as the UI", "This mirrors how Dagster swaps resources per deployment/environment"). It is efficient with minor over-explanation, matching anchor 4 rather than 5 where every token would earn its place. | 4 / 5 |
Actionability | Guidance is copy-paste ready: complete YAML snippets (connection: my_snowflake_12345, ${{ ENV.SNOWFLAKE_CONN }}, inputs: blocks), full resource-to-connection mapping tables with key fields, an exact SDK call (orchestra.get_linked_connection("snowflake", connection_id="prod_12345")), a profiles.yml env_var snippet, and a concrete setup checklist. Not a 4 because no common case lacks executable detail; connection creation via API is delegated to a documented reference rather than left vague. | 5 / 5 |
Workflow Clarity | The "Connection Setup Checklist" gives a clear sequenced process and validation checkpoints appear inline ("Orchestra reads the secret when the connection is saved and rejects it if it can't be read or its keys don't match", "Check a variable exists rather than assuming it"), but there is no explicit validate-then-fix-then-retry loop for the overall migration. This matches anchor 4 (most checkpoints present, minor validation gaps) rather than 5 (explicit feedback loops). | 4 / 5 |
Progressive Disclosure | With no bundle files present, the single-file skill is well organized: clear section headers, scoped tables, a setup checklist, and a clearly listed References section of external docs. It falls short of anchor 5 because the ~211-line body carries large lookup tables (the resource-type mapping section) that would naturally split into a one-level-deep reference file in a progressively disclosed bundle. | 4 / 5 |
Total | 17 / 20 Passed |