github-issue-from-templates

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitHub Issue Creation — Data-Driven Workflow Engine

GitHub Issue 创建——数据驱动的工作流引擎

This skill creates GitHub issues by dynamically fetching field definitions from GitHub issue templates at runtime. Template metadata (triggers, labels, defaults, formatting rules) is stored in per-template JSON config files. Configs can be stored locally or in a GitHub repository for cross-machine and team sharing. The skill itself contains no hardcoded field definitions.

本Skill通过在运行时从GitHub Issue模板动态获取字段定义来创建GitHub Issue。模板元数据（触发器、标签、默认值、格式化规则）存储在每个模板对应的JSON配置文件中。配置文件可存储在本地或GitHub仓库中，实现跨机器和团队共享。本Skill本身不包含任何硬编码的字段定义。

File Structure

文件结构

~/.claude/skills/github-issue-from-templates/
  SKILL.md                    # This file — generic workflow engine
  references/
    schema.json               # JSON Schema for template config files
    settings-schema.json      # JSON Schema for settings.json

~/.claude/configs/github-issue-from-templates/
  settings.json               # Storage mode config — created on first run
  *.json                      # Template configs (local mode only) — user-managed, survives skill updates

<owner>/<repo>/<path>/        # Template configs (GitHub mode) — stored in a GitHub repo
  *.json

Why a separate directory? The skill installation directory (
~/.claude/skills/...
) is replaced on
npx skills update
. Storing template configs in
~/.claude/configs/github-issue-from-templates/
(local mode) or a GitHub repo (GitHub mode) keeps them safe across updates. The
settings.json
file always lives locally since it tells the skill where to find configs.

~/.claude/skills/github-issue-from-templates/
  SKILL.md                    # 本文件——通用工作流引擎
  references/
    schema.json               # 模板配置文件的JSON Schema
    settings-schema.json      # settings.json的JSON Schema

~/.claude/configs/github-issue-from-templates/
  settings.json               # 存储模式配置——首次运行时创建
  *.json                      # 模板配置文件（仅本地模式）——由用户管理，Skill更新时不会被覆盖

<owner>/<repo>/<path>/        # 模板配置文件（GitHub模式）——存储在GitHub仓库中
  *.json

为何使用独立目录？ Skill安装目录（
~/.claude/skills/...
）在执行
npx skills update
时会被替换。将模板配置文件存储在
~/.claude/configs/github-issue-from-templates/
（本地模式）或GitHub仓库（GitHub模式）中，可确保它们在Skill更新后依然保留。
settings.json
文件始终存储在本地，因为它用于告知Skill配置文件的位置。

Tool Detection

工具检测

Before starting the workflow, determine which GitHub tool is available:

GitHub MCP (preferred): Check if the GitHub MCP server is available by looking for MCP tools like
```
get_file_contents
```
or
```
create_issue
```
. If available, use MCP tools throughout.
gh
CLI (fallback): If GitHub MCP is not available, verify the
```
gh
```
CLI is installed and authenticated by running
```
gh auth status
```
. If authenticated, use
```
gh
```
CLI commands throughout.
Neither available: Notify the user that either the GitHub MCP server or the
```
gh
```
CLI
is required, and stop.

Store the detected tool as the GitHub method (

mcp

cli

) and use it consistently for all GitHub operations in the workflow.

Note: When using GitHub repo storage, the same detected method is used for additional operations: listing directory contents, reading files, creating/updating files, and optionally creating repositories.

在启动工作流之前，先确定可用的GitHub工具：

GitHub MCP（优先选择）：通过查找
```
get_file_contents
```
或
```
create_issue
```
等MCP工具，检查GitHub MCP服务器是否可用。如果可用，则全程使用MCP工具。
gh
CLI（备选）：如果GitHub MCP不可用，则验证
```
gh
```
CLI是否已安装并通过运行
```
gh auth status
```
完成认证。如果已认证，则全程使用
```
gh
```
CLI命令。
两者均不可用：通知用户需要安装GitHub MCP服务器或
```
gh
```
CLI
，然后停止操作。

将检测到的工具存储为GitHub方法（

mcp

或

cli

），并在工作流的所有GitHub操作中统一使用该方法。

注意：当使用GitHub仓库存储时，检测到的方法也会用于其他操作：列出目录内容、读取文件、创建/更新文件，以及可选的创建仓库。

Workflow

工作流

Step 0: Settings & Storage Resolution

步骤0：设置与存储解析

Before template selection, resolve where configs are stored.

Check if

~/.claude/configs/github-issue-from-templates/settings.json

exists.

If it exists: Read it, validate against
```
references/settings-schema.json
```
, and resolve the storage mode:
- ```
configStorage.type === "local"
```
  → configs are in
```
~/.claude/configs/github-issue-from-templates/
```
- ```
configStorage.type === "github"
```
  → configs are in the specified GitHub repo at the configured path and branch
If it does not exist: Run the Setup Flow (see below).

在选择模板之前，先确定配置文件的存储位置。

检查

~/.claude/configs/github-issue-from-templates/settings.json

是否存在。

