AgentSkillsCN

gh-issue-improvement

根据对话背景，为GitHub问题生成结构化的改进/优化方案。

SKILL.md
--- frontmatter
name: gh-issue-improvement
description: Generate a structured improvement/enhancement proposal for GitHub issues based on conversation context
disable-model-invocation: true
hooks:
  PreToolUse:
    - matcher: "Write|Edit"
      hooks:
        - type: command
          command: "$CLAUDE_PROJECT_DIR/.claude/hooks/allow-temp-writes.py"
    - matcher: "Bash"
      hooks:
        - type: command
          command: "$CLAUDE_PROJECT_DIR/.claude/hooks/allow-temp-dirs.py"

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 temp/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:

text
temp/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: temp/gh_issues/260128-migrate-logs-to-direct-api.md

3. Create Issue Document

Write a Markdown document with the following sections:

markdown
# [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:

markdown
## 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:

bash
/gh-issue-improvement

You should:

  1. •Review the conversation for improvement details
  2. •Generate filename like temp/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 temp/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