Scratch Blocks

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.

Security Scan

The skill's code and runtime instructions are coherent with its stated purpose (rendering Scratch .sb3/.sprite3 content to ASCII blocks); it runs only local Python scripts, requests no credentials, and performs no networking.

Purpose & Capability

Name/description (render Scratch projects into block-style ASCII) match the included files and scripts: extract.py converts .sb3/.sprite3/project.json to the internal scratch-json, and render_ascii.py renders that format using the bundled BLOCK_CATALOG. No unrelated binaries, env vars, or external services are requested.

Instruction Scope

SKILL.md gives explicit, constrained instructions: run scripts/extract.py for archives, produce scratch-json in /tmp, and run scripts/render_ascii.py to render output. It forbids returning scratch-json to users and requires using the renderer output. The runtime steps reference only local files and the temp output; they do not ask the agent to read other system files or contact external endpoints.

Install Mechanism

No install specification — instruction-only plus bundled Python scripts. Both scripts use only the Python standard library and local data files; nothing is downloaded or executed from external URLs.

Credentials

The skill requires no environment variables, credentials, or config paths. The scripts operate on user-provided Scratch files and local temp dirs only.

Persistence & Privilege

extract.py creates a working directory under /tmp/scratchcode/<md5>/ and writes blocks.json there (and may leave that directory). The skill is not always-enabled and does not request persistent elevated privileges or modify other skills.

Assessment

This skill appears to do what it says: it will execute the included Python scripts locally to extract and render Scratch projects, and it does not request credentials or make network calls. Before installing, review that you're comfortable with the agent running those local Python scripts on user-supplied .sb3/.sprite3 files (the extractor writes to /tmp/scratchcode/<md5>/blocks.json and may leave files behind). If you are concerned about residual files, delete /tmp/scratchcode after use. If you need additional assurance, inspect the two scripts (scripts/extract.py and scripts/render_ascii.py) yourself — they use only the Python standard library and the bundled BLOCK_CATALOG, and I found no code that exfiltrates data or contacts external endpoints.

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.