如果存在：读取该文件，根据
```
references/settings-schema.json
```
进行验证，然后解析存储模式：
- ```
configStorage.type === "local"
```
  → 配置文件存储在
```
~/.claude/configs/github-issue-from-templates/
```
- ```
configStorage.type === "github"
```
  → 配置文件存储在指定GitHub仓库的配置路径和分支中
如果不存在：运行设置流程（见下文）。

Setup Flow (First Run)

设置流程（首次运行）

Ask the user how they want to store their template configs:

Option A — Local storage:

Create the directory

~/.claude/configs/github-issue-from-templates/

if it doesn't exist

Write

settings.json

json

{
  "configStorage": {
    "type": "local"
  }
}

Offer to create a first template config

Option B — GitHub repository storage:

Ask if they have an existing repo for configs

If yes:

Gather:

owner

repo

path

(default:

configs/github-issue-from-templates/

branch

(default:

main

)

Validate access by listing the directory contents using the detected GitHub method (see Loading Configs from GitHub for commands)

Write

settings.json

json

{
  "configStorage": {
    "type": "github",
    "owner": "<owner>",
    "repo": "<repo>",
    "path": "configs/github-issue-from-templates/",
    "branch": "main"
  }
}

If no — help create a new repo:

Suggest the name
```
github-issue-from-templates-configs
```
(default private)

If MCP: Use

create_repository

with

name

private: true

description

If CLI:

gh repo create <owner>/github-issue-from-templates-configs --private --description "Template configs for github-issue-from-templates skill"

Create the initial directory by committing a placeholder
```
README.md
```
at the configured path
Write
```
settings.json
```
as above

询问用户希望如何存储模板配置文件：

选项A——本地存储：

如果目录

~/.claude/configs/github-issue-from-templates/

不存在，则创建该目录

写入

settings.json

：

json

{
  "configStorage": {
    "type": "local"
  }
}

提供创建首个模板配置文件的选项

选项B——GitHub仓库存储：

询问用户是否已有用于存储配置文件的仓库

如果有：

收集信息：
```
owner
```
、
```
repo
```
、
```
path
```
（默认值：
```
configs/github-issue-from-templates/
```
）、
```
branch
```
（默认值：
```
main
```
）
使用检测到的GitHub方法列出目录内容，验证访问权限（验证命令见从GitHub加载配置文件）

写入

settings.json

：

json

{
  "configStorage": {
    "type": "github",
    "owner": "<owner>",
    "repo": "<repo>",
    "path": "configs/github-issue-from-templates/",
    "branch": "main"
  }
}

如果没有——帮助创建新仓库：
- 建议仓库名称为
```
github-issue-from-templates-configs
```
  （默认设为私有）
- 如果使用MCP：使用
```
create_repository
```
  方法，传入
```
name
```
  、
```
private: true
```
  和
```
description
```
- 如果使用CLI：执行命令
```
gh repo create <owner>/github-issue-from-templates-configs --private --description "Template configs for github-issue-from-templates skill"
```
- 在配置路径下提交一个占位符
```
README.md
```
  ，创建初始目录
- 写入如上所示的
```
settings.json
```

Switching Storage Modes

切换存储模式

If the user asks to change their storage mode (e.g., from local to GitHub or vice versa):

Read the current
```
settings.json
```
to determine the current mode
Ask the user if they want to migrate existing configs to the new location:
- Local → GitHub: Read each local
```
.json
```
  config (excluding
```
settings.json
```
  ), then commit each to the GitHub repo at the configured path
- GitHub → Local: Fetch each
```
.json
```
  config from GitHub, then write each to
```
~/.claude/configs/github-issue-from-templates/
```
Update
```
settings.json
```
with the new storage configuration
Confirm the switch and report how many configs were migrated

如果用户要求更改存储模式（例如从本地切换到GitHub，或反之）：

读取当前的
```
settings.json
```
，确定当前的存储模式
询问用户是否需要迁移现有配置文件到新位置：
- 本地→GitHub：读取每个本地
```
.json
```
  配置文件（排除
```
settings.json
```
  ），然后将每个文件提交到GitHub仓库的配置路径下
- GitHub→本地：从GitHub获取每个
```
.json
```
  配置文件，然后将每个文件写入
```
~/.claude/configs/github-issue-from-templates/
```
更新
```
settings.json
```
，使用新的存储配置
确认切换完成，并告知用户已迁移的配置文件数量

Step 1: Template Selection

步骤1：模板选择

Load configs based on the resolved storage mode from Step 0:
- Local: Read all
```
.json
```
  files from
```
~/.claude/configs/github-issue-from-templates/
```
  , excluding
```
settings.json
```
  . If the directory does not exist or contains no config files, offer to create a first template config.
- GitHub: List and fetch
```
.json
```
  files from the configured repo/path/branch (see Loading Configs from GitHub), excluding
```
settings.json
```
  and
```
README.md
```
  . If the directory is empty or inaccessible, notify the user and offer to add a first config.
For each config, compare the user's request against
```
triggers.keywords
```
(case-insensitive substring match) and
```
triggers.description
```
.
Single match: Proceed with that template. Confirm the selection with the user briefly (e.g., "I'll use the [template name] template.").
Multiple matches: Present the matching templates by
```
name
```
and
```
description
```
and ask the user to choose.
No match: Present all available templates by
```
name
```
and
```
description
```
and ask the user to choose.

加载配置文件：根据步骤0中解析的存储模式加载配置文件：
- 本地模式：读取
```
~/.claude/configs/github-issue-from-templates/
```
  下所有
```
.json
```
  文件，排除
```
settings.json
```
  。如果目录不存在或没有配置文件，提供创建首个模板配置文件的选项。
- GitHub模式：列出并获取配置仓库/路径/分支下的
```
.json
```
  文件（见从GitHub加载配置文件），排除
```
settings.json
```
  和
```
README.md
```
  。如果目录为空或无法访问，通知用户并提供添加首个配置文件的选项。
对于每个配置文件，将用户的请求与
```
triggers.keywords
```
（不区分大小写的子字符串匹配）和
```
triggers.description
```
进行比较。
单个匹配项：使用该模板继续操作。向用户简要确认选择（例如：“我将使用[模板名称]模板。”）。
多个匹配项：展示所有匹配模板的
```
name
```
和
```
description
```
，让用户选择。
无匹配项：展示所有可用模板的
```
name
```
和
```
description
```
，让用户选择。

Loading Configs from GitHub

从GitHub加载配置文件

When

configStorage.type === "github"

, use these methods to list and fetch config files.

当

configStorage.type === "github"

时，使用以下方法列出和获取配置文件。

Listing files in the config directory

列出配置目录中的文件

If MCP: Use

get_file_contents

on the directory path:

owner: <configStorage.owner>
repo:  <configStorage.repo>
path:  <configStorage.path>
ref:   <configStorage.branch>

The response returns an array of file entries. Filter to

.json

files, excluding

settings.json

If CLI: Use the GitHub contents API:

bash

gh api repos/<owner>/<repo>/contents/<path>?ref=<branch> --jq '.[] | select(.name | endswith(".json")) | select(.name != "settings.json") | .name'

如果使用MCP：对目录路径使用

get_file_contents

方法：

owner: <configStorage.owner>
repo:  <configStorage.repo>
path:  <configStorage.path>
ref:   <configStorage.branch>

响应会返回文件条目数组。筛选出

.json

文件，排除

settings.json

。

如果使用CLI：使用GitHub内容API：

bash

gh api repos/<owner>/<repo>/contents/<path>?ref=<branch> --jq '.[] | select(.name | endswith(".json")) | select(.name != "settings.json") | .name'

Fetching individual config files

获取单个配置文件

If MCP: Use

get_file_contents

with the full file path:

owner: <configStorage.owner>
repo:  <configStorage.repo>
path:  <configStorage.path>/<filename>
ref:   <configStorage.branch>

If CLI:

bash

gh api repos/<owner>/<repo>/contents/<path>/<filename>?ref=<branch> --jq '.content' | base64 -d

Parse each fetched file as JSON. Skip files that fail to parse and notify the user (see Error Handling).

如果使用MCP：对完整文件路径使用

get_file_contents

方法：

owner: <configStorage.owner>
repo:  <configStorage.repo>
path:  <configStorage.path>/<filename>
ref:   <configStorage.branch>

如果使用CLI：

bash

gh api repos/<owner>/<repo>/contents/<path>/<filename>?ref=<branch> --jq '.content' | base64 -d

将每个获取到的文件解析为JSON。跳过解析失败的文件并通知用户（见错误处理）。

Step 2: Fetch Template from GitHub

步骤2：从GitHub获取模板

Fetch the template file using the detected GitHub method:

If MCP: Use

get_file_contents

owner: <config.repository.owner>
repo:  <config.repository.repo>
path:  <config.templateSource.path>

If CLI: Use

gh

to fetch the raw file content:

bash

gh api repos/<config.repository.owner>/<config.repository.repo>/contents/<config.templateSource.path> --jq '.content' | base64 -d

Then parse based on

config.templateSource.format

使用检测到的GitHub方法获取模板文件：

如果使用MCP：使用

get_file_contents

方法：

owner: <config.repository.owner>
repo:  <config.repository.repo>
path:  <config.templateSource.path>

如果使用CLI：使用

gh

命令获取原始文件内容：

bash

gh api repos/<config.repository.owner>/<config.repository.repo>/contents/<config.templateSource.path> --jq '.content' | base64 -d

然后根据

config.templateSource.format

进行解析：

Format:

yml

(Form-based templates)

格式：

yml

（基于表单的模板）

Parse the YAML content and extract:

Title pattern: From the top-level

title:

field (e.g.,

"[Issue Type] [Short descriptive title]"

)

Template-level labels: From the top-level
```
labels:
```
array
Template-level assignees: From the top-level
```
assignees:
```
array
Fields: From the
```
body:
```
array. For each entry:
- Skip entries where
```
type: markdown
```
  — these are instructional text, not fields
- For all other entries, extract:
  - ```
  id
```
  — unique field identifier
- ```
type
```
    —
```
dropdown
```
    ,
```
input
```
    ,
```
textarea
```
  - ```
  attributes.label
```
  — human-readable field name
- ```
attributes.description
```
    — help text for the field
  - ```
  attributes.options
```
  — available choices (for dropdowns)
- ```
attributes.placeholder
```
    — example/guidance text
  - ```
  validations.required
```
  — whether the field must be filled

解析YAML内容并提取：

标题模板：从顶层
```
title:
```
字段提取（例如：
```
"[Issue Type] [Short descriptive title]"
```
）
模板级标签：从顶层
```
labels:
```
数组提取
模板级经办人：从顶层
```
assignees:
```
数组提取
字段：从
```
body:
```
数组提取。对于每个条目：
- 跳过
```
type: markdown
```
  的条目——这些是说明文本，不是字段
- 对于其他所有条目，提取：
  - ```
  id
```
  ——唯一字段标识符
- ```
type
```
    ——
```
dropdown
```
    、
```
input
```
    、
```
textarea
```
  - ```
  attributes.label
```
  ——易读的字段名称
- ```
attributes.description
```
    ——字段的帮助文本
  - ```
  attributes.options
```
  ——可选选项（适用于下拉菜单）
- ```
attributes.placeholder
```
    ——示例/指导文本
  - ```
  validations.required
```
  ——该字段是否为必填项

Format:

md

(Frontmatter + markdown templates)

格式：

md

（Frontmatter + Markdown模板）

Parse the frontmatter (between

---

delimiters) and extract:

Title pattern: From

title:

(e.g.,

'[A11y]: Product - Feature - Request'

)

Template-level labels: From
```
labels:
```
(may be a string or array)
Template-level assignees: From
```
assignees:
```
(may be a string or array)

Parse the markdown body to identify:

Sections:
```
##
```
headings define major sections
Checkbox groups: Lines matching
```
- [ ] Item text
```
grouped under a heading or bold label
Labeled fields: Bold-labeled list items like
```
- **Team name:**
```
under a section
Self-verification checklists: Sections like "Yes, I have" contain items the skill should satisfy automatically

解析分隔符

---

之间的Frontmatter并提取：

标题模板：从
```
title:
```
字段提取（例如：
```
'[A11y]: Product - Feature - Request'
```
）
模板级标签：从
```
labels:
```
提取（可能是字符串或数组）
模板级经办人：从
```
assignees:
```
提取（可能是字符串或数组）

解析Markdown正文，识别：

章节：
```
##
```
标题定义主要章节
复选框组：匹配
```
- [ ] Item text
```
格式的行，按标题或粗体标签分组
带标签的字段：章节下的粗体标签列表项，如
```
- **Team name:**
```
自我验证清单：诸如“Yes, I have”的章节包含Skill应自动满足的条目

Step 3: Gather Information

步骤3：收集信息

For each extracted field, apply the following logic in order:

Pre-fill from user request: If the user already provided a value for this field in their initial message, pre-fill it and confirm during the preview step.
Apply defaults: Check
```
config.fieldDefaults[fieldId].value
```
— if present, use as the default. Also check
```
config.defaults
```
for matching keys.
Check skip conditions: Check
```
config.fieldSkipConditions[fieldId]
```
— if an
```
onlyWhen
```
condition exists and is not met, skip this field entirely.
Prompt if needed: If the field is required (
```
validations.required: true
```
) and no value has been determined, prompt the user. Use the field's
```
label
```
as the question and
```
description
```
/
```
placeholder
```
as guidance.
Apply gathering notes: Use
```
config.fieldDefaults[fieldId].gatheringNotes
```
for additional guidance on how to present or gather this field.

Gathering style:

Be conversational — don't present a wall of questions
Batch related questions together (e.g., ask for summary and description in one turn)
For dropdowns, present the options from the template
For fields with defaults, mention the default and ask if it's correct
Skip optional fields that the user hasn't mentioned unless they're likely relevant

对于每个提取的字段，按以下顺序应用逻辑：

从用户请求中预填充：如果用户在初始消息中已提供该字段的值，则预填充该值，并在预览步骤中确认。
应用默认值：检查
```
config.fieldDefaults[fieldId].value
```
——如果存在，则将其用作默认值。同时检查
```
config.defaults
```
中是否有匹配的键。
检查跳过条件：检查
```
config.fieldSkipConditions[fieldId]
```
——如果存在
```
onlyWhen
```
条件且未满足，则完全跳过该字段。
必要时提示用户：如果字段是必填项（
```
validations.required: true
```
）且尚未确定值，则提示用户。使用字段的
```
label
```
作为问题，
```
description
```
/
```
placeholder
```
作为指导。
应用收集说明：使用
```
config.fieldDefaults[fieldId].gatheringNotes
```
获取关于如何展示或收集该字段的额外指导。

收集风格：

采用对话式语气——不要一次性抛出大量问题
将相关问题批量提出（例如，在一轮对话中询问摘要和描述）
对于下拉菜单，展示模板中的选项
对于有默认值的字段，提及默认值并询问是否正确
跳过用户未提及的可选字段，除非它们可能相关

Step 4: Compose Issue

步骤4：组装Issue

Title

标题

Build the title by substituting placeholders in the title pattern:

Use
```
config.title.override
```
if present; otherwise use the pattern extracted from the template in Step 2
Replace placeholder text with gathered field values using reasoning (e.g.,
```
[Issue Type]
```
→ the value of the
```
issue-type
```
field,
```
[Short descriptive title]
```
→ the
```
summary
```
field value)

通过替换标题模板中的占位符生成标题：

如果存在
```
config.title.override
```
，则使用该值；否则使用步骤2中从模板提取的标题模板
通过逻辑匹配将占位符文本替换为收集到的字段值（例如：
```
[Issue Type]
```
→
```
issue-type
```
字段的值，
```
[Short descriptive title]
```
→
```
summary
```
字段的值）

Body

正文

Render the issue body following the structure from the fetched template:

yml templates: Render each field as a
```
### Field Label
```
section with the gathered value. Use
```
no response
```
for empty optional sections. Maintain the exact field order from the template.
md templates: Reconstruct the markdown body with gathered values filled in. Check the appropriate checkboxes, fill in labeled fields, and include all sections.

根据获取到的模板结构渲染Issue正文：

yml模板：将每个字段渲染为
```
### 字段标签
```
章节，内容为收集到的值。对于未填写的可选章节，使用
```
no response
```
。保持模板中的字段顺序不变。
md模板：重构Markdown正文，填入收集到的值。勾选相应的复选框，填充带标签的字段，并包含所有章节。

Labels

Start with
```
config.labels.default
```
Merge in template-level labels (from the fetched template's
```
labels:
```
field) — avoid duplicates
Apply
```
config.labels.conditional
```
rules:
- keyword
  : Check if any keyword appears in the user's request (case-insensitive)
- fieldValue
  : Check if the specified field has the specified value
- fieldTransform
  : Derive a label from a field value using the specified transform (e.g.,
```
lowercase-hyphenate
```
  converts "Document Status" to "document-status")
Apply any additional label logic defined in the template config's
```
notes
```

生成标签集合：

以
```
config.labels.default
```
为基础
合并模板级标签（从获取到的模板的
```
labels:
```
字段）——避免重复
应用
```
config.labels.conditional
```
规则：
- keyword
  ：检查用户请求中是否包含任何关键词（不区分大小写）
- fieldValue
  ：检查指定字段是否具有指定值
- fieldTransform
  ：使用指定的转换规则从字段值生成标签（例如：
```
lowercase-hyphenate
```
  将“Document Status”转换为“document-status”）
应用模板配置的
```
notes
```
中定义的其他标签逻辑

Assignees

经办人

Merge

config.assignees.default

with template-level assignees. If

config.assignees.promptUser

is true, ask the user if they want to assign anyone else.

合并

config.assignees.default

和模板级经办人。如果

config.assignees.promptUser

为true，询问用户是否需要添加其他经办人。

Step 5: Preview & Confirm

步骤5：预览与确认

Present the composed issue to the user for review:

**Title**: [composed title]
**Labels**: label1, label2, label3
**Assignees**: @user1, @user2
**Project**: [project board name] → [status]

**Body**:
[rendered body preview]

Ask for confirmation or edits. If the user requests changes, apply them and re-preview.

将组装好的Issue展示给用户审核：

**标题**：[组装好的标题]
**标签**：label1, label2, label3
**经办人**：@user1, @user2
**项目**：[项目看板名称] → [状态]

**正文**:
[渲染后的正文预览]

请求用户确认或编辑。如果用户要求修改，则应用修改并重新预览。

Step 6: Create Issue

步骤6：创建Issue

Create the issue using the detected GitHub method:

If MCP: Use

issue_write

method: create
owner: <config.repository.owner>
repo: <config.repository.repo>
title: <composed title>
body: <composed body>
labels: <label array>
assignees: <assignee array>

If CLI: Use

gh issue create

bash

gh issue create \
  --repo <config.repository.owner>/<config.repository.repo> \
  --title "<composed title>" \
  --body "<composed body>" \
  --label "<label1>" --label "<label2>" \
  --assignee "<assignee1>" --assignee "<assignee2>"

Pass each label and assignee as a separate
```
--label
```
/
```
--assignee
```
flag

Use a heredoc for the body if it contains special characters:

bash

gh issue create \
  --repo owner/repo \
  --title "Title" \
  --body "$(cat <<'EOF'
<composed body>
EOF
)" \
  --label "label1" --label "label2"

