What your agent can call

Six-stage cascade — BM25 + MiniLM + RRF + cross-encoder + local k-NN + cross-user global priors.

Returns ranked candidates with descriptions only (no full bodies — pair with skill_graft to load winners). Stage 1 is wink-bm25 over name + description + tags + category. Stage 2 is cosine similarity vs ~800KB of bundled embeddings (all-MiniLM-L6-v2, 384-dim, one vector per skill, packed as a Float32 array and shipped with the brew formula). Stage 3 is reciprocal rank fusion (Cormack et al, K=60). Stage 4 takes the RRF top-30 and reranks with Xenova/ms-marco-MiniLM-L-6-v2 — a cross-encoder that scores (query, candidate) jointly, catching interactions that bi-encoder cosine misses. Stage 5 is per-user attribution k-NN: every /next-move you run writes a triple to ~/.windags/triples/ with the prompt and the skills that got accepted; this stage embeds the historical prompts (cached after first call), finds the k nearest to your current query, and boosts skills that worked in similar past sessions. Empty history → no-op. Stage 6 blends in cross-user global priors served by api.windags.ai — three nested tiers (manifest_match ⊆ exact_match ⊆ any_match) decomposed into exclusive subsets and capped at a 0.2 blend weight; fetched once at startup with adaptive freshness refresh. Network unreachable or WINDAGS_TELEMETRY=off → Stage 6 silently no-ops. Both MiniLM models (~25MB each) download once and cache in ~/.cache/transformers-js/. Local-first, with one cheap public read per startup.

windags_skill_search({ query: "stripe webhook idempotency", limit: 5 })

Full SKILL.md bodies for the top N + adjacency descriptions + per-skill asset manifest.

Runs the same six-stage cascade as skill_search (lexical + semantic + RRF + cross-encoder rerank + per-user attribution k-NN + cross-user global priors), then loads the actual SKILL.md bodies from disk for the top N primaries (~10–12K tokens for top-4) plus 4 adjacent catalog entries (name + description, ~500 tokens) for awareness, plus a per-skill asset manifest (references, scripts, templates, examples — paths + sizes) the agent can call windags_skill_reference on. This is the tool measured in the bench article.

windags_skill_graft({ task: "set up stripe webhook with retries" })

Load one reference file from a skill on demand.

Skills carry references/, scripts/, templates/, diagrams/, and examples/ directories. The graft response includes a manifest (paths + sizes), and the agent calls this tool when it decides a specific reference is worth pulling into context. Returns the file contents as text. If the path is wrong, returns the actual file list so the agent can pivot.

windags_skill_reference({ skill_id: "stripe-webhooks", file_path: "references/idempotency-keys.md" })

Recent /next-move predictions for context.

Returns the last N /next-move predictions from your local history (~/.windags/history/). Useful for resuming work, comparing predictions, or letting an agent see what was recently planned without re-running.

N cascade searches in one round-trip — designed for DAG planners.

When a planner is materializing a multi-node DAG, calling skill_search per node costs N MCP round-trips. This tool takes an array of {query, limit} and runs them in parallel, returning results in the same order. Same six-stage cascade as skill_search per query — bundled+user catalogs, BM25 + MiniLM + RRF + cross-encoder + per-user attribution k-NN + cross-user global priors. Hard cap of 20 queries per call to bound payload size.

windags_skill_search_batch({ queries: [{ query: 'caching', limit: 5 }, { query: 'docker', limit: 5 }] })

N grafts in one round-trip for materializing a whole DAG up-front.

Same shape as skill_search_batch but for graft — array of {task, count} returns the full SKILL.md bodies + adjacencies + asset manifests for each task in parallel. Per-task primary count is capped at 3 to bound payload size. When you need a deeper reference for a specific node, call windags_skill_reference. Hard cap of 20 tasks per call.

windags_skill_graft_batch({ tasks: [{ task: 'design REST API' }, { task: 'add caching layer' }] })

Per-node specs a DAG planner needs — allowed-tools, pairs-with, and provider-native model IDs.

Given an array of skill IDs, returns each skill's allowed-tools (from frontmatter), pairs-with relationships, suggested model_tier (fast/balanced/powerful — heuristic by category), and a list of provider-native model IDs that match the tier. Critical: model IDs are real, provider-accepted strings (`gpt-5.4-nano`, `llama-3.1-8b-instant`, `claude-haiku-4-5-20251001`), not abstract Anthropic-only labels. Fixes the bug where DAGs emitted bare "haiku" / "sonnet" strings that 400'd on OpenAI/Groq/etc. The full all_tier_options block is included so a planner can pick a different provider per node if needed.

windags_node_requirements({ skill_ids: ['api-architect', 'data-pipeline-engineer'] })

Schema-check a candidate DAG before you save it.

A DAG planner emits JSON; this tool validates it against the PredictedDAG schema (waves, nodes, dependencies, premortem, confidence, problem_classification). Returns either { valid: true, plus a summary } or { valid: false, errors: ["path.to.field: message", ...] }. The schema is permissive on most fields (defaults applied) but strict on shape — a malformed wave or missing required node field surfaces clearly. Use this during multi-step planning to catch problems before they reach the executor.

windags_validate_dag({ dag: { title: 'my plan', waves: [{ nodes: [{ id: 'r', skill_id: 'research-craft', role_description: 'Research' }] }] } })

Per-node + total cost estimate during planning, surfaced before the executor's runtime cost gate.

Given the planned nodes (id, skillIds, description, dependencies, optional model + referenceFileCount) plus a defaultModel tier, returns the predicted total USD + total tokens + a per-node breakdown. Char-based estimator (no tokenizer) — calibrated to Anthropic Claude tier pricing. Treat as planning-time order-of-magnitude, not a billing prediction. The point is to surface roughly-how-much-this-will-cost during predict, before the runtime cost gate fires at execution time. Reads bundled SKILL.md bodies from disk to estimate prompt size.

windags_estimate_cost({ nodes: [{ id: 'r', skillIds: ['research-craft'], description: 'Research', dependencies: [] }, { id: 'w', skillIds: ['technical-writer'], description: 'Write', dependencies: ['r'], model: 'sonnet' }], defaultModel: 'haiku' })

Execute a script bundled with a skill (locally, sandboxed) and return its output.

Many skills carry executable scripts (compliance checks, code generators, lint rules). Today an agent has to inline the script into context to use it. This tool runs the script on the user's machine in a subprocess sandbox (no network unless --remote=allow, time + output caps), returning only stdout/stderr/exit. The agent gets the result without burning context on the script body. Local-only by design — the MCP server is what runs on the user's machine; api.windags.ai never sees the user's files.

Index the references/, scripts/, templates/, examples/ for a grafted skill.

Graft already returns a per-skill manifest, but this lets the agent re-list assets later in the conversation without re-grafting. Returns paths + sizes + a one-line peek so the agent can decide what's worth pulling via skill_reference. Also surfaces script entry points (scripts/lint.py, scripts/migrate.sh) so the agent knows what's runnable via run_skill_script.

Graph traversal: given a skill, return the skills it pairs with (frontmatter pairs-with field).

Skills declare their natural partners in YAML frontmatter (`pairs-with: [{skill: data-pipeline-engineer, reason: ...}]`). When the agent realizes a grafted skill needs reinforcement, this tool returns the partners without a fresh search.