assembler-conventions

Documents sjasmplus syntax rules and naming conventions for editing Z80 assembly files.

Updated Nov 29, 2024
One-click install
npx skills add https://github.com/SpeedRD/Arkanoid_Z80 --skill assembler-conventions-speedrd
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: assembler-conventions
Source: https://github.com/SpeedRD/Arkanoid_Z80/tree/main/.claude/skills/assembler-conventions
Command: npx skills add https://github.com/SpeedRD/Arkanoid_Z80 --skill assembler-conventions-speedrd

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Editing Z80 assembly in this repo is risky: sjasmplus silently accepts fake instructions, directives at column 0 become labels, and reordering INCLUDE lines relocates every address. This Skill encodes the verified conventions so new code assembles cleanly without breaking the existing tree. ## Core Features & Use Cases - Syntax ground truth: Documents the column-0 label rule, EQU variants, DB/DW/DEFB/DEFW usage, hex prefixes, and relaxed mnemonics like add b, all verified against sjasmplus v1.23.1. - Hazard catalog: Lists fake instructions (ld iy,ix) that silently expand into stack-touching sequences, plus common mistakes like placing DB inside a code path or re-encoding accented Spanish comments. - Naming and placement policy: New code uses English identifiers while existing Spanish names stay untouched; new routines go in colisiones.asm or a new INCLUDE'd file with data placed after ret. - Use Case: When adding a collision routine to the Arkanoid Z80 game, follow the worked example showing the banner comment with register contract, column-0 label, and correct data placement. ## Quick Start Use the assembler-conventions skill to check the correct sjasmplus syntax and naming rules before I add a new routine to colisiones.asm.

Frequently Asked Questions about assembler-conventions

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a new routine to a sjasmplus Z80 assembly project?

Create the routine with a label at column 0, indented instructions, a banner comment stating the register contract, and end with ret. Add an INCLUDE line in main.asm, then rebuild with ./build.sh and confirm warnings stay at zero.

Why does sjasmplus report 'Unrecognized instruction' on a DB directive?

The directive was placed at column 0, where sjasmplus parses it as a label and then fails on its operands. Indent every instruction and directive; only labels belong at column 0.

Does sjasmplus support fake instructions like ld iy,ix?

Yes, sjasmplus silently expands fake register-pair loads like ld iy,ix into push/pop sequences that touch the stack, with no warning. Write push ix / pop iy explicitly so the cost is visible in the source.

Can I reorder INCLUDE lines in main.asm to organize the code?

No. All files assemble into one contiguous org $8000 image, so reordering INCLUDE lines relocates every symbol address. Mapas.asm in particular must stay in place because map data is walked contiguously.

Should I normalize mixed case and indentation in existing assembly files?

No. Mixed case, indentation styles, and hex prefixes ($ vs #) all assemble identically in sjasmplus. Normalizing them produces huge diffs with zero functional change; match the style of the file you are editing.