Merge pull request #2979 from adobe/copilot/update-markdown-best-practices

Fix checklist format, active voice, and skill routing in markdown files

Author: afranken

.claude/skills/document/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: document
-description: Generate or update project documentation. Use when asked to document code, create docs, or explain features.
+description: Generate or update project documentation. Use when asked to document code, create docs, explain features, or fix formatting, wording, or style in existing documentation files.
 ---
 
 # Documentation Skill — S3Mock
@@ -36,6 +36,6 @@ Concise, active voice. Include runnable examples (Kotlin for API, shell for CLI)
 
 ## Checklist
 
-- Verify technical accuracy against source code
-- Ensure links and code examples are valid
-- Match surrounding style and formatting
+- [ ] Verify technical accuracy against source code
+- [ ] Ensure links and code examples are valid
+- [ ] Match surrounding style and formatting

.claude/skills/implement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: implement
-description: Implement features, fix bugs, or refactor code. Use when asked to add functionality, modify code, or improve structure.
+description: Implement features, fix bugs, or refactor source code. Use when asked to add functionality, modify source code, or improve code structure. Not for documentation-only changes.
 ---
 
 # Implementation Skill — S3Mock
@@ -32,12 +32,12 @@ Follow **DTO → Store → Service → Controller** (see AGENTS.md Architecture)
 - [ ] Read root + module `AGENTS.md` (required before any other step)
 - [ ] Identify the S3 API operation ([AWS docs](https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html))
 - [ ] Review existing similar implementations
-- [ ] Run `./mvnw ktlint:format` then `./mvnw clean install`
+- [ ] Run `make format` then `make install`
 - [ ] Invoke the **`test` skill** to add/update unit and integration tests
 - [ ] Invoke the **`document` skill** to update `CHANGELOG.md`, `README.md`, and `AGENTS.md`
 
 ## Troubleshooting
 
-- **Build fails**: Check Java 25, run `./mvnw ktlint:format`
+- **Build fails**: Check Java 25, run `make format`
 - **Tests fail**: Ensure XML matches AWS API exactly — run integration tests
-- **Docker fails**: Try `./mvnw clean install -DskipDocker` to isolate
+- **Docker fails**: Try `make skip-docker` to isolate

.claude/skills/refactor/SKILL.md

