Sontek Skills

Use `uv` instead of `pip` / `python` / `venv` for Python work in repos that have adopted uv. Use when running Python scripts (`uv run`), adding dependencies (`uv add`), creating standalone scripts with inline dependency metadata (`uv init --script`), or managing the Python build backend (`uv_build`). Triggered by mentions of `uv`, inline script metadata blocks (`# /// script ... ///`), `uv.lock`, `pyproject.toml` with `[tool.uv]`, or any Python script Claude is about to run in a uv project.

Explain a topic, module, decision, or incident as if the reader knows nothing about it, then publish the explanation as a big-picture, few-words HTML Artifact. This is the default way to answer a request for a plain-language explanation. Use for "/eli5", "eli5 this", "explain like I'm 5/five", "explain this simply", "give/provide me a simple explanation", "explain how this works", "explain why we did this", "what caused this", or any other request to explain a module, decision, tradeoff, or incident in plain terms. Not for a request that explicitly wants technical depth ("deep dive", "explain in detail", "walk me through the implementation") or a task that isn't an explanation request at all (review, fix, write code).

Diagnose bugs scientifically: reproduce, form a hypothesis, run a falsifying experiment, identify the root cause, then fix it and add a regression test. Use for "debug this", "why isn't this working?", flaky/intermittent failures, "can't reproduce", or "find the root cause". Unlike fix-issue, debug is for cases where the cause is not yet known.

ALWAYS use this skill when committing code changes — never commit directly without it. Creates commits following conventional commit format with proper issue references and clean, scoped messages. Trigger on any commit, git commit, save changes, or commit message task.

Fetch and analyze Sentry data — issues (grouped errors), events (individual occurrences with stack traces and breadcrumbs), transactions, and logs. Use when the user asks to "look at Sentry", "fetch this Sentry issue", "find errors in Sentry", "search Sentry events", "what happened in Sentry around <time>", "get the latest event for issue X", or wants Claude to investigate a production error using Sentry data. Authenticates via `~/.sentryclirc`. Composes with review-code / iterate-pr (e.g., debug a Sentry issue, then produce a fix PR).

Interview the user to resolve ambiguity in a request, plan, or design before committing to work — one targeted question at a time until intent, scope, and constraints are pinned down. Use when a request is underspecified, could have multiple valid interpretations, hides a false premise, or the user wants to stress-test a plan. Triggers on "clarify this", "grill me", "stress-test my plan", "get grilled on my design", "what am I missing", or any request vague enough that proceeding would mean guessing. Pairs with plan-implementation for pre-planning requirements clarification.

Write a structured handoff document so a fresh Claude Code session can continue the current work without re-reading the entire transcript. Use when asked to "hand off", "handoff", run "/handoff", prepare for a "/clear", start a fresh session without losing context, or save the current conversation's state for a future session. Produces a local `HANDOFF_<slug>.md` (or `/tmp/HANDOFF_<slug>.md` outside a repo) that the user pastes or opens in the new session.

ALWAYS use this skill when creating or updating pull requests — never create or edit a PR directly without it. Follows conventional PR title format, respects repo PR templates when present, and produces concise descriptions focused on what and why. Trigger on any create PR, open PR, submit PR, make PR, update PR title, update PR description, edit PR, push and create PR, or prepare changes for review task.

Implement a fix for a bug, issue, or failing behavior from scratch, reproduce-first. Use when asked to "fix this bug", "fix this issue", "resolve

Cache and refresh remote git repositories under `~/.cache/checkouts/<host>/<org>/<repo>` so future references reuse a local copy instead of re-cloning. Use when the user references a remote git repository — full URL (`https://github.com/foo/bar`, `git@github.com:foo/bar.git`), `owner/repo` shorthand, or asks Claude to "look at", "read", "search", or "find something in" an external repo by name. Returns a stable local path that downstream skills (review-code, grep, Read) can use directly.

Review a PR or branch with specialized reviewers and propose concise, deduplicated comments. Use for "review this PR", "full PR review", "give me review comments", multi-agent review, or self-review/merge-readiness. Propose-only: never edit or post without approval. Use review-code for a focused pass, auto-review-code for fixes, and iterate-pr for CI/feedback.

Iterate on a PR until CI passes. Use when you need to fix CI failures, address review feedback, or continuously push fixes until all checks are green. Automates the feedback-fix-push-wait cycle.

Run a multi-reviewer audit of your own branch, diff, or explicit paths and return a prioritized, deduplicated report on correctness, security, performance, design, and tests. Use for "review my changes", "review this branch/diff", "find bugs", or "audit these files". Use review-pr for others' PRs, auto-review-code to apply fixes, and review-plan for plans.

