diff --git a/.agents/skills/docs/SKILL.md b/.agents/skills/docs/SKILL.md
index 8d074f21b..5afcd7168 100644
--- a/.agents/skills/docs/SKILL.md
+++ b/.agents/skills/docs/SKILL.md
@@ -79,6 +79,8 @@ Preferred mapping:
 Guardrails:
 
 - Do not handwrite separate Maven/Gradle dependency blocks when `dependency:` is suitable.
+- Do not replace Micronaut `snippet::` macros with direct Asciidoctor `[source]` includes or pasted code blocks just because the current examples have one language. The macro is the multi-language, source-backed contract for generated module docs.
+- Do not remove snippet callouts when touching examples. Preserve existing callout tags and callout explanations unless the underlying executable source no longer has that behavior.
 - Do not duplicate configuration property tables manually when generated references exist.
 - Keep environment-sensitive instructions explicit (for example `MICRONAUT_ENVIRONMENTS=dev`).
 - Prefer stable links to official Micronaut docs for endpoint semantics.
@@ -122,6 +124,7 @@ When finishing docs work, report:
 
 - [ ] `toc.yml` and `.adoc` changes are consistent.
 - [ ] Macros and includes follow Micronaut maintainer conventions.
+- [ ] Existing `snippet::` macros and callouts are preserved unless executable source changes require a different tagged snippet.
 - [ ] `publishGuide` and `docs` executed successfully.
 - [ ] Output and navigation verified under `build/docs/`.
 - [ ] Guidance remains maintainer-focused (not generic app docs).
diff --git a/.agents/skills/docs/references/micronaut-docs-providers.md b/.agents/skills/docs/references/micronaut-docs-providers.md
index 5a43704ab..5df9605ba 100644
--- a/.agents/skills/docs/references/micronaut-docs-providers.md
+++ b/.agents/skills/docs/references/micronaut-docs-providers.md
@@ -60,6 +60,9 @@ Maintainer guidance:
 
 - Use for examples that should stay aligned with source/test files.
 - Prefer tagged snippets for stable, focused excerpts.
+- Preserve `snippet::` macros even when a repository currently has only one language under `doc-examples/`. The macro is still the docs contract for language-aware rendering and lets the same guide continue to support future Java, Kotlin, or Groovy examples without rewriting the guide.
+- Preserve callouts attached to snippet excerpts. Callouts are part of the tutorial explanation, not disposable rendering decoration; remove them only when the referenced executable source behavior is removed or the callout is replaced with an equivalent source-backed explanation.
+- Do not convert snippet output to raw `[source,<language>]` blocks, `include::` of generated source, or pasted code as a cleanup shortcut.
 
 ## 5) `[configuration]` block processor