Skull

Restructure frontend code so it's testable, predictable, and correctly layered — without changing behavior. Pull pure logic out of framework glue, fix reactivity anti-patterns (derived state synced by a watcher/effect, logic in the view, effects with no cleanup, unstable list keys), name and place extractions right (util vs helper vs colocated), and keep the base ← common ← feature dependency one-way. Triggers on "refactor this component", "logic in the template/JSX", "this is hard to test", "watch/useEffect misused", "component does too much", "where does this helper go". Vue & React.

Find and fix hardcoded design values that bypass the design system — raw hex/rgb/hsl colors, arbitrary Tailwind classes like `bg-[#1f2432]`, inline-style colors, and magic spacing/radius/shadow — and route each through a token. Triggers on "remove hardcoded colors", "use our design tokens", "enforce the design system", "why isn't dark mode working here", or a linter flagging arbitrary values. Complements `fe-design-system` (which defines the tokens); this enforces their use.

Test frontend UI code the way it should be tested — risk-scored per file (P0–P3), behavior-not-implementation, boundary-only mocking, and the minimum valuable set. Covers components, composables/hooks, stores, forms, and SSR/hydration safety using the project's own runner (Vitest/Jest + Testing Library / Vue Test Utils, Playwright for E2E). Triggers on "test this component/page", "frontend/Vue/React/Nuxt tests", "component/composable/store tests", "why is this test flaky", "should this be an E2E?". Not for non-UI logic (use test-code) or outside-in black-box QA (use test-blackbox).

Capture the *why* after a change — the non-obvious knowledge a future developer or agent can't recover by reading the code: hidden constraints, business rules, rejected alternatives, edge-case guards, invisible API contracts, and what silently breaks if the code changes. Triggers on "document this", "write docs for what we built", "capture why this exists", "document the constraints/decisions", "preserve this for future devs" — after a feature, refactor, or bug fix. NOT for README, API docs, code comments, or CHANGELOG — only the knowledge the code can't tell you.

The SKULL leader/conductor. Triggers on "skull", "set up skull", "mc setup", "onboard me", "build my team", "what's new", or when starting work in a new/unfamiliar project. It interviews you (grill-me), maps the project, then assembles a tailored team from the installed skills and agents — Sentinel the project cartographer plus planning, review, understanding, guardrail and security specialists — and runs it on your work. It builds the best `.claude/` workspace per project, delegates to parallel subagents (choosing the right model per agent), brainstorms hard and decides fast, keeps a complete view of every installed capability, keeps itself and you current with the newest Claude Code features, and proactively offers the right tool the moment a need shows up.

Drive a full QA pass on any project as a SKULL-led tester team — user-end, black-box, code, and stress/load — then emit a charted skull.html status dashboard. Triggers on "test everything", "QA this", "full test pass", "is it ready to ship", "pre-release check", "the app has no tests", "test this app end to end". Not for a single unit test (use cap-tdd) or a security audit (use wf-security-audit).

Generate and edit Microsoft Office files — Word, Excel, PowerPoint — when the deliverable is a document, not code. Triggers on "make a Word doc", "generate an Excel report", "build a spreadsheet with formulas or charts", "create a deck or slides", "fill a docx template". Reaches for python-docx and docxtpl (templated documents), openpyxl and XlsxWriter (spreadsheets with real formulas, styling, charts), and python-pptx (slides from data). Prefers templating over hand-building; keeps numbers as live formulas, not strings.

Create, fill, and extract PDFs — when the deliverable is a PDF, not code. Triggers on "generate a PDF", "make a report or invoice PDF", "fill this PDF form", "extract text or tables from a PDF", "HTML to PDF". Picks the right engine: WeasyPrint or headless Chromium for styled HTML-to-PDF reports, ReportLab for programmatic layout, pypdf for form-filling and merge/split, pdfplumber or PyMuPDF for text/table extraction. Keeps output selectable, styled, and accessible — never a page of rasterized text.

