Linear Skill

[danicunhac]

---

dependencies: 🔴 create-skill skill - merge that before attempting to incorporate this as an aidd Framework skill.

What this is

The /linear skill is a Claude Code SKILL that takes a Linear ticket ID (like ENG-1412) as input and transforms it into a complete, ready-to-execute implementation workflow.

What it does

This skill converts a Linear ticket into a structured development process. It produces three key outputs: a validated ticket with complete requirements, a task plan saved as an epic file, and guided implementation that walks you through each step of the work.

How it works

The workflow begins by fetching the ticket from Linear using the mcp__linear__get_issue command through the Linear MCP integration. If the Linear MCP server isn't configured, the skill provides setup instructions to get you started.

Next, it automatically scans the ticket for Figma links. When designs are available, it fetches both the design context and screenshots, which helps inform the requirements and implementation details.

The skill then validates the ticket description against the template defined in @ai/rules/[linear-ticket-template.md], checking for required sections and marking the ticket as either VALID or INVALID.

If the ticket is invalid, the skill researches your codebase and any linked context from Notion or Figma. It then writes a complete description that matches the template requirements and updates the Linear ticket automatically using mcp__linear__update_issue.

Once the ticket is validated, the skill plans the work by breaking it down into small, sequential tasks following the guidelines in @ai/rules/task-creator.mdc. It creates an epic file at tasks/[ticket-id]-[short-name].md and tracks all tasks using TodoWrite.

Before starting implementation, there's an approval gate where the skill summarizes the ticket, any designs found, the implementation plan, and files that will be changed. It then asks you: "Ready to implement this plan?"

After you approve, implementation begins. The skill executes one task at a time, waits for your explicit approval before moving to the next task, and follows all repository standards defined in CLAUDE.md, JavaScript style guides, and TDD rules.

Failure / setup handling

The skill gracefully handles various failure scenarios including missing MCP servers (Linear, Notion, or Figma), authentication failures that require running the /mcp flow, and issues like tickets not being found, update failures, malformed Figma links, or missing node IDs.

Installation folder

.claude/skills/linear/SKILL.md

Skill

---
name: linear
description: Fetch a Linear ticket, validate/improve its description, create a plan, and implement it
argument-hint: <ticket-id>
allowed-tools: Read, Grep, Glob, Edit, Write, Bash, Task, TodoWrite
---

# Linear Ticket Workflow

This skill automates the complete workflow from Linear ticket to implementation.

## Arguments

- `$ARGUMENTS[0]` - The Linear ticket ID (e.g., `ENG-1412` or just `1412`)

## Workflow

Execute these steps in order:

### Step 1: Fetch the Ticket

Use the Linear MCP server to fetch the ticket details:

mcp__linear__get_issue with identifier: $ARGUMENTS[0]

