Content
62%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is highly actionable with excellent workflow clarity, providing specific commands and clear decision points throughout a well-sequenced multi-step process. However, it is significantly over-verbose — the lint gate sub-workflow, sketch cleanup conditional logic, and exhaustive error handling inflate the token cost substantially. Much of this detail should be moved to reference files, keeping the main skill as a lean orchestration overview.
Suggestions
Extract the Lint and Format Gate (Step 3, sub-step 3) into a separate reference file like `references/lint-gate.md` — it's ~40 lines of conditional logic that bloats the main workflow.
Move Step 5b (Sketch Cleanup) into a reference file like `references/sketch-cleanup.md` — it handles multiple paradigms and statuses that don't need to be inline.
Consolidate the Error Handling section into a reference file or significantly compress it — many entries (e.g., 'Git not available — inform user, exit') are obvious behaviors Claude can infer from the workflow steps themselves.
Remove explanatory phrases like 'This skill handles the entire shipping workflow: verifying git state, ensuring the user is on the right branch...' from the intro — the workflow steps already make this clear.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is extremely verbose at ~300+ lines with extensive detail on lint gate sub-options, sketch cleanup paradigm-conditional logic, feature tracker integration, and exhaustive error handling. Much of this could be condensed or moved to reference files. Claude doesn't need this level of hand-holding for git operations, option menu formatting, or conditional branching logic. | 1 / 3 |
Actionability | The skill provides specific, executable git commands throughout (e.g., `git branch --show-current`, `git push -u origin <branch-name>`, `gh pr create --title "..." --body "..."`), concrete CLI invocations for both GitHub and Bitbucket platforms, and clear decision trees with exact user-facing prompts. Every step has copy-paste ready commands. | 3 / 3 |
Workflow Clarity | The workflow is clearly sequenced (Steps 1-6) with explicit validation checkpoints: git state verification before proceeding, lint gate with 3-option resolution, sensitive file scanning before staging, push rejection handling with rebase suggestion, and PR creation gated on auth status. Feedback loops are present (lint fix → re-run, push rejected → pull rebase → retry). | 3 / 3 |
Progressive Disclosure | The skill references external files like `feature-tracker-update.md` and `platform-labels.md` appropriately, and Step 6 correctly defers to a reference file. However, the massive inline content for lint gate logic (Step 3.3), sketch cleanup (Step 5b), and the exhaustive error handling section should be split into reference files rather than inlined. The main SKILL.md tries to be both overview and complete reference. | 2 / 3 |
Total | 9 / 12 Passed |