@xonovex/skills 0.1.0

package/skills/c99-guidelines/reference/memory-management.md

@@ -0,0 +1,35 @@
+# memory-management: Memory Management Patterns
+
+**Guideline:** Prefer stack allocation and ensure proper cleanup of heap allocations with clear ownership tracking.
+
+**Rationale:** Proper memory management prevents leaks and use-after-free bugs. Stack allocation is simpler as it's automatically cleaned up when the function returns.
+
+**Example:**
+
+```c
+// Stack allocation (preferred)
+void process_data(void) {
+    char buffer[1024];
+    int values[100];
+    // Automatically freed when function returns
+}
+
+// Heap allocation with explicit free
+void dynamic_array(size_t size) {
+    int *array = malloc(size * sizeof(int));
+    if (!array) {
+        return;  // Handle allocation failure
+    }
+
+    // Use array...
+
+    free(array);  // Always free
+}
+```
+
+**Techniques:**
+- Default stack: Use stack allocation for fixed-size data by default
+- Heap when needed: Use malloc/calloc only for dynamic or longer-lived data
+- Malloc/free pairing: Always pair every malloc with corresponding free call
+- Failure checking: Check allocation return value before dereferencing
+- Clear ownership: Document who owns and must free each allocation

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

@@ -0,0 +1,44 @@
+---
+name: c99-opinionated-guidelines
+description: >-
+  Trigger on `.c/.h` files for systems/game/embedded development. Opinionated patterns: caller-owns-memory, data-oriented design (SoA), SIMD variants, strict file naming. Keywords: C99, alignment, SIMD, AoS/SoA, caller-owns-memory, data-oriented design.
+---
+
+# C99 Opinionated Guidelines (Systems/Game/Embedded)
+
+## Essentials
+
+- **Memory management** - Prefer stack, free all heap allocations, 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, see [reference/inline-functions.md](reference/inline-functions.md)
+- **Data-oriented design** - Structure for cache locality, see [reference/data-oriented-design.md](reference/data-oriented-design.md)
+- **Quality** - Treat warnings as errors, run static analysis
+
+## Architecture
+
+- **Implementation variants** - Scalar → AoS → SoA → SIMD, see [reference/implementation-variants.md](reference/implementation-variants.md)
+- **Caller-owns-memory** - Libraries never allocate, caller provides arrays, see [reference/caller-owns-memory.md](reference/caller-owns-memory.md)
+- **Alignment** - 16-byte for SIMD, cache line for hot data, see [reference/alignment.md](reference/alignment.md)
+- **File naming** - `*_type.h`, `*_impl.h`, `*_aos.h`, `*_soa.h`, `*_simde.h`, see [reference/file-naming.md](reference/file-naming.md)
+
+## Safety
+
+- **Input validation** - Check capacity, bounds, NULL, division, overflow, see [reference/safety-validations.md](reference/safety-validations.md)
+- **Work buffers** - Complex functions use caller-provided buffers, see [reference/caller-owns-memory.md](reference/caller-owns-memory.md)
+- **SIMD parity** - Test variants against scalar reference, see [reference/testing-patterns.md](reference/testing-patterns.md)
+
+## 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/data-oriented-design.md](reference/data-oriented-design.md) - When optimizing cache performance or data layouts
+- Read [reference/error-handling.md](reference/error-handling.md) - When implementing error codes or handling failures
+- Read [reference/implementation-variants.md](reference/implementation-variants.md) - When choosing between scalar, AoS, SoA, or SIMD implementations
+- Read [reference/caller-owns-memory.md](reference/caller-owns-memory.md) - When designing APIs where caller provides memory
+- Read [reference/alignment.md](reference/alignment.md) - When aligning data for SIMD or cache performance
+- Read [reference/file-naming.md](reference/file-naming.md) - When organizing headers by type, implementation, and variant
+- Read [reference/testing-patterns.md](reference/testing-patterns.md) - When writing tests with assertions, epsilon comparisons, or parity checks
+- Read [reference/safety-validations.md](reference/safety-validations.md) - When validating inputs for capacity, bounds, NULL, or overflow

package/skills/c99-opinionated-guidelines/reference/alignment.md

