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

Skill grafting with discovery, estimate, and full-body modes so agents do not burn context blindly.

Runs the same six-stage cascade as skill_search, then either returns a body-free shortlist or loads the actual SKILL.md bodies for the primary skills. Use mode:'ids' while browsing: it returns skill IDs, one-line descriptions, confidence scores, and a windags_skill_reference pointer for each full body. Use mode:'estimate' to get the shortlist plus context_cost and warnings. Use mode:'full' when you are ready to load bodies; if estimated body tokens exceed max_body_tokens, the response preflights with no bodies unless allow_large_payload:true is set. The default body threshold is 8K estimated tokens, with warnings around 6K.

windags_skill_graft({ task: "set up stripe webhook with retries", mode: "ids", count: 2 })

Load SKILL.md or one reference file from a skill on demand.

Skills carry SKILL.md plus references/, scripts/, templates/, diagrams/, and examples/ directories. Discovery-mode graft responses point here with file_path:'SKILL.md' for full body loading. Full graft responses include manifests, and the agent calls this tool when 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: "SKILL.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, with aggregate context-cost preflight for planners.

Same shape as skill_search_batch but for graft. Array of {task, count} runs in parallel and supports the same mode:'ids' | 'estimate' | 'full' contract as the single graft tool. Per-task primary count is capped at 3, and max_body_tokens is evaluated against the aggregate skill-body payload for the whole batch. If a planner asks for full bodies and the batch would be too large, the tool returns mode:'preflight', a body-free result set, warnings, and retry_with instructions.

windags_skill_graft_batch({ mode: 'ids', 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.