# Skill: aws

## Metadata

| Field | Value |
|-------|-------|
| **Name** | `aws` |
| **Version** | `1.0.0` |
| **Package** | `oclawma-skill-aws` |
| **Category** | `cloud` |
| **Author** | `OpenClaw Team` |
| **License** | `MIT` |
| **Python** | `>=3.9` |

## Description

Official AWS skill for OCLAWMA providing comprehensive cloud resource management capabilities across multiple AWS services.

### Features

- **EC2** - Instance management (list, start, stop, describe)
- **S3** - Bucket and object operations
- **Lambda** - Function management and invocation
- **CloudWatch** - Metrics and logs
- **IAM** - User and role listing
- **RDS** - Database instance information
- **Route53** - Hosted zone management
- **STS** - Identity verification

## Installation

```bash
pip install oclawma-skill-aws
```

Or install from source:

```bash
git clone https://github.com/openclaw/oclawma-skill-aws.git
cd oclawma-skill-aws
pip install -e .
```

### Prerequisites

- **AWS Account** - Valid AWS credentials
- **IAM Permissions** - Appropriate permissions for operations
- **boto3** - Installed automatically

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `AWS_ACCESS_KEY_ID` | - | AWS access key ID |
| `AWS_SECRET_ACCESS_KEY` | - | AWS secret access key |
| `AWS_SESSION_TOKEN` | - | AWS session token (optional) |
| `AWS_DEFAULT_REGION` | `us-east-1` | Default AWS region |

### AWS Credentials File

Configure in `~/.aws/credentials`:

```ini
[default]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
```

And `~/.aws/config`:

```ini
[default]
region = us-west-2
output = json
```

## Tools

### EC2 Operations

#### `ec2_list_instances`

List EC2 instances with optional filtering.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `region` | `string` | No | - | AWS region |
| `filters` | `object` | No | - | Filters (e.g., `{"instance-state-name": "running"}`) |
| `max_results` | `integer` | No | - | Maximum results to return |

**Example:**
```python
# List all instances
result = await registry.execute_tool("aws", "ec2_list_instances")

# List running instances in specific region
result = await registry.execute_tool(
    "aws", "ec2_list_instances",
    region="us-west-2",
    filters={"instance-state-name": "running"}
)
```

#### `ec2_start_instance`

Start an EC2 instance.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `instance_id` | `string` | Yes | - | EC2 instance ID |
| `region` | `string` | No | - | AWS region |

**Example:**
```python
result = await registry.execute_tool(
    "aws", "ec2_start_instance",
    instance_id="i-1234567890abcdef0"
)
```

#### `ec2_stop_instance`

Stop an EC2 instance.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `instance_id` | `string` | Yes | - | EC2 instance ID |
| `region` | `string` | No | - | AWS region |
| `force` | `boolean` | No | false | Force stop |

#### `ec2_describe_instance`

Get detailed information about an EC2 instance.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `instance_id` | `string` | Yes | - | EC2 instance ID |
| `region` | `string` | No | - | AWS region |

### S3 Operations

#### `s3_list_buckets`

List S3 buckets.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `max_results` | `integer` | No | - | Maximum results |

**Example:**
```python
result = await registry.execute_tool("aws", "s3_list_buckets")
```

#### `s3_list_objects`

List objects in an S3 bucket.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `bucket` | `string` | Yes | - | S3 bucket name |
| `prefix` | `string` | No | - | Object key prefix |
| `max_results` | `integer` | No | - | Maximum results |

**Example:**
```python
# List all objects in bucket
result = await registry.execute_tool(
    "aws", "s3_list_objects",
    bucket="my-bucket"
)

# List objects with prefix
result = await registry.execute_tool(
    "aws", "s3_list_objects",
    bucket="my-bucket",
    prefix="data/2024/"
)
```

#### `s3_upload`

Upload a file to S3.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `bucket` | `string` | Yes | - | S3 bucket name |
| `key` | `string` | Yes | - | Object key (path in bucket) |
| `file_path` | `string` | Yes | - | Local file path to upload |
| `metadata` | `object` | No | - | Object metadata |

**Example:**
```python
result = await registry.execute_tool(
    "aws", "s3_upload",
    bucket="my-bucket",
    key="uploads/data.csv",
    file_path="/path/to/local/data.csv",
    metadata={"author": "user", "project": "demo"}
)
```

#### `s3_download`

Download a file from S3.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `bucket` | `string` | Yes | - | S3 bucket name |
| `key` | `string` | Yes | - | Object key |
| `file_path` | `string` | Yes | - | Local file path to save |

#### `s3_delete_object`

