core-workflow

commit skill — Stage, lint, and create a conventional commit

Automatically stages relevant files, runs shellcheck on changed .sh files, generates a conventional commit message in imperative mood with a Co-Authored-By trailer, and confirms the commit. Designed to make snapshotting working state cheap so debug rounds don't accumulate uncommitted regressions.

Invoke when the user says 'commit', 'save this', 'snapshot this state', or 'checkpoint' without specifying the commit message themselves. Skip if the user asked for push, PR open, or anything beyond local commit.

contribute skill — Push changes back to claude-skills repo

Drives the claude-skills-contribute script from any repo or machine. Captures state of a locally developed or modified skill, agent, hook, command, or plugin manifest, creates a feature branch, validates, commits with conventional message, and opens a PR for review.

Use when the user says 'contribute this back', 'add this to claude-skills', 'share this skill', or invokes the /contribute-skill command.

/team command — Evaluate if task fits agent-team mode

Evaluates whether the current (or specified) task warrants spawning a Claude Code agent team. Applies a four-criterion heuristic: ≥3 independent workstreams with non-overlapping file ownership; read-heavy work or disjoint write surfaces; >60% context window fill or competing hypotheses; and scope not capped to a quick fix.

Returns either a team proposal (with role and directory ownership per teammate) or a pushback with better-fit alternative. Never spawns without explicit user confirmation.

/contribute-skill command — CLI wrapper for contribute skill

Slash-command entry point to the contribute skill. Accepts optional flags: --skill <name> to scaffold a new skill; --message "<text>" for commit message and PR title; --no-pr to skip PR and push only; --auto-merge to squash-merge once CI passes (use sparingly).

Directly invokes the contribute skill with the given arguments.

image-parser agent — Analyze screenshots and images

Specialized subagent for image and screenshot analysis. Answers questions like 'what does this screenshot show', 'OCR the text', 'compare these two simulator screenshots', 'is the title cut off', 'extract the data table from this PNG'. Runs on Sonnet for cost efficiency.

Reads image files with the Read tool (content rendered visually), answers the specific question first, references UI elements concretely, flags uncertainty, and avoids fabrication. Common Paperix use case: check sheet titles, button labels, list item rendering, dark-mode contrast, PAS capsule presence.

web-researcher agent — API/framework lookups and doc research

Specialized subagent for web research and library documentation. Answers 'API behavior', 'framework changes', 'SDK syntax', 'version migration', 'what's the current way to do X in React/Django/etc'. Prefers Context7 for library docs, falls back to WebSearch and WebFetch.

Reads actual pages (doesn't trust snippets), stops early once confident, synthesizes with source URLs, and avoids speculation. Runs on Sonnet for cost.

shellcheck-on-edit hook — Auto-lint shell scripts after edits

PostToolUse hook that triggers automatically after any Edit or Write operation on a .sh file. Runs shellcheck and surfaces findings as non-blocking informational output. Complements the commit skill by catching shell script issues before they're committed.

Matches file paths ending in .sh; skips if shellcheck is not installed or file does not exist; always exits cleanly (non-blocking).

Commit automation and validation

The commit skill runs three read-only commands in parallel to gather context: git status (untracked and modified files), git diff (staged and unstaged changes), and git log --oneline -10 (recent commit style). Then sequentially, it lints changed .sh files using shellcheck, stages files by name (never using git add -A or . to avoid accidentally staging .env or build artifacts), generates a conventional commit message (title ≤72 chars, imperative mood, lowercase, optional body focused on why, Co-Authored-By trailer), commits via heredoc to preserve formatting, and confirms via git status. If shellcheck finds errors, it surfaces them and asks the user whether to proceed, enforcing awareness of known issues without blocking the commit.

Skill contribution workflow

The contribute skill wraps claude-skills-contribute, a script that operates on $CLAUDE_SKILLS_HOME (the claude-skills repo clone, not the user's current working directory). When invoked, it confirms the user's intent (capture live state vs. scaffold new skill), runs the contribute script with optional --skill <name> and --message arguments, captures the PR URL printed by gh, or returns the branch name if --no-pr was used. The script handles branch creation, validation, committing, and PR opening; Claude surfaces the result and, on offline work, tells the user the branch name for later manual push. Never runs with --auto-merge unless explicitly requested.

Agent-team evaluation heuristic

The /team command applies a four-criterion filter to determine if parallel multi-agent execution is justified. Criterion 1: ≥3 independent workstreams with non-overlapping file ownership (by directory, target, or review lens, not by feature within the same module). Criterion 2: Each workstream is read-heavy (research, investigation) or owns a disjoint write surface. Criterion 3: Serial execution would fill >60% of context window OR task involves competing hypotheses. Criterion 4: User has not capped scope to a quick fix. If all four hold, the command outputs a proposal block with role, directory ownership per teammate, and estimated cost (~3–4× single-session); on user confirmation, teammates spawn in parallel via Agent tool calls. If any criterion fails, it outputs a pushback block with the failing criterion and a better-fit alternative (single session, Explore subagent, plan mode, etc.).

PostToolUse hook pipeline for shellcheck

When Edit or Write is invoked, the Claude Code harness fires the PostToolUse hook. shellcheck-on-edit.sh receives the hook payload as JSON stdin, extracts the file_path from tool_input, checks if it matches *.sh, verifies the file exists, and confirms shellcheck is installed. If all checks pass, it runs shellcheck on the file and captures output; if shellcheck finds issues, output is printed to Claude as informational (non-blocking). Hook always exits 0 so it never fails the underlying edit operation; Claude sees the findings and decides whether to fix immediately or defer.

Image-parser and web-researcher subagent delegation

When Claude encounters an image-analysis question or a web-research task during development, it dispatches to a specialized subagent (image-parser or web-researcher, respectively) instead of answering from context. These agents receive the Read tool for file/image ingestion, run on Sonnet (lower cost than Opus), and return a focused answer: image-parser leads with yes/no or a side-by-side diff and flags blurry/occluded content; web-researcher prefers Context7 for library docs and WebSearch/WebFetch for other research, synthesizes with source URLs, and stops once confident. Both agents are read-only (no code edits) and avoid speculation beyond what sources say. Dispatcher then integrates the subagent's answer into the main conversation.