@@ -0,0 +1,50 @@
+# alignment: Memory Alignment
+
+**Guideline:** 16 bytes for SIMD, cache line (64/128B) for hot data.
+
+**Rationale:** SIMD loads require alignment. Misalignment causes penalties/crashes. Cache alignment prevents false sharing in concurrent code.
+
+**Example:**
+
+```c
+// SIMD-friendly vec3 (16 bytes)
+typedef struct { float x, y, z, _pad; } vec3_t;
+
+// Compiler alignment
+typedef struct { _Alignas(16) float data[4]; } aligned_vec4_t;
+
+// Cache-line aligned hot data
+#define CACHE_LINE_SIZE 64
+typedef struct {
+    _Alignas(CACHE_LINE_SIZE) uint32_t counter;
+    char pad[CACHE_LINE_SIZE - sizeof(uint32_t)];
+} atomic_counter_t;
+
+// SoA arrays
+typedef struct {
+    _Alignas(16) float *x, *y, *z;
+    size_t count;
+} vec3_soa_t;
+
+// Aligned allocation
+void *aligned_alloc_16(size_t size) {
+    void *ptr;
+    return posix_memalign(&ptr, 16, size) == 0 ? ptr : NULL;
+}
+
+// Platform detection
+#if defined(__x86_64__) || defined(_M_X64)
+    #define CACHE_LINE_SIZE 64
+#elif defined(__aarch64__)
+    #define CACHE_LINE_SIZE 128
+#else
+    #define CACHE_LINE_SIZE 64
+#endif
+```
+
+**Techniques:**
+- SIMD alignment: Pad vec3 to 16-byte aligned structures for SIMD instructions
+- Compiler directives: Use `_Alignas(16)` for explicit struct field alignment
+- SoA layout: Align array-of-structures for batch SIMD operations
+- Cache alignment: Align hot data to 64B (x86) or 128B (ARM) cache line size
+- Platform detection: Use conditional compilation for architecture-specific alignment

package/skills/c99-opinionated-guidelines/reference/caller-owns-memory.md

@@ -0,0 +1,38 @@
+# caller-owns-memory: Caller-Owns-Memory Pattern
+
+**Guideline:** Libraries never allocate. Caller provides all storage; library operates on it.
+
+**Rationale:** No hidden allocations. Caller controls memory strategy (stack, pool, arena). No leaks. Batch-friendly.
+
+**Example:**
+
+```c
+typedef struct {
+    float *pos_x, *pos_y;
+    uint32_t count, capacity;
+} entity_system_t;
+
+status_t entity_system_init(entity_system_t *sys,
+    float *x, float *y, uint32_t cap) {
+    sys->pos_x = x;
+    sys->pos_y = y;
+    sys->count = 0;
+    sys->capacity = cap;
+    return STATUS_OK;
+}
+
+status_t entity_add(entity_system_t *sys, float x, float y) {
+    if (sys->count >= sys->capacity) return STATUS_FULL;
+    sys->pos_x[sys->count] = x;
+    sys->pos_y[sys->count] = y;
+    sys->count++;
+    return STATUS_OK;
+}
+```
+
+**Techniques:**
+- Functions receive pointers: Accept caller-provided storage instead of allocating
+- Init functions: Bind library state to caller-owned arrays with capacity tracking
+- Status returns: Return status codes, never allocated pointers
+- Work buffers: Accept scratch space from caller for temporary operations
+- Batch-friendly: Enable processing arrays without individual allocations

package/skills/c99-opinionated-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-opinionated-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-opinionated-guidelines/reference/data-oriented-design.md

