@dennisrongo/skills 0.1.0

package/lib/remove.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const kleur = require('kleur');
+const { getInstallDir } = require('./paths');
+const { listInstalledSkills } = require('./skills');
+
+/**
+ * Remove one or more installed skills.
+ * @param {string[]} identifiers
+ * @param {object} options - { scope }
+ */
+function remove(identifiers, options) {
+  const { scope = 'global' } = options;
+  const installDir = getInstallDir(scope);
+  const installed = listInstalledSkills(installDir);
+
+  if (identifiers.length === 0) {
+    console.error(kleur.red('Specify at least one skill to remove (or use --all).'));
+    process.exitCode = 1;
+    return;
+  }
+
+  for (const id of identifiers) {
+    const match = installed.find((s) => s.name === id || s.slug === id);
+    if (!match) {
+      console.error(kleur.yellow(`⊘ Not installed: ${id}`));
+      continue;
+    }
+    fs.rmSync(match.dir, { recursive: true, force: true });
+    console.log(kleur.green(`✓ removed`) + `  ${match.name}`);
+  }
+}
+
+function removeAll(options) {
+  const { scope = 'global' } = options;
+  const installDir = getInstallDir(scope);
+  const installed = listInstalledSkills(installDir);
+
+  if (installed.length === 0) {
+    console.log(kleur.yellow('No skills installed.'));
+    return;
+  }
+
+  for (const skill of installed) {
+    fs.rmSync(skill.dir, { recursive: true, force: true });
+    console.log(kleur.green(`✓ removed`) + `  ${skill.name}`);
+  }
+}
+
+module.exports = { remove, removeAll };

package/lib/skills.js

