boshu2 ms — meta_skill search/load engine
Core Insight:
msis the skill-search engine over both configured corpora (agentops + jsm). Consume via MCP, write/admin via CLI. One law: after ANY reindex/wipe, every runningms mcp serveMUST be killed (sessions respawn fresh). A surviving server silently reads pre-wipe data and returnsrecorded:trueon writes that land in orphaned files.
Constraints
- Load with
full: trueor--fullwhen 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-resultms searchCLI 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
msretrieval-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):
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 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.
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.contentforms load --full -O json. - Validation command: run
skills/ms/scripts/validate.shfor the retrieval boundary andscripts/ms-reindex.sh --check-sourcefor 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
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
msafter 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 outcomerecords observed usefulness only after independent downstream evidence.
References
- Upstream: Jeffrey Emanuel's
meta_skill(source at~/dev/meta_skill, branchlocal/frontmatter-id). - Related consume-tool skill in this repo:
cass(session archaeology). The jsmcass-memory(cm) procedural-memory tool is the write-side complement (installed separately, not in this repo). - Lifecycle contract validator:
scripts/validate.sh.