@@ -0,0 +1,42 @@
+# data-oriented-design: Data-Oriented Design
+
+**Guideline:** Organize data structures for cache locality using Struct of Arrays (SoA) instead of Array of Structs (AoS) when processing arrays of data.
+
+**Rationale:** Modern CPUs load data in cache lines. Struct of Arrays layout ensures sequential memory access patterns that maximize cache utilization.
+
+**Example:**
+
+```c
+// Array of Structs (AoS) - poor cache locality
+struct Entity {
+    float x, y, z;      // Position
+    float vx, vy, vz;   // Velocity
+    int health;
+    int type;
+};
+
+struct Entity entities[1000];
+for (size_t i = 0; i < 1000; i++) {
+    entities[i].x += entities[i].vx;
+}
+
+// Struct of Arrays (SoA) - better cache locality
+struct EntitySystem {
+    float *positions_x, *positions_y, *positions_z;
+    float *velocities_x, *velocities_y, *velocities_z;
+    int *health, *type;
+    size_t count;
+};
+
+// Sequential memory access, better cache usage
+for (size_t i = 0; i < system.count; i++) {
+    system.positions_x[i] += system.velocities_x[i];
+}
+```
+
+**Techniques:**
+- Separate fields: Move frequently accessed fields into their own arrays
+- Cache locality: Sequential memory access maximizes CPU cache utilization
+- Array sync: Keep indices synchronized across all component arrays
+- Hot loops: Identify performance-critical loops for SoA conversion
+- Measurement: Profile before and after refactoring to verify improvements

package/skills/c99-opinionated-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-opinionated-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-opinionated-guidelines/reference/file-naming.md

@@ -0,0 +1,33 @@
+# file-naming: File Naming Conventions
+
+**Guideline:** Suffixes for purpose: `_type.h` (types), `_impl.h` (scalar), `_aos/_soa/_simd` (variants).
+
+**Rationale:** Enables quick file identification, prevents include order issues, supports multiple variant implementations.
+
+**Example:**
+
+```
+vector_type.h        # Types only
+vector_impl.h        # Scalar implementations
+vector.h             # Includes _type + _impl
+vector_aos.h         # Batch AoS
+vector_soa.h         # Batch SoA (cache-friendly)
+vector_simd_impl.h   # SIMD scalar
+vector_soa_simd.h    # SIMD SoA batch
+vector.test.c        # Scalar tests
+
+// vector.h
+#include "vector_type.h"
+#include "vector_impl.h"
+
+// vector_soa_simd.h
+#include "vector_type.h"
+#include "vector_soa.h"
+```
+
+**Techniques:**
+- Type suffix: Use `_type.h` for type definitions only
+- Impl suffix: Use `_impl.h` for inline scalar implementations
+- Batch variants: Use `_aos.h`, `_soa.h` for batch implementations
+- SIMD suffix: Use `_simd.h` for SIMD implementations
+- Dimension modules: Use `{name}{dim}.h` pattern like `aabb2d.h`, `sphere3d_simd.h`

package/skills/c99-opinionated-guidelines/reference/implementation-variants.md

@@ -0,0 +1,35 @@
+# implementation-variants: Implementation Variant Strategy
+
+**Guideline:** Progressive variants: scalar single → AoS batch → SoA batch → SIMD.
+
+**Rationale:** Different use cases need different trade-offs: debugging (single), existing structs (AoS), cache-friendly (SoA), peak throughput (SIMD).
+
+**Example:**
+
+```c
+// Scalar single (reference)
+float vec3_dot(const vec3_t *a, const vec3_t *b) {
+    return a->x*b->x + a->y*b->y + a->z*b->z;
+}
+
+// AoS batch (struct arrays)
+void vec3_dot_aos(float *out, const vec3_t *a, const vec3_t *b, size_t n) {
+    for (size_t i = 0; i < n; i++)
+        out[i] = a[i].x*b[i].x + a[i].y*b[i].y + a[i].z*b[i].z;
+}
+
+// SoA batch (component arrays, cache-friendly)
+typedef struct { float *x, *y, *z; size_t count; } vec3_soa_t;
+
+void vec3_dot_soa(float *out, const vec3_soa_t *a, const vec3_soa_t *b) {
+    for (size_t i = 0; i < a->count; i++)
+        out[i] = a->x[i]*b->x[i] + a->y[i]*b->y[i] + a->z[i]*b->z[i];
+}
+```
+
+**Techniques:**
+- Scalar single: Start with single-object reference implementation for debugging
+- AoS batch: Add batch processing for struct arrays (1.5x speedup)
+- SoA batch: Add cache-friendly variant for large workloads (2-3x speedup)
+- SIMD variants: Add vectorized implementations for critical paths (4-10x)
+- Parity testing: Test correctness across all variants with same test suite

package/skills/c99-opinionated-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

package/skills/c99-opinionated-guidelines/reference/memory-management.md

