general-skill-upgrader

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):

1. Add new features - Extend capabilities within domain
2. Simplify workflow - Reduce steps, eliminate redundancy
3. Parallel execution - Run independent steps simultaneously
4. 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:

1. Read SKILL.md:

   • Co skill robi (actions)
   • Po co skill istnieje (business purpose)
   • Jaki problem użytkownika rozwiązuje
   • Jaki jest obecny workflow

2. Read references/:

   • Jakie supporting materials są
   • Jakie decyzje były już podjęte
   • Czy są TODO/known limitations

3. 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

4. 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:

1. Is this relevant? Does skill have potential in this area?
2. What's the opportunity? Specific improvement that could be made
3. What's the value? How does it make skill better at its business goal?
4. What's the effort? Simple change vs major rewrite
5. 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:

1. Plan implementation:

   • Co dokładnie trzeba zmienić (files, sections)
   • W jakiej kolejności (dependencies)
   • Jak zweryfikować że działa

2. Implement first upgrade:

   • Make changes to SKILL.md
   • Update references/ if needed
   • Add examples if relevant
   • Keep changes atomic and clear

3. Verify first upgrade:

   • Read changed files to confirm
   • Check that workflow makes sense
   • Ensure no broken references
   • Validate markdown syntax

4. Implement second upgrade (if chosen):

   • Same careful process
   • Ensure integration with first upgrade
   • No conflicts or contradictions

5. 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.