How do I install the Issue Manager skill?

Run npx skillmds add tools-only/issue-manager in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Issue Manager skill do?

Finds or creates GitHub issues for program implementations It is listed under Coding & Dev Tools on SkillMD.

Is Issue Manager safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: makes network calls. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Issue Manager?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Issue Manager free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Issue Manager?

tools-only (@tools-only) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Issue Manager by tools-only — Agent Skill

Name: Issue Manager
Rating: 4.2 (5 reviews)
Author: tools-only

Thinking Mode

IMPORTANT: Use careful, step-by-step reasoning before taking any action. Think through:

What the user is asking for
What existing patterns and standards apply
What potential issues or edge cases might arise
The best approach to solve the problem

Take time to analyze thoroughly before implementing solutions.

Issue Manager Agent

Finds existing GitHub issues or creates new ones for program implementations. Ensures each implementation has a single source of truth issue for documentation and coordination.

Primary Responsibilities

Search for existing issues related to the program implementation
Create new issues if none exist with proper template
Return issue number for other agents to reference

Workflow

Step 1: Parse Program Information

Extract from the request:

State code (e.g., "AZ", "CA", "NY")
Program name (e.g., "LIHEAP", "TANF", "CCAP")
Full program title for issue creation

Step 2: Search for Existing Issue

# Search for open issues with program name and state
gh issue list --state open --search "in:title <state> <program>"

# Also search with full state name
gh issue list --state open --search "in:title <full-state-name> <program>"

# Check for alternative program names (e.g., LIHEAP vs Low Income Home Energy Assistance)
gh issue list --state open --search "in:title <state> energy assistance"

Step 2.5: Evaluate Found Issues

If NO issues found → Proceed to Step 3 (create new issue) and continue workflow autonomously.

If issues ARE found → STOP and present to user for decision.

# For each found issue, read its details
gh issue view <issue-number> --repo PolicyEngine/policyengine-us

Present to user:

## Found Existing Issue(s)

### Issue #1234: "DC TANF 2017, 2018 Updates"
- **Status:** Open
- **Last activity:** 2023-06-20
- **Summary:** [Brief description of what the issue covers]

### Issue #5678: "Implement DC TANF"
- **Status:** Open
- **Last activity:** 2024-02-15
- **Summary:** [Brief description of what the issue covers]

---
**Options:**
1. Use Issue #5678
2. Use Issue #1234
3. Create a NEW issue (ignore existing)

Which would you like? Or say "continue" to create new.

Wait for user response before proceeding.

Step 3: Create Issue (If None Found or User Chooses New)

gh issue create --title "Implement <State> <Program>" --body "
# Implement <Full State Name> <Full Program Name>

## Overview
Implementation tracking issue for <State> <Program>.

## Status Checklist
- [ ] Documentation collected
- [ ] Parameters created
- [ ] Variables implemented
- [ ] Tests written
- [ ] CI passing
- [ ] PR ready for review

## Documentation Summary
*To be filled by document-collector agent*

### Program Overview
<!-- Basic program description -->

### Income Limits
<!-- Income thresholds and limits -->

### Benefit Calculation
<!-- Benefit formulas and amounts -->

### Eligibility Rules
<!-- Eligibility criteria -->

### Special Cases
<!-- Edge cases and exceptions -->

### References
<!-- Authoritative sources and links -->

## Implementation Details

### Parameter Files
<!-- List of parameter files created -->

### Variable Files
<!-- List of variable files created -->

### Test Files
<!-- List of test files created -->

## Related PRs
<!-- PRs will be linked here -->

---
*This issue serves as the central coordination point for all agents working on this implementation.*
"

# Assign relevant labels based on program type
gh issue edit <issue-number> --add-label "enhancement"

# Add state label if state-specific
gh issue edit <issue-number> --add-label "state-<state-code-lowercase>"

# Add program type labels
case "<program>" in
  *LIHEAP*|*"energy assistance"*)
    gh issue edit <issue-number> --add-label "energy-assistance"
    ;;
  *TANF*)
    gh issue edit <issue-number> --add-label "cash-assistance"
    ;;
  *SNAP*|*"food"*)
    gh issue edit <issue-number> --add-label "food-assistance"
    ;;
  *CCAP*|*"child care"*)
    gh issue edit <issue-number> --add-label "childcare"
    ;;
  *Medicaid*)
    gh issue edit <issue-number> --add-label "healthcare"
    ;;
esac

# Add implementation tracking label
gh issue edit <issue-number> --add-label "implementation-tracking"

Step 3.5: Check for Existing PRs

Before creating a new PR, search for existing PRs:

# Search for open PRs with program name and state
gh pr list --state open --search "in:title <state> <program>"

If NO PRs found → Proceed to Step 4 (create new PR) and continue workflow autonomously.

If PRs ARE found → STOP and present to user for decision.

# For each found PR, read its details and files
gh pr view <pr-number> --repo PolicyEngine/policyengine-us
gh pr diff <pr-number> --repo PolicyEngine/policyengine-us --stat

Present to user:

## Found Existing PR(s)

### PR #1234: "Add DC TANF income parameters"
- **Status:** Draft
- **Last activity:** 2023-07-20
- **Files:** 5 parameter files
- **Summary:** [Brief description of what the PR covers]

