training/data/raw/about-aws-devops-agent-devops-agent-skills.md

DevOps Agent Skills

AWS DevOps Agent Skills are modular instruction sets that extend the agent's capabilities with specialized domain knowledge and investigation methodologies tailored to your infrastructure and operational workflows.

What are Skills

Skills are self-contained directories containing Markdown instructions that provide specialized capabilities to AWS DevOps Agent. AWS DevOps Agent supports a subset of the Agent Skills specification—an open standard for packaging agent instructions and resources—supporting only non-executable documents: Markdown instructions, PDFs, images, and data files.

Every skill requires a SKILL.md file containing instructions you want to provide for your AWS DevOps Agent. In addition to the required SKILL.md file, skills can include:

• Investigation workflows for specific scenarios or infrastructure types.
• Reference materials including architecture patterns and operational procedures.
• Agent type targeting – Skills can be targeted to specific agent types (Generic, On-demand, Incident Triage, Incident RCA, Incident Mitigation, Evaluation) to reduce context consumption and improve agent focus.

Why use Skills

Skills transform AWS DevOps Agent from a general-purpose assistant into a specialist for your infrastructure and operational workflows. Unlike one-time instructions provided in a chat message, Skills are reusable capabilities that load automatically when relevant to tasks performed by AWS DevOps Agent.

Key benefits:

• Specialize your agent – Tailor AWS DevOps Agent with investigation procedures, best practices, and organizational knowledge specific to your infrastructure and operational patterns.
• Reduce repetition – Create investigation workflows once and AWS DevOps Agent uses them automatically across all relevant investigations, eliminating the need to provide the same guidance repeatedly.
• Compose capabilities – Combine multiple Skills to build end-to-end investigation workflows. AWS DevOps Agent reads multiple skills during execution, such as a skill to retrieve deployments from your custom CI/CD pipeline and a skill to search your code repositories.
• Amplify custom tools – Create skills that guide AWS DevOps Agent in using your custom MCP server tools effectively. Skills can document when to invoke specific tools, what parameters to use for different scenarios, and how to interpret results to accomplish workflows specific to your infrastructure.

How Skills work

When AWS DevOps Agent encounters a relevant task, it loads the appropriate skills and follows the instructions to guide its investigation. For example, a "Database Performance Investigation" skill might include step-by-step procedures for analyzing RDS throttling issues, enabling the agent to systematically check alarm status, analyze connection metrics, and identify slow queries.

Skill structure

A skill is organized as a directory containing:

my-skill/
├── SKILL.md              # Main skill instructions
├── references/           # Optional: additional reference documentation
└── assets/               # Optional: images, diagrams, data files

SKILL.md

The SKILL.md is the only mandatory file. It contains the core instructions written in Markdown format. This file should:

• Describe when and how to use the skill.
• Provide step-by-step investigation procedures.
• Include decision trees for different scenarios.
• Document expected outputs and success criteria.

Frontmatter

Frontmatter is the metadata block at the top of a SKILL.md file, enclosed between --- delimiters. It contains the name and description fields that AWS DevOps Agent uses to determine when to activate the Skill during an investigation or task.

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

name – A unique identifier for the Skill. Use lowercase letters, numbers, and hyphens only (maximum 64 characters). Must not start or end with a hyphen.

description – A detailed explanation of when and why AWS DevOps Agent should use this Skill. AWS DevOps Agent evaluates this field to decide whether the Skill is relevant to the current task. A vague or missing description can cause the agent to skip the Skill entirely, even if the instructions are well-written.

Important – Write the description from the agent's perspective. Include the specific scenarios, services, error types, or symptoms that should trigger the Skill.

When you create a Skill in the UI, the system generates frontmatter automatically from the name and description you provide. Skills uploaded as zip files must include frontmatter in the SKILL.md file.

Example: Complete skill

The following example shows a complete, well-formed skill for investigating RDS performance issues.

Directory structure:

rds-performance-investigation/
├── SKILL.md
├── references/
│   └── rds-metrics-reference.md
└── assets/
    └── rds-investigation-flowchart.png

SKILL.md:

---
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

