Skills

• 1: Skill Package Format
• 2: Skill Hierarchy
• 3: Catalog
• 3.1: Process Skills
• 3.2: Language Skills
• 3.3: Infrastructure Skills
• 3.4: Architecture Skills
• 3.5: Design & Visual Skills
• 3.6: Data & Analytics Skills
• 3.7: AI & ML Skills
• 3.8: API & Integration Skills
• 3.9: Security Skills
• 3.10: Observability Skills
• 3.11: Database Skills
• 3.12: Framework & SEO Skills
• 3.13: Performance Skills

src/context/skills/<category>/<skill-name>/
  SKILL.md              ← agent instructions (Intro / Overview / Gotchas / Full reference)
  examples/             ← example outputs
  assets/               ← templates, reference data, reusable artifacts
  references/           ← optional deep-dive material (keeps SKILL.md under 5 000 words)
  scripts/              ← optional helper scripts
  mcp/                  ← optional Python MCP server

---
name: workitem-management
description: |
  Creates, transitions, and queries WorkItems — the task-tracking primitive
  in processkit. Use when managing backlog items, updating work item state,
  or querying items by status, owner, or priority.
metadata:
  processkit:
    apiVersion: processkit.projectious.work/v1
    id: SKILL-workitem-management
    version: "1.0.0"
    created: 2026-04-06T00:00:00Z
    category: process
    layer: 2
    uses:
      - skill: event-log
        purpose: "records state transitions as auditable log entries"
    provides:
      primitives: [WorkItem]
      mcp_tools: [create_workitem, transition_workitem, query_workitems]
      assets: [workitem, workitem-bug, workitem-story]
---

1 - Skill Package Format

This page summarizes the skill package format. The authoritative source is src/context/skills/FORMAT.md in the processkit repo.

Directory layout

src/context/skills/<category>/<skill-name>/
  SKILL.md              ← required — three-level agent instructions
  INDEX.md              ← optional — human-readable overview
  examples/             ← recommended — example outputs
  templates/            ← recommended — YAML frontmatter entity scaffolds
  references/           ← optional — deep-dive reference material
  mcp/                  ← optional — Python MCP server
    server.py
    mcp-config.json
    README.md

Required frontmatter fields

Optional fields

Categories

process, language, framework, infrastructure, architecture, design, data, ai, api, security, observability, database, performance, meta.

The provides block

A promise to consumers — what an agent gains by activating this skill:

provides:
  primitives: [WorkItem]
  mcp_tools: [create_workitem, transition_workitem, query_workitems]
  templates: [workitem, workitem-bug, workitem-story]
  processes: [backlog-grooming]

Installers and release checks can cross-check these promises against the actual files shipped in the skill.

MCP server conventions (v0.3.0+)

Skills ship Python MCP servers as standalone scripts with PEP 723 inline dependencies:

#!/usr/bin/env -S uv run
# /// script
# requires-python = ">=3.10"
# dependencies = ["mcp[cli]>=1.0,<2.0"]
# ///
from mcp.server.fastmcp import FastMCP
server = FastMCP("<skill-name>")
...
if __name__ == "__main__":
    server.run(transport="stdio")

Consumers need only Python 3.10 or newer and uv.

2 - Skill Hierarchy

Process-primitive skills form a strict layered DAG. A skill’s spec.uses field may only reference skills in lower layers. Cycles are validation errors.

The layers

Layer 0 has three skills with one intra-layer edge. index-management and id-management are the absolute foundation — they depend on nothing. event-log is also Layer 0 but uses: [index-management, id-management], so it conceptually sits “atop” them. This is the only intra-layer edge in the entire hierarchy. The strict-downward rule applies to Layers 1+ unchanged.

What the layers mean

• Layer 0 — the foundation that every entity-creating skill depends on. index-management provides the read side (look up entities by ID, kind, state, text). id-management provides the write side (allocate unique IDs in the configured format). event-log is also at Layer 0 but uses both — the only intra-layer edge in the hierarchy.
• Layer 1 — management for the “participants” of processes: Actors (who does things) and Roles (what things they do).
• Layer 2 — management for the primary work artifacts: WorkItems, DecisionRecords, Scopes. Depends on Layers 0–1.
• Layer 3 — workflow policy: Gates and Constraints tie Layer 2 entities together. Process, Schedule, and StateMachine skills remain as legacy/migration guidance; v2 expresses runs as WorkItems, definitions as Artifacts, recurrence as time-window Bindings, and lifecycle enforcement through MCP server contracts.
• Layer 4 — cross-cutting concerns that reference everything: Discussions produce decisions and reference work items; metrics-management records metric specifications as artifacts and observations as LogEntries. This is a skill-layer placement, not a Metric primitive.

Technical/language skills are unlayered

Skills in categories like language, framework, infrastructure, database, data, ai, security, observability, performance, design are layer: null. They don’t fit the layered hierarchy — they describe how to do engineering things, not how to manage process artifacts. Such skills can still use spec.uses for other technical skills (e.g. fastapi-patterns uses python-best-practices).

Validation

Phase 5 of the DISC-002 plan adds DAG validation to the index MCP server:

• Every spec.uses entry must reference an existing skill.
• For process-primitive skills, each referenced skill’s spec.layer must be strictly less than the referencing skill’s spec.layer.
• No cycles are permitted.

3 - Catalog

The shipped skills by category. Each entry states what the skill covers and when an agent should reach for it.

3.1 - Process Skills

Skills for managing project workflows, team coordination, and operational processes. Most process-primitive skills have an accompanying MCP server that enforces schema validation and state-machine rules.

workitem-management

Creates, transitions, and queries WorkItems — the task-tracking primitive in processkit. Use when managing backlog items, updating work item state, or querying items by status, owner, or priority.

Triggers: When the user asks to create a ticket, update a work item, query the backlog, or track progress on a task. Tools: create_workitem, transition_workitem, query_workitems, get_workitem, link_workitems Layers: Layer 2 (depends on event-log, actor-profile)

Key capabilities:

• Create WorkItems with type (task, story, bug, epic, spike, chore) and priority (critical, high, medium, low)
• Transition through the default state machine: backlog → in-progress → review → done (with blocked as a side state)
• Link parent/child WorkItems for epics and subtasks
• Query by state, type, priority, owner, or label
• All state transitions auto-append a LogEntry via event-log

decision-record

Captures architectural and product decisions as DecisionRecord entities (ADR pattern). Use when the team makes a significant choice with rationale, alternatives, and implications.

Triggers: When the user says “write a decision”, “document this ADR”, “record why we chose X”, or “capture this architectural decision”. Tools: record_decision, transition_decision, query_decisions, get_decision, supersede_decision, link_decision_to_workitem Layers: Layer 2 (depends on event-log)

Key capabilities:

• Record decisions with status (proposed, accepted, rejected), rationale, alternatives considered, and implications
• Link decisions to WorkItems for traceability
• Supersede old decisions when context changes
• Query by status, tag, or date

artifact-management

Registers and retrieves completed deliverables — documents, datasets, builds, diagrams, URLs, runbooks. Use when cataloguing a produced output so future agents and humans can find it.

Triggers: When the user says “register an artifact”, “catalog this document”, “store this deliverable”, or “link this design file”. Tools: create_artifact, get_artifact, query_artifacts, update_artifact Layers: Layer 2 (no state machine — Artifact is a catalogue record)

Key capabilities:

• Two usage patterns: self-hosted (Markdown body in the entity file) and pointer (external URL or file path via location)
• Tag artifacts for filtering (kind, labels)
• Query by kind, tag, or title substring
• Update metadata on existing artifacts

event-log

Writes auditable LogEntry records for any project event. Use when you want an immutable record of something that happened.

Triggers: When the user says “log this event”, “audit trail”, “record that we did X”, or when any entity-mutating MCP server fires a side-effect log. Tools: log_event, query_events, recent_events Layers: Layer 0 (foundation — no dependencies)

Key capabilities:

• Append-only — LogEntries are never updated or deleted
• Entity-mutating MCP servers (create, transition, link) auto-append a LogEntry without the caller doing anything extra
• Query by actor, entity, event type, or date range
• recent_events returns the last N entries across all entities

note-management

Captures, reviews, and promotes fleeting ideas and insights using the Zettelkasten method. Use when the user wants to record an observation, link related ideas, or build a personal knowledge base.

Triggers: When the user says “remember this”, “note this idea”, “capture this”, or “link this to another note”. Tools: create_note, capture_inbox_item, claim_inbox_item, complete_inbox_item, fail_inbox_item Layers: Layer 2

Key capabilities:

• Three note types: fleeting (raw capture), insight (permanent note, never discarded), reference (literature note)
• links field for typed Zettelkasten edges: elaborates, contradicts, supports, is-example-of, see-also, refines, sourced-from
• Each link requires a context sentence explaining why the connection matters — tags group, links argue
• Notes stored under context/notes/
• Hook inbox lifecycle for interrupt, ambient, and next-cycle items

session-handover

Writes an end-of-session handover document before the agent shuts down or the container restarts. Use to preserve state across context resets.

Triggers: When the user says “write a handover”, “shutting down”, “container restart”, “end of session”, or when context is approaching its limit. Tools: None (file-based via SKILL.md instructions) Layers: Layer 4

Key capabilities:

• Captures: current task state, open decisions, blockers, what was completed, and suggested next actions
• Stores as a LogEntry with a generated LOG- ID under context/logs/
• Includes a generate_id call and date-sharded path derivation
• Designed to be the first thing the next agent reads at session start

standup-context

Writes a standup update in Done / Doing / Next / Blockers format. Use at the start of a work session, for daily standups, or for async team updates.

Triggers: When the user says “write a standup”, “daily update”, “what did we do yesterday”, or “status update for the team”. Tools: None (file-based via SKILL.md instructions) Layers: Layer 4

Key capabilities:

• Reads open and recently-completed WorkItems to populate Done / Doing
• Reads Discussion entities for blockers
• Outputs a clean, copy-pasteable standup
• Optionally stores as a LogEntry for the audit trail

status-briefing

Generates a session-start orientation from the current project state. Use at the beginning of a session to get a fast, structured catch-up.

Triggers: When the user says “status briefing”, “catch me up”, “state of things”, or “what’s on the board”. Tools: Reads query_entities, recent_events via index-management Layers: Layer 4

Key capabilities:

• Summarises open WorkItems by state and priority
• Surfaces recent LogEntries (what changed since last session)
• Highlights open Discussions and pending Decisions
• Reports any pending Migrations

context-grooming

Periodically prunes and compacts the project context to keep it navigable. Use when context/ has grown stale or cluttered.

Triggers: When the user says “groom the context”, “clean up context”, or when the entity count in any directory is getting unwieldy. Tools: index-management for enumeration; per-kind MCP servers for transitions Layers: Layer 4

Key capabilities:

