/addvalue — Find and ship real value
Purpose
Review a target carefully (remote Git repo, local folder, library, CLI, UI,
docs site, or product surface) and produce a ranked plan of improvements that
actually help users or maintainers. Then optionally implement the top item.
This is not “open 20 tiny PRs.” Prefer one hard, reviewable change over many shallow ones.
Triggers
/addvalue [path|owner/repo|.]
- “add value”, “how can this be improved”, “inspiring updates”, “what should we build”
- Track B contribution hunting when quality > volume
Partners (optional)
| Partner |
When |
How |
| This agent (default) |
Always |
Full review + implement |
| Ollama Cloud GLM |
User says /addvalue --ollama or /ollama mid-pass |
Load ollama skill; one high-reasoning plan call; execute or merge with your plan |
| Local Ollama |
User says /addvalue --local or /local |
Load local skill; use as second opinion only |
| agy / agent CLIs |
User names a CLI (agy, hermes, project scripts) |
Prefer project engines over inventing parallel tools; pass paths not huge file dumps |
Paid/cloud partners: honor the user’s Paid Models — Ask First rule. /ollama is standing approval for one GLM planner call on that turn. Ask before other paid APIs.
Hard rules
- Scope lock — name the target and one primary outcome before editing.
- Read before invent — README, CONTRIBUTING, AI_POLICY, recent issues/PRs, architecture entrypoints. No drive-by.
- Value > vanity — reject star-farm, typo-only, comment-churn, duplicate open PRs.
- Hard + inspirational bar (non-negotiable) — Prefer work a sharp maintainer would not clear in an afternoon. Reject “correct but small” DX/docs/pattern-rebase fixes unless the user explicitly lowers the bar. Winning work should be either:
- Hard: races, protocol/semantics bugs, cross-layer design, subtle correctness with non-obvious tests, or
- Inspirational: a capability users invent workarounds for; something that changes what the tool can do, not just how you debug it.
- Human gate for upstream — for third-party GitHub PRs, stop at draft +
Take OWNER/REPO#N unless already approved.
- Reproduce / accept — bugs need a failing test or exact repro; features need acceptance checks from issues/docs/users.
- Verify with evidence — project’s own test/lint/build; report commands + exit codes.
- No fake done — ledger or session note: what changed, how verified, what remains.
Explicit rejects (fail the bar)
- Explain/debug CLIs for existing behavior
- Single-file pattern/rebase fixes with clear recipes
- Good-first-issue labeled work unless it hides a deep bug
- Anything a competent maintainer would ship between meetings
- Competing open PRs / already-assigned maintainer work you cannot uniquely advance
Workflow
Copy and track:
ADDVALUE Progress:
- [ ] 1. Target + intent
- [ ] 2. Map the system
- [ ] 3. Signal scan (issues, users, friction)
- [ ] 4. Opportunity bank + score
- [ ] 5. Pick ONE winner
- [ ] 6. Plan (smallest correct change)
- [ ] 7. Implement + verify (if in scope)
- [ ] 8. Report
1. Target + intent
Identify:
| Field |
Example |
| Target |
pypa/hatch, ~/projects/foo, . |
| Kind |
library / app / CLI / docs / monorepo / playbook |
| Intent |
contribute upstream / improve own product / invent roadmap |
| Constraint |
max 1 PR, no UI, Windows-only, etc. |
If target missing, default to current workspace root.
2. Map the system
Spend tokens on structure, not trivia:
- Entry points (CLI,
main, routes, pyproject scripts)
- Core domain modules (where value lives)
- Test/verify path (
hatch test, pytest, npm test, …)
- Contribution/AI policy if present
- Recent release notes / changelog tone
For remote repos: gh repo view, gh issue list, gh pr list, clone only when implementing.
For local / non-git projects: same mapping via filesystem + run scripts; VCS optional.
3. Signal scan
Gather friction from:
- Open issues (bugs and enhancements; “help wanted”; milestone)
- Closed-but-painful issues / “won’t fix” that aging may reopen
- Docs vs reality (README steps that fail)
- Error paths, Windows/macOS gaps, silent failures
- Competitor / sibling tools (what users already expect)
- Your own dry-run of the happy path
Optional partner pass: ask Ollama Cloud (/ollama) for a ranked opportunity list given only paths + issue titles (not full dumps).
4. Opportunity bank + score
Write 5–12 candidates. Score each 1–5 on:
| Axis |
High score means |
| User impact |
Pain or desire is real and frequent |
| Leverage |
One change unlocks many workflows |
| Fit |
Matches project style and maintainer taste |
| Feasibility |
Clear repro/acceptance; you can verify |
| Novelty |
Not already PR’d / not trivial |
| Hardness |
Would take a sharp maintainer >1 day, or needs deep domain/design |
| Inspiration |
Users will say “finally” — new capability, not polish |
| Risk |
(invert) low chance of breaking core contracts |
Winner score = impact + leverage + fit + feasibility + novelty + hardness + inspiration − risk.
Floor: reject candidates with hardness < 4 and inspiration < 4 unless the user asked for a small win.
Discard: duplicates of open PRs, policy violations, scope bombs, “rewrite the world.”
5. Pick ONE winner
State in one paragraph:
- Problem / missing capability
- Who benefits
- Why this beats the runners-up
- Out of scope for this pass
6. Plan
Minimum plan:
- Repro or acceptance checks
- Files likely touched
- Smallest design that matches existing patterns
- Verify commands
- Upstream gate (if any)
Use Plan mode when trade-offs are large; otherwise implement.
7. Implement
- Smallest diff; match project style
- Tests first when fixing bugs
- No
Co-authored-by LLM on third-party PRs
- Disclose AI if the project’s CONTRIBUTING requires it
- Stop before
gh pr create unless user said Take OWNER/REPO#N
8. Report
## ADDVALUE: <target>
**Winner:** <title> (<issue/url or local>)
**Why:** <one line>
### Also considered
- ...
### Done / next
- Implemented: ...
- Verified: `<cmd>` → exit N
- Blocked / gate: ...
Domains the review must consider
Do not only hunt bugs. Explicitly scan:
| Lens |
Questions |
| Correctness |
Silent data loss? Wrong defaults? Race? |
| Features |
What’s half-built? What’s documented but missing? |
| UX / DX |
Confusing errors? Missing --help examples? Slow feedback? |
| Perf |
Hot paths? Accidental O(n²)? |
| Security / safety |
Trust boundaries? Path traversal? Secret leakage? |
| Platform |
Windows path/newline/env gaps? |
| Docs |
Lies, missing recipes, no migration notes |
| Inspiration |
What would make a power user say “finally”? |
Anti-patterns
- Mass AI PRs / typo farms / readme churn for graph greens
- Picking an issue that already has an active PR
- “Improvements” that fight the maintainer’s stated design
- Partner model dumps that you paste as the PR body unread
- Claiming value without verify evidence
- Opening a third upstream PR while two are already waiting (unless user overrides)
Compose with other modes
| Need |
Use |
| Contract before multi-session work |
/goal |
| Autonomous until criteria |
/goal-loop |
| Quality polish after implement |
/better |
| Many unique variants |
/scale |
| Cloud planner partner |
/ollama inside or after /addvalue |
| Recurring re-scan |
/loop 1d /addvalue . |
Progressive disclosure
- Scoring templates + output schemas → reference.md
- Worked examples → examples.md
Installation paths
- Skill: this folder's
SKILL.md
- Command: optional
/addvalue command file in the host agent
1---
2name: addvalue
3description: "Deep-reviews a GitHub repo, local project, CLI, docs, or product for high-leverage bugs, features, UX gaps, and inspiring upgrades—not typo farms. Use when the user says /addvalue, add value, find improvements, or what to build next. Do not use for a /better polish pass, a reproduce-then-fix hunt (bug-hunter), or mass good-first-issue PRs."
4metadata:
5 source: https://skillmd.com/skills/kayforkind/addvalue
6---
7
8# /addvalue — Find and ship real value
9
10## Purpose
11
12Review a **target** carefully (remote Git repo, local folder, library, CLI, UI,
13docs site, or product surface) and produce a ranked plan of improvements that
14actually help users or maintainers. Then optionally implement the top item.
15
16This is **not** “open 20 tiny PRs.” Prefer one hard, reviewable change over many shallow ones.
17
18## Triggers
19
20- `/addvalue [path|owner/repo|.]`
21- “add value”, “how can this be improved”, “inspiring updates”, “what should we build”
22- Track B contribution hunting when quality > volume
23
24## Partners (optional)
25
26| Partner | When | How |
27|---------|------|-----|
28| **This agent (default)** | Always | Full review + implement |
29| **Ollama Cloud GLM** | User says `/addvalue --ollama` or `/ollama` mid-pass | Load `ollama` skill; one high-reasoning plan call; execute or merge with your plan |
30| **Local Ollama** | User says `/addvalue --local` or `/local` | Load local skill; use as second opinion only |
31| **agy / agent CLIs** | User names a CLI (`agy`, `hermes`, project scripts) | Prefer project engines over inventing parallel tools; pass paths not huge file dumps |
32
33Paid/cloud partners: honor the user’s **Paid Models — Ask First** rule. `/ollama` is standing approval for one GLM planner call on that turn. Ask before other paid APIs.
34
35## Hard rules
36
371. **Scope lock** — name the target and one primary outcome before editing.
382. **Read before invent** — README, CONTRIBUTING, AI_POLICY, recent issues/PRs, architecture entrypoints. No drive-by.
393. **Value > vanity** — reject star-farm, typo-only, comment-churn, duplicate open PRs.
404. **Hard + inspirational bar (non-negotiable)** — Prefer work a sharp maintainer would **not** clear in an afternoon. Reject “correct but small” DX/docs/pattern-rebase fixes unless the user explicitly lowers the bar. Winning work should be either:
41 - **Hard:** races, protocol/semantics bugs, cross-layer design, subtle correctness with non-obvious tests, or
42 - **Inspirational:** a capability users invent workarounds for; something that changes what the tool can do, not just how you debug it.
435. **Human gate for upstream** — for third-party GitHub PRs, stop at draft + `Take OWNER/REPO#N` unless already approved.
446. **Reproduce / accept** — bugs need a failing test or exact repro; features need acceptance checks from issues/docs/users.
457. **Verify with evidence** — project’s own test/lint/build; report commands + exit codes.
468. **No fake done** — ledger or session note: what changed, how verified, what remains.
47
48### Explicit rejects (fail the bar)
49
50- Explain/debug CLIs for existing behavior
51- Single-file pattern/rebase fixes with clear recipes
52- Good-first-issue labeled work unless it hides a deep bug
53- Anything a competent maintainer would ship between meetings
54- Competing open PRs / already-assigned maintainer work you cannot uniquely advance
55
56## Workflow
57
58Copy and track:
59
60```
61ADDVALUE Progress:
62- [ ] 1. Target + intent
63- [ ] 2. Map the system
64- [ ] 3. Signal scan (issues, users, friction)
65- [ ] 4. Opportunity bank + score
66- [ ] 5. Pick ONE winner
67- [ ] 6. Plan (smallest correct change)
68- [ ] 7. Implement + verify (if in scope)
69- [ ] 8. Report
70```
71
72### 1. Target + intent
73
74Identify:
75
76| Field | Example |
77|-------|---------|
78| Target | `pypa/hatch`, `~/projects/foo`, `.` |
79| Kind | library / app / CLI / docs / monorepo / playbook |
80| Intent | contribute upstream / improve own product / invent roadmap |
81| Constraint | max 1 PR, no UI, Windows-only, etc. |
82
83If target missing, default to **current workspace root**.
84
85### 2. Map the system
86
87Spend tokens on structure, not trivia:
88
89- Entry points (CLI, `main`, routes, `pyproject` scripts)
90- Core domain modules (where value lives)
91- Test/verify path (`hatch test`, `pytest`, `npm test`, …)
92- Contribution/AI policy if present
93- Recent release notes / changelog tone
94
95For remote repos: `gh repo view`, `gh issue list`, `gh pr list`, clone only when implementing.
96
97For **local / non-git** projects: same mapping via filesystem + run scripts; VCS optional.
98
99### 3. Signal scan
100
101Gather friction from:
102
103- Open issues (bugs **and** enhancements; “help wanted”; milestone)
104- Closed-but-painful issues / “won’t fix” that aging may reopen
105- Docs vs reality (README steps that fail)
106- Error paths, Windows/macOS gaps, silent failures
107- Competitor / sibling tools (what users already expect)
108- Your own dry-run of the happy path
109
110Optional partner pass: ask Ollama Cloud (`/ollama`) for a **ranked opportunity list** given only paths + issue titles (not full dumps).
111
112### 4. Opportunity bank + score
113
114Write 5–12 candidates. Score each 1–5 on:
115
116| Axis | High score means |
117|------|------------------|
118| **User impact** | Pain or desire is real and frequent |
119| **Leverage** | One change unlocks many workflows |
120| **Fit** | Matches project style and maintainer taste |
121| **Feasibility** | Clear repro/acceptance; you can verify |
122| **Novelty** | Not already PR’d / not trivial |
123| **Hardness** | Would take a sharp maintainer >1 day, or needs deep domain/design |
124| **Inspiration** | Users will say “finally” — new capability, not polish |
125| **Risk** | (invert) low chance of breaking core contracts |
126
127**Winner score** = impact + leverage + fit + feasibility + novelty + hardness + inspiration − risk.
128
129**Floor:** reject candidates with hardness < 4 **and** inspiration < 4 unless the user asked for a small win.
130
131Discard: duplicates of open PRs, policy violations, scope bombs, “rewrite the world.”
132
133### 5. Pick ONE winner
134
135State in one paragraph:
136
137- Problem / missing capability
138- Who benefits
139- Why this beats the runners-up
140- Out of scope for this pass
141
142### 6. Plan
143
144Minimum plan:
145
1461. Repro or acceptance checks
1472. Files likely touched
1483. Smallest design that matches existing patterns
1494. Verify commands
1505. Upstream gate (if any)
151
152Use Plan mode when trade-offs are large; otherwise implement.
153
154### 7. Implement
155
156- Smallest diff; match project style
157- Tests first when fixing bugs
158- No `Co-authored-by` LLM on third-party PRs
159- Disclose AI if the project’s CONTRIBUTING requires it
160- Stop before `gh pr create` unless user said `Take OWNER/REPO#N`
161
162### 8. Report
163
164```markdown
165## ADDVALUE: <target>
166
167**Winner:** <title> (<issue/url or local>)
168**Why:** <one line>
169
170### Also considered
171- ...
172
173### Done / next
174- Implemented: ...
175- Verified: `<cmd>` → exit N
176- Blocked / gate: ...
177```
178
179## Domains the review must consider
180
181Do not only hunt bugs. Explicitly scan:
182
183| Lens | Questions |
184|------|-----------|
185| **Correctness** | Silent data loss? Wrong defaults? Race? |
186| **Features** | What’s half-built? What’s documented but missing? |
187| **UX / DX** | Confusing errors? Missing `--help` examples? Slow feedback? |
188| **Perf** | Hot paths? Accidental O(n²)? |
189| **Security / safety** | Trust boundaries? Path traversal? Secret leakage? |
190| **Platform** | Windows path/newline/env gaps? |
191| **Docs** | Lies, missing recipes, no migration notes |
192| **Inspiration** | What would make a power user say “finally”? |
193
194## Anti-patterns
195
196- Mass AI PRs / typo farms / readme churn for graph greens
197- Picking an issue that already has an active PR
198- “Improvements” that fight the maintainer’s stated design
199- Partner model dumps that you paste as the PR body unread
200- Claiming value without verify evidence
201- Opening a third upstream PR while two are already waiting (unless user overrides)
202
203## Compose with other modes
204
205| Need | Use |
206|------|-----|
207| Contract before multi-session work | `/goal` |
208| Autonomous until criteria | `/goal-loop` |
209| Quality polish after implement | `/better` |
210| Many unique variants | `/scale` |
211| Cloud planner partner | `/ollama` inside or after `/addvalue` |
212| Recurring re-scan | `/loop 1d /addvalue .` |
213
214## Progressive disclosure
215
216- Scoring templates + output schemas → [reference.md](reference.md)
217- Worked examples → [examples.md](examples.md)
218
219## Installation paths
220
221- Skill: this folder's `SKILL.md`
222- Command: optional `/addvalue` command file in the host agent