/ms

name: ms
description: 'Find and load guidance with the meta_skill search engine. Use when: searching a skill corpus; CASS owns past sessions and Skill Builder owns package authoring.'
practices:
- pragmatic-programmer
skill_api_version: 1
user-invocable: true
hexagonal_role: supporting
consumes: []
produces: []
context_rel: []
metadata:
  dependencies: []
  capabilities: [ms]
  effects: [spawn_search_server, write_feedback_outcomes, rebuild_search_index]
  canonical_status: canonical
  disposition: keep_optional_adapter
  tier: execution
  external_dependencies:
  - "ms binary (Jeffrey Emanuel's meta_skill). The 0.1.2 release binary corrupts IDs on Anthropic-frontmatter skills, so it must be built from a source checkout carrying the frontmatter-id fix; this operator builds from ~/dev/meta_skill, branch local/frontmatter-id."
  - jq (required for parsing -O json output)
  - python3 (required by the disposable MCP search helper)
output_contract: search and load results plus source identity on stdout; the local index is disposable state, never a source of truth

<!-- TOC: Core Insight | Constraints | Quick Start | Consume (MCP) | Write/Admin (CLI) | Output | Production Skill Handoff | Footguns | Concurrency | Scenarios | Quality | References -->

ms — meta_skill search/load engine

> **Core Insight:** `ms` is the skill-search engine over both configured corpora (agentops + jsm). **Consume via MCP, write/admin via CLI.** One law: after ANY reindex/wipe, every running `ms mcp serve` MUST be killed (sessions respawn fresh). A surviving server silently reads pre-wipe data and returns `recorded:true` on writes that land in orphaned files.

Constraints

• Load with `full: true` or `--full` when the intent is to execute a skill, because metadata cards and packed overviews omit runnable guidance.
• Keep the consume/write boundary explicit: use MCP for search and load, but use the CLI for feedback and outcomes because only CLI writes are verified to land in the live database.
• When attached `mcp__ms__*` tools are unavailable, use the skill-local one-shot MCP helper for search. A zero-result `ms search` CLI response is not evidence that MCP BM25 found no match and must not silently substitute for it.
• Reindex only through `scripts/ms-reindex.sh`, because it sweeps stale servers and proves source equivalence after rebuilding the index.
• Treat the local index as disposable state, not a source of truth; the non-goal is editing indexed content instead of `skills/**`.
• Keep `ms` retrieval-only for production skill work. It returns search and load

results; the caller owns authoring, validation, and every subsequent decision.

Session evidence and instruction changes

For a requested instruction-improvement task, use CASS to discover relevant episodes and `ms` to find existing guidance that could explain the behavior or already address it. Load only the relevant skills, then inspect their canonical source before proposing an edit. An `AGENTS.md` or task-prompt change does not require inventing a skill or loading an unrelated one.

Upstream MS also offers `build --from-cass`; this adapter deliberately does not invoke that authoring path. Inspect `ms build --help` if the caller selects it separately. A generated skill, search rank, repeated prompt, or recorded outcome is not proof of downstream improvement.

CASS search/pack supplies candidate evidence. Use AO's bounded excerpt view only when the investigation needs exact raw spans, literal fields or instruction identity that the selected CASS output does not establish. These are optional capabilities, not a required sequence on every task. The caller owns a supported candidate edit or no-change judgment, independent review and later usefulness testing; retrieval never awards that outcome itself.

Quick Start

Find a skill (MCP-primary — BM25, currently strictly better than CLI search), then load the FULL runnable SKILL.md in one call (always `full: true` when you mean to use it):

mcp__ms__search {query: "handle a rate limit switching accounts"}
mcp__ms__load {skill: "account-rotation", full: true}

No attached MCP tool: start one disposable stdio server, return only the structured search JSON, and reap it on success, error, or timeout:

python3 skills/ms/scripts/mcp-search.py "switch accounts on rate limit"
ms load account-rotation --full -O json | jq -r '.data.content'

State root: `~/Library/Application Support/ms/`.

---

Consume — MCP-primary (`mcp__ms__*`)

Prefer the MCP tools whenever a `ms mcp serve` is attached — they are the fast, verified read path.

| Tool | Use | |------|-----| | `mcp__ms__search {query}` | BM25 search. **Currently strictly better than CLI search** (see Footguns — CLI hybrid is BM25-only; ms never stores doc embeddings). | | `mcp__ms__load {skill, full: true}` | Returns the full runnable SKILL.md in ONE call, zero extraction friction. **`full: false` returns a useless metadata card — always `full: true` when you intend to use the skill.** | | `mcp__ms__show {skill}` | Metadata card for a skill. | | `mcp__ms__suggest {cwd}` | Suggests skills for a directory. Works — but **ignore its project-language detection** (misdetects Makefile repos as C; cosmetic only). |

**No attached MCP tool:** use the server-backed one-shot helper so retrieval still follows the MCP BM25 path:

python3 skills/ms/scripts/mcp-search.py "<query>"

The helper writes a clean search object (`query`, `count`, `results`) to stdout, reports transport/protocol errors on stderr, applies a 30-second timeout by default, and owns the disposable server process group through termination and reap. Override its executable with `MS_BIN` and its timeout with `MS_MCP_SEARCH_TIMEOUT` or `--timeout`.

The CLI remains the supported full-load fallback after search:

ms load <id> --full -O json | jq -r '.data.content'   # content lives in .data.content

Do not replace the helper with `ms search`. The CLI