• Identifies done WorkItems older than N days as candidates for archiving
• Surfaces Discussions in open state that have had no activity
• Detects Notes in fleeting state that have not been promoted
• Proposes a grooming plan — does not auto-archive without confirmation

release-semver

Plans and executes a semantic versioning release. Use when preparing a new version of a project or library.

Triggers: When the user says “plan the release”, “version bump”, “cut a release”, or “prepare vX.Y.Z”. Tools: None (checklist-driven via SKILL.md instructions) Layers: Layer 4

Key capabilities:

• Determine bump type (patch/minor/major) from change audit
• Update CHANGELOG and PROVENANCE
• Run smoke tests before tagging
• Commit, tag, push, build release tarball, create GitHub release
• processkit-specific: stamp-provenance.sh and build-release-tarball.sh are the canonical scripts

retrospective

Facilitates team or project retrospectives — what worked, what didn’t, action items. Use at the end of a sprint, milestone, or project phase.

Triggers: When the user says “let’s do a retro”, “what went well?”, “lessons learned”, or “end of sprint review”. Tools: None Layers: Layer 4

Key capabilities:

• Scope the retrospective (time period or milestone)
• Gather input in three categories: What Worked, What Didn’t, What to Try Next
• Action items must be specific, assignable, and time-bound
• Store as a LogEntry or Artifact in context/

incident-response

Guides production incident handling — triage, communicate, fix, postmortem. Use when something is broken in production.

Triggers: When the user reports a production issue or says “production is down”, “users are affected”, “we have an incident”. Tools: None Layers: Layer 4

Key capabilities:

• Triage within first 5 minutes: assess user impact, identify recent changes, evaluate rollback options
• Communicate to stakeholders with status, impact, and ETA
• Mitigate first, fix later: rollback or temporary workaround
• Postmortem within 48 hours: timeline, root cause, action items, blameless approach

estimation-planning

Software estimation and planning — story points, velocity tracking, scope negotiation, technical debt budgeting. Use when estimating work or planning sprints.

Triggers: When the user asks to estimate work, plan a sprint, negotiate scope, or asks “how should I estimate this?”. Tools: None Layers: Layer 4

Key capabilities:

• Story points vs time estimates: Fibonacci sizing, relative complexity
• Planning poker with anchoring-bias prevention
• Cone of uncertainty: communicate estimates as ranges with confidence
• Velocity tracking and MoSCoW prioritisation
• Three-point estimation with PERT formula

postmortem-writing

Blameless postmortem writing with timeline, root cause analysis, and corrective actions. Use when writing incident postmortems.

Triggers: When writing an incident postmortem, conducting a post-incident review, or asking “how do I write a blameless postmortem?”. Tools: None Layers: Layer 4

Key capabilities:

• Structured template: summary, impact, timeline, root cause, corrective actions, lessons learned
• 5 Whys root cause analysis down to systemic/process issues
• Corrective actions in prevent/detect/mitigate categories, each with owner and due date
• Blameless culture: systems-focused language, passive voice for human errors

3.2 - Language Skills

Language-specific conventions, patterns, and best practices.

python-best-practices

Python conventions and patterns – typing, testing, project layout, tooling. Use when writing or reviewing Python code.

Triggers: When the user is working with Python code and asks about conventions, project structure, typing, testing, or says “how should I structure this Python project?”. Tools: None References: None

Key capabilities:

• Project layout: src/ layout with pyproject.toml, use uv for dependency management
• Type hints on all public function signatures with from __future__ import annotations
• Testing with pytest: fixtures, parametrize, test naming test_<function>_<scenario>_<expected>
• Code style: ruff format and ruff check, prefer dataclasses/Pydantic over dicts, pathlib over os.path
• Error handling: raise specific exceptions, custom exception classes, never bare except:

rust-conventions

Rust patterns and conventions – error handling, module structure, clippy compliance. Use when writing or reviewing Rust code.

Triggers: When the user is working with Rust code and asks about patterns, error handling, module organization, or says “how should I structure this in Rust?”. Tools: None References: None

Key capabilities:

• Error handling: anyhow::Result for apps, thiserror for libraries, .context() on all ? operations
• Module structure: one module per file, thin main.rs/lib.rs, group by domain
• Naming: PascalCase types, snake_case functions, SCREAMING_SNAKE constants, builder pattern
• Clippy compliance: build with cargo clippy -- -D warnings, prefer &str over &String
• Testing: unit tests in #[cfg(test)] mod tests, integration tests in tests/, descriptive assert_eq! messages

typescript-patterns

TypeScript project patterns – strict mode, type safety, project setup. Use when writing or reviewing TypeScript code.

Triggers: When the user is working with TypeScript and asks about project setup, type patterns, strict mode, or says “how should I type this?”. Tools: None References: None

Key capabilities:

• Project setup: strict mode in tsconfig.json, noUncheckedIndexedAccess, committed lockfile
• Type safety: avoid any, use unknown with type guards, explicit return types on public functions
• Discriminated unions for state modeling, as const for literal types, satisfies operator
• Use zod or similar for runtime validation of external data
• Error handling: custom error classes, Result types in library code, validate all external inputs
• Testing with vitest or jest, type-level testing with expectTypeOf

go-conventions

Go idioms and conventions including error handling, interfaces, goroutine patterns, and testing. Use when writing Go code, reviewing Go projects, or designing Go package layouts.

Triggers: When the user is working with Go code and asks about idiomatic patterns, error handling, concurrency, package organization, or testing strategies. Tools: Bash(go:*), Read, Write References: references/go-patterns.md

Key capabilities:

• Error handling: return errors as last value, wrap with fmt.Errorf and %w, use errors.Is/errors.As
• Interfaces: accept interfaces, return concrete types, keep interfaces small (1-3 methods), define at consumption site
• Goroutine patterns: context.Context as first parameter, errgroup.Group for fan-out/fan-in, clear lifecycle ownership
• Package layout: organize by domain, avoid util/common packages, internal/ for private packages
• Testing: table-driven tests, testify/assert, httptest, t.Helper(), go test -race
• Go proverbs: share memory by communicating, clear is better than clever, make the zero value useful
• Code style: follow gofmt unconditionally, group imports, exported names get doc comments

java-patterns

Modern Java 17+ patterns including records, sealed classes, Stream API, and Spring Boot conventions. Use when writing Java code, reviewing Java projects, or modernizing legacy Java.

Triggers: When the user is working with Java code and asks about modern language features, Spring Boot conventions, Stream API patterns, or says “how should I modernize this Java code?”. Tools: Bash(mvn:*), Bash(gradle:*), Read, Write References: None

Key capabilities:

• Modern Java 17+ features: records, sealed classes, pattern matching with instanceof, switch expressions, text blocks
• Records and sealed classes for algebraic data types with exhaustive switch handling
• Stream API: filter -> map -> collect pipelines, groupingBy, flatMap, proper Optional usage
• Spring Boot: constructor injection, thin controllers, @Transactional at service layer, @ConfigurationProperties, @RestControllerAdvice
• Dependency injection: prefer constructor injection, use interfaces for contracts, avoid circular dependencies
• Testing with JUnit 5 and Mockito: @ParameterizedTest, AssertJ assertions, test slices (@WebMvcTest, @DataJpaTest)
• Code organization: package by feature, single responsibility, prefer composition over inheritance

sql-style-guide

SQL formatting and naming conventions for tables, columns, queries, migrations, and constraints. Use when writing SQL, reviewing database code, or establishing SQL style guidelines.

Triggers: When the user is writing SQL queries, designing schemas, creating migrations, or asks “how should I format this SQL?” or “what naming convention should I use for tables?”. Tools: None References: None

Key capabilities:

• Table and column naming: snake_case, singular table names, is_/has_ for booleans, _at for timestamps
• Keyword capitalization: SQL keywords in UPPERCASE, identifiers in lowercase
• Query formatting: one clause per line, leading commas, explicit JOIN syntax, meaningful table aliases
• Comment conventions: -- for single-line, explain WHY not WHAT
• Migration file naming: sequential timestamps, one structural change per migration, include both up and down
• Constraint naming: pk_, fk_, uq_, ck_, ix_ prefixes with table and column names
• Query best practices: WHERE EXISTS over WHERE IN, CTEs for complex queries, avoid SELECT *

latex-authoring

Comprehensive LaTeX document authoring with LuaLaTeX, modern packages, math, TikZ, and bibliography management. Use when writing or editing LaTeX documents.

Triggers: When the user asks to write or edit LaTeX documents, set up document classes and preambles, create math equations or TikZ diagrams, or manage bibliographies. Tools: None References: references/packages.md, references/math-reference.md, references/tikz-reference.md

Key capabilities:

• Document classes: article, book, report, beamer, standalone, and when to use each
• LuaLaTeX vs pdfLaTeX: prefer LuaLaTeX for new projects (Unicode, system fonts, Lua scripting)
• Essential packages: geometry, fontspec, amsmath, siunitx, tabularray, tikz, biblatex, tcolorbox
• Document structure: one sentence per line, split with \input{}, preamble in separate file
• Bibliography with BibLaTeX and Biber backend
• Math typesetting: inline, display, multi-line environments, custom commands, SI units with siunitx
• TikZ for programmatic vector graphics with common libraries
• Common mistakes to avoid: $$...$$ for display math, missing \label after \caption

3.3 - Infrastructure Skills

Skills for containers, orchestration, networking, system administration, and CI/CD.

dockerfile-review

Dockerfile best practices review – layer optimization, caching, security, image size. Use when writing or reviewing Dockerfiles.

Triggers: When the user asks to review a Dockerfile, optimize an image, or says “why is my image so big?”, “is this Dockerfile correct?”, or “help me with Docker”. Tools: None References: None

Key capabilities:

• Layer optimization: combine related RUN commands, order from least to most frequently changing
• Caching: copy dependency manifests first, install, then copy source
• Security: don’t run as root, never COPY secrets, pin base images with digest, remove package caches
• Size reduction: slim/alpine base images, multi-stage builds, --no-install-recommends
• Correctness: use COPY over ADD, set WORKDIR instead of cd, exec form for CMD/ENTRYPOINT

ci-cd-setup

CI/CD pipeline setup – GitHub Actions, testing, linting, deployment. Use when setting up or improving continuous integration and deployment.

Triggers: When the user asks to “set up CI”, “add GitHub Actions”, “automate tests”, “add deployment”, or wants to improve their build pipeline. Tools: None References: None

Key capabilities:

• Pipeline stages in order: lint (fastest feedback), test (unit then integration), build, deploy
• GitHub Actions basics: trigger on push/PR, specific action versions, cache dependencies, set timeouts
• Testing in CI: same commands as local dev, matrix builds when needed, fail fast
• Security: use GitHub Secrets, permissions key for token scope, pin third-party actions to SHA
• Best practices: keep CI under 5 minutes for PRs, require CI pass before merge, run expensive checks only on main

kubernetes-basics

