How to use the Authoring Patch Sets agent skill

What the skill makes the agent do

Every firmware patch in the project is declared in a patch set, selected by a preset, and written only if its gate allows it. A patch that exists in code but in no manifest still applies, but it cannot be turned off and it prints a warning on every run. The skill teaches the agent to declare each new patch properly.

The skill is not a patching tool. It does not run patches or modify firmware. It gives the agent rules and examples for naming a patch identifier, setting version gates, marking boot-essential patches and creating new patch sets or presets.

• Declare a patch in a set's patches array using a VPhonePatchDeclaration
• Pick an identifier in the form {component}-{effect}-{name}
• Set version gates with VPhonePatchApplicability instead of strings
• Mark patches the guest needs to boot with bootEssential: true
• Create a new patch set or add a preset plist

How to install the authoring-patch-sets skill

Download the skill ZIP from this page. The skill is a single file, SKILL.md. Unzip it into one of two locations depending on how you want to use it.

For a personal setup available across projects, unzip it into ~/.claude/skills/. To limit it to one project, unzip it into that project's .claude/skills/ folder.

In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/authoring-patch-sets/
• Project only: .claude/skills/authoring-patch-sets/ inside the project
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

How to trigger the skill with natural requests

You do not need a special command. The skill's description tells the agent when to use it, so ask for patch work in plain language while working in the vphone-cli source repository. The skill is written for changes to that codebase, so make sure the agent can access it.

Requests that match the skill's description include adding or changing a patch in FirmwarePatcher, giving a patch a version gate, making a patch selectable or off by default, and building an out-of-tree .vphonepatchset.

• "Add a kernel boot patch for the new sandbox hook and declare it properly."
• "This patch only applies to iOS 18. Add a version gate."
• "Make the new txm patch off by default but selectable in the UI."
• "I want to package my patches as an out-of-tree .vphonepatchset. Set it up."

Follow the rules the skill enforces

Adding a patch to an existing set has five parts: write the patch, note the record identifier it emits, declare it, build, and check the logs. Naming follows a fixed scheme, and declarations cover their own record and any site written as <identifier>.<site>. Only a dot starts a site, so an underscore never separates one.

Version gates must be structured. A version gate is not a preference, and a preset cannot widen a gate. Boot-essential declarations must have a summary, because it is the text read before someone unticks a box that stops their VM booting.

• Identifier shape: {component}-{effect}-{name}, with snake_case names using only [a-z0-9_]
• Effect is derived: boot if bootEssential, else exp if standard leaves it off, else cfw
• No identifier may be a record-site prefix of another
• Do not add boolean flags to FirmwarePipeline or --force-something CLI flags for patches

Check the work with the test corpus

After adding a declaration, build and run the golden corpus. A record that no declaration covers prints a warning that it is declared by no patch set and is being applied anyway. Search the logs for that phrase and make sure it is absent.

The test named for patch identifiers in FirmwarePatchSetCatalogTests checks the shape, effect and uniqueness of every bundled declaration. The agent should be told to run these checks rather than assume the change is correct.

• Grep the build logs for "declared by no patch set"; it must not appear
• Run the FirmwarePatchSetCatalogTests suite

Create a new patch set or preset

Create a new set only when its patches share a reason to be on or off together. The skill points to FirmwareKernelFridaPatchSet.swift as the smallest example to copy. Register the new manifest in FirmwarePatchSetCatalog.bundled, and gate its patcher's construction on includesSet(...) so that leaving the set out also leaves the patcher out.

Add the set to both shipped preset plists. Each preset names every set, and presets differ by their selection rather than by which sets they use. The minimal preset is the one exception.

• Manifest fields include identifier, name, summary, patches, requires, provides, conflictsWith and after
• Shipped presets live in VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/