Agent-Skills.md

Agent Skills: Create Issue

Create Linear tickets or GitHub issues following n8n conventions. Use when the user asks to create a ticket, file a bug, open an issue, or says /create-issue.

UncategorizedID: n8n-io/n8n/create-issue

Repository

n8n-io/n8n
n8n-ioLicense: NOASSERTION
180,86856,114

Install this agent skill to your local

pnpm dlx add-skill https://github.com/n8n-io/n8n/tree/HEAD/.claude/skills/create-issue

Skill Files

Browse the full folder contents for create-issue.

Download Skill

Loading file tree…

.claude/skills/create-issue/SKILL.md

Skill Metadata

Name
create-issue
Description
Required for creating GitHub issues. Must be authenticated (gh auth login)

Create Issue

Create a Linear ticket or GitHub issue for: $ARGUMENTS

Determine Target

Decide where the issue should be created based on user input:

  • If the user says "Linear", "ticket", or provides a team key (e.g., AI, NODE, N8N) → Linear
  • If the user says "GitHub", "GH issue", or "open source" → GitHub
  • If ambiguous, ask the user which platform they want

Linear Tickets

Prerequisites

Verify the Linear MCP is connected before proceeding.

Style Guide

Title

  • Sentence case — capitalize only the first word (e.g., "Add webhook verification to Trello trigger")
  • Descriptive — a reader should understand the scope without opening the ticket
  • 5–15 words — long enough to be specific, short enough to scan
  • Imperative mood for features/enhancements — "Add ...", "Support ...", "Improve ..."
  • Bug titles — prefix with Bug - followed by a description of the symptom (e.g., "Bug - Pin data not updating after workflow edit")
  • No ticket IDs in titles — the identifier (AI-1234) is assigned automatically
  • No trailing punctuation

Description

Structure the description using markdown headers. Use the appropriate template:

For bugs:

## Description
[Clear explanation of the problem]

## Expected
[What should happen]

## Actual
[What happens instead]

## Attachments
[Screenshots, videos, or screen recordings that illustrate the problem]

## Steps to reproduce
1. [Step-by-step reproduction]

## Additional context
- n8n version: [version]
- Database: [SQLite/PostgreSQL]
- Hosting: [cloud/self-hosted]

For features / enhancements:

## Summary
[One-paragraph overview of what this adds or changes]

## Problem
[What limitation or gap exists today]

## Proposed solution
[How it should work — technical approach if known]

## Out of scope
[Explicitly note what this does NOT cover, if helpful]

For tech debt:

## Summary
[What technical improvement is needed]

