manage-issue

name	manage-issue
description	Read, create, close, comment, resolve, or list GitHub issues with optional sub-issue attachment
user-invocable	false
model	sonnet
allowed-tools	Bash, Read

manage-issue

Model-invocable skill for managing GitHub issues.

Purpose

Read existing issues, create new ones, close issues, post comments, or resolve an issue reference (find existing or create new). Supports attaching issues as sub-issues to a parent.

You DO the issue operations. You do NOT make decisions about what to do with the results.

Input

Receive from agent:

• action — read | create | close | comment | resolve_or_create | list
• issue_number — (required for read, close, and comment, optional for resolve_or_create)
• body — (required for comment) The comment body to post to the issue
• description — (required for create, optional for resolve_or_create)
• parent_issue_number — (optional) If provided, attach created/resolved issue as sub-issue
• platform — github (from config)
• labels — (optional) Comma-separated labels to apply on create
• reason — (optional, close only) Close reason: completed (default) or not_planned
• comment — (optional, close only) Comment to add when closing the issue
• filters — (optional, list only) Object with optional fields:
  • state — default: open
  • assignee — default: none (unassigned issues only)
  • labels — default: ["enhancement", "no-label"] (enhancement label OR no label)
  • sort — default: updated_desc
  • limit — default: 5 (maximum: 5)

Process

Action: read

Invoke the platform-adapter skill with verb: view-issue and args: {issue_number: {issue_number}}.

Parse and return structured output.

Action: create

1. Load template from: ~/.garura/core/memory/standards/templates/github-issue.md
2. Construct issue body from description using template format
3. Invoke the platform-adapter skill with verb: create-issue and args: {title: {title}, body: {body}, labels: {labels}, assignee: "@me"}.
4. If parent_issue_number is provided, attach as sub-issue (see Sub-Issue Attachment below)

Action: list

Return a filtered, sorted list of open issues for candidate selection. GitHub's CLI does not support label:X OR no:label in a single query, so this action runs two separate queries and merges the results.

Step 1 — Query labeled candidates:

Invoke the platform-adapter skill with verb: list-issues and args: {state: "open", query: "no:assignee label:enhancement", limit: 10}.

Step 2 — Query unlabeled candidates:

Invoke the platform-adapter skill with verb: list-issues and args: {state: "open", query: "no:assignee no:label", limit: 10}.

Step 3 — Merge and sort:

1. Combine both result sets
2. Deduplicate by number (keep one entry per issue)
3. Sort by updatedAt descending
4. Take the top limit entries (default: 5, hard cap: 5)

Apply any caller-provided overrides to state, assignee, labels, sort, or limit before running the queries. When limit exceeds 5, cap it at 5 silently.

Output (written to the calling agent's designated STM path):

candidates:
  - number: 42
    title: "Add OAuth login"
    updated_at: "2026-04-28T10:30:00Z"
    labels: ["enhancement"]
    state: "open"
  - number: 37
    title: "Improve error messages"
    updated_at: "2026-04-25T08:15:00Z"
    labels: []
    state: "open"
candidate_count: 2
query_filters:
  state: open
  assignee: none
  labels: [enhancement, no-label]
  sort: updated_desc
  limit: 5

If both queries return zero results, candidate_count is 0 and candidates is an empty list.

---

Action: resolve_or_create

1. If issue_number is provided → perform read action
2. If only description is provided: a. Search for matching issues: Invoke the platform-adapter skill with verb: list-issues and args: {state: "open", query: "{description}", limit: 5}. b. If a matching open issue is found → return it c. If no match → perform create action
3. If parent_issue_number is provided, attach as sub-issue after resolve/create

Action: comment

1. Invoke the platform-adapter skill with verb: view-issue and args: {issue_number: {issue_number}} to verify the issue exists and is open.
2. If issue does not exist or is closed → return output with commented: false and reason.
3. Invoke the platform-adapter skill with verb: comment-issue and args: {issue_number: {issue_number}, body: {body}}.
4. Return output with commented: true and the comment URL.

Action: close

1. Invoke the platform-adapter skill with verb: view-issue and args: {issue_number: {issue_number}} to verify the issue exists and is open.
2. If issue is already closed → return output with closed: false (no action taken)
3. Invoke the platform-adapter skill with verb: close-issue and args: {issue_number: {issue_number}, reason: {reason}, comment: {comment}}. Pass comment only when provided. Note: on GitLab, the reason argument is silently ignored by the adapter.
4. Invoke the platform-adapter skill with verb: view-issue and args: {issue_number: {issue_number}} to verify closure.
5. Return output with closed: true

Sub-Issue Attachment

When parent_issue_number is provided and an issue is created or resolved:

Invoke the platform-adapter skill with verb: attach-sub-issue and args: {child_number: {child_number}, parent_number: {parent_number}}.

Important: On GitHub, the adapter uses the issue's internal numeric id (not the visible issue number) for the sub-issue attachment. On GitLab, parent/child hierarchy is not supported — the adapter falls back to a related-issues link, which creates a peer "relates to" link only. See memory/tools/gitlab/adapter.md for caveats.

Output

Produce output using template: templates/issue-output.md

IMPORTANT: This skill produces operation results. The calling agent receives this output and decides what to do next. Do NOT instruct the agent to return or stop.

Reference

Platform-specific CLI and API reference: reference/github-issue.md (GitHub). This file is retained as a delegation pointer — the executable command translations now live in core/components/skills/platform-adapter/reference/{platform}/verbs.md. Do NOT add a gitlab-issue.md sibling here; GitLab translations are in the adapter's reference layer.

Constraints

• NEVER delete issues
• NEVER close issues unless action is explicitly close
• NEVER modify issue state unless explicitly requested in the action
• NEVER assign to anyone other than @me on create
• ALWAYS route all issue operations through the platform-adapter skill — never call gh or glab directly
• ALWAYS verify issue exists after creation

Version

Field	Value
Version	1.2.0
Category	operations