issue-writer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitHub Issue Writer

Purpose

用途

Help users draft and update well-structured GitHub issues by:

Analyzing the user's initial description
Asking targeted clarifying questions
Generating a concise title (under 72 characters)
Producing a comprehensive description using the project template
Updating existing issues on GitHub

帮助用户起草和更新结构清晰的GitHub Issue，具体包括：

分析用户的初始描述
提出针对性的澄清问题
生成简洁的标题（不超过72个字符）
使用项目模板生成全面的描述内容
更新GitHub上的现有Issue

Asking the User

询问用户

Every question in this skill is written as

AskUserQuestion

options. Use that tool where the host offers it, or the host's nearest structured-choice equivalent. Where the host has neither, ask the same question in normal chat as a numbered list of 2–5 options — recommended first, one short line of description each — and wait for the user to reply with a number.

本技能中的所有问题均以

AskUserQuestion

选项形式编写。如果宿主提供该工具，则使用它；如果宿主有类似的结构化选择工具，则使用最接近的替代工具。如果两者都没有，则以普通聊天形式将问题作为包含2-5个选项的编号列表提出——推荐选项放在首位，每个选项配一行简短描述——等待用户回复编号。

When to Use This Skill

使用场景

Use this skill when the user:

Drafting issues:

Asks to "write an issue" or "draft an issue"
Wants help structuring a bug report or feature request
Mentions wanting to document a task for GitHub
Needs to formalize a task description

For creating new issues on GitHub, use
issue-flow
when that skill is available. Otherwise use this skill to prepare the title and body, then create the issue with the available GitHub tooling.

Updating issues:

Asks to "update issue", "edit issue", or "modify issue"
Wants to "change the title" or "update description"
References a specific issue: "update issue #123", "edit https://github.com/..."
Says "update the issue" (use recently created issue from same session)

当用户有以下需求时使用本技能：

起草Issue：

请求“写一个Issue”或“起草一个Issue”
需要帮助整理Bug报告或功能请求的结构
提到想要为GitHub记录一项任务
需要将任务描述规范化

若要在GitHub上创建新Issue，当
issue-flow
技能可用时请使用该技能。否则，使用本技能准备标题和正文，然后通过可用的GitHub工具创建Issue。

更新Issue：

请求“更新Issue”、“编辑Issue”或“修改Issue”
想要“更改标题”或“更新描述”
引用特定Issue：“更新Issue #123”、“编辑https://github.com/...”
提到“更新这个Issue”（使用同一会话中最近创建的Issue）

Bundled Scripts

内置脚本

This skill includes helper bash scripts in the

scripts/

directory:

get-issue.sh - Fetches existing issue data (title, body, labels, state)
update-issue.sh - Updates an existing issue

To use bundled scripts, execute them from the skill directory:

bash

bash scripts/get-issue.sh 123
bash scripts/update-issue.sh --issue 123 --title "New Title" --add-label "bug"

本技能在

scripts/

目录中包含辅助bash脚本：

get-issue.sh - 获取现有Issue的数据（标题、正文、标签、状态）
update-issue.sh - 更新现有Issue

要使用内置脚本，请从技能目录执行：

bash

bash scripts/get-issue.sh 123
bash scripts/update-issue.sh --issue 123 --title "New Title" --add-label "bug"

Workflow

工作流程

Follow these steps in order. Adapt based on the scope and complexity of the issue.

按以下顺序执行步骤。可根据Issue的范围和复杂度进行调整。

Step 1: Gather Initial Input

步骤1：收集初始输入

Ask the user to describe what they want the issue to cover. If they've already provided a description, proceed to analysis.

请用户描述Issue需要涵盖的内容。如果用户已经提供了描述，则直接进入分析阶段。

Step 1.5: Determine Format

步骤1.5：确定格式

Check if the user's request indicates a preferred format:

Auto-detect Short format if keywords present:

"short issue", "minimal issue", "quick issue"

Auto-detect Default format if keywords present:

"simple issue", "draft issue", "basic issue"

If not auto-detected, ask the user which format they want, per Asking the User:

question: "What level of detail should this issue have?"
header: "Format"
options:
  - label: "Default (Recommended)"
    description: "Simple format with description, rationale, references, and implementation notes"
  - label: "Short"
    description: "Minimal format with just description and rationale (no section headers)"
  - label: "Full"
    description: "Comprehensive format with acceptance criteria, testing steps, and detailed implementation plan"

检查用户的请求是否表明了偏好的格式：

