xways-xtension-authoring

name: xways-xtension-authoring description: This skill should be used when the user asks to "create a new X-Tension", "scaffold an X-Tension", "wrap a tool in an X-Tension", "update/modify an X-Tension", "port a convention into an X-Tension", "add helper-exe verification", "add Ctrl-to-save", "add a LICENSE/README/CLAUDE.md to an X-Tension", "prep an X-Tension for public release", "audit/modernize an X-Tension", or "build/compile an existing X-Tension" for X-Ways Forensics. It covers template/exemplar selection, the copy+rename+identity scaffold, the CLI-wrapper anatomy, licensing/beta-versioning/README+roadmap/repo-hygiene conventions, porting the project's CLAUDE.md conventions, verifying XWF_ API calls against the SDK header/docs, and writing findings back to docs/ + CLAUDE.md. It does NOT handle general X-Ways usage questions or open-ended "what tool should I build" ideation — those belong to an upstream brainstorming / ideation step. license: MIT metadata: version: 0.1.0

X-Ways X-Tension Authoring

Author and maintain X-Ways Forensics X-Tensions — the xways-<name> DLLs that live in your own project's x-tensions/ folder — quickly and correctly. This repo ships the starter templates (templates/x-tensions/), a distilled docs/ knowledge base, and this skill; the scaffold scripts copy a template into your project's x-tensions/xways-<name>/ (not into this repo). Scaffold new X-Tensions by copying and parameterizing a starter template, port the project's 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.

Hard gates (never violate)

• Read-only template source. templates/x-tensions/ is the pristine template source — never edit, move, or delete it in place; copy a template into your project's x-tensions/xways-<name>/ first (the scaffold script does this). If you create a local references/ tree for a user-acquired SDK (per docs/getting-the-sdk.md), it is read-only and must never be committed (copyright).
• Never invent XWF_ functions or flags. Verify every call, in this priority order: (1) the distilled notes in docs/ (the routing-table targets — primary); (2) the live official API page https://www.x-ways.net/forensics/x-tensions/XWF_functions.html (authoritative for additions made after the SDK snapshot); (3) an optional locally-downloaded SDK header (references/api/.../X-Tension.h) if you acquired it per docs/getting-the-sdk.md (fallback — may be absent). Route any API question through references/api-guardrail.md.
• x-tensions/ (hyphen) is the source tree; xtensions\ (no hyphen) is the build-output / deploy folder that X-Ways auto-loads from. Never confuse the two — a wrong spelling means X-Ways will not load the DLL. See docs/conventions/naming-deployment.md.
• 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 runs as a GUI-subsystem process — it accepts command-line parameters, but has no console window attached, so a child you spawn inherits null std handles and any helper that writes to stdout/stderr can hard-crash. Always hand the child real handles (open \NUL, or a pipe if you capture output) with STARTF_USESTDHANDLES. See docs/conventions/subprocess-stdio.md.
• Public-repo hygiene. Never commit credentials, live .cfg, local paths (C:\Users\…), case data, or compiled DLLs/EXEs — binaries ship via GitHub Releases once the repo is public. Run scripts/prepublish-scan.ps1 before a public push. See docs/conventions/repo-hygiene.md.

Choose the flow, then load its reference

The guardrail row is an always-on correctness layer applied during every flow — not a /xtension subcommand.

