General Skill Upgrader

Overview

Purpose: Strategic enhancement and functional evolution of agent skills

Approach:

Understand business goal - what problem does this skill solve?
Identify opportunities - 22 types of potential upgrades
Present options - show 1-2 most valuable upgrades per run
User decides - pick what matters most right now
Implement & verify - make it better, confirm it works
Iterative process - run again for next round of upgrades

Output: Enhanced skill + upgrade report in .tasks/skill-upgrade-[skill-name]-[date]/

Key Difference from Refiner:

Refiner = fix problems (quality issues, bugs, violations)
Upgrader = add value (new capabilities, better UX, smarter workflow)

Guidelines

What Makes a Good Upgrade

Value-Driven:

Solves real user pain point
Makes workflow smoother/faster/easier
Reduces mental overhead
Enables new use cases
Improves reliability

Practical:

Actually implementable (not fantasy features)
Fits skill's core purpose (not scope creep)
Worth the added complexity
User will actually use it

Clear Win:

Measurable improvement (fewer steps, less friction, better output)
Doesn't break existing functionality
Easy to understand benefit
Aligns with skill's business goal

The 22 Types of Upgrades

Complete details in references/upgrade-types.md.

Workflow Enhancements (1-4):

Add new features - Extend capabilities within domain
Simplify workflow - Reduce steps, eliminate redundancy
Parallel execution - Run independent steps simultaneously
Checkpoints - Resume long processes from interruption

Quality & Reliability (5-8): 5. Better edge cases - Handle unusual scenarios gracefully 6. Early validation - Catch problems before end of workflow 7. Self-checking - Skill verifies its own output quality 8. Error recovery - Smart rollback, retry, or repair mechanisms

Automation & Intelligence (9-12): 9. Automate manual steps - Replace human intervention with logic 10. Context-awareness - Adapt to project type, user preferences, history 11. Learning from history - Use previous runs to improve suggestions 12. Smart defaults - Intelligent choices based on patterns

User Experience (13-16): 13. Better briefing - Smarter questions, fewer iterations 14. Interactive choices - Option menus instead of open questions 15. Progress visibility - Clear feedback on what's happening 16. Dry-run mode - Preview changes before committing

Integration & Output (17-20): 17. Tool integration - Better use of available tools (bash, git, etc.) 18. Reusable outputs - Results that feed into other skills 19. Better reports - More actionable, clearer insights 20. Batch processing - Handle multiple items efficiently

Documentation (21-22): 21. More examples - Concrete use cases, templates, patterns 22. Best practices - Guidance on optimal usage

Examples

Example 1: Adding Dry-Run Mode

Skill analyzed: code-refactor

Current state: Makes changes directly to files

Upgrade opportunity:

Type: #16 Dry-run mode
Problem: Users nervous about automatic changes
Solution: Add --preview mode that shows diffs without applying
Value: User confidence, safety net, teaching tool

Implementation:

## Options

**Preview mode (recommended for first run):**
1. Analyze code and generate refactoring plan
2. Show diffs of proposed changes
3. Ask: "Apply these changes?"

**Direct mode:**
1. Analyze and apply changes immediately
2. Report what was changed

Example 2: Adding Self-Checking

Skill analyzed: documentation-writer

Current state: Writes docs, user reviews manually

Upgrade opportunity:

Type: #7 Self-checking
Problem: Common doc issues not caught automatically
Solution: Built-in quality checks before presenting to user
Value: Higher quality output, fewer user corrections

Implementation:

## Phase 4: Quality Verification (NEW)

Before presenting documentation, run self-checks:

**Completeness:**
- [ ] All public APIs documented
- [ ] All parameters explained
- [ ] Return values specified

**Clarity:**
- [ ] No jargon without explanation
- [ ] Examples for complex features
- [ ] Clear section structure

If checks fail → Fix issues → Re-check → Present to user

See references/examples.md for more detailed scenarios.

Workflow

Phase 1: Read & Understand Business Goal

Cel: Dogłębnie zrozumieć PO CO ten skill istnieje.

Kroki:

Read SKILL.md:
- Co skill robi (actions)
- Po co skill istnieje (business purpose)
- Jaki problem użytkownika rozwiązuje
- Jaki jest obecny workflow
Read references/:
- Jakie supporting materials są
- Jakie decyzje były już podjęte
- Czy są TODO/known limitations
Understand user experience:
- Jak user używa tego skilla
- Które kroki są manualne vs automatyczne
- Gdzie są friction points
- Co mogłoby być prostsze
Identify core purpose:
- One sentence: "Ten skill istnieje żeby [business goal]"
- Success criteria: Jak poznać że skill dobrze wykonał swoją robotę?
- Boundaries: Co jest in-scope vs out-of-scope?

Output: Jasne zrozumienie biznesowego celu i obecnego stanu skilla.

Phase 2: Identify Upgrade Opportunities

Goal: Find 3-5 most valuable potential upgrades across 22 categories

Analysis Process:

For each upgrade type (1-22), ask:

Is this relevant? Does skill have potential in this area?
What's the opportunity? Specific improvement that could be made
What's the value? How does it make skill better at its business goal?
What's the effort? Simple change vs major rewrite
Priority? High/Medium/Low based on value vs effort

Use references/upgrade-types.md for detailed criteria.

Look for:

Repeated manual steps → automation opportunity
User confusion points → UX improvement opportunity
Common failures → reliability upgrade opportunity
Limited scope → feature expansion opportunity
Generic approach → context-awareness opportunity

Red flags (avoid):

Scope creep - feature doesn't match skill's core purpose
Over-engineering - adds complexity without clear value
Speculative - "might be useful someday" features
Redundant - capability already exists elsewhere

For each opportunity found:

Document:

## [Upgrade Name]

**Type:** #[number] [type name]
**Current state:** [what skill does now]
**Opportunity:** [what could be improved]
**Value:** [why this matters for business goal]
**Implementation:** [high-level approach]
**Effort:** Low/Medium/High
**Priority:** High/Medium/Low

Output: 3-5 concrete upgrade opportunities ranked by priority

Phase 3: Present & Gather Feedback

Cel: Pokazać najlepsze opcje i dać userowi wybór.

Presentation format:

# Upgrade Opportunities for [skill-name]

## 🎯 Skill's Business Goal

[One sentence core purpose]

## 📊 Current State Analysis

**Co działa dobrze:**
- [Good aspect 1]
- [Good aspect 2]

**Gdzie można ulepszać:**
- [Opportunity area 1]
- [Opportunity area 2]

## 🚀 Top Upgrade Options

### Option 1: [Upgrade Name] ⭐

**Type:** [Type name from 22 types]

**Problem it solves:**
[Clear description of current limitation]

**How it works:**
[Konkretny opis co by się zmieniło]

**Value:**
- [Benefit 1]
- [Benefit 2]

**Example:**
[Before/after comparison or concrete scenario]

**Effort:** [Low/Medium/High]

---

### Option 2-5: [Continue similarly]

---

## 💡 Recommendation

Based on value vs effort, I recommend:
1. **[Option X]** - [brief why]
2. **[Option Y]** - [good second choice]

Concrete example (file-analyzer → batch processing):

## 🎯 Business Goal: Analyze files for quality/security issues

## 📊 Current State
Good: Clear per-file reports | Can improve: Must run 150x separately (slow)

## 🚀 Option 1: Batch Processing Mode ⭐
**Type:** #20 Batch processing
**Problem:** 150 separate invocations with repeated setup
**Solution:** Process multiple files at once with shared setup
**Value:** 10x faster, aggregate insights, single report
**Example:** Before: 150 commands | After: 1 command processes all
**Effort:** Medium

## 💡 Recommendation: Option 1 - highest impact for medium effort

Ask user:

"Które ulepszenia chcesz żebym zaimplementował? Wybierz 1-2 z powyższych opcji.

Możesz też:

Zaproponować własne ulepszenie
Poprosić o więcej szczegółów
Powiedzieć że żadna nie pasuje"

Listen for:

Które opcje user wybiera (max 2 per run)
Czy user ma modyfikacje do propozycji
Czy user widzi inne ulepszenia
Czy user chce zobaczyć więcej opcji