如果存在以下关键词，则自动检测为Short格式：

"short issue"、"minimal issue"、"quick issue"

如果存在以下关键词，则自动检测为Default格式：

"simple issue"、"draft issue"、"basic issue"

如果未自动检测到格式，则按照询问用户的规则，向用户询问所需格式：

question: "这个Issue需要包含多少细节？"
header: "格式"
options:
  - label: "默认（推荐）"
    description: "包含描述、理由、参考资料和实现说明的简洁格式"
  - label: "简短"
    description: "仅包含描述和理由的极简格式（无章节标题）"
  - label: "完整"
    description: "包含验收标准、测试步骤和详细实现计划的全面格式"

Step 2: Analyze and Categorize

步骤2：分析与分类

Determine the issue type based on the description:

Feature: New functionality or enhancement
Bug: Something is broken or not working as expected
Task: General work item, refactoring, documentation
Question: Needs discussion or clarification

Type-to-Label Mapping:

Based on the issue type, determine the recommended label:

Type	Recommended Label	Notes
Bug	`bug`	Add `critical` if severe/blocking
Feature	`feature`	New functionality
Task	Context-based	See keywords below
Question	None	Usually doesn't need a label

Task Label Keywords:

Keywords: refactor, cleanup, reorganize, restructure →
```
refactoring
```
Keywords: improve, enhance, update, optimize, better →
```
improvement
```
Keywords: research, investigate, explore, spike, prototype →
```
r&d
```
Default (no keywords matched):
```
improvement
```

Identify which template sections are relevant based on scope:

Scope	Required Sections
Short (minimal, quick)	Brief Description, Rationale (no section headers, bold markers only)
Default (simple task, draft)	Description, Rationale; optionally References, Implementation Notes
Small (bug fix, typo)	Brief Description, Acceptance Criteria
Medium (feature, enhancement)	Brief Description, Rationale, Implementation, Acceptance Criteria
Large / Full (architecture, major feature)	All sections as needed

Format Auto-Detection:

If keywords like "short issue", "minimal issue", or "quick issue" are present, use Short format
If keywords like "simple issue", "draft issue", or "basic issue" are present, use Default format

根据描述确定Issue类型：

Feature：新功能或增强功能
Bug：功能损坏或未按预期工作
Task：常规工作项、重构、文档编写
Question：需要讨论或澄清的问题

类型与标签映射：

根据Issue类型确定推荐标签：

类型	推荐标签	说明
Bug	`bug`	如果问题严重/阻塞，添加 `critical`
Feature	`feature`	新功能
Task	基于上下文	见下方关键词
Question	无	通常不需要标签

Task标签关键词：

关键词：refactor、cleanup、reorganize、restructure →
```
refactoring
```
关键词：improve、enhance、update、optimize、better →
```
improvement
```
关键词：research、investigate、explore、spike、prototype →
```
r&d
```
默认（未匹配关键词）：
```
improvement
```

根据范围确定相关的模板章节：

范围	必填章节
简短（极简、快速）	简要描述、理由（无章节标题，仅用粗体标记）
默认（简单任务、草稿）	描述、理由；可选参考资料、实现说明
小型（Bug修复、拼写错误）	简要描述、验收标准
中型（功能、增强）	简要描述、理由、实现、验收标准
大型/完整（架构、重大功能）	根据需要包含所有章节

格式自动检测：

如果存在"short issue"、"minimal issue"或"quick issue"等关键词，使用简短格式
如果存在"simple issue"、"draft issue"或"basic issue"等关键词，使用默认格式

Step 3: Interactive Questionnaire

步骤3：交互式问卷

Ask clarifying questions to fill in gaps, per Asking the User. Tailor them to the issue type and scope.

For Features:

What problem does this solve?
Are there any design references or examples?
What are the key acceptance criteria?
Any technical constraints to consider?

For Bugs:

What is the expected behavior?
What is the actual behavior?
Steps to reproduce?
Any error messages or screenshots?

For Tasks:

Why is this work needed now?
Are there dependencies on other work?
What does "done" look like?

Keep questions focused and avoid asking about things already clear from the description.

按照询问用户的规则，提出澄清问题以填补信息空白。根据Issue类型和范围调整问题。

针对Feature：

该功能解决了什么问题？
是否有任何设计参考或示例？
关键验收标准是什么？
需要考虑哪些技术限制？

针对Bug：

预期行为是什么？
实际行为是什么？
重现步骤？
是否有错误信息或截图？

