personal-os-setup: Skill for Claude Code

Known drift between docs and reality in personal-os-setup

Cross-check these before assuming documentation is current — several claims in CONTRIBUTING.md/Makefile don't match the code as of this writing.

Makefile

• make help's "Development:" section is broken: it greps makefiles/dev.mk, which doesn't exist — the real file is makefiles/check_format.mk. Running make help prints a grep: ... No such file or directory and shows an empty Development section, even though make lint/make format/make pre-commit/make pre-commit-install all work fine when invoked directly.
• make test-installation (uv run --directory . hello) looks stale/broken — no hello console-script is registered in pyproject.toml's [project.scripts] (only personal-os-setup is). Don't rely on it.
• make install installs zero dev/docs dependencies — pyproject.toml sets default-groups = [], so plain uv sync (what make install runs) gets you only runtime deps. Use make install-dev (uv sync --all-groups) to get pytest/ruff/pre-commit/mkdocs tooling.
• common.mk's $(UV) variable falls back to ~/.local/bin/uv if uv isn't on PATH — if it's installed somewhere else, every target fails with a plain "command not found" rather than a clear error.

.pre-commit-config.yaml vs CONTRIBUTING.md § 3.1 "Security"

CONTRIBUTING.md claims actionlint, zizmor, and pip-audit are active local pre-commit security hooks. They're commented out in .pre-commit-config.yaml — not actually running. bandit and markdown-link-check are also present-but-commented-out. Nothing currently lints/security-scans the GitHub Actions workflow YAML itself — hand-review workflow diffs carefully, especially for script-injection via untrusted ${{ }} interpolation, since no tool catches it here.

• commitizen's hook only fires at git's commit-msg stage — pre-commit run --all-files (what make pre-commit runs) does not exercise it. A clean make pre-commit says nothing about whether your commit message is well-formed. See [[ship-feature]].
• detect-secrets runs stateless (no --baseline file configured) — false positives on new files must be suppressed with an inline # pragma: allowlist secret comment, not by adding the whole file to --exclude-files in .pre-commit-config.yaml (explicit repo convention).
• end-of-file-fixer/trailing-whitespace/ruff --fix/ruff-format all auto-rewrite files in place and fail the first run — re-git add and commit again, nothing is actually wrong.