General application performance review for non-Django code (Flask, FastAPI, Go, Node, generic Python). Use when asked to "review performance", "audit performance", "find slow code", "perf review", or audit app-tier code for blocking I/O on async paths, algorithmic blow-ups, per-item network loops, unbounded memory accumulation, or missing application caching. Find-only — use `optimize-perf` to apply fixes with benchmarks. Covers the application surface that `review-django-perf` (Django ORM) and `sql-reviewer` (raw SQL / migrations) do not. Validation-first — no flag without traced evidence.

Review a plan for architectural, DRY, scope, and UX concerns before implementation starts. Covers IMPLEMENTATION_PLAN_*.md / REFACTOR_PLAN_*.md files AND in-conversation plans drafted in Claude Code plan mode (ExitPlanMode) or inline messages. Use when user asks to "review the plan", "analyze the plan", "critique the plan", "is this plan good", or wants a senior engineer / product manager pass over a planning document. For creating a plan from scratch use plan-implementation or plan-refactor. For reviewing code or a PR use review-code.

Write, rewrite, or review project prose so it is clear, controlled, human, and free of AI-style filler. Use for docs, READMEs, PR text, review comments, commit messages, errors, release notes, "make this not sound like AI", tone review, de-slopping, or STE checks. Not for persuasive marketing, essays, chat, or sales copy.

Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill. Also covers when to ship a capability as an agent instead of a skill.

Audit existing skills (SKILL.md files) against the write-skill authoring rubric — frontmatter validity, description trigger coverage, structural size, detection-rule over-fit, reference resolution, intra-skill cross-references. Use when reviewing a newly written skill, checking skill quality before merge, evaluating refactored or consolidated skills, or running a compliance pass over the skill plugin. Outputs findings classified as real gaps, observations, or pre-existing issues, each with a concrete recommended fix.

Create git branches following naming conventions. Use when creating new feature branches, bug fix branches, or any branch for development work. Defines the branch naming standards used across commit and PR skills.

Apply performance improvements with before/after benchmarks. Use when asked to "optimize this", "make it faster", "speed this up", "profile and fix", or when the user wants perf fixes applied (not just reviewed). Runs `review-perf` to find candidates, then for each fix writes a benchmark, applies the change, re-measures, and reverts on regression. Companion to `review-perf` (which only finds issues); distinct from `auto-review-code` (which applies generic fixes without wall-clock measurement).

Create a local REFACTOR_PLAN_<name>.md through a user interview, decomposing behavior-preserving restructuring into tiny commits. Use for "plan a refactor", "restructure this code", "extract a module", or tiny-commit refactor planning. Use plan-implementation for NEW features or phased additions, and review-plan for an existing plan-mode draft.

Review EXISTING code at module/package scope for coupling, abstraction depth, seams, testability, and scalability; return a verdict and prioritized concerns. Use for "design review this module", "is this too coupled?", or "will this scale?". Use review-code for diff defects, review-plan for plan documents, and improve-architecture for codebase-wide redesign ideas.

Review changed code for AI-generated slop and apply fixes. Use when the user says "simplify", "clean this up", "deslop", "tidy up", or after AI-generated code lands. Fans out to focused code-quality lane detectives (comments, structure, typing, complexity, defensive), coalesces their findings, and applies the safe ones.

Design and implement distinctive, production-ready frontend interfaces with strong aesthetic direction. Use when the user asks to "design a landing page", "redesign this UI", "improve the visual design", "make this look better", "build a marketing page", "design a dashboard", "restyle this component", or wants a greenfield FE design with character — not a generic AI-default UI. Pushes Claude to commit to a single bold aesthetic (brutalist / editorial / luxury / retro-futuristic / etc.) instead of producing the same gradient-and-Inter UI every time.

Security code review for vulnerabilities. Use when asked to "review security", "security review", "find vulnerabilities", "check for security issues", "audit security", "OWASP review", or review code for injection, XSS, authentication, authorization, cryptography issues. Provides systematic review with confidence-based reporting.

Use this skill when the user asks to "write AGENTS.md", "create AGENTS.md", "update AGENTS.md", "maintain agent docs", "set up CLAUDE.md", or needs to keep agent instructions concise. Enforces research-backed best practices for minimal, high-signal agent documentation.

Automatically iterate review-code and code-simplifier until no more safe fixes remain. Use when user wants to "auto-review-code", "auto-fix", run review-and-simplify on repeat, or clean up code without staying in the loop for each finding. Auto-applies local, low-risk fixes; batches risky changes for a single end-of-run approval pass.

Automatically iterate review-plan against a plan until no safe blocking edits remain. Use when user wants to "auto-review-plan", "auto-fix the plan", tighten a plan without staying in the loop for each finding, or harden an `IMPLEMENTATION_PLAN_*.md` / `REFACTOR_PLAN_*.md` / plan-mode draft before implementation. Auto-applies small, concrete blocking edits; batches structural recommendations for a single end-of-run approval pass.

