github-issues

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitHub Issues Management

GitHub Issues 管理

Create, retrieve, update, and manage GitHub issues with comprehensive context integration and structured workflows.

支持创建、获取、更新和管理GitHub Issue，具备完整的上下文集成能力和结构化工作流。

When to Use This Skill

何时使用本技能

Activate this skill when:

The user wants to create a new GitHub issue
The user asks to view or retrieve issue details
The user needs to update an existing issue
The user wants to list issues in a repository
The user mentions managing issues, bug reports, or feature requests in GitHub
The user wants to close, reopen, or modify issue properties
The user needs to add comments or labels to issues
The user wants to search for issues

在以下场景激活本技能：

用户想要创建新的GitHub Issue
用户请求查看或获取Issue详情
用户需要更新现有Issue
用户想要列出代码仓库中的Issue
用户提到需要管理GitHub中的Issue、错误报告或功能需求
用户想要关闭、重新打开或修改Issue属性
用户需要给Issue添加评论或标签
用户想要搜索Issue

Critical Rules

核心规则

IMPORTANT: Always confirm owner/repo before creating or modifying issues

Always use descriptive issue titles and provide structured descriptions

Never create duplicate issues - search existing issues first when appropriate

重要提示：创建或修改Issue前，请务必确认仓库的所有者/名称

始终使用清晰描述性的Issue标题，并提供结构化的描述内容

绝对不要创建重复Issue：在合适的场景下，请先搜索现有Issue

Available CLI Commands

可用CLI命令

Command	Purpose
`gh issue create`	Create new issues
`gh issue edit <number>`	Update existing issues
`gh issue view <number>`	Fetch issue details
`gh search issues "<query>"`	Search issues
`gh issue comment <number>`	Add comments
`gh issue list`	List repository issues

命令	用途
`gh issue create`	创建新Issue
`gh issue edit <number>`	更新现有Issue
`gh issue view <number>`	获取Issue详情
`gh search issues "<query>"`	搜索Issue
`gh issue comment <number>`	添加评论
`gh issue list`	列出仓库Issue

Workflow

工作流

1. Gather Context

1. 收集上下文

First, collect information about the current repository and context:

Identify the repository (owner and repo name)
Understand the type of issue (bug, feature, task, etc.)
Gather relevant labels, milestones, and assignees if applicable

首先，收集当前仓库和上下文的相关信息：

确定仓库信息（所有者和仓库名称）
了解Issue类型（错误、功能需求、任务等）
收集相关的标签、里程碑和经办人信息（如适用）

2. Repository Verification

2. 仓库验证

Before any operation, verify you have the correct repository identifier:

Confirm repository exists
Understand repository structure
Check available labels and milestones

在执行任何操作前，确认你使用的是正确的仓库标识：

确认仓库存在
了解仓库结构
检查可用的标签和里程碑

3. Issue Operations

3. Issue操作

Creating a New Issue

创建新Issue

When creating issues, gather complete context:

Required Information:

```
owner
```
: Repository owner (organization or user)
```
repo
```
: Repository name
```
title
```
: Clear, descriptive issue title

Optional but Recommended:

```
body
```
: Detailed description in Markdown format
```
labels
```
: Label names (e.g., "bug,enhancement")
```
assignees
```
: Usernames to assign
```
milestone
```
: Milestone number (integer)

Human-in-the-Loop - Ask for Context

Always ask to clarify issue details:

Question: "What type of issue is this?"
Options:
- "Bug report - something is not working correctly"
- "Feature request - new functionality needed"
- "Task - work item to complete"
- "Documentation - documentation needs update"
- "Other - let me describe it"

Title Guidelines:

Start with type prefix when useful:
```
[Bug]
```
,
```
[Feature]
```
,
```
[Docs]
```
Be specific and actionable
Keep under 72 characters

Examples:

```
[Bug] Login fails with SSO enabled
```
```
[Feature] Add dark mode support
```
```
Add unit tests for auth module
```

Issue Description Template:

Structure descriptions for clarity:

markdown

undefined

创建Issue时，请收集完整的上下文信息：

必填信息：

```
owner
```
：仓库所有者（组织或用户）
```
repo
```
：仓库名称
```
title
```
：清晰、具有描述性的Issue标题

可选但推荐填写的信息：

```
body
```
：Markdown格式的详细描述
```
labels
```
：标签名称（例如："bug,enhancement"）
```
assignees
```
：经办人用户名
```
milestone
```
：里程碑编号（整数）

人在回路-询问上下文信息

始终要询问确认Issue的详细信息：

Question: "What type of issue is this?"
Options:
- "Bug report - something is not working correctly"
- "Feature request - new functionality needed"
- "Task - work item to complete"
- "Documentation - documentation needs update"
- "Other - let me describe it"

