# DevOps Agent Skill Quality Guide

Use this reference when designing or reviewing AWS DevOps Agent skills, learned skills, incident investigation workflows, tool-use best practices, frontmatter descriptions, and operational output contracts.

## What people get wrong

The lazy story is:

> A good skill is a detailed runbook pasted into SKILL.md.

Wrong. A useful DevOps Agent skill triggers correctly, loads progressively, constrains tool use, separates evidence from inference, and has deterministic evaluation criteria.

Common bad assumptions:

- More instructions mean better behavior.
- Broad descriptions improve triggering.
- Learned skills can safely encode environment-specific secrets or account details.
- Tool guidance is safe if it says “read-only” once.
- RCA/mitigation/evaluation can live in one vague workflow.
- A skill is done without tests or example failure cases.

## Skill-design failure modes

- Frontmatter description is too broad and steals unrelated tasks.
- SKILL.md bloats with reference material instead of progressive disclosure.
- Tool instructions allow mutation without approval gates.
- Incident workflow claims root cause from weak evidence.
- Learned skill contains internal role names, customer identifiers, account IDs, or secret-bearing commands.
- Output contract lacks verdict, evidence level, blockers, safe next actions, and open questions.

## Minimum safe workflow

1. Define target agent type, use cases, non-use cases, and trigger boundaries.
2. Keep SKILL.md lean: purpose, when to use, operating rules, references, and response minimum.
3. Move domain depth into references with failure modes, workflow, verification targets, and pushback criteria.
4. Specify allowed tools and mutation boundaries; require approval for live changes.
5. Add eval criteria before editing: trigger fit, safety gates, source grounding, output contract, and no internal identifiers.
6. Validate schema, manifests, links, and examples.
7. Document what evidence the skill can and cannot prove.

## Verification targets

- AWS DevOps Agent skill structure, SKILL.md frontmatter, references, and packaging constraints
- trigger description clarity, anti-triggers, role targeting, and allowed tools
- learned-skill content for topology, tool patterns, automatic updates, activation/deactivation implications
- safety checklist, source grounding, live evidence labels, mutation gates, and final response contract
- eval files, deterministic graders, schema validation, manifest validation, and no-secret/no-internal-identifier scans
- example incident or workflow prompts that prove the skill triggers only where intended

## When to push back

Push back if the user asks to:

- paste a giant runbook into SKILL.md
- include account IDs, internal role names, tokens, or environment-specific secrets
- make a skill trigger for every AWS problem
- allow remediation tools without approval and rollback rules
- skip evals because the skill “reads well”
- mix unrelated domains into one agent skill for convenience

# Official sources

Use this reference only when you need source grounding for AWS service behavior or the detailed source list.

## AWS documentation

Use these as starting points, not as proof of the user's live AWS state:
- https://docs.aws.amazon.com/devopsagent/latest/userguide/working-with-devops-agent-proactive-incident-prevention.html
- https://docs.aws.amazon.com/devops-guru/latest/userguide/monitoring-cloudwatch.html
- https://docs.aws.amazon.com/devopsagent/latest/userguide/about-aws-devops-agent.html
- https://docs.aws.amazon.com/wellarchitected/latest/operational-excellence-pillar/welcome.html

## Grounding rule

Official documentation explains AWS service behavior. It does not prove the user's current account, Region, quota, resource configuration, IAM boundary, pricing, entitlement, or operational state. Prefer read-only AWS MCP or CLI evidence, repository evidence, or sanitized user-provided evidence for current-state claims.

## Current MCP/documentation refresh (2026-06-02)

Service facts from official docs:
- AWS DevOps Agent proactive incident prevention analyzes incident patterns, ranks improvements, and can generate agent-ready specifications.
- DevOps Guru monitoring guidance exposes insight and usage metrics through CloudWatch; those metrics are evidence inputs for operational skill design, not proof that a skill is effective.

Sampled live evidence:
- Read-only regional availability sampling reported `DevOps Guru+DescribeInsight` and `DevOps Guru+ListInsights` as `isAvailableIn` in `us-east-1`, `us-west-2`, `eu-west-1`, and `ap-southeast-1`.

Review implications:
- Skill design must define trigger boundaries, evidence collection steps, output contracts, and evaluation criteria; vague incident prose is not enough.
- Treat DevOps Agent recommendations as candidates that need owner approval, validation, rollback planning, and eval coverage before implementation.

# Safety checklist

Use this reference before privileged, destructive, traffic-changing, cost-changing, compliance-impacting, or production-impacting recommendations.

## Non-negotiables

- Never ask users to paste secrets, access keys, session tokens, private keys, customer identifiers, or sensitive account data into chat.
- Use read-only AWS MCP or read-only AWS CLI evidence for live state when available; otherwise use repository evidence, sanitized user evidence, or official documentation and label the evidence level.
- Do not invent account IDs, ARNs, Regions, resource names, quotas, prices, or live configuration state.
- Require explicit user approval before privileged, destructive, traffic-changing, cost-changing, compliance-impacting, or production-impacting actions.
- Use current official AWS documentation for service behavior when the answer depends on AWS service details.
- Keep remediation least-privilege, reversible, and scoped to the requested workload or account boundary.

## Stress checks

- What can expose data?
- What can escalate privilege?
- What can break production or block rollback?
- What can create unbounded cost?
- What compliance or audit evidence is missing?
- What rollback or validation path is unproven?

## Evidence labels

Use `live evidence`, `repo evidence`, `user-provided evidence`, `documentation-based`, or `inference`. Documentation alone never proves the user's live AWS state.

# Workflow and output contract

Use this reference only when performing the full review, implementation guidance, incident triage, or production-readiness pass.

## Review domains

Check these areas before giving a verdict:
- Skill scope, trigger scenarios, agent type targeting, evidence sources, tools/MCPs, and reference materials
- Investigation sequence, decision tree, expected outputs, success criteria, and failure/timeout handling
- Learned-skill patterns: Agent Space understanding, tool-use best practices, common errors, and parameter guidance
- Safety: least privilege, no secrets, prompt injection concerns, source grounding, compliance, and eval plan

## Safe workflow

1. **Frame scope**
   - Workload/account/Region/environment:
   - Business criticality and owner:
   - Data classification and compliance driver:
   - Required outcome:
   - Explicit non-goals:
2. **Collect evidence**
   - Prefer read-only AWS MCP or read-only AWS CLI evidence for current-state claims when available.
   - Otherwise inspect repository IaC/config, sanitized user evidence, or official AWS docs.
   - Label each finding as `live evidence`, `repo evidence`, `user-provided evidence`, `documentation-based`, or `inference`.
3. **Stress-test risk**
   - What can expose data?
   - What can escalate privilege?
   - What can break production or block rollback?
   - What can create unbounded cost?
   - What evidence is missing?
4. **Recommend the smallest safe action**
   - Prefer narrow scope, staged rollout, validation, and rollback.
   - If the safest action is to stop and gather evidence, say that plainly.

## Output contract

Return this structure:
```markdown
# AWS DevOps Agent Skill Designer: <scope>
## Executive verdict
- Status: READY / READY WITH RISKS / NOT READY / NEEDS EVIDENCE
- Biggest risk:
- Evidence level:
## Scope and assumptions
- Confirmed:
- Unknown:
- Out of scope:
## Findings
| Severity | Finding | Evidence | Why it matters | Minimum safe action |
|---|---|---|---|---|
## Recommended actions
1. <action> — owner: <owner>, validation: <check>, rollback: <rollback>
## Validation
- Commands or checks:
- Expected result:
## Residual risk
- <risk or explicit none>
```