@@ -0,0 +1,121 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { getLibraryDir } = require('./paths');
+
+/**
+ * Parse YAML-ish frontmatter from a SKILL.md.
+ * We only need `name` and `description`, so a tiny parser is fine —
+ * no need to pull in a yaml dependency.
+ */
+function parseFrontmatter(content) {
+  if (!content.startsWith('---')) return {};
+  const end = content.indexOf('\n---', 3);
+  if (end === -1) return {};
+  const block = content.slice(3, end).trim();
+
+  const out = {};
+  let currentKey = null;
+  let buffer = [];
+
+  const flush = () => {
+    if (currentKey) {
+      out[currentKey] = buffer.join(' ').trim().replace(/^["']|["']$/g, '');
+    }
+  };
+
+  for (const rawLine of block.split('\n')) {
+    const line = rawLine.replace(/\r$/, '');
+    const match = line.match(/^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/);
+    if (match) {
+      flush();
+      currentKey = match[1];
+      buffer = [match[2]];
+    } else if (currentKey && line.trim()) {
+      // continuation line for multi-line values
+      buffer.push(line.trim());
+    }
+  }
+  flush();
+  return out;
+}
+
+/**
+ * List all skills bundled in this package's `skills/` directory.
+ * Returns: [{ name, description, dir }]
+ */
+function listLibrarySkills() {
+  const libDir = getLibraryDir();
+  if (!fs.existsSync(libDir)) return [];
+
+  const entries = fs.readdirSync(libDir, { withFileTypes: true });
+  const skills = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name.startsWith('.') || entry.name.startsWith('_')) continue;
+
+    const skillDir = path.join(libDir, entry.name);
+    const skillFile = path.join(skillDir, 'SKILL.md');
+    if (!fs.existsSync(skillFile)) continue;
+
+    const content = fs.readFileSync(skillFile, 'utf8');
+    const fm = parseFrontmatter(content);
+
+    skills.push({
+      name: fm.name || entry.name,
+      description: fm.description || '(no description)',
+      dir: skillDir,
+      slug: entry.name,
+    });
+  }
+
+  return skills.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * List skills installed at a given directory.
+ */
+function listInstalledSkills(installDir) {
+  if (!fs.existsSync(installDir)) return [];
+
+  const entries = fs.readdirSync(installDir, { withFileTypes: true });
+  const skills = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const skillDir = path.join(installDir, entry.name);
+    const skillFile = path.join(skillDir, 'SKILL.md');
+    if (!fs.existsSync(skillFile)) continue;
+
+    const content = fs.readFileSync(skillFile, 'utf8');
+    const fm = parseFrontmatter(content);
+
+    skills.push({
+      name: fm.name || entry.name,
+      description: fm.description || '(no description)',
+      dir: skillDir,
+      slug: entry.name,
+    });
+  }
+
+  return skills.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Find a skill in the library by either its `name` frontmatter or its directory slug.
+ */
+function findLibrarySkill(identifier) {
+  const skills = listLibrarySkills();
+  return skills.find(
+    (s) => s.name === identifier || s.slug === identifier
+  );
+}
+
+module.exports = {
+  parseFrontmatter,
+  listLibrarySkills,
+  listInstalledSkills,
+  findLibrarySkill,
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@dennisrongo/skills",
+  "version": "0.1.0",
+  "description": "A curated, fine-tunable library of Claude Code skills. Install globally or per-project via npx.",
+  "bin": {
+    "claude-skills": "bin/claude-skills.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "skills/",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/cli.test.js test/skills.test.js",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "skills",
+    "anthropic",
+    "ai",
+    "cli"
+  ],
+  "author": "Dennis Rongo",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0",
+    "kleur": "^4.1.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dennisrongo/claude-skills.git"
+  },
+  "homepage": "https://github.com/dennisrongo/claude-skills#readme",
+  "bugs": {
+    "url": "https://github.com/dennisrongo/claude-skills/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/skills/_template/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: my-skill-name
+description: One sentence describing what this skill does AND when to use it. Be specific about trigger phrases. Make sure to use this skill whenever the user mentions [X], [Y], or [Z], even if they don't explicitly ask for a "[skill name]".
+---
+
+# My Skill Name
+
+A short paragraph explaining what this skill is and when it applies.
+
+## When to use this skill
+
+- Trigger condition 1
+- Trigger condition 2
+- Trigger condition 3
+
+## Instructions
+
+Step-by-step guidance for Claude on how to handle the task.
+
+1. First, do X.
+2. Then, do Y.
+3. Finally, do Z.
+
+## Examples
+
+### Example 1: [scenario]
+
+**User:** "..."
+
+**Claude:** [what the ideal response looks like]
+
+## Notes
+
+Any caveats, edge cases, or things to watch out for.

package/skills/conventional-commits/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: conventional-commits
+description: Write git commit messages following the Conventional Commits specification, with an automatic ticket number pulled from the current branch and a project tag (API / CLIENT / CONSOLE / DB) when the project type can be detected from the diff. Use this skill whenever the user asks to write a commit message, asks for help committing changes, runs `git commit`, or mentions writing changelog entries — even if they don't explicitly say "conventional commits".
+---
+
+# Conventional Commits
+
+Write commit messages that follow the [Conventional Commits](https://www.conventionalcommits.org/) spec, prefixed with the ticket number (from the current branch) and the project tag (`API` / `CLIENT` / `CONSOLE` / `DB`) when those can be determined.
+
+## Format
+
+```
+[#<ticket>] [(<PROJECT>)] <type>[(<scope>)][!]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+Bracketed segments are included only when they apply (see [Branch & project context](#branch--project-context)). A fully-tagged example:
+
+```
+#12345 (CLIENT) fix: prevent modal z-index regression on settings page
+```
+
+## Types
+
+- **feat** — a new feature (correlates with MINOR in semver)
+- **fix** — a bug fix (correlates with PATCH in semver)
+- **docs** — documentation only changes
+- **style** — formatting, missing semicolons, etc; no code change
+- **refactor** — code change that neither fixes a bug nor adds a feature
+- **perf** — a code change that improves performance
+- **test** — adding or correcting tests
+- **build** — changes to the build system or external dependencies
+- **ci** — changes to CI configuration files and scripts
+- **chore** — other changes that don't modify src or test files
+- **revert** — reverts a previous commit
+
+## Branch & project context
+
+Before composing the message, gather two pieces of context from the repo.
+
+### Ticket number (from current branch)
+
+1. Run `git rev-parse --abbrev-ref HEAD` to get the current branch name.
+2. Take the last `/`-separated segment of the branch (so `feature/12345-fix_this_bug` becomes `12345-fix_this_bug`).
+3. If that segment starts with one or more digits followed by `-`, `_`, or end-of-string, those leading digits are the ticket number.
+4. If no leading numeric ID is found, **omit `#<ticket>` from the message entirely** — do not invent one and do not prompt the user for it.
+
+Examples:
+
+| Branch                          | Extracted ticket |
+|---------------------------------|------------------|
+| `feature/12345-fix_this_bug`    | `12345`          |
+| `12345-fix_this_bug`            | `12345`          |
+| `bugfix/9-typo`                 | `9`              |
+| `main`, `release/v2`, `feature/redesign` | (none — omit `#`) |
+
+### Project tag
+
+Pick ONE of `API`, `CLIENT`, `CONSOLE`, or `DB` based on what was actually changed in the diff:
+
+- **API** — backend services, REST / GraphQL endpoints, server-side handlers. Signals: paths like `api/`, `server/`, `backend/`, `services/api/`, `apps/api/`; server framework code (Express, NestJS, FastAPI, Django, Rails, Spring); OpenAPI specs.
+- **CLIENT** — user-facing frontend. Signals: paths like `client/`, `web/`, `frontend/`, `apps/web/`, `apps/client/`, `ui/`; `.tsx` / `.jsx` / `.vue` / `.svelte`; React / Vue / Angular / Svelte component files; user-facing CSS / Tailwind / design assets.
+- **CONSOLE** — .NET console applications (CLIs, worker services, background tools). Signals: `.csproj` files with `<OutputType>Exe</OutputType>` or `Sdk="Microsoft.NET.Sdk"` (and NOT `Microsoft.NET.Sdk.Web`); `Program.cs` without ASP.NET / web-host bootstrap; `Microsoft.Extensions.Hosting` worker or `BackgroundService` usage; CLI libraries like `System.CommandLine`, `Spectre.Console`, `CommandLineParser`, `McMaster.Extensions.CommandLineUtils`; project names ending in `.Console`, `.Cli`, `.Worker`, or `.Tool`; paths like `console/`, `apps/console/`, `tools/`, `cli/`.
+- **DB** — database schema, migrations, seeds, ORM models. Signals: paths like `db/`, `migrations/`, `prisma/`, `schema.prisma`, SQL files, `alembic/`, `knex/`, model-only changes.
+
+How to decide:
+
+1. Run `git diff --cached --name-only` (fall back to `git diff --name-only` if nothing is staged).
+2. Match the changed paths against the signals above. If all changed files cluster under one bucket, use that tag.
+3. If the diff genuinely spans multiple buckets, pick the dominant one (most files or largest change) and mention the secondary in the body.
+4. If none of the four buckets fit the repo (e.g., a library, a docs-only repo, a meta-tooling project), **omit `(PROJECT)`** — same fallback rule as the missing ticket.
+5. If two buckets are plausibly equal and you can't break the tie from the diff, ask the user which one applies. Do not guess silently.
+
+## Rules
+
+1. Description must be lowercase, present tense ("add" not "added"), and under 72 characters. The `#12345 (CLIENT)` prefix counts toward the 72-char header budget — keep the description tight.
+2. No period at the end of the description.
+3. Breaking changes get a `!` after the type / scope (e.g., `#12345 (API) feat!: drop support for Node 16`) and a `BREAKING CHANGE:` footer.
+4. Inner `type(scope)` is optional and usually redundant once `(PROJECT)` is present. Only use it when it adds real specificity beyond the project tag (e.g., `#12345 (API) fix(auth): ...` when "auth" narrows further than "API").
+5. Body explains the *why*, not the *what*. Wrap at 72 chars.
+
+## Workflow
+
+When the user asks for a commit message:
+
+1. Get the current branch with `git rev-parse --abbrev-ref HEAD` and extract the ticket number per the rules above.
+2. Inspect the staged diff: `git diff --cached` (or `git diff` if nothing is staged).
+3. From the changed file paths, determine the project tag — or decide to omit it.
+4. Categorize the change into one of the types.
+5. Write a concise description.
+6. If the change is non-trivial, add a body explaining the rationale.
+7. Flag breaking changes explicitly.
+8. Assemble the header as `[#<ticket>] [(<PROJECT>)] <type>: <description>`, including only the segments that apply.
+
+## Examples
+
+```
+#12345 (CLIENT) fix: prevent modal z-index regression on settings page
+
+#12345 (API) feat(auth): add OAuth2 PKCE flow for mobile clients
+
+#987 (DB) chore: add index on users.created_at for analytics query
+
+#42 (CONSOLE) feat: add bulk-export action to billing dashboard
+
+(API) refactor: extract token validator into shared middleware
+# ^ branch had no ticket — `#` omitted
+
+#7 fix: correct off-by-one in pagination cursor
+# ^ repo doesn't fit API / CLIENT / CONSOLE / DB — `(PROJECT)` omitted
+
+fix: prevent race condition in cache invalidation
+
+The previous implementation could double-invalidate when two requests
+arrived within the lock window. Use a single atomic CAS.
+
+Fixes #482
+# ^ no ticket in branch, no project bucket fits — both prefixes omitted
+
+#1024 (API) refactor!: rename `user.email` column to `user.email_address`
+
+BREAKING CHANGE: clients reading `user.email` must update to `user.email_address`.
+```
+
+## Anti-patterns to avoid
+
+- ❌ `update stuff` (no type, vague)
+- ❌ `Fix: Bug in login page.` (capitalized, trailing period)
+- ❌ `feat: added the ability to export CSV files` (past tense)
+- ❌ `#12345 (CLIENT) feat: added export.` (past tense + trailing period)
+- ❌ Inventing a ticket number when the branch doesn't have one
+- ❌ Forcing a `(PROJECT)` tag when the diff doesn't actually map to API / CLIENT / CONSOLE / DB
+- ✅ `#12345 (CLIENT) feat: add CSV export`

package/skills/diagnose/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: diagnose
+description: Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use this skill whenever the user says "diagnose this", "debug this", "/diagnose", reports a bug, says something is broken / throwing / failing / flaky / hanging / leaking, or describes a performance regression — even if they don't explicitly ask for a "diagnose skill".
+---
+
+# Diagnose
+
+A discipline for hard bugs. Skip phases only when explicitly justified.
+
+When exploring the codebase, use the project's domain glossary to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.
+
+## When to use this skill
+
+- The user runs `/diagnose` or types "diagnose this" / "debug this".
+- The user reports a bug or says code is broken, throwing, failing, hanging, crashing, leaking, or producing wrong output.
+- The user describes a performance regression ("got slower", "high CPU", "timeout", "p95 climbed", "memory growing").
+- The user shows a stack trace, error log, or failing test and asks why.
+- A test is flaky and the user wants the underlying cause, not just a retry / skip.
+
+Do **not** use this skill for: tiny known-cause one-line fixes, typos, or questions about how code works when nothing is actually wrong.
+
+## Phase 1 — Build a feedback loop
+
+**This is the skill.** Everything else is mechanical. If you have a fast, deterministic, agent-runnable pass/fail signal for the bug, you will find the cause — bisection, hypothesis-testing, and instrumentation all just consume that signal. If you don't have one, no amount of staring at code will save you.
+
+Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
+
+### Ways to construct one — try them in roughly this order
+
+1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
+2. **Curl / HTTP script** against a running dev server.
+3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
+4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
+5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
+6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
+7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
+8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
+9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
+10. **HITL bash script.** Last resort. If a human must click, drive _them_ with a structured prompt-and-capture loop so the signal is still machine-readable. Captured output feeds back to you.
+
+Build the right feedback loop, and the bug is 90% fixed.
+
+### Iterate on the loop itself
+
+Treat the loop as a product. Once you have _a_ loop, ask:
+
+- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
+- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
+- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
+
+A 30-second flaky loop is barely better than no loop. A 2-second deterministic loop is a debugging superpower.
+
+### Non-deterministic bugs
+
+The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable.
+
+### When you genuinely cannot build a loop
+
+Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
+
+Do not proceed to Phase 2 until you have a loop you believe in.
+
+## Phase 2 — Reproduce
+
+Run the loop. Watch the bug appear.
+
+Confirm:
+
+- [ ] The loop produces the failure mode the **user** described — not a different failure that happens to be nearby. Wrong bug = wrong fix.
+- [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
+- [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
+
+Do not proceed until you reproduce the bug.
+
+## Phase 3 — Hypothesise
+
+Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.
+
+Each hypothesis must be **falsifiable**: state the prediction it makes.
+
+> Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."
+
+If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
+
+**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it — proceed with your ranking if the user is AFK.
+
+## Phase 4 — Instrument
+
+Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.**
+
+Tool preference:
+
+1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
+2. **Targeted logs** at the boundaries that distinguish hypotheses.
+3. Never "log everything and grep".
+
+**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
+
+**Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
+
+## Phase 5 — Fix + regression test
+
+Write the regression test **before the fix** — but only if there is a **correct seam** for it.
+
+A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence.
+
+**If no correct seam exists, that itself is the finding.** Note it. The codebase architecture is preventing the bug from being locked down. Flag this for the next phase.
+
+If a correct seam exists:
+
+1. Turn the minimised repro into a failing test at that seam.
+2. Watch it fail.
+3. Apply the fix.
+4. Watch it pass.
+5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
+
+## Phase 6 — Cleanup + post-mortem
+
+Required before declaring done:
+
+- [ ] Original repro no longer reproduces (re-run the Phase 1 loop)
+- [ ] Regression test passes (or absence of seam is documented)
+- [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
+- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
+- [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
+
+**Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling), surface it as a follow-up recommendation with specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.
+
+## Anti-patterns
+
+- Jumping to a fix before building a feedback loop — you're guessing, not diagnosing.
+- A single hypothesis becomes "the cause" without falsification — anchoring.
+- "Added some logs" without tagging them — they survive into production.
+- Marking the bug fixed because the symptom went away once — without re-running the loop or adding a regression test, you don't know.
+- Treating a flaky test as flaky-by-nature and retrying — flakes are bugs with a low reproduction rate; raise the rate.
+- Skipping the post-mortem question — same class of bug returns.
+
+## Notes
+
+- Adapted from Matt Pocock's `diagnose` skill — same six-phase discipline (reproduce → minimise → hypothesise → instrument → fix → regression-test), with the architectural-handoff step generalised since this library doesn't ship a paired `improve-codebase-architecture` skill.