@@ -33,8 +33,8 @@ Document what, why, and gotchas. Link to AWS API docs where relevant. See **[doc
 
 ## Checklist
 
-- [ ] No behavior changes — tests still pass
-- [ ] Run `./mvnw ktlint:format`
-- [ ] Comments explain *why*, not *what*
-- [ ] Public APIs have KDoc
-- [ ] Names are self-documenting
+- [ ] Verify no behavior changes — run tests
+- [ ] Run `make format`
+- [ ] Ensure comments explain *why*, not *what*
+- [ ] Add KDoc for all public APIs
+- [ ] Use self-documenting names

.claude/skills/test/SKILL.md

@@ -20,8 +20,8 @@ Read **[docs/TESTING.md](../../../docs/TESTING.md)**, **[docs/KOTLIN.md](../../.
 
 - [ ] Read `docs/TESTING.md` and root + module `AGENTS.md`
 - [ ] If existing tests have structural problems (poor naming, shared state, weak assertions), invoke the **`refactor` skill** to fix them rather than working around them
-- [ ] Tests pass locally
-- [ ] Both success and failure cases covered
-- [ ] Tests are independent (no shared state, UUID bucket names)
-- [ ] Assertions are specific
-- [ ] Run `./mvnw ktlint:format`
+- [ ] Verify tests pass locally
+- [ ] Cover both success and failure cases
+- [ ] Keep tests independent (no shared state, UUID bucket names)
+- [ ] Use specific assertions
+- [ ] Run `make format`

.github/CONTRIBUTING.md

@@ -21,17 +21,10 @@ All third-party contributions to this project must be accompanied by a signed co
 
 **Build and verify:**
 ```shell
-# Full build with Docker
-./mvnw clean install
-
-# Skip Docker (faster, for unit tests only)
-./mvnw clean install -DskipDocker
-
-# Run integration tests
-./mvnw verify -pl integration-tests
-
-# Format Kotlin code
-./mvnw ktlint:format
+make install           # Full build with Docker
+make skip-docker       # Skip Docker (faster, for unit tests only)
+make integration-tests # Run integration tests
+make format            # Format Kotlin code
 ```
 
 ## Architecture
@@ -45,8 +38,8 @@ Module-specific documentation:
 
 ## Code Style
 
-- **Kotlin**: Enforced by ktlint - run `./mvnw ktlint:format` before submitting
-- **XML/Java**: Enforced by Checkstyle - configuration in [`etc/checkstyle.xml`](../etc/checkstyle.xml)
+- **Kotlin**: Enforced by ktlint — run `make format` before submitting
+- **XML/Java**: Enforced by Checkstyle — configuration in [`etc/checkstyle.xml`](../etc/checkstyle.xml)
 - **Key conventions**: Constructor injection, data classes for DTOs, backtick test names, `val` over `var`
 - See the DO / DON'T section in [AGENTS.md](../AGENTS.md) for the full list
 

.github/PULL_REQUEST_TEMPLATE.md

@@ -9,6 +9,6 @@
 
 - [ ] I have signed the [CLA](http://adobe.github.io/cla.html).
 - [ ] I have written tests and verified that they fail without my change.
-- [ ] I have run `./mvnw ktlint:format` to fix code style.
+- [ ] I have run `make format` to fix code style.
 - [ ] I have updated `CHANGELOG.md` (if applicable).
 - [ ] I have updated documentation (if applicable).

AGENTS.md

@@ -98,10 +98,10 @@ See **[docs/TESTING.md](docs/TESTING.md)** for the full testing strategy, base c
 ## Build
 
 ```bash
-./mvnw clean install              # Full build
-./mvnw clean install -DskipDocker # Skip Docker
-./mvnw verify -pl integration-tests
-./mvnw ktlint:format
+make install              # Full build
+make skip-docker          # Skip Docker
+make integration-tests    # Run integration tests
+make format               # Format Kotlin code
 ```
 
 ## CI/CD Pipeline

Makefile

@@ -14,7 +14,7 @@
 #  limitations under the License.
 #
 
-.PHONY: build verify install sort
+.PHONY: build verify install skip-docker format integration-tests run test sort
 .DEFAULT_GOAL := build
 
 build: verify
@@ -25,5 +25,20 @@ verify:
 install:
 	./mvnw -B -V -Dstyle.color=always clean install
 
+skip-docker:
+	./mvnw -B -V -Dstyle.color=always clean install -DskipDocker
+
+format:
+	./mvnw -B -V -Dstyle.color=always ktlint:format
+
+integration-tests:
+	./mvnw -B -V -Dstyle.color=always verify -pl integration-tests
+
+run:
+	./mvnw spring-boot:run -pl server
+
+test:
+	./mvnw -B -V -Dstyle.color=always test -pl server
+
 sort:
 	./mvnw -B -V -Dstyle.color=always com.github.ekryd.sortpom:sortpom-maven-plugin:sort

README.md

@@ -484,17 +484,13 @@ graph LR
 
 **Build:**
 ```shell
-# Full build with Docker
-./mvnw clean install
-
-# Skip Docker build
-./mvnw clean install -DskipDocker
+make install       # Full build with Docker
+make skip-docker   # Skip Docker build
 ```
 
 **Run from source:**
 ```shell
-# As Spring Boot application
-./mvnw spring-boot:run -pl server
+make run           # As Spring Boot application
 
 # As Docker container
 ./mvnw clean package -pl server -am -DskipTests
@@ -503,7 +499,7 @@ docker run -p 9090:9090 -p 9191:9191 adobe/s3mock:latest
 
 **Run integration tests:**
 ```shell
-./mvnw verify -pl integration-tests
+make integration-tests
 ```
 
 **Technology:**

docs/TESTING.md

@@ -80,11 +80,11 @@ See **[docs/KOTLIN.md](KOTLIN.md)** for Kotlin naming conventions (backtick test
 ## Running Tests
 
 ```bash
-./mvnw test -pl server                                          # Unit tests only
-./mvnw verify -pl integration-tests                             # All integration tests
-./mvnw verify -pl integration-tests -Dit.test=BucketIT          # Specific class
-./mvnw verify -pl integration-tests -Dit.test=BucketIT#shouldCreateBucket  # Specific method
-./mvnw test -pl server -DskipDocker                             # Skip Docker
+make test                                                                    # Unit tests only
+make integration-tests                                                       # All integration tests
+./mvnw verify -pl integration-tests -Dit.test=BucketIT                      # Specific class
+./mvnw verify -pl integration-tests -Dit.test=BucketIT#shouldCreateBucket   # Specific method
+./mvnw test -pl server -DskipDocker                                         # Skip Docker
 ```
 
 > Integration tests require Docker to be running.
@@ -98,8 +98,8 @@ See **[docs/KOTLIN.md](KOTLIN.md)** for Kotlin naming conventions (backtick test
 
 ## Checklist
 
-- [ ] Tests pass locally
-- [ ] Both success and failure cases covered
-- [ ] Tests are independent (no shared state, UUID bucket names)
-- [ ] Assertions are specific
-- [ ] Run `./mvnw ktlint:format`
+- [ ] Verify tests pass locally
+- [ ] Cover both success and failure cases
+- [ ] Keep tests independent (no shared state, UUID bucket names)
+- [ ] Use specific assertions
+- [ ] Run `make format`