Parse the issue URL from the command output (printed to stdout on success)

使用检测到的GitHub方法创建Issue：

如果使用MCP：使用

issue_write

方法：

method: create
owner: <config.repository.owner>
repo: <config.repository.repo>
title: <组装好的标题>
body: <组装好的正文>
labels: <标签数组>
assignees: <经办人数组>

如果使用CLI：使用

gh issue create

命令：

bash

gh issue create \
  --repo <config.repository.owner>/<config.repository.repo> \
  --title "<组装好的标题>" \
  --body "<组装好的正文>" \
  --label "<label1>" --label "<label2>" \
  --assignee "<assignee1>" --assignee "<assignee2>"

每个标签和经办人都作为单独的
```
--label
```
/
```
--assignee
```
参数传入

如果正文包含特殊字符，使用here-doc格式：

bash

gh issue create \
  --repo owner/repo \
  --title "Title" \
  --body "$(cat <<'EOF'
<组装好的正文>
EOF
)" \
  --label "label1" --label "label2"

从命令输出中解析Issue URL（成功时会打印到标准输出）

Step 7: Post-Creation

步骤7：创建后操作

Extract the issue URL from the creation response:

If MCP: Get the URL from the response payload (e.g.,
```
html_url
```
field)
If CLI: The
```
gh issue create
```
command prints the issue URL to stdout

