This skill is used to handle toolchain failures: first determine whether the problem comes from the tool, the environment, or the execution channel, then choose a conservative recovery plan and capture new reusable experience.
-
First distinguish toolchain problems from business problems. Do not misjudge missing script dependencies, sandbox helper exceptions, encoding misreads, path compatibility, or command parameter differences as problems with user requirements, code logic, or file content itself.
-
Do not fabricate validation results. If official validation, testing, or build tools cannot run due to environment problems, you must explain the real reason for the failure and use alternative validation to supplement the evidence. Do not claim that the original tool passed.
-
Do not bypass permission and security boundaries. When encountering permission, network, installation, or destructive operation requirements, request authorization according to the current agent's approval rules; do not use workarounds to evade approval.
-
Alternative solutions must be explainable and verifiable. When using alternative commands, different editing tools, or manual checks, record the original failure, alternative actions, validation evidence, and residual risks.
-
After resolution, capture reusable experience. If this skill does not cover the current toolchain problem, and you have already found a stable solution, you must write the general rule back to
skills/toolchain-issue-recovery/inSKILL.md、USAGE.mdorevals/evals.json. Do not write one-off project details into the skill. -
Use Chinese throughout. Unless the user explicitly requests another language, all interactions with the user, problem records, recovery explanations, test records, audit conclusions, and artifact descriptions must be in Chinese. Code, file paths, commands, API names, original error text, technical terms, and third-party library names may remain in English.
Handling process
1. Capture failure facts
Record the minimal facts:
- The failed command or tool.
- Key error information.
- The location where it occurred and the target file.
- Whether partial artifacts have already been produced.
- Current permission, sandbox, network, or dependency restrictions.
Do not rush to retry the same command. First determine the failure type.
2. Classify and choose a solution
Prioritize matching the known categories below.
| Category | Judgment signal | Preferred solution |
|---|---|---|
| Encoding and Chinese garbled text | Appears as 椤圭洰鍚嶇О、闇€姹傛枃妗 and other mojibake |
Explicit UTF-8 read/write, see "Encoding and Chinese garbled text" |
| Patch tool failure | apply_patch reports sandbox/helper/read/update errors |
Shrink the patch; if it still fails, use native commands in the workspace to write, and record the reason for the deviation |
| Initialization script partially fails | Directories or templates have been created, but UI metadata, validation, or subsequent steps fail | Keep valid artifacts, check for residue, then fill in the target files |
| Validation tool missing dependencies or decoding failure | ModuleNotFoundError, missing yaml、UnicodeDecodeError: 'gbk' codec can't decode , etc. |
Do not claim validation passed; complete dependencies or enable UTF-8 mode and rerun; if still unavailable, perform alternative structural checks |
| Incompatible command parameters | Parameters do not exist, version differences, PowerShell/cmd behavior differences | Check local help or switch to a more general command |
| Permission or network restrictions | access denied, DNS, registry/index failures | Request permissions per approval rules or state that it cannot be completed |
| Path and shell differences | Paths with spaces, backslashes, wildcards, redirection failures | Use -LiteralPath, explicit working directory, and a single shell |
3. Perform conservative recovery
Recovery actions should be as small as possible:
- Prioritize preserving artifacts that have already been generated correctly.
- Read the current state first, then fill in missing files.
- Avoid deleting content the user has not confirmed in order to "clean up the scene".
- Perform operations such as directory deletion, overwriting, and batch moves only after the user explicitly requests them or approval is granted.
4. Alternative verification
If the original validation tool is unavailable, fill the gap with observable evidence:
- File existence: whether the target files and directories exist.
- frontmatter:
nameanddescriptionexist and the directory names match. - JSON/YAML: whether they can be parsed by a local parser.
- Key text: whether hard gates, path constraints, Chinese constraints, and trigger scenarios exist.
- Template remnants: use
rgto search for placeholder words such as to-do placeholder markers. - Scope check: whether only the expected directories were modified.
When alternative verification passes, you may only say "alternative verification passed"; do not say "official validation passed".
5. Write back experience
When encountering a new issue, after resolving it, determine whether it is worth writing back:
- The probability of future recurrence is relatively high.
- The recovery steps can be generalized.
- It is not a one-off path or temporary state of a particular project.
- It can help the agent avoid misjudgments or unsafe operations.
Write-back locations:
- Write general recovery rules to
SKILL.md。 - Write human-facing quick instructions to
USAGE.md。 - Write testable scenarios to
evals/evals.json。
Encoding and Chinese garbled text
This is a solution migrated from the old powershell-chinese-encoding skill.
Quick diagnosis
If Chinese displays as something like the following, it is usually not that the file content is actually corrupted, but that the wrong encoding was used when reading or outputting:
椤圭洰鍚嶇О
闇€姹傛枃妗
浣滆€?
Primary suspicion: a UTF-8 Chinese file is being read by Windows PowerShell as ANSI/GBK.
Reading Chinese files
When reading Chinese Markdown, JSON, YAML, logs, configuration, or skill files, explicitly specify UTF-8 first:
Get-Content -Raw -Encoding UTF8 path\to\file.md
Do not rely only on:
Get-Content -Raw path\to\file.md
The default encoding of Windows PowerShell 5.1 may not be UTF-8.
Writing Chinese files
When writing or overwriting Chinese text, also explicitly specify the encoding:
Set-Content -Path path\to\file.md -Value $content -Encoding UTF8
When appending content:
Add-Content -Path path\to\file.md -Value $content -Encoding UTF8
If the target is PowerShell 7, the default UTF-8 behavior is more stable; but for cross-environment reproducibility, explicitly writing -Encoding UTF8。
Output to the terminal
If the file is read correctly but external commands or terminal output are still garbled, you can set the console output encoding in the current session:
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$OutputEncoding = [System.Text.Encoding]::UTF8
This mainly affects text passing between PowerShell and external programs, and does not replace Get-Content -Encoding UTF8。
Encoding diagnostics
- First use
Get-Content -Raw -Encoding UTF8 <path>to read once. - If UTF-8 displays correctly, record the conclusion as "garbled text caused by the default read encoding" and do not determine that the file is corrupted.
- If UTF-8 is still garbled, then check whether the file's actual encoding or content has already been incorrectly transcoded.
- In the test record or troubleshooting conclusion, clearly write down the PowerShell version, the read command, and the observed results.
Note:Format-Hex parameters are not completely consistent across different PowerShell versions; do not assume that all environments support -Count。
Known recovery solutions
apply_patch fails in the Windows sandbox
Example symptom:
windows sandbox failed: helper_unknown_error: setup refresh had errors
Handling:
- First narrow the patch scope, for example change only one file or add only one file.
- If it still fails, confirm that the target path is within the writable range of the workspace.
- Switch to using the same shell's native command to write, for example PowerShell
Set-Content -Encoding UTF8。 - In the final explanation, record: originally
apply_patchshould have been used, but due to a sandbox helper error, an alternative write was used instead. - Run alternative verification to confirm that the content, encoding, and scope are correct.
Initialization script partially fails
Example symptom:
[OK] Created skill directory
[OK] Created SKILL.md
[ERROR] short_description must be 25-64 characters
Handling:
- Do not repeat initialization, which could cause overwriting or confusion.
- Check the files and directories that have already been generated.
- Keep the valid directories and templates.
- Fill in the missing artifacts or replace the template content.
- Check whether extra directories such as
agents/、scripts/、references/、assets/were generated; if they need to be deleted, confirm that they were indeed generated this time and are not needed.
Validation script is missing dependencies
Example symptom:
ModuleNotFoundError: No module named 'yaml'
Handling:
- Do not claim that the validation script passed.
- If installing dependencies requires network access or permissions, handle it according to the approval rules.
- If dependencies are not installed, perform alternative verification: frontmatter, JSON, key text, template remnants, and directory scope.
- In the final explanation, clearly state "the original validation did not run successfully; alternative verification passed/failed".
Windows Python decodes UTF-8 files with GBK by default
Example symptom:
UnicodeDecodeError: 'gbk' codec can't decode byte ...
This commonly occurs on Windows when running Python validation scripts to read Chinese Markdown, YAML, or JSON files. Even if the file itself is correct UTF-8, if the script relies on the system default text encoding, it may fail by decoding as GBK.
Handling:
-
Do not determine that the file is corrupted, and do not claim that validation passed.
-
First confirm that the file can be read normally as UTF-8, for example
Get-Content -Raw -Encoding UTF8 <path>。 -
Enable UTF-8 mode before running the Python script:
$env:PYTHONUTF8='1' .\.venv\Scripts\python.exe path\to\script.py path\to\target -
If the script then reports
No YAML frontmatter found, check whether the file has a UTF-8 BOM; some strict validation scripts require the first character of the file to be-。 -
When the file encoding needs to be rewritten, prefer UTF-8 no BOM, and clearly record that this is to adapt to a strict validation tool, not a content change.
-
If the original validation still cannot be run, perform alternative verification, and explain the reason for the original validation failure and the alternative verification results.
Pre-completion check
Before finishing, confirm:
- The original error and the failing tool have been recorded.
- Which recovery solution was used has been explained.
- No bypassing of permissions, security, or user confirmation.
- If alternative verification is used, it is clearly stated that it is not the original tool's verification.
- If the problem is of a new type, it has been determined whether it needs to be written back to the skill.
- Chinese garbled text handling has explicitly used a UTF-8 read/write strategy.