@phuetz/code-buddy 0.1.0

package/.codebuddy/skills/bundled/pdf-tools/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: pdf-tools
+version: 1.0.0
+description: Read, extract, convert, and manipulate PDF files
+author: Code Buddy
+tags: pdf, extract, convert, document
+---
+
+# PDF Tools
+
+## Overview
+
+Read, extract text, convert, and manipulate PDF files using common CLI tools.
+
+## Reading PDFs
+
+### Extract text
+```bash
+# Using pdftotext (poppler-utils)
+pdftotext document.pdf -         # stdout
+pdftotext document.pdf output.txt
+
+# Specific pages
+pdftotext -f 1 -l 5 document.pdf -  # pages 1-5
+
+# Layout mode (preserve formatting)
+pdftotext -layout document.pdf -
+```
+
+### Get PDF info
+```bash
+pdfinfo document.pdf
+# Pages, size, creator, producer, etc.
+```
+
+## Converting
+
+### PDF to images
+```bash
+# Using pdftoppm (poppler-utils)
+pdftoppm -png document.pdf /tmp/page   # page-1.png, page-2.png, ...
+pdftoppm -png -f 1 -l 1 document.pdf /tmp/cover  # first page only
+pdftoppm -jpeg -r 300 document.pdf /tmp/hires     # 300 DPI
+```
+
+### Images to PDF
+```bash
+# Using ImageMagick
+convert image1.png image2.png output.pdf
+
+# Using img2pdf (preserves quality)
+img2pdf *.png -o output.pdf
+```
+
+### Markdown/HTML to PDF
+```bash
+# Using pandoc
+pandoc document.md -o output.pdf
+pandoc --pdf-engine=weasyprint document.html -o output.pdf
+```
+
+## Manipulating
+
+### Merge PDFs
+```bash
+# Using pdfunite (poppler-utils)
+pdfunite file1.pdf file2.pdf merged.pdf
+
+# Using qpdf
+qpdf --empty --pages file1.pdf file2.pdf -- merged.pdf
+```
+
+### Split PDF
+```bash
+# Extract specific pages with qpdf
+qpdf input.pdf --pages . 1-5 -- first5.pdf
+qpdf input.pdf --pages . 10 -- page10.pdf
+```
+
+### Rotate pages
+```bash
+qpdf input.pdf --rotate=90:1-3 -- rotated.pdf  # rotate pages 1-3 by 90°
+```
+
+### Compress
+```bash
+# Using Ghostscript
+gs -sDEVICE=pdfwrite -dCompatibilityLevel=1.4 -dPDFSETTINGS=/ebook \
+   -dNOPAUSE -dQUIET -dBATCH -sOutputFile=compressed.pdf input.pdf
+```
+
+## Prerequisites
+
+Install on Ubuntu/Debian:
+```bash
+sudo apt-get install poppler-utils qpdf ghostscript
+```
+
+Install on macOS:
+```bash
+brew install poppler qpdf ghostscript
+```
+
+## Tips
+
+- Always check page count first: `pdfinfo file.pdf | grep Pages`
+- For OCR on scanned PDFs: `ocrmypdf scanned.pdf searchable.pdf`
+- Use `pdftotext -layout` to preserve tables and columns
+- For large PDFs, process page ranges to save memory