针对Task：

为什么现在需要开展这项工作？
是否依赖其他工作？
完成的标准是什么？

保持问题聚焦，避免询问描述中已明确的内容。

Step 3.5: Confirm Label

步骤3.5：确认标签

Based on the type-to-label mapping from Step 2, confirm the label, per Asking the User:

question: "Which label best describes this issue?"
header: "Label"
options:
  - label: "{{RECOMMENDED_LABEL}} (Recommended)"
    description: "Based on issue type: {{TYPE}}"
  - label: "{{ALTERNATIVE_LABEL_1}}"
    description: "{{DESCRIPTION_1}}"
  - label: "{{ALTERNATIVE_LABEL_2}}"
    description: "{{DESCRIPTION_2}}"
  - label: "No label"
    description: "Skip label assignment"

Example for Bug type:

options:
  - label: "bug (Recommended)"
    description: "This appears to be a bug based on the error behavior described"
  - label: "critical"
    description: "High priority bug, needs immediate attention"
  - label: "improvement"
    description: "If this is more of an enhancement than a bug"
  - label: "No label"
    description: "Skip label assignment"

Example for Feature type:

options:
  - label: "feature (Recommended)"
    description: "New functionality being added"
  - label: "improvement"
    description: "Enhancement to existing functionality"
  - label: "epic"
    description: "Large feature spanning multiple issues"
  - label: "No label"
    description: "Skip label assignment"

Example for Task type (with refactoring keywords):

options:
  - label: "refactoring (Recommended)"
    description: "Code restructuring based on keywords: refactor, cleanup"
  - label: "improvement"
    description: "General enhancement"
  - label: "r&d"
    description: "Research and exploration work"
  - label: "No label"
    description: "Skip label assignment"

根据步骤2中的类型与标签映射，按照询问用户的规则确认标签：

question: "哪个标签最适合描述这个Issue？"
header: "标签"
options:
  - label: "{{RECOMMENDED_LABEL}}（推荐）"
    description: "基于Issue类型：{{TYPE}}"
  - label: "{{ALTERNATIVE_LABEL_1}}"
    description: "{{DESCRIPTION_1}}"
  - label: "{{ALTERNATIVE_LABEL_2}}"
    description: "{{DESCRIPTION_2}}"
  - label: "无标签"
    description: "跳过标签分配"

Bug类型示例：

options:
  - label: "bug（推荐）"
    description: "根据描述的错误行为，这似乎是一个Bug"
  - label: "critical"
    description: "高优先级Bug，需要立即处理"
  - label: "improvement"
    description: "如果这更偏向于增强而非Bug"
  - label: "无标签"
    description: "跳过标签分配"

Feature类型示例：

options:
  - label: "feature（推荐）"
    description: "正在添加的新功能"
  - label: "improvement"
    description: "对现有功能的增强"
  - label: "epic"
    description: "跨多个Issue的大型功能"
  - label: "无标签"
    description: "跳过标签分配"

Task类型（含重构关键词）示例：

options:
  - label: "refactoring（推荐）"
    description: "基于关键词：refactor、cleanup，属于代码重构"
  - label: "improvement"
    description: "常规增强"
  - label: "r&d"
    description: "研究与探索工作"
  - label: "无标签"
    description: "跳过标签分配"

Step 4: Generate Title

步骤4：生成标题

Create a title that:

Is under 72 characters (hard limit)
Starts with the component/area if applicable (e.g., "Button: Add loading state")
Uses imperative mood ("Add", "Fix", "Update", not "Adding", "Fixed")
Is specific but concise
Avoids redundant words like "Issue:" or "Task:"

Good examples:

Button: Add disabled state visual feedback

Fix tooltip positioning on viewport edge

```
TreeView: Implement keyboard navigation
```

Bad examples:

```
Issue: There's a problem with buttons
```
(vague, has "Issue:")

Adding a new feature for users to be able to see loading spinners

(too long, wrong mood)

创建满足以下要求的标题：

不超过72个字符（硬性限制）
如有适用，以组件/领域开头（例如："Button: Add loading state"）
使用祈使语气（"Add"、"Fix"、"Update"，而非"Adding"、"Fixed"）
具体且简洁
避免"Issue:"或"Task:"等冗余词汇

优秀示例：

Button: Add disabled state visual feedback

Fix tooltip positioning on viewport edge

```
TreeView: Implement keyboard navigation
```

不良示例：

```
Issue: There's a problem with buttons
```
（模糊，包含"Issue:"）

