菜单
OEM hardware first-boot setup hooks in projectbluefin/common. Use when adding hardware-specific setup, understanding hook directories and versioning contract, or applying shellcheck requirements.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/projectbluefin/common --skill oem-hardware-hooks命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
基于 SOC 职业分类
| name | oem-hardware-hooks |
| version | 1.1 |
| last_updated | 2026-08-08 |
| id | oem-hardware-hooks |
| one_line_purpose | Add OEM hardware first-boot setup hooks safely. |
| entry_point | docs/skills/oem-hardware-hooks/SKILL.md |
| category | test-authoring |
| mcp_compliance_level | partial |
| optimization_status | draft |
| status | active |
| dependencies | [] |
| tags | ["hardware","oem","first-boot","hooks","shellcheck"] |
| description | OEM hardware first-boot setup hooks in projectbluefin/common. Use when adding hardware-specific setup, understanding hook directories and versioning contract, or applying shellcheck requirements. |
| metadata | {"type":"reference"} |
How to add, move, or maintain hardware-specific first-boot setup hooks
in projectbluefin/common. Covers the hook directories, the versioning
contract, shellcheck requirements, and what belongs here vs upstream.
projectbluefin/common20-oem-brew.sh hookbrew install --cask without trust (use Brewfile)Two directories are scanned automatically at first boot — no registration needed:
system_files/bluefin/usr/share/glib-2.0/schemas/zz0-bluefin-modifications.gschema.overridesystem_files/bluefin/etc/dconf/db/distro.d/locks/01-bluefin-locked-settingssystem_files/shared/usr/share/ublue-os/user-setup.hooks.d/ with version-script contract| Directory | Runner | Runs as |
|---|---|---|
system_files/shared/usr/share/ublue-os/system-setup.hooks.d/ | ublue-system-setup (systemd system service) | root |
system_files/shared/usr/share/ublue-os/user-setup.hooks.d/ | ublue-user-setup (systemd user service) | current user |
Name scripts with a numeric prefix (10-, 20-) to control execution order.
Every hook must begin with:
# shellcheck disable=SC1091
source /usr/lib/ublue/setup-services/libsetup.sh
version-script <name> <type> <version> || exit 0
<name> — a stable slug (e.g. framework, theming)<type> — system, user, or privileged — must match the runner<version> — integer; bump when you want the hook to re-run on existing systemsCritical when migrating: use the same version number as the downstream hook. Bumping it re-runs the hook on every existing system on next boot.
version-script must fire AFTER all preconditions pass — the stamp is written before your hook logic runs. See references/hook-patterns.md for the canonical safe pattern and anti-pattern.
CI runs shellcheck -e SC2207 on all *.sh files in system_files/.
Always suppress SC1091 inline:
# shellcheck disable=SC1091
source /usr/lib/ublue/setup-services/libsetup.sh
Move to common when the hook:
Leave in the downstream repo when the hook:
brew install --cask (depends on tap trust being configured first)| Hook | Type | What it does |
|---|---|---|
system-setup.hooks.d/10-framework.sh | system | Intel Framework keyboard karg; Framework 13 Ryzen 7040 suspend fix; AMD 3.5mm jack (kernel-aware) |
system-setup.hooks.d/11-asus.sh | system | Enables asusd.service + asus-shutdown.service once asusctl is installed |
user-setup.hooks.d/10-theming.sh | user | Framework scroll/font tweaks; Thelio Astra Ampere logo (non-brew vendors) |
user-setup.hooks.d/20-oem-brew.sh | user | Generic OEM brew install + logo set (data-driven) |
user-setup.hooks.d/12-framework-color.sh | user | Assigns factory ICC color profiles to Framework 13/16 displays via colormgr |
version-script before checking transient preconditions (permanently burns the stamp)system_files/shared/usr/share/wireplumber/wireplumber.conf.d/ (ships globally)hardware-profiles/ loader from bazzite works in stock bluefin WirePlumberBefore closing any OEM hook PR:
shellcheck -e SC2207 passes on all modified *.sh filesversion-script called after all transient preconditions are checkedbluefin-lts path structure confirmed (system_files/usr/share/... — no shared/ prefix)just check and pre-commit run --all-files pass clean| Reference | Description |
|---|---|
references/hook-patterns.md | version-script safe/anti-patterns; migrating a hook from bluefin to common; kernel-aware modprobe fixes; colormgr subcommands |
references/oem-brew.md | OEM brew hook data-driven pattern; adding a new OEM vendor; OEM directories table; WirePlumber rules; known gaps |