Content
68%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-organized overview skill that is appropriately concise and gives concrete, executable scaffolding commands and security directives, while correctly deferring deep API detail to the installed packages' authoritative READMEs. The main gap is workflow clarity: the develop/deploy sequence is only implied and lacks any inline summary or validation checkpoints, and there is no minimal code example for the most common task (defining an API method with a Block).
Suggestions
Add a short inline 3-5 step development workflow (scaffold -> define ApiNamespace methods with Blocks -> npm run sandbox -> verify locally -> npm run deploy) with an explicit validation checkpoint before deploy, instead of delegating the whole workflow to the external README.
Include one minimal copy-paste example of defining an API method that uses a Building Block (e.g., a KVStore-backed method with requireAuth and a Zod schema), since that is the skill's most common task.
Trim redundancy: collapse the Overview prose and 'Key characteristics' bullets into one section, and merge the 'existing project' and 'Amplify Gen 2' subsections that show the identical command.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly lean: scaffolding commands are bare bash blocks, the templates table is dense reference material, and the security section is a compact actionable bullet list. Minor over-explanation remains — the Overview's prose ('AWS Blocks is an Infrastructure-from-Code framework where Building Blocks bundle CDK, SDK, and local mocks') partially repeats the 'Key characteristics' bullets, and the Amplify subsection restates the same command already shown for existing projects. | 4 / 5 |
Actionability | Mostly executable guidance: copy-paste-ready commands ('npx @aws-blocks/create-blocks-app my-app --template demo'), a concrete template table, and specific API directives ('await auth.requireAuth(context)', 'new AppSetting(scope, id, { secret: true })', 'crossDomain: true'). Not a 5 because the core development workflow is delegated wholesale to node_modules READMEs with no inline minimal example (e.g., defining an ApiNamespace method or wiring a Block), leaving a gap for the most common task. | 4 / 5 |
Workflow Clarity | Scaffolding steps are clear and sequenced, but the actual develop-then-deploy workflow is only implied ('Deploy ephemeral... with npm run sandbox and long-lived environments with npm run deploy') and the Development Workflow section defers to an external README without summarizing the sequence. There are no validation checkpoints (e.g., verifying a sandbox build or checking deployed stack status) before deploying, which per the rubric caps this dimension at 3. | 3 / 5 |
Progressive Disclosure | Good structure with well-organized sections and clearly signaled, one-level-deep pointers to authoritative external docs ('refer to node_modules/@aws-blocks/blocks/README.md', 'read its package README... e.g., node_modules/@aws-blocks/bb-kv-store/README.md') — no nested reference chains. Not a 5: the body runs ~85 lines with a fairly detailed inline Security Considerations section that could live in a reference file, and no bundle files of its own are provided. | 4 / 5 |
Total | 15 / 20 Passed |