Skip to content
Skills Library
Programming · Building & coding

assembly-guide

/assembly-guide

Assembly language guardrails, patterns, and best practices for AI-assisted development. Use when working with assembly files (.asm, .s, .S), or when the user mentions Assembly/x86/ARM. Provides calling convention guidelines, register usage patterns, and debugging techniques specific to this project's coding standards.

Repository
samuel ↗
Licence
MIT
Last repository change
29.04.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
8
Deprecation

No signals detected. Repository changed on 29.04.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Assembly language guardrails, patterns, and best practices for AI-assisted development. Use when working with assembly files (.asm, .s, .S), or when the user mentions Assembly/x86/ARM. Provides calling convention guidelines, register usage patterns, and debugging techniques specific to this project's coding standards.

Original author description

Assembly language guardrails, patterns, and best practices for AI-assisted development. Use when working with assembly files (.asm, .s, .S), or when the user mentions Assembly/x86/ARM. Provides calling convention guidelines, register usage patterns, and debugging techniques specific to this project's coding standards.

How it works

  1. Core Principles
  2. Guardrails
  3. Key Patterns
  4. Debugging
  5. Tooling
  6. References
  7. External References
Original SKILL.md headings · 241 lines, 1,101 words
SKILL.md preview
---
name: assembly-guide
description: |
  Assembly language guardrails, patterns, and best practices for AI-assisted development.
  Use when working with assembly files (.asm, .s, .S), or when the user mentions Assembly/x86/ARM.
  Provides calling convention guidelines, register usage patterns, and debugging techniques
  specific to this project's coding standards.
license: MIT
metadata:
  author: samuel
  version: "1.0"
  category: language
  language: assembly
  extensions: ".asm,.s,.S"
---

# Assembly Guide

> Applies to: x86-64 (System V ABI), ARM64 (AAPCS), NASM, GAS syntax

## Core Principles

1. **Clarity Over Cleverness**: Comment every instruction's purpose; assembly lacks self-documentation
2. **ABI Compliance**: Follow calling conventions precisely for interoperability with C/system code
3. **Minimal Register Pressure**: Preserve callee-saved registers, minimize spills to stack
4. **Correctness First**: Get it working correctly, then profile, then optimize with SIMD
5. **Structured Layout**: Use consistent label naming, section organization, and macro definitions

## Guardrails

### Architecture Selection

- Declare target architecture at the top of every file
- x86-64: default for Linux/macOS server and desktop workloads
- ARM64: default for Apple Silicon, mobile, and embedded Linux
- Never mix architecture-specific code without `%ifdef` / `.ifdef` guards

### Calling Conventions

- **x86-64 System V ABI** (Linux, macOS, BSD):
  - Arguments: `rdi`, `rsi`, `rdx`, `rcx`, `r8`, `r9` (integer/pointer, in order)
  - Floating-point arguments: `xmm0`-`xmm7`
  - Return value: `rax` (integer), `xmm0` (float)
  - Caller-saved (volatile): `rax`, `rcx`, `rdx`, `rsi`, `rdi`, `r8`-`r11`
  - Callee-saved (non-volatile): `rbx`, `rbp`, `r12`-`r15`
  - Stack must be 16-byte aligned before `call` instruction
- **ARM64 AAPCS** (Linux, macOS):
  - Arguments: `x0`-`x7` (integer/pointer), `d0`-`d7` (float)
  - Return value: `x0` (integer), `d0` (float)
  - Callee-saved: `x19`-`x28`, `x29` (frame pointer), `x30` (link register)
  - Stack must be 16-byte aligned at all times

### Register Usage

- Document which registers hold which logical values at function entry
- Never clobber callee-saved registers without saving and restoring them
- Use `rbp` / `x29` as frame pointer for debuggability (omit only in leaf functions)
- Reserve scratch registers for temporaries; name them in comments
- Zero-extend results when returning values smaller than 64 bits

### Stack Management

