## Context

The `gradle-mcp` server ships five skills in `src/main/skills/` providing expert guidance on using Gradle MCP tools. The `gradle` skill (347 lines) is the only mixed-audience skill: it serves both Gradle users (software engineers running builds/tests) and build authors (engineers writing/maintaining build scripts and plugins).

Content mixing manifests in three ways:
1. **Constitution**: Rules 1-10 target Gradle users (tool invocation, path syntax, test selection), while rules 11-20 target build authors (Kotlin DSL, lazy APIs, version catalogs, configuration cache).
2. **Directives**: "Idiomatic DSL Patterns" section is entirely build-author content, sandwiched between tool-usage and workflow sections.
3. **Workflows**: "Running a Foreground Build" (user) sits next to "Performance Audit" / "Build Logic Refactoring" (author).

Additionally, the 36 best-practices detail files (~2,500 lines) are entirely build-author content but reside physically under `gradle/references/best-practices/` and are generated by `GenerateBestPracticesDoc.kt` which writes to that path.

The other 4 skills (`exploring_dependency_sources`, `managing_gradle_dependencies`, `interacting_with_project_runtime`, `verifying_compose_ui`) are cleanly targeted at Gradle users.

The 2026-05-07 consolidation correctly unified tool-usage guidance but inadvertently trapped build-authoring content inside a user-facing skill. This change reverses that specific over-consolidation.

## Goals / Non-Goals

**Goals:**
- Split build-authoring content from `gradle` into a dedicated `gradle-build-authoring` skill
- Move best-practices (generated content) to co-locate with the build-authoring skill
- Author 10 new gap-filling reference documents for build authoring
- Update frontmatter descriptions to ensure precise agent routing
- Preserve all unique workflows, rules, and examples — only relocate and expand

**Non-Goals:**
- Do NOT change the other 4 skills (they are already cleanly targeted)
- Do NOT change `SkillTools.kt` or `build.gradle.kts` (build configuration)
- Do NOT hand-edit generated best-practices files
- Do NOT change MCP tool implementations or signatures

## Decisions

### Decision 1: Move best-practices generator output to gradle-build-authoring

The `best-practices/` directory under `gradle/references/` is physically moved to `gradle-build-authoring/references/best-practices/` by changing the output path in `GenerateBestPracticesDoc.kt`.

**Rationale**: All 36 best-practices detail files target build authors (convention plugins, lazy APIs, version catalogs, task registration patterns). Co-locating them with the build-authoring skill is architecturally clean and eliminates cross-directory relative path references. The `zipSkills` task handles subdirectories recursively, so no packaging changes are needed.

**Alternative considered**: Keep best-practices under `gradle/references/` and cross-reference from `gradle-build-authoring` via `../gradle/references/...` paths. Rejected because all best-practices content is build-author material; having it under a different skill's directory creates a confusing ownership model and fragile cross-skill path dependencies.

### Decision 2: `common_build_patterns.md` stays under gradle/references/ with cross-reference

`common_build_patterns.md` remains at `gradle/references/common_build_patterns.md`. The `gradle-build-authoring` skill references it via relative path `../gradle/references/common_build_patterns.md`.

**Rationale**: This file is hand-authored, not generated. Moving it would require updating the existing reference path in the `gradle` skill and could break any external consumers. A single cross-reference path (`../gradle/references/common_build_patterns.md`) is manageable and keeps blast radius minimal.

### Decision 3: `gradle_docs` rule duplicated in both skills

The "ALWAYS use `gradle_docs` for authoritative documentation lookup" rule appears in both skills.

**Rationale**: Documentation research serves both audiences: Gradle users lookup build diagnostic info (`tag:release-notes`, `tag:userguide`), while build authors research build-quality patterns (`tag:best-practices`). The scoping differs by skill (diagnosis vs. research), so each skill frames `gradle_docs` usage appropriately. This avoids the need for cross-skill `gradle_docs` routing logic.

**Alternative considered**: Keep `gradle_docs` only in `gradle` and have `gradle-build-authoring` reference it. Rejected because it breaks the principle that `gradle-build-authoring` should be a fully standalone skill with no missing capabilities.

### Decision 4: Version bumps — gradle to "5.0", gradle-build-authoring to "1.0"

The `gradle` skill version increments to "5.0" reflecting the major restructure (build-authoring content removed). The new `gradle-build-authoring` skill starts at "1.0".

**Rationale**: Clear version signals. "5.0" communicates a breaking/restructuring change to the gradle skill. "1.0" signals the initial release of the new dedicated skill.

## Risks / Trade-offs

| Risk | Mitigation |
|------|------------|
| **Cross-skill relative paths** — `gradle-build-authoring` references `../gradle/references/common_build_patterns.md` which may not resolve at runtime if `SkillTools.installSkills` copies to a flat directory | Verify `SkillTools.installSkills` preserves directory nesting during install. If not, copy shared refs into `gradle-build-authoring/references/` during zip packaging as a fallback. |
| **Agent routing overlap** — Both skills mention `gradle_docs`. An agent may activate both simultaneously. | Frontmatter negative triggers make boundaries explicit. `gradle` scopes `gradle_docs` to lookup during diagnosis; `gradle-build-authoring` scopes it to build-quality research. |
| **Skill count increase (5 to 6)** — Adds agent discovery overhead | Mutually exclusive frontmatter descriptions with clear negative triggers minimize incorrect activation. |
| **`:properties --property` rule** — Could be accidentally removed from both skills | Explicitly preserve it in `gradle` constitution (tool-usage pattern). Not in scope for `gradle-build-authoring`. |
| **Generator path change breaks existing installs** — Existing projects with stale best-practices under `gradle/references/` | Best-practices are read-only references that get regenerated on next `zipSkills` run. No runtime dependency on the old path. The stale content may remain under `gradle/references/best-practices/` until manually cleaned. |

## Open Questions

- Should `SkillTools.installSkills` be updated to handle the new skill directory, or does it auto-discover by scanning `src/main/skills/`? (Per the 2026-05-07 consolidation design, it scans by directory — so no changes needed, but verify during implementation.)