标题规范：

合适的情况下以类型前缀开头：
```
[Bug]
```
、
```
[Feature]
```
、
```
[Docs]
```
内容具体、可执行
长度控制在72个字符以内

示例：

```
[Bug] Login fails with SSO enabled
```
```
[Feature] Add dark mode support
```
```
Add unit tests for auth module
```

Issue描述模板：

采用以下结构提升描述清晰度：

markdown

undefined

Summary

[Brief description of the issue]

Current Behavior

[What is happening now - for bugs]

Expected Behavior

[What should happen - for bugs]

Steps to Reproduce

[For bugs - numbered steps]

Acceptance Criteria

[For features/tasks - what defines "done"]

Additional Context

[Screenshots, logs, related issues, etc.]

undefined

[Screenshots, logs, related issues, etc.]

undefined

Retrieving Issue Details

获取Issue详情

Use

gh issue view <number>

with:

```
<number>
```
: Issue number (e.g., 42)

This returns complete issue information including:

Title and body
State (open/closed)
Labels and milestone
Assignees and author
Created/updated timestamps

使用

gh issue view <number>

命令，参数说明：

```
<number>
```
：Issue编号（例如42）

该命令会返回完整的Issue信息，包括：

标题和正文
状态（开放/关闭）
标签和里程碑
经办人和创建者
创建/更新时间戳

Listing Issues

列出Issue

Use

gh issue list

with filters:

```
--state
```
: "open", "closed", or "all"
```
--label
```
: Filter by labels (comma-separated)
```
--assignee
```
: Filter by assignee username
```
--search
```
: Search in title and description
```
--sort
```
: Sort by "created", "updated", "comments"
```
--order
```
: "asc" or "desc"
```
--limit
```
: Results per page (default 30)

使用带筛选参数的

gh issue list

命令：

```
--state
```
："open"（开放）、"closed"（关闭）或"all"（全部）
```
--label
```
：按标签筛选（逗号分隔）
```
--assignee
```
：按经办人用户名筛选
```
--search
```
：在标题和描述中搜索
```
--sort
```
：按"created"（创建时间）、"updated"（更新时间）、"comments"（评论数）排序
```
--order
```
："asc"（升序）或"desc"（降序）
```
--limit
```
：每页返回结果数（默认30）

Searching Issues

搜索Issue

Use

gh search issues "<query>"

for advanced queries:

Search across repositories
Use GitHub search qualifiers (is:open, label:bug, etc.)
Full-text search in titles and bodies

使用

gh search issues "<query>"

执行高级查询：

可跨仓库搜索
支持GitHub搜索限定符（is:open、label:bug等）
支持标题和正文的全文搜索

Updating an Issue

更新Issue

When updating issues, only provide changed fields:

Use

gh issue edit <number>

with flags for fields to update (--title, --body, --add-label, --remove-label, --add-assignee, --milestone, etc.)

State Changes:

```
gh issue reopen <number>
```
- Open/reopen the issue
```
gh issue close <number>
```
- Close the issue

更新Issue时，仅提供需要修改的字段即可：

使用

gh issue edit <number>

命令，搭配对应参数指定要更新的字段（--title、--body、--add-label、--remove-label、--add-assignee、--milestone等）

状态变更：

```
gh issue reopen <number>
```
- 开放/重新开放Issue
```
gh issue close <number>
```
- 关闭Issue

Adding Comments

添加评论

Use

gh issue comment <number> --body "<comment>"

with:

```
<number>
```
: Issue number
```
<comment>
```
: Comment content in Markdown

使用

gh issue comment <number> --body "<comment>"

命令，参数说明：

```
<number>
```
：Issue编号
```
<comment>
```
：Markdown格式的评论内容

4. Execute Operations (Requires Confirmation)

4. 执行操作（需要确认）

CRITICAL: Confirm with user before creating or modifying issues

After gathering all information, present a summary for user approval:

Creating issue in repository: owner/repo
Title: [title]
Description: [summary]
Labels: [labels]
Assignee: [assignee]

Proceed with issue creation?

重要提示：创建或修改Issue前必须获得用户确认

收集完所有信息后，请向用户展示操作摘要请求审批：

Creating issue in repository: owner/repo
Title: [title]
Description: [summary]
Labels: [labels]
Assignee: [assignee]

Proceed with issue creation?

Issue Type Templates

Issue类型模板

Bug Report

错误报告

markdown

undefined

markdown

undefined

Description

The [component] is experiencing [issue] when [condition].

Steps to Reproduce

[First step]
[Second step]
[See error]

[First step]
[Second step]
[See error]