Kubernetes cluster management, resource definitions, networking, storage, Helm, and troubleshooting. Use when working with Kubernetes manifests, kubectl commands, Helm charts, or debugging pod/service issues.

Triggers: When writing or editing Kubernetes YAML manifests, running kubectl or helm commands, debugging pods/services/networking/storage, or managing Helm charts. Tools: Bash(kubectl:*), Bash(helm:*), Bash(k9s:*), Read, Write References: references/resource-cheatsheet.md, references/cluster-architecture.md, references/troubleshooting.md

Key capabilities:

• Cluster context management: confirm active cluster and namespace before changes
• Core resources: Deployments (stateless), StatefulSets (stateful), DaemonSets (per-node), Jobs/CronJobs
• Networking: ClusterIP, NodePort, LoadBalancer services; Ingress for HTTP routing; Network Policies
• Storage: PersistentVolumes, PersistentVolumeClaims, StorageClasses, volumeClaimTemplates
• Configuration: ConfigMaps and Secrets, prefer volume mounts over env vars
• Helm: repo management, install/upgrade/rollback, helm template for inspection, pin chart versions
• Troubleshooting workflow: events, describe, logs, exec, top
• Safe changes: kubectl diff before apply, --dry-run=client for validation, rollout undo for rollback

dns-networking

DNS resolution, IP addressing, subnetting, network protocols, and diagnostic tools. Use when configuring DNS records, debugging connectivity, setting up networking, or troubleshooting network issues.

Triggers: When setting up or modifying DNS records, debugging DNS resolution or connectivity, configuring firewalls, analyzing HTTP/TLS issues, calculating subnets, or diagnosing latency and routing problems. Tools: Bash(dig:*), Bash(nslookup:*), Bash(traceroute:*), Bash(curl:*), Bash(ss:*), Read, Write References: references/protocol-reference.md, references/troubleshooting-tools.md

Key capabilities:

• DNS fundamentals: record types (A, AAAA, CNAME, MX, TXT, SRV, NS, SOA, PTR), TTL management
• IP addressing and subnetting: CIDR notation, private ranges (RFC 1918), quick subnet math
• Common protocols: TCP vs UDP, HTTP/HTTPS, DNS, SSH, SMTP/IMAP
• TLS and HTTPS: handshake process, debugging expired certificates and hostname mismatches
• Port management: listing listeners with ss, well-known vs ephemeral port ranges
• Firewall basics with ufw and iptables
• Load balancing concepts: round-robin DNS, reverse proxy (Layer 7), Layer 4 LB
• Diagnostic workflow: DNS resolution, reachability, route tracing, port checks, application testing

terraform-basics

Infrastructure-as-code with Terraform/OpenTofu. Resources, providers, state, modules, and plan/apply workflow. Use when writing Terraform configs, managing cloud infrastructure, or reviewing IaC code.

Triggers: When writing or editing .tf files, planning/applying/destroying infrastructure, managing state and backends, creating modules, or reviewing IaC for best practices. Tools: Bash(terraform:*), Bash(tofu:*), Read, Write References: None

Key capabilities:

• Resources and providers: pin provider versions in required_providers, descriptive resource names
• Variables with types, descriptions, and validation; outputs with descriptions
• Data sources to reference existing infrastructure without managing it
• State management: remote backends (S3 + DynamoDB), never edit state manually, terraform import
• Modules for reuse: focused on single concern, pin versions in production
• Plan/apply/destroy workflow: init, fmt, validate, plan -out, apply
• Best practices: one state per environment, prevent_destroy on critical resources, tag all resources, moved blocks for refactoring

container-orchestration

Docker Compose patterns for multi-service architectures. Health checks, networking, volumes, and service dependencies. Use when designing docker-compose files, debugging container networking, or managing multi-container applications.

Triggers: When writing Docker Compose files, designing multi-service architectures, debugging container networking, setting up health checks, managing volumes, or configuring environment variables. Tools: Bash(docker:*), Bash(docker-compose:*), Read, Write References: references/compose-patterns.md

Key capabilities:

• Compose file structure: services, networks, and volumes at top level
• Build vs image: build for developed services, image for third-party
• Health checks with depends_on: condition: service_healthy for proper startup ordering
• Networking: custom networks for traffic isolation, service name as hostname, expose vs ports
• Volume strategies: named volumes (persistent), bind mounts (dev), tmpfs (sensitive/cache)
• Environment management: .env files with overrides, never put secrets in docker-compose.yml
• Profiles for optional services (e.g., debug tools)
• Common commands: up -d, logs -f, exec, down -v, config for validation

linux-administration

Essential Linux system administration for developers. File permissions, process management, systemd, journald, cron, and disk management. Use when managing Linux servers, debugging system issues, or writing system scripts.

Triggers: When managing file permissions, investigating processes, creating systemd services, querying logs with journalctl, setting up cron jobs, diagnosing disk issues, managing users, or installing packages. Tools: Bash, Read, Write References: references/commands-cheatsheet.md, references/systemd-reference.md

Key capabilities:

• File permissions and ownership: rwx model, numeric and symbolic notation, special bits (setuid, setgid, sticky)
• Process management: ps aux, pgrep, kill with SIGTERM before SIGKILL, lsof, ss
• User and group management: useradd, usermod -aG, prefer useradd for scripting
• Systemd services: create unit files, systemctl commands, always daemon-reload after edits
• Journald logging: journalctl -u, filter by time and priority, manage journal size
• Cron jobs: crontab format, common schedules, always redirect output
• Disk and filesystem management: df -h, du -sh, lsblk, emergency disk space cleanup
• Package management with apt (Debian/Ubuntu) and dnf (RHEL/Fedora)

shell-scripting

Bash scripting best practices including error handling, argument parsing, and shellcheck compliance. Use when writing shell scripts, reviewing bash code, or automating tasks with shell commands.

Triggers: When writing new shell scripts, reviewing bash code, adding error handling, parsing command-line arguments, or fixing shellcheck warnings. Tools: Bash(shellcheck:*), Bash(bash:*), Read, Write References: references/bash-patterns.md

Key capabilities:

