@xonovex/skills 0.1.0

package/skills/astro-guidelines/reference/content-collections.md

@@ -0,0 +1,32 @@
+# content-collections: Content Collections with Type Safety
+
+**Guideline:** Use Astro content collections API with Zod schemas for type-safe content management.
+
+**Rationale:** Content collections provide type safety, schema validation, IntelliSense, standardized organization, and build-time frontmatter validation.
+
+**Example:**
+
+```typescript
+// src/content/config.ts
+import {defineCollection, z} from "astro:content";
+
+export const collections = {
+  posts: defineCollection({
+    type: "content",
+    schema: z.object({
+      title: z.string(),
+      published: z.date(),
+      author: z.string(),
+      tags: z.array(z.string()),
+      draft: z.boolean().default(false),
+    }),
+  }),
+};
+```
+
+**Techniques:**
+- Collection schemas: Define Zod schemas in `src/content/config.ts` for validation
+- Directory structure: Organize content in `src/content/[collection-name]/` directories
+- Query functions: Use `getCollection()` and `getEntry()` for type-safe queries
+- Filtering: Apply runtime filters in `getCollection()` callback
+- Rendering: Use `.render()` method to compile markdown to HTML components

package/skills/astro-guidelines/reference/islands-architecture.md

@@ -0,0 +1,26 @@
+# islands-architecture: Islands Architecture and Hydration
+
+**Guideline:** Ship minimal JavaScript by hydrating only interactive components; static HTML by default.
+
+**Rationale:** Astro renders to static HTML by default (zero JS). Framework components only hydrate when marked with directives, resulting in faster loads and better performance.
+
+**Example:**
+
+```astro
+---
+import Counter from "../components/Counter.tsx";
+import SearchBar from "../components/SearchBar.tsx";
+---
+<Layout title="Home">
+  <h1>Static Content</h1>
+  <Counter client:visible />        <!-- Hydrate on viewport entry -->
+  <SearchBar client:load />         <!-- Hydrate immediately -->
+</Layout>
+```
+
+**Techniques:**
+- Static by default: Build pages with Astro components that render zero JavaScript
+- Framework components: Import React, Vue, Svelte only for interactive features
+- client:load: Hydrate immediately for critical interactive components
+- client:visible: Hydrate when component enters viewport for lazy interactivity
+- client:idle: Hydrate during browser idle time for lower-priority features

package/skills/astro-guidelines/reference/project-structure.md

@@ -0,0 +1,32 @@
+# project-structure: Project Structure and Organization
+
+**Guideline:** Organize using conventional directories: pages, components, layouts, content, public.
+
+**Rationale:** Opinionated defaults enable file-based routing, clear separation of concerns, better maintainability, easier navigation.
+
+**Example:**
+
+```
+src/
+├── pages/
+│   ├── index.astro           # → /
+│   ├── about.astro           # → /about
+│   └── blog/[slug].astro     # → /blog/:slug
+├── components/
+│   ├── Header.astro
+│   ├── Card.tsx
+├── layouts/
+│   ├── BaseLayout.astro
+│   └── BlogLayout.astro
+├── content/
+│   ├── config.ts
+│   └── posts/
+└── styles/global.css
+```
+
+**Techniques:**
+- Pages directory: Place routes in `src/pages/` for automatic file-based routing
+- Components folder: Store reusable components in `src/components/`
+- Layouts directory: Create reusable layouts in `src/layouts/`
+- Content collections: Organize structured content in `src/content/[collection]/`
+- Static assets: Place static files in `public/` directory for direct access

