mirror of
https://github.com/n8n-io/n8n
synced 2026-04-21 15:47:20 +00:00
chore: Add create-issue skill for Linear tickets and GitHub issues (#27285)
This commit is contained in:
Albert Alises
GitHub
parent
fee5f2ea94
commit
3ad5926a5e
1 changed files with 361 additions and 0 deletions
361
.claude/skills/create-issue/SKILL.md
Normal file
361
.claude/skills/create-issue/SKILL.md
Normal file
|
|
@ -0,0 +1,361 @@
|
|||
---
|
||||
name: create-issue
|
||||
description: 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.
|
||||
argument-hint: "[linear|github] <description of the issue>"
|
||||
compatibility:
|
||||
requires:
|
||||
- mcp: linear
|
||||
description: Required for creating Linear tickets
|
||||
- cli: gh
|
||||
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:**
|
||||
|
||||
```markdown
|
||||
## 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:**
|
||||
|
||||
```markdown
|
||||
## 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:**
|
||||
|
||||
```markdown
|
||||
## 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:**
|
||||
|
||||
```markdown
|
||||
## 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 (``)
|
||||
- **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](https://community.n8n.io). 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:
|
||||
|
||||
```markdown
|
||||
### 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`:
|
||||
```bash
|
||||
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.
|
||||
Loading…
Reference in a new issue