Linear

Overview of Linear skill

What the Linear skill does

Linear is a workflow-focused skill for managing issues, projects, initiatives, labels, and team updates in Linear. It is best for users who want reliable Linear usage beyond a generic prompt: creating and updating work items, querying status, and keeping project ops consistent.

When this skill is a good fit

Use the Linear skill if you need a practical Linear guide for project management, especially when you care about discovery before creation, status discipline, or repeatable team workflows. It is useful for agents that should act with less guesswork when working in an existing Linear workspace.

What makes it different

This skill is not just a natural-language helper. It includes tool-aware guidance, fallback paths when MCP is unavailable, and repository-backed scripts for more complex operations. That makes it a stronger Linear install choice when you want both quick actions and deeper automation.

How to Use Linear skill

Install and confirm the tool path

Install the Linear skill with the repo’s skill command, then verify which backend is available. The skill is designed to use mcp__linear when present, but it can fall back to the linear CLI through Bash. If you only skim one part of the repo, read SKILL.md first because it explains tool availability and the safety rules that affect real execution.

Turn a rough goal into a usable prompt

Good Linear usage starts with specific input: team key, item type, target project or issue key, desired state, and any labels or priority. Instead of asking to “clean up the project,” ask for a concrete action such as: “Create a Linear issue for ENG, assign it to Phase 6A, set priority 2, add labels for backend and bug, and include acceptance criteria.” That level of detail improves matching and reduces back-and-forth.

Read these files first

For a fast Linear install workflow, preview SKILL.md, README.md, CLAUDE.md, api.md, and troubleshooting.md. Then inspect scripts/create-issue-with-project.ts, scripts/create-project-update.ts, and scripts/create-initiative-update.ts for the exact arguments and validation behavior. If you plan to automate, also check scripts/linear-ops.ts and scripts/linear-api.mjs.

Practical workflow tips

Use the skill for a discovery-first process: check for existing projects or issues before creating duplicates, confirm state names before updates, and prefer markdown-rich descriptions when creating work. For security-sensitive actions, follow the repo’s secret-handling pattern and avoid exposing LINEAR_API_KEY in output or context. If MCP is missing, do not stop—use the CLI path the skill documents.

Linear skill FAQ

Is this better than a normal prompt about Linear?

Yes. A normal prompt may work for one-off requests, but the Linear skill adds installable workflow rules, backend fallback logic, and scripts that make repeated Linear usage more dependable. That matters when you need consistent behavior across issue creation, status updates, and project management.

Do I need MCP to use the Linear skill?

No. MCP is supported, but the skill explicitly supports a CLI-based path via Bash when MCP tools are not available. That makes the Linear skill more portable across environments and less likely to fail on tool access alone.

Is the Linear skill beginner-friendly?

Mostly yes, if you can identify the workspace basics: team key, issue key, project name, and desired outcome. Beginners may struggle only when they give vague requests. The skill works best when you provide enough structure for a clear Linear install/use decision.

When should I not use it?

Do not use the skill if you only need a high-level explanation of Linear or if your task does not involve actual workspace changes, queries, or project tracking. It is also a weaker fit if you want a completely hands-off experience without naming the team, project, or issue context.

How to Improve Linear skill

Provide the missing workspace facts

The biggest quality gain comes from naming the exact Linear objects and constraints up front: team key, project name, issue key, target state, assignee, priority, and labels. Strong input looks like: “Update ENG-123 to In Review, add the frontend label, and leave a short comment summarizing the blocker.” Weak input like “move this forward” forces the skill to guess.

Include output requirements, not just intent

When you want better Linear usage, specify the artifact you expect: issue description, project update, initiative update, or comment. If you want a new issue, include acceptance criteria or a short template. If you want a project update, give a markdown outline and the status signal you want reflected, such as onTrack, atRisk, or offTrack.

Watch for common failure modes

The most common failure mode is ambiguity: partial project names, missing team keys, or a request to update status without knowing the state ID or state name. Another frequent issue is asking for creation before discovery. The skill performs better when it searches first, then creates only if the target does not already exist.

Iterate after the first pass

If the first result is close but not right, refine by adding the missing constraint rather than restating the whole request. For example, add “use the existing project description style,” “match the team’s label taxonomy,” or “keep the update under 120 words.” That kind of iteration improves the Linear skill more than broad rewording and makes the final result closer to real project management needs.