diff --git a/.agents/skills/agent-md-refactor/SKILL.md b/.agents/skills/agent-md-refactor/SKILL.md new file mode 100644 index 00000000..46ad5a03 --- /dev/null +++ b/.agents/skills/agent-md-refactor/SKILL.md @@ -0,0 +1,84 @@ +--- +name: agent-md-refactor +description: 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. +license: Apache-2.0 +compatibility: Repositories using markdown instruction files such as AGENTS.md, CLAUDE.md, or COPILOT.md +metadata: + author: Álvaro Sánchez-Mariscal + version: "1.0.0" +--- + +# Agent MD Refactor + +Refactor monolithic instruction files into a compact root file plus linked topic files. +Keep this file focused on execution flow and load detailed templates/examples from references. + +## Goal + +Deliver a maintainable instruction system with: + +- a minimal root instruction file containing only universal guidance, +- linked topic files for detailed rules, +- contradictions resolved and vague/redundant rules removed. + +## Trigger Examples + +Should trigger: + +- "Refactor this AGENTS.md to use progressive disclosure." +- "Split my CLAUDE.md into focused instruction files." +- "My instruction file is too long, reorganize it." + +Should not trigger: + +- "Explain what AGENTS.md is." +- "Fix one typo in CLAUDE.md." +- "Write a brand-new coding standard from scratch." + +More examples: [examples-and-anti-patterns](references/examples-and-anti-patterns.md). + +## Procedure + +1. Inventory instruction sources (`AGENTS.md`, `CLAUDE.md`, `COPILOT.md`, related guidance docs). +2. Detect contradictions and resolve by repository precedence. +3. Keep only root-level essentials in the root instruction file. +4. Group remaining content into 3-8 linked topic files with clear names. +5. Remove non-actionable, redundant, and outdated directives. +6. Validate links, coverage, and consistency before completion. + +Detailed step playbook: [refactor-playbook](references/refactor-playbook.md). + +## Inputs + +- Root instruction file path(s) +- Existing repository conventions (commands, toolchain, style) +- User constraints (must-keep rules, preferred layout) + +## Outputs + +- Refactored root instruction file (minimal, universal guidance) +- Topic files with detailed rules +- List of removed/merged rules with rationale +- Notes on contradiction handling + +## Edge Cases + +- If rule precedence is impossible to infer, request one targeted user decision. +- If multiple files repeat the same rule, keep one canonical source and replace others with links. +- If the instruction file is already concise, avoid unnecessary splitting. +- Use relative markdown links for portability. + +## Validation Checklist + +- [ ] Frontmatter is valid YAML and `name` matches directory. +- [ ] Description states capability and usage triggers. +- [ ] Root file contains only universal instructions. +- [ ] Topic files are self-contained and linked from root. +- [ ] Contradictions are resolved or explicitly called out. +- [ ] Vague/default/redundant directives are removed or rewritten. +- [ ] Relative links resolve. + +## References + +- [Refactor playbook](references/refactor-playbook.md) +- [Examples and anti-patterns](references/examples-and-anti-patterns.md) diff --git a/.agents/skills/agent-md-refactor/references/examples-and-anti-patterns.md b/.agents/skills/agent-md-refactor/references/examples-and-anti-patterns.md new file mode 100644 index 00000000..6e98be38 --- /dev/null +++ b/.agents/skills/agent-md-refactor/references/examples-and-anti-patterns.md @@ -0,0 +1,74 @@ +# Examples and Anti-Patterns + +Use these examples to guide consistent refactors. + +## Root File Pattern + +Good root structure: + +```markdown +# Project Instructions + +One-line project description. + +## Commands +- `pnpm build` +- `pnpm test` +- `pnpm typecheck` + +## Detailed Guidance +- [Architecture](.agent-instructions/architecture.md) +- [Code Style](.agent-instructions/code-style.md) +- [Testing](.agent-instructions/testing.md) +``` + +Avoid: + +```markdown +# AGENTS.md + +## Code Style +... 150 lines ... + +## Testing +... 120 lines ... + +## TypeScript +... 180 lines ... +``` + +## Topic File Pattern + +Good topic file: + +```markdown +# Testing + +## Scope +When to use each test type. + +## Rules +- Use integration tests for persistence adapters. +- Keep unit tests deterministic. + +## Examples +- Good: verifies behavior with stable fixtures. +- Avoid: brittle tests tied to timestamps. +``` + +## Anti-Patterns + +- Keeping all details in root file. +- Splitting into too many tiny files with unclear ownership. +- Duplicating the same rule across files. +- Retaining vague guidance like "write clean code". +- Using absolute or agent-specific links when relative links work. + +## Deletion Candidates + +Flag these for removal during refactor: + +- Rules that just restate defaults. +- Outdated references to removed tools/frameworks. +- Safety slogans without actionable behavior. +- Duplicate rules that conflict in wording. diff --git a/.agents/skills/agent-md-refactor/references/refactor-playbook.md b/.agents/skills/agent-md-refactor/references/refactor-playbook.md new file mode 100644 index 00000000..b3c78988 --- /dev/null +++ b/.agents/skills/agent-md-refactor/references/refactor-playbook.md @@ -0,0 +1,79 @@ +# Refactor Playbook + +Use this playbook to execute a deterministic refactor from monolithic instruction files to progressive disclosure. + +## Phase 1: Contradictions + +Find conflicts across instruction files: + +- style conflicts (`use semicolons` vs `no semicolons`) +- workflow conflicts (`always run full test suite` vs `run only targeted tests`) +- tool conflicts (`pnpm` vs `npm`) + +Capture using: + +```markdown +## Contradiction + +- Instruction A: +- Instruction B: +- Proposed resolution: +- Needs user decision: +``` + +Escalate to user only when precedence cannot be inferred from repository conventions. + +## Phase 2: Root Essentials + +Keep only universal material in root: + +- one-line project description +- canonical commands (build/test/typecheck/dev) +- package manager only if non-default +- critical global overrides applying to all tasks + +Move everything else to topic files. + +## Phase 3: Topic Grouping + +Target 3-8 files. Common categories: + +- `architecture.md` +- `code-style.md` +- `testing.md` +- `typescript.md` +- `git-workflow.md` +- `security.md` + +Rules: + +1. One topic per file. +2. No cross-file contradictions. +3. Use concrete imperative rules, not slogans. + +## Phase 4: Structure + +Preferred structure: + +```text +project-root/ +├── AGENTS.md (or CLAUDE.md/COPILOT.md) +└── .agent-instructions/ + ├── architecture.md + ├── code-style.md + ├── testing.md + └── ... +``` + +Use relative links from root to each topic file. + +## Phase 5: Prune + +Remove statements that are: + +- redundant with repository defaults +- vague and non-actionable +- generic safe-language with no behavioral effect +- obsolete/outdated + +When pruning, keep a short "removed rules" note with reasons. diff --git a/.agents/skills/coding/SKILL.md b/.agents/skills/coding/SKILL.md new file mode 100644 index 00000000..a84a0d58 --- /dev/null +++ b/.agents/skills/coding/SKILL.md @@ -0,0 +1,142 @@ +--- +name: coding +description: Implement and review Java code changes for Micronaut framework repositories using maintainer standards. 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. +license: Apache-2.0 +compatibility: Micronaut framework repositories in micronaut-projects generated from micronaut-project-template +metadata: + author: Álvaro Sánchez-Mariscal + version: "1.0.0" +--- + +# Coding (Micronaut Committer) + +Use this skill for maintainer-facing Java implementation work in Micronaut repositories. Do not default to end-user application shortcuts. + +## Goal + +Deliver minimal, source-backed Java changes that preserve framework quality: binary compatibility, null-safety, reflection-free behavior, and full Gradle verification (`check`, `docs`, and compatibility checks when API-facing). + +## Trigger Examples + +Should trigger: + +- "Implement this Micronaut Java feature in `src/main/java` and keep API compatibility." +- "Refactor this module internals and mark non-public APIs correctly." +- "Fix failing framework tests and prepare committer-ready validation output." +- "Add configuration support using Micronaut conventions, not app-level shortcuts." + +Should not trigger: + +- "Explain Micronaut basics to a beginner." +- "Create an end-user sample app from scratch." +- "Only edit release notes/changelog text." + +## Procedure + +1. Establish scope and API impact. +2. Implement Java code with Micronaut maintainer conventions. +3. Enforce API boundaries and binary compatibility. +4. Keep Gradle/build changes aligned with repository conventions. +5. Verify with maintainer-grade checks before completion. + +### 1) Establish scope and API impact + +- Identify affected modules and whether any change is public API or internal-only. +- Inspect existing package patterns before editing (imports, nullability style, tests, naming). +- For API-facing edits, plan compatibility checks up front (`japiCmp`). +- Keep change surface minimal; avoid opportunistic refactors unless required. + +### 2) Implement Java with Micronaut maintainer conventions + +- 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. +- Do not use fully qualified class names unless import conflicts force it. +- Follow the repository's established nullability annotations/defaults; use JSpecify and package-level `@NullMarked` only when that convention already exists in the module. +- Avoid reflection-oriented implementations in framework code paths; prefer Micronaut compile-time/introspection mechanisms. +- Use `jakarta.inject` APIs for DI, not `javax.inject`. +- Prefer constructor injection and immutable state over field injection. +- For configuration models, prefer `@ConfigurationProperties` over scattered `@Value` usage. + +### 3) Enforce API boundaries and compatibility + +- Treat all public-facing changes through a Semantic Versioning lens (`https://semver.org/`) before implementation. +- Classify impact explicitly: patch for backward-compatible fixes, minor for backward-compatible feature additions, major for breaking API/behavioral changes. +- Keep public API binary compatible unless a major-version change explicitly allows breaks. +- Prefer non-breaking API evolution first: deprecate existing methods and add replacement variants/overloads instead of deleting methods or changing signatures in place. +- 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. +- 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. +- Mark non-user-facing APIs with `@io.micronaut.core.annotation.Internal`. +- Keep visibility as narrow as possible for non-public internals. +- When deprecating API, provide migration-friendly Javadoc and avoid silent behavioral breaks. + +### 4) Keep Gradle/build changes convention-aligned + +- Use `./gradlew` for all Gradle execution. +- Use Gradle version catalogs (`gradle/libs.versions.toml`) instead of hard-coded dependency versions. +- Use appropriate scopes (`api`, `implementation`, `compileOnly`, `runtimeOnly`) based on API exposure. +- Do not add custom build logic directly in module build files when it belongs in convention plugins. +- When uncertain about module paths, use `./gradlew projects` and prefer canonical `micronaut-*` project names. + +### 5) Verify before completion + +First confirm canonical verification tasks from `CONTRIBUTING.md` and existing CI/build files, then run the repository equivalents from root. + +Common sequence in Micronaut repositories: + +```bash +./gradlew ::compileTestJava +# If module includes Groovy tests: +./gradlew ::compileTestGroovy +./gradlew ::test --tests 'pkg.ClassTest' +./gradlew ::test +# If repository documents cM alias/checkstyle aggregate task: +./gradlew -q cM +./gradlew -q spotlessCheck +./gradlew check +./gradlew docs +``` + +For API-affecting changes, also run if configured in the repository: + +```bash +./gradlew japiCmp +``` + +If Spotless fails, run `./gradlew -q spotlessApply` and re-run `spotlessCheck`. + +## Guardrails + +- Do not introduce `javax.inject` usage. +- Do not hard-code dependency versions in module build files. +- Do not break public APIs without explicit major-version intent. +- Do not skip tests or docs verification for code changes. +- Do not use reflection as a convenience in framework internals. + +## Delivery Contract + +When finishing implementation work, report: + +1. Exactly which files changed and why. +2. Whether the change is API-facing or internal-only. +3. Semantic Versioning impact classification (patch/minor/major) for any public-facing change. +4. For deprecate-and-add API evolution, which elements were deprecated and which replacement variants were introduced. +5. For breaking public-facing changes, which user guide files were updated and what migration guidance was added. +6. Commands executed for verification and outcomes. +7. Any follow-up risk (for example compatibility implications). + +## Validation Checklist + +- [ ] `SKILL.md` frontmatter is valid and `name` matches directory (`coding`). +- [ ] Guidance is maintainer-focused (not end-user app guidance). +- [ ] Java conventions include nullability, DI, and reflection-free guidance. +- [ ] API boundary guidance includes `@Internal` and compatibility checks. +- [ ] For public API evolution without breaking changes, deprecations include clear replacement guidance and functional compatibility is preserved. +- [ ] If breaking changes are allowed, user guide docs in `src/main/docs/guide` are updated with migration notes. +- [ ] Verification includes tests, style checks, `check`, and `docs`. + +## References + +- `CONTRIBUTING.md` +- `MAINTAINING.md` +- `.agents/skills/gradle/SKILL.md` +- `.agents/skills/docs/SKILL.md` +- `.agents/skills/skill-creator/references/spec-checklist.md` diff --git a/.agents/skills/docs/SKILL.md b/.agents/skills/docs/SKILL.md new file mode 100644 index 00000000..8d074f21 --- /dev/null +++ b/.agents/skills/docs/SKILL.md @@ -0,0 +1,134 @@ +--- +name: docs +description: 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. +license: Apache-2.0 +compatibility: Micronaut framework repositories in micronaut-projects generated from micronaut-project-template +metadata: + author: Álvaro Sánchez-Mariscal + version: "1.0.0" +--- + +# Docs (Micronaut Maintainer) + +Use this skill for maintainer-facing guide work in Micronaut framework repositories. Do not default to end-user application documentation advice. + +## Goal + +Implement 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. + +## Procedure + +1. Confirm repository docs layout and build tasks. +2. Plan `toc.yml` and `.adoc` updates in lockstep. +3. Apply Micronaut docs macro conventions used by maintainers. +4. Prefer generated configuration property references over manual tables. +5. Build and validate `publishGuide` and `docs` outputs. + +### 1) Confirm docs layout and build tasks + +- Check `src/main/docs/guide/toc.yml` first. +- List relevant guide files under `src/main/docs/guide/**/*.adoc`. +- If examples are involved, inspect `doc-examples/` (if present) and plan snippet tags from executable sources. +- If assets are involved, keep images in `src/main/docs/resources/img/`. +- Confirm standard commands from `CONTRIBUTING.md`: + - `./gradlew publishGuide` (or `./gradlew pG`) for guide assembly. + - `./gradlew docs` for guide + API docs assembly. +- If repository layout diverges from template conventions, follow local conventions and explicitly report the divergence. + +### 2) Keep `toc.yml` and files in lockstep + +Treat `src/main/docs/guide/toc.yml` as navigation source of truth. + +Rules: + +1. Every visible section must exist in `toc.yml`. +2. Every `toc.yml` entry must resolve to a real `.adoc` path. +3. Preserve section order unless the request explicitly changes navigation. +4. Use nested sections for grouped topics when needed. + +Example nested pattern: + +```yaml +controlPanels: + title: Available Control Panels + builtIn: Built-in + management: Management +``` + +This maps to: + +- `src/main/docs/guide/controlPanels.adoc` +- `src/main/docs/guide/controlPanels/builtIn.adoc` +- `src/main/docs/guide/controlPanels/management.adoc` + +### 3) Apply Micronaut docs macro conventions + +Use docs macros registered by `micronaut-build` (`DocsExtensionRegistry`) and maintained for framework guides. + +Preferred mapping: + +| Need | Preferred pattern | +|---|---| +| Dependency instructions | `dependency:group:artifact[scope=...]` | +| Source sample synchronized with test suites | `snippet::path/to/File.ext[tags=...]` | +| Multi-format configuration snippets | `[configuration]` listing blocks | +| Configuration properties reference | `include::{includedir}configurationProperties/.adoc[]` | +| Shell commands | `[source,bash]` blocks | +| Repository/release links | `https://github.com/{githubSlug}` and `/releases` links | + +Guardrails: + +- Do not handwrite separate Maven/Gradle dependency blocks when `dependency:` is suitable. +- 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. + +### 4) Use generated configuration property references correctly + +- `micronaut-docs` provides `AsciiDocPropertyReferenceWriter`, which generates AsciiDoc property fragments from configuration metadata. +- Micronaut docs build wiring consumes those fragments via `{includedir}configurationProperties/...` includes. +- Prefer includes over hand-maintained property tables. + +See `references/micronaut-docs-providers.md` for confirmed provider/macro details and source locations. + +### 5) Build and validate documentation + +From repository root, run: + +```bash +./gradlew publishGuide +./gradlew docs +``` + +Validation checklist: + +1. Commands exit with code `0`. +2. Output exists under `build/docs/`. +3. Updated sections appear in navigation and render without missing includes. +4. Added images/links resolve. + +If `publishGuide` passes but `docs` fails, fix the failing stage and rerun both commands. + +## Maintainer Delivery Contract + +When finishing docs work, report: + +1. Exact changed files (`.adoc`, `toc.yml`, docs resources). +2. Which conventions were applied (`dependency:`, `snippet::`, `[configuration]`, generated property includes). +3. Build commands run and outcomes. +4. Any repo-specific divergences or follow-ups. + +## Validation Checklist + +- [ ] `toc.yml` and `.adoc` changes are consistent. +- [ ] Macros and includes follow Micronaut maintainer conventions. +- [ ] `publishGuide` and `docs` executed successfully. +- [ ] Output and navigation verified under `build/docs/`. +- [ ] Guidance remains maintainer-focused (not generic app docs). + +## References + +- `references/micronaut-docs-providers.md` +- `references/control-panel-patterns.md` +- `CONTRIBUTING.md` +- `src/main/docs/guide/toc.yml` diff --git a/.agents/skills/docs/references/control-panel-patterns.md b/.agents/skills/docs/references/control-panel-patterns.md new file mode 100644 index 00000000..ccd31c3d --- /dev/null +++ b/.agents/skills/docs/references/control-panel-patterns.md @@ -0,0 +1,85 @@ +# Micronaut Control Panel Guide Patterns + +This reference captures practical guide-authoring conventions observed in `micronaut-projects/micronaut-control-panel` and applicable to other Micronaut framework modules. + +## Structure patterns + +Source files: + +- `src/main/docs/guide/toc.yml` +- `src/main/docs/guide/quickStart.adoc` +- `src/main/docs/guide/controlPanels.adoc` + +Observed conventions: + +1. `toc.yml` defines order and nesting. +2. Nested sections map to folders/files under `src/main/docs/guide/`. +3. Top-level section pages are concise and delegate details to subpages. + +## `toc.yml` nested section pattern + +Observed pattern: + +```yaml +controlPanels: + title: Available Control Panels + builtIn: Built-in + management: Management +``` + +Mapping: + +- `src/main/docs/guide/controlPanels.adoc` +- `src/main/docs/guide/controlPanels/builtIn.adoc` +- `src/main/docs/guide/controlPanels/management.adoc` + +## Content patterns in `.adoc` + +### Dependency instructions + +Use `dependency:` macro with scope where relevant: + +```asciidoc +dependency:io.micronaut.controlpanel:micronaut-control-panel-ui[scope=developmentOnly] +``` + +### Configuration properties includes + +Use generated include fragments: + +```asciidoc +include::{includedir}configurationProperties/io.micronaut.controlpanel.core.config.ControlPanelModuleConfiguration.adoc[] +``` + +### Runtime environment commands + +Use explicit environment examples in `[source,bash]` blocks: + +```bash +MICRONAUT_ENVIRONMENTS=dev ./gradlew run +``` + +### Endpoint links and warnings + +- Prefer links to official `docs.micronaut.io` endpoint sections. +- Use admonitions for critical requirements (`WARNING:`). + +## Build workflow alignment + +Contributing workflow in control-panel matches template repos: + +- `./gradlew publishGuide` (or `./gradlew pG`) for guide output. +- `./gradlew docs` for guide + Javadocs. + +## Example-source strategy + +- Keep runnable examples in `doc-examples/` when the repository contains that project. +- Prefer including examples via Micronaut docs macros/snippet workflows so docs stay aligned with tested code. +- Avoid large hand-written code blocks in guide pages when the same content can be sourced from executable examples. + +## Maintainer takeaways + +1. Keep `toc.yml` and guide files synchronized at all times. +2. Favor macro/includes-backed content to reduce drift. +3. Keep examples runnable and environment-explicit. +4. Validate docs output before finalizing changes. diff --git a/.agents/skills/docs/references/micronaut-docs-providers.md b/.agents/skills/docs/references/micronaut-docs-providers.md new file mode 100644 index 00000000..5a43704a --- /dev/null +++ b/.agents/skills/docs/references/micronaut-docs-providers.md @@ -0,0 +1,90 @@ +# Micronaut Docs Providers and Guide Macros + +This reference captures source-backed behavior relevant to framework maintainers writing guide documentation. + +## 1) Configuration property writer from `micronaut-docs` + +`micronaut-docs` provides a metadata writer that emits AsciiDoc configuration property fragments. + +Source evidence: + +- `docs-asciidoc-config-props/src/main/java/io/micronaut/documentation/asciidoc/AsciiDocPropertyReferenceWriter.java` +- `docs-asciidoc-config-props/src/main/resources/META-INF/services/io.micronaut.inject.configuration.ConfigurationMetadataWriter` + +Behavior: + +- Writes `META-INF/config-properties.adoc` from Micronaut configuration metadata. +- Produces property table content (property, type, description, default value). + +Maintainer implication: + +- Prefer `include::{includedir}configurationProperties/.adoc[]` in guides instead of manually writing property tables. + +## 2) Asciidoctor extension registry used in module docs builds + +Guide macros used by Micronaut module docs are registered by `micronaut-build`. + +Source evidence: + +- `micronaut-build/micronaut-gradle-plugins/src/main/groovy/io/micronaut/docs/DocsExtensionRegistry.groovy` +- `micronaut-build/micronaut-gradle-plugins/src/main/resources/META-INF/services/org.asciidoctor.jruby.extension.spi.ExtensionRegistry` + +Registered extensions include: + +- Inline macros: `api`, `mnapi`, `ann`, `pkg`, `jdk`, `jee`, `rs`, `rx`, `reactor`, `dependency` +- Block macro: `snippet` +- Block processor: `configuration` + +## 3) `dependency:` macro + +Source: + +- `micronaut-build/micronaut-gradle-plugins/src/main/groovy/io/micronaut/docs/BuildDependencyMacro.groovy` + +Usage: + +- `dependency:io.micronaut.controlpanel:micronaut-control-panel-ui[scope=developmentOnly]` + +Why maintainers should prefer it: + +- Keeps dependency snippets consistent across Gradle/Maven output. +- Avoids drift from hand-written dual build-tool snippets. + +## 4) `snippet::` macro + +Source: + +- `micronaut-build/micronaut-gradle-plugins/src/main/groovy/io/micronaut/docs/LanguageSnippetMacro.groovy` + +Maintainer guidance: + +- Use for examples that should stay aligned with source/test files. +- Prefer tagged snippets for stable, focused excerpts. + +## 5) `[configuration]` block processor + +Source: + +- `micronaut-build/micronaut-gradle-plugins/src/main/groovy/io/micronaut/docs/ConfigurationPropertiesMacro.groovy` + +Maintainer guidance: + +- Use for multi-format configuration examples rather than one-off single-format blocks. + +## 6) Docs task wiring in `micronaut-build` + +Source: + +- `micronaut-build/micronaut-gradle-plugins/src/main/groovy/io/micronaut/build/MicronautDocsPlugin.groovy` + +Relevant properties and behavior: + +- Guide tasks include `publishGuide*`, `assembleDocs`, and `docs`. +- Asciidoctor properties include `includedir`, `micronautapi`, `source-highlighter`, and language handling. +- Built docs are assembled into `build/docs/`. + +## Practical rules + +1. Prefer macro-driven docs (`dependency:`, `snippet::`, `[configuration]`) over hand-maintained formatting. +2. Prefer generated config property includes over manually authored property tables. +3. Validate with `./gradlew publishGuide` and `./gradlew docs` before completion. diff --git a/.agents/skills/gradle/SKILL.md b/.agents/skills/gradle/SKILL.md new file mode 100644 index 00000000..7069b0dc --- /dev/null +++ b/.agents/skills/gradle/SKILL.md @@ -0,0 +1,126 @@ +--- +name: gradle +description: 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. +license: Apache-2.0 +compatibility: Micronaut framework repositories in micronaut-projects using micronaut-build plugins +metadata: + author: Álvaro Sánchez-Mariscal + version: "1.0.0" + gradle-major-version: "9.x" +mcp: + maven-tools: + command: docker + args: ["run", "-i", "--rm", "arvindand/maven-tools-mcp:latest"] +--- + +# Gradle (Micronaut Committer) + +Use this skill for Micronaut framework maintainer work. Do not default to end-user app guidance. + +## Goal + +Apply correct, source-backed Gradle changes in Micronaut repositories, using the `micronaut-build` plugin contracts and current Gradle best practices. + +Current coverage target: repositories on Gradle major line `9.x`. + +For dependency-intelligence tasks (version freshness, stability, release cadence, CVE/license checks), use the embedded `maven-tools` MCP via `skill_mcp`. + +## Procedure + +1. Identify build shape and active plugins. +2. Map requested work to exact `micronaut-build` plugin behavior. +3. Execute minimal maintainer-safe change. +4. Verify with targeted and aggregate Gradle tasks. + +### 1) Establish build shape first + +- Inspect `settings.gradle` or `settings.gradle.kts` for settings plugins and dependency management. +- Confirm `io.micronaut.build.shared.settings` is present unless the repository intentionally diverged. +- Validate settings-scoped plugins (especially Develocity wiring) in `settings.gradle(.kts)`, not in project `build.gradle(.kts)`. +- Confirm root build applies `io.micronaut.build.internal.parent` for standard aggregation behavior. +- Inspect root and impacted module build files for applied plugin IDs and `micronautBuild` extension usage. +- Inspect `buildSrc`/convention plugins before modifying module build scripts. +- Inspect `gradle.properties` and `gradle/*.versions.toml` for version source and overrides. +- Treat module directory names and Gradle project paths separately; if standardized names are enabled, use `:micronaut-*` paths for task targeting. +- If module paths are unclear, run `./gradlew projects`. +- If dependency resolution is involved, capture `dependencyInsight` before changing files. + +### 2) Use source-of-truth plugin contracts + +- Use `references/micronaut-build-plugins.md` as the authoritative plugin behavior map. +- Treat `micronaut-build` source as primary truth. Its README may be outdated. +- Remember default plugin IDs are internal: `io.micronaut.build.internal.`. +- Important exception: `io.micronaut.build.shared.settings`. + +### 3) Execute maintainer workflows + +- **Build failures**: reproduce with minimal task path, then expand to module `check`, then root validation. +- **Catalog/version updates**: use plugin-provided workflows (`updateVersionCatalogs`, `useLatestVersions`) where available. +- **Catalog imports**: prefer `micronautBuild { importMicronautCatalog() }` and alias-specific imports over ad hoc BOM wiring when repository conventions use settings extension catalog import. +- **Dependency intelligence**: use the `maven-tools` MCP for latest stable versions, upgrade comparisons, and dependency health signals before changing catalogs or BOM constraints. +- **Dependency scope hygiene**: choose `api` only for public API surface; use `implementation` for internals; use `compileOnly`/`runtimeOnly` intentionally. +- **BOM/publishing**: verify BOM generation, inlining behavior, publication metadata, and signing gates. +- **Binary compatibility**: keep baseline discovery and accepted API changes explicit; never silently suppress regressions. +- **Docs/quality**: treat root-only aggregator plugins and docs pipelines as first-class checks. +- **Layering**: prefer convention plugin changes (`buildSrc`) over duplicating logic in many module build files. + +### 4) Verify before completion + +- Run at least one targeted task and one aggregate task: + - `./gradlew ::check` + - `./gradlew check` +- For maintainer pipelines, include docs and style gates where applicable: + - `./gradlew check docs` + - `./gradlew spotlessApply spotlessCheck` +- For API-affecting changes, run compatibility checks: + - `./gradlew japiCmp` +- For newly added published modules, define when binary compatibility checks start in module build logic (example): + +```kotlin +micronautBuild { + binaryCompatibility.enabledAfter("2.0.0") +} +``` + +- Use the repository's intended first compatible release version instead of blindly reusing `2.0.0`. +- Add focused diagnostics when needed: + - `./gradlew dependencyInsight --configuration --dependency ` + - `./gradlew --scan ` +- Report exact commands and outcomes. + +## Guardrails + +- Do not use `enforcedPlatform` when plugin logic explicitly forbids it. +- Do not bypass Micronaut version mismatch checks except intentional development-version flows. +- Do not apply root-only plugins to subprojects. +- Do not replace framework maintainer workflows with generic app-centric shortcuts. + +## Best Practices + +Use `references/gradle-best-practices.md` for operational standards on: + +- configuration and build cache behavior, +- provider/lazy configuration patterns, +- toolchains and reproducibility, +- secure publishing and dependency verification, +- CI reliability. + +## Examples + +- "Diagnose why micronaut-core version mismatch fails on compileClasspath." +- "Update version catalogs safely and apply latest allowed minor versions." +- "Fix Sonatype release pipeline behavior for a non-snapshot release." +- "Investigate binary compatibility failure and validate accepted changes file usage." + +## Validation Checklist + +- [ ] Active plugins identified from build files. +- [ ] Decisions mapped to `micronaut-build` source behavior. +- [ ] Changes align with maintainer workflows. +- [ ] Verification tasks run and outcomes captured. +- [ ] No end-user-only Gradle guidance substituted for framework operations. + +## References + +- `references/micronaut-build-plugins.md` +- `references/gradle-best-practices.md` diff --git a/.agents/skills/gradle/references/gradle-best-practices.md b/.agents/skills/gradle/references/gradle-best-practices.md new file mode 100644 index 00000000..53482aa0 --- /dev/null +++ b/.agents/skills/gradle/references/gradle-best-practices.md @@ -0,0 +1,100 @@ +# Gradle Best Practices for Micronaut Maintainers + +This guidance targets framework committers maintaining many repositories and CI pipelines. + +Current coverage target: Gradle major line `9.x`. + +## Version Scope Policy + +1. Treat the repository wrapper major line as authoritative (`gradle/wrapper/gradle-wrapper.properties`). +2. Avoid hard-coding patch-specific guidance in shared maintainer docs. +3. Use `docs.gradle.org/current` references as the baseline unless a repository pins a behavior. + +## Core Principles + +1. Prefer deterministic, cache-friendly builds. +2. Keep configuration lazy and provider-driven. +3. Centralize versions and avoid drift. +4. Validate changes with targeted plus aggregate tasks. + +## Configuration and Performance + +- Prefer task configuration avoidance (`tasks.register`, `configureEach`) over eager task realization. +- Keep task inputs/outputs explicit and stable for cacheability. +- Avoid absolute paths in cache-sensitive task inputs whenever possible. +- Prefer providers (`providers.gradleProperty`, `providers.environmentVariable`, `Provider` chaining) over imperative reads. +- Use build scans in CI triage (`--scan`) to identify config cache/caching misses and slow paths. +- Prefer convention plugin ownership over broad root `subprojects {}` mutation. + +## Configuration Cache and Build Cache + +- Keep custom task logic free from unsafe runtime access to mutable project state. +- Use provider-backed values for environment/system properties. +- Treat non-cache-compatible tasks as exceptional and document why they are excluded. +- For CI reproducibility, keep caching policy explicit in settings and workflows. + +## Version Management + +- Keep dependency versions in `gradle/*.versions.toml` catalogs. +- Prefer catalog aliases and platform/BOM alignment instead of ad hoc version literals. +- For Micronaut repos, maintain explicit core/bom alignment and investigate mismatch failures with `dependencyInsight`. +- Use automated catalog update workflows with clear policy for major/minor/prerelease boundaries. +- Use `java-library` API/implementation boundaries in reusable modules to minimize downstream compile classpaths. +- Where `micronautBuild` settings extension is the convention, prefer `importMicronautCatalog()` / `importMicronautCatalog("")` over one-off dependency-management wiring. + +## Java and Toolchains + +- Prefer Java toolchains for reproducible compilation and test execution. +- Keep `javaVersion` and test JVM version strategy explicit in build extension configuration. +- Avoid mixing legacy source/target compatibility settings unless migration requires it. + +## Publishing and Release Safety + +- Keep credentials and signing material in env/system properties; never commit secrets. +- Validate publication metadata (name, description, SCM, developers) before release. +- Distinguish snapshot and release behaviors and verify staging/publish flow accordingly. +- Ensure release pipelines run pre-release checks and artifact verification before publication. + +## Quality Gates + +- Enforce style and static checks in normal `check` workflows. +- Keep test reporting readable and deterministic in CI. +- Aggregate coverage and quality reporting from root where plugin design expects it. +- Treat binary compatibility checks as release blockers unless explicitly accepted and documented. + +## Diagnostics Patterns + +- Dependency source tracing: + +```bash +./gradlew dependencyInsight --configuration compileClasspath --dependency io.micronaut:micronaut-core +``` + +- Targeted task reproduction: + +```bash +./gradlew ::check --stacktrace +``` + +- Aggregate validation before merge: + +```bash +./gradlew check +``` + +## Anti-Patterns to Avoid + +- Hard-coding dependency versions in many module build files. +- Disabling guard checks to get green CI without root-cause analysis. +- Applying root-only plugins on subprojects. +- Making broad Gradle changes without a narrow reproduction and verification plan. + +## References + +- Gradle User Manual: https://docs.gradle.org/current/userguide/userguide.html +- Gradle Best Practices: https://docs.gradle.org/current/userguide/best_practices.html +- Build Cache: https://docs.gradle.org/current/userguide/build_cache.html +- Configuration Cache: https://docs.gradle.org/current/userguide/configuration_cache.html +- Toolchains: https://docs.gradle.org/current/userguide/toolchains.html +- Version Catalogs: https://docs.gradle.org/current/userguide/version_catalogs.html +- Dependency Verification: https://docs.gradle.org/current/userguide/dependency_verification.html diff --git a/.agents/skills/gradle/references/micronaut-build-plugins.md b/.agents/skills/gradle/references/micronaut-build-plugins.md new file mode 100644 index 00000000..71d218d1 --- /dev/null +++ b/.agents/skills/gradle/references/micronaut-build-plugins.md @@ -0,0 +1,197 @@ +# Micronaut Build Plugin Map (Source-Backed) + +This reference is for Micronaut Framework committers. It summarizes plugin behavior from `micronaut-projects/micronaut-build` source (branch `8.0.x`), not from README prose. + +## Plugin Registration and IDs + +In `micronaut-build`, plugin IDs are generated via internal helper logic: + +- `definePlugin("", ...)` -> `io.micronaut.build.internal.` +- Exception: shared settings plugin is explicitly `io.micronaut.build.shared.settings` + +Primary registration files: + +- `micronaut-gradle-plugins/build.gradle.kts` +- `micronaut-kotlin-build-plugins/build.gradle.kts` + +## Canonical Template Entry Points + +For repositories generated from the template, default entry points are: + +- `settings.gradle(.kts)`: `io.micronaut.build.shared.settings` +- root `build.gradle(.kts)`: `io.micronaut.build.internal.parent` +- `buildSrc` convention plugin: wraps module-level internal plugins as needed + +## Project Plugins (internal IDs) + +- `io.micronaut.build.internal.aot-module` -> `io.micronaut.build.aot.MicronautAotModulePlugin` +- `io.micronaut.build.internal.base` -> `io.micronaut.build.MicronautBasePlugin` +- `io.micronaut.build.internal.base-module` -> `io.micronaut.build.MicronautBaseModulePlugin` +- `io.micronaut.build.internal.binary-compatibility-check` -> `io.micronaut.build.compat.MicronautBinaryCompatibilityPlugin` +- `io.micronaut.build.internal.bom` -> `io.micronaut.build.MicronautBomPlugin` +- `io.micronaut.build.internal.common` -> `io.micronaut.build.MicronautBuildCommonPlugin` +- `io.micronaut.build.internal.dependency-updates` -> `io.micronaut.build.MicronautDependencyUpdatesPlugin` +- `io.micronaut.build.internal.docs` -> `io.micronaut.build.MicronautDocsPlugin` +- `io.micronaut.build.internal.java-base` -> `io.micronaut.build.MicronautBuildJavaBasePlugin` +- `io.micronaut.build.internal.kotlin-base` -> `io.micronaut.build.MicronautBuildKotlinBasePlugin` +- `io.micronaut.build.internal.module` -> `io.micronaut.build.MicronautModulePlugin` +- `io.micronaut.build.internal.parent` -> `io.micronaut.build.MicronautParentPlugin` +- `io.micronaut.build.internal.parent-publishing` -> `io.micronaut.build.MicronautParentPublishingPlugin` +- `io.micronaut.build.internal.publishing` -> `io.micronaut.build.MicronautPublishingPlugin` +- `io.micronaut.build.internal.quality-checks` -> `io.micronaut.build.MicronautQualityChecksParticipantPlugin` +- `io.micronaut.build.internal.quality-reporting` -> `io.micronaut.build.MicronautQualityReportingAggregatorPlugin` +- `io.micronaut.build.internal.version-catalog-updates` -> `io.micronaut.build.catalogs.MicronautVersionCatalogUpdatePlugin` + +Kotlin-specific plugin IDs: + +- `io.micronaut.build.internal.kotlin` -> `io.micronaut.build.kotlin.MicronautBuildKotlinPlugin` +- `io.micronaut.build.internal.kotlin-kapt` -> `io.micronaut.build.kotlin.MicronautBuildKotlinKaptPlugin` +- `io.micronaut.build.internal.kotlin-ksp` -> `io.micronaut.build.kotlin.MicronautBuildKotlinKspPlugin` + +Settings plugin IDs: + +- `io.micronaut.build.internal.develocity` -> `io.micronaut.build.MicronautDevelocityPlugin` (apply in `settings.gradle(.kts)`) +- `io.micronaut.build.shared.settings` -> `io.micronaut.build.MicronautSharedSettingsPlugin` + +## High-Impact Behaviors by Plugin + +### `base` (`MicronautBasePlugin`) + +- Applies dependency resolution configuration and build extension creation. +- Validates `projectVersion` format (must start with a digit) and sets `project.version`. +- Applies configuration properties, aggregated Javadoc participant, and native image support helpers. + +### `common` (`MicronautBuildCommonPlugin`) + +- Applies `base` and quality checks participant. +- Configures Java/Groovy conventions, Spotless, Test Logger, IDEA defaults, JAR manifest attributes. +- Adds Micronaut BOM as platform when enabled. +- Enforces Micronaut core major/minor version consistency after resolution unless disabled intentionally. +- Registers `allDeps` task. + +### `java-base` (`MicronautBuildJavaBasePlugin`) + +- Applies Java plugin and aligns compile/test Java behavior from `micronautBuild` extension. +- Supports toolchains or source/target compatibility fallback. +- Configures test defaults (JUnit platform, locale normalization, Develocity test retry/PTS integration when present). + +### `kotlin-base` and Kotlin wrappers + +- `kotlin-base` bridges Kotlin JVM target to `micronautBuild.javaVersion` using reflection. +- `kotlin` applies Kotlin JVM + `kotlin-base`. +- `kotlin-kapt` and `kotlin-ksp` layer annotation processing plugin choice on top. + +### `base-module` and `module` + +- `base-module` composes common, dependency-updates, publishing, binary compatibility, Sonatype configuration, and module descriptor generation. +- Asserts expected settings plugin state through shared service registration. +- Registers POM checking once `maven-publish` is present. +- `module` adds Micronaut injection/doc processors and framework-specific test framework dependencies. + +### `bom` (`MicronautBomPlugin`) + +- Configures Java Platform + Version Catalog + publishing + binary compatibility. +- Creates `micronautBom` extension with inlining, inclusion, and exclusion controls. +- Generates and mutates BOM/catalog outputs, supports nested catalog/BOM inlining and version inference. +- Maintains helper configurations for BOM and catalog resolution/inference. + +### `dependency-updates` (`MicronautDependencyUpdatesPlugin`) + +- If root `gradle/libs.versions.toml` exists, applies catalog update plugin on root and exits. +- Otherwise, configures legacy resolution strategy and registers deprecated compatibility tasks named `dependencyUpdates` and `useLatestVersions`. + +### `version-catalog-updates` (`MicronautVersionCatalogUpdatePlugin`) + +- Root-only plugin. +- Registers `updateVersionCatalogs`, `useLatestVersions` (real catalog copy task), and compatibility `dependencyUpdates` task. +- Defaults: reject prerelease qualifiers, allow minor updates, disallow major updates. + +### `publishing` (`MicronautPublishingPlugin`) + +- Applies `maven-publish`; conditionally applies signing when credentials and keys are present. +- Populates POM metadata from project/root properties. +- Configures local build repo and optional external publishing endpoint. +- Embeds generated POM into JAR artifacts for scanner compatibility. + +### `parent` and `parent-publishing` + +- `parent` is root-oriented composition (`docs`, `quality-reporting`, `parent-publishing`). +- `parent-publishing` is root-only and non-snapshot focused; prepares Maven Central bundle and publish task. + +### `quality-checks` and `quality-reporting` + +- Participant plugin configures Checkstyle, Sonar integration hooks, and JaCoCo enablement behavior. +- Aggregator plugin is root-only; configures Sonar + Jacoco report aggregation and links subproject quality data. + +### `binary-compatibility-check` + +- Configures baseline discovery and `japicmp` checks for Java modules. +- Supports version-catalog compatibility checks for BOM modules. +- Wires into `check` and honors accepted regressions configuration files. + +### `docs` (`MicronautDocsPlugin`) + +- Creates end-to-end docs pipeline: resources, guide generation, property reference generation, assembly, validation, release dropdown, zip outputs. +- Integrates with Javadoc aggregation and GitHub tag data service. + +### `aot-module` + +- Composes `base-module`, disables standard DI/BOM processing defaults for AOT module semantics. +- Adds AOT core/context dependencies and test fixture capability wiring. + +### Shared settings plugin (`io.micronaut.build.shared.settings`) + +- Applies build settings + Develocity behavior. +- Configures project naming standardization, root version/group propagation, optional Nexus publishing setup. +- Provides settings extension APIs for importing Micronaut catalogs and including development versions from upstream repos. +- Applies `MicronautDevelocityPlugin` as part of shared settings wiring. +- Writes `micronaut-build-version` into `buildSrc/gradle.properties` when `buildSrc` exists. + +## Extension Contracts to Know + +### Project extension: `micronautBuild` + +Important properties in `MicronautBuildExtension` include: + +- `javaVersion`, `testJavaVersion` +- `checkstyleVersion` +- `dependencyUpdatesPattern` +- `enforcedPlatform` (guarded in common plugin behavior) +- `enableProcessing`, `enableBom` +- `testFramework` +- `useToolchains` +- `bomSuppressions` and compile option hooks + +### Settings extension: `micronautBuild` + +`MicronautBuildSettingsExtension` includes: + +- cache toggles (`useLocalCache`, `useRemoteCache`) +- project naming standardization controls +- catalog import helpers (`importMicronautCatalog*`) +- development-version include helper (`requiresDevelopmentVersion`) + +## Committer Triage Shortcuts + +- Micronaut version mismatch errors: inspect `compileClasspath`/`runtimeClasspath` and use `dependencyInsight`. +- Version catalog update behavior: confirm root plugin application and `gradle/libs.versions.toml` presence. +- Release issues: check signing credentials, key presence, non-snapshot constraints, and root-only publishing tasks. +- Compatibility failures: validate baseline resolution and accepted API changes config before suppressing. + +## Source Verification Pointers + +Key source files to read in `micronaut-build`: + +- Plugin registration: + - `micronaut-gradle-plugins/build.gradle.kts` + - `micronaut-kotlin-build-plugins/build.gradle.kts` +- Core plugins: + - `MicronautBasePlugin.groovy` + - `MicronautBuildCommonPlugin.groovy` + - `MicronautBuildJavaBasePlugin.java` + - `MicronautBuildKotlinBasePlugin.java` + - `MicronautModulePlugin.groovy` + - `MicronautBomPlugin.java` + - `MicronautPublishingPlugin.java` + - `MicronautDependencyResolutionConfigurationPlugin.java` + - `MicronautSharedSettingsPlugin.java` diff --git a/.agents/skills/skill-creator/SKILL.md b/.agents/skills/skill-creator/SKILL.md new file mode 100644 index 00000000..d7d56291 --- /dev/null +++ b/.agents/skills/skill-creator/SKILL.md @@ -0,0 +1,145 @@ +--- +name: skill-creator +description: 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. +license: MIT +compatibility: Compatible with Agent Skills spec and skill directories such as .agents/skills or equivalent agent-specific skill paths. +metadata: + author: local + version: "1.0.0" +--- + +# Skill Creator + +Create and refine skills that work across agents implementing the Agent Skills specification. + +Use imperative instructions. Keep the process deterministic where possible. Keep the skill output portable. + +## Objectives + +1. Produce a valid skill with a correct `SKILL.md` frontmatter and useful body instructions. +2. Keep the skill agent-agnostic unless the user explicitly requests agent-specific behavior. +3. Apply progressive disclosure so only essential content stays in `SKILL.md`. +4. Validate structure and naming before declaring completion. + +## Workflow + +### 1) Identify intent and scope + +Determine whether the user wants one of these outcomes: + +- New skill from scratch +- Update an existing skill +- Improve trigger quality (`description` tuning) +- Add reusable resources (`scripts/`, `references/`, `assets/`) + +Extract known constraints from conversation context first. Only ask for missing details that materially change implementation. + +### 2) Gather concrete examples + +Collect 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. + +Use these examples to decide: + +- Required workflow steps +- Output format expectations +- Edge cases to handle +- Whether deterministic scripts are needed + +### 3) Design the skill anatomy + +Create a minimal structure first: + +```text +/ +└── SKILL.md +``` + +Add optional directories only when justified: + +- `scripts/` for deterministic or repeated operations +- `references/` for detailed docs, schemas, and long procedures +- `assets/` for templates and static resources used in outputs + +### 4) Author `SKILL.md` frontmatter + +Set required fields: + +- `name`: lowercase, digits, hyphens; matches folder name +- `description`: what the skill does and when to use it + +Common 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. + +Description guidance: + +- Include both capability and trigger cues +- Avoid vague phrases like "helps with X" +- Prefer concrete contexts and user-language synonyms + +### 5) Author `SKILL.md` body + +Structure the body for execution, not marketing: + +1. Goal and success criteria +2. Step-by-step operating procedure +3. Input/output expectations +4. Error handling and edge cases +5. Examples +6. Validation checklist + +Write in imperative style. Explain why non-obvious constraints matter. + +### 6) Apply progressive disclosure + +Keep `SKILL.md` concise. Move large or specialized content into `references/` and link to it from `SKILL.md`. + +If the skill spans multiple variants, separate variant details into dedicated reference files and keep variant-selection logic in `SKILL.md`. + +### 7) Validate and harden + +Run a final compatibility pass: + +- Frontmatter parses as valid YAML +- `name` complies with spec constraints and folder match +- `description` is explicit about trigger contexts +- Relative file references resolve +- Optional scripts are executable and documented +- Language is agent-neutral and avoids vendor lock-in + +If `skills-ref` is available, run: + +```bash +skills-ref validate ./ +``` + +If the skills CLI is available, verify discovery from the repo root: + +```bash +npx skills list +``` + +## Agent-Agnostic Rules + +- Do not require a specific model vendor or proprietary UI affordance. +- Do not rely on agent-only file paths when portable paths exist. +- Do not reference unavailable tools as mandatory. +- Prefer open, portable commands and plain Markdown guidance. + +## Safety and integrity + +- Refuse to create skills intended for malware, exploitation, data exfiltration, or unauthorized access. +- Keep behavior aligned with user intent; avoid hidden actions. + +## Completion criteria + +A skill-creation task is complete only when all are true: + +1. Skill folder exists in the requested location. +2. `SKILL.md` is valid and complete. +3. Optional resources are present only if needed. +4. Validation checks pass or limitations are explicitly reported. + +## References + +- See `references/spec-checklist.md` for implementation rules distilled from the spec. +- See `references/templates.md` for copy-ready scaffolds. +- See `references/research-synthesis.md` for design rationale from cross-source research. diff --git a/.agents/skills/skill-creator/references/research-synthesis.md b/.agents/skills/skill-creator/references/research-synthesis.md new file mode 100644 index 00000000..2aa9af89 --- /dev/null +++ b/.agents/skills/skill-creator/references/research-synthesis.md @@ -0,0 +1,33 @@ +# Research Synthesis + +This note captures the design decisions used for `skill-creator`. + +## Sources + +- Agent Skills specification: https://agentskills.io/specification +- Anthropic skill-creator reference: + https://github.com/anthropics/skills/tree/main/skills/skill-creator +- OpenAI skill-creator reference: + https://github.com/openai/skills/tree/main/skills/.system/skill-creator +- Skills CLI reference: + https://github.com/vercel-labs/skills + +## Shared patterns extracted + +1. Core process is iterative: scope, draft, test, refine. +2. Trigger quality depends primarily on frontmatter description clarity. +3. Progressive disclosure is essential for context efficiency. +4. Optional resources should be added only when they reduce repeated work. + +## Vendor-specific elements intentionally avoided + +1. Model/provider-specific instructions and path assumptions. +2. Dependence on platform-specific UI workflows. +3. Tooling that only exists in one agent runtime. + +## Decisions in this skill + +1. Keep the main workflow in `SKILL.md` as a portable baseline. +2. Move strict checklists and scaffolds into `references/` files. +3. Include skills CLI validation guidance (`npx skills list`) and optional spec validator guidance (`skills-ref validate`). +4. Keep language imperative and implementation-focused. diff --git a/.agents/skills/skill-creator/references/spec-checklist.md b/.agents/skills/skill-creator/references/spec-checklist.md new file mode 100644 index 00000000..895228e4 --- /dev/null +++ b/.agents/skills/skill-creator/references/spec-checklist.md @@ -0,0 +1,61 @@ +# Agent Skills Spec Checklist + +Use this checklist when creating or modifying a skill to keep it compatible with the Agent Skills specification. + +Primary source: https://agentskills.io/specification + +## MUST requirements + +1. Skill is a directory containing `SKILL.md`. +2. `SKILL.md` starts with valid YAML frontmatter. +3. Frontmatter includes required fields: + - `name` + - `description` +4. `name` rules: + - 1-64 characters + - lowercase letters, numbers, hyphens only + - does not start/end with hyphen + - no consecutive hyphens + - matches parent directory name +5. `description` rules: + - 1-1024 characters + - non-empty + - states what the skill does and when to use it +6. Markdown body exists after frontmatter. + +## SHOULD guidance + +1. Keep `SKILL.md` under ~500 lines for efficient context usage. +2. Use progressive disclosure: + - keep core instructions in `SKILL.md` + - move detailed material to `references/` +3. Add `scripts/` only for deterministic or repeated work. +4. Keep file references relative to skill root. +5. Keep references shallow and easy to discover from `SKILL.md`. + +## Optional frontmatter fields + +- `license` +- `compatibility` +- `metadata` +- `allowed-tools` (experimental; support varies by agent) + +## Portability rules + +1. Avoid vendor-specific instructions unless requested by the user. +2. Avoid agent-specific path assumptions if portable paths are possible. +3. Avoid relying on non-standard tools without fallback guidance. + +## Validation commands + +If available: + +```bash +skills-ref validate ./ +``` + +For discovery checks in a workspace using skills CLI: + +```bash +npx skills list +``` diff --git a/.agents/skills/skill-creator/references/templates.md b/.agents/skills/skill-creator/references/templates.md new file mode 100644 index 00000000..1bc1a347 --- /dev/null +++ b/.agents/skills/skill-creator/references/templates.md @@ -0,0 +1,84 @@ +# Universal Skill Templates + +Use these templates as starting points. Keep them concise and agent-agnostic. + +## 1) Minimal `SKILL.md` template + +```markdown +--- +name: +description: +license: MIT +--- + +# + +## Goal + + + +## Procedure + +1. +2. +3. + +## Inputs + +- +- + +## Outputs + +- + +## Edge cases + +- +- + +## Validation + +- [ ] Frontmatter is valid YAML +- [ ] Name matches folder +- [ ] Description includes trigger contexts +- [ ] Relative file references resolve +``` + +## 2) Expanded structure template + +```text +/ +├── SKILL.md +├── scripts/ +│ └──