package/.codebuddy/skills/bundled/prepare-pr/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: prepare-pr
+version: 1.0.0
+description: Prepare a GitHub PR for merge by fixing review findings, running checks, and pushing updates. Use after review-pr. Never merge or push to main.
+author: Code Buddy
+tags: git, github, pr, prepare, fix
+---
+
+# Prepare PR
+
+## Overview
+
+Prepare a PR branch for merge with review fixes, green CI, and an updated head branch.
+
+## Inputs
+
+- Ask for PR number or URL if not provided.
+- If review findings exist, use them to guide fixes.
+
+## Safety
+
+- **Never push to `main` or `origin/main`.** Push only to the PR head branch.
+- **Never run bare `git push`.** Always specify remote and branch explicitly.
+- **Do not run `git add -A` or `git add .`.** Stage only specific changed files.
+- Do not run `git clean -fdx`.
+
+## Workflow
+
+### 1. Checkout the PR branch
+```bash
+gh pr checkout <number>
+```
+
+### 2. Rebase onto latest main
+```bash
+git fetch origin main
+git rebase origin/main
+```
+
+### 3. Fix review findings
+Address BLOCKER and IMPORTANT issues from the review. For each fix:
+- Make the minimal change needed
+- Stage only the specific files changed
+- Commit with a descriptive message: `fix: address review — <description>`
+
+### 4. Run validation
+```bash
+npm run validate  # or the project's equivalent: lint + typecheck + test
+```
+
+### 5. Fix any validation errors
+If lint/typecheck/test fails, fix and commit.
+
+### 6. Push to PR branch
+```bash
+git push origin HEAD:<head-branch> --force-with-lease
+```
+
+### 7. Verify PR is up to date
+```bash
+gh pr checks <number>
+gh pr view <number> --json mergeable
+```
+
+## Output
+
+Confirm: "PR #<number> is prepared and ready for merge."

package/.codebuddy/skills/bundled/project-best-practices/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: project-best-practices
+version: 1.0.0
+description: Best practices for initializing and structuring software projects
+author: Code Buddy
+tags: project, init, architecture, best-practices
+---
+
+# Project Best Practices
+
+When creating or scaffolding a new project, follow these guidelines.
+
+## Project Initialization
+
+1. **Always start with a package manager lockfile** — run `npm init -y` (or `pnpm init`) then install dependencies to generate a lockfile immediately.
+2. **Use TypeScript by default** — unless the user explicitly asks for JavaScript. Configure `strict: true` in `tsconfig.json`.
+3. **Add a `.gitignore`** from the start — include `node_modules/`, `dist/`, `.env`, coverage reports, OS files.
+4. **Initialize git** — `git init` with an initial commit after scaffolding.
+5. **Create a README.md** — with project name, description, setup instructions, and available scripts.
+
+## Directory Structure
+
+Follow a standard layout based on project type:
+
+### Node.js / Backend
+```
+src/
+  index.ts          # Entry point
+  routes/           # HTTP route handlers
+  services/         # Business logic
+  models/           # Data models / schemas
+  utils/            # Shared utilities
+  middleware/       # Express/Fastify middleware
+  types/            # TypeScript type definitions
+tests/              # Test files mirroring src/
+.env.example        # Environment variable template (never commit .env)
+```
+
+### Frontend (React/Vue/Svelte)
+```
+src/
+  components/       # Reusable UI components
+  pages/            # Route-level views
+  hooks/            # Custom hooks
+  services/         # API client / business logic
+  utils/            # Helpers
+  types/            # TypeScript types
+  assets/           # Static files (images, fonts)
+public/             # Public static assets
+```
+
+### Library / Package
+```
+src/
+  index.ts          # Public API exports
+  lib/              # Internal implementation
+  types/            # Type definitions
+tests/
+examples/           # Usage examples
+```
+
+## Code Quality
+
+1. **Linter** — Add ESLint with a flat config (`eslint.config.js`). Prefer `@typescript-eslint` rules.
+2. **Formatter** — Add Prettier with consistent config (single quotes, semicolons, 2-space indent).
+3. **Pre-commit hooks** — Use `husky` + `lint-staged` to run lint/format on commit.
+4. **EditorConfig** — Add `.editorconfig` for consistent formatting across editors.
+
+## Testing
+
+1. **Test framework** — Use Jest (with `ts-jest`) or Vitest. Configure in `package.json` or dedicated config file.
+2. **Test structure** — Mirror `src/` in `tests/`. Name files `*.test.ts` or `*.spec.ts`.
+3. **Coverage** — Configure coverage reporting. Aim for 80%+ on critical paths.
+4. **Scripts** — Add `npm test`, `npm run test:watch`, `npm run test:coverage`.
+
+## Dependencies
+
+1. **Pin versions** — Use exact versions or lockfiles for reproducibility.
+2. **Separate dev dependencies** — `devDependencies` for tools, `dependencies` for runtime.
+3. **Minimize dependencies** — Prefer built-in Node.js APIs (fs, path, crypto, http) over trivial packages.
+4. **Audit regularly** — Run `npm audit` to check for vulnerabilities.
+
+## Environment & Configuration
+
+1. **Use `.env` files** — with `dotenv` or framework-native support. Never commit secrets.
+2. **Provide `.env.example`** — document all required environment variables with descriptions.
+3. **Validate config at startup** — fail fast if required variables are missing.
+
+## Scripts (package.json)
+
+Always include these npm scripts:
+```json
+{
+  "dev": "tsx src/index.ts",
+  "build": "tsc",
+  "start": "node dist/index.js",
+  "test": "jest",
+  "test:watch": "jest --watch",
+  "test:coverage": "jest --coverage",
+  "lint": "eslint src/",
+  "lint:fix": "eslint src/ --fix",
+  "typecheck": "tsc --noEmit",
+  "validate": "npm run lint && npm run typecheck && npm test"
+}
+```
+
+## Security
+
+1. **Never hardcode secrets** — use environment variables.
+2. **Validate all user input** — at system boundaries (API endpoints, CLI args).
+3. **Use parameterized queries** — never concatenate SQL strings.
+4. **Set security headers** — `helmet` for Express, built-in for Fastify.
+5. **CORS** — configure explicitly, never use `*` in production.
+
+## Commit Conventions
+
+Use Conventional Commits:
+- `feat(scope): description` — new feature
+- `fix(scope): description` — bug fix
+- `docs: description` — documentation
+- `test: description` — adding tests
+- `refactor: description` — code restructure
+- `chore: description` — tooling, deps, config

