Content
81%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.
This is a highly actionable, well-sequenced setup skill: exact commands, file paths, env writes, and validation gates with genuine error-recovery guidance in Troubleshooting. Its main weakness is repetition — the @-mention fact and several operational caveats are stated multiple times, and a hard-pinned dependency version will drift. Structure is good for a single-file skill, though Troubleshooting and Channel Info could live in a reference file.
Suggestions
State the "Linear OAuth apps can't be @-mentioned, so the agent answers every comment" fact once (intro or Channel Info) and cut the repeats in the Apply preamble, Wiring, and Channel Info.
De-duplicate the WEBHOOK_HOST=0.0.0.0 guidance — keep it in one place (Troubleshooting or the Credentials prompt), not both.
Flag the pinned "@chat-adapter/linear@4.41.1" version as time-sensitive (e.g. a short maintenance note on how to re-pin) so the exact version doesn't silently go stale.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The prose is project-specific and operational, but the same facts repeat: "no @-mention needed" / "Linear can't be @-mentioned" appears in the intro ("Every comment on a Linear issue triggers the agent — no @-mention needed"), the Apply preamble, Wiring ("Linear can't be @-mentioned, so the agent answers every comment"), and Channel Info ("No @-mention needed (Linear OAuth apps can't be @-mentioned)"); the WEBHOOK_HOST=0.0.0.0 guidance appears in both the Credentials prompt and Troubleshooting; self-message filtering is explained three times. This is more than the "minor instances" of the 4 anchor, though the content itself is not padded with concepts Claude already knows, so it sits above a 2; the time-sensitive pinned version "@chat-adapter/linear@4.41.1" also counts against conciseness per the rubric guidelines. | 3 / 5 |
Actionability | Fully executable throughout: exact directive fences with file paths ("src/channels/linear.ts", "nc:append to:src/channels/index.ts"), copy-paste commands ("pnpm exec vitest run src/channels/linear-registration.test.ts", "ncl messaging-groups create --channel-type linear --platform-id linear:{{linear_team_key}} ..."), exact env var names, and concrete Linear UI navigation ("Linear Settings > API > Webhooks > New webhook"). The common cases are covered, including the fallback Personal-API-key path. | 5 / 5 |
Workflow Clarity | The sequence (Prerequisites → Apply → Credentials → Wiring → Next Steps) has an explicit validation gate — "Both must be clean before proceeding" after the build and test steps — plus explained failure semantics and error-recovery loops in Troubleshooting ("red means the barrel import or the @chat-adapter/linear install drifted, so re-run the Apply steps"). This matches the anchor for clear sequencing with explicit validation and feedback loops. | 5 / 5 |
Progressive Disclosure | A single-file skill (no references/, scripts/, or assets/ bundle) with well-organized, clearly headed sections (Prerequisites, Apply, Credentials, Wiring, Next Steps, Channel Info, Troubleshooting) and no nested references — the one external pointer ("see the GitHub skill for adding members") is one level and clearly signaled. It is not a 5 because the file runs ~200 lines with Channel Info and Troubleshooting as candidate material for a separate reference file, and there is no overview/navigation of the sections. | 4 / 5 |
Total | 17 / 20 Passed |