refactor(prompts): apply Claude 5 context-engineering rules to the commands

.antigravity/skills/code-refinement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: code-refinement
-description: "Review staged files for code quality (KISS, DRY, YAGNI, Clean Code) and fix linting issues."
+description: "Review staged files for code quality (KISS, DRY, YAGNI, Clean Code) and fix linting issues. Use to clean up staged work before review or commit — unlike code-review, this one edits the code: it applies refactors, runs the linter, and fills test gaps."
 ---
 
 # Code Refinement

.antigravity/skills/code-review/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: code-review
-description: "Review staged changes for security, correctness, performance, and clarity. Writes findings to agent-code-review.md."
+description: "Review staged changes for security, correctness, performance, and clarity. Use when asked to review, audit, or sanity-check work that is staged but not yet committed, or before opening a PR. Writes findings to agent-code-review.md; does not modify source. For an already-open GitHub PR use review-pr instead."
 ---
 
 # Role
 
-You are a senior code reviewer and security expert. You are tech stack agnostic and adapt your review to the project's languages and frameworks.
+You are a senior code reviewer and security expert.
 You only read and analyze the code — you must never modify any source code files in the repository.
 The sole exception is writing your review output into a Markdown file.
 You never ask the user what to do next and you produce exactly one review report per run.
@@ -26,22 +26,14 @@ You never ask the user what to do next and you produce exactly one review report
 
 - Review only files that are currently staged in Git, not the entire repository.
 - Focus on changed lines and minimal necessary surrounding context.
-- Use unified diffs to compute accurate new file line numbers for comments.
 - If information is missing, state reasonable assumptions and proceed.
 
 ## How to Collect Context
 
-1. Verify staged files exist: git status --porcelain (look for changes in column 1)
-2. Get the diff: git diff --staged --unified=0 --no-color
-3. If diff is empty but status shows staged files: git diff --staged --no-color (fallback)
-4. For context when needed: git diff --staged -U3 --no-color
-   Parse output:
-   - Hunk headers: @@ -oldStart,oldCount +newStart,newCount @@
-   - Target line numbers from +newStart and +newCount
-   - File paths from diff --git lines
-
-   Fallback if inconsistent: Always trust git status --porcelain over empty diff output.
-5. For dead code detection or DRY/YAGNI opportunities, you may examine other project files (e.g., to confirm unused functions or repeated patterns). Restrict this exploration to the minimal files necessary to support the finding.
+- `git diff --staged --unified=0 --no-color` is the primary input; pull `-U3` when a finding needs surrounding context.
+- Cite line numbers from the `+` side of each hunk so they match the post-merge file.
+- Gotcha: an empty diff does not mean an empty review. If `git status --porcelain` shows staged files, trust it and re-run the diff without `--unified=0`.
+- For dead code, DRY, or YAGNI findings, read the fewest other project files needed to support the claim.
 
 ## Review Policy
 

.antigravity/skills/commitmsg/SKILL.md

@@ -1,12 +1,10 @@
 ---
 name: commitmsg
-description: "Propose a single git commit message for the currently staged changes."
+description: "Propose a single git commit message for the currently staged changes. Use when asked to write, draft, or suggest a commit message, or to check that a message matches the repo's conventions. Proposes the message only — it does not commit."
 ---
 
 # Commit Message
 
-Propose a single git commit message for the currently staged changes.
-
 ## Gather context
 
 Run these commands to understand the changes:

.antigravity/skills/dependency-review/SKILL.md

@@ -1,16 +1,12 @@
 ---
 name: dependency-review
-description: "Audit package dependency updates for supply-chain risk: publish-age gate, changelog/diff verification, security advisories, community signals, and breaking changes."
+description: "Audit package dependency updates for supply-chain risk: publish-age gate, changelog/diff verification, security advisories, community signals, and breaking changes. Use whenever a branch, PR, or working directory changes a dependency manifest or lockfile — package.json, requirements.txt, pyproject.toml, Gemfile, go.mod, Cargo.toml, pom.xml, build.gradle, composer.json, pubspec.yaml, or the lockfile beside them — including Dependabot/Renovate batches and newly added packages."
 ---
 
 # Package Update Supply Chain Review
 
 Review dependency updates to catch supply chain attacks, breaking changes, and risky packages before they land in your codebase.
 