Expected Behavior

[What should happen]

Actual Behavior

[What actually happens]

Environment

Application Version: [version]

Application Version: [version]

Screenshots/Logs

[Attach relevant files]

Possible Solution

[Optional: if you have ideas]

undefined

[Optional: if you have ideas]

undefined

Feature Request

功能需求

markdown

undefined

markdown

undefined

Summary

[One-line description of the feature]

Motivation

[Why is this feature needed? What problem does it solve?]

Proposed Solution

[How should this work?]

Acceptance Criteria

Alternatives Considered

[Other approaches considered]

Additional Context

[Mockups, examples, references]

undefined

[Mockups, examples, references]

undefined

Task

任务

markdown

undefined

markdown

undefined

Task Description

[What needs to be done]

Background

[Why is this needed?]

Requirements

[Requirement 1]
[Requirement 2]

[Requirement 1]
[Requirement 2]

Definition of Done

[Criterion 1]
[Criterion 2]

[Criterion 1]
[Criterion 2]

Dependencies

[Related issues, blockers]

undefined

[Related issues, blockers]

undefined

Examples

示例

Example 1: Creating a Bug Report

示例1：创建错误报告

User: "Create a bug issue - the login page crashes when using SSO"

AI Workflow:

Ask for repository (owner/repo) if not known
Ask clarifying questions about the bug
Generate structured description
Present summary for confirmation

Create issue with

gh issue create --title "[Bug] Login page crashes when using SSO" --body "<description>" --label "bug"

Result:

gh issue create \
  --title "[Bug] Login page crashes when using SSO" \
  --body "## Description
The login page crashes when users attempt to authenticate using SSO.

用户： "Create a bug issue - the login page crashes when using SSO"

AI工作流：

若未知仓库信息，先询问仓库所有者/名称
询问关于错误的补充细节
生成结构化描述
展示操作摘要请求确认

使用

gh issue create --title "[Bug] Login page crashes when using SSO" --body "<description>" --label "bug"

创建Issue

结果：

gh issue create \
  --title "[Bug] Login page crashes when using SSO" \
  --body "## Description
The login page crashes when users attempt to authenticate using SSO.

Steps to Reproduce

Navigate to login page
Click 'Sign in with SSO'
Page crashes

Navigate to login page
Click 'Sign in with SSO'
Page crashes

Expected Behavior

SSO authentication should complete and redirect to dashboard.

Actual Behavior

Page becomes unresponsive and displays error.

Environment

Browser: [To be filled]
OS: [To be filled]"
--label "bug"

undefined

Browser: [To be filled]
OS: [To be filled]"
--label "bug"

undefined

Example 2: Feature Request with Priority

示例2：高优先级功能需求

User: "Create a feature request for dark mode with high priority"

AI Workflow:

Gather feature details
Structure the request
Add appropriate labels
Confirm and create

Result:

gh issue create \
  --title "[Feature] Add dark mode support" \
  --body "## Summary
Add dark mode theme option for improved user experience and accessibility.

用户： "Create a feature request for dark mode with high priority"

AI工作流：

收集功能细节
结构化需求内容
添加对应标签
确认后创建Issue

结果：

gh issue create \
  --title "[Feature] Add dark mode support" \
  --body "## Summary
Add dark mode theme option for improved user experience and accessibility.

Motivation

Reduces eye strain in low-light environments
Increasingly expected by users
Improves accessibility

Reduces eye strain in low-light environments
Increasingly expected by users
Improves accessibility

Proposed Solution

Implement theme toggle with system preference detection.

Acceptance Criteria

Toggle switch in settings
Persists user preference
Respects system preference by default
All UI components support both themes"
--label "enhancement,high-priority"

undefined

Toggle switch in settings
Persists user preference
Respects system preference by default
All UI components support both themes"
--label "enhancement,high-priority"

undefined

Example 3: Listing and Filtering Issues

示例3：筛选列出Issue

User: "Show me all open bugs assigned to me"

AI Workflow:

Use

gh issue list --state open --label bug --assignee @me

Result:

Found 3 open bug issues assigned to you:

#142 - [Bug] API timeout on large file uploads
      Labels: bug, priority-medium
      Created: 2024-01-15

#138 - [Bug] Dashboard graphs not rendering on Safari
      Labels: bug, frontend
      Created: 2024-01-12

#125 - [Bug] Email notifications delayed by 30+ minutes
      Labels: bug, priority-high
      Created: 2024-01-08

用户： "Show me all open bugs assigned to me"

AI工作流：

执行命令

gh issue list --state open --label bug --assignee @me

结果：

Found 3 open bug issues assigned to you:

