Compare Skills

TODAY=!date +%Y-%m-%d

Compare Skills

Compares the skill libraries in two directories, identifies best practices present in "theirs" but missing or weaker in "mine", and produces a prioritized adoption plan.

Prerequisites

• Two directories containing skill libraries, each with SKILL.md files in subdirectories
• `` — your skill directory (the one to improve)
• `` — the reference skill directory (the one to learn from)

What Counts as a Best Practice

| Category | What to Look For | |----------|-----------------| | Structural patterns | Consistent frontmatter fields, section ordering, standard sections (Prerequisites, Steps, Output Format, Examples) | | Instruction quality | Specificity of steps, use of code blocks, error handling guidance, edge case coverage | | Reusability | Parameterization via arguments or environment variables, ! template syntax for dynamic values | | Completeness | Prerequisites section, example usage scenarios, useful commands reference, next steps | | Safety | Guardrails, validation steps, rollback guidance, confirmation prompts before destructive actions | | Observability | Logging guidance, output formatting, status reporting | | Tool usage | allowed-tools frontmatter, appropriate tool constraints, tool-specific tips |

What Counts as a Removal Candidate

Patterns in "mine" that "theirs" has evolved away from or that are demonstrably harmful:

| Category | Signals | |----------|---------| | Over-constraint | Instructions that micromanage the agent (e.g., prescribing exact phrasing, mandating specific library versions in prose) where theirs delegates judgement | | Redundancy | Instructions duplicated across sections, or content repeated in multiple skills that theirs consolidates | | Stale assumptions | Hardcoded paths, version pins, or tool names that may be outdated; theirs uses dynamic values or omits them | | Vague handwaving | Steps like "handle errors appropriately" or "do the right thing" with no specificity; theirs either removes these or makes them concrete | | Boilderplate noise | Large copy-pasted blocks that add no instructional value (license headers, repeated disclaimers, decorative formatting) | | Premature optimization | Instructions that optimize for edge cases the agent handles naturally, bloating the skill without benefit | | Anti-patterns from theirs | Patterns present in mine that theirs explicitly avoids (e.g., mine uses cd && chains, theirs uses workdir; mine hardcodes values, theirs uses ! syntax) |

What Counts as a Disagreement

Conflicting instructions that pull the agent in different directions. These are higher priority than removal candidates because they actively cause wrong behavior.

| Scope | What to Detect | Example | |-------|---------------|---------| | Intra-skill (within one skill) | A step says one thing, a later step or output format template says the opposite | Step 3 says "always ask before committing" but Output Format shows auto-commit | | Inter-skill (across mine) | Two skills in mine give incompatible instructions for overlapping scenarios | Skill A says "use conventional commits"; Skill B says "write one-line commit messages" | | Cross-library (mine vs theirs) | For the same skill, mine and theirs prescribe different approaches with no clear reason for the divergence | Mine: "use find for file discovery"; Theirs: "use Glob tool, never find" | | Tone / style conflicts | One section demands brevity, another demands exhaustive detail | Preamble says "be concise" but Steps say "document every edge case exhaustively" | | Tool conflicts | Skill tells the agent to use one tool, but the code examples use a different one | Prose says "use uv" but code blocks show pip install |

Steps

1. Parse Arguments

MINE_DIR=$1
THEIRS_DIR=$2

Validate both directories exist and contain at least one SKILL.md. If arguments are missing or directories are invalid, report the error and stop.

2. Inventory Skills

List all skills in both directories:

find $MINE_DIR -name "SKILL.md" -type f | sort
find $THEIRS_DIR -name "SKILL.md" -type f | sort

3. Build Skill Maps

For each skill in both directories, extract:

• Name (from frontmatter name field)
• Description (from frontmatter description field)
• Frontmatter fields present (name, description, allowed-tools, argument-hint, etc.)
• Section headers present (Prerequisites, Steps, Output Format, Examples, etc.)
• Line count (proxy for thoroughness)
• Uses dynamic values (! syntax)
• Has code blocks (fenced blocks with language hints)
• Has examples (scenario-based example usage sections)

4. Categorize Relationships

For each skill, determine its relationship across the two directories:

| Relationship | Condition | |-------------|-----------| | Match | Same skill name exists in both directories | | Unique to mine | Skill exists only in ` | | **Unique to theirs** | Skill exists only in ` | | Similar | Different name but semantically overlapping purpose (manual judgement based on description comparison) |

5. Compare Matched Skills

For each matched pair, compare along these dimensions:

Frontmatter completeness:

• Does theirs have allowed-tools that mine lacks?
• Does theirs have argument-hint that mine lacks?
• Does theirs use additional frontmatter fields?

Section structure:

• Sections present in theirs but missing in mine
• Order and flow of sections

Instruction quality:

• Specificity and actionability of steps (numbered steps vs vague guidance)
• Use of concrete code examples and commands
• Error handling and edge case coverage
• Validation and verification steps

Parameterization:

• Dynamic value usage (! syntax)
• Argument handling
• Environment variable usage

Examples and reference:

• Example usage scenarios
• Useful commands reference tables
• Output format templates

6. Identify Removal Candidates in Mine

For each skill in ``, check for the removal candidate signals above. Cross-reference with "theirs" where a matched skill exists:

• If theirs omits a section mine has, determine if the omission is intentional (the section adds no value) or a gap in theirs
• If theirs has a cleaner version of the same instruction, flag mine's version as a simplification target
• If mine has content theirs does not, assess whether it is project-specific (keep) or boilerplate noise (remove)
• Flag any instructions in mine that contradict patterns observed as standard in theirs

