          /`·.¸
         /¸...¸`:·
     ¸.·´  ¸   `·.¸.·´)
    : © ):´;      ¸  {    f i s h - s k i l l s
     `·.¸ `·  ¸.·´\`·¸)
         `\\´´\¸.·´

fish-skills

Personal Claude Code skills for development workflows — PR resolution, code simplification, worktree management, meeting processing, and more.

Installation

Quick Install (Recommended)

Uses the Vercel Skills CLI — interactive picker, symlinks, multi-agent support (Claude Code, Cursor, Copilot, Gemini CLI, Codex, Amp, and more).

npx skills add skinnyandbald/fish-skills

This clones the repo, shows an interactive skill picker (space to toggle), and installs your selections via symlinks. Cherry-pick a single skill with:

npx skills add skinnyandbald/fish-skills@pr-resolution

Additional skills — these live in separate repos and need their own install:

# Counselors: fan-out to multiple AI agents (required by /critic-review)
npm install -g @skinnyandbald/counselors    # installs the CLI binary
npx skills add skinnyandbald/counselors     # installs the /counselors skill

# Community skills
npx skills add rjs/shaping-skills           # Basecamp-style shaping workflow
npx skills add mvanhorn/last30days-skill    # Trending topic research

Managing installed skills:

npx skills list       # see what's installed
npx skills check      # check for updates
npx skills update     # update all skills

Manual Install (Alternative)

If you prefer managing symlinks yourself:

git clone https://github.com/skinnyandbald/fish-skills.git ~/fish-skills

Claude Code looks for skills in two places:

Location	Scope	Path
User skills	Available in every project on your machine	`~/.claude/skills/`
Project skills	Available only in a specific project	`<project-root>/.claude/skills/`

Install all skills globally:

mkdir -p ~/.claude/skills
find ~/fish-skills/skills -iname skill.md -exec dirname {} \; | while read d; do
  ln -sf "$d" ~/.claude/skills/
done

Cherry-pick individual skills:

mkdir -p ~/.claude/skills
ln -s ~/fish-skills/skills/pr-resolution ~/.claude/skills/pr-resolution
ln -s ~/fish-skills/skills/simplify-parallel ~/.claude/skills/simplify-parallel

Install into a specific project:

cd ~/my-project
mkdir -p .claude/skills
ln -s ~/fish-skills/skills/pr-resolution .claude/skills/pr-resolution

After installing (either method), restart Claude Code or start a new session. Skills are auto-discovered and show up as /skill-name commands.

Required dependencies

Most skills work out of the box, but some require additional setup:

Dependency	Required by	Install
GitHub CLI (`gh`)	pr-resolution, process-meeting-notes	`brew install gh && gh auth login`
@skinnyandbald/counselors	critic-review, counselors	`npm install -g @skinnyandbald/counselors`
Claude Code v2.1.63+	simplify-parallel	Built-in `/simplify` provides the review model; `/simplify-parallel` extends it to full-codebase sweeps
Fireflies MCP	process-meeting-notes	Configure in Claude Code MCP settings

Most skills work with no additional setup. Skills with dependencies are listed above.

Quick Start

Open any project in Claude Code and invoke a skill:

/pr-resolution 42
/simplify-parallel --focus=lib
/git-worktree create feat/my-feature
/last30days "best AI coding tools"

Each skill runs in Claude Code's context with access to your codebase, git history, and configured tools.

Skills

Code Review & Quality

Skill	Command	Description
pr-resolution	`/pr-resolution [PR#]`	Resolve PR review comments using parallel agents with 5-phase workflow
simplify-parallel	`/simplify-parallel`	Parallel codebase simplification with automatic segmentation (complements built-in `/simplify`)
web-design-guidelines	`/web-design-guidelines`	Review UI code against Web Interface Guidelines
vercel-react-best-practices	`/vercel-react-best-practices`	React/Next.js performance optimization (45 rules across 8 categories)
review-style-guide	`/review-style-guide`	Review code changes against STYLE_GUIDE.md before committing
audit-claude-md	`/audit-claude-md`	Audit a project's CLAUDE.md against best practices and score its effectiveness

Development Workflow

