Skip to content
Skills Library
Management & product · Tool integration

linear

/linear

Linear project management via MCP or GraphQL API: issue queries, state transitions, epic authoring for VantageEx agent teams, and epic auditing. Use when interacting with Linear issues, creating or auditing epics, querying workflow states, or managing Linear project data.

Licence
MIT
Last repository change
07.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
11
Scripts
0
HTML comments
0
URLs in SKILL.md
5
Deprecation

No signals detected. Repository changed on 07.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Linear project management via MCP or GraphQL API: issue queries, state transitions, epic authoring for VantageEx agent teams, and epic auditing. Use when interacting with Linear issues, creating or auditing epics, querying workflow states, or managing Linear project data.

Original author description

Linear project management via MCP or GraphQL API: issue queries, state transitions, epic authoring for VantageEx agent teams, and epic auditing. Use when interacting with Linear issues, creating or auditing epics, querying workflow states, or managing Linear project data.

How it works

  1. MCP Setup (Preferred)
  2. GraphQL Fallback
  3. Common Operations
  4. Introspection
  5. VantageEx Epic Format
  6. Epic Body Format Rules
  7. Workflow States
  8. Commands
  9. References
  10. Templates
Original SKILL.md headings · 311 lines, 1,349 words
SKILL.md preview
---
name: linear
description: "Linear project management via MCP or GraphQL API: issue queries, state transitions, epic authoring for VantageEx agent teams, and epic auditing. Use when interacting with Linear issues, creating or auditing epics, querying workflow states, or managing Linear project data."
license: MIT
---

# 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:

```bash
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

```bash
# 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`):

```graphql
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

```graphql
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`:

```graphql
query IssueTeamStates($id: String!) {
  issue(id: $id) {
    team {
      states { nodes { id name type } }
    }
  }
}
```

Then transition:

```graphql
mutation MoveIssue($id: String!, $stateId: String!) {
  issueUpdate(id: $id, input: { stateId: $stateId }) {
    success
    issue { id identifier state { name } }
  }
}
```

### Add a Comment

```graphql
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:

```graphql
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

```graphql
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:

```graphql
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:

````markdown
## Skills

```yaml
- skill1
- skill2
```
````

CORRECT:

```markdown
## 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:

```markdown
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:

```markdown
## Design context

[full design content pasted here]
```

```markdown
## 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 `## Instructions`
- `in_progress` -> `review`: Agent submits PR
- `review` -> `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 `stateId` values
- Prefer `attachmentLinkGitHubPR` over `attachmentLinkURL` when linking GitHub PRs
- Keep queries narrow — request only the fields needed
- Treat top-level `errors` array in GraphQL responses as failures
- When writing epic descriptions, follow the section format exactly — VantageEx parses these programmatically
Files in this package (11)
  • SKILL.md 10 KB
  • references/audit-checklist.md 7 KB
  • references/epic-format.md 11 KB
  • references/epic-sizing.md 4 KB
  • references/graphql-api.md 8 KB
  • references/mcp-setup.md 4 KB
  • references/workflow-states.md 4 KB
  • scripts/0.1.0/linear.nu 6 KB
  • templates/0.1.0/audit-report.md 1 KB
  • templates/0.1.0/epic.md 2 KB
  • templates/0.1.0/team-definition.md 2 KB

Versions

RepositoryScoreLicence
This page · vinnie357/claude-skills100MIT
jjuraszek/pi-gauntlet100MIT
TerminalSkills/skills100Apache-2.0
OpenHands/extensions100MIT
magnus919/agent-skills100MIT
joe-broadhead/opencode-linear100MIT
glebis/claude-skills100MIT
apideck-libraries/api-skills100Apache-2.0
getsentry/junior100Apache-2.0

Database snapshot: 13.11.2026 · package version bdfa733de85f (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 96linear-project-management
    Use this skill when driving Linear projects and issues from an agent.
  • 100issue-tracking
    Create, manage, and track issues in GitHub, Linear, or GitLab. Use when the user asks to "create an issue", "file a bug", "check issues", "update a ticket", "create an epic", or anything about issue/ticket management.
  • 100linear-api
    Read and manage Linear issues, projects, cycles, teams, comments, and labels. Use this whenever the user wants to list their issues, search issues, create or update an issue, move an issue between states, add a comment, check a project or cycle, look up a team, or ask "what's on…
  • 100issue-tracking
    Use when the user asks to 'create an issue', 'file a bug', 'check issues', 'update a ticket', 'create an epic', or anything about issue or ticket management. Creates, manages, and tracks issues in GitHub, Linear, or GitLab.
  • 100issue-tracking
    Use when the user asks to 'create an issue', 'file a bug', 'check issues', 'update a ticket', 'create an epic', or anything about issue or ticket management. Creates, manages, and tracks issues in GitHub, Linear, or GitLab.
  • 100linear-task-submission
    Manage Linear issues and projects. Use when drafting, creating, editing, or reviewing Linear issues, including Simplified Chinese issue descriptions and agent execution context.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.