How do I install the Hal And Abstractions skill?

Run npx skillmds@latest add crosspoint-reader/hal-and-abstractions in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Hal And Abstractions safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Hal And Abstractions?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Hal And Abstractions free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Hal And Abstractions?

crosspoint-reader (@crosspoint-reader) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Hal And Abstractions by crosspoint-reader

Name: Hal And Abstractions
Author: crosspoint-reader

Hal And Abstractions

Layering and abstraction discipline for the firmware. Use when touching storage, input, display, settings, i18n, or rendering, or any code that could reach into the SDK. Covers routing through the HAL (HalStorage / HalGPIO / HalDisplay) instead of raw SDK classes, MappedInputManager logical buttons instead of raw GPIO indices, UITheme/GUI for all rendering, the singleton macros, tr() for user-facing text, and where a new abstraction boundary belongs.

File contents

HAL and Abstractions

CLAUDE.md lists the HAL classes and the SdFat-concurrency reason they exist. This is when and how to route through them, and where to draw a new boundary.

Route through the layer, always

SD card I/O: Storage (HalStorage) and HalFile. Never SdFat, FsFile, SdSpiCard, FsBaseFile, or SDCardManager directly. The HAL serializes every SD access through one mutex; bypassing it races the SPI state machine and panics FreeRTOS (CLAUDE.md has the failure mode). This is a correctness boundary, not a style preference.
Display: HalDisplay over EInkDisplay. Input: HalGPIO over InputManager.
Rendering: everything through the GUI macro (UITheme) and the renderer's oriented metrics. No hardcoded fonts, colors, coordinates, or 800/480 literals; ask the renderer for width/height and use the oriented viewable area.
Input in activities: MappedInputManager::Button logical enums (Button::Confirm, Button::PageForward, ...). Never raw HalGPIO::BTN_* indices outside ButtonRemapActivity. Logical buttons survive user remapping and orientation; raw indices do not.
Shared state: the singleton macros (SETTINGS, APP_STATE, GUI, Storage, I18N), not threaded pointers.

User-facing text

Every string a user reads goes through tr(STR_*). Add the key to the English YAML, regenerate with scripts/gen_i18n.py, then use the StrId. Log lines (LOG_*) stay hardcoded.

Drawing a new boundary

When you need an SDK capability the HAL does not expose yet, add the method to the HAL; do not reach around it. The new method inherits the mutex, logging, and error contract the rest of the HAL carries. A one-off direct SDK call in an activity is exactly the layering violation the mutex discipline cannot tolerate.

Keep abstractions thin. A wrapper that only renames an SDK call without adding the mutex, logging, or an error contract is dead weight. Add a layer only when it carries one of those contracts or hides a real implementation choice.

Self-review

No direct SdFat / FsFile / SDCardManager / EInkDisplay / InputManager use outside lib/hal.
File access uses HalFile; no .close() on a local handle (DESTRUCTOR_CLOSES_FILE); members closed in onExit.
Input uses MappedInputManager::Button, not raw BTN_* indices.
Rendering goes through GUI/UITheme and oriented metrics; no 800/480 or hardcoded fonts/coords.
User-facing strings use tr(STR_*); new keys added to YAML and regenerated.
Any new SDK capability is exposed as a HAL method, not called inline.

---name: hal-and-abstractionsdescription: Layering and abstraction discipline for the firmware. Use when touching storage, input, display, settings, i18n, or rendering, or any code that could reach into the SDK. Covers routing through the HAL (HalStorage / HalGPIO / HalDisplay) instead of raw SDK classes, MappedInputManager logical buttons instead of raw GPIO indices, UITheme/GUI for all rendering, the singleton macros, tr() for user-facing text, and where a new abstraction boundary belongs.---# HAL and AbstractionsCLAUDE.md lists the HAL classes and the SdFat-concurrency reason they exist.This is when and how to route through them, and where to draw a new boundary.## Route through the layer, always- **SD card I/O:** `Storage` (HalStorage) and `HalFile`. Never `SdFat`, `FsFile`, `SdSpiCard`, `FsBaseFile`, or `SDCardManager` directly. The HAL serializes every SD access through one mutex; bypassing it races the SPI state machine and panics FreeRTOS (CLAUDE.md has the failure mode). This is a correctness boundary, not a style preference.- **Display:** `HalDisplay` over `EInkDisplay`. **Input:** `HalGPIO` over `InputManager`.- **Rendering:** everything through the `GUI` macro (UITheme) and the renderer's oriented metrics. No hardcoded fonts, colors, coordinates, or 800/480 literals; ask the renderer for width/height and use the oriented viewable area.- **Input in activities:** `MappedInputManager::Button` logical enums (`Button::Confirm`, `Button::PageForward`, ...). Never raw `HalGPIO::BTN_*` indices outside `ButtonRemapActivity`. Logical buttons survive user remapping and orientation; raw indices do not.- **Shared state:** the singleton macros (`SETTINGS`, `APP_STATE`, `GUI`, `Storage`, `I18N`), not threaded pointers.## User-facing textEvery string a user reads goes through `tr(STR_*)`. Add the key to the EnglishYAML, regenerate with `scripts/gen_i18n.py`, then use the `StrId`. Log lines(`LOG_*`) stay hardcoded.## Drawing a new boundaryWhen you need an SDK capability the HAL does not expose yet, **add the method tothe HAL; do not reach around it.** The new method inherits the mutex, logging,and error contract the rest of the HAL carries. A one-off direct SDK call in anactivity is exactly the layering violation the mutex discipline cannot tolerate.Keep abstractions thin. A wrapper that only renames an SDK call without addingthe mutex, logging, or an error contract is dead weight. Add a layer only whenit carries one of those contracts or hides a real implementation choice.## Self-review- [ ] No direct SdFat / FsFile / SDCardManager / EInkDisplay / InputManager use outside `lib/hal`.- [ ] File access uses `HalFile`; no `.close()` on a local handle (DESTRUCTOR_CLOSES_FILE); members closed in `onExit`.- [ ] Input uses `MappedInputManager::Button`, not raw `BTN_*` indices.- [ ] Rendering goes through GUI/UITheme and oriented metrics; no 800/480 or hardcoded fonts/coords.- [ ] User-facing strings use `tr(STR_*)`; new keys added to YAML and regenerated.- [ ] Any new SDK capability is exposed as a HAL method, not called inline.

Frequently asked questions