@dennisrongo/skills 0.1.0

package/skills/pr-review/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: pr-review
+description: Conduct a thorough, structured code review of a local branch, grouped by task number (#NNN) referenced in commit messages. Use this skill whenever the user asks to review a PR, asks for feedback on a diff or branch, mentions "review my changes", or pastes code asking what could be improved. Auto-detects all tasks on the branch and produces one verdict per task. Covers correctness, design, tests, security, performance, and readability in that priority order.
+---
+
+# Pull Request Review
+
+A structured approach to reviewing local branch work that catches real issues without nitpicking style. Reviews are scoped per task (e.g. `#123`) so each unit of work gets its own verdict.
+
+## Assumptions
+
+- Work happens on a feature branch off `develop` (git-flow style). If a repo uses a different base, substitute accordingly.
+- The branch carries one or more `#NNN` task references in its commit messages — typically one task per branch, occasionally several when work is naturally bundled.
+- The review runs against the currently checked-out branch.
+
+## Priority order
+
+Review in this order — earlier categories matter more, and finding issues there often makes later ones moot:
+
+1. **Correctness** — does it do what it claims?
+2. **Design** — is the approach sound? Will it cause problems later?
+3. **Tests** — are behaviors covered? Are tests meaningful or just for coverage?
+4. **Security** — any new attack surface? Input validation? Secrets?
+5. **Performance** — obvious inefficiencies? Will it scale?
+6. **Readability** — naming, structure, comments where non-obvious.
+7. **Style** — only mention if the project lacks a formatter/linter.
+
+## Workflow
+
+1. **Refresh the base branch ref.** Run `git fetch origin develop` so the diff baseline is current. Do **not** `git pull` or check out `develop` — fetching updates `origin/develop` without touching the working tree or the local `develop` branch. If there's no `origin` remote, fall back to local `develop` and note it in the output.
+2. **List commits on the branch.** Run `git log origin/develop..HEAD --format="%h %s"` (substitute the actual base branch if not `develop`). This is the universe of work to review.
+3. **Group commits by task number.** Scan each subject and body for `#NNN` tokens (use `git log origin/develop..HEAD --format="%H%n%B%n---"` to see full messages). Bucket commits by task:
+   - A commit referencing `#123` belongs to task `#123`.
+   - A commit referencing multiple tasks belongs to each (review it once, note it in both verdicts).
+   - A commit with no `#NNN` goes into an `unscoped` bucket — still review it, but flag the missing task reference.
+4. **For each task, read its intent first.** What is `#123` trying to accomplish? Infer from the commit subjects/bodies in that bucket. If intent is unclear, ask the user before reviewing — "is the code correct" is unanswerable without it.
+5. **Get the per-task diff.** For each task, view its commits with `git show <sha>` per commit, or `git diff <first>^..<last>` if the commits are contiguous. Don't merge tasks into one combined diff — keep them scoped.
+6. **Skim each task once, top to bottom.** Get a mental model of what changed before commenting on specifics.
+7. **Re-read each task with the priority list in mind.** Note issues as you go.
+8. **Look at the tests in each task.** Do they test the new behavior or just exercise the new lines?
+9. **Check what's *not* in each task's diff.** Missing error handling, missing tests for edge cases, missing migration for a schema change.
+
+## How to phrase feedback
+
+Categorize each comment so the author knows what's required vs optional:
+
+- **`blocking`** — must fix before merge (bug, security issue, broken contract)
+- **`suggestion`** — would improve the code, author can take or leave
+- **`question`** — author may know something you don't; ask before asserting
+- **`nit`** — minor style/preference; should not block merge
+- **`praise`** — something done well, worth calling out
+
+Lead with the *why*, not just the *what*. "This will deadlock if two callers hit it simultaneously" is more useful than "use a lock here".
+
+## What to look for
+
+### Correctness
+- Off-by-one errors in loops and slicing
+- Null/undefined handling at boundaries
+- Concurrent access without synchronization
+- Error paths that swallow exceptions silently
+- Default values that change behavior unexpectedly
+
+### Design
+- New abstractions that don't pay for themselves
+- Tight coupling that will be painful to undo
+- Duplication that should be unified (or unification that should be duplication)
+- Public API changes that aren't backwards-compatible
+- State that should live elsewhere
+
+### Tests
+- Tests that pass even when the code is broken (assertion-free, mocked too aggressively)
+- Missing edge cases: empty inputs, max sizes, unicode, timezones
+- Tests that are flaky by design (timing, ordering, network)
+
+### Security
+- User input flowing into shell, SQL, or HTML without escaping
+- Secrets in code, logs, or error messages
+- Authn/authz checks missing on new endpoints
+- Crypto: hand-rolled, weak algorithms, hardcoded keys/IVs
+
+### Performance
+- N+1 queries in loops
+- Unbounded memory growth (caches without eviction, accumulating arrays)
+- Synchronous I/O in hot paths
+- Repeated work that could be hoisted out of a loop
+
+## Output format
+
+Produce one section per task, with comments grouped by file and line inside each. Each task gets its own verdict — tasks are independent units of work and should be approvable or blockable on their own.
+
+```
+## #123 — <inferred or stated task intent>
+
+Commits:
+- <sha> <subject>
+- <sha> <subject>
+
+Verdict: Approve with suggestions / Request changes / Comment
+
+Strengths:
+- ...
+
+Blockers:
+- ...
+
+Suggestions:
+- ...
+
+---
+
+## #124 — ...
+
+(same structure)
+
+---
+
+## unscoped — commits without a #NNN reference
+
+(same structure; also flag the missing task reference as a blocker or nit depending on project convention)
+```
+
+End with a one-line roll-up: e.g. `Overall: 2 approve, 1 request changes, 1 unscoped`.
+
+## Anti-patterns
+
+- ❌ Reviewing without understanding the goal of the change
+- ❌ Reflexively requesting tests without saying what they should cover
+- ❌ Drive-by style nits that derail the substantive discussion
+- ❌ "I would have done it differently" without a concrete reason
+- ❌ Collapsing multiple tasks into one verdict — each `#NNN` is independent and should stand or fall on its own
+- ❌ Silently ignoring commits with no task reference — surface them in the `unscoped` bucket

package/skills/write-a-skill/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: write-a-skill
+description: Create a new Claude Code skill — scaffolds a properly-structured `SKILL.md` (with YAML frontmatter, trigger-rich description, workflow, examples, anti-patterns), drops it in the right location (this library's `skills/`, the project's `.claude/skills/`, or the global `~/.claude/skills/`), and — when adding to the `dennisrongo/claude-skills` library — also updates the README table. Use this skill whenever the user says "create a skill", "write a skill", "new skill", "add a skill", "make a skill", "/write-a-skill", or pastes a SKILL.md URL and asks for something similar — even if they don't explicitly say "skill author".
+---
+
+# Write a Skill
+
+Author a new Claude Code skill that Claude will actually trigger when it should. The description field is the **only** thing Claude sees when deciding whether to load the skill, so most of the effort goes into making that field specific and trigger-rich — not into the body.
+
+## When to use this skill
+
+- The user says any of: "create a skill", "write a skill", "new skill", "add a skill", "make a skill", "scaffold a skill", "/write-a-skill".
+- The user pastes a URL to an existing `SKILL.md` (e.g. a GitHub link to someone else's skill) and asks for "one like this" / "similar to this" / "based on this".
+- The user describes a recurring workflow ("every time I do X, I want you to Y") that should be packaged as a skill rather than dropped into `CLAUDE.md`.
+
+Do **not** auto-trigger when the user is just *discussing* skills, asking how skills work in general, or editing an existing skill's body. Wait for an explicit author-a-new-skill cue.
+
+## Detect the target location first
+
+Before scaffolding anything, figure out where the new skill belongs. The CWD usually tells you:
+
+| Signal | Target |
+|---|---|
+| CWD is the `dennisrongo/claude-skills` repo (has `bin/claude-skills.js` + `skills/_template/`) | `skills/<name>/SKILL.md` in this library — and update README table |
+| CWD is some other project, user says "project skill" / "for this repo" | `./.claude/skills/<name>/SKILL.md` |
+| User says "global" / "every project" / "all my sessions" | `~/.claude/skills/<name>/SKILL.md` |
+| Ambiguous | Ask once with `AskUserQuestion` — don't guess |
+
+If you're in the library repo, prefer that destination — the user can install it elsewhere later with `claude-skills install <name>`.
+
+## Workflow
+
+1. **Confirm the trigger.** Restate in one sentence what the skill is for and the phrases that should trigger it. Bail and ask if either is fuzzy.
+2. **Gather requirements** with `AskUserQuestion` (one question at a time, max 3–4 total). Pull from this menu — skip ones already answered:
+   - **Trigger phrases** — what does the user actually say when they want this? Collect 3+ concrete phrases / commands.
+   - **Inputs** — does Claude need a file? A URL? Just a free-form description?
+   - **Outputs** — files written, commands run, a structured response, a PR?
+   - **Scripts / references** — does the skill need bundled executable helpers or long reference docs, or is plain `SKILL.md` enough?
+   - **Anti-patterns** — what should Claude explicitly *not* do? (Most-overlooked input — ask for it.)
+3. **Pick the name.** kebab-case, 2–4 words, matches what the user says. Use the leading-verb form when the skill *does* something (`write-a-skill`, `diagnose`, `handoff`); use the noun form when it *defines* something (`conventional-commits`, `pr-review`).
+4. **Check for collisions.** `ls` the target skills directory. If a skill with the same name exists, stop and ask the user whether to overwrite, rename, or extend the existing one.
+5. **Scaffold from `_template/`** if it exists in the destination, otherwise from the template embedded below. Create the parent directory if missing.
+6. **Draft the SKILL.md** using the section structure in [Required structure](#required-structure). Write the description LAST — it depends on the body.
+7. **Write the description carefully** — see [Writing the description](#writing-the-description). This is the single highest-leverage part of the file.
+8. **Self-review** against the [Review checklist](#review-checklist) before showing the user.
+9. **If targeting the library repo, update `README.md`** — add a row to the skills table in alphabetical order with a one-paragraph "what it does" hook matching the existing voice. Verify the row by re-reading the file after the edit.
+10. **Report back**: skill path, the description verbatim, and the install command the user can run on other machines (`npx --yes github:dennisrongo/claude-skills install <name>` for library skills).
+
+## Required structure
+
+```markdown
+---
+name: <kebab-case-name>
+description: <see "Writing the description">
+---
+
+# <Title Case Name>
+
+<1–2 sentence elevator pitch — what this skill does and why it exists.>
+
+## When to use this skill
+
+- <Concrete trigger phrase or condition>
+- <Concrete trigger phrase or condition>
+- <Concrete trigger phrase or condition>
+
+<Optional: "Do **not** auto-trigger when …" — explicit non-triggers if the skill has near-neighbors.>
+
+## Workflow
+
+1. <Imperative step>
+2. <Imperative step>
+3. <Imperative step>
+
+## Examples
+
+### Example 1: <scenario name>
+
+**User:** "<exact phrasing>"
+
+**Claude:** <what the ideal behavior looks like — 1–3 bullets, not a full transcript>
+
+## Anti-patterns
+
+- ❌ <Thing Claude would plausibly do that's wrong>
+- ❌ <Thing Claude would plausibly do that's wrong>
+- ✅ <The right thing, contrasted>
+
+## Notes
+
+<Caveats, edge cases, things that only matter occasionally. Optional.>
+```
+
+Skip sections that would be empty. Reorder only if there's a real reason. Keep the file under ~150 lines — split into `references/` if a section grows past that.
+
+## Writing the description
+
+The description is the **only** field Claude reads when deciding whether to consult the skill. Optimize it for that decision:
+
+- **First sentence** — what the skill produces or does, named concretely (not "helps with X").
+- **Second sentence** — `Use this skill whenever the user says "<phrase 1>", "<phrase 2>", "<phrase 3>", … — even if they don't explicitly say "<skill name>".`
+- **Third sentence (optional)** — explicit non-triggers if there's a near-neighbor skill it could be confused with.
+- **Length** — max 1024 chars. Use the budget for trigger phrases, not adjectives.
+- **Voice** — third person, present tense.
+
+**Good:**
+
+> Capture a session hand-off so work can resume cleanly in a new Claude session before context runs out. Writes a canonical dated Markdown file (objective, progress, decisions, files, open issues, and a ready-to-paste "Next Session Prompt") AND a lightweight project-memory pointer to it. Use this skill whenever the user says "/handoff", "hand off", "handoff", "save context", "preserve context", "running out of context", …
+
+**Bad:**
+
+> Helps the user create handoffs.
+
+(The bad one tells Claude nothing about *when* — it'll under-trigger and the skill effectively doesn't exist.)
+
+The most common failure mode is **under-triggering** (Claude doesn't load the skill when it should). Err on the side of *more* trigger phrases — three is the floor, not the ceiling.
+
+## When to add scripts or reference files
+
+Default to a single `SKILL.md`. Only escalate when:
+
+- **Scripts** (`scripts/*.{js,sh,py}`) — the operation is deterministic and Claude would otherwise regenerate the same code each call (validators, formatters, scaffolders). Scripts save tokens and improve reliability.
+- **References** (`references/*.md`) — long lookup tables, exhaustive option lists, or domain glossaries that Claude only needs occasionally. Link from `SKILL.md` rather than inlining.
+
+If you do add either, mention them by relative path from the `SKILL.md` body so Claude knows they exist.
+
+## Review checklist
+
+Before showing the draft to the user:
+
+- [ ] `name:` matches the directory name exactly
+- [ ] `description:` starts with what the skill does, then "Use this skill whenever the user says …"
+- [ ] Description includes ≥ 3 concrete trigger phrases / commands
+- [ ] Description ends with "— even if they don't explicitly say …" escape hatch
+- [ ] `## When to use this skill` lists the same triggers as bullets (so the body reinforces the description)
+- [ ] Workflow steps are imperative and verifiable, not vibes ("Verify X exists", not "Be careful")
+- [ ] At least one concrete example
+- [ ] Anti-patterns section names plausible wrong behaviors, not strawmen
+- [ ] No time-sensitive info (specific dates, "as of 2026", model version numbers) unless load-bearing
+- [ ] File is under ~150 lines; longer content is split into `references/`
+- [ ] If targeting the library repo, README table row is added in alphabetical order
+
+## Examples
+
+### Example 1: Library skill from scratch
+
+**User:** "/write-a-skill — I want one that runs eslint --fix and stages the changes whenever I say 'lint this'"
+
+**Claude:**
+1. Confirms the trigger phrases ("lint this", "fix lint", "/lint-and-stage") via `AskUserQuestion`.
+2. Names it `lint-and-stage`, scaffolds `skills/lint-and-stage/SKILL.md` from `_template/`.
+3. Fills in the workflow (run `eslint --fix`, run `git add -u`, summarize changed files).
+4. Writes a description with all three trigger phrases.
+5. Adds a row to `README.md` skills table.
+6. Reports the path and the install command.
+
+### Example 2: "One like this" from a pasted URL
+
+**User:** "Create a skill like https://github.com/mattpocock/skills/blob/main/skills/productivity/write-a-skill/SKILL.md but for our repo"
+
+**Claude:**
+1. Fetches the URL, reads the source skill.
+2. Identifies what to keep (process, description requirements, checklist) and what to adapt (directory structure, README updates, this repo's voice).
+3. Scaffolds the adapted version, gets user sign-off, writes the file.
+
+### Example 3: Project-scoped skill
+
+**User:** "Add a skill just for this repo that reminds me to run `pnpm changeset` before any feat/fix commit"
+
+**Claude:**
+1. Detects CWD is not the library repo → targets `./.claude/skills/changeset-reminder/SKILL.md`.
+2. Creates `.claude/skills/` if missing.
+3. Drafts a tiny skill keyed on `git commit` / "commit" triggers that checks for a changeset file and warns if missing.
+4. Does **not** touch the library README.
+
+## Anti-patterns
+
+- ❌ Writing a vague description like "Helps with commits." — Claude won't trigger it. Always include explicit trigger phrases.
+- ❌ Inventing trigger phrases the user didn't confirm — ask, don't guess.
+- ❌ Padding `SKILL.md` with motivational prose. Every line should change Claude's behavior; if removing it changes nothing, cut it.
+- ❌ Hard-coding model names, package versions, or dates that will rot. Resolve at runtime when possible.
+- ❌ Putting executable behavior in `SKILL.md` prose when a 10-line script would be deterministic and cheaper.
+- ❌ For library skills: drafting the SKILL.md but forgetting to update the README table — the skill is invisible to anyone browsing the repo.
+- ❌ Overwriting an existing skill without confirmation when the names collide.
+- ✅ Trigger-rich description, imperative workflow, one concrete example, explicit anti-patterns, under 150 lines.
+
+## Notes
+
+- The library repo's `_template/SKILL.md` is the canonical starting point when working inside `dennisrongo/claude-skills`. The `_` prefix excludes it from installation, so it's safe to leave as-is.
+- When adapting a skill from an external source (e.g. another GitHub repo), credit the inspiration in a `## Notes` line — don't copy verbatim if the voice doesn't match this repo's existing skills.
+- Skills installed to `~/.claude/skills/` are picked up by every Claude Code session globally; `.claude/skills/` in a project is scoped to that repo. The library repo's `skills/<name>/` is the *source* — not where Claude reads from at runtime.