@jesdi/skills 0.0.1

package/README.md

@@ -0,0 +1,57 @@
+# @jesdi/skills
+
+Personal agent skills, installable into Claude Code and OpenCode.
+
+## Install skills
+
+```bash
+npx @jesdi/skills-cli
+```
+
+Pick skills → pick agents → pick project-local or global. Skills are stored
+in `.my-skills/` (or `~/.my-skills/`) and symlinked into each agent's skills
+directory.
+
+## Team sync
+
+`.my-skills.json` is meant to be committed. Teammates run:
+
+```bash
+npx @jesdi/skills-cli sync
+```
+
+## Commands
+
+```
+npx @jesdi/skills-cli                      # interactive wizard
+npx @jesdi/skills-cli install <skill...> [--agent claude,opencode] [--global]
+npx @jesdi/skills-cli update [skill] [--all] [--global]
+npx @jesdi/skills-cli sync
+npx @jesdi/skills-cli list
+npx @jesdi/skills-cli uninstall <skill> [--global]
+```
+
+## Third-party skills (not vendored)
+
+Skills authored by other people are **not** copied into this repo — they keep
+their own authors, upstreams, and licenses. `external-skills.json` records
+which ones are part of the standard setup and where they come from. Install
+them from upstream with the [skills.sh](https://skills.sh/) CLI:
+
+```bash
+npx skills add mattpocock/skills          # grill-me, grill-with-docs, improve-codebase-architecture
+npx skills add JuliusBrussee/caveman      # caveman suite
+npx skills add vercel-labs/skills         # find-skills
+npx skills add vercel-labs/agent-skills   # vercel-react-best-practices
+npx skills add anthropics/skills          # frontend-design (skip if using the Claude Code plugin)
+```
+
+The skills.sh lockfile (`~/.agents/.skill-lock.json`) tracks installed
+versions; `npx skills update` refreshes them.
+
+## Authoring skills
+
+Add `skills/<name>/SKILL.md` (frontmatter `name` must match the directory,
+`description` required). Push to `main` — CI hashes the skill, bumps its
+version in `skills-manifest.json`, and publishes `@jesdi/skills`. See
+`DESIGN.md` for the full architecture.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@jesdi/skills",
+  "version": "0.0.1",
+  "description": "jesdi's agent skills (content package consumed by @jesdi/skills-cli)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jesdi/general-skills.git"
+  },
+  "type": "module",
+  "files": [
+    "skills",
+    "skills-manifest.json"
+  ],
+  "workspaces": [
+    "cli"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "generate-manifest": "tsx scripts/generate-manifest.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "gray-matter": "^4.0.3",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/skills/branch-audit/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: branch-audit
+description: >
+  Audit local and remote git branches to see which are merged into main, which have
+  unpushed commits, which have diverged, and which have stale worktrees. Use this skill
+  whenever the user asks: "is this branch already pushed?", "can I delete this branch?",
+  "which branches are stale?", "clean up merged branches", "remove old worktrees",
+  "what branches haven't been pushed yet?", or anything related to branch hygiene,
+  branch status, or pruning local/remote branches. Also use it when the user wants to
+  delete branches in bulk, either locally or on the remote.
+---
+
+# Branch Audit
+
+This skill bundles `scripts/branch-audit.sh` (in this skill's directory) that categorises
+every local branch and identifies stale remote branches. Always use it rather than
+running one-off `git branch` commands. Run it from the repo root of the repository being
+audited. If the target repo has its own `scripts/branch-audit.sh`, prefer that copy.
+
+The default branch is auto-detected from `origin/HEAD` (falling back to `main`);
+override with `MAIN=<branch>` or `REMOTE=<remote>` env vars if needed.
+
+## When to use each flag
+
+Below, `branch-audit.sh` means the bundled script — invoke it by its path inside this
+skill's directory, e.g. `bash <skill-dir>/scripts/branch-audit.sh`.
+
+| Goal | Command |
+|------|---------|
+| See branch status (read-only) | `bash branch-audit.sh` |
+| Preview what cleanup would do | `bash branch-audit.sh --clean-all --dry-run` |
+| Remove stale worktrees + delete merged local branches | `bash branch-audit.sh --clean-local` |
+| Delete merged branches on `origin` | `bash branch-audit.sh --clean-remote` |
+| Do both at once | `bash branch-audit.sh --clean-all` |
+
+Always run `--dry-run` first when the user hasn't explicitly said "go ahead and delete".
+
+## Output categories
+
+- **Green — merged into main**: safe to delete locally. Branches with an associated
+  worktree show the worktree path; clean-local removes both.
+- **Purple — remote merged into main**: the remote counterpart is also merged; clean-remote
+  deletes them from `origin`.
+- **Red — unmerged / dirty**: has commits not in main and is in sync with remote. Needs
+  manual review before deletion.
+- **Yellow — unpushed**: has local commits not yet pushed to remote, or no remote branch
+  at all.
+- **Cyan — diverged**: local and remote have both moved on; requires manual reconciliation.
+
+## Workflow
+
+1. Run the audit (no flags) and share the output with the user.
+2. If the user wants to clean up, run `--dry-run` first so they can confirm.
+3. Once confirmed, run without `--dry-run`.
+4. For remote deletion, remind the user this pushes a delete to `origin` — make sure
+   they're OK with that before proceeding.
+
+## Answering "is branch X already pushed?"
+
+Look at the Yellow section. If the branch appears there with "no remote branch" or
+"N unpushed", it is **not fully pushed**. If it's in Green or not listed at all
+(it may already be gone), it is pushed and merged. If it's in Red, it's pushed but
+not yet merged into main.

package/skills/branch-audit/scripts/branch-audit.sh

@@ -0,0 +1,235 @@
+#!/usr/bin/env bash
+# Audits local branches: merged, unpushed commits, diverged, and unmerged dirty branches.
+# Also detects stale worktrees and remote branches merged into main.
+#
+# Usage:
+#   branch-audit.sh                          # report only
+#   branch-audit.sh --clean-local            # remove stale worktrees + delete merged local branches
+#   branch-audit.sh --clean-remote           # delete merged remote branches on origin
+#   branch-audit.sh --clean-all              # both of the above
+#   branch-audit.sh --clean-* --dry-run      # show what would be done without executing
+
+set -euo pipefail
+
+# MAIN/REMOTE overridable via env; MAIN falls back to the remote's HEAD branch, then "main".
+REMOTE="${REMOTE:-origin}"
+MAIN="${MAIN:-$(git symbolic-ref --short "refs/remotes/$REMOTE/HEAD" 2>/dev/null | sed "s|^$REMOTE/||")}"
+MAIN="${MAIN:-main}"
+
+RED='\033[0;31m'
+YEL='\033[1;33m'
+CYA='\033[0;36m'
+GRN='\033[0;32m'
+MAG='\033[0;35m'
+BLD='\033[1m'
+DIM='\033[2m'
+RST='\033[0m'
+
+clean_local=false
+clean_remote=false
+dry_run=false
+
+for arg in "$@"; do
+  case "$arg" in
+    --clean-local)  clean_local=true ;;
+    --clean-remote) clean_remote=true ;;
+    --clean-all)    clean_local=true; clean_remote=true ;;
+    --dry-run)      dry_run=true ;;
+    *) echo "Unknown option: $arg" >&2; exit 1 ;;
+  esac
+done
+
+# run_cmd: prints the command, executes only when not in dry-run mode
+run_cmd() {
+  if $dry_run; then
+    echo -e "    ${DIM}[dry-run]${RST} $*"
+  else
+    echo -e "    $*"
+    "$@"
+  fi
+}
+
+# Fetch quietly to get up-to-date remote state
+git fetch --prune "$REMOTE" 2>/dev/null
+
+main_tip=$(git rev-parse "$MAIN")
+current=$(git rev-parse --abbrev-ref HEAD)
+
+# ── Build worktree index: "branch\tpath" lines (bash 3.2 compatible) ─────────
+worktree_index=""
+while IFS= read -r line; do
+  wt_path=$(echo "$line" | awk '{print $1}')
+  wt_branch=$(echo "$line" | sed -n 's/.*\[\(.*\)\].*/\1/p')
+  [[ -n "$wt_branch" ]] && worktree_index+="${wt_branch}	${wt_path}"$'\n'
+done < <(git worktree list)
+
+worktree_for() {
+  echo "$worktree_index" | awk -F'\t' -v b="$1" '$1==b{print $2; exit}'
+}
+
+# ── Classify local branches ───────────────────────────────────────────────────
+merged_into_main=()   # "branch|worktree_path_or_empty"
+dirty=()              # "branch|remote_status|ahead_main"
+unpushed=()           # "branch|push_status|ahead_main"
+diverged=()           # "branch|divergence|ahead_main"
+
+while IFS= read -r branch; do
+  [[ "$branch" == "$MAIN" ]] && continue
+  [[ "$branch" == "$current" ]] && continue
+
+  remote_ref="$REMOTE/$branch"
+  has_remote=false
+  git rev-parse --verify "$remote_ref" &>/dev/null && has_remote=true
+
+  branch_tip=$(git rev-parse "$branch")
+
+  if git merge-base --is-ancestor "$branch_tip" "$main_tip" 2>/dev/null; then
+    wt=$(worktree_for "$branch")
+    merged_into_main+=("$branch|$wt")
+    continue
+  fi
+
+  ahead_main=$(git rev-list --count "$MAIN".."$branch" 2>/dev/null || echo 0)
+
+  if $has_remote; then
+    ahead_remote=$(git rev-list --count "$remote_ref".."$branch" 2>/dev/null || echo 0)
+    behind_remote=$(git rev-list --count "$branch".."$remote_ref" 2>/dev/null || echo 0)
+
+    if [[ "$ahead_remote" -gt 0 && "$behind_remote" -gt 0 ]]; then
+      diverged+=("$branch|+${ahead_remote}/-${behind_remote} vs remote|+${ahead_main} vs main")
+    elif [[ "$ahead_remote" -gt 0 ]]; then
+      unpushed+=("$branch|${ahead_remote} unpushed|+${ahead_main} vs main")
+    else
+      dirty+=("$branch|in sync with remote|+${ahead_main} vs main")
+    fi
+  else
+    unpushed+=("$branch|no remote branch|+${ahead_main} vs main")
+  fi
+
+done < <(git branch --format='%(refname:short)')
+
+# ── Remote branches merged into main ─────────────────────────────────────────
+remote_merged=()
+while IFS= read -r ref; do
+  # Only process refs that genuinely start with "$REMOTE/" to avoid symrefs
+  [[ "$ref" != "$REMOTE/"* ]] && continue
+  branch="${ref#$REMOTE/}"
+  [[ "$branch" == "HEAD" || "$branch" == "$MAIN" ]] && continue
+
+  remote_tip=$(git rev-parse "$ref" 2>/dev/null || true)
+  [[ -z "$remote_tip" ]] && continue
+
+  if git merge-base --is-ancestor "$remote_tip" "$main_tip" 2>/dev/null; then
+    remote_merged+=("$branch")
+  fi
+done < <(git branch -r --format='%(refname:short)')
+
+# ── Print helpers ─────────────────────────────────────────────────────────────
+
+print_table() {
+  local color="$1"; shift
+  local header1="$1"; shift
+  local header2="$1"; shift
+  local header3="$1"; shift
+  printf "${color}${BLD}  %-42s %-28s %s${RST}\n" "$header1" "$header2" "$header3"
+  printf "${color}  %-42s %-28s %s${RST}\n" "$(printf '%.0s─' {1..42})" "$(printf '%.0s─' {1..28})" "$(printf '%.0s─' {1..20})"
+  for entry in "$@"; do
+    IFS='|' read -r b c1 c2 <<< "$entry"
+    printf "${color}  %-42s %-28s %s${RST}\n" "$b" "$c1" "$c2"
+  done
+}
+
+echo
+echo -e "${BLD}Branch Audit — $(git rev-parse --abbrev-ref HEAD) @ $(git rev-parse --short HEAD)${RST}"
+echo -e "Main branch: ${BLD}${MAIN}${RST}   Remote: ${BLD}${REMOTE}${RST}"
+echo
+
+# ── Merged local branches ─────────────────────────────────────────────────────
+if [[ ${#merged_into_main[@]} -gt 0 ]]; then
+  branches_to_delete=()
+  worktrees_to_remove=()
+
+  echo -e "${GRN}${BLD}✓ Merged into main (safe to delete locally)${RST}"
+  printf "${GRN}${BLD}  %-42s %s${RST}\n" "Branch" "Worktree"
+  printf "${GRN}  %-42s %s${RST}\n" "$(printf '%.0s─' {1..42})" "$(printf '%.0s─' {1..40})"
+
+  for entry in "${merged_into_main[@]}"; do
+    IFS='|' read -r b wt <<< "$entry"
+    branches_to_delete+=("$b")
+    if [[ -n "$wt" ]]; then
+      worktrees_to_remove+=("$wt")
+      printf "${GRN}  %-42s ${DIM}%s${RST}\n" "$b" "$wt"
+    else
+      printf "${GRN}  %s${RST}\n" "$b"
+    fi
+  done
+  echo
+
+  if $clean_local; then
+    $dry_run && echo -e "  ${BLD}--clean-local --dry-run: showing commands that would run${RST}" \
+             || echo -e "  ${BLD}--clean-local: removing worktrees and deleting branches...${RST}"
+    for wt in "${worktrees_to_remove[@]}"; do
+      run_cmd git worktree remove --force "$wt"
+    done
+    run_cmd git branch -d "${branches_to_delete[@]}"
+    $dry_run || echo -e "  ${GRN}Done.${RST}"
+  else
+    if [[ ${#worktrees_to_remove[@]} -gt 0 ]]; then
+      echo -e "  Remove worktrees first:"
+      for wt in "${worktrees_to_remove[@]}"; do
+        echo -e "    ${BLD}git worktree remove --force \"$wt\"${RST}"
+      done
+      echo
+    fi
+    echo -e "  Then delete branches: ${BLD}git branch -d ${branches_to_delete[*]}${RST}"
+    echo -e "  Or run: ${BLD}$0 --clean-local${RST}"
+  fi
+  echo
+fi
+
+# ── Remote branches merged into main ─────────────────────────────────────────
+if [[ ${#remote_merged[@]} -gt 0 ]]; then
+  echo -e "${MAG}${BLD}☁  Remote branches merged into main (safe to delete on remote)${RST}"
+  printf "${MAG}  %-42s${RST}\n" "$(printf '%.0s─' {1..42})"
+  for b in "${remote_merged[@]}"; do
+    printf "${MAG}  %s${RST}\n" "$b"
+  done
+  echo
+
+  if $clean_remote; then
+    $dry_run && echo -e "  ${BLD}--clean-remote --dry-run: showing commands that would run${RST}" \
+             || echo -e "  ${BLD}--clean-remote: deleting merged remote branches...${RST}"
+    run_cmd git push "$REMOTE" --delete "${remote_merged[@]}"
+    $dry_run || echo -e "  ${GRN}Done.${RST}"
+  else
+    echo -e "  Delete with: ${BLD}git push $REMOTE --delete ${remote_merged[*]}${RST}"
+    echo -e "  Or run: ${BLD}$0 --clean-remote${RST}"
+  fi
+  echo
+fi
+
+# ── Dirty (not merged, up-to-date with remote) ────────────────────────────────
+if [[ ${#dirty[@]} -gt 0 ]]; then
+  echo -e "${RED}${BLD}✗ Unmerged / dirty (not integrated into main)${RST}"
+  print_table "$RED" "Branch" "Remote status" "Ahead of main" "${dirty[@]}"
+  echo
+fi
+
+# ── Unpushed commits ──────────────────────────────────────────────────────────
+if [[ ${#unpushed[@]} -gt 0 ]]; then
+  echo -e "${YEL}${BLD}↑ Unpushed commits (local-only work)${RST}"
+  print_table "$YEL" "Branch" "Push status" "Ahead of main" "${unpushed[@]}"
+  echo
+fi
+
+# ── Diverged ─────────────────────────────────────────────────────────────────
+if [[ ${#diverged[@]} -gt 0 ]]; then
+  echo -e "${CYA}${BLD}⇅ Diverged from remote${RST}"
+  print_table "$CYA" "Branch" "Divergence" "Ahead of main" "${diverged[@]}"
+  echo
+fi
+
+if [[ ${#merged_into_main[@]} -eq 0 && ${#remote_merged[@]} -eq 0 && \
+      ${#dirty[@]} -eq 0 && ${#unpushed[@]} -eq 0 && ${#diverged[@]} -eq 0 ]]; then
+  echo -e "${GRN}All local branches (except current and main) are clean.${RST}"
+fi

package/skills/ceo-review/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: ceo-review
+description: |
+  CEO/founder-mode plan review. Rethink the problem, find the 10-star product,
+  challenge premises, expand scope when it creates a better product. Four modes:
+  SCOPE EXPANSION (dream big), SELECTIVE EXPANSION (hold scope + cherry-pick
+  expansions), HOLD SCOPE (maximum rigor), SCOPE REDUCTION (strip to essentials).
+  Use when asked to "think bigger", "expand scope", "strategy review", "rethink this",
+  "what would you do differently", or when reviewing project direction and goals.
+  Produces a structured review document with analysis and recommendations.
+preamble-tier: 3
+interactive: true
+version: 1.0.0
+---
+
+# CEO Review Skill
+
+This skill helps you conduct CEO/founder-style reviews of projects, plans, or ideas.
+It guides you through rethinking assumptions, challenging premises, and considering
+different scoping approaches to find better solutions.
+
+## How to Use
+
+When you want to perform a CEO-style review, invoke this skill and follow the prompts.
+The skill will guide you through four different scoping modes:
+
+1. **SCOPE EXPANSION (dream big)** - What if we expanded scope significantly?
+2. **SELECTIVE EXPANSION (hold scope + cherry-pick)** - What specific expansions would add value?
+3. **HOLD SCOPE (maximum rigor)** - How can we execute current scope with excellence?
+4. **SCOPE REDUCTION (strip to essentials)** - What's absolutely essential?
+
+## Process
+
+The skill will ask you to:
+1. Describe the current problem, plan, or idea you want to review
+2. Consider each scoping mode and what it would look like
+3. Identify premises that might be worth challenging
+4. Imagine what a 10-star product/service would look like
+5. Generate a structured review document with insights and recommendations
+
+## Output Format
+
+The skill produces a structured review document containing:
+- Current state assessment
+- Analysis through each scoping mode
+- Challenged premises and assumptions
+- 10-star vision
+- Recommended next steps and insights
+
+## When to Use
+
+Use this skill when:
+- You want to "think bigger" about a project or problem
+- You're asked to do a "strategy review" or "rethink this"
+- You want to challenge existing assumptions
+- You're reviewing project direction and considering different approaches
+- Someone mentions doing a "CEO review" or founder-style review
+
+## Example Invocations
+
+- "Let's do a CEO review of our current roadmap"
+- "Can we rethink this feature expansion?"
+- "What would you do differently if you were the CEO?"
+- "Help me think bigger about this project"
+- "Let's challenge our premises on this initiative"
+
+The skill works best when you have a specific project, plan, or idea to review and are open to rethinking assumptions and considering different scoping approaches.

package/skills/file-bug-issue/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: file-bug-issue
+description: >-
+  Open (or update) a GitHub issue whenever a bug or misbehaviour is detected while
+  working in a repo. Use this PROACTIVELY — the moment you notice something broken
+  (a failing test that reveals a real defect, a crash, a stack trace, wrong output,
+  a UI glitch, a regression, an API returning the wrong thing, flaky behaviour, a
+  "that shouldn't happen") — not only when the user says "file a bug". It first
+  searches the repo's OPEN issues (filtered by the labels that fit the bug) and
+  judges whether the same defect is already tracked. If a real duplicate exists, it
+  adds your new reproduction/context as a comment; otherwise it creates a fresh,
+  well-structured issue with reproducible steps and the context a fixer will need.
+  Trigger phrases include "file an issue", "report this bug", "log this", "open a
+  ticket", "track this", "this is broken", "that's a bug" — and also fire with no
+  prompt at all when you stumble onto a defect mid-task.
+---
+
+# File a Bug Issue on GitHub
+
+When you detect a bug or misbehaviour, your job is to make sure it ends up tracked
+on GitHub **without creating duplicates**. The flow is always: understand the bug →
+find the right repo → search existing open issues → judge for duplicates → comment
+on the existing one **or** create a new one.
+
+The point of this skill is leverage: a future fixer (human or agent) should be able
+to open the issue and reproduce the problem without re-deriving everything you
+already know right now. Capture that context while it's fresh.
+
+## Preconditions
+
+- `gh` must be authenticated for the repo. Verify quickly if unsure: `gh auth status`.
+- Run from inside the git repo so `gh` auto-detects it, or pass `--repo owner/name`.
+  Confirm the target: `gh repo view --json nameWithOwner -q .nameWithOwner`.
+
+If `gh` isn't available or authenticated, say so and stop — don't silently skip the
+tracking step.
+
+## Step 1 — Pin down the bug
+
+Before touching `gh`, get crisp on what actually went wrong. You usually already
+have this in your working context; pull it together:
+
+- **What you observed** — the actual wrong behaviour, in one sentence.
+- **Where** — `file_path:line`, the route, the component, the endpoint, the command.
+- **Reproduction** — the minimal sequence that triggers it. If you triggered it via
+  a test, a request, or a UI action, write the exact steps/commands.
+- **Expected vs. actual** — what should have happened instead.
+- **Evidence** — the stack trace, error message, failing assertion, log line, or
+  screenshot description. Trim noise but keep the diagnostic core.
+- **Suspected cause / scope** — only if you genuinely have a lead. Don't guess
+  loudly; mark speculation as speculation.
+
+If you can't actually describe a reproduction or concrete observation, you probably
+don't have a bug worth filing yet — investigate first rather than logging a vague
+"something seems off".
+
+## Step 2 — Choose the labels that fit
+
+Labels are how you narrow the duplicate search, so pick them before searching. List
+what the repo offers: `gh label list`.
+
+Always include the repo's bug label if it has one (commonly `bug`). Then add any
+labels that scope the area — language (`python`, `javascript`/`frontend`),
+subsystem, or component — when the repo has matching ones. Only use labels that
+already exist; don't invent new ones here.
+
+## Step 3 — Search open issues, filtered by those labels
+
+The goal is a small, high-signal candidate set, not a keyword dragnet. Filter open
+issues by the scoping labels, then look:
+
+```bash
+# Candidates within the same area (repeat --label to AND them, or widen if empty)
+gh issue list --state open --label bug --limit 50 \
+  --json number,title,labels,updatedAt
+
+# Also do a focused text search on the distinctive terms of THIS bug
+# (error class, function name, symptom) to catch issues labelled differently:
+gh issue list --state open --search "TypeError serialize holdings" \
+  --json number,title --limit 20
+```
+
+If the label-filtered list is empty or tiny, widen: drop the most specific label, or
+fall back to a text search over all open issues. You want to be confident you didn't
+miss an existing report.
+
+## Step 4 — Judge for a real duplicate
+
+Don't dedup on title similarity alone — read the candidates. Open the few that look
+plausible:
+
+```bash
+gh issue view <number> --json title,body,labels,comments
+```
+
+A candidate is the **same** bug only if it's the same defect: same symptom AND same
+root area/trigger. Different symptoms that might share a cause are *not* automatic
+duplicates — and two issues with similar words but different reproductions are
+distinct. When genuinely unsure, prefer treating it as **new** but link to the
+possibly-related issue in your write-up (cheaper to cross-link than to bury a real
+bug as a false duplicate).
+
+## Step 5a — If it's a duplicate: comment with the new context
+
+Add what the existing issue is missing — your fresh reproduction, the new
+environment, an additional stack trace, "still happening as of <commit/date>", or a
+narrower repro. Don't restate what's already there.
+
+```bash
+gh issue comment <number> --body "$(cat <<'EOF'
+Reproduced again on `<branch>` @ `<short-sha>` (<date>).
+
+**Steps**
+1. …
+
+**New context**
+- …
+
+**Evidence**
+```
+<trimmed trace>
+```
+EOF
+)"
+```
+
+Report back: the issue number/URL and that you commented (not created).
+
+## Step 5b — If it's new: create the issue
+
+Create it directly (no confirmation needed) with the bug + scope labels and a
+structured body. Use this template — keep headings, drop a section only if it
+truly doesn't apply:
+
+```markdown
+## Summary
+<one-sentence description of the wrong behaviour>
+
+## Where
+<file:line / route / component / command>
+
+## Steps to reproduce
+1. …
+2. …
+3. …
+
+## Expected
+<what should happen>
+
+## Actual
+<what happens instead>
+
+## Evidence
+` ` `
+<stack trace / error / failing assertion / log — trimmed to the diagnostic core>
+` ` `
+
+## Environment
+<branch @ short-sha, OS, runtime/version, container, browser — whatever's relevant>
+
+## Notes
+<suspected cause if you have a real lead; links to related issues #N; mark guesses as guesses>
+```
+
+Create it:
+
+```bash
+gh issue create \
+  --title "<concise, specific: symptom + where, not just 'bug'>" \
+  --label bug \
+  --body "$(cat <<'EOF'
+## Summary
+…
+EOF
+)"
+```
+
+Good titles name the symptom and locus: `Holdings serialize crashes with TypeError
+when weight is null` beats `Bug in portfolio`. After creation, report the issue
+URL back to the user.
+
+## After filing
+
+Tell the user concisely what you did: created vs. commented, the issue number/URL,
+and the labels applied. If you were mid-task when you spotted the bug, this is a
+side-quest — log it, mention it, and return to the original task unless the user
+redirects.
+
+## Guardrails
+
+- **One issue per distinct defect.** Don't bundle unrelated bugs; don't split one
+  bug across several issues.
+- **Don't fabricate reproductions.** If you couldn't actually reproduce it, say so
+  in the issue and label the steps as "observed once / not yet reproduced".
+- **Respect the existing tracker.** Match the repo's label and title conventions
+  rather than imposing your own.
+- **Creating/commenting is outward-facing.** It's authorized to do so without
+  asking here, but never delete or close others' issues, and never edit an existing
+  issue's body — only add comments.

package/skills/file-bug-issue/evals/evals.json

@@ -0,0 +1,23 @@
+{
+  "skill_name": "file-bug-issue",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "While testing the data table I noticed that when a row has a null quantity, the serialize step throws a TypeError and the whole report endpoint 500s. Steps: load a report, add a row with no quantity set, hit save, watch the backend crash. Can you make sure this is tracked?",
+      "expected_output": "Searches open issues filtered by bug/python labels, judges for duplicates, and either creates a structured issue (Summary/Where/Steps/Expected/Actual/Evidence/Environment) with the bug label or comments on a real existing duplicate. Reports the issue URL.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "The company logo in the footer attribution renders as a broken image when the third-party API token is missing — it should fall back to a placeholder instead. Log this so we don't forget.",
+      "expected_output": "Picks frontend/javascript + bug labels, searches open issues, and files (or comments on) an issue with a clear UI-bug repro and expected fallback behaviour.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "I think there's already an open issue about a background job double-firing when a record is superseded. I just hit it again on a fresh branch. Make sure the latest reproduction is captured.",
+      "expected_output": "Finds the existing open issue via label-filtered + text search, judges it as the same defect, and ADDS A COMMENT with the new reproduction/context rather than creating a duplicate.",
+      "files": []
+    }
+  ]
+}

package/skills/hello-world/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: hello-world
+description: Minimal example skill proving the distribution pipeline works. Responds to "test my skills setup" by confirming the skill is loaded.
+---
+
+# Hello World
+
+When the user asks to test their skills setup, reply exactly:
+"✅ hello-world skill is installed and loaded."

package/skills-manifest.json

@@ -0,0 +1,30 @@
+{
+  "schemaVersion": 1,
+  "generatedAt": "2026-07-14T10:05:20.198Z",
+  "skills": [
+    {
+      "name": "branch-audit",
+      "version": "0.1.0",
+      "hash": "sha256-d1983aa0577bd64e23d17cc4e91a7e214a72677b3d0d7bcdcf175a27449cc636",
+      "description": "Audit local and remote git branches to see which are merged into main, which have unpushed commits, which have diverged, and which have stale worktrees. Use this skill whenever the user asks: \"is this branch already pushed?\", \"can I delete this branch?\", \"which branches are stale?\", \"clean up merged branches\", \"remove old worktrees\", \"what branches haven't been pushed yet?\", or anything related to branch hygiene, branch status, or pruning local/remote branches. Also use it when the user wants to delete branches in bulk, either locally or on the remote.\n"
+    },
+    {
+      "name": "ceo-review",
+      "version": "0.1.0",
+      "hash": "sha256-5f239c09fd46ba4c1887da88374a75e12e3df31ff18e93ed9367bdd06f3b386c",
+      "description": "CEO/founder-mode plan review. Rethink the problem, find the 10-star product,\nchallenge premises, expand scope when it creates a better product. Four modes:\nSCOPE EXPANSION (dream big), SELECTIVE EXPANSION (hold scope + cherry-pick\nexpansions), HOLD SCOPE (maximum rigor), SCOPE REDUCTION (strip to essentials).\nUse when asked to \"think bigger\", \"expand scope\", \"strategy review\", \"rethink this\",\n\"what would you do differently\", or when reviewing project direction and goals.\nProduces a structured review document with analysis and recommendations.\n"
+    },
+    {
+      "name": "file-bug-issue",
+      "version": "0.1.0",
+      "hash": "sha256-6e1aae08cf08d2ef18b963c3600701aeddbac744db1d82ce9fb9ff75ca650651",
+      "description": "Open (or update) a GitHub issue whenever a bug or misbehaviour is detected while working in a repo. Use this PROACTIVELY — the moment you notice something broken (a failing test that reveals a real defect, a crash, a stack trace, wrong output, a UI glitch, a regression, an API returning the wrong thing, flaky behaviour, a \"that shouldn't happen\") — not only when the user says \"file a bug\". It first searches the repo's OPEN issues (filtered by the labels that fit the bug) and judges whether the same defect is already tracked. If a real duplicate exists, it adds your new reproduction/context as a comment; otherwise it creates a fresh, well-structured issue with reproducible steps and the context a fixer will need. Trigger phrases include \"file an issue\", \"report this bug\", \"log this\", \"open a ticket\", \"track this\", \"this is broken\", \"that's a bug\" — and also fire with no prompt at all when you stumble onto a defect mid-task."
+    },
+    {
+      "name": "hello-world",
+      "version": "0.1.0",
+      "hash": "sha256-916ea397cd74d91c4b6060672088b9c54353c915b98bcaef3514815694842e5a",
+      "description": "Minimal example skill proving the distribution pipeline works. Responds to \"test my skills setup\" by confirming the skill is loaded."
+    }
+  ]
+}