If the MCP server is not available, inform the user to run:
```bash
claude mcp add --transport http linear https://mcp.linear.app/mcp

Then restart Claude Code and run /mcp to authenticate.

Optional: Notion MCP - If the user wants to search Notion for related documents (specs, designs, etc.), ensure the Notion MCP is configured. If not available:

claude mcp add notion -- npx -y @anthropic-ai/notion-mcp --oauth

Then restart Claude Code and run /mcp to authenticate with Notion.

Optional: Figma MCP - The skill automatically detects Figma links in tickets. If Figma MCP is not configured but Figma links are found, inform the user:

claude mcp add figma -- npx -y @figma/plugin-mcp

Then restart Claude Code and run /mcp to authenticate with Figma.

Step 1.5: Detect Figma Links (Automatic)

After fetching the ticket, automatically scan the description and attachments for Figma links:

• Design file URLs: https://figma.com/design/:fileKey/:fileName?node-id=:nodeId
• FigJam URLs: https://figma.com/board/:fileKey/:fileName?node-id=:nodeId
• Branch URLs: https://figma.com/design/:fileKey/branch/:branchKey/:fileName (use branchKey as fileKey)

If Figma links are found but Figma MCP is not configured, inform the user and continue without Figma data.

Step 2: Validate Against Template

Read the template from @ai/rules/linear-ticket-template.md.

Check if the ticket description contains these required sections:

1. Description - Must have meaningful content explaining the "why"
2. Requirements - At least one requirement with MUST or MUST NOT
3. Acceptance Criteria - At least one testable criterion
4. Out of Scope - Must be present (can contain "None" or "N/A")

Validation Result:

• If ALL required sections are present with meaningful content → Mark as VALID
• If ANY required section is missing or has only placeholder text → Mark as INVALID

Step 3: Generate/Update Description (if INVALID)

If the ticket is INVALID:

1. Analyze the existing title and any partial description
2. Research the codebase and documentation to understand context:
   • Search for related files, components, or functions
   • Read CLAUDE.md for architecture understanding
   • Check existing patterns in similar features
   • If the ticket references Notion links, fetch them using mcp__plugin_Notion_notion__notion-fetch
   • If the user requests, search Notion for related specs/designs using mcp__plugin_Notion_notion__notion-search
   • Check for Figma links in the ticket description or attachments:
     • Detect Figma URLs (format: https://figma.com/design/:fileKey/:fileName?node-id=:nodeId or https://figma.com/board/:fileKey/:fileName?node-id=:nodeId)
     • Extract fileKey and nodeId from each URL
     • For each Figma link found:
       1. Fetch design context using mcp__plugin_figma_figma__get_design_context (provides UI code and asset URLs)
       2. Fetch screenshot using mcp__plugin_figma_figma__get_screenshot (provides visual reference)
       3. Optionally fetch metadata using mcp__plugin_figma_figma__get_metadata (provides structure overview)
     • Store Figma design information to inform requirements and implementation details
     • Always set clientFrameworks: "react" and clientLanguages: "typescript" for this project
3. Generate a complete description following the template schema:
   • Write a clear Description with the "why"
   • Define Requirements with MUST/MUST NOT/WHERE
   • Identify Services & Dependencies from codebase analysis
   • Determine if Analytics are needed (check analyticsService.ts patterns)
   • List Out of Scope items based on ticket focus
   • Write testable Acceptance Criteria
4. Update the ticket using Linear MCP:

   mcp__linear__update_issue with id and description
   

5. Show the user the updated description for review

Step 4: Create Implementation Plan

Following @ai/rules/task-creator.mdc:

1. Read the (now valid) ticket description
2. Decompose into atomic, sequential tasks (~50 lines of code max each)
3. Order tasks by dependencies and logical flow
4. Validate each task is specific, actionable, and independently testable
5. Create an epic file at tasks/[ticket-id]-[short-name].md:

# [Ticket Title] Epic

**Status**: 📋 PLANNED
**Linear**: [ticket-id]
**Goal**: [Brief goal from description]

## Overview

[Single paragraph starting with WHY - explain user benefit/problem being solved and what gaps are being addressed. Keep it terse.]

---

## [Task Name]

[Brief task description - 1 sentence max]

**Requirements**:
- Given [situation], should [job to do]
- Given [situation], should [job to do]

---

## [Task Name]

[Brief task description]

**Requirements**:
- Given [situation], should [job to do]

Epic constraints (from task-creator.mdc):

• No task numbering (use task names only)
• Requirements MUST use "Given X, should Y" format
• Include ONLY novel, meaningful requirements (no obvious boilerplate)
• NO extra sections beyond the template (no "Files to modify", etc.)

6. Use TodoWrite to track the tasks

Step 5: Request Implementation Approval

Before implementing, summarize:

• The ticket (valid or was updated)
• Figma designs (if any were found):
  • Show screenshot references
  • Summarize key UI components from design context
  • Highlight any design system patterns or variables used
• The implementation plan with task breakdown
• Files that will be modified
• Any risks or considerations

Ask: "Ready to implement this plan?"

Step 6: Implement

If approved, follow the executePlan() protocol from @ai/rules/task-creator.mdc:

1. Complete only the current task
2. Validate the task meets its success criteria
3. Report what was accomplished
4. Await explicit user approval before proceeding to the next task
5. Update TodoWrite status as you progress
6. Follow coding standards from:
   • CLAUDE.md - Project architecture
   • @ai/rules/javascript.mdc - Code style
   • @ai/rules/tdd.mdc - Testing approach

On completion (all tasks done):

1. Update epic status to ✅ COMPLETED (YYYY-MM-DD)
2. Move epic file to tasks/archive/YYYY-MM-DD-[epic-name].md

Error Handling

• Linear MCP not configured: Provide Linear setup instructions
• Notion MCP not configured: Provide Notion setup instructions (if user requests Notion search)
• Figma MCP not configured: Provide Figma setup instructions (if Figma links detected in ticket)
• Ticket not found: Ask user to verify the ticket ID
• Authentication failed: Guide user through /mcp auth flow
• Update failed: Show error and allow manual description copy
• Figma link parsing failed: Show the malformed URL and ask user to verify the Figma link format
• Figma node not found: Verify the node ID exists in the specified file

Example Usage

/linear ENG-1412

This will:

1. Fetch ENG-1412 from Linear
2. Validate its description
3. If incomplete, research and generate a proper description
   • If Figma links are found (e.g., https://figma.com/design/abc123/MyDesign?node-id=42-1):
     • Extract fileKey: abc123, nodeId: 42:1
     • Fetch design context (UI code and assets)
     • Fetch screenshot for visual reference
     • Use design information to inform requirements
4. Create an implementation plan (informed by Figma designs if available)
5. Ask for approval (showing Figma screenshots and design summary)
6. Implement the changes (with design specifications from Figma)

## Redundant Tasks

-