ms

Meta Skill (ms) is a local-first skill management platform that turns operational knowledge into structured, searchable, reusable artifacts. It provides dual persistence (SQLite + Git), hybrid search (lexical + semantic), adaptive suggestions with bandit optimization, multi-layer security (prompt injection defense + command safety gates), dependency graph analysis, provenance tracking, and native AI agent integration via MCP.

Quick Install

cargo install --path .

Or run without installing:

cargo run -- <COMMAND>

Works on Linux, macOS, and Windows. Requires Rust 1.85+ (Edition 2024).

What ms Actually Is

ms is not just a tool for extracting skills from AI sessions. It's a complete skill management platform with these core capabilities:

Skills can come from anywhere: hand-written SKILL.md files, mined from CASS sessions, imported from bundles, or generated through guided workflows. The CASS integration is one input method, not the defining feature.

Quick Example

# Initialize a local ms root (.ms/)
ms init

# Configure skill paths
ms config skill_paths.project '["./skills"]'

# Index SKILL.md files
ms index

# Search and inspect
ms search "error handling"
ms show rust-error-handling

# Get context-aware suggestions
ms suggest

# Analyze skill dependencies
ms graph insights

# Start MCP server for AI agent integration
ms mcp serve

Why This Architecture

Dual Persistence: Speed + Accountability

Every skill is stored twice:

• SQLite for fast queries, filtering, full-text search, and metadata operations
• Git archive for immutable history, diffs, and audit trails

This mirrors how production systems balance operational speed with accountability. SQLite handles the "what do I need right now?" questions in milliseconds. Git answers "what happened and why?" when you need provenance.

The split also enables resilience: if the database corrupts, skills can be rebuilt from Git. If Git history is unavailable, the database still serves queries. Neither persistence layer is privileged—they serve different needs equally well.

Hash Embeddings: Semantic Search Without Dependencies

Semantic search matters because keywords fail on phrasing differences. "Error handling" and "exception management" should match. But external embedding models create dependencies, latency, and reproducibility problems.

ms uses deterministic hash embeddings: FNV-1a based, 384 dimensions, computed locally. The same text produces the same vector on any machine, any time, with no model downloads or API calls. Combined with BM25 lexical search and RRF fusion, this gives both precision (exact matches) and recall (conceptual matches) without external dependencies.

Why RRF (Reciprocal Rank Fusion)? Because merging by raw scores is unstable—BM25 scores and embedding similarities have different scales and distributions. RRF uses rank positions instead, which normalizes the signals and produces stable, predictable rankings regardless of query type.

Bandit Optimization: Learning What Works

Static ranking systems can't adapt. The suggestion engine uses a Thompson sampling bandit that learns from feedback:

• Each signal type (BM25 score, semantic similarity, recency, feedback rating, etc.) is an "arm"
• Success/failure feedback updates beta distributions for each arm
• UCB exploration bonus prevents premature convergence
• Context modifiers adjust weights based on project type, time of day, and other factors

Over time, the system learns which signals matter for your workflow. A team that values recency will see recency weighted higher. A codebase where semantic matches outperform keywords will shift accordingly. This isn't magic—it's a well-understood algorithm applied to a problem that benefits from continuous learning.

Multi-Layer Security: Defense in Depth

AI-assisted workflows create new attack surfaces. ms implements defense at multiple layers:

ACIP (Agent Content Injection Prevention): Classifies content by trust boundary (user/assistant/tool/file) and quarantines prompt injection attempts. Disallowed content is stored with safe excerpts for review, not silently dropped. Replay is opt-in and requires explicit acknowledgment.

DCG (Destructive Command Guard): Evaluates shell commands before execution. Commands are classified into tiers (Safe/Caution/Danger/Critical) with configurable approval requirements. Dangerous commands can require verbatim approval through environment variables.

Path Policy: Prevents symlink escapes and directory traversal attacks. All file operations validate paths against allowed roots.

Secret Scanning: Detects and redacts credentials, API keys, and PII before content enters the system.

Graph Analysis via bv: Use the Right Tool

Skill dependencies form a graph. Rather than implement graph algorithms from scratch, ms converts skills to a beads-style JSONL format and delegates to bv (beads_viewer):

• PageRank identifies keystone skills that anchor many others
• Betweenness centrality finds bottlenecks that block progress
• Cycle detection surfaces circular dependencies
• Critical path analysis generates execution plans with parallel tracks
• HITS algorithm distinguishes authoritative skills from hubs

This is the same philosophy as using SQLite for queries: use battle-tested tools for what they do best, keep the core focused. bv has the graph algorithms; ms has the skill semantics.

Effectiveness as Data, Not Anecdotes

Usage feedback, outcomes, experiments, and quality scores are stored as structured data:

• Feedback: Explicit signals (helpful/unhelpful, ratings, comments) linked to skills
• Outcomes: Success/failure markers for suggestions that were acted upon
• Experiments: A/B test records tracking variant performance
• Quality Scores: Session quality signals (tests passed, clear resolution, backtracking, abandonment)

This transforms "this skill seems useful" into measurable evidence. The bandit learns from it. Prune commands can use it. Graph analysis can weight by it. Quality signals inform which sessions are worth mining.

MCP Server: Native AI Agent Integration

Rather than force AI agents to parse CLI output, ms exposes a proper MCP (Model Context Protocol) server:

