Resolve duplicate Agent Skills by grouping equal or similar names across ~/.agents/skills, ~/.codex/skills, and ~/.claude/skills. Compare source metadata, instruction content, agent scope, update path, and local usage evidence. Keep the canonical copy and archive only the confirmed redundant path with recovery data.
Three kinds of overlap
| Pattern | Meaning | Review |
|---|---|---|
| Exact copy | Same purpose and matching content in two roots | Choose the path with the clearest ownership |
| Version drift | Same name with changed instructions or files | Identify the maintained source and inspect differences |
| Intentional variant | Shared name with agent-specific workflow details | Keep both when each has a defined consumer |
Name equality provides a useful first pass. Contents and scope determine the final decision. Two packages can reuse a generic name for different jobs, while renamed skills can contain nearly identical instructions.
Find overlapping names and locations
$ npx github:Ryan-yang125/skill-manager audit --jsonGroup inventory records by normalized name, then inspect every location. Keep full paths in the report because a root determines which agent can discover the skill.
Compare the candidates
- Source: package ID, repository, plugin, and whether metadata was inferred.
- Scope: shared root or agent-specific root.
- Content: frontmatter, full instructions, scripts, references, and assets.
- Freshness: modification or package update time.
- Evidence: matched sessions, last reference, and coverage boundary.
For an exact local comparison, hash the two files or compare their directories. A matching SKILL.md hash confirms that instruction text is equal at that moment; supporting scripts still need their own comparison.
$ shasum -a 256 /path/one/SKILL.md /path/two/SKILL.mdChoose the canonical copy
- Trusted, maintained source
- Correct root for the intended agent
- Current and readable instructions
- Clear package update route
- Usage evidence that matches the workflow
Precedence rule: agent loading order can evolve. Preserve both paths in your comparison and verify behavior in the agent after archiving one candidate.
Archive and verify
Preview one redundant path, archive it through the ledger, and re-run the inventory. Open the intended agent and exercise the workflow that uses the canonical copy. The archive remains available if a hidden dependency appears.
Duplicate skills FAQ
What counts as a duplicate Agent Skill?
Skills with the same name, purpose, or substantially similar instructions are candidates for review. Agent-specific behavior can justify separate copies.
Which copy should I keep?
Prefer the copy with a trusted source, correct scope, current content, recent evidence, and a clear update route.
Can I delete the extra folder directly?
A ledger-backed archive preserves the original path and recovery data, giving you a verifiable restore route.
See every location
Run the JSON audit, group matching names, and inspect provenance before changing a path.
Run Skill Manager