Delete an object from S3.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `bucket` | `string` | Yes | - | S3 bucket name |
| `key` | `string` | Yes | - | Object key |

### Lambda Operations

#### `lambda_list_functions`

List Lambda functions.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `region` | `string` | No | - | AWS region |
| `max_results` | `integer` | No | - | Maximum results |

#### `lambda_invoke`

Invoke a Lambda function.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `function_name` | `string` | Yes | - | Function name or ARN |
| `payload` | `object` | No | - | JSON payload |
| `region` | `string` | No | - | AWS region |

**Example:**
```python
result = await registry.execute_tool(
    "aws", "lambda_invoke",
    function_name="my-function",
    payload={"action": "process", "data": [1, 2, 3]},
    region="us-east-1"
)
```

#### `lambda_get_logs`

Get CloudWatch logs for a Lambda function.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `function_name` | `string` | Yes | - | Function name |
| `region` | `string` | No | - | AWS region |
| `start_time` | `string` | No | - | Start time (ISO format) |
| `end_time` | `string` | No | - | End time (ISO format) |
| `limit` | `integer` | No | 100 | Number of log events |

**Example:**
```python
from datetime import datetime, timedelta

# Get logs from last hour
start = (datetime.utcnow() - timedelta(hours=1)).isoformat()

result = await registry.execute_tool(
    "aws", "lambda_get_logs",
    function_name="my-function",
    start_time=start,
    limit=50
)
```

### CloudWatch Operations

#### `cloudwatch_get_metrics`

Get CloudWatch metrics.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `namespace` | `string` | Yes | - | Metric namespace (e.g., AWS/EC2) |
| `metric_name` | `string` | Yes | - | Metric name |
| `dimensions` | `object` | No | - | Metric dimensions |
| `start_time` | `string` | No | - | Start time (ISO format) |
| `end_time` | `string` | No | - | End time (ISO format) |
| `period` | `integer` | No | 300 | Data point period in seconds |
| `region` | `string` | No | - | AWS region |

**Example:**
```python
# Get CPU utilization for an EC2 instance
result = await registry.execute_tool(
    "aws", "cloudwatch_get_metrics",
    namespace="AWS/EC2",
    metric_name="CPUUtilization",
    dimensions={"InstanceId": "i-1234567890abcdef0"},
    period=3600
)
```

### IAM Operations

#### `iam_list_users`

List IAM users.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `max_results` | `integer` | No | - | Maximum results |

#### `iam_list_roles`

List IAM roles.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `max_results` | `integer` | No | - | Maximum results |

### RDS Operations

#### `rds_describe_instances`

List RDS database instances.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `region` | `string` | No | - | AWS region |
| `max_results` | `integer` | No | - | Maximum results |

### Route53 Operations

#### `route53_list_hosted_zones`

List Route53 hosted zones.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `max_results` | `integer` | No | - | Maximum results |

### STS Operations

#### `sts_get_caller_identity`

Get current AWS identity.

**Returns:** Account ID, ARN, and UserId of the current credentials.

**Example:**
```python
result = await registry.execute_tool("aws", "sts_get_caller_identity")
# Returns:
# {
#   "Account": "123456789012",
#   "Arn": "arn:aws:iam::123456789012:user/myuser",
#   "UserId": "AIDAI..."
# }
```

## Error Handling

All tools return a standardized result dictionary:

```python
{
    "success": bool,           # True if operation succeeded
    "output": str,             # JSON-formatted output
    "data": dict,              # Structured response data
    "error": str | None,       # Error message on failure
    "count": int | None        # Number of results (where applicable)
}
```

### Common Errors

- **Invalid credentials** - Check AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
- **Insufficient permissions** - Verify IAM policies
- **Resource not found** - Check resource IDs/names
- **Region not supported** - Verify service availability in region

## Dependencies

- `oclawma>=0.1.0` - Core OCLAWMA framework
- `boto3>=1.28.0` - AWS SDK
- `pyyaml>=6.0` - YAML parsing

## Testing

```bash
# Run test suite
pytest tests/ -v

# Test with moto (AWS mock)
pytest tests/ -v --cov=src/oclawma_skill_aws
```

## Development

```bash
# Clone repository
git clone https://github.com/openclaw/oclawma-skill-aws.git
cd oclawma-skill-aws

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
black src tests
ruff check src tests
mypy src
```

## Security Notes

- Never commit AWS credentials to version control
- Use IAM roles when running on AWS infrastructure
- Follow least-privilege principle for IAM policies
- Rotate credentials regularly

## License

MIT License - see LICENSE file for details.

## Contributing

Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request