Skill	Command	Description
setup-ai	`/setup-ai [--global\|--project\|--check]`	One-command AI onboarding — generates AGENTS.md, STYLE_GUIDE.md, and configures hooks/plugins
git-worktree	`/git-worktree [cmd] [args]`	Manage Git worktrees for isolated parallel development
handoff	`/handoff`	Generate or resume from structured session handoffs for seamless context transfer
finalize	`/finalize`	Clean up completed feature work — remove false starts, debug statements, and experimental remnants
test	`/test`	Auto-detect test framework, run suite, diagnose failures, and fix them
tests-new	`/tests-new`	Add missing test coverage for a feature you just built
generate-comprehensive-style-guide	`/generate-comprehensive-style-guide`	Deep codebase analysis to generate a 17-section STYLE_GUIDE.md with evidence citations
verify-worktree-plugins	`/verify-worktree-plugins`	Verify worktree plugin patches are intact after plugin updates

Planning & Research

Skill	Command	Description
critic-review	`/critic-review [path] [--dry-run] [--feedback="..."] [--models=x,y]`	Unified plan review: stack detection, Context7 staleness scan, multi-model counselors dispatch, and prioritized triage
interview-me	`/interview-me`	Socratic thinking partner — refines half-baked ideas into clear specs through iterative questioning
requirements-builder	`/requirements-builder`	Progressively gather requirements through codebase discovery and yes/no questions
deepproduct	`/deepproduct`	Build a product profile, then generate a research prompt for any UX or product design question
deepstack	`/deepstack`	Detect your project's full tech stack, then generate a research prompt for security, performance, or testing
ceo-briefing	`/ceo-briefing [topic]`	Research any topic and produce a structured executive briefing
last30days	`/last30days [topic]`	Research trending topics from Reddit, X, YouTube, and the web
process-meeting-notes	`/process-meeting-notes`	Process Fireflies transcripts into action items and GitHub issues

EOS Operating System

Skill	Command	Description
eos	`/eos [request]`	Context-aware EOS router — suggests actions based on day of week, quarter position, and data staleness

The /eos skill is a conductor that routes to CEOS (17 skills for running EOS with Claude Code). Install CEOS first, then use /eos as your single entry point:

npx skills add skinnyandbald/ceos    # install the 17 CEOS skills
npx skills add skinnyandbald/fish-skills@eos  # install the /eos router

/eos reads your project's CLAUDE.md for customization (CEOS data root path, L10 day, solopreneur mode). Without arguments, it shows a context-aware dashboard with prioritized suggestions. With arguments (e.g., /eos scorecard, /eos rocks), it routes directly to the right CEOS skill.

Utilities

Skill	Command	Description
ascii	`/ascii`	Create ASCII diagrams for flows, architectures, sequence diagrams, and state machines
clipboard	`/clipboard`	Copy generated text to macOS clipboard — auto-triggers when content is paste-ready
invoice	`/invoice [client] [items]`	Generate professional PDF invoices with auto-incrementing IDs

Skill Details

critic-review

Unified plan validation skill — runs before writing code to catch gaps, ordering issues, and staleness risks.

Full pipeline (default):

Auto-detects the plan file (or accept a path argument)
Detects/caches the project stack to .claude/stack-profile.md
Pulls current library docs via Context7 (staleness safeguard)
Builds a structured rubric prompt
Dispatches to counselors (default: claude-opus, gemini-3-pro-preview, amp-smart, codex-5.4-high)
Synthesizes findings into Critical/High/Medium/Low action items

/critic-review                                # auto-detect plan, full pipeline
/critic-review docs/plans/my-feature.md       # explicit path
/critic-review docs/plans/my-feature.md --dry-run          # copyable prompt only
/critic-review --models=gemini,codex          # subset of models
/critic-review --model=gemini                 # single model
/critic-review --feedback="Reviewer said X"  # analyze external input, skip dispatch
/critic-review --feedback-file=review.txt    # analyze feedback from file

--dry-run: generates the full enriched prompt as a fenced code block — ready to paste into Cursor, Claude.ai, or any multi-model interface. No API calls made.

--feedback / --feedback-file: skip stack detection, Context7, and counselors dispatch. Jump straight to the synthesis phase with the provided reviewer text as input.

On first run, auto-detects the project's tech stack and caches it to .claude/stack-profile.md. Subsequent runs use the cache. To refresh after a stack change, delete .claude/stack-profile.md.

Output: Priority-classified action items with effort estimates and a reviewer agreement matrix.

Typical Plan Review Workflow