Collaborate in a live Hunk diff-review session: address the user's inline hunk notes, or walk through a changeset by steering the view and adding explanations. Use for "address my Hunk notes", "fix what I flagged", or "walk me through this diff". Unlike review-code/review-pr, this is interactive; unlike auto-review-code, it keeps the user in the loop.

Update `CHANGELOG.md` (or `CHANGELOG`) with notable user-facing changes since the last release tag. Use when the user asks to "update the changelog", "update CHANGELOG.md", "write release notes", "prepare release notes", or "add unreleased entries". Adds entries to the `## Unreleased` section, preserves existing format, and filters out trivial commits (typo fixes, internal refactors, dependency bumps without security impact).

Draft or polish a sales/GTM email in John Anderson's voice as Founder of Drape — the CI Brain, a CI reliability platform. Use when writing, improving, or formatting an outbound, prospect-facing, or customer email given a goal, topic, recipient context, rough draft, or bullet points. Applies Drape's brand voice and a Win Without Pitching posture. Works for non-sales email too, with the sales posture relaxed. Family: sales-email-draft / sales-email-prospect / sales-email-followup / sales-email-reply.

Draft a reply to a forwarded email thread in John Anderson's voice as Founder of Drape — the CI Brain, a CI reliability platform. Use when the user pastes an email thread and wants a response drafted, optionally with instructions on tone, stance, or what to address. Applies a Win Without Pitching posture for sales-adjacent threads. Family: sales-email-draft / sales-email-prospect / sales-email-followup / sales-email-reply.

Create and validate customer- or support-facing AWS/cloud infrastructure diagrams in Mermaid. Use for "draw an infra diagram", "AWS architecture diagram", cloud flows, or debugging maps. Adds AWS shapes, colors, region tinting, legends, DLQ styling, edge labels, resource checks, and PDF export. Use draw-mermaid-diagram for other diagrams.

Django performance code review. Use when asked to "review Django performance", "find N+1 queries", "optimize Django", "check queryset performance", "database performance", "Django ORM issues", or audit Django code for performance problems.

Create a local IMPLEMENTATION_PLAN_<feature>.md for NEW features, complex additions, or multi-phase work, with reconnaissance, binary ideal-state criteria, premortem, phases, and quality gates. Use for "create an implementation plan". Use plan-refactor for behavior-preserving restructuring, and review-plan for an existing plan-mode draft.

GitHub Actions security review for workflow exploitation vulnerabilities. Use when asked to "review GitHub Actions", "audit workflows", "check CI security", "GHA security", "workflow security review", or review .github/workflows/ for pwn requests, expression injection, credential theft, and supply chain attacks. Exploitation-focused with concrete PoC scenarios.

Create and validate Mermaid flowcharts, sequence, class, ER, state, gantt, journey, timeline, mindmap, and pie diagrams. Use for "draw a Mermaid diagram", "draw a sequence/state/ER/class diagram", "make a flowchart", or a non-infrastructure flow. Use draw-infra-diagram for AWS/cloud architecture with specialized shapes and debugging composition.

Explore a codebase to find opportunities for architectural improvement, focusing on making the codebase more testable by deepening shallow modules. Use when user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more AI-navigable.

Django access control and IDOR security review. Use when reviewing Django views, DRF viewsets, ORM queries, or any Python/Django code handling user authorization. Trigger keywords: "IDOR", "access control", "authorization", "Django permissions", "object permissions", "tenant isolation", "broken access".

Draft a post-meeting follow-up email in John Anderson's voice as Founder of Drape — the CI Brain, a CI reliability platform — grounded in the actual meeting notes from Google Docs (Google Drive). Use when sending a follow-up after a call or meeting; pulls the notes doc so the email is specific, not boilerplate. Applies a Win Without Pitching posture and the Four Conversations model. Family: sales-email-draft / sales-email-prospect / sales-email-followup / sales-email-reply.

Draft a prospecting or outreach email in John Anderson's voice as Founder of Drape — the CI Brain, a CI reliability platform. Use when reaching out to a lead, prospect, or existing contact, given their name, company, role, and any context you provide. Sells from expertise with a direct, confident ask for an intro meeting; consultative, not pushy. Family: sales-email-draft / sales-email-prospect / sales-email-followup / sales-email-reply.

Generate a high-level architecture document for a module, service, or codebase using 4 parallel Explore sub-agents (data, API/interface, business logic, integrations). Composes with `draw-mermaid-diagram` and `draw-infra-diagram` to embed validated diagrams. Use when asked to "document this codebase", "write architecture docs", "create an arch doc", "generate onboarding docs", "document this service", "map this module". Output is a single Markdown file optimized for human onboarding, not LLM context.