package/.codebuddy/skills/bundled/review-pr/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: review-pr
+version: 1.0.0
+description: Review-only GitHub pull request analysis with the gh CLI. Use when asked to review a PR, provide structured feedback, or assess readiness to merge. Do not merge, push, or make code changes.
+author: Code Buddy
+tags: git, github, pr, review, code-review
+---
+
+# Review PR
+
+## Overview
+
+Perform a thorough review-only PR assessment and return a structured recommendation.
+
+## Inputs
+
+- Ask for PR number or URL if not provided.
+- If ambiguous, ask for clarification.
+
+## Safety
+
+- **Never push to `main` or `origin/main`.**
+- **Do not run `git push` at all during review.** Review is read-only.
+- Do not modify code.
+
+## Workflow
+
+### 1. Identify PR metadata
+```bash
+gh pr view <number> --json title,body,author,baseRefName,headRefName,additions,deletions,files,reviews,state
+```
+
+### 2. Read the diff
+```bash
+gh pr diff <number>
+```
+
+### 3. Check CI status
+```bash
+gh pr checks <number>
+```
+
+### 4. Read changed files in context
+For each changed file, read the full file to understand the surrounding code.
+
+### 5. Produce structured review
+
+Write the review with these sections:
+
+**A) TL;DR** — One-line recommendation: APPROVE, REQUEST_CHANGES, or NEEDS_DISCUSSION
+
+**B) What changed** — Concise summary of the changes
+
+**C) What is good** — Positive aspects of the implementation
+
+**D) Security findings** — Any security concerns (injection, secrets, auth issues)
+
+**E) Concerns** — Categorized as:
+- `BLOCKER` — Must fix before merge
+- `IMPORTANT` — Should fix, but not a dealbreaker
+- `NIT` — Style/preference, optional
+
+**F) Tests** — Are changes tested? Are edge cases covered?
+
+**G) Docs** — Are docs updated if needed?
+
+**H) Suggested PR comment** — Ready-to-post review comment
+
+## Output Format
+
+```markdown
+## PR Review: #<number> — <title>
+
+### A) TL;DR
+APPROVE / REQUEST_CHANGES / NEEDS_DISCUSSION
+
+### B) What changed
+...
+
+### C) What is good
+...
+
+### D) Security
+...
+
+### E) Concerns
+- BLOCKER: ...
+- IMPORTANT: ...
+- NIT: ...
+
+### F) Tests
+...
+
+### G) Docs
+...
+
+### H) Suggested comment
+...
+```

