GitHub Improvement Proposal Generator Skill

This skill generates a well-structured improvement/enhancement proposal for GitHub issues based on the conversation context and saves it to .ai/gh_issues/YYMMDD-<short-issue-name>.md. This skill is specifically designed for improvements and enhancements - not for bug reports or error fixes.

Purpose

When invoked, this skill extracts improvement information from the current conversation and creates a standardized GitHub enhancement proposal document.

Use this skill for:

• Feature enhancements or improvements
• Code refactoring or restructuring
• Performance optimizations
• Architecture improvements
• Tool migrations (e.g., migrating MCP tools to direct_api_call)
• API consolidation or simplification
• Documentation improvements
• Testing improvements

Do NOT use this skill for:

• Bugs, errors, or broken functionality
• Incorrect behavior or unexpected results
• System failures or crashes

Workflow

1. Extract Issue Information

Review the conversation to identify:

• The improvement or enhancement being proposed
• Current state and its limitations
• Motivation and benefits of the improvement
• Proposed changes at a conceptual level
• Expected outcomes or impact

2. Generate Filename

Create a filename using the pattern:

.ai/gh_issues/YYMMDD-<short-issue-name-with-dashes>.md

Where:

• YYMMDD: Current date in 2-digit year, month, day format (e.g., 260128 for January 28, 2026)
• <short-issue-name-with-dashes>: A brief, descriptive name using lowercase letters and dashes (e.g., migrate-logs-to-direct-api, optimize-pagination-logic, consolidate-nft-tools)

Example: .ai/gh_issues/260128-migrate-logs-to-direct-api.md

3. Create Issue Document

Write a Markdown document with the following sections:

# [Brief Title of the Improvement]

## Description

[Short description of the improvement - 2-3 sentences summarizing what is being proposed]

## Motivation

[Clear explanation of why this improvement is needed - what problems does it solve, what benefits does it provide]

## Current State

[Description of how things work currently, including any limitations or pain points]

## Proposed Changes

[High-level description of what should change conceptually. Focus on WHAT changes, not HOW to implement them. Avoid step-by-step implementation details, specific file paths, or granular action items. Keep it strategic and outcome-focused.]

## Expected Benefits

[List of concrete benefits that will result from this improvement - can include improved performance, better maintainability, reduced complexity, etc.]

Example of well-formed "Proposed Changes" section:

## Proposed Changes

- Transition the standalone tool to a handler-based architecture consistent with similar tools
- Maintain backward compatibility by preserving the REST API endpoint with deprecation notices
- Consolidate response processing logic within the dispatcher pattern
- Update all references in documentation and integration examples to reflect the new approach

4. Content Guidelines

MUST INCLUDE:

• Short description (2-3 sentences)
• Motivation explaining why the improvement is needed
• Current state description showing what exists today
• Proposed changes (clear, organized list describing what should change)
• Expected benefits (concrete outcomes)

MUST NOT INCLUDE:

• Detailed code implementation or snippets
• Specific file paths or module names (e.g., blockscout_mcp_server/tools/direct_api/handlers/x_handler.py)
• Step-by-step implementation checklists (e.g., "1. Create X, 2. Update Y, 3. Delete Z")
• Granular action items for each file or component
• Function names, decorator names, or code structure details
• Line-by-line diffs or patches
• Test case implementations or test file locations
• Documentation file names or specific sections to update

STYLE GUIDELINES:

• Focus on "what" should change and "why" it matters, not "how" to implement it in detail
• Use lists and structured formatting for clarity
• Be specific enough to be actionable but general enough to allow implementation flexibility
• Avoid prescriptive implementation details - leave room for refinement during development
• Keep "Proposed Changes" to 3-6 high-level points maximum
• Each point should describe an outcome or conceptual change, not an implementation task

PROPOSED CHANGES - GOOD EXAMPLES:

✓ "Consolidate transaction-related tools under a unified dispatcher pattern" ✓ "Deprecate the dedicated tool in favor of the generic direct_api_call interface" ✓ "Preserve existing response processing logic while relocating it to a handler" ✓ "Update documentation to reflect the new tool architecture"

PROPOSED CHANGES - BAD EXAMPLES:

✗ "Create handler module at blockscout_mcp_server/tools/direct_api/handlers/x_handler.py with @register_handler decorator" ✗ "Update REST API in api/routes.py to return deprecation response with 410 status code" ✗ "Remove import of transaction_summary function from server.py" ✗ "Migrate tests: Delete test_transaction_summary.py and create new handler tests"

5. Output Confirmation

After creating the file, confirm:

• The full path where the file was created
• A brief summary of the improvement documented

Example Usage

When the user says:

/gh-issue-improvement

You should:

1. Review the conversation for improvement details
2. Generate filename like .ai/gh_issues/260128-consolidate-transaction-tools.md
3. Create the issue document with all required sections
4. Confirm creation with: "Created GitHub improvement proposal at .ai/gh_issues/260128-consolidate-transaction-tools.md"

Example Improvements

This skill can document various types of improvements:

• Tool Migration: Migrating an MCP tool to use direct_api_call handler pattern
• Refactoring: Consolidating duplicate code into shared utilities
• Performance: Optimizing caching strategies or reducing API calls
• Architecture: Restructuring modules for better separation of concerns
• API Changes: Simplifying or consolidating API endpoints
• Testing: Adding comprehensive test coverage for a module
• Documentation: Improving inline documentation or user guides

Notes

• The skill is designed for improvements discussed during development planning or code reviews
• If insufficient information exists in the conversation, ask the user for clarification before generating the document
• CRITICAL: Keep proposed changes conceptual and strategic - avoid prescriptive implementation details
• Before writing "Proposed Changes", review the GOOD vs BAD examples above to ensure appropriate level of abstraction
• Think: "What outcomes do we want?" not "What steps should we take?"
• If you find yourself writing file paths, function names, or numbered checklists, you're being too prescriptive
• Focus on the value proposition - make it clear why this improvement matters