Skill Improver

The Problem: The Challenge of Skill Maintenance

Building and publishing an AI Agent skill (skill) is only the beginning. As usage evolves and requirements change, skills frequently reveal underlying issues:

• Instructional Flaws: Logical contradictions, unhandled edge cases, or ambiguous steps in the original design can lead to execution failures or poor outcomes.
• Imprecise Triggers: The description metadata in SKILL.md might be insufficiently precise, causing user intent to fail to map correctly to the skill.
• Lack of Evolution: Once deployed, skills can stagnate without a system to learn from real-world usage data (like BUG_LOG.md) or external best practices, causing them to become outdated.

Manually inspecting and optimizing these skill files is time-consuming and difficult to systematize. Skill Improver is a "meta-skill" built specifically to address this, focusing on the systematic diagnosis, repair, and enhancement of other skills.

Core Capabilities and Workflow

This skill implements a structured six-step workflow powered by three synergistic improvement modes, creating an evolutionary loop.

Three Improvement Sources

1. User-Request Driven (Mode A): Activated when users explicitly identify a skill's shortcomings or propose a direction (e.g., "fix the trigger issue," "add error handling"). It conducts a multi-dimensional diagnosis (metadata, instruction quality, resource organization, UX), generates a structured report, and performs targeted optimizations.
2. Operational-Logging Driven (Mode B): This mode (B) directly connects to the skill's feedback loop. It reads unresolved issues recorded in BUG_LOG.md, prioritizes them by severity, and fixes them one by one, updating the log status. Post-fix, it may add defensive instructions to prevent recurrence.
3. Web-Search Driven (Mode C): When users request an "automatic optimization" or provide no specific direction, mode (C) takes over. It analyzes the skill's functional positioning, automatically constructs search queries (e.g., "[skill domain] prompt engineering best practices"), retrieves best practices from the web, evaluates them, and presents actionable improvements for user confirmation.

Key Execution Steps

• Locate & Analyze: First, it searches for and loads the target skill's complete files and references based on a priority (User-level > Project-level > Built-in).
• Mode Selection & Execution: The appropriate mode(s) are selected based on the trigger (e.g., "auto-optimize and fix bugs" triggers both C and B). Improvements are executed adhering strictly to the principles of minimal change, style consistency, and incremental safety, prioritizing high-severity items like description optimization.
• Verify & Log: Post-modification, verification checks YAML validity, file references, and logical coherence. All newly discovered issues found during execution are appended to BUG_LOG.md in a standardized format, regardless of immediate fixes, to fuel the next iteration.

Scope and Important Notes

• Target Scope: This skill improves skill definition files (primarily SKILL.md) and their references, not end-user applications or data. It is designed for skills built under the ai-agent category following this specification.
• Technical Prerequisite: Users should have a basic understanding of skill development structures (e.g., frontmatter, instruction writing) to comprehend diagnostic reports and confirm improvement proposals.
• Modification Risk: Executing improvements directly modifies skill files. For built-in skills, changes create a user-level override. Manual backups or version control is recommended before significant modifications for rollback readiness.
• Not a Silver Bullet: Proposals from web search (Mode C) are evaluated and require confirmation; not all external practices are applicable. Fundamental architectural redesigns of a skill may be beyond the scope of this automation.