@@ -0,0 +1,35 @@
+# memory-management: Memory Management Patterns
+
+**Guideline:** Prefer stack allocation and ensure proper cleanup of heap allocations with clear ownership tracking.
+
+**Rationale:** Proper memory management prevents leaks, reduces fragmentation, and improves performance. Stack allocation is faster and automatically cleaned up.
+
+**Example:**
+
+```c
+// Stack allocation (preferred)
+void process_data(void) {
+    char buffer[1024];
+    int values[100];
+    // Automatically freed when function returns
+}
+
+// Heap allocation with explicit free
+void dynamic_array(size_t size) {
+    int *array = malloc(size * sizeof(int));
+    if (!array) {
+        return;  // Handle allocation failure
+    }
+
+    // Use array...
+
+    free(array);  // Always free
+}
+```
+
+**Techniques:**
+- Default stack: Use stack allocation for fixed-size data by default
+- Heap when needed: Use malloc/calloc only for dynamic or longer-lived data
+- Malloc/free pairing: Always pair every malloc with corresponding free call
+- Failure checking: Check allocation return value before dereferencing
+- Clear ownership: Document who owns and must free each allocation

package/skills/c99-opinionated-guidelines/reference/safety-validations.md

@@ -0,0 +1,32 @@
+# safety-validations: Safety Validations
+
+**Guideline:** Validate capacity, bounds, NULL pointers, division-by-zero, overflow before use.
+
+**Rationale:** Prevents undefined behavior, crashes, security vulnerabilities. Return status codes for graceful error handling.
+
+**Example:**
+
+```c
+status_t buffer_write(buffer_t *buf, const void *data, size_t size) {
+    if (buf->used + size > buf->capacity) return STATUS_FULL;
+    if (size > SIZE_MAX - buf->used) return STATUS_OVERFLOW;
+    memcpy(buf->data + buf->used, data, size);
+    buf->used += size;
+    return STATUS_OK;
+}
+
+vec3_t vec3_normalize(const vec3_t *v) {
+    if (!v) return (vec3_t){0};
+    float len = sqrtf(v->x*v->x + v->y*v->y + v->z*v->z);
+    if (len < 1e-6f) return (vec3_t){0};
+    float inv = 1.0f / len;
+    return (vec3_t){v->x*inv, v->y*inv, v->z*inv, 0};
+}
+```
+
+**Techniques:**
+- Capacity checks: Validate `used + size <= capacity` before writing
+- Bounds checks: Check `idx < count` before array access
+- NULL checks: Test `if (!ptr)` at function entry
+- Epsilon division: Use `len < 1e-6f` for zero checks in float operations
+- Overflow checks: Test `count > SIZE_MAX / size` before multiplication

package/skills/c99-opinionated-guidelines/reference/testing-patterns.md

@@ -0,0 +1,39 @@
+# testing-patterns: Testing Patterns
+
+**Guideline:** Typed assertions, epsilon for floats, parity tests for variants.
+
+**Rationale:** Catches type mismatches. Epsilon handles float imprecision. Parity ensures variants produce identical results.
+
+**Example:**
+
+```c
+void test_vec3_dot(void) {
+    vec3_t a = {1, 2, 3, 0}, b = {4, 5, 6, 0};
+    assert_float_eq(vec3_dot(&a, &b), 32.0f);  // 1*4+2*5+3*6
+}
+
+void test_vec3_dot_soa_parity(void) {
+    float ax[100], ay[100], az[100];
+    float bx[100], by[100], bz[100];
+    float scalar_out[100], soa_out[100];
+
+    for (size_t i = 0; i < 100; i++) {
+        vec3_t a = {ax[i], ay[i], az[i], 0};
+        vec3_t b = {bx[i], by[i], bz[i], 0};
+        scalar_out[i] = vec3_dot(&a, &b);
+    }
+
+    vec3_soa_t a_soa = {ax, ay, az, 100};
+    vec3_dot_soa(soa_out, &a_soa, &(vec3_soa_t){bx, by, bz, 100});
+
+    for (size_t i = 0; i < 100; i++)
+        assert_float_near(soa_out[i], scalar_out[i], 1e-5f);
+}
+```
+
+**Techniques:**
+- Typed assertions: Use `assert_int_eq`, `assert_float_eq`, `assert_ptr_not_null`
+- Epsilon values: Use 1e-4f general, 1e-5f cumulative, 5e-4f for SIMD
+- Scalar tests: Validate against known values for correctness
+- Parity tests: Compare variant implementations against scalar reference
+- Edge cases: Test zero, negative, denormal, infinity, and boundary conditions

