{"owner":"micronaut-projects","repo":"micronaut-core","hasSkills":true,"totalSkillsCount":23,"totalTokensCount":28350,"categories":["anthropic-skill","root-instruction"],"hasMcp":false,"mcpConfig":null,"found":[".agents/skills/gradle/SKILL.md",".agents/skills/agent-md-refactor/SKILL.md",".agents/skills/skill-creator/SKILL.md",".agents/skills/docs/SKILL.md",".agents/skills/guides/SKILL.md",".agents/skills/coding/SKILL.md",".agents/skills/micronaut-sourcegen/SKILL.md",".agents/skills/skill-creator/references/spec-checklist.md",".agents/skills/skill-creator/references/research-synthesis.md",".agents/skills/skill-creator/references/templates.md","inject/AGENTS.md","core-processor/AGENTS.md",".agents/skills/micronaut-sourcegen/references/sourcegen-cookbook.md",".agents/skills/guides/references/guide-authoring-conventions.md",".agents/skills/guides/references/guide-inventory.md",".agents/skills/guides/references/pdf-export-and-pr.md",".agents/skills/guides/references/repository-workflow.md",".agents/skills/gradle/references/gradle-best-practices.md",".agents/skills/gradle/references/micronaut-build-plugins.md",".agents/skills/docs/references/control-panel-patterns.md",".agents/skills/docs/references/micronaut-docs-providers.md",".agents/skills/agent-md-refactor/references/examples-and-anti-patterns.md",".agents/skills/agent-md-refactor/references/refactor-playbook.md"],"skills":{".agents/skills/gradle/SKILL.md":"---\nname: gradle\ndescription: Execute Gradle maintainer operations for Micronaut repositories using micronaut-build internals and modern Gradle best practices. Use when users ask to diagnose build failures, maintain BOM/version catalogs, manage publishing/signing, enforce binary compatibility, or debug micronaut-build plugin behavior.\nlicense: Apache-2.0\ncompatibility: Micronaut framework repositories in micronaut-projects using micronaut-build plugins\nmetadata:\n author: Álvaro Sánchez-Mariscal\n version: \"1.0.0\"\n gradle-major-version: \"9.x\"\nmcp:\n maven-tools:\n command: docker\n args: [\"run\", \"-i\", \"--rm\", \"arvindand/maven-tools-mcp:latest\"]\n---\n\n# Gradle (Micronaut Committer)\n\nUse this skill for Micronaut framework maintainer work. Do not default to end-user app guidance.\n\n## Goal\n\nApply correct, source-backed Gradle changes in Micronaut repositories, using the `micronaut-build` plugin contracts and current Gradle best practices.\n\nCurrent coverage target: repositories on Gradle major line `9.x`.\n\nFor dependency-intelligence tasks (version freshness, stability, release cadence, CVE/license checks), use the embedded `maven-tools` MCP via `skill_mcp`.\n\n## Procedure\n\n1. Identify build shape and active plugins.\n2. Map requested work to exact `micronaut-build` plugin behavior.\n3. Execute minimal maintainer-safe change.\n4. Verify with targeted and aggregate Gradle tasks.\n\n### 1) Establish build shape first\n\n- Inspect `settings.gradle` or `settings.gradle.kts` for settings plugins and dependency management.\n- Confirm `io.micronaut.build.shared.settings` is present unless the repository intentionally diverged.\n- Validate settings-scoped plugins (especially Develocity wiring) in `settings.gradle(.kts)`, not in project `build.gradle(.kts)`.\n- Confirm root build applies `io.micronaut.build.internal.parent` for standard aggregation behavior.\n- Inspect root and impacted module build files for applied plugin IDs and `micronautBuild` extension usage.\n- Inspect `buildSrc`/convention plugins before modifying module build scripts.\n- Inspect `gradle.properties` and `gradle/*.versions.toml` for version source and overrides.\n- Treat module directory names and Gradle project paths separately; if standardized names are enabled, use `:micronaut-*` paths for task targeting.\n- If module paths are unclear, run `./gradlew projects`.\n- If dependency resolution is involved, capture `dependencyInsight` before changing files.\n\n### 2) Use source-of-truth plugin contracts\n\n- Use `references/micronaut-build-plugins.md` as the authoritative plugin behavior map.\n- Treat `micronaut-build` source as primary truth. Its README may be outdated.\n- Remember default plugin IDs are internal: `io.micronaut.build.internal.`.\n- Important exception: `io.micronaut.build.shared.settings`.\n\n### 3) Execute maintainer workflows\n\n- **Build failures**: reproduce with minimal task path, then expand to module `check`, then root validation.\n- **Catalog/version updates**: use plugin-provided workflows (`updateVersionCatalogs`, `useLatestVersions`) where available.\n- **Catalog imports**: prefer `micronautBuild { importMicronautCatalog() }` and alias-specific imports over ad hoc BOM wiring when repository conventions use settings extension catalog import.\n- **Dependency intelligence**: use the `maven-tools` MCP for latest stable versions, upgrade comparisons, and dependency health signals before changing catalogs or BOM constraints.\n- **Dependency scope hygiene**: choose `api` only for public API surface; use `implementation` for internals; use `compileOnly`/`runtimeOnly` intentionally.\n- **BOM/publishing**: verify BOM generation, inlining behavior, publication metadata, and signing gates.\n- **Binary compatibility**: keep baseline discovery and accepted API changes explicit; never silently suppress regressions.\n- **Docs/quality**: treat root-only aggregator plugins and docs pipelines as first-class checks.\n- **Layering**: prefer convention plugin changes (`buildSrc`) over duplicating logic in many module build files.\n\n### 4) Verify before completion\n\n- Run at least one targeted task and one aggregate task:\n - `./gradlew ::check`\n - `./gradlew check`\n- For maintainer pipelines, include docs and style gates where applicable:\n - `./gradlew check docs`\n - `./gradlew spotlessApply spotlessCheck`\n- For API-affecting changes, run compatibility checks:\n - `./gradlew japiCmp`\n- For newly added published modules, define when binary compatibility checks start in module build logic (example):\n\n```kotlin\nmicronautBuild {\n binaryCompatibility.enabledAfter(\"2.0.0\")\n}\n```\n\n- Use the repository's intended first compatible release version instead of blindly reusing `2.0.0`.\n- Add focused diagnostics when needed:\n - `./gradlew dependencyInsight --configuration --dependency `\n - `./gradlew --scan `\n- Report exact commands and outcomes.\n\n## Guardrails\n\n- Do not use `enforcedPlatform` when plugin logic explicitly forbids it.\n- Do not bypass Micronaut version mismatch checks except intentional development-version flows.\n- Do not apply root-only plugins to subprojects.\n- Do not replace framework maintainer workflows with generic app-centric shortcuts.\n\n## Best Practices\n\nUse `references/gradle-best-practices.md` for operational standards on:\n\n- configuration and build cache behavior,\n- provider/lazy configuration patterns,\n- toolchains and reproducibility,\n- secure publishing and dependency verification,\n- CI reliability.\n\n## Examples\n\n- \"Diagnose why micronaut-core version mismatch fails on compileClasspath.\"\n- \"Update version catalogs safely and apply latest allowed minor versions.\"\n- \"Fix Sonatype release pipeline behavior for a non-snapshot release.\"\n- \"Investigate binary compatibility failure and validate accepted changes file usage.\"\n\n## Validation Checklist\n\n- [ ] Active plugins identified from build files.\n- [ ] Decisions mapped to `micronaut-build` source behavior.\n- [ ] Changes align with maintainer workflows.\n- [ ] Verification tasks run and outcomes captured.\n- [ ] No end-user-only Gradle guidance substituted for framework operations.\n\n## References\n\n- `references/micronaut-build-plugins.md`\n- `references/gradle-best-practices.md`\n",".agents/skills/agent-md-refactor/SKILL.md":"---\nname: agent-md-refactor\ndescription: Refactor oversized agent instruction files into a progressive-disclosure structure. Use when users ask to split AGENTS.md/CLAUDE.md/COPILOT.md, reduce instruction bloat, or organize guidance into linked topic files.\nlicense: Apache-2.0\ncompatibility: Repositories using markdown instruction files such as AGENTS.md, CLAUDE.md, or COPILOT.md\nmetadata:\n author: Álvaro Sánchez-Mariscal\n version: \"1.0.0\"\n---\n\n# Agent MD Refactor\n\nRefactor monolithic instruction files into a compact root file plus linked topic files.\nKeep this file focused on execution flow and load detailed templates/examples from references.\n\n## Goal\n\nDeliver a maintainable instruction system with:\n\n- a minimal root instruction file containing only universal guidance,\n- linked topic files for detailed rules,\n- contradictions resolved and vague/redundant rules removed.\n\n## Trigger Examples\n\nShould trigger:\n\n- \"Refactor this AGENTS.md to use progressive disclosure.\"\n- \"Split my CLAUDE.md into focused instruction files.\"\n- \"My instruction file is too long, reorganize it.\"\n\nShould not trigger:\n\n- \"Explain what AGENTS.md is.\"\n- \"Fix one typo in CLAUDE.md.\"\n- \"Write a brand-new coding standard from scratch.\"\n\nMore examples: [examples-and-anti-patterns](references/examples-and-anti-patterns.md).\n\n## Procedure\n\n1. Inventory instruction sources (`AGENTS.md`, `CLAUDE.md`, `COPILOT.md`, related guidance docs).\n2. Detect contradictions and resolve by repository precedence.\n3. Keep only root-level essentials in the root instruction file.\n4. Group remaining content into 3-8 linked topic files with clear names.\n5. Remove non-actionable, redundant, and outdated directives.\n6. Validate links, coverage, and consistency before completion.\n\nDetailed step playbook: [refactor-playbook](references/refactor-playbook.md).\n\n## Inputs\n\n- Root instruction file path(s)\n- Existing repository conventions (commands, toolchain, style)\n- User constraints (must-keep rules, preferred layout)\n\n## Outputs\n\n- Refactored root instruction file (minimal, universal guidance)\n- Topic files with detailed rules\n- List of removed/merged rules with rationale\n- Notes on contradiction handling\n\n## Edge Cases\n\n- If rule precedence is impossible to infer, request one targeted user decision.\n- If multiple files repeat the same rule, keep one canonical source and replace others with links.\n- If the instruction file is already concise, avoid unnecessary splitting.\n- Use relative markdown links for portability.\n\n## Validation Checklist\n\n- [ ] Frontmatter is valid YAML and `name` matches directory.\n- [ ] Description states capability and usage triggers.\n- [ ] Root file contains only universal instructions.\n- [ ] Topic files are self-contained and linked from root.\n- [ ] Contradictions are resolved or explicitly called out.\n- [ ] Vague/default/redundant directives are removed or rewritten.\n- [ ] Relative links resolve.\n\n## References\n\n- [Refactor playbook](references/refactor-playbook.md)\n- [Examples and anti-patterns](references/examples-and-anti-patterns.md)\n",".agents/skills/skill-creator/SKILL.md":"---\nname: skill-creator\ndescription: Create new Agent Skills or improve existing ones in an agent-agnostic way. Use when users ask to build, refactor, validate, or package skills compatible with the Agent Skills specification and the skills CLI ecosystem.\nlicense: MIT\ncompatibility: Compatible with Agent Skills spec and skill directories such as .agents/skills or equivalent agent-specific skill paths.\nmetadata:\n author: local\n version: \"1.0.0\"\n---\n\n# Skill Creator\n\nCreate and refine skills that work across agents implementing the Agent Skills specification.\n\nUse imperative instructions. Keep the process deterministic where possible. Keep the skill output portable.\n\n## Objectives\n\n1. Produce a valid skill with a correct `SKILL.md` frontmatter and useful body instructions.\n2. Keep the skill agent-agnostic unless the user explicitly requests agent-specific behavior.\n3. Apply progressive disclosure so only essential content stays in `SKILL.md`.\n4. Validate structure and naming before declaring completion.\n\n## Workflow\n\n### 1) Identify intent and scope\n\nDetermine whether the user wants one of these outcomes:\n\n- New skill from scratch\n- Update an existing skill\n- Improve trigger quality (`description` tuning)\n- Add reusable resources (`scripts/`, `references/`, `assets/`)\n\nExtract known constraints from conversation context first. Only ask for missing details that materially change implementation.\n\n### 2) Gather concrete examples\n\nCollect at least 2 realistic user prompts that should trigger the target skill. Also collect at least 2 near-miss prompts that should not trigger it.\n\nUse these examples to decide:\n\n- Required workflow steps\n- Output format expectations\n- Edge cases to handle\n- Whether deterministic scripts are needed\n\n### 3) Design the skill anatomy\n\nCreate a minimal structure first:\n\n```text\n/\n└── SKILL.md\n```\n\nAdd optional directories only when justified:\n\n- `scripts/` for deterministic or repeated operations\n- `references/` for detailed docs, schemas, and long procedures\n- `assets/` for templates and static resources used in outputs\n\n### 4) Author `SKILL.md` frontmatter\n\nSet required fields:\n\n- `name`: lowercase, digits, hyphens; matches folder name\n- `description`: what the skill does and when to use it\n\nCommon optional fields include `license`, `compatibility`, `metadata`, and `allowed-tools`. Additional frontmatter keys (for example, MCP or tooling configuration) are allowed when supported by the Agent Skills spec/validator, and may be nested under `metadata` when appropriate.\n\nDescription guidance:\n\n- Include both capability and trigger cues\n- Avoid vague phrases like \"helps with X\"\n- Prefer concrete contexts and user-language synonyms\n\n### 5) Author `SKILL.md` body\n\nStructure the body for execution, not marketing:\n\n1. Goal and success criteria\n2. Step-by-step operating procedure\n3. Input/output expectations\n4. Error handling and edge cases\n5. Examples\n6. Validation checklist\n\nWrite in imperative style. Explain why non-obvious constraints matter.\n\n### 6) Apply progressive disclosure\n\nKeep `SKILL.md` concise. Move large or specialized content into `references/` and link to it from `SKILL.md`.\n\nIf the skill spans multiple variants, separate variant details into dedicated reference files and keep variant-selection logic in `SKILL.md`.\n\n### 7) Validate and harden\n\nRun a final compatibility pass:\n\n- Frontmatter parses as valid YAML\n- `name` complies with spec constraints and folder match\n- `description` is explicit about trigger contexts\n- Relative file references resolve\n- Optional scripts are executable and documented\n- Language is agent-neutral and avoids vendor lock-in\n\nIf `skills-ref` is available, run:\n\n```bash\nskills-ref validate ./\n```\n\nIf the skills CLI is available, verify discovery from the repo root:\n\n```bash\nnpx skills list\n```\n\n## Agent-Agnostic Rules\n\n- Do not require a specific model vendor or proprietary UI affordance.\n- Do not rely on agent-only file paths when portable paths exist.\n- Do not reference unavailable tools as mandatory.\n- Prefer open, portable commands and plain Markdown guidance.\n\n## Safety and integrity\n\n- Refuse to create skills intended for malware, exploitation, data exfiltration, or unauthorized access.\n- Keep behavior aligned with user intent; avoid hidden actions.\n\n## Completion criteria\n\nA skill-creation task is complete only when all are true:\n\n1. Skill folder exists in the requested location.\n2. `SKILL.md` is valid and complete.\n3. Optional resources are present only if needed.\n4. Validation checks pass or limitations are explicitly reported.\n\n## References\n\n- See `references/spec-checklist.md` for implementation rules distilled from the spec.\n- See `references/templates.md` for copy-ready scaffolds.\n- See `references/research-synthesis.md` for design rationale from cross-source research.\n",".agents/skills/docs/SKILL.md":"---\nname: docs\ndescription: Write and maintain Micronaut Framework module guides for micronaut-projects repositories. Use when users ask to add or update AsciiDoc guide sections, edit guide toc.yml, apply Micronaut docs macros, or fix docs build/publishing tasks.\nlicense: Apache-2.0\ncompatibility: Micronaut framework repositories in micronaut-projects generated from micronaut-project-template\nmetadata:\n author: Álvaro Sánchez-Mariscal\n version: \"1.0.0\"\n---\n\n# Docs (Micronaut Maintainer)\n\nUse this skill for maintainer-facing guide work in Micronaut framework repositories. Do not default to end-user application documentation advice.\n\n## Goal\n\nImplement source-backed documentation changes in `src/main/docs/guide`, keep `toc.yml` and content in sync, and validate with the Gradle docs pipeline used across `micronaut-projects` modules.\n\n## Procedure\n\n1. Confirm repository docs layout and build tasks.\n2. Plan `toc.yml` and `.adoc` updates in lockstep.\n3. Apply Micronaut docs macro conventions used by maintainers.\n4. Prefer generated configuration property references over manual tables.\n5. Build and validate `publishGuide` and `docs` outputs.\n\n### 1) Confirm docs layout and build tasks\n\n- Check `src/main/docs/guide/toc.yml` first.\n- List relevant guide files under `src/main/docs/guide/**/*.adoc`.\n- If examples are involved, inspect `doc-examples/` (if present) and plan snippet tags from executable sources.\n- If assets are involved, keep images in `src/main/docs/resources/img/`.\n- Confirm standard commands from `CONTRIBUTING.md`:\n - `./gradlew publishGuide` (or `./gradlew pG`) for guide assembly.\n - `./gradlew docs` for guide + API docs assembly.\n- If repository layout diverges from template conventions, follow local conventions and explicitly report the divergence.\n\n### 2) Keep `toc.yml` and files in lockstep\n\nTreat `src/main/docs/guide/toc.yml` as navigation source of truth.\n\nRules:\n\n1. Every visible section must exist in `toc.yml`.\n2. Every `toc.yml` entry must resolve to a real `.adoc` path.\n3. Preserve section order unless the request explicitly changes navigation.\n4. Use nested sections for grouped topics when needed.\n\nExample nested pattern:\n\n```yaml\ncontrolPanels:\n title: Available Control Panels\n builtIn: Built-in\n management: Management\n```\n\nThis maps to:\n\n- `src/main/docs/guide/controlPanels.adoc`\n- `src/main/docs/guide/controlPanels/builtIn.adoc`\n- `src/main/docs/guide/controlPanels/management.adoc`\n\n### 3) Apply Micronaut docs macro conventions\n\nUse docs macros registered by `micronaut-build` (`DocsExtensionRegistry`) and maintained for framework guides.\n\nPreferred mapping:\n\n| Need | Preferred pattern |\n|---|---|\n| Dependency instructions | `dependency:group:artifact[scope=...]` |\n| Source sample synchronized with test suites | `snippet::path/to/File.ext[tags=...]` |\n| Multi-format configuration snippets | `[configuration]` listing blocks |\n| Configuration properties reference | `include::{includedir}configurationProperties/.adoc[]` |\n| Shell commands | `[source,bash]` blocks |\n| Repository/release links | `https://github.com/{githubSlug}` and `/releases` links |\n\nGuardrails:\n\n- Do not handwrite separate Maven/Gradle dependency blocks when `dependency:` is suitable.\n- 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.\n- 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.\n- Do not duplicate configuration property tables manually when generated references exist.\n- Keep environment-sensitive instructions explicit (for example `MICRONAUT_ENVIRONMENTS=dev`).\n- Prefer stable links to official Micronaut docs for endpoint semantics.\n\n### 4) Use generated configuration property references correctly\n\n- `micronaut-docs` provides `AsciiDocPropertyReferenceWriter`, which generates AsciiDoc property fragments from configuration metadata.\n- Micronaut docs build wiring consumes those fragments via `{includedir}configurationProperties/...` includes.\n- Prefer includes over hand-maintained property tables.\n\nSee `references/micronaut-docs-providers.md` for confirmed provider/macro details and source locations.\n\n### 5) Build and validate documentation\n\nFrom repository root, run:\n\n```bash\n./gradlew publishGuide\n./gradlew docs\n```\n\nValidation checklist:\n\n1. Commands exit with code `0`.\n2. Output exists under `build/docs/`.\n3. Updated sections appear in navigation and render without missing includes.\n4. Added images/links resolve.\n\nIf `publishGuide` passes but `docs` fails, fix the failing stage and rerun both commands.\n\n## Maintainer Delivery Contract\n\nWhen finishing docs work, report:\n\n1. Exact changed files (`.adoc`, `toc.yml`, docs resources).\n2. Which conventions were applied (`dependency:`, `snippet::`, `[configuration]`, generated property includes).\n3. Build commands run and outcomes.\n4. Any repo-specific divergences or follow-ups.\n\n## Validation Checklist\n\n- [ ] `toc.yml` and `.adoc` changes are consistent.\n- [ ] Macros and includes follow Micronaut maintainer conventions.\n- [ ] Existing `snippet::` macros and callouts are preserved unless executable source changes require a different tagged snippet.\n- [ ] `publishGuide` and `docs` executed successfully.\n- [ ] Output and navigation verified under `build/docs/`.\n- [ ] Guidance remains maintainer-focused (not generic app docs).\n\n## References\n\n- `references/micronaut-docs-providers.md`\n- `references/control-panel-patterns.md`\n- `CONTRIBUTING.md`\n- `src/main/docs/guide/toc.yml`\n",".agents/skills/guides/SKILL.md":"---\nname: guides\ndescription: Create or update standalone Micronaut Guides in micronaut-projects/micronaut-guides, including topic discovery, guide authoring, validation, PDF export, and pull request handoff. Use for requests to create a Micronaut Guide, add a guide to micronaut-guides, author a tutorial for a Micronaut module, or prepare a guide PR with PDF.\nlicense: Apache-2.0\ncompatibility: Micronaut Guides repository and Micronaut repositories that need standalone tutorial PRs\nmetadata:\n author: Micronaut Agent Company\n version: \"1.0.0\"\n---\n\n# Guides (Micronaut Maintainer)\n\nUse this skill for standalone tutorial work in `micronaut-projects/micronaut-guides`. Start from the caller's local Micronaut repository to understand the API, module, or behavior being taught, then do the guide implementation in a current clone of `micronaut-guides`.\n\nDo not use this skill for ordinary module documentation under `src/main/docs/guide`; use the `docs` skill for that work. Do not use it for generic non-Micronaut tutorials.\n\n## Goal\n\nProduce a reviewable pull request against `micronaut-projects/micronaut-guides` with source-backed guide content, validation evidence, and a PDF export of the rendered guide page for maintainers.\n\n## Procedure\n\n1. Define the topic from the local repository.\n2. Refresh upstream `micronaut-guides` and deduplicate against existing guides.\n3. Inspect current repository conventions before writing.\n4. Author the smallest correct guide change.\n5. Validate the guide and render the page.\n6. Export a PDF and prepare the PR handoff.\n\n### 1) Define the Topic\n\n- Identify the exact Micronaut feature, module, API, integration, or migration path the guide should teach.\n- Read the local implementation, tests, module docs, and examples that prove the behavior.\n- Decide the target reader task in one sentence, for example: \"Use Micronaut Serialization with a custom serializer in a controller response.\"\n- Prefer a runnable application and tests over prose-only explanation.\n\n### 2) Refresh and Deduplicate\n\nWork from current upstream facts, not this skill's snapshot:\n\n```bash\ngit clone https://github.com/micronaut-projects/micronaut-guides.git\ncd micronaut-guides\ngit fetch origin\ngit switch master\ngit pull --ff-only\n```\n\nBefore creating a new guide, inventory `guides/*/metadata.json` and nearby guide source. Check titles, slugs, tags, categories, `apps`, `base`, `publish`, and guide bodies for duplicates or near-duplicates. Treat `publish: false` guides as base or partial guides, not public topics, but inspect them when a new guide could reuse them.\n\nIf an existing guide already teaches the task, update that guide instead of creating a duplicate. If overlap is ambiguous, stop and ask for maintainer direction.\n\n### 3) Inspect Current Conventions\n\nAlways read these current upstream files before editing:\n\n- `README.md`\n- `build.gradle`\n- `buildSrc/src/main/java/io/micronaut/guides/core/Guide.java`\n- `buildSrc/src/main/java/io/micronaut/guides/Category.java`\n- `buildSrc/src/main/resources/guide-metadata.schema.json`\n- Nearby guides in the same topic family\n\nUse `references/repository-workflow.md` for clone, branch, build-output, task naming, and validation details. Use `references/guide-authoring-conventions.md` for metadata, directory layout, macros, placeholders, and base-guide rules.\n\n### 4) Author the Guide\n\n- Choose a kebab-case slug that matches the reader task and does not collide with existing guide directories.\n- Create or update `guides//metadata.json`.\n- Use one root AsciiDoc file named `.adoc` unless current metadata conventions require `asciidoctor`.\n- Put source under the expected Java, Groovy, and Kotlin layout when the guide supports multiple languages. If the feature is language-specific, set `languages` in metadata and explain why in the PR.\n- For single-app guides, use an app named `default`. For multi-app guides, mirror existing app-directory patterns and declare each app in metadata.\n- Use validated guide macros such as `common:`, `source:`, `resource:`, `test:`, `testResource:`, `callout:`, `external:`, `dependency:`, and `guideLink:` instead of manually duplicating generated paths.\n- Use conditional blocks such as `:exclude-for-languages:` and `:exclude-for-build:` for language-specific or build-tool-specific text.\n- Keep secrets out of source, generated code, rendered HTML, and the PDF. Use placeholders and documented cleanup steps for cloud resources.\n\n### 5) Validate\n\nConvert the guide slug from kebab-case to lowerCamelCase for dynamic tasks:\n\n```bash\n./gradlew Build\n./gradlew RunTestScript\n```\n\nFor broad validation or shared infrastructure changes, run:\n\n```bash\n./gradlew build\n```\n\nGenerated applications are under `build/code`. Rendered HTML and site assets are under `build/dist`. For cloud, credentialed, or cost-incurring guides, do not run provisioning commands without explicit confirmation; document skipped validation and the reason.\n\n### 6) Export PDF and Handoff\n\nAfter rendering, export the reviewed HTML page to PDF. Prefer a headless browser export when available, and fall back to a manual browser \"Print to PDF\" export when needed. Keep the PDF as local review evidence or attach it to the PR; do not commit generated PDFs unless maintainers explicitly request that.\n\nThe PR body must include:\n\n- Guide slug and user-facing task.\n- Files changed.\n- Commands run and outcomes.\n- Rendered HTML path inspected.\n- PDF filename and whether it is attached or linked.\n- Any skipped validation, cloud costs, credentials, or cleanup notes.\n\nSee `references/pdf-export-and-pr.md` for the export workflow and PR checklist.\n\n## Security Guardrails\n\n- Never commit secrets, tokens, local credentials, cloud account identifiers, `.env` files, or generated PDFs containing private data.\n- Ask before running commands that provision cloud resources or incur cost.\n- Prefer sample placeholders for credentials and explain cleanup for created resources.\n- Scrub screenshots, HTML, logs, and PDFs before attaching them to a PR.\n- Do not add custom Starter features, dependencies, or buildSrc changes unless the guide topic requires them and nearby guide conventions support the change.\n\n## Examples\n\nUse this skill for:\n\n- \"Create a Micronaut Guide for the new serialization feature.\"\n- \"Add a guide to `micronaut-guides` for this module.\"\n- \"Author a tutorial for Micronaut Data's new repository behavior.\"\n- \"Prepare a guide PR with the rendered PDF.\"\n\nDo not use this skill for:\n\n- \"Update `src/main/docs/guide/toc.yml` in this module.\"\n- \"Fix the release history page in this repository.\"\n- \"Write a generic blog post about Java.\"\n\n## Validation Checklist\n\n- [ ] Current `micronaut-guides` was cloned or fetched before writing.\n- [ ] Existing guide titles, slugs, tags, categories, and `publish: false` bases were checked for duplicates.\n- [ ] `README.md`, metadata schema, category source, and nearby guide examples were inspected.\n- [ ] Guide source uses current metadata, directory, macro, language, and build-tool conventions.\n- [ ] Single-guide build and test-script tasks were run, or skipped with a specific reason.\n- [ ] Rendered HTML was inspected under `build/dist`.\n- [ ] PDF export was created and named in the PR handoff.\n- [ ] PR handoff explains changed files, validation, skipped steps, and any security-sensitive handling.\n\n## References\n\n- `references/repository-workflow.md`\n- `references/guide-authoring-conventions.md`\n- `references/guide-inventory.md`\n- `references/pdf-export-and-pr.md`\n",".agents/skills/coding/SKILL.md":"---\nname: coding\ndescription: Implement and review Java code changes for Micronaut framework repositories using maintainer standards, including JSpecify null-safety conventions. Use when users ask to add or refactor Java code, fix framework bugs, evolve internal APIs, or prepare committer-ready changes with tests and verification.\nlicense: Apache-2.0\ncompatibility: Micronaut framework repositories in micronaut-projects generated from micronaut-project-template\nmetadata:\n author: Álvaro Sánchez-Mariscal\n version: \"1.0.0\"\n---\n\n# Coding (Micronaut Committer)\n\nUse this skill for maintainer-facing Java implementation work in Micronaut repositories. Do not default to end-user application shortcuts.\n\n## Goal\n\nDeliver minimal, source-backed Java changes that preserve framework quality: binary compatibility, JSpecify null-safety, reflection-free behavior, and full Gradle verification (`check`, `docs`, and compatibility checks when API-facing).\n\n## Trigger Examples\n\nShould trigger:\n\n- \"Implement this Micronaut Java feature in `src/main/java` and keep API compatibility.\"\n- \"Refactor this module internals and mark non-public APIs correctly.\"\n- \"Fix failing framework tests and prepare committer-ready validation output.\"\n- \"Add configuration support using Micronaut conventions, not app-level shortcuts.\"\n\nShould not trigger:\n\n- \"Explain Micronaut basics to a beginner.\"\n- \"Create an end-user sample app from scratch.\"\n- \"Only edit release notes/changelog text.\"\n\n## Procedure\n\n1. Establish scope and API impact.\n2. Implement Java code with Micronaut maintainer conventions.\n3. Enforce API boundaries and binary compatibility.\n4. Document Java APIs and implementation intent.\n5. Keep Gradle/build changes aligned with repository conventions.\n6. Verify with maintainer-grade checks before completion.\n\n### 1) Establish scope and API impact\n\n- Identify affected modules and whether any change is public API or internal-only.\n- Inspect existing package patterns before editing (imports, nullability style, tests, naming).\n- For API-facing edits, plan compatibility checks up front (`japiCmp`).\n- Keep change surface minimal; avoid opportunistic refactors unless required.\n\n### 2) Implement Java with Micronaut maintainer conventions\n\n- Prefer modern Java idioms where they improve clarity (records, sealed types, pattern matching, `var` for local inference), but only when supported by the repository toolchain/target level.\n- Do not use fully qualified class names unless import conflicts force it.\n- Micronaut Java code uses JSpecify nullness annotations from `org.jspecify.annotations`; use JSpecify for new or modified nullability contracts.\n- New Java packages must include `package-info.java` with `@NullMarked` and `import org.jspecify.annotations.NullMarked`; when touching an existing package without `@NullMarked`, add it unless the local code has an explicit exception.\n- Use `org.jspecify.annotations.Nullable` for nullable values, including nullable parameters, return values, fields, array/component positions such as `String @Nullable []`, nullable collection elements such as `List<@Nullable T>`, and nullable type bounds such as ``.\n- Preserve existing nullability intent when editing older code. Use JSpecify for new or modified contracts, but do not rewrite deliberate compatibility annotations such as `io.micronaut.core.annotation.Nullable` or `jakarta.annotation.Nullable` unless the task is specifically a nullability migration and compatibility impact has been checked.\n- Avoid reflection-oriented implementations in framework code paths; prefer Micronaut compile-time/introspection mechanisms.\n- Use `jakarta.inject` APIs for DI, not `javax.inject`.\n- Prefer constructor injection and immutable state over field injection.\n- For configuration models, prefer `@ConfigurationProperties` over scattered `@Value` usage.\n\n### 3) Enforce API boundaries and compatibility\n\n- Treat all public-facing changes through a Semantic Versioning lens (`https://semver.org/`) before implementation.\n- Classify impact explicitly: patch for backward-compatible fixes, minor for backward-compatible feature additions, major for breaking API/behavioral changes.\n- Keep public API binary compatible unless a major-version change explicitly allows breaks.\n- Prefer non-breaking API evolution first: deprecate existing methods and add replacement variants/overloads instead of deleting methods or changing signatures in place.\n- When using the deprecate-and-add path, keep deprecated APIs functional, point to replacements in Javadoc, and schedule removals only for the next major version.\n- If breaking public-facing changes are explicitly allowed, document them in the user guide under `src/main/docs/guide` with migration notes, and update `toc.yml` when adding new guide sections.\n- Mark non-user-facing APIs with `@io.micronaut.core.annotation.Internal`.\n- Mark unstable public APIs with `@io.micronaut.core.annotation.Experimental` and avoid presenting them as stable contracts.\n- Mark members directly called by generated code with `@io.micronaut.core.annotation.UsedByGeneratedCode`; preserve those signatures unless the generated-code callers are updated in the same change.\n- Keep visibility as narrow as possible for non-public internals.\n- When deprecating API, provide migration-friendly Javadoc and avoid silent behavioral breaks.\n\n### 4) Document Java APIs and implementation intent\n\n- All public Java types and public methods must have Javadoc. Include public constructors when they are part of the user-facing API.\n- All new public Java types, methods, and user-facing constructors must include an `@since` Javadoc tag for the version where the PR will debut.\n- Determine the `@since` version from the approved target branch, not from guesswork. Inspect that branch's `gradle.properties` (`projectVersion`) and use the corresponding release version; for example, `4.9.0-SNAPSHOT` means the new API debuts in `4.9.0`.\n- If the PR is retargeted during follow-through, re-check the target branch's `gradle.properties` and update any newly added `@since` tags when the debut version changes.\n- Do not add `@since` tags to internal-only APIs annotated with `@Internal` unless the repository already does so for that internal package.\n- Internal and package-private methods should include maintainer-focused Javadoc when the implementation contract, lifecycle, invariants, or generated-code interaction is not obvious from the signature.\n- Complex new code should include focused inline comments that explain implementation decisions or invariants; do not narrate straightforward control flow.\n\n### 5) Keep Gradle/build changes convention-aligned\n\n- Use `./gradlew` for all Gradle execution.\n- Use Gradle version catalogs (`gradle/libs.versions.toml`) instead of hard-coded dependency versions.\n- Use appropriate scopes (`api`, `implementation`, `compileOnly`, `runtimeOnly`) based on API exposure.\n- Do not add custom build logic directly in module build files when it belongs in convention plugins.\n- When uncertain about module paths, use `./gradlew projects` and prefer canonical `micronaut-*` project names.\n\n### 6) Verify before completion\n\nFirst confirm canonical verification tasks from `CONTRIBUTING.md` and existing CI/build files, then run the repository equivalents from root.\n\nCommon sequence in Micronaut repositories:\n\n```bash\n./gradlew ::compileTestJava\n# If module includes Groovy tests:\n./gradlew ::compileTestGroovy\n./gradlew ::test --tests 'pkg.ClassTest'\n./gradlew ::test\n# If repository documents cM alias/checkstyle aggregate task:\n./gradlew -q cM\n./gradlew -q spotlessCheck\n./gradlew check\n./gradlew docs\n```\n\nFor API-affecting changes, also run if configured in the repository:\n\n```bash\n./gradlew japiCmp\n```\n\nIf Spotless fails, run `./gradlew -q spotlessApply` and re-run `spotlessCheck`.\n\n## Guardrails\n\n- Do not introduce `javax.inject` usage.\n- Do not introduce legacy or third-party nullability annotations for new or modified Micronaut Java contracts when JSpecify is available, except for deliberate compatibility annotations whose impact has been checked.\n- Do not hard-code dependency versions in module build files.\n- Do not break public APIs without explicit major-version intent.\n- Do not skip tests or docs verification for code changes.\n- Do not use reflection as a convenience in framework internals.\n\n## Delivery Contract\n\nWhen finishing implementation work, report:\n\n1. Exactly which files changed and why.\n2. Whether the change is API-facing or internal-only.\n3. Semantic Versioning impact classification (patch/minor/major) for any public-facing change.\n4. For deprecate-and-add API evolution, which elements were deprecated and which replacement variants were introduced.\n5. For breaking public-facing changes, which user guide files were updated and what migration guidance was added.\n6. For new public Java APIs, the `@since` version used and how it was derived from the target branch's `gradle.properties`.\n7. Commands executed for verification and outcomes.\n8. Any follow-up risk (for example compatibility implications).\n\n## Validation Checklist\n\n- [ ] `SKILL.md` frontmatter is valid and `name` matches directory (`coding`).\n- [ ] Guidance is maintainer-focused (not end-user app guidance).\n- [ ] Java conventions include JSpecify nullability (`@NullMarked`, `@Nullable`), DI, and reflection-free guidance.\n- [ ] API boundary guidance includes `@Internal`, `@Experimental`, `@UsedByGeneratedCode`, and compatibility checks.\n- [ ] Public Java types and methods require Javadoc.\n- [ ] New public Java APIs require `@since` tags derived from the approved target branch's `gradle.properties`.\n- [ ] Internal/package-private methods and complex new code include maintainer-focused Javadoc or inline comments when implementation intent is not obvious.\n- [ ] For public API evolution without breaking changes, deprecations include clear replacement guidance and functional compatibility is preserved.\n- [ ] If breaking changes are allowed, user guide docs in `src/main/docs/guide` are updated with migration notes.\n- [ ] Verification includes tests, style checks, `check`, and `docs`.\n\n## References\n\n- `CONTRIBUTING.md`\n- `MAINTAINING.md`\n- `.agents/skills/gradle/SKILL.md`\n- `.agents/skills/docs/SKILL.md`\n- `.agents/skills/skill-creator/references/spec-checklist.md`\n",".agents/skills/micronaut-sourcegen/SKILL.md":"---\nname: micronaut-sourcegen\ndescription: Add, integrate, or review Micronaut Sourcegen usage in modules that generate Java source, Kotlin source, Groovy-compatible source, or bytecode from ObjectDef, TypeDef, MethodDef, ExpressionDef, StatementDef, and SourceGenerator APIs.\nlicense: Apache-2.0\ncompatibility: Micronaut framework and library modules that use io.micronaut.sourcegen for compile-time generation\nmetadata:\n author: Denis Stepanov\n version: \"1.0.0\"\n---\n\n# Micronaut Sourcegen\n\nUse this skill when a Micronaut module wants to generate types with Micronaut Sourcegen instead of handwritten source strings, reflection, JavaPoet/KotlinPoet calls in visitors, or ad hoc bytecode. The target module may emit Java source, Kotlin source, Groovy-compatible source, or bytecode, but the generation logic should model the type once with `io.micronaut.sourcegen.model`.\n\n## Goal\n\nHelp other modules adopt Micronaut Sourcegen safely: choose the right backend, wire the right processor dependencies, build language-neutral model definitions, and verify generated Java/Kotlin/bytecode behavior with targeted tests.\n\n## Trigger Examples\n\nShould trigger:\n\n- \"Use Micronaut Sourcegen in this module to generate a repository implementation.\"\n- \"Generate bytecode instead of Java source for this visitor.\"\n- \"Make this annotation processor generate Java and Kotlin outputs with Sourcegen.\"\n- \"Replace handwritten generated-source strings with `ClassDef` and `MethodDef`.\"\n- \"Add method bodies with switches, static calls, static field arguments, and constructor calls.\"\n\nShould not trigger:\n\n- \"Only edit user guide text.\"\n- \"Only change Gradle publishing metadata.\"\n- \"Only refactor backend writer internals without a module consuming Sourcegen.\"\n- \"Explain Micronaut annotation processing without generated types.\"\n\n## Procedure\n\n1. Identify the consuming module and generation target.\n2. Choose one backend for each compilation path.\n3. Wire dependencies using the repository version catalogs and processor configurations.\n4. Implement generation in a visitor with Sourcegen model builders and helpers.\n5. Emit through `SourceGenerator.write(...)` or bytecode writer APIs as appropriate.\n6. Add cross-target tests for the generated contract.\n7. Run focused compile/test/style verification.\n\n### 1) Identify the Consuming Module\n\n- Confirm whether the module is an annotation processor/generator module, an application/test-suite module consuming a generator, or a backend writer module.\n- Locate existing visitor registration under `META-INF/services/io.micronaut.inject.visitor.TypeElementVisitor`.\n- Identify source language paths:\n - Java annotation processing uses `annotationProcessor`.\n - Kotlin compilation usually uses `ksp`.\n - Bytecode generation runs during Java-language processing and writes class files directly.\n- Inspect existing generated-type tests before changing behavior.\n\n### 2) Choose the Backend\n\n- Use `sourcegen-generator-java` when the module should emit `.java` source for `VisitorContext.Language.JAVA`; it also provides `GroovyPoetSourceGenerator` for `GROOVY`.\n- Use `sourcegen-generator-kotlin` when Kotlin/KSP processing should emit `.kt` source for `VisitorContext.Language.KOTLIN`.\n- Use `sourcegen-generator-bytecode` when Java-language processing should emit `.class` files directly through `ByteCodeGenerator`.\n- Do not put both Java-source and bytecode Sourcegen generators on the same Java annotation-processor path unless the module intentionally owns selection. Both advertise `VisitorContext.Language.JAVA`, and `SourceGenerators.findByLanguage(JAVA)` expects a single effective backend.\n- Use `sourcegen-bytecode-writer` directly only when implementing or testing bytecode writer behavior, not as the normal integration point for consuming annotation processors.\n\n### 3) Wire Dependencies\n\n- In a generator/processor module, depend on `sourcegen-generator` for the model and service lookup APIs. Add `sourcegen-annotations` only when the module consumes Sourcegen annotations such as builders/wither support.\n- In a Java consumer/test module, add the chosen backend and the custom generator to `annotationProcessor`.\n- In a Kotlin consumer/test module, add the Kotlin backend and KSP-compatible custom generator to `ksp`.\n- In a bytecode consumer/test module, add `sourcegen-generator-bytecode` to `annotationProcessor`.\n- Use Gradle version catalogs and existing project accessors. Do not hardcode dependency coordinates or versions.\n\nExample repository-local shapes:\n\n```kotlin\ndependencies {\n implementation(projects.sourcegenGenerator)\n\n annotationProcessor(projects.sourcegenGeneratorJava)\n annotationProcessor(projects.myCustomGenerators)\n}\n```\n\n```kotlin\ndependencies {\n ksp(projects.sourcegenGeneratorKotlin)\n ksp(projects.myCustomGeneratorsKotlin)\n}\n```\n\n```kotlin\ndependencies {\n annotationProcessor(projects.sourcegenGeneratorBytecode)\n annotationProcessor(projects.myCustomGenerators)\n}\n```\n\n### 4) Build Models With Factories, Not Record Constructors\n\n- Always create Sourcegen model elements through builders, factory methods, or helper methods: `ClassDef.builder`, `InterfaceDef.builder`, `RecordDef.builder`, `EnumDef.builder`, `AnnotationObjectDef.builder`, `MethodDef.builder`, `MethodDef.constructor`, `FieldDef.builder`, `PropertyDef.builder`, `ParameterDef.builder`, `TypeDef.of`, `ClassTypeDef.of`, `TypeDef.parameterized`, `ExpressionDef.constant`, `StatementDef.multi`, `StatementDef.doTry`, `expr.returning`, `expr.invoke`, `type.invokeStatic`, `type.getStaticField`, and switch/if helper methods.\n- Do not instantiate DSL records directly in consuming modules, for example avoid `new ClassTypeDef.Parameterized(...)`, `new TypeDef.Array(...)`, `new ExpressionDef.Constant(...)`, `new StatementDef.Switch(...)`, or other `new ...record(...)` forms.\n- If a construct has no public helper yet, add or use a small named helper/factory at the nearest appropriate level instead of spreading direct record construction through module code.\n- Keep model construction language-neutral. Do not call JavaPoet, KotlinPoet, ASM, or write source strings from a visitor unless the task is explicitly inside a backend writer.\n\n### 5) Implement Visitors\n\n- Prefer `TypeElementVisitor` with `VisitorKind.ISOLATING` when generated output depends only on the visited element.\n- Resolve the backend through `SourceGenerators.findByLanguage(context.getLanguage()).orElse(null)` and return when none is available.\n- Build `ObjectDef` instances from Micronaut AST metadata (`ClassElement`, `MethodElement`, `FieldElement`, `PropertyElement`) when possible.\n- Emit with `sourceGenerator.write(objectDef, context, originatingElement)`.\n- Use `SourceGenerators.handleFatalException(...)` when generation may postpone to a later round.\n\nMinimal visitor shape:\n\n```java\nSourceGenerator sourceGenerator = SourceGenerators.findByLanguage(context.getLanguage()).orElse(null);\nif (sourceGenerator == null) {\n return;\n}\n\nClassDef generated = ClassDef.builder(element.getPackageName() + \".Generated\")\n .addModifiers(Modifier.PUBLIC, Modifier.FINAL)\n .addMethod(MethodDef.builder(\"name\")\n .addModifiers(Modifier.PUBLIC)\n .returns(TypeDef.STRING)\n .build((aThis, params) -> ExpressionDef.constant(\"generated\").returning()))\n .build();\n\nsourceGenerator.write(generated, context, element);\n```\n\n### 6) Model Generated Behavior\n\n- Use `ClassDef`, `InterfaceDef`, `RecordDef`, `EnumDef`, and `AnnotationObjectDef` for generated type kind.\n- Use `TypeDef` and `ClassTypeDef` for primitives, arrays, generics, generated class names, nullability, and static field owners.\n- Use `MethodDef` body builders for executable logic. Prefer explicit `returns(...)` for public or non-trivial generated methods.\n- When generated code reads or writes a field that the same generator defines, keep the `FieldDef` instance and reference it with `aThis.field(fieldDef)` or `generatedType.getStaticField(fieldDef)` instead of repeating the field name and type.\n- When generated code invokes a method that the same generator defines, keep the `MethodDef` instance and invoke it with `receiver.invoke(methodDef, ...)` or `generatedType.invokeStatic(methodDef, ...)` instead of repeating the method name, parameter types, and return type.\n- When generated code targets an existing method or field that is accessible reflectively and present on the annotation processor classpath, prefer a reflective handle from `ReflectionUtils.getRequiredMethod(...)` or `ReflectionUtils.getRequiredField(...)`. Pass method handles to `receiver.invoke(method, ...)` or `type.invokeStatic(method, ...)`; pass static field handles to `type.getStaticField(field)`; for instance fields, centralize the field-name/type bridge in a helper fed by the reflective `Field`. This uses reflection only at generation time to describe a known member; it must not generate runtime reflection.\n- Use `StatementDef.multi(...)`, `expr.returning()`, `expr.newLocal(...)`, `condition.doIf(...)`, `expr.asExpressionSwitch(...)`, `expr.asStatementSwitch(...)`, `StatementDef.doTry(...)`, and invocation helpers to compose bodies.\n- Use `ClassTypeDef.getStaticField(\"NAME\", valueType)` for enum constants, static constants, class literals, and static-field arguments passed to invocations.\n- String switches are supported. For string switch cases, use a `TypeDef.STRING` switch expression and `ExpressionDef.constant(\"case\")` keys with `asExpressionSwitch(...)` or `asStatementSwitch(...)`.\n\n### 7) Verify\n\n- Compile the generator module and the consuming test module.\n- Run targeted tests that load or compile generated types for each backend touched.\n- For Java source generation, verify generated `.java` behavior through Java test-suite tests.\n- For Kotlin source generation, verify KSP and Kotlin tests.\n- For bytecode generation, verify runtime behavior and bytecode writer tests when the model shape exercises bytecode-specific paths.\n- Finish source changes with the repository checks required by `AGENTS.md`: affected compile tasks, targeted tests, full affected module tests, `./gradlew -q cM`, and `./gradlew -q spotlessCheck` if new files were added.\n\n## Backend Notes\n\n- Java source backend: `JavaPoetSourceGenerator` writes Java source for `VisitorContext.Language.JAVA`.\n- Groovy-compatible source backend: `GroovyPoetSourceGenerator` reuses the Java source generator for `GROOVY`.\n- Kotlin source backend: `KotlinPoetSourceGenerator` writes Kotlin source for `VisitorContext.Language.KOTLIN`.\n- Bytecode backend: `ByteCodeGenerator` advertises `JAVA` and writes class files through `context.visitClass(...)`; it does not support `write(ObjectDef, Writer)`.\n\n## Cookbook\n\nUse `references/sourcegen-cookbook.md` for adoption patterns covering:\n\n- Gradle dependency placement for generator modules and consumers,\n- backend selection for Java, Kotlin, Groovy-compatible source, and bytecode,\n- type/model construction using builders and helper methods,\n- generated classes, interfaces, records, enums, annotations, method bodies, switches, invocations, static fields, arrays, lambdas, and super constructors,\n- testing and validation across source and bytecode backends.\n\n## Guardrails\n\n- Do not instantiate Sourcegen DSL records directly in consuming modules; use builders, factories, or named helper methods.\n- Do not duplicate generated member metadata in generated code bodies; prefer the existing `FieldDef` or `MethodDef` instance when reading/writing generated fields or invoking generated methods.\n- Do not use string-based references for known existing classpath methods/static fields when a `ReflectionUtils.getRequiredMethod(...)` or `ReflectionUtils.getRequiredField(...)` handle can describe the member safely.\n- Do not generate source text with string concatenation when a Sourcegen model construct exists.\n- Do not place multiple `JAVA` Sourcegen backends on the same annotation-processor path unless selection is explicit and tested.\n- Do not use backend-specific JavaPoet/KotlinPoet/ASM APIs from normal visitors.\n- Do not use reflection for generation metadata when Micronaut AST elements are available.\n- Do not break public Sourcegen APIs without explicit approval and compatibility checks.\n\n## Validation Checklist\n\n- [ ] Skill folder name and `name:` frontmatter are `micronaut-sourcegen`.\n- [ ] Consuming module and target backend are identified.\n- [ ] Java/Kotlin/bytecode processor dependencies are scoped correctly.\n- [ ] Only one effective `JAVA` Sourcegen backend is present for a Java compilation path.\n- [ ] Model definitions use builders/factories/helpers, not direct DSL record constructors.\n- [ ] Generated fields/methods referenced from generated bodies are referenced through their `FieldDef`/`MethodDef` instances where available.\n- [ ] Generated sources/classes are emitted through `SourceGenerator.write(...)` or backend writer APIs where appropriate.\n- [ ] Targeted and full affected tests pass, or unrun checks are reported clearly.\n\n## References\n\n- `references/sourcegen-cookbook.md`\n",".agents/skills/skill-creator/references/spec-checklist.md":"# Agent Skills Spec Checklist\n\nUse this checklist when creating or modifying a skill to keep it compatible with the Agent Skills specification.\n\nPrimary source: https://agentskills.io/specification\n\n## MUST requirements\n\n1. Skill is a directory containing `SKILL.md`.\n2. `SKILL.md` starts with valid YAML frontmatter.\n3. Frontmatter includes required fields:\n - `name`\n - `description`\n4. `name` rules:\n - 1-64 characters\n - lowercase letters, numbers, hyphens only\n - does not start/end with hyphen\n - no consecutive hyphens\n - matches parent directory name\n5. `description` rules:\n - 1-1024 characters\n - non-empty\n - states what the skill does and when to use it\n6. Markdown body exists after frontmatter.\n\n## SHOULD guidance\n\n1. Keep `SKILL.md` under ~500 lines for efficient context usage.\n2. Use progressive disclosure:\n - keep core instructions in `SKILL.md`\n - move detailed material to `references/`\n3. Add `scripts/` only for deterministic or repeated work.\n4. Keep file references relative to skill root.\n5. Keep references shallow and easy to discover from `SKILL.md`.\n\n## Optional frontmatter fields\n\n- `license`\n- `compatibility`\n- `metadata`\n- `allowed-tools` (experimental; support varies by agent)\n\n## Portability rules\n\n1. Avoid vendor-specific instructions unless requested by the user.\n2. Avoid agent-specific path assumptions if portable paths are possible.\n3. Avoid relying on non-standard tools without fallback guidance.\n\n## Validation commands\n\nIf available:\n\n```bash\nskills-ref validate ./\n```\n\nFor discovery checks in a workspace using skills CLI:\n\n```bash\nnpx skills list\n```\n",".agents/skills/skill-creator/references/research-synthesis.md":"# Research Synthesis\n\nThis note captures the design decisions used for `skill-creator`.\n\n## Sources\n\n- Agent Skills specification: https://agentskills.io/specification\n- Anthropic skill-creator reference:\n https://github.com/anthropics/skills/tree/main/skills/skill-creator\n- OpenAI skill-creator reference:\n https://github.com/openai/skills/tree/main/skills/.system/skill-creator\n- Skills CLI reference:\n https://github.com/vercel-labs/skills\n\n## Shared patterns extracted\n\n1. Core process is iterative: scope, draft, test, refine.\n2. Trigger quality depends primarily on frontmatter description clarity.\n3. Progressive disclosure is essential for context efficiency.\n4. Optional resources should be added only when they reduce repeated work.\n\n## Vendor-specific elements intentionally avoided\n\n1. Model/provider-specific instructions and path assumptions.\n2. Dependence on platform-specific UI workflows.\n3. Tooling that only exists in one agent runtime.\n\n## Decisions in this skill\n\n1. Keep the main workflow in `SKILL.md` as a portable baseline.\n2. Move strict checklists and scaffolds into `references/` files.\n3. Include skills CLI validation guidance (`npx skills list`) and optional spec validator guidance (`skills-ref validate`).\n4. Keep language imperative and implementation-focused.\n",".agents/skills/skill-creator/references/templates.md":"# Universal Skill Templates\n\nUse these templates as starting points. Keep them concise and agent-agnostic.\n\n## 1) Minimal `SKILL.md` template\n\n```markdown\n---\nname: \ndescription: \nlicense: MIT\n---\n\n# \n\n## Goal\n\n\n\n## Procedure\n\n1. \n2. \n3. \n\n## Inputs\n\n- \n- \n\n## Outputs\n\n- \n\n## Edge cases\n\n- \n- \n\n## Validation\n\n- [ ] Frontmatter is valid YAML\n- [ ] Name matches folder\n- [ ] Description includes trigger contexts\n- [ ] Relative file references resolve\n```\n\n## 2) Expanded structure template\n\n```text\n/\n├── SKILL.md\n├── scripts/\n│ └──