perfect-skill-suggester

Perfect Skill Suggester (PSS)

Installation: This plugin is distributed via the Emasoft Plugins Marketplace. See Installation below for instructions.

Claude Code version support: PSS tracks CC compatibility in docs/CC-COMPATIBILITY.md — see it for the full version-by-version matrix, declared hook events, and migration notes.

---

Built for Claude Code | Orchestrated by AI Maestro | Part of the Emasoft Plugins ecosystem

High-accuracy skill activation (88%+) for Claude Code with AI-analyzed keywords, weighted scoring, synonym expansion, and three-tier confidence routing. Indexes 6 element types: skills, agents, commands, rules, MCP servers, and LSP servers — 874+ elements including 246 MCP servers.

What's New (last 3 releases)

v3.6.12 — 2026-05-16

• rust: Bump submodule for F-12 version-history subcommand — focused "what versions has this element gone through?" history, filtered to signal events (installed, content_changed, description_changed, removed) with content hash and diff JSON per row.

v3.6.11 — 2026-05-16

• rust: Bump submodule for F-17 / F-18 / F-19 Tier B subcommands — changes-in-batch, last-changes, and stats-by-scope for inspecting a single reindex's event set and counting elements per scope.

v3.6.10 — 2026-05-16

• rust: Bump submodule for F-6 scope-diff + UX-6 similarity score — surfaces what's in scope A but not in scope B (and vice versa), plus a similarity score on pss compare output.

Full history: CHANGELOG.md

Features

Multi-Type Element Indexing

Indexes all 6 Claude Code element types — not just skills. The unified index powers both real-time hook suggestions and AI-driven agent configuration profiling.

Cross-Client Skill Discovery

Scans skills from 27 known AI clients beyond Claude Code — including Codex, Copilot, Gemini, Kiro, Roo, Trae, Qwen, OpenHands, and more. Follows the AgentSkills open standard for cross-client interoperability. Skills with metadata fields (language, framework, platform, tags) get authoritative domain gates for more precise matching.

AI-Analyzed Keywords

Sonnet subagents analyze each element's source file to extract optimal activation patterns. Instead of relying on manually defined keywords, the AI reads the content and determines what user prompts should trigger it.

MCP Server Auto-Discovery

Automatically discovers and indexes MCP servers from installed marketplace plugins (~250+ servers). Each MCP server entry includes AI-extracted tools, domain gates, patterns, and multi-word keyword phrases for precise matching.

Native Rust Binary (~10ms)

A pre-compiled Rust binary handles all matching logic, keeping hook latency minimal. No Python interpreter startup, no JIT compilation - just fast native code.

Synonym Expansion (70+ patterns)

User prompts are expanded with synonyms before matching. For example:

• "pr" → "github pull request"
• "403" → "oauth2 authentication"
• "db" → "database"
• "ci" → "cicd deployment automation"

5-Tier Logarithmic Scoring

Each match signal occupies a tier that is 10x more powerful than the one below it. A single tool match always outranks any number of generic keyword matches. See How It Works for the full rationale.

Tier	Range	Examples
T1	10-90	Common words: "test", "build", "debug"
T2	100-900	Specific keywords/phrases
T3	1,000-9,000	Tool names: bun, webpack, docker
T4	10,000-90,000	Frameworks: react, django, flutter
T5	100,000-900,000	Services/APIs: aws, openai, stripe

Binary Filters (Languages, Platforms, Domains)

When the prompt mentions a language, platform, or domain, skills locked to a different value are excluded entirely (not penalized). A Rust-only skill never appears for a Python prompt, regardless of other matches.

Commitment Mechanism

For HIGH confidence matches, output includes an evaluation reminder prompting Claude to pause and assess whether the skill truly fits the user's needs before blindly following instructions.