Agent skill

linear-workflow

Linear issue-tracked development workflow. Auto-activates when starting work on issues, creating branches, changing status, writing comments, or creating PRs.

View SKILL.md on GitHub Repository

Stars 3

Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/bahamoth/claude-linear-workflow/tree/main/skills/linear-workflow

SKILL.md

Linear-Tracked Development Workflow

Prerequisites

Linear MCP: Configure in MCP settings:

json

{
  "mcpServers": {
    "linear": {
      "command": "mcp-remote",
      "args": ["-y", "https://mcp.linear.app/mcp"]
    }
  }
}

gh CLI: Install and authenticate:

bash

brew install gh  # or: https://cli.github.com/
gh auth login

Configuration

This skill requires Linear MCP to be configured. On first use:

Check environment variables in .claude/settings.json:
- If LINEAR_WORKFLOW_TEAM and LINEAR_WORKFLOW_PROJECT exist → use them
- If not → guide user to set them up before proceeding

Get issue prefix dynamically:

bash

mcp__linear-server__list_issues(team: "{LINEAR_WORKFLOW_TEAM}", limit: 1)
# Extract prefix from identifier (e.g., "ABC-34" → "ABC")

Example settings.json

json

{
  "env": {
    "LINEAR_WORKFLOW_TEAM": "YourTeam",
    "LINEAR_WORKFLOW_PROJECT": "YourProject"
  }
}

Note: issuePrefix is auto-detected from Linear, no manual config needed.

Auto-Activation Triggers

Starting code implementation
File modifications on main/master without issue branch
Mentioning a Linear issue ({PREFIX}-XX) in conversation
Creating commits with Conventional Commits format
Creating a PR with Fixes {PREFIX}-XX

Workflow Overview

Has Issue                    No Issue
    │                            │
    ▼                            ▼
Query via MCP          Plan → Create Issue in Linear
    │                            │
    └──────────┬─────────────────┘
               ▼
    Create branch (use gitBranchName)
               ▼
    Linear status: In Progress + start comment
               ▼
    Work (comment on decisions/blockers)
               ▼
    Create PR (Fixes {PREFIX}-XX)
               ▼
    Merge (rebase-ff) → Linear auto-Done

Quick Reference

Action	Command
Get issue	`mcp__linear-server__get_issue(id: "{PREFIX}-XX")`
Update status	`mcp__linear-server__update_issue(id: "{PREFIX}-XX", state: "In Progress")`
Add comment	`mcp__linear-server__create_comment(issueId: "{PREFIX}-XX", body: "...")`
Create issue	`mcp__linear-server__create_issue(title: "...", team: "{TEAM}", project: "{PROJECT}")`

1. Check or Create Issue

Case A: Starting with Existing Issue

bash

# Query issue via MCP
mcp__linear-server__get_issue(id: "{PREFIX}-XX")

Use gitBranchName field as branch name
Check Acceptance Criteria in issue description

Case B: Starting without Issue

After planning, before implementation, create Linear issue using this template:

bash

mcp__linear-server__create_issue(
  title: "Concise work title",
  description: "<issue description template below>",
  team: "{LINEAR_WORKFLOW_TEAM}"
)

If LINEAR_WORKFLOW_PROJECT is configured: Add project: "{LINEAR_WORKFLOW_PROJECT}" parameter.

Issues without a project are created in the team's Backlog.

Issue Description Template

markdown

## Objective

[One sentence describing what this work achieves]

## Background

- [Why this work is needed]
- [Context or constraints]
- [Related prior work or decisions]

## Implementation Approach

- [High-level approach or strategy]
- [Key technical decisions]
- [Files/components to modify]

## Acceptance Criteria

- [ ] [Specific, testable criterion 1]
- [ ] [Specific, testable criterion 2]
- [ ] [Specific, testable criterion 3]

Guidelines:

Objective: Single sentence, action-oriented (e.g., "Add logging infrastructure for LLM debugging")
Background: 2-4 bullet points explaining why, not how
Implementation Approach: Technical strategy, not step-by-step instructions
Acceptance Criteria: Checkboxes, testable conditions for "done"

2. Create Branch

Use the gitBranchName field from the Linear issue directly:

bash

# Get issue details (gitBranchName is included in response)
mcp__linear-server__get_issue(id: "{PREFIX}-XX")

# Create branch using gitBranchName value
git checkout -b <gitBranchName>

Branch Format: Configured in Linear at Settings > Workspace > Integrations > GitHub/GitLab > Branch format. The gitBranchName field reflects your team's configured format.

Branch Validation

This workflow validates branch names loosely—only requiring a Linear issue ID (e.g., ABC-123). This allows teams to use any branch format configured in Linear:

Branch Example	Valid?
`feature/ABC-123-auth`	Yes
`john/ABC-123-auth`	Yes
`ABC-123-auth`	Yes
`ABC-123`	Yes
`main`	No (protected)
`feature/auth`	No (no issue ID)

3. Update Status + Start Comment

bash

# Update status
mcp__linear-server__update_issue(id: "{PREFIX}-XX", state: "In Progress")

# Start comment (use actual branch name)
mcp__linear-server__create_comment(
  issueId: "{PREFIX}-XX",
  body: "## Started\n\n- Branch: `<branch-name>`\n- Implementing ..."
)

Linear Status Transitions

