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:

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

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:

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

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