skills

Designs, reviews, and implements app UX architecture for mobile, tablet, desktop, native, hybrid, cross-platform, and web/PWA apps. Use when shaping information architecture, navigation models, route contracts, URLs, deep links, state restoration, adaptive layouts, windows, sidebars, inspectors, toolbars, menus, command palettes, task flows, permission flows, accessibility, widgets, shortcuts, App Intents, App Actions, or system entry points. Trigger when the user asks for app UX, mobile UX, desktop app UX, app navigation, tabs vs sidebars, back behavior, deep links, route design, PWA navigation, app review, or a framework-agnostic plan before choosing SwiftUI, UIKit, AppKit, Jetpack Compose, React Native, Flutter, Kotlin Multiplatform, Electron, Tauri, Capacitor, native web views, or a PWA stack.

Writes, refines, splits, and scores the issue artifact itself: compact implementer-ready body, acceptance criteria, scope boundary, routing metadata, and complexity. Use when the user asks to create an issue, write ticket-ready issue text, refine issue scope, add acceptance criteria, add issue metadata, estimate issue points, split oversized work, or make one issue clear enough for an implementer. Do not use for picking work, tidying Linear projects, implementation, pull requests, or project planning.

Keeps an existing Linear project tidy after planning and during execution. Use when the user asks to "tidy Linear", "clean up the project", "audit issues", "find duplicates", "check stale blockers", "fix project drift", or run periodic Linear housekeeping on a project, initiative, or milestone set. Use when planning is underway or execution has started and relationships, labels, priorities, documents, and issue states need coherence without changing product scope.

Create, audit, document, and evolve digital design systems from the bundled universal design-system guide. Use when the user says "create a design system", "write a system brief", "audit our design system", "define tokens", "make a component spec", "plan adoption", "write release notes", "create governance", "build a design-system roadmap", or asks about foundations, color, typography, spacing, motion, media, data visualization, content voice, accessibility, component APIs, component libraries, patterns, templates, themes, modes, multi-brand architecture, platform support, engineering architecture, design tooling, source-of-truth rules, documentation, contribution, deprecation, migration, testing, quality gates, metrics, maturity, templates, or readiness checklists.

Use when the user asks to create, update, review, or refactor an agent skill, including requests like "turn this workflow into a skill", "make a skill for this", "fix this SKILL.md", "add references to this skill", "make this skill work in Codex and Claude", or "split this bloated skill". Creates skill directories, writes portable SKILL.md frontmatter and workflows, adds references, validates structure and token budgets. For adding executable helpers, use the tooling skill.

Mines recent Codex or Claude agent conversations and git history for struggles, repeated corrections, rework patterns, and taste signals — then turns findings into new skills or updates to existing ones. Use when retrospecting on recent coding sessions, extracting learnings, identifying skill gaps, improving skills from real usage patterns, codifying recurring preferences, or when the user says "retro this repo", "mine recent conversations", "what should become a skill", or "find repeated agent mistakes".

Cross-platform Apple Human Interface Guidelines: color, typography, layout, materials, motion, accessibility, SF Symbols, branding, plus shared UI elements (activity views, rating indicators, web views, …) and meta sections (components, patterns, technologies). Use when the design topic is platform-agnostic. User says: "iOS color tokens", "SF Symbols", "Apple typography", "dark mode guidance".

Apple Human Interface Guidelines by platform: iOS and iPadOS, macOS, watchOS, tvOS, and visionOS UI components, controls, navigation, and platform conventions. Use when designing, building, or auditing UI for a specific Apple platform. Pair with `foundations` for shared Apple design principles and `services` for framework integrations. User says: "design iPhone UI", "macOS component", "watchOS audit", "tvOS navigation", "visionOS layout".

Apple framework and service integrations: Apple Pay, HealthKit, HomeKit, Siri, CarPlay, Sign in with Apple, App Clips, widgets, Camera, Control Center, sensors, and more. Use when integrating an Apple framework or designing UI that surfaces one. User says: "add Apple Pay", "Sign in with Apple", "HealthKit UI", "design a widget".

Designs REST, GraphQL, or gRPC APIs from requirements — picks the right protocol for the use case, models resources and operations, defines schemas (Zod for internal, OpenAPI/GraphQL SDL/proto for specs), and writes the spec to .context/architecture/api/. Use when the user asks to design an API, sketch out endpoints, model a schema, plan a service's interface, or says things like "what should the API look like for X", "design endpoints for Y", or "how should clients talk to this service".

Structures codebases and repositories by project type, runtime boundary, domain ownership, and maintenance workflow. Use when the user asks how to organize a codebase, scaffold a repo, split a monolith, design a monorepo, move files, choose folders, clean up LLM-generated project layout, or decide where app, package, service, test, config, docs, and deployment code should live. Covers Apple apps, web apps, websites, Expo/React Native, Cloudflare/full-stack services, CLIs, agent skills/plugins, Home Assistant integrations, and GitOps/homelab projects.

