skills

Adversarially hunt for correctness bugs and regressions in a change set. Use when reviewing a diff before finalizing, during a cleanup pass, or when asked to find bugs, pressure-test, or stress-test recently modified code. Triggers on: "find bugs", "what could break", "review for correctness", "did I break anything", "hunt regressions", "adversarial review", "pressure-test this change".

End-of-session cleanup pass for Swift code. Use this skill whenever the user asks to "clean up", "polish", "tidy", "refactor", or "review" Swift work at the end of a coding session, or when they invoke this skill by name. Performs a holistic review of files modified during the session — simplification, type-driven design, macOS conventions, and comment hygiene. Make sure to use this skill anytime the user signals they want to wrap up or finalize Swift work, even if they don't explicitly say "cleanup". Do NOT use for one-off edits, bug fixes, or active feature work.

End-of-session cleanup pass for TypeScript, React, and web code. Use this skill whenever the user asks to "clean up", "polish", "tidy", "refactor", or "review" web/frontend work at the end of a coding session, or when they invoke this skill by name. Performs a holistic review of files modified during the session — simplification, type safety, React patterns, CSS modernization, and comment hygiene. Make sure to use this skill anytime the user signals they want to wrap up or finalize TypeScript/React/web work, even if they don't explicitly say "cleanup". Do NOT use for one-off edits, bug fixes, or active feature work.

Simplify and refine recently modified code for clarity and consistency. Use after writing or modifying code, during cleanup passes, or when asked to simplify/refactor without changing behavior.

Pull PR review comments and triage them — separate substantive feedback from bikeshedding, stale comments, misreads, AI slop, and other noise. Use this skill whenever the user asks to "review my PR comments", "triage feedback", "go through my PR", or wants help deciding what to address vs push back on. Make sure to use this skill anytime the user mentions PR comments or code review feedback, even if they don't explicitly say "triage". Pulls comments via the `gh` CLI, classifies each, and proposes an action with a draft response. Do NOT use for writing PR descriptions, reviewing someone else's PR, or applying the changes — this skill triages and drafts only.

The 23 Gang of Four object-oriented design patterns (Gamma, Helm, Johnson, Vlissides, 1994) distilled as a practical field guide, not a catalog. Use when naming a shape in code review, choosing between competing designs, deciding whether to introduce indirection, or auditing for over-abstraction. Each pattern documents intent, tradeoffs, modern relevance, language-level replacements, and when NOT to use it. Triggers on: "design pattern", "GoF", "factory", "builder", "singleton", "adapter", "decorator", "observer", "strategy", "visitor", "state machine", "command pattern", "too many constructors", "subclass explosion", "program to an interface", "composition over inheritance", "am I over-abstracting this", "Swift design patterns", "protocol-oriented programming", "POP in Swift", "Crusty talk", "protocol vs class", "value types over reference types", "start with a protocol".

Build native macOS desktop applications in Swift using AppKit and SwiftUI. Use when building or modifying macOS .app bundles, NSDocument-based apps, menu bar apps, preferences windows, NSWindow/NSToolbar/NSSplitView layouts, NSMenu/NSStatusItem, Core Data/SwiftData/GRDB persistence, drag-and-drop, undo/redo, sandboxing, notarization, Sparkle auto-updates, XPC helpers, or XCTest for macOS. Also covers GPU-accelerated rendering with Metal and CAMetalLayer, infinite canvas UIs, libghostty terminal embedding, and WKWebView embedding. Trigger on AppKit, NSApplicationDelegate, NSDocument, NSViewController, Swift+Metal, macOS code signing, or when a user asks for production-grade Swift desktop patterns from repos like CodeEdit, Rectangle, CotEditor, IINA, Ice, Stats, Xcodes.app, STTextView, or Ghostty.

Use when adding, removing, or renaming a skill in this repository to keep the Available Skills table in README.md current.

Safe GitHub pull request workflow for low-experience Git users. Use when pulling, syncing a feature branch with `main`, resolving conflicts, undoing mistakes, recovering from a bad rebase, or deciding how to merge a PR while keeping `main` clean. Triggers on: "update my branch", "rebase my branch", "resolve git conflicts", "recover from rebase", "undo pushed commit", "keep main clean", "squash merge".

Prevent unnecessary React `useEffect` usage by steering code toward derived state, event handlers, memoization, `key`-based resets, `useSyncExternalStore`, and framework or query-library data APIs. Use when writing or reviewing React/Next.js components, refactoring effect-heavy code, or when a change introduces `useEffect`, `useLayoutEffect`, or dependency-array churn. Triggers on: "avoid useEffect", "remove useEffect", "you might not need an effect", "effect dependencies", "derived state", "React side effects".