Scaffold from a starter template under templates/x-tensions/ (cpp, cpp-xtmgr-compatible, 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. docs/exemplars.md is a registry of community exemplars (with X-Ways 21+ verdicts and attribution) to read and port patterns from — not bundled copy-targets; none are shipped in this repo. The -Exemplar script parameter applies only to exemplars you have locally in your own project.

Scripts (the deterministic core)

Run from the repo root in PowerShell.

• scripts/new-xtension.ps1 — copy a starter template (or a locally-available exemplar) into your project's x-tensions/xways-<name>/, rename the source files to the xways-<name> stem, and set the identity constants. Always run with -DryRun first to review the planned copies / renames / edits before committing to them.
  • Parameters: -Name <name> (the xways-<name> stem), -Template cpp|python|xtmgr|wrapper or -Exemplar <local-exemplar> (only for an exemplar you have locally — none are bundled here), optional -Version -Description -ReportTable, -DryRun, -Force. (xtmgr = templates/x-tensions/cpp-xtmgr-compatible/; wrapper = the manager-compatible CLI-wrapper template at templates/x-tensions/wrapper/.)
• scripts/build-xtension.ps1 -Name <name> — refuse to build while X-Ways is running, bootstrap the MSVC x64 environment if needed, run the X-Tension's build.bat, verify xtensions\xways-<name>\xways-<name>.dll was produced, then deploy the staged folder into your X-Ways install at xtensions\xways-<name>\. The deploy target is the user's own environment — nothing is hardcoded: pass -DeployRoot '<install-root>' once (the folder holding xwb64.exe / xwforensics64.exe; it's remembered in a git-ignored .xtension-deploy.local), or set $env:XWT_DEPLOY_ROOT. With neither set, the build still succeeds and stages the DLL locally; -NoDeploy skips deploy outright. On a user's first build, ask them for their X-Ways install path and pass it via -DeployRoot (remembered thereafter). The mirror is newer-only so an analyst-edited sidecar .cfg/.yaml in the install survives rebuilds. This is the build gate — never claim a scaffold "works" without pasting this script's success output.
• scripts/check-manager-sync.ps1 [-Name <name>] — verify each manager-compatible X-Tension's manager-plugin.h copy matches the canonical templates/x-tensions/cpp-xtmgr-compatible/manager-plugin.h (catches ABI drift that silently breaks managed loading). build-xtension.ps1 runs it automatically for manager-compatible X-Tensions.
• scripts/prepublish-scan.ps1 [-Strict] — read-only pre-publish hygiene scan over git-tracked files: flags local paths (C:\Users\…), tracked binaries, and case/ data (high-severity, non-zero exit), plus credential-ish keywords / emails (review advisories). Clear it before any public push. See docs/conventions/repo-hygiene.md.
• scripts/backfill-standards.ps1 [-DryRun] [-Force] — additively backfill a missing LICENSE (MIT) + CLAUDE.md.example into every active X-Tension that lacks them (idempotent; pulls each tool's name/description/version from source). Does not touch versions or READMEs. See docs/conventions/licensing.md + xtension-claude-md.md.

Convention library

The reusable patterns live in docs/conventions/ — the single source of truth. The references cite these pages by symbol; the pages cite the wrapper template's code (templates/x-tensions/wrapper/), so nothing drifts. Key pages: naming-deployment, output-dir, verbose-logging, subprocess-stdio, helper-exe-verification, ctrl-to-save, wrapper-anatomy, tool-resolution, manager-compatibility, licensing, versioning, readme-roadmap, xtension-claude-md, repo-hygiene.

Manager compatibility (opt-in — do not default to it). xways-xt-manager (the tabbed host that loads manager-compatible X-Tensions) is a work in progress and its contract may still change, so do not make X-Tensions manager-compatible by default. Use a plain template (cpp, python, or wrapper) unless the user specifically asks for manager support — only then scaffold with -Template xtmgr or port it in. The contract (manager-plugin.h, ABI 1) and how to add it are documented in references/manager-compat.md.

Close the loop

After learning something new about the API/behavior, or completing a CLAUDE.md pending-rollout item, record it: update the relevant docs/ page (and docs/INDEX.md / docs/exemplars.md as needed) and the CLAUDE.md pending-rollout list, using absolute dates. See references/docs-loop.md.

Invocation

This skill auto-triggers on the phrases in its description. It is also reachable as the slash command /xtension <new|wrap|port|audit|docs> [name], which routes to the same flows.