skills/nilbuild__diffity
1
0
Fork 0
mirror of https://github.com/nilbuild/diffity.git synced 2026-09-19 07:26:16 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat: improve skills for resolution and rename

Browse Source
This commit is contained in:
Kamran Ahmed
2026-03-17 22:02:17 +00:00
parent 94ec7168d9
commit 753cfe06ca
11 changed files with 186 additions and 112 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+13 -17
View File
@@ -36,27 +36,23 @@ npx skills add kamranahmedse/diffity
Then use the slash commands:
### `/diffity-diff`
Opens the diff viewer in your browser. Leave comments on any line — when you're done, run `/diffity-resolve` to have your agent fix them.
### `/diffity-review`
Your agent reviews the diff and leaves comments in the viewer. Uses severity tags: `[must-fix]`, `[suggestion]`, `[nit]`, `[question]`. You can focus on a specific area:
```
# use this skill to open the browser with diff viewer
# you can review the code yourself and leave comments
/diffity-start
# once done, you can come back to the agent and use the
# below skill to ask agent to resolve your comments.
/diffity-resolve
# you can use this to have AI review your uncommitted
# changes and leave comments in the diff viewer
/diffity-review
/diffity-review security
/diffity-review performance
/diffity-review naming
```
The review uses severity tags so you know what matters:
- `[must-fix]` — Bugs, security issues
- `[suggestion]` — Meaningful improvements
- `[nit]` — Style preferences
- `[question]` — Needs clarification
### `/diffity-resolve`
You can focus the review on what you care about: `/diffity-review security` or `/diffity-review performance`
Reads all open comments and makes the requested code changes. Works with both your comments and AI review comments.
## Multiple projects
packages/cli/CHANGELOG.md
+12
View File
@@ -1,5 +1,17 @@
# diffity
## 0.2.0
### Minor Changes
- Refactor skills
## 0.1.5
### Patch Changes
- Improve skills and add support for multiple sessions
## 0.1.4
### Patch Changes
packages/cli/package.json
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "diffity",
"version": "0.1.4",
"version": "0.2.0",
"description": "GitHub-style git diff viewer in the browser",
"type": "module",
"bin": {
packages/skills/diffity-diff/SKILL.md
+24
View File
@@ -0,0 +1,24 @@
---
name: diffity-diff
description: Open the diffity diff viewer in the browser to see your changes
user-invocable: true
---
# Diffity Diff Skill
You are opening the diffity diff viewer so the user can see their changes in the browser.
## Instructions
1. Check that `{{binary}}` is available: run `which {{binary}}`. If not found, {{install_hint}}.
2. Run `{{binary}}` using the Bash tool with `run_in_background: true`:
- The CLI handles everything: if an instance is already running for this repo it reuses it and opens the browser, otherwise it starts a new server and opens the browser.
- Do NOT use `&` or `--quiet` — let the Bash tool handle backgrounding.
3. Wait 2 seconds, then run `{{binary}} list --json` to get the port.
4. Tell the user diffity is running. Print the URL and keep it short — don't show session IDs, hashes, or other internals. Example:
> Diffity is running at http://localhost:5391
>
> When you're ready:
> - Leave comments on the diff in your browser, then run **{{slash}}resolve** to fix them
> - Or run **{{slash}}review** to get an AI code review
packages/skills/diffity-resolve/SKILL.md
+13 -7
View File
@@ -32,7 +32,7 @@ You are reading open review comments and resolving them by making the requested
## Prerequisites
1. Check that `{{binary}}` is available: run `which {{binary}}`. If not found, {{install_hint}}.
2. Check that a review session exists: run `{{binary}} agent list`. If this fails with "No active review session", tell the user to start diffity first (e.g. `{{binary}}` or **{{slash}}start**).
2. Check that a review session exists: run `{{binary}} agent list`. If this fails with "No active review session", tell the user to start diffity first (e.g. `{{binary}}` or **{{slash}}diff**).
## Instructions
@@ -42,11 +42,17 @@ You are reading open review comments and resolving them by making the requested
```
If a `thread-id` argument was provided, filter to just that thread. The JSON output includes the full comment body, file path, line numbers, and side for each thread.
2. If there are no open threads, tell the user there's nothing to resolve.
3. For each open thread:
3. For each open thread, check the `comments` array and the `author.type` field (`"user"` or `"agent"`) on each comment:
a. **Skip** general comments (filePath `__general__`) — these are summaries, not actionable code changes.
b. **Skip** threads where the comment body starts with an explicit `[question]` or `[nit]` tag prefix — these don't require code changes. Tell the user you skipped them and why.
- **Important:** Only skip if the comment body literally begins with `[question]` or `[nit]`. Do NOT skip comments just because they are phrased as a question (e.g. "should we add X?" or "can we rename this?"). Comments phrased as questions without explicit tags are suggestions — treat them as actionable requests.
c. Read the comment body from the JSON output and understand what change is requested. Interpret the intent:
b. **Skip** threads where the last comment is an agent reply that asks the user a question (e.g. "Could you clarify...?") and the user hasn't responded yet — the agent is waiting for user input. Still process threads where the agent left the original comment (code suggestion, review feedback, etc.) — those are actionable.
c. **`[nit]` comments** — these are minor suggestions but still actionable. Resolve them like any other comment.
d. **`[question]` comments** (from the user) — read the question, examine the relevant code, and reply with an answer:
```
{{binary}} agent reply <thread-id> --body "Your answer here"
```
Then resolve the thread with a summary of your answer.
e. Comments phrased as questions without an explicit `[question]` tag (e.g. "should we add X?" or "can we rename this?") are suggestions — treat them as actionable requests and make the change.
f. Read the comment body from the JSON output and understand what change is requested. Interpret the intent:
- If the comment suggests a code change, make the change.
- If the comment suggests adding documentation, add or update the relevant docs.
- If the comment asks a question that implies an action (e.g. "should we add X?"), treat it as a request to do that action.
@@ -54,8 +60,8 @@ You are reading open review comments and resolving them by making the requested
```
{{binary}} agent reply <thread-id> --body "Could you clarify what change you'd like here?"
```
d. Read the relevant source file to understand the full context around the commented lines, then make the requested change using the Edit tool.
e. After making the change, resolve the thread with a summary:
g. Read the relevant source file to understand the full context around the commented lines, then make the requested change using the Edit tool.
h. After making the change, resolve the thread with a summary:
```
{{binary}} agent resolve <thread-id> --summary "Fixed: <brief description of what was changed>"
```
packages/skills/diffity-review/SKILL.md
+43 -12
View File
@@ -32,11 +32,23 @@ You are reviewing a diff and leaving inline comments using the `{{binary}} agent
## Prerequisites
1. Check that `{{binary}}` is available: run `which {{binary}}`. If not found, {{install_hint}}.
2. Check that a review session exists: run `{{binary}} agent list`. If this fails with "No active review session", tell the user to start diffity first (e.g. `{{binary}}` or **{{slash}}start**).
## Instructions
1. Read the current diff using `git diff`. Check `.diffity/current-session` to determine which ref is active.
### Step 1: Ensure diffity is running (without opening browser)
The review needs a running session to add comments to, but we don't want to open the browser until comments are ready.
1. Run `{{binary}} list --json` to check if diffity is already running for this repo.
2. If already running, note the port and continue to Step 2.
3. If not running, start it in the background **without opening the browser**:
- Command: `{{binary}} --no-open`
- Use Bash tool with `run_in_background: true`
- Wait 2 seconds, then verify with `{{binary}} list --json` and note the port.
### Step 2: Review the diff
1. Read the current diff using `git diff`. If diffity was started with a specific ref, use the appropriate git diff command.
2. For each changed file, read the **entire file** (not just the diff hunks) to understand the full context. This prevents false positives from missing surrounding code.
3. Analyze the code changes thoroughly. If a `focus` argument was provided, concentrate on that area. Otherwise look for:
- Bugs, logic errors, off-by-one errors
@@ -49,26 +61,45 @@ You are reviewing a diff and leaving inline comments using the `{{binary}} agent
4. **Only comment on code that was changed in the diff.** Do not flag pre-existing issues in unchanged code — this is a review of the diff, not an audit of the entire file. The only exception is if a change in the diff introduces a bug in combination with existing code.
5. **Prioritize signal over volume.** A clean diff should get a clean review. Do not manufacture findings to appear thorough. If a diff with 5 changed lines only has 1 real issue, leave 1 comment.
6. **Do not repeat the same issue across files.** If the same pattern appears in multiple places, leave one inline comment on the first occurrence and mention it in the general summary instead of commenting on every instance.
7. Categorize each finding with a severity prefix in the comment body:
### Step 3: Leave comments
1. Categorize each finding with a severity prefix in the comment body:
- `[must-fix]` — Bugs, security issues, data loss risks. These must be addressed.
- `[suggestion]` — Improvements that would meaningfully improve the code.
- `[nit]` — Style or preference. Fine to ignore.
- `[question]` — Something unclear that needs clarification from the author.
8. For each finding, leave a comment using:
2. For each finding, leave an inline comment using:
```
{{binary}} agent comment --file <path> --line <n> [--end-line <n>] [--side new] --body "<comment>"
```
- Use `--side new` (default) for comments on added/modified code
- Use `--side old` for comments on removed code
- Use `--end-line` when the issue spans multiple lines
- Be specific and actionable in your comments
9. After leaving all inline comments, write a general comment that summarizes your overall assessment of the diff. This should cover:
- Overall quality verdict (e.g. "Looks good with minor issues" or "Needs significant changes before merging")
- Cross-cutting concerns that don't belong on any single line (architecture, naming consistency across files, missing tests, etc.)
- A count of findings by severity (e.g. "2 must-fix, 3 suggestions, 1 nit")
- Be specific and actionable — lead with the point, skip filler
3. After leaving all inline comments, write a general comment summarizing the diff. **Do not use severity prefixes in the general comment** — prefixes are only for inline findings. The general comment should:
- **Lead with the verdict** (e.g. "LGTM", "Needs changes before merging", "Looks good with minor issues")
- Use separate paragraphs or bullets when covering multiple points — no walls of text
- Mention cross-cutting concerns that don't belong on any single line (architecture, naming consistency, missing tests, etc.)
- Include a count of findings by severity if there are any (e.g. "1 must-fix, 2 suggestions")
- Be direct and concise — no compliments, no filler, no narrating what the code does
```
{{binary}} agent general-comment --body "<overall review summary>"
```
If there are no inline findings, still leave a general comment with your assessment (e.g. "Clean diff — no issues found").
10. Run `{{binary}} agent list` to confirm all comments were created.
11. Tell the user to check the browser — comments will appear within 2 seconds via polling.
If there are no inline findings, still leave a general comment with your assessment (e.g. "LGTM — clean diff, no issues found").
### Step 4: Open the browser
1. Run `{{binary}} agent list` to confirm all comments were created.
2. Open the browser now that comments are ready:
```
open http://localhost:<port>
```
Use the port from Step 1.
3. Tell the user the review is ready and they can check the browser. Example:
> Review complete — check your browser.
>
> Found: 2 must-fix, 3 suggestions, 1 nit
>
> When you're ready, run **{{slash}}resolve** to fix them.
packages/skills/diffity-start/SKILL.md
-27
View File
@@ -1,27 +0,0 @@
---
name: diffity-start
description: Start the diffity diff viewer server for the current working tree or staged changes
user-invocable: true
---
# Diffity Start Skill
You are starting the diffity diff viewer so the user can see their changes in the browser.
## Instructions
1. Check that `{{binary}}` is available: run `which {{binary}}`. If not found, {{install_hint}}.
2. Check if diffity is already running for this repo: run `{{binary}} list --json`. If it shows an entry for this repo, diffity is already running — skip to step 5.
3. Start the server using the Bash tool with `run_in_background: true`:
- Command: `{{binary}}`
- Do NOT use `&` or `--quiet` — let the Bash tool handle backgrounding
- The browser will open automatically and the session is auto-created on startup
- If diffity detects an existing instance for this repo, it will reuse it automatically
4. Wait 2 seconds, then verify it's running with `{{binary}} list`.
5. Tell the user diffity is running and show them what they can do next. Keep it short — don't show session IDs, hashes, or other internals. Example:
> Diffity is running — check your browser.
>
> When you're ready:
> - Leave comments on the diff in your browser, then run **{{slash}}resolve** to fix them
> - Or run **{{slash}}review** to get an AI code review
skills/diffity-diff/SKILL.md
+24
View File
@@ -0,0 +1,24 @@
---
name: diffity-diff
description: Open the diffity diff viewer in the browser to see your changes
user-invocable: true
---
# Diffity Diff Skill
You are opening the diffity diff viewer so the user can see their changes in the browser.
## Instructions
1. Check that `diffity` is available: run `which diffity`. If not found, install it with `npm install -g diffity`.
2. Run `diffity` using the Bash tool with `run_in_background: true`:
- The CLI handles everything: if an instance is already running for this repo it reuses it and opens the browser, otherwise it starts a new server and opens the browser.
- Do NOT use `&` or `--quiet` — let the Bash tool handle backgrounding.
3. Wait 2 seconds, then run `diffity list --json` to get the port.
4. Tell the user diffity is running. Print the URL and keep it short — don't show session IDs, hashes, or other internals. Example:
> Diffity is running at http://localhost:5391
>
> When you're ready:
> - Leave comments on the diff in your browser, then run **/diffity-resolve** to fix them
> - Or run **/diffity-review** to get an AI code review
skills/diffity-resolve/SKILL.md
+13 -7
View File
@@ -32,7 +32,7 @@ diffity agent reply <id> --body "<text>"
## Prerequisites
1. Check that `diffity` is available: run `which diffity`. If not found, install it with `npm install -g diffity`.
2. Check that a review session exists: run `diffity agent list`. If this fails with "No active review session", tell the user to start diffity first (e.g. `diffity` or **/diffity-start**).
2. Check that a review session exists: run `diffity agent list`. If this fails with "No active review session", tell the user to start diffity first (e.g. `diffity` or **/diffity-diff**).
## Instructions
@@ -42,11 +42,17 @@ diffity agent reply <id> --body "<text>"
```
If a `thread-id` argument was provided, filter to just that thread. The JSON output includes the full comment body, file path, line numbers, and side for each thread.
2. If there are no open threads, tell the user there's nothing to resolve.
3. For each open thread:
3. For each open thread, check the `comments` array and the `author.type` field (`"user"` or `"agent"`) on each comment:
a. **Skip** general comments (filePath `__general__`) — these are summaries, not actionable code changes.
b. **Skip** threads where the comment body starts with an explicit `[question]` or `[nit]` tag prefix — these don't require code changes. Tell the user you skipped them and why.
- **Important:** Only skip if the comment body literally begins with `[question]` or `[nit]`. Do NOT skip comments just because they are phrased as a question (e.g. "should we add X?" or "can we rename this?"). Comments phrased as questions without explicit tags are suggestions — treat them as actionable requests.
c. Read the comment body from the JSON output and understand what change is requested. Interpret the intent:
b. **Skip** threads where the last comment is an agent reply that asks the user a question (e.g. "Could you clarify...?") and the user hasn't responded yet — the agent is waiting for user input. Still process threads where the agent left the original comment (code suggestion, review feedback, etc.) — those are actionable.
c. **`[nit]` comments** — these are minor suggestions but still actionable. Resolve them like any other comment.
d. **`[question]` comments** (from the user) — read the question, examine the relevant code, and reply with an answer:
```
diffity agent reply <thread-id> --body "Your answer here"
```
Then resolve the thread with a summary of your answer.
e. Comments phrased as questions without an explicit `[question]` tag (e.g. "should we add X?" or "can we rename this?") are suggestions — treat them as actionable requests and make the change.
f. Read the comment body from the JSON output and understand what change is requested. Interpret the intent:
- If the comment suggests a code change, make the change.
- If the comment suggests adding documentation, add or update the relevant docs.
- If the comment asks a question that implies an action (e.g. "should we add X?"), treat it as a request to do that action.
@@ -54,8 +60,8 @@ diffity agent reply <id> --body "<text>"
```
diffity agent reply <thread-id> --body "Could you clarify what change you'd like here?"
```
d. Read the relevant source file to understand the full context around the commented lines, then make the requested change using the Edit tool.
e. After making the change, resolve the thread with a summary:
g. Read the relevant source file to understand the full context around the commented lines, then make the requested change using the Edit tool.
h. After making the change, resolve the thread with a summary:
```
diffity agent resolve <thread-id> --summary "Fixed: <brief description of what was changed>"
```
skills/diffity-review/SKILL.md
+43 -12
View File
@@ -32,11 +32,23 @@ diffity agent reply <id> --body "<text>"
## Prerequisites
1. Check that `diffity` is available: run `which diffity`. If not found, install it with `npm install -g diffity`.
2. Check that a review session exists: run `diffity agent list`. If this fails with "No active review session", tell the user to start diffity first (e.g. `diffity` or **/diffity-start**).
## Instructions
1. Read the current diff using `git diff`. Check `.diffity/current-session` to determine which ref is active.
### Step 1: Ensure diffity is running (without opening browser)
The review needs a running session to add comments to, but we don't want to open the browser until comments are ready.
1. Run `diffity list --json` to check if diffity is already running for this repo.
2. If already running, note the port and continue to Step 2.
3. If not running, start it in the background **without opening the browser**:
- Command: `diffity --no-open`
- Use Bash tool with `run_in_background: true`
- Wait 2 seconds, then verify with `diffity list --json` and note the port.
### Step 2: Review the diff
1. Read the current diff using `git diff`. If diffity was started with a specific ref, use the appropriate git diff command.
2. For each changed file, read the **entire file** (not just the diff hunks) to understand the full context. This prevents false positives from missing surrounding code.
3. Analyze the code changes thoroughly. If a `focus` argument was provided, concentrate on that area. Otherwise look for:
- Bugs, logic errors, off-by-one errors
@@ -49,26 +61,45 @@ diffity agent reply <id> --body "<text>"
4. **Only comment on code that was changed in the diff.** Do not flag pre-existing issues in unchanged code — this is a review of the diff, not an audit of the entire file. The only exception is if a change in the diff introduces a bug in combination with existing code.
5. **Prioritize signal over volume.** A clean diff should get a clean review. Do not manufacture findings to appear thorough. If a diff with 5 changed lines only has 1 real issue, leave 1 comment.
6. **Do not repeat the same issue across files.** If the same pattern appears in multiple places, leave one inline comment on the first occurrence and mention it in the general summary instead of commenting on every instance.
7. Categorize each finding with a severity prefix in the comment body:
### Step 3: Leave comments
1. Categorize each finding with a severity prefix in the comment body:
- `[must-fix]` — Bugs, security issues, data loss risks. These must be addressed.
- `[suggestion]` — Improvements that would meaningfully improve the code.
- `[nit]` — Style or preference. Fine to ignore.
- `[question]` — Something unclear that needs clarification from the author.
8. For each finding, leave a comment using:
2. For each finding, leave an inline comment using:
```
diffity agent comment --file <path> --line <n> [--end-line <n>] [--side new] --body "<comment>"
```
- Use `--side new` (default) for comments on added/modified code
- Use `--side old` for comments on removed code
- Use `--end-line` when the issue spans multiple lines
- Be specific and actionable in your comments
9. After leaving all inline comments, write a general comment that summarizes your overall assessment of the diff. This should cover:
- Overall quality verdict (e.g. "Looks good with minor issues" or "Needs significant changes before merging")
- Cross-cutting concerns that don't belong on any single line (architecture, naming consistency across files, missing tests, etc.)
- A count of findings by severity (e.g. "2 must-fix, 3 suggestions, 1 nit")
- Be specific and actionable — lead with the point, skip filler
3. After leaving all inline comments, write a general comment summarizing the diff. **Do not use severity prefixes in the general comment** — prefixes are only for inline findings. The general comment should:
- **Lead with the verdict** (e.g. "LGTM", "Needs changes before merging", "Looks good with minor issues")
- Use separate paragraphs or bullets when covering multiple points — no walls of text
- Mention cross-cutting concerns that don't belong on any single line (architecture, naming consistency, missing tests, etc.)
- Include a count of findings by severity if there are any (e.g. "1 must-fix, 2 suggestions")
- Be direct and concise — no compliments, no filler, no narrating what the code does
```
diffity agent general-comment --body "<overall review summary>"
```
If there are no inline findings, still leave a general comment with your assessment (e.g. "Clean diff — no issues found").
10. Run `diffity agent list` to confirm all comments were created.
11. Tell the user to check the browser — comments will appear within 2 seconds via polling.
If there are no inline findings, still leave a general comment with your assessment (e.g. "LGTM — clean diff, no issues found").
### Step 4: Open the browser
1. Run `diffity agent list` to confirm all comments were created.
2. Open the browser now that comments are ready:
```
open http://localhost:<port>
```
Use the port from Step 1.
3. Tell the user the review is ready and they can check the browser. Example:
> Review complete — check your browser.
>
> Found: 2 must-fix, 3 suggestions, 1 nit
>
> When you're ready, run **/diffity-resolve** to fix them.
skills/diffity-start/SKILL.md
-29
View File
@@ -1,29 +0,0 @@
---
name: diffity-start
description: >-
Start the diffity diff viewer server for the current working tree or staged
changes
user-invocable: true
---
# Diffity Start Skill
You are starting the diffity diff viewer so the user can see their changes in the browser.
## Instructions
1. Check that `diffity` is available: run `which diffity`. If not found, install it with `npm install -g diffity`.
2. Check if diffity is already running for this repo: run `diffity list --json`. If it shows an entry for this repo, diffity is already running — skip to step 5.
3. Start the server using the Bash tool with `run_in_background: true`:
- Command: `diffity`
- Do NOT use `&` or `--quiet` — let the Bash tool handle backgrounding
- The browser will open automatically and the session is auto-created on startup
- If diffity detects an existing instance for this repo, it will reuse it automatically
4. Wait 2 seconds, then verify it's running with `diffity list`.
5. Tell the user diffity is running and show them what they can do next. Keep it short — don't show session IDs, hashes, or other internals. Example:
> Diffity is running — check your browser.
>
> When you're ready:
> - Leave comments on the diff in your browser, then run **/diffity-resolve** to fix them
> - Or run **/diffity-review** to get an AI code review