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

```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 another authoring tool.

**Authority boundary:** `skills/**` is canonical source; the generator owns the `ms` Codex twin and other projections. Never edit the index, loaded copies, or generated projections as source.

`ms` never validates or interprets downstream work. A failed search,
load, write, or reindex is returned as evidence and ends this invocation.

**Outcome timing:** Record `ms outcome` only after the caller has independent evidence about downstream usefulness, never after retrieval alone. That observation does not change core state.

---

## Footguns (measured through 2026-07-15)

| Footgun | Truth |
|---|---|
| **MCP server survives a DB wipe/reindex** | An `ms mcp serve` NEVER reopens handles — it follows renamed inodes into the backup, giving stale reads AND silent misdirected writes (`recorded:true` into orphaned files). **Reindex via `scripts/ms-reindex.sh` — THE way to reindex** (rebuilds, proves every live-discovered skill was indexed or reported as an allowed error, TERMs every server, probes a fresh server, then compares normalized local loads with current `skills/**` source); never run bare `ms index` and leave servers up. Sessions respawn fresh. |
| **`ms load --pack N`** | Trap: caps at the gutted `overview` tier for ANY N (`800` == `20000`) — drops the executable steps and returns LESS than the no-flag default. Use `--full` (CLI) or `full: true` (MCP). |
| **`-O plain`** | Prints name-only on `load`; truncates list output (`[N more lines]`). The content lives in `-O json` → `.data.content`. |
| **CLI `ms search` "hybrid"** | Effectively BM25-only — ms never stores doc embeddings (`upsert_embedding` is called only from a unit test), so hybrid ≡ BM25 under ANY backend; no config/backend change fixes it (upstream gap, feature-noted; measured 2026-07-02, age-s3jf). It can return zero while MCP BM25 returns ranked matches. Without attached tools, use `scripts/mcp-search.py`; never treat zero CLI results as a successful MCP fallback. |
| **Stale `ms.lock`** | `ms doctor` prints "Lock held" for a DEAD pid yet still says all-pass. A dead-pid lock is safe to delete. |
| **Symlinks** | ms does NOT follow directory symlinks — `skill_paths` must list BOTH roots explicitly: the `~/.claude` skills dir AND the `~/dev/agentops/skills` repo dir. |
| **Binary** | Source build only (`~/dev/meta_skill`, branch `local/frontmatter-id`); the 0.1.2 release binary corrupts IDs on Anthropic-frontmatter skills. Update: `git fetch && git rebase origin/main && cargo install --path . --locked`. |

## Concurrency

Parallel CLI + MCP `load` measured clean — no lock errors. The lock hazard is the survive-a-wipe case above (kill the serve), not concurrent reads.

---

## Scenarios

```gherkin
Scenario: Load a skill's full runnable guidance
  Given an ms mcp serve is attached
  When I call mcp__ms__load {skill: "account-rotation", full: true}
  Then the full runnable SKILL.md content is returned in one call

Scenario: Search without an attached MCP tool
  Given mcp__ms__search is unavailable
  When I run python3 skills/ms/scripts/mcp-search.py with the query
  Then it returns only structured MCP search JSON
  And its disposable ms mcp serve process is reaped on success, error, or timeout

Scenario: Reindex invalidates every running server
  Given one or more ms mcp serve processes are running
  When I run ms index (or wipe/rebuild the DB)
  Then I kill every ms mcp serve so sessions respawn against fresh data
  And a surviving server would silently read pre-wipe data and mis-land writes

Scenario: A stale local projection fails closed
  Given AgentOps skills are authoritative and ms is a disposable local index
  When a full ms load has a different normalized name or description from source
  Then scripts/ms-reindex.sh exits nonzero and names the stale skill
```

## Quality Checklist

- Full loads preserve the complete runnable guidance rather than a metadata card or packed overview.
- Search reads use attached MCP tools or the one-shot MCP helper, never a silent zero-result CLI substitution; full loads use MCP or the verified CLI shape.
- Any rebuild accounts for every live-discovered skill, rejects an empty searchable index, then finishes with stale servers swept and source equivalence reported.
- Production skill intent leaves `ms` after retrieval; generated twins and loaded/indexed copies are never hand-edited as source.
- Search and load results remain advisory inputs, never proof that downstream work is correct.
- `ms outcome` records observed usefulness only after independent downstream evidence.

## References

- Upstream: Jeffrey Emanuel's `meta_skill` (source at `~/dev/meta_skill`, branch `local/frontmatter-id`).
- Related consume-tool skill in this repo: [`cass`](../cass/SKILL.md) (session archaeology). The jsm `cass-memory` (cm) procedural-memory tool is the write-side complement (installed separately, not in this repo).
- Lifecycle contract validator: [`scripts/validate.sh`](scripts/validate.sh).