## Current state
[What the code/system looks like today and why it's problematic]

## Proposed improvement
[What the improved state should look like]

## Motivation
[Why this matters — maintainability, performance, developer experience, etc.]

## Scope
[What is included / excluded from this work]

For spikes / investigations:

## Goal
[What question are we trying to answer]

## Context
[Why this investigation is needed now]

## Expected output
[What deliverable is expected — RFC, PoC, decision document, etc.]

Attachments (Screenshots / Videos)

If the user provides screenshots, videos, or screen recordings:

  • URLs — embed directly in the description using markdown image syntax (![description](url))
  • File paths — if the user provides a local file path, ask them to upload it to a hosting service (e.g., GitHub, Imgur) or use mcp__linear-server__create_attachment to attach it to the Linear ticket after creation
  • Pasted images in conversation — describe what the image shows in the ticket description and note that a screenshot was provided. You cannot upload binary data directly.

Always mention in the description when visual evidence was provided, even if it cannot be directly embedded.

Priority

| Value | Level | When to use | |-------|----------|-------------| | 4 | Low | Nice-to-have, no user impact | | 3 | Normal | Default — standard planned work | | 2 | High | Blocks other work or affects users significantly | | 1 | Urgent | Production-breaking, security vulnerability, data loss | | 0 | None | Not yet assessed |

Guardrails:

  • Default to Normal (3) unless the user explicitly states otherwise
  • Never set Urgent (1) unless the user explicitly says "urgent", "P0", "production down", or "security vulnerability"
  • Never set None (0) — always make a priority assessment. If unsure, use Normal (3)

Status

Guardrails:

  • Never create issues in Triage status — Triage is for externally-reported issues that enter through automated pipelines (GitHub sync, support escalation). Agent-created tickets have known context and should skip triage
  • Default to Backlog — use this when the issue is acknowledged but not yet planned for a sprint
  • Use Todo only when the user indicates the work is planned for the current cycle or should be picked up soon
  • Never set In Progress, Review, or Done at creation time

Team

  • Try to fetch up-to-date team areas of responsibility from Notion using mcp__notion__notion-search (search for "areas of responsibility" or similar). Use the fetched data to determine the best team for the issue.
  • If Notion MCP is unavailable or the lookup fails, fall back to these common teams: Engineering (N8N), AI, NODES, Identity & Access (IAM), Catalysts (CAT), Lifecycle & Governance (LIGO), Cloud Platform, Docs (DOC)
  • Always ask the user which team if not obvious from context or the Notion lookup
  • If the issue is node-specific, it likely belongs to NODES
  • If it involves AI/LangChain nodes, it likely belongs to AI

Labels

Apply labels from these groups as appropriate:

Type (pick one):

  • bug — something is broken
  • feature — net-new capability
  • enhancement — improvement to existing functionality
  • tech debt — internal quality improvement
  • spike — time-boxed investigation
  • doc — documentation-only change

Area (pick if applicable):

  • frontend, backend, performance, testing, infra, DX, Security-Team

Source (pick if applicable):

  • Internal — created by team members
  • GitHub — originated from a GitHub issue
  • Sentry — originated from error monitoring
  • Zammad — originated from support

Bucket (pick if applicable):

  • Use the relevant feature-area bucket (e.g., Credentials, Canvas/Node, RBAC, LangChain nodes, Form Trigger, etc.)

Guardrails:

  • Always apply a type label — every ticket needs at least a type
  • Do not apply triage-state labels (Triage: Pending, Triage: Complete, etc.) — these are managed by triage automation
  • Do not apply release labels (n8n@1.36.0, etc.) — these are managed by release automation
  • Do not apply docs-automation labels — these are managed by docs automation

Estimates

Only set an estimate if the user provides one or explicitly asks for one. Use t-shirt sizes:

| Size | Value | Approximate effort | |------|-------|--------------------| | XS | 1 | ≤ 1 hour | | S | 2 | ≤ 1 day | | M | 3 | 2–3 days | | L | 4 | 3–5 days | | XL | 5 | ≥ 6 days |

Creating the Ticket

  1. Gather required fields — if any are missing, ask the user:

    • Title
    • Team
    • Description (draft one from the user's input using the templates above)

  2. Present a preview before creating — show the user:

    • Title
    • Team
    • Status
    • Priority
    • Labels
    • Description (abbreviated if long)

  3. Wait for user confirmation — do not create until the user approves

  4. Create the ticket using mcp__linear-server__save_issue:

    title: <title>
team: <team name>
description: <markdown description>
priority: <priority number>
state: <status name>
labels: [<label names>]

  5. Report back with the issue identifier and URL

Things to Never Do (Linear)

  • Never create issues in Triage status
  • Never set Urgent priority without explicit user instruction
  • Never apply triage-state, release, or docs-automation labels
  • Never set assignee unless the user explicitly asks
  • Never set a cycle or milestone unless the user explicitly asks
  • Never create duplicate issues — if the user describes something that sounds like it may exist, search first with mcp__linear-server__list_issues

GitHub Issues

Prerequisites

Verify gh CLI is authenticated: gh auth status

Important Context

The n8n GitHub issue tracker (n8n-io/n8n) is bug-only. Feature requests and questions are redirected to the community forum. Blank issues are disabled — the bug template must be used.

Style Guide

Title

  • Sentence case — same as Linear
  • Descriptive of the symptom — what is broken, not what you want
  • No prefixes required — do not add "Bug:" or "Bug Report:" (the template handles categorization)
  • No trailing punctuation

Body

GitHub issues must follow the bug report template structure:

### Bug Description

[Clear explanation of the bug]

### Steps to Reproduce

1. [Step 1]
2. [Step 2]
3. [Step 3]

### Expected Behavior

[What should happen]

### Debug Info

[If available — output from Help > About n8n > Copy debug information]

### Operating System

[e.g., macOS 14.2, Ubuntu 22.04]

### n8n Version

[e.g., 1.72.1]

### Node.js Version

[e.g., 20.11.0]

### Database

SQLite / PostgreSQL

### Execution Mode

main / queue

### Hosting

n8n cloud / self hosted

Guardrails:

  • Always include reproduction steps — issues without them get closed as closed:incomplete-template
  • Include debug info if available — this is critical for triage
  • Never file feature requests as GitHub issues — redirect the user to the community forum or suggest creating a Linear ticket instead

Labels

Do not manually apply labels when creating GitHub issues. The triage automation handles labeling:

  • triage:pending is auto-applied
  • status:in-linear is auto-applied when synced

Creating the Issue

  1. Verify it's a bug — if the user describes a feature request, inform them that GitHub issues are bug-only and suggest alternatives (Linear ticket or community forum)

  2. Draft the issue using the template above, filling in fields from the user's input

  3. Present a preview before creating — show the user:

    • Title
    • Body (abbreviated if long)
    • Repository (default: n8n-io/n8n)

  4. Wait for user confirmation

  5. Create the issue using gh:

    gh issue create --repo n8n-io/n8n --title "<title>" --body "$(cat <<'EOF'
<body content>
EOF
)"

  6. Report back with the issue number and URL

Things to Never Do (GitHub)

  • Never file feature requests as GitHub issues
  • Never create issues without reproduction steps
  • Never manually apply labels — let automation handle it
  • Never create issues in repositories other than n8n-io/n8n unless the user explicitly specifies

Cross-Linking

When both a Linear ticket and GitHub issue exist for the same problem:

  • Linear → GitHub: Add the GitHub issue URL as a link attachment on the Linear ticket
  • GitHub → Linear: Add https://linear.app/n8n/issue/<TICKET-ID> in the GitHub issue body

If the user creates one and mentions the other exists, offer to add the cross-link.