involvexinvolvex/youtube-music-cli/.agents/skills/bun-win32/SKILL.md

bun-win32

Skill461 starsChanged 3 months agoMITView on GitHub

Win32 FFI binding lifecycle for @bun-win32/* packages (Win32 DLL bindings via bun:ffi on Windows). Use when generating a new package from a DLL, auditing FFI↔TS↔header consistency, fixing nullability (| NULL / | 0n), or understanding the bootstrap→catalog→stub→audit→nullcheck pipeline. Covers 117 packages; strict TypeScript; Bun runtime; Biome formatting.

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
WORKING_DIR is the repo root: All commands run from there.
line 32
Very specific:
Use as any / forced casts — fix the FFI mapping instead
line 105

≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

bun-win32 Skill

Win32 FFI binding development lifecycle for the bun-win32 monorepo.

Repository Context

WORKING_DIR (repo root = ../.. from this skill directory)
  packages/       117 @bun-win32/* binding packages
  scripts/        repo automation scripts
  PROMPT.md       authoritative playbook (FFI rules, nullability, audits)
  AGENTS.md       operating rules — read before touching bindings

This skill dir: skill/bun-win32/
  SKILL.md        ← you are here
  scripts/        automation scripts (run from WORKING_DIR)
  references/     AGENTS.md, ai-core.md, ai-all.md

WORKING_DIR is the repo root. All commands run from there. Scripts in scripts/ use ROOT = join(import.meta.dir, '../..') so they resolve correctly when executed from this skill directory.

Lifecycle Commands (run from WORKING_DIR)

# 1. Check prerequisites (platform Windows, Bun ≥1.3.0, ripgrep, SDK, dumpbin)
bun run skill/bun-win32/scripts/doctor.ts

# 2. Full pipeline: doctor → scaffold → install → catalog → ffi-runtime → stub
bun run skill/bun-win32/scripts/bootstrap.ts {name} [--class=ClassName] [--rg=<path>] [--dll=<path>]

# 3. Individual steps
bun run skill/bun-win32/scripts/catalog.ts {name} --json        # DLL∩SDK symbols
bun run skill/bun-win32/scripts/ffi-runtime.ts {name}            # FFI return shapes
bun run skill/bun-win32/scripts/stub.ts {name} [--class=C]      # paste-ready stubs

# 4. Auditing (run after writing bindings)
bun run skill/bun-win32/scripts/audit.ts {name}        # FFI↔TS↔header consistency (--all, --fix)
bun run skill/bun-win32/scripts/nullcheck.ts {name}    # SAL nullability (--all, --fix, --strict)
bunx tsc --noEmit                                      # type-check the package

Release

rm bun.lock && bun install
bun run skill/bun-win32/scripts/preflight.ts
bun run skill/bun-win32/scripts/nullcheck.ts --all && bun run skill/bun-win32/scripts/audit.ts --all
cd packages/{name} && bun publish --access public --otp <code>

Scripts Reference

Script	What it does
`scripts/doctor.ts`	Prerequisites checker
`scripts/bootstrap.ts`	Orchestrated full pipeline
`scripts/catalog.ts`	dumpbin exports ∩ SDK headers → JSON
`scripts/scaffold.ts`	Template → package skeleton
`scripts/ffi-runtime.ts`	Probe FFI return-value shapes
`scripts/stub.ts`	catalog JSON → Symbols + method stubs
`scripts/audit.ts`	FFI↔TS↔header consistency auditor
`scripts/nullcheck.ts`	SAL-driven nullability auditor
`scripts/preflight.ts`	Lockfile staleness gate

FFI Type Quick Reference

Win32 type	FFI	TS
`HANDLE`, `HWND`, `HKEY`, `HMODULE`…	`FFIType.u64`	`bigint`
`SIZE_T`, `*_PTR`, `LPARAM`, `LRESULT`, `WPARAM`	`FFIType.u64`	`bigint`
`LARGE_INTEGER`, `ULARGE_INTEGER`	`FFIType.i64` / `u64`	`bigint`
`DWORD`, `UINT`, `BOOL`, `HRESULT`, `INT`, `LONG`, `WORD`, `BYTE`	`FFIType.u32` / `i32`	`number`
`LPVOID`, `LPCWSTR`, `LPSTR`, `LPDWORD`, `LPBYTE`…	`FFIType.ptr`	`Pointer`
`void`	`FFIType.void`	`void`

Decision rule: Does the caller pass .ptr from a Buffer/TypedArray they allocated? Yes → ptr. No → u64.

NULL: u64 → 0n, ptr → null, u32 → 0.

Key Files

references/agents.md — full AGENTS.md (binding rules, toolchain, FFI rules, prohibitions)
references/ai-core.md — @bun-win32/core contract (Win32 base class, .ptr extension, types)
references/ai-all.md — @bun-win32/all contract (re-export aggregator, when to use)
PROMPT.md at WORKING_DIR — deep playbook for FFI mapping, nullability, audits

Prohibited

Bind exports not confirmed by dumpbin //EXPORTS
Guess types/nullability — always verify vs SDK header + MS Learn
Use as any / forced casts — fix the FFI mapping instead
Reformat untouched files
Ship without running audit.ts --all and nullcheck.ts --all (zero findings required)

Download now (ZIP)

In this repository45 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .agents/skills/react-best-practices/AGENTS.mdAGENTS.md
- .claude/skills/react-best-practices/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- .cursor/rules/ymc-agents.mdcCursor rule
- brainstormingSkill
- bun-buildSkill
- bun-developmentSkill
- bun-dev-serverSkill
- bun-initSkill
- bun-testSkill
- Cli-ExpertSkill
- cli-masterySkill
- create-implementation-planSkill
- planning-with-filesSkill
- powershell-windowsSkill
- react-best-practicesSkill
- react:componentsSkill
- react-patternsSkill
- react-state-managementSkill
- systematic-debuggingSkill
- writing-plansSkill
- ymc-downloadsSkill
- ymc-playbackSkill
- brainstormingSkill
- bun-buildSkill
- bun-developmentSkill
- bun-dev-serverSkill
- bun-initSkill
- bun-testSkill
- bun-win32Skill
- Cli-ExpertSkill
- cli-masterySkill
- create-implementation-planSkill
- planning-with-filesSkill
- powershell-windowsSkill
- react-best-practicesSkill
- react:componentsSkill
- react-patternsSkill
- react-state-managementSkill
- systematic-debuggingSkill
- writing-plansSkill
- ymc-downloadsSkill
- ymc-playbackSkill

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free