Provide a summary with:
1. Current performance status (healthy / degraded / critical)
2. Root cause hypothesis with supporting metrics
3. Recommended remediation steps ranked by priority

references/rds-metrics-reference.md:

# 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% |

Example: Incident filtering skill

Skills targeted to the Incident Triage agent type can define criteria for automatically skipping incidents. Use this to filter incidents that don't require investigation.

SKILL.md:

---
name: skip-scheduled-maintenance
description: Skip low-priority incidents during a scheduled maintenance window.
  Use this skill to automatically filter MEDIUM and LOW severity alarms that
  fire during planned maintenance, avoiding unnecessary investigations for
  expected disruptions.
---

# Skip Scheduled Maintenance

Skip all incidents that meet BOTH of the following criteria:

1. The incident arrived between **2025-03-15 02:00 UTC** and **2025-03-15 06:00 UTC**
2. Severity is MEDIUM or LOW

Do NOT skip HIGH or CRITICAL severity incidents, even during the maintenance window.

Creating Skills

You can create skills in two ways depending on your workflow preferences and skill complexity.

Creating a skill in the UI

Skills created in the AWS DevOps Agent Operator Web App contain a name, description, and instructions in a single SKILL.md file.

To create a skill in the UI:

• Navigate to the Knowledge page in your Agent Space Operator Web App and choose the Skills tab.
• Click "Add skill".
• Select "Create skill" from the modal.
• Fill out the skill form:
  • Name – Lowercase letters, numbers, and hyphens only (maximum 64 characters). Must not start or end with a hyphen.
  • Description – Brief explanation of when to use this skill (minimum 100 characters recommended, maximum 1,024 characters).
  • Status – Set to Active (default) or Inactive.
  • Agent Type – Select one or more agent types that can use this skill.
  • Instructions – Step-by-step procedures in Markdown format.
• Choose "Create" to save the skill.

Uploading a skill

Skills uploaded as zip files contain a SKILL.md file plus additional resources such as reference materials or assets.

Skill structure:

my-skill.zip
├── SKILL.md              # Required: main skill instructions
├── references/           # Optional: reference documentation
│   ├── architecture.md
│   └── troubleshooting.md
└── assets/               # Optional: images, diagrams, data files
    ├── topology.png
    └── metrics.csv

To create a skill via zip upload:

• Create a directory with your skill files following the structure above.
• Ensure SKILL.md includes proper frontmatter (name and description).
• Compress the directory into a .zip file.
• Navigate to the Knowledge page and choose the Skills tab.
• Click "Add skill".
• Select "Upload skill" from the modal.
• Drag and drop your .zip file or choose to browse (ZIP files only, maximum 6 MB).
• Select one or more agent types.
• Choose "Upload" to add the skill to your Agent Space.

Importing a skill from a repository

You can import skills directly from a GitHub repository directory. AWS DevOps Agent fetches the skill content from the repository, extracts the name and description from the SKILL.md frontmatter, and creates the skill in your Agent Space.

Prerequisites:

• A GitHub account associated with your Agent Space.
• A GitHub repository containing a valid skill directory with a SKILL.md file at the root.

To import a skill from a repository:

• Navigate to the Knowledge page and choose the Skills tab.
• Click "Add skill".
• Select "Import from repository" from the modal.
• Enter the GitHub directory URL that contains your SKILL.md file.
• Select one or more agent types.
• Set the lifecycle status (Active or Inactive).
• Click "Import skill".

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.

Managing Skills

AWS DevOps Agent provides comprehensive skill management capabilities through the Operator Web App:

Listing skills – View all Skills in your Agent Space on the Knowledge page Skills tab.

Viewing skills – Choose any skill to see its detail view.

Selecting agents for a skill – Configure which agent types can use each skill.

Activating and deactivating skills – Temporarily disable skills without deleting them.

Updating skills – Modify existing skills based on how they were created.

Deleting skills – Permanently remove skills from your Agent Space.

Migrating from Runbooks

Existing Runbooks are automatically migrated to Skills with no customer action required. When your Agent Space transitions to the Skills model, all Runbooks are converted to Skills and appear in your Skills UI.