• Script header: shebang (#!/usr/bin/env bash) and strict mode (set -euo pipefail)
• Variable quoting: always double-quote expansions, ${var:-default} for defaults, ${var:?error} for required
• Argument parsing with positional args and getopts for options
• Functions with local variables, return values via stdout
• Error handling and cleanup with trap cleanup EXIT
• Arrays for safe file path handling with find -print0 and read -d ''
• Common pitfalls: never parse ls, use [[ ]] over [ ], $(command) over backticks
• Shellcheck compliance: run on every script, disable warnings locally with comments, never globally

dependency-audit

Audits project dependencies for vulnerabilities and outdated packages. Use when checking security posture or planning dependency updates.

Triggers: When the user asks to “check dependencies”, “audit security”, “update packages”, “are my dependencies safe?”, or before a release to verify dependency health. Tools: None References: None

Key capabilities:

• Identify the package manager and run its audit tool: cargo audit, pip-audit, npm audit, govulncheck
• Review findings by severity: critical/high (fix immediately), medium (plan for current sprint), low (track)
• Update strategy: one dependency at a time, full test suite after each, check changelogs for breaking changes
• Check for outdated packages: cargo outdated, pip list --outdated, npm outdated
• Ongoing maintenance: monthly reviews, Dependabot/Renovate for automated PRs, document pinned versions

repo-management

Repository stewardship across issues, change requests, commits, and pushes. Use when reconciling open issues or PRs/MRs, merging ready work, or committing and pushing local repository changes.

Triggers: When the user asks to “check all open issues”, “check all PRs”, “merge ready PRs”, “repo reconcile”, “commit and push all”, or “clean up the repository”. Tools: processkit-repo-management MCP server References: None

Key capabilities:

• Provider detection for GitHub, GitLab, Gitea, Forgejo/Codeberg, Bitbucket Cloud, Azure DevOps, and SourceHut remotes
• Local git inspection: branch, upstream, dirty state, ahead/behind, and push readiness
• GitHub issue and PR listing through gh when authenticated
• Guarded issue comments/closes, PR merges, local commits, and pushes
• Dry-run reconciliation plans with blockers for unsupported providers, auth gaps, draft PRs, failing checks, and missing upstreams

secret-management

Guides secure handling of secrets – env vars, .env files, vault patterns. Use when dealing with API keys, passwords, tokens, or credentials.

Triggers: When the user needs to handle API keys, passwords, tokens, database credentials, or asks “where should I put this secret?”, “is this safe?”, or “how do I manage credentials?”. Tools: None References: None

Key capabilities:

• Never commit secrets to git: add .env to .gitignore, check history for leaked secrets, rotate if compromised
• Local development: .env files with dotenv pattern, .env.example with placeholder values committed
• CI/CD: platform secret stores (GitHub Secrets, GitLab CI Variables), OIDC tokens over long-lived credentials
• Production: secrets managers (Vault, AWS Secrets Manager), rotate on 90-day schedule, short-lived tokens, least privilege
• Code patterns: read from environment variables, never hardcode, never log secrets, separate secrets per environment

3.4 - Architecture Skills

Skills for software architecture, design patterns, and system design.

software-architecture

Analyzes codebases for architectural patterns and quality. Use when designing systems, creating ADRs, reviewing structure, or generating architecture diagrams.

Triggers: Designing systems, creating ADRs, reviewing code structure, generating C4 diagrams, applying SOLID/DRY/KISS principles Tools: None References: patterns.md

Key capabilities:

• Analyze existing architecture by mapping module organization, dependency directions, and identifying violations (circular deps, layer skipping, leaky abstractions)
• Suggest architecture patterns matched to project type (layered, hexagonal, modular monolith, microservices, pipe-and-filter, event-driven)
• Create Architecture Decision Records (ADRs) with context, decision, and consequences
• Review code for architectural violations: god modules, tight coupling, missing boundaries
• Generate C4 diagrams (System Context, Container, Component) using Mermaid syntax

event-driven-architecture

Event-driven system design including event sourcing, CQRS, pub/sub, saga patterns, and message broker selection. Use when designing event-driven systems, implementing messaging, or reviewing async architectures.

Triggers: Designing event-driven systems, choosing message brokers, implementing event sourcing or CQRS, designing saga patterns, debugging async architecture issues Tools: None References: messaging-patterns.md

Key capabilities:

• Evaluate whether event-driven design is a good fit for the system at hand
• Choose messaging patterns: pub/sub, point-to-point, request-reply, competing consumers
• Select message brokers (Kafka, RabbitMQ, NATS, SQS/SNS, Redis Streams) based on throughput, ordering, replay, and operational requirements
• Implement event sourcing with append-only event streams, snapshots, and schema evolution
• Design CQRS with separate write and read models, handling eventual consistency
• Implement saga patterns (orchestration vs. choreography) for distributed transactions
• Ensure reliability with idempotent consumers, dead letter queues, outbox pattern, and schema registries

domain-driven-design

Domain-Driven Design strategic and tactical patterns. Bounded contexts, aggregates, value objects, and context mapping. Use when modeling complex domains, designing microservice boundaries, or reviewing domain models.

Triggers: Modeling complex business domains, defining microservice boundaries, reviewing domain models, creating ubiquitous language, refactoring monoliths Tools: None References: ddd-building-blocks.md

Key capabilities:

• Establish ubiquitous language with precise domain term definitions aligned between code and domain experts
• Strategic design: identify bounded contexts by mapping business capabilities and linguistic boundaries
• Context mapping with patterns: Shared Kernel, Customer-Supplier, Conformist, Anti-Corruption Layer, Open Host Service, Published Language
• Tactical design: aggregate design with small aggregates, single root, transactional boundaries, and ID-based references
• Model entities (identity-based), value objects (attribute-based, immutable), and domain events (past-tense, immutable facts)
• Design repositories, domain services, and factories following DDD principles
• Identify anti-patterns: anemic domain model, god aggregate, leaking context, shared database

system-design

System design methodology from requirements through capacity estimation to component design and trade-offs. Use when designing distributed systems, evaluating architectures, or preparing system design discussions.

Triggers: Designing distributed systems from scratch, evaluating scalability and reliability, performing capacity estimation, discussing architectural trade-offs Tools: None References: estimation-cheatsheet.md

Key capabilities:

• Gather functional and non-functional requirements (scale, latency, availability, consistency, durability, cost)
• Back-of-envelope capacity estimation: users to QPS, storage, bandwidth, and compute
• High-level design with 5-10 major components following data flow from client inward
• Component deep dives: API design, data model, scaling strategy, failure handling, caching
• Trade-off analysis: consistency vs. availability, latency vs. throughput, simplicity vs. scalability
• Apply scalability patterns: horizontal scaling, sharding, read replicas, caching layers, async processing, rate limiting, circuit breakers

3.5 - Design & Visual Skills

Skills for frontend development, visual design, and creative production.

excalidraw

Generates Excalidraw diagrams programmatically as JSON. Use when creating architecture diagrams, flowcharts, or hand-drawn-style visuals for documentation.

Triggers: Creating architecture diagrams, flowcharts, system diagrams, or hand-drawn-style visuals for documentation Tools: None References: json-schema.md

Key capabilities:

• Generate Excalidraw JSON files with proper structure (elements, appState, version 2 format)
• Create element types: rectangles, ellipses, diamonds, lines, arrows, text, with configurable styles
• Bind text labels to shapes for labeled diagrams
• Follow layout guidelines: grid alignment (multiples of 20), consistent spacing, readable font sizes
• Apply a semantic color palette (primary, secondary, success, warning, danger, neutral)
• Produce architecture diagrams, flowcharts, and sequence-style diagrams
• Embed in documentation as .excalidraw, SVG, or PNG

frontend-design

Frontend architecture and UI design – component hierarchies, accessibility, performance, state management. Use when designing or reviewing frontend applications.

Triggers: Designing frontend architecture, building component hierarchies, implementing accessibility, optimizing performance, structuring React/Next.js projects Tools: None References: accessibility-checklist.md

Key capabilities:

• Design component architecture with single-responsibility, container vs. presentational separation, and composition over configuration
• Apply semantic HTML first (landmarks, correct elements, ARIA only when needed)
• Implement WCAG 2.2 AA accessibility: keyboard navigation, focus management, color contrast, target size, motion preferences
• Choose state management by complexity: useState, Context, Zustand/Jotai/Redux, TanStack Query, React Hook Form
• Apply React/Next.js patterns: Server Components, Client Components, Suspense streaming, SSG/SSR/ISR
• Optimize Core Web Vitals: LCP, INP, CLS with specific techniques
• Select styling approaches: Tailwind CSS, CSS Modules, Vanilla CSS, CSS-in-JS with trade-off analysis
• Structure Next.js App Router projects with route groups, layouts, and feature-based organization

infographics

Creates data-driven infographics and charts as SVG. Use when visualizing data, creating charts, or designing informational graphics.

Triggers: Creating charts, graphs, data visualizations, infographics, or visual summaries from data Tools: None References: best-practices.md

Key capabilities:

• Generate standalone SVG files with proper viewBox, responsive scaling, and semantic structure
• Map data to visuals: identify the message, choose encoding (position, length, angle, area, color), apply visual hierarchy
• Select chart types based on data relationship: line for trends, bar for comparison, histogram for distribution, scatter for correlation, treemap for hierarchy
• Apply visual design: 3-5 color palette, typography hierarchy, generous whitespace, direct data labels
• Ensure accessibility: 4.5:1 contrast ratio, patterns alongside color, <title> and <desc> for screen readers
• Avoid common pitfalls: truncated y-axis, 3D effects, pie charts with many slices, dual y-axes, rainbow colormaps
• Alternative formats when appropriate: Mermaid, ASCII art, CSV with narrative

logo-design

Creates SVG logos with proper scalability, color theory, and variant generation. Use when designing logos, icons, or brand marks.

Triggers: Designing logos or brand marks, generating favicons, reviewing logo scalability, applying color theory to branding Tools: None References: design-principles.md

Key capabilities:

• Apply logo design principles: simplicity (recognizable at 16x16), memorability, timelessness, versatility, appropriateness
• Construct SVG logos with clean geometric shapes, proper viewBox, optimized paths, and meaningful groups
• Apply color theory: monochromatic, complementary, analogous, triadic, split-complementary schemes with 2-3 color maximum
• Handle typography in logos: font personality, custom ligatures, text-to-path conversion, optical spacing
• Generate logo variants: full logo, icon/mark only, favicon (16x16, 32x32), monochrome, reversed (dark mode), social banner
• Test and validate: render at multiple sizes, test on varied backgrounds, simulate colorblindness, verify single-color reproduction

tailwind

Tailwind CSS v4 patterns – utility-first styling, responsive design, dark mode, component extraction. Use when building or reviewing Tailwind-based UIs.

Triggers: Building UIs with Tailwind CSS, styling components, setting up Tailwind, implementing responsive layouts or dark mode Tools: None References: cheatsheet.md

Key capabilities:

• Set up Tailwind v4 projects with @import "tailwindcss" and @theme design tokens (no config file needed)
• Apply utility-first principles: compose styles in markup, group by concern, avoid arbitrary values
• Extract components in the framework (React/Vue/Svelte), not with @apply
• Implement responsive design: mobile-first breakpoints, container queries, content width constraints
• Configure dark mode with semantic color tokens and .dark class overrides
• Use OKLCH color space, color-mix() via opacity modifiers, and multi-brand theming
• Optimize performance: automatic unused CSS elimination, avoid dynamic class construction
• Ensure accessibility: focus-visible: styles, motion-reduce:, sr-only, contrast compliance

pixijs-gamedev

PixiJS 2D rendering and game development including sprites, animations, interactions, and WebGL/Canvas rendering. Use when building PixiJS applications, creating 2D games, or implementing interactive graphics.

Triggers: Building 2D games or interactive graphics with PixiJS, managing sprites, animation loops, event handling, or WebGL rendering Tools: Bash(npm:*) Bash(npx:*) Read Write References: api-cheatsheet.md

Key capabilities:

• Set up PixiJS Application with await app.init(), responsive canvas, HiDPI rendering
• Manage sprites and textures: Assets.load(), Spritesheet atlases, anchor centering, texture caching
• Build display hierarchies with Containers, child transforms, zIndex sorting, ParticleContainer for bulk sprites
• Implement animation: app.ticker.add() with deltaTime, GSAP tweening, AnimatedSprite frame playback
• Handle interaction and events: eventMode, pointer events, custom hitArea, drag patterns, cursor styles
• Draw vector graphics with Graphics(): shapes, chained fills/strokes, shared GraphicsContext
• Apply filters and effects: BlurFilter, ColorMatrixFilter, DisplacementFilter, AlphaFilter
• Load assets with bundles, progress callbacks, and lazy loading for secondary assets
• Optimize performance: ParticleContainer, texture atlases, object pooling, GPU memory management

mobile-app-design

Mobile app UX design including touch targets, navigation patterns, platform conventions, and accessibility. Use when designing mobile interfaces, reviewing mobile UX, or adapting web designs for mobile.

Triggers: Designing mobile interfaces, reviewing mobile UX, adapting web designs for iOS and Android, implementing touch interactions Tools: None References: platform-guidelines.md

Key capabilities:

• Size touch targets correctly: 44x44pt (iOS) / 48x48dp (Android) minimum, with 8pt gaps between targets
• Choose navigation patterns: tab bar (3-5 destinations), navigation drawer (5+), stack navigation, modal sheets
• Design responsive layouts: smallest screen first (375pt/360dp), 4pt/8pt spacing grid, Dynamic Type support
• Follow iOS vs. Android conventions: back navigation, button styles, alerts, typography, icons
• Implement gesture patterns: tap, long press, swipe, pull to refresh, pinch to zoom – with visible alternatives
• Ensure accessibility: screen reader support, 4.5:1 contrast, font scaling, reduced motion, VoiceOver/TalkBack testing
• Design offline-first: cached content, offline indicators, action queuing, optimistic UI, conflict resolution
• Handle push notifications: contextual permission requests, grouping, deep linking, in-app controls
• Create onboarding flows: 3-5 screens max, show value first, progressive disclosure, skip option on every screen

3.6 - Data & Analytics Skills

Skills for data science, data engineering, and analytics workflows.

data-science

Data analysis workflow from import through modeling and communication. Covers tidy data, EDA, statistical reasoning, and visualization. Use when analyzing datasets, building statistical models, exploring data, or communicating findings.

Triggers: Analyzing datasets, exploring data, building statistical models, creating visualizations, cleaning messy data, communicating findings Tools: Bash(python:*) Bash(jupyter:*) Read Write References: tidy-data-principles.md, statistical-methods.md, visualization-guidelines.md

Key capabilities:

• Import and clean data: inspect shape/dtypes/nulls, handle missing data explicitly, parse dates, validate assumptions
• Reshape data to tidy form (one variable per column, one observation per row) using melt/pivot
• Conduct exploratory data analysis: univariate distributions, bivariate relationships, outlier detection, groupby aggregations
• Apply statistical reasoning: state the question first, check assumptions, report effect sizes alongside p-values, use confidence intervals
• Perform feature selection: remove zero-variance features, handle multicollinearity, use domain knowledge then data-driven methods
• Follow model selection workflow: start simple (baseline), add complexity only when justified, use cross-validation, document decisions
• Visualize with best practices: titles, axis labels, colorblind-friendly palettes, annotations, publication-quality export
• Communicate results: lead with findings, plain language, show uncertainty, include actionable “so what”

data-pipeline

Data pipeline patterns including ETL/ELT, batch vs streaming, idempotency, and orchestration. Use when designing data pipelines, reviewing data workflows, or troubleshooting data processing.

Triggers: Designing data pipelines, choosing batch vs. streaming, implementing data ingestion or transformation, setting up orchestration, debugging pipeline failures Tools: Bash Read Write References: None

Key capabilities:

• Choose between ETL and ELT based on target system capabilities and governance requirements
• Decide batch vs. streaming: start with batch unless explicit real-time requirement, micro-batch as middle ground
• Ensure idempotency: upserts, partition overwrite on rerun, deduplication by natural key hash
• Implement data quality checks at each stage: row counts, null checks, value range validation, fail fast on violations
• Manage schemas with registries, backward compatibility, versioning, and field documentation
• Design backfill strategies with date-range parameters, partition overwrite, and progress tracking
• Set up orchestration (Airflow, Prefect, Dagster) with explicit DAG dependencies, retries with exponential backoff, and SLA tagging
• Monitor pipelines with alerts on failure/SLA breach, metadata logging, and dead letter queues for failed records

data-visualization

Data visualization best practices including chart selection, color accessibility, and dashboard design. Use when creating charts, designing dashboards, or reviewing data presentations.

Triggers: Creating charts, designing dashboards, choosing visualization types, improving chart readability, reviewing data presentations Tools: Bash(python:*) Read Write References: chart-selection.md

Key capabilities:

• Select chart types by data relationship: bar for comparison, line for trend, histogram for distribution, scatter for relationship
• Apply color and accessibility: colorblind-friendly palettes (viridis, cividis), sequential/diverging/categorical schemes, 7-color maximum
• Annotate insights: max/min values, threshold lines, trend-change events, direct labels instead of legends
• Design dashboard layouts: most important metric top-left, consistent grid, grouped by domain, filters at top, 6-8 visualizations max
• Tell stories with data: lead with conclusion, context-finding-implication structure, progressive disclosure, highlight the relevant
• Choose static vs. interactive: matplotlib/seaborn for reports, plotly/Altair/D3 for dashboards with tooltips and zoom
• Avoid common mistakes: truncated y-axis on bars, dual y-axes, overplotting, missing units, default titles, excess decimal places

feature-engineering

Feature engineering for ML including encoding, imputation, scaling, selection, and time-series features. Use when preparing data for ML models, selecting features, or engineering new features from raw data.

Triggers: Preparing data for ML models, encoding categorical variables, handling missing data, creating new features, selecting features, building time-series features Tools: Bash(python:*) Read Write References: None

Key capabilities:

• Encode categorical variables: one-hot (< 15 values), ordinal (natural order), target encoding (high cardinality, cross-validated), frequency encoding
• Handle missing data: understand missingness mechanism (MCAR/MAR/MNAR), median/mode imputation, binary indicator columns, KNN/MICE for correlated features
• Scale features: StandardScaler for linear models, MinMaxScaler for neural networks, RobustScaler for outlier-heavy data; tree models need no scaling
• Select features: filter methods (correlation, mutual information), wrapper methods (RFE), embedded methods (L1, tree importance, permutation importance)
• Engineer time-series features: lag values, rolling statistics, seasonal extraction (hour/day/month with sin/cos encoding), difference features, expanding statistics
• Create text features: TF-IDF, count vectorizer, pre-trained embeddings, extracted features (length, sentiment, readability)
• Build interaction and derived features: multiplication, ratios, polynomial terms, domain-driven binning, log transforms
• Prevent data leakage: fit transformers on training data only, respect temporal ordering, use sklearn Pipeline

data-quality

Data quality framework covering completeness, accuracy, consistency, validation rules, and data contracts. Use when implementing data validation, setting up data quality checks, or defining data contracts.

Triggers: Implementing data validation, setting up quality checks for pipelines, defining data contracts between teams, investigating data anomalies Tools: Bash Read Write References: None

Key capabilities:

• Evaluate data against six dimensions: completeness, accuracy, consistency, timeliness, uniqueness, validity
• Define validation rules: schema validation, range checks, format checks, referential integrity, business rules, freshness checks – categorized by severity (error vs. warning)
• Detect anomalies: track metrics over time (row counts, null rates, distinct values), alert on threshold deviations, monitor distribution shifts and schema changes
• Define data contracts: formal agreements on schema, SLAs, quality thresholds, ownership – versioned and machine-readable (JSON Schema, protobuf, YAML)
• Implement Great Expectations patterns: expectation suites per table, core expectations (row count, not null, unique, in set), pipeline integration
• Set up data observability: metadata instrumentation, lineage graphs, health dashboards, automated root cause analysis
• Place quality checks at pipeline boundaries with stored results, configurable thresholds, and the five critical checks (row count, null rate, duplicate rate, freshness, schema match)

3.7 - AI & ML Skills

Skills for AI/ML development, RAG pipelines, prompt engineering, and model evaluation.

ai-fundamentals

Core ML/AI concepts including model types, training pipelines, evaluation metrics, and neural network architectures. Use when explaining AI concepts, choosing model approaches, designing ML solutions, or reviewing AI-related code.

Triggers: Explaining ML/AI concepts, choosing model architectures, designing training pipelines, selecting evaluation metrics, debugging model performance (overfitting, leakage, class imbalance) Tools: None References: ml-concepts.md, math-foundations.md

Key capabilities:

• Classify problems by learning paradigm: supervised, unsupervised, reinforcement, self-supervised
• Match model types to problems: linear models for baselines, tree-based (XGBoost/LightGBM) for tabular data, neural networks for unstructured data, probabilistic models for uncertainty
• Design correct training pipelines: data prep, train/val/test split before preprocessing, feature engineering, training, hyperparameter tuning, regularization, final evaluation
• Select evaluation metrics by task: F1/AUC-ROC for classification, RMSE/MAE for regression, NDCG/MAP for ranking, BLEU/ROUGE for generation
• Understand neural network architectures: MLP, CNN, RNN/LSTM, Transformer, GAN, VAE, diffusion models
• Explain modern LLM concepts: attention, tokenization, pre-training + fine-tuning, RLHF, prompting strategies, scaling laws
• Identify common pitfalls: data leakage, overfitting, underfitting, class imbalance, distribution shift, metric mismatch

rag-engineering

Retrieval-Augmented Generation pipeline design including document ingestion, chunking, embedding, vector stores, retrieval strategies, and evaluation. Use when building RAG systems, optimizing retrieval quality, or debugging RAG pipelines.

Triggers: Building RAG pipelines, choosing chunking/embedding/vector store strategies, debugging poor retrieval quality or hallucinations, evaluating RAG systems Tools: Bash Read Write References: chunking-strategies.md, retrieval-patterns.md, evaluation.md

Key capabilities:

• Design end-to-end RAG architecture: indexing (parse, chunk, embed, store) and query (embed, retrieve, construct prompt, generate)
• Ingest documents from PDF, HTML, and code with metadata extraction (source, title, section, page, date)
• Choose chunking strategies: fixed-size with overlap, sentence-based, semantic chunking, recursive character, document-structure-aware
• Select embedding models by domain, dimensionality, context window, and cost (OpenAI, nomic, bge, voyage)
• Choose vector stores: FAISS for prototyping, Chroma for local dev, pgvector for Postgres shops, Qdrant for production, Pinecone for zero ops
• Implement retrieval strategies: dense, sparse (BM25), hybrid search with RRF, reranking with cross-encoders, MMR for diversity, parent-document retrieval, multi-query
• Construct effective prompts: context ordering, window budgeting, citation numbering, chunk deduplication, low-similarity handling
• Evaluate with RAGAS metrics: context precision, context recall, faithfulness, answer relevance – using golden datasets of 50-100 triples

prompt-engineering

Prompt design patterns for LLMs including few-shot, chain-of-thought, structured output, and injection defense. Use when crafting prompts, optimizing LLM outputs, or building prompt-based features.

Triggers: Crafting or refining LLM prompts, improving output quality and consistency, designing system prompts, implementing structured output, defending against prompt injection Tools: None References: techniques-catalog.md

Key capabilities:

• Structure prompts with role/context, task, constraints, examples, and input – using delimiters for separation
• Apply core techniques: zero-shot, few-shot (2-5 diverse examples), chain-of-thought, self-consistency, structured output with JSON schema
• Design system prompts: persona definition, hard constraints, output format, domain knowledge – versioned and tested
• Tune temperature and sampling: 0.0-0.3 for factual/code, 0.5-0.8 for creative, top-p as alternative, appropriate max tokens and stop sequences
• Defend against prompt injection: input sanitization, delimited input sections, output validation, privilege separation, canary tokens
• Build reusable prompt templates with variable slots and systematic iteration (test on 10-20 inputs, identify failure modes, add constraints)
• Evaluate prompts systematically: build eval sets of 20-50 pairs, score pass/fail or rubric-based, track metrics across versions

llm-evaluation

LLM output evaluation including automated metrics, LLM-as-judge, A/B testing, and regression testing. Use when evaluating model outputs, building eval pipelines, or comparing prompt versions.

Triggers: Measuring LLM output quality, comparing prompt or model versions, building automated evaluation pipelines, setting up regression testing, detecting bias Tools: None References: None

Key capabilities:

• Build evaluation datasets: 50-100 representative input/expected-output pairs from real usage, including edge cases, with metadata labels
• Apply automated metrics: text overlap (BLEU, ROUGE, exact match), semantic similarity (BERTScore, embedding similarity), task-specific (Pass@k for code, schema compliance)
• Implement LLM-as-judge: rubric with 3-5 criteria scored 1-5, temperature 0.0, mitigations for position bias, multi-judge averaging, calibration against human ratings
• Conduct human evaluation: 3+ raters per example, clear rubrics, blinded to version, Cohen’s kappa for agreement
• Run A/B testing: same eval set, automated + LLM-as-judge scoring, distribution comparison, significance testing, regression checking
• Set up regression testing: golden test suite with expected outputs, threshold-based pass/fail in CI, trend alerting
• Detect bias and safety issues: demographically diverse inputs, stereotyping/toxicity checks, red-teaming, refusal rate monitoring
• Evaluate RAG pipelines with RAGAS: context precision, context recall, faithfulness, answer relevance

embedding-vectordb

Vector embeddings and vector database patterns including model selection, similarity metrics, and index tuning. Use when building semantic search, choosing vector stores, or optimizing embedding pipelines.

Triggers: Choosing embedding models, selecting or migrating vector databases, optimizing semantic search, implementing hybrid search, tuning vector index parameters Tools: None References: None

Key capabilities:

• Select embedding models: commercial (OpenAI text-embedding-3, Cohere embed-v3, Voyage) and open-source (nomic, bge, e5-mistral, MiniLM) with trade-offs on quality, dimensions, context window, latency, and cost
• Use Matryoshka embeddings for dimension reduction (3072 to 1024 or 512) without retraining
• Choose similarity metrics: cosine similarity (default), dot product (when magnitude matters), Euclidean (spatial clustering)
• Select vector databases: FAISS (prototyping), pgvector (Postgres), Chroma (local dev), Qdrant (production), Weaviate (multimodal), Pinecone (managed), Milvus (billions of vectors)
• Tune index types: HNSW (default, tune M/ef_construction/ef_search), IVF (large datasets, tune nlist/nprobe), PQ (memory-constrained)
• Implement hybrid search: dense + sparse (BM25) with Reciprocal Rank Fusion
• Configure metadata filtering and multi-tenancy with pre-filter strategy
• Optimize embedding pipelines: batch processing, content-hash caching, normalization, chunk-before-embed ordering, monitoring

ml-pipeline

ML pipeline design including data versioning, experiment tracking, model deployment, and drift monitoring. Use when building ML pipelines, setting up MLOps, or reviewing ML infrastructure.

Triggers: Building ML pipelines from data to deployment, setting up experiment tracking, choosing deployment patterns, implementing drift monitoring, designing ML CI/CD Tools: Bash Read Write References: pipeline-stages.md

Key capabilities:

• Design reproducible pipeline architecture: data collection through versioning, feature engineering, training, evaluation, registry, deployment, monitoring
• Version data with DVC, Delta Lake, or immutable datasets in object storage with naming conventions
• Set up feature stores (Feast, Tecton, Hopsworks) for consistent online/offline feature access, or skip for simple projects
• Track experiments with MLflow, W&B, or Neptune: log git hash, dataset version, hyperparameters, metrics per epoch, model artifacts, environment
• Manage model registry: versioned models with staging/production/archived lifecycle, model cards, promotion gates
• Choose deployment patterns: shadow (validation), canary (gradual rollout), A/B test (business metrics), blue-green (instant rollback), feature flag (kill switch)
• Monitor for drift: data drift (KS test, PSI), concept drift (prediction distribution shift, business metric tracking), operational metrics (latency, error rate, resource utilization)
• Implement ML CI/CD: unit tests and smoke training on CI, full evaluation + bias checks + shadow deployment + canary rollout on CD

3.8 - API & Integration Skills

Skills for API design, protocol patterns, and system integration.

api-design

REST API design including resource naming, HTTP methods, status codes, pagination, versioning, and OpenAPI specs. Use when designing APIs, reviewing API contracts, or writing OpenAPI/Swagger documentation.

Triggers: Designing a new REST API or extending an existing one, reviewing API contracts, writing OpenAPI/Swagger docs, choosing pagination or versioning strategies, defining error response formats. Tools: Bash Read Write References: rest-conventions.md, openapi-patterns.md

Key capabilities:

• Resource naming conventions (plural nouns, kebab-case, shallow nesting)
• HTTP method-to-CRUD mapping with correct status codes
• Cursor-based and offset-based pagination patterns
• Filtering and sorting via query parameters
• URI path versioning and header versioning strategies
• Consistent error response envelope format
• Rate limiting headers (X-RateLimit-Limit, Remaining, Reset)
• HATEOAS links for discoverable APIs
• OpenAPI 3.1 spec authoring with reusable components
• API design review checklist (8-point verification)

graphql-patterns

GraphQL schema design, resolver patterns, N+1 prevention with DataLoader, and federation. Use when designing GraphQL APIs, implementing resolvers, or optimizing GraphQL performance.

Triggers: Designing a GraphQL schema, implementing resolvers, diagnosing N+1 query problems, adding pagination, setting up federation, evolving a schema without breaking clients. Tools: Bash Read Write References: None

Key capabilities:

• Schema design from the client perspective (types, queries, mutations, subscriptions)
• Resolver patterns (root, field, default) with thin resolver architecture
• N+1 problem diagnosis and DataLoader batching/caching solution
• Relay Connection Spec cursor-based pagination
• Domain errors as union types for type-safe error handling
• Apollo Federation with @key directives and subgraph composition
• Schema evolution rules (safe additions, deprecation with @deprecated, breaking change avoidance)
• Automatic persisted queries (APQ) for bandwidth and security

grpc-protobuf

Protocol Buffers schema design and gRPC service patterns including streaming, error handling, and backward compatibility. Use when designing gRPC services, writing .proto files, or implementing gRPC clients/servers.

Triggers: Designing .proto files, implementing gRPC services (unary, streaming), choosing communication patterns, handling errors with gRPC status codes, ensuring backward compatibility, adding interceptors. Tools: Bash(protoc:*) Bash(grpcurl:*) Read Write References: proto-conventions.md

Key capabilities:

• Proto3 schema design with proper packaging, enums (UNSPECIFIED zero value), and timestamps
• Four gRPC service patterns: unary, server streaming, client streaming, bidirectional
• Dedicated Request/Response wrapper messages per RPC
• Error handling with gRPC status codes (INVALID_ARGUMENT, NOT_FOUND, UNAVAILABLE, etc.)
• Rich error details using google.rpc.Status with BadRequest/ErrorInfo
• Backward compatibility rules and reserved field management
• Interceptor chains for auth, logging, metrics, and validation
• Tooling guidance: buf for linting/breaking change detection, grpcurl for invocation

webhook-integration

Webhook design and consumption including signature verification, idempotency, retry handling, and security. Use when implementing webhooks, designing event notification systems, or debugging webhook deliveries.

Triggers: Designing a webhook system for event notifications, implementing a webhook consumer, adding HMAC-SHA256 signature verification, debugging failed deliveries or duplicate processing, setting up dead letter queues. Tools: Bash(curl:*) Read Write References: None

Key capabilities:

• Payload design with unique event IDs, dotted type names, and stable envelope format
• HMAC-SHA256 signature verification with constant-time comparison and replay prevention
• Idempotency via event ID deduplication with TTL-bounded storage
• Retry handling with exponential backoff (sender) and async processing (consumer)
• Dead letter queues for exhausted retries with replay tooling
• Out-of-order event handling with version/sequence numbers
• Local testing with ngrok/cloudflared and payload inspection tools
• Security hardening: TLS-only, IP allowlisting, payload size limits, vault-stored secrets

3.9 - Security Skills

Skills for application security, authentication, and threat analysis.

dependency-audit

Audits project dependencies for vulnerabilities and outdated packages. Use when checking security posture or planning dependency updates.

Triggers: Checking dependencies, auditing security, updating packages, verifying dependency health before a release. Tools: None References: None

Key capabilities:

• Multi-ecosystem audit tool selection (cargo audit, pip-audit, npm audit, govulncheck)
• Severity-based triage: critical/high (fix immediately), medium (this sprint), low (when convenient)
• Update strategy: one dependency at a time, full test suite after each, changelog review
• Outdated package detection (cargo outdated, pip list –outdated, npm outdated)
• Ongoing maintenance: monthly reviews, Dependabot/Renovate automation, pinned version documentation

secret-management

Guides secure handling of secrets – env vars, .env files, vault patterns. Use when dealing with API keys, passwords, tokens, or credentials.

Triggers: Handling API keys, passwords, tokens, database credentials, or asking where to store secrets and how to manage credentials. Tools: None References: None

Key capabilities:

• Git secret prevention: .gitignore setup, history scanning, immediate rotation if committed
• Local development: .env files with dotenv pattern, .env.example with placeholders
• CI/CD: platform secret stores (GitHub Secrets, GitLab CI Variables), OIDC tokens over long-lived credentials
• Production: secrets managers (Vault, AWS/GCP Secret Manager), 90-day rotation, least-privilege access
• Code patterns: environment variable reads, no hardcoding, secret redaction in logs, per-environment isolation

auth-patterns

Authentication and authorization patterns including OAuth2, JWT, session management, and RBAC/ABAC. Use when implementing login flows, securing APIs, managing tokens, or designing permission systems.

Triggers: Implementing OAuth2 login flows, working with JWTs, designing session management, building RBAC or ABAC permission systems, securing API endpoints, reviewing authentication code. Tools: Bash Read Write References: oauth-flows.md, jwt-reference.md

Key capabilities:

• OAuth2 flow selection by client type (Authorization Code, PKCE, Client Credentials, Device Authorization)
• JWT best practices: validation (signature, exp, iss, aud), short expiry, RS256/ES256, JWKS rotation
• Token refresh pattern with single-use rotating refresh tokens
• Session management: cryptographic IDs, server-side storage, HttpOnly/Secure/SameSite cookies, idle and absolute timeouts
• RBAC with permission-to-role mapping and role-to-user assignment
• ABAC with policy evaluation based on subject, resource, action, and context attributes
• API key patterns: prefixed keys, hashed storage, scoped permissions
• CORS configuration with explicit origins (never wildcard with credentials)
• Security review checklist (8-point verification for auth implementations)

secure-coding

Secure coding practices based on OWASP Top 10. Injection prevention, XSS mitigation, CSRF protection, input validation, and security headers. Use when reviewing code for security, implementing auth, or hardening web applications.

Triggers: Reviewing code for security vulnerabilities, implementing input validation or output encoding, adding security headers, preventing injection attacks, implementing CSRF protection, auditing for secrets exposure, hardening before production. Tools: Bash Read Write References: owasp-checklist.md

Key capabilities:

• Input validation: allowlist over denylist, type/length/range/format checks, server-side enforcement
• Context-aware output encoding (HTML body, attributes, JavaScript, URL, CSS)
• Injection prevention: parameterized SQL queries, subprocess argument lists (no shell=True)
• CSRF protection: anti-CSRF tokens, SameSite cookies, Origin/Referer verification
• Security headers: CSP, HSTS, X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy
• Secrets management: environment variables, .gitignore patterns, per-environment isolation
• Dependency security: regular audits, pinned versions, minimized dependency tree
• Security review checklist (10-point verification covering input, output, auth, headers, secrets, deps)

threat-modeling

Threat modeling using STRIDE methodology. Data flow diagrams, trust boundaries, attack surface mapping, and risk assessment. Use when analyzing system security, designing secure architectures, or conducting security reviews.

Triggers: Designing a new system handling sensitive data, reviewing architecture for security, conducting threat assessments, identifying trust boundaries and attack surfaces, prioritizing security work by risk. Tools: None References: None

Key capabilities:

• STRIDE methodology: Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege
• Data flow diagram creation with processes, data stores, data flows, external entities, and trust boundaries
• Trust boundary identification across network segments, privilege levels, and service boundaries
• Systematic STRIDE analysis applied to each component and data flow
• Risk assessment matrix (likelihood x impact) with Critical/High/Medium/Low ratings
• Mitigation strategies mapped to each STRIDE category (MFA, encryption, audit logging, rate limiting, etc.)
• Attack surface mapping across network, application, authentication, data, infrastructure, and human vectors
• Structured output format with system description, DFD, assets, threat table, and prioritized recommendations

3.10 - Observability Skills

Skills for logging, monitoring, tracing, and alerting in production systems.

logging-strategy

Structured logging strategy including log levels, correlation IDs, context propagation, and PII avoidance. Use when designing logging, reviewing log statements, or setting up log aggregation.

Triggers: Designing a logging approach, reviewing existing log statements, setting up log aggregation (ELK, Loki, CloudWatch), adding correlation IDs, deciding what to log and what to avoid. Tools: Bash Read Write References: structured-logging.md

Key capabilities:

• Six log levels with clear usage guidance (TRACE through FATAL) and rules for choosing between them
• Structured logging (JSON/key-value) over unstructured text for machine parseability
• Correlation IDs: generate request_id at system boundary, propagate via X-Request-ID header, include in every log line
• W3C Trace Context propagation with trace_id and span_id for distributed systems
• MDC (Mapped Diagnostic Context) for transparent ID propagation
• What to log: request summaries, state transitions, decision points, errors, performance data, lifecycle events, retries, external calls
• What NOT to log: PII, secrets, sensitive business data, high-cardinality user input
• Log aggregation: centralized systems, JSON ingestion, retention policies (hot/warm/cold), rotation by size or time
• Performance considerations: lazy evaluation, avoid logging in tight loops, sampling, async appenders
• Anti-pattern detection: log-and-throw, everything-at-INFO, string concatenation, missing context, swallowed exceptions

metrics-monitoring

Application metrics and monitoring using RED/USE methods, Prometheus patterns, and SLO-based alerting. Use when instrumenting applications, designing dashboards, or setting up monitoring.

Triggers: Instrumenting an application with metrics, designing monitoring dashboards, setting up alerting, choosing metric types, defining SLIs/SLOs, applying observability methodology (RED, USE, golden signals). Tools: Bash Read Write References: metric-types.md

Key capabilities:

• Four Golden Signals (Google SRE): latency, traffic, errors, saturation
• RED method for request-driven services: rate, errors, duration (p50/p95/p99)
• USE method for infrastructure resources: utilization, saturation, errors
• Prometheus metric types: counter, gauge, histogram, summary with naming conventions
• Dashboard design: golden signals first, percentile latency, layered dashboards, deployment markers
• Alerting thresholds: symptom-based over cause-based, SLO burn-rate alerting, baseline-derived thresholds, multi-window alerting
• SLI/SLO/SLA framework: quantitative indicators, target objectives, error budgets, budget-based feature freezes
• Instrumentation checklist: endpoint RED metrics, dependency metrics, queue depth, connection pools, business metrics, runtime metrics

distributed-tracing

Distributed tracing with OpenTelemetry including spans, traces, context propagation, and sampling strategies. Use when instrumenting distributed systems, debugging request flows, or setting up tracing infrastructure.

Triggers: Instrumenting a distributed system with tracing, debugging requests spanning multiple services, setting up OpenTelemetry, choosing sampling strategies, understanding latency across service boundaries. Tools: Bash Read Write References: None

Key capabilities:

• Core concepts: traces, spans (with parent-child tree structure), context propagation, baggage
• OpenTelemetry architecture: SDK, API, Exporter, Collector, auto-instrumentation
• Instrumentation strategy: auto-instrumentation first, then manual spans for business logic
• Span naming (component.operation), attributes (HTTP, DB, business context), and error recording
• Context propagation: W3C Trace Context (traceparent/tracestate), B3, message queues, async boundaries
• Head-based sampling: probabilistic and rate-limiting approaches
• Tail-based sampling via OTel Collector: error-based, latency-based, and policy-based rules
• Trace analysis for debugging: critical path identification, gap detection, fast-vs-slow comparison, waterfall analysis
• Common pitfalls: missing propagation, over-instrumentation, sensitive data in attributes, no production sampling, broken async traces

alerting-oncall

Alert design and on-call practices including severity levels, runbooks, SLO-based alerting, and escalation policies. Use when designing alerts, writing runbooks, or improving on-call processes.

Triggers: Designing alerts for a service, writing runbooks, reducing alert fatigue, setting up escalation policies, implementing SLO-based alerting, improving on-call processes. Tools: None References: None

Key capabilities:

• Alert severity levels: P1 (immediate, page), P2 (30 min, page), P3 (4 hours, ticket), P4 (1 business day, ticket)
• Page vs ticket decision framework based on user impact and intervention urgency
• SLO-based burn-rate alerting with multi-window thresholds (14.4x/5min+1hr for P1, 6x/30min+6hr for P2, 3x/2hr+24hr for P3)
• Runbook template: what it means, likely causes, diagnosis steps, mitigation, escalation
• Alert fatigue prevention: track volume (<2 pages/shift target), weekly review, merge related alerts, auto-resolve transients
• Escalation policies: primary to secondary (10 min P1, 30 min P2), to engineering lead (1hr P1, 4hr P2), incident declaration
• On-call handoff practices: consistent timing, written summaries, acknowledgment, shadow rotations for new members
• Incident communication: dedicated channel, initial summary, 15-30 min updates, status page, post-incident review within 48 hours

3.11 - Database Skills

Skills for SQL, data modeling, NoSQL patterns, and schema migrations.

sql-patterns

SQL query patterns, schema design, and optimization. Joins, CTEs, window functions, indexing, and anti-patterns. Use when writing SQL queries, designing schemas, optimizing database performance, or reviewing database code.

Triggers: Writing or optimizing SQL queries (joins, CTEs, window functions), designing or reviewing schemas, analyzing EXPLAIN plans, choosing indexing strategies, fixing slow queries, implementing pagination or analytical queries. Tools: Bash Read Write References: query-patterns.md, schema-design.md

Key capabilities:

• Query construction: join types (INNER, LEFT, FULL OUTER, CROSS), CTEs over nested subqueries, window functions (RANK, LAG, SUM OVER)
• Aggregation evaluation order: WHERE, GROUP BY, HAVING, window functions
• Query optimization process: EXPLAIN plan reading, index verification, early filtering, anti-pattern avoidance
• Anti-patterns: SELECT *, functions on indexed columns, NOT IN with NULLs, correlated subqueries, missing LIMIT, implicit type conversions
• Indexing strategy: B-tree, Hash, GIN, GiST, composite (leftmost prefix rule), partial, covering (INCLUDE)
• Transactions and concurrency: isolation levels (READ COMMITTED, REPEATABLE READ, SERIALIZABLE), SELECT FOR UPDATE, deadlock handling
• Schema design basics: normalize to 3NF by default, surrogate keys, timestamps, foreign keys, named constraints

database-modeling

Data modeling approaches including ER diagrams, normalization, denormalization trade-offs, and schema evolution. Use when designing database schemas, evaluating data models, or planning schema migrations.

Triggers: Designing a database schema for a new feature or project, evaluating an existing data model, choosing between normalized and denormalized designs, modeling complex relationships, planning schema evolution. Tools: None References: modeling-patterns.md

Key capabilities:

• Requirements gathering: entities, cardinality, access patterns, data volume, consistency requirements
• Conceptual modeling with Mermaid ER diagrams and standard cardinality notation
• Normalization to 3NF: atomic values (1NF), full key dependency (2NF), no transitive dependencies (3NF)
• Denormalization trade-offs: summary tables, embedded lookups, materialized views – only when measured performance problems exist
• Relationship patterns: junction tables, polymorphic associations, single/class-table inheritance, adjacency lists, nested sets, materialized paths, JSONB columns
• Schema evolution: expand/contract pattern, nullable additions, additive-only changes, independent API/schema versioning
• Polyglot persistence decisions: PostgreSQL as default, with guidance for Elasticsearch, Redis, TimescaleDB, Neo4j, MongoDB, Kafka by data type

nosql-patterns

NoSQL database patterns for document, key-value, graph, and wide-column stores. Access-pattern-driven design and consistency models. Use when choosing or designing NoSQL data models.

Triggers: Choosing between NoSQL database types, designing document/key-value/graph/wide-column data models, optimizing access patterns, understanding consistency models, migrating between relational and NoSQL. Tools: None References: None

Key capabilities:

• Store type selection: document (MongoDB), key-value (Redis, DynamoDB), wide-column (Cassandra), graph (Neo4j) – matched to access patterns
• Access-pattern-driven design: list operations first, design data to serve queries directly, accept duplication
• Document store patterns: embedding vs referencing decision criteria, bucket pattern for time-series
• Key-value patterns: colon-separated hierarchical key naming, TTL caching, rate limiting with INCR+EXPIRE, sorted sets, streams
• DynamoDB single-table design: composite PK/SK keys, multiple entity types per table, GSIs for alternate access patterns
• Consistency models: strong, eventual, causal, read-your-writes – with practical guidance on when to use each
• CAP theorem: AP vs CP trade-offs, default to eventual consistency unless stale reads cause financial or safety harm

database-migration

Schema migration workflows including zero-downtime migrations, data backfills, and rollback strategies. Use when planning database migrations, reviewing migration scripts, or troubleshooting migration failures.

Triggers: Writing or reviewing schema migrations, planning zero-downtime migrations for production, backfilling data after schema changes, setting up migration tooling, rolling back failed migrations, avoiding locking and data loss. Tools: Bash Read Write References: None

Key capabilities:

• Migration file structure: up/down scripts, sequential versioning, one logical change per migration, immutable once applied
• Zero-downtime expand/contract pattern: add new structure, backfill and update code, remove old structure
• Safe operations by database: PostgreSQL and MySQL compatibility matrix for ALTER TABLE operations
• PostgreSQL-specific: CREATE INDEX CONCURRENTLY, NOT NULL with NOT VALID + VALIDATE CONSTRAINT
• Data backfills: batch processing (1,000-10,000 rows), throttling with sleep between batches, replication lag monitoring
• Rollback strategies: down migrations, forward-fix, point-in-time recovery (PITR) as last resort
• Pre-production checklist: backup confirmation, staging test with production-like data, execution time measurement, rollback command ready
• Version tracking with schema_migrations table; tool support for Flyway, Alembic, Knex, Diesel, Ecto, and others
• Common pitfalls: large table locking, missing FK indexes, DDL inside long transactions, NULL handling during backfill, irreversible migrations without backup

3.12 - Framework & SEO Skills

Skills for specific frameworks and search engine optimization.

reflex-python

Reflex Python web framework for building full-stack apps in pure Python. Components, state management, and deployment. Use when building Reflex apps, designing component hierarchies, or managing app state.

Triggers: When building web apps with Reflex, designing components, managing state, routing, or creating full-stack Python web applications. Tools: Bash(reflex:*) Bash(python:*) Read Write References: component-reference.md

Key capabilities:

• App structure: initialization, entry points, page decorators, file-based routing, configuration
• Component system: layout (box, flex, grid), display (text, heading, image), input (input, select, checkbox), feedback (alert, toast, spinner)
• State management with rx.State classes, typed vars, event handlers, computed vars, and substates
• Event handling: on_click, on_change, two-way binding, background tasks, event chaining
• Styling with Radix UI design tokens, responsive props, light/dark themes
• Routing with dynamic segments, programmatic navigation, on_load events, and 404 handling
• Database integration via built-in SQLModel with automatic migrations
• Deployment to Reflex Cloud or self-hosted via Docker

??? example “Example usage” Build a todo app: Defines a TodoState with a list of todos and input field, creates event handlers for add/delete/toggle, builds UI with rx.input, rx.button, and rx.foreach(TodoState.todos, render_todo) to render the list dynamically.

fastapi-patterns

FastAPI patterns including dependency injection, Pydantic models, async endpoints, middleware, and testing. Use when building FastAPI applications, designing API endpoints, or reviewing FastAPI code.

Triggers: When building APIs with FastAPI, designing endpoints, implementing dependency injection, authentication, or testing FastAPI applications. Tools: Bash(python:*) Bash(uvicorn:*) Read Write References: endpoint-patterns.md

Key capabilities:

• Route definitions with HTTP method decorators, path/query parameters, and APIRouter modules
• Pydantic models for request/response: separate Create/Update/Response schemas, validation with Field()
• Dependency injection with Depends(), chained dependencies, Annotated for reusable deps, yield-based cleanup
• Async endpoint patterns: when to use async def vs def, pairing with async libraries
• Middleware: CORS, custom timing, trusted hosts, GZip compression
• Authentication: OAuth2 password flow, JWT decoding, API key headers, scopes
• Background tasks, WebSocket support, and structured error handling
• Testing with TestClient, dependency overrides, async tests, and WebSocket testing

??? example “Example usage” REST API for a blog: Creates Pydantic schemas for PostCreate, PostResponse, CommentCreate, defines APIRouter modules for /posts and /posts/{id}/comments, implements CRUD handlers with SQLAlchemy dependency injection, and adds pagination to list endpoints.

pandas-polars

DataFrame operations with pandas and polars including groupby, joins, reshaping, and performance optimization. Use when manipulating tabular data, choosing between pandas and polars, or optimizing DataFrame code.

Triggers: When working with tabular data, performing DataFrame operations, data transformations, cleaning data, aggregating by group, or choosing between pandas and polars. Tools: Bash(python:*) Read Write References: api-comparison.md

Key capabilities:

• Choosing between pandas (mature ecosystem, exploratory work, <1GB) and polars (faster, lower memory, lazy evaluation, 1GB+)
• DataFrame I/O: Parquet over CSV, dtype enforcement, chunked reading, column selection
• Selection and filtering with expressions (polars) and .loc[]/.iloc[] (pandas)
• GroupBy and aggregation with named columns, window functions (over() in polars)
• Joins and merges with explicit join types, duplicate checking, anti-joins
• Reshaping with pivot and melt/unpivot for wide and long formats
• Missing data handling: null counts, fill strategies, interpolation
• String and datetime operations across both libraries
• Performance optimization: lazy evaluation, avoiding apply(), categorical dtypes

??? example “Example usage” Process a large CSV with group statistics: Uses polars lazy mode to scan the CSV, applies filters before collection, groups by the requested column with multiple aggregations in one .agg() call, sorts results, and writes output to Parquet for downstream use.

flutter-development

Flutter/Dart development including widget architecture, state management, navigation, and cross-platform patterns. Use when building Flutter apps, choosing state management, or designing responsive mobile layouts.

Triggers: When building mobile or cross-platform apps with Flutter, designing widgets, managing state, adding navigation, or creating responsive layouts. Tools: Bash(flutter:*) Bash(dart:*) Read Write References: widget-catalog.md

Key capabilities:

• Widget architecture: StatelessWidget vs StatefulWidget, composition over inheritance, const constructors
• Layout system: Row, Column, Expanded, Flexible, Stack, ListView.builder, responsive design with LayoutBuilder
• State management options: setState (local), Provider (lightweight DI), Riverpod (type-safe), BLoC (event-driven)
• Navigation with GoRouter: declarative routes, nested navigation with ShellRoute, redirect guards, deep linking
• Theming with Material 3, ColorScheme.fromSeed, dark mode support, custom TextTheme
• Networking with http/dio, json_serializable, FutureBuilder/StreamBuilder, repository pattern
• Platform channels for native code integration (MethodChannel, EventChannel)
• Testing: unit, widget (testWidgets, pumpWidget), integration, and golden tests
• Performance: const widgets, ListView.builder, RepaintBoundary, DevTools profiling

??? example “Example usage” Product list with search and pull-to-refresh: Creates a StatefulWidget with a search TextField, uses ListView.builder for efficient rendering, implements RefreshIndicator for pull-to-refresh, fetches products from a repository, and shows loading/error/empty states.

seo-optimization

SEO optimization including on-page SEO, technical SEO, Core Web Vitals, structured data, and mobile-first indexing. Use when optimizing websites for search engines, implementing structured data, or improving page performance.

Triggers: When optimizing a website for search engines, working with meta tags, structured data, page speed, Core Web Vitals, or mobile-first indexing. Tools: Bash(curl:*) Bash(lighthouse:*) Read Write References: technical-seo-checklist.md

Key capabilities:

• On-page SEO: title tags, meta descriptions, heading hierarchy, alt text, internal links, URL structure
• Technical SEO: robots.txt, XML sitemaps, canonical URLs, hreflang, redirect chains, index control
• Structured data with JSON-LD: Article, Product, FAQ, BreadcrumbList, Organization schemas
• Core Web Vitals optimization: LCP (<2.5s), INP (<200ms), CLS (<0.1) with specific fix strategies
• Page speed: render-blocking resources, image compression (WebP/AVIF), CDN, minification, Brotli/gzip
• Mobile-first indexing: responsive design, viewport meta, touch targets, content parity
• Internal linking strategy: content hubs, descriptive anchor text, orphan page detection
• Security and trust signals: HTTPS, HSTS, E-E-A-T authorship

??? example “Example usage” SEO audit of a Next.js site: Checks meta tags on key pages, verifies sitemap.xml and robots.txt, validates structured data with Rich Results Test, runs Lighthouse for Core Web Vitals, checks canonical URLs, and produces a prioritized list of fixes sorted by expected impact.

3.13 - Performance Skills

Skills for performance analysis, optimization, and load testing.

performance-profiling

Performance analysis methodology and profiling techniques for CPU, memory, and I/O. Flame graphs, benchmarking, and regression detection. Use when optimizing performance, profiling bottlenecks, or reviewing performance-critical code.

Triggers: When identifying bottlenecks, profiling CPU/memory/I/O, interpreting flame graphs, setting up benchmarks, or optimizing slow code paths. Tools: Bash Read Write References: profiling-tools.md

Key capabilities:

• Follow the full performance analysis cycle: Identify, Measure, Profile, Optimize, Verify
• CPU profiling with sampling profilers and flame graph generation
• Memory profiling to detect leaks, allocation pressure, and unbounded growth
• I/O profiling for disk, network, and database bottlenecks (N+1 queries, connection pooling, slow queries)
• Benchmarking with statistical significance and regression detection
• Flame graph interpretation: reading X-axis (alphabetical, not time), Y-axis (stack depth), and differential flame graphs
• Common optimization patterns: algorithmic improvements, batching, caching, pooling, lazy evaluation, data layout

??? example “Example usage” Slow API endpoint: Measures end-to-end latency, profiles the handler, discovers 80% of time spent in 47 sequential database queries (N+1 problem). Rewrites as a single JOIN query, reducing response time from 3 seconds to 120ms.

caching-strategies

Caching patterns including cache-aside, write-through, TTL strategies, cache invalidation, and HTTP caching. Use when designing caching layers, optimizing response times, or debugging cache-related issues.

Triggers: When adding caching to reduce latency, choosing caching patterns, configuring HTTP caching headers, debugging stale data or cache stampede issues, or designing invalidation strategies. Tools: None References: None

Key capabilities:

• Choose the right caching pattern: cache-aside, read-through, write-through, write-behind
• Design TTL strategies with jitter to prevent thundering herd on expiration
• Cache invalidation via event-driven, tag-based, or versioned key approaches
• HTTP caching configuration: Cache-Control, ETag, CDN caching with s-maxage and Surrogate-Key
• Prevent cache stampede with locking (mutex), probabilistic early expiration (XFetch), and stale-while-revalidate
• Cache warming strategies for deploys and predictable access patterns

??? example “Example usage” Product page too slow: Profiles the endpoint and finds 3 database queries per request. Implements cache-aside with Redis: product data (TTL 10min), category tree (TTL 1hr), user-specific pricing (TTL 60s, private). Adds stale-while-revalidate to HTTP headers. Response time drops to 45ms on cache hit.

concurrency-patterns

Concurrency and parallelism patterns including async/await, threads, actors, channels, and deadlock prevention. Use when designing concurrent systems, debugging race conditions, or choosing between concurrency models.

Triggers: When choosing between threads, async/await, or actors; designing concurrent pipelines; debugging deadlocks or race conditions; implementing producer-consumer or fan-out/fan-in patterns. Tools: None References: patterns-catalog.md

Key capabilities:

• Distinguish concurrency from parallelism and choose based on I/O-bound vs CPU-bound bottlenecks
• Choose the right model: async/await, OS threads, green threads, actors, channels, or thread pools
• Manage shared state safely with Mutex, RwLock, and atomic operations
• Prevent deadlocks via lock ordering, try-lock with timeout, reduced lock scope, and lock-free algorithms
• Detect and fix race conditions using ThreadSanitizer, cargo miri, and pattern recognition (TOCTOU, partial init)
• Implement backpressure with bounded channels, rate limiting, load shedding, and reactive streams

??? example “Example usage” Go service deadlocks under load: Enables mutex profiling with GODEBUG=mutexprofile, identifies two goroutines acquiring locks on userCache and sessionCache in opposite orders. Fixes by establishing consistent lock ordering and reducing the critical section.

load-testing

Load testing methodology including test types, scenario design, and capacity planning. Use when planning load tests, analyzing test results, or setting up performance testing in CI.

Triggers: When planning or running load tests, choosing tools, designing test scenarios, analyzing results, estimating capacity, or setting up performance testing in CI pipelines. Tools: Bash Read Write References: None

Key capabilities:

• Choose the right test type: smoke, load, stress, spike, and soak/endurance tests
• Design realistic scenarios with user journeys, think time, traffic distribution, and authentication
• Capture essential metrics: latency percentiles (p50/p95/p99), throughput (RPS), error rate, and resource utilization
• Tool selection guidance: k6, Locust, Gatling, wrk, hey, vegeta
• Identify bottlenecks from results: linear latency climb, periodic spikes, error thresholds, throughput plateaus
• Capacity planning: find throughput ceiling, calculate headroom, estimate scaling needs
• CI integration with performance gates and relative thresholds

??? example “Example usage” Pre-Black Friday load test: Designs a test plan with smoke test first, then load test at 2x normal traffic, then stress test at 5x to find the breaking point. Uses k6 with scenarios modeling the top 5 user journeys weighted by actual traffic distribution. Configures thresholds at p95 < 500ms and error rate < 0.1%.