# How to Contribute to the AWS Agent Toolkit: Bug Reports, Feature Requests, and Security Disclosures

> Contribute to the AWS Agent Toolkit project by filing bug reports, submitting feature requests, or reporting security vulnerabilities. Learn how to provide valuable feedback via GitHub issues.

- Repository: [Amazon Web Services/agent-toolkit-for-aws](https://github.com/aws/agent-toolkit-for-aws)
- Tags: how-to-guide
- Published: 2026-06-28

---

**The AWS Agent Toolkit does not accept external code contributions; instead, contribute by filing bug reports, submitting feature requests, or reporting security vulnerabilities through the official GitHub issue templates.**

The **AWS Agent Toolkit** is an open-source collection of plugins, skills, and rule files hosted in the `aws/agent-toolkit-for-aws` repository that enables AI coding agents to interact with AWS services via the **AWS MCP Server**. While the project welcomes community involvement, it currently operates under a specific contribution model that restricts direct code submissions in favor of structured feedback mechanisms. Understanding this workflow ensures your contributions reach the maintainers through the appropriate channels.

## Understanding the Contribution Model

The project maintains a strict policy regarding external contributions. According to the [`CONTRIBUTING.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/CONTRIBUTING.md) file, the repository **does not accept external code contributions** at this time. Instead, the maintainers solicit community input through three primary channels:

- **Bug reports** – Document unexpected behavior or errors in plugins, skills, or the MCP Server integration
- **Feature requests** – Propose new skills, plugin capabilities, or improvements to existing AWS service integrations  
- **Security vulnerability reports** – Disclose potential security issues through private channels rather than public issues

This model ensures that the curated set of AI agent capabilities maintains consistent quality and security standards while still incorporating community feedback.

## How to File a Bug Report

When you encounter unexpected behavior in the AWS Agent Toolkit, use the official Bug Report template to ensure maintainers can reproduce and diagnose the issue.

First, verify you are using the latest version of the plugin or skill, then search existing issues to avoid duplicates. Navigate to the bug report template at `https://github.com/aws/agent-toolkit-for-aws/issues/new?template=bug_report.yml` and provide:

- The specific plugin or skill file path (e.g., `plugins/aws-core/` or [`skills/aws-serverless.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/skills/aws-serverless.md))
- Environment details (agent type: Claude Code, Codex, Cursor, etc.)
- Steps to reproduce the issue
- Expected versus actual behavior

## How to Submit a Feature Request

New capabilities for AWS service integrations or agent skills should be submitted through the Feature Request template rather than as pull requests.

Access the template at `https://github.com/aws/agent-toolkit-for-aws/issues/new?template=feature_request.yml`. When requesting features:

- Reference specific components in the repository structure (such as the `skills/` directory or [`rules/aws-agent-rules.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/rules/aws-agent-rules.md))
- Describe the AWS service integration or use case
- Explain how the feature would benefit AI coding agents using the MCP Server

## Reporting Security Vulnerabilities

Security issues require special handling to prevent public disclosure of exploitable weaknesses.

**Do not** open a public GitHub issue for security vulnerabilities. Instead, email `aws-security@amazon.com` or use the official AWS vulnerability reporting page at `https://aws.amazon.com/security/vulnerability-reporting/`. This ensures the security team can investigate and remediate issues before public disclosure.

## Project Structure for Contributors

Understanding the repository layout helps you file precise reports that reference the correct file paths and components.

### Core Components

The repository organizes functionality around three primary concepts:

- **Plugins** – Bundled MCP Server configurations and skill sets located in `plugins/aws-core/`, `plugins/aws-agents/`, `plugins/aws-data-analytics/`, and `plugins/aws-agents-for-devsecops/`. These serve as the entry point for agents discovering AWS capabilities.
- **Skills** – Markdown-based instruction packages stored in the `skills/` directory that describe how to perform specific AWS tasks (e.g., `aws-serverless`, `cdk`, `billing-and-cost-management`).
- **Rules Files** – Project-level configuration in [`rules/aws-agent-rules.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/rules/aws-agent-rules.md) that guides agents on MCP Server usage, preferred skills, and documentation sources.

### Key Files to Reference

When contributing feedback, cite these specific files:

| File | Purpose |
|------|---------|
| [`CONTRIBUTING.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/CONTRIBUTING.md) | Official contribution policy and issue templates |
| [`README.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/README.md) | High-level project overview and quick-start guide |
| [`plugins/aws-core/README.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-core/README.md) | Core plugin installation and capabilities |
| [`rules/aws-agent-rules.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/rules/aws-agent-rules.md) | Agent behavior guidelines |
| `skills/` | Directory containing all skill definitions |

## Testing and Reproducing Issues

Before filing bug reports, verify issues using the standard installation methods documented in the source code.

### Installing the Core Plugin (Claude Code)

```text
/plugin install aws-core@claude-plugins-official
/plugin reload-plugins

```

This command installs the `aws-core` plugin from `plugins/aws-core/`, which provides the MCP Server configuration and default skill set.

### Installing the Core Plugin (Codex)

```bash
codex plugin marketplace add aws/agent-toolkit-for-aws

```

Then navigate to the Codex UI and select `/plugins → install → aws-core`.

### Adding Skills via CLI

For agents supporting the Skill CLI, install the complete skill suite:

```bash
npx skills add aws/agent-toolkit-for-aws/skills

```

This pulls every skill from the `skills/` directory into the agent's knowledge base.

### Example: Testing CloudFormation Skills

To verify skill functionality before reporting issues, test with a sandboxed script:

```python
import boto3, json, sys
cf = boto3.client('cloudformation')
with open('template.yaml') as f:
    template_body = f.read()
response = cf.create_stack(
    StackName='my-stack',
    TemplateBody=template_body,
    Capabilities=['CAPABILITY_IAM']
)
print(json.dumps(response, default=str))

```

This script executes within the MCP Server's sandboxed environment, which provides authenticated AWS API access via the `call_aws` capability.

## Summary

- **The AWS Agent Toolkit does not accept pull requests or external code patches**; all contributions must go through the issue tracking system.
- **File bugs** using the Bug Report template after verifying the issue against the latest plugin version.
- **Request features** through the Feature Request template, referencing specific components like `skills/` or `plugins/aws-core/`.
- **Report security vulnerabilities** privately via `aws-security@amazon.com`, never through public GitHub issues.
- **Reference specific file paths** such as [`CONTRIBUTING.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/CONTRIBUTING.md), [`rules/aws-agent-rules.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/rules/aws-agent-rules.md), and [`plugins/aws-core/README.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-core/README.md) when documenting issues.

## Frequently Asked Questions

### Can I submit a pull request to add new skills or plugins?

No, the AWS Agent Toolkit does not accept external code contributions, including pull requests for new skills or plugins. Instead, submit a feature request using the GitHub issue template describing the desired functionality and referencing the relevant skill area in the `skills/` directory or plugin category.

### How do I report a bug in the AWS MCP Server integration?

Use the Bug Report template at the repository's issue page. Include the specific plugin path (e.g., `plugins/aws-core/`), your agent environment (Claude Code, Codex, etc.), and reproduction steps. Ensure you are testing with the latest version installed via `/plugin install aws-core@claude-plugins-official` or the equivalent for your agent.

### What should I do if I find a security vulnerability in the agent toolkit?

Do not create a public GitHub issue. Email `aws-security@amazon.com` or use the official AWS vulnerability reporting page at `https://aws.amazon.com/security/vulnerability-reporting/` to disclose security issues privately. This allows the AWS security team to investigate and release patches before public disclosure.

### Where can I find the contribution guidelines for the AWS Agent Toolkit?

The official contribution guidelines are located in [`CONTRIBUTING.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/CONTRIBUTING.md) at the root of the `aws/agent-toolkit-for-aws` repository. This file outlines the bug report workflow, feature request process, and security reporting procedures, and explicitly states that the project does not accept external code contributions.