SKULL's tool advisor — "Welcome to the Secret Shop! Ho ho!" Scans the project and recommends the right EXTERNAL third-party tools for THIS codebase: graphify + caveman for token economy, Context7 / CodeGraph / Serena for big-repo retrieval, RTK for log compression, Tokscale for cost tracking, Presidio for PII. It hands you the exact install command, records what you install to `.skull/tools.json`, and then prefers those tools in later work. Triggers on "recommend tools", "what tools should I use", "the secret shop", "set up my tooling", "this is getting expensive / token cost", "big repo is slow to navigate", "we send user data to a model", or when a project signal matches a registered tool. Reads `registry.json`. Never auto-installs — it recommends and lets you run the command; installs stay permissioned and explicit.

Review UI before you ship it, like a picky designer. Triggers on "review this UI / page / component", "does this look good / professional", "is this accessible", before merging frontend work, or after building any interface. Returns findings labeled blocker / major / minor with the fix — across visual hierarchy, spacing, contrast & a11y, responsive behavior, interaction states, and consistency with the design system.

Set the design foundation before building any UI, so the output looks designed, not default. Triggers when starting a new frontend, a redesign, a landing page, or a component library, and on "make it look good/professional", "it looks generic / like Bootstrap / AI-generated", or any UI work with no established visual system. Establish or detect design tokens (color, type scale, spacing, radius, shadow, motion), a font pairing, and a component vocabulary — reusing shadcn/Radix/Tailwind conventions — before writing components.

Design intelligence — the concrete picks, not just the taste. Queries a local database of product types, color palettes, UI styles, font pairings and UX rules, and returns an actual design system: real hex tokens, a named style, a font pairing, decision rules and the anti-patterns to avoid. Triggers at the START of any UI work — a new page, app, landing page, redesign, component library — and on "what colors / font / style should this use", "make it look designed, not generic", or "it looks AI-generated". Persists the result to .skull/design/MASTER.md so every later session builds the same product.

Decide what to build before deciding how it looks. Triggers on a new product, feature or redesign, on "who is this for", "what should this screen do", "users are confused / churning / not converting", on vague briefs ("make a dashboard"), and before any information-architecture or navigation decision. Produces the user, the job-to-be-done, the primary flow, and the one thing each screen must accomplish — the brief the rest of the design team builds against.

Continuity across long sessions. Snapshots in-progress work before context compaction and restores it after, and nudges auto-compaction toward a natural breakpoint so nothing important is lost mid-task.

The guardrail switchboard. Triggers on "which guardrails are on?", "turn on / turn off <guardrail>", "set up guardrails for this project", or when a guardrail keeps firing and the developer wants it quieter. Records the choice in .claude/skull.json so it survives the session; the leader honours it.

Stay current with Claude Code and Claude itself. Triggers on "what's new", "what can Claude Code do now", "is there a newer/better way", "update skull", "which model should I use", or before relying on any claim about a Claude Code feature, model, price, or limit. Checks the installed version, the live changelog, and the harness surface SKULL depends on — then reports only the deltas that matter for this project.

Design a custom Claude Code status line for a CLI user — the bar under the prompt that can show model, branch, context budget, cost and time in their colors. Triggers on "status line", "statusline", "status bar", "/statusline", "customize my terminal / CLI / prompt", "make my terminal show <model/branch/cost/ context>", or wanting a sharper Claude Code setup. Opt-in and gated: confirm it's a terminal session and that they actually want one before spending a single token designing it — never push it.

Author a great SKULL skill (or sharpen one). Triggers on "write a skill", "add a skill", "create a skill", "make this a skill", "improve this skill's triggering", or when turning a repeatable methodology into a reusable `.md`. Covers the SKILL.md shape, the trigger-only description that actually fires, keeping it focused, crediting borrowed techniques, and the stay-in-sync checklist so the leader, docs and site all learn about it.

Know which environment you are standing in before you touch anything. Triggers on starting work on a server, "is this prod?", "which environment is this", before any deploy, migration, restart or seed, and the moment you ssh into a box you didn't just provision. Writes the verdict to `.skull/env` so every other ops skill can key off it.