package/.codebuddy/skills/bundled/screenshot/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: screenshot
+version: 1.0.0
+description: Capture screenshots and screen recordings from the terminal
+author: Code Buddy
+tags: screenshot, screen, capture, record, scrot
+---
+
+# Screenshot & Screen Recording
+
+## Overview
+
+Capture screenshots and screen recordings from the terminal.
+
+## Screenshots
+
+### Linux
+```bash
+# Full screen (scrot)
+scrot /tmp/screenshot.png
+
+# Active window
+scrot -u /tmp/window.png
+
+# Selection (click and drag)
+scrot -s /tmp/selection.png
+
+# Delayed (5 seconds)
+scrot -d 5 /tmp/delayed.png
+
+# Using gnome-screenshot
+gnome-screenshot -f /tmp/screenshot.png
+gnome-screenshot -a -f /tmp/area.png   # area selection
+
+# Using import (ImageMagick)
+import /tmp/screenshot.png             # click to select window
+import -window root /tmp/fullscreen.png
+```
+
+### macOS
+```bash
+# Full screen
+screencapture /tmp/screenshot.png
+
+# Selection
+screencapture -i /tmp/selection.png
+
+# Window (click to select)
+screencapture -iW /tmp/window.png
+
+# Delayed (5 seconds)
+screencapture -T 5 /tmp/delayed.png
+
+# No shadow
+screencapture -io /tmp/noshadow.png
+```
+
+### WSL (Windows Subsystem for Linux)
+```bash
+# Use PowerShell from WSL
+powershell.exe -c "Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.Screen]::PrimaryScreen | ForEach-Object { \$bitmap = New-Object System.Drawing.Bitmap(\$_.Bounds.Width, \$_.Bounds.Height); \$graphics = [System.Drawing.Graphics]::FromImage(\$bitmap); \$graphics.CopyFromScreen(\$_.Bounds.Location, [System.Drawing.Point]::Empty, \$_.Bounds.Size); \$bitmap.Save('C:\\tmp\\screenshot.png') }"
+cp /mnt/c/tmp/screenshot.png /tmp/screenshot.png
+```
+
+## Screen Recording
+
+### Linux (ffmpeg)
+```bash
+# Record screen (X11)
+ffmpeg -f x11grab -r 30 -s 1920x1080 -i :0.0 -c:v libx264 -preset fast /tmp/recording.mp4
+
+# Record with audio
+ffmpeg -f x11grab -r 30 -s 1920x1080 -i :0.0 -f pulse -i default -c:v libx264 -c:a aac /tmp/recording.mp4
+
+# Stop with Ctrl+C
+```
+
+### macOS
+```bash
+# Start recording
+screencapture -v /tmp/recording.mp4
+# Stop with Ctrl+C or Escape
+```
+
+## Tips
+
+- Use PNG for screenshots (lossless)
+- Use MP4/WebM for recordings
+- For OCR on screenshots: `tesseract screenshot.png - --oem 3` (requires tesseract)
+- Resize: `convert screenshot.png -resize 50% thumbnail.png`
+- Annotate: `convert screenshot.png -pointsize 24 -annotate +10+30 "Text" annotated.png`

package/.codebuddy/skills/bundled/session-logs/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: session-logs
+version: 1.0.0
+description: Search and analyze Code Buddy session logs and conversation history
+author: Code Buddy
+tags: sessions, logs, history, analysis, cost
+---
+
+# Session Logs
+
+## Overview
+
+Search and analyze your own session logs to find past conversations, track usage, and review costs.
+
+## Location
+
+Session data is stored in `.codebuddy/sessions/` in the project directory.
+
+## Common Queries
+
+### List sessions by date
+```bash
+ls -lt .codebuddy/sessions/*.json | head -20
+```
+
+### Search across all sessions
+```bash
+rg -l "search term" .codebuddy/sessions/
+```
+
+### Extract user messages from a session
+```bash
+jq '.messages[] | select(.role == "user") | .content' .codebuddy/sessions/<session>.json
+```
+
+### Extract assistant responses
+```bash
+jq '.messages[] | select(.role == "assistant") | .content' .codebuddy/sessions/<session>.json
+```
+
+### Get tool usage breakdown
+```bash
+jq '[.messages[] | select(.role == "assistant") | .tool_calls[]? | .function.name] | group_by(.) | map({tool: .[0], count: length}) | sort_by(-.count)' .codebuddy/sessions/<session>.json
+```
+
+### Calculate session cost
+```bash
+jq '.usage.totalCost // "unknown"' .codebuddy/sessions/<session>.json
+```
+
+### Find sessions that used a specific tool
+```bash
+for f in .codebuddy/sessions/*.json; do
+  if jq -e '.messages[] | select(.role == "assistant") | .tool_calls[]? | select(.function.name == "bash")' "$f" > /dev/null 2>&1; then
+    echo "$f"
+  fi
+done
+```
+
+## Tips
+
+- Use `jq` for structured queries on JSON session files
+- Use `rg` (ripgrep) for fast full-text search across all sessions
+- Combine with `sort`, `uniq -c` for frequency analysis
+- Export a session summary: pipe jq output to a markdown file