Output: 1-2 wybrane ulepszenia z user approval.

Phase 4: Implement Upgrades

Cel: Wprowadzić wybrane ulepszenia systematycznie i bezpiecznie.

Implementation workflow:

Plan implementation:
- Co dokładnie trzeba zmienić (files, sections)
- W jakiej kolejności (dependencies)
- Jak zweryfikować że działa
Implement first upgrade:
- Make changes to SKILL.md
- Update references/ if needed
- Add examples if relevant
- Keep changes atomic and clear
Verify first upgrade:
- Read changed files to confirm
- Check that workflow makes sense
- Ensure no broken references
- Validate markdown syntax
Implement second upgrade (if chosen):
- Same careful process
- Ensure integration with first upgrade
- No conflicts or contradictions
Final integration check:
- Both upgrades work together
- Workflow is coherent
- No redundancy introduced
- Overall skill is better

Implementation patterns:

Use references/implementation-patterns.md for detailed guidance on:

Adding new features
Improving UX
Adding automation
Better error handling
Each of the 22 upgrade types

Track changes:

Create .tasks/skill-upgrade-[skill-name]-[date]/implementation.md:

# Implementation Log

## Upgrade 1: [Name]

**Changes made:**
- [File] line [X]: [change description]
- [File]: Added new section [name]

**Before:** [snippet]
**After:** [new version]
**Rationale:** [why]

## Upgrade 2: [Name]
[Same structure]

Output: Upgraded skill with both enhancements implemented.

Phase 5: Verify & Report

Cel: Potwierdzić że ulepszenia działają i komunikować rezultat.

Verification checklist:

✅ Files are valid:

SKILL.md syntax correct
All references exist
Links work
No broken markdown

✅ Upgrades implemented:

Feature 1 fully integrated
Feature 2 fully integrated
Both work together harmoniously
No contradictions

✅ Quality maintained:

No time estimates introduced
Structure clear
Examples helpful
Workflow logical

✅ Business goal better served:

Skill more effective at core purpose
User experience improved
Value clearly increased

Report to user:

# Skill Upgraded: [skill-name]

## ✅ Upgrades Implemented

### 1. [Upgrade Name]
**What changed:** [description]
**Where:** [files/sections]
**Value:** [how it helps]

### 2. [Upgrade Name]
[same structure]

## 📈 Improvements

**Before:** [key limitations]
**After:** [how it's better now]
**Example:** [scenario showing improvement]

## 🎯 Business Goal Impact

[How upgrades make skill better at its core purpose]

## 📝 Details

Full implementation log in `.tasks/skill-upgrade-[name]-[date]/`

## 🔄 Next Steps

Want more upgrades? Run upgrader again.

Remaining opportunities:
- [Option X]
- [Option Y]

Ask:

"Czy ulepszenia działają jak oczekiwałeś?"
"Czy chcesz jakieś modyfikacje?"
"Czy uruchomić upgrader ponownie?"

Special Cases

Skill is already excellent: Say so honestly. Look for minor polish (docs, examples). May not need upgrades.

Ambitious upgrade: Be honest about complexity. Break into phases or multiple runs. May need separate skill if different domain.

Conflicts with design: Explain why it doesn't fit. Propose alternative or note if it's a Refiner issue instead.

Multiple ideas same category: Present best 1-2. Others go to "future opportunities" for next run.

Reveals bigger issue: Note it but stay focused. User can address separately.

Quality Checklist

✅ Business goal understood & all 22 types considered ✅ 3-5 valuable options presented, user chose 1-2 ✅ Changes verified, no breakage, quality maintained ✅ Value delivered - skill measurably better ✅ Changes documented, user satisfied, can iterate

Key Reminders

DO: Understand WHY skill exists. Consider all 22 types. Present clear value. Let user choose 1-2. Verify changes. Enable iteration.

DON'T: Confuse with Refiner (fix vs add value). Propose scope creep. Overwhelm with options. Implement without approval. Break functionality. Add complexity without value.

Approach: Strategic product manager. Present options, respect choices, deliver improvements.

Remember: Better ≠ bigger. Simpler often wins. Listen to user priorities. Business goal is the north star.

general-skill-upgrader