ark-issues

name	ark-issues
description	Search, list, view, and update existing GitHub issues. Primary use case is CVE tracking and security vulnerability issue management. Used by the ark-security-patcher agent. For drafting NEW issues with research and task breakdowns, use the "issue-creation" skill instead.

Ark Issues

Manage GitHub issues for the Ark project (mckinsey/agents-at-scale-ark).

When to use this skill

Use this skill when:

• Searching for existing issues by keyword or CVE number
• Finding issues related to security vulnerabilities
• Creating new issues to track bugs or features
• Viewing issue details and status
• Listing open or closed issues

Note: This skill is commonly used by the ark-security-patcher agent to:

1. Search for existing CVE-related issues before starting work
2. Link PRs to existing issues with "Closes #N" syntax
3. Create new issues for tracking discovered vulnerabilities

GitHub CLI Commands

Use the gh CLI tool for all issue operations:

Searching Issues

# Search issues by keyword
gh search issues --repo mckinsey/agents-at-scale-ark "CVE"

# Search for specific CVE numbers
gh search issues --repo mckinsey/agents-at-scale-ark "CVE-2025-55183"

# Search with filters
gh search issues --repo mckinsey/agents-at-scale-ark "security" --state open
gh search issues --repo mckinsey/agents-at-scale-ark "vulnerability" --label security

Listing Issues

# List all open issues
gh issue list --repo mckinsey/agents-at-scale-ark

# List issues with filters
gh issue list --repo mckinsey/agents-at-scale-ark --state open
gh issue list --repo mckinsey/agents-at-scale-ark --label bug
gh issue list --repo mckinsey/agents-at-scale-ark --assignee @me

# List with custom fields
gh issue list --repo mckinsey/agents-at-scale-ark --json number,title,state,labels

Viewing Issue Details

# View specific issue
gh issue view 123 --repo mckinsey/agents-at-scale-ark

# View with comments
gh issue view 123 --repo mckinsey/agents-at-scale-ark --comments

# View as JSON for parsing
gh issue view 123 --repo mckinsey/agents-at-scale-ark --json number,title,body,state,labels

Creating Issues

# Create issue interactively
gh issue create --repo mckinsey/agents-at-scale-ark

# Create with title and body
gh issue create --repo mckinsey/agents-at-scale-ark \
  --title "Security: Fix CVE-2025-XXXXX" \
  --body "Description of the vulnerability..."

# Create with labels
gh issue create --repo mckinsey/agents-at-scale-ark \
  --title "Bug: API endpoint fails" \
  --body "Steps to reproduce..." \
  --label bug,priority:high

Updating Issues

# Close an issue
gh issue close 123 --repo mckinsey/agents-at-scale-ark

# Reopen an issue
gh issue reopen 123 --repo mckinsey/agents-at-scale-ark

# Add comment
gh issue comment 123 --repo mckinsey/agents-at-scale-ark \
  --body "Fixed in PR #456"

# Edit issue
gh issue edit 123 --repo mckinsey/agents-at-scale-ark \
  --title "New title" \
  --add-label security

Common Workflows

Workflow 1: Check for Existing CVE Issues

Before creating a new security fix, check if an issue already exists:

# Search for CVE number
gh search issues --repo mckinsey/agents-at-scale-ark "CVE-2025-55183"

# If found, note the issue number
# If not found, you may want to create one

Tip: When creating PRs, reference the issue number using Closes #123 in the PR body to automatically close the issue when the PR merges.

Workflow 2: Find All Security-Related Issues

# Search by keyword
gh search issues --repo mckinsey/agents-at-scale-ark "security OR vulnerability OR CVE"

# Filter by label if security labels exist
gh issue list --repo mckinsey/agents-at-scale-ark --label security

Workflow 3: Create Security Issue for Tracking

gh issue create --repo mckinsey/agents-at-scale-ark \
  --title "fix: CVE-2025-XXXXX in [component]" \
  --body "$(cat <<'EOF'