package/.codebuddy/skills/bundled/skill-creator/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: skill-creator
+version: 1.0.0
+description: Create or update Code Buddy skills. Use when designing, structuring, or packaging new SKILL.md files.
+author: Code Buddy
+tags: skill, create, meta, template
+---
+
+# Skill Creator
+
+## Overview
+
+Guide for creating well-structured Code Buddy skills.
+
+## Anatomy of a Skill
+
+```
+skill-name/
+├── SKILL.md          # Required — instructions for the agent
+├── scripts/          # Optional — executable helpers
+├── references/       # Optional — detailed docs loaded on demand
+└── assets/           # Optional — templates, icons, config files
+```
+
+## SKILL.md Structure
+
+### Frontmatter (required)
+```yaml
+---
+name: my-skill           # lowercase, hyphens, <64 chars
+version: 1.0.0
+description: One-line description used for skill matching and activation
+author: Your Name
+tags: keyword1, keyword2
+env:                      # Optional env overrides
+  MY_VAR: default_value
+---
+```
+
+### Body (required)
+```markdown
+# Skill Name
+
+## Overview
+What this skill does in 1-2 sentences.
+
+## When to Use
+Trigger conditions — when should the agent activate this skill?
+
+## Workflow / Commands
+Step-by-step instructions or command reference.
+
+## Output Format
+Expected output structure.
+
+## Tips / Gotchas
+Common pitfalls and workarounds.
+```
+
+## Design Principles
+
+### 1. Concise is Key
+Context window is a shared resource. Only include what the LLM doesn't already know.
+
+**Bad**: Explaining what `git commit` does.
+**Good**: Documenting a specific workflow with safety rules.
+
+### 2. Set Appropriate Degrees of Freedom
+
+| Freedom | Use When | Format |
+|---------|----------|--------|
+| High | Multiple approaches valid | Natural language description |
+| Medium | Preferred pattern exists | Pseudocode or examples |
+| Low | Operation is fragile | Exact commands with safety checks |
+
+### 3. Progressive Disclosure
+
+- **Frontmatter**: Always loaded (name + description for matching)
+- **SKILL.md body**: Loaded when skill is triggered
+- **References**: Loaded on demand for detailed sub-topics
+
+### 4. Avoid Duplication
+
+Information should live in ONE place:
+- General knowledge → Don't include (LLM already knows)
+- Skill-specific workflow → SKILL.md body
+- Detailed reference → `references/` directory
+
+## Skill Locations
+
+| Location | Source | Purpose |
+|----------|--------|---------|
+| `.codebuddy/skills/bundled/` | Ships with Code Buddy | Core skills |
+| `.codebuddy/skills/managed/` | Installed by user | Community skills |
+| `.codebuddy/skills/workspace/` | Project-specific | Per-project skills |
+
+## Creation Checklist
+
+1. [ ] Name is lowercase with hyphens, descriptive
+2. [ ] Description clearly states when to activate
+3. [ ] Tags cover likely search terms
+4. [ ] Body has Overview, When to Use, Workflow sections
+5. [ ] Safety rules included if skill modifies state
+6. [ ] Commands are copy-pasteable
+7. [ ] No redundant information the LLM already knows
+8. [ ] Tested with a real conversation