docs: refine EncodingFix skill layout

Author: MaxLogic

agent-skill/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: encodingfix-delphi-cleanup
+description: Use EncodingFixTool whenever an AI agent edits, generates, patches, or reviews Delphi/Pascal files and needs safe CRLF or UTF-8 cleanup. Trigger this skill after apply_patch, WSL/Linux tools, formatters, bulk rewrites, or pre-commit cleanup involving .pas, .dpr, .dpk, .inc, .dfm, or .dproj files, even when the user only mentions wrong line endings or encoding drift.
+---
+
+# EncodingFix Delphi Cleanup
+
+Run EncodingFixTool after AI/editor work may have changed Delphi line endings or encoding. Keep the cleanup narrow, auditable, and separate from build/test validation.
+
+## Use This For
+
+- Delphi files: `.pas`, `.dpr`, `.dpk`, `.inc`, `.dfm`, `.dproj`.
+- AI-generated or patched Delphi code that should use Windows CRLF.
+- Delphi files that should be UTF-8 with BOM when non-ASCII text is present.
+- Pre-build or pre-commit cleanup after code generation, patching, formatters, WSL, or Linux tooling.
+
+Do not use it for unrelated dirty files, vendored code, non-Delphi cleanup, or as a replacement for the repo's build/test gates. Binary `.dfm` files are safe because EncodingFixTool skips them.
+
+## Core Workflow
+
+1. Check the dirty set first:
+
+```powershell
+git status --short
+```
+
+If unrelated user changes are dirty, avoid broad cleanup. Narrow `path=...`, override `ext=...`, or ask before touching files outside our work.
+
+2. In a Git worktree, prefer the AI cleanup preset:
+
+```powershell
+EncodingFixTool path=. preset=delphi-ai scope=git-changed format=json
+```
+
+If the executable is not on `PATH`, use a local build such as:
+
+```powershell
+.\bin\EncodingFixTool.exe path=. preset=delphi-ai scope=git-changed format=json
+```
+
+3. Outside Git, use an explicit path and dry run first:
+
+```powershell
+EncodingFixTool path=.\src preset=delphi-ai format=json dry
+```
+
+Run the same command without `dry` only after the reported scope is correct.
+
+## Read Results
+
+Treat the run as successful only when the process exits with code `0` and JSON `failed` is `0`.
+
+- `changed > 0`: inspect the relevant diffs before reporting done.
+- `skipped > 0`: usually expected for binary `.dfm`; mention it only when relevant.
+- `failed > 0` or exit code `1`: stop and report the file-level failure.
+- Exit code `2`: fix the missing `path` and rerun.
+
+## Verify
+
+After cleanup:
+
+```powershell
+git diff --stat
+git ls-files --eol *.pas *.dpr *.dpk *.inc *.dfm *.dproj
+```
+
+Then continue with the repo's normal Delphi build/test gates. EncodingFixTool only fixes encoding and line endings.
+
+## Reporting Pattern
+
+Keep the final note short and evidence-based:
+
+```text
+Ran EncodingFixTool with preset=delphi-ai scope=git-changed format=json.
+Result: scanned=4, changed=2, skipped=1, failed=0.
+Checked git diff --stat and continued with the repo build/test gate.
+```
+
+If the tool was not run, state why: for example, no Delphi files were touched, the worktree had unrelated changes, or EncodingFixTool was unavailable.
+
+## More Detail
+
+Read `references/encodingfix-tool.md` only when you need command details, preset precedence, dry-run behavior, install/copy notes, or examples for non-standard scopes.

agent-skill/encodingfix-delphi-cleanup/SKILL.md