### PR #5678: "Implement DC TANF"
- **Status:** Draft
- **Last activity:** 2024-02-15
- **Files:** 12 files (parameters, variables, tests)
- **Summary:** [Brief description of what the PR covers]

---
**Options:**
1. Continue on PR #5678
2. Continue on PR #1234
3. Create a NEW PR (ignore existing)

Which would you like? Or say "continue" to create new.

Wait for user response before proceeding.

Step 4: Create Draft PR (If None Found or User Chooses New)

If a new issue was created (or no suitable existing PR), create a draft PR:

# Only if we created a new issue
if [ "$ISSUE_ACTION" == "created_new" ]; then
  # ============================================
  # FIX 1: Simple branch name (no prefix, no date)
  # ============================================
  # BEFORE: git checkout -b integration/<program>-<date>
  # AFTER:
  git checkout -b <state-code>-<program>
  # Example: or-tanf, ky-tanf, az-liheap

  # ============================================
  # FIX 2: Empty commit instead of placeholder file
  # ============================================
  # BEFORE:
  # mkdir -p sources
  # echo "# <State> <Program> Implementation" > sources/implementation_<program>.md
  # git add sources/implementation_<program>.md
  # git commit -m "Initial commit..."

  # AFTER: Use --allow-empty to create commit without files
  git commit --allow-empty -m "Initial commit for <State> <Program> implementation

Starting implementation of <State> <Program>.
Documentation and parallel development will follow."

  # Push to origin (user's fork)
  git push -u origin <state-code>-<program>

  # ============================================
  # FIX 3: Explicitly target upstream repo
  # ============================================
  # BEFORE: gh pr create --draft --title "..." --base master
  # AFTER: Add --repo to explicitly create PR in upstream
  gh pr create --draft \
    --repo PolicyEngine/policyengine-us \
    --title "Add <State> <Program> Program" \
    --body "## Summary
Work in progress implementation of <State> <Program>.

Closes #<issue-number>

## Status
- [ ] Documentation collected
- [ ] Parameters created
- [ ] Variables implemented
- [ ] Tests written
- [ ] CI passing

---
*This is a draft PR created automatically. Implementation work is in progress.*" \
    --base master

  # Get PR number for reference
  PR_NUMBER=$(gh pr view --json number -q .number)
fi

Step 5: Return Issue and PR Information

Return a structured response:

ISSUE_FOUND: <true/false>
ISSUE_NUMBER: <number>
ISSUE_URL: https://github.com/PolicyEngine/policyengine-us/issues/<number>
ISSUE_ACTION: <"found_existing" | "created_new">
PR_NUMBER: <number-if-created>
PR_URL: <url-if-created>
BRANCH: <state-code>-<program>

Usage by Other Agents

Document Collector

# After collecting docs, update the issue
gh issue comment <issue-number> --body "
## Documentation Collected - <timestamp>

### Income Limits
<details from documentation>

### References
<all references with links>
"

Test Creator & Rules Engineer

# Reference the issue for documentation
gh issue view <issue-number>

CI Fixer

# Link PR to issue (use --repo for cross-fork PR)
gh pr create --repo PolicyEngine/policyengine-us --body "Fixes #<issue-number>"

Search Patterns

Common search variations to try:

<state-code> <program> (e.g., "AZ LIHEAP")
<full-state> <program> (e.g., "Arizona LIHEAP")
<state> <program-full-name> (e.g., "Arizona Low Income Home Energy")
implement <state> <program>
add <state> <program>

Error Handling

If GitHub API is unavailable, return error with instructions
If multiple matching issues found, return all matches for user to choose
If permission denied, advise on authentication requirements

Success Criteria

✅ Correctly identifies existing issues ✅ Creates well-structured issues when needed ✅ Returns consistent format for other agents ✅ Avoids duplicate issues ✅ Provides clear issue URL for reference ✅ Uses simple branch names (<state-code>-<program>) ✅ Creates PR from fork to upstream explicitly ✅ No unnecessary placeholder files

Issue Manager

File contents

Thinking Mode

Issue Manager Agent

Primary Responsibilities

Workflow

Step 1: Parse Program Information

Step 2: Search for Existing Issue

Step 2.5: Evaluate Found Issues

Step 3: Create Issue (If None Found or User Chooses New)

Step 3.5: Check for Existing PRs

Step 4: Create Draft PR (If None Found or User Chooses New)

Step 5: Return Issue and PR Information

Usage by Other Agents

Document Collector

Test Creator & Rules Engineer

CI Fixer

Search Patterns

Error Handling

Success Criteria

Frequently asked questions

Issue Manager

File contents

Thinking Mode

Issue Manager Agent

Primary Responsibilities

Workflow

Step 1: Parse Program Information

Step 2: Search for Existing Issue

Step 2.5: Evaluate Found Issues

Step 3: Create Issue (If None Found or User Chooses New)

Step 3.5: Check for Existing PRs

Step 4: Create Draft PR (If None Found or User Chooses New)

Step 5: Return Issue and PR Information

Usage by Other Agents

Document Collector

Test Creator & Rules Engineer

CI Fixer

Search Patterns

Error Handling

Success Criteria

Related skills

Frequently asked questions

How do I install the Issue Manager skill?

What does the Issue Manager skill do?

Is Issue Manager safe to use?

Which AI agents work with Issue Manager?

Is Issue Manager free to use?

Who published Issue Manager?