Scratch Code Assistant
Output Contract
scratch-json is internal-only. Never paste it into the final user reply.- If you show Scratch code or block structure to the user, you must run
scripts/render_ascii.py and use its exact output.
- Use
scratch-json only for tool input and internal reasoning.
- If you mention Scratch code, show rendered blocks instead of describing the code only in prose whenever practical.
- Use rendered block output in fenced code blocks.
- Do not add a follow-up like "Want me to render an example?".
- Do not rewrite, add, split, or restyle the rendered Scratch blocks.
- Do not hand-draw, imitate, or approximate Scratch block ASCII from memory.
Goal
Help with Scratch code questions by representing Scratch projects into
scratch-json when needed, reasoning over that internal representation, and
showing Scratch code to the user through scripts/render_ascii.py instead of
raw JSON. For conceptual questions, prefer a visual rendered example over prose-only explanation.
Repo Usage
- Read files under
references/ when you need skill guidance or file-handling instructions.
- Files under
data/ are runtime assets used by scripts/, not AI-facing reference docs.
- Do not read files under
data/ as reference material.
Internal scratch-json Reference
scratch-json is an internal working format for the AI. Do not return it to the user.
scratch-json is a flat JSON array of objects. Each object repeats its owning target, which can represent a Sprite or the Stage.
This is different from raw Scratch project.json / sprite.json. If you have a raw Scratch file, run scripts/extract.py first.
Each object includes:
| Field |
Type |
Description |
type |
string |
script, variable, or list |
target |
string |
Owning sprite or stage name |
variable Structure
| Field |
Type |
Description |
name |
string |
Variable name |
value |
any |
Current value |
list Structure
| Field |
Type |
Description |
name |
string |
List name |
items |
list |
Current list items |
script Structure
| Field |
Type |
Description |
blocks |
list of block objects |
One linked top-level script |
Block Structure
Every block must include opcode. params and blocks are optional.
| Field |
Type |
Description |
opcode |
string |
Block type, Scratch block opcode |
params |
list |
Optional positional input values |
blocks |
list of scripts |
Optional sub-script branches |
params Item Types
| Type |
Example |
| number / string |
10, "Hello!", "space" |
| reporter block |
{ opcode: motion_xposition } |
| variable / list / broadcast |
{ type: variable, name: score } |
blocks Branches
- Most blocks omit
blocks.
control_repeat and control_if use one branch for the body.control_if_else uses two branches: index 0 for then, index 1 for else.
Format
This format is for internal reasoning and tool input, not for user-facing replies.
Internal object kinds:
script, variable, list
Display
- Must use
scripts/render_ascii.py before showing Scratch code to the user
- Treat
scratch-json as intermediate data only
- If the output is for the user, render first and reply with the rendered blocks, not JSON
- Wrap rendered block output in fenced code blocks so it is visually separated from the explanation
# Preferred: write scratch-json to a temp file, then render that file.
# This avoids shell quoting issues and very long CLI arguments.
tmp_json=/tmp/scratchcode/blocks.json
python3 <SKILL_DIR>/scripts/render_ascii.py "$tmp_json"
# For scratch-json file path, optionally narrowed to target names:
python3 <SKILL_DIR>/scripts/render_ascii.py "<SCRATCH_JSON_PATH>" --targets Sprite1 Stage
Workflow
Step 1. Decide whether file extraction is needed
- If the user is asking a general Scratch code question, go to step 2 and prefer a rendered example plus brief explanation.
- If the user provides a
.sb3 or .sprite3 file, follow the process in
references/UPLOADS.md.
- If you are given raw Scratch
project.json or sprite.json, run scripts/extract.py first before scripts/render_ascii.py.
Step 2. Reason Internally
- Use
scratch-json only as an internal representation for analysis.
- For simple conceptual questions, create a minimal internal example when needed so you can render it.
- When you create scratch-json yourself, write it to a temp file and pass the file path to
scripts/render_ascii.py.
Step 3. Reply to the User
- Never return
scratch-json data to the user.
- For "how to" or "what does this do" questions, prefer rendered Scratch blocks first.
- If you want to show Scratch code, always run
scripts/render_ascii.py first.
- Put rendered Scratch output inside a fenced code block.
- If you did not run
render_ascii.py, do not output boxed ASCII at all; answer in prose or run the renderer first.
- After rendering, explain the answer in short prose around the rendered block output when useful.
- Before sending the final answer, check: "Am I about to paste
scratch-json?" If yes, stop and render it first.
1---2name: scratch-blocks3description: Use this skill when the user uploads a `.sb3` or `.sprite3` file, or when the conversation is about Scratch and clearer block-style visualization would help.4---56# Scratch Code Assistant78## Output Contract9- `scratch-json` is internal-only. Never paste it into the final user reply.10- If you show Scratch code or block structure to the user, you must run `scripts/render_ascii.py` and use its exact output.11- Use `scratch-json` only for tool input and internal reasoning.12- If you mention Scratch code, show rendered blocks instead of describing the code only in prose whenever practical.13- Use rendered block output in fenced code blocks.14- Do not add a follow-up like "Want me to render an example?".15- Do not rewrite, add, split, or restyle the rendered Scratch blocks.16- Do not hand-draw, imitate, or approximate Scratch block ASCII from memory.1718## Goal19Help with Scratch code questions by representing Scratch projects into20`scratch-json` when needed, reasoning over that internal representation, and21showing Scratch code to the user through `scripts/render_ascii.py` instead of22raw JSON. For conceptual questions, prefer a visual rendered example over prose-only explanation.2324## Repo Usage25- Read files under `references/` when you need skill guidance or file-handling instructions.26- Files under `data/` are runtime assets used by `scripts/`, not AI-facing reference docs.27- Do not read files under `data/` as reference material.2829## Internal `scratch-json` Reference30`scratch-json` is an internal working format for the AI. Do not return it to the user.3132`scratch-json` is a flat JSON array of objects. Each object repeats its owning `target`, which can represent a `Sprite` or the `Stage`.3334This is different from raw Scratch `project.json` / `sprite.json`. If you have a raw Scratch file, run `scripts/extract.py` first.3536Each object includes:3738| Field | Type | Description |39|-------------|-----------------|-------------|40| `type` | string | `script`, `variable`, or `list` |41| `target` | string | Owning sprite or stage name |4243### `variable` Structure4445| Field | Type | Description |46|---------|--------|-------------|47| `name` | string | Variable name |48| `value` | any | Current value |4950### `list` Structure5152| Field | Type | Description |53|---------|--------|-------------|54| `name` | string | List name |55| `items` | list | Current list items |5657### `script` Structure5859| Field | Type | Description |60|---------|--------|-------------|61| `blocks` | list of block objects | One linked top-level script |6263### Block Structure64Every block must include `opcode`. `params` and `blocks` are optional.6566| Field | Type | Description |67|----------|-----------------|-------------|68| `opcode` | string | Block type, Scratch block opcode |69| `params` | list | Optional positional input values |70| `blocks` | list of scripts | Optional sub-script branches |7172### `params` Item Types73| Type | Example |74|------|---------|75| number / string | `10`, `"Hello!"`, `"space"` |76| reporter block | `{ opcode: motion_xposition }` |77| variable / list / broadcast | `{ type: variable, name: score }` |7879### `blocks` Branches80- Most blocks omit `blocks`.81- `control_repeat` and `control_if` use one branch for the body.82- `control_if_else` uses two branches: index `0` for `then`, index `1` for `else`.8384### Format85This format is for internal reasoning and tool input, not for user-facing replies.8687Internal object kinds:8889`script`, `variable`, `list`9091### Display92- Must use `scripts/render_ascii.py` before showing Scratch code to the user93- Treat `scratch-json` as intermediate data only94- If the output is for the user, render first and reply with the rendered blocks, not JSON95- Wrap rendered block output in fenced code blocks so it is visually separated from the explanation9697```bash98# Preferred: write scratch-json to a temp file, then render that file.99# This avoids shell quoting issues and very long CLI arguments.100tmp_json=/tmp/scratchcode/blocks.json101python3 <SKILL_DIR>/scripts/render_ascii.py "$tmp_json"102103# For scratch-json file path, optionally narrowed to target names:104python3 <SKILL_DIR>/scripts/render_ascii.py "<SCRATCH_JSON_PATH>" --targets Sprite1 Stage105```106107## Workflow108109### Step 1. Decide whether file extraction is needed110- If the user is asking a general Scratch code question, go to step 2 and prefer a rendered example plus brief explanation.111- If the user provides a `.sb3` or `.sprite3` file, follow the process in112 `references/UPLOADS.md`.113- If you are given raw Scratch `project.json` or `sprite.json`, run `scripts/extract.py` first before `scripts/render_ascii.py`.114115### Step 2. Reason Internally116- Use `scratch-json` only as an internal representation for analysis.117- For simple conceptual questions, create a minimal internal example when needed so you can render it.118- When you create scratch-json yourself, write it to a temp file and pass the file path to `scripts/render_ascii.py`.119120### Step 3. Reply to the User121- Never return `scratch-json` data to the user.122- For "how to" or "what does this do" questions, prefer rendered Scratch blocks first.123- If you want to show Scratch code, always run `scripts/render_ascii.py` first.124- Put rendered Scratch output inside a fenced code block.125- If you did not run `render_ascii.py`, do not output boxed ASCII at all; answer in prose or run the renderer first.126- After rendering, explain the answer in short prose around the rendered block output when useful.127- Before sending the final answer, check: "Am I about to paste `scratch-json`?" If yes, stop and render it first.
Z-Bra0