Blockly Best Practices

Blockly Implementation Workflow

Use this skill only for implementing or modifying a Blockly/ABS program. Project selection and creation belong to the blockly-project-planning skill.

1. Start from runtime facts

• Treat the injected project path, current board, installed library list, readme_ai.md references, and project.abs path as current runtime facts.
• Do not call tools merely to rediscover those facts.
• Treat project.abs as the canonical editable Blockly source. Generated .ino/C++ is derived output used for diagnostics, not the normal edit target.

2. Gather only task-relevant evidence

• Identify the smallest set of libraries needed for the current feature. Do not inspect every installed library or add lib-core-* packages speculatively.
• For each relevant installed library, call analyzeLibrary with mode="auto" first.
• When it returns a readme_ai.md reference, read that file. The README is usually sufficient, but it is not an absolute stopping point.
• If the README is missing, incomplete, contradictory, or does not answer the current question, escalate narrowly:
  1. inspect the relevant block.json for block types, fields, inputs, and args0 order;
  2. inspect generator.js only when generated-code semantics remain unclear;
  3. inspect the minimum native source needed only when underlying library behavior remains unresolved.
• Stop reading once the evidence answers the current implementation question.

3. Resolve board facts through the board capability source

• Use get_board_parameters for GPIO, ADC, PWM, UART, I2C, SPI, builtin LEDs, and other board defaults. Its board.json result is authoritative.
• Pinmap data describes schematic terminals and connection geometry. Do not use it as the source of MCU capability or default-pin facts.
• Use schematic/pinmap capabilities only when the request actually requires wiring or a connection diagram.

4. Edit the canonical ABS source

1. Read project.abs directly. The host synchronizes the visible Blockly workspace to this file before a submitted turn.
2. Use syncAbs action="export" only if the workspace may have changed after the turn began or a status check shows drift.
3. Make the smallest coherent ABS edit. Preserve unrelated blocks and structure.
4. Use syncAbs action="import" to apply the updated ABS to the visible workspace.
5. Treat parse warnings, failed blocks, degraded text expressions, or partial imports as failed validation and repair them before continuing.

Load abs-syntax-reference when block argument order, statement inputs, nested value blocks, or other non-trivial ABS grammar is involved. Do not guess positional arguments; verify them from the selected library evidence.

5. Validate immediately

• Check the imported workspace/ABS structure after a non-trivial change.
• Run lint for generated-code syntax validation when appropriate.
• Run buildProject when the task requires a compile result.
• If validation fails, use the nearest error and the smallest relevant source as the next evidence anchor. Do not restart broad project exploration.

Completion criteria

• The visible workspace reflects the intended ABS structure.
• No ABS import warning or failed block remains.
• Requested focused validation passes, or the remaining blocker is reported precisely.
• Do not claim completion from compiler success alone when the Blockly import was partial or structurally degraded.