---
name: skill-upgrader
description: Compare, evaluate, and upgrade SKILL.md skills. This skill should be used when introducing a new skill that overlaps with an existing one, checking if an installed skill has upstream updates, merging two skills with complementary strengths, evaluating whether a skill is worth installing, or auditing unused skills. Trigger phrases include 'compare skills', 'check for updates', 'merge skills', 'evaluate this skill', 'upgrade skill', 'audit skills'.
---

# Skill Upgrader

Compare, evaluate, and upgrade SKILL.md-standard skills across any AI tool that supports the format.

## Scenarios

Identify the applicable scenario before proceeding:

| Scenario | Trigger | Action |
|----------|---------|--------|
| S1: Introduce | A new skill overlaps with an existing one | → Compare Flow |
| S2: Update | An installed skill may have upstream changes | → Update Check Flow |
| S3: Merge | Two skills each have unique strengths | → Merge Flow |
| S4: Evaluate | A skill is discovered but not yet installed | → Evaluate Flow |
| S5: Audit | Periodic review of installed skills | → Audit Flow |

---

## S1: Compare Flow

### Step 1: Load Both Skills

Read the SKILL.md files for both the existing (A) and candidate (B) skills. If B is a URL, fetch its raw content.

### Step 2: Dimension Evaluation

Score each skill on the 6 evaluation dimensions (see `references/evaluation.md` for detailed rubrics):

| Dimension | Wt | Skill A | Skill B |
|-----------|----|---------|---------|
| Description trigger coverage | 20% | _/10 | _/10 |
| Execution step clarity | 25% | _/10 | _/10 |
| Writing style compliance | 10% | _/10 | _/10 |
| Resource completeness | 15% | _/10 | _/10 |
| Project fit | 20% | _/10 | _/10 |
| Maintainability | 10% | _/10 | _/10 |
| **Weighted Total** | | _/10 | _/10 |

### Step 3: Decision

- **B ≥ A on all dimensions** → Path A: Replace
  - Archive the old skill to `.archive/{name}_{date}/`
  - Copy B into position
  - Preserve A's `source` and `version` history in a comment
- **B ≤ A on all dimensions** → Path B: Keep existing
  - Log the evaluation outcome for future reference
- **Mixed results** → Path C: Merge (proceed to S3)

### Step 4: Report

Output a structured comparison report with scores, rationale, and recommendation.

---

## S2: Update Check Flow

### Step 1: Read Frontmatter

Extract `source` and `version` fields from the installed skill's SKILL.md:

```yaml
---
name: example
source: https://github.com/org/repo
version: 2026-03-20
---
```

If `source` is missing, prompt the user to provide the upstream URL or skip.

### Step 2: Fetch Remote

Retrieve the remote SKILL.md from the `source` URL. Construct the raw content URL:
- GitHub: `https://raw.githubusercontent.com/{org}/{repo}/main/SKILL.md`
- Direct URL: use as-is

### Step 3: Diff Analysis

Compare local vs remote:
- If identical → Report "Up to date" and stop
- If different → Show a summary of what changed (added sections, removed sections, modified rules)

### Step 4: Upgrade Decision

Present changes and ask:
1. Apply update as-is (full replace)?
2. Review and selectively merge (→ S3)?
3. Skip this update?

If applying: archive the current version, replace with remote, update `version` in frontmatter.

---

## S3: Merge Flow

### Step 1: Identify the Trunk

Select the skill with higher **Project fit** score as the trunk (base). The other becomes the graft source.

### Step 2: Extract Graft Elements

From the graft source, identify elements that score higher than the trunk:
- Superior trigger phrases from `description`
- More precise execution steps
- Additional scripts or references
- Better-structured sections

### Step 3: Apply Grafts

Edit the trunk SKILL.md to incorporate the identified elements. Rules:
- Maintain the trunk's overall structure and voice
- Add graft elements in their logical positions
- Do NOT create a "Frankenstein" of mixed styles — normalize to imperative form
- Add `merged-from: {source}` to frontmatter for traceability

### Step 4: Validate

Run `quick_validate.py` on the merged result. Fix any issues.

### Step 5: Record

Document the merge rationale and what was taken from each source.

---

## S4: Evaluate Flow

For evaluating a skill before installation (no existing skill to compare against).

### Step 1: Load and Score

Read the candidate SKILL.md. Score it on the 6 dimensions against an **ideal baseline** (all 10s).

### Step 2: Fitness Check

Answer three critical questions:
1. Does this skill overlap with any already-installed skill?
2. Does it match the project's technical stack and workflow?
3. Is the maintenance burden acceptable (file count, complexity)?

### Step 3: Recommendation

- Score ≥ 7.0 + no overlap + good fit → **Recommend install**
- Score ≥ 7.0 + overlap → **Recommend compare** (→ S1)
- Score < 7.0 → **Do not recommend** (explain why)

---

## S5: Audit Flow

### Step 1: Inventory

List all installed skills with their metadata:
- Name, description, source, version, last modified date

### Step 2: Stale Detection

Flag skills that:
- Have no `source` field (cannot track updates)
- Have `version` older than 90 days with a known `source`
- Have SKILL.md smaller than 20 lines (potentially incomplete)

### Step 3: Recommendations

For each flagged skill, recommend one of:
- Check for updates (→ S2)
- Evaluate continued relevance (→ S4)
- Archive if no longer needed

---

## Frontmatter Convention

To enable upstream tracking, all externally-sourced skills SHOULD include:

```yaml
---
name: skill-name
description: ...
source: https://github.com/org/repo        # upstream repository
version: YYYY-MM-DD                         # date of last sync
merged-from: https://github.com/other/repo  # if created via merge
---
```

Skills created locally MAY omit `source` and `version`.