AWS Builder Center

Extend AWS DevOps Agent with custom skills for your operational workflows

AWS DevOps Agent Skills let you package your team's operational knowledge, including investigation procedures, troubleshooting patterns, and best practices, into modular, reusable instruction sets that the agent automatically applies during relevant investigations. This turns the agent from a general-purpose assistant into one that follows your specific workflows, reducing repetition and ensuring consistent incident response.

Service teams often develop deep institutional knowledge about their infrastructure: investigation procedures, escalation paths, and troubleshooting patterns that live in wikis, runbooks, or the heads of senior engineers. When an incident occurs, this knowledge is critical, but it's rarely available in a structured, actionable format at the moment it's needed most.
Today, we are announcing  AWS DevOps Agent Skills , a new capability that lets you extend AWS DevOps Agent with modular, reusable instruction sets tailored to your infrastructure and operational workflows. Skills transform AWS DevOps Agent from a general-purpose assistant into a specialist for your environment. One that knows your investigation procedures, understands your architecture patterns, and follows your team's best practices automatically.

What are skills

Skills are self-contained packages of instructions that provide specialized capabilities to AWS DevOps Agent. They follow a subset of the  Agent Skills specification , an open standard for packaging agent instructions and resources. Each skill contains a  SKILL.md  file with step-by-step procedures, decision trees, and reference materials that guide the agent during investigations. Skills can also include supplementary documents such as PDFs, images, and data files.
Unlike one-time instructions provided in a chat message, skills are reusable capabilities that load automatically when relevant to the task at hand. You create them once, and AWS DevOps Agent uses them across all relevant investigations. A skill can include:
  • Investigation workflows for specific scenarios or infrastructure types
  • Reference materials such as architecture patterns and operational procedures
  • Agent type targeting to control which agent types (On-demand, Incident Triage, Incident RCA, Incident Mitigation, or Evaluation) can use the skill

Why skills matter for your operations

Consider a common scenario: your team manages a fleet of Amazon RDS instances, and you've developed a well-tested procedure for diagnosing performance issues. Without skills, every time a database latency alarm fires, the on-call engineer must recall (or look up) the right sequence of checks: alarm status, connection metrics, slow queries, storage capacity. With a skill, AWS DevOps Agent follows that exact procedure automatically, checking each metric in the right order and surfacing findings in a structured summary.
Skills deliver four key benefits:
  1. Specialize your agent. Encode investigation procedures, best practices, and organizational knowledge specific to your infrastructure.
  1. Reduce repetition. Create investigation workflows once and have them applied automatically across all relevant investigations.
  1. Compose capabilities. Combine multiple skills to build end-to-end investigation workflows. For example, pair a skill that retrieves deployments from your CI/CD pipeline with one that searches your code repositories.
  1. Amplify custom tools. Guide AWS DevOps Agent in using your custom MCP server tools effectively, documenting when to invoke specific tools, what parameters to use, and how to interpret results.

How skills work

When AWS DevOps Agent encounters a task, it evaluates available skills and loads the ones relevant to the current investigation. The agent then follows the instructions in the skill to guide its analysis. Every skill requires a  SKILL.md  file. Beyond that, you can organize supporting content into any subdirectory structure that makes sense for your team.
Note: Skills containing executable scripts are not currently supported and will be rejected during upload. This includes script files anywhere in the skill directory, not just in a  scripts/  folder. Script execution will be enabled in a future release once agents have access to a secure coding environment.
my-skill/
├── SKILL.md # Main skill instructions (required)
├── references/ # Example: reference documentation
├── assets/ # Example: images, diagrams, data files
└── procedures/ # Example: any directory structure you need
The  SKILL.md  file uses frontmatter to declare the skill's name and description, followed by Markdown instructions:
---
name: rds-performance-investigation
description: Investigation procedures for RDS performance issues including connection exhaustion, slow queries, replication lag, and storage capacity.
---
# RDS Performance Investigation

Use this skill when customers report database latency, connection errors,
query timeouts, or read/write performance degradation.
## Step 1: Check alarm status

Query CloudWatch for active alarms on the affected RDS instance. Look for:- DatabaseConnections exceeding 80% of max*_connections
- ReadLatency or WriteLatency above 20ms
- FreeStorageSpace below 20% of total storage*

Getting started with skills

To add a skill, navigate to the Skills page in your Agent Space Operator Web App and choose Add skill. You'll see two options: Create skill to write instructions directly in the UI, or Upload skill to upload a zip file with your skill contents.

Creating a skill in the UI

Navigate to the Skills page in your Agent Space Operator Web App and choose Add skill, then Create skill. Fill in the following:
  • Name. Use lowercase letters, numbers, and hyphens (for example,  rds-throttling-investigation ). Maximum 64 characters.
  • Description. Explain when to use this skill. Minimum 100 characters recommended, maximum 1,024 characters. This helps the agent determine when to activate the skill.
  • Agent type. Select which agent types can use this skill. Generic (the default) makes the skill available to all agent types. To target specific agents, deselect Generic and choose from On-demand, Incident Triage, Incident RCA, Incident Mitigation, or Evaluation.
  • Instructions. Write step-by-step procedures in Markdown format. Be specific and actionable.