-## When to Use This Skill
-
-Activate this review whenever a branch, PR, or working directory includes changes to dependency manifests or lockfiles. Common triggers include version bumps in package.json, requirements.txt, pyproject.toml, Gemfile, go.mod, Cargo.toml, pom.xml, build.gradle, composer.json, pubspec.yaml, or their corresponding lockfiles.
-
 ## Review Workflow
 
 For each updated or newly added package, work through all five checks below. Prefer CLI and API lookups (`npm view`, `pip index`, `gh api`, `curl` against registry/OSV endpoints) over web browsing — they are faster, cheaper, and available in more environments. Never invent results for a check you could not actually perform: report it as **SKIPPED** with the reason. Present findings in a single summary report at the end, grouped by package. Flag any failing check as a **HOLD** and recommend the team investigate before merging.
@@ -22,8 +18,7 @@ For each updated or newly added package, work through all five checks below. Pre
 **Steps:**
 
 1. Look up the publish date for the exact version on its registry — e.g. `npm view <pkg> time --json`, `curl https://pypi.org/pypi/<pkg>/<version>/json`, `gem info <pkg> --remote`, or the registry's web page.
-2. Calculate the number of days between the publish date and today.
-3. If fewer than 7 days have elapsed, flag this as **HOLD - TOO NEW** and include the publish date, the age in days, and a recommendation to wait or pin to the prior version.
+2. If fewer than 7 days have elapsed, flag this as **HOLD - TOO NEW** and include the publish date, the age in days, and a recommendation to wait or pin to the prior version.
 
 ### 2. Changelog and Diff Verification
 
@@ -75,7 +70,7 @@ For each updated or newly added package, work through all five checks below. Pre
 
 **Steps:**
 
-1. Check if the version bump follows semver. A major version bump signals intentional breaking changes. A minor or patch bump with breaking changes is a red flag on its own (either accidental or a sign of poor maintenance practices).
+1. Check the bump against semver. Breaking changes in a minor or patch release are a red flag on their own — either accidental or a sign of poor maintenance practices.
 2. Read the migration guide or upgrade notes if one exists.
 3. Look at the diff for: removed or renamed exports, changed function signatures, altered default values, removed configuration options, or dropped support for runtimes/platforms.
 4. Search the codebase for usages of any changed or removed APIs. List the files and line numbers that may need updates.

.antigravity/skills/efficient-orchestration/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: efficient-orchestration
-description: "Run this task with your current model orchestrating while cheaper subagents do the token-heavy research, coding, and testing."
+description: "Run this task with your current model orchestrating while cheaper subagents do the token-heavy research, coding, and testing. Use for work that is large, parallelizable, or token-hungry — broad repo scans, long logs, wide test or browser passes, repetitive edits — or when the user asks to conserve usage limits. Skip it for small, sequential, or judgment-dense tasks."
 ---
 
 # Efficient Orchestration
 
-Orchestrate this task on your current model; delegate token-heavy work to cheaper, faster subagents. Use your harness's subagent mechanism if it has one (e.g. Claude Code's Task tool, Antigravity subagents); otherwise spawn your own CLI non-interactively per slice with an explicit model (e.g. `codex exec -m <model> "<handoff>"`).
+Use your harness's subagent mechanism if it has one (e.g. Claude Code's Task tool, Antigravity subagents); otherwise spawn your own CLI non-interactively per slice with an explicit model (e.g. `codex exec -m <model> "<handoff>"`).
 
 ## Tiers
 

.antigravity/skills/review-pr/SKILL.md

@@ -1,12 +1,10 @@
 ---
 name: review-pr
-description: "Process unresolved review comments on a GitHub PR, fix valid issues, ensure CI passes, and re-request review."
+description: "Process unresolved review comments on a GitHub PR, fix valid issues, ensure CI passes, and re-request review. Use when asked to address, respond to, or clear PR feedback, or to get a PR green and back in front of its reviewers. Operates on an open PR; for local staged work use code-review instead."
 ---
 
 # Review PR Feedback Loop
 
-Process unresolved review comments on a GitHub PR, fix valid issues, ensure CI passes, and re-request review.
-
 ## Constraints
 
 ALL shell operations: `gh api` with `--jq`/`--paginate` and bash only. No Python/Node/script files. No `curl` for GitHub API. Polling loops must be inline bash `while`/`sleep`.

.claude/commands/code-refinement.md

@@ -1,5 +1,5 @@
 ---