Creates, audits, and updates private or closed-source project documentation, including internal README hubs, codebase navigation guides, ownership links, Linear initiative links, onboarding notes, runbooks, and contribution guidance for teams. Use when maintaining docs for private repositories, internal apps, services, infrastructure, or company projects, especially when the user says "make this README an internal hub", "document how to navigate this repo", "add Linear links to the docs", or "write private project documentation".

Maintains Markdown document templates in the documentation plugin's project-docs library. Use when working in this skills repo and the user asks to add a reusable project document template, update an existing template reference, change the project-docs template library, or adjust README/template validation for project-docs.

Creates, audits, and updates public open-source repository documentation, including README files, CONTRIBUTING guides, SECURITY and SUPPORT docs, project badges, quickstarts, usage guidance, community links, and contributor onboarding. Use when maintaining docs for public GitHub projects, libraries, CLIs, apps, or reusable packages, especially when the user says "update this README", "write CONTRIBUTING.md", "make these docs open-source ready", or "improve the public project docs".

Generates and maintains a hierarchical .context/ directory with architecture overviews, coding conventions, domain glossaries, and dependency maps that give any LLM working in the project the right background. Use when setting up a new project for AI-assisted development, when the user asks to create or update context docs, when onboarding a new LLM tool to an existing codebase, or when the user says the AI doesn't understand their project.

Writes and edits project documents from the project-docs templates. Use when the user asks for a project brief, feature spec, technical design, decision record, research brief, platform dependency doc, customer profile, testing strategy, release readiness doc, post-release review, documentation placement rules, or is filling one of those project document templates.

Writes Architecture Decision Records (ADRs) in MADR format — captures context and problem, decision drivers, considered options with pros/cons, the chosen option and why, and consequences. Numbers files sequentially under .context/architecture/adr/. Use when the user asks to document a decision, write an ADR, record a trade-off, capture why something was chosen over alternatives, or says things like "let's write this up as an ADR", "log this decision", or "we should document why we picked X".

Assembles architecture, data modeling, and API design work into a structured, readable system design document. Focuses on writing quality, document structure, and completeness — the thinking work (decomposition, trade-offs, data modeling) happens in other skills and this skill pulls the results together into a single artifact that engineers and LLMs can implement from. Use when the user asks to write a design doc, document a design, write up the architecture, create a technical spec, assemble a system design, or says things like "write this up", "let's document the design", "create a design doc for this", or "turn this into a spec".

Creates fresh Linear planning projects from Luca's five-phase planner structure. Use when the user asks to "create a planner project", "set up planning in Linear", "turn this app idea into a Linear planning project", or replace a live Linear template project with a reusable skill-backed workflow. Use when a real web, native, backend, automation, data, AI, or mixed-surface project needs initiative, project, milestone, and issue records in Linear without keeping reusable template issues live.

Assigns issue points using Luca's complexity metadata rules. Use when the user asks to grade, estimate, score, point, size, triage, compare, normalize, or audit issues by complexity, especially when they mention points, estimates, acceptance criteria, issue sizing, uncertainty, or oversized work.

Picks up the next actionable Linear issue for the product represented by the current repository. Use when the user says "/pickup-work", "pickup work", "pick up an issue", "what should I work on next", or asks to start Linear work from a repo. Use when a local monorepo should be mapped to its Linear product initiative or project before assigning and starting an issue.

Facilitates structured project-intent interviews and A/B/C option narrowing before planning work. Use when the user asks to refine an app, product, repo, automation, or project idea, feels lost across many projects, wants Codex to interview them, wants A/B/C choices, needs an LLM alignment packet, wants to decide whether to build, pause, merge, or kill a project, or wants to prepare a Linear planning project before creating docs, issues, or implementation work.

Gathers, structures, and prioritizes requirements for a system before any design work begins. Use when the user has a vague idea ("I need to build X", "we need a service that does Y"), wants to define what a system should do and under what constraints, asks about non-functional requirements, says things like "what are the requirements for", "help me scope this", "what do I need to think about before building", or "let's figure out what this needs to do". Do NOT use for designing the system itself — this skill produces the inputs that architecture and design skills consume.

Interviews the user to turn rough intent into a written task spec before filing an issue, starting code, or doing substantial work. Use when the user asks to create an issue, start implementation, scope a task, capture specs, clarify intent, write acceptance criteria, says "grill me", or has a fuzzy request that needs a concrete brief before action.

Guides system architecture and decomposition — turns requirements into a concrete system shape by identifying components, drawing boundaries, tracing data flow, analyzing failure modes, and selecting technology. Covers the intellectual work of breaking a system apart, not the writing of a design document. Use when the user asks to architect a system, decompose a feature into components, figure out how services should talk to each other, evaluate system trade-offs, or says things like "how should we structure this", "what components do we need", "let's think through the architecture", or "where should this logic live".