Adding a new feature for users to be able to see loading spinners

（过长，语气错误）

Step 5: Generate Description

步骤5：生成描述

Use the appropriate template based on the selected format.

Writing rules (all formats):

Never start the description with a markdown header — always lead with plain text
Use present tense for existing problems ("the button does not respond", not "the button did not respond" or "added responsive button handling") — describe the issue as it currently exists
Preserve the user's original wording where possible — restructure, don't rewrite

The templates live in

references/templates.md

, one per format — Full, Default, and Short. Read the one matching the chosen format.

## Template Section Guidelines

below says what belongs in each section.

根据所选格式使用相应的模板。

写作规则（所有格式）：

描述永远不要以Markdown标题开头——始终以纯文本开头
描述现有问题时使用一般现在时（"the button does not respond"，而非"the button did not respond"或"added responsive button handling"）——按当前状态描述问题
尽可能保留用户的原始措辞——仅调整结构以提升清晰度，不要重写

模板位于

references/templates.md

，每种格式对应一个模板——完整、默认和简短。阅读与所选格式匹配的模板。下方的

## 模板章节指南

说明了每个章节应包含的内容。

Step 6: Present to User

步骤6：呈现给用户

Show the user:

Title: The generated title
Description: The formatted description
Type suggestion: bug, feature, enhancement, documentation, etc.
Label suggestions: Based on the content

Ask if they want any modifications. Use a structured question tool when available; otherwise ask directly in chat.

向用户展示：

标题： 生成的标题
描述： 格式化后的描述
类型建议： bug、feature、enhancement、documentation等
标签建议： 基于内容生成的标签

询问用户是否需要修改。如果有结构化问题工具可用，则使用该工具；否则直接在聊天中询问。

Update Workflow

更新工作流程

Use this workflow when the user wants to update an existing issue.

当用户想要更新现有Issue时使用此工作流程。

Step 1: Identify the Issue

步骤1：确定Issue

Determine which issue to update:

Issue specified: User provides issue number or URL
- ```
#123
```
  ,
```
123
```
  ,
```
https://github.com/owner/repo/issues/123
```
Recent issue in session: If an issue was just created in this conversation, offer to use that
Ask: If neither, ask the user for the issue number or URL

确定要更新的Issue：

指定Issue： 用户提供Issue编号或URL
- ```
#123
```
  、
```
123
```
  、
```
https://github.com/owner/repo/issues/123
```
会话中的最近Issue： 如果本次对话中刚创建了一个Issue，提议使用该Issue
询问用户： 如果以上两种情况都不满足，询问用户提供Issue编号或URL

Step 2: Fetch Current Issue Data

步骤2：获取当前Issue数据

bash

bash scripts/get-issue.sh <issue-number-or-url>

Show the user:

Current title
Current description (summarized if long)
Current labels

bash

bash scripts/get-issue.sh <issue-number-or-url>

向用户展示：

当前标题
当前描述（如果过长则显示摘要）
当前标签

Step 3: Determine Changes

步骤3：确定修改内容

Ask the user what they want to change:

Title only
Description only
Both title and description
Labels (add or remove)

询问用户想要修改的内容：

仅标题
仅描述
标题和描述都修改
标签（添加或移除）

Step 4: Apply Changes

步骤4：应用修改

For description updates:

If minor edit: Apply the specific change
If rewrite: Use the same template logic as creating (Steps 2-5 of create workflow)

For title updates:

Follow the same title guidelines (under 72 chars, imperative mood)

对于描述更新：

如果是小修改：直接应用具体更改
如果是重写：使用与创建Issue相同的模板逻辑（创建流程的步骤2-5）

对于标题更新：

遵循相同的标题准则（不超过72字符，祈使语气）

Step 5: Present Changes for Approval

步骤5：呈现修改内容供确认

Important: Always show the changes to the user before updating the issue on GitHub. Skip this step only if the user explicitly requests to update without preview (e.g., "update without showing", "skip preview").

Show the user:

Before: Current title/description
After: New title/description
Label changes: Labels being added/removed

Ask for confirmation before updating. Use a structured question tool when available; otherwise ask directly in chat.

重要提示： 在GitHub上更新Issue之前，务必向用户展示修改内容。仅当用户明确要求无需预览即可更新（例如："直接更新，不要展示"、"跳过预览"）时，才可跳过此步骤。

向用户展示：

修改前： 当前标题/描述
修改后： 新标题/描述
标签变化： 要添加/移除的标签

