Ultra-fast skill scanner with audit-based ranking, automatic promotion, and 9-tier leveling system.
irm https://raw.githubusercontent.com/your-repo/medusa/main/install.ps1 | iexcurl -SL https://raw.githubusercontent.com/your-repo/medusa/main/install.bat -o install.bat && install.batcurl -sSL https://raw.githubusercontent.com/your-repo/medusa/main/install.sh | bashStep 1: Install Rust
- Windows:
irm https://win.rustup.rs/x86_64 | iex(or download from https://rustup.rs) - macOS/Linux:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Step 2: Clone & Build
# All platforms (Windows CMD/PowerShell, macOS, Linux):
git clone https://github.com/your-repo/medusa.git
cd medusa
cargo build --releaseBinary Location:
| Platform | Binary Path |
|---|---|
| Windows | target\release\medusa.exe |
| macOS/Linux | target/release/medusa |
Step 3: Run
# Windows (CMD)
.\target\release\medusa.exe --help
# Windows (PowerShell)
.\target\release\medusa.exe --help
# macOS/Linux
./target/release/medusa --help| Feature | Description | Performance |
|---|---|---|
| Audit-Based Ranking | Measures complexity, value, technical depth | 9-tier system |
| Automatic Promotion | Skills rank up as they improve | No manual needed |
| Parallel Scanning | Rayon-powered concurrent processing | 46% faster (A/B tested) |
| Fusion Detection | Finds similar skills (name + content) | FxHash-powered |
| HTML Visualization | Dark-themed reports with progress bars | Interactive |
| A/B Test Framework | Validate performance claims scientifically | Statistical rigor |
| Dreaming Process | Cross-session pattern detection, recurring gaps, trends | Auto-records every scan |
| Memory Consolidation | Merges duplicates, prunes low-severity, caps at 200 | Runs after every dream |
| Outcomes Framework | Weighted rubric-based skill assessment | 4 default criteria |
| Learning Paths | Built-in fix suggestions mapped to gap patterns | Per-skill recommendations |
| Multi-Agent Orchestration | 4 specialized sub-audits (doc quality, code quality, dependencies, learning value) | Synthesized weighted scoring |
| Dream Diary | Narrative timeline of skill evolution with gap history | Console + Markdown export |
| Configurable Dreaming | Tune frequency, retention, auto-apply, max insights | Via medusa.toml |
| Procedural Memory | Auto-detects step-by-step workflows from skill content | 38 workflows from 36 skills |
| Cross-Agent Memory | Export/import dream + procedural + outcome bundles | Merge with source tracking |
# Windows (CMD)
.\target\release\medusa.exe scan C:\path\to\skills
# Windows (PowerShell)
.\target\release\medusa.exe scan C:\path\to\skills
# macOS/Linux
./target/release/medusa scan /path/to/skills# Windows
.\target\release\medusa.exe audit C:\path\to\skills
# macOS/Linux
./target/release/medusa audit /path/to/skillsExample Output:
=== Medusa Skill Audit Report ===
Skill: ai-ml (ai-ml), level: Godlike
Experience: 100.0/100
Confidence: 75%
Metrics:
- Content Length: 5966 chars
- Code Blocks: 15
- Step Instructions: 0
- Technical Terms: 26
- Complexity Score: 80.0/100
- Value Score: 90.0/100
# Windows (CMD)
.\target\release\medusa.exe html C:\path\to\skills C:\path\to\report.html
# Windows (PowerShell)
.\target\release\medusa.exe html C:\path\to\skills C:\path\to\report.html
# macOS/Linux
./target/release/medusa html /path/to/skills /path/to/report.htmlOpens a beautiful dark-themed visualization with:
- Skill bars showing experience levels
- Color-coded tiers (Godlike = Purple gradient, Unique = Orange gradient, etc.)
- Detailed metrics for each skill
- Fusion detection (similar skills)
# Windows (CMD)
.\target\release\medusa.exe ab-test C:\path\to\skills --iterations 20
# Windows (PowerShell)
.\target\release\medusa.exe ab-test C:\path\to\skills --iterations 20
# macOS/Linux
./target/release/medusa ab-test /path/to/skills --iterations 20Example Output:
Running A/B Test: Parallel vs Sequential Scan
Path: /path/to/skills
Iterations: 20
Hypothesis: Parallel scanning is faster than sequential
Primary metric: scan_time_ms
Iteration 1: Parallel=178ms, Sequential=362ms
Iteration 2: Parallel=187ms, Sequential=325ms
...
Iteration 20: Parallel=204ms, Sequential=391ms
=== A/B Test Results ===
Parallel avg: 190.00ms
Sequential avg: 352.00ms
β
Parallel is 46.0% faster
| Tier | Range | Color | Background |
|---|---|---|---|
| Godlike | 95+ | π΄ Red-Orange-Green | Gradient |
| Unique | 90+ | π΄ Red | Solid |
| Legendary | 85+ | π Pink-Purple | Solid |
| Mythic | 80+ | π£ Purple | Solid |
| Epic | 75+ | π‘ Yellow | Solid |
| Ultra Rare | 65+ | π’ Teal | Solid |
| Rare | 55+ | π΅ Blue | Solid |
| Uncommon | 45+ | π’ Green | Solid |
| Common | 25+ | βͺ Light Gray | Solid |
| Poor | <25 | β« Dark Gray | Solid |
medusa --helpOutput:
Medusa Skill Framework (MSF) v0.12 - Audit-Based Ranking with Context
Usage: medusa <command> [options]
Commands:
scan <path> Scan skills with FULL audit (60/30/10 scoring)
--sequential Use sequential scanning (no Rayon)
--no-cache Disable incremental scan cache
audit <path> Show detailed skill audit with cross-session context
--no-cache Disable cache
html <path> <output> Generate HTML visualization
--sequential Use sequential scanning
--no-cache Disable cache
export-csv <path> <f> Export skills to CSV format
export-md <path> <f> Export skills to Markdown
export-svg <path> <f> Export skills to SVG visualization
ab-test <path> Run A/B test (parallel vs sequential)
--iterations N Number of test iterations (default: 10)
dream <path> Run dreaming process (cross-session pattern detection)
dream-status <path> Show dream knowledge base and patterns
dream-reset <path> Reset dream state and history
dream-consolidate <path> Manually consolidate dream knowledge base
dream-diary <path> Show dream diary (narrative skill evolution timeline)
--output <file.md> Export diary as Markdown
dream-params <path> Show dreaming configuration parameters
orchestrate <path> Run multi-agent orchestrated audit (4 specialized sub-audits)
--sequential Use sequential scanning
--no-cache Disable cache
outcome-add <path> <id> Add default outcome rubric for a skill
outcome-list <path> List outcome rubrics
outcome-remove <path> <id> Remove an outcome rubric
learning-path <path> <id> Show learning path and suggestions for a skill
procedural-list <path> List all learned procedural workflows
procedural-show <p> <id> Show workflows associated with a skill
memory-export <p> <f> Export all memory (dream, procedural, outcomes) to JSON bundle
memory-import <p> <f> Import and merge a memory bundle from another Medusa instance
--source <name> Tag imported data with a source identifier
update Update Medusa from GitHub (git pull + rebuild)
Options:
--help, -h Show this help message
--version, -v Show version
SKILL.md files
β
[WalkDir] Scan filesystem (max depth 4)
β
[Rayon] Parallel processing (46% faster, optional)
β
[Regex] Extract YAML frontmatter
β
[Audit] Measure complexity (length, code, steps, terms)
β
[Score] Calculate experience (60% + 30% + 10%)
β
[Rank] Assign tier (Godlike β Poor)
β
[Fusion] Detect similar skills (FxHash)
β
[Session] Record snapshot for dreaming
β
[Dream] Cross-session pattern detection + consolidation
β
[Diary] Generate skill evolution timeline
β
[Agents] Multi-agent orchestrated sub-audits
β
[Outcomes] Rubric-based quality assessment
β
[Procedural] Extract step-by-step workflows
β
[Output] JSON / HTML / CSV / MD / SVG
| Platform | Binary | Build Command |
|---|---|---|
| Windows | medusa.exe |
cargo build --release |
| macOS (Intel) | medusa |
cargo build --release |
| macOS (Apple Silicon) | medusa |
cargo build --release |
| Linux (x86_64) | medusa |
cargo build --release |
| Linux (ARM64) | medusa |
cargo build --release |
No WSL required! Runs natively on all platforms.
medusa/
βββ src/
β βββ main.rs # CLI entry, scoring, reports (~1350 lines)
β βββ dream.rs # Dreaming, consolidation, diary, learning paths
β βββ outcomes.rs # Rubric CRUD, skill assessment
β βββ agents.rs # Multi-agent orchestrated audit (4 agents)
β βββ procedural.rs # Procedural workflow detection & memory
βββ target/
β βββ release/
β βββ medusa # Compiled binary
βββ Cargo.toml # Dependencies (minimal: 9 deps)
βββ medusa.toml # Configurable scoring + dreaming params
βββ README.md # This file
βββ TECHNICAL.md # Architecture deep-dive
βββ .medusa_state.json # Promotion state (auto-created)
serde β Struct serialization
serde_json β JSON output
toml β Config parsing
fxhash β Fusion hash computation
walkdir β Directory traversal
rayon β Parallel processing
regex β Pattern extraction
lazy_static β Regex compilation
chrono β Timestamps for dream sessions
Compile time: ~5 seconds (release, stripped) Binary size: ~2MB (Windows/Linux/macOS) No runtime dependencies! Single binary, just download and run.
# Windows
.\target\release\medusa.exe scan C:\Project\.opencode\skills
# macOS/Linux
./target/release/medusa scan ~/.hermes/skills# Windows
.\target\release\medusa.exe audit C:\Project\.opencode\skills\ai-ml
# macOS/Linux
./target/release/medusa audit ~/.hermes/skills/ai-mlShows detailed breakdown:
- Why it's ranked "Godlike"
- Content length, code blocks, step count
- Technical term density
- Complexity and value scores
# Windows
.\target\release\medusa.exe html C:\Project\.opencode\skills C:\Project\medusa\report.html
# macOS/Linux
./target/release/medusa html ~/.hermes/skills ~/report.html# Shows WHY it's at its tier
medusa audit /path/to/skills/ai-mlExample Output:
=== Medusa Skill Audit Report ===
Skill: ai-ml (ai-ml), level: Godlike
Experience: 100.0/100
Confidence: 75%
Metrics:
- Content Length: 5966 chars
- Code Blocks: 15
- Step Instructions: 0
- Technical Terms: 26
- Complexity Score: 80.0/100
- Value Score: 90.0/100
# Windows
.\target\release\medusa.exe html C:\path\to\skills report.html
# Mac/Linux
./target/release/medusa html /path/to/skills report.htmlOpens in browser with:
- Dark theme (hacker style)
- Color-coded skill cards
- Experience progress bars
- Fusion detection section
A/B Test Results (36 skills, 20 iterations):
- Parallel (Rayon): 190ms average
- Sequential: 352ms average
- Speedup: 46% faster
Scalability:
- 36 skills scanned in ~150ms
- Linear scaling with Rayon parallelization
- Memory-efficient (no unnecessary copies)
# One-line update (pull latest + rebuild)
cd /path/to/medusa && git pull && cargo build --releaseOr use the built-in update command:
medusa updateAfter installation, verify it works:
# Windows (CMD)
.\target\release\medusa.exe --version
# Windows (PowerShell)
.\target\release\medusa.exe --version
# macOS/Linux
./target/release/medusa --versionExpected output:
Medusa Skill Framework (MSF) v0.12.1
# Windows: medusa scan C:\Project\.opencode\skills
# macOS/Linux:
./target/release/medusa scan ~/.hermes/skillsShould output JSON with skills audit.
Traditional skill systems use static rankings (you manually set the level).
Medusa uses audit-based ranking:
- Measures actual skill complexity (content, code, steps, terms)
- Calculates objective experience score (60% complexity + 30% value)
- Assigns tier automatically (Godlike β Poor)
- Promotes as you improve (just edit SKILL.md, next scan updates!)
No manual promotion commands needed!
MIT License (or your choice)
- v0.12 (Current): Multi-agent orchestration, dream diary, configurable dreaming, procedural memory, cross-agent memory sharing + all Phase 1 features
- v0.11: 9-tier leveling system (Godlike β Poor), rank promotion system
- v0.5.0: Rank promotion system
- v0.4.0: CLI improvements, A/B test framework
- v0.3.0: Fusion detection, HTML visualization
- v0.2.0: Parallel scanning with Rayon
- v0.1.0: Initial release
Built with Rust π¦ + Rayon β‘ + Regex π

