investigating-incidents-with-aws-devops-agent

Run a deep root-cause investigation on the AWS DevOps Agent. Use when the user describes an incident, alarm, outage, or unexplained behavior — keywords like "5xx", "503", "OOM", "latency spike", "deployment failure", "rollback", "sev1", "investigate", "root cause", "debug", "alarm fired", "service down". Polls and streams progress, then surfaces recommendations.

Quality

84%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Quality

Content

77%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.

A well-structured, actionable runbook: the core investigation loop is fully specified with edge-case recovery and a security gate, and the writing is mostly lean. The main defect is the dangling REFERENCE.md link — the one progressive-disclosure hook points at a nonexistent file — plus a small gap in the fallback path (executionId provenance) and a few trimmable motivational lines.

Suggestions

Create REFERENCE.md (or remove the link) — the body's only external reference is broken since no such file exists in the bundle; either move the journal record-type table, polling cadence, and edge-case/error-recovery details into it or drop the pointer.

In the fallback path, state where the executionId comes from (e.g., that get-backlog-task's response includes it) before using it in list-journal-records, so the fallback is executable end-to-end.

Trim motivational phrasing such as "This is the killer feature — the DevOps Agent knows your AWS cloud; you know the user's local workspace" to tighten token efficiency.

Dimension	Reasoning	Score
Conciseness	The body is efficient — compact code blocks, a useful record-type mapping, and tight edge-case bullets — but contains minor trimmable flourishes such as "This is the killer feature — the DevOps Agent knows your AWS cloud; you know the user's local workspace" and a motivational tone in the polling section. Fits 'efficient; minor instances of over-explanation' rather than the every-token-earns-its-place anchor 5.	4 / 5
Actionability	Concrete, near copy-paste-ready tool calls with parameters and expected responses, exact fallback CLI commands, and a fully-specified polling cadence. Not a 5 because the fallback path invokes "list-journal-records --execution-id EXEC_ID" without ever explaining where the executionId comes from, and the AgentSpace routing precondition is left conditional without a resolution path.	4 / 5
Workflow Clarity	Clear sequence (pre-flight → start → poll loop of check status / fetch new records / summarize → completion) with explicit checkpoints: 30–45s cadence, incremental next_token fetching, a 10-minute stall check, stuck/FAILED/empty-journal recovery guidance, and an explicit user-approval gate before acting on recommendations. This matches the anchor's 'explicit validation steps; feedback loops for error recovery'.	5 / 5
Progressive Disclosure	Section structure is good, but the body's single external reference — "See [REFERENCE.md](REFERENCE.md) for polling cadence, journal record types, and error recovery" — points to a file that does not exist in the bundle (no references/, scripts/, or assets/ directories are present), so the link is broken. Additionally, the material the reference would cover (record types, cadence, error recovery) is largely inlined in SKILL.md anyway, so the split is unrealized. Fits 'references present but not effectively organized' rather than the well-placed anchor 4.	3 / 5
	Total	16 / 20 Passed

Description

91%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 that clearly states what the skill does and when to use it, with an unusually rich set of natural incident keywords. Third-person voice is used correctly. The only weaknesses are minor: slightly generic trigger terms ("debug", "investigate") that could collide with general debugging skills, and action coverage that could name one more capability.

Dimension	Reasoning	Score
Specificity	Lists three concrete actions — "Run a deep root-cause investigation", "Polls and streams progress", "surfaces recommendations" — which matches the 'several specific actions; minor gaps' anchor. Not a 5 because coverage of the workflow (e.g., fetching findings/recommendations detail, fallback paths) is not comprehensive.	4 / 5
Completeness	Explicitly answers both what ("Run a deep root-cause investigation on the AWS DevOps Agent... Polls and streams progress, then surfaces recommendations") and when ("Use when the user describes an incident, alarm, outage, or unexplained behavior") with concrete trigger phrases. Matches the anchor-5 example structure exactly.	5 / 5
Trigger Term Quality	Comprehensive natural keyword coverage including synonyms and specific error codes: "5xx", "503", "OOM", "latency spike", "deployment failure", "rollback", "sev1", "investigate", "root cause", "debug", "alarm fired", "service down", plus "incident, alarm, outage, unexplained behavior". These are exactly the phrases a user would say during an incident.	5 / 5
Distinctiveness Conflict Risk	Clear niche (AWS incident investigation via the DevOps Agent) with mostly distinct triggers, but generic terms like "debug", "investigate", and "root cause" could overlap with general debugging/troubleshooting skills. Fits 'mostly distinct; minor overlap risk' rather than the minimal-conflict anchor 5.	4 / 5
	Total	18 / 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
relative_links	Relative link issues: 1 missing	Warning

	Total	15 / 16 Passed

Repository: aws/agent-toolkit-for-aws
Path: plugins/aws-agents-for-devsecops/skills/investigating-incidents-with-aws-devops-agent/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.