-description: "Review staged files for code quality (KISS, DRY, YAGNI, Clean Code) and fix linting issues."
+description: "Review staged files for code quality (KISS, DRY, YAGNI, Clean Code) and fix linting issues. Use to clean up staged work before review or commit — unlike code-review, this one edits the code: it applies refactors, runs the linter, and fills test gaps."
 ---
 
 # Code Refinement

.claude/commands/code-review.md

@@ -1,10 +1,10 @@
 ---
-description: "Review staged changes for security, correctness, performance, and clarity. Writes findings to agent-code-review.md."
+description: "Review staged changes for security, correctness, performance, and clarity. Use when asked to review, audit, or sanity-check work that is staged but not yet committed, or before opening a PR. Writes findings to agent-code-review.md; does not modify source. For an already-open GitHub PR use review-pr instead."
 ---
 
 # Role
 
-You are a senior code reviewer and security expert. You are tech stack agnostic and adapt your review to the project's languages and frameworks.
+You are a senior code reviewer and security expert.
 You only read and analyze the code — you must never modify any source code files in the repository.
 The sole exception is writing your review output into a Markdown file.
 You never ask the user what to do next and you produce exactly one review report per run.
@@ -25,22 +25,14 @@ You never ask the user what to do next and you produce exactly one review report
 
 - Review only files that are currently staged in Git, not the entire repository.
 - Focus on changed lines and minimal necessary surrounding context.
-- Use unified diffs to compute accurate new file line numbers for comments.
 - If information is missing, state reasonable assumptions and proceed.
 
 ## How to Collect Context
 
-1. Verify staged files exist: git status --porcelain (look for changes in column 1)
-2. Get the diff: git diff --staged --unified=0 --no-color
-3. If diff is empty but status shows staged files: git diff --staged --no-color (fallback)
-4. For context when needed: git diff --staged -U3 --no-color
-   Parse output:
-   - Hunk headers: @@ -oldStart,oldCount +newStart,newCount @@
-   - Target line numbers from +newStart and +newCount
-   - File paths from diff --git lines
-
-   Fallback if inconsistent: Always trust git status --porcelain over empty diff output.
-5. For dead code detection or DRY/YAGNI opportunities, you may examine other project files (e.g., to confirm unused functions or repeated patterns). Restrict this exploration to the minimal files necessary to support the finding.
+- `git diff --staged --unified=0 --no-color` is the primary input; pull `-U3` when a finding needs surrounding context.
+- Cite line numbers from the `+` side of each hunk so they match the post-merge file.
+- Gotcha: an empty diff does not mean an empty review. If `git status --porcelain` shows staged files, trust it and re-run the diff without `--unified=0`.
+- For dead code, DRY, or YAGNI findings, read the fewest other project files needed to support the claim.
 
 ## Review Policy
 

.claude/commands/commitmsg.md

@@ -1,12 +1,10 @@
 ---
-description: "Propose a single git commit message for the currently staged changes."
+description: "Propose a single git commit message for the currently staged changes. Use when asked to write, draft, or suggest a commit message, or to check that a message matches the repo's conventions. Proposes the message only — it does not commit."
 allowed-tools: Bash(git diff:*), Bash(git status:*), Bash(git log:*), Bash(git branch:*)
 ---
 
 # Commit Message
 
-Propose a single git commit message for the currently staged changes.
-
 ## Gather context
 
 Run these commands to understand the changes:

.claude/commands/dependency-review.md

@@ -1,15 +1,11 @@
 ---
-description: "Audit package dependency updates for supply-chain risk: publish-age gate, changelog/diff verification, security advisories, community signals, and breaking changes."
+description: "Audit package dependency updates for supply-chain risk: publish-age gate, changelog/diff verification, security advisories, community signals, and breaking changes. Use whenever a branch, PR, or working directory changes a dependency manifest or lockfile — package.json, requirements.txt, pyproject.toml, Gemfile, go.mod, Cargo.toml, pom.xml, build.gradle, composer.json, pubspec.yaml, or the lockfile beside them — including Dependabot/Renovate batches and newly added packages."
 ---
 
 # Package Update Supply Chain Review
 
 Review dependency updates to catch supply chain attacks, breaking changes, and risky packages before they land in your codebase.
 
