
linear
Linear project management: MCP/GraphQL API, VantageEx epic authoring, auditing, and grooming
- version
- 0.1.10
- GitHub stars
- 27
Install
/plugin install linear@vinnie357Run it inside Claude Code after adding the marketplace with /plugin marketplace add vinnie357/claude-skills.
Contents
Discovered from sourceSkills 1
Linear
Manage Linear issues, author VantageEx-compatible epics, and interact with the Linear API via MCP or direct GraphQL.
MCP Setup (Preferred)
The Linear MCP server provides tool-based access to Linear. Set up once:
claude mcp add --transport http linear-server https://mcp.linear.app/mcp
Then run /mcp in a Claude Code session to complete OAuth authentication (opens browser).
After setup, use MCP tools directly for all Linear operations. The MCP server handles authentication and provides structured tool interfaces.
For full setup details, troubleshooting, and alternative client configurations, read references/mcp-setup.md.
GraphQL Fallback
When MCP is unavailable (headless environments, scripting, CI), use the GraphQL API directly.
Endpoint: https://api.linear.app/graphql
Auth: Bearer token via LINEAR_API_KEY environment variable
# Test connectivity
curl -s -H "Authorization: Bearer $LINEAR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "{ viewer { id name email } }"}' \
https://api.linear.app/graphql
For the full query catalog, read references/graphql-api.md.
The nushell client at scripts/0.1.0/linear.nu wraps common GraphQL operations.
Common Operations
Query an Issue
By key (e.g., MT-686):
query IssueByKey($key: String!) {
issue(id: $key) {
id identifier title url description
state { id name type }
project { id name }
labels { nodes { name } }
attachments { nodes { title url sourceType } }
}
}
Create an Issue
mutation CreateIssue($teamId: String!, $title: String!, $description: String, $stateId: String, $labelIds: [String!]) {
issueCreate(input: {
teamId: $teamId
title: $title
description: $description
stateId: $stateId
labelIds: $labelIds
}) {
success
issue { id identifier url }
}
}
Update Issue State
Always fetch team workflow states first to get the exact stateId:
query IssueTeamStates($id: String!) {
issue(id: $id) {
team {
states { nodes { id name type } }
}
}
}
Then transition:
mutation MoveIssue($id: String!, $stateId: String!) {
issueUpdate(id: $id, input: { stateId: $stateId }) {
success
issue { id identifier state { name } }
}
}
Add a Comment
mutation CreateComment($issueId: String!, $body: String!) {
commentCreate(input: { issueId: $issueId, body: $body }) {
success
comment { id url }
}
}
Attach a GitHub PR
Prefer the GitHub-specific mutation for PR metadata:
mutation AttachPR($issueId: String!, $url: String!, $title: String) {
attachmentLinkGitHubPR(issueId: $issueId, url: $url, title: $title, linkKind: links) {
success
attachment { id title url }
}
}
List Workflow States
query TeamStates($teamId: String!) {
team(id: $teamId) {
states { nodes { id name type position } }
}
}
Introspection
When an unfamiliar mutation or type is needed, query the schema:
query ListMutations {
__type(name: "Mutation") { fields { name } }
}
query InspectInput($typeName: String!) {
__type(name: $typeName) {
inputFields { name type { kind name ofType { kind name } } }
}
}
VantageEx Epic Format
VantageEx epics follow a three-level hierarchy: Epic (user-authored) -> Issues (team leader creates) -> Tasks (agents create).
The user authors the epic description in Linear. The epic body uses markdown sections that VantageEx parses.
Required Sections
| Section | Purpose | Author |
|---|---|---|
## Objective | 2-3 sentences defining success criteria | User (immutable) |
## Skills | Domain-specific skills needed (core skills implicit) | User (immutable) |
## Repos | Target repositories | User (immutable) |
Optional Sections
| Section | Purpose | Author |
|---|---|---|
## Instructions | User guidance added at re-queue (ADR-027) | User or dashboard |
## Constraints | Boundaries (defaults: mise run ci, no attribution, squash merge) | User |
## Agents | Priority-ordered agent CLIs from {claude, codex, antigravity, local} (default [claude]) | User |
## Team | Claude model layer: lead, default, escalation (applies when Agents resolves to claude) | User |
## Escalation | Failure and ambiguity policies | User |
## PR | Pull request URL when submitted | Agent |
Title and Slug
- Title: Imperative statement ("Implement OAuth2 PKCE flow for API gateway")
- Slug: kebab-case, max ~30 chars, URL-safe (
oauth-pkce-flow) - Branch:
feature/<epic-slug>
For the full epic specification with examples and anti-patterns, read references/epic-format.md.
Epic Body Format Rules
Epic bodies use plain markdown for every section. Parsers that ingest epic bodies (including the /linear:audit-epics command and downstream consumers) capture YAML fences as garbage labels.
No YAML fences in epic bodies
WRONG:
## Skills
```yaml
- skill1
- skill2
```
CORRECT:
## Skills
- skill1
- skill2
Skills, Repos, and Constraints sections all use plain bullet lists. Code fences in these sections produce empty or junk labels in the parser output.
Skill-label discipline
Skill labels listed in the epic body must exist in the claude-skills marketplace at https://github.com/vinnie357/claude-skills/blob/main/.claude-plugin/marketplace.json. The audit command checks this; missing labels are flagged.
Core skills are implicit and MUST NOT be listed in epic bodies: anti-fabrication, git, tdd, twelve-factor, security, mise, nushell. Listing them adds noise without value — every epic loads them by default.
Self-contained content
Epic bodies are self-contained. Workers pick up epics on any machine; local-filesystem paths (~/.claude/plans/..., /Users/<name>/...) resolve only on the author's system and fail everywhere else.
WRONG — points at a local file:
See `~/.claude/plans/foo.md` for the design context.
CORRECT — embed the content inline under a ## Design context (or similarly named) section, or link to another epic by URL:
## Design context
[full design content pasted here]
## Instructions
Design rationale lives in the paired docs epic [VIN-316](https://linear.app/...).
When a design plan is too large for a single body, split into paired epics (docs + implementation) linked by URL. Each epic carries its own self-contained context; cross-references between epics use URLs, never filesystem paths.
Initial state
New epics start in Backlog. Labels are team-scoped; missing skill labels auto-create on first use via issueLabelCreate.
Workflow States
Linear uses typed workflow states. VantageEx maps these to its lifecycle:
| VantageEx Status | Linear State | Meaning |
|---|---|---|
ready | Backlog / Ready | Epic in backlog, all fields present |
up_next | Up Next | User approved for agent work |
in_progress | In Progress | Agent actively working |
needs_help | Needs Help | Agent exhausted fix cycles |
review | In Review | CI passed, PR created |
complete | Done | PR merged |
archived | Archived | Hidden from dashboard |
Key transitions:
ready->up_next: User only (the gate)up_next->in_progress: EpicPickerWorker (automatic)in_progress->needs_help: ValidateWorker (after 3 fix cycles)needs_help->up_next: User re-queues with## Instructionsin_progress->review: Agent submits PRreview->complete: User merges PR
For the full state machine and cross-system mapping, read references/workflow-states.md.
Commands
| Command | Purpose |
|---|---|
/linear:plan-epic | Create a new VantageEx-compatible epic in Linear |
/linear:audit-epics | Audit existing epics for VantageEx compatibility |
/linear:groom-epics | Fix issues found by audit |
References
| File | Content |
|---|---|
references/mcp-setup.md | Linear MCP server setup and troubleshooting |
references/graphql-api.md | Full GraphQL query catalog |
references/epic-format.md | VantageEx epic specification |
references/audit-checklist.md | Epic validation checks |
references/epic-sizing.md | Epic sizing heuristics and dependency-ordering conventions |
references/workflow-states.md | State machine and cross-system mapping |
Templates
| File | Content |
|---|---|
templates/0.1.0/epic.md | Epic description template |
templates/0.1.0/audit-report.md | Audit output format |
templates/0.1.0/team-definition.md | Team section template |
Scripts
| File | Content |
|---|---|
scripts/0.1.0/linear.nu | Nushell GraphQL client for non-MCP use |
Usage Rules
- Prefer MCP tools over raw GraphQL when the Linear MCP server is configured
- For state transitions, always fetch team states first — never hardcode
stateIdvalues - Prefer
attachmentLinkGitHubPRoverattachmentLinkURLwhen linking GitHub PRs - Keep queries narrow — request only the fields needed
- Treat top-level
errorsarray in GraphQL responses as failures - When writing epic descriptions, follow the section format exactly — VantageEx parses these programmatically
Commands 3
Audit existing Linear epics for VantageEx compatibility.
Steps
- Load the
/linearskill - Read the audit checklist at
references/audit-checklist.md - Read the audit report template at
templates/0.1.0/audit-report.md
Fetch Issues
Determine scope from arguments:
--issue=<key>: Audit a single issue by key (e.g., MT-123)--project=<slug>: Audit all issues in a project--state=<state>: Filter by Linear state type (e.g., "started", "unstarted", "completed")- No arguments: Ask the user which project or issues to audit
Use Linear MCP tools (preferred) or GraphQL to fetch issues with their full descriptions, states, labels, and attachments.
Run Checks
For each issue, run every check from the audit checklist:
Structure Checks
- Parse description for
## Objective,## Skills,## Repossections - Validate objective quality (2-3 sentences)
- Validate skills exist in marketplace (read marketplace.json)
- Check for core skills that should not be listed
Team Checks
- Check for
## Teamsection - Check for escalation policy
Naming Checks
- Evaluate title quality (imperative statement)
- Check slug derivability
- Check branch naming convention if branch exists
State Consistency Checks
- For completed/review issues: check for
## PRsection or GitHub PR attachment - For needs_help issues: check for blocker documentation
- Use
gh pr listandgh pr viewto cross-reference PR URLs
Epic-Sizing Checks
See references/epic-sizing.md for thresholds.
- Flag epics with > 8 issues — signal to split the epic
- Flag issues with > ~10 target files — exceeds one worker session
- Flag multi-deliverable issue titles (joined by "and", "also", "then", "plus") — split them
- Flag acceptance criteria that cannot be verified in a single worker session
- Flag issues with cross-subsystem or cross-repo scope — split candidates
Dependency-Ordering Checks
See references/epic-sizing.md for conventions.
- Flag issues with implicit or missing dependency declarations (no blocking relations / bees deps)
- Flag dependency cycles — halt: re-decompose required before queueing
- Flag dependency chains deeper than 5 levels — serializes workers unnecessarily
- Flag independent issues that are serialized without cause — reduces worker fan-out
- Flag a DAG source issue that is itself marked
blockedByanother issue — inconsistent foundational ordering
Generate Report
Use the templates/0.1.0/audit-report.md format:
- Summary table with counts by severity
- Per-issue findings sorted by error count (most errors first)
- Each finding includes: check name, severity, status, detail
- Remediation actions for each failing check
Output
Present the report to the user. Suggest running /linear:groom-epics to fix errors and warnings automatically.
Fix VantageEx compatibility issues across one epic or a whole project. Scoped, pre-flight-gated, and offloads the audit pass to a haiku mapper so the parent session never holds full descriptions for an entire project.
Steps
- Load the
/linearskill - Read the epic format spec at
references/epic-format.md - Read the audit checklist at
references/audit-checklist.md - Read the team definition template at
templates/0.1.0/team-definition.md
Phase A — Pre-flight
Run on every invocation. Halt with a clear message if any check fails — never partial-progress.
-
Verify Linear access. Pass if either:
- The Linear MCP server is registered (
claude mcp listshows alinear-serverentry), OR LINEAR_API_KEYenvironment variable is set.
If neither, halt with:
Linear access is not configured. Set up one of:
claude mcp add --transport http linear-server https://mcp.linear.app/mcpthen/mcpto authenticateexport LINEAR_API_KEY=<key>(see https://linear.app/settings/account/security)
- The Linear MCP server is registered (
-
Resolve scope from arguments:
--issue=<key>(e.g.,--issue=VIN-42) → single-issue path. Skip Phase B; audit + groom inline.--project=<slug>→ project path. Continue to Phase B.- Neither → ask the user which scope.
-
For project scope: identify open-state IDs. Query the team's
workflowStatesand keep only states whosetypeis in{triage, backlog, unstarted, started}. Exclude any state whosetypeiscompletedorcanceled— grooming closed epics is forbidden and would mutate finished work. -
Count candidates. Query the project for issues in the open-state IDs only. Print the count.
-
Overload gate. If
count >= --max-issues(default50), refuse to proceed without--confirm-bulk. Suggest narrowing with--issue=<key>or batching as a follow-up. This is a hard gate —--autodoes not bypass it.
Phase B — Mapper (project scope only)
Spawn a single read-only haiku agent to audit all candidates and return a compact digest. The parent session never holds the full descriptions.
Use the Task tool with subagent_type: Explore and model: haiku. The mapper prompt:
## Load skills
Load these by exact name (no globs):
- /linear (provides MCP/GraphQL helpers and the epic format spec)
- /core:anti-fabrication (no claim without tool verification)
Quote one sentence from each loaded skill in your first response.
## Task
You are auditing Linear epics for VantageEx compatibility. READ-ONLY — do not write to Linear.
For each issue in the candidate list, fetch via Linear MCP (preferred) or GraphQL:
- identifier, url, title, state.name, state.type, labels, attachments
- full description
Run the structure + content checks from `references/audit-checklist.md`:
- Objective Present, Objective Quality
- Skills Present, Skills Valid, Skills Not Listing Core
- Repos Present
- Agents Valid, Agents Section Non-Empty
- Team Defined
- PR on Completed (only for state.type == "started" with a state.name suggesting review)
- Implementation Details
Return JSON, sorted by error_count desc, truncated to top 25:
[
{
"identifier": "VIN-42",
"url": "https://linear.app/...",
"state_type": "started",
"state_name": "In Progress",
"error_count": 2,
"warning_count": 1,
"info_count": 0,
"findings": [
{"check": "Objective Present", "severity": "error"},
{"check": "Agents Valid", "severity": "warning", "detail": "gemini -> antigravity"}
]
}
]
Do not include description bodies in the response. The groom phase re-fetches them.
Phase C — Groom
For single-issue scope: audit the one issue inline, then proceed to fix. For project scope: iterate over the mapper digest.
For each entry:
-
Re-fetch the full issue body via MCP or GraphQL (only at fix time — Phase B kept tokens cheap).
-
Apply fixes per check:
Missing Objective
- If the title is descriptive, generate a 2-3 sentence objective from the title and any existing content
- Ask the user to confirm before applying
--autoskips this fix (content change requires human review)
Missing Skills
- Suggest skills from the title and description
- Validate against
marketplace.json - Ask the user to confirm the skill list
Missing Repos
- Check the description and comments for repo names
- Ask the user to specify if none can be inferred
Missing Team
- Insert the default team definition:
lead: sonnet, default_model: haiku, escalation: haiku -> sonnet -> opus - Apply without asking (safe default)
Core Skills Listed
- Strip core skills (
anti-fabrication, git, tdd, twelve-factor, security, mise, nushell) automatically
Invalid Agents
- Confirm with the user before any rewrite
- Rewrite
gemini→antigravity(the Google CLI runs Gemini) - Flag any other unknown value (e.g.,
gpt4,bard) — do not auto-rewrite
Empty Agents Section
- Ask the user: remove the empty header (default
[claude]applies) or fill in agents - No auto-fix — intent is ambiguous
Missing PR on Completed
- Search via
gh pr list --search "<issue-identifier>"andgh pr list --search "<title>" - If found, attach via
attachmentLinkGitHubPRand add## PRsection - If no PR found, flag for manual resolution
- (Phase A excludes
completed/canceledepics; this rule fires only forreview-state work)
Implementation Details in Description
- Flag the specific content for user review
- Do not auto-remove — user may have intentional content
- Apply writes via Linear MCP (preferred) or GraphQL.
--auto semantics: safe fixes (team default insertion, core-skill stripping) apply silently. Content fixes (objective, skills, repos, invalid agents) still confirm with the user.
Phase D — Verify + Report
- Re-run the audit checks on touched epics (reuse the same check set from Phase B).
- Output a summary:
- Before/after error + warning counts per epic
- Epics flagged but skipped (user declined a content fix)
- Any writes that failed (auth, mutation errors) — these get listed individually with error text
- For project scope, also report the top-25 cap — if more epics had findings, name the next batch the user can target.
Auto Mode
If --auto is specified:
- Apply all safe fixes without asking (team defaults, core skill removal)
- Still ask for confirmation on content changes (objective, skills, repos, invalid agents)
- Empty Agents Section still requires user input (no auto-fix)
- Pre-flight overload gate still applies (
--autodoes not bypass--confirm-bulk)
Create a new VantageEx-compatible epic in Linear.
Steps
- Load the
/linearskill - Read the epic template at
templates/0.1.0/epic.md - Read the epic format spec at
references/epic-format.md
Gather Information
Interactively collect from the user:
- Title: Clear, imperative statement of what gets built
- Slug: Derive from title (kebab-case, max ~30 chars). Confirm with user.
- Objective: 2-3 sentences defining success criteria
- Skills: Domain-specific skills needed. Validate each against the marketplace at
https://github.com/vinnie357/claude-skills/blob/main/.claude-plugin/marketplace.json. Warn if a skill is not found. - Repos: Target repositories
- Constraints: Optional. Note that defaults apply (mise run ci, no attribution, squash merge, feature/)
- Team: Optional. Default: lead=sonnet, default_model=haiku, escalation=haiku->sonnet->opus
Size & Order
Apply references/epic-sizing.md to the issues you intend to create:
- Decompose the epic into 3–8 independently completable issues. If the count would exceed 8, split the epic.
- Size each issue to one worker session: ≤ ~10 target files, one deliverable, one subsystem, verifiable by a single acceptance check. Reject multi-deliverable titles (joined by "and/also/then/plus") — split them.
- Declare dependencies explicitly using Linear blocking relations. Never rely on implicit ordering.
- Order topologically: foundation issues (schemas, references, interfaces) first, then core, integration, and verification. No cycles — if a cycle is detected, re-decompose before proceeding.
- Keep chains shallow: dependency depth < 5 levels; do not serialize issues that can run in parallel.
See references/epic-sizing.md for thresholds and the full checklist.
Validate
Before creating:
- Confirm skills exist in the marketplace (read marketplace.json from the claude-skills repo)
- Confirm core skills are NOT listed (anti-fabrication, git, tdd, twelve-factor, security, mise, nushell)
- Confirm objective is 2-3 sentences
- Confirm slug is kebab-case and under 30 chars
- Confirm at least one repo is specified
- Confirm the body is self-contained: no local-filesystem paths (
~/.claude/...,/Users/<name>/...) used as the source of truth. Embed design plans inline under a## Design contextsection, or link to other epics by Linear URL. - Sizing check: confirm the objective's scope can decompose into approximately 6–8 independently-shippable issues (the adopted sizing convention; see "Epic Sizing Heuristics" in
references/epic-format.md). If the scope appears to require significantly more issues, spans many repositories with large cross-cutting changes, or contains work that could be separately delivered, prompt the user to consider splitting into multiple epics. - Dependency-ordering check: confirm that the anticipated issues can be ordered topologically (foundational work first, no cycles). If the user has described ordering intent, include a
## Dependenciessection in the epic body; see "Dependency Ordering" inreferences/epic-format.mdfor format and rules.
Body Format Rules
Apply the format rules from the /linear skill's "Epic Body Format Rules" section to the body you produce in the next step:
- Plain markdown only — no YAML fences in any section.
- Skill labels must exist in the marketplace; core skills (anti-fabrication, git, tdd, twelve-factor, security, mise, nushell) are implicit and not listed.
- Initial state is
Backlog. - Bodies are self-contained: embed design context inline, cross-link other epics by Linear URL, never reference local-filesystem paths.
See plugins/tools/linear/skills/linear/SKILL.md "Epic Body Format Rules" for the canonical wording.
When the epic's anticipated issue ordering is known, include a ## Dependencies section in the produced body declaring which issues depend on which others, with foundational issues listed first. The team leader translates this into formal blockedBy edges in Linear during decomposition. See "Dependency Ordering" in references/epic-format.md for format and rules.
Create in Linear
Use the Linear MCP tools (preferred) or the GraphQL API to:
- Create the issue with the title
- Set the description using the template format with all gathered sections
- Apply skill names as labels (create labels if they do not exist)
- Set initial state to "Ready" or "Backlog" (the default unstarted state)
Report
Output:
- Linear issue URL
- Issue identifier (e.g., MT-123)
- Feature branch name:
feature/<slug> - Summary of what was created
Sponsors
Details
- Marketplace
- vinnie357/claude-skills
- Source
- plugins/tools/linear
- Category
- Tools
- License
- MIT
- Keywords
- linear, project-management, epics, graphql, vantageex, mcp