package/skills/cmake-guidelines/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: cmake-guidelines
+description: >-
+  Trigger on `CMakeLists.txt` files. Use when writing CMake 3.20+ build systems for C/C++ projects. Apply for target-based builds, dependency management, testing setup, visibility specifiers. Keywords: CMake, add_library, add_executable, target_link_libraries, PUBLIC/PRIVATE/INTERFACE, find_package, FetchContent, CTest.
+---
+
+# CMake Coding Guidelines
+
+## Requirements
+
+- CMake ≥ 3.20; modern target-based usage.
+
+## Essentials
+
+- **Target-based builds** - Use targets, no global include/link dirs, see [reference/target-types.md](reference/target-types.md), [reference/compile-options.md](reference/compile-options.md)
+- **Visibility specifiers** - Use PUBLIC/PRIVATE/INTERFACE correctly, see [reference/visibility-specifiers.md](reference/visibility-specifiers.md)
+- **Dependencies** - Declare explicitly with FetchContent/find_package, see [reference/find-package.md](reference/find-package.md), [reference/fetchcontent.md](reference/fetchcontent.md)
+- **Testing** - Enable testing with CTest, see [reference/testing.md](reference/testing.md)
+- **Project structure** - Organize multi-directory projects, see [reference/project-structure.md](reference/project-structure.md)
+
+## Progressive disclosure
+
+- Read [reference/target-types.md](reference/target-types.md) - When choosing between library types or executables
+- Read [reference/visibility-specifiers.md](reference/visibility-specifiers.md) - When deciding PUBLIC vs PRIVATE vs INTERFACE
+- Read [reference/compile-options.md](reference/compile-options.md) - When adding compiler flags to targets
+- Read [reference/find-package.md](reference/find-package.md) - When integrating external dependencies
+- Read [reference/fetchcontent.md](reference/fetchcontent.md) - When vendoring dependencies from git/archives
+- Read [reference/testing.md](reference/testing.md) - When setting up CTest or test targets
+- Read [reference/project-structure.md](reference/project-structure.md) - When organizing multi-directory CMake projects
+- Read [reference/generator-expressions.md](reference/generator-expressions.md) - When using conditional build configuration
+- Read [reference/installation.md](reference/installation.md) - When creating install targets or package exports

package/skills/cmake-guidelines/reference/compile-options.md

@@ -0,0 +1,34 @@
+# compile-options: Compile Options and Definitions
+
+**Guideline:** Set compiler flags, definitions, and features on targets using target_compile_* commands with appropriate visibility.
+
+**Rationale:** Target-scoped settings prevent pollution of the global build environment and allow different targets to have different requirements.
+
+**Example:**
+
+```cmake
+# Set compile options
+target_compile_options(mylib
+    PRIVATE
+        $<$<CXX_COMPILER_ID:GNU,Clang>:-Wall -Wextra -pedantic>
+        $<$<CXX_COMPILER_ID:MSVC>:/W4>
+)
+
+# Set compile definitions
+target_compile_definitions(mylib
+    PUBLIC API_VERSION=2
+    PRIVATE
+        $<$<CONFIG:Debug>:DEBUG_BUILD>
+        $<$<CONFIG:Release>:RELEASE_BUILD>
+)
+
+# Set compile features
+target_compile_features(mylib PUBLIC cxx_std_20)
+```
+
+**Techniques:**
+- target_compile_options(): Set compiler-specific flags with generator expressions
+- target_compile_definitions(): Define preprocessor macros with visibility control
+- target_compile_features(): Require C++ standard using cxx_std_20, cxx_std_17, etc
+- Compiler detection: Use $<$<CXX_COMPILER_ID:GNU,Clang>:flags> for portability
+- Configuration-based: Apply $<$<CONFIG:Debug>:DEBUG> for build-type-specific settings