Uploading a skill as a zip file

For skills that need reference materials, architecture diagrams, or data files, create a zip file containing your  SKILL.md  and any supporting directories:
my-skill.zip
├── SKILL.md
├── references/
│ ├── architecture.md
│ └── troubleshooting.md
└── assets/
└── topology.png
Navigate to the Skills page, choose Add skill, then Upload skill. Drag and drop your zip file (maximum 6 MB), select the target agent types, and choose Upload.

Example: Database performance investigation skill

Here is a complete example that demonstrates how to structure a skill for investigating RDS performance issues:
---
name: rds-performance-investigation
description: Investigation procedures for RDS performance issues including
connection exhaustion, slow queries, replication lag, and storage capacity.
Use this skill when investigating database latency, connection errors, or read/write performance degradation.
---
# RDS Performance Investigation

Use this skill when customers report database latency, connection errors,
query timeouts, or read/write performance degradation.
## Step 1: Check alarm status

Query CloudWatch for active alarms on the affected RDS instance. Look for:- DatabaseConnections exceeding 80% of max*_connections
- ReadLatency or WriteLatency above 20ms
- FreeStorageSpace below 20% of total storage
- ReplicaLag above 30 seconds (read replicas only)

## Step 2: Analyze connection metrics

Retrieve DatabaseConnections over the past hour. If connections are near
the max_*connections limit, check for connection pool misconfiguration or
long-running idle connections.
## Step 3: Identify slow queries

Use Performance Insights (pi:GetResourceMetrics) to retrieve the top SQL
statements by average active sessions. Focus on queries with high db.load
contribution or frequent I/O waits.
## Step 4: Summarize findings

Refer to [references/rds-metrics-reference.md](_references/rds-metrics-reference.md_) for normal ranges and investigation thresholds.

Provide a summary with:1. Current performance status (healthy / degraded / critical)2. Root cause hypothesis with supporting metrics3. Recommended remediation steps ranked by priority
You can supplement this with a  references/rds-metrics-reference.md  file containing threshold tables and metric definitions that the agent can consult during its investigation:
# RDS CloudWatch Metrics Reference

| Metric | Normal Range | Investigation Threshold |
|---|---|---|
| DatabaseConnections | < 70% max*_connections | > 80% max_*connections |
| ReadLatency | < 5ms | > 20ms |
| WriteLatency | < 5ms | > 20ms |
| FreeStorageSpace | > 30% total storage | < 20% total storage |
| ReplicaLag | < 5 seconds | > 30 seconds |
| CPUUtilization | < 70% | > 85% |

Managing your skills

The Skills page in the Operator Web App provides full lifecycle management:
  • View and edit. Click any skill to see its details and edit its name, description, or instructions directly in the UI.
  • Activate and deactivate. Temporarily disable a skill without deleting it using the Active/Inactive toggle. In-progress investigations continue using the skill; new investigations will not load it.
  • Update. Edit any skill directly in the UI and save, regardless of how it was originally created.
  • Delete. Permanently remove a skill from your Agent Space. Consider deactivating instead if you may need it again.

Migrating from runbooks

If you previously used runbooks in your Agent Space, they have already been migrated to skills automatically. You can review the converted skills, update descriptions, and configure agent type targeting at any time from the Skills page.

Sample skills

The  AWS DevOps Agent Skills samples repository  on GitHub contains community-contributed skills you can use as-is or as a starting point for writing your own. Available samples include skills for AWS Health event investigation, AWS Support case analysis, EKS operational reviews, and RDS operational reviews.
To use a sample skill, clone the repository, zip the skill directory, and upload it to your Agent Space. Each skill includes a README with prerequisites and usage instructions.

Best practices for writing effective skills

  • Be specific and actionable. Write step-by-step procedures with concrete metric thresholds, specific API calls, and clear decision criteria. Avoid vague guidance like "check the logs."
  • Use descriptive names. Choose names that reflect the specific scenario, such as  rds-throttling-investigation  rather than  database-skill .
  • Target agent types. Assign skills to specific agent types to reduce context consumption and improve agent focus. A triage skill doesn't need to load during root cause analysis.
  • Include reference materials. Add metric threshold tables, architecture diagrams, and escalation procedures as supplementary files. This keeps the main  SKILL.md  focused on the investigation workflow.
  • Compose skills. Build focused, single-purpose skills and combine them for end-to-end workflows rather than creating one large skill that covers everything.

Conclusion

AWS DevOps Agent Skills give you a structured way to encode your team's operational expertise and make it available to the agent automatically. Whether you're standardizing incident investigation procedures, documenting architecture-specific troubleshooting steps, or guiding the agent in using your custom tools, skills help you get more value from AWS DevOps Agent with less repetition.
To get started, navigate to the Skills page in your Agent Space Operator Web App in AWS DevOps Agent and create your first skill. For detailed documentation, see  AWS DevOps Agent Skills  in the AWS DevOps Agent User Guide.
Yeremy Turcios is a Software Development Engineer on the AWS DevOps Agent team, primarily focusing on agent development.
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article