package/skills/c99-game-opinionated-guidelines/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: c99-game-opinionated-guidelines
+description: >-
+  Trigger on `.c/.h` files in game/engine directories. Opinionated game engine patterns: caller-owns-memory, inverse mass, SoA optimization, builder pattern. Keywords: vectors, matrices, quaternions, physics, meshes, spatial structures, tagged unions, inverse mass.
+---
+
+# C99 Game Engine Opinionated Guidelines
+
+## Requirements
+
+- C99; extends `c99-guidelines` skill.
+
+## Math
+
+- **Types** - 16-byte aligned vectors/matrices/quaternions, see [reference/math-types.md](reference/math-types.md)
+- **Access** - Use accessor functions for matrices, direct fields for vectors, see [reference/math-types.md](reference/math-types.md)
+- **Coordinates** - Right-handed Y-up, CCW winding, configurable clip depth, see [reference/coordinate-system.md](reference/coordinate-system.md)
+- **Suffixes** - `_aos/_soa` layouts, `_simde` SIMD, `2d/3d` dimensions
+
+## Geometry Pipeline
+
+- **Analytic → Discrete → Packing** - Separate logic/rendering/GPU layers, see [reference/geometry-pipeline.md](reference/geometry-pipeline.md)
+- **Builder pattern** - `*_req()` query size, `*_build()` write to caller buffer, see [reference/builder-pattern.md](reference/builder-pattern.md)
+
+## Patterns
+
+- **Caller-owns-memory** - Libraries never allocate, app provides arrays
+- **Tagged unions** - Type enum + union for polymorphism, see [reference/tagged-unions.md](reference/tagged-unions.md)
+- **Inverse mass** - Store `1/mass`, static objects use `0.0`, see [reference/physics-patterns.md](reference/physics-patterns.md)
+- **SoA optimization** - AoS for single objects, SoA for batches, see [reference/mesh-types.md](reference/mesh-types.md)
+- **Validation** - Check capacity, bounds, NULL, overflow before operations
+
+## Progressive disclosure
+
+- Read [reference/math-types.md](reference/math-types.md) - When working with vectors, matrices, or quaternions
+- Read [reference/coordinate-system.md](reference/coordinate-system.md) - When setting up camera, projection, or mesh normals
+- Read [reference/tagged-unions.md](reference/tagged-unions.md) - When implementing shape or entity polymorphism
+- Read [reference/physics-patterns.md](reference/physics-patterns.md) - When implementing rigid bodies, collision, or constraints
+- Read [reference/geometry-pipeline.md](reference/geometry-pipeline.md) - When converting analytic shapes to renderable meshes
+- Read [reference/builder-pattern.md](reference/builder-pattern.md) - When generating meshes or other variable-size data
+- Read [reference/vertex-packing.md](reference/vertex-packing.md) - When preparing vertex data for GPU upload
+- Read [reference/mesh-types.md](reference/mesh-types.md) - When working with 2D or 3D mesh structures
+- Read [reference/spatial-structures.md](reference/spatial-structures.md) - When implementing broad-phase collision or spatial queries

package/skills/c99-game-opinionated-guidelines/reference/builder-pattern.md

@@ -0,0 +1,29 @@
+# builder-pattern: Builder Pattern for Meshes
+
+**Guideline:** Two-phase construction: `*_req()` queries memory, `*_build()` fills caller-provided buffer.
+
+**Rationale:** Caller controls allocation (stack, pool, arena). Builder never allocates. Exact sizes prevent over-allocation.
+
+**Example:**
+
+```c
+// Query
+mesh_req_t req = sphere_mesh3d_req(1.0f, 32, 16);
+
+// Allocate (caller decides strategy)
+vertex3f_t vertices[req.vertex_count];
+uint32_t indices[req.index_count];
+
+// Build
+mesh3d_t mesh = {.vertices = vertices, .indices = indices,
+                 .vertex_capacity = req.vertex_count,
+                 .index_capacity = req.index_count};
+status_t status = sphere_mesh3d_build(&mesh, 1.0f, 32, 16);
+```
+
+**Techniques:**
+- Query phase: Call `*_req()` to get exact vertex/index counts needed
+- Caller allocation: Choose strategy (stack, malloc, arena) for complete control
+- Build phase: Call `*_build()` to fill pre-allocated caller buffer
+- Status checking: Always check return status for insufficient capacity errors
+- Function naming: Use `{shape}_mesh{dim}_req` and `{shape}_mesh{dim}_build` pattern

package/skills/c99-game-opinionated-guidelines/reference/coordinate-system.md