- Always maintain 16-byte stack alignment on x86-64 and ARM64
- Allocate local variables by subtracting from `rsp` / `sp` in the prologue
- Deallocate in the epilogue before `ret` (never leave the stack dirty)
- Use red zone (128 bytes below `rsp`) only in leaf functions on System V ABI
- Never write below the stack pointer outside the red zone

### Documentation

- File header: purpose, target architecture, assembler syntax, author
- Function header: C-style prototype comment, argument register mapping, return value
- Inline comments: explain the *why*, not the *what* (avoid `; increment counter`)
- Label naming: `module_function_sublabel` (e.g., `crypto_sha256_loop`)
- Constants: use `equ` / `.equ` directives with descriptive names

## Key Patterns

### x86-64 Function with Frame Pointer

```nasm
; long compute(long x, long y, long z)
; Args: rdi = x, rsi = y, rdx = z
; Returns: rax = x * y + z
global compute
compute:
    push    rbp                 ; save frame pointer
    mov     rbp, rsp            ; establish stack frame
    mov     rax, rdi            ; rax = x
    imul    rax, rsi            ; rax = x * y
    add     rax, rdx            ; rax = x * y + z
    pop     rbp                 ; restore frame pointer
    ret
```

### ARM64 AAPCS Function

```asm
// int64_t multiply_add(int64_t a, int64_t b, int64_t c)
// Args: x0 = a, x1 = b, x2 = c  |  Returns: x0 = a * b + c
    .global multiply_add
multiply_add:
    stp     x29, x30, [sp, #-16]!  // save fp and lr
    mov     x29, sp                 // establish stack frame
    mul     x0, x0, x1              // x0 = a * b
    add     x0, x0, x2              // x0 = a * b + c
    ldp     x29, x30, [sp], #16     // restore fp and lr
    ret
```

### SIMD / SSE2 (4 floats per iteration)

```nasm
; void add_f32(float *dst, const float *a, const float *b, size_t n)
; Args: rdi = dst, rsi = a, rdx = b, rcx = n
global add_f32
add_f32:
    shr     rcx, 2              ; n /= 4
.loop:
    test    rcx, rcx
    jz      .done
    movups  xmm0, [rsi]        ; load 4 floats from a
    addps   xmm0, [rdx]        ; add 4 floats from b
    movups  [rdi], xmm0        ; store result
    add     rsi, 16
    add     rdx, 16
    add     rdi, 16
    dec     rcx
    jnz     .loop
.done:
    ret
```

### Linux x86-64 Syscall Interface

```nasm
; Syscall: rax = number, args in rdi/rsi/rdx/r10/r8/r9, return in rax
; Note: r10 replaces rcx (clobbered by syscall instruction)
SYS_WRITE equ 1
SYS_EXIT  equ 60

section .data
    msg db "Hello, world!", 10
    msg_len equ $ - msg

section .text
global _start
_start:
    mov     rax, SYS_WRITE      ; write(stdout, msg, msg_len)
    mov     rdi, 1               ; fd = STDOUT
    lea     rsi, [rel msg]       ; RIP-relative for PIC
    mov     rdx, msg_len
    syscall
    mov     rax, SYS_EXIT        ; exit(0)
    xor     edi, edi
    syscall
```

### Position-Independent Code (PIC)

```nasm
default rel                     ; all memory refs become RIP-relative

section .data
    counter dq 0

section .text
global get_counter
get_counter:
    mov     rax, [counter]      ; RIP-relative with default rel
    ret

global increment_counter
increment_counter:
    lock inc qword [counter]    ; atomic increment (thread-safe)
    mov     rax, [counter]
    ret
```

## Debugging

### GDB Commands

```bash
gdb ./program
(gdb) layout asm                # show disassembly window
(gdb) layout regs               # show registers window
(gdb) stepi                     # step one instruction
(gdb) nexti                     # step over call
(gdb) info registers            # print all register values
(gdb) p/x $rax                  # print rax in hex
(gdb) x/4gx $rsp               # examine 4 quad-words at stack pointer
(gdb) break *0x401000           # break at address
(gdb) display/i $pc             # show current instruction after each step
(gdb) set disassembly-flavor intel
```