Status	When to Use	Transition
Backlog	Initial state, not yet prioritized	Auto
Todo	Ready for work	Manual
In Progress	Actively working	Set at branch creation
In Review	PR created, awaiting review	Set at PR creation
Done	PR merged	Auto (via `Fixes {PREFIX}-XX`)

4. Comments During Work

Write comments for major decisions, progress updates, or blockers.

Language: English only (for global team collaboration)

Progress Update

markdown

## Progress Update

- Completed: [what was done]
- In Progress: [current work]
- Next: [upcoming tasks]

Technical Decision

markdown

## Decision: [title]

**Context**: [why this decision was needed]

**Options considered**:

1. [Option A] - pros/cons
2. [Option B] - pros/cons

**Chosen**: [option] because [reason]

Blocked

markdown

## Blocked

**Issue**: [description]
**Waiting on**: [dependency/person]
**Workaround**: [if any]

5. Commit Rules

Conventional Commits + Linear reference:

bash

git commit -m "feat(scope): implement feature

Refs {PREFIX}-XX"

Commit Types

SemVer-relevant (required for versioning):

Type	Usage	SemVer Impact
`feat`	New feature	MINOR bump
`fix`	Bug fix	PATCH bump
`feat!:`	Breaking change (add ! suffix)	MAJOR bump

Other common types:

docs, refactor, test, chore, style, perf, ci, build, revert, or any lowercase word that fits the change.

Linear Reference Keywords

Refs {PREFIX}-XX: Link only (no status change)
Closes {PREFIX}-XX: Auto-close issue on PR merge

6. Create PR

PR Title

Conventional Commit format:

feat(linear): add workflow skills

PR Body

markdown

## Summary

- [Change 1]
- [Change 2]

## Test Plan

- [ ] Test item 1
- [ ] Test item 2

Fixes {PREFIX}-XX

PR Creation Command

bash

gh pr create --title "feat(scope): description" --body "$(cat <<'EOF'
## Summary
- ...

## Test Plan
- [ ] ...

Fixes {PREFIX}-XX

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

7. Merge

GitHub standard method (rebase-ff):

bash

# After PR approval
gh pr merge --rebase

Linear detects Fixes {PREFIX}-XX → auto-closes issue as Done

Linear Magic Words Reference

Keyword	Effect
`closes`, `fixes`, `resolves`, `completes`	Close issue on PR merge
`refs`, `part of`, `related to`	Link only, no status change

Workflow Checklist

Copy this checklist and check off items as you complete them:

Linear Workflow Progress:

Starting Work:
- [ ] Check if issue exists (create if not)
- [ ] Create branch using `gitBranchName`
- [ ] Status → In Progress
- [ ] Write start comment

During Work:
- [ ] Comment on major decisions/blockers
- [ ] Follow Conventional Commits
- [ ] Include `Refs {PREFIX}-XX` in commits

On Completion:
- [ ] Create PR (include `Fixes {PREFIX}-XX`)
- [ ] Request code review
- [ ] Merge (rebase-ff)
- [ ] Verify Linear auto-Done

Maintainer

bahamoth Core maintainer

Source details

Full Name: bahamoth/claude-linear-workflow
Branch: main
Path in repo: skills/linear-workflow
License: MIT License

Featured Tools

Join Our Newsletter

Stay updated with the latest AI tools, news, and offers by subscribing to our weekly newsletter.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

mattpocock/skills

git-guardrails-claude-code

Set up Claude Code hooks to block dangerous git commands (push, reset --hard, clean, branch -D, etc.) before they execute. Use when user wants to prevent destructive git operations, add git safety hooks, or block git push/reset in Claude Code.

111,310 9,758

Explore

mattpocock/skills

setup-pre-commit

Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing.

111,310 9,758

Explore

mattpocock/skills

obsidian-vault

Search, create, and manage notes in the Obsidian vault with wikilinks and index notes. Use when user wants to find, create, or organize notes in Obsidian.

111,310 9,758

Explore

mattpocock/skills

migrate-to-shoehorn

Migrate test files from `as` type assertions to @total-typescript/shoehorn. Use when user mentions shoehorn, wants to replace `as` in tests, or needs partial test data.

111,310 9,758

Explore

mattpocock/skills

edit-article

Edit and improve articles by restructuring sections, improving clarity, and tightening prose. Use when user wants to edit, revise, or improve an article draft.

111,310 9,758

Explore

mattpocock/skills

scaffold-exercises

Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. Use when user wants to scaffold exercises, create exercise stubs, or set up a new course section.

111,310 9,758

Explore

Didn't find tool you were looking for?

Search AI Tools

Install this agent skill to your Project

SKILL.md

Linear-Tracked Development Workflow

Prerequisites

Configuration

Example settings.json

Auto-Activation Triggers

Workflow Overview

Quick Reference

1. Check or Create Issue

Case A: Starting with Existing Issue

Case B: Starting without Issue

Issue Description Template

2. Create Branch

Branch Validation

3. Update Status + Start Comment

Linear Status Transitions

4. Comments During Work

Progress Update

Technical Decision

Blocked

5. Commit Rules

Commit Types

Linear Reference Keywords

6. Create PR

PR Title

PR Body

PR Creation Command

7. Merge

Linear Magic Words Reference

Workflow Checklist

Recommended Agent Skills

git-guardrails-claude-code

setup-pre-commit

obsidian-vault

migrate-to-shoehorn

edit-article

scaffold-exercises