@@ -0,0 +1,27 @@
+# coordinate-system: Coordinate System Conventions
+
+**Guideline:** Right-handed Y-up coordinates, CCW winding. Use suffixes `_rh`/`_lh` for explicit handedness. Override with defines.
+
+**Rationale:** Consistent handedness and winding across geometry reduces bugs and ensures interoperability with standard graphics APIs.
+
+**Example:**
+
+```c
+// Default (right-handed)
+matrix4f_t proj = matrix4f_perspective(fov, aspect, near, far);
+matrix4f_t view = matrix4f_look_at(eye, target, up);
+
+// Explicit or Vulkan setup
+matrix4f_t view_rh = matrix4f_look_at_rh(eye, target, up);
+matrix4f_t view_lh = matrix4f_look_at_lh(eye, target, up);
+
+#define MATH_COORDINATE_SYSTEM_LEFT_HANDED 1
+#define MATH_CLIP_SPACE_DEPTH_ZERO_TO_ONE 1
+```
+
+**Techniques:**
+- Right-handed default: Use +X right, +Y up, +Z forward as base convention
+- CCW winding: Define front faces with counter-clockwise vertex order
+- Suffix variants: Provide `_rh` and `_lh` function suffixes for explicit systems
+- Compile-time overrides: Use defines like `MATH_COORDINATE_SYSTEM_LEFT_HANDED`
+- Normal calculation: Cross product respects handedness for correct face normals

package/skills/c99-game-opinionated-guidelines/reference/geometry-pipeline.md

@@ -0,0 +1,29 @@
+# geometry-pipeline: Geometry Pipeline
+
+**Guideline:** Three-layer pipeline: Analytic (logic) → Discrete (mesh) → Packing (GPU).
+
+**Rationale:** Each layer handles specific concerns: math/physics, rendering data, GPU format optimization.
+
+**Example:**
+
+```c
+// 1. Analytic
+sphere3d_t sphere = {.center = {0, 1, 0}, .radius = 2.0f};
+
+// 2. Discrete: Build mesh
+mesh_req_t req = sphere_mesh3d_req(&sphere, 32, 16);
+mesh3d_t mesh = {.vertices = verts, .indices = idx,
+                 .vertex_capacity = req.vertex_count};
+sphere_mesh3d_build(&mesh, &sphere, 32, 16);
+
+// 3. Packing: GPU format
+size_t size = mesh3d_pack_size(&mesh, VERTEX_FORMAT_3F_4U8);
+mesh3d_pack_3f_4u8(packed, &mesh, color);
+```
+
+**Techniques:**
+- Analytic layer: Define shapes like `sphere3d_t`, `circle2d_t` for physics/logic
+- Discrete layer: Build indexed meshes from analytic shapes with builder pattern
+- Packing layer: Convert mesh to GPU-ready vertex formats (interleaved/streaming)
+- Separation of concerns: Keep physics, rendering, and GPU separate
+- Conversion functions: Provide `*_req` and `*_build` for shape-to-mesh conversion

package/skills/c99-game-opinionated-guidelines/reference/math-types.md

@@ -0,0 +1,31 @@
+# math-types: Game Math Types
+
+**Guideline:** Use 16-byte aligned vectors/matrices/quaternions. Union-based for named and indexed access.
+
+**Rationale:** 16-byte alignment enables SIMD operations and efficient cache access; unions allow both semantic and array-based access.
+
+**Example:**
+
+```c
+typedef union {
+    struct { float x, y, z, _pad; };
+    float col[4];
+} vec3f_t;
+
+typedef union {
+    float col[16];
+    vec4f_t columns[4];
+} matrix4f_t;
+
+// Usage
+vec3f_t pos = {.x = 1.0f, .y = 2.0f, .z = 3.0f};
+matrix4f_t m;
+m.columns[3] = (vec4f_t){.x = tx, .y = ty, .z = tz, .w = 1.0f};
+```
+
+**Techniques:**
+- 16-byte alignment: Pad vec3 with _pad field for SIMD-friendly 16B size
+- Union design: Combine named fields with array access for flexibility
+- Column-major matrices: Store matrix4f_t as 4 column vectors
+- Quaternion format: Use x, y, z, w order with normalization constraint
+- Array access: Support both `.x`, `.y` named and `[0]`, `[1]` indexed access

