          /`·.¸
         /¸...¸`:·
     ¸.·´  ¸   `·.¸.·´)
    : © ):´;      ¸  {    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

Submodule skills (community contributions) aren't included in the main repo install — add them separately:

npx skills add aarondfrancis/counselors     # Fan-out to multiple AI agents
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, or want everything including submodule skills in one clone:

git clone --recursive https://github.com/skinnyandbald/fish-skills.git ~/code/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 ~/code/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 ~/code/fish-skills/skills/pr-resolution ~/.claude/skills/pr-resolution
ln -s ~/code/fish-skills/skills/simplify-parallel ~/.claude/skills/simplify-parallel

Install into a specific project:

cd ~/my-project
mkdir -p .claude/skills
ln -s ~/code/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`
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

Skills not listed above (setup-ai, git-worktree, capture-learning, last30days, web-design-guidelines, vercel-react-best-practices, critic-review, simplify-parallel) work with no additional setup beyond the dependencies 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)

Development Workflow

Skill	Command	Description
setup-ai	`/setup-ai [--global\|--project\|--check]`	Configure Claude Code for power-user AI development (hooks, plugins, CLAUDE.md)
git-worktree	`/git-worktree [cmd] [args]`	Manage Git worktrees for isolated parallel development
capture-learning	`/capture-learning`	Capture problem-solving narratives as structured learnings
handoff	`/handoff`	Generate or resume from structured session handoffs for seamless context transfer between Claude Code sessions

Planning & Review

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

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.

Research & Knowledge

Skill	Command	Description
last30days	`/last30days [topic]`	Research trending topics from Reddit, X, and the web
process-meeting-notes	`/process-meeting-notes`	Process Fireflies transcripts into action items and GitHub issues

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)

Requires Fireflies MCP integration in Claude Code.

capture-learning

Capture problem-solving narratives with a 6-element structure:

The Problem
Initial Assumption
Actual Reality
Troubleshooting Journey
The Solution
The Takeaway

Saves to <project-root>/.claude/learnings/YYYY-MM-DD-problem-description.md. Falls back to ~/.claude/learnings/ if not in a git repo. Trigger with phrases like "Great job, log this" or "Capture this learning".

After saving, optionally promotes the learning to ~/.claude/learnings/global-patterns.md — a cross-project knowledge store that the Superpowers code-reviewer checks on every review (see Hooks).

Setup: Add this to your project's CLAUDE.md so Claude reads past learnings and captures new ones:

## Learnings
Before starting work, check `.claude/learnings/` for relevant past
problem-solving narratives. Apply those lessons instead of repeating
mistakes.

**IMPORTANT:** After solving any non-trivial debugging session or
discovering something that contradicts an initial assumption, invoke
`/capture-learning` before moving on. Do not skip this step.

The .claude/learnings/ directory is created automatically on first capture. Without the CLAUDE.md snippet, Claude won't check for existing learnings or know to capture new ones.

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/ (capture-learning), 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

After solving a non-trivial bug, run /capture-learning. At the end it asks "Promote to global cross-project patterns?" — say yes and it appends a structured entry to ~/.claude/learnings/global-patterns.md. The session-start hook ensures every future code review (in any project) sees these patterns.

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. Pairs especially well with /capture-learning — learnings you capture become searchable knowledge.

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/                          # All skills (directories with SKILL.md)
│   ├── capture-learning/            # Problem-solving narrative capture
│   │   ├── SKILL.md
│   │   └── scripts/
│   ├── critic-review/               # Unified plan review (stack, Context7, counselors dispatch)
│   │   └── SKILL.md
│   ├── eos/                         # EOS operating system router (requires skinnyandbald/ceos)
│   │   └── SKILL.md
│   ├── handoff/                     # Session context transfer
│   │   └── SKILL.md
│   ├── git-worktree/                # Worktree management
│   │   ├── SKILL.md
│   │   └── scripts/
│   ├── last30days/                  # Trending topic research (submodule)
│   │   └── ...
│   ├── pr-resolution/               # PR comment resolution (v3, parallel agents)
│   │   ├── SKILL.md
│   │   ├── bin/
│   │   └── references/
│   ├── process-meeting-notes/       # Fireflies → GitHub issues
│   │   ├── SKILL.md
│   │   ├── references/
│   │   ├── templates/
│   │   └── workflows/
│   ├── setup-ai/                    # AI dev environment setup & audit
│   │   └── SKILL.md
│   ├── simplify-parallel/           # Parallel codebase simplification (complements built-in /simplify)
│   │   ├── SKILL.md
│   │   ├── analyze.md
│   │   └── orchestrator.md
│   ├── vercel-react-best-practices/ # React/Next.js optimization
│   │   ├── SKILL.md
│   │   ├── AGENTS.md
│   │   └── rules/
│   └── web-design-guidelines/       # Web UI compliance checker
│       └── SKILL.md
└── 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`
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	simplify
Description	Run code-simplifier on current branch/PR changes to show a cleaned-up version

simplify

SKILL.md