Introducing Open-Source Skills for AWS SDK Best Practices

We released a set of AWS SDK Skills as part of the open-source Agent Toolkit for AWS. These are AI skills that teach coding agents how to follow AWS SDK best practices. The project is available on GitHub under the Apache-2.0 license.

The problem

AI coding agents know the general shape of AWS SDK usage, but they get the details wrong. They generate incorrect API names, use incorrect parameter types, and miss SDK-specific patterns like paginators, waiters, and high-level APIs such as the transfer manager for Amazon Simple Storage Service (Amazon S3). These errors are especially common for newer SDKs like the AWS SDK for Swift, where agents generate code that looks plausible but fails to compile.

As developers increasingly rely on AI agents to write AWS SDK code, we need to make sure those agents produce code that compiles, follows best practices, and uses each SDK the way it was intended to be used.

What’s in a skill

Skills are modular packages that give AI coding agents specialized SDK knowledge. Each skill is authored by the SDK team that owns the language, so it reflects the things agents consistently get wrong for that specific SDK. A skill includes:

• SKILL.md — core instructions with SDK-specific patterns and concrete examples
• references/ — on-demand documentation for deeper topics, loaded only when needed
• scripts/ — automation for build, test, and validation workflows

Skills are agent-agnostic. They work with any coding agent that supports the open skills format.

Common mistakes skills help prevent

Code that doesn’t compile. This is the most common failure mode for newer SDKs where the agent’s training data is thin or out of date. The AWS SDK for Swift uses Swift concurrency throughout. Operations are async-throwing, and so are the convenience client constructors. Agents frequently miss this and produce code that looks reasonable but doesn’t build:

// What agents tend to write. Does not compile.
let client = S3Client()
let response = client.listBuckets(input: ListBucketsInput())

Both lines are wrong: S3Client() is async throws, and so is listBuckets. With the Swift skill installed, the agent writes the modern Swift concurrency form:

let config = try await S3Client.S3ClientConfig(region: "us-west-2")
let client = S3Client(config: config)
let response = try await client.listBuckets(input: ListBucketsInput())

The first version sends the developer back to the docs to figure out why a plausible-looking line won’t build. The second one runs.

Code that runs but performs poorly or costs more. Agents often skip SDK features that exist precisely to make AWS calls efficient: paginators for ListObjects and similar APIs, waiters for resource-state polling, and the SDK’s high-level file methods like upload_file / download_file for large transfers. A handwritten loop that calls ListObjects without pagination silently drops results past the first page, polling code without waiters burns API calls and risks throttling, and manual file I/O for S3 transfers gives up multipart uploads and parallelism. The code compiles and often appears to work in small tests, but breaks once you’re dealing with real data volumes. With a skill installed, the agent reaches for the right SDK feature for the job: paginators for list operations, waiters for state polling, and the high-level transfer methods for files.

Code that runs but has subtle bugs. Manually marshalling DynamoDB types like {"S": "value"} is easy to get slightly wrong in ways that fail only on certain inputs. Catching a generic Exception instead of typed exceptions like ConditionalCheckFailedException makes retry logic swallow real failures. With a skill installed, the agent reaches for the document client (which handles the conversion correctly) and uses typed exceptions tied to the actual operations it’s calling.

Measuring the impact

We evaluate each skill against a benchmark of real SDK tasks (Amazon S3 operations, Amazon DynamoDB queries, client configuration, presigned URL generation, credential management) and grade the generated code on whether it compiles, passes lint, and actually does what the task asked for (judged by an LLM). Every task runs twice: once with no skill installed, and once with the relevant skill loaded.

Across our test suite, code generated with a skill installed consistently passed more checks than code generated without one.

Available skills

The following table summarizes the skills available at launch:

Get started

You’ll need a coding agent that supports the open skills format. To install a skill from the Agent Toolkit for AWS, run:

npx skills add aws/agent-toolkit-for-aws/skills --skill <skill>

Replace <skill> with the one you want:

• aws-sdk-swift-usage
• aws-sdk-js-v3-usage
• aws-sdk-python-usage

Or pass --skill multiple times to install more than one.

If your favorite SDK is missing or you’ve seen agents make mistakes that aren’t covered yet, open an issue or submit a skill. Visit the repository on GitHub to try it out.