package/skills/c99-game-opinionated-guidelines/reference/mesh-types.md

@@ -0,0 +1,32 @@
+# mesh-types: Mesh Data Structures
+
+**Guideline:** Use `mesh2d_t`/`mesh3d_t` with capacity tracking. Builders generate from analytic shapes.
+
+**Rationale:** Separate count/capacity enables efficient reuse; builder pattern decouples construction from memory strategy.
+
+**Example:**
+
+```c
+typedef struct {
+    vertex2f_t *vertices;
+    uint32_t *indices;
+    size_t vertex_count, index_count;
+    size_t vertex_capacity, index_capacity;
+} mesh2d_t;
+
+typedef struct {
+    vertex3f_t *vertices;
+    vec3f_t *normals;     // Optional
+    vec2f_t *uvs;         // Optional
+    uint32_t *indices;
+    size_t vertex_count, index_count;
+    size_t vertex_capacity, index_capacity;
+} mesh3d_t;
+```
+
+**Techniques:**
+- Capacity tracking: Maintain separate count and capacity for dynamic growth
+- Builder pattern: Use `{shape}_mesh{dim}_{req|build}` naming convention
+- Optional data: Include normals/UVs in mesh3d for advanced rendering
+- Operations: Provide bounds calculation, normal computation, merging
+- Vertex types: Use aligned types like `vertex3f_t` with padding for SIMD

package/skills/c99-game-opinionated-guidelines/reference/physics-patterns.md

@@ -0,0 +1,28 @@
+# physics-patterns: Physics Engine Patterns
+
+**Guideline:** Use inverse mass (0 = static), bit flags for state, sync maps for decoupled systems.
+
+**Rationale:** Inverse mass simplifies static bodies and impulse application; flags enable efficient state management; sync maps decouple physics from entity systems.
+
+**Example:**
+
+```c
+typedef struct {
+    vec3f_t position, velocity;
+    float inv_mass;  // 0 = static (never moves)
+} rigidbody_t;
+
+// Automatically handles static (inv_mass=0 zeroes impulse)
+void apply_impulse(rigidbody_t *rb, vec3f_t impulse) {
+    rb->velocity.x += impulse.x * rb->inv_mass;
+    rb->velocity.y += impulse.y * rb->inv_mass;
+    rb->velocity.z += impulse.z * rb->inv_mass;
+}
+```
+
+**Techniques:**
+- Inverse mass: Store `inv_mass` (1/mass); zero for static bodies to disable movement
+- Bit flags: Use `uint32_t` with bitmask enums for state like ACTIVE, SLEEPING
+- Sync maps: Index maps decouple physics arrays from entity system arrays
+- Flag operations: Use `|=` (set), `&= ~` (clear), `&` (test) for bit manipulation
+- Update loop: Separate integration, broadphase detection, and narrowphase solving

package/skills/c99-game-opinionated-guidelines/reference/spatial-structures.md

@@ -0,0 +1,26 @@
+# spatial-structures: Spatial Data Structures
+
+**Guideline:** Use dimension-suffixed structures (grid, tree, bvh) for broad-phase queries. Choose by density/pattern.
+
+**Rationale:** Different structures suit different spatial distributions; dimension suffixes (_2d, _3d) enable consistent APIs across dimensions.
+
+**Example:**
+
+```c
+typedef struct {
+    uint32_t *cells, *objects;
+    aabb2d_t bounds;
+    uint32_t cells_x, cells_y;
+} grid2d_t;
+
+uint32_t cell_x = (uint32_t)((pos.x - g->bounds.min.x) / cell_width);
+uint32_t cell_y = (uint32_t)((pos.y - g->bounds.min.y) / cell_height);
+uint32_t cell_idx = cell_y * g->cells_x + cell_x;
+```
+
+**Techniques:**
+- Uniform grids: Use for dense/uniform object distributions with O(1) insertion
+- Quadtrees/Octrees: Use for sparse/varying density with O(log n) operations
+- BVH structures: Use for static geometry and ray casting queries
+- KD-trees: Use for point clouds and nearest-neighbor searches
+- SoA variants: Provide `_soa` versions for batch processing same-type queries