Incident commander for a production emergency. Triggers on "prod is down", "we're seeing 500s", users who can't log in, check out, or load the page, an alert firing, a pager going off, or "the site is slow" in a production context. Stabilizes first, diagnoses second, and keeps a timeline — the advisor, never the one typing on the prod box.

Read the system's own story before you touch it — logs, metrics, health, recent deploys, error rates. Triggers on "why is it slow", "what's happening on the server", "check the logs", "is it healthy", and as the first step of `ops-incident`. Read-only toward the system: it gathers evidence and files findings, it never mutates the box.

The blameless post-mortem that closes the loop after an incident. Triggers on "post-mortem", "how did this happen", "how do we prevent this", a retro after any outage, or a failure that has now recurred. Turns a timeline into contributing causes, action items with owners, and one concrete artifact that would have caught it — built, not admired.

The pre-deploy gate. Triggers on "deploy", "ship it", "release", "cut a release", "push to prod", "roll it out", or editing a CI or deploy config. Produces a deploy brief with five required slots and a tagged release — or it refuses to call the deploy ready.

Curate the model's context window for the most signal per token — stop burning tokens on bloat. Triggers on "context engineering", "burning tokens", "context window full", "reduce token usage", "the model lost the thread", "too much in context", "prompt caching", "session handoff", or any long / expensive session. The discipline of deciding what goes in the window (and what doesn't): cache-stable instructions, retrieve don't dump, fresh docs at query time, audit your MCPs, compress tool output, and measure tokens like an infra cost.

Run the team across SEPARATE, parallel Claude Code sessions for real throughput — beyond in-session subagents. Triggers on "make it faster", "too slow", "parallelize", "run the team in separate sessions", "fan out", "background agents", "agent teams", "run several at once", or a big batch of independent work. The leader decomposes the job into independent chunks, dispatches each to its own session (true OS-level parallelism), monitors, and integrates — with hard guardrails on cost and isolation, because N parallel sessions burn usage N× and editing the same files in parallel causes merge hell.

How SKULL picks the right model for each agent and task. Triggers on "which model", "pick a model", "model selection", "use haiku/sonnet/opus", "cheaper model", "model per agent", or whenever spawning a subagent/team and choosing its model, or optimizing cost vs. quality on a long run. Gives a role→model heuristic, the "turn count beats token price" rule, the effort dial, and the cost math so the team is both strong where it matters and cheap where it doesn't.

