feat: add Claude Platform on AWS migration skill (.claude/skills/)

[wirjo]

Summary

Adds a structured .claude/skills/ directory with a Claude Platform on AWS migration skill — a reference that coding agents (Claude Code, etc.) can use to automatically convert Anthropic 1P (direct API) code to CPOA.

What this adds

.claude/skills/claude-platform-on-aws/
├── SKILL.md                     # Core conversion guide + pitfalls
└── references/
    └── code-patterns.md         # Python, Node.js, curl before/after examples

Motivation

Developers migrating from api.anthropic.com to aws-external-anthropic.{region}.api.aws encounter several non-obvious differences:

• Required anthropic-workspace-id header (not documented prominently)
• Environment keys not supported on CPOA
• AnthropicAWS class unavailable in Node.js SDK
• WorkPoller requires environmentKey workaround
• Quick Start API keys expire in ~15 min

This skill provides a structured checklist and code patterns covering both auth modes (SigV4 + API key), managed agents, and session lifecycle.

Why .claude/skills/?

This sets the foundation for a skills directory in this repository that:

1. Any Claude Code session cloned into this repo automatically picks up
2. Can be extended with additional skills for other patterns in this repo (e.g., agent SDK patterns, Bedrock migration, etc.)
3. Others can borrow and install in their own coding environments

Relationship to existing content

The repo already has CPOA notebooks under claude-platform-on-aws/notebooks/. This skill complements those by providing an agent-consumable reference (SKILL.md format) for automated conversions rather than human-walkthrough notebooks.

Alternative repository

An alternative home for this type of contribution could be https://github.com/aws/agent-toolkit-for-aws/tree/main/skills/specialized-skills (the official AWS agent skills repository). Happy to cross-post or move there if preferred by maintainers.

Checklist

• Working against latest main
• No reformatting of existing code
• MIT-0 license compatible
• No secrets/credentials in code (all examples use placeholders)

[wirjo]

@rodzanto FYI, no rush

[scouturier]

The CPOA path is the dedicated AnthropicAWS client rather than Anthropic() with a manual base_url — it handles SigV4 signing, base-URL construction, and the anthropic-workspace-id header for you, so all the plumbing here collapses:

from anthropic import AnthropicAWS  # pip install -U "anthropic[aws]"

client = AnthropicAWS(api_key=API_KEY)  # region + workspace from AWS_REGION / ANTHROPIC_AWS_WORKSPACE_ID

Ref: Claude Platform on AWS → Making requests — "Each SDK provides a platform-specific client class that handles SigV4 signing, region-based base URL construction, and the anthropic-workspace-id header."

[wirjo]

Confirmed ✅ — docs show AnthropicAWS (Python) and AnthropicAws (TypeScript from @anthropic-ai/aws-sdk) as the canonical CPOA clients. Will update all examples to use these instead of manual base_url/headers.

[scouturier]

Heads up — credentials={"type": "aws_iam", ...} isn't a real parameter, and a plain Anthropic() can't SigV4-sign at all. SigV4 mode is just the dedicated client with no key; it resolves creds via the standard AWS provider chain (env → ~/.aws → IRSA → ECS → IMDS):

from anthropic import AnthropicAWS
client = AnthropicAWS(aws_region=REGION)  # SigV4 via default AWS credential chain

Ref: CPOA → SigV4 authentication.

[wirjo]

Confirmed ✅ — credentials={"type": "aws_iam", ...} is not a real SDK parameter. SigV4 mode is simply AnthropicAWS() with no API key, which resolves creds via the standard AWS provider chain (env → ~/.aws → IRSA → ECS → IMDS).

Will fix to:

from anthropic import AnthropicAWS
client = AnthropicAWS(aws_region=REGION)  # SigV4 via default AWS credential chain

Ref: SigV4 authentication — credential precedence shows apiKey → env creds → provider chain.

[scouturier]

Same as the Python case — the Node client is AnthropicAws from @anthropic-ai/aws-sdk (npm install @anthropic-ai/aws-sdk), which sets the workspace header and signing automatically:

import AnthropicAws from "@anthropic-ai/aws-sdk";
const client = new AnthropicAws({ apiKey });

[wirjo]

Confirmed ✅ — Node client is AnthropicAws from @anthropic-ai/aws-sdk (npm install @anthropic-ai/aws-sdk). Will update:

import AnthropicAws from "@anthropic-ai/aws-sdk";
const client = new AnthropicAws({ apiKey, awsRegion: "us-west-2" });

Ref: Install an SDK → TypeScript — npm install @anthropic-ai/aws-sdk