@@ -1,20 +1,20 @@
-{
-  "skill_name": "encodingfix-delphi-cleanup",
-  "evals": [
-    {
-      "id": 1,
-      "prompt": "I just used apply_patch on several Delphi .pas and .dfm files in this repo. Before you run the build, clean up any AI-created LF line endings or encoding issues without touching unrelated files.",
-      "expected_output": "The agent should check git status, run EncodingFixTool with path=. preset=delphi-ai scope=git-changed format=json, inspect the JSON summary and relevant diffs, then continue to the normal build/test gate."
-    },
-    {
-      "id": 2,
-      "prompt": "This is a Delphi checkout but it is not a Git worktree. Please repair CRLF/UTF-8 only under .\\src after generated code was pasted there.",
-      "expected_output": "The agent should avoid scope=git-changed, use an explicit path such as path=.\\src with preset=delphi-ai format=json dry first, then rerun without dry only after confirming scope."
-    },
-    {
-      "id": 3,
-      "prompt": "The worktree has my unrelated changes plus your generated Delphi units. Fix only your files' line endings and tell me what happened.",
-      "expected_output": "The agent should not run a broad scope=git-changed cleanup over all dirty files. It should narrow path or extensions, ask if needed, run dry when scope is unclear, and report scanned/changed/skipped/failed counts."
-    }
-  ]
-}
+{
+  "skill_name": "encodingfix-delphi-cleanup",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I just used apply_patch on several Delphi .pas and .dfm files in this repo. Before you run the build, clean up any AI-created LF line endings or encoding issues without touching unrelated files.",
+      "expected_output": "The agent should check git status, run EncodingFixTool with path=. preset=delphi-ai scope=git-changed format=json, inspect the JSON summary and relevant diffs, then continue to the normal build/test gate."
+    },
+    {
+      "id": 2,
+      "prompt": "This is a Delphi checkout but it is not a Git worktree. Please repair CRLF/UTF-8 only under .\\src after generated code was pasted there.",
+      "expected_output": "The agent should avoid scope=git-changed, use an explicit path such as path=.\\src with preset=delphi-ai format=json dry first, then rerun without dry only after confirming scope."
+    },
+    {
+      "id": 3,
+      "prompt": "The worktree has my unrelated changes plus your generated Delphi units. Fix only your files' line endings and tell me what happened.",
+      "expected_output": "The agent should not run a broad scope=git-changed cleanup over all dirty files. It should narrow path or extensions, ask if needed, run dry when scope is unclear, and report scanned/changed/skipped/failed counts."
+    }
+  ]
+}

agent-skill/evals/evals.json …odingfix-delphi-cleanup/evals/evals.jsonagent-skill/evals/evals.json renamed to agent-skill/encodingfix-delphi-cleanup/evals/evals.json agent-skill/evals/evals.json renamed to agent-skill/encodingfix-delphi-cleanup/evals/evals.json

@@ -0,0 +1,83 @@
+# EncodingFixTool Reference
+
+Use this reference when the standard `preset=delphi-ai scope=git-changed` workflow is not enough.
+
+## Runtime Dependency
+
+Prefer `EncodingFixTool` from `PATH`. If unavailable, use a repo-local executable such as `.\bin\EncodingFixTool.exe`.
+
+## Delphi AI Preset
+
+`preset=delphi-ai` is designed for AI/editor cleanup:
+
+- Delphi extensions: `.pas`, `.dpr`, `.dpk`, `.inc`, `.dfm`, `.dproj`.
+- Recursive scan.
+- CRLF normalization.
+- UTF-8 BOM policy for files with non-ASCII text.
+- Binary `.dfm` safety.
+
+`scope=git-changed` limits work to modified and untracked files in the current Git worktree. Do not use it outside Git, and do not use it when unrelated dirty files would be included.
+
+## Dry Run
+
+Use `dry` when the scope is not obvious, many files are dirty, or the user only asked for inspection:
+
+```powershell
+EncodingFixTool path=. preset=delphi-ai scope=git-changed format=json dry
+```
+
+`dry` reports what would change without rewriting files. Proceed without `dry` only when the file set is expected.
+
+## Non-Git Or Narrow Scope
+
+Outside a Git worktree:
+
+```powershell
+EncodingFixTool path=.\src preset=delphi-ai format=json dry
+EncodingFixTool path=.\src preset=delphi-ai format=json
+```
+
+For a deliberately narrow repair, keep overrides visible:
+
+```powershell
+EncodingFixTool path=.\src preset=delphi-ai ext=pas,inc format=json dry
+```
+
+## Configured Presets
+
+Repo presets may live in `.encodingfix.json`; user presets may live in:
+
+```text
+%APPDATA%\MaxLogic\EncodingFixTool\config.json
+```
+
+Preset precedence:
+
+```text
+built-in defaults < user config < repo .encodingfix.json < explicit config=... < CLI arguments
+```
+
+Example repo config:
+
+```json
+{
+  "presets": {
+    "agent": {
+      "ext": "pas,dpr,dpk,inc,dfm,dproj",
+      "eol": "crlf",
+      "utf8-bom": "y",
+      "recursive": "y"
+    }
+  }
+}
+```
+
+Run it with:
+
+```powershell
+EncodingFixTool path=. preset=agent scope=git-changed format=json
+```
+
+## Install Or Copy
+
+To install this as an agent skill, copy the `encodingfix-delphi-cleanup/` folder into the agent's skills directory. Keep `SKILL.md`, `references/`, and `evals/` together.