The git mechanics SKULL runs by default — invoked by the leader, not auto-triggered. Covers session awareness (branch, dirty count, ahead/behind), branch-before-you-build (mc/<slug>, never the default branch), commit at every green step (conventional, Fixes #N), a WIP commit before risky bash, finishing a branch (PR/merge/delete), worktrees for parallel writers, and the bright line: local git aggressive by default, remote git always consented, never auto-push. The off switch lives in .claude/skull.json.

How SKULL delegates work to subagents and teams. Triggers on "delegate", "spawn agents", "parallel agents", "fan out", "run these in parallel", "subagent", "orchestrate", "build a team for this", or whenever a task splits into independent chunks, needs a fresh-eyes review, or means reading many files. Teaches the orchestrator-worker pattern: pick the right primitive (subagent vs agent-team vs background session), write a complete delegation brief, parallelize only when it pays, scale effort to the task, and verify with an adversarial reviewer. Use to plan and run any multi-agent push.

How SKULL builds the best Claude Code workspace for a project. Triggers on "set up my workspace", "configure .claude", "CLAUDE.md", "what should this project have", "make this project Claude-ready", "best setup for this repo", or at the start of working in any project. Decides what each project's .claude/ should contain — a lean CLAUDE.md, the right skills/agents/settings/hooks/MCP, tuned to the stack and goal, with a real verification path — and avoids the bloat that makes Claude ignore half its own config.

Brainstorm an idea, problem, or design as a sharp thinking partner — diverge wide, then converge on a decision. Triggers on "brainstorm", "ideate", "what should we build", "explore options/approaches", "help me think through", or before any open-ended design/architecture choice. One question at a time, many genuinely different options (not the first idea), then a recommended call with the runner-up and what would change it. Ends with a written artifact, not just chat.

Drive an approved plan or spec to done — supervised, one verified step at a time. Triggers on "execute the plan", "work the backlog", "build it from the plan/spec", "implement this plan", or right after cap-plan-first / cap-decomposer / grill-me produced a plan. Works the tasks in order, verifies each (build/tests) before moving on, checkpoints with you at the risky/irreversible steps, and keeps a progress trail. You stay in the loop the whole way, verifying each step.

Turn an approved spec + decomposition into a precise, zero-context implementation plan document that another engineer (or a fresh subagent) can execute with no prior knowledge. Triggers on "write the plan", "write an implementation plan", "turn this spec into a plan", or after grill-me/cap-spec-smith + cap-decomposer have produced a spec and a step list, before any code. Each task carries exact file paths, interface contracts, real test code, exact commands and their expected output — no placeholders. The plan is the contract; cap-execute-plan (or parallel subagents) runs it.

Relentlessly interview the user with sharp clarifying questions to fully specify a vague or ambiguous request before building anything. Use when requirements are unclear, when the user types "grillme" or asks to be grilled/interviewed, or before any non-trivial implementation where scope, constraints, data shapes, edge cases, or success criteria are underspecified.

Generate skull.html — a self-contained, CLI-styled, professional, charted dashboard at the project root showing SKULL's team and its findings for THIS project (test results, coverage, audit/map findings), led by SKULL. Triggers on "make the dashboard", "skull.html", "show the project status", "generate the team report", or as the final step of wf-tester. A local artifact — never published to any website.

Test a deployed surface from the outside as a black box — no source, no test hooks: functional smoke, visual regression, accessibility (axe), performance (Lighthouse), SEO, PWA (manifest/service worker/offline), broken links, and console/network errors. Triggers on "black-box test", "test the live site", "check the deployed app", "lighthouse/a11y/seo audit of the site". Not for unit tests.

Test at the code level — unit and integration tests, coverage of the critical paths, and test-first (TDD) discipline for new work — reusing the project's own test runner. Triggers on "add tests", "increase coverage", "unit/integration tests", "TDD", "the code has no tests", "test this function/module". Not for outside-in UI checks (use test-blackbox) or load (use test-stress).

Load, stress, spike, and soak testing — find where a service bends or breaks under pressure and where latency/error rates cross the line. Uses k6 (scriptable, low-overhead). Triggers on "load test", "stress test", "how much traffic can it handle", "test under pressure", "spike/soak test", "will it hold up at launch". Not for single-user functional checks (use test-blackbox/test-user-end).

Build a ranked, token-budgeted map of the codebase — the top files and their key symbols, ranked by how referenced they are — so you navigate to the right 3 files instead of reading 30. Triggers on "map the repo", "where is X", "how is this codebase laid out", "lay of the land", "I'm new to this repo", or at the start of work in a large/unfamiliar project. A zero-dependency repo-map (Glob + Grep + reference counts) that approximates a code graph; complements Sentinel's architectural map and saves tokens.

Turn the team's findings into GitHub issues, and keep them in sync. Triggers on "file these as issues", "sync findings", "open issues for the security review / the QA run / Sentinel", "close the fixed ones", or after a sweep/audit that produced findings. Local finding files stay the source of truth; issues are the human surface. Security findings on a public repo are held back by default.

Run a full design pass over a product — establish who it's for, generate and persist a real design system, rebuild the UI against it, then review front-to-back and report what changed. Use when a whole frontend needs to go from generic to designed: a redesign, a pre-launch polish, "make this look professional", "our UI looks AI-generated", or a new product with no visual system. For one page or one component, use the focused fe-* skill instead.