Content
50%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.
The body is strong on concrete, executable commands and covers setup, conventions, security, and project lifecycle well, but it is badly padded — the same 'When to Use This Skill' boilerplate appears five times and command docs are duplicated — and its bulk/batch workflows lack the validation checkpoints the rubric requires. Referenced bundle files are clearly signaled but cannot be verified and some detailed reference material is inlined instead.
Suggestions
Delete the four duplicate 'When to Use This Skill' boilerplate blocks (keep at most one, merged into a proper intro) and consolidate the duplicated project-status/link-initiative documentation into a single section or into projects.md.
Add a validation step to batch operations, e.g., after `status Done ENG-101 ENG-102 ENG-103`, verify with `linear issues list` or re-query the issues before reporting success.
Move the detailed project management command reference out of SKILL.md into projects.md, keeping only quick-start commands inline, and ensure all referenced files (api.md, sdk.md, sync.md, troubleshooting.md, docs/labels.md) actually ship with the skill.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The boilerplate block "Manage Linear issues, projects, and teams / Use this skill when working with manage linear issues, projects, and teams" is repeated verbatim five times throughout the body, and the project-status/link-initiative command documentation appears twice (in 'Project Management Commands' and again in 'Projects & Initiatives'). This is noticeably verbose with several padded sections — worse than 'some unnecessary explanation'. | 2 / 5 |
Actionability | Mostly executable guidance: concrete `npx tsx scripts/linear-ops.ts ...` commands with real arguments, a valid-states table, MCP JSON config, and a full project lifecycle example. Minor gaps keep it from a 5: the MCP invocation `update_issue with id="issue-uuid", state="Done"` is illustrative rather than copy-paste ready, and several examples use ENG-XXX placeholders. | 4 / 5 |
Workflow Clarity | Sequences are clearly laid out (setup check → test connection, the 7-step project lifecycle), but batch operations such as `status Done ENG-101 ENG-102 ENG-103` and bulk project updates include no validation or verification step, which caps workflow clarity at 3 per the batch-operations rule. Not a 4 because the checkpoint gaps affect the risky bulk paths, not just minor cases. | 3 / 5 |
Progressive Disclosure | There is good intent — a reference table and one-level-deep 'See X for Y' pointers to api.md, sdk.md, sync.md, projects.md, troubleshooting.md — but the detailed project-status/link-initiative command reference is inlined in the body (duplicating what projects.md should carry), the repeated 'When to Use' blocks break section flow, and none of the referenced files exist in the bundle to verify. This fits 'some structure but could be better organized' better than the anchor-4 'most content is appropriately placed'. | 3 / 5 |
Total | 12 / 20 Passed |