Build design system components and UI that are accessible, themeable, and visually polished. Use when building buttons, dialogs, forms, cards, or any reusable UI components. Covers component API design, design tokens, accessibility, theming, visual design rules, and interaction patterns. Triggers on: "build a component", "design system", "create a button", "build a dialog", "add dark mode", "design tokens", "theme", "accessible component", "UI component", "component library".

Write clean, pragmatically functional TypeScript — simple, composable, soundly typed

Systematically refactor TypeScript codebases for readability, type safety, and AI-friendliness. Use when asked to "refactor this", "clean up this code", "make this codebase better", "improve code quality", or when inheriting a messy TypeScript project. Covers assessment, prioritization, and safe incremental transformation. Triggers on: "refactor", "clean up", "improve this code", "code quality", "make this readable", "technical debt", "code review", "modernize".

Create, remove, and list git worktrees in a standardized location

Write clean, terse technical docs — commits, issues, PRDs, specs, and technical communication

Distill knowledge from any source — blog posts, articles, documentation, GitHub repos, video transcripts, books, papers — into a well-structured agent skill. Use when the user shares a URL, article, repo, or body of knowledge and wants it turned into a reusable skill. Triggers on: "make a skill from this", "distill this into a skill", "create a skill from this article", "turn this repo into a skill", "extract patterns from", "convert to a skill". This skill complements the `skill-creator` skill — skill-creator handles the mechanics (frontmatter, packaging, init scripts), this skill handles the distillation process.

Write effective AGENTS.md files that give coding agents the context they need to work in a repository. Use when creating a new AGENTS.md, improving an existing one, setting up a repo for AI coding agents, or onboarding agents to a codebase. Triggers on: "write AGENTS.md", "create AGENTS.md", "agent instructions", "set up repo for agents", "configure coding agent", "onboard agent to codebase", "agent context file".

Structure a repository and its documentation so AI coding agents can work effectively. Covers knowledge hierarchy, progressive disclosure, mechanical enforcement of architecture, and entropy management. Use when setting up a new project for agent-first development, refactoring a repo to be more agent-friendly, designing documentation structure for AI consumption, or optimizing an existing codebase for agent throughput. Triggers on: "agent-first", "make repo agent-friendly", "agent legibility", "optimize for AI agents", "repo structure for agents", "agent-first development", "harness engineering", "codex workflow".

Type-driven design principle: transform unstructured data into structured types at system boundaries, making illegal states unrepresentable. Use when writing or reviewing code that validates input, designs data types, defines function signatures, handles errors, or models domain logic. Use when you see validation functions that return void/undefined, redundant null checks, stringly-typed data, boolean flags controlling behavior, or functions that can receive data they shouldn't. Triggers on: "parse don't validate", "type-driven design", "make illegal states unrepresentable", "input validation", "data modeling", "refactor types", "strengthen types", "smart constructor", "newtype", "branded type".

Generate an ARCHITECTURE.md file for a codebase following matklad's principles. Use when asked to "write an architecture doc", "create ARCHITECTURE.md", "document the architecture", "explain the codebase structure", "write a codemap", or when onboarding contributors to a project. Based on https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html and modeled after rust-analyzer's architecture doc.

Patterns for building lightweight, zero-dependency TypeScript tools and libraries. Use when building new CLI tools, libraries, or utilities from scratch. Use when refactoring existing TypeScript projects to remove unnecessary dependencies. Use when writing fetch wrappers, CLI parsers, loggers, config merging, string utilities, or any infrastructure code that should be lean and self-contained. Triggers on: "build a CLI", "write a logger", "fetch wrapper", "remove dependencies", "lightweight", "zero-dep", "inline utility", "refactor to be simpler".

Behavioral testing methodology — test what users experience, not how code is structured. Use when writing tests, reviewing test quality, planning test strategy for new features, or when existing tests are brittle/verbose/coupled to implementation details. Triggers: writing tests, TDD, test review, "tests keep breaking", "too many mocks", "tests are verbose", test coverage planning, behavior-driven development.

Teaches agents to write modern CSS using native features instead of legacy hacks, workarounds, and JavaScript. Covers layout, animation, color, typography, selectors, and workflow patterns with 64 old-vs-modern comparisons. The agent should always prefer modern CSS approaches, warn about browser compatibility for newer features, and ask the user before using techniques with limited browser availability (<80% support).