Always display the issue URL to the user as a clickable link, regardless of whether

config.postCreation

is configured. This is the minimum required output on success.

config.postCreation.displayFormat

is defined, also render it by substituting

{issueNumber}

and

{issueUrl}

with actual values.

Display each item from

config.postCreation.additionalNotes

as a follow-up note.

从创建响应中提取Issue URL：

如果使用MCP：从响应负载中获取URL（例如
```
html_url
```
字段）
如果使用CLI：
```
gh issue create
```
命令会将Issue URL打印到标准输出

无论是否配置
config.postCreation
，都必须向用户显示Issue URL，这是成功时的最低要求输出。

如果定义了

config.postCreation.displayFormat

，则替换

{issueNumber}

和

{issueUrl}

为实际值后进行渲染。

将

config.postCreation.additionalNotes

中的每个条目作为后续说明展示。

Link Formatting Rules

链接格式化规则

When rendering links in the issue body, apply the rules from

config.linkFormatting.rules

in order. For each link:

Check each rule's
```
match
```
description to determine if it applies
Apply the
```
format
```
specified by the matching rule
Use
```
customText
```
as link text if provided

Common patterns:

GitHub issue/PR URLs as list items → raw URL (no markdown wrapping) so GitHub renders title + status
Design links → markdown link with
```
(see design)
```
as text
All other links → standard markdown
```
[descriptive text](url)
```

