Real anonymized demo: complete Linear issue workflow with the linear Agent Skill

linear-agent-skill-demo-v2.md

A real Linear workflow from an Agent Skill

The linear Agent Skill gives an AI agent a focused, auditable way to operate Linear through its public GraphQL API. It uses Python 3.8+ with no third-party Python packages and no MCP server.

This demo performs a complete issue workflow against a live Linear workspace:

1. Discover the team.
2. Preview issue creation without changing Linear.
3. Create the issue.
4. Update its title and priority.
5. Add a comment.
6. Move it into active work.
7. Read it back with comments and related context.
8. Complete it.
9. Cancel the demo issue as cleanup.

The commands and results are real. Output blocks are field-selected and anonymized after capture. Example Engineering, DEMO, and DEMO-101 consistently replace the live workspace, team, and issue identifiers. Names, email addresses, URLs, UUIDs, and timestamps are omitted.

Install

Install the linear/ directory from magnus919/agent-skills with an Agent Skills-compatible client, or clone the repository to run the included CLI directly:

$ git clone --depth 1 https://github.com/magnus919/agent-skills.git
Cloning into 'agent-skills'...

$ cd agent-skills

Set exactly one credential through your normal secret-management mechanism:

• LINEAR_API_KEY for a personal API key
• LINEAR_ACCESS_TOKEN for OAuth

1. Discover the workspace

$ ./linear/scripts/linear team list --limit 10 --json
{
  "teams": {
    "nodes": [
      {
        "key": "DEMO",
        "name": "Example Engineering"
      }
    ]
  }
}

2. Preview the write

--dry-run does not require a network request and does not change Linear.

$ ./linear/scripts/linear issue create --team DEMO --title "Demo: ship the release checklist" --description "Prepare the release checklist and verify rollback steps." --priority medium --dry-run --json
{
  "dry_run": true,
  "operations": [
    {
      "operation": "resolve team",
      "reference": "DEMO"
    },
    {
      "operation": "issueCreate",
      "input": {
        "team": "DEMO",
        "title": "Demo: ship the release checklist",
        "description": "Prepare the release checklist and verify rollback steps.",
        "priority": "medium"
      }
    }
  ]
}

3. Create the issue

$ ./linear/scripts/linear issue create --team DEMO --title "Demo: ship the release checklist" --description "Prepare the release checklist and verify rollback steps." --priority medium --confirm --json
{
  "issueCreate": {
    "success": true,
    "issue": {
      "identifier": "DEMO-101",
      "title": "Demo: ship the release checklist",
      "priority": 3,
      "state": {
        "name": "Backlog",
        "type": "backlog"
      }
    }
  }
}

4. Update it

$ ./linear/scripts/linear issue update DEMO-101 --title "Demo: ship the verified release checklist" --priority high --confirm --json
{
  "issueUpdate": {
    "success": true,
    "issue": {
      "identifier": "DEMO-101",
      "title": "Demo: ship the verified release checklist",
      "priority": 2,
      "state": {
        "name": "Backlog",
        "type": "backlog"
      }
    }
  }
}

5. Add an issue comment

$ ./linear/scripts/linear issue comment DEMO-101 --body "Validation passed. The rollback procedure is documented." --confirm --json
{
  "commentCreate": {
    "success": true,
    "comment": {
      "body": "Validation passed. The rollback procedure is documented."
    }
  }
}

6. Move it into active work

Workflow state names are resolved inside the issue's own team.

$ ./linear/scripts/linear issue move DEMO-101 --state "In Progress" --confirm --json
{
  "issueUpdate": {
    "success": true,
    "issue": {
      "identifier": "DEMO-101",
      "state": {
        "name": "In Progress",
        "type": "started"
      }
    }
  }
}

7. Read back the full issue context

--detail includes the project, cycle, parent and child issues, comments, attachments, and relations when present.

$ ./linear/scripts/linear issue get DEMO-101 --detail --json
{
  "identifier": "DEMO-101",
  "title": "Demo: ship the verified release checklist",
  "description": "Prepare the release checklist and verify rollback steps.",
  "priority": 2,
  "state": {
    "name": "In Progress",
    "type": "started"
  },
  "team": {
    "key": "DEMO",
    "name": "Example Engineering"
  },
  "project": null,
  "cycle": null,
  "parent": null,
  "children": {
    "nodes": []
  },
  "comments": {
    "nodes": [
      {
        "body": "Validation passed. The rollback procedure is documented."
      }
    ]
  },
  "relations": {
    "nodes": []
  }
}

8. Complete it

$ ./linear/scripts/linear issue move DEMO-101 --state Done --confirm --json
{
  "issueUpdate": {
    "success": true,
    "issue": {
      "identifier": "DEMO-101",
      "state": {
        "name": "Done",
        "type": "completed"
      }
    }
  }
}

9. Clean up the demo

The CLI intentionally has no destructive issue deletion command. Moving the demo issue to Canceled preserves an audit trail and leaves existing work untouched.

$ ./linear/scripts/linear issue move DEMO-101 --state Canceled --confirm --json
{
  "issueUpdate": {
    "success": true,
    "issue": {
      "identifier": "DEMO-101",
      "state": {
        "name": "Canceled",
        "type": "canceled"
      }
    }
  }
}

What else it supports

The same CLI can list and inspect projects and cycles, search and read documents, filter issue lists by team and workflow state, search issues by text, and run a narrow documented GraphQL operation through raw when the focused commands do not cover it.

The skill adds the operating discipline around those commands: bounded discovery, exact target resolution, dry-run previews, explicit confirmation, and structured results suitable for agent workflows.

Source and installation: https://github.com/magnus919/agent-skills/tree/main/linear