creating-api-gateway-stage

Creates an API Gateway stage with CloudWatch logging, X-Ray tracing, throttling, WAF integration, and IAM roles following AWS best practices. Use when deploying a REST API to different environments such as dev, test, or production.

Quality

85%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

78%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

An exemplarily lean, well-structured skill body with excellent progressive disclosure and a single clear workflow pointer. The weakest area is actionability of the in-body troubleshooting guidance, which names what to check but not how to check it.

Suggestions

Add one concrete command or resource-name pattern per troubleshooting entry (e.g., the CloudWatch log group naming convention `API-Gateway-Execution-Logs_{rest_api_id}/{stage_name}` or the `aws apigateway get-account` check for `cloudwatchRoleArn`) so recovery is executable without opening the reference.

Include a one-line prerequisites note in the body (rest_api_id, deployment_id, stage_name) so required inputs are visible before diving into the procedure.

Link the 'Stage creation fails' and 'WAF blocking legitimate requests' troubleshooting subsections to the relevant sections of the reference procedure for faster navigation.

Dimension	Reasoning	Score
Conciseness	The body is lean and assumes competence: a 4-line overview, a two-line pointer to the procedure, and terse troubleshooting entries ("Check REST API ID, deployment ID, IAM permissions, and stage naming conventions") with zero padding or explanation of concepts Claude already knows. This matches the 'every token earns its place' anchor; it does not fall to score 4 because there is no over-explanation to trim.	5 / 5
Actionability	The create section fully delegates to the referenced procedure (appropriate), but the troubleshooting entries are high-level hints with no commands ("Verify the CloudWatch role permissions, log group existence") — direction without the specific CLI calls or log-group naming to execute. This sits between 'minimal concrete guidance' (2) and 'mostly executable' (4); the executable detail all lives in the reference file rather than the body.	3 / 5
Workflow Clarity	The workflow is clearly signaled ("follow the procedure exactly. See [API Gateway stage creation procedure](references/create-api-gateway-stage.md)"), and the referenced procedure contains validation checkpoints (verify dependencies, validate REST API/deployment existence, stop on failure), with the body's troubleshooting section covering error recovery. Minor gap: the body itself surfaces no validation steps, keeping it below the explicit-checkpoints-in-place anchor of 5.	4 / 5
Progressive Disclosure	The SKILL.md is a clean overview pointing to one real, well-signaled, one-level-deep reference (references/create-api-gateway-stage.md, verified to exist as a 14KB detailed SOP); no nested references and no content inlined that belongs in a separate file. This matches the top anchor exactly.	5 / 5
	Total	17 / 20 Passed

Description

92%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description: third-person voice, specific capability list, and an explicit 'Use when' trigger clause naming environments. The only minor improvement area is broader trigger-term synonym coverage.

Dimension	Reasoning	Score
Specificity	The description lists multiple concrete actions — "Creates an API Gateway stage with CloudWatch logging, X-Ray tracing, throttling, WAF integration, and IAM roles" — giving comprehensive coverage of the skill's capabilities. This matches the anchor for multiple specific concrete actions; it is not score 4 because there are no noticeable coverage gaps within the stage-creation domain.	5 / 5
Completeness	It explicitly answers both questions: what ("Creates an API Gateway stage with CloudWatch logging, X-Ray tracing, throttling, WAF integration, and IAM roles") and when ("Use when deploying a REST API to different environments such as dev, test, or production"). The explicit 'Use when' clause with concrete environment triggers matches the top anchor; score 4 would require the 'when' to be less specific.	5 / 5
Trigger Term Quality	Natural phrases users would say are present: "deploying a REST API", "API Gateway", "dev, test, or production" environments. A few common variations are missing (e.g., "endpoint", "deploy to prod", "stage deployment"), which fits the 'good keyword coverage; a few natural terms missing' anchor rather than the comprehensive synonym coverage of score 5.	4 / 5
Distinctiveness Conflict Risk	"API Gateway stage" with CloudWatch/X-Ray/WAF specifics carves out a clear AWS niche with distinct triggers, unlikely to collide with general deployment or infrastructure skills. It is clearly above the 'minor overlap risk with closely related skills' anchor of score 4.	5 / 5
	Total	19 / 20 Passed

Validation

93%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: aws/agent-toolkit-for-aws
Path: skills/specialized-skills/serverless-skills/creating-api-gateway-stage/SKILL.md
Commit: b8171ad

Reviewed: 5 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.