diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
deleted file mode 100644
index 7abbcca76..000000000
--- a/.github/CONTRIBUTING.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# Contributing to Shadow Gradle Plugin
-
-Thank you for considering contributing
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..83cc35c3b
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,9 @@
+# Agent Guidelines
+
+To understand how to contribute code, format commits, and run tests for this repository, 
+please refer to the [CONTRIBUTING.md](./CONTRIBUTING.md) file.
+
+**Instructions for AI Agents:**
+1. Read `CONTRIBUTING.md` before suggesting any code changes.
+2. Adhere to the coding standards and PR templates defined therein.
+3. Follow the environment setup steps to verify your proposed fixes.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 000000000..bab7e4341
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,72 @@
+# Contributing to Shadow
+
+Thank you for considering contributing to the Shadow Gradle plugin! This document provides guidelines and information to help you get started.
+
+## Development Commands
+
+### Code Style
+
+Shadow uses [Spotless](https://github.com/diffplug/spotless) to maintain consistent code formatting.
+
+- **Check code style**: `./gradlew spotlessCheck`
+- **Format code**: `./gradlew spotlessFormat`
+
+Please ensure your code is properly formatted before submitting a pull request.
+
+### Testing
+
+Shadow has multiple test suites to ensure code quality:
+
+- **Unit tests**: `./gradlew test`
+- **Documentation tests**: `./gradlew documentTest` - Tests code snippets in the `./docs` directory
+- **Functional/Integration tests**: `./gradlew functionalTest`
+
+Make sure all tests pass before submitting your changes.
+
+### API Compatibility
+
+Shadow uses Kotlin's [binary compatibility validator](https://kotlinlang.org/docs/gradle-binary-compatibility-validation.html) to track public API changes.
+
+- **Check API dumps**: `./gradlew checkKotlinAbi`
+- **Update API dumps**: `./gradlew updateKotlinAbi`
+
+If you add or modify public APIs, you'll need to update the API dump files.
+
+### Linting
+
+Shadow uses [Android Lint](https://developer.android.com/studio/write/lint) to catch potential issues.
+
+- **Run lint checks**: `./gradlew lint`
+- **Update lint baseline**: `./gradlew updateLintBaseline`
+
+## Contribution Guidelines
+
+### Fixing Issues
+
+When fixing bugs or issues:
+
+1. Ensure all existing tests pass
+2. Add regression tests that verify the fix for the reported issue
+3. Run the full test suite to ensure no unintended side effects
+4. Update documentation if the fix changes behavior
+
+### Adding New Features or APIs
+
+When adding new features or public APIs:
+
+1. Ensure proper visibility modifiers are used
+2. All public APIs must be documented with KDoc comments
+3. Run `./gradlew updateKotlinAbi` to update the API dump files
+4. Add appropriate tests for the new functionality
+5. Update the documentation in the `./docs` directory if applicable
+
+### Before Submitting a Pull Request
+
+1. Run `./gradlew spotlessFormat` to format your code
+2. Run `./gradlew spotlessCheck` to verify formatting
+3. Run all test suites: `./gradlew test documentTest functionalTest`
+4. Run `./gradlew checkKotlinAbi` to ensure API compatibility
+5. Run `./gradlew lint` to check for potential issues
+6. Optionally, run `./gradlew build` to run compilation, tests, and standard verification tasks configured for the project
+7. Ensure your commit messages are clear and descriptive
+