issue-creation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When to Use

适用场景

Use this skill when:

Creating a GitHub issue (bug report or feature request)
Helping a contributor file an issue
Triaging or approving issues as a maintainer

在以下场景使用本规范：

创建GitHub议题（Bug报告或功能需求）
协助贡献者提交议题
作为维护者进行议题分类或审批

Critical Rules

核心规则

Blank issues are disabled — MUST use a template (bug report or feature request)
Every issue gets
status:needs-review
automatically on creation
A maintainer MUST add
status:approved
before any PR can be opened
Questions go to Discussions, not issues

禁用空白议题 — 必须使用模板（Bug报告或功能需求模板）
所有议题创建时自动添加
status:needs-review
标签
维护者必须添加
status:approved
标签后，才能发起PR
疑问请前往Discussions，不要提交为议题

Workflow

工作流

1. Search existing issues for duplicates
2. Choose the correct template (Bug Report or Feature Request)
3. Fill in ALL required fields
4. Check pre-flight checkboxes
5. Submit → issue gets status:needs-review automatically
6. Wait for maintainer to add status:approved
7. Only then open a PR linking this issue

1. 搜索现有议题，避免重复
2. 选择正确的模板（Bug报告或功能需求）
3. 填写所有必填字段
4. 勾选预检复选框
5. 提交 → 议题自动添加status:needs-review标签
6. 等待维护者添加status:approved标签
7. 之后才能发起关联该议题的PR

Issue Templates

议题模板

Bug Report

Bug报告

Template:

.github/ISSUE_TEMPLATE/bug_report.yml

Auto-labels:

bug

status:needs-review

模板：

.github/ISSUE_TEMPLATE/bug_report.yml

自动标签：

bug

status:needs-review

Required Fields

必填字段

Field	Description
Pre-flight Checks	Checkboxes: no duplicate + understands approval workflow
Bug Description	Clear description of the bug
Steps to Reproduce	Numbered steps to reproduce
Expected Behavior	What should have happened
Actual Behavior	What happened instead (include errors/logs)
Operating System	Dropdown: macOS, Linux variants, Windows, WSL
Agent / Client	Dropdown: Claude Code, OpenCode, Gemini CLI, Cursor, Windsurf, Codex, Other
Shell	Dropdown: bash, zsh, fish, Other

字段	说明
预检检查	复选框：无重复议题 + 理解审批工作流
Bug描述	清晰描述Bug内容
复现步骤	编号列出复现步骤
预期行为	应该出现的正确结果
实际行为	实际发生的情况（包含错误信息/日志）
操作系统	下拉选项：macOS、Linux发行版、Windows、WSL
Agent / 客户端	下拉选项：Claude Code、OpenCode、Gemini CLI、Cursor、Windsurf、Codex、其他
Shell环境	下拉选项：bash、zsh、fish、其他

Optional Fields

可选字段

Field	Description
Relevant Logs	Log output (auto-formatted as code block)
Additional Context	Screenshots, workarounds, extra info

字段	说明
相关日志	日志输出（自动格式化为代码块）
补充说明	截图、临时解决方案、额外信息

Example — Bug Report via CLI

示例 — 通过CLI提交Bug报告

bash

gh issue create --template "bug_report.yml" \
  --title "fix(scripts): setup.sh fails on zsh with glob error" \
  --body "

bash

gh issue create --template "bug_report.yml" \
  --title "fix(scripts): setup.sh fails on zsh with glob error" \
  --body "

Pre-flight Checks

I have searched existing issues and this is not a duplicate
I understand this issue needs status:approved before a PR can be opened

I have searched existing issues and this is not a duplicate
I understand this issue needs status:approved before a PR can be opened

Bug Description

Running setup.sh on zsh throws a glob error when no matching files exist.

Steps to Reproduce

Clone the repo
Run `./scripts/setup.sh` in zsh
See error: `zsh: no matches found: skills/*`

Clone the repo
Run `./scripts/setup.sh` in zsh
See error: `zsh: no matches found: skills/*`

Expected Behavior

The script should handle missing glob matches gracefully.

Actual Behavior

Script crashes with glob error.

Operating System

macOS

Agent / Client

Claude Code

Shell

zsh

Relevant Logs

``` zsh: no matches found: skills/* ``` "

---

``` zsh: no matches found: skills/* ``` "

---

Feature Request

功能需求

Template:

.github/ISSUE_TEMPLATE/feature_request.yml

Auto-labels:

enhancement

status:needs-review

模板：

.github/ISSUE_TEMPLATE/feature_request.yml

