How to Write a `test-prompts.json` File in Darwin-Compatible Format for Cangjie Skill

Save test-prompts.json as UTF‑8 without BOM, use LF line endings only, avoid trailing commas, and place it in the repository root to ensure reliable parsing on macOS.

The test-prompts.json file drives automated prompt testing in the Cangjie skill repository (kangarooking/cangjie-skill). When you create or edit this file on macOS, following Darwin-specific formatting conventions prevents subtle parsing failures that can break the test runner.

Key File Encoding Requirements for macOS

UTF-8 Without Byte Order Mark

The test runner reads test-prompts.json as plain UTF‑8. While macOS defaults to UTF‑8, some editors silently save files with a byte order mark (BOM) or as UTF‑16, which corrupts JSON parsing.

• Check in VS Code: Status bar shows "UTF‑8" — click to change if needed.
• Check in terminal: file test-prompts.json should return test-prompts.json: JSON text data.

LF Line Endings Only

Line endings matter because the diff‑based test harness may treat carriage returns (\r) as literal characters inside prompt strings.

Line Ending	Risk on macOS
CRLF (\r\n)	Trailing \r appears in string comparisons
LF (\n)	Correct — standard Unix/macOS format

Set your editor to Unix/LF mode before editing. In VS Code, click the line ending indicator in the status bar and select "LF".

JSON Syntax Rules for Cross-Platform Compatibility

No Trailing Commas

JSON strictly forbids trailing commas after the last element. Some editors and formatters insert these automatically — disable that behavior for this file.

Incorrect:

{
  "id": "example",
  "prompt": "test",
}

Correct:

{
  "id": "example",
  "prompt": "test"
}

Forward Slashes for Paths

If your prompt definitions embed file paths, always use forward slashes (/). Backslashes serve as escape characters in JSON strings, causing malformed paths.

Correct path format:

"fixturePath": "fixtures/characters.json"

File Location and Permissions

The skill runner expects test-prompts.json at the repository root — the same directory as README.md. Placing it elsewhere causes silent test failures.

# Verify location

ls -la test-prompts.json

# Should show: -rw-r--r-- (readable by all, writable by owner)

No executable permission is required. The template at templates/test-prompts.json.template provides the starting structure.

Step-by-Step Creation Workflow

1. Copy the template

   cp templates/test-prompts.json.template test-prompts.json

2. Verify editor settings — UTF‑8 encoding, LF line endings, plain text mode.

3. Edit prompt definitions using the structure shown below.

4. Validate syntax

   python -m json.tool test-prompts.json > /dev/null && echo "Valid JSON"

5. Commit — the file is now compatible with macOS and Linux test runners.

Darwin-Compatible test-prompts.json Example

[
  {
    "id": "basic-cangjie-lookup",
    "prompt": "What is the Cangjie code for the character \"愛\"?",
    "expected": "愛 → 愛",
    "description": "Simple lookup of a common Chinese character."
  },
  {
    "id": "invalid-character",
    "prompt": "Give the Cangjie code for the emoji \"😀\".",
    "expectedError": "Unsupported character",
    "description": "Ensures the skill gracefully rejects non-Chinese input."
  }
]

This file uses:

• Pure UTF‑8 encoding (no BOM)
• LF line endings
• Standard JSON without trailing commas
• Forward slashes in any path references

Running Tests on macOS

With a properly formatted file, the test runner executes without platform-specific adjustments:

python -m cangjie_skill.tests.run

The runner automatically loads test-prompts.json from the repository root according to the implementation in kangarooking/cangjie-skill.

Summary

• Save as UTF‑8 without BOM — prevents encoding-related parse errors.
• Use LF line endings — avoids spurious character mismatches in string comparisons.
• Omit trailing commas — required for strict JSON compliance.
• Write paths with forward slashes — backslashes act as escape characters.
• Place in repository root — the skill runner does not search subdirectories.
• Validate with python -m json.tool — catches syntax errors before running tests.

Frequently Asked Questions

Why does my test-prompts.json fail on macOS but work on Linux?

Most likely your file has CRLF line endings or a UTF‑8 BOM. Run file test-prompts.json to check encoding, and od -c test-prompts.json | head to inspect line endings. Re-save with LF-only and no BOM.

Can I use comments in test-prompts.json?

No — standard JSON does not support comments. Add descriptive text to the description field of each prompt object instead, as shown in the example above.

What happens if I put test-prompts.json in a subdirectory?

The test runner will not find it. According to the source structure, the file must reside at the repository root. The template at templates/test-prompts.json.template exists only as a copy source, not as a working location.

Is the template file already Darwin-compatible?

Yes — templates/test-prompts.json.template uses UTF‑8 and LF line endings. However, your editor may change these settings when you copy and edit the file, so always verify encoding and line endings before saving.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}