@jgamaraalv/ts-dev-kit 4.0.0 → 5.0.0

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "ts-dev-kit",
       "source": "./",
       "description": "15 specialized agents and 22 skills for TypeScript fullstack development",
-      "version": "4.0.0",
+      "version": "5.0.0",
       "author": {
         "name": "jgamaraalv"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-dev-kit",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "description": "15 specialized agents and 22 skills for TypeScript fullstack development with Fastify, Next.js, PostgreSQL, Redis, and more.",
   "author": {
     "name": "jgamaraalv",

package/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.0.0] - 2026-02-28
+
+### Changed
+
+- Standardize all 15 reference and workflow skills to use semantic XML tags (`<rules>`, `<quick_reference>`, `<examples>`, `<anti_patterns>`, `<gotchas>`, `<constraints>`, `<references>`, `<workflow>`, `<output>`) — previously only 7 workflow skills used XML tags while 15 reference skills used plain markdown headings
+- Skills with multi-step workflows (`owasp-security-review`, `ui-ux-guidelines`) now use `<workflow>` with numbered `<phase_N_name>` tags matching the pattern established by `debug`, `execute-task`, and `generate-prd`
+
+### BREAKING CHANGE
+
+- All skill SKILL.md files now wrap content sections in XML tags. Custom forks or overrides that parse skill files by markdown heading structure may need updating to account for the new XML tag wrappers.
+
 ## [4.0.0] - 2026-02-27
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgamaraalv/ts-dev-kit",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "description": "Claude Code plugin: 15 agents + 22 skills for TypeScript fullstack development",
   "author": "jgamaraalv",
   "license": "MIT",

package/skills/bullmq/SKILL.md

@@ -23,6 +23,8 @@ Redis-backed queue system for Node.js. Four core classes: `Queue`, `Worker`, `Qu
 
 `yarn add bullmq` — requires Redis 5.0+ with `maxmemory-policy=noeviction`.
 
+<quick_reference>
+
 ## Quick Start
 
 ```ts
@@ -73,6 +75,22 @@ queueEvents.on("failed", ({ jobId, failedReason }) => {
 });
 ```
 
+## Job Lifecycle States
+
+```
+add() → wait / prioritized / delayed
+         ↓
+       active → completed
+         ↓
+       failed → (retry) → wait/delayed
+```
+
+With FlowProducer: jobs can also be in `waiting-children` state until all children complete.
+
+</quick_reference>
+
+<rules>
+
 ## Connections
 
 BullMQ uses ioredis internally. Pass `connection` options or an existing ioredis instance.
@@ -103,6 +121,10 @@ const w1 = new Worker("q1", async (job) => {}, { connection: workerConn });
 - `QueueEvents` cannot share connections (uses blocking Redis commands).
 - Redis MUST have `maxmemory-policy=noeviction`.
 
+</rules>
+
+<examples>
+
 ## Queue
 
 ```ts
@@ -179,6 +201,10 @@ const worker = new Worker<JobData, JobReturn>("paint", async (job) => {
 });
 ```
 
+</examples>
+
+<events>
+
 ## Events
 
 **Worker events** (local to that worker instance):
@@ -205,17 +231,9 @@ const worker = new Worker<JobData, JobReturn>("paint", async (job) => {
 
 Event stream is auto-trimmed (~10,000 events). Configure via `streams.events.maxLen`.
 
-## Job Lifecycle States
+</events>
 
-```
-add() → wait / prioritized / delayed
-         ↓
-       active → completed
-         ↓
-       failed → (retry) → wait/delayed
-```
-
-With FlowProducer: jobs can also be in `waiting-children` state until all children complete.
+<references>
 
 ## Advanced Topics
 
@@ -223,3 +241,5 @@ With FlowProducer: jobs can also be in `waiting-children` state until all childr
 - **Flows and schedulers** (FlowProducer, parent-child, job schedulers, cron): See [references/flows-and-schedulers.md](references/flows-and-schedulers.md)
 - **Patterns** (step jobs, idempotent, throttle, manual rate-limit): See [references/patterns.md](references/patterns.md)
 - **Production** (shutdown, Redis config, retries, backoff, monitoring): See [references/production.md](references/production.md)
+
+</references>

package/skills/codebase-adapter/SKILL.md

@@ -6,9 +6,9 @@ argument-hint: "[optional: path to project root — defaults to current director
 allowed-tools: Bash(ls *), Bash(cat *), Bash(node *), Bash(python3 *)
 ---
 
-<system>
+<role>
 You are a plugin configuration specialist. You adapt specific, well-defined sections in ts-dev-kit's skill and agent files to match the host project — making them accurate and immediately useful without touching any workflow, phase logic, or behavioral patterns.
-</system>
+</role>
 
 <context>
 **User-provided path:** $ARGUMENTS

package/skills/composition-patterns/SKILL.md

@@ -10,6 +10,8 @@ boolean prop proliferation by using compound components, lifting state, and
 composing internals. These patterns make codebases easier for both humans and AI
 agents to work with as they scale.
 
+<constraints>
+
 ## When NOT to Use
 
 Skip these patterns when: fewer than 3 props, simple variants, or single-use components.
@@ -24,6 +26,10 @@ Reference these guidelines when:
 - Reviewing component architecture
 - Working with compound components or context providers
 
+</constraints>
+
+<rules>
+
 ## Rule Categories by Priority
 
 | Priority | Category                | Impact | Prefix          |
@@ -33,6 +39,10 @@ Reference these guidelines when:
 | 3        | Implementation Patterns | MEDIUM | `patterns-`     |
 | 4        | React 19 APIs           | MEDIUM | `react19-`      |
 
+</rules>
+
+<references>
+
 ## Quick Reference
 
 ### 1. Component Architecture (HIGH)
@@ -56,3 +66,5 @@ Reference these guidelines when:
 > **React 19+ only.** Skip this section if using React 18 or earlier.
 
 - **No forwardRef** — Don't use `forwardRef`; pass `ref` as a regular prop. Use `use()` instead of `useContext()` — see [references/react19-no-forwardref.md](references/react19-no-forwardref.md)
+
+</references>

package/skills/core-web-vitals/SKILL.md

@@ -9,6 +9,8 @@ allowed-tools: Bash(python3 *)
 The three stable Core Web Vitals, each measured at the **75th percentile** of
 real page loads (segmented by mobile and desktop):
 
+<quick_reference>
+
 | Metric | Measures | Good | Needs Improvement | Poor |
 |--------|----------|------|-------------------|------|
 | **LCP** — Largest Contentful Paint | Loading | ≤ 2.5 s | 2.5–4.0 s | > 4.0 s |
@@ -17,6 +19,36 @@ real page loads (segmented by mobile and desktop):
 
 A page **passes** Core Web Vitals only if all three metrics meet "Good" at the 75th percentile.
 
+## Supporting metrics (non-Core but diagnostic)
+
+- **FCP** (First Contentful Paint) — diagnoses render-blocking resources upstream of LCP
+- **TTFB** (Time to First Byte) — server response time; directly affects LCP
+- **TBT** (Total Blocking Time) — lab proxy for INP; identifies long tasks
+
+## Tools matrix
+
+| Tool | Type | LCP | INP | CLS | Notes |
+|------|------|-----|-----|-----|-------|
+| Chrome User Experience Report (CrUX) | Field | ✓ | ✓ | ✓ | 28-day rolling window of real users |
+| PageSpeed Insights | Field + Lab | ✓ | ✓ | ✓ | Field = CrUX data; Lab = Lighthouse |
+| Search Console CWV report | Field | ✓ | ✓ | ✓ | Groups URLs by template |
+| Chrome DevTools Performance panel | Field + Lab | ✓ | ✓ | ✓ | Local profiling, interaction tracing |
+| Lighthouse | Lab | ✓ | TBT* | ✓ | CI integration; INP → use TBT as proxy |
+
+*Lighthouse uses **Total Blocking Time (TBT)** as a lab proxy for INP. TBT
+correlates with INP but does not replace field measurement.
+
+## Metric lifecycle
+
+Metrics progress through: **Experimental → Pending → Stable**.
+All three current Core Web Vitals (LCP, CLS, INP) are **Stable**.
+INP replaced FID (First Input Delay) in March 2024.
+Changes to stable metrics follow an annual cadence with advance notice.
+
+</quick_reference>
+
+<examples>
+
 ## Quick setup: measure all three in the field
 
 ```bash
@@ -43,33 +75,9 @@ Each callback receives `{ name, value, rating, delta, id, navigationType }`.
 > The `web-vitals` library handles bfcache restores, prerendered pages, iframe
 > aggregation, and other edge cases that raw PerformanceObserver does not.
 
-## Tools matrix
-
-| Tool | Type | LCP | INP | CLS | Notes |
-|------|------|-----|-----|-----|-------|
-| Chrome User Experience Report (CrUX) | Field | ✓ | ✓ | ✓ | 28-day rolling window of real users |
-| PageSpeed Insights | Field + Lab | ✓ | ✓ | ✓ | Field = CrUX data; Lab = Lighthouse |
-| Search Console CWV report | Field | ✓ | ✓ | ✓ | Groups URLs by template |
-| Chrome DevTools Performance panel | Field + Lab | ✓ | ✓ | ✓ | Local profiling, interaction tracing |
-| Lighthouse | Lab | ✓ | TBT* | ✓ | CI integration; INP → use TBT as proxy |
-
-*Lighthouse uses **Total Blocking Time (TBT)** as a lab proxy for INP. TBT
-correlates with INP but does not replace field measurement.
-
-## Supporting metrics (non-Core but diagnostic)
-
-- **FCP** (First Contentful Paint) — diagnoses render-blocking resources upstream of LCP
-- **TTFB** (Time to First Byte) — server response time; directly affects LCP
-- **TBT** (Total Blocking Time) — lab proxy for INP; identifies long tasks
+</examples>
 
-## When to read reference files
-
-| Reference | Read when… |
-|-----------|-----------|
-| [references/lcp.md](references/lcp.md) | LCP > 2.5 s, diagnosing slow image/text load, preload/CDN questions |
-| [references/inp.md](references/inp.md) | INP > 200 ms, slow click/key/tap response, long task investigations |
-| [references/cls.md](references/cls.md) | CLS > 0.1, elements jumping on scroll or load, font/image shift |
-| [references/tools.md](references/tools.md) | Setting up monitoring, using DevTools/Lighthouse/PSI, top-9 optimization checklist |
+<visual_report>
 
 ## Generate a visual report
 
@@ -101,9 +109,17 @@ python3 SCRIPT_PATH/visualize.py \
 The script (`scripts/visualize.py`) requires only Python 3 stdlib — no packages to install.
 It outputs a self-contained HTML file with color-coded metric cards, a visual progress bar showing where each value falls on the Good/Needs Improvement/Poor scale, and an overall PASS/FAIL/NEEDS IMPROVEMENT verdict.
 
-## Metric lifecycle
+</visual_report>
 
-Metrics progress through: **Experimental → Pending → Stable**.
-All three current Core Web Vitals (LCP, CLS, INP) are **Stable**.
-INP replaced FID (First Input Delay) in March 2024.
-Changes to stable metrics follow an annual cadence with advance notice.
+<references>
+
+## When to read reference files
+
+| Reference | Read when… |
+|-----------|-----------|
+| [references/lcp.md](references/lcp.md) | LCP > 2.5 s, diagnosing slow image/text load, preload/CDN questions |
+| [references/inp.md](references/inp.md) | INP > 200 ms, slow click/key/tap response, long task investigations |
+| [references/cls.md](references/cls.md) | CLS > 0.1, elements jumping on scroll or load, font/image shift |
+| [references/tools.md](references/tools.md) | Setting up monitoring, using DevTools/Lighthouse/PSI, top-9 optimization checklist |
+
+</references>

package/skills/docker/SKILL.md

@@ -8,12 +8,7 @@ description: "Docker containerization reference — multi-stage builds, Compose
 
 Docker best practices for Node.js monorepos with Yarn 4 Berry.
 
-## When to Load References
-
-| Need                                               | Reference file                                                         |
-| -------------------------------------------------- | ---------------------------------------------------------------------- |
-| Writing or reviewing a Dockerfile for the monorepo | [references/monorepo-dockerfile.md](references/monorepo-dockerfile.md) |
-| Configuring docker-compose for dev or production   | [references/compose-configs.md](references/compose-configs.md)         |
+<rules>
 
 ## Key Principles
 
@@ -41,6 +36,10 @@ Docker best practices for Node.js monorepos with Yarn 4 Berry.
 - Read-only filesystem where possible: `read_only: true`
 - Drop capabilities: `cap_drop: [ALL]`
 
+</rules>
+
+<quick_reference>
+
 ## Useful Commands
 
 ```bash
@@ -53,3 +52,16 @@ docker system df                  # View cache usage
 docker system prune -a            # Prune unused images
 docker stats                      # Resource usage
 ```
+
+</quick_reference>
+
+<references>
+
+## When to Load References
+
+| Need                                               | Reference file                                                         |
+| -------------------------------------------------- | ---------------------------------------------------------------------- |
+| Writing or reviewing a Dockerfile for the monorepo | [references/monorepo-dockerfile.md](references/monorepo-dockerfile.md) |
+| Configuring docker-compose for dev or production   | [references/compose-configs.md](references/compose-configs.md)         |
+
+</references>

package/skills/drizzle-pg/SKILL.md

@@ -15,6 +15,8 @@ Packages: `drizzle-orm` (runtime), `drizzle-kit` (CLI/migrations).
 - [Common Patterns](#common-patterns)
 - [Reference Files](#reference-files)
 
+<examples>
+
 ## Quick Start
 
 ### Connect
@@ -151,15 +153,6 @@ npx drizzle-kit pull         # introspect DB -> Drizzle schema
 npx drizzle-kit studio       # visual browser UI
 ```
 
-## Import Cheat Sheet
-
-| Import path           | Key exports                                                                                                                                                                                                                                   |
-| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `drizzle-orm/pg-core` | `pgTable`, `pgEnum`, column types (`serial`, `text`, `integer`, `uuid`, `timestamp`, `jsonb`, `varchar`, `boolean`, `numeric`, `bigint`, `geometry`, `vector`, ...), `index`, `uniqueIndex`, `unique`, `check`, `primaryKey`, `foreignKey`    |
-| `drizzle-orm`         | Operators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `and`, `or`, `not`, `isNull`, `isNotNull`, `inArray`, `between`, `like`, `ilike`, `exists`, `sql`, `asc`, `desc`. Utilities: `getColumns`, `defineRelations`, `cosineDistance`, `l2Distance` |
-| `drizzle-orm` (types) | `InferSelectModel`, `InferInsertModel`                                                                                                                                                                                                        |
-| `drizzle-zod`         | `createInsertSchema`, `createSelectSchema`                                                                                                                                                                                                    |
-
 ## Common Patterns
 
 ### Conditional filters
@@ -190,6 +183,23 @@ type User = typeof users.$inferSelect;
 type NewUser = typeof users.$inferInsert;
 ```
 
+</examples>
+
+<quick_reference>
+
+## Import Cheat Sheet
+
+| Import path           | Key exports                                                                                                                                                                                                                                   |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `drizzle-orm/pg-core` | `pgTable`, `pgEnum`, column types (`serial`, `text`, `integer`, `uuid`, `timestamp`, `jsonb`, `varchar`, `boolean`, `numeric`, `bigint`, `geometry`, `vector`, ...), `index`, `uniqueIndex`, `unique`, `check`, `primaryKey`, `foreignKey`    |
+| `drizzle-orm`         | Operators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `and`, `or`, `not`, `isNull`, `isNotNull`, `inArray`, `between`, `like`, `ilike`, `exists`, `sql`, `asc`, `desc`. Utilities: `getColumns`, `defineRelations`, `cosineDistance`, `l2Distance` |
+| `drizzle-orm` (types) | `InferSelectModel`, `InferInsertModel`                                                                                                                                                                                                        |
+| `drizzle-zod`         | `createInsertSchema`, `createSelectSchema`                                                                                                                                                                                                    |
+
+</quick_reference>
+
+<references>
+
 ## Reference Files
 
 For detailed API coverage, see:
@@ -200,3 +210,5 @@ For detailed API coverage, see:
 - **sql`` template: raw, empty, join, identifier, placeholders**: [references/sql-operator.md](references/sql-operator.md)
 - **drizzle-kit commands, drizzle.config.ts, migration workflows**: [references/migrations.md](references/migrations.md)
 - **Dynamic queries, transactions, custom types, Zod, utilities**: [references/advanced.md](references/advanced.md)
+
+</references>

package/skills/fastify-best-practices/SKILL.md

@@ -10,12 +10,10 @@ description: "Fastify 5 best practices, API reference, and patterns for routes,
 - [Request lifecycle](#request-lifecycle-exact-order)
 - [Top anti-patterns](#top-anti-patterns)
 - [Quick patterns](#quick-patterns)
-  - [Plugin with fastify-plugin (FastifyPluginCallback)](#plugin-with-fastify-plugin-fastifyplugincallback)
-  - [Route with validation](#route-with-validation)
-  - [Hook (application-level)](#hook-application-level)
-  - [Error handler](#error-handler)
 - [Reference files](#reference-files)
 
+<quick_reference>
+
 ## Request lifecycle (exact order)
 
 ```
@@ -36,6 +34,10 @@ Incoming Request
 
 Error at any stage → `onError` hooks → error handler → `onSend` → response → `onResponse`.
 
+</quick_reference>
+
+<anti_patterns>
+
 ## Top anti-patterns
 
 1. **Mixing async/callback in handlers** — Use `async` OR callbacks, never both. With async, `return` the value; don't call `reply.send()` AND return.
@@ -58,6 +60,10 @@ Error at any stage → `onError` hooks → error handler → `onSend` → respon
 
 10. **Missing response schema** — Without `response` schema, Fastify serializes with `JSON.stringify()` (slow) and may leak sensitive fields. Use `fast-json-stringify` via response schemas.
 
+</anti_patterns>
+
+<examples>
+
 ## Quick patterns
 
 ### Plugin with fastify-plugin (FastifyPluginCallback)
@@ -130,6 +136,10 @@ fastify.setErrorHandler((error, request, reply) => {
 });
 ```
 
+</examples>
+
+<references>
+
 ## Reference files
 
 Load the relevant file when you need detailed API information:
@@ -141,3 +151,5 @@ Load the relevant file when you need detailed API information:
 - **Validation & serialization** — JSON Schema, Ajv, response schemas, custom validators: [references/validation-and-serialization.md](references/validation-and-serialization.md)
 - **Request, Reply & errors** — request/reply API, error handling, FST_ERR codes: [references/request-reply-errors.md](references/request-reply-errors.md)
 - **TypeScript & logging** — route generics, type providers, Pino config, decorators: [references/typescript-and-logging.md](references/typescript-and-logging.md)
+
+</references>

package/skills/generate-prd/SKILL.md

@@ -4,9 +4,9 @@ description: "Generates a complete, structured, and implementation-ready Product
 argument-hint: "[product-idea | feature-description | business-context | prd-md-file-path]"
 ---
 
-<system>
+<role>
 You are a Senior Product Manager and Product Strategist. Generate a complete, structured, and implementation-ready Product Requirements Document (PRD).
-</system>
+</role>
 
 <spec>
 $ARGUMENTS

package/skills/ioredis/SKILL.md

@@ -7,6 +7,8 @@ description: "ioredis v5 reference for Node.js Redis client — connection setup
 
 ioredis v5.x. Requires Node.js >= 12, Redis >= 2.6.12. 100% TypeScript.
 
+<quick_reference>
+
 ## Critical: Import Style
 
 ```ts
@@ -17,15 +19,6 @@ import { Redis } from "ioredis";
 import { Redis, Cluster } from "ioredis";
 ```
 
-## When to Load References
-
-| Need                                                                           | Reference file                                                       |
-| ------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
-| Connection setup, RedisOptions, TLS, retryStrategy, lifecycle                  | [references/connection-options.md](references/connection-options.md) |
-| Core API: pipelines, transactions, Pub/Sub, Lua scripting, scanning, events    | [references/core-api.md](references/core-api.md)                     |
-| Streams, auto-pipelining, transformers, binary data, error handling, debugging | [references/advanced-patterns.md](references/advanced-patterns.md)   |
-| Redis Cluster setup, ClusterOptions, Sentinel config, failover                 | [references/cluster-sentinel.md](references/cluster-sentinel.md)     |
-
 ## Quick Reference
 
 | Operation      | Code                                                                       |
@@ -40,6 +33,10 @@ import { Redis, Cluster } from "ioredis";
 | Graceful close | `await redis.quit()`                                                       |
 | Force close    | `redis.disconnect()`                                                       |
 
+</quick_reference>
+
+<gotchas>
+
 ## Common Gotchas
 
 1. **Named import**: Always `import { Redis } from "ioredis"` with NodeNext resolution
@@ -49,3 +46,18 @@ import { Redis, Cluster } from "ioredis";
 5. **`showFriendlyErrorStack`**: Performance cost — never enable in production
 6. **Cluster pipelines**: All keys in a pipeline must hash to slots served by the same node
 7. **`enableAutoPipelining`**: 35-50% throughput improvement, safe to enable globally
+
+</gotchas>
+
+<references>
+
+## When to Load References
+
+| Need                                                                           | Reference file                                                       |
+| ------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
+| Connection setup, RedisOptions, TLS, retryStrategy, lifecycle                  | [references/connection-options.md](references/connection-options.md) |
+| Core API: pipelines, transactions, Pub/Sub, Lua scripting, scanning, events    | [references/core-api.md](references/core-api.md)                     |
+| Streams, auto-pipelining, transformers, binary data, error handling, debugging | [references/advanced-patterns.md](references/advanced-patterns.md)   |
+| Redis Cluster setup, ClusterOptions, Sentinel config, failover                 | [references/cluster-sentinel.md](references/cluster-sentinel.md)     |
+
+</references>

package/skills/nextjs-best-practices/SKILL.md

@@ -9,27 +9,7 @@ Apply these rules when writing or reviewing Next.js code.
 
 > **Note:** Next.js 16 renamed `middleware.ts` to `proxy.ts`. Verify `proxy.ts` support in your version; `middleware.ts` remains the stable API.
 
-## Table of Contents
-
-- [File Conventions](#file-conventions)
-- [RSC Boundaries](#rsc-boundaries)
-- [Async Patterns](#async-patterns)
-- [Runtime Selection](#runtime-selection)
-- [Directives](#directives)
-- [Functions](#functions)
-- [Error Handling](#error-handling)
-- [Data Patterns](#data-patterns)
-- [Route Handlers](#route-handlers)
-- [Metadata & OG Images](#metadata--og-images)
-- [Image Optimization](#image-optimization)
-- [Font Optimization](#font-optimization)
-- [Bundling](#bundling)
-- [Scripts](#scripts)
-- [Hydration Errors](#hydration-errors)
-- [Suspense Boundaries](#suspense-boundaries)
-- [Parallel & Intercepting Routes](#parallel--intercepting-routes)
-- [Self-Hosting](#self-hosting)
-- [Debug Tricks](#debug-tricks)
+<references>
 
 ## File Conventions
 
@@ -192,3 +172,5 @@ See [debug-tricks.md](references/debug-tricks.md) for:
 
 - MCP endpoint for AI-assisted debugging
 - Rebuild specific routes with `--debug-build-paths`
+
+</references>

package/skills/owasp-security-review/SKILL.md

@@ -5,6 +5,8 @@ description: "Review code and architectures against the OWASP Top 10:2025 — th
 
 # OWASP Top 10:2025 Security Review
 
+<quick_reference>
+
 ## Quick reference
 
 | #   | Category                              | Key risk                                                               | Avg incidence |
@@ -20,9 +22,23 @@ description: "Review code and architectures against the OWASP Top 10:2025 — th
 | A09 | Security Logging & Alerting Failures  | Missing audit logs, no alerting, log injection, sensitive data in logs | 3.91%         |
 | A10 | Mishandling of Exceptional Conditions | Failing open, info leakage via errors, unchecked return values         | 2.95%         |
 
+## Severity classification
+
+Use these severity levels when reporting findings:
+
+- **Critical**: Directly exploitable, leads to full system compromise or mass data breach (e.g., SQLi with no parameterization, hardcoded admin credentials, missing auth on admin endpoints).
+- **High**: Exploitable with moderate effort, significant data exposure or privilege escalation (e.g., IDOR, weak password hashing, SSRF, deserialization of untrusted data).
+- **Medium**: Exploitable under specific conditions, limited impact (e.g., missing CSRF protection, verbose error messages, missing security headers).
+- **Low**: Defense-in-depth issue, minimal direct impact (e.g., missing rate limiting, incomplete logging, suboptimal crypto configuration).
+
+</quick_reference>
+
+<workflow>
+
 ## Workflows
 
-### 1. Code review for security
+<phase_1_code_review>
+### Code review for security
 
 Systematically check the code against each relevant category:
 
@@ -41,8 +57,10 @@ Priority order for review (highest impact first):
 - `[MEDIUM]` Error handling → A10 (Exceptional Conditions), A09 (Logging)
 - `[MEDIUM]` Architecture/design → A06 (Insecure Design)
 - `[MEDIUM]` Data integrity → A08 (Integrity Failures)
+</phase_1_code_review>
 
-### 2. Security audit checklist
+<phase_2_audit_checklist>
+### Security audit checklist
 
 Generate a checklist for a feature or codebase:
 
@@ -50,8 +68,10 @@ Generate a checklist for a feature or codebase:
 2. For each of the 10 categories, determine if it applies.
 3. For applicable categories, load the reference file and produce a checklist of items to verify.
 4. Output a markdown checklist grouped by category.
+</phase_2_audit_checklist>
 
-### 3. Remediation guidance
+<phase_3_remediation>
+### Remediation guidance
 
 When a vulnerability is identified:
 
@@ -59,6 +79,11 @@ When a vulnerability is identified:
 2. Load the corresponding reference file.
 3. Apply the prevention checklist to produce a specific, actionable fix.
 4. Provide a code example of the fix when possible.
+</phase_3_remediation>
+
+</workflow>
+
+<references>
 
 ## Reference files
 
@@ -75,15 +100,8 @@ Load the relevant file when you need detailed guidance for a specific category:
 - **A09 Logging & Alerting** — audit trails, log injection, alerting, sensitive data in logs: [references/a09-logging-alerting-failures.md](references/a09-logging-alerting-failures.md)
 - **A10 Exceptional Conditions** — error handling, fail-closed, resource cleanup, info leakage: [references/a10-exceptional-conditions.md](references/a10-exceptional-conditions.md)
 
-## Severity classification
-
-Use these severity levels when reporting findings:
-
-- **Critical**: Directly exploitable, leads to full system compromise or mass data breach (e.g., SQLi with no parameterization, hardcoded admin credentials, missing auth on admin endpoints).
-- **High**: Exploitable with moderate effort, significant data exposure or privilege escalation (e.g., IDOR, weak password hashing, SSRF, deserialization of untrusted data).
-- **Medium**: Exploitable under specific conditions, limited impact (e.g., missing CSRF protection, verbose error messages, missing security headers).
-- **Low**: Defense-in-depth issue, minimal direct impact (e.g., missing rate limiting, incomplete logging, suboptimal crypto configuration).
-
-## Output format
+</references>
 
+<output>
 When reporting security findings, use the template in [template.md](template.md) for each finding.
+</output>

package/skills/postgresql/SKILL.md

@@ -7,6 +7,8 @@ description: "PostgreSQL 16+ reference for writing queries, designing schemas, m
 
 Version: **16+**. All syntax is standard; most features apply to PostgreSQL 13+.
 
+<quick_reference>
+
 ## Quick patterns
 
 ```sql
@@ -24,6 +26,25 @@ WHERE relkind = 'r' ORDER BY pg_total_relation_size(oid) DESC;
 SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE pid = <pid>;
 ```
 
+</quick_reference>
+
+<rules>
+
+## Key non-obvious facts
+
+- Every statement runs in a transaction. Without `BEGIN`, each statement auto-commits.
+- `jsonb` stores parsed binary (faster queries); `json` stores raw text (exact input preserved). Prefer `jsonb`.
+- `LIKE 'foo%'` can use B-tree; `LIKE '%foo'` cannot — use `pg_trgm` GIN for suffix search.
+- `CREATE INDEX CONCURRENTLY` avoids table lock but cannot run inside a transaction block.
+- `EXPLAIN` without `ANALYZE` shows the planner's _estimate_. Always use `EXPLAIN (ANALYZE, BUFFERS)` for real data.
+- Null values are stored in indexes by B-tree (unlike some other databases). `IS NULL` can use an index.
+- `SERIAL`/`BIGSERIAL` are shorthand for sequence + default; prefer `GENERATED ALWAYS AS IDENTITY` (SQL standard).
+- Default isolation level is **Read Committed**. `SERIALIZABLE` prevents all anomalies but may abort transactions.
+
+</rules>
+
+<references>
+
 ## Reference files
 
 Load the relevant file when working on a specific topic:
@@ -38,13 +59,4 @@ Load the relevant file when working on a specific topic:
 | EXPLAIN output, VACUUM, stats          | [references/performance.md](references/performance.md)   | Query tuning or performance analysis   |
 | psql meta-commands                     | [references/psql-cli.md](references/psql-cli.md)         | Working interactively in psql          |
 
-## Key non-obvious facts
-
-- Every statement runs in a transaction. Without `BEGIN`, each statement auto-commits.
-- `jsonb` stores parsed binary (faster queries); `json` stores raw text (exact input preserved). Prefer `jsonb`.
-- `LIKE 'foo%'` can use B-tree; `LIKE '%foo'` cannot — use `pg_trgm` GIN for suffix search.
-- `CREATE INDEX CONCURRENTLY` avoids table lock but cannot run inside a transaction block.
-- `EXPLAIN` without `ANALYZE` shows the planner's _estimate_. Always use `EXPLAIN (ANALYZE, BUFFERS)` for real data.
-- Null values are stored in indexes by B-tree (unlike some other databases). `IS NULL` can use an index.
-- `SERIAL`/`BIGSERIAL` are shorthand for sequence + default; prefer `GENERATED ALWAYS AS IDENTITY` (SQL standard).
-- Default isolation level is **Read Committed**. `SERIALIZABLE` prevents all anomalies but may abort transactions.
+</references>

package/skills/react-best-practices/SKILL.md

@@ -7,18 +7,7 @@ description: "React and Next.js performance patterns. Use when writing, reviewin
 
 Performance optimization guide for React and Next.js applications, based on Vercel Engineering practices. 8 categories organized by impact.
 
-## Table of Contents
-
-- [When to Apply](#when-to-apply)
-- [Quick Reference](#quick-reference)
-  - [Async Patterns (CRITICAL)](#1-async-patterns-critical)
-  - [Bundle Optimization (CRITICAL)](#2-bundle-optimization-critical)
-  - [Server-Side Performance (HIGH)](#3-server-side-performance-high)
-  - [Client-Side Patterns (MEDIUM-HIGH)](#4-client-side-patterns-medium-high)
-  - [Re-render Optimization (MEDIUM)](#5-re-render-optimization-medium)
-  - [Rendering Performance (MEDIUM)](#6-rendering-performance-medium)
-  - [JavaScript Performance (LOW-MEDIUM)](#7-javascript-performance-low-medium)
-  - [Advanced Patterns (LOW)](#8-advanced-patterns-low)
+<constraints>
 
 ## When to Apply
 
@@ -27,6 +16,10 @@ Performance optimization guide for React and Next.js applications, based on Verc
 - Reviewing code for performance issues
 - Optimizing bundle size or load times
 
+</constraints>
+
+<references>
+
 ## Quick Reference
 
 ### 1. Async Patterns (CRITICAL)
@@ -108,3 +101,5 @@ Performance optimization guide for React and Next.js applications, based on Verc
 
 - Store event handlers in refs -- stable effect subscriptions
 - Initialize app once per load -- module-level guard
+
+</references>

package/skills/service-worker/SKILL.md

@@ -10,17 +10,12 @@ description: "Service Worker API implementation guide — registration, lifecycl
 - [Constraints](#constraints)
 - [Lifecycle](#lifecycle)
 - [Registration](#registration)
-- [Install Event — Pre-cache Assets](#install-event--pre-cache-assets)
-- [Activate Event — Clean Up Old Caches](#activate-event--clean-up-old-caches)
-- [Fetch Event — Intercept Requests](#fetch-event--intercept-requests)
-- [Navigation Preload](#navigation-preload)
-- [Updating a Service Worker](#updating-a-service-worker)
-- [Communicating with Pages](#communicating-with-pages)
+- [Install / Activate / Fetch Events](#install-event--pre-cache-assets)
 - [Common Pitfalls](#common-pitfalls)
-- [Push Notifications & Background Sync](#push-notifications--background-sync)
-- [API Quick Reference](#api-quick-reference)
 - [Next.js Integration](#nextjs-integration)
-- [DevTools](#devtools)
+- [Reference files](#reference-files)
+
+<constraints>
 
 ## Constraints
 
@@ -31,6 +26,10 @@ description: "Service Worker API implementation guide — registration, lifecycl
 - Scope defaults to the directory containing the SW file
 - `self` refers to `ServiceWorkerGlobalScope`
 
+</constraints>
+
+<quick_reference>
+
 ## Lifecycle
 
 ```
@@ -45,6 +44,27 @@ register() → Download → Install → [Wait] → Activate → Fetch control
 
 A document must reload to be controlled (or call `clients.claim()` during activate).
 
+## Updating a Service Worker
+
+- Browser byte-compares the SW file on each navigation (or every 24h)
+- New version installs in background while old version still serves
+- Increment the cache name (e.g., `v1` → `v2`) in the new version
+- Delete old caches in the `activate` handler
+- Call `self.skipWaiting()` in `install` to activate immediately
+- Call `self.clients.claim()` in `activate` to take control of open pages
+
+## DevTools
+
+- **Chrome**: `chrome://inspect/#service-workers` or Application > Service Workers
+- **Firefox**: `about:debugging#/runtime/this-firefox` or Application > Service Workers
+- **Edge**: `edge://inspect/#service-workers` or Application > Service Workers
+
+Unregister, update, and inspect caches from the Application panel. Use "Update on reload" checkbox during development.
+
+</quick_reference>
+
+<examples>
+
 ## Registration
 
 ```js
@@ -125,15 +145,6 @@ self.addEventListener("fetch", (event) => {
 });
 ```
 
-## Updating a Service Worker
-
-- Browser byte-compares the SW file on each navigation (or every 24h)
-- New version installs in background while old version still serves
-- Increment the cache name (e.g., `v1` → `v2`) in the new version
-- Delete old caches in the `activate` handler
-- Call `self.skipWaiting()` in `install` to activate immediately
-- Call `self.clients.claim()` in `activate` to take control of open pages
-
 ## Communicating with Pages
 
 ```js
@@ -150,22 +161,6 @@ self.addEventListener("message", (event) => {
 });
 ```
 
-## Common Pitfalls
-
-1. **Response cloning** — `response.clone()` before both caching and returning, since body streams can only be read once
-2. **Opaque responses** — cross-origin fetches without CORS return opaque responses (status 0). `cache.add()` will refuse them. Use `cache.put()` but you can't inspect the response
-3. **waitUntil timing** — call `event.waitUntil()` synchronously within the event handler, not inside an async callback
-4. **Scope ceiling** — a SW cannot control URLs above its own directory unless `Service-Worker-Allowed` header is set
-5. **No state persistence** — the SW may terminate at any time when idle. Don't store state in global variables — use Cache API or IndexedDB
-
-## Push Notifications & Background Sync
-
-For push subscription, handling push events, and background sync implementation, see [references/push-and-sync.md](references/push-and-sync.md).
-
-## API Quick Reference
-
-For detailed interfaces (`Cache`, `CacheStorage`, `FetchEvent`, `Clients`, `ServiceWorkerRegistration`, `ServiceWorkerGlobalScope`), see [references/api-reference.md](references/api-reference.md).
-
 ## Next.js Integration
 
 In Next.js, place the service worker file in `public/sw.js`. `public/sw.js` is intentionally plain JS (not processed by Next.js build pipeline). Register it from a client component:
@@ -186,10 +181,26 @@ export function ServiceWorkerRegistrar() {
 
 Add to root layout. Next.js serves `public/` files at the root, so `/sw.js` scope covers `/`.
 
-## DevTools
+</examples>
 
-- **Chrome**: `chrome://inspect/#service-workers` or Application > Service Workers
-- **Firefox**: `about:debugging#/runtime/this-firefox` or Application > Service Workers
-- **Edge**: `edge://inspect/#service-workers` or Application > Service Workers
+<gotchas>
 
-Unregister, update, and inspect caches from the Application panel. Use "Update on reload" checkbox during development.
+## Common Pitfalls
+
+1. **Response cloning** — `response.clone()` before both caching and returning, since body streams can only be read once
+2. **Opaque responses** — cross-origin fetches without CORS return opaque responses (status 0). `cache.add()` will refuse them. Use `cache.put()` but you can't inspect the response
+3. **waitUntil timing** — call `event.waitUntil()` synchronously within the event handler, not inside an async callback
+4. **Scope ceiling** — a SW cannot control URLs above its own directory unless `Service-Worker-Allowed` header is set
+5. **No state persistence** — the SW may terminate at any time when idle. Don't store state in global variables — use Cache API or IndexedDB
+
+</gotchas>
+
+<references>
+
+## Reference files
+
+- **Caching strategies** (cache-first, network-first, stale-while-revalidate): [references/caching-strategies.md](references/caching-strategies.md)
+- **Push notifications & background sync** (push subscription, push events, background sync): [references/push-and-sync.md](references/push-and-sync.md)
+- **API quick reference** (`Cache`, `CacheStorage`, `FetchEvent`, `Clients`, `ServiceWorkerRegistration`, `ServiceWorkerGlobalScope`): [references/api-reference.md](references/api-reference.md)
+
+</references>

package/skills/tanstack-query/SKILL.md

@@ -13,6 +13,8 @@ description: |
 
 # TanStack Query v5 (React)
 
+<quick_reference>
+
 ## Setup
 
 ```tsx
@@ -52,6 +54,10 @@ function App() {
 
 **Key recommendation:** Set `staleTime` above 0 to control refetch frequency rather than disabling individual refetch triggers.
 
+</quick_reference>
+
+<examples>
+
 ## queryOptions — co-locate key + fn
 
 Always use `queryOptions` to define query configurations. It enables type inference across `useQuery`, `prefetchQuery`, `getQueryData`, and `setQueryData`.
@@ -325,6 +331,10 @@ const { data } = useQuery({
 
 `skipToken` prevents `refetch()` from working — use `enabled: false` if you need manual refetch.
 
+</examples>
+
+<gotchas>
+
 ## setQueryData — immutability
 
 ```tsx
@@ -340,9 +350,15 @@ queryClient.setQueryData(['todo', id], (old) =>
 )
 ```
 
+</gotchas>
+
+<references>
+
 ## Further Reference
 
 - **Full API signatures** (useQuery, useMutation, useInfiniteQuery, QueryClient): See [references/api-reference.md](references/api-reference.md)
 - **SSR & Next.js** (hydration, App Router, streaming): See [references/ssr-nextjs.md](references/ssr-nextjs.md)
 - **Testing** (renderHook, mocking, setup): See [references/testing.md](references/testing.md)
 - **Advanced patterns** (TypeScript, Suspense, waterfalls, network modes): See [references/advanced-patterns.md](references/advanced-patterns.md)
+
+</references>

package/skills/typescript-conventions/SKILL.md

@@ -7,6 +7,8 @@ description: "TypeScript coding conventions for strict, type-safe projects. Use
 
 Project-wide TypeScript standards that complement agent-specific instructions.
 
+<rules>
+
 ## Type Safety
 
 - **No `any`**: Use `unknown` if the type is truly dynamic, then narrow.
@@ -43,9 +45,15 @@ import { Redis } from "ioredis";
 - **Query** (returns data): `get`, `find`, `list`, `fetch`
 - **Command** (changes state): `create`, `update`, `delete`, `add`, `remove`
 
+</rules>
+
+<anti_patterns>
+
 ## Anti-Patterns
 
 - **Primitive obsession**: Use branded types or Zod enums, not raw strings for IDs and statuses.
 - **Magic numbers/strings**: Use constants from a shared package (e.g., `RATE_LIMITS`, `PAGINATION`, `CACHE`).
 - **Long parameter lists**: Use an options object or a Zod schema.
 - **Premature abstraction**: Three similar lines > one premature helper. Abstract on the third repetition.
+
+</anti_patterns>

package/skills/ui-ux-guidelines/SKILL.md

@@ -7,15 +7,7 @@ description: "Review UI code for Web Interface Guidelines compliance. Use when a
 
 Dispatch hub for UI/UX rules. Load the relevant reference file for full details.
 
-## Contents
-
-1. [Rule Categories](#rule-categories-by-priority)
-2. [Workflows](#workflows)
-3. [Anti-patterns](#anti-patterns-flag-these)
-4. [Output Format](#code-review-output-format)
-5. [Reference Files](#reference-files)
-
----
+<rules>
 
 ## Rule Categories by Priority
 
@@ -31,31 +23,41 @@ Dispatch hub for UI/UX rules. Load the relevant reference file for full details.
 | 8        | Content & Navigation | MEDIUM   | `forms-content-checklist`       |
 | 9        | Charts & Data        | LOW      | `layout-typography-animation`   |
 
----
+</rules>
+
+<workflow>
 
 ## Workflows
 
-### 1. Review UI code
+<phase_1_review_ui>
+### Review UI code
 
 1. Read the target file(s).
 2. Load the relevant reference file(s) from `references/` based on what the code contains.
 3. Check each applicable rule. Report violations in the output format below.
+</phase_1_review_ui>
 
-### 2. Build new component
+<phase_2_build_component>
+### Build new component
 
 1. Load `references/accessibility-and-interaction.md` -- all components must meet CRITICAL rules.
 2. Load additional references based on component type:
    - Form component -> `references/forms-content-checklist.md`
    - Layout/visual component -> `references/layout-typography-animation.md`
 3. Follow rules during implementation.
+</phase_2_build_component>
 
-### 3. Pre-delivery checklist
+<phase_3_pre_delivery>
+### Pre-delivery checklist
 
 1. Load `references/forms-content-checklist.md` for the full checklist.
 2. Load `references/accessibility-and-interaction.md` for the interaction checklist.
 3. Walk through every checkbox before shipping.
+</phase_3_pre_delivery>
 
----
+</workflow>
+
+<anti_patterns>
 
 ## Anti-patterns (flag these)
 
@@ -70,7 +72,9 @@ Dispatch hub for UI/UX rules. Load the relevant reference file for full details.
 - Hardcoded date/number formats -- use `Intl.*`
 - Icon-only buttons without `aria-label`
 
----
+</anti_patterns>
+
+<output>
 
 ## Code Review Output Format
 
@@ -78,7 +82,9 @@ Group findings by file. Use `file:line` format (VS Code clickable). Be terse --
 
 See [template.md](template.md) for the expected output format.
 
----
+</output>
+
+<references>
 
 ## Reference Files
 
@@ -87,3 +93,5 @@ Load these as needed during reviews and implementation:
 - **[Accessibility & Interaction](references/accessibility-and-interaction.md)** -- Focus, ARIA, keyboard, touch targets, cursors, drag UX
 - **[Layout, Typography & Animation](references/layout-typography-animation.md)** -- Performance, responsive, fonts, color, motion, charts
 - **[Forms, Content & Checklist](references/forms-content-checklist.md)** -- Forms, content handling, navigation, dark mode, locale, hydration, pre-delivery checklist
+
+</references>

package/skills/yolo/SKILL.md

@@ -31,11 +31,11 @@ allowed-tools: Bash(docker *), Bash(ls *), Bash(cat *), Bash(cp *), Bash(mkdir *
 - "Set up autonomous mode"
 </trigger_examples>
 
-<system>
+<role>
 You are a devcontainer setup specialist. Your goal is to get the user into a secure, sandboxed devcontainer running `claude --dangerously-skip-permissions` as quickly as possible. You follow a strict decision tree and never skip safety checks.
 
 **IMPORTANT SECURITY NOTE:** While the devcontainer provides substantial protections (network firewall, isolation), it is NOT immune to all attacks. Only use devcontainers with **trusted repositories**. The `--dangerously-skip-permissions` flag gives Claude full access to everything inside the container, including credentials mounted into it. Always inform the user of this trade-off.
-</system>
+</role>
 
 <task>
 $ARGUMENTS