Agent Skills
› kinncj/Heimdall
› gh-issues
gh-issues
GitHub自动化管理GitHub Issue全生命周期，支持创建、查看、编辑标签与指派、评论及关闭。通过CLI操作关联故事制品，自动记录阶段状态与TDD结果，实现无干预的故事流转管理。
Trigger Scenarios
需要创建或更新GitHub Issue以追踪故事进展时
在故事不同阶段（如发现、架构、实现）需要标记状态并通知相关人员时
遇到测试失败或阻塞情况需要记录日志并请求人工介入时
Install
npx skills add kinncj/Heimdall --skill gh-issues -g -y
SKILL.md
Frontmatter
{
"name": "gh-issues",
"description": "Create, read, update, and link GitHub Issues as story artifacts throughout the story lifecycle. Use when managing issues for stories."
}
SKILL: gh-issues
Purpose
Create, read, update, and link GitHub Issues as first-class story artifacts. Agents use this skill to manage issue lifecycle — from PO story creation through QA closure — without human intervention.
Inputs
| Field | Source | Example |
|---|---|---|
title |
story frontmatter | "User can reset password" |
body_file |
story file path | docs/stories/auth-reset-0001.md |
labels |
story frontmatter + phase | "type:feature,priority:high,phase:discover" |
milestone |
project.config.yaml |
"v1.0" |
assignee |
orchestrator context | "@me" |
issue_number |
previously created issue | 42 |
Outputs
| Field | Description |
|---|---|
issue_number |
integer, use for all subsequent operations |
issue_url |
full GitHub URL for logging |
issue_node_id |
GraphQL node ID, needed for Projects v2 card add |
Create an Issue
# Capture issue number and URL
RESULT=$(gh issue create \
--title "{title}" \
--body-file "{body_file}" \
--label "{labels}" \
--milestone "{milestone}" \
--json number,url,id)
ISSUE_NUMBER=$(echo "$RESULT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['number'])")
ISSUE_URL=$(echo "$RESULT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['url'])")
ISSUE_NODE=$(echo "$RESULT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['id'])")
View an Issue
gh issue view {issue_number} --json number,title,state,labels,body
Edit Labels and Assignee
# Add label, remove old phase label
gh issue edit {issue_number} \
--add-label "phase:architect" \
--remove-label "phase:discover"
# Assign to current actor
gh issue edit {issue_number} --add-assignee "@me"
Add a Comment
gh issue comment {issue_number} \
--body "{message}"
Comment conventions by role:
| Event | Template |
|---|---|
| Phase start | "Phase {N} {PHASE_NAME}: starting. Artifact target: {path}" |
| Phase complete | "Phase {N} {PHASE_NAME}: complete. Artifacts: {path}" |
| TDD red | "RED: Failing test at {test_path} — {failure_message}" |
| TDD green | "GREEN: {test_count} tests passing." |
| Blocked | "BLOCKED: {agent} failed 3x on {task}. Human intervention required." |
Close an Issue
# Close with final validation summary
gh issue close {issue_number} \
--comment "All acceptance criteria passing. Validation: {summary}"
List Issues
# All open issues for current phase
gh issue list --label "phase:implement" --state open --json number,title,labels
# Blocked issues
gh issue list --label "blocked" --state open
Link Issues (parent / blocks)
GitHub Issues has no native parent field — use body references and labels:
# In the child issue body, add:
# "Closes #{parent_number}" → auto-closes parent when child closes
# "Part of #{epic_issue_number}"
# For blocking relationships, comment on the blocked issue:
gh issue comment {blocked_number} \
--body "Blocked by #{blocker_number} — {reason}"
gh issue edit {blocked_number} --add-label "blocked"
Failure Modes
| Condition | Action |
|---|---|
gh not authenticated |
Stop. Output: gh auth login required. Do not retry. |
| Issue already exists with same title | Check with gh issue list --search "{title}" --state all. Skip create if found; return existing number. |
| Label does not exist | Create label first via gh label create. See gh-labels-milestones skill. |
| Milestone not found | Create milestone first: gh api repos/{owner}/{repo}/milestones -f title="{name}". |
| Rate limit hit | Wait 60 seconds, retry once. If second attempt fails, stop and log. |
Logging
Always log after every gh issue mutation:
[gh-issues] CREATE #42 "User can reset password" labels=[type:feature,priority:high]
[gh-issues] COMMENT #42 phase:implement start
[gh-issues] CLOSE #42 all criteria passing
Format: [gh-issues] {ACTION} #{number} {description}
Version History
- f4ea31f Current 2026-07-05 10:40