在更新前请求确认。如果有结构化问题工具可用，则使用该工具；否则直接在聊天中询问。

Step 6: Update on GitHub

步骤6：在GitHub上更新

bash

bash scripts/update-issue.sh \
  --issue {{ISSUE_NUMBER}} \
  --title "{{NEW_TITLE}}" \
  --body "{{NEW_DESCRIPTION}}" \
  --add-label "{{LABEL}}" \
  --remove-label "{{LABEL}}"

Return the updated issue URL to the user.

bash

bash scripts/update-issue.sh \
  --issue {{ISSUE_NUMBER}} \
  --title "{{NEW_TITLE}}" \
  --body "{{NEW_DESCRIPTION}}" \
  --add-label "{{LABEL}}" \
  --remove-label "{{LABEL}}"

将更新后的Issue URL返回给用户。

Template Section Guidelines

模板章节指南

Description (Required)

描述（必填）

The opening paragraph before any sections. Length varies by format: Short 4-6 sentences, Default 4-8 sentences, Full 1-2 sentences (detailed sections follow). Describe the issue in present tense. Preserve the user's original phrasing — restructure for clarity, don't rewrite.

所有章节之前的开头段落。长度因格式而异：简短格式4-6句，默认格式4-8句，完整格式1-2句（后续是详细章节）。使用一般现在时描述问题。保留用户的原始措辞——仅调整结构以提升清晰度，不要重写。

Rationale (Optional)

理由（可选）

Explain the "why" when it's not obvious:

Business/technical value
Why this approach vs alternatives
Architectural decisions

当原因不明显时解释"为什么"：

业务/技术价值
为什么选择此方法而非其他方案
架构决策

References (Optional)

参考资料（可选）

Links that provide context:

Design files (Figma, screenshots)
Similar implementations
Documentation or RFCs
Related issues/PRs

提供上下文的链接：

设计文件（Figma、截图）
类似实现
文档或RFC
相关Issue/PR

Things to Consider (Optional)

需要考虑的事项（可选）

Important aspects affecting implementation:

Edge cases
Performance considerations
Integration points
Future extensibility

影响实现的重要方面：

边缘情况
性能考量
集成点
未来扩展性

Implementation (Medium/Large scope)

实现（中型/大型范围）

Functional checklist, not micromanagement:

Clear about WHAT needs to be done
Context for WHY
Code snippets for complex patterns
Logical order

功能性清单，而非微观管理：

明确需要完成的内容
说明原因的上下文
复杂模式的代码片段
逻辑顺序

UI Behavior (If applicable)

UI行为（如适用）

Expected user interactions:

Focus management
Keyboard navigation
Animations/transitions
Responsive behavior

预期的用户交互：

焦点管理
键盘导航
动画/过渡效果
响应式行为

Acceptance Criteria (Required)

验收标准（必填）

Testable yes/no checkboxes defining completion.

定义完成标准的可测试复选框（是/否）。

Testing Steps (Optional)

测试步骤（可选）

How to find and test in the application:

Navigation steps
Actions to trigger
Expected outcomes

如何在应用中找到并测试：

导航步骤
触发操作
预期结果

Examples (Optional)

示例（可选）

Screenshots, mockups, or code examples showing expected result.

展示预期结果的截图、模型或代码示例。

Out of Scope (Optional)

范围外内容（可选）

What is explicitly NOT part of this task. Prevents scope creep.

明确不属于本任务的内容。防止范围蔓延。

Technical Constraints (Optional)

技术限制（可选）

Specific requirements:

Performance targets
Browser support
Accessibility standards

特定要求：

性能目标
浏览器支持
无障碍标准

Prerequisites

前提条件

```
gh
```
CLI installed and authenticated (
```
gh auth login
```
) — required for updating issues
Must be run from within a GitHub repository for update operations

See

references/helper-scripts.md

for detailed script documentation, usage examples, and exit codes.

已安装并认证
```
gh
```
CLI（
```
gh auth login
```
）——更新Issue时必需
更新操作必须在GitHub仓库内执行

有关脚本的详细文档、使用示例和退出代码，请参阅

references/helper-scripts.md

。

Error Handling

错误处理

If
```
gh
```
CLI is not available, skip update operations and just provide the formatted output
If not in a git repository, skip GitHub integration and just provide the formatted output

如果
```
gh
```
CLI不可用，则跳过更新操作，仅提供格式化后的输出
如果不在git仓库内，则跳过GitHub集成，仅提供格式化后的输出