Tessl • The management layer for AI agent skills

SkillPublic

linear-graphql

Call the Linear GraphQL API from agent sessions in this repo — authenticate via LINEAR_API_KEY loaded from .env.local without tripping the Freebuff env guard, use shorthand issue IDs, avoid the IssueFilter/ID-typing schema traps, and flip issues or query state with scripts/linear-flip-done.mjs.

Quality

82%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Quality

Content

83%Weight 40%Scale 1-5

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

A dense, high-value skill: all knowledge is repo-specific and non-derivable, and the code is fully executable. The main gap is verification for batch/state-mutating operations — the wrapper detects GraphQL errors but never confirms the mutation actually succeeded. The inline code block is the only structural tightening candidate.

Suggestions

Add a verification checkpoint after flipping issues: check that issueUpdate returns success (e.g. `const { issueUpdate: { success } } = ...; if (!success) throw ...`) and/or re-query the issue state to confirm the flip.

Have linear-flip-done.mjs report each identifier's before/after state so a partial batch failure is visible, closing the feedback loop on the batch operation.

Consider bundling the loader + gql wrapper as a scripts/ file (the skill already tells agents to recreate linear-flip-done.mjs from it), keeping only the pattern's key lines in SKILL.md.

Dimension	Reasoning	Score
Conciseness	Every bullet is non-derivable repo knowledge (guard behavior, schema traps, raw-key auth, renamed 'Done' states) with zero filler or explanation of concepts Claude already knows; the 2026-09 mentions are provenance stamps, not date-branching API guidance, so they do not penalize.	5 / 5
Actionability	Fully copy-paste-ready: the flip command, the env-set command, and the complete JS loader + error-checking gql wrapper covering the common cases (query by shorthand id, resolve completed state, update) are all executable as written.	5 / 5
Workflow Clarity	The numbered sequence (ensure key → reuse helper → copy loader → housekeeping) is clear and gql checks the errors array, but the batch/mutating flip workflow never verifies outcomes: issueUpdate's success field is unchecked and there is no post-flip state re-query. Per the batch-operation guideline this caps at 3 — validation is missing, not merely implicit.	3 / 5
Progressive Disclosure	Well-organized single file with clear sections (Knowledge, Instructions 1–4, Housekeeping) and a compact tooling table, but the ~65-line inline loader/gql block that the skill itself says to recreate as a script is a plausible candidate for a bundled file — good structure with a minor organization gap.	4 / 5
	Total	17 / 20 Passed

Description

75%Weight 40%Scale 1-5

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

A specific, distinctive description that clearly states what the skill does with concrete, non-generic actions. Its main weakness is the missing explicit 'Use when...' trigger clause, which caps completeness, and a few natural trigger phrases (close Linear issue, Linear ticket, projects) are absent.

Suggestions

Add an explicit trigger clause, e.g. 'Use when closing or updating Linear issues, filing follow-ups, or checking tracker state from this repo.'

Include the natural user phrasings for the common case — 'close Linear issues', 'mark Linear issues done', 'Linear tickets' — alongside 'flip issues'.

Mention projects since the body covers reading/mutating 'issues, states, projects'.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — 'authenticate via LINEAR_API_KEY loaded from .env.local', 'use shorthand issue IDs', 'avoid the IssueFilter/ID-typing schema traps', 'flip issues or query state with scripts/linear-flip-done.mjs' — with comprehensive coverage of what the skill does; no gaps that would drop it to 4.	5 / 5
Completeness	The 'what' is clear (specific API actions listed), but there is no 'Use when...' clause or equivalent explicit trigger guidance — 'from agent sessions in this repo' is a scope qualifier, not a when-to-use trigger — so completeness is capped at 3 per the guideline.	3 / 5
Trigger Term Quality	Good natural terms (Linear, GraphQL, issues, state, flip) a user would plausibly say, but a few common phrasings are missing — 'close Linear issue(s)', 'Linear ticket', 'projects' — so it fits 'good keyword coverage; a few natural terms missing' rather than the comprehensive 5.	4 / 5
Distinctiveness Conflict Risk	A clear niche with distinct triggers: Linear GraphQL API, the Freebuff env guard, shorthand issue IDs, and a named repo script make it highly unlikely to fire for any other skill.	5 / 5
	Total	17 / 20 Passed

Validation

87%

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 — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
metadata_version	'metadata.version' is missing	Warning
referenced_paths_exist	Referenced path issues: 4 missing	Warning

	Total	14 / 16 Passed

Repository: pvnkmnk/vault-memory
Path: .agents/skills/linear-graphql/SKILL.md
Revision: f7f6289

Reviewed: 16 days ago

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.

linear-graphql

Table of Contents

Is this your skill?