Use fmql-semantic when the user wants meaning-based / semantic / hybrid search over a directory of markdown or frontmatter notes — phrasings like "find docs about X concept", "what have I written on …", "semantic search my notes", "retrieve by topic", "RAG over my vault", or when plain grep will miss hits because the user's query wording differs from the documents' wording. Also triggers on "hybrid search", "BM25 plus embeddings", "index my notes vault", "embed my markdown", "rerank results", "dense retrieval", "cosine similarity search over markdown". This is the `semantic` search backend for fmql — it sits on top of fmql's core commands, so also load the fmql skill for anything involving the Cypher query language, frontmatter edits, or graph traversal.
Use fmql whenever the user works with a directory of markdown or frontmatter files — notes, tasks, Zettelkasten, an Obsidian vault, a project-management packet collection, a knowledge base, a "digital garden" — and wants to query, aggregate, traverse, or bulk-edit YAML frontmatter fields. Reach for this instead of grep whenever the user's question involves structured fields (status, priority, tags, due_date, assignees, uuid, dependency links like blocked_by or belongs_to) or whenever a mutation needs to apply across many files at once. Also triggers on "find all docs where…", "set status on every overdue task", "describe this workspace", "what's blocking task-X", "cycle detection", "traverse blocked_by", "bulk-edit frontmatter", "query my notes". If the user mentions "frontmatter", "YAML header", "markdown metadata", or points at a directory of .md files, load this skill.