7. Detect Disagreements

Check for conflicting instructions at every scope:

Intra-skill (within a single skill):

• Read each skill in mine end to end
• Look for assertions in one section that are violated by code blocks, output templates, or later steps in the same skill
• Common signals: "always X" in prose but output format shows not-X; "never Y" in prerequisites but Step N does Y; argument-hint says one signature but steps describe a different one

Inter-skill (across skills in mine):

• Build a topic map: for each skill, extract the key topics it governs (e.g., commit messages, PR descriptions, test structure)
• Where two skills share a topic, compare their instructions for conflicts
• Common signals: different naming conventions, different tool preferences, different required sections

Cross-library (mine vs theirs on matched skills):

• For matched pairs, compare the actual instructions not just the structure
• Flag cases where mine and theirs prescribe different approaches to the same step
• Assess which approach is better (clearer, more specific, more aligned with the rest of the library) and recommend which to keep

Tone/style and tool conflicts:

• Check if a skill's preamble (or AGENTS.md conventions) sets a tone that the steps violate
• Check if prose mentions a tool by name but code blocks use a different one

For each disagreement found, record: the two conflicting assertions, their locations (file + section), the scope (intra/inter/cross), and a recommendation for which to keep.

8. Extract Cross-Cutting Best Practices

Analyze all skills in `` for patterns not tied to a single skill:

• Consistent conventions used across all their skills (e.g., every skill has an Examples section)
• Novel frontmatter fields not used in mine
• Common structural patterns (e.g., Prerequisites always listed first, Output Format always before Examples)
• Reusable techniques (e.g., confirmation prompts, dry-run modes, progressive disclosure)

9. Analyze Unique-to-Theirs Skills

For skills that exist only in ``:

• Summarize what the skill does
• Assess whether it fills a gap in `` or represents a workflow worth adding
• Note any novel patterns or techniques it introduces

10. Prioritize Findings

Rank each finding by impact and effort:

| Priority | Criteria | |----------|----------| | High | Applies to many skills in mine, easy to adopt, clear benefit | | Medium | Applies to several skills, moderate effort, notable benefit | | Low | Applies to few skills, high effort, or marginal benefit |

11. Print the Report

# Skill Comparison Report — {TODAY}

## Summary

- Mine: N skills in ``
- Theirs: N skills in ``
- Matched skills: N
- Unique to mine: N
- Unique to theirs: N
- Similar skills: N
- Total findings: N (N high, N medium, N low)

## Cross-Cutting Best Practices

### [HIGH] 

**Observation:** What theirs does differently.
**Impact:** Why this matters (which of my skills benefit).
**Suggestion:** Concrete change to make in mine.

## Matched Skill Comparisons

### 

**Dimension where theirs is stronger:**
- 
- 

**Suggested changes:**
- 

## Unique-to-Theirs Skills

| Skill | Description | Gap Filled? | Adoption Priority |
|-------|-------------|-------------|-------------------|
| `` |  | Yes/No | High/Medium/Low |

## Similar Skills (Potential Deduplication or Merge)

| Mine | Theirs | Overlap |
|------|--------|---------|
| `` | `` |  |

## Adoption Checklist

Prioritized list of changes to apply:

1. [HIGH]  — affects N skills
2. [HIGH]  — affects N skills
3. [MEDIUM]  — affects N skills
...

## Removal Candidates

Sections, instructions, or patterns in mine to consider removing or simplifying:

| Skill | Section/Content | Reason | Confidence |
|-------|----------------|--------|------------|
| `` |  |  | High/Medium/Low |

Confidence levels:
- **High** — Theirs has the same skill without this content and works well
- **Medium** — The content appears to be noise but no direct evidence from theirs
- **Low** — May be project-specific; needs human judgement

## Disagreements

Conflicting instructions found, sorted by scope and severity:

### Intra-Skill Conflicts

| Skill | Assertion A | Assertion B | Resolution |
|-------|------------|------------|------------|
| `` | Step 2: "always ask before committing" | Output Format: auto-commit shown |  |

### Inter-Skill Conflicts (Across Mine)

| Skill A | Skill B | Topic | A says | B says | Resolution |
|---------|---------|-------|--------|--------|------------|
| `` | `` | commit messages | conventional commits | one-line summaries |  |

### Cross-Library Conflicts (Mine vs Theirs)

| Skill | Mine approach | Theirs approach | Recommendation |
|-------|--------------|----------------|----------------|
| `` |  |  |  |

## Statistics

| Metric | Mine | Theirs |
|--------|------|--------|
| Total skills | N | N |
| Avg lines per skill | N | N |
| Skills with examples | N | N |
| Skills with output format | N | N |
| Skills with prerequisites | N | N |
| Skills using dynamic values | N | N |
| Skills with allowed-tools | N | N |

Example Usage

Scenario 1: Compare your skills against a reference repo

/compare-skills ~/.opencode/skills /path/to/reference-repo/skills

Finds that the reference repo consistently includes allowed-tools frontmatter and Example sections, while yours lacks them on 12 skills. Produces a checklist to add these to each affected skill.

Scenario 2: Compare two team members' skill sets

/compare-skills ~/my-skills ~/teammate-skills

Discovers 5 unique skills in teammate's directory that cover workflows you also perform. Recommends adopting them.

Scenario 3: Upgrade your skills after pulling upstream changes

/compare-skills ~/.claude/skills ~/.opencode/skills

Finds that the upstream .opencode/skills has improved output formatting and added error handling sections. Prioritizes which improvements to backport.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tomzx
• Source: tomzx/agents
• License: MIT

Install and usage instructions live in the source repository linked above.