feat: add agent skill

skills/diffx/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: diffx
+description: Operate the diffx Git-diff CLI for worktree diffs, local/remote ref ranges, GitHub PR diffs, GitLab MR diffs, commit/compare URL diffs, and git-diff-compatible pass-through. Use when an agent must decide what to diff, map intent to `diffx` input syntax, choose output mode (`diff`/`patch`/`stat`/etc.), apply include/exclude filters, or resolve common flag/pager conflicts.
+---
+
+# Use Diffx CLI
+
+Use this skill to translate a diffing request into the right `diffx` command.
+
+## Decision Flow
+
+1. Classify the target.
+- Current repo changes only -> load `references/worktree.md`.
+- Two refs/branches/tags/SHAs -> load `references/local-and-remote-ranges.md`.
+- GitHub PR/commit/compare URL or `github:owner/repo#123` -> load `references/github-and-gitlab.md`.
+- GitLab MR (`gitlab:owner/repo!123`) -> load `references/github-and-gitlab.md`.
+
+2. Choose output shape.
+- Full code review output -> `diff` (default).
+- Apply-ready output -> `--mode patch`.
+- Summary output -> `--stat`, `--numstat`, `--shortstat`, `--name-only`, `--name-status`, or `--summary`.
+- Custom table output -> `--overview` only.
+
+3. Apply optional narrowing.
+- File globs -> load `references/filters-and-pass-through.md`.
+- Native git diff flags/pathspec -> load `references/filters-and-pass-through.md`.
+
+4. Handle failures/conflicts.
+- Unexpected empty output, invalid input, or flag conflicts -> load `references/troubleshooting.md`.
+
+## Defaults
+
+- For generic "what changed?": `diffx --no-pager`
+- For compact review: `diffx <range-or-target> --stat --no-pager`
+- For patch handoff: `diffx <range-or-target> --mode patch --no-pager`
+
+## Reference Map
+
+- `references/worktree.md`: current working tree and `--index` behavior.
+- `references/local-and-remote-ranges.md`: branch/tag/SHA and remote shorthand ranges.
+- `references/github-and-gitlab.md`: PR/MR/commit/compare forms.
+- `references/filters-and-pass-through.md`: include/exclude, git flags, pathspec.
+- `references/troubleshooting.md`: invalid combos, exit codes, quick fixes.

skills/diffx/references/filters-and-pass-through.md

@@ -0,0 +1,29 @@
+# Filters And Git Pass-Through
+
+Use when the user wants narrowed output or native `git diff` flags.
+
+## Include/exclude filters
+
+```bash
+diffx main..feature --include "src/**/*.ts" --no-pager
+diffx main..feature --exclude "**/*.test.ts" --no-pager
+diffx --include "*.ts" --include "*.tsx" --exclude "*.js" --exclude "*.jsx" --no-pager
+```
+
+## Native git flag pass-through
+
+```bash
+diffx main..feature -U10 --word-diff --no-pager
+diffx --word-diff-regex 'foo..bar' --no-pager
+```
+
+## Pathspec
+
+```bash
+diffx --stat --no-pager -- src/cli src/utils
+```
+
+## Guidance
+
+- Quote globs to avoid shell expansion side effects.
+- Place pathspecs after `--`.

skills/diffx/references/github-and-gitlab.md

@@ -0,0 +1,34 @@
+# GitHub And GitLab Targets
+
+Use when the input is a hosted PR/MR reference, URL, commit URL, or compare URL.
+
+## GitHub
+
+```bash
+# PR ref shorthand
+diffx github:owner/repo#123 --stat --no-pager
+
+# PR URL
+diffx https://github.com/owner/repo/pull/123 --no-pager
+
+# Commit URL
+diffx https://github.com/owner/repo/commit/abc123 --no-pager
+
+# Compare URL
+diffx https://github.com/owner/repo/compare/main...feature --no-pager
+```
+
+## GitLab
+
+```bash
+# MR ref shorthand
+diffx gitlab:owner/repo!123 --no-pager
+
+# Range shorthand
+diffx gitlab:owner/repo@main..feature --no-pager
+```
+
+## Guidance
+
+- Use `--stat` for quick PR/MR summaries.
+- Use `--mode patch` when the user requests apply-able output.

skills/diffx/references/local-and-remote-ranges.md

@@ -0,0 +1,25 @@
+# Local And Remote Ranges
+
+Use when the request compares two refs, branches, tags, or SHAs.
+
+## Local ranges
+
+```bash
+diffx main..feature --no-pager
+diffx abc123..def456 --no-pager
+diffx refs/heads/main..refs/tags/v1.0 --no-pager
+```
+
+## Remote shorthand ranges
+
+```bash
+diffx owner/repo@main..owner/repo@feature --no-pager
+diffx owner/repo@main..feature --no-pager
+```
+
+## Output variants
+
+```bash
+diffx main..feature --stat --no-pager
+diffx main..feature --mode patch --no-pager
+```

skills/diffx/references/troubleshooting.md

@@ -0,0 +1,22 @@
+# Troubleshooting
+
+Use when command output is empty, errors occur, or flags conflict.
+
+## Invalid combinations
+
+- Do not combine `--pager` with `--no-pager`.
+- Do not combine `--overview` with git output-format flags:
+  - `--stat`, `--numstat`, `--name-only`, `--name-status`, `--raw`, `-p`, `--patch`, `--shortstat`
+
+## Exit code meaning
+
+- `0`: success
+- `1`: no files matched filters
+- `2`: invalid range/input format
+- `3`: git/fetch execution failure
+
+## Quick fixes
+
+- If filters return nothing, retry without filters to verify data exists.
+- If range parsing fails, try explicit local range form (`left..right`) or hosted shorthand (`github:...`, `gitlab:...`).
+- If automation hangs, add `--no-pager`.

skills/diffx/references/worktree.md

@@ -0,0 +1,21 @@
+# Worktree Use Cases
+
+Use when the request is about local uncommitted changes.
+
+## Core commands
+
+```bash
+# Show tracked + untracked local changes
+diffx --no-pager
+
+# Compact status view
+diffx --name-status --no-pager
+
+# Strict git index/worktree behavior
+diffx --index --no-pager
+```
+
+## Guidance
+
+- Prefer plain `diffx` for "what changed locally?".
+- Add a summary flag (`--stat`, `--shortstat`, `--name-only`) when user asks for concise output.