ms mcp serve              # stdio transport for Claude Code
ms mcp serve --port 8080  # HTTP transport for other integrations

The server exposes six tools that agents can call directly: - search: Query skills with hybrid search - load: Retrieve skill content with progressive disclosure - evidence: Get provenance for a skill - list: Enumerate available skills - show: Full skill details - doctor: Health check

This means Claude, Codex, and other MCP-aware agents can use ms as a native tool, not a string-parsing exercise.

Skill Sources

Skills can enter the system through multiple paths:

1. Hand-Written SKILL.md Files

Write skills directly as markdown:

# Rust Error Handling

Best practices for error handling in Rust projects.

## Overview

Use `Result<T, E>` and propagate errors with `?`. Define custom error types for domain logic.

## Examples

```rust
fn read_config(path: &str) -> Result<Config, ConfigError> {
    let contents = std::fs::read_to_string(path)?;
    toml::from_str(&contents).map_err(ConfigError::Parse)
}
```

## Guidelines

- Prefer `thiserror` for library errors, `anyhow` for application errors
- Always include context when wrapping errors
- Use `expect()` only when panic is the correct response

2. CASS Session Mining

Extract patterns from prior AI agent sessions:

# Single-shot extraction
ms build --from-cass "error handling" --since "7 days"

# Guided workflow with checkpoints
ms build --guided --from-cass "authentication"

The extraction pipeline: 1. Searches CASS for relevant sessions 2. Applies quality filters (clear resolution, tests passed, no backtracking) 3. Extracts patterns with uncertainty quantification 4. Synthesizes into structured skill format 5. Links evidence back to source sessions

3. Bundle Import

Install pre-packaged skill sets:

ms install https://example.com/team-skills.msb
ms bundle install ./local-bundle.msb

Bundles are verified with checksums and per-file hashes. Updates are gated by local modification detection so user edits are not overwritten by surprise.

4. Multi-Machine Sync

Pull skills from configured remotes:

ms remote add origin git@github.com:team/skills.git --remote-type git --auth ssh
ms sync

Sync with JeffreysPrompts Premium Cloud:

ms remote add jfp https://pro.jeffreysprompts.com/api/ms/sync \
  --remote-type jfp-cloud \
  --auth token \
  --token-env JFP_CLOUD_TOKEN
ms sync

Core Commands

Global flags work with all commands:

--robot     # JSON output to stdout (for automation)
--verbose   # Increase logging verbosity
--quiet     # Suppress non-error output
--config    # Explicit config path

Initialization and Configuration

ms init                              # Create .ms/ in current directory
ms init --global                     # Create in ~/.local/share/ms/
ms config                            # Show current config
ms config skill_paths.project '["./skills"]'
ms config search.use_embeddings true

Indexing and Discovery

ms index                             # Index all configured skill paths
ms index ./skills /other/path        # Index specific paths
ms list                              # List all indexed skills
ms list --tags rust --layer project  # Filter by tags/layer
ms show rust-error-handling          # Full skill details
ms show rust-error-handling --meta   # Metadata only

Search

ms search "error handling"           # Hybrid search (BM25 + semantic + RRF)
ms search "async" --search-type bm25 # Lexical only
ms search "async" --search-type semantic  # Semantic only

Loading and Suggestions

ms load rust-error-handling --level overview  # Progressive disclosure
ms load rust-error-handling --pack 2000       # Token-constrained packing
ms load rust-error-handling --pack 800 --contract debug   # Contracted packing (debug/refactor/learn/quickref/codegen)
ms suggest                           # Context-aware recommendations
ms suggest --cwd /path/to/project    # Explicit context

Context-Aware Auto-Loading

Automatically load relevant skills based on your current project context:

ms load --auto                       # Auto-detect and load relevant skills
ms load --auto --threshold 0.5       # Only load skills scoring above 0.5
ms load --auto --dry-run             # Preview what would be loaded
ms load --auto --confirm             # Prompt before loading each skill

Auto-loading analyzes your project to determine relevant skills:

• Project detection: Identifies Rust, Node.js, Python, Go, etc. from marker files
• File patterns: Matches recently modified files against skill file patterns
• Tool detection: Checks for installed tools (cargo, npm, pip, etc.)
• Context signals: Scans file content for framework/library patterns

Skills can specify context requirements in their frontmatter:

---
name: rust-error-handling
context:
  project_types: [rust]
  file_patterns: ["*.rs"]
  tools: [cargo, rustc]
  signals:
    - pattern: "use thiserror"
      weight: 0.8
---

Configuration options in config.toml:

[auto_load]
learning_enabled = true      # Enable bandit learning from feedback
exploration_rate = 0.1       # Rate of exploration for new skills
bandit_blend = 0.3           # Blend factor for learned vs computed scores
cold_start_threshold = 10    # Min uses before trusting learned weights
persist_state = true         # Save bandit state between sessions

Pack Contracts

Pack contracts let you persist custom packing rules (required groups, weights, max-per-group) and reuse them across sessions.

```bash ms contract list # Show built-in + custom contracts ms contract create debug-lite \ --description "Slim debug pack" \ --required pitfalls,rules \ --group-weight pitfalls:2.0 \ --group-weight rules:1.2

ms load rust-error-handling --pack 800 --contract debug # Built-i