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:

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

Apply update as-is (full replace)?
Review and selectively merge (→ S3)?
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:

Does this skill overlap with any already-installed skill?
Does it match the project's technical stack and workflow?
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.

skill-upgrader