# 1. Write a plan
/plan "Add transcript import feature"

# 2. Run unified review (auto-dispatches to multiple models)
/critic-review docs/plans/transcript-import.md

# — or, if you want to review manually in Cursor —
/critic-review docs/plans/transcript-import.md --dry-run
# → copy prompt → paste into Cursor → run

# 3. Apply the prioritized improvements to your plan

pr-resolution

Resolves GitHub PR review comments through a 5-phase parallel workflow:

Pre-Flight — Optional GoodToGo check for deterministic PR readiness
Discovery — Gather all unresolved review threads (supports CodeRabbit, Gemini, Claude, human reviewers)
Classification — Categorize comments by type, severity, and file grouping
Parallel Resolution — Launch dedicated agents per file group to implement fixes
Verification & Completion — Run checks, commit changes, resolve threads

/pr-resolution           # auto-detect PR for current branch
/pr-resolution 42        # resolve comments on PR #42

simplify-parallel

Codebase-wide simplification using parallel agents with automatic file segmentation and dependency ordering.

Note: Claude Code v2.1.63+ ships a built-in /simplify that reviews recently changed files through 3 parallel agents (code reuse, quality, efficiency). /simplify-parallel complements it for full-codebase sweeps and large PRs where the built-in's diff-scoped approach may hit context limits.

/simplify-parallel                # analyze and simplify entire codebase
/simplify-parallel --dry-run      # analyze only, show plan
/simplify-parallel --focus=lib    # limit to specific area
/simplify-parallel --segments=4   # set max parallel agents

Each worker reviews its file segment through the same three lenses as the built-in /simplify: code reuse, code quality, and efficiency.

git-worktree

Manage Git worktrees in .github/worktrees/ for isolated parallel development:

/git-worktree create feat/auth    # create worktree with branch
/git-worktree list                # show all worktrees
/git-worktree switch feat/auth    # switch to worktree
/git-worktree cleanup             # remove stale worktrees

Key behavior: symlinks .env (not copies) so all worktrees share a single source of truth for environment variables. Automatically updates .gitignore.

last30days

Research any topic across Reddit, X, and the web to surface what people are actually discussing right now:

/last30days "best AI coding tools" for Claude Code
/last30days "photorealistic AI prompts"

Three research modes based on available API keys:

Full: Reddit + X + Web (requires OPENAI_API_KEY + XAI_API_KEY)
Partial: Single platform + Web
Web-Only: No API keys needed

process-meeting-notes

Process Fireflies meeting transcripts into structured outputs:

Extract action items with WHO/WHAT/WHEN accountability (EOS Level 10 format)
Create GitHub issues with labels, checklists, and project assignment
Detect duplicate issues before creating
Dynamic repo context detection (available labels, milestones, projects)
Save structured notes and raw transcripts to a local vault (optional)

Requires Fireflies MCP integration in Claude Code.

Vault integration: Set MEETING_NOTES_DIR and MEETING_TRANSCRIPTS_DIR in ~/.env to auto-save meeting notes and transcripts to your knowledge base. See the skill README for details.

handoff

Generate or resume from a structured handoff document when ending a session or switching contexts. Auto-detects git branch and working tree state, infers role/status/next steps from conversation context, and outputs a formatted document the next session can consume immediately.

Generate mode (default): Captures current session state into a handoff document.

/handoff              # generate handoff from current session context

Resume mode: Reads an existing handoff, validates the environment (branch, dirty state, new commits), surfaces any mismatches, and confirms next steps before proceeding.

/handoff resume                          # find most recent handoff in 00_Inbox/
/handoff resume 00_Inbox/handoff-2026-03-05.md  # resume from specific file

Output includes: role, current work summary, status, git state, numbered next steps, and any relevant notes (decisions made, gotchas, trade-offs). Sections with no content are omitted automatically.

vercel-react-best-practices

45 optimization rules across 8 priority categories:

Priority	Category	Rules
Critical	Eliminating Waterfalls	Async patterns, parallel data fetching
Critical	Bundle Size	Barrel imports, tree shaking, dynamic imports
High	Server-Side Performance	RSC patterns, streaming, caching
Medium-High	Client Data Fetching	TanStack Query, SWR patterns
Medium	Re-render Optimization	7 rules for memo, callbacks, state
Medium	Rendering Performance	Virtualization, layout thrashing
Low-Medium	JavaScript Performance	10 micro-optimization rules
Low	Advanced Patterns	Web Workers, WASM, compiler hints

