企业官网建设流程全解析

Kibana gh-create-issue 技能：用 AI 编码助手规范化创建 GitHub Issue 的完整流程

【免费下载链接】kibanaYour window into all of your data项目地址: https://gitcode.com/GitHub_Trending/ki/kibana

Kibana 仓库在.agents/skills/gh-create-issue/SKILL.md中定义了一个名为gh-create-issue的 Agent 技能：它接收用户对功能需求或缺陷的非结构化口语描述，将其分类为 bug report 或 feature request，按 Kibana 官方 Issue 模板逐字段补全，以“一次只问一个问题”的方式访谈用户补齐薄弱字段，并通过 GitHub CLI 校验标签、提交 Issue。读完本文，你将掌握该技能的 9 步工作流、两份 Issue 模板的字段语义、标签校验命令与提交命令的用法，以及配套的边界保护机制。

技能定位与调用方式

该技能的 Front Matter 定义了三个关键属性：

• name: gh-create-issue：技能名，用户在 Claude Code、Cursor 等编码助手中通过/gh-create-issue显式触发；
• description：一句话说明职责——收集非结构化描述、分类、填充 Kibana 模板、访谈补强、最终通过 GitHub CLI 提交；
• disable-model-invocation: true：禁止模型在对话中隐式自动调用该技能，必须由用户主动发起。

这一点在.agents/skills/gh-create-issue/agents/openai.yaml中有对应配置：policy.allow_implicit_invocation: false。两处声明一致，意味着该技能是“用户驱动”的——它涉及向远程仓库写入内容（创建 Issue），因此被设计为只能在用户明确指令下运行。

适用前提：本地已安装并登录gh（GitHub CLI），且账号对elastic/kibana仓库有创建 Issue 的权限；技能中的命令均通过--repo elastic/kibana显式指定目标仓库，因此不要求本地 clone 在该远程下。

全流程总览：九个步骤

技能的主体是一个严格串行的 9 步流程，其中 4 个步骤（Step 1、Step 6、Step 7、Step 8）被显式要求“结束回复并等待用户输入”，这保证了 Agent 不会在未确认的情况下越过用户直接提交。

1. 收集非结构化描述（Step 1）
2. 分类 Issue 类型（Step 2）
3. 读取对应模板（Step 3）
4. 基于描述草拟正文（Step 4）
5. 生成标题（Step 5）
6. 访谈用户补齐弱字段（Step 6）
7. 收集并校验标签（Step 7）
8. 展示草稿并确认（Step 8）
9. 创建 Issue（Step 9）

Step 1–2：收集描述与分类

Step 1要求 Agent 请用户用自己的话描述功能需求或 Bug，不要求任何结构，并给出示例提示语：

Describe the feature you'd like or the bug you've found in your own words. Don't worry about structure — just tell me what you're thinking and I'll help shape it.

发出提问后必须结束回复、等待用户输入，禁止自行假设内容继续推进。

Step 2依据描述中的语言特征做二分类：

若描述模棱两可，必须先询问用户属于哪一类，再继续后续步骤。这个关键词表与配套的gh-enhance-issue技能中用于“从已有 Issue 的标题和正文推断类型”的规则完全一致，说明 Kibana 对 Issue 类型的判定标准在两个技能间保持统一。

Step 3：读取对应的 Issue 模板

分类结果决定模板文件：

• Bug report→ 读取.github/ISSUE_TEMPLATE/Bug_report.md
• Feature request→ 读取.github/ISSUE_TEMPLATE/Feature_request.yml

Bug 报告模板（Markdown）

Bug_report.md的 YAML 头声明labels: bug——即通过该模板创建的 Issue 会自动带上bug标签。正文包含以下待填字段：

• Kibana version/Elasticsearch version：环境版本
• Server OS version/Browser version/Browser OS version：服务端与浏览器环境
• Original install method：原始安装方式（如 download page、yum、from source）
• Describe the bug/Steps to reproduce（预置 1/2/3 编号列表）/Expected behavior
• Screenshots (if relevant)/Errors in browser console (if relevant)/Provide logs and/or server output (if relevant)/Any additional context

功能需求模板（YAML Form）

Feature_request.yml采用 GitHub 的 YAML Issue Form 格式，字段结构与技能 Step 4 的推断规则一一对应：

值得注意：该模板开头有一段 markdown 提示，直接引导用户“在编码助手中使用/gh-create-issue技能，它会访谈你并替你提交 Issue”——即模板本身为这个 Agent 技能做了流量入口。

此外，.github/ISSUE_TEMPLATE/config.yml中blank_issues_enabled: true且提供了一条指向 Discuss 论坛的contact_links，说明仓库同时保留了无模板提问通道，而gh-create-issue技能服务的是结构化提交场景。

Step 4–5：先草拟，再定标题

Step 4的核心原则是“先有草稿，再提问”。Agent 以用户描述为素材，尽可能填充模板字段，并做合理推断：

• 对feature request：综合出清晰的“What feature do you want added?”陈述（如能从描述中看出范围外内容则注明）；从用例中推导“Why?”（包括用户当前的变通方式和目标用户）；根据描述的行为草拟初版 Acceptance Criteria（happy path + 边界情形）；如有线索则推断 Priority；记录阻塞项到 Blocked By。
• 对bug report：抽取复现步骤、预期与实际行为、提及的环境细节。

描述没有依据的字段保持留空；此阶段禁止提问，先把草稿做出来。

Step 5要求草拟一个简洁、描述性、不超过 72 字符的标题，能体现核心诉求或 Bug 本质；如能明确所属领域，则加前缀，例如[Discover]、[Maps]、[Alerting]。

Step 6：逐字段访谈补齐弱项