[scouturier]

Same note as the Python SigV4 block — no credentials object; new AnthropicAws({ awsRegion: region }) signs via the default AWS chain.

[wirjo]

Confirmed ✅ — same as Python: new AnthropicAws({ awsRegion: region }) signs via default AWS chain. No credentials object. Will fix.

[scouturier]

Small correction — there is a dedicated Node client (AnthropicAws in @anthropic-ai/aws-sdk), so this note is the one thing to flip. The docs list platform clients for Python, TypeScript, Go, Java, C#, PHP, and Ruby. Ref: CPOA → Install an SDK.

[wirjo]

Confirmed ✅ — this note is wrong and will be removed. There IS a dedicated Node client (AnthropicAws in @anthropic-ai/aws-sdk). Docs list platform clients for Python, TypeScript, Go, Java, C#, PHP, and Ruby.

Ref: Install an SDK

[scouturier]

CPOA API keys go on the x-api-key header rather than Authorization: Bearer — the short-term token generators also return tokens that "work with the x-api-key header." The anthropic-version + anthropic-workspace-id headers here are spot on. Ref: CPOA → API key authentication.

[wirjo]

Confirmed ✅ — CPOA API keys use the x-api-key header, not Authorization: Bearer. The docs say short-term tokens also "work with the x-api-key header." Will fix the curl example:

-H "x-api-key: $ANTHROPIC_AWS_API_KEY"

Ref: Short-term API keys — "returns a time-limited token that works with the x-api-key header"

[scouturier]

from anthropic.helpers.beta.environments import WorkPoller isn't the documented path — the self-hosted worker helper is EnvironmentWorker from anthropic.lib.environments. Worth aligning the "Before" side with that so the contrast is accurate.

[wirjo]

Good catch — will align the "Before" example with the documented EnvironmentWorker pattern rather than the invented WorkPoller path. The self-hosted docs show the SDK helpers .run() / .run_one() as the main interface.

Ref: Self-hosted sandboxes → Environment worker

[scouturier]