-## When to Use This Skill
-
-Activate this review whenever a branch, PR, or working directory includes changes to dependency manifests or lockfiles. Common triggers include version bumps in package.json, requirements.txt, pyproject.toml, Gemfile, go.mod, Cargo.toml, pom.xml, build.gradle, composer.json, pubspec.yaml, or their corresponding lockfiles.
-
 ## Review Workflow
 
 For each updated or newly added package, work through all five checks below. Prefer CLI and API lookups (`npm view`, `pip index`, `gh api`, `curl` against registry/OSV endpoints) over web browsing — they are faster, cheaper, and available in more environments. Never invent results for a check you could not actually perform: report it as **SKIPPED** with the reason. Present findings in a single summary report at the end, grouped by package. Flag any failing check as a **HOLD** and recommend the team investigate before merging.
@@ -21,8 +17,7 @@ For each updated or newly added package, work through all five checks below. Pre
 **Steps:**
 
 1. Look up the publish date for the exact version on its registry — e.g. `npm view <pkg> time --json`, `curl https://pypi.org/pypi/<pkg>/<version>/json`, `gem info <pkg> --remote`, or the registry's web page.
-2. Calculate the number of days between the publish date and today.
-3. If fewer than 7 days have elapsed, flag this as **HOLD - TOO NEW** and include the publish date, the age in days, and a recommendation to wait or pin to the prior version.
+2. If fewer than 7 days have elapsed, flag this as **HOLD - TOO NEW** and include the publish date, the age in days, and a recommendation to wait or pin to the prior version.
 
 ### 2. Changelog and Diff Verification
 
@@ -74,7 +69,7 @@ For each updated or newly added package, work through all five checks below. Pre
 
 **Steps:**
 
-1. Check if the version bump follows semver. A major version bump signals intentional breaking changes. A minor or patch bump with breaking changes is a red flag on its own (either accidental or a sign of poor maintenance practices).
+1. Check the bump against semver. Breaking changes in a minor or patch release are a red flag on their own — either accidental or a sign of poor maintenance practices.
 2. Read the migration guide or upgrade notes if one exists.
 3. Look at the diff for: removed or renamed exports, changed function signatures, altered default values, removed configuration options, or dropped support for runtimes/platforms.
 4. Search the codebase for usages of any changed or removed APIs. List the files and line numbers that may need updates.

.claude/commands/efficient-orchestration.md

@@ -1,10 +1,10 @@
 ---
-description: "Run this task with your current model orchestrating while cheaper subagents do the token-heavy research, coding, and testing."
+description: "Run this task with your current model orchestrating while cheaper subagents do the token-heavy research, coding, and testing. Use for work that is large, parallelizable, or token-hungry — broad repo scans, long logs, wide test or browser passes, repetitive edits — or when the user asks to conserve usage limits. Skip it for small, sequential, or judgment-dense tasks."
 ---
 
 # Efficient Orchestration
 
-Orchestrate this task on your current model; delegate token-heavy work to cheaper, faster subagents. Use your harness's subagent mechanism if it has one (e.g. Claude Code's Task tool, Antigravity subagents); otherwise spawn your own CLI non-interactively per slice with an explicit model (e.g. `codex exec -m <model> "<handoff>"`).
+Use your harness's subagent mechanism if it has one (e.g. Claude Code's Task tool, Antigravity subagents); otherwise spawn your own CLI non-interactively per slice with an explicit model (e.g. `codex exec -m <model> "<handoff>"`).
 
 ## Tiers
 

.claude/commands/review-pr.md

@@ -1,12 +1,10 @@
 ---
-description: "Process unresolved review comments on a GitHub PR, fix valid issues, ensure CI passes, and re-request review."
+description: "Process unresolved review comments on a GitHub PR, fix valid issues, ensure CI passes, and re-request review. Use when asked to address, respond to, or clear PR feedback, or to get a PR green and back in front of its reviewers. Operates on an open PR; for local staged work use code-review instead."
 argument-hint: "[PR_NUMBER]"
 ---
 
 # Review PR Feedback Loop
 
-Process unresolved review comments on a GitHub PR, fix valid issues, ensure CI passes, and re-request review.
-
 ## Constraints
 
 ALL shell operations: `gh api` with `--jq`/`--paginate` and bash only. No Python/Node/script files. No `curl` for GitHub API. Polling loops must be inline bash `while`/`sleep`.

.codex/skills/code-refinement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: code-refinement
-description: "Review staged files for code quality (KISS, DRY, YAGNI, Clean Code) and fix linting issues."
+description: "Review staged files for code quality (KISS, DRY, YAGNI, Clean Code) and fix linting issues. Use to clean up staged work before review or commit — unlike code-review, this one edits the code: it applies refactors, runs the linter, and fills test gaps."
 ---
 
 # Code Refinement