Agent Skills Basics

Seven examples to get you started with packaging AWS SDK work as agent skills - five basic and two intermediate.

Each example treats a "skill" as a practice, not a product: a written convention plus a worked example that an AI assistant or a teammate can follow the same way every time.

Prerequisites

• No new package to install - a skill is a markdown/YAML document you keep in your repo or team wiki.
• Python: pip install boto3 (boto3 1.43.x, Python 3.10+). TypeScript: npm install @aws-sdk/client-<service> (Node.js 18+), for the code a skill produces or checks.
• A convention worth writing down: something your team already does consistently but has never put in one place.

Basic Examples

1. The Anatomy of a Skill File

A skill is a name, a trigger, a procedure, and an example - nothing more.

This is a language-neutral instructions document, so it gets a plain fence, not a <CodeGroup>.

---
name: service-client-scaffold
description: Scaffold a new AWS service client consistently in Python and TypeScript.
triggers:
  - "add a new AWS service client"
  - "wire up <service> in this project"
---
 
# Service Client Scaffold
 
1. Confirm the target service and the operations this project needs.
2. Reuse the existing credential chain - never hardcode keys.
3. Create one client per service, scoped to the project's default region.
4. Emit both a boto3 client and an AWS SDK v3 client.
5. Include one smoke-test call (a cheap list or describe operation).

• The name and triggers fields tell an assistant when to reach for this skill.
• The numbered procedure is the actual convention, written once.
• Nothing here is AWS-specific machinery - it is your team's house style, documented.

Related: What an "Agent Skill" Means for AWS SDK Work - the concept behind this document shape.

2. Matching a Task to a Trigger

A skill only fires when its trigger matches what someone actually asks for.

Task asked: "add DynamoDB to this service"
Trigger matched: "add a new AWS service client"
Skill invoked: service-client-scaffold

• Triggers are phrased the way a real request sounds, not the way a spec sounds.
• A skill with a vague trigger ("help with AWS") never reliably fires, because nothing narrows it.
• If two skills could plausibly match, split the ambiguity out into more specific triggers.

3. Following the Procedure: Scaffolding a Client

Running the skill from Example 1 produces matching output in both SDKs, because both call the same underlying AWS API.

# --- Python (boto3) ---
import boto3
 
# Step 2: reuse the existing credential chain - no keys here.
# Step 3: one client, scoped to the project's default region.
dynamodb = boto3.client("dynamodb", region_name="us-east-1")
 
# Step 5: minimal smoke-test call.
dynamodb.describe_table(TableName="Orders")

// --- TypeScript (AWS SDK v3) ---
import { DynamoDBClient, DescribeTableCommand } from "@aws-sdk/client-dynamodb";
 
// Step 2: reuse the existing credential chain - no keys here.
// Step 3: one client, scoped to the project's default region.
const dynamodb = new DynamoDBClient({ region: "us-east-1" });
 
// Step 5: minimal smoke-test call.
await dynamodb.send(new DescribeTableCommand({ TableName: "Orders" }));

• The skill's procedure maps directly onto the output: each numbered step becomes a line or comment.
• Both languages hit the same DynamoDB DescribeTable API, so the shapes line up.
• A smoke test at the end is what makes the output checkable, not just plausible-looking.

Related: A Service-Client Scaffolding Skill - this pattern developed in full.

4. A Skill That References, Rather Than Repeats

A good skill points at an existing convention instead of re-explaining it inline.

## Credential Handling
 
Do not derive credential logic here. Follow this project's existing
provider chain (see: the credential provider chain reference).
Only add project-specific role scoping if this integration needs new
permissions beyond what the chain already resolves.

• The skill stays short because it defers to a reference that already exists.
• This keeps skills maintainable: the credential mechanics live in one place, not copied into every skill that touches auth.
• If the referenced convention changes, only one document needs updating.

5. A Checklist Is a Valid Skill Output

Not every skill produces code. Some produce a review result.

## Cost Review Output (example)
 
- [x] No tight polling loop found.
- [ ] Per-item `get_item` call in a loop over 200+ ids - flag for batching.
- [x] Pagination limit present on list operation.
- [ ] No budget alarm referenced in this PR - flag for follow-up.

• The skill's expected output here is a filled-in checklist, not a diff.
• A checklist output is just as checkable as generated code: each line is pass or fail.
• This is the shape a cost-review skill produces against a real PR.

Related: A Cost-Review Skill for SDK-Heavy PRs - this checklist developed in full.

Intermediate Examples

6. Composing Two Skills in Sequence

Skills can chain without depending on each other's internals.

1. Run: credential-setup-skill
   -> produces: an IAM role/policy and a local profile for the new project.
2. Run: service-client-scaffold
   -> produces: a boto3 client and an AWS SDK v3 client that use the role from step 1.

• Each skill still documents its own inputs and output independently.
• Composition is just running one skill, then another, in the order a task naturally needs.
• Neither skill needs to know how the other is implemented - only what it produces.

7. Reviewing a Skill When the Underlying Pattern Changes

A skill document needs an owner and a trigger to get re-checked.

## Review Log
 
- 2026-05-10: written, wraps the existing credential chain and paginator helpers.
- 2026-07-20: reviewed after this repo added a new batching helper - procedure
  updated to reference it instead of a manual loop.

• Treat a skill like a runbook: someone owns it, and it gets revisited when the pattern it wraps changes.
• A stale skill is worse than no skill, because it still looks authoritative.
• A short review log makes staleness visible instead of silent.

Related: Agent Skills Best Practices - keeping skills narrow, current, and reviewable.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).