[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7AWCBHTZHMGWER9NTBHNNMY":3,"skill-same:01M7AWCBHTZHMGWER9NTBHNNMY":67},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":23,"commitSha":24,"skillDirectory":25,"forksCount":26,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":29,"ownerDescription":6,"updatedAt":30,"install":31,"resources":44},"01M7AWCBHTZHMGWER9NTBHNNMY","nim-c-wrappers",null,"Turn low-level C FFI bindings into an idiomatic Nim API, with safer types, cleaner module boundaries, resource management, callbacks, enums, bitflags, and exception-based error handling. Use when building a high-level Nim wrapper around a C library or improving the usability of existing raw bindings.","Vyrnexis\u002Fnim-agent-template","Vyrnexis","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F315210836?v=4","01M7AWARQX2P2CQ25GD7S71DHH","01M7AWARRJ3WF9DRPNJ6S1W9CG",5,"MIT","https:\u002F\u002Fgithub.com\u002FVyrnexis\u002Fnim-agent-template\u002Fblob\u002Fmain\u002Fskills\u002Fnim-c-wrappers\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: nim-c-wrappers\ndescription: Turn low-level C FFI bindings into an idiomatic Nim API, with safer types, cleaner module boundaries, resource management, callbacks, enums, bitflags, and exception-based error handling. Use when building a high-level Nim wrapper around a C library or improving the usability of existing raw bindings.\n---\n\n# Nim C Wrappers\n\n## Rules\n\n### Architecture\n\n- Use a **two-layer design**: raw FFI layer (ABI-faithful) + ergonomic Nim layer (safe, idiomatic). Keep the raw layer thin and stable.\n- Split modules by library domain. Mirror the C header structure for large libraries.\n- Centralize shared types in a `lib_raw_types` module to avoid cyclic imports.\n- Export raw symbols only for advanced users; re-export selected symbols from ergonomic modules.\n\n### Raw FFI Layer\n\n- Use `importc` with `cdecl` (or `stdcall` if the library requires it). Prefer `{.push callconv: cdecl, importc.}` blocks for shared conventions.\n- `header` declares linker-resolved imports; `dynlib` loads symbols at runtime. Do not combine them on one proc. Guard library names with `when defined(windows):` etc.\n- **Never reorder struct fields.** Use `object` in C field order. Add `packed` only if C headers specify packing.\n- Use `incompleteStruct` and list only needed fields to reduce ABI risk.\n- For C enums, use `distinct` integer types + `const` values. Do not use Nim `enum` in raw bindings. Find actual enum values in C headers—do not guess.\n- For bitflags, use `distinct` integer types with bitwise helpers. Do not use `set[Enum]`.\n- Map C macros: numeric → `const`; function-like → `template`; use `inline proc` when arguments should evaluate once.\n- Keep pointer types as C intends — do not convert them in the raw layer.\n\n### Type Mapping\n\n| C Type | Nim Type | Notes |\n|--------|----------|-------|\n| `char` | `cchar` | Platform-dependent signedness |\n| `signed char` | `cschar` | Always `int8` |\n| `unsigned char` | `uint8` | Safer default spelling; avoid relying on `cuchar` status across Nim versions |\n| `short` | `cshort` | Always `int16` |\n| `unsigned short` | `cushort` | Always `uint16` |\n| `int` | `cint` | Always `int32` |\n| `unsigned int` | `cuint` | Always `uint32` |\n| `long` | `clong` | ABI-sized (4 on Win64, 8 on LP64) |\n| `unsigned long` | `culong` | ABI-sized |\n| `long long` | `clonglong` | Always `int64` |\n| `unsigned long long` | `culonglong` | Always `uint64` |\n| `size_t` | `csize_t` | Alias for `uint` |\n| `intptr_t` | `int` | Pointer-sized signed |\n| `uintptr_t` | `uint` | Pointer-sized unsigned |\n| `float` | `cfloat` | Always `float32` |\n| `double` | `cdouble` | Always `float64` |\n| `long double` | `clongdouble` | Limited codegen support |\n| `void*` | `pointer` | Untyped |\n| `T*` | `ptr T` | Nullable |\n| `T**` | `ptr ptr T` | |\n| `char*` \u002F `const char*` | `cstring` | NUL-terminated |\n| `char**` | `cstringArray` | `ptr UncheckedArray[cstring]` |\n\nStruct types: `object` in C order. Fixed arrays: `array[N, T]`. Pointer+length: `ptr T` + `csize_t`. Raw buffers: `ptr UncheckedArray[T]`. Opaque handles: `pointer` or `ptr OpaqueObj` (empty object).\n\n### Ergonomic Layer\n\n- In `=destroy`, explicitly call `=destroy` on owned nested GC-managed fields (string, seq) after releasing C resources.\n- Define ownership hooks in the **same module** as the type. Cross-module hook definitions are a compile error.\n- Raise exceptions (IOError, ValueError, etc.) for C errors — do not return result wrappers that only carry ok\u002Fkind\u002Fmessage.\n- Do not create custom exception types unless callers handle them differently.\n- Catch errors only at translation boundaries (C return code → Nim exception, or exception → domain result). Let exceptions propagate otherwise.\n\n### Naming\n\n- In raw bindings, match C identifier names directly.\n- `importc` without an explicit string resolves the C symbol from the Nim name.\n- Strip redundant C prefixes (LIB_, foo_) in the ergonomic layer.\n- Keep raw constant names in C style (e.g., `CURLE_OK`).\n- When a C identifier collides with a Nim keyword, rename the Nim identifier and use `importc:` to map to the original C name.\n\n### Callbacks\n\n- Declare callbacks as plain C-callable procs such as `proc onEvent(code: cint; userData: pointer) {.cdecl.}`.\n- Pass closure state through `userdata` via `rawProc`\u002F`rawEnv`. See `references\u002Fcallback_pattern.md`.\n\n### Verification\n\n- Add `static: doAssert sizeof(T) == N` and `offsetOf` checks in tests to verify struct layouts.\n- Test ABI with compile + link + smoke test + runtime checks.\n\n## Workflow\n\n1. **Read the C API.** Identify structs, enums, functions, callbacks, and ownership semantics.\n2. **Map types.** Use the type table. Verify sizes with `static: doAssert sizeof`.\n3. **Write raw bindings.** One module per C header or subsystem. Centralize shared raw types to avoid cycles. Use `importc`, correct calling convention, `packed` only when C specifies it. Use typed integer aliases for enums.\n4. **Write ergonomic wrappers.** Add destructors for owned resources (move-only or RC). Raise exceptions for C errors. Re-export only the intended public surface. Strip prefixes.\n5. **Test.** Compile check → link check → smoke test → ABI sizeof\u002Foffset asserts → runtime ownership tests.\n6. **Iterate.** Add missing APIs as needed. Keep raw layer stable.\n\n## Common Mistakes\n\n| Mistake | Why it's wrong |\n|---------|----------------|\n| Passing Nim `string` directly to `char*` parameter | Type mismatch; use `.cstring` |\n| Using `seq` where C expects stable pointer | `add()` can reallocate, invalidating the pointer |\n| Reordering struct fields | Breaks ABI layout, causes garbage values |\n| Using Nim `enum` for C enum values | ABI incompatibility; use typed integer aliases |\n| Adding enum or constant values without inspecting headers | Find actual enum values in C headers, do not guess |\n| Passing closures as C callbacks | C expects plain function pointers, not GC closures |\n| Storing `cstring` beyond the call | `cstring` from `string.cstring` dangles after the source is freed |\n| `=dup` body using `result = src` in RC pattern | May trigger implicit `=copy` instead of `=dup`; use field-by-field assignment |\n| Wrong calling convention | Causes crashes at call sites |\n\n## References\n\n- `references\u002Fmove_only_resource.md` — A move-only wrapper for one owner of a C handle.\n- `references\u002Frc_resource.md` — A reference-counted wrapper for shared C resource ownership.\n- `references\u002Fcallback_pattern.md` — C callbacks with userdata, captured Nim state, and lifetime\n  management.\n- `references\u002Fenum_and_bitflags.md` — Distinct-integer wrappers for non-contiguous enums and\n  bitwise flags.\n- `references\u002Fmodule_layout.md` — Separating raw FFI from an ergonomic API in two modules.\n","# Nim C Wrappers\n\n## Rules\n\n### Architecture\n\n- Use a **two-layer design**: raw FFI layer (ABI-faithful) + ergonomic Nim layer (safe, idiomatic). Keep the raw layer thin and stable.\n- Split modules by library domain. Mirror the C header structure for large libraries.\n- Centralize shared types in a `lib_raw_types` module to avoid cyclic imports.\n- Export raw symbols only for advanced users; re-export selected symbols from ergonomic modules.\n\n### Raw FFI Layer\n\n- Use `importc` with `cdecl` (or `stdcall` if the library requires it). Prefer `{.push callconv: cdecl, importc.}` blocks for shared conventions.\n- `header` declares linker-resolved imports; `dynlib` loads symbols at runtime. Do not combine them on one proc. Guard library names with `when defined(windows):` etc.\n- **Never reorder struct fields.** Use `object` in C field order. Add `packed` only if C headers specify packing.\n- Use `incompleteStruct` and list only needed fields to reduce ABI risk.\n- For C enums, use `distinct` integer types + `const` values. Do not use Nim `enum` in raw bindings. Find actual enum values in C headers—do not guess.\n- For bitflags, use `distinct` integer types with bitwise helpers. Do not use `set[Enum]`.\n- Map C macros: numeric → `const`; function-like → `template`; use `inline proc` when arguments should evaluate once.\n- Keep pointer types as C intends — do not convert them in the raw layer.\n\n### Type Mapping\n\n| C Type | Nim Type | Notes |\n|--------|----------|-------|\n| `char` | `cchar` | Platform-dependent signedness |\n| `signed char` | `cschar` | Always `int8` |\n| `unsigned char` | `uint8` | Safer default spelling; avoid relying on `cuchar` status across Nim versions |\n| `short` | `cshort` | Always `int16` |\n| `unsigned short` | `cushort` | Always `uint16` |\n| `int` | `cint` | Always `int32` |\n| `unsigned int` | `cuint` | Always `uint32` |\n| `long` | `clong` | ABI-sized (4 on Win64, 8 on LP64) |\n| `unsigned long` | `culong` | ABI-sized |\n| `long long` | `clonglong` | Always `int64` |\n| `unsigned long long` | `culonglong` | Always `uint64` |\n| `size_t` | `csize_t` | Alias for `uint` |\n| `intptr_t` | `int` | Pointer-sized signed |\n| `uintptr_t` | `uint` | Pointer-sized unsigned |\n| `float` | `cfloat` | Always `float32` |\n| `double` | `cdouble` | Always `float64` |\n| `long double` | `clongdouble` | Limited codegen support |\n| `void*` | `pointer` | Untyped |\n| `T*` | `ptr T` | Nullable |\n| `T**` | `ptr ptr T` | |\n| `char*` \u002F `const char*` | `cstring` | NUL-terminated |\n| `char**` | `cstringArray` | `ptr UncheckedArray[cstring]` |\n\nStruct types: `object` in C order. Fixed arrays: `array[N, T]`. Pointer+length: `ptr T` + `csize_t`. Raw buffers: `ptr UncheckedArray[T]`. Opaque handles: `pointer` or `ptr OpaqueObj` (empty object).\n\n### Ergonomic Layer\n\n- In `=destroy`, explicitly call `=destroy` on owned nested GC-managed fields (string, seq) after releasing C resources.\n- Define ownership hooks in the **same module** as the type. Cross-module hook definitions are a compile error.\n- Raise exceptions (IOError, ValueError, etc.) for C errors — do not return result wrappers that only carry ok\u002Fkind\u002Fmessage.\n- Do not create custom exception types unless callers handle them differently.\n- Catch errors only at translation boundaries (C return code → Nim exception, or exception → domain result). Let exceptions propagate otherwise.\n\n### Naming\n\n- In raw bindings, match C identifier names directly.\n- `importc` without an explicit string resolves the C symbol from the Nim name.\n- Strip redundant C prefixes (LIB_, foo_) in the ergonomic layer.\n- Keep raw constant names in C style (e.g., `CURLE_OK`).\n- When a C identifier collides with a Nim keyword, rename the Nim identifier and use `importc:` to map to the original C name.\n\n### Callbacks\n\n- Declare callbacks as plain C-callable procs such as `proc onEvent(code: cint; userData: pointer) {.cdecl.}`.\n- Pass closure state through `userdata` via `rawProc`\u002F`rawEnv`. See `references\u002Fcallback_pattern.md`.\n\n### Verification\n\n- Add `static: doAssert sizeof(T) == N` and `offsetOf` checks in tests to verify struct layouts.\n- Test ABI with compile + link + smoke test + runtime checks.\n\n## Workflow\n\n1. **Read the C API.** Identify structs, enums, functions, callbacks, and ownership semantics.\n2. **Map types.** Use the type table. Verify sizes with `static: doAssert sizeof`.\n3. **Write raw bindings.** One module per C header or subsystem. Centralize shared raw types to avoid cycles. Use `importc`, correct calling convention, `packed` only when C specifies it. Use typed integer aliases for enums.\n4. **Write ergonomic wrappers.** Add destructors for owned resources (move-only or RC). Raise exceptions for C errors. Re-export only the intended public surface. Strip prefixes.\n5. **Test.** Compile check → link check → smoke test → ABI sizeof\u002Foffset asserts → runtime ownership tests.\n6. **Iterate.** Add missing APIs as needed. Keep raw layer stable.\n\n## Common Mistakes\n\n| Mistake | Why it's wrong |\n|---------|----------------|\n| Passing Nim `string` directly to `char*` parameter | Type mismatch; use `.cstring` |\n| Using `seq` where C expects stable pointer | `add()` can reallocate, invalidating the pointer |\n| Reordering struct fields | Breaks ABI layout, causes garbage values |\n| Using Nim `enum` for C enum values | ABI incompatibility; use typed integer aliases |\n| Adding enum or constant values without inspecting headers | Find actual enum values in C headers, do not guess |\n| Passing closures as C callbacks | C expects plain function pointers, not GC closures |\n| Storing `cstring` beyond the call | `cstring` from `string.cstring` dangles after the source is freed |\n| `=dup` body using `result = src` in RC pattern | May trigger implicit `=copy` instead of `=dup`; use field-by-field assignment |\n| Wrong calling convention | Causes crashes at call sites |\n\n## References\n\n- `references\u002Fmove_only_resource.md` — A move-only wrapper for one owner of a C handle.\n- `references\u002Frc_resource.md` — A reference-counted wrapper for shared C resource ownership.\n- `references\u002Fcallback_pattern.md` — C callbacks with userdata, captured Nim state, and lifetime\n  management.\n- `references\u002Fenum_and_bitflags.md` — Distinct-integer wrappers for non-contiguous enums and\n  bitwise flags.\n- `references\u002Fmodule_layout.md` — Separating raw FFI from an ergonomic API in two modules.\n",{"name":5,"description":7},"main","060e1c453fdad0410a2b385f59275494911d9a4b","skills\u002Fnim-c-wrappers",2,"https:\u002F\u002Fgithub.com\u002FVyrnexis\u002Fnim-agent-template","https:\u002F\u002Fgithub.com\u002FVyrnexis","https:\u002F\u002Fvyrnexis.github.io","2026-10-27 00:06:43",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add Vyrnexis\u002Fnim-agent-template --skill nim-c-wrappers",{"tool":37,"command":38},"bunx","bunx skills add Vyrnexis\u002Fnim-agent-template --skill nim-c-wrappers",{"tool":40,"command":41},"pnpm","pnpm dlx skills add Vyrnexis\u002Fnim-agent-template --skill nim-c-wrappers","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FVyrnexis\u002Fnim-agent-template\u002Fblob\u002Fmain\u002Fskills\u002Fnim-c-wrappers\u002FSKILL.md",true,[45,51,55,59,63],{"path":46,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":49,"sourceHtmlUrl":50},"references\u002Fcallback_pattern.md","REFERENCE","参考文档",2270,"https:\u002F\u002Fgithub.com\u002FVyrnexis\u002Fnim-agent-template\u002Fblob\u002Fmain\u002Fskills\u002Fnim-c-wrappers\u002Freferences\u002Fcallback_pattern.md",{"path":52,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":53,"sourceHtmlUrl":54},"references\u002Fenum_and_bitflags.md",1453,"https:\u002F\u002Fgithub.com\u002FVyrnexis\u002Fnim-agent-template\u002Fblob\u002Fmain\u002Fskills\u002Fnim-c-wrappers\u002Freferences\u002Fenum_and_bitflags.md",{"path":56,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":57,"sourceHtmlUrl":58},"references\u002Fmodule_layout.md",2369,"https:\u002F\u002Fgithub.com\u002FVyrnexis\u002Fnim-agent-template\u002Fblob\u002Fmain\u002Fskills\u002Fnim-c-wrappers\u002Freferences\u002Fmodule_layout.md",{"path":60,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":61,"sourceHtmlUrl":62},"references\u002Fmove_only_resource.md",1272,"https:\u002F\u002Fgithub.com\u002FVyrnexis\u002Fnim-agent-template\u002Fblob\u002Fmain\u002Fskills\u002Fnim-c-wrappers\u002Freferences\u002Fmove_only_resource.md",{"path":64,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":65,"sourceHtmlUrl":66},"references\u002Frc_resource.md",1774,"https:\u002F\u002Fgithub.com\u002FVyrnexis\u002Fnim-agent-template\u002Fblob\u002Fmain\u002Fskills\u002Fnim-c-wrappers\u002Freferences\u002Frc_resource.md",[68,75,82,89,96,103],{"skillNo":69,"name":70,"nameZh":6,"description":71,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":72,"categories":73,"keywords":74,"publishedAt":18},"01M7AWEDMYZVEFGPQYGCVC4NQN","run-tests","Runs the project unit tests and validation suites.","https:\u002F\u002Fgithub.com\u002FVyrnexis\u002Fnim-agent-template\u002Fblob\u002Fmain\u002Fskills\u002Frun-tests\u002FSKILL.md",[],[],{"skillNo":76,"name":77,"nameZh":6,"description":78,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":18},"01M7AWE9HNJ36TDH5NPDVCEAHC","nimonyplugins","Build and debug Nimony compile-time plugins for code generation and DSL rewrites. Use when replacing Nim macros with Nimony plugins, writing or reviewing template, for-loop, module, type, or import plugins, or diagnosing NIF traversal and generated output.","https:\u002F\u002Fgithub.com\u002FVyrnexis\u002Fnim-agent-template\u002Fblob\u002Fmain\u002Fskills\u002Fnimonyplugins\u002FSKILL.md",[],[],{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":18},"01M7AWE4F7EJ1H837ETBHESE2T","nim-testing","Write and run deterministic Nim tests, including isolated test files, expected-exception checks, multi-configuration builds, and sanitizer integration. Use when setting up a Nim test suite, testing failure behavior, running tests across debug\u002Frelease\u002Fdanger modes, or adding AddressSanitizer support.","https:\u002F\u002Fgithub.com\u002FVyrnexis\u002Fnim-agent-template\u002Fblob\u002Fmain\u002Fskills\u002Fnim-testing\u002FSKILL.md",[],[],{"skillNo":90,"name":91,"nameZh":6,"description":92,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":93,"categories":94,"keywords":95,"publishedAt":18},"01M7AWE0S8C3Y39VGR54R23FZD","nim-style-guide","Write clear, consistent Nim code in a simple stdlib-aligned style, covering imports, naming, proc vs func vs template choices, local variables, constructors, formatting, and control flow. Use when writing new Nim code or reviewing a Nim module for readability, consistency, and low-noise style decisions.","https:\u002F\u002Fgithub.com\u002FVyrnexis\u002Fnim-agent-template\u002Fblob\u002Fmain\u002Fskills\u002Fnim-style-guide\u002FSKILL.md",[],[],{"skillNo":97,"name":98,"nameZh":6,"description":99,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":100,"categories":101,"keywords":102,"publishedAt":18},"01M7AWDWZAD6RQ547RT96RHA5B","nim-ownership-hooks","Implement and review Nim ARC\u002FORC ownership hooks for types that manually manage resources, including move-only, deep-copy, refcounted, and copy-on-write patterns. Use when a Nim type owns pointers, buffers, file descriptors, or custom heap memory and you need correct `=destroy`, `=copy`, `=dup`, `=sink`, or move semantics.","https:\u002F\u002Fgithub.com\u002FVyrnexis\u002Fnim-agent-template\u002Fblob\u002Fmain\u002Fskills\u002Fnim-ownership-hooks\u002FSKILL.md",[],[],{"skillNo":104,"name":105,"nameZh":6,"description":106,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":107,"categories":108,"keywords":109,"publishedAt":18},"01M7AWDQ5JGN9XNNJ9FKJQ14GP","nim-mcp-tools","Use for Nim symbol navigation, diagnostics, and type resolution. MANDATORY: Use specialized MCP tools (nimFindSymbols, nimFindReferences, nimListSymbols, nimCheckFile, nimCheckProject, nimFindTypeDefinition) first; fall back to grep only on error or user confirmation.","https:\u002F\u002Fgithub.com\u002FVyrnexis\u002Fnim-agent-template\u002Fblob\u002Fmain\u002Fskills\u002Fnim-mcp-tools\u002FSKILL.md",[],[]]