Step 6是技能中约束最细的步骤。Agent 审查草稿，找出空字段、含糊不可验证的字段（尤其是 Acceptance Criteria）、缺必填信息的字段，然后每次只问一个问题，问完立即结束回复等用户回答，再进入下一个字段。具体规则：

• 必填字段（Describe the bug、Steps to reproduce、Expected behavior、What feature do you want added?、Why?）：缺失或薄弱时必须追问。
• Acceptance Criteria：若草稿过于含糊（如“should work correctly”），要求用户改写成具体、可测试的条目。
• 可选字段（screenshots、logs、browser console errors、additional context、Priority）：只问一次，接受“N/A”或“none”后立即推进。
• 一次追问后答案仍然含糊时，允许再做一次针对性澄清，然后继续。

对feature request，技能还额外要求检查四类常见缺口（即使字段非空也要确认草稿覆盖了）：

• 范围边界：是否明确“不做什么”？功能若可被宽泛解读，须问清范围外内容；
• 当前 workaround：用户今天如何绕开该缺失？“Why?”中未描述变通方式时要追问；
• 目标用户：谁会使用？什么角色或 persona？未说明要问；
• 依赖：是否有必须先行落地的 Issue、功能或基础设施改动？有则写入 Blocked By。

这套追问维度与Feature_request.yml中why、acceptance-criteria、blocked-by字段的 description 引导语互为印证：模板定义了“问什么”，技能定义了“何时问、问几次”。

Step 7：标签收集与并行校验

Step 8 之前，Agent 先向用户收集两类标签：

• 团队标签（如Team:Visualizations）与附加标签（如accessibility、performance），两者都可回答“none”；
• 类型标签（bug或enhancement）由流程自动附加，无需用户提供。

收集后必须等待用户回复，然后将所有标签并行对仓库做存在性校验：

gh label list --repo elastic/kibana --search "<label>" --limit 10 --json name,description --jq '.[] | "- `\(.name)` — \(.description // "no description")"'

该命令通过gh label list的--search模糊检索每个标签，输出其名称与描述。校验结果的三种处理路径：

• 精确匹配→ 直接保留；
• 只有近似匹配→ 以`<name>` — <description>形式列出候选，让用户选择或跳过；
• 无匹配→ 告知用户，请求跳过或提供替代标签。

任何需要用户输入的标签都要等待回复并重新校验新标签，循环直到全部标签都解析成功。这一步的价值在于：gh issue create传入不存在的标签会直接报错，提前校验可以避免最后一步失败。

Step 8–9：确认预览与提交

Step 8要求按固定格式展示完整预览：

Title:<title>Labels:<label1>,<label2>, ...

---

<issue body>

然后请用户确认或提出修改，并在得到明确确认之前结束回复、不提交。

Step 9在确认后执行创建命令：

gh issue create --repo elastic/kibana \ --title "<TITLE>" \ --label "<label1>" --label "<label2>" --label "<labelN>" \ --body "$(cat <<'EOF' <formatted body here> EOF )"

要点：

• 每个标签对应一个独立的--label标志；
• 标签必须同时包含类型标签（bug或enhancement）与全部已校验标签；
• 正文通过带引号定界符的 heredoc（<<'EOF'）传入，避免正文中的引号、反引号等 shell 特殊字符破坏命令；
• 完成后向用户报告新 Issue 的 URL。

配套的gh-enhance-issue技能在更新已有 Issue 时采用了同样的 heredoc 变量传递方式（NEW_BODY=$(cat <<'EOF' ... EOF)+gh issue edit），两处写法一致，是 Kibana Agent 技能对 GitHub CLI 操作的统一约定。

配套边界保护：技能文件不可被技能自身改写

从源码结构看，Kibana 为这类“可写入远程仓库”的技能设置了非 LLM 的硬性护栏。.agents/hooks/guard-skill-boundaries.mjs是一个供 Claude Code 与 Cursor 共用的 hook 分析器，其注释明确了两个强制面：

1. 凭据读取拦截：拒绝 Agent 通过 Read/Bash 访问~/.netrc、~/.aws、~/.ssh、~/.claude、~/.config/gh（GitHub CLI 的认证令牌所在）以及任意.env文件——这直接保护了gh命令所需的认证凭据，即使模型未能识别提示注入也无法泄取；
2. 技能文件写保护：拒绝 Agent 对任何技能的SKILL.md及references/目录的 Write/Edit 操作，防止恶意指令跨会话污染技能上下文。

该 hook 被标注为 fails-open（自身出错时放行）的纵深防御，配合disable-model-invocation: true与allow_implicit_invocation: false的显式调用约束，构成gh-create-issue这类外部写入型技能的完整安全设计：只能人发起、不能改自己、不能读凭据。

小结与可复用要点

gh-create-issue技能本质上把 Kibana 的 Issue 模板（Bug_report.md、Feature_request.yml）翻译成了 Agent 可执行的访谈剧本，可复用的设计模式包括：

• 模板即字段契约：技能 Step 4/6 的推断与追问维度不是凭空写的，而是逐字段映射模板的label/description/validations，修改模板时技能应同步更新；
• “先草稿、后提问、每次一问”：避免 Agent 一次抛出问卷或未经确认就写操作；
• 写前校验：标签在提交前用gh label list --search对仓库做存在性验证；
• 确认门：每个对外副作用（创建 Issue）前都有“结束回复并等待明确确认”的强制点；
• 显式调用 + 边界 hook：外部写入型技能禁用隐式触发，并以非 LLM hook 保护凭据与技能文件。

完整定义见.agents/skills/gh-create-issue/SKILL.md，相关改写已有 Issue 的流程见.agents/skills/gh-enhance-issue/SKILL.md。

【免费下载链接】kibanaYour window into all of your data项目地址: https://gitcode.com/GitHub_Trending/ki/kibana