feat: improve agent skill with forked context, reference docs, and release packaging

Run the skill in an isolated subagent (context: fork) to avoid bloating the main conversation. Split JSON schema and jq recipes into reference.md. Ship skill as a tarball in releases with one-liner install commands for Claude Code, Codex, and Amp.

Author: luispadron

.claude/skills/drift/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: drift
-description: Compare files, directories, archives, or binaries using drift. Use when asked to compare, diff, or analyze differences between two paths - builds, releases, directories, archives (.ipa, .apk, .aar, .jar, .tar.gz), binaries, plists, or text files.
+description: Compare and diff files, directories, builds, releases, archives, or binaries. Use when the user wants to compare two versions of something, diff two directories or files, analyze what changed between builds or releases, or examine differences in .ipa, .apk, .aar, .jar, .tar.gz, .tar.bz2, Mach-O binaries, plists, or text files.
 argument-hint: "<path-a> <path-b> [-m mode]"
-allowed-tools: Bash(drift *)
+allowed-tools: Bash(drift *), Bash(jq *)
+context: fork
 ---
 
 Compare $ARGUMENTS using `drift --json` and analyze the results.
@@ -13,9 +14,7 @@ Compare $ARGUMENTS using `drift --json` and analyze the results.
 drift --json <path-a> <path-b>
 ```
 
-Optional: force a comparison mode with `-m <mode>` where mode is one of: `tree`, `binary`, `plist`, `text`.
-
-drift auto-detects the correct mode from the inputs. Use `-m` only when the user explicitly requests a specific mode or auto-detection picks the wrong one.
+Optional: force a comparison mode with `-m <mode>` where mode is one of: `tree`, `binary`, `plist`, `text`. drift auto-detects the correct mode from the inputs - only use `-m` when the user explicitly requests a mode or auto-detection picks the wrong one.
 
 ## Supported inputs
 
@@ -26,45 +25,14 @@ drift auto-detects the correct mode from the inputs. Use `-m` only when the user
 | plist | Property list files (.plist) | Structured key-value diff |
 | text | Everything else | Line-by-line unified diff |
 
-## JSON output schema
-
-Every result includes:
-
-- `path_a`, `path_b` - the compared paths
-- `mode` - detected comparison mode
-- `root` - diff tree where each node has: `name`, `path`, `status` (unchanged/added/removed/modified), `kind`, `is_dir`, `size_a`, `size_b`, and optional `children`
-- `summary` - aggregate counts: `added`, `removed`, `modified`, `unchanged`, `size_delta`
-
-For single-file modes (binary, plist, text), a `detail` field is included:
-
-- **binary**: `symbols` (added/removed symbol names), `sections` (segment/section size changes)
-- **plist**: `changes` with `key_path`, `status`, and before/after values
-- **text**: `hunks` with line-level diffs (`kind`: context/added/removed)
-
-## How to analyze
+## Steps
 
 1. Run `drift --json <path-a> <path-b>` and capture the output
 2. Start with `summary` to give an overview of what changed
 3. For tree mode, walk the `root` to identify the most significant changes (largest size deltas, added/removed files)
 4. For binary mode, focus on symbol changes and section size deltas - these indicate code/data growth
 5. For plist mode, highlight changed keys and their before/after values
 6. For text mode, summarize the hunks by theme (e.g. "updated imports", "refactored function X")
+7. Present size deltas in human-readable units (KB/MB)
 
-When the output is large, use `jq` to extract specific parts rather than dumping everything:
-
-```sh
-# Just the summary
-drift --json A B | jq '.summary'
-
-# Only changed files
-drift --json A B | jq '[.root | .. | select(.status? != "unchanged" and .is_dir? == false)]'
-
-# Size delta per file, sorted
-drift --json A B | jq '[.root | .. | select(.is_dir? == false and .status? == "modified")] | sort_by(.size_b - .size_a) | reverse | .[] | {path, delta: (.size_b - .size_a)}'
-```
-
-## Tips
-
-- For large archives, the JSON can be verbose. Summarize at the directory level first, then drill into specific paths if the user asks.
-- Size delta is in bytes. Convert to human-readable units (KB/MB) when presenting to the user.
-- When comparing builds, highlight: new files added, files removed, largest size increases, and any unexpected changes.
+When the output is large, use `jq` to extract specific parts rather than dumping everything. See [reference.md](reference.md) for the JSON schema and useful jq recipes.

.claude/skills/drift/reference.md

@@ -0,0 +1,40 @@
+# drift JSON reference
+
+## Output schema
+
+Every result includes:
+
+- `path_a`, `path_b` - the compared paths
+- `mode` - detected comparison mode (`tree`, `binary`, `plist`, `text`)
+- `root` - diff tree where each node has: `name`, `path`, `status` (unchanged/added/removed/modified), `kind`, `is_dir`, `size_a`, `size_b`, and optional `children`
+- `summary` - aggregate counts: `added`, `removed`, `modified`, `unchanged`, `size_delta`
+
+For single-file modes (binary, plist, text), a `detail` field is included:
+
+- **binary**: `symbols` (added/removed symbol names), `sections` (segment/section size changes)
+- **plist**: `changes` with `key_path`, `status`, and before/after values
+- **text**: `hunks` with line-level diffs (`kind`: context/added/removed)
+
+## Useful jq recipes
+
+```sh
+# Just the summary
+drift --json A B | jq '.summary'
+
+# Only changed files (flat list)
+drift --json A B | jq '[.root | .. | select(.status? != "unchanged" and .is_dir? == false)]'
+
+# Size delta per file, sorted largest first
+drift --json A B | jq '[.root | .. | select(.is_dir? == false and .status? == "modified")] | sort_by(.size_b - .size_a) | reverse | .[] | {path, delta: (.size_b - .size_a)}'
+
+# List all added files
+drift --json A B | jq '[.root | .. | select(.status? == "added") | .path]'
+
+# Total size delta
+drift --json A B | jq '.summary.size_delta'
+```
+
+## Tips
+
+- For large archives, summarize at the directory level first, then drill into specific paths if the user asks.
+- When comparing builds, highlight: new files added, files removed, largest size increases, and any unexpected changes.

.goreleaser.yaml

@@ -22,9 +22,13 @@ archives:
 checksum:
   name_template: "checksums.txt"
 
+before:
+  hooks:
+    - tar -czf skill.tar.gz -C .claude/skills/drift .
+
 release:
   extra_files:
-    - glob: .claude/skills/drift/SKILL.md
+    - glob: skill.tar.gz
 
 changelog:
   sort: asc

README.md

@@ -158,20 +158,20 @@ drift works on **macOS**, **Linux**, and **Windows**. Core features (directory/a
 
 ## Agent skill
 
-drift ships a skill file that gives AI coding agents native access to structured file comparison via `drift --json`. The skill is included in every [GitHub release](https://github.com/block/drift/releases).
+drift ships a skill that gives AI coding agents native access to structured file comparison via `drift --json`. The skill is included in every [GitHub release](https://github.com/block/drift/releases).
 
 Install with a single command:
 
 **Claude Code**
 
 ```sh
-gh release download --repo block/drift --pattern 'SKILL.md' --dir ~/.claude/skills/drift
+mkdir -p ~/.claude/skills/drift && gh release download --repo block/drift --pattern 'skill.tar.gz' --output - | tar -xz -C ~/.claude/skills/drift
 ```
 
 **Codex / Amp**
 
 ```sh
-gh release download --repo block/drift --pattern 'SKILL.md' --dir ~/.agents/skills/drift
+mkdir -p ~/.agents/skills/drift && gh release download --repo block/drift --pattern 'skill.tar.gz' --output - | tar -xz -C ~/.agents/skills/drift
 ```
 
 ## License