在Issue正文中渲染链接时，按顺序应用

config.linkFormatting.rules

中的规则。对于每个链接：

检查每个规则的
```
match
```
描述，确定是否适用
应用匹配规则指定的
```
format
```
如果提供了
```
customText
```
，则使用该文本作为链接文本

常见模式：

作为列表项的GitHub Issue/PR URL → 使用原始URL（不使用Markdown包裹），以便GitHub渲染标题+状态
设计链接 → 使用Markdown链接，文本为
```
(see design)
```
所有其他链接 → 使用标准Markdown格式
```
[描述文本](url)
```

Acceptance Criteria

验收标准

When

config.acceptanceCriteria

is defined:

Start with
```
config.acceptanceCriteria.defaultItems
```
as baseline criteria
Ask the user for additional criteria

Render using

config.acceptanceCriteria.formatting.style

(

checklist

- [ ] item

bullets

- item

)

Avoid the prefixes listed in

config.acceptanceCriteria.formatting.avoidPrefixes

当定义了

config.acceptanceCriteria

时：

以
```
config.acceptanceCriteria.defaultItems
```
作为基准标准
向用户询问额外标准

使用

config.acceptanceCriteria.formatting.style

进行渲染（

checklist

- [ ] 条目

bullets

- 条目

）

避免使用

