Xways Xtension Authoring

X-Ways X-Tension Authoring

Author and maintain X-Ways Forensics X-Tensions — the xways-<name> DLLs that live in an x-tensions/ working folder — quickly and correctly. Scaffold new X-Tensions by copying and parameterizing a starter template, port the documented conventions into existing ones, audit untested ones for API validity, and route every API question to the authoritative reference so generated code never invents XWF_ calls.

This skill owns the X-Ways-specific how. For open-ended "what should this new tool do" ideation, brainstorm the tool's purpose first (the superpowers:brainstorming skill helps if you have it), then return here for template choice, scaffolding, conventions, and build.

Everything this skill needs is bundled with it — every path below is relative to this file.

Hard gates (never violate)

• Never edit templates/x-tensions/ in place — it is the pristine source. Scaffold a copy into <project>/x-tensions/xways-<name>/ first (the script does this).
• Never edit or commit a user-acquired SDK tree. It lives at references/api/ in their project — read-only, and never committed (copyright). That tree, not this skill's own references/ flow guides, is what "never edit references/" means. See getting-the-sdk.
• Never invent XWF_ functions or flags. Verify every call against, in order: (1) the distilled notes in docs/; (2) the live https://www.x-ways.net/forensics/x-tensions/XWF_functions.html, which carries post-SDK additions; (3) a locally-downloaded SDK header, if present. Route API questions through api-guardrail.
• x-tensions/ (hyphen) is the source tree; xtensions\ (no hyphen) is the build-output / deploy folder. The build scripts stage, verify, and mirror the no-hyphen path, so a wrong spelling breaks the tooling. It is a project convention, not an X-Ways discovery mechanism — how X-Ways actually finds a DLL is in naming-deployment.
• Close X-Ways before building. The DLL is locked while X-Ways is open; there is no hot reload.
• Events API ⇒ C++ template only. XT_Python.dll does not expose XWF_AddEvent / XWF_GetEvent.
• Subprocess ⇒ open \NUL + STARTF_USESTDHANDLES. X-Ways is a GUI-subsystem process with no console attached, so a child inherits null std handles and any helper writing to stdout/stderr can hard-crash. Hand the child real handles — \NUL, or a pipe if you capture output. See subprocess-stdio.
• 0x01 delivers each item to every per-item callback you export. Export both XT_ProcessItem and XT_ProcessItemEx and each item hits both — the empirically verified "2N" double-count. Do per-item work in one callback (XT_ProcessItemEx for hItem), or route both through one deduping collector. RVS is multi-threaded, so shared state needs a mutex. 0x04 is EXPECTMOREITEMS, not "call Ex". See item-collection.
• Never call XWF_* from a worker thread you spawned — run synchronously on X-Ways' thread. XWF_AddEvent off-thread can corrupt the event store or crash the host. A settings dialog should request a run, then run it in XT_Finalize. See threading-model.
• Output writers: sanitise to valid UTF-8/XML, propagate I/O errors, bound memory. Raw log bytes break an encoding="UTF-8" XLSX; a silent write error truncates evidence; buffering every row OOMs. Spill + stream + split. See output-writers.
• Never commit credentials, live .cfg, local paths (C:\Users\…), case data, or compiled binaries — binaries ship via GitHub Releases. Run prepublish-scan.ps1 before a public push. See repo-hygiene.

Choose the flow, then load its reference

The guardrail row is an always-on correctness layer applied during every flow.

Scaffold from a starter template under templates/x-tensions/ (cpp, python, or the CLI-wrapper wrapper template). For a CLI-tool wrapper, prefer the wrapper template (-Template wrapper) — it already wires helper-exe verification, Ctrl-to-save, output-dir, and subprocess stdio. exemplars is a registry of community exemplars (with X-Ways 21+ verdicts and attribution) to read and port patterns from; none are bundled here.

Scripts (the deterministic core)

In scripts/, runnable from any working directory. For the scaffold/build scripts, output lands under the current directory by default, or a project passed via -DestRoot — never the skill install. (backfill-standards.ps1 is the exception: it operates on a repo working copy in place and has no -DestRoot.) Full parameters, deploy-target resolution, and the plugin-mode invocation: scripts.

Two rules that always apply:

• -DryRun first on new-xtension.ps1 — review the planned copies, renames, and edits before committing to them.
• build-xtension.ps1 is the build gate — never claim a scaffold "works" without pasting its success output. Close X-Ways first, and pass the same -DestRoot used to scaffold. On a user's first build, ask them for their X-Ways install path and pass it via -DeployRoot.

Convention library

The reusable patterns live in docs/conventions/ — the single source of truth. The pages cite the wrapper template's code (templates/x-tensions/wrapper/), so nothing drifts. Load the one you need:

• Correctness — item-collection · threading-model · output-writers · subprocess-stdio · events-emission
• Wrapping a CLI tool — wrapper-anatomy · tool-resolution · helper-exe-verification · ctrl-to-save
• Settings dialogs — xtension-dialog-conventions, the long-form UI companion (.rc layout, ID ranges, fonts, validation, cancel safety, progress, pickers). Load it when an X-Tension grows a dialog.
• Output — output-dir · add-output-to-case · verbose-logging
• Naming + release — naming-deployment · licensing · versioning · readme-roadmap · xtension-claude-md · repo-hygiene

Close the loop

After learning something new about the API/behavior, record it: update the relevant docs/ page (and INDEX / exemplars as needed), using absolute dates. See docs-loop.

Examples

• "Wrap yara in an X-Tension" → wrap flow: load wrapper-generator; scaffold with new-xtension.ps1 -Name yara -Template wrapper -DryRun, then for real; fill the // TODO stubs (the tool's command line + result-to-item mapping); build-gate with build-xtension.ps1 -Name xways-yara. Result: a deployable xtensions\xways-yara\ bundle.
• "How do I read a file's bytes from an X-Tension?" → guardrail flow: answer from xways-reading-events-and-items (XWF_OpenItem → XWF_Read → XWF_Close), citing the nFlags table in xways-openitem-flags; verify anything uncertain against the live XWF_functions.html.
• "Audit my old X-Tension for 21.8" → audit flow: load audit-modernize; check XT_Prepare return flags, deprecated calls (XWF_AddToReportTable → XWF_Label), action-code constants, and convention gaps; output a prioritized TODO list — do not change code until asked.

Invocation

Reachable as the slash command /xtension <new|wrap|port|audit|docs> [name] (namespaced as /xways-xtension-authoring:xtension when installed as a plugin), which routes to the same flows. guardrail is deliberately absent from that list — it is a correctness layer, not a subcommand.