Each rule includes incorrect vs correct code examples with explanations.

Optional Enhancements

Some skills detect and use optional tools at runtime. These are not required — skills work fine without them but gain extra capabilities when available.

GoodToGo (`gtg`)

Used by: pr-resolution

GoodToGo provides deterministic PR readiness detection. When installed, pr-resolution uses it to skip unnecessary work (READY → fast-path), route intelligently based on status (CI_FAILING vs ACTION_REQUIRED vs UNRESOLVED_THREADS), and gate completion with a final check.

pip install gtg

Uses your GitHub CLI auth automatically (gh auth token). No additional configuration needed.

API Keys (last30days)

Optional keys for expanded research capabilities:

# ~/.config/last30days/.env
OPENAI_API_KEY=sk-...    # enables Reddit research
XAI_API_KEY=xai-...      # enables X/Twitter research

Without these, last30days falls back to web-only research mode.

Code Quality Gate: /simplify

The built-in /simplify skill runs 3 parallel agents reviewing your code for reuse opportunities, quality issues, and efficiency problems. It's the highest-value review you can run -- but it's token-expensive (3 agents doing codebase-wide analysis), so use it intentionally rather than automatically.

Recommended approach: Add this to your global ~/.claude/CLAUDE.md:

## Code Quality Gate
- Before creating a PR or pushing code, run /simplify to review changes for reuse, quality, and efficiency

This runs one deep review pass on finalized code -- right before other humans see it. No hooks, no loops, no wasted tokens reviewing work-in-progress.

Why not auto-trigger on every stop? We tested a Stop hook that auto-ran /simplify after every code change. The tradeoffs weren't worth it: 3 agents spinning up per stop is expensive, it interrupts flow during iteration, and it reviews half-finished code. The PR boundary is the natural review point.

On-demand during a branch: Run /simplify manually whenever you've completed a significant chunk of work and want a sanity check. No need to wait for PR time if you want earlier feedback.

Hooks

The hooks/ directory contains session-start automation that keeps your Claude Code setup durable across plugin updates.

session-start-hook.ts

Runs on every session start. Currently patches the Superpowers code-reviewer template with a knowledge-lookup Step 0 that checks docs/solutions/ (Compound Engineering), .claude/learnings/ (project-specific notes), and ~/.claude/learnings/global-patterns.md (cross-project patterns) before reviewing any code.

Why a hook instead of a direct file edit: Superpowers stores its templates in versioned directories (~/.claude/plugins/cache/superpowers-marketplace/superpowers/4.3.1/). Each plugin update creates a new versioned directory with fresh files, silently dropping any direct edits. The session-start hook re-applies the patch on every session, so it survives updates automatically.

Installation:

# Copy hook to your Claude Code hooks directory
cp hooks/session-start-hook.ts ~/.claude/hooks/session-start-hook.ts

# Copy the Step 0 delta (canonical content that gets injected)
cp hooks/code-reviewer-step0.md ~/.claude/code-reviewer-step0.md

# Create the global cross-project patterns file
mkdir -p ~/.claude/learnings
touch ~/.claude/learnings/global-patterns.md

Then register the hook in ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bun ~/.claude/hooks/session-start-hook.ts"
          }
        ]
      }
    ]
  }
}

If bun is not in your PATH, use the absolute path from which bun (e.g. /Users/you/.bun/bin/bun).

If you already have a session-start-hook.ts, add just the patchCodeReviewer() function and its call from main() to your existing file.

code-reviewer-step0.md

The canonical content injected into the Superpowers code-reviewer template. Edit this file to change what the knowledge-lookup step does — the next session will apply the updated content to whatever plugin version is active.

Cross-project patterns

When you want a fix or invariant to show up in every project's code review, append a structured entry to ~/.claude/learnings/global-patterns.md. The session-start hook injects that file into the Superpowers code-reviewer Step 0 on each session.