config.acceptanceCriteria.formatting.avoidPrefixes

中列出的前缀

Error Handling

错误处理

Malformed settings.json

格式错误的settings.json

settings.json

exists but fails validation against

references/settings-schema.json

Notify the user that the settings file is invalid
Show the specific validation error
Offer to re-run the Setup Flow to create a new
```
settings.json
```

如果

settings.json

存在但未通过

references/settings-schema.json

的验证：

通知用户设置文件无效
显示具体的验证错误
提供重新运行设置流程以创建新
```
settings.json
```
的选项

GitHub config repo access failure

GitHub配置仓库访问失败

If the configured GitHub repo (for

configStorage.type === "github"

) is inaccessible:

Notify the user that the config repository could not be reached
Suggest checking: repository existence, access permissions, branch name
If using CLI, suggest
```
gh auth status
```
to verify authentication
Offer to switch to local storage mode

如果配置的GitHub仓库（

configStorage.type === "github"

）无法访问：

通知用户无法连接到配置仓库
建议检查：仓库是否存在、访问权限、分支名称
如果使用CLI，建议执行
```
gh auth status
```
验证认证状态
提供切换到本地存储模式的选项

Empty config directory

空配置目录

If the config directory (local or GitHub) exists but contains no

.json

config files:

Notify the user that no template configs were found
Offer to create a first template config

如果配置目录（本地或GitHub）存在但没有

.json

配置文件：

通知用户未找到模板配置文件
提供创建首个模板配置文件的选项

Config write failure (GitHub)

GitHub配置写入失败

If writing a config to GitHub fails:

Notify the user of the failure
Provide context about potential causes: branch protection rules, insufficient permissions, file conflicts
If the error includes a SHA mismatch, suggest re-fetching the file and retrying
Offer to save the config locally as a fallback