package/skills/c99-game-opinionated-guidelines/reference/tagged-unions.md

@@ -0,0 +1,40 @@
+# tagged-unions: Tagged Union Pattern
+
+**Guideline:** Type enum + union for polymorphism without virtual functions. Cache-friendly, compiler optimizable.
+
+**Rationale:** Avoids virtual function overhead and pointer chasing; enables compiler exhaustiveness checks and efficient batch processing.
+
+**Example:**
+
+```c
+typedef enum {
+    SHAPE_SPHERE, SHAPE_BOX, SHAPE_CAPSULE,
+} shape_type_t;
+
+typedef struct {
+    shape_type_t type;
+    union {
+        struct { float radius; } sphere;
+        struct { vec3f_t half_extents; } box;
+        struct { float radius, height; } capsule;
+    };
+} shape_t;
+
+float shape_volume(const shape_t *s) {
+    switch (s->type) {
+        case SHAPE_SPHERE:
+            return (4.0f/3.0f) * PI * s->sphere.radius * s->sphere.radius * s->sphere.radius;
+        case SHAPE_BOX:
+            return 8 * s->box.half_extents.x * s->box.half_extents.y * s->box.half_extents.z;
+        case SHAPE_CAPSULE:
+            return PI * s->capsule.radius * s->capsule.radius * s->capsule.height;
+    }
+}
+```
+
+**Techniques:**
+- Type enum: Define all variant types in single enum for exhaustiveness
+- Union members: Create named structs within union for each type variant
+- Switch dispatch: Use switch on type field with no default clause
+- Designated init: Use `.type = SHAPE_BOX, .box = {...}` for clarity
+- Small members: Keep union data small; use pointers for large heap data

package/skills/c99-game-opinionated-guidelines/reference/vertex-packing.md

@@ -0,0 +1,38 @@
+# vertex-packing: Vertex Packing for GPU
+
+**Guideline:** Pack mesh data to GPU-ready formats. Support interleaved (single buffer) and non-interleaved (streaming).
+
+**Rationale:** GPU-ready vertex formats maximize performance; flexible layouts support different rendering pipelines and optimization strategies.
+
+**Example:**
+
+```c
+typedef struct {
+    float x, y, z;
+    uint8_t r, g, b, a;
+} vertex_3f_4u8_t;
+
+void mesh3d_pack_3f_4u8(vertex_3f_4u8_t *out, const mesh3d_t *m, color4u8_t c) {
+    for (size_t i = 0; i < m->vertex_count; i++) {
+        out[i] = (vertex_3f_4u8_t){
+            m->vertices[i].x, m->vertices[i].y, m->vertices[i].z,
+            c.r, c.g, c.b, c.a
+        };
+    }
+}
+
+size_t mesh3d_pack_size(const mesh3d_t *m, vertex_format_t fmt) {
+    switch(fmt) {
+        case VERTEX_FORMAT_3F: return m->vertex_count * 12;
+        case VERTEX_FORMAT_3F_4U8: return m->vertex_count * 16;
+    }
+    return 0;
+}
+```
+
+**Techniques:**
+- Vertex format naming: Use `vertex_{components}_{types}_t` (e.g., `vertex_3f_4u8_t`)
+- Interleaved layout: Pack all attributes per-vertex in single buffer
+- Streaming layout: Separate position/normal/UV into different buffers
+- Size queries: Provide `*_pack_size` functions before allocation
+- No GPU calls: Library never touches graphics APIs; caller handles upload

