Content
68%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A well-structured contributor guide that front-loads the authoritative repo documents, enforces a package-visibility boundary, and provides exact Breeze/E2E/Gradle commands. Its main gaps are the absence of validation checkpoints inside the multi-step workflows (upgrade and coordinator changes are not tied back to running tests) and some inline architectural depth that a reference file could absorb.
Suggestions
Append a validation step to the schema-upgrade and coordinator-change workflows (e.g. "then run `breeze testing task-sdk-tests -- task_sdk/coordinators/java` to verify").
Move the fat-JAR/thin-JAR manifest and scan mechanics into a reference file (or the already-referenced README) and keep only the Main-Class / schema-version essentials in SKILL.md.
In the 'Running tests' section, state which test suite verifies which change type (Gradle vs Breeze vs E2E) so a contributor knows which command to run after an edit.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with project-specific facts Claude cannot know (manifest attributes, wire-protocol negotiation, package visibility rules, exact test commands) with almost no general-concept padding. Not 5: the bundle-composition section spends several sentences on fat-JAR vs thin-JAR mechanics and the manifest-scan flow that could be tightened; not 3 because there are no unnecessary explanations of things Claude already knows. | 4 / 5 |
Actionability | Gives copy-paste-ready commands — `breeze testing task-sdk-tests -- task_sdk/coordinators/java`, the E2E `uv run ... pytest` invocation, `./gradlew generateJsonSchema2Pojo` — plus the hard rule "Always use `./gradlew` from inside `java-sdk/`; never run Gradle via apt's `gradle". Not 5: the architecture and coordinator sections are descriptive guidance rather than executable steps, and the full Gradle command list is deferred to the README; not 3 because the commands that are present are concrete and complete. | 4 / 5 |
Workflow Clarity | Tasks are grouped into clear sections (tests, coordinator update, schema upgrade), but workflows lack validation checkpoints: the upgrade section is just "Regenerate models with `./gradlew generateJsonSchema2Pojo`" → "Modify `execution/Client.kt` to handle changes" with no step telling the contributor to run the coordinator or E2E tests afterward, and the test commands sit in a separate section without being wired into the workflows. Not 4: checkpoints are not merely minor gaps, they are absent from the sequences; not 2 because the sections do give a coherent rough order and specific commands. | 3 / 5 |
Progressive Disclosure | No skill bundle files exist, and the body correctly defers bulk detail to two well-signaled one-level-deep repo documents ("Read these two documents early in every session": `airflow-core/docs/.../java.rst` and `java-sdk/README.md`) with section anchors like `java-sdk/README.md#testing` and `#contributing`, plus a key-files table for navigation. Not 5: the ~30-line bundle-composition/manifest-scan walkthrough is inline detail that arguably belongs in a reference file or the README; not 3 because the structure is well organized and every reference is explicitly signposted. | 4 / 5 |
Total | 15 / 20 Passed |