Use a repeatable shape (one pattern per ## section, stable bullet labels) so Step 0 and reviewers can skim the file—same idea as dated notes under .claude/learnings/, but in one shared file:

## <short title> — <YYYY-MM-DD>
**Applies when:** …stack or workflow where this matters…
**Invariant:** …rule to enforce across projects…
**Avoid:** …anti-pattern or footgun…

Recommended Plugins

These Claude Code plugins pair well with fish-skills. They're not required, but they make your workflow significantly better.

Superpowers

Adds structured workflows for test-driven development, systematic debugging, parallel agent dispatch, git worktrees, code review, and plan execution. Teaches Claude to work more methodically instead of jumping straight to code.

claude plugins:add obra/superpowers

Episodic Memory

Gives Claude persistent memory across sessions. It indexes your conversation history so Claude can search past sessions for decisions, solutions, and context you've already discussed.

claude plugins:add obra/episodic-memory

After installing, start a new Claude Code session. Both plugins auto-register their skills and agents.

Architecture

fish-skills/
├── skills/
│   ├── ascii/                       # ASCII diagram generation
│   ├── audit-claude-md/             # CLAUDE.md best-practices audit
│   ├── ceo-briefing/                # Executive briefing generator
│   ├── clipboard/                   # macOS clipboard integration
│   ├── critic-review/               # Multi-model plan review (counselors dispatch)
│   ├── deepproduct/                 # UX/product research prompt builder
│   ├── deepstack/                   # Tech stack research prompt builder
│   ├── eos/                         # EOS router (requires skinnyandbald/ceos)
│   ├── finalize/                    # Feature cleanup before commit
│   ├── generate-comprehensive-style-guide/
│   ├── git-worktree/                # Worktree management
│   ├── handoff/                     # Session context transfer
│   ├── interview-me/                # Socratic idea refinement
│   ├── invoice/                     # PDF invoice generation
│   ├── last30days/                  # Trending topic research (separate repo)
│   ├── pr-resolution/               # PR comment resolution (parallel agents)
│   ├── process-meeting-notes/       # Fireflies → GitHub issues
│   ├── requirements-builder/        # Progressive requirements gathering
│   ├── review-style-guide/          # Style guide compliance check
│   ├── setup-ai/                    # AI dev environment onboarding
│   ├── shaping-skills/              # Basecamp-style shaping (separate repo)
│   ├── simplify-parallel/           # Parallel codebase simplification
│   ├── test/                        # Auto-detect + run + fix tests
│   ├── tests-new/                   # Add missing test coverage
│   ├── vercel-react-best-practices/ # React/Next.js optimization
│   ├── verify-worktree-plugins/     # Plugin patch verification
│   └── web-design-guidelines/       # Web UI compliance checker
├── hooks/                           # Session-start automation
└── README.md

Skill Anatomy

Every skill follows the same structure:

skill-name/
├── SKILL.md        # Required: YAML frontmatter + instructions
├── references/     # Optional: supporting docs referenced by SKILL.md
├── scripts/        # Optional: shell/TypeScript/Python scripts
├── bin/            # Optional: executable CLI tools
└── templates/      # Optional: output templates

The SKILL.md frontmatter controls how Claude Code runs the skill:

---
name: skill-name
description: One-line description
argument-hint: "[args]"       # shown in autocomplete
context: fork                 # fork = isolated context
agent: Explore                # agent type to handle execution
allowed-tools: Bash, Read...  # tool access whitelist
---

Prerequisites

Requirement	Used By	Notes
Claude Code	All skills	Host environment
GitHub CLI (`gh`)	pr-resolution, process-meeting-notes	Authenticated via `gh auth login`
Node.js + npm	counselors, critic-review	For `npm install -g @skinnyandbald/counselors`
Git	git-worktree, pr-resolution, simplify-parallel	Standard installation
Python 3	git-worktree, last30days	For scripts
Bash	git-worktree	Shell scripts

Built-in /simplify (Claude Code v2.1.63+)

Claude Code ships a built-in /simplify command that reviews recently changed files through 3 parallel agents (code reuse, quality, efficiency). No installation needed — it's available automatically.

/simplify-parallel from this repo complements it for codebase-wide sweeps where the built-in's diff-scoped approach may hit context limits. Each parallel worker uses the same three-lens review model.

Contributing

Fork the repository
Create a feature branch: git checkout -b feat/my-skill
Add your skill to skills/ as a directory with a SKILL.md
Submit a pull request

Skills must have a SKILL.md with valid YAML frontmatter. See Skill Anatomy for the required structure.

License

MIT

Name	analyze-plan-feedback
Description	Analyze and prioritize peer review feedback from multiple AI reviewers on a plan

analyze-plan-feedback

SKILL.md