如果向GitHub写入配置文件失败：

通知用户操作失败
提供潜在原因的上下文：分支保护规则、权限不足、文件冲突
如果错误包含SHA不匹配，建议重新获取文件并重试
提供将配置文件保存到本地作为备选方案

Template fetch failure

模板获取失败

If the template fetch fails (MCP

get_file_contents

gh api

Notify the user that the template could not be fetched
Suggest checking repository access permissions
If using CLI, suggest running
```
gh auth status
```
to verify authentication
Offer to create the issue manually without template structure

如果模板获取失败（MCP

get_file_contents

或

gh api

）：

通知用户无法获取模板
建议检查仓库访问权限
如果使用CLI，建议执行
```
gh auth status
```
验证认证状态
提供不使用模板结构手动创建Issue的选项

JSON config parse failure

JSON配置解析失败

If a template config file is malformed:

Skip that template during selection
Notify the user which config failed to parse

如果模板配置文件格式错误：

在选择过程中跳过该模板
通知用户哪个配置文件解析失败

Issue creation failure

Issue创建失败

If issue creation fails (MCP

issue_write

gh issue create

Stop the operation immediately
Notify the user of the failure
Provide context about potential causes: authentication token issues, permissions, rate limits, invalid repository access
If using CLI, include the stderr output from the
```
gh
```
command for diagnostics
Offer to display the composed issue body so the user can create it manually

如果Issue创建失败（MCP

issue_write

或

gh issue create

）：

立即停止操作
通知用户操作失败
提供潜在原因的上下文：认证令牌问题、权限、速率限制、仓库访问无效
如果使用CLI，包含
```
gh
```
命令的标准错误输出以用于诊断
提供展示组装好的Issue正文的选项，让用户手动创建

Adding a New Template

添加新模板

To add support for a new issue type, create a new

.json

config file following the schema in

references/schema.json

. The save location depends on the storage mode configured in

settings.json

要支持新的Issue类型，请按照

references/schema.json

中的Schema创建新的

.json

配置文件。保存位置取决于

settings.json

中配置的存储模式：

Local storage (

configStorage.type === "local"

)

本地存储（

configStorage.type === "local"

）

Create a new

.json

file in

~/.claude/configs/github-issue-from-templates/

Follow the schema defined in
```
references/schema.json
```
Set
```
repository.owner
```
and
```
repository.repo
```
to the target GitHub repository
Set
```
templateSource.path
```
to the repo-relative path of the GitHub issue template
Set
```
templateSource.format
```
to
```
yml
```
or
```
md
```
based on the template type
Define
```
triggers.keywords
```
for automatic template matching
Add any
```
fieldDefaults
```
,
```
fieldSkipConditions
```
, label rules, and formatting overrides
No changes to this SKILL.md file are needed

在

~/.claude/configs/github-issue-from-templates/

中创建新的

.json

文件

遵循
```
references/schema.json
```
中定义的Schema
将
```
repository.owner
```
和
```
repository.repo
```
设置为目标GitHub仓库
将
```
templateSource.path
```
设置为GitHub Issue模板在仓库中的相对路径
根据模板类型将
```
templateSource.format
```
设置为
```
yml
```
或
```
md
```
定义
```
triggers.keywords
```
以实现自动模板匹配
添加任何
```
fieldDefaults
```
、
```
fieldSkipConditions
```
、标签规则和格式化覆盖
无需修改本SKILL.md文件

GitHub storage (

configStorage.type === "github"

)

GitHub存储（

configStorage.type === "github"

）

Compose the config JSON following
```
references/schema.json
```

Commit the file to the configured repo:

If MCP: Use

create_or_update_file

owner:   <configStorage.owner>
repo:    <configStorage.repo>
path:    <configStorage.path>/<filename>.json
content: <base64-encoded JSON>
message: "Add <template-name> template config"
branch:  <configStorage.branch>

If CLI: Use the GitHub contents API:

bash

gh api repos/<owner>/<repo>/contents/<path>/<filename>.json \
  --method PUT \
  --field message="Add <template-name> template config" \
  --field branch=<branch> \
  --field content=$(echo '<JSON content>' | base64)

No changes to this SKILL.md file are needed

遵循
```
references/schema.json
```
编写配置JSON

将文件提交到配置仓库：

如果使用MCP：使用

create_or_update_file

方法：

owner:   <configStorage.owner>
repo:    <configStorage.repo>
path:    <configStorage.path>/<filename>.json
content: <base64编码的JSON>
message: "Add <template-name> template config"
branch:  <configStorage.branch>

如果使用CLI：使用GitHub内容API：

bash

gh api repos/<owner>/<repo>/contents/<path>/<filename>.json \
  --method PUT \
  --field message="Add <template-name> template config" \
  --field branch=<branch> \
  --field content=$(echo '<JSON content>' | base64)

无需修改本SKILL.md文件

Updating an Existing Template Config

更新现有模板配置

Local storage

本地存储

Read, edit, and overwrite the

.json

file in

~/.claude/configs/github-issue-from-templates/

directly.

直接读取、编辑并覆盖

~/.claude/configs/github-issue-from-templates/

中的

.json

文件。

GitHub storage

GitHub存储

Updating a file via the GitHub contents API requires the current file's SHA. Follow these steps:

Fetch the current file to get its SHA:

If MCP: Use

get_file_contents

— the response includes the

sha

field.

If CLI:

bash

gh api repos/<owner>/<repo>/contents/<path>/<filename>.json?ref=<branch> --jq '.sha'

Update the file with the SHA included:

If MCP: Use

create_or_update_file

with the

sha

parameter:

owner:   <configStorage.owner>
repo:    <configStorage.repo>
path:    <configStorage.path>/<filename>.json
content: <base64-encoded updated JSON>
message: "Update <template-name> template config"
branch:  <configStorage.branch>
sha:     <current SHA>

If CLI:

bash

gh api repos/<owner>/<repo>/contents/<path>/<filename>.json \
  --method PUT \
  --field message="Update <template-name> template config" \
  --field branch=<branch> \
  --field content=$(echo '<updated JSON>' | base64) \
  --field sha=<current SHA>

通过GitHub内容API更新文件需要当前文件的SHA。请按照以下步骤操作：

获取当前文件以获取其SHA：
如果使用MCP：使用
```
get_file_contents
```
方法——响应包含
```
sha
```
字段。
如果使用CLI：
bash
```
gh api repos/<owner>/<repo>/contents/<path>/<filename>.json?ref=<branch> --jq '.sha'
```

更新文件，包含SHA参数：

如果使用MCP：使用

create_or_update_file

方法，传入

sha

参数：

owner:   <configStorage.owner>
repo:    <configStorage.repo>
path:    <configStorage.path>/<filename>.json
content: <base64编码的更新后的JSON>
message: "Update <template-name> template config"
branch:  <configStorage.branch>
sha:     <当前SHA>

如果使用CLI：

bash

gh api repos/<owner>/<repo>/contents/<path>/<filename>.json \
  --method PUT \
  --field message="Update <template-name> template config" \
  --field branch=<branch> \
  --field content=$(echo '<更新后的JSON>' | base64) \
  --field sha=<当前SHA>

Section Formatting Conventions

章节格式约定

Use
```
no response
```
for any section where no information was provided — never omit sections
Include all template sections in the exact order they appear in the fetched template
Use bullet points for lists
Use proper markdown formatting
Label names: lowercase with hyphens (e.g.,
```
document-status
```
,
```
bmt-team-2
```
)

对于未提供信息的章节，使用
```
no response
```
——切勿省略章节
按照获取到的模板中的顺序包含所有模板章节
使用项目符号列表
使用正确的Markdown格式
标签名称：小写，使用连字符分隔（例如：
```
document-status
```
,
```
bmt-team-2
```
）

github-issue-from-templates

Original

Translation

GitHub Issue Creation — Data-Driven Workflow Engine

GitHub Issue 创建——数据驱动的工作流引擎

File Structure

文件结构

Tool Detection

工具检测

Workflow

工作流

Step 0: Settings & Storage Resolution

步骤0：设置与存储解析

Setup Flow (First Run)

设置流程（首次运行）

Switching Storage Modes

切换存储模式

Step 1: Template Selection

步骤1：模板选择

Loading Configs from GitHub

从GitHub加载配置文件

Listing files in the config directory

列出配置目录中的文件

Fetching individual config files

获取单个配置文件

Step 2: Fetch Template from GitHub

步骤2：从GitHub获取模板

Format: yml (Form-based templates)

格式：yml（基于表单的模板）

Format: md (Frontmatter + markdown templates)

格式：md（Frontmatter + Markdown模板）

Step 3: Gather Information

步骤3：收集信息

Step 4: Compose Issue

步骤4：组装Issue

Title

标题

Body

正文

Labels

标签

Assignees

经办人

Step 5: Preview & Confirm

步骤5：预览与确认

Step 6: Create Issue

步骤6：创建Issue

Step 7: Post-Creation

步骤7：创建后操作

Link Formatting Rules

链接格式化规则

Acceptance Criteria

验收标准

Error Handling

错误处理

Malformed settings.json

格式错误的settings.json

GitHub config repo access failure

GitHub配置仓库访问失败

Empty config directory

空配置目录

Config write failure (GitHub)

GitHub配置写入失败

Template fetch failure

模板获取失败

JSON config parse failure

JSON配置解析失败

Issue creation failure

Issue创建失败

Adding a New Template

添加新模板

Local storage (configStorage.type === "local")

本地存储（configStorage.type === "local"）

GitHub storage (configStorage.type === "github")

GitHub存储（configStorage.type === "github"）

Updating an Existing Template Config

更新现有模板配置

Local storage

本地存储

GitHub storage

Format:
`yml`
(Form-based templates)

格式：
`yml`
（基于表单的模板）

Format:
`md`
(Frontmatter + markdown templates)

格式：
`md`
（Frontmatter + Markdown模板）

Local storage (
`configStorage.type === "local"`
)

本地存储（
`configStorage.type === "local"`
）

GitHub storage (
`configStorage.type === "github"`
)

GitHub存储（
`configStorage.type === "github"`
）