zeph-skills

SKILL.md parser, registry, embedding matcher, and hot-reload for Zeph.

Overview

Parses SKILL.md files (YAML frontmatter + markdown body) from the .zeph/skills/ directory, maintains an in-memory registry with hot-reload support, and formats selected skills into LLM system prompts. Supports semantic matching via Qdrant embeddings and self-learning skill evolution with trust scoring. Multi-language feedback detection (7 languages) drives trust transitions across all skills.

Key modules

Re-exports: SkillError, SkillTrust, TrustLevel (from zeph-tools), compute_skill_hash

Prompt modes

The prompt_mode config option ([skills] section) controls how skills are serialized into the LLM system prompt:

All modes include reliability="N%" and uses="N" XML attributes derived from the Wilson score posterior, so the model is aware of each skill's historical reliability.

Self-learning and re-ranking

Skills accumulate outcomes over time. After each use, the Wilson score lower-bound is recomputed and stored as posterior_weight and posterior_mean. check_trust_transition() evaluates whether accumulated evidence justifies a trust level change:

• Sufficient high-quality outcomes → promote toward Trusted
• Repeated failures or rejections → demote toward Quarantined

The /skill reject <name> <reason> command records a typed FailureKind rejection immediately, persisting it to the outcome_detail column (migration 018).

Feedback signals are detected by FeedbackDetector in zeph-core, which now supports 7 languages (English, Russian, Spanish, German, French, Portuguese, Chinese). Multi-language implicit correction detection drives skill trust transitions regardless of the user's language.

Hybrid search configuration

[skills]
cosine_weight            = 0.7   # weight of cosine similarity in RRF fusion (default: 0.7)
hybrid_search            = true  # enable BM25 + cosine hybrid search (default: true)
disambiguation_threshold = 0.20  # minimum score gap for skill disambiguation (default: 0.20, was 0.05 before v0.18.2)
min_injection_score      = 0.20  # minimum match score for skill injection into the prompt (default: 0.20)

Note: disambiguation_threshold default changed from 0.05 to 0.20 in v0.18.2 — this reduces false-positive skill injections for low-confidence queries. min_injection_score is a new field that gates injection independently of disambiguation.

Note: When hybrid_search = true, BM25 keyword scores are computed locally and fused with Qdrant cosine scores using Reciprocal Rank Fusion. This improves recall for exact-match queries while preserving semantic ranking quality for paraphrase queries.

D2Skill step-level error correction

D2Skill (Dynamic Diagnostic Skill) tracks step-level execution outcomes within multi-step skills. When a step fails, the error context and correction are persisted via insert_step_correction so subsequent invocations can pre-empt the same failure. Corrections are embedded and retrieved by cosine similarity during skill execution.

SkillOrchestra RL routing head

SkillOrchestra uses a RoutingHead (LinUCB contextual bandit) to select which skill variant to invoke. The routing head maintains per-skill weight vectors and a shared baseline; after each invocation, it updates weights based on the observed reward signal. Enable via rl_routing_enabled = true in [skills].

[skills]
rl_routing_enabled = true

NL skill generation and GitHub repo mining

SkillGenerator accepts a natural language description and produces a complete SKILL.md file via LLM generation. SkillMiner searches GitHub repositories for tool-use patterns and converts them into candidate skills. The STEM heuristic (should_generate_skill) monitors tool-call sequences and triggers automatic skill generation when a pattern recurs above a configurable threshold.

Confusability detection

SkillMatcher::confusability_report identifies pairs of skills whose embeddings are close enough to cause ambiguous matching. The report includes the cosine similarity score and both skill names, helping skill authors disambiguate overlapping definitions.

Injection sanitization

The scanner module detects prompt injection patterns in SKILL.md content at load time. Detected patterns are flagged and mitigated before the skill enters the registry.

Installation

cargo add zeph-skills

Documentation

Full documentation: https://bug-ops.github.io/zeph/

License

MIT