自动标签：

enhancement

status:needs-review

Required Fields

必填字段

Field	Description
Pre-flight Checks	Checkboxes: no duplicate + understands approval workflow
Problem Description	The pain point this feature solves
Proposed Solution	How it should work from the user's perspective
Affected Area	Dropdown: Scripts, Skills, Examples, Documentation, CI/Workflows, Other

字段	说明
预检检查	复选框：无重复议题 + 理解审批工作流
问题描述	该功能要解决的痛点
解决方案建议	从用户视角描述功能的预期工作方式
影响范围	下拉选项：脚本、Skills、示例、文档、CI/工作流、其他

Optional Fields

可选字段

Field	Description
Alternatives Considered	Other approaches or workarounds
Additional Context	Mockups, examples, references

字段	说明
备选方案	其他可行方案或临时解决办法
补充说明	原型图、示例、参考资料

Example — Feature Request via CLI

示例 — 通过CLI提交功能需求

bash

gh issue create --template "feature_request.yml" \
  --title "feat(scripts): add Codex support to setup.sh" \
  --body "

bash

gh issue create --template "feature_request.yml" \
  --title "feat(scripts): add Codex support to setup.sh" \
  --body "

Pre-flight Checks

I have searched existing issues and this is not a duplicate
I understand this issue needs status:approved before a PR can be opened

I have searched existing issues and this is not a duplicate
I understand this issue needs status:approved before a PR can be opened

Problem Description

The setup script only configures Claude Code, Gemini CLI, and OpenCode. Codex users have to manually copy skills.

Proposed Solution

Add a Codex option to setup.sh that links skills to the .codex/ directory.

Example: ```bash ./scripts/setup.sh --agent codex ```

Add a Codex option to setup.sh that links skills to the .codex/ directory.

Example: ```bash ./scripts/setup.sh --agent codex ```

Affected Area

Scripts (setup, installation)

Alternatives Considered

Manually symlinking, but that defeats the purpose of the setup script. "

---

Manually symlinking, but that defeats the purpose of the setup script. "

---

Label System

标签体系

Applied Automatically on Issue Creation

议题创建时自动添加的标签

Template	Labels added
Bug Report	`bug` , `status:needs-review`
Feature Request	`enhancement` , `status:needs-review`

模板	添加的标签
Bug报告	`bug` , `status:needs-review`
功能需求	`enhancement` , `status:needs-review`

Applied by Maintainers

维护者手动添加的标签

Label	When to apply
`status:approved`	Issue accepted for implementation — PRs can now be opened
`priority:high`	Critical bug or urgent feature
`priority:medium`	Important but not blocking
`priority:low`	Nice to have

标签	适用场景
`status:approved`	议题已被接受可实施 — 现在可以发起PR
`priority:high`	严重Bug或紧急功能需求
`priority:medium`	重要但不阻塞进度
`priority:low`	锦上添花的需求

Maintainer Approval Workflow

维护者审批工作流

1. New issue arrives with status:needs-review
2. Review the issue — is it valid, clear, and in scope?
3. If YES → add status:approved label
4. If NO → comment with reason, close if needed
5. Contributor can now open a PR linking this issue

1. 新议题创建，带有status:needs-review标签
2. 审核议题 — 是否有效、清晰且符合项目范围？
3. 若通过 → 添加status:approved标签
4. 若不通过 → 备注原因，必要时关闭议题
5. 贡献者现在可以发起关联该议题的PR

Decision Tree

决策树

Is it a bug?                    → Use Bug Report template
Is it a new feature/improvement? → Use Feature Request template
Is it a question?               → Use Discussions, NOT issues
Is it a duplicate?              → Link to existing issue, close

是否为Bug？                    → 使用Bug报告模板
是否为新功能/改进？ → 使用功能需求模板
是否为疑问？               → 使用Discussions，不要提交为议题
是否重复？              → 关联现有议题，关闭当前议题

Commands

命令

bash

undefined

bash

undefined

Search existing issues before creating

创建前搜索现有议题

gh issue list --search "keyword"

Create bug report

创建Bug报告

gh issue create --template "bug_report.yml" --title "fix(scope): description"

Create feature request

创建功能需求

gh issue create --template "feature_request.yml" --title "feat(scope): description"

Maintainer: approve an issue

维护者：审批议题

gh issue edit <number> --add-label "status:approved"

Maintainer: add priority

维护者：添加优先级标签

gh issue edit <number> --add-label "priority:high"

undefined

gh issue edit <number> --add-label "priority:high"

undefined