# Blockly Best Practices

> Aily Blockly implementation workflow for scoped library evidence, ABS editing, workspace synchronization, and focused validation. Use for creating or modifying Blockly/ABS programs.

- Skill: `ailyproject/blockly-best-practices` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ailyproject/blockly-best-practices`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ailyproject/blockly-best-practices/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: ailyproject (https://skillmd.com/u/ailyproject)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ailyproject/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.