## Vulnerability Details
- **CVE**: CVE-2025-XXXXX
- **Severity**: High
- **Component**: [package name]

## Description
[What the vulnerability is]

## Impact on Ark
[How it affects Ark]

## Proposed Fix
[Update package to version X.Y.Z]

## References
- CVE: https://cve.circl.lu/cve/CVE-2025-XXXXX
- Advisory: [URL]
EOF
)" \
  --label security

Best Practices

Before Creating Issues

1. Always search first: Check if a similar issue already exists

   gh search issues --repo mckinsey/agents-at-scale-ark "keyword"
   

2. Be specific: Use clear, descriptive titles

   • Good: "fix: CVE-2025-55183 in Next.js affects dashboard"
   • Bad: "security issue"

3. Include context: Provide all relevant details in the issue body

When Linking Issues to PRs

• Use Closes #123 or Fixes #123 in PR descriptions to auto-close issues
• Reference multiple issues: Closes #123, Closes #456
• Use issue numbers in commit messages for traceability

Issue Formatting

For security issues, use this template:

## Vulnerability Details
- **CVE**: CVE-YYYY-NNNNN
- **Severity**: [Critical/High/Medium/Low]
- **Component**: [Package/library name]

## Description
[Clear explanation of the vulnerability]

## Impact on Ark
[Which services are affected and how]

## Proposed Fix
[Recommended mitigation approach]

## References
- CVE: [URL]
- Advisory: [URL]

Error Handling

Issue Not Found

gh issue view 999 --repo mckinsey/agents-at-scale-ark
# Error: issue not found

Solution: Verify the issue number is correct

Permission Denied

gh issue create --repo mckinsey/agents-at-scale-ark
# Error: permission denied

Solution: Ensure you're authenticated with gh auth status and have write access to the repo

Rate Limiting

If you hit GitHub API rate limits:

• Wait a few minutes before retrying
• Use gh auth status to check your rate limit status
• Consider batching operations

Integration with Security Workflow

The ark-security-patcher agent uses this skill to:

1. Search for existing CVE issues before starting work:

   gh search issues --repo mckinsey/agents-at-scale-ark "CVE-2025-55183"
   

2. Link PRs to issues by including in PR body:

   Closes #33
   

3. Track vulnerability fixes by creating issues when CVEs are discovered

Example workflow:

# Agent searches for CVE issue
ISSUE=$(gh search issues --repo mckinsey/agents-at-scale-ark "CVE-2025-55183" --json number --jq '.[0].number')

if [ -n "$ISSUE" ]; then
  echo "Found existing issue #$ISSUE"
  # Include "Closes #$ISSUE" in PR
else
  echo "No existing issue found"
  # Optionally create a new issue
fi

Important Notes

• Repository: All commands target mckinsey/agents-at-scale-ark
• Authentication: Requires gh CLI to be authenticated (gh auth login)
• Permissions: Need read access to search/view, write access to create/update
• Rate limits: GitHub API has rate limits; be mindful of excessive searches

Common Patterns

Parse JSON Output

# Get issue numbers matching a search
gh search issues --repo mckinsey/agents-at-scale-ark "CVE" \
  --json number,title --jq '.[] | "\(.number): \(.title)"'

# Check if issue exists
EXISTS=$(gh search issues --repo mckinsey/agents-at-scale-ark "CVE-2025-55183" --json number --jq 'length')
if [ "$EXISTS" -gt 0 ]; then
  echo "Issue exists"
fi

Batch Operations

# List all open security issues
gh issue list --repo mckinsey/agents-at-scale-ark \
  --label security --state open \
  --json number,title --jq '.[] | "\(.number): \(.title)"'

# Create multiple issues from a list
for cve in CVE-2025-001 CVE-2025-002; do
  gh issue create --repo mckinsey/agents-at-scale-ark \
    --title "Security: Fix $cve" \
    --body "Track fix for $cve"
done