| name | linear |
| description | Use repo-local GraphQL helpers to read and write Linear through
`LINEAR_API_KEY`.
|
Linear
Use this skill whenever the agent needs to read or write Linear state from an
OpenSymphony-managed repository.
Required auth
LINEAR_API_KEY must be present in the environment.
- If it is missing, treat Linear access as a real blocker.
tracker.project_slug stores Linear Project.slugId, not a display name.
Primary path
Run the repo-local helper:
python3 .agents/skills/linear/scripts/linear_graphql.py \
--query-file .agents/skills/linear/queries/viewer.graphql
Pass variables as inline JSON or a JSON file:
python3 .agents/skills/linear/scripts/linear_graphql.py \
--query-file .agents/skills/linear/queries/issue_by_key.graphql \
--variables '{"key":"COE-123"}'
References
Rules
- This repo uses GraphQL-only Linear access through the checked-in helper.
- Prefer query files under
.agents/skills/linear/queries/ over ad hoc inline
GraphQL strings.
- Keep exactly one GraphQL operation per request.
- Use variables instead of string interpolation.
- Treat a top-level
errors array as a failed Linear operation even if the
HTTP request succeeds.
- Keep requested fields narrow and task-specific.
- When an unfamiliar mutation or input shape is needed, start with the
introspection query files before guessing.
- Use the reference docs for exact variable shapes and example commands instead
of copying large GraphQL documents inline.
Common workflows
- Review feedback polling:
- When a workflow asks for PR feedback, review polling, rework feedback, or a
final merge-readiness sweep, read latest Linear issue comments first with
.agents/skills/linear/queries/issue_comments.graphql.
- Treat unresolved, actionable operator comments on the Linear issue as
feedback even when the GitHub PR has no new review comments.
- Create an issue or sub-issue:
.agents/skills/linear/queries/issue_create.graphql
- Update an issue title, body, or metadata:
.agents/skills/linear/queries/issue_update.graphql
- Read issue comments:
.agents/skills/linear/queries/issue_comments.graphql
- Create a comment:
.agents/skills/linear/queries/comment_create.graphql
- Edit a comment:
.agents/skills/linear/queries/comment_update.graphql
- Move an issue to a new state:
.agents/skills/linear/queries/issue_team_states.graphql
.agents/skills/linear/queries/issue_move_to_state.graphql
- Attach a GitHub PR:
.agents/skills/linear/queries/attachment_link_github_pr.graphql
- Attach a plain URL:
.agents/skills/linear/queries/attachment_link_url.graphql
- Create an issue relation:
.agents/skills/linear/queries/issue_relation_create.graphql
- Read project planning state:
.agents/skills/linear/queries/project_planning_state.graphql
- Create or update a project milestone:
.agents/skills/linear/queries/project_milestone_create.graphql
.agents/skills/linear/queries/project_milestone_update.graphql
- Update project overview/content:
.agents/skills/linear/queries/project_by_slug.graphql
.agents/skills/linear/queries/project_update_content.graphql
- Create or update project status:
.agents/skills/linear/queries/project_status_create.graphql
.agents/skills/linear/queries/project_status_update.graphql
.agents/skills/linear/queries/project_set_status.graphql
- Upload a file for a comment:
.agents/skills/linear/queries/file_upload.graphql
- upload the bytes to the returned
uploadUrl with Content-Type matching
the requested contentType plus every header returned by Linear
- then create or update the comment with the returned
assetUrl
- Inspect the schema:
.agents/skills/linear/queries/introspect_mutations.graphql
.agents/skills/linear/queries/introspect_input_shape.graphql