`minimax-docx` skill: false-negative env check, broken `run-script` reference, broken XSD validator, and SKILL.md inconsistencies ## Summary While using the `minimax-docx` skill to create a DOCX from scratch (Pipeline A), I hit several concrete issues that block the documented workflow. This is **separate from #89** — that one covers build/OOM/path issues on Apple Silicon for `~/.mavis/.builtin-skills/docx/` with `DocumentFormat.OpenXml` 3.5.1 and `net9.0`. The skill I used lives at `~/.mavis/skills/minimax-docx/`, depends on `DocumentFormat.OpenXml` 3.2.0, targets `net8.0`, and the issues below are different in nature. ## Environment - macOS Tahoe (Apple Silicon, arm64) - .NET SDK 9.0.315 at `~/.dotnet/dotnet` (not on `PATH` by default) - pandoc 3.10, soffice 26.2.4, zip/unzip available - Skill path: `~/.mavis/skills/minimax-docx/` - Workspace: standalone console app at `~/workspace/MavisCapabilities/` ## Issues ### 1. `env_check.sh` reports `NOT READY` even when everything works After running the skill's `setup.sh` (which failed at `brew install --cask dotnet-sdk` due to missing sudo in a non-interactive shell) and manually adding `~/.dotnet` to `PATH`, I ran: ```bash PATH="$HOME/.dotnet:$PATH" DOTNET_ROOT="$HOME/.dotnet" \ bash ~/.mavis/skills/minimax-docx/scripts/env_check.sh ``` Output: ``` [OK] dotnet 9.0.315 (>= 8.0) [OK] nuget packages restored [FAIL] project build failed [OK] pandoc, soffice, zip/unzip, locale [WARN] permissions 4 script(s) not executable Status: NOT READY ``` But running `dotnet build ~/.mavis/skills/minimax-docx/scripts/dotnet` in the same shell succeeded with `Сборка успешно завершена` and zero errors. The check appears to invoke `dotnet build` with a path that the shell does not resolve correctly, or reads cached state from a previous failed run. **Suggested fix:** print the actual command it ran and its stderr, and treat `OK` items as definitive — do not lump `WARN` into the final status. ### 2. `SKILL.md` references a `run-script` subcommand that does not exist `SKILL.md` "Quick Start" section says: ``` File: scripts/dotnet/task.csx (or a new .cs in a Console project) dotnet run --project scripts/dotnet/MiniMaxAIDocx.Cli -- run-script task.csx ``` But `Program.cs` of `MiniMaxAIDocx.Cli` only registers these commands: ```csharp rootCommand.Add(CreateCommand.Create()); rootCommand.Add(EditContentCommand.Create()); rootCommand.Add(ApplyTemplateCommand.Create()); rootCommand.Add(ValidateCommand.Create()); rootCommand.Add(MergeRunsCommand.Create()); rootCommand.Add(FixOrderCommand.Create()); rootCommand.Add(AnalyzeCommand.Create()); rootCommand.Add(DiffCommand.Create()); ``` There is no `run-script`. The `MiniMaxAIDocx.Cli/Commands/` directory is empty. The real command implementations live in `MiniMaxAIDocx.Core/Commands/`. Following the documented "write C# directly" path leads to a dead end unless you create your own standalone console app — which is not what the example implies. **Suggested fix:** either implement `run-script` in the CLI, or remove the example from `SKILL.md` and point users to the Core library / a separate template csproj. ### 3. `validate --xsd wml-subset.xsd` throws an unhandled exception ```bash dotnet run --project scripts/dotnet/MiniMaxAIDocx.Cli -- \ validate --input out.docx --xsd assets/xsd/wml-subset.xsd ``` Throws: ``` Unhandled exception: System.Xml.Schema.XmlSchemaValidationException: The 'http://schemas.openxmlformats.org/officeDocument/2006/relationships:id' attribute is not declared. at System.Xml.Schema.XmlSchemaValidator.SendValidationEvent(...) ... at MiniMaxAIDocx.Core.Validation.XsdValidator.ValidateXml(...) ``` This is a bug in `wml-subset.xsd` — it does not import the relationships namespace, but `r:id` attributes appear throughout OpenXML documents. The XSD gate-check is therefore unusable on every output the skill produces. **Suggested fix:** add `<xs:import namespace="http://schemas.openxmlformats.org/officeDocument/2006/relationships" schemaLocation="..."/>` to `assets/xsd/wml-subset.xsd`, or ship a curated subset that explicitly declares the attributes used by the skill's emitters. ### 4. `validate --business` reports a benign orphaned relationship on every output Every document I produce passes `--business` but emits: ``` WARNINGS (1): [Warning] Orphaned relationship: Id='Re3dcb71e2ebe46ea' is defined but never referenced Validation: PASSED ``` The orphan is the `FooterPart` rel — `mainPart.GetIdOfPart(footerPart)` returns an id that the validator does not see as referenced from `document.xml.rels` (likely because the SDK registers the rel via `AddNewPart` first and only the explicit `FooterReference` in `sectPr` ties it back). The relationship is in fact correct and required for the page-number footer; the validator should not warn about it. **Suggested fix:** either recognize footer/header rels as referenced-by-virtue-of-attachment, or have `AestheticRecipeSamples.AddPageNumberFooter` register the rel in a way the validator accepts. ### 5. `setup.sh` calls `brew install --cask dotnet-sdk` without checking sudo availability `setup.sh` runs: ``` brew install --cask dotnet-sdk ``` which invokes `sudo /usr/sbin/installer ...`. In a non-interactive shell (CI, agent runs, SSH without TTY), sudo prompts for a password and fails with: ``` sudo: a terminal is required to read the password; either use -S ... ``` The script then aborts and the user has to install `dotnet` by hand. Meanwhile, the script does not look in the obvious existing locations: `~/.dotnet/dotnet`, `/usr/local/share/dotnet`, `/opt/homebrew/Cellar/dotnet*`. **Suggested fix:** probe `~/.dotnet/dotnet` / `~/.dotnet/sdk` / `/usr/local/share/dotnet` / `/opt/homebrew/Cellar/dotnet*` first; only fall back to `brew install` if none exist; and if `brew install` is needed, document the manual install path (`curl -sSL https://dot.net/v1/dotnet-install.sh | bash -s -- --channel 9.0`) instead. ### 6. `docx_preview.sh` (pandoc) silently drops paragraphs styled `Title` / `Subtitle` I built a cover page with three paragraphs: `Title` ("Mavis"), `Subtitle` ("Capabilities of your personal assistant"), `Caption` ("Документ сгенерирован ..."). The XML in `word/document.xml` is correct and `soffice --convert-to pdf` renders it correctly. But `scripts/docx_preview.sh` shows only the `Caption` line — the title and subtitle are eaten by pandoc because it treats the first heading-level paragraph as the document title and pulls metadata from elsewhere. This made me think the cover was broken until I checked the raw XML. For a skill whose name ends in `docx` and whose core use case is producing documents, this is misleading. **Suggested fix:** use `pandoc --standalone --nometadata` or `pandoc -t plain` with `--wrap=none` so style-only paragraphs are preserved; or run `unzip -p … word/document.xml | xmllint --format -` for a faithful text dump. ### 7. Four scripts are not executable after `setup.sh` `env_check.sh` consistently reports: ``` [WARN] permissions 4 script(s) not executable ``` These are presumably `setup.sh`, `env_check.sh`, `docx_preview.sh`, `doc_to_docx.sh`. The skill never `chmod +x`s them after install, so on a fresh checkout every downstream invocation has to be prefixed with `bash`. **Suggested fix:** add `chmod +x` to the install paths in `setup.sh`. ## Reproduction ```bash # After setup.sh has been run once (even partially): cd ~/.mavis/skills/minimax-docx # Issue 1: env check false-negative PATH="$HOME/.dotnet:$PATH" DOTNET_ROOT="$HOME/.dotnet" \ bash scripts/env_check.sh # → "Status: NOT READY" but build actually works # Issue 2: missing run-script dotnet run --project scripts/dotnet/MiniMaxAIDocx.Cli -- run-script foo.csx # → error: No command was found for: run-script # Issue 3: XSD validator crashes dotnet run --project scripts/dotnet/MiniMaxAIDocx.Cli -- \ validate --input any.docx --xsd assets/xsd/wml-subset.xsd # → XmlSchemaValidationException, not a clean failure # Issue 6: preview swallows title bash scripts/docx_preview.sh docs/with-cover.docx # → cover content missing from output ``` ## Impact - Issues 1–3 mean the documented "first run" path (`setup.sh` → `env_check.sh` → `validate`) does not work cleanly on a fresh macOS environment. - Issue 2 blocks the "structural / write C# directly" path that `SKILL.md` recommends for non-trivial documents — exactly the path a user takes when producing anything beyond a one-pager. - Issues 6–7 are smaller but erode trust in the skill on every run. ## Notes - Cross-references: #89 already covers the Apple Silicon build/permissions path issues at a more fundamental level — those apply here too. The seven items above are the additional issues I hit on top of #89. - I produced a 6-page DOCX successfully (MinimalModern recipe, business-rules validation passed, PDF render verified visually), so the skill is functional despite the friction. The friction just makes the first session longer than it needs to be.