The work.poll(environment_id=..., timeout=30) signature is invented — the documented Python surface is the EnvironmentWorker helper (.run() / .run_one()), with client.beta.environments.work.poller(...) as the mid-level API. (The underlying REST route GET /v1/environments/{id}/work/poll does exist, so the concept is right — it's just the SDK shape.) Ref: Self-hosted sandboxes.

[wirjo]

Confirmed — the SDK shape is EnvironmentWorker with .run() / .run_one(), and client.beta.environments.work.poller(...) as the mid-level API. The REST route GET /v1/environments/{id}/work/poll does exist (confirmed in IAM actions under ProcessEnvironmentWork), but the Python SDK wraps it differently.

Will rewrite the "After" pattern to use the documented SDK helper, and note the raw endpoint as a fallback for custom implementations.

Ref: IAM actions → ProcessEnvironmentWork confirms GET /v1/environments/{id}/work/poll is a real route.

[scouturier]

One correctness catch: AnthropicSelfHostedEnvironmentAccess is the self-hosted worker policy — its grant is GetEnvironment, ProcessEnvironmentWork, GetSession, UpdateSession, GetSkill, CallWithBearerToken, with no CreateInference. A role with only this policy 403s on /v1/messages. For plain SigV4 inference the minimal managed policy is AnthropicInferenceAccess. Ref: IAM actions → Managed policies.

[wirjo]

Confirmed ✅ — important distinction. Per the IAM docs:

• AnthropicSelfHostedEnvironmentAccess = worker policy (GetEnvironment, ProcessEnvironmentWork, GetSession, UpdateSession, GetSkill, CallWithBearerToken) — no CreateInference
• AnthropicInferenceAccess = needed for plain SigV4 calls to /v1/messages

Will split the IAM guidance: inference needs AnthropicInferenceAccess; self-hosted workers need AnthropicSelfHostedEnvironmentAccess.

Ref: IAM actions → Managed policies

[scouturier]

Could we cite a source for the aws-external-anthropic-api-key- prefix? The CPOA docs describe key generation but don't state a fixed prefix, so I'd soften this to avoid an agent asserting on a shape that may not hold. (Same prefix claim appears in SKILL.md lines 15 & 30.)

[wirjo]

Fair point — the docs describe key generation via the AWS Console but do not state a guaranteed aws-external-anthropic-api-key- prefix. This was observed empirically but should not be treated as a stable contract.

Will soften to: "API keys are generated in the AWS Console under Claude Platform on AWS → API keys" without asserting a specific prefix format. Will remove the prefix-based validation checklist item too.

[scouturier]

This is a bit too absolute — self-hosted sandbox agents are supported on CPOA and do authenticate with ANTHROPIC_ENVIRONMENT_KEY (the AnthropicSelfHostedEnvironmentAccess policy + ProcessEnvironmentWork action exist precisely for that worker). Might scope this to "managed/cloud agents" so an agent following the rule doesn't strip a required credential. (Also drives pitfall #3 at line 86 and step 5 at line 59.) Ref: CPOA → Claude Managed Agents.

[wirjo]

Confirmed ✅ — this was overly broad. The self-hosted sandboxes docs explicitly state:

"On Claude Platform on AWS, the worker authenticates with AWS IAM (SigV4) or an API key generated in the AWS Console, not an environment key. Environment keys generated in the Claude Console don't work with the Claude Platform on AWS endpoint."

So: environment keys from the Claude Console don't work on CPOA, but the worker still authenticates — just via IAM/API key instead. The table row and pitfall should say "Environment keys from Claude Console not used on CPOA — workers authenticate via IAM or CPOA API key" rather than implying the concept of worker auth doesn't exist.

Ref: Self-hosted sandboxes → Before you begin (CPOA note)

[scouturier]

The ~15-min figure doesn't match the docs — short-term tokens "default to 12 hours and are capped at the lesser of your requested duration, your AWS credentials' expiry, and 12 hours." Worth correcting here and in pitfall #4 (line 87). Ref: CPOA → Short-term API keys.

[wirjo]

Confirmed ✅ — the docs clearly state:

"Token lifetime defaults to 12 hours and is capped at the lesser of your requested duration, your AWS credentials' expiry, and 12 hours."

The ~15 min figure was likely confused with something else (perhaps an STS session token from a very short-lived assume-role). Will correct to 12 hours default, capped at min(requested, AWS creds expiry, 12h).

Ref: Short-term API keys

[wirjo]

All review comments from @scouturier have been addressed in the latest commit (a55e37d). Summary of changes:

• Replaced manual base_url/defaultHeaders with the documented AnthropicAWS (Python) and AnthropicAws (TypeScript) platform clients
• Fixed SigV4 auth to use the standard AWS credential provider chain (no invented credentials parameter)
• Corrected auth header to x-api-key (not Authorization: Bearer)
• Fixed short-term token lifetime to 12 hours (not 15 min)
• Split IAM guidance: AnthropicInferenceAccess for inference vs AnthropicSelfHostedEnvironmentAccess for workers
• Replaced invented WorkPoller with documented EnvironmentWorker SDK helper
• Removed undocumented API key prefix assertion
• Added SigV4 curl example and short-term token generation patterns

All corrections are backed by the official docs:

• https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws
• https://platform.claude.com/docs/en/api/claude-platform-on-aws-iam-actions
• https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes

@scouturier @rodzanto — this should be ready for merge when you get a chance. Let us know if anything else needs attention. 🙏

[scouturier]

Thanks @wirjo — re-verified the earlier review points and they're resolved. Two things before merge:

1. Rebase on main (blocks merge). The failing build check isn't from this PR — the branch is well behind main and the failure is a known dependency/CI issue since fixed there. A rebase should clear it.

2. Model ID nit (non-blocking). Examples use claude-sonnet-4-6 — valid but previous-gen. The official CPOA docs use claude-sonnet-5. Since this skill is a template agents copy, worth swapping claude-sonnet-4-6 → claude-sonnet-5 across code-patterns.md and SKILL.md.

Everything else checks out against the live docs (token generators, clients, IAM, curl SigV4). LGTM once those two are in. 🙏

[wirjo]

@scouturier Rebased on latest main (should clear the CI failure) and updated all model IDs to claude-sonnet-5 per your suggestion. Ready for another look when you get a chance 🙏

[scouturier]

One thing that slipped past the earlier round: the "Worker with IAM Auth" block still uses bare AsyncAnthropic(), and the comment # SigV4 via AWS credential chain is inaccurate — base AsyncAnthropic targets api.anthropic.com and can't SigV4-sign (same defect we fixed for the inference examples at :49/:109). We corrected the prose for this in SKILL.md:19 but not this code block.

Two things to reconcile:

1. Use the AWS client, not the base one — the CPOA worker should be constructed via the platform client that signs and sets the workspace header.
2. If a SigV4-authenticated EnvironmentWorker isn't actually a documented pattern (the self-hosted docs only show the async worker with auth_token=<key>), mark this variant as unverified rather than shipping it as working. The API-key worker block just below is fine as-is.