flake-brief

Analyzes uncommitted flake.lock bumps and emits a transition and breakage brief.

1|Updated Aug 21, 2023
One-click install
npx skills add https://github.com/jmuchovej/homelab --skill flake-brief-jmuchovej
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: flake-brief
Source: https://github.com/jmuchovej/homelab/tree/main/.agents/skills/flake-brief
Command: npx skills add https://github.com/jmuchovej/homelab --skill flake-brief-jmuchovej

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Bumping Nix flake inputs can silently break a configuration when upstream renames options, deprecates APIs, or changes behavior. This Skill inspects an uncommitted flake.lock bump before you switch, so you know exactly what changed and whether your repo is affected. ## Core Features & Use Cases - Lock diffing: Compares old and new flake.lock revisions for watched structural inputs like den, flake-parts, home-manager, nix-darwin, sops-nix, and nixpkgs. - Upstream analysis: Prefetches both revisions into the Nix store, diffs the source trees, and reads upstream commit messages via the GitHub API for breaking-change markers. - Repo intersection: Searches src/modules for call sites of changed symbols, so only changes that actually affect your code are reported with file:line citations. - Use Case: After running just update, invoke the skill headlessly to get a verdict (safe / needs attention / blocking) plus likely breakages, obsoleted workarounds, and doc actions before switching generations. ## Quick Start Run the flake-brief skill to analyze my uncommitted flake.lock bump and give me the transition brief.

Frequently Asked Questions about flake-brief

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I check if a flake.lock update will break my Nix config?

Run this skill after updating the lock but before switching. It diffs the lock, prefetches both revisions of each changed input, diffs the upstream source trees, and intersects changed symbols with call sites in your repo to report likely breakages with file:line references.

How to diff two revisions of a Nix flake input?

Use nix flake prefetch with the github:owner/repo/rev URL for each revision to get store paths from the JSON output, then run diff -r on the two store paths. The skill automates this and focuses on exported names, module options, and function signatures.

Which flake inputs does the bump analysis cover?

It watches structural inputs: den, flake-file, import-tree, flake-parts, home-manager, nix-darwin, sops-nix, and nixpkgs (major channel moves only). Leaf and package inputs are skipped unless explicitly requested, and den receives the deepest analysis.

Can I run the flake bump analysis headlessly in CI?

Yes, the skill is designed for headless runs via claude -p with the slash command, writing the brief to stdout. Pipelines typically redirect stdout into a briefs directory for later human review, since the skill is strictly read-only.

Does the flake-brief skill modify or fix my configuration?

No, it is strictly read-only and never edits, restamps, or fixes anything. Its final response is the brief itself; a human reviews the findings and performs any migrations, verification, or documentation updates.