From aws-devops-agent
First-time setup of the AWS DevOps Agent for Claude Code — install the binary, configure AWS profiles for one or more AgentSpaces, discover space IDs, write the local routing guide, and verify the MCP server starts. Use when the user says "set up devops agent", "configure agent spaces", "I have multiple AWS accounts", or you detect that credentials / spaces are missing.
How this skill is triggered — by the user, by Claude, or both
Slash command
/aws-devops-agent:setupThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Run this skill when:
Run this skill when:
ExpiredTokenException, AccessDeniedException, or "no AgentSpace found"The plugin uses the AWS MCP Server (uvx mcp-proxy-for-aws) which is fetched automatically via uvx. Verify uv is installed:
uv --version # should print 0.4.0+
uvx mcp-proxy-for-aws@latest --help # fetches and runs — no pip install needed
If uv is missing, install it: curl -LsSf https://astral.sh/uv/install.sh | sh
Verify AWS credentials are configured:
aws sts get-caller-identity # should return your account/user info
If credentials are missing or expired: aws sso login (SSO) or aws configure (access keys).
Ask the user once, listing what's needed:
What AWS accounts hold your AgentSpaces? For each, tell me:
- AWS account ID
- Region (default
us-east-1)- Purpose (e.g. "production", "staging", "shared knowledge")
Use named profiles in ~/.aws/config. The naming convention is the purpose — not the account ID — so future references stay readable.
# ~/.aws/config
[profile devops-prod]
region = us-east-1
[profile devops-stage]
region = us-east-1
[profile devops-kb]
region = us-east-1
Then attach credentials:
aws configure sso --profile devops-prodaws configure --profile devops-prod~/.aws/config to add sso_session, sso_account_id, sso_role_nameVerify each profile:
AWS_PROFILE=devops-prod aws sts get-caller-identity
For each profile, list spaces using the AWS CLI:
AWS_PROFILE=devops-prod aws devops-agent list-agent-spaces --region us-east-1
Record the space name and ID for each. If a profile has no space:
AWS_PROFILE=devops-prod aws devops-agent create-agent-space --name 'my-prod-space' --region us-east-1 to create one, orAdd the AWS MCP Server to Claude Code's MCP configuration (typically ~/.claude/settings/mcp.json or the project-level .mcp.json):
{
"mcpServers": {
"aws-mcp": {
"command": "uvx",
"timeout": 100000,
"transport": "stdio",
"args": [
"mcp-proxy-for-aws@latest",
"https://aws-mcp.us-east-1.api.aws/mcp",
"--metadata", "AWS_REGION=us-east-1"
]
}
}
}
Change AWS_REGION=us-east-1 in --metadata if your AgentSpaces are in a different region.
The AWS MCP Server reads credentials from the standard AWS credential chain. Set the primary profile in your shell rc file:
# ~/.zshrc or ~/.bashrc
export AWS_PROFILE=devops-prod # the primary space's profile
Or set it project-scoped for a Claude Code project that should always target a specific space.
After installing the plugin (/plugin install aws-devops-agent@aws-devops-tools), reload: /reload-plugins. Verify the tools are available — you should see aws___call_aws and aws___run_script in /tools.
For each space that is NOT the MCP primary, generate a wrapper script so the user can query it from the terminal:
#!/usr/bin/env bash
# Query the staging AgentSpace
set -euo pipefail
SPACE_ID="as-def456" # staging agent space ID
REGION="us-east-1"
[ $# -eq 0 ] && { echo "Usage: $(basename "$0") \"your question\""; exit 1; }
# Create a chat session and send the message
EXEC_ID=$(AWS_PROFILE=devops-stage aws devops-agent create-chat --user-id $USER_ID --user-type IAM \
--agent-space-id "$SPACE_ID" --region "$REGION" \
--query 'executionId' --output text)
AWS_PROFILE=devops-stage python3 - "$EXEC_ID" "$SPACE_ID" "$REGION" "$*" <<'EOF'
import sys, boto3
exec_id, space_id, region, content = sys.argv[1], sys.argv[2], sys.argv[3], sys.argv[4]
client = boto3.client('devops-agent', region_name=region)
response = client.send_message(agentSpaceId=space_id, executionId=exec_id, content=content)
full = []
current = None
for event in response['events']:
if 'contentBlockStart' in event:
current = event['contentBlockStart'].get('type')
elif 'contentBlockDelta' in event and current in (None, 'text'):
delta = event['contentBlockDelta'].get('delta', {})
if 'textDelta' in delta:
full.append(delta['textDelta']['text'])
elif 'contentBlockStop' in event:
current = None
print(''.join(full))
EOF
Install at ~/.local/bin/devops-stage (and chmod +x). Repeat per non-primary space.
This is the file the multi-space skill reads at the start of every future session. Default location: .claude/aws-devops-agent.md (project-scoped) or ~/.claude/AGENTS.md (user-scoped).
# AWS DevOps Agent — local setup
## AgentSpaces
| Space | Account | AWS Profile | Agent Space ID | Region | Purpose |
|-------|---------|-------------|----------------|--------|---------|
| **prod** | 111111111111 | `devops-prod` | `as-abc123` | us-east-1 | Production incidents, customer-facing services |
| **stage** | 222222222222 | `devops-stage` | `as-def456` | us-east-1 | Pre-prod validation, integration testing |
| **kb** | 333333333333 | `devops-kb` | `as-ghi789` | us-east-1 | Shared runbooks, cross-account knowledge |
## MCP primary
Plugin MCP server targets **prod** (`AWS_PROFILE=devops-prod`).
## Reaching other spaces
- `devops-stage "your question"` (shell wrapper)
- `devops-kb "your question"` (shell wrapper)
- Or restart Claude Code with `AWS_PROFILE=<other>` exported.
## Credential refresh
When you see `ExpiredTokenException`:
- SSO: `aws sso login --profile <profile>`
- Access keys: `aws configure --profile <profile>`
In Claude Code:
aws___call_aws(cli_command="aws devops-agent list-agent-spaces --region us-east-1") returns the primary space's spaces.aws___call_aws(cli_command="aws devops-agent create-chat --agent-space-id SPACE_ID --user-id USER_ID --user-type IAM --region us-east-1") returns an executionId.aws___run_script with a send_message call returns a response within ~10s.devops-stage "list runbooks") prints results.ExpiredTokenException at startup → user needs aws sso login --profile <name>.uvx not found or not in PATH; install uv first. Or check aws sts get-caller-identity to confirm credentials are valid.MCP error -32000: Connection closed → Most commonly missing/expired AWS credentials. Run aws sts get-caller-identity to verify, then aws sso login to refresh. Also check that uvx is in your PATH./reload-plugins, then /tools to confirm aws___call_aws appears.User identity could not be resolved on create-chat → CreateChat requires Operator App identity (IDC or IAM). Use aws sso login for SSO identity. Alternatively, use SendMessage on investigation executionIds from create-backlog-task which works with any credential type.Guides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub aws-samples/sample-aws-devops-agent-claude-plugin --plugin aws-devops-agent