### objdump & strace

```bash
objdump -d -M intel program     # disassemble with Intel syntax
objdump -h program              # show section headers
objdump -t program              # show symbol table
objdump -r program.o            # show relocations (PIC debugging)

strace ./program                # trace all syscalls
strace -e trace=write,read ./program  # filter specific syscalls
```

## Tooling

### Assemblers & Linkers

```bash
# NASM (Intel syntax)
nasm -f elf64 -g -F dwarf program.asm -o program.o   # Linux
nasm -f macho64 program.asm -o program.o              # macOS

# GAS (AT&T syntax, supports .intel_syntax)
as --64 -g program.s -o program.o

# LLVM
clang -c program.s -o program.o

# Linking
ld -o program program.o               # bare metal (no libc)
gcc -o program program.o              # with libc (C interop)
gcc -shared -o libfoo.so foo.o        # shared library (requires PIC)
```

### Verification

```bash
nm program.o                    # verify symbol visibility
nm -u program.o                 # check undefined references
readelf -S program.o            # verify section layout
# In GDB: p/x $rsp & 0xf       # should be 0x0 at call boundaries
```

## References

For detailed patterns and code examples, see:

- [references/patterns.md](references/patterns.md) -- Prologue/epilogue, syscall examples, SIMD patterns

## External References

- [x86-64 System V ABI Specification](https://gitlab.com/x86-psABIs/x86-64-ABI)
- [ARM Architecture Reference Manual](https://developer.arm.com/documentation/ddi0487/latest)
- [NASM Documentation](https://www.nasm.us/doc/)
- [GAS Manual (GNU Assembler)](https://sourceware.org/binutils/docs/as/)
- [Intel Intrinsics Guide (SSE/AVX)](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html)
- [Linux Syscall Table (x86-64)](https://blog.rchapman.org/posts/Linux_System_Call_Table_for_x86_64/)
- [Agner Fog's Optimization Manuals](https://www.agner.org/optimize/)
- [Felix Cloutier x86 Instruction Reference](https://www.felixcloutier.com/x86/)
Files in this package (2)
  • SKILL.md 8 KB
  • references/patterns.md 3 KB

Versions

The database has no other skills named assembly-guide.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 408848f4c0a5 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100go-guide
    Go language guardrails, patterns, and best practices for AI-assisted development. Use when working with Go files (.go), go.mod, or when the user mentions Go/Golang. Provides project structure conventions, error handling patterns, testing standards, and concurrency guidelines…
  • 100html-css-guide
    HTML and CSS guardrails, patterns, and best practices for AI-assisted development. Use when working with HTML/CSS files (.html, .css, .scss, .less), or when the user mentions HTML/CSS. Provides semantic HTML guidelines, accessibility standards, modern CSS patterns, and…
  • 86assembly
    汇编语言开发专家助手。当用户需要进行汇编语言编程、x86/ARM指令集、底层系统开发、逆向工程或嵌入式汇编时调用。
  • 100assembly-arm
    AArch64 and ARM assembly skill for reading and writing ARM assembly code. Use when reading GCC/Clang output for AArch64 or ARM Thumb targets, writing inline asm in C/C++, understanding the ARM ABI (AAPCS64/AAPCS), or debugging register and stack state on ARM hardware or QEMU.…
  • 100assembly-arm
    Use when reading or writing AArch64 or AArch32 Thumb assembly, inline asm in C, AAPCS64 register roles, or NEON and SVE vector code. Not for ABI detail across ISAs: use abi-and-calling-conventions.
  • 100assembly
    Expert x86-64 and ARM64 assembly assistance covering registers, calling conventions, stack frames, and inline asm. Use when writing low-level code, optimizing hot loops, or reverse engineering binaries.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.