#142 - [Bug] API timeout on large file uploads
      Labels: bug, priority-medium
      Created: 2024-01-15

#138 - [Bug] Dashboard graphs not rendering on Safari
      Labels: bug, frontend
      Created: 2024-01-12

#125 - [Bug] Email notifications delayed by 30+ minutes
      Labels: bug, priority-high
      Created: 2024-01-08

Example 4: Closing an Issue with Comment

示例4：关闭Issue并添加评论

User: "Close issue #142 and add a comment that it's fixed in v2.4.0"

AI Workflow:

First, add a comment to the issue:

gh issue comment 142 --body "Fixed in v2.4.0. Closing this issue."

Then close the issue:
```
gh issue close 142
```

Result:

Issue #142 has been commented and closed.

用户： "Close issue #142 and add a comment that it's fixed in v2.4.0"

AI工作流：

首先给Issue添加评论：

gh issue comment 142 --body "Fixed in v2.4.0. Closing this issue."

然后关闭Issue：
```
gh issue close 142
```

结果：

Issue #142 has been commented and closed.

Common Labels

常用标签

Use these standard labels when applicable:

Label	Use For
`bug`	Something isn't working
`enhancement`	New feature or improvement
`documentation`	Documentation updates
`good first issue`	Good for newcomers
`help wanted`	Extra attention needed
`question`	Further information requested
`wontfix`	Will not be addressed
`duplicate`	Already exists
`invalid`	Not a valid issue

适用场景下请使用以下标准标签：

标签	用途
`bug`	功能运行异常
`enhancement`	新功能或体验优化
`documentation`	文档更新需求
`good first issue`	适合新贡献者认领的任务
`help wanted`	需要额外关注与支持
`question`	需要更多信息澄清
`wontfix`	不会处理的Issue
`duplicate`	重复的Issue
`invalid`	无效的Issue

Important Notes

重要注意事项

Always verify repository access - Ensure you have permission to create/modify issues
Use labels consistently - Follow repository labeling conventions
Be specific in titles - Prefix with [Bug], [Feature], [Task] for clarity
Include reproduction steps - Essential for bug reports
Define acceptance criteria - Clear "definition of done" for features/tasks
Link related issues - Use "Related to #XX" or "Blocks #XX" in descriptions
Mention users with @username - For visibility and notifications
Use milestones - Associate issues with releases when applicable

始终验证仓库权限 - 确保你有创建/修改Issue的权限
保持标签使用一致性 - 遵循仓库的标签规范
标题内容要具体 - 增加[Bug]、[Feature]、[Task]前缀提升可读性
包含复现步骤 - 错误报告中必须提供复现步骤
定义验收标准 - 功能/任务需要明确的「完成定义」
关联相关Issue - 在描述中使用「Related to #XX」或「Blocks #XX」关联其他Issue
使用@username提及用户 - 用于通知相关人员查看
使用里程碑 - 适用场景下将Issue关联到对应版本

GitHub Issue Best Practices

GitHub Issue最佳实践

Writing Effective Titles

编写高效标题

Be concise but descriptive
Include issue type prefix: [Bug], [Feature], [Task], [Docs]
Mention affected component if applicable
Avoid vague titles like "Fix bug" or "Update code"

简洁但具备描述性
包含Issue类型前缀：[Bug]、[Feature]、[Task]、[Docs]
适用场景下提及受影响的组件
避免模糊的标题，例如「Fix bug」或「Update code」

Structuring Descriptions

结构化描述内容

Use Markdown formatting for readability
Include all relevant context upfront
Add screenshots or logs when helpful
Link to related issues, PRs, or documentation
Use task lists for trackable sub-items

使用Markdown格式提升可读性
开头就展示所有相关上下文
适用场景下添加截图或日志
关联相关Issue、PR或文档
使用任务列表跟踪子项进度

Label Strategy

标签使用策略

Combine type labels (
```
bug
```
,
```
enhancement
```
) with area labels (
```
frontend
```
,
```
api
```
)
Use priority labels when needed (
```
priority-high
```
,
```
priority-low
```
)
Keep label taxonomy consistent across repositories

组合使用类型标签（
```
bug
```
、
```
enhancement
```
）和领域标签（
```
frontend
```
、
```
api
```
）
需要时使用优先级标签（
```
priority-high
```
、
```
priority-low
```
）
跨仓库保持标签分类体系一致

Assignment and Workflow

任务分配与工作流

Assign issues to specific team members
Use milestones for release planning
Update issue status as work progresses
Close issues with reference to fixing PR: "Fixes #XX"

将Issue分配给具体的团队成员
使用里程碑做版本规划
工作推进时及时更新Issue状态
关闭Issue时关联修复的PR：「Fixes #XX」