Merge pull request #2978 from adobe/copilot/add-cross-references-instructions

Cross-reference refactor, test, and document skills from implement; add refactor guidance to test and review

Author: afranken

.claude/skills/implement/SKILL.md

@@ -5,7 +5,18 @@ description: Implement features, fix bugs, or refactor code. Use when asked to a
 
 # Implementation Skill — S3Mock
 
-Read `AGENTS.md` (root + relevant module) before making changes — especially DO/DON'T, code style, and architecture sections.
+> **Before making any changes**: Read `AGENTS.md` (root + relevant module). These files are the authoritative source for architecture, conventions, and guardrails — they must be read, not skipped.
+
+## Skill Workflow
+
+A complete feature implementation requires these skills — run them in sequence:
+
+1. **`refactor` skill** — if nearby existing code, tests, or configuration would benefit from cleanup *before* adding new code, do it first rather than working around it
+2. **`implement` skill** (this skill) — write the production code
+3. **`test` skill** — add/update unit and integration tests (`*Test.kt`, `*IT.kt`)
+4. **`document` skill** — update `CHANGELOG.md`, `README.md`, and `AGENTS.md` where applicable
+
+> **Prefer refactoring over workarounds**: if you find yourself adding complexity to work around existing code, stop and invoke the `refactor` skill to clean it up first.
 
 ## Implementation Flow for New S3 Operations
 
@@ -18,12 +29,12 @@ Follow **DTO → Store → Service → Controller** (see AGENTS.md Architecture)
 
 ## Checklist
 
-- [ ] Read root + module `AGENTS.md`
+- [ ] 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`
-- [ ] Add/update unit tests (`*Test.kt`) and integration tests (`*IT.kt`)
-- [ ] Update `CHANGELOG.md` and operations table in `README.md` if applicable
+- [ ] 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
 

.claude/skills/review/SKILL.md

@@ -48,7 +48,7 @@ See **[docs/KOTLIN.md](../../../docs/KOTLIN.md)** for the full list of idioms an
 Structure feedback as:
 
 - **Must fix** — blocks merge (correctness issues, convention violations, missing tests)
-- **Should fix** — strongly recommended (idiom improvements, missing docs)
+- **Should fix** — strongly recommended (idiom improvements, missing docs); suggest invoking the **`refactor` skill** for purely readability/style improvements rather than asking the author to add more code
 - **Nit** — optional style suggestions
 
 For each finding, reference the specific AGENTS.md rule or AWS API doc where applicable.

.claude/skills/test/SKILL.md

@@ -19,6 +19,7 @@ Read **[docs/TESTING.md](../../../docs/TESTING.md)**, **[docs/KOTLIN.md](../../.
 ## Checklist
 
 - [ ] 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)