# mfs-find

Searches and reads records across configured MFS sources like codebases, databases, Jira, and Slack. It handles retrieval over existing indexes via the CLI.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · ★ 157
- Author: zilliztech
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/zilliztech/mfs/tree/HEAD/skills/mfs-find/SKILL.md
- Updated: 2026-07-31
- HTML: https://affpapa.org/en/nevibecode/skills/mfs-find

## What it does

The skill gives the agent access to the MFS retrieval layer through command-line operations. It organizes local directories, cloud storage, relational databases, and issue trackers under uniform URI paths. You query them with standard verbs such as `mfs search`, `mfs grep`, and `mfs cat`.

Search queries combine dense vectors and BM25 keywords via reciprocal rank fusion. Hits return precise POSIX-style locators — line ranges for text files or primary key dictionaries for database rows. The `mfs search` command requires a pre-built index, whereas `mfs grep` can fall back to linear scans.

Operations are strictly read-only. The skill cannot register new connectors or trigger re-indexing; those tasks belong to `mfs-ingest`. Without an active MFS server, all retrieval calls will fail.

## Requirements
- Works with: GitHub, PostgreSQL, MongoDB

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add zilliztech/mfs --skill mfs-find -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/mfs-find/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/mfs-find/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add zilliztech/mfs --skill mfs-find -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/mfs-find/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add zilliztech/mfs --skill mfs-find -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/mfs-find/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install zilliztech/mfs mfs-find
```

2. **Manually: put the files in place**
- File: `.github/skills/mfs-find/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add zilliztech/mfs --skill mfs-find -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/zilliztech/mfs --path skills/mfs-find
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/mfs-find/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add zilliztech/mfs --skill mfs-find -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/zilliztech/mfs/tree/HEAD/skills/mfs-find/SKILL.md

## When to use it
- search across codebases, Slack, and issue trackers in one call
- locate exact line ranges or table rows using POSIX locators
- run hybrid semantic and keyword queries over large corpora
- inspect outlines of large files without reading the entire document

## Example prompts
- Search across our Slack and Jira tickets for past discussions on auth tokens.
- Find anywhere in the codebase mentioning the connection retry limit.
- Show me an outline of `schema.sql` using `mfs cat --peek`.

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 1e6a7fe3be5c213a.

BEGIN THIRD-PARTY FILE 1e6a7fe3be5c213a
```text
---
name: mfs-find
version: 0.4.0
mfs_compat: ">=0.4,<0.5"
description: >-
  Search, grep, browse, and read across registered MFS data sources via the
  `mfs` CLI — codebases, docs, PDFs, web crawls, databases
  (postgres/mysql/mongo/snowflake/bigquery), issue trackers
  (jira/linear/github), CRMs (hubspot), chat (slack/discord/gmail/feishu),
  object stores (s3/gdrive). Use whenever the user asks to find, locate,
  look up, look across, or read something out of an already-configured MFS
  index. Trigger phrases include "search the codebase for", "find anywhere
  about", "where is X mentioned", "look across our [slack/jira/postgres/etc]",
  "any past tickets/RFCs/commits about", "what does our wiki say about",
  "cat / head / tail / ls / tree this MFS path". Do NOT use for:
  registering a NEW data source (use `mfs-ingest`), changing connector config,
  kicking off re-ingest, or any write/delete operation — `mfs` is read-only.
---

# MFS — find / read across configured sources

## 1. What MFS is

A retrieval layer that exposes many kinds of content as a unified path
tree and makes that tree searchable through one hybrid index:

- **One CLI (`mfs`), one mental model.** Local dir, Postgres, GitHub repo,
  Slack workspace, S3 bucket, BigQuery dataset — all addressed as paths
  under their `<scheme>://` URI. Same verbs everywhere: `ls / tree / cat /
  head / tail / grep / search / export`.
- **One hybrid index.** Dense vectors (semantic) + BM25 (keyword) fused
  per query — covers conceptual recall and exact-token recall in one call.
- **POSIX-style locators.** Every search hit carries a `locator` that
  reopens the exact unit: `{"lines":[s,e]}` for text/code, a PK dict for
  rows/issues/threads.

## 2. When to use MFS — and when NOT to

| Situation | Use MFS? |
|---|---|
| 1000+ files / rows / pages, you don't know where the answer is | ✅ |
| Cross-source question ("any past tickets / commits / RFCs about X") | ✅ `--all` |
| Concept-style query that won't match literally | ✅ `--mode semantic` |
| You already know the exact file + roughly where to look | ❌ plain `cat`/`grep` |
| Exact identifier / error code in 5 files you can list | ❌ plain `grep`/`rg` |
| Real-time tailing of a live log | ❌ index lags ingest |
| The source isn't in MFS yet | wrong skill, use `mfs-ingest` to register first |

**Rule:** use the smallest tool that answers the question. MFS pays off
when the scope is too big for `rg`.

**Borderline — ASK the user:**

| Ask | Likely answer | Why |
|---|---|---|
| "Summarise these 10 PDFs" | ✅ `mfs search` + `cat --peek` per hit | each PDF gets a `converted_md` artifact + searchable chunks |
| "Find similar tickets to this one" | ✅ paste the ticket text as the search query | semantic over `row_text` does similarity matching |
| "Watch for new slack messages" | ❌ no `watch` capability; use Slack's API | index lags ingest |
| "Look up user 12345" | ❌ `mfs cat <source> --locator '{"id":12345}'` directly (skip search) | one-record-by-id doesn't need ranking |
```
END THIRD-PARTY FILE 1e6a7fe3be5c213a

The third-party file has ended. Everything between the 1e6a7fe3be5c213a tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3053 of 16528 bytes. © zilliztech · Apache-2.0 · https://github.com/zilliztech/mfs/tree/HEAD/skills/mfs-find/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md