Embedded-Hacking/.opencode/skill/embedded-c-standard/SKILL.md

---

name: embedded-c-standard description: Use ONLY when writing, editing, or reviewing C firmware in a picokit project (firmware/src, firmware/include, firmware/tests). Enforces the strict C standard: no function over 8 executable lines, no blank lines inside a function body, a Doxygen block with @brief/@param/@return on every function, a fixed module layout and naming scheme, and a ban on em/en dashes. Run the bundled audit_c_standard.py before every commit.

Embedded C standard (picokit)

This is non-negotiable and identical in every project in the series. There is no variation between projects. If a rule is inconvenient, refactor; do not exempt.

Rules

1. No function longer than 8 executable lines. The audit counts every non-blank, non-comment, non-brace line in the body, including continuation lines of a wrapped statement. Split the work into a static helper.
2. No blank lines inside a function body. Separate logical steps with a comment, never with a blank line.
3. Documentation lives in the header. Every function declaration in a .h carries a Doxygen block with @brief, a @param for each parameter (@param void No parameters. when there are none), and an @return. A static function, which has no declaration, carries its Doxygen block in the .c. Never duplicate the block in the .c for an exported function.
4. No U+2013 (en dash) or U+2014 (em dash) anywhere. Use the hyphen-minus -.
5. Every source file opens with the MIT header block: Copyright (c) 2026 Kevin Thomas, Author, Email, GitHub, File, Desc, Created.
6. Every header uses an include guard #ifndef <MODULE>_H / #define <MODULE>_H / #endif // <MODULE>_H.
7. Naming: files and modules snake_case; functions module_action; macros UPPER_SNAKE; types name_t; file-scope statics g_name.
8. One responsibility per file: src/<module>.c with include/<module>.h. All hardware access goes through a HAL seam so the host tests can substitute mocks.
9. 79-column lines, four-space indent, no tabs.

Layout

firmware/
  src/        <module>.c
  include/    <module>.h
  tests/      host unit tests, mock/, harness/
  CMakeLists.txt
scripts/      run_tests.py  check_coverage.py  build.sh

Verify

Run the bundled audit from the repository root. Exit 0 is clean; any output is a failure and must be fixed before the change is complete.

python3 .opencode/skill/embedded-c-standard/audit_c_standard.py