Audit, reorganize, and manage skills, agents, plugins, commands, and rules across AI runtimes with a canonical-source-aware, skillshare-aware pipeline. Use when the user wants to clean up a skill library, compare skill installs across Claude/Codex/ Cursor/Gemini/Factory/Craft Agent, detect drift, analyze routing collisions, or make safe merge/archive/delete plans. Also use for requests about the canonical source of truth under ~/.config/skillshare/skills, sync drift against downstream installs, skill inventory, overlap analysis, canonical-vs-install reports, or any rollback-safe skill ecosystem maintenance task. This skill should cover both machine-wide broad sweeps where skills live across many runtimes and unified skillshare setups where one source library distributes to downstream targets.
Systematic audit and maintenance pipeline for a growing AI agent skill library. Treat skills as composable infrastructure, with explicit distinction between:
This upgraded version is designed for a skillshare-based setup where the canonical skill library lives at:
/Users/kosta/.config/skillshare/skillsand distribution targets are defined in:
/Users/kosta/.config/skillshare/config.yamlPhases 0–8 are analysis-only. They read files, run scripts, and produce JSON, markdown, and visual reports. They do not modify source or installed skills.
Phase 9 (Execute) is the only phase that changes anything, and it requires explicit user approval.
Use this when the user wants to understand skills by installed runtime location.
Questions this mode answers:
Use this when the user wants analysis of the source-of-truth skill library.
Questions this mode answers:
~/.config/skillshare/skills?When in doubt, ask whether the user wants a runtime view or a canonical source view. If they mention skillshare or ~/.config, prefer canonical mode.
The bundled scripts should support both paths:
Default behavior should auto-detect canonical mode when the scanned data includes the configured skillshare source. Otherwise, fall back to broad-sweep.
Choose the lightest mode that answers the user’s question.
runtime-auditUse for installed-library cleanup within and across runtimes.
canonical-auditUse for source-of-truth analysis centered on ~/.config/skillshare/skills.
sync-driftUse when the user wants to know what is in sync, out of sync, install-only, or undistributed.
distribution-topologyUse when the user wants a map of canonical source → targets → installed copies.
cleanup-candidatesUse when the user wants archive/delete/promote/regenerate recommendations.
full-library-auditRun the whole upgraded pipeline.
If the user does not specify a mode:
canonical-audit when the request names skillshare, ~/.config/skillshare/skills, or downstream target driftruntime-audit for machine-wide cleanup or “what is installed where?” questionsRead FEEDBACK.md before every use to apply lessons from prior audits.
FEEDBACK.md.Load only the references needed for the active question.
| Reference | Load when... |
|---|---|
FEEDBACK.md | Always |
references/analysis-framework.md | Relationship mapping and similarity reasoning |
references/canonical-library-mode.md | Canonical source-of-truth or ~/.config analysis |
references/skillshare-topology.md | Reading skillshare config and target topology |
references/distribution-drift.md | Sync drift / canonical-vs-install questions |
references/capability-taxonomy.md | Capability extraction and overlap analysis |
references/routing-collision-guide.md | Trigger and routing collision analysis |
references/blocklist.md | Skills that should be treated as hands-off by cleanup actions |
references/action-scoring.md | Merge/archive/delete/sync/promote scoring |
references/reporting-guide.md | Final report and visual structure |
references/merge-protocol.md | Execute phase only |
Do not collapse these into one concept:
Two same-named skills in different places are not automatically merge candidates.
A drifted install is primarily a sync problem, not a merge problem.
Skills named in references/blocklist.md should be treated as protected: report on them if needed, but do not recommend merge, rewrite, archive, or delete actions by default.
Phase 0: Discovery
Phase 1: Inventory
Phase 2: Skillshare / Canonical Topology
Phase 3: Canonical vs Install Drift Analysis
Phase 4: Relationship Map
Phase 5: Similarity Analysis
Phase 6: Capability / Trigger / Routing Analysis
Phase 7: Safety + Action Scoring
Phase 8: Visualize + Report
Phase 9: Execute (approved only)
Map the entire skill ecosystem.
Use the discovery script to identify:
For each item, record:
Roles should include:
Extract frontmatter and structural metadata.
Also capture:
Load references/canonical-library-mode.md and references/skillshare-topology.md.
Read:
~/.config/skillshare/config.yamlTreat:
~/.config/skillshare/skillsas the canonical source when the user wants canonical analysis.
Generate:
Load references/distribution-drift.md.
Compare canonical skills against downstream installs.
Classify each source/target pair as:
in-syncout-of-syncinstall-onlyundistributed-sourcemissingImportant: drift is a distribution problem first. Do not jump to merge or delete.
Load references/analysis-framework.md.
Preserve the existing strong concepts here:
Run:
Keep these distinct:
Do not recommend merging canonical source with downstream install copies.
Load references/capability-taxonomy.md and references/routing-collision-guide.md.
Extract:
This phase should reduce false merges by separating:
Load references/action-scoring.md.
Every skill should end with one primary action.
Preferred action set:
Use canonical-aware logic:
Load references/reporting-guide.md.
Produce machine-readable outputs first, then markdown and visuals.
Preferred JSON outputs:
skill-discovery.jsonskill-inventory.jsonskill-capabilities.jsonskill-topology.jsoncanonical-vs-install.jsondistribution-matrix.jsonduplicate-clusters.jsonsimilarity-clusters.jsonrouting-collisions.jsondelete-candidates.jsonaction-plan.jsonvisual-data.jsonPreferred visuals:
Load references/merge-protocol.md.
Only after approval.
Execution order should be:
This prevents syncing garbage or deleting the wrong copy.
Use these scripts for deterministic work:
scripts/discover_skills.pyscripts/inventory_to_json.pyscripts/analyze_skillshare_topology.pyscripts/compare_canonical_vs_installs.pyscripts/extract_skill_capabilities.pyscripts/cluster_skill_duplicates.pyscripts/cluster_skill_near_duplicates.pyscripts/detect_routing_collisions.pyscripts/score_skill_actions.pyscripts/score_skill_delete_candidates.pyscripts/build_distribution_matrix.pyscripts/render_skill_cleanup_manifest.pyscripts/render_skill_visual_data.pyPrefer visuals heavily. This skill is about topology and drift, not just prose.
The final report should include:
skill-creator).