Generates C4 model architecture diagrams (System Context, Container, Component) as Mermaid for embedding in docs — picks the right C4 level for the question being answered, labels every element with its technology and responsibility, and avoids the "everything touches everything" spaghetti that makes most architecture diagrams useless. Writes to .context/architecture/diagrams/. Use when the user asks for a diagram of their system, an architecture visualization, a container/component diagram, wants to see how pieces fit together, or mentions "C4".

Designs the data layer — schemas, entities, relationships, ID strategy, naming, tenancy, timestamps, indexes, audit logging, and migrations. Turns a set of domain concepts into a concrete Drizzle schema with all the small decisions that compound into either a clean data layer or a mess. Use when the user asks to design a schema, model the data, plan the database, add tables, review an existing schema, or says things like "what should the database look like", "design the schema for X", "add a table for Y", or "how should I store Z". Does NOT cover system decomposition (use architecture) or API design (use api-design).

Creates decision trees that both humans and AI agents can follow reliably — captures expert knowledge as branching logic with concrete conditions, clear actions, and visible reasoning traces. Use when the user wants to document a decision process, create a troubleshooting guide, build a triage flowchart, write an escalation tree, or turn tribal knowledge into structured steps.

Reviews and critiques an existing or proposed system design — flags single points of failure, missing non-functional requirements, scaling bottlenecks, security gaps, operational blind spots, unjustified tech choices, and places where the design will fall over under load or failure. Produces a structured review with severity-tagged findings, not just vibes. Use when the user asks for a second opinion on an architecture, requests a design review, wants feedback on a proposed system, pastes a design doc, or says things like "review this design", "what's wrong with X", "poke holes in this", or "is this a good architecture".

Guides a full system design from idea to spec — sequences requirements gathering, architecture decomposition, data modeling, API design, and document writing into a coherent workflow with clear handoffs. Use when the user asks to "design a system", "build X from scratch", "architect something end-to-end", "plan a new service", or has a broad design ask that spans multiple concerns. Also use when the user says things like "I need to build X" without specifying which aspect to start with. This is the entry point for any design task that isn't clearly scoped to a single skill (data model only, API only, etc.).

Manages Codex, Claude Code, and Cursor skill/plugin marketplaces — publishes plugin-owned skills, updates plugin groups, removes entries, packages skills for distribution, regenerates plugin manifests, and validates catalog integrity. Use when publishing a skill to the marketplace, bumping a version, removing a skill from the catalog, packaging a skill as a .skill file, regenerating marketplace files, moving a skill between plugins, fixing marketplace validation errors, or when the user says "publish this skill", "regenerate the marketplace", "move this skill to another plugin", or "package this skill".

End-to-end repository management: inspect and protect local state, create signed and well-scoped commits, split messy working trees, rebase or merge and resolve conflicts, open GitHub pull requests, repair PRs, watch and fix CI, clean stale branches/worktrees/stashes, and leave repos in a shippable state. Use when the user asks to commit, create a PR, clean up a repo, rebase, resolve conflicts, fix CI, make a PR merge-ready, watch checks, merge or prepare branches, or otherwise manage Git/GitHub repository state.

Interviews the user to extract their design taste, technology preferences, and opinionated defaults for a domain, then encodes those preferences into skill reference files, decision rules, conventions, and anti-patterns. Use when the user says "encode my taste", "add my preferences to this skill", "make this skill opinionated", "interview me about my preferences for X", or asks to capture style/defaults in a reusable skill.

Creates and improves Bun-based tools for skills — decides when a tool earns its place, scaffolds zero-dependency scripts with dual output, validates tool quality, and wires tools into SKILL.md decision trees. Use when adding a tool to a skill, improving an existing tool, deciding whether something should be a tool or inline instructions, reviewing tool quality, or when the user says "add a tool to this skill", "write a validator for this skill", "make this repeatable", or "check this tool".

Designs, reviews, and implements modern public-facing websites with strong content, hierarchy, conversion, accessibility, performance, and visual quality. Use for marketing sites, campaign landing pages, homepages, pricing pages, product pages, portfolio sites, editorial sites, ecommerce/catalog pages, service websites, nonprofit/government/healthcare/education sites, event pages, hospitality/restaurant pages, personal brand sites, and similar website content surfaces. Trigger when the user asks for web design, landing page design, marketing website UX, homepage structure, website copy hierarchy, responsive site layout, conversion-focused page design, website audit, or modern website visual direction.

Designs decision-first dashboards, admin consoles, operational workbenches, database management interfaces, support queues, analytics surfaces, settings hubs, and internal tools. Use for advisory conversations with a person asking for dashboard UX advice and for autonomous agent work when creating, redesigning, reviewing, or implementing dashboard-like product UI. Trigger when choosing dashboard archetypes, layout, metrics, charts, tables, filters, forms, actions, states, permissions, accessibility, or domain-specific dashboard patterns; or when the user asks for "dashboard UX", "admin UI", "ops console", "management dashboard", "support workbench", "database console", or similar.