nxs-gh-create-epic
从Epic文档创建GitHub问题。当用户想要从epic.md文件创建GitHub问题、同步Epic到GitHub或链接Epic文档到GitHub问题时使用。技能从YAML前置元数据中提取Epic标题和类型,通过`gh issue create`创建问题,并更新前置元数据以包含问题链接。
📖 中文导读:从Epic文档创建GitHub问题。当用户想要从epic.md文件创建GitHub问题、同步Epic到GitHub或链接Epic文档到GitHub问题时使用。技能从YAML前置元数据中提取Epic标题和类型,通过`gh issue create`创建问题,并更新前置元数据以包含问题链接。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: nxs-gh-create-epic
description: Create a GitHub issue from an Epic document. Use when the user wants to create a GitHub issue from an epic.md file, sync an epic to GitHub, or link an epic document to a GitHub issue. The skill extracts the epic title and type from YAML frontmatter, creates an issue via gh issue create, and updates the frontmatter with the issue link.
GitHub Epic Issue Creator
Create a GitHub issue from an Epic document's content and link it back to the epic.
Prerequisites
- GitHub CLI (
gh) installed and authenticated - Running within a git repository connected to GitHub
Workflow
- Locate the Epic document from user reference, open file, or argument
- Run the script to create the issue and update frontmatter:
python ./scripts/nxs_gh_create_epic.py "<path-to-epic.md>"
Optional Flags
| Flag | Description |
|---|---|
--project "<name>" |
Specify the GitHub project to add the issue to (e.g., my-org/my-project). If omitted, auto-discovers from repository. |
-y, --yes |
Skip confirmation if a link already exists |
--no-project |
Skip adding the issue to any project |
Examples
# Basic usage (auto-discovers project from repo)
python ./scripts/nxs_gh_create_epic.py "<path-to-epic.md>"
# Specify target project explicitly
python ./scripts/nxs_gh_create_epic.py --project "acme-corp/backend-roadmap" "<path-to-epic.md>"
# Skip confirmation for existing links
python ./scripts/nxs_gh_create_epic.py -y "<path-to-epic.md>"
# Create issue without adding to any project
python ./scripts/nxs_gh_create_epic.py --no-project "<path-to-epic.md>"
Script Behavior
The script (./scripts/nxs_gh_create_epic.py):
- Parses YAML frontmatter for
epic(title) andtype(label, defaults to "epic") - Creates temp file with markdown body (frontmatter stripped)
- Executes
gh issue create --title "<epic>" --label "<type>" --body-file <temp> - Extracts issue number from returned URL
- Adds the issue to the specified project (or auto-discovered project)
- Updates frontmatter with
link: "#<issue-number>" - Cleans up temp file
Expected Frontmatter
---
feature: "Feature Name"
epic: "Epic Title" # Required - becomes issue title
created: 2025-01-02
status: draft
type: enhancement # Optional - becomes GitHub label (default: "epic")
---
After execution, link: "#123" is added to frontmatter.
Error Handling
| Error | Resolution |
|---|---|
gh: command not found |
Install GitHub CLI: https://cli.github.com |
gh: not logged in |
Run gh auth login |
label does not exist |
Create label in GitHub or use existing label |
not a git repository |
Navigate to project root |
No 'epic' field found |
Add epic: "Title" to frontmatter |
Project not found |
Verify project name or use --no-project |