package/skills/c99-guidelines/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: c99-guidelines
+description: >-
+  Trigger on `.c/.h` files. Use when writing C99 code. Apply for memory management, data structures, low-level operations. Keywords: C99, malloc/free, const-correctness, designated initializers, inline functions, error handling.
+---
+
+# C99 Coding Guidelines
+
+## Essentials
+
+- **Memory management** - Free all heap allocations, avoid leaks, see [reference/memory-management.md](reference/memory-management.md)
+- **Modern C99** - Use `const`, designated initializers, small functions, see [reference/designated-initializers.md](reference/designated-initializers.md), [reference/const-correctness.md](reference/const-correctness.md)
+- **Type safety** - Favor `inline` functions over macros where practical, see [reference/inline-functions.md](reference/inline-functions.md)
+- **Quality** - Enable warnings, run static analysis
+
+## Best practices
+
+- **Error handling** - Use return codes, check all fallible operations, see [reference/error-handling.md](reference/error-handling.md)
+- **Input validation** - Check bounds, NULL pointers, division by zero
+- **Readability** - Small functions, clear naming, comments for non-obvious logic
+
+## Progressive disclosure
+
+- Read [reference/memory-management.md](reference/memory-management.md) - When allocating memory or managing resource lifetimes
+- Read [reference/designated-initializers.md](reference/designated-initializers.md) - When initializing structs or arrays with specific values
+- Read [reference/inline-functions.md](reference/inline-functions.md) - When replacing macros or writing small utility functions
+- Read [reference/compound-literals.md](reference/compound-literals.md) - When creating temporary values without named variables
+- Read [reference/const-correctness.md](reference/const-correctness.md) - When marking immutable data or understanding pointer const
+- Read [reference/error-handling.md](reference/error-handling.md) - When implementing error codes or handling failures

package/skills/c99-guidelines/reference/compound-literals.md

@@ -0,0 +1,33 @@
+# compound-literals: Compound Literals
+
+**Guideline:** Use compound literals to create temporary values inline without declaring separate variables.
+
+**Rationale:** Compound literals reduce boilerplate code and improve readability by creating temporary structs or arrays directly in expressions.
+
+**Example:**
+
+```c
+struct Point {
+    int x, y;
+};
+
+int distance(struct Point a, struct Point b);
+
+void example(void) {
+    // Create temporary Point inline
+    int d = distance(
+        (struct Point){.x = 0, .y = 0},
+        (struct Point){.x = 3, .y = 4}
+    );
+
+    // Initialize array inline
+    int arr[] = {(int[]){1, 2, 3, 4, 5}};
+}
+```
+
+**Techniques:**
+- Inline syntax: Use `(Type){initializer-list}` to create temporaries inline
+- With designators: Combine with designated initializers for clarity
+- Function arguments: Create temporary structs directly in function calls
+- Aggregate types: Works with any struct or array type
+- Automatic cleanup: Lifetime extends to end of enclosing scope automatically

package/skills/c99-guidelines/reference/const-correctness.md

@@ -0,0 +1,32 @@
+# const-correctness: Const Correctness
+
+**Guideline:** Use const qualifier to mark immutable data, function parameters, and return values to prevent unintended modifications.
+
+**Rationale:** Const correctness catches bugs at compile time, documents intent, and helps maintain API contracts.
+
+**Example:**
+
+```c
+// Use const for immutable data
+void process_buffer(const char *input, size_t len) {
+    // input cannot be modified
+}
+
+// Const pointers
+const int *p1;        // pointer to const int
+int *const p2;        // const pointer to int
+const int *const p3;  // const pointer to const int
+
+// Const in function return
+const char *get_name(void) {
+    static const char name[] = "example";
+    return name;
+}
+```
+
+**Techniques:**
+- Read-only parameters: Mark function parameters with const when not modified
+- Pointer variants: Distinguish `const T *p` (pointer to const) vs `T *const p` (const pointer)
+- Return values: Use const for immutable return values to prevent modification
+- Intent documentation: Const clearly indicates what can/cannot be modified
+- Compile-time safety: Catches unintended modifications at compile time

package/skills/c99-guidelines/reference/designated-initializers.md

@@ -0,0 +1,32 @@
+# designated-initializers: Designated Initializers
+
+**Guideline:** Use designated initializers for struct and array initialization to make code self-documenting and reduce errors.
+
+**Rationale:** Designated initializers explicitly name fields being initialized, making code more readable and maintainable.
+
+**Example:**
+
+```c
+struct Point {
+    int x, y, z;
+};
+
+// Named field initialization
+struct Point p = {.x = 1, .y = 2, .z = 3};
+
+// Partial initialization (rest zeroed)
+struct Point origin = {.x = 0, .y = 0};
+
+// Array designated initializers
+int days[12] = {
+    [0] = 31, [1] = 28, [2] = 31,
+    [3] = 30, [4] = 31, [5] = 30
+};
+```
+
+**Techniques:**
+- Field syntax: Use `.field = value` for struct initialization with clarity
+- Array syntax: Use `[index] = value` for sparse array initialization
+- Partial init: Unspecified fields are automatically zeroed without explicit values
+- Order-independent: Fields can be specified in any order within initializer
+- Large structs: Especially useful for structs with many fields or optional fields

package/skills/c99-guidelines/reference/error-handling.md

@@ -0,0 +1,49 @@
+# error-handling: Error Handling Patterns
+
+**Guideline:** Return error codes from functions and use output parameters for results to enable proper error checking and recovery.
+
+**Rationale:** Error codes force callers to handle errors explicitly, unlike exceptions. Using return values for errors and output parameters for results creates a consistent pattern throughout the codebase.
+
+**Example:**
+
+```c
+typedef enum {
+    ERR_OK = 0,
+    ERR_NOMEM,
+    ERR_INVALID,
+    ERR_IO
+} error_t;
+
+error_t load_file(const char *path, char **out, size_t *len) {
+    FILE *f = fopen(path, "rb");
+    if (!f) return ERR_IO;
+
+    fseek(f, 0, SEEK_END);
+    long size = ftell(f);
+    fseek(f, 0, SEEK_SET);
+
+    char *buf = malloc(size);
+    if (!buf) {
+        fclose(f);
+        return ERR_NOMEM;
+    }
+
+    if (fread(buf, 1, size, f) != (size_t)size) {
+        free(buf);
+        fclose(f);
+        return ERR_IO;
+    }
+
+    fclose(f);
+    *out = buf;
+    *len = size;
+    return ERR_OK;
+}
+```
+
+**Techniques:**
+- Error enums: Define descriptive error types with zero for success
+- Output parameters: Use pointers to return multiple results alongside error codes
+- Error checking: Always check return values immediately after function calls
+- Cleanup: Properly free resources in all error paths before returning
+- Context: Provide specific error codes to indicate failure reason, not generic errors

package/skills/c99-guidelines/reference/inline-functions.md

@@ -0,0 +1,37 @@
+# inline-functions: Inline Functions vs Macros
+
+**Guideline:** Prefer static inline functions over macros for type safety and predictable behavior.
+
+**Rationale:** Inline functions provide type checking, proper scoping, and avoid macro side effects like multiple evaluation of arguments.
+
+**Example:**
+
+```c
+// Macro - unsafe, no type checking
+#define CLAMP(v, lo, hi) ((v) < (lo) ? (lo) : ((v) > (hi) ? (hi) : (v)))
+
+// Inline function - type safe
+static inline int clampi(int v, int lo, int hi) {
+    if (v < lo) return lo;
+    if (v > hi) return hi;
+    return v;
+}
+
+static inline float clampf(float v, float lo, float hi) {
+    if (v < lo) return lo;
+    if (v > hi) return hi;
+    return v;
+}
+
+// Macro side effect: x++ evaluated multiple times
+// Inline function: x++ evaluated once safely
+int x = 5;
+int result = clampi(x++, 0, 10);
+```
+
+**Techniques:**
+- Replace macros: Replace function-like macros with `static inline` functions
+- Type-specific variants: Create `clampi`, `clampf` instead of generic macro
+- Header placement: Use inline functions in headers for no multiple definition issues
+- Avoid side effects: Inline functions safely evaluate arguments once
+- Simple logic: Keep inline functions simple for compiler optimization