Content
88%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 strong procedural skill body: executable commands, concrete conventions with real examples, and a clearly sequenced workflow with genuine validation checkpoints (stop-and-ask, permission-before-push, duplicate detection, post-push sync). Weaknesses are minor — slight cross-reference repetition and an inconsistent heading hierarchy with some example content that could be split into a reference file.
Suggestions
Nest the Step 1–4 headings under "Creating a new request" (use ### instead of ##) so the section hierarchy matches the document's logical structure.
Move the ten title examples and the per-item documentation-checklist rules into a one-level-deep references file (e.g. references/title-conventions.md), keeping only the format rules and 2–3 illustrative examples inline.
De-duplicate the empty-description cross-reference (stated in both "Editing an existing request" step 2 and the "Creating a new request" intro) and the repeated 'read the template fresh' instruction in Step 3.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with non-obvious, repo-specific rules ("For an existing request, use `production` unless the user asked for a different base", "If the stat output shows more than ~20 files changed, do **not** run the full diff") and avoids explaining concepts Claude already knows. It is not a 5 because of minor repetition: the empty-description cross-reference is stated in both "Editing an existing request" and "Creating a new request", and "Do not rely on any hardcoded version of the template — always read it fresh from disk" restates the preceding sentence. | 4 / 5 |
Actionability | Guidance is copy-paste executable: concrete git commands (`git diff <base>...HEAD --stat`), exact file paths for inference ("Read the `title` field from `src/content/docs/{slug}/index.mdx`"), ten real title examples, and summary examples at three sizes. The provider-tool abstraction ("Use the available integration or authenticated CLI for that provider") is explicitly justified flexibility ("Do not assume a provider or hardcode a remote URL"), not vagueness, so it does not lower the score. | 5 / 5 |
Workflow Clarity | Creating a new request is sequenced as explicit Steps 1–4 with validation checkpoints throughout: "If `git status` shows untracked or modified files, stop and ask the user", "check for an existing open request with the same head branch... instead of creating a duplicate", "ask for permission before pushing", and the post-push loop comparing title/body against the full branch diff and updating if "inaccurate or incomplete". Error-recovery paths ("If no provider integration or authenticated CLI is available, stop and explain the blocker") and checklist handling for the complex pruning decision complete the anchor-5 fit. | 5 / 5 |
Progressive Disclosure | The body has no bundle files (no references/, scripts/, or assets/ exist) and is well-sectioned (Repository operations, Editing, After pushing, Creating Steps 1–4, Output), keeping the ~200 lines navigable as a single procedural document. It is not a 5 because the heading hierarchy is inconsistent — "## Step 1 — Gather context" sits as a sibling of "## Creating a new request" rather than nested under it — and content like the ten title examples and per-item checklist rules could plausibly live in a one-level-deep reference file to slim the always-loaded body. | 4 / 5 |
Total | 18 / 20 Passed |