linear

Use Symphony's `linear_graphql` client tool for raw Linear GraphQL operations such as comment editing and upload flows.

1.58x

Quality

61%

Does it follow best practices?

Impact

84%

1.58x

Average score across 3 eval scenarios

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.codex/skills/linear/SKILL.md

Quality

Content

65%Weight 40%Scale 1-3

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is highly actionable, packed with executable, copy-paste-ready GraphQL and clear operational rules, and it avoids explaining concepts Claude already knows. Its main weaknesses are duplicated field selections across query variants, a missing verification checkpoint in the upload workflow, and no progressive disclosure into separate reference files.

Suggestions

Add an explicit verification step to the video-upload workflow, e.g. 'Confirm the curl PUT returned 2xx and assetUrl resolves before calling commentCreate; if it fails, re-run fileUpload.'

Tighten the duplicated issue-lookup queries by showing one canonical field set and noting only the differing argument (key vs identifier vs internal id) for the variants.

Consider splitting introspection patterns and the full query catalog into a references file (e.g. references/queries.md) to reduce inline length while keeping SKILL.md a focused overview.

Dimension	Reasoning	Score
Conciseness	It assumes Claude's competence (no GraphQL/introspection basics explained) and is mostly code, but field selections are duplicated across four issue-lookup queries and four introspection snippets could be consolidated.	2 / 3
Actionability	Nearly the entire body is concrete, copy-paste-ready GraphQL queries and mutations with variables and field selections, and the upload flow specifies exact curl commands and headers.	3 / 3
Workflow Clarity	The issue-lookup progression and 'fetch team states first' are clearly sequenced, but the multi-step video upload lacks an explicit verification checkpoint, relying only on the general 'treat the errors array as failure' rule.	2 / 3
Progressive Disclosure	Headers are well organized with easy in-page navigation, but it is a single ~390-line file with no bundle references, and introspection patterns and query variants are inline content that could be split out.	2 / 3
	Total	9 / 12 Passed

Description

57%Weight 40%Scale 1-3

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description names a specific, distinctive tool and niche with a couple of concrete action areas, but it omits explicit 'when to use' trigger guidance and its keywords are narrow and technical. Adding a Use-when clause and broader natural trigger terms would raise it substantially.

Suggestions

Add an explicit trigger clause, e.g. 'Use when you need to edit Linear comments, upload files/attachments to Linear issues, or run ad-hoc Linear GraphQL queries during a Symphony session.'

Broaden natural trigger terms to include phrases users actually say, such as 'Linear issue', 'Linear ticket', 'Linear API', and 'upload a video to a Linear comment'.

Expand the action list beyond two hedged examples ('comment editing and upload flows') to name more concrete operations like querying issues, moving issue state, and attaching GitHub PRs.

Dimension	Reasoning	Score
Specificity	Names the tool and domain plus two action areas ('comment editing and upload flows'), but the 'such as' hedge and only two vague categories fall short of a rich multi-action list.	2 / 3
Completeness	Clearly states what the skill does but lacks any 'Use when...' trigger clause, so per the rubric completeness is capped at 2.	2 / 3
Trigger Term Quality	Relevant keywords ('Linear GraphQL', 'comment editing', 'upload flows', 'linear_graphql') are present but narrow and jargon-heavy, missing common user variations like 'Linear issue' or 'upload video to Linear'.	2 / 3
Distinctiveness Conflict Risk	Names Symphony's specific 'linear_graphql' client tool and the raw Linear GraphQL niche, making it highly distinct and unlikely to trigger for the wrong skill.	3 / 3
	Total	9 / 12 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: openai/symphony
Path: .codex/skills/linear/SKILL.md
Commit: f8e8b8a

Reviewed: 6 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.