ms

<!-- 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.

## 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):

```bash
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:

```bash
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:

```bash
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:

```bash
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 path is useful only for diagnostics while its retrieval parity gap remains; in particular, zero CLI results do not prove the corpus has no matching skill.

---

## Write / Admin — CLI-only (verified landing in the live DB)

The MCP feedback tool exists, but **only the CLI write path is verified to land** — trust the CLI for writes.

```bash
ms feedback add <skill> --positive --comment "..."   # feedback on a skill
ms feedback add <skill> --negative --comment "..."

ms outcome <skill> --success   # record only AFTER downstream factory use + validation
ms outcome <skill> --failure

ms doctor                      # admin: health
scripts/ms-reindex.sh          # (re)index THE way: rebuild + sweep + probe + source-equivalence check
scripts/ms-reindex.sh --check-source  # read-only freshness proof against current skills/** source
# Optional operator policy only; rebuild completeness is derived from live
# discovered/indexed/errors accounting, not a historical absolute count:
MS_REINDEX_MIN_INDEXED=100 scripts/ms-reindex.sh
ms list -O jsonl --limit 1000  # counting / enumeration
ms config                      # resolved config + skill_paths
```

## Output Specification

- **Path:** search, load, and admin results are returned on `stdout`; durable index state remains under `~/Library/Application Support/ms/`.
- **Filename:** no result filename is created by this skill; callers capture CLI output explicitly when they need a durable artifact.
- **Format:** attached MCP returns structured tool data; the one-shot helper unwraps MCP content into clean search JSON; CLI automation uses JSON or JSONL, with full skill text at `.data.content` for `ms load --full -O json`.
- **Validation command:** run `skills/ms/scripts/validate.sh` for the retrieval boundary and `scripts/ms-reindex.sh --check-source` for normalized source equivalence.
- **Downstream handoff:** return the loaded guidance and source identity to the caller. Retrieval never chooses or starts a workflow.

## Production Skill Handoff

**Production-intent handoff:** When the query concerns creating or editing a skill, `ms` retrieves relevant guidance and stops. The caller may separately invoke `skill-builder` (create, heal, or audit mode) or an