dayz-ask
Answers a plain English question about vanilla DayZ with checked path:line citations. Use when the user asks how vanilla does something, where it lives, or what a vanilla class or config value does.
SKILL.mdskills/dayz-ask/SKILL.md
GitHub<!-- skill-dir-note -->
Path note:
<skill-dir>in commands below is the absolute path of this skill's folder. When the agent loads this skill the harness exposes the skill's base directory; substitute it before running. Sibling skills are reached via<skill-dir>\..\dayz-X\.
/dayz-ask
A script finds and checks the evidence. You read it and write the answer. Every claim in the answer cites a line the script read from disk. The script runs the RAG search, checks every hit against the file on P:\, and falls back to a keyword Grep of the vanilla folders when there is no VOYAGE_API_KEY or index.
Follow skills/_shared/dayz-conventions.md. Format the answer per skills/_shared/answer-formatting.md.
How to run
python "<skill-dir>\ask.py" "<question>" [--top-k N] [--excerpt-lines N] [--file-type T] [--folder F] [--grep] [--json]
Narrow the search whenever the question allows it: --file-type cpp for a config.cpp value, --file-type c for script behaviour, --folder gui for a layout. For example:
python "<skill-dir>\ask.py" "what does the food config set for spoil time" --file-type cpp --folder dz
| Argument | Notes |
|---|---|
"<question>" |
The user's question in their words. |
--top-k N |
Search hits, or Grep files, to keep (1 to 25, default 5). |
--excerpt-lines N |
Longest excerpt printed per citation (1 to 300, default 60). Raise it to see whole functions. |
--file-type T |
Only one file type: c, cpp, hpp, h, layout, cfg, rvmat, xml, json or csv. Use cpp for config.cpp questions and c for script questions. |
--folder F |
Vanilla folder for the Grep fallback: scripts, dz, gui, core, graphics or languagecore. Repeat it for more than one. The default is scripts and dz. |
--grep |
Skip RAG and use the Grep fallback. |
--json |
Print the report as JSON after the verdict line. |
What the script does
- Runs
search_dayz_sourcefrom thedayz-ragserver when the index is built andVOYAGE_API_KEYis set. Each run is a new process, so the dayz-rag server's in-memory cache does not carry over between/dayz-askruns; the MCP toolsearch_dayz_sourcein a session does reuse it. - Reads every hit's lines from
P:\. A hit isverifiedwhen the cited lines still hold the indexed text, ormovedwhen the text now sits at other lines, in which case the citation points at the new lines. A hit whose text is gone is dropped and listed underdropped.verifiedsays only that the citation is real, not that it answers the question. - Re-cites a checked hit longer than 60 lines at its best term lines. The index can return a whole config class (the
CfgVehicleshit inP:\dz\gear\food\config.cppspans lines 240 to 14564), and the first 60 lines of it rarely hold the answer. The lines inside the span are scored the way the Grep fallback scores a file's lines, and each window (two lines either side of a matching line, up to three per hit) becomes its own citation, withwithinnaming the whole span. A long hit with no term line inside it is dropped as off topic. - Drops a checked hit as off topic when its distance is above 1.15 (
RAG_MAX_DISTANCE), or when neither its excerpt nor its class context holds a search term from the question. A term inside a quoted asset path ("food" inmodel="\dz\gear\food\BoxCereal.p3d") does not count. A cooking config class returned for a food spoilage question is dropped this way. Each one is listed underdroppedwith its reason. - Falls back to Grep when there is no key, no index, the search fails, or no hit survives the checks. It splits the question into search terms (common words and words under three letters are dropped, except a two-letter word written in capitals or one of
AI,HP,UI,ID,NV,UV; a two-letter term matches only as its own word or name part, soAIfindsEntityAIbut notFAIL), scans the vanilla folders, and ranks files by how many of the rarer terms they hold. A file that declares a class or function whose name holds a term ranks higher. Debug and GUI files (aguifolder, ordebugin a folder or file name) count half, so gameplay classes come before debug readouts. Grep citations are lines read from disk, so they count as checked.
Output and exit codes
The first line is the verdict: EVIDENCE (exit 0), NONE (exit 1, nothing found) or ERROR (exit 2: empty question, a question made only of common words such as "how does it work", bad argument (reported before the common-words check), P:\ not mounted, or the script crashed, for example when the dayz-rag server fails to load). Notes follow, then each citation with the lines read from disk:
EVIDENCE 2 citation(s) via rag
[1] P:\scripts\4_world\classes\bleedingsources\bleedingsource.c:7-203 verified distance=0.708 BleedingSource
| class BleedingSource
| ...
via is rag, grep, or rag+grep when RAG gave no surviving hit (none returned, or all dropped as stale or off topic). An excerpt shows at most 60 lines.
With --json, the report holds verdict, question, mode, notes, citations and dropped. Each dropped entry has cite and reason. Each citation has cite (path:line_start-line_end), path, line_start, line_end, status, source (rag or grep) and excerpt; RAG citations add distance and context, and within when the hit was re-cited from a longer span; Grep citations add match_line and terms_in_file.
Writing the answer
- Answer only from the excerpts. When the answer needs lines past an excerpt, read them with
get_dayz_fileorReadfirst. - Cite every claim as
path:line_start-line_end, using thecitevalue or a narrower range inside it. - Lead with the answer in a sentence or two, then the supporting citations.
- A kept citation is real and shares a word with the question, but may still not answer it. Grep results match words, not meaning. Use only the citations that answer the question and ignore the rest.
- If the evidence does not answer the question, say so, and suggest a narrower question or a
--file-typeor--folder. Do not fill the gap from memory. - Pass on each note that names a fix: a missing key, a missing index, or dropped hits that call for
/dayz-search-index --full.
Limits
- It reads vanilla files only, never your mod.
- Grep ranks by words, so a question about behaviour can return lines that only share a word with it. The RAG search ranks by meaning.
- It checks that
P:\is mounted itself and does not run/dayz-preflight, since it only reads files. Mount the drive with/dayz-workdrive.