Content
64%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a solid, highly actionable skill with executable GraphQL examples covering a good range of Linear operations. Its main weaknesses are verbosity from redundant query variants and a lack of explicit error-handling/validation checkpoints in multi-step workflows. The content would benefit from splitting detailed query catalogs into a separate reference file and adding feedback loops for failure scenarios.
Suggestions
Add explicit error-handling guidance: what to check after each GraphQL call (inspect `errors` array, verify `success` field), and what to do on failure (retry, introspect schema, etc.) — especially for the multi-step upload workflow.
Consolidate the four issue lookup queries into one or two with inline comments noting which fields to add/remove, or move the full catalog to a separate REFERENCE.md file.
Move introspection patterns and less-common workflows to a separate file (e.g., INTROSPECTION.md or REFERENCE.md) and link from the main skill to keep it concise.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is mostly efficient and avoids explaining what GraphQL is or how Linear works, but it includes many similar query variants (e.g., four different issue lookup queries that are largely redundant) and some introspection examples that could be consolidated. The content could be tightened by ~30% without losing actionability. | 2 / 3 |
Actionability | Every workflow includes fully executable GraphQL queries and mutations with proper variable declarations. The tool input format is clearly specified with a concrete JSON example, and the upload workflow provides a clear three-step process with the exact mutation and curl approach. | 3 / 3 |
Workflow Clarity | The upload workflow has a clear three-step sequence, and the state transition workflow correctly instructs to fetch states first. However, there are no explicit validation checkpoints or error-handling feedback loops — e.g., no guidance on what to do if fileUpload fails, if the curl upload returns an error, or if a GraphQL errors array is returned beyond the initial mention to treat it as failure. | 2 / 3 |
Progressive Disclosure | The content is well-structured with clear section headers and logical grouping, but it's a long monolithic file (~250 lines) with no references to external files. The many query variants and introspection patterns could be split into a reference file, keeping the SKILL.md as a concise overview with links to detailed examples. | 2 / 3 |
Total | 9 / 12 Passed |