Initial plan

- P0: Catalog includes nested skills (listSkillIdsRecursive), 626 skills
- P0: update_readme.py regex fixes 'high-performance agentic skills'
- P1: SKILL_ANATOMY risk values aligned to none|safe|critical|offensive (EN + vi)
- P1: requirements.txt + CONTRIBUTING Python setup
- P1: data/package.json version 4.6.0
- P2: npm run test + CI test step; validator docs + validation-baseline in .gitignore
- P3: Installer --version/--tag support; CI npm audit; __pycache__ in .gitignore

.github/ISSUE_49_COMMENT.md

@@ -0,0 +1,15 @@
+Suggested comment for [Issue #49](https://github.com/sickn33/antigravity-awesome-skills/issues/49). Paste this on the issue:
+
+---
+
+The 404 happens because the package wasn’t published to npm yet. We’ve addressed it in two ways:
+
+1. **Publish to npm** – We’re set up to publish so `npx antigravity-awesome-skills` will work after the first release. You can also trigger a manual publish via the “Publish to npm” workflow (Actions tab) if you have `NPM_TOKEN` configured.
+
+2. **Fallback** – Until then (or if you hit a 404 for any reason), use:
+   ```bash
+   npx github:sickn33/antigravity-awesome-skills
+   ```
+   The README, GETTING_STARTED, and FAQ now mention this fallback.
+
+Thanks for reporting.

.github/MAINTENANCE.md

@@ -41,7 +41,7 @@ it means you **did not run or commit** the Validation Chain correctly.
 
 ### 3. 📝 EVIDENCE OF WORK
 
-- You must create/update `walkthrough.md` or `RELEASE_NOTES.md` to document what changed.
+- You must create/update `walkthrough.md` or `CHANGELOG.md` to document what changed.
 - If you made something new, **link it** in the artifacts.
 
 ### 4. 🚫 NO BRANCHES
@@ -172,20 +172,30 @@ Reject any PR that fails this:
 When cutting a new version (e.g., V4):
 
 1.  **Run Full Validation**: `python3 scripts/validate_skills.py --strict`
-2.  **Update Changelog**: Create `RELEASE_NOTES.md`.
-3.  **Bump Version**: Update header in `README.md`.
+2.  **Update Changelog**: Add the new release section to `CHANGELOG.md`.
+3.  **Bump Version**:
+    - Update `package.json` → `"version": "X.Y.Z"` (source of truth for npm).
+    - Update version header in `README.md` if it displays the number.
+    - One-liner: `npm version patch` (or `minor`/`major`) — bumps `package.json` and creates a git tag; then amend if you need to tag after release.
 4.  **Tag Release**:
     ```bash
     git tag -a v4.0.0 -m "V4 Enterprise Edition"
     git push origin v4.0.0
     ```
+5.  **Publish to npm** (so `npx antigravity-awesome-skills` works):
+    - **Option A (manual):** From repo root, with npm logged in and 2FA/token set up:
+      ```bash
+      npm publish
+      ```
+      You cannot republish the same version; always bump `package.json` before publishing.
+    - **Option B (CI):** On GitHub, create a **Release** (tag e.g. `v4.6.1`). The workflow [Publish to npm](.github/workflows/publish-npm.yml) runs on **Release published** and runs `npm publish` if the repo secret `NPM_TOKEN` is set (npm → Access Tokens → Granular token with Publish, then add as repo secret `NPM_TOKEN`).
 
-### 📋 Release Note Template
+### 📋 Changelog Entry Template
 
-All changeslogs/release notes MUST follow this structure to ensure professionalism and quality:
+Each new release section in `CHANGELOG.md` should follow [Keep a Changelog](https://keepachangelog.com/) and this structure:
 
 ```markdown
-# Release vX.Y.Z: [Theme Name]
+## [X.Y.Z] - YYYY-MM-DD - "[Theme Name]"
 
 > **[One-line catchy summary of the release]**
 

.github/workflows/ci.yml

@@ -45,6 +45,13 @@ jobs:
       - name: Install npm dependencies
         run: npm ci
 
+      - name: Audit npm dependencies
+        run: npm audit --audit-level=high
+        continue-on-error: true
+
+      - name: Run tests
+        run: npm run test
+
       - name: 📦 Build catalog
         run: npm run catalog
 

.github/workflows/publish-npm.yml

@@ -0,0 +1,28 @@
+# Publish antigravity-awesome-skills to npm on release.
+# Requires NPM_TOKEN secret (npm → Access Tokens → Granular token with Publish).
+# Before creating a Release: bump package.json "version" (npm forbids republishing the same version).
+# Release tag (e.g. v4.6.1) should match package.json version.
+
+name: Publish to npm
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Publish
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -1,7 +1,31 @@
 node_modules/
+__pycache__/
+.worktrees/
 
 walkthrough.md
 .agent/rules/
 .gemini/
 LOCAL_CONFIG.md
 data/node_modules
+
+# Temporary analysis and report files
+*_REPORT.md
+*_ANALYSIS*.md
+*_COUNT.md
+*_SUMMARY.md
+*_analysis.json
+*_validation.json
+*_results.json
+voltagent_*.json
+similar_skills_*.json
+remaining_*.json
+html_*.json
+
+# Temporary analysis scripts
+scripts/*voltagent*.py
+scripts/*html*.py
+scripts/*similar*.py
+scripts/*count*.py
+
+# Optional baseline for legacy JS validator (scripts/validate-skills.js)
+validation-baseline.json

CATALOG.md

@@ -1,16 +1,17 @@
 # Skill Catalog
 
-Generated at: 2026-01-30T07:28:45.635Z
+Generated at: 2026-02-03T09:20:12.539Z
 
-Total skills: 553
+Total skills: 626
 
-## architecture (53)
+## architecture (60)
 
 | Skill | Description | Tags | Triggers |
 | --- | --- | --- | --- |
 | `architect-review` | Master software architect specializing in modern architecture patterns, clean architecture, microservices, event-driven systems, and DDD. Reviews system desi... |  | architect, review, software, specializing, architecture, clean, microservices, event, driven, ddd, reviews, designs |
 | `architecture` | Architectural decision-making framework. Requirements analysis, trade-off evaluation, ADR documentation. Use when making architecture decisions or analyzing ... | architecture | architecture, architectural, decision, making, framework, requirements, analysis, trade, off, evaluation, adr, documentation |
 | `architecture-decision-records` | Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation. Use when documenting significant techn... | architecture, decision, records | architecture, decision, records, write, maintain, adrs, following, technical, documentation, documenting, significant, decisions |
+| `automate-whatsapp` | Build WhatsApp automations with Kapso workflows: configure WhatsApp triggers, edit workflow graphs, manage executions, deploy functions, and use databases/in... | automate, whatsapp | automate, whatsapp, automations, kapso, configure, triggers, edit, graphs, executions, deploy, functions, databases |
 | `avalonia-viewmodels-zafiro` | Optimal ViewModel and Wizard creation patterns for Avalonia using Zafiro and ReactiveUI. | avalonia, viewmodels, zafiro | avalonia, viewmodels, zafiro, optimal, viewmodel, wizard, creation, reactiveui |
 | `bash-linux` | Bash/Linux terminal patterns. Critical commands, piping, error handling, scripting. Use when working on macOS or Linux systems. | bash, linux | bash, linux, terminal, critical, commands, piping, error, handling, scripting, working, macos |
 | `binary-analysis-patterns` | Master binary analysis patterns including disassembly, decompilation, control flow analysis, and code pattern recognition. Use when analyzing executables, un... | binary | binary, analysis, including, disassembly, decompilation, control, flow, code, recognition, analyzing, executables, understanding |
@@ -23,6 +24,7 @@ Total skills: 553
 | `code-refactoring-refactor-clean` | You are a code refactoring expert specializing in clean code principles, SOLID design patterns, and modern software engineering best practices. Analyze and r... | code, refactoring, refactor, clean | code, refactoring, refactor, clean, specializing, principles, solid, software, engineering, analyze, provided, improve |
 | `codebase-cleanup-refactor-clean` | You are a code refactoring expert specializing in clean code principles, SOLID design patterns, and modern software engineering best practices. Analyze and r... | codebase, cleanup, refactor, clean | codebase, cleanup, refactor, clean, code, refactoring, specializing, principles, solid, software, engineering, analyze |
 | `competitor-alternatives` | When the user wants to create competitor comparison or alternative pages for SEO and sales enablement. Also use when the user mentions 'alternative page,' 'v... | competitor, alternatives | competitor, alternatives, user, wants, comparison, alternative, pages, seo, sales, enablement, mentions, page |
+| `context-degradation` | Recognize patterns of context failure: lost-in-middle, poisoning, distraction, and clash | degradation | degradation, context, recognize, failure, lost, middle, poisoning, distraction, clash |
 | `core-components` | Core component library and design system patterns. Use when building UI, using design tokens, or working with the component library. | core, components | core, components, component, library, building, ui, tokens, working |
 | `cpp-pro` | Write idiomatic C++ code with modern features, RAII, smart pointers, and STL algorithms. Handles templates, move semantics, and performance optimization. Use... | cpp | cpp, pro, write, idiomatic, code, features, raii, smart, pointers, stl, algorithms, move |
 | `cqrs-implementation` | Implement Command Query Responsibility Segregation for scalable architectures. Use when separating read and write models, optimizing query performance, or bu... | cqrs | cqrs, command, query, responsibility, segregation, scalable, architectures, separating, read, write, models, optimizing |
@@ -34,6 +36,7 @@ Total skills: 553
 | `error-handling-patterns` | Master error handling patterns across languages including exceptions, Result types, error propagation, and graceful degradation to build resilient applicatio... | error, handling | error, handling, languages, including, exceptions, result, types, propagation, graceful, degradation, resilient, applications |
 | `event-sourcing-architect` | Expert in event sourcing, CQRS, and event-driven architecture patterns. Masters event store design, projection building, saga orchestration, and eventual con... | event, sourcing | event, sourcing, architect, cqrs, driven, architecture, masters, store, projection, building, saga, orchestration |
 | `event-store-design` | Design and implement event stores for event-sourced systems. Use when building event sourcing infrastructure, choosing event store technologies, or implement... | event, store | event, store, stores, sourced, building, sourcing, infrastructure, choosing, technologies, implementing, persistence |
+| `game-development/multiplayer` | Multiplayer game development principles. Architecture, networking, synchronization. | game, development/multiplayer | game, development/multiplayer, multiplayer, development, principles, architecture, networking, synchronization |
 | `godot-gdscript-patterns` | Master Godot 4 GDScript patterns including signals, scenes, state machines, and optimization. Use when building Godot games, implementing game systems, or le... | godot, gdscript | godot, gdscript, including, signals, scenes, state, machines, optimization, building, games, implementing, game |
 | `haskell-pro` | Expert Haskell engineer specializing in advanced type systems, pure functional design, and high-reliability software. Use PROACTIVELY for type-level programm... | haskell | haskell, pro, engineer, specializing, type, pure, functional, high, reliability, software, proactively, level |
 | `i18n-localization` | Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support. | i18n, localization | i18n, localization, internationalization, detecting, hardcoded, strings, managing, translations, locale, files, rtl |
@@ -41,6 +44,8 @@ Total skills: 553
 | `julia-pro` | Master Julia 1.10+ with modern features, performance optimization, multiple dispatch, and production-ready practices. Expert in the Julia ecosystem including... | julia | julia, pro, 10, features, performance, optimization, multiple, dispatch, ecosystem, including, package, scientific |
 | `minecraft-bukkit-pro` | Master Minecraft server plugin development with Bukkit, Spigot, and Paper APIs. Specializes in event-driven architecture, command systems, world manipulation... | minecraft, bukkit | minecraft, bukkit, pro, server, plugin, development, spigot, paper, apis, specializes, event, driven |
 | `monorepo-architect` | Expert in monorepo architecture, build systems, and dependency management at scale. Masters Nx, Turborepo, Bazel, and Lerna for efficient multi-project devel... | monorepo | monorepo, architect, architecture, dependency, scale, masters, nx, turborepo, bazel, lerna, efficient, multi |
+| `multi-agent-patterns` | Master orchestrator, peer-to-peer, and hierarchical multi-agent architectures | multi, agent | multi, agent, orchestrator, peer, hierarchical, architectures |
+| `n8n-mcp-tools-expert` | Expert guide for using n8n-mcp MCP tools effectively. Use when searching for nodes, validating configurations, accessing templates, managing workflows, or us... | n8n, mcp | n8n, mcp, effectively, searching, nodes, validating, configurations, accessing, managing, any, provides, selection |
 | `nestjs-expert` | Nest.js framework expert specializing in module architecture, dependency injection, middleware, guards, interceptors, testing with Jest/Supertest, TypeORM/Mo... | nestjs | nestjs, nest, js, framework, specializing, module, architecture, dependency, injection, middleware, guards, interceptors |
 | `nx-workspace-patterns` | Configure and optimize Nx monorepo workspaces. Use when setting up Nx, configuring project boundaries, optimizing build caching, or implementing affected com... | nx, workspace | nx, workspace, configure, optimize, monorepo, workspaces, setting, up, configuring, boundaries, optimizing, caching |
 | `on-call-handoff-patterns` | Master on-call shift handoffs with context transfer, escalation procedures, and documentation. Use when transitioning on-call responsibilities, documenting s... | on, call, handoff | on, call, handoff, shift, handoffs, context, transfer, escalation, procedures, documentation, transitioning, responsibilities |
@@ -49,6 +54,7 @@ Total skills: 553
 | `production-code-audit` | Autonomously deep-scan entire codebase line-by-line, understand architecture and patterns, then systematically transform it to production-grade, corporate-le... | production, code, audit | production, code, audit, autonomously, deep, scan, entire, codebase, line, understand, architecture, then |
 | `projection-patterns` | Build read models and projections from event streams. Use when implementing CQRS read sides, building materialized views, or optimizing query performance in ... | projection | projection, read, models, projections, event, streams, implementing, cqrs, sides, building, materialized, views |
 | `prompt-engineering` | Expert guide on prompt engineering patterns, best practices, and optimization techniques. Use when user wants to improve prompts, learn prompting strategies,... | prompt, engineering | prompt, engineering, optimization, techniques, user, wants, improve, prompts, learn, prompting, debug, agent |
+| `radix-ui-design-system` | Build accessible design systems with Radix UI primitives. Headless component customization, theming strategies, and compound component patterns for productio... | radix, ui | radix, ui, accessible, primitives, headless, component, customization, theming, compound, grade, libraries |
 | `saga-orchestration` | Implement saga patterns for distributed transactions and cross-aggregate workflows. Use when coordinating multi-step business processes, handling compensatin... | saga | saga, orchestration, distributed, transactions, cross, aggregate, coordinating, multi, step, business, processes, handling |
 | `salesforce-development` | Expert patterns for Salesforce platform development including Lightning Web Components (LWC), Apex triggers and classes, REST/Bulk APIs, Connected Apps, and ... | salesforce | salesforce, development, platform, including, lightning, web, components, lwc, apex, triggers, classes, rest |
 | `skill-developer` | Create and manage Claude Code skills following Anthropic best practices. Use when creating new skills, modifying skill-rules.json, understanding trigger patt... | skill | skill, developer, claude, code, skills, following, anthropic, creating, new, modifying, rules, json |
@@ -56,13 +62,14 @@ Total skills: 553
 | `tailwind-design-system` | Build scalable design systems with Tailwind CSS, design tokens, component libraries, and responsive patterns. Use when creating component libraries, implemen... | tailwind | tailwind, scalable, css, tokens, component, libraries, responsive, creating, implementing, standardizing, ui |
 | `tailwind-patterns` | Tailwind CSS v4 principles. CSS-first configuration, container queries, modern patterns, design token architecture. | tailwind | tailwind, css, v4, principles, first, configuration, container, queries, token, architecture |
 | `testing-patterns` | Jest testing patterns, factory functions, mocking strategies, and TDD workflow. Use when writing unit tests, creating test factories, or following TDD red-gr... |  | testing, jest, factory, functions, mocking, tdd, writing, unit, tests, creating, test, factories |
+| `tool-design` | Build tools that agents can use effectively, including architectural reduction patterns |  | agents, effectively, including, architectural, reduction |
 | `unreal-engine-cpp-pro` | Expert guide for Unreal Engine 5.x C++ development, covering UObject hygiene, performance patterns, and best practices. | unreal, engine, cpp | unreal, engine, cpp, pro, development, covering, uobject, hygiene, performance |
 | `wcag-audit-patterns` | Conduct WCAG 2.2 accessibility audits with automated testing, manual verification, and remediation guidance. Use when auditing websites for accessibility, fi... | wcag, audit | wcag, audit, conduct, accessibility, audits, automated, testing, manual, verification, remediation, guidance, auditing |
 | `workflow-orchestration-patterns` | Design durable workflows with Temporal for distributed systems. Covers workflow vs activity separation, saga patterns, state management, and determinism cons... |  | orchestration, durable, temporal, distributed, covers, vs, activity, separation, saga, state, determinism, constraints |
 | `workflow-patterns` | Use this skill when implementing tasks according to Conductor's TDD workflow, handling phase checkpoints, managing git commits for tasks, or understanding th... |  | skill, implementing, tasks, according, conductor, tdd, handling, phase, checkpoints, managing, git, commits |
 | `zapier-make-patterns` | No-code automation democratizes workflow building. Zapier and Make (formerly Integromat) let non-developers automate business processes without writing code.... | zapier, make | zapier, make, no, code, automation, democratizes, building, formerly, integromat, let, non, developers |
 
-## business (35)
+## business (37)
 
 | Skill | Description | Tags | Triggers |
 | --- | --- | --- | --- |
@@ -72,6 +79,7 @@ Total skills: 553
 | `context-driven-development` | Use this skill when working with Conductor's context-driven development methodology, managing project context artifacts, or understanding the relationship be... | driven | driven, context, development, skill, working, conductor, methodology, managing, artifacts, understanding, relationship, between |
 | `copy-editing` | When the user wants to edit, review, or improve existing marketing copy. Also use when the user mentions 'edit this copy,' 'review my copy,' 'copy feedback,'... | copy, editing | copy, editing, user, wants, edit, review, improve, existing, marketing, mentions, my, feedback |
 | `copywriting` | Use this skill when writing, rewriting, or improving marketing copy for any page (homepage, landing page, pricing, feature, product, or about page). This ski... | copywriting | copywriting, skill, writing, rewriting, improving, marketing, copy, any, page, homepage, landing, pricing |
+| `deep-research` | Execute autonomous multi-step research using Google Gemini Deep Research Agent. Use for: market analysis, competitive landscaping, literature reviews, techni... | deep, research | deep, research, execute, autonomous, multi, step, google, gemini, agent, market, analysis, competitive |
 | `defi-protocol-templates` | Implement DeFi protocols with production-ready templates for staking, AMMs, governance, and lending systems. Use when building decentralized finance applicat... | defi, protocol | defi, protocol, protocols, staking, amms, governance, lending, building, decentralized, finance, applications, smart |
 | `employment-contract-templates` | Create employment contracts, offer letters, and HR policy documents following legal best practices. Use when drafting employment agreements, creating HR poli... | employment, contract | employment, contract, contracts, offer, letters, hr, policy, documents, following, legal, drafting, agreements |
 | `framework-migration-legacy-modernize` | Orchestrate a comprehensive legacy system modernization using the strangler fig pattern, enabling gradual replacement of outdated components while maintainin... | framework, migration, legacy, modernize | framework, migration, legacy, modernize, orchestrate, modernization, strangler, fig, enabling, gradual, replacement, outdated |
@@ -85,6 +93,7 @@ Total skills: 553
 | `paywall-upgrade-cro` | When the user wants to create or optimize in-app paywalls, upgrade screens, upsell modals, or feature gates. Also use when the user mentions "paywall," "upgr... | paywall, upgrade, cro | paywall, upgrade, cro, user, wants, optimize, app, paywalls, screens, upsell, modals, feature |
 | `pricing-strategy` | Design pricing, packaging, and monetization strategies based on value, customer willingness to pay, and growth objectives. | pricing | pricing, packaging, monetization, value, customer, willingness, pay, growth, objectives |
 | `sales-automator` | Draft cold emails, follow-ups, and proposal templates. Creates pricing pages, case studies, and sales scripts. Use PROACTIVELY for sales outreach or lead nur... | sales, automator | sales, automator, draft, cold, emails, follow, ups, proposal, creates, pricing, pages, case |
+| `screenshots` | Generate marketing screenshots of your app using Playwright. Use when the user wants to create screenshots for Product Hunt, social media, landing pages, or ... | screenshots | screenshots, generate, marketing, app, playwright, user, wants, product, hunt, social, media, landing |
 | `scroll-experience` | Expert in building immersive scroll-driven experiences - parallax storytelling, scroll animations, interactive narratives, and cinematic web experiences. Lik... | scroll, experience | scroll, experience, building, immersive, driven, experiences, parallax, storytelling, animations, interactive, narratives, cinematic |
 | `seo-cannibalization-detector` | Analyzes multiple provided pages to identify keyword overlap and potential cannibalization issues. Suggests differentiation strategies. Use PROACTIVELY when ... | seo, cannibalization, detector | seo, cannibalization, detector, analyzes, multiple, provided, pages, identify, keyword, overlap, potential, issues |
 | `seo-content-auditor` | Analyzes provided content for quality, E-E-A-T signals, and SEO best practices. Scores content and provides improvement recommendations based on established ... | seo, content, auditor | seo, content, auditor, analyzes, provided, quality, signals, scores, provides, improvement, recommendations, established |
@@ -102,7 +111,7 @@ Total skills: 553
 | `startup-financial-modeling` | This skill should be used when the user asks to "create financial projections", "build a financial model", "forecast revenue", "calculate burn rate", "estima... | startup, financial, modeling | startup, financial, modeling, skill, should, used, user, asks, projections, model, forecast, revenue |
 | `team-composition-analysis` | This skill should be used when the user asks to "plan team structure", "determine hiring needs", "design org chart", "calculate compensation", "plan equity a... | team, composition | team, composition, analysis, skill, should, used, user, asks, plan, structure, determine, hiring |
 
-## data-ai (81)
+## data-ai (92)
 
 | Skill | Description | Tags | Triggers |
 | --- | --- | --- | --- |
@@ -115,12 +124,14 @@ Total skills: 553
 | `api-documenter` | Master API documentation with OpenAPI 3.1, AI-powered tools, and modern developer experience practices. Create interactive docs, generate SDKs, and build com... | api, documenter | api, documenter, documentation, openapi, ai, powered, developer, experience, interactive, docs, generate, sdks |
 | `autonomous-agent-patterns` | Design patterns for building autonomous coding agents. Covers tool integration, permission systems, browser automation, and human-in-the-loop workflows. Use ... | autonomous, agent | autonomous, agent, building, coding, agents, covers, integration, permission, browser, automation, human, loop |
 | `autonomous-agents` | Autonomous agents are AI systems that can independently decompose goals, plan actions, execute tools, and self-correct without constant human guidance. The c... | autonomous, agents | autonomous, agents, ai, independently, decompose, goals, plan, actions, execute, self, correct, without |
+| `beautiful-prose` | Hard-edged writing style contract for timeless, forceful English prose without AI tics | beautiful, prose | beautiful, prose, hard, edged, writing, style, contract, timeless, forceful, english, without, ai |
 | `behavioral-modes` | AI operational modes (brainstorm, implement, debug, review, teach, ship, orchestrate). Use to adapt behavior based on task type. | behavioral, modes | behavioral, modes, ai, operational, brainstorm, debug, review, teach, ship, orchestrate, adapt, behavior |
 | `blockrun` | Use when user needs capabilities Claude lacks (image generation, real-time X/Twitter data) or explicitly requests external models ("blockrun", "use grok", "u... | blockrun | blockrun, user, capabilities, claude, lacks, image, generation, real, time, twitter, data, explicitly |
 | `browser-automation` | Browser automation powers web testing, scraping, and AI agent interactions. The difference between a flaky script and a reliable system comes down to underst... | browser | browser, automation, powers, web, testing, scraping, ai, agent, interactions, difference, between, flaky |
 | `business-analyst` | Master modern business analysis with AI-powered analytics, real-time dashboards, and data-driven insights. Build comprehensive KPI frameworks, predictive mod... | business, analyst | business, analyst, analysis, ai, powered, analytics, real, time, dashboards, data, driven, insights |
 | `cc-skill-backend-patterns` | Backend architecture patterns, API design, database optimization, and server-side best practices for Node.js, Express, and Next.js API routes. | cc, skill, backend | cc, skill, backend, architecture, api, database, optimization, server, side, node, js, express |
 | `cc-skill-clickhouse-io` | ClickHouse database patterns, query optimization, analytics, and data engineering best practices for high-performance analytical workloads. | cc, skill, clickhouse, io | cc, skill, clickhouse, io, database, query, optimization, analytics, data, engineering, high, performance |
+| `clarity-gate` | Pre-ingestion verification for epistemic quality in RAG systems with 9-point verification and Two-Round HITL workflow | clarity, gate | clarity, gate, pre, ingestion, verification, epistemic, quality, rag, point, two, round, hitl |
 | `code-documentation-doc-generate` | You are a documentation expert specializing in creating comprehensive, maintainable documentation from code. Generate API docs, architecture diagrams, user g... | code, documentation, doc, generate | code, documentation, doc, generate, specializing, creating, maintainable, api, docs, architecture, diagrams, user |
 | `codex-review` | Professional code review with auto CHANGELOG generation, integrated with Codex AI | codex | codex, review, professional, code, auto, changelog, generation, integrated, ai |
 | `content-marketer` | Elite content marketing strategist specializing in AI-powered content creation, omnichannel distribution, SEO optimization, and data-driven performance marke... | content, marketer | content, marketer, elite, marketing, strategist, specializing, ai, powered, creation, omnichannel, distribution, seo |
@@ -139,6 +150,12 @@ Total skills: 553
 | `documentation-generation-doc-generate` | You are a documentation expert specializing in creating comprehensive, maintainable documentation from code. Generate API docs, architecture diagrams, user g... | documentation, generation, doc, generate | documentation, generation, doc, generate, specializing, creating, maintainable, code, api, docs, architecture, diagrams |
 | `documentation-templates` | Documentation templates and structure guidelines. README, API docs, code comments, and AI-friendly documentation. | documentation | documentation, structure, guidelines, readme, api, docs, code, comments, ai, friendly |
 | `embedding-strategies` | Select and optimize embedding models for semantic search and RAG applications. Use when choosing embedding models, implementing chunking strategies, or optim... | embedding, strategies | embedding, strategies, select, optimize, models, semantic, search, rag, applications, choosing, implementing, chunking |
+| `fal-audio` | Text-to-speech and speech-to-text using fal.ai audio models | fal, audio | fal, audio, text, speech, ai, models |
+| `fal-generate` | Generate images and videos using fal.ai AI models | fal, generate | fal, generate, images, videos, ai, models |
+| `fal-image-edit` | AI-powered image editing with style transfer and object removal | fal, image, edit | fal, image, edit, ai, powered, editing, style, transfer, object, removal |
+| `fal-upscale` | Upscale and enhance image and video resolution using AI | fal, upscale | fal, upscale, enhance, image, video, resolution, ai |
+| `fal-workflow` | Generate workflow JSON files for chaining AI models | fal | fal, generate, json, files, chaining, ai, models |
+| `fp-ts-react` | Practical patterns for using fp-ts with React - hooks, state, forms, data fetching. Use when building React apps with functional programming patterns. Works ... | fp, ts, react | fp, ts, react, practical, hooks, state, forms, data, fetching, building, apps, functional |
 | `frontend-dev-guidelines` | Opinionated frontend development standards for modern React + TypeScript applications. Covers Suspense-first data fetching, lazy loading, feature-based archi... | frontend, dev, guidelines | frontend, dev, guidelines, opinionated, development, standards, react, typescript, applications, covers, suspense, first |
 | `geo-fundamentals` | Generative Engine Optimization for AI search engines (ChatGPT, Claude, Perplexity). | geo, fundamentals | geo, fundamentals, generative, engine, optimization, ai, search, engines, chatgpt, claude, perplexity |
 | `graphql` | GraphQL gives clients exactly the data they need - no more, no less. One endpoint, typed schema, introspection. But the flexibility that makes it powerful al... | graphql | graphql, gives, clients, exactly, data, no, less, one, endpoint, typed, schema, introspection |
@@ -150,6 +167,7 @@ Total skills: 553
 | `llm-application-dev-langchain-agent` | You are an expert LangChain agent developer specializing in production-grade AI systems using LangChain 0.1+ and LangGraph. | llm, application, dev, langchain, agent | llm, application, dev, langchain, agent, developer, specializing, grade, ai, langgraph |
 | `llm-application-dev-prompt-optimize` | You are an expert prompt engineer specializing in crafting effective prompts for LLMs through advanced techniques including constitutional AI, chain-of-thoug... | llm, application, dev, prompt, optimize | llm, application, dev, prompt, optimize, engineer, specializing, crafting, effective, prompts, llms, through |
 | `llm-evaluation` | Implement comprehensive evaluation strategies for LLM applications using automated metrics, human feedback, and benchmarking. Use when testing LLM performanc... | llm, evaluation | llm, evaluation, applications, automated, metrics, human, feedback, benchmarking, testing, performance, measuring, ai |
+| `nanobanana-ppt-skills` | AI-powered PPT generation with document analysis and styled images | nanobanana, ppt, skills | nanobanana, ppt, skills, ai, powered, generation, document, analysis, styled, images |
 | `neon-postgres` | Expert patterns for Neon serverless Postgres, branching, connection pooling, and Prisma/Drizzle integration Use when: neon database, serverless postgres, dat... | neon, postgres | neon, postgres, serverless, branching, connection, pooling, prisma, drizzle, integration, database |
 | `nextjs-app-router-patterns` | Master Next.js 14+ App Router with Server Components, streaming, parallel routes, and advanced data fetching. Use when building Next.js applications, impleme... | nextjs, app, router | nextjs, app, router, next, js, 14, server, components, streaming, parallel, routes, data |
 | `nextjs-best-practices` | Next.js App Router principles. Server Components, data fetching, routing patterns. | nextjs, best, practices | nextjs, best, practices, next, js, app, router, principles, server, components, data, fetching |
@@ -172,9 +190,11 @@ Total skills: 553
 | `senior-architect` | Comprehensive software architecture skill for designing scalable, maintainable systems using ReactJS, NextJS, NodeJS, Express, React Native, Swift, Kotlin, F... | senior | senior, architect, software, architecture, skill, designing, scalable, maintainable, reactjs, nextjs, nodejs, express |
 | `seo-audit` | Diagnose and audit SEO issues affecting crawlability, indexation, rankings, and organic performance. Use when the user asks for an SEO audit, technical SEO r... | seo, audit | seo, audit, diagnose, issues, affecting, crawlability, indexation, rankings, organic, performance, user, asks |
 | `similarity-search-patterns` | Implement efficient similarity search with vector databases. Use when building semantic search, implementing nearest neighbor queries, or optimizing retrieva... | similarity, search | similarity, search, efficient, vector, databases, building, semantic, implementing, nearest, neighbor, queries, optimizing |
+| `skill-seekers` | -Automatically convert documentation websites, GitHub repositories, and PDFs into Claude AI skills in minutes. | skill, seekers | skill, seekers, automatically, convert, documentation, websites, github, repositories, pdfs, claude, ai, skills |
 | `spark-optimization` | Optimize Apache Spark jobs with partitioning, caching, shuffle optimization, and memory tuning. Use when improving Spark performance, debugging slow jobs, or... | spark, optimization | spark, optimization, optimize, apache, jobs, partitioning, caching, shuffle, memory, tuning, improving, performance |
 | `sql-optimization-patterns` | Master SQL query optimization, indexing strategies, and EXPLAIN analysis to dramatically improve database performance and eliminate slow queries. Use when de... | sql, optimization | sql, optimization, query, indexing, explain, analysis, dramatically, improve, database, performance, eliminate, slow |
 | `sqlmap-database-pentesting` | This skill should be used when the user asks to "automate SQL injection testing," "enumerate database structure," "extract database credentials using sqlmap,... | sqlmap, database, pentesting | sqlmap, database, pentesting, penetration, testing, skill, should, used, user, asks, automate, sql |
+| `stitch-ui-design` | Expert guide for creating effective prompts for Google Stitch AI UI design tool. Use when user wants to design UI/UX in Stitch, create app interfaces, genera... | stitch, ui | stitch, ui, creating, effective, prompts, google, ai, user, wants, ux, app, interfaces |
 | `tdd-orchestrator` | Master TDD orchestrator specializing in red-green-refactor discipline, multi-agent workflow coordination, and comprehensive test-driven development practices... | tdd, orchestrator | tdd, orchestrator, specializing, red, green, refactor, discipline, multi, agent, coordination, test, driven |
 | `team-collaboration-standup-notes` | You are an expert team communication specialist focused on async-first standup practices, AI-assisted note generation from commit history, and effective remo... | team, collaboration, standup, notes | team, collaboration, standup, notes, communication, async, first, ai, assisted, note, generation, commit |
 | `telegram-bot-builder` | Expert in building Telegram bots that solve real problems - from simple automation to complex AI-powered bots. Covers bot architecture, the Telegram Bot API,... | telegram, bot, builder | telegram, bot, builder, building, bots, solve, real, problems, simple, automation, complex, ai |
@@ -182,13 +202,13 @@ Total skills: 553
 | `unity-ecs-patterns` | Master Unity ECS (Entity Component System) with DOTS, Jobs, and Burst for high-performance game development. Use when building data-oriented games, optimizin... | unity, ecs | unity, ecs, entity, component, dots, jobs, burst, high, performance, game, development, building |
 | `vector-database-engineer` | Expert in vector databases, embedding strategies, and semantic search implementation. Masters Pinecone, Weaviate, Qdrant, Milvus, and pgvector for RAG applic... | vector, database | vector, database, engineer, databases, embedding, semantic, search, masters, pinecone, weaviate, qdrant, milvus |
 | `vector-index-tuning` | Optimize vector index performance for latency, recall, and memory. Use when tuning HNSW parameters, selecting quantization strategies, or scaling vector sear... | vector, index, tuning | vector, index, tuning, optimize, performance, latency, recall, memory, hnsw, parameters, selecting, quantization |
+| `vexor` | Vector-powered CLI for semantic file search with a Claude/Codex skill | vexor | vexor, vector, powered, cli, semantic, file, search, claude, codex, skill |
 | `voice-ai-development` | Expert in building voice AI applications - from real-time voice agents to voice-enabled apps. Covers OpenAI Realtime API, Vapi for voice agents, Deepgram for... | voice, ai | voice, ai, development, building, applications, real, time, agents, enabled, apps, covers, openai |
 | `voice-ai-engine-development` | Build real-time conversational AI voice engines using async worker pipelines, streaming transcription, LLM agents, and TTS synthesis with interrupt handling ... | voice, ai, engine | voice, ai, engine, development, real, time, conversational, engines, async, worker, pipelines, streaming |
 | `web-artifacts-builder` | Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use ... | web, artifacts, builder | web, artifacts, builder, suite, creating, elaborate, multi, component, claude, ai, html, frontend |
-| `xlsx` | Comprehensive spreadsheet creation, editing, and analysis with support for formulas, formatting, data analysis, and visualization. When Claude needs to work ... | xlsx | xlsx, spreadsheet, creation, editing, analysis, formulas, formatting, data, visualization, claude, work, spreadsheets |
 | `xlsx-official` | Comprehensive spreadsheet creation, editing, and analysis with support for formulas, formatting, data analysis, and visualization. When Claude needs to work ... | xlsx, official | xlsx, official, spreadsheet, creation, editing, analysis, formulas, formatting, data, visualization, claude, work |
 
-## development (72)
+## development (81)
 
 | Skill | Description | Tags | Triggers |
 | --- | --- | --- | --- |
@@ -215,9 +235,13 @@ Total skills: 553
 | `fastapi-pro` | Build high-performance async APIs with FastAPI, SQLAlchemy 2.0, and Pydantic V2. Master microservices, WebSockets, and modern Python async patterns. Use PROA... | fastapi | fastapi, pro, high, performance, async, apis, sqlalchemy, pydantic, v2, microservices, websockets, python |
 | `fastapi-templates` | Create production-ready FastAPI projects with async patterns, dependency injection, and comprehensive error handling. Use when building new FastAPI applicati... | fastapi | fastapi, async, dependency, injection, error, handling, building, new, applications, setting, up, backend |
 | `firecrawl-scraper` | Deep web scraping, screenshots, PDF parsing, and website crawling using Firecrawl API | firecrawl, scraper | firecrawl, scraper, deep, web, scraping, screenshots, pdf, parsing, website, crawling, api |
+| `fp-ts-errors` | Handle errors as values using fp-ts Either and TaskEither for cleaner, more predictable TypeScript code. Use when implementing error handling patterns with f... | fp, ts, errors | fp, ts, errors, handle, values, either, taskeither, cleaner, predictable, typescript, code, implementing |
+| `fp-ts-pragmatic` | A practical, jargon-free guide to fp-ts functional programming - the 80/20 approach that gets results without the academic overhead. Use when writing TypeScr... | fp, ts, pragmatic | fp, ts, pragmatic, practical, jargon, free, functional, programming, 80, 20, approach, gets |
 | `frontend-design` | Create distinctive, production-grade frontend interfaces with intentional aesthetics, high craft, and non-generic visual identity. Use when building or styli... | frontend | frontend, distinctive, grade, interfaces, intentional, aesthetics, high, craft, non, generic, visual, identity |
 | `frontend-developer` | Build React components, implement responsive layouts, and handle client-side state management. Masters React 19, Next.js 15, and modern frontend architecture... | frontend | frontend, developer, react, components, responsive, layouts, handle, client, side, state, masters, 19 |
 | `frontend-mobile-development-component-scaffold` | You are a React component architecture expert specializing in scaffolding production-ready, accessible, and performant components. Generate complete componen... | frontend, mobile, component | frontend, mobile, component, development, scaffold, react, architecture, specializing, scaffolding, accessible, performant, components |
+| `frontend-slides` | Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a... | frontend, slides | frontend, slides, stunning, animation, rich, html, presentations, scratch, converting, powerpoint, files, user |
+| `game-development/mobile-games` | Mobile game development principles. Touch input, battery, performance, app stores. | game, development/mobile, games | game, development/mobile, games, mobile, development, principles, touch, input, battery, performance, app, stores |
 | `go-concurrency-patterns` | Master Go concurrency with goroutines, channels, sync primitives, and context. Use when building concurrent Go applications, implementing worker pools, or de... | go, concurrency | go, concurrency, goroutines, channels, sync, primitives, context, building, concurrent, applications, implementing, worker |
 | `golang-pro` | Master Go 1.21+ with modern patterns, advanced concurrency, performance optimization, and production-ready microservices. Expert in the latest Go ecosystem i... | golang | golang, pro, go, 21, concurrency, performance, optimization, microservices, latest, ecosystem, including, generics |
 | `hubspot-integration` | Expert patterns for HubSpot CRM integration including OAuth authentication, CRM objects, associations, batch operations, webhooks, and custom objects. Covers... | hubspot, integration | hubspot, integration, crm, including, oauth, authentication, objects, associations, batch, operations, webhooks, custom |
@@ -226,12 +250,16 @@ Total skills: 553
 | `javascript-testing-patterns` | Implement comprehensive testing strategies using Jest, Vitest, and Testing Library for unit tests, integration tests, and end-to-end testing with mocking, fi... | javascript | javascript, testing, jest, vitest, library, unit, tests, integration, mocking, fixtures, test, driven |
 | `javascript-typescript-typescript-scaffold` | You are a TypeScript project architecture expert specializing in scaffolding production-ready Node.js and frontend applications. Generate complete project st... | javascript, typescript | javascript, typescript, scaffold, architecture, specializing, scaffolding, node, js, frontend, applications, generate, complete |
 | `launch-strategy` | When the user wants to plan a product launch, feature announcement, or release strategy. Also use when the user mentions 'launch,' 'Product Hunt,' 'feature r... | launch | launch, user, wants, plan, product, feature, announcement, release, mentions, hunt, go, market |
+| `makepad-skills` | Makepad UI development skills for Rust apps: setup, patterns, shaders, packaging, and troubleshooting. | makepad, skills | makepad, skills, ui, development, rust, apps, setup, shaders, packaging, troubleshooting |
 | `mcp-builder` | Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use whe... | mcp, builder | mcp, builder, creating, high, quality, model, context, protocol, servers, enable, llms, interact |
 | `memory-safety-patterns` | Implement memory-safe programming with RAII, ownership, smart pointers, and resource management across Rust, C++, and C. Use when writing safe systems code, ... | memory, safety | memory, safety, safe, programming, raii, ownership, smart, pointers, resource, rust, writing, code |
 | `mobile-design` | Mobile-first design and engineering doctrine for iOS and Android apps. Covers touch interaction, performance, platform conventions, offline behavior, and mob... | mobile | mobile, first, engineering, doctrine, ios, android, apps, covers, touch, interaction, performance, platform |
 | `mobile-developer` | Develop React Native, Flutter, or native mobile apps with modern architecture patterns. Masters cross-platform development, native integrations, offline sync... | mobile | mobile, developer, develop, react, native, flutter, apps, architecture, masters, cross, platform, development |
 | `modern-javascript-patterns` | Master ES6+ features including async/await, destructuring, spread operators, arrow functions, promises, modules, iterators, generators, and functional progra... | modern, javascript | modern, javascript, es6, features, including, async, await, destructuring, spread, operators, arrow, functions |
 | `multi-platform-apps-multi-platform` | Build and deploy the same feature consistently across web, mobile, and desktop platforms using API-first architecture and parallel implementation strategies. | multi, platform, apps | multi, platform, apps, deploy, same, feature, consistently, web, mobile, desktop, platforms, api |
+| `n8n-code-python` | Write Python code in n8n Code nodes. Use when writing Python in n8n, using _input/_json/_node syntax, working with standard library, or need to understand Py... | n8n, code, python | n8n, code, python, write, nodes, writing, input, json, node, syntax, working, standard |
+| `n8n-node-configuration` | Operation-aware node configuration guidance. Use when configuring nodes, understanding property dependencies, determining required fields, choosing between g... | n8n, node, configuration | n8n, node, configuration, operation, aware, guidance, configuring, nodes, understanding, property, dependencies, determining |
+| `observe-whatsapp` | Observe and troubleshoot WhatsApp in Kapso: debug message delivery, inspect webhook deliveries/retries, triage API errors, and run health checks. Use when in... | observe, whatsapp | observe, whatsapp, troubleshoot, kapso, debug, message, delivery, inspect, webhook, deliveries, retries, triage |
 | `product-manager-toolkit` | Comprehensive toolkit for product managers including RICE prioritization, customer interview analysis, PRD templates, discovery frameworks, and go-to-market ... | product, manager | product, manager, toolkit, managers, including, rice, prioritization, customer, interview, analysis, prd, discovery |
 | `python-development-python-scaffold` | You are a Python project architecture expert specializing in scaffolding production-ready Python applications. Generate complete project structures with mode... | python | python, development, scaffold, architecture, specializing, scaffolding, applications, generate, complete, structures, tooling, uv |
 | `python-packaging` | Create distributable Python packages with proper project structure, setup.py/pyproject.toml, and publishing to PyPI. Use when packaging Python libraries, cre... | python, packaging | python, packaging, distributable, packages, proper, structure, setup, py, pyproject, toml, publishing, pypi |
@@ -254,6 +282,7 @@ Total skills: 553
 | `shopify-development` | Build Shopify apps, extensions, themes using GraphQL Admin API, Shopify CLI, Polaris UI, and Liquid.
 TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify, development, apps, extensions, themes, graphql, admin, api, cli, polaris, ui, liquid |
 | `slack-bot-builder` | Build Slack apps using the Bolt framework across Python, JavaScript, and Java. Covers Block Kit for rich UIs, interactive components, slash commands, event h... | slack, bot, builder | slack, bot, builder, apps, bolt, framework, python, javascript, java, covers, block, kit |
+| `swiftui-expert-skill` | Write, review, or improve SwiftUI code following best practices for state management, view composition, performance, modern APIs, Swift concurrency, and iOS ... | swiftui, skill | swiftui, skill, write, review, improve, code, following, state, view, composition, performance, apis |
 | `systems-programming-rust-project` | You are a Rust project architecture expert specializing in scaffolding production-ready Rust applications. Generate complete project structures with cargo to... | programming, rust | programming, rust, architecture, specializing, scaffolding, applications, generate, complete, structures, cargo, tooling, proper |
 | `tavily-web` | Web search, content extraction, crawling, and research capabilities using Tavily API | tavily, web | tavily, web, search, content, extraction, crawling, research, capabilities, api |
 | `telegram-mini-app` | Expert in building Telegram Mini Apps (TWA) - web apps that run inside Telegram with native-like experience. Covers the TON ecosystem, Telegram Web App API, ... | telegram, mini, app | telegram, mini, app, building, apps, twa, web, run, inside, native, like, experience |
@@ -266,7 +295,7 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
 | `viral-generator-builder` | Expert in building shareable generator tools that go viral - name generators, quiz makers, avatar creators, personality tests, and calculator tools. Covers t... | viral, generator, builder | viral, generator, builder, building, shareable, go, name, generators, quiz, makers, avatar, creators |
 | `webapp-testing` | Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing... | webapp | webapp, testing, toolkit, interacting, local, web, applications, playwright, supports, verifying, frontend, functionality |
 
-## general (96)
+## general (128)
 
 | Skill | Description | Tags | Triggers |
 | --- | --- | --- | --- |
@@ -276,6 +305,7 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
 | `angular-migration` | Migrate from AngularJS to Angular using hybrid mode, incremental component rewriting, and dependency injection updates. Use when upgrading AngularJS applicat... | angular, migration | angular, migration, migrate, angularjs, hybrid, mode, incremental, component, rewriting, dependency, injection, updates |
 | `anti-reversing-techniques` | Understand anti-reversing, obfuscation, and protection techniques encountered during software analysis. Use when analyzing protected binaries, bypassing anti... | anti, reversing, techniques | anti, reversing, techniques, understand, obfuscation, protection, encountered, during, software, analysis, analyzing, protected |
 | `app-builder` | Main application building orchestrator. Creates full-stack applications from natural language requests. Determines project type, selects tech stack, coordina... | app, builder | app, builder, main, application, building, orchestrator, creates, full, stack, applications, natural, language |
+| `app-builder/templates` | Project scaffolding templates for new applications. Use when creating new projects from scratch. Contains 12 templates for various tech stacks. | app, builder/templates | app, builder/templates, scaffolding, new, applications, creating, scratch, contains, 12, various, tech, stacks |
 | `arm-cortex-expert` | Senior embedded software engineer specializing in firmware and driver development for ARM Cortex-M microcontrollers (Teensy, STM32, nRF52, SAMD). Decades of ... | arm, cortex | arm, cortex, senior, embedded, software, engineer, specializing, firmware, driver, development, microcontrollers, teensy |
 | `avalonia-layout-zafiro` | Guidelines for modern Avalonia UI layout using Zafiro.Avalonia, emphasizing shared styles, generic components, and avoiding XAML redundancy. | avalonia, layout, zafiro | avalonia, layout, zafiro, guidelines, ui, emphasizing, shared, styles, generic, components, avoiding, xaml |
 | `avalonia-zafiro-development` | Mandatory skills, conventions, and behavioral rules for Avalonia UI development using the Zafiro toolkit. | avalonia, zafiro | avalonia, zafiro, development, mandatory, skills, conventions, behavioral, rules, ui, toolkit |
@@ -290,43 +320,67 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
 | `cc-skill-continuous-learning` | Development skill from everything-claude-code | cc, skill, continuous, learning | cc, skill, continuous, learning, development, everything, claude, code |
 | `cc-skill-project-guidelines-example` | Project Guidelines Skill (Example) | cc, skill, guidelines, example | cc, skill, guidelines, example |
 | `cc-skill-strategic-compact` | Development skill from everything-claude-code | cc, skill, strategic, compact | cc, skill, strategic, compact, development, everything, claude, code |
+| `claude-ally-health` | A health assistant skill for medical information analysis, symptom tracking, and wellness guidance. | claude, ally, health | claude, ally, health, assistant, skill, medical, information, analysis, symptom, tracking, wellness, guidance |
 | `claude-code-guide` | Master guide for using Claude Code effectively. Includes configuration templates, prompting strategies "Thinking" keywords, debugging techniques, and best pr... | claude, code | claude, code, effectively, includes, configuration, prompting, thinking, keywords, debugging, techniques, interacting, agent |
+| `claude-scientific-skills` | Scientific research and analysis skills | claude, scientific, skills | claude, scientific, skills, research, analysis |
+| `claude-speed-reader` | -Speed read Claude's responses at 600+ WPM using RSVP with Spritz-style ORP highlighting | claude, speed, reader | claude, speed, reader, read, responses, 600, wpm, rsvp, spritz, style, orp, highlighting |
+| `claude-win11-speckit-update-skill` | Windows 11 system management | claude, win11, speckit, update, skill | claude, win11, speckit, update, skill, windows, 11 |
 | `clean-code` | Pragmatic coding standards - concise, direct, no over-engineering, no unnecessary comments | clean, code | clean, code, pragmatic, coding, standards, concise, direct, no, engineering, unnecessary, comments |
 | `code-documentation-code-explain` | You are a code education expert specializing in explaining complex code through clear narratives, visual diagrams, and step-by-step breakdowns. Transform dif... | code, documentation, explain | code, documentation, explain, education, specializing, explaining, complex, through, clear, narratives, visual, diagrams |
 | `code-refactoring-context-restore` | Use when working with code refactoring context restore | code, refactoring, restore | code, refactoring, restore, context, working |
 | `code-refactoring-tech-debt` | You are a technical debt expert specializing in identifying, quantifying, and prioritizing technical debt in software projects. Analyze the codebase to uncov... | code, refactoring, tech, debt | code, refactoring, tech, debt, technical, specializing, identifying, quantifying, prioritizing, software, analyze, codebase |
 | `code-review-excellence` | Master effective code review practices to provide constructive feedback, catch bugs early, and foster knowledge sharing while maintaining team morale. Use wh... | code, excellence | code, excellence, review, effective, provide, constructive, feedback, catch, bugs, early, foster, knowledge |
 | `codebase-cleanup-tech-debt` | You are a technical debt expert specializing in identifying, quantifying, and prioritizing technical debt in software projects. Analyze the codebase to uncov... | codebase, cleanup, tech, debt | codebase, cleanup, tech, debt, technical, specializing, identifying, quantifying, prioritizing, software, analyze, uncover |
+| `commit` | Create commit messages following Sentry conventions. Use when committing code changes, writing commit messages, or formatting git history. Follows convention... | commit | commit, messages, following, sentry, conventions, committing, code, changes, writing, formatting, git, history |
 | `comprehensive-review-full-review` | Use when working with comprehensive review full review | comprehensive, full | comprehensive, full, review, working |
 | `comprehensive-review-pr-enhance` | You are a PR optimization expert specializing in creating high-quality pull requests that facilitate efficient code reviews. Generate comprehensive PR descri... | comprehensive, pr, enhance | comprehensive, pr, enhance, review, optimization, specializing, creating, high, quality, pull, requests, facilitate |
 | `concise-planning` | Use when a user asks for a plan for a coding task, to generate a clear, actionable, and atomic checklist. | concise, planning | concise, planning, user, asks, plan, coding, task, generate, clear, actionable, atomic, checklist |
+| `context-compression` | Design and evaluate compression strategies for long-running sessions | compression | compression, context, evaluate, long, running, sessions |
+| `context-fundamentals` | Understand what context is, why it matters, and the anatomy of context in agent systems | fundamentals | fundamentals, context, understand, what, why, matters, anatomy, agent |
 | `context-management-context-restore` | Use when working with context management context restore | restore | restore, context, working |
 | `context-management-context-save` | Use when working with context management context save | save | save, context, working |
+| `context-optimization` | Apply compaction, masking, and caching strategies | optimization | optimization, context, apply, compaction, masking, caching |
+| `create-pr` | Create pull requests following Sentry conventions. Use when opening PRs, writing PR descriptions, or preparing changes for review. Follows Sentry's code revi... | create, pr | create, pr, pull, requests, following, sentry, conventions, opening, prs, writing, descriptions, preparing |
+| `culture-index` | Index and search culture documentation | culture, index | culture, index, search, documentation |
 | `daily-news-report` | Scrapes content based on a preset URL list, filters high-quality technical information, and generates daily Markdown reports. | daily, news, report | daily, news, report, scrapes, content, preset, url, list, filters, high, quality, technical |
 | `debugging-strategies` | Master systematic debugging techniques, profiling tools, and root cause analysis to efficiently track down bugs across any codebase or technology stack. Use ... | debugging, strategies | debugging, strategies, systematic, techniques, profiling, root, cause, analysis, efficiently, track, down, bugs |
 | `debugging-toolkit-smart-debug` | Use when working with debugging toolkit smart debug | debugging, debug | debugging, debug, toolkit, smart, working |
+| `design-md` | Analyze Stitch projects and synthesize a semantic design system into DESIGN.md files | md | md, analyze, stitch, synthesize, semantic, files |
 | `dispatching-parallel-agents` | Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | dispatching, parallel, agents | dispatching, parallel, agents, facing, independent, tasks, worked, without, shared, state, sequential, dependencies |
-| `docx` | Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. When Claude ... | docx | docx, document, creation, editing, analysis, tracked, changes, comments, formatting, preservation, text, extraction |
 | `docx-official` | Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. When Claude ... | docx, official | docx, official, document, creation, editing, analysis, tracked, changes, comments, formatting, preservation, text |
 | `dx-optimizer` | Developer Experience specialist. Improves tooling, setup, and workflows. Use PROACTIVELY when setting up new projects, after team feedback, or when developme... | dx, optimizer | dx, optimizer, developer, experience, improves, tooling, setup, proactively, setting, up, new, after |
 | `environment-setup-guide` | Guide developers through setting up development environments with proper tools, dependencies, and configurations | environment, setup | environment, setup, developers, through, setting, up, development, environments, proper, dependencies, configurations |
 | `error-debugging-multi-agent-review` | Use when working with error debugging multi agent review | error, debugging, multi, agent | error, debugging, multi, agent, review, working |
 | `error-diagnostics-smart-debug` | Use when working with error diagnostics smart debug | error, diagnostics, debug | error, diagnostics, debug, smart, working |
+| `evaluation` | Build evaluation frameworks for agent systems | evaluation | evaluation, frameworks, agent |
 | `executing-plans` | Use when you have a written implementation plan to execute in a separate session with review checkpoints | executing, plans | executing, plans, written, plan, execute, separate, session, review, checkpoints |
+| `fal-platform` | Platform APIs for model management, pricing, and usage tracking | fal, platform | fal, platform, apis, model, pricing, usage, tracking |
+| `ffuf-claude-skill` | Web fuzzing with ffuf | ffuf, claude, skill | ffuf, claude, skill, web, fuzzing |
 | `file-organizer` | Intelligently organizes files and folders by understanding context, finding duplicates, and suggesting better organizational structures. Use when user wants ... | file, organizer | file, organizer, intelligently, organizes, files, folders, understanding, context, finding, duplicates, suggesting, better |
 | `finishing-a-development-branch` | Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting s... | finishing, a, branch | finishing, a, branch, development, complete, all, tests, pass, decide, how, integrate, work |
+| `fix-review` | Verify fix commits address audit findings without new bugs | fix | fix, review, verify, commits, address, audit, findings, without, new, bugs |
 | `framework-migration-code-migrate` | You are a code migration expert specializing in transitioning codebases between frameworks, languages, versions, and platforms. Generate comprehensive migrat... | framework, migration, code, migrate | framework, migration, code, migrate, specializing, transitioning, codebases, between, frameworks, languages, versions, platforms |
 | `game-development` | Game development orchestrator. Routes to platform-specific skills based on project needs. | game | game, development, orchestrator, routes, platform, specific, skills |
+| `game-development/2d-games` | 2D game development principles. Sprites, tilemaps, physics, camera. | game, development/2d, games | game, development/2d, games, 2d, development, principles, sprites, tilemaps, physics, camera |
+| `game-development/3d-games` | 3D game development principles. Rendering, shaders, physics, cameras. | game, development/3d, games | game, development/3d, games, 3d, development, principles, rendering, shaders, physics, cameras |
+| `game-development/game-audio` | Game audio principles. Sound design, music integration, adaptive audio systems. | game, development/game, audio | game, development/game, audio, principles, sound, music, integration, adaptive |
+| `game-development/game-design` | Game design principles. GDD structure, balancing, player psychology, progression. | game, development/game | game, development/game, principles, gdd, structure, balancing, player, psychology, progression |
+| `game-development/pc-games` | PC and console game development principles. Engine selection, platform features, optimization strategies. | game, development/pc, games | game, development/pc, games, pc, console, development, principles, engine, selection, platform, features, optimization |
+| `game-development/vr-ar` | VR/AR development principles. Comfort, interaction, performance requirements. | game, development/vr, ar | game, development/vr, ar, vr, development, principles, comfort, interaction, performance, requirements |
+| `game-development/web-games` | Web browser game development principles. Framework selection, WebGPU, optimization, PWA. | game, development/web, games | game, development/web, games, web, browser, development, principles, framework, selection, webgpu, optimization, pwa |
 | `git-advanced-workflows` | Master advanced Git workflows including rebasing, cherry-picking, bisect, worktrees, and reflog to maintain clean history and recover from any situation. Use... | git, advanced | git, advanced, including, rebasing, cherry, picking, bisect, worktrees, reflog, maintain, clean, history |
 | `git-pr-workflows-onboard` | You are an **expert onboarding specialist and knowledge transfer architect** with deep experience in remote-first organizations, technical team integration, ... | git, pr, onboard | git, pr, onboard, onboarding, knowledge, transfer, architect, deep, experience, remote, first, organizations |
 | `git-pr-workflows-pr-enhance` | You are a PR optimization expert specializing in creating high-quality pull requests that facilitate efficient code reviews. Generate comprehensive PR descri... | git, pr, enhance | git, pr, enhance, optimization, specializing, creating, high, quality, pull, requests, facilitate, efficient |
+| `imagen` |  | imagen | imagen |
 | `infinite-gratitude` | Multi-agent research skill for parallel research execution (10 agents, battle-tested with real case studies). | infinite, gratitude | infinite, gratitude, multi, agent, research, skill, parallel, execution, 10, agents, battle, tested |
 | `interactive-portfolio` | Expert in building portfolios that actually land jobs and clients - not just showing work, but creating memorable experiences. Covers developer portfolios, d... | interactive, portfolio | interactive, portfolio, building, portfolios, actually, land, jobs, clients, just, showing, work, creating |
 | `last30days` | Research a topic from the last 30 days on Reddit + X + Web, become an expert, and write copy-paste-ready prompts for the user's target tool. | last30days | last30days, research, topic, last, 30, days, reddit, web, become, write, copy, paste |
 | `legacy-modernizer` | Refactor legacy codebases, migrate outdated frameworks, and implement gradual modernization. Handles technical debt, dependency updates, and backward compati... | legacy, modernizer | legacy, modernizer, refactor, codebases, migrate, outdated, frameworks, gradual, modernization, technical, debt, dependency |
+| `linear-claude-skill` | Manage Linear issues, projects, and teams | linear, claude, skill | linear, claude, skill, issues, teams |
 | `lint-and-validate` | Automatic quality control, linting, and static analysis procedures. Use after every code modification to ensure syntax correctness and project standards. Tri... | lint, and, validate | lint, and, validate, automatic, quality, control, linting, static, analysis, procedures, after, every |
 | `linux-privilege-escalation` | This skill should be used when the user asks to "escalate privileges on Linux", "find privesc vectors on Linux systems", "exploit sudo misconfigurations", "a... | linux, privilege, escalation | linux, privilege, escalation, skill, should, used, user, asks, escalate, privileges, find, privesc |
 | `linux-shell-scripting` | This skill should be used when the user asks to "create bash scripts", "automate Linux tasks", "monitor system resources", "backup files", "manage users", or... | linux, shell, scripting | linux, shell, scripting, scripts, skill, should, used, user, asks, bash, automate, tasks |
+| `memory-systems` | Design short-term, long-term, and graph-based memory architectures | memory | memory, short, term, long, graph, architectures |
 | `micro-saas-launcher` | Expert in launching small, focused SaaS products fast - the indie hacker approach to building profitable software. Covers idea validation, MVP development, p... | micro, saas, launcher | micro, saas, launcher, launching, small, products, fast, indie, hacker, approach, building, profitable |
 | `monorepo-management` | Master monorepo management with Turborepo, Nx, and pnpm workspaces to build efficient, scalable multi-package repositories with optimized builds and dependen... | monorepo | monorepo, turborepo, nx, pnpm, workspaces, efficient, scalable, multi, package, repositories, optimized, dependency |
 | `nft-standards` | Implement NFT standards (ERC-721, ERC-1155) with proper metadata handling, minting strategies, and marketplace integration. Use when creating NFT contracts, ... | nft, standards | nft, standards, erc, 721, 1155, proper, metadata, handling, minting, marketplace, integration, creating |
@@ -340,24 +394,30 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
 | `plan-writing` | Structured task planning with clear breakdowns, dependencies, and verification criteria. Use when implementing features, refactoring, or any multi-step work. | plan, writing | plan, writing, structured, task, planning, clear, breakdowns, dependencies, verification, criteria, implementing, features |
 | `planning-with-files` | Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks,... | planning, with, files | planning, with, files, implements, manus, style, file, complex, tasks, creates, task, plan |
 | `posix-shell-pro` | Expert in strict POSIX sh scripting for maximum portability across Unix-like systems. Specializes in shell scripts that run on any POSIX-compliant shell (das... | posix, shell | posix, shell, pro, strict, sh, scripting, maximum, portability, unix, like, specializes, scripts |
-| `pptx` | Presentation creation, editing, and analysis. When Claude needs to work with presentations (.pptx files) for: (1) Creating new presentations, (2) Modifying o... | pptx | pptx, presentation, creation, editing, analysis, claude, work, presentations, files, creating, new, modifying |
 | `pptx-official` | Presentation creation, editing, and analysis. When Claude needs to work with presentations (.pptx files) for: (1) Creating new presentations, (2) Modifying o... | pptx, official | pptx, official, presentation, creation, editing, analysis, claude, work, presentations, files, creating, new |
 | `privilege-escalation-methods` | This skill should be used when the user asks to "escalate privileges", "get root access", "become administrator", "privesc techniques", "abuse sudo", "exploi... | privilege, escalation, methods | privilege, escalation, methods, skill, should, used, user, asks, escalate, privileges, get, root |
 | `prompt-library` | Curated collection of high-quality prompts for various use cases. Includes role-based prompts, task-specific templates, and prompt refinement techniques. Use... | prompt, library | prompt, library, curated, collection, high, quality, prompts, various, cases, includes, role, task |
+| `readme` | When the user wants to create or update a README.md file for a project. Also use when the user says | readme | readme, user, wants, update, md, file, says |
 | `receiving-code-review` | Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technic... | receiving, code | receiving, code, review, feedback, before, implementing, suggestions, especially, seems, unclear, technically, questionable |
 | `referral-program` | When the user wants to create, optimize, or analyze a referral program, affiliate program, or word-of-mouth strategy. Also use when the user mentions 'referr... | referral, program | referral, program, user, wants, optimize, analyze, affiliate, word, mouth, mentions, ambassador, viral |
 | `requesting-code-review` | Use when completing tasks, implementing major features, or before merging to verify work meets requirements | requesting, code | requesting, code, review, completing, tasks, implementing, major, features, before, merging, verify, work |
 | `search-specialist` | Expert web researcher using advanced search techniques and synthesis. Masters search operators, result filtering, and multi-source verification. Handles comp... | search | search, web, researcher, techniques, synthesis, masters, operators, result, filtering, multi, source, verification |
+| `sharp-edges` | Identify error-prone APIs and dangerous configurations | sharp, edges | sharp, edges, identify, error, prone, apis, dangerous, configurations |
 | `shellcheck-configuration` | Master ShellCheck static analysis configuration and usage for shell script quality. Use when setting up linting infrastructure, fixing code issues, or ensuri... | shellcheck, configuration | shellcheck, configuration, static, analysis, usage, shell, script, quality, setting, up, linting, infrastructure |
 | `signup-flow-cro` | When the user wants to optimize signup, registration, account creation, or trial activation flows. Also use when the user mentions "signup conversions," "reg... | signup, flow, cro | signup, flow, cro, user, wants, optimize, registration, account, creation, trial, activation, flows |
 | `skill-creator` | Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capa... | skill, creator | skill, creator, creating, effective, skills, should, used, users, want, new, update, existing |
+| `skill-rails-upgrade` | Analyze Rails apps and provide upgrade assessments | skill, rails, upgrade | skill, rails, upgrade, analyze, apps, provide, assessments |
 | `slack-gif-creator` | Knowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users reques... | slack, gif, creator | slack, gif, creator, knowledge, utilities, creating, animated, gifs, optimized, provides, constraints, validation |
 | `social-content` | When the user wants help creating, scheduling, or optimizing social media content for LinkedIn, Twitter/X, Instagram, TikTok, Facebook, or other platforms. A... | social, content | social, content, user, wants, creating, scheduling, optimizing, media, linkedin, twitter, instagram, tiktok |
 | `subagent-driven-development` | Use when executing implementation plans with independent tasks in the current session | subagent, driven | subagent, driven, development, executing, plans, independent, tasks, current, session |
+| `superpowers-lab` | Lab environment for Claude superpowers | superpowers, lab | superpowers, lab, environment, claude |
 | `theme-factory` | Toolkit for styling artifacts with a theme. These artifacts can be slides, docs, reportings, HTML landing pages, etc. There are 10 pre-set themes with colors... | theme, factory | theme, factory, toolkit, styling, artifacts, these, slides, docs, reportings, html, landing, pages |
+| `threejs-skills` | Three.js skills for creating 3D elements and interactive experiences | threejs, skills | threejs, skills, three, js, creating, 3d, elements, interactive, experiences |
 | `turborepo-caching` | Configure Turborepo for efficient monorepo builds with local and remote caching. Use when setting up Turborepo, optimizing build pipelines, or implementing d... | turborepo, caching | turborepo, caching, configure, efficient, monorepo, local, remote, setting, up, optimizing, pipelines, implementing |
 | `tutorial-engineer` | Creates step-by-step tutorials and educational content from code. Transforms complex concepts into progressive learning experiences with hands-on examples. U... | tutorial | tutorial, engineer, creates, step, tutorials, educational, content, code, transforms, complex, concepts, progressive |
+| `ui-skills` | Opinionated, evolving constraints to guide agents when building interfaces | ui, skills | ui, skills, opinionated, evolving, constraints, agents, building, interfaces |
 | `ui-ux-designer` | Create interface designs, wireframes, and design systems. Masters user research, accessibility standards, and modern design tools. Specializes in design toke... | ui, ux, designer | ui, ux, designer, interface, designs, wireframes, masters, user, research, accessibility, standards, specializes |
+| `upgrading-expo` | Upgrade Expo SDK versions | upgrading, expo | upgrading, expo, upgrade, sdk, versions |
 | `upstash-qstash` | Upstash QStash expert for serverless message queues, scheduled jobs, and reliable HTTP-based task delivery without managing infrastructure. Use when: qstash,... | upstash, qstash | upstash, qstash, serverless, message, queues, scheduled, jobs, reliable, http, task, delivery, without |
 | `using-git-worktrees` | Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with sma... | using, git, worktrees | using, git, worktrees, starting, feature, work, isolation, current, workspace, before, executing, plans |
 | `using-superpowers` | Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions | using, superpowers | using, superpowers, starting, any, conversation, establishes, how, find, skills, requiring, skill, invocation |
@@ -366,8 +426,9 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
 | `windows-privilege-escalation` | This skill should be used when the user asks to "escalate privileges on Windows," "find Windows privesc vectors," "enumerate Windows for privilege escalation... | windows, privilege, escalation | windows, privilege, escalation, skill, should, used, user, asks, escalate, privileges, find, privesc |
 | `writing-plans` | Use when you have a spec or requirements for a multi-step task, before touching code | writing, plans | writing, plans, spec, requirements, multi, step, task, before, touching, code |
 | `writing-skills` | Use when creating, updating, or improving agent skills. | writing, skills | writing, skills, creating, updating, improving, agent |
+| `x-article-publisher-skill` | Publish articles to X/Twitter | x, article, publisher, skill | x, article, publisher, skill, publish, articles, twitter |
 
-## infrastructure (71)
+## infrastructure (78)
 
 | Skill | Description | Tags | Triggers |
 | --- | --- | --- | --- |
@@ -376,6 +437,7 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
 | `api-testing-observability-api-mock` | You are an API mocking expert specializing in realistic mock services for development, testing, and demos. Design mocks that simulate real API behavior and e... | api, observability, mock | api, observability, mock, testing, mocking, specializing, realistic, development, demos, mocks, simulate, real |
 | `application-performance-performance-optimization` | Optimize end-to-end application performance with profiling, observability, and backend/frontend tuning. Use when coordinating performance optimization across... | application, performance, optimization | application, performance, optimization, optimize, profiling, observability, backend, frontend, tuning, coordinating, stack |
 | `aws-serverless` | Specialized skill for building production-ready serverless applications on AWS. Covers Lambda functions, API Gateway, DynamoDB, SQS/SNS event-driven patterns... | aws, serverless | aws, serverless, specialized, skill, building, applications, covers, lambda, functions, api, gateway, dynamodb |
+| `aws-skills` | AWS development with infrastructure automation and cloud architecture patterns | aws, skills | aws, skills, development, infrastructure, automation, cloud, architecture |
 | `backend-architect` | Expert backend architect specializing in scalable API design, microservices architecture, and distributed systems. Masters REST/GraphQL/gRPC APIs, event-driv... | backend | backend, architect, specializing, scalable, api, microservices, architecture, distributed, masters, rest, graphql, grpc |
 | `backend-development-feature-development` | Orchestrate end-to-end backend feature development from requirements to deployment. Use when coordinating multi-phase feature delivery across teams and servi... | backend | backend, development, feature, orchestrate, requirements, deployment, coordinating, multi, phase, delivery, teams |
 | `bash-defensive-patterns` | Master defensive Bash programming techniques for production-grade scripts. Use when writing robust shell scripts, CI/CD pipelines, or system utilities requir... | bash, defensive | bash, defensive, programming, techniques, grade, scripts, writing, robust, shell, ci, cd, pipelines |
@@ -400,8 +462,10 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
 | `error-debugging-error-trace` | You are an error tracking and observability expert specializing in implementing comprehensive error monitoring solutions. Set up error tracking systems, conf... | error, debugging, trace | error, debugging, trace, tracking, observability, specializing, implementing, monitoring, solutions, set, up, configure |
 | `error-diagnostics-error-analysis` | You are an expert error analysis specialist with deep expertise in debugging distributed systems, analyzing production incidents, and implementing comprehens... | error, diagnostics | error, diagnostics, analysis, deep, expertise, debugging, distributed, analyzing, incidents, implementing, observability, solutions |
 | `error-diagnostics-error-trace` | You are an error tracking and observability expert specializing in implementing comprehensive error monitoring solutions. Set up error tracking systems, conf... | error, diagnostics, trace | error, diagnostics, trace, tracking, observability, specializing, implementing, monitoring, solutions, set, up, configure |
+| `expo-deployment` | Deploy Expo apps to production | expo, deployment | expo, deployment, deploy, apps |
 | `file-uploads` | Expert at handling file uploads and cloud storage. Covers S3, Cloudflare R2, presigned URLs, multipart uploads, and image optimization. Knows how to handle l... | file, uploads | file, uploads, handling, cloud, storage, covers, s3, cloudflare, r2, presigned, urls, multipart |
 | `flutter-expert` | Master Flutter development with Dart 3, advanced widgets, and multi-platform deployment. Handles state management, animations, testing, and performance optim... | flutter | flutter, development, dart, widgets, multi, platform, deployment, state, animations, testing, performance, optimization |
+| `game-development/game-art` | Game art principles. Visual style selection, asset pipeline, animation workflow. | game, development/game, art | game, development/game, art, principles, visual, style, selection, asset, pipeline, animation |
 | `gcp-cloud-run` | Specialized skill for building production-ready serverless applications on GCP. Covers Cloud Run services (containerized), Cloud Run Functions (event-driven)... | gcp, cloud, run | gcp, cloud, run, specialized, skill, building, serverless, applications, covers, containerized, functions, event |
 | `git-pr-workflows-git-workflow` | Orchestrate a comprehensive git workflow from code review through PR creation, leveraging specialized agents for quality assurance, testing, and deployment r... | git, pr | git, pr, orchestrate, code, review, through, creation, leveraging, specialized, agents, quality, assurance |
 | `github-actions-templates` | Create production-ready GitHub Actions workflows for automated testing, building, and deploying applications. Use when setting up CI/CD with GitHub Actions, ... | github, actions | github, actions, automated, testing, building, deploying, applications, setting, up, ci, cd, automating |
@@ -410,8 +474,10 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
 | `gitops-workflow` | Implement GitOps workflows with ArgoCD and Flux for automated, declarative Kubernetes deployments with continuous reconciliation. Use when implementing GitOp... | gitops | gitops, argocd, flux, automated, declarative, kubernetes, deployments, continuous, reconciliation, implementing, automating, setting |
 | `grafana-dashboards` | Create and manage production Grafana dashboards for real-time visualization of system and application metrics. Use when building monitoring dashboards, visua... | grafana, dashboards | grafana, dashboards, real, time, visualization, application, metrics, building, monitoring, visualizing, creating, operational |
 | `helm-chart-scaffolding` | Design, organize, and manage Helm charts for templating and packaging Kubernetes applications with reusable configurations. Use when creating Helm charts, pa... | helm, chart | helm, chart, scaffolding, organize, charts, templating, packaging, kubernetes, applications, reusable, configurations, creating |
+| `hugging-face-cli` | Execute Hugging Face Hub operations using the `hf` CLI. Use when the user needs to download models/datasets/spaces, upload files to Hub repositories, create ... | hugging, face, cli | hugging, face, cli, execute, hub, operations, hf, user, download, models, datasets, spaces |
 | `hybrid-cloud-networking` | Configure secure, high-performance connectivity between on-premises infrastructure and cloud platforms using VPN and dedicated connections. Use when building... | hybrid, cloud, networking | hybrid, cloud, networking, configure, secure, high, performance, connectivity, between, premises, infrastructure, platforms |
 | `istio-traffic-management` | Configure Istio traffic management including routing, load balancing, circuit breakers, and canary deployments. Use when implementing service mesh traffic po... | istio, traffic | istio, traffic, configure, including, routing, load, balancing, circuit, breakers, canary, deployments, implementing |
+| `iterate-pr` | Iterate on a PR until CI passes. Use when you need to fix CI failures, address review feedback, or continuously push fixes until all checks are green. Automa... | iterate, pr | iterate, pr, until, ci, passes, fix, failures, address, review, feedback, continuously, push |
 | `java-pro` | Master Java 21+ with modern features like virtual threads, pattern matching, and Spring Boot 3.x. Expert in the latest Java ecosystem including GraalVM, Proj... | java | java, pro, 21, features, like, virtual, threads, matching, spring, boot, latest, ecosystem |
 | `kpi-dashboard-design` | Design effective KPI dashboards with metrics selection, visualization best practices, and real-time monitoring patterns. Use when building business dashboard... | kpi, dashboard | kpi, dashboard, effective, dashboards, metrics, selection, visualization, real, time, monitoring, building, business |
 | `langfuse` | Expert in Langfuse - the open-source LLM observability platform. Covers tracing, prompt management, evaluation, datasets, and integration with LangChain, Lla... | langfuse | langfuse, open, source, llm, observability, platform, covers, tracing, prompt, evaluation, datasets, integration |
@@ -436,14 +502,16 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
 | `sql-pro` | Master modern SQL with cloud-native databases, OLTP/OLAP optimization, and advanced query techniques. Expert in performance tuning, data modeling, and hybrid... | sql | sql, pro, cloud, native, databases, oltp, olap, optimization, query, techniques, performance, tuning |
 | `temporal-python-pro` | Master Temporal workflow orchestration with Python SDK. Implements durable workflows, saga patterns, and distributed transactions. Covers async/await, testin... | temporal, python | temporal, python, pro, orchestration, sdk, implements, durable, saga, distributed, transactions, covers, async |
 | `terraform-module-library` | Build reusable Terraform modules for AWS, Azure, and GCP infrastructure following infrastructure-as-code best practices. Use when creating infrastructure mod... | terraform, module, library | terraform, module, library, reusable, modules, aws, azure, gcp, infrastructure, following, code, creating |
+| `terraform-skill` | Terraform infrastructure as code best practices | terraform, skill | terraform, skill, infrastructure, code |
 | `test-automator` | Master AI-powered test automation with modern frameworks, self-healing tests, and comprehensive quality engineering. Build scalable testing strategies with a... | automator | automator, test, ai, powered, automation, frameworks, self, healing, tests, quality, engineering, scalable |
 | `unity-developer` | Build Unity games with optimized C# scripts, efficient rendering, and proper asset management. Masters Unity 6 LTS, URP/HDRP pipelines, and cross-platform de... | unity | unity, developer, games, optimized, scripts, efficient, rendering, proper, asset, masters, lts, urp |
+| `vercel-deploy-claimable` | Deploy applications and websites to Vercel. Use this skill when the user requests deployment actions such as | vercel, deploy, claimable | vercel, deploy, claimable, applications, websites, skill, user, requests, deployment, actions, such |
 | `vercel-deployment` | Expert knowledge for deploying to Vercel with Next.js Use when: vercel, deploy, deployment, hosting, production. | vercel, deployment | vercel, deployment, knowledge, deploying, next, js, deploy, hosting |
 | `voice-agents` | Voice agents represent the frontier of AI interaction - humans speaking naturally with AI systems. The challenge isn't just speech recognition and synthesis,... | voice, agents | voice, agents, represent, frontier, ai, interaction, humans, speaking, naturally, challenge, isn, just |
 | `wireshark-analysis` | This skill should be used when the user asks to "analyze network traffic with Wireshark", "capture packets for troubleshooting", "filter PCAP files", "follow... | wireshark | wireshark, network, traffic, analysis, skill, should, used, user, asks, analyze, capture, packets |
 | `workflow-automation` | Workflow automation is the infrastructure that makes AI agents reliable. Without durable execution, a network hiccup during a 10-step payment flow means lost... |  | automation, infrastructure, makes, ai, agents, reliable, without, durable, execution, network, hiccup, during |
 
-## security (107)
+## security (112)
 
 | Skill | Description | Tags | Triggers |
 | --- | --- | --- | --- |
@@ -479,6 +547,7 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
 | `docker-expert` | Docker containerization expert with deep knowledge of multi-stage builds, image optimization, container security, Docker Compose orchestration, and productio... | docker | docker, containerization, deep, knowledge, multi, stage, image, optimization, container, security, compose, orchestration |
 | `ethical-hacking-methodology` | This skill should be used when the user asks to "learn ethical hacking", "understand penetration testing lifecycle", "perform reconnaissance", "conduct secur... | ethical, hacking, methodology | ethical, hacking, methodology, skill, should, used, user, asks, learn, understand, penetration, testing |
 | `file-path-traversal` | This skill should be used when the user asks to "test for directory traversal", "exploit path traversal vulnerabilities", "read arbitrary files through web a... | file, path, traversal | file, path, traversal, testing, skill, should, used, user, asks, test, directory, exploit |
+| `find-bugs` | Find bugs, security vulnerabilities, and code quality issues in local branch changes. Use when asked to review changes, find bugs, security review, or audit ... | find, bugs | find, bugs, security, vulnerabilities, code, quality, issues, local, branch, changes, asked, review |
 | `firebase` | Firebase gives you a complete backend in minutes - auth, database, storage, functions, hosting. But the ease of setup hides real complexity. Security rules a... | firebase | firebase, gives, complete, backend, minutes, auth, database, storage, functions, hosting, ease, setup |
 | `firmware-analyst` | Expert firmware analyst specializing in embedded systems, IoT security, and hardware reverse engineering. Masters firmware extraction, analysis, and vulnerab... | firmware, analyst | firmware, analyst, specializing, embedded, iot, security, hardware, reverse, engineering, masters, extraction, analysis |
 | `form-cro` | Optimize any form that is NOT signup or account registration — including lead capture, contact, demo request, application, survey, quote, and checkout forms.... | form, cro | form, cro, optimize, any, signup, account, registration, including, lead, capture, contact, demo |
@@ -488,6 +557,7 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
 | `gdpr-data-handling` | Implement GDPR-compliant data handling with consent management, data subject rights, and privacy by design. Use when building systems that process EU persona... | gdpr, data, handling | gdpr, data, handling, compliant, consent, subject, rights, privacy, building, process, eu, personal |
 | `graphql-architect` | Master modern GraphQL with federation, performance optimization, and enterprise security. Build scalable schemas, implement advanced caching, and design real... | graphql | graphql, architect, federation, performance, optimization, enterprise, security, scalable, schemas, caching, real, time |
 | `html-injection-testing` | This skill should be used when the user asks to "test for HTML injection", "inject HTML into web pages", "perform HTML injection attacks", "deface web applic... | html, injection | html, injection, testing, skill, should, used, user, asks, test, inject, web, pages |
+| `hugging-face-jobs` | This skill should be used when users want to run any workload on Hugging Face Jobs infrastructure. Covers UV scripts, Docker-based jobs, hardware selection, ... | hugging, face, jobs | hugging, face, jobs, skill, should, used, users, want, run, any, workload, infrastructure |
 | `hybrid-cloud-architect` | Expert hybrid cloud architect specializing in complex multi-cloud solutions across AWS/Azure/GCP and private clouds (OpenStack/VMware). Masters hybrid connec... | hybrid, cloud | hybrid, cloud, architect, specializing, complex, multi, solutions, aws, azure, gcp, private, clouds |
 | `idor-testing` | This skill should be used when the user asks to "test for insecure direct object references," "find IDOR vulnerabilities," "exploit broken access control," "... | idor | idor, vulnerability, testing, skill, should, used, user, asks, test, insecure, direct, object |
 | `incident-responder` | Expert SRE incident responder specializing in rapid problem resolution, modern observability, and comprehensive incident management. Masters incident command... | incident, responder | incident, responder, sre, specializing, rapid, problem, resolution, observability, masters, command, blameless, post |
@@ -531,6 +601,7 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
 | `scanning-tools` | This skill should be used when the user asks to "perform vulnerability scanning", "scan networks for open ports", "assess web application security", "scan wi... | scanning | scanning, security, skill, should, used, user, asks, perform, vulnerability, scan, networks, open |
 | `secrets-management` | Implement secure secrets management for CI/CD pipelines using Vault, AWS Secrets Manager, or native platform solutions. Use when handling sensitive credentia... | secrets | secrets, secure, ci, cd, pipelines, vault, aws, manager, native, platform, solutions, handling |
 | `security-auditor` | Expert security auditor specializing in DevSecOps, comprehensive cybersecurity, and compliance frameworks. Masters vulnerability assessment, threat modeling,... | security, auditor | security, auditor, specializing, devsecops, cybersecurity, compliance, frameworks, masters, vulnerability, assessment, threat, modeling |
+| `security-bluebook-builder` | Build security Blue Books for sensitive apps | security, bluebook, builder | security, bluebook, builder, blue, books, sensitive, apps |
 | `security-compliance-compliance-check` | You are a compliance expert specializing in regulatory requirements for software systems including GDPR, HIPAA, SOC2, PCI-DSS, and other industry standards. ... | security, compliance, check | security, compliance, check, specializing, regulatory, requirements, software, including, gdpr, hipaa, soc2, pci |
 | `security-requirement-extraction` | Derive security requirements from threat models and business context. Use when translating threats into actionable requirements, creating security user stori... | security, requirement, extraction | security, requirement, extraction, derive, requirements, threat, models, business, context, translating, threats, actionable |
 | `security-scanning-security-dependencies` | You are a security expert specializing in dependency vulnerability analysis, SBOM generation, and supply chain security. Scan project dependencies across eco... | security, scanning, dependencies | security, scanning, dependencies, specializing, dependency, vulnerability, analysis, sbom, generation, supply, chain, scan |
@@ -550,12 +621,14 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
 | `top-web-vulnerabilities` | This skill should be used when the user asks to "identify web application vulnerabilities", "explain common security flaws", "understand vulnerability catego... | top, web, vulnerabilities | top, web, vulnerabilities, 100, reference, skill, should, used, user, asks, identify, application |
 | `twilio-communications` | Build communication features with Twilio: SMS messaging, voice calls, WhatsApp Business API, and user verification (2FA). Covers the full spectrum from simpl... | twilio, communications | twilio, communications, communication, features, sms, messaging, voice, calls, whatsapp, business, api, user |
 | `ui-visual-validator` | Rigorous visual validation expert specializing in UI testing, design system compliance, and accessibility verification. Masters screenshot analysis, visual r... | ui, visual, validator | ui, visual, validator, rigorous, validation, specializing, testing, compliance, accessibility, verification, masters, screenshot |
+| `using-neon` | Guides and best practices for working with Neon Serverless Postgres. Covers getting started, local development with Neon, choosing a connection method, Neon ... | using, neon | using, neon, guides, working, serverless, postgres, covers, getting, started, local, development, choosing |
+| `varlock-claude-skill` | Secure environment variable management ensuring secrets are never exposed in Claude sessions, terminals, logs, or git commits | varlock, claude, skill | varlock, claude, skill, secure, environment, variable, ensuring, secrets, never, exposed, sessions, terminals |
 | `vulnerability-scanner` | Advanced vulnerability analysis principles. OWASP 2025, Supply Chain Security, attack surface mapping, risk prioritization. | vulnerability, scanner | vulnerability, scanner, analysis, principles, owasp, 2025, supply, chain, security, attack, surface, mapping |
 | `web-design-guidelines` | Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my si... | web, guidelines | web, guidelines, review, ui, code, interface, compliance, asked, my, check, accessibility, audit |
 | `wordpress-penetration-testing` | This skill should be used when the user asks to "pentest WordPress sites", "scan WordPress for vulnerabilities", "enumerate WordPress users, themes, or plugi... | wordpress, penetration | wordpress, penetration, testing, skill, should, used, user, asks, pentest, sites, scan, vulnerabilities |
 | `xss-html-injection` | This skill should be used when the user asks to "test for XSS vulnerabilities", "perform cross-site scripting attacks", "identify HTML injection flaws", "exp... | xss, html, injection | xss, html, injection, cross, site, scripting, testing, skill, should, used, user, asks |
 
-## testing (21)
+## testing (22)
 
 | Skill | Description | Tags | Triggers |
 | --- | --- | --- | --- |
@@ -567,6 +640,7 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
 | `pentest-commands` | This skill should be used when the user asks to "run pentest commands", "scan with nmap", "use metasploit exploits", "crack passwords with hydra or john", "s... | pentest, commands | pentest, commands, skill, should, used, user, asks, run, scan, nmap, metasploit, exploits |
 | `performance-testing-review-multi-agent-review` | Use when working with performance testing review multi agent review | performance, multi, agent | performance, multi, agent, testing, review, working |
 | `playwright-skill` | Complete browser automation with Playwright. Auto-detects dev servers, writes clean test scripts to /tmp. Test pages, fill forms, take screenshots, check res... | playwright, skill | playwright, skill, complete, browser, automation, auto, detects, dev, servers, writes, clean, test |
+| `pypict-skill` | Pairwise test generation | pypict, skill | pypict, skill, pairwise, test, generation |
 | `screen-reader-testing` | Test web applications with screen readers including VoiceOver, NVDA, and JAWS. Use when validating screen reader compatibility, debugging accessibility issue... | screen, reader | screen, reader, testing, test, web, applications, readers, including, voiceover, nvda, jaws, validating |
 | `startup-analyst` | Expert startup business analyst specializing in market sizing, financial modeling, competitive analysis, and strategic planning for early-stage companies. Us... | startup, analyst | startup, analyst, business, specializing, market, sizing, financial, modeling, competitive, analysis, strategic, planning |
 | `startup-metrics-framework` | This skill should be used when the user asks about "key startup metrics", "SaaS metrics", "CAC and LTV", "unit economics", "burn multiple", "rule of 40", "ma... | startup, metrics, framework | startup, metrics, framework, skill, should, used, user, asks, about, key, saas, cac |
@@ -581,7 +655,7 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
 | `unit-testing-test-generate` | Generate comprehensive, maintainable unit tests across languages with strong coverage and edge case focus. | unit, generate | unit, generate, testing, test, maintainable, tests, languages, strong, coverage, edge, case |
 | `web3-testing` | Test smart contracts comprehensively using Hardhat and Foundry with unit tests, integration tests, and mainnet forking. Use when testing Solidity contracts, ... | web3 | web3, testing, test, smart, contracts, comprehensively, hardhat, foundry, unit, tests, integration, mainnet |
 
-## workflow (17)
+## workflow (16)
 
 | Skill | Description | Tags | Triggers |
 | --- | --- | --- | --- |
@@ -598,7 +672,6 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
 | `git-pushing` | Stage, commit, and push git changes with conventional commit messages. Use when user wants to commit and push changes, mentions pushing to remote, or asks to... | git, pushing | git, pushing, stage, commit, push, changes, conventional, messages, user, wants, mentions, remote |
 | `kaizen` | Guide for continuous improvement, error proofing, and standardization. Use this skill when the user wants to improve code quality, refactor, or discuss proce... | kaizen | kaizen, continuous, improvement, error, proofing, standardization, skill, user, wants, improve, code, quality |
 | `mermaid-expert` | Create Mermaid diagrams for flowcharts, sequences, ERDs, and architectures. Masters syntax for all diagram types and styling. Use PROACTIVELY for visual docu... | mermaid | mermaid, diagrams, flowcharts, sequences, erds, architectures, masters, syntax, all, diagram, types, styling |
-| `pdf` | Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms. When Claude needs ... | pdf | pdf, manipulation, toolkit, extracting, text, tables, creating, new, pdfs, merging, splitting, documents |
 | `pdf-official` | Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms. When Claude needs ... | pdf, official | pdf, official, manipulation, toolkit, extracting, text, tables, creating, new, pdfs, merging, splitting |
 | `team-collaboration-issue` | You are a GitHub issue resolution expert specializing in systematic bug investigation, feature implementation, and collaborative development workflows. Your ... | team, collaboration, issue | team, collaboration, issue, github, resolution, specializing, systematic, bug, investigation, feature, collaborative, development |
 | `track-management` | Use this skill when creating, managing, or working with Conductor tracks - the logical work units for features, bugs, and refactors. Applies to spec.md, plan... | track | track, skill, creating, managing, working, conductor, tracks, logical, work, units, features, bugs |

CHANGELOG.md

@@ -7,8 +7,93 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [4.7.0] - 2026-02-03 - "Installer Fix & OpenCode Docs"
+
+> Critical installer fix for Windows and OpenCode documentation completion.
+
+### Fixed
+
+- **Installer**: Resolved `ReferenceError` for `tagArg` variable in `bin/install.js` ensuring correct execution on Windows/PowerShell (PR #53).
+
+### Documentation
+
+- **OpenCode**: Completed documentation for OpenCode integration in `README.md`.
+
 ---
 
+## [4.6.0] - 2026-02-01 - "SPDD & Radix UI Design System"
+
+> Agent workflow docs (SPDD) and Radix UI design system skill.
+
+### Added
+
+- **New Skill**: `radix-ui-design-system` – Build accessible design systems with Radix UI primitives (headless, theming, WCAG, examples).
+- **Docs**: `skills/SPDD/` – Research, spec, and implementation workflow docs (1-research.md, 2-spec.md, 3-implementation.md).
+
+### Registry
+
+- **Total Skills**: 626 (from 625). Catalog regenerated.
+
+---
+
+## [4.5.0] - 2026-01-31 - "Stitch UI Design"
+
+> Expert prompting guide for Google Stitch AI-powered UI design tool.
+
+### Added
+
+- **New Skill**: `stitch-ui-design` – Expert guide for creating effective prompts for Google Stitch AI UI design tool (Gemini 2.5 Flash). Covers prompt structure, specificity techniques, iteration strategies, design-to-code workflows, and 10+ examples for landing pages, mobile apps, and dashboards.
+
+### Changed
+
+- **Documentation**: Clarified in README.md and GETTING_STARTED.md that installation means cloning the full repo once; Starter Packs are curated lists to discover skills by role, not a different installation method (fixes [#44](https://github.com/sickn33/antigravity-awesome-skills/issues/44)).
+
+### Registry
+
+- **Total Skills**: 625 (from 624). Catalog regenerated.
+
+### Credits
+
+- [@ALEKGG1](https://github.com/ALEKGG1) – stitch-ui-design (PR #45)
+- [@CypherPoet](https://github.com/CypherPoet) – Documentation clarity (#44)
+
+---
+
+## [4.4.0] - 2026-01-30 - "fp-ts skills for TypeScript"
+
+> Three practical fp-ts skills for TypeScript functional programming.
+
+### Added
+
+- **New Skills** (from [whatiskadudoing/fp-ts-skills](https://github.com/whatiskadudoing/fp-ts-skills)):
+  - `fp-ts-pragmatic` – Pipe, Option, Either, TaskEither without academic jargon.
+  - `fp-ts-react` – Patterns for fp-ts with React 18/19 and Next.js 14/15 (state, forms, data fetching).
+  - `fp-ts-errors` – Type-safe error handling with Either and TaskEither.
+
+### Registry
+
+- **Total Skills**: 624 (from 621). Catalog regenerated.
+
+---
+
+## [4.3.0] - 2026-01-29 - "VoltAgent Integration & Context Engineering Suite"
+
+> 61 new skills from VoltAgent/awesome-agent-skills: official team skills and context engineering suite.
+
+### Added
+
+- **61 new skills** from [VoltAgent/awesome-agent-skills](https://github.com/VoltAgent/awesome-agent-skills):
+  - **Official (27)**: Sentry (commit, create-pr, find-bugs, iterate-pr), Trail of Bits (culture-index, fix-review, sharp-edges), Expo (expo-deployment, upgrading-expo), Hugging Face (hugging-face-cli, hugging-face-jobs), Vercel, Google Stitch (design-md), Neon (using-neon), n8n (n8n-code-python, n8n-mcp-tools-expert, n8n-node-configuration), SwiftUI, fal.ai (fal-audio, fal-generate, fal-image-edit, fal-platform, fal-upscale, fal-workflow), deep-research, imagen, readme.
+  - **Community (34)**: Context suite (context-fundamentals, context-degradation, context-compression, context-optimization, multi-agent-patterns, memory-systems, evaluation), frontend-slides, linear-claude-skill, skill-rails-upgrade, terraform-skill, tool-design, screenshots, automate-whatsapp, observe-whatsapp, aws-skills, ui-skills, vexor, pypict-skill, makepad-skills, threejs-skills, claude-scientific-skills, claude-win11-speckit-update-skill, security-bluebook-builder, claude-ally-health, clarity-gate, beautiful-prose, claude-speed-reader, skill-seekers, varlock-claude-skill, superpowers-lab, nanobanana-ppt-skills, x-article-publisher-skill, ffuf-claude-skill.
+
+### Registry
+
+- **Total Skills**: 614 (from 553). Catalog and SOURCES.md updated.
+
+### Credits
+
+- VoltAgent/awesome-agent-skills and official teams (Sentry, Trail of Bits, Expo, Hugging Face, Vercel Labs, Google Labs, Neon, fal.ai).
+
 ---
 
 ## [4.0.0] - 2026-01-28 - "The Enterprise Era"
@@ -120,7 +205,7 @@ The following skills are now correctly indexed and visible in the registry:
 - **Documentation**:
   - `docs/EXAMPLES.md`: Cookbook with 3 real-world scenarios.
   - `docs/SOURCES.md`: Legal ledger for attributions and licenses.
-  - `RELEASE_NOTES.md`: Generated release announcement (archived).
+  - Release announcements are documented in this CHANGELOG.
 
 ### Changed
 

CONTRIBUTING.md

@@ -48,6 +48,23 @@ You don't need to be an expert! Here are ways anyone can help:
 
 ---
 
+## Local development setup
+
+To run validation, index generation, and README updates locally:
+
+1. **Node.js** (for catalog and installer): `npm ci`
+2. **Python 3** (for validate, index, readme scripts): install dependencies with
+   ```bash
+   pip install -r requirements.txt
+   ```
+   Then you can run `npm run chain` (validate → index → readme) and `npm run catalog`.
+
+**Validation:** The canonical validator is **Python** (`scripts/validate_skills.py`). Use `npm run validate` (or `npm run validate:strict` for CI-style checks). The JavaScript validator (`scripts/validate-skills.js`) is legacy/optional and uses a different schema; CI and PR checks rely on the Python validator only.
+
+**npm audit:** CI runs `npm audit --audit-level=high`. To fix issues locally: run `npm audit`, then `npm update` or `npm audit fix` as appropriate; for breaking changes, update dependencies manually and run tests.
+
+---
+
 ## How to Create a New Skill
 
 ### Step-by-Step Guide

README.md

@@ -1,6 +1,6 @@
-# 🌌 Antigravity Awesome Skills: 560+ Agentic Skills for Claude Code, Gemini CLI, Cursor, Copilot & More
+# 🌌 Antigravity Awesome Skills: 626+ Agentic Skills for Claude Code, Gemini CLI, Cursor, Copilot & More
 
-> **The Ultimate Collection of 560+ Universal Agentic Skills for AI Coding Assistants — Claude Code, Gemini CLI, Codex CLI, Antigravity IDE, GitHub Copilot, Cursor, OpenCode**
+> **The Ultimate Collection of 626+ Universal Agentic Skills for AI Coding Assistants — Claude Code, Gemini CLI, Codex CLI, Antigravity IDE, GitHub Copilot, Cursor, OpenCode, AdaL**
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Claude Code](https://img.shields.io/badge/Claude%20Code-Anthropic-purple)](https://claude.ai)
@@ -10,8 +10,9 @@
 [![Copilot](https://img.shields.io/badge/GitHub%20Copilot-VSCode-lightblue)](https://github.com/features/copilot)
 [![OpenCode](https://img.shields.io/badge/OpenCode-CLI-gray)](https://github.com/opencode-ai/opencode)
 [![Antigravity](https://img.shields.io/badge/Antigravity-DeepMind-red)](https://github.com/sickn33/antigravity-awesome-skills)
+[![AdaL](https://img.shields.io/badge/AdaL-Self--evolving%20Agent-pink)](https://github.com/HumanSignal/Adala)
 
-**Antigravity Awesome Skills** is a curated, battle-tested library of **560 high-performance agentic skills** designed to work seamlessly across all major AI coding assistants:
+**Antigravity Awesome Skills** is a curated, battle-tested library of **626 high-performance agentic skills** designed to work seamlessly across all major AI coding assistants:
 
 - 🟣 **Claude Code** (Anthropic CLI)
 - 🔵 **Gemini CLI** (Google DeepMind)
@@ -20,6 +21,7 @@
 - 🩵 **GitHub Copilot** (VSCode Extension)
 - 🟠 **Cursor** (AI-native IDE)
 - ⚪ **OpenCode** (Open-source CLI)
+- 🌸 **AdaL** (Self-evolving AI Agent)
 
 This repository provides essential skills to transform your AI assistant into a **full-stack digital agency**, including official capabilities from **Anthropic**, **OpenAI**, **Google**, **Supabase**, and **Vercel Labs**.
 
@@ -29,7 +31,7 @@ This repository provides essential skills to transform your AI assistant into a
 - [🔌 Compatibility & Invocation](#compatibility--invocation)
 - [📦 Features & Categories](#features--categories)
 - [🎁 Curated Collections (Bundles)](#curated-collections)
-- [📚 Browse 560+ Skills](#browse-560-skills)
+- [📚 Browse 626+ Skills](#browse-626-skills)
 - [🛠️ Installation](#installation)
 - [🤝 How to Contribute](#how-to-contribute)
 - [👥 Contributors & Credits](#credits--sources)
@@ -52,9 +54,10 @@ AI Agents (like Claude Code, Cursor, or Gemini) are smart, but they lack **speci
 
 ### 2. ⚡️ Quick Start (The "Bundle" Way)
 
-Don't install 560+ skills manually. Use our **Starter Packs**:
+Install once (clone or npx); then use our **Starter Packs** in [docs/BUNDLES.md](docs/BUNDLES.md) to see which skills fit your role. You get the full repo; Starter Packs are curated lists, not a separate install.
 
 1.  **Install** (pick one):
+
     ```bash
     # Easiest: npx installer (clones to ~/.agent/skills by default)
     npx antigravity-awesome-skills
@@ -62,6 +65,7 @@ Don't install 560+ skills manually. Use our **Starter Packs**:
     # Or clone manually
     git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
     ```
+
 2.  **Pick your persona** (See [docs/BUNDLES.md](docs/BUNDLES.md)):
     - **Web Dev?** use the `Web Wizard` pack.
     - **Hacker?** use the `Security Engineer` pack.
@@ -82,13 +86,16 @@ Once installed, just ask your agent naturally:
 
 These skills follow the universal **SKILL.md** format and work with any AI coding assistant that supports agentic skills.
 
-| Tool            | Type | Invocation Example                | Path              |
-| :-------------- | :--- | :-------------------------------- | :---------------- |
-| **Claude Code** | CLI  | `>> /skill-name help me...`       | `.claude/skills/` |
-| **Gemini CLI**  | CLI  | `(User Prompt) Use skill-name...` | `.gemini/skills/` |
-| **Antigravity** | IDE  | `(Agent Mode) Use skill...`       | `.agent/skills/`  |
-| **Cursor**      | IDE  | `@skill-name (in Chat)`           | `.cursor/skills/` |
-| **Copilot**     | Ext  | `(Paste content manually)`        | N/A               |
+| Tool            | Type  | Invocation Example                | Path              |
+| :-------------- | :---- | :-------------------------------- | :---------------- |
+| **Claude Code** | CLI   | `>> /skill-name help me...`       | `.claude/skills/` |
+| **Gemini CLI**  | CLI   | `(User Prompt) Use skill-name...` | `.gemini/skills/` |
+| **Codex CLI**   | CLI   | `(User Prompt) Use skill-name...` | `.codex/skills/`  |
+| **Antigravity** | IDE   | `(Agent Mode) Use skill...`       | `.agent/skills/`  |
+| **Cursor**      | IDE   | `@skill-name (in Chat)`           | `.cursor/skills/` |
+| **Copilot**     | Ext   | `(Paste content manually)`        | N/A               |
+| **OpenCode**    | CLI   | `opencode run @skill-name`        | `.agent/skills/`  |
+| **AdaL**        | Agent | `(Agent Mode) Use skill...`       | `.agent/skills/`  |
 
 > [!TIP]
 > **Universal Path**: We recommend cloning to `.agent/skills/`. Most modern tools (Antigravity, recent CLIs) look here by default.
@@ -100,7 +107,7 @@ These skills follow the universal **SKILL.md** format and work with any AI codin
 
 ---
 
-Whether you are using **Gemini CLI**, **Claude Code**, **Codex CLI**, **Cursor**, **GitHub Copilot**, **Antigravity**, or **OpenCode**, these skills are designed to drop right in and supercharge your AI agent.
+Whether you are using **Gemini CLI**, **Claude Code**, **Codex CLI**, **Cursor**, **GitHub Copilot**, **Antigravity**, **OpenCode**, or **AdaL**, these skills are designed to drop right in and supercharge your AI agent.
 
 This repository aggregates the best capabilities from across the open-source community, transforming your AI assistant into a full-stack digital agency capable of Engineering, Design, Security, Marketing, and Autonomous Operations.
 
@@ -108,23 +115,23 @@ This repository aggregates the best capabilities from across the open-source com
 
 The repository is organized into specialized domains to transform your AI into an expert across the entire software development lifecycle:
 
-| Category | Focus | Example skills |
-| :--- | :--- | :--- |
-| Architecture (52) | System design, ADRs, C4, and scalable patterns | `architecture`, `c4-context`, `senior-architect` |
-| Business (35) | Growth, pricing, CRO, SEO, and go-to-market | `copywriting`, `pricing-strategy`, `seo-audit` |
-| Data & AI (81) | LLM apps, RAG, agents, observability, analytics | `rag-engineer`, `prompt-engineer`, `langgraph` |
-| Development (72) | Language mastery, framework patterns, code quality | `typescript-expert`, `python-patterns`, `react-patterns` |
-| General (95) | Planning, docs, product ops, writing, guidelines | `brainstorming`, `doc-coauthoring`, `writing-plans` |
-| Infrastructure (72) | DevOps, cloud, serverless, deployment, CI/CD | `docker-expert`, `aws-serverless`, `vercel-deployment` |
-| Security (107) | AppSec, pentesting, vuln analysis, compliance | `api-security-best-practices`, `sql-injection-testing`, `vulnerability-scanner` |
-| Testing (21) | TDD, test design, fixes, QA workflows | `test-driven-development`, `testing-patterns`, `test-fixing` |
-| Workflow (17) | Automation, orchestration, jobs, agents | `workflow-automation`, `inngest`, `trigger-dev` |
+| Category            | Focus                                              | Example skills                                                                  |
+| :------------------ | :------------------------------------------------- | :------------------------------------------------------------------------------ |
+| Architecture (52)   | System design, ADRs, C4, and scalable patterns     | `architecture`, `c4-context`, `senior-architect`                                |
+| Business (35)       | Growth, pricing, CRO, SEO, and go-to-market        | `copywriting`, `pricing-strategy`, `seo-audit`                                  |
+| Data & AI (81)      | LLM apps, RAG, agents, observability, analytics    | `rag-engineer`, `prompt-engineer`, `langgraph`                                  |
+| Development (72)    | Language mastery, framework patterns, code quality | `typescript-expert`, `python-patterns`, `react-patterns`                        |
+| General (95)        | Planning, docs, product ops, writing, guidelines   | `brainstorming`, `doc-coauthoring`, `writing-plans`                             |
+| Infrastructure (72) | DevOps, cloud, serverless, deployment, CI/CD       | `docker-expert`, `aws-serverless`, `vercel-deployment`                          |
+| Security (107)      | AppSec, pentesting, vuln analysis, compliance      | `api-security-best-practices`, `sql-injection-testing`, `vulnerability-scanner` |
+| Testing (21)        | TDD, test design, fixes, QA workflows              | `test-driven-development`, `testing-patterns`, `test-fixing`                    |
+| Workflow (17)       | Automation, orchestration, jobs, agents            | `workflow-automation`, `inngest`, `trigger-dev`                                 |
 
 ## Curated Collections
 
 [Check out our Starter Packs in docs/BUNDLES.md](docs/BUNDLES.md) to find the perfect toolkit for your role.
 
-## Browse 560+ Skills
+## Browse 626+ Skills
 
 We have moved the full skill registry to a dedicated catalog to keep this README clean.
 
@@ -132,7 +139,7 @@ We have moved the full skill registry to a dedicated catalog to keep this README
 
 ## Installation
 
-To use these skills with **Claude Code**, **Gemini CLI**, **Codex CLI**, **Cursor**, **Antigravity**, or **OpenCode**:
+To use these skills with **Claude Code**, **Gemini CLI**, **Codex CLI**, **Cursor**, **Antigravity**, **OpenCode**, or **AdaL**:
 
 ### Option A: npx (recommended)
 
@@ -149,12 +156,20 @@ npx antigravity-awesome-skills --claude
 # Gemini CLI
 npx antigravity-awesome-skills --gemini
 
+# Codex CLI
+npx antigravity-awesome-skills --codex
+
+# OpenCode (Universal)
+npx antigravity-awesome-skills
+
 # Custom path
 npx antigravity-awesome-skills --path ./my-skills
 ```
 
 Run `npx antigravity-awesome-skills --help` for all options. If the directory already exists, the installer runs `git pull` to update.
 
+> **If you see a 404 error:** the package may not be published to npm yet. Use: `npx github:sickn33/antigravity-awesome-skills`
+
 ### Option B: git clone
 
 ```bash
@@ -167,8 +182,14 @@ git clone https://github.com/sickn33/antigravity-awesome-skills.git .claude/skil
 # Gemini CLI specific
 git clone https://github.com/sickn33/antigravity-awesome-skills.git .gemini/skills
 
+# Codex CLI specific
+git clone https://github.com/sickn33/antigravity-awesome-skills.git .codex/skills
+
 # Cursor specific
 git clone https://github.com/sickn33/antigravity-awesome-skills.git .cursor/skills
+
+# OpenCode specific (Universal path)
+git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
 ```
 
 ---
@@ -223,11 +244,13 @@ This collection would not be possible without the incredible work of the Claude
 - **[zebbern/claude-code-guide](https://github.com/zebbern/claude-code-guide)**: Comprehensive Security suite & Guide (Source for ~60 new skills).
 - **[alirezarezvani/claude-skills](https://github.com/alirezarezvani/claude-skills)**: Senior Engineering and PM toolkit.
 - **[karanb192/awesome-claude-skills](https://github.com/karanb192/awesome-claude-skills)**: A massive list of verified skills for Claude Code.
+- **[VoltAgent/awesome-agent-skills](https://github.com/VoltAgent/awesome-agent-skills)**: Curated collection of 61 high-quality skills including official team skills from Sentry, Trail of Bits, Expo, Hugging Face, and comprehensive context engineering suite (v4.3.0 integration).
 - **[zircote/.claude](https://github.com/zircote/.claude)**: Shopify development skill reference.
 - **[vibeforge1111/vibeship-spawner-skills](https://github.com/vibeforge1111/vibeship-spawner-skills)**: AI Agents, Integrations, Maker Tools (57 skills, Apache 2.0).
 - **[coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills)**: Marketing skills for CRO, copywriting, SEO, paid ads, and growth (23 skills, MIT).
 - **[vudovn/antigravity-kit](https://github.com/vudovn/antigravity-kit)**: AI Agent templates with Skills, Agents, and Workflows (33 skills, MIT).
 - **[affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code)**: Complete Claude Code configuration collection from Anthropic hackathon winner - skills only (8 skills, MIT).
+- **[whatiskadudoing/fp-ts-skills](https://github.com/whatiskadudoing/fp-ts-skills)**: Practical fp-ts skills for TypeScript – fp-ts-pragmatic, fp-ts-react, fp-ts-errors (v4.4.0).
 - **[webzler/agentMemory](https://github.com/webzler/agentMemory)**: Source for the agent-memory-mcp skill.
 - **[sstklen/claude-api-cost-optimization](https://github.com/sstklen/claude-api-cost-optimization)**: Save 50-90% on Claude API costs with smart optimization strategies (MIT).
 
@@ -265,32 +288,47 @@ ai-developer-tools, ai-pair-programming, vibe-coding, skill, skills, SKILL.md, r
 
 ## Repo Contributors
 
+<a href="https://github.com/sickn33/antigravity-awesome-skills/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=sickn33/antigravity-awesome-skills" />
+</a>
+
+Made with [contrib.rocks](https://contrib.rocks).
+
 We officially thank the following contributors for their help in making this repository awesome!
 
-- [mvanhorn](https://github.com/mvanhorn)
-- [rookie-ricardo](https://github.com/rookie-ricardo)
-- [sck_0](https://github.com/sck_0)
-- [Munir Abbasi](https://github.com/munirabbasi)
-- [Mohammad Faiz](https://github.com/mohdfaiz2k9)
-- [Ianj332](https://github.com/Ianj332)
+- [sck_0](https://github.com/sck000)
+- [Munir Abbasi](https://github.com/munir-abbasi)
 - [sickn33](https://github.com/sickn33)
+- [Mohammad Faiz](https://github.com/Mohammad-Faiz-Cloud-Engineer)
+- [Đỗ Khắc Gia Khoa](https://github.com/Dokhacgiakhoa)
+- [Ianj332](https://github.com/IanJ332)
 - [GuppyTheCat](https://github.com/GuppyTheCat)
 - [Tiger-Foxx](https://github.com/Tiger-Foxx)
 - [arathiesh](https://github.com/arathiesh)
 - [1bcMax](https://github.com/1bcMax)
+- [ALEKGG1](https://github.com/ALEKGG1)
 - [Ahmed Rehan](https://github.com/ar27111994)
 - [BenedictKing](https://github.com/BenedictKing)
+- [whatiskadudoing](https://github.com/whatiskadudoing)
 - [Nguyen Huu Loc](https://github.com/LocNguyenSGU)
 - [Owen Wu](https://github.com/yubing744)
 - [SuperJMN](https://github.com/SuperJMN)
+- [Truong Nguyen](https://github.com/truongnmt)
 - [Viktor Ferenczi](https://github.com/viktor-ferenczi)
-- [Đỗ Khắc Gia Khoa](https://github.com/Dokhacgiakhoa)
+- [c1c3ru](https://github.com/c1c3ru)
+- [ckdwns9121](https://github.com/ckdwns9121)
 - [junited31](https://github.com/junited31)
-- [krisnasantosa15](https://github.com/krisnasantosa15)
-- [raeef1001](https://github.com/raeef1001)
+- [liyin2015](https://github.com/liyin2015)
+- [krisnasantosa15](https://github.com/KrisnaSantosa15)
+- [sstklen](https://github.com/sstklen)
 - [taksrules](https://github.com/taksrules)
 - [zebbern](https://github.com/zebbern)
 - [vuth-dogo](https://github.com/vuth-dogo)
+- [mvanhorn](https://github.com/mvanhorn)
+- [rookie-ricardo](https://github.com/rookie-ricardo)
+- [evandro-miguel](https://github.com/evandro-miguel)
+- [raeef1001](https://github.com/raeef1001)
+- [devchangjun](https://github.com/devchangjun)
 
 ## Star History
 

RELEASE_NOTES.md

@@ -1,39 +0,0 @@
-# Release v4.2.0: Writing Skills Gold Standard Architecture
-
-> **Complete refactor of the writing-skills skill to Cloudflare Gold Standard architecture for modular, discoverable skill creation excellence**
-
-This release modernizes the core skill-creation skill with a modular architecture inspired by Cloudflare's documentation patterns. The refactored writing-skills now offers progressive disclosure, decision trees, and dedicated reference modules for CSO, anti-rationalization, testing, and tier-based skill structures.
-
-## 🚀 Improvements
-
-### 📝 [writing-skills](skills/writing-skills/) – Gold Standard Refactor
-
-**Modular architecture for skill creation excellence**
-
-The writing-skills skill has been completely refactored to align with Cloudflare Gold Standard principles. Content is now organized into focused, navigable modules instead of a monolithic document.
-
-- **Quick Decision Tree**: Start with "Create new" vs "Improve existing" vs "Verify compliance" to find the right path
-- **Component Index**: Direct links to CSO (discovery), Standards (metadata), Anti-Rationalization (rules that stick), and Testing (TDD for skills)
-- **Tier Architecture**: Tier 1 (simple, single file), Tier 2 (expanded, references/), Tier 3 (platform, multi-product)
-- **Templates**: Technique, Reference, Discipline, and Pattern skill templates with clear structure
-- **Gotchas & Examples**: New gotchas.md and examples.md for common pitfalls and copy-pasteable patterns
-- **References Module**: Dedicated READMEs for anti-rationalization, CSO, standards, templates, testing, and tier guides
-
-> **Try it:** `"I want to create a new skill"` or `"How do I fix a skill that agents ignore?"`
-
----
-
-## 📦 Registry Update
-
-- **Catalog**: Regenerated for 553 skills
-- **Structure**: writing-skills now uses `references/` subdirectory with 12+ supporting documents
-
-## 👥 Credits
-
-A huge shoutout to our community contributors:
-
-- **@evandro-miguel** for writing-skills Gold Standard refactor (PR #41)
-
----
-
-_Upgrade now: `git pull origin main` to fetch the latest skills._

bin/install.js

@@ -16,18 +16,23 @@ function resolveDir(p) {
 function parseArgs() {
   const a = process.argv.slice(2);
   let pathArg = null;
-  let cursor = false, claude = false, gemini = false;
+  let versionArg = null;
+  let tagArg = null;
+  let cursor = false, claude = false, gemini = false, codex = false;
 
   for (let i = 0; i < a.length; i++) {
     if (a[i] === '--help' || a[i] === '-h') return { help: true };
     if (a[i] === '--path' && a[i + 1]) { pathArg = a[++i]; continue; }
+    if (a[i] === '--version' && a[i + 1]) { versionArg = a[++i]; continue; }
+    if (a[i] === '--tag' && a[i + 1]) { tagArg = a[++i]; continue; }
     if (a[i] === '--cursor') { cursor = true; continue; }
     if (a[i] === '--claude') { claude = true; continue; }
     if (a[i] === '--gemini') { gemini = true; continue; }
+    if (a[i] === '--codex') { codex = true; continue; }
     if (a[i] === 'install') continue;
   }
 
-  return { pathArg, cursor, claude, gemini };
+  return { pathArg, versionArg, tagArg, cursor, claude, gemini, codex };
 }
 
 function defaultDir(opts) {
@@ -35,6 +40,11 @@ function defaultDir(opts) {
   if (opts.cursor) return path.join(HOME, '.cursor', 'skills');
   if (opts.claude) return path.join(HOME, '.claude', 'skills');
   if (opts.gemini) return path.join(HOME, '.gemini', 'skills');
+  if (opts.codex) {
+    const codexHome = process.env.CODEX_HOME;
+    if (codexHome) return path.join(codexHome, 'skills');
+    return path.join(HOME, '.codex', 'skills');
+  }
   return path.join(HOME, '.agent', 'skills');
 }
 
@@ -50,11 +60,15 @@ Options:
   --cursor    Install to ~/.cursor/skills (Cursor)
   --claude    Install to ~/.claude/skills (Claude Code)
   --gemini    Install to ~/.gemini/skills (Gemini CLI)
+  --codex     Install to ~/.codex/skills (Codex CLI)
   --path <dir> Install to <dir> (default: ~/.agent/skills)
+  --version <ver>  After clone, checkout tag v<ver> (e.g. 4.6.0 -> v4.6.0)
+  --tag <tag>      After clone, checkout this tag (e.g. v4.6.0)
 
 Examples:
   npx antigravity-awesome-skills
   npx antigravity-awesome-skills --cursor
+  npx antigravity-awesome-skills --version 4.6.0
   npx antigravity-awesome-skills --path ./my-skills
 `);
 }
@@ -66,6 +80,8 @@ function run(cmd, args, opts = {}) {
 
 function main() {
   const opts = parseArgs();
+  const { tagArg, versionArg } = opts;
+  
   if (opts.help) {
     printHelp();
     return;
@@ -106,6 +122,13 @@ function main() {
     run('git', ['clone', REPO, target]);
   }
 
+  const ref = tagArg || (versionArg ? (versionArg.startsWith('v') ? versionArg : `v${versionArg}`) : null);
+  if (ref) {
+    console.log(`Checking out ${ref}…`);
+    process.chdir(target);
+    run('git', ['checkout', ref]);
+  }
+
   console.log(`\nInstalled to ${target}`);
   console.log('Pick a bundle in docs/BUNDLES.md and use @skill-name in your AI assistant.');
 }

data/aliases.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-01-30T07:28:45.635Z",
+  "generatedAt": "2026-02-03T09:20:12.539Z",
   "aliases": {
     "accessibility-compliance-audit": "accessibility-compliance-accessibility-audit",
     "active directory attacks": "active-directory-attacks",
@@ -7,6 +7,7 @@
     "agent-orchestration-optimize": "agent-orchestration-multi-agent-optimize",
     "api fuzzing for bug bounty": "api-fuzzing-bug-bounty",
     "api-testing-mock": "api-testing-observability-api-mock",
+    "templates": "app-builder/templates",
     "application-performance-optimization": "application-performance-performance-optimization",
     "aws penetration testing": "aws-penetration-testing",
     "backend-development-feature": "backend-development-feature-development",
@@ -24,6 +25,7 @@
     "cicd-automation-automate": "cicd-automation-workflow-automate",
     "claude code guide": "claude-code-guide",
     "d3-viz": "claude-d3js-skill",
+    "claude-win11-skill": "claude-win11-speckit-update-skill",
     "cloud penetration testing": "cloud-penetration-testing",
     "code-documentation-explain": "code-documentation-code-explain",
     "code-documentation-generate": "code-documentation-doc-generate",
@@ -44,6 +46,7 @@
     "deployment-validation-validate": "deployment-validation-config-validate",
     "distributed-debugging-trace": "distributed-debugging-debug-trace",
     "documentation-generation-generate": "documentation-generation-doc-generate",
+    "docx": "docx-official",
     "error-debugging-analysis": "error-debugging-error-analysis",
     "error-debugging-review": "error-debugging-multi-agent-review",
     "error-diagnostics-analysis": "error-diagnostics-error-analysis",
@@ -58,6 +61,16 @@
     "frontend-mobile-scaffold": "frontend-mobile-development-component-scaffold",
     "frontend-mobile-scan": "frontend-mobile-security-xss-scan",
     "full-stack-feature": "full-stack-orchestration-full-stack-feature",
+    "2d-games": "game-development/2d-games",
+    "3d-games": "game-development/3d-games",
+    "game-art": "game-development/game-art",
+    "game-audio": "game-development/game-audio",
+    "game-design": "game-development/game-design",
+    "mobile-games": "game-development/mobile-games",
+    "multiplayer": "game-development/multiplayer",
+    "pc-games": "game-development/pc-games",
+    "vr-ar": "game-development/vr-ar",
+    "web-games": "game-development/web-games",
     "git-pr-workflow": "git-pr-workflows-git-workflow",
     "html injection testing": "html-injection-testing",
     "idor vulnerability testing": "idor-testing",
@@ -78,11 +91,13 @@
     "observability-monitoring-setup": "observability-monitoring-monitor-setup",
     "observability-monitoring-implement": "observability-monitoring-slo-implement",
     "obsidian-clipper-creator": "obsidian-clipper-template-creator",
+    "pdf": "pdf-official",
     "pentest checklist": "pentest-checklist",
     "pentest commands": "pentest-commands",
     "performance-testing-ai": "performance-testing-review-ai-review",
     "performance-testing-agent": "performance-testing-review-multi-agent-review",
     "supabase-postgres-best-practices": "postgres-best-practices",
+    "pptx": "pptx-official",
     "privilege escalation methods": "privilege-escalation-methods",
     "python-development-scaffold": "python-development-python-scaffold",
     "vercel-react-best-practices": "react-best-practices",
@@ -106,6 +121,7 @@
     "windows privilege escalation": "windows-privilege-escalation",
     "wireshark network traffic analysis": "wireshark-analysis",
     "wordpress penetration testing": "wordpress-penetration-testing",
+    "xlsx": "xlsx-official",
     "cross-site scripting and html injection testing": "xss-html-injection"
   }
 }

data/bundles.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-01-30T07:28:45.635Z",
+  "generatedAt": "2026-02-03T09:20:12.539Z",
   "bundles": {
     "core-dev": {
       "description": "Core development skills across languages, frameworks, and backend/frontend fundamentals.",
@@ -45,16 +45,22 @@
         "firebase",
         "firecrawl-scraper",
         "flutter-expert",
+        "fp-ts-errors",
+        "fp-ts-pragmatic",
+        "fp-ts-react",
         "frontend-design",
         "frontend-dev-guidelines",
         "frontend-developer",
         "frontend-mobile-development-component-scaffold",
         "frontend-mobile-security-xss-scan",
         "frontend-security-coder",
+        "frontend-slides",
+        "game-development/mobile-games",
         "go-concurrency-patterns",
         "golang-pro",
         "graphql",
         "hubspot-integration",
+        "hugging-face-jobs",
         "ios-developer",
         "java-pro",
         "javascript-mastery",
@@ -63,6 +69,7 @@
         "javascript-typescript-typescript-scaffold",
         "langgraph",
         "launch-strategy",
+        "makepad-skills",
         "mcp-builder",
         "memory-safety-patterns",
         "mobile-design",
@@ -71,11 +78,14 @@
         "modern-javascript-patterns",
         "moodle-external-api-development",
         "multi-platform-apps-multi-platform",
+        "n8n-code-python",
+        "n8n-node-configuration",
         "nextjs-app-router-patterns",
         "nextjs-best-practices",
         "nextjs-supabase-auth",
         "nodejs-backend-patterns",
         "nodejs-best-practices",
+        "observe-whatsapp",
         "openapi-spec-generation",
         "php-pro",
         "plaid-fintech",
@@ -103,6 +113,8 @@
         "shopify-apps",
         "shopify-development",
         "slack-bot-builder",
+        "stitch-ui-design",
+        "swiftui-expert-skill",
         "systems-programming-rust-project",
         "tavily-web",
         "telegram-bot-builder",
@@ -116,6 +128,7 @@
         "typescript-expert",
         "typescript-pro",
         "ui-ux-pro-max",
+        "using-neon",
         "uv-package-manager",
         "viral-generator-builder",
         "voice-agents",
@@ -152,6 +165,7 @@
         "design-orchestration",
         "docker-expert",
         "ethical-hacking-methodology",
+        "find-bugs",
         "firebase",
         "firmware-analyst",
         "form-cro",
@@ -160,6 +174,7 @@
         "frontend-security-coder",
         "gdpr-data-handling",
         "graphql-architect",
+        "hugging-face-jobs",
         "hybrid-cloud-architect",
         "idor-testing",
         "k8s-manifest-generator",
@@ -190,6 +205,7 @@
         "scanning-tools",
         "secrets-management",
         "security-auditor",
+        "security-bluebook-builder",
         "security-compliance-compliance-check",
         "security-requirement-extraction",
         "security-scanning-security-dependencies",
@@ -207,6 +223,8 @@
         "top-web-vulnerabilities",
         "twilio-communications",
         "ui-visual-validator",
+        "using-neon",
+        "varlock-claude-skill",
         "vulnerability-scanner",
         "web-design-guidelines",
         "wordpress-penetration-testing",
@@ -263,9 +281,11 @@
         "database-optimizer",
         "dbt-transformation-patterns",
         "firebase",
+        "fp-ts-react",
         "frontend-dev-guidelines",
         "gdpr-data-handling",
         "graphql",
+        "hugging-face-jobs",
         "hybrid-cloud-networking",
         "idor-testing",
         "ios-developer",
@@ -298,8 +318,8 @@
         "sql-pro",
         "sqlmap-database-pentesting",
         "unity-ecs-patterns",
+        "using-neon",
         "vector-database-engineer",
-        "xlsx",
         "xlsx-official"
       ]
     },
@@ -335,7 +355,9 @@
         "error-debugging-error-trace",
         "error-diagnostics-error-analysis",
         "error-diagnostics-error-trace",
+        "expo-deployment",
         "flutter-expert",
+        "game-development/game-art",
         "git-pr-workflows-git-workflow",
         "gitlab-ci-patterns",
         "gitops-workflow",
@@ -372,6 +394,7 @@
         "temporal-python-pro",
         "terraform-specialist",
         "unity-developer",
+        "vercel-deploy-claimable",
         "vercel-deployment",
         "voice-agents"
       ]

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "antigravity-awesome-skills",
-  "version": "4.2.0",
+  "version": "4.6.0",
   "dependencies": {
     "yaml": "^2.8.2"
   }

docs/FAQ.md

@@ -11,7 +11,7 @@
 Skills are specialized instruction files that teach AI assistants how to handle specific tasks. Think of them as expert knowledge modules that your AI can load on-demand.
 **Simple analogy:** Just like you might consult different experts (a lawyer, a doctor, a mechanic), these skills let your AI become an expert in different areas when you need them.
 
-### Do I need to install all 560+ skills?
+### Do I need to install all 626+ skills?
 
 **No!** When you clone the repository, all skills are available, but your AI only loads them when you explicitly invoke them with `@skill-name`.
 It's like having a library - all books are there, but you only read the ones you need.
@@ -62,7 +62,11 @@ _Always check the Risk label and review the code._
 
 ### Where should I install the skills?
 
-The universal path that works with most tools is `.agent/skills/`:
+The universal path that works with most tools is `.agent/skills/`.
+
+**Using npx:** `npx antigravity-awesome-skills` (or `npx github:sickn33/antigravity-awesome-skills` if you get a 404).
+
+**Using git clone:**
 
 ```bash
 git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
@@ -72,6 +76,7 @@ git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skill
 
 - Claude Code: `.claude/skills/`
 - Gemini CLI: `.gemini/skills/`
+- Codex CLI: `.codex/skills/`
 - Cursor: `.cursor/skills/` or project root
 
 ### Does this work with Windows?

docs/GETTING_STARTED.md

@@ -15,9 +15,11 @@ AI Agents (like **Claude Code**, **Gemini**, **Cursor**) are smart, but they lac
 
 ## ⚡️ Quick Start: The "Starter Packs"
 
-Don't panic about the 560+ skills. You don't need them all at once.
+Don't panic about the 626+ skills. You don't need them all at once.
 We have curated **Starter Packs** to get you running immediately.
 
+You **install the full repo once** (npx or clone); Starter Packs are curated lists to help you **pick which skills to use** by role (e.g. Web Wizard, Hacker Pack)—they are not a different way to install.
+
 ### 1. Install the Repo
 
 **Option A — npx (easiest):**
@@ -26,7 +28,9 @@ We have curated **Starter Packs** to get you running immediately.
 npx antigravity-awesome-skills
 ```
 
-This clones to `~/.agent/skills` by default. Use `--cursor`, `--claude`, or `--gemini` to install for a specific tool, or `--path <dir>` for a custom location. Run `npx antigravity-awesome-skills --help` for details.
+This clones to `~/.agent/skills` by default. Use `--cursor`, `--claude`, `--gemini`, or `--codex` to install for a specific tool, or `--path <dir>` for a custom location. Run `npx antigravity-awesome-skills --help` for details.
+
+If you see a 404 error, use: `npx github:sickn33/antigravity-awesome-skills`
 
 **Option B — git clone:**
 
@@ -78,6 +82,7 @@ Once installed, just talk to your AI naturally.
 | :-------------- | :-------------- | :---------------- |
 | **Claude Code** | ✅ Full Support | `.claude/skills/` |
 | **Gemini CLI**  | ✅ Full Support | `.gemini/skills/` |
+| **Codex CLI**   | ✅ Full Support | `.codex/skills/`  |
 | **Antigravity** | ✅ Native       | `.agent/skills/`  |
 | **Cursor**      | ✅ Native       | `.cursor/skills/` |
 | **Copilot**     | ⚠️ Text Only    | Manual copy-paste |
@@ -98,8 +103,8 @@ _Check the [Skill Catalog](../CATALOG.md) for the full list._
 
 ## ❓ FAQ
 
-**Q: Do I need to install all 560 skills?**
-A: You clone the whole repo, but your AI only _reads_ the ones you ask for (or that are relevant). It's lightweight!
+**Q: Do I need to install all 626 skills?**
+A: You clone the whole repo once; your AI only _reads_ the skills you invoke (or that are relevant), so it stays lightweight. **Starter Packs** in [BUNDLES.md](BUNDLES.md) are curated lists to help you discover the right skills for your role—they don't change how you install.
 
 **Q: Can I make my own skills?**
 A: Yes! Use the **@skill-creator** skill to build your own.

docs/QUALITY_BAR.md

@@ -21,6 +21,7 @@ The skill MUST have a section explicitly stating when to trigger it.
 
 - **Good**: "Use when the user asks to debug a React component."
 - **Bad**: "This skill helps you with code."
+Accepted headings: `## When to Use`, `## Use this skill when`, `## When to Use This Skill`.
 
 ### 3. Safety & Risk Classification
 

docs/SKILL_ANATOMY.md

@@ -73,7 +73,7 @@ Some skills include additional metadata:
 ---
 name: my-skill-name
 description: "Brief description"
-risk: "safe" # safe | risk | official
+risk: "safe" # none | safe | critical | offensive (see QUALITY_BAR.md)
 source: "community"
 tags: ["react", "typescript"]
 ---

docs/SOURCES.md

@@ -14,6 +14,72 @@ If you recognize your work here and it is not properly attributed, please open a
 | `react-patterns`            | [React Docs](https://react.dev/)                       | CC-BY          | Official patterns.            |
 | **All Official Skills**     | [Anthropic / Google / OpenAI]                          | Proprietary    | Usage encouraged by vendors.  |
 
+## Skills from VoltAgent/awesome-agent-skills
+
+The following skills were added from the curated collection at [VoltAgent/awesome-agent-skills](https://github.com/VoltAgent/awesome-agent-skills):
+
+### Official Team Skills
+
+| Skill | Original Source | License | Notes |
+| :---- | :-------------- | :------ | :---- |
+| `vercel-deploy-claimable` | [Vercel Labs](https://github.com/vercel-labs/agent-skills) | MIT | Official Vercel skill |
+| `design-md` | [Google Labs (Stitch)](https://github.com/google-labs-code/stitch-skills) | Compatible | Google Labs Stitch skills |
+| `hugging-face-cli`, `hugging-face-jobs` | [Hugging Face](https://github.com/huggingface/skills) | Compatible | Official Hugging Face skills |
+| `culture-index`, `fix-review`, `sharp-edges` | [Trail of Bits](https://github.com/trailofbits/skills) | Compatible | Security skills from Trail of Bits |
+| `expo-deployment`, `upgrading-expo` | [Expo](https://github.com/expo/skills) | Compatible | Official Expo skills |
+| `commit`, `create-pr`, `find-bugs`, `iterate-pr` | [Sentry](https://github.com/getsentry/skills) | Compatible | Sentry dev team skills |
+| `using-neon` | [Neon](https://github.com/neondatabase/agent-skills) | Compatible | Neon Postgres best practices |
+| `fal-audio`, `fal-generate`, `fal-image-edit`, `fal-platform`, `fal-upscale`, `fal-workflow` | [fal.ai Community](https://github.com/fal-ai-community/skills) | Compatible | fal.ai AI model skills |
+
+### Community Skills
+
+| Skill | Original Source | License | Notes |
+| :---- | :-------------- | :------ | :---- |
+| `automate-whatsapp`, `observe-whatsapp` | [gokapso](https://github.com/gokapso/agent-skills) | Compatible | WhatsApp automation skills |
+| `readme` | [Shpigford](https://github.com/Shpigford/skills) | Compatible | README generation |
+| `screenshots` | [Shpigford](https://github.com/Shpigford/skills) | Compatible | Marketing screenshots |
+| `aws-skills` | [zxkane](https://github.com/zxkane/aws-skills) | Compatible | AWS development patterns |
+| `deep-research` | [sanjay3290](https://github.com/sanjay3290/ai-skills) | Compatible | Gemini Deep Research Agent |
+| `ffuf-claude-skill` | [jthack](https://github.com/jthack/ffuf_claude_skill) | Compatible | Web fuzzing with ffuf |
+| `ui-skills` | [ibelick](https://github.com/ibelick/ui-skills) | Compatible | UI development constraints |
+| `vexor` | [scarletkc](https://github.com/scarletkc/vexor) | Compatible | Vector-powered CLI |
+| `pypict-skill` | [omkamal](https://github.com/omkamal/pypict-claude-skill) | Compatible | Pairwise test generation |
+| `makepad-skills` | [ZhangHanDong](https://github.com/ZhangHanDong/makepad-skills) | Compatible | Makepad UI development |
+| `swiftui-expert-skill` | [AvdLee](https://github.com/AvdLee/SwiftUI-Agent-Skill) | Compatible | SwiftUI best practices |
+| `threejs-skills` | [CloudAI-X](https://github.com/CloudAI-X/threejs-skills) | Compatible | Three.js 3D experiences |
+| `claude-scientific-skills` | [K-Dense-AI](https://github.com/K-Dense-AI/claude-scientific-skills) | Compatible | Scientific research skills |
+| `claude-win11-speckit-update-skill` | [NotMyself](https://github.com/NotMyself/claude-win11-speckit-update-skill) | Compatible | Windows 11 management |
+| `imagen` | [sanjay3290](https://github.com/sanjay3290/ai-skills) | Compatible | Google Gemini image generation |
+| `security-bluebook-builder` | [SHADOWPR0](https://github.com/SHADOWPR0/security-bluebook-builder) | Compatible | Security documentation |
+| `claude-ally-health` | [huifer](https://github.com/huifer/Claude-Ally-Health) | Compatible | Health assistant |
+| `clarity-gate` | [frmoretto](https://github.com/frmoretto/clarity-gate) | Compatible | RAG quality verification |
+| `n8n-code-python`, `n8n-mcp-tools-expert`, `n8n-node-configuration` | [czlonkowski](https://github.com/czlonkowski/n8n-skills) | Compatible | n8n automation skills |
+| `varlock-claude-skill` | [wrsmith108](https://github.com/wrsmith108/varlock-claude-skill) | Compatible | Secure environment variables |
+| `beautiful-prose` | [SHADOWPR0](https://github.com/SHADOWPR0/beautiful_prose) | Compatible | Writing style guide |
+| `claude-speed-reader` | [SeanZoR](https://github.com/SeanZoR/claude-speed-reader) | Compatible | Speed reading tool |
+| `skill-seekers` | [yusufkaraaslan](https://github.com/yusufkaraaslan/Skill_Seekers) | Compatible | Skill conversion tool |
+
+- **frontend-slides** - [zarazhangrui](https://github.com/zarazhangrui/frontend-slides)
+- **linear-claude-skill** - [wrsmith108](https://github.com/wrsmith108/linear-claude-skill)
+- **skill-rails-upgrade** - [robzolkos](https://github.com/robzolkos/skill-rails-upgrade)
+- **context-fundamentals** - [muratcankoylan](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering)
+- **context-degradation** - [muratcankoylan](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering)
+- **context-compression** - [muratcankoylan](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering)
+- **context-optimization** - [muratcankoylan](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering)
+- **multi-agent-patterns** - [muratcankoylan](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering)
+- **tool-design** - [muratcankoylan](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering)
+- **evaluation** - [muratcankoylan](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering)
+- **memory-systems** - [muratcankoylan](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering)
+- **terraform-skill** - [antonbabenko](https://github.com/antonbabenko/terraform-skill)
+
+## Skills from whatiskadudoing/fp-ts-skills (v4.4.0)
+
+| Skill | Original Source | License | Notes |
+| :---- | :-------------- | :------ | :---- |
+| `fp-ts-pragmatic` | [whatiskadudoing/fp-ts-skills](https://github.com/whatiskadudoing/fp-ts-skills) | Compatible | Pragmatic fp-ts guide – pipe, Option, Either, TaskEither |
+| `fp-ts-react` | [whatiskadudoing/fp-ts-skills](https://github.com/whatiskadudoing/fp-ts-skills) | Compatible | fp-ts with React 18/19 and Next.js |
+| `fp-ts-errors` | [whatiskadudoing/fp-ts-skills](https://github.com/whatiskadudoing/fp-ts-skills) | Compatible | Type-safe error handling with Either and TaskEither |
+
 ## License Policy
 
 - **Code**: All original code in this repository is **MIT**.

docs/vietnamese/SKILL_ANATOMY.vi.md

@@ -73,7 +73,7 @@ Một số skill bao gồm thêm siêu dữ liệu bổ sung:
 ---
 name: my-skill-name
 description: "Mô tả ngắn"
-risk: "safe" # safe | risk | official
+risk: "safe" # none | safe | critical | offensive (xem QUALITY_BAR.md)
 source: "community"
 tags: ["react", "typescript"]
 ---

lib/skill-utils.js

@@ -149,12 +149,39 @@ function readSkill(skillDir, skillId) {
 
 function listSkillIds(skillsDir) {
   return fs.readdirSync(skillsDir)
-    .filter(entry => !entry.startsWith('.') && fs.statSync(path.join(skillsDir, entry)).isDirectory())
+    .filter(entry => {
+      if (entry.startsWith('.')) return false;
+      const dirPath = path.join(skillsDir, entry);
+      if (!fs.statSync(dirPath).isDirectory()) return false;
+      const skillPath = path.join(dirPath, 'SKILL.md');
+      return fs.existsSync(skillPath);
+    })
     .sort();
 }
 
+/**
+ * Recursively list all skill directory paths under skillsDir (relative paths).
+ * Matches generate_index.py behavior so catalog includes nested skills (e.g. game-development/2d-games).
+ */
+function listSkillIdsRecursive(skillsDir, baseDir = skillsDir, acc = []) {
+  const entries = fs.readdirSync(baseDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue;
+    if (!entry.isDirectory()) continue;
+    const dirPath = path.join(baseDir, entry.name);
+    const skillPath = path.join(dirPath, 'SKILL.md');
+    const relPath = path.relative(skillsDir, dirPath);
+    if (fs.existsSync(skillPath)) {
+      acc.push(relPath);
+    }
+    listSkillIdsRecursive(skillsDir, dirPath, acc);
+  }
+  return acc.sort();
+}
+
 module.exports = {
   listSkillIds,
+  listSkillIdsRecursive,
   parseFrontmatter,
   parseInlineList,
   readSkill,

package.json

@@ -1,7 +1,7 @@
 {
   "name": "antigravity-awesome-skills",
-  "version": "4.2.0",
-  "description": "560+ agentic skills for Claude Code, Gemini CLI, Cursor, Antigravity & more. Installer CLI.",
+  "version": "4.7.0",
+  "description": "626+ agentic skills for Claude Code, Gemini CLI, Cursor, Antigravity & more. Installer CLI.",
   "license": "MIT",
   "scripts": {
     "validate": "python3 scripts/validate_skills.py",
@@ -10,17 +10,18 @@
     "readme": "python3 scripts/update_readme.py",
     "chain": "npm run validate && npm run index && npm run readme",
     "catalog": "node scripts/build-catalog.js",
-    "build": "npm run chain && npm run catalog"
+    "build": "npm run chain && npm run catalog",
+    "test": "node scripts/tests/validate_skills_headings.test.js && python3 scripts/tests/test_validate_skills_headings.py"
   },
-  "dependencies": {
+  "devDependencies": {
     "yaml": "^2.8.2"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/sickn33/antigravity-awesome-skills.git"
+    "url": "git+https://github.com/sickn33/antigravity-awesome-skills.git"
   },
   "bin": {
-    "antigravity-awesome-skills": "./bin/install.js"
+    "antigravity-awesome-skills": "bin/install.js"
   },
   "files": [
     "bin"

scripts/build-catalog.js

@@ -1,7 +1,7 @@
 const fs = require('fs');
 const path = require('path');
 const {
-  listSkillIds,
+  listSkillIdsRecursive,
   readSkill,
   tokenize,
   unique,
@@ -297,8 +297,8 @@ function renderCatalogMarkdown(catalog) {
 }
 
 function buildCatalog() {
-  const skillIds = listSkillIds(SKILLS_DIR);
-  const skills = skillIds.map(skillId => readSkill(SKILLS_DIR, skillId));
+  const skillRelPaths = listSkillIdsRecursive(SKILLS_DIR);
+  const skills = skillRelPaths.map(relPath => readSkill(SKILLS_DIR, relPath));
   const catalogSkills = [];
 
   for (const skill of skills) {

scripts/normalize-frontmatter.js

@@ -8,6 +8,8 @@ const SKILLS_DIR = path.join(ROOT, 'skills');
 const ALLOWED_FIELDS = new Set([
   'name',
   'description',
+  'risk',
+  'source',
   'license',
   'compatibility',
   'metadata',

scripts/release_cycle.sh

@@ -21,8 +21,12 @@ python3 scripts/generate_index.py
 echo "Running update_readme.py..."
 python3 scripts/update_readme.py
 
-# 2. Stats Consistency Check
-echo -e "\n${YELLOW}Step 2: verifying Stats Consistency...${NC}"
+# 2. Catalog (required for CI)
+echo -e "\n${YELLOW}Step 2: Build catalog...${NC}"
+npm run catalog
+
+# 3. Stats Consistency Check
+echo -e "\n${YELLOW}Step 3: Verifying Stats Consistency...${NC}"
 JSON_COUNT=$(python3 -c "import json; print(len(json.load(open('skills_index.json'))))")
 echo "Skills in Registry (JSON): $JSON_COUNT"
 
@@ -36,8 +40,14 @@ if [[ "$README_CONTENT" != *"$JSON_COUNT high-performance"* ]]; then
 fi
 echo -e "${GREEN}✅ Stats Consistent.${NC}"
 
-# 3. Contributor Check
-echo -e "\n${YELLOW}Step 3: Contributor Check${NC}"
+# 4. Version check (package.json is source of truth for npm)
+echo -e "\n${YELLOW}Step 4: Version check${NC}"
+PKG_VERSION=$(node -p "require('./package.json').version")
+echo "package.json version: $PKG_VERSION"
+echo "Ensure this version is bumped before 'npm publish' (npm forbids republishing the same version)."
+
+# 5. Contributor Check
+echo -e "\n${YELLOW}Step 5: Contributor Check${NC}"
 echo "Recent commits by author (check against README 'Repo Contributors'):"
 git shortlog -sn --since="1 month ago" --all --no-merges | head -n 10
 
@@ -52,4 +62,5 @@ if [ "$CONFIRM_CONTRIB" != "yes" ]; then
 fi
 
 echo -e "\n${GREEN}✅ Release Cycle Checks Passed. You may now commit and push.${NC}"
+echo -e "${YELLOW}After tagging a release: run \`npm publish\` from repo root (or use GitHub Release + NPM_TOKEN for CI).${NC}"
 exit 0

scripts/tests/test_validate_skills_headings.py

@@ -0,0 +1,18 @@
+import os
+import sys
+
+sys.path.append(os.path.dirname(os.path.dirname(__file__)))
+from validate_skills import has_when_to_use_section
+
+SAMPLES = [
+    ("## When to Use", True),
+    ("## Use this skill when", True),
+    ("## When to Use This Skill", True),
+    ("## Overview", False),
+]
+
+for heading, expected in SAMPLES:
+    content = f"\n{heading}\n- item\n"
+    assert has_when_to_use_section(content) is expected, heading
+
+print("ok")

scripts/tests/validate_skills_headings.test.js

@@ -0,0 +1,16 @@
+const assert = require('assert');
+const { hasUseSection } = require('../validate-skills');
+
+const samples = [
+  ['## When to Use', true],
+  ['## Use this skill when', true],
+  ['## When to Use This Skill', true],
+  ['## Overview', false],
+];
+
+for (const [heading, expected] of samples) {
+  const content = `\n${heading}\n- item\n`;
+  assert.strictEqual(hasUseSection(content), expected, heading);
+}
+
+console.log('ok');

scripts/update_readme.py

@@ -36,7 +36,7 @@ def update_readme():
 
     # 3. Update Intro Text Count
     content = re.sub(
-        r"(library of \*\*)\d+( high-performance skills\*\*)",
+        r"(library of \*\*)\d+( high-performance agentic skills\*\*)",
         rf"\g<1>{total_skills}\g<2>",
         content,
     )

scripts/validate-skills.js

@@ -32,12 +32,24 @@ const MAX_SKILL_LINES = 500;
 const ALLOWED_FIELDS = new Set([
   'name',
   'description',
+  'risk',
+  'source',
   'license',
   'compatibility',
   'metadata',
   'allowed-tools',
 ]);
 
+const USE_SECTION_PATTERNS = [
+  /^##\s+When\s+to\s+Use/im,
+  /^##\s+Use\s+this\s+skill\s+when/im,
+  /^##\s+When\s+to\s+Use\s+This\s+Skill/im,
+];
+
+function hasUseSection(content) {
+  return USE_SECTION_PATTERNS.some(pattern => pattern.test(content));
+}
+
 function isPlainObject(value) {
   return value && typeof value === 'object' && !Array.isArray(value);
 }
@@ -99,172 +111,183 @@ function addStrictSectionErrors(label, missing, baselineSet) {
   }
 }
 
-const skillIds = listSkillIds(SKILLS_DIR);
-const baseline = loadBaseline();
-const baselineUse = new Set(baseline.useSection || []);
-const baselineDoNotUse = new Set(baseline.doNotUseSection || []);
-const baselineInstructions = new Set(baseline.instructionsSection || []);
-const baselineLongFile = new Set(baseline.longFile || []);
+function run() {
+  const skillIds = listSkillIds(SKILLS_DIR);
+  const baseline = loadBaseline();
+  const baselineUse = new Set(baseline.useSection || []);
+  const baselineDoNotUse = new Set(baseline.doNotUseSection || []);
+  const baselineInstructions = new Set(baseline.instructionsSection || []);
+  const baselineLongFile = new Set(baseline.longFile || []);
 
-for (const skillId of skillIds) {
-  const skillPath = path.join(SKILLS_DIR, skillId, 'SKILL.md');
+  for (const skillId of skillIds) {
+    const skillPath = path.join(SKILLS_DIR, skillId, 'SKILL.md');
 
-  if (!fs.existsSync(skillPath)) {
-    addError(`Missing SKILL.md: ${skillId}`);
-    continue;
-  }
-
-  const content = fs.readFileSync(skillPath, 'utf8');
-  const { data, errors: fmErrors, hasFrontmatter } = parseFrontmatter(content);
-  const lineCount = content.split(/\r?\n/).length;
-
-  if (!hasFrontmatter) {
-    addError(`Missing frontmatter: ${skillId}`);
-  }
-
-  if (fmErrors && fmErrors.length) {
-    fmErrors.forEach(error => addError(`Frontmatter parse error (${skillId}): ${error}`));
-  }
-
-  if (!NAME_PATTERN.test(skillId)) {
-    addError(`Folder name must match ${NAME_PATTERN}: ${skillId}`);
-  }
-
-  if (data.name !== undefined) {
-    const nameError = validateStringField('name', data.name, { min: 1, max: MAX_NAME_LENGTH });
-    if (nameError) {
-      addError(`${nameError} (${skillId})`);
-    } else {
-      const nameValue = String(data.name).trim();
-      if (!NAME_PATTERN.test(nameValue)) {
-        addError(`name must match ${NAME_PATTERN}: ${skillId}`);
-      }
-      if (nameValue !== skillId) {
-        addError(`name must match folder name: ${skillId} -> ${nameValue}`);
-      }
+    if (!fs.existsSync(skillPath)) {
+      addError(`Missing SKILL.md: ${skillId}`);
+      continue;
     }
-  }
 
-  const descError = data.description === undefined
-    ? 'description is required.'
-    : validateStringField('description', data.description, { min: 1, max: MAX_DESCRIPTION_LENGTH });
-  if (descError) {
-    addError(`${descError} (${skillId})`);
-  }
+    const content = fs.readFileSync(skillPath, 'utf8');
+    const { data, errors: fmErrors, hasFrontmatter } = parseFrontmatter(content);
+    const lineCount = content.split(/\r?\n/).length;
 
-  if (data.license !== undefined) {
-    const licenseError = validateStringField('license', data.license, { min: 1, max: 128 });
-    if (licenseError) {
-      addError(`${licenseError} (${skillId})`);
+    if (!hasFrontmatter) {
+      addError(`Missing frontmatter: ${skillId}`);
     }
-  }
 
-  if (data.compatibility !== undefined) {
-    const compatibilityError = validateStringField(
-      'compatibility',
-      data.compatibility,
-      { min: 1, max: MAX_COMPATIBILITY_LENGTH },
-    );
-    if (compatibilityError) {
-      addError(`${compatibilityError} (${skillId})`);
+    if (fmErrors && fmErrors.length) {
+      fmErrors.forEach(error => addError(`Frontmatter parse error (${skillId}): ${error}`));
     }
-  }
 
-  if (data['allowed-tools'] !== undefined) {
-    if (typeof data['allowed-tools'] !== 'string') {
-      addError(`allowed-tools must be a space-delimited string. (${skillId})`);
-    } else if (!data['allowed-tools'].trim()) {
-      addError(`allowed-tools cannot be empty. (${skillId})`);
+    if (!NAME_PATTERN.test(skillId)) {
+      addError(`Folder name must match ${NAME_PATTERN}: ${skillId}`);
     }
-  }
 
-  if (data.metadata !== undefined) {
-    if (!isPlainObject(data.metadata)) {
-      addError(`metadata must be a string map/object. (${skillId})`);
-    } else {
-      for (const [key, value] of Object.entries(data.metadata)) {
-        if (typeof value !== 'string') {
-          addError(`metadata.${key} must be a string. (${skillId})`);
+    if (data.name !== undefined) {
+      const nameError = validateStringField('name', data.name, { min: 1, max: MAX_NAME_LENGTH });
+      if (nameError) {
+        addError(`${nameError} (${skillId})`);
+      } else {
+        const nameValue = String(data.name).trim();
+        if (!NAME_PATTERN.test(nameValue)) {
+          addError(`name must match ${NAME_PATTERN}: ${skillId}`);
+        }
+        if (nameValue !== skillId) {
+          addError(`name must match folder name: ${skillId} -> ${nameValue}`);
         }
       }
     }
-  }
 
-  if (data && Object.keys(data).length) {
-    const unknownFields = Object.keys(data).filter(key => !ALLOWED_FIELDS.has(key));
-    if (unknownFields.length) {
-      unknownFieldSkills.push(skillId);
-      addError(`Unknown frontmatter fields (${skillId}): ${unknownFields.join(', ')}`);
+    const descError = data.description === undefined
+      ? 'description is required.'
+      : validateStringField('description', data.description, { min: 1, max: MAX_DESCRIPTION_LENGTH });
+    if (descError) {
+      addError(`${descError} (${skillId})`);
+    }
+
+    if (data.license !== undefined) {
+      const licenseError = validateStringField('license', data.license, { min: 1, max: 128 });
+      if (licenseError) {
+        addError(`${licenseError} (${skillId})`);
+      }
+    }
+
+    if (data.compatibility !== undefined) {
+      const compatibilityError = validateStringField(
+        'compatibility',
+        data.compatibility,
+        { min: 1, max: MAX_COMPATIBILITY_LENGTH },
+      );
+      if (compatibilityError) {
+        addError(`${compatibilityError} (${skillId})`);
+      }
+    }
+
+    if (data['allowed-tools'] !== undefined) {
+      if (typeof data['allowed-tools'] !== 'string') {
+        addError(`allowed-tools must be a space-delimited string. (${skillId})`);
+      } else if (!data['allowed-tools'].trim()) {
+        addError(`allowed-tools cannot be empty. (${skillId})`);
+      }
+    }
+
+    if (data.metadata !== undefined) {
+      if (!isPlainObject(data.metadata)) {
+        addError(`metadata must be a string map/object. (${skillId})`);
+      } else {
+        for (const [key, value] of Object.entries(data.metadata)) {
+          if (typeof value !== 'string') {
+            addError(`metadata.${key} must be a string. (${skillId})`);
+          }
+        }
+      }
+    }
+
+    if (data && Object.keys(data).length) {
+      const unknownFields = Object.keys(data).filter(key => !ALLOWED_FIELDS.has(key));
+      if (unknownFields.length) {
+        unknownFieldSkills.push(skillId);
+        addError(`Unknown frontmatter fields (${skillId}): ${unknownFields.join(', ')}`);
+      }
+    }
+
+    if (lineCount > MAX_SKILL_LINES) {
+      longFiles.push(skillId);
+    }
+
+    if (!hasUseSection(content)) {
+      missingUseSection.push(skillId);
+    }
+
+    if (!content.includes('## Do not use')) {
+      missingDoNotUseSection.push(skillId);
+    }
+
+    if (!content.includes('## Instructions')) {
+      missingInstructionsSection.push(skillId);
     }
   }
 
-  if (lineCount > MAX_SKILL_LINES) {
-    longFiles.push(skillId);
+  if (missingUseSection.length) {
+    addWarning(`Missing "Use this skill when" section: ${missingUseSection.length} skills (examples: ${missingUseSection.slice(0, 5).join(', ')})`);
   }
 
-  if (!content.includes('## Use this skill when')) {
-    missingUseSection.push(skillId);
+  if (missingDoNotUseSection.length) {
+    addWarning(`Missing "Do not use" section: ${missingDoNotUseSection.length} skills (examples: ${missingDoNotUseSection.slice(0, 5).join(', ')})`);
   }
 
-  if (!content.includes('## Do not use')) {
-    missingDoNotUseSection.push(skillId);
+  if (missingInstructionsSection.length) {
+    addWarning(`Missing "Instructions" section: ${missingInstructionsSection.length} skills (examples: ${missingInstructionsSection.slice(0, 5).join(', ')})`);
   }
 
-  if (!content.includes('## Instructions')) {
-    missingInstructionsSection.push(skillId);
+  if (longFiles.length) {
+    addWarning(`SKILL.md over ${MAX_SKILL_LINES} lines: ${longFiles.length} skills (examples: ${longFiles.slice(0, 5).join(', ')})`);
   }
-}
 
-if (missingUseSection.length) {
-  addWarning(`Missing "Use this skill when" section: ${missingUseSection.length} skills (examples: ${missingUseSection.slice(0, 5).join(', ')})`);
-}
-
-if (missingDoNotUseSection.length) {
-  addWarning(`Missing "Do not use" section: ${missingDoNotUseSection.length} skills (examples: ${missingDoNotUseSection.slice(0, 5).join(', ')})`);
-}
-
-if (missingInstructionsSection.length) {
-  addWarning(`Missing "Instructions" section: ${missingInstructionsSection.length} skills (examples: ${missingInstructionsSection.slice(0, 5).join(', ')})`);
-}
-
-if (longFiles.length) {
-  addWarning(`SKILL.md over ${MAX_SKILL_LINES} lines: ${longFiles.length} skills (examples: ${longFiles.slice(0, 5).join(', ')})`);
-}
-
-if (unknownFieldSkills.length) {
-  addWarning(`Unknown frontmatter fields detected: ${unknownFieldSkills.length} skills (examples: ${unknownFieldSkills.slice(0, 5).join(', ')})`);
-}
-
-addStrictSectionErrors('Use this skill when', missingUseSection, baselineUse);
-addStrictSectionErrors('Do not use', missingDoNotUseSection, baselineDoNotUse);
-addStrictSectionErrors('Instructions', missingInstructionsSection, baselineInstructions);
-addStrictSectionErrors(`SKILL.md line count <= ${MAX_SKILL_LINES}`, longFiles, baselineLongFile);
-
-if (writeBaseline) {
-  const baselineData = {
-    generatedAt: new Date().toISOString(),
-    useSection: [...missingUseSection].sort(),
-    doNotUseSection: [...missingDoNotUseSection].sort(),
-    instructionsSection: [...missingInstructionsSection].sort(),
-    longFile: [...longFiles].sort(),
-  };
-  fs.writeFileSync(BASELINE_PATH, JSON.stringify(baselineData, null, 2));
-  console.log(`Baseline written to ${BASELINE_PATH}`);
-}
-
-if (warnings.length) {
-  console.warn('Warnings:');
-  for (const warning of warnings) {
-    console.warn(`- ${warning}`);
+  if (unknownFieldSkills.length) {
+    addWarning(`Unknown frontmatter fields detected: ${unknownFieldSkills.length} skills (examples: ${unknownFieldSkills.slice(0, 5).join(', ')})`);
   }
-}
 
-if (errors.length) {
-  console.error('\nErrors:');
-  for (const error of errors) {
-    console.error(`- ${error}`);
+  addStrictSectionErrors('Use this skill when', missingUseSection, baselineUse);
+  addStrictSectionErrors('Do not use', missingDoNotUseSection, baselineDoNotUse);
+  addStrictSectionErrors('Instructions', missingInstructionsSection, baselineInstructions);
+  addStrictSectionErrors(`SKILL.md line count <= ${MAX_SKILL_LINES}`, longFiles, baselineLongFile);
+
+  if (writeBaseline) {
+    const baselineData = {
+      generatedAt: new Date().toISOString(),
+      useSection: [...missingUseSection].sort(),
+      doNotUseSection: [...missingDoNotUseSection].sort(),
+      instructionsSection: [...missingInstructionsSection].sort(),
+      longFile: [...longFiles].sort(),
+    };
+    fs.writeFileSync(BASELINE_PATH, JSON.stringify(baselineData, null, 2));
+    console.log(`Baseline written to ${BASELINE_PATH}`);
   }
-  process.exit(1);
+
+  if (warnings.length) {
+    console.warn('Warnings:');
+    for (const warning of warnings) {
+      console.warn(`- ${warning}`);
+    }
+  }
+
+  if (errors.length) {
+    console.error('\nErrors:');
+    for (const error of errors) {
+      console.error(`- ${error}`);
+    }
+    process.exit(1);
+  }
+
+  console.log(`Validation passed for ${skillIds.length} skills.`);
 }
 
-console.log(`Validation passed for ${skillIds.length} skills.`);
+if (require.main === module) {
+  run();
+}
+
+module.exports = {
+  hasUseSection,
+  run,
+};

scripts/validate_skills.py

@@ -3,6 +3,15 @@ import re
 import argparse
 import sys
 
+WHEN_TO_USE_PATTERNS = [
+    re.compile(r"^##\s+When\s+to\s+Use", re.MULTILINE | re.IGNORECASE),
+    re.compile(r"^##\s+Use\s+this\s+skill\s+when", re.MULTILINE | re.IGNORECASE),
+    re.compile(r"^##\s+When\s+to\s+Use\s+This\s+Skill", re.MULTILINE | re.IGNORECASE),
+]
+
+def has_when_to_use_section(content):
+    return any(pattern.search(content) for pattern in WHEN_TO_USE_PATTERNS)
+
 def parse_frontmatter(content):
     """
     Simple frontmatter parser using regex to avoid external dependencies.
@@ -30,7 +39,6 @@ def validate_skills(skills_dir, strict_mode=False):
     
     # Pre-compiled regex
     security_disclaimer_pattern = re.compile(r"AUTHORIZED USE ONLY", re.IGNORECASE)
-    trigger_section_pattern = re.compile(r"^##\s+When to Use", re.MULTILINE | re.IGNORECASE)
 
     valid_risk_levels = ["none", "safe", "critical", "offensive"]
 
@@ -80,7 +88,7 @@ def validate_skills(skills_dir, strict_mode=False):
                 else: warnings.append(msg)
 
             # 3. Content Checks (Triggers)
-            if not trigger_section_pattern.search(content):
+            if not has_when_to_use_section(content):
                 msg = f"⚠️  {rel_path}: Missing '## When to Use' section"
                 if strict_mode: errors.append(msg.replace("⚠️", "❌"))
                 else: warnings.append(msg)

skills/SPDD/1-research.md

@@ -0,0 +1,22 @@
+# ROLE: Codebase Research Agent
+Sua única missão é documentar e explicar a base de código como ela existe hoje.
+
+## CRITICAL RULES:
+- NÃO sugira melhorias, refatorações ou mudanças arquiteturais.
+- NÃO realize análise de causa raiz ou proponha melhorias futuras.
+- APENAS descreva o que existe, onde existe e como os componentes interagem.
+- Você é um cartógrafo técnico criando um mapa do sistema atual.
+
+## STEPS TO FOLLOW:
+1. **Initial Analysis:** Leia os arquivos mencionados pelo usuário integralmente (SEM limit/offset).
+2. **Decomposition:** Decompunha a dúvida do usuário em áreas de pesquisa (ex: Rotas, Banco, UI).
+3. **Execution:** - Localize onde os arquivos e componentes vivem.
+   - Analise COMO o código atual funciona (sem criticar).
+   - Encontre exemplos de padrões existentes para referência.
+4. **Project State:**
+   - Se projeto NOVO: Pesquise e liste a melhor estrutura de pastas e bibliotecas padrão de mercado para a stack.
+   - Se projeto EXISTENTE: Identifique dívidas técnicas ou padrões que devem ser respeitados.
+
+## OUTPUT:
+- Gere o arquivo `docs/prds/prd_current_task.md` com YAML frontmatter (date, topic, tags, status).
+- **Ação Obrigatória:** Termine com: "Pesquisa concluída. Por favor, dê um `/clear` e carregue `.agente/2-spec.md` para o planejamento."

skills/SPDD/2-spec.md

@@ -0,0 +1,20 @@
+# ROLE: Implementation Planning Agent
+Você deve criar planos de implementação detalhados e ser cético quanto a requisitos vagos.
+
+## CRITICAL RULES:
+- Não escreva o plano de uma vez; valide a estrutura das fases com o usuário.
+- Cada decisão técnica deve ser tomada antes de finalizar o plano.
+- O plano deve ser acionável e completo, sem "perguntas abertas".
+
+## STEPS TO FOLLOW:
+1. **Context Check:** Leia o `docs/prds/prd_current_task.md` gerado anteriormente.
+2. **Phasing:** Divida o trabalho em fases incrementais e testáveis.
+3. **Detailing:** Para cada arquivo afetado, defina:
+   - **Path exato.**
+   - **Ação:** (CRIAR | MODIFICAR | DELETAR).
+   - **Lógica:** Snippets de pseudocódigo ou referências de implementação.
+4. **Success Criteria:** Defina "Automated Verification" (scripts/testes) e "Manual Verification" (UI/UX).
+
+## OUTPUT:
+- Gere o arquivo `docs/specs/spec_current_task.md` seguindo o template de fases.
+- **Ação Obrigatória:** Termine com: "Spec finalizada. Por favor, dê um `/clear` e carregue `.agente/3-implementation.md` para execução."

skills/SPDD/3-implementation.md

@@ -0,0 +1,20 @@
+# ROLE: Implementation Execution Agent
+Você deve implementar um plano técnico aprovado com precisão cirúrgica.
+
+## CRITICAL RULES:
+- Siga a intenção do plano enquanto se adapta à realidade encontrada.
+- Implemente uma fase COMPLETAMENTE antes de passar para a próxima.
+- **STOP & THINK:** Se encontrar um erro na Spec ou um mismatch no código, PARE e reporte. Não tente adivinhar.
+
+## STEPS TO FOLLOW:
+1. **Sanity Check:** Leia a Spec e o Ticket original. Verifique se o ambiente está limpo.
+2. **Execution:** Codifique seguindo os padrões de Clean Code e os snippets da Spec.
+3. **Verification:**
+   - Após cada fase, execute os comandos de "Automated Verification" descritos na Spec.
+   - PAUSE para confirmação manual do usuário após cada fase concluída.
+4. **Progress:** Atualize os checkboxes (- [x]) no arquivo de Spec conforme avança.
+
+## OUTPUT:
+- Código fonte implementado.
+- Relatório de conclusão de fase com resultados de testes.
+- **Ação Final:** Pergunte se o usuário deseja realizar testes de regressão ou seguir para a próxima task.

skills/automate-whatsapp/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: automate-whatsapp
+description: "Build WhatsApp automations with Kapso workflows: configure WhatsApp triggers, edit workflow graphs, manage executions, deploy functions, and use databases/integrations for state. Use when automating WhatsApp conversations and event handling."
+source: "https://github.com/gokapso/agent-skills/tree/master/skills/automate-whatsapp"
+risk: safe
+---
+
+# Automate WhatsApp
+
+## When to use
+
+Use this skill to build and run WhatsApp automations: workflow CRUD, graph edits, triggers, executions, function management, app integrations, and D1 database operations.
+
+## Setup
+
+Env vars:
+- `KAPSO_API_BASE_URL` (host only, no `/platform/v1`)
+- `KAPSO_API_KEY`
+
+## How to
+
+### Edit a workflow graph
+
+1. Fetch graph: `node scripts/get-graph.js <workflow_id>` (note the `lock_version`)
+2. Edit the JSON (see graph rules below)
+3. Validate: `node scripts/validate-graph.js --definition-file <path>`
+4. Update: `node scripts/update-graph.js <workflow_id> --expected-lock-version <n> --definition-file <path>`
+5. Re-fetch to confirm
+
+For small edits, use `edit-graph.js` with `--old-file` and `--new-file` instead.
+
+If you get a lock_version conflict: re-fetch, re-apply changes, retry with new lock_version.
+
+### Manage triggers
+
+1. List: `node scripts/list-triggers.js <workflow_id>`
+2. Create: `node scripts/create-trigger.js <workflow_id> --trigger-type <type> --phone-number-id <id>`
+3. Toggle: `node scripts/update-trigger.js --trigger-id <id> --active true|false`
+4. Delete: `node scripts/delete-trigger.js --trigger-id <id>`
+
+For inbound_message triggers, first run `node scripts/list-whatsapp-phone-numbers.js` to get `phone_number_id`.
+
+### Debug executions
+
+1. List: `node scripts/list-executions.js <workflow_id>`
+2. Inspect: `node scripts/get-execution.js <execution-id>`
+3. Get value: `node scripts/get-context-value.js <execution-id> --variable-path vars.foo`
+4. Events: `node scripts/list-execution-events.js <execution-id>`
+
+### Create and deploy a function
+
+1. Write code with handler signature (see function rules below)
+2. Create: `node scripts/create-function.js --name <name> --code-file <path>`
+3. Deploy: `node scripts/deploy-function.js --function-id <id>`
+4. Verify: `node scripts/get-function.js --function-id <id>`
+
+### Set up agent node with app integrations
+
+1. Find model: `node scripts/list-provider-models.js`
+2. Find account: `node scripts/list-accounts.js --app-slug <slug>` (use `pipedream_account_id`)
+3. Find action: `node scripts/search-actions.js --query <word> --app-slug <slug>` (action_id = key)
+4. Create integration: `node scripts/create-integration.js --action-id <id> --app-slug <slug> --account-id <id> --configured-props <json>`
+5. Add tools to agent node via `flow_agent_app_integration_tools`
+
+### Database CRUD
+
+1. List tables: `node scripts/list-tables.js`
+2. Query: `node scripts/query-rows.js --table <name> --filters <json>`
+3. Create/update/delete with row scripts
+
+## Graph rules
+
+- Exactly one start node with `id` = `start`
+- Never change existing node IDs
+- Use `{node_type}_{timestamp_ms}` for new node IDs
+- Non-decide nodes have 0 or 1 outgoing `next` edge
+- Decide edge labels must match `conditions[].label`
+- Edge keys are `source`/`target`/`label` (not `from`/`to`)
+
+For full schema details, see `references/graph-contract.md`.
+
+## Function rules
+
+```js
+async function handler(request, env) {
+  // Parse input
+  const body = await request.json();
+  // Use env.KV and env.DB as needed
+  return new Response(JSON.stringify({ result: "ok" }));
+}
+```
+
+- Do NOT use `export`, `export default`, or arrow functions
+- Return a `Response` object
+
+## Execution context
+
+Always use this structure:
+- `vars` - user-defined variables
+- `system` - system variables
+- `context` - channel data
+- `metadata` - request metadata
+
+## Scripts
+
+### Workflows
+
+| Script | Purpose |
+|--------|---------|
+| `list-workflows.js` | List workflows (metadata only) |
+| `get-workflow.js` | Get workflow metadata |
+| `create-workflow.js` | Create a workflow |
+| `update-workflow-settings.js` | Update workflow settings |
+
+### Graph
+
+| Script | Purpose |
+|--------|---------|
+| `get-graph.js` | Get workflow graph + lock_version |
+| `edit-graph.js` | Patch graph via string replacement |
+| `update-graph.js` | Replace entire graph |
+| `validate-graph.js` | Validate graph structure locally |
+
+### Triggers
+
+| Script | Purpose |
+|--------|---------|
+| `list-triggers.js` | List triggers for a workflow |
+| `create-trigger.js` | Create a trigger |
+| `update-trigger.js` | Enable/disable a trigger |
+| `delete-trigger.js` | Delete a trigger |
+| `list-whatsapp-phone-numbers.js` | List phone numbers for trigger setup |
+
+### Executions
+
+| Script | Purpose |
+|--------|---------|
+| `list-executions.js` | List executions |
+| `get-execution.js` | Get execution details |
+| `get-context-value.js` | Read value from execution context |
+| `update-execution-status.js` | Force execution state |
+| `resume-execution.js` | Resume waiting execution |
+| `list-execution-events.js` | List execution events |
+
+### Functions
+
+| Script | Purpose |
+|--------|---------|
+| `list-functions.js` | List project functions |
+| `get-function.js` | Get function details + code |
+| `create-function.js` | Create a function |
+| `update-function.js` | Update function code |
+| `deploy-function.js` | Deploy function to runtime |
+| `invoke-function.js` | Invoke function with payload |
+| `list-function-invocations.js` | List function invocations |
+
+### App integrations
+
+| Script | Purpose |
+|--------|---------|
+| `list-apps.js` | Search integration apps |
+| `search-actions.js` | Search actions (action_id = key) |
+| `get-action-schema.js` | Get action JSON schema |
+| `list-accounts.js` | List connected accounts |
+| `create-connect-token.js` | Create OAuth connect link |
+| `configure-prop.js` | Resolve remote_options for a prop |
+| `reload-props.js` | Reload dynamic props |
+| `list-integrations.js` | List saved integrations |
+| `create-integration.js` | Create an integration |
+| `update-integration.js` | Update an integration |
+| `delete-integration.js` | Delete an integration |
+
+### Databases
+
+| Script | Purpose |
+|--------|---------|
+| `list-tables.js` | List D1 tables |
+| `get-table.js` | Get table schema + sample rows |
+| `query-rows.js` | Query rows with filters |
+| `create-row.js` | Create a row |
+| `update-row.js` | Update rows |
+| `upsert-row.js` | Upsert a row |
+| `delete-row.js` | Delete rows |
+
+### OpenAPI
+
+| Script | Purpose |
+|--------|---------|
+| `openapi-explore.mjs` | Explore OpenAPI (search/op/schema/where) |
+
+Install deps (once):
+```bash
+npm i
+```
+
+Examples:
+```bash
+node scripts/openapi-explore.mjs --spec workflows search "variables"
+node scripts/openapi-explore.mjs --spec workflows op getWorkflowVariables
+node scripts/openapi-explore.mjs --spec platform op queryDatabaseRows
+```
+
+## Notes
+
+- Prefer file paths over inline JSON (`--definition-file`, `--code-file`)
+- `action_id` is the same as `key` from `search-actions`
+- `--account-id` uses `pipedream_account_id` from `list-accounts`
+- Variable CRUD (`variables-set.js`, `variables-delete.js`) is blocked - Platform API doesn't support it
+- Raw SQL execution is not supported via Platform API
+
+## References
+
+Read before editing:
+- [references/graph-contract.md](references/graph-contract.md) - Graph schema, computed vs editable fields, lock_version
+- [references/node-types.md](references/node-types.md) - Node types and config shapes
+- [references/workflow-overview.md](references/workflow-overview.md) - Execution flow and states
+
+Other references:
+- [references/execution-context.md](references/execution-context.md) - Context structure and variable substitution
+- [references/triggers.md](references/triggers.md) - Trigger types and setup
+- [references/app-integrations.md](references/app-integrations.md) - App integration and variable_definitions
+- [references/functions-reference.md](references/functions-reference.md) - Function management
+- [references/functions-payloads.md](references/functions-payloads.md) - Payload shapes for functions
+- [references/databases-reference.md](references/databases-reference.md) - Database operations
+
+## Assets
+
+| File | Description |
+|------|-------------|
+| `workflow-linear.json` | Minimal linear workflow |
+| `workflow-decision.json` | Minimal branching workflow |
+| `workflow-agent-simple.json` | Minimal agent workflow |
+| `workflow-customer-support-intake-agent.json` | Customer support intake |
+| `workflow-interactive-buttons-decide-function.json` | Interactive buttons + decide (function) |
+| `workflow-interactive-buttons-decide-ai.json` | Interactive buttons + decide (AI) |
+| `workflow-api-template-wait-agent.json` | API trigger + template + agent |
+| `function-decide-route-interactive-buttons.json` | Function for button routing |
+| `agent-app-integration-example.json` | Agent node with app integrations |
+
+## Related skills
+
+- `integrate-whatsapp` - Onboarding, webhooks, messaging, templates, flows
+- `observe-whatsapp` - Debugging, logs, health checks
+
+<!-- FILEMAP:BEGIN -->
+```text
+[automate-whatsapp file map]|root: .
+|.:{package.json,SKILL.md}
+|assets:{agent-app-integration-example.json,databases-example.json,function-decide-route-interactive-buttons.json,functions-example.json,workflow-agent-simple.json,workflow-api-template-wait-agent.json,workflow-customer-support-intake-agent.json,workflow-decision.json,workflow-interactive-buttons-decide-ai.json,workflow-interactive-buttons-decide-function.json,workflow-linear.json}
+|references:{app-integrations.md,databases-reference.md,execution-context.md,function-contracts.md,functions-payloads.md,functions-reference.md,graph-contract.md,node-types.md,triggers.md,workflow-overview.md,workflow-reference.md}
+|scripts:{configure-prop.js,create-connect-token.js,create-function.js,create-integration.js,create-row.js,create-trigger.js,create-workflow.js,delete-integration.js,delete-row.js,delete-trigger.js,deploy-function.js,edit-graph.js,get-action-schema.js,get-context-value.js,get-execution-event.js,get-execution.js,get-function.js,get-graph.js,get-table.js,get-workflow.js,invoke-function.js,list-accounts.js,list-apps.js,list-execution-events.js,list-executions.js,list-function-invocations.js,list-functions.js,list-integrations.js,list-provider-models.js,list-tables.js,list-triggers.js,list-whatsapp-phone-numbers.js,list-workflows.js,openapi-explore.mjs,query-rows.js,reload-props.js,resume-execution.js,search-actions.js,update-execution-status.js,update-function.js,update-graph.js,update-integration.js,update-row.js,update-trigger.js,update-workflow-settings.js,upsert-row.js,validate-graph.js,variables-delete.js,variables-list.js,variables-set.js}
+|scripts/lib/databases:{args.js,filters.js,kapso-api.js}
+|scripts/lib/functions:{args.js,kapso-api.js}
+|scripts/lib/workflows:{args.js,kapso-api.js,result.js}
+```
+<!-- FILEMAP:END -->
+

skills/aws-skills/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: aws-skills
+description: "AWS development with infrastructure automation and cloud architecture patterns"
+source: "https://github.com/zxkane/aws-skills"
+risk: safe
+---
+
+# Aws Skills
+
+## Overview
+
+AWS development with infrastructure automation and cloud architecture patterns
+
+## When to Use This Skill
+
+Use this skill when you need to work with aws development with infrastructure automation and cloud architecture patterns.
+
+## Instructions
+
+This skill provides guidance and patterns for aws development with infrastructure automation and cloud architecture patterns.
+
+For more information, see the [source repository](https://github.com/zxkane/aws-skills).

skills/beautiful-prose/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: beautiful-prose
+description: "Hard-edged writing style contract for timeless, forceful English prose without AI tics"
+source: "https://github.com/SHADOWPR0/beautiful_prose"
+risk: safe
+---
+
+# Beautiful Prose
+
+## Overview
+
+Hard-edged writing style contract for timeless, forceful English prose without AI tics
+
+## When to Use This Skill
+
+Use this skill when you need to work with hard-edged writing style contract for timeless, forceful english prose without ai tics.
+
+## Instructions
+
+This skill provides guidance and patterns for hard-edged writing style contract for timeless, forceful english prose without ai tics.
+
+For more information, see the [source repository](https://github.com/SHADOWPR0/beautiful_prose).

skills/changelog-automation/resources/implementation-playbook.md

@@ -292,7 +292,7 @@ jobs:
         uses: softprops/action-gh-release@v1
         with:
           tag_name: ${{ steps.version.outputs.tag }}
-          body_path: RELEASE_NOTES.md
+          body_path: CHANGELOG.md
           generate_release_notes: true
 ```
 
@@ -368,7 +368,7 @@ repo = "repo"
 git cliff -o CHANGELOG.md
 
 # Generate for specific range
-git cliff v1.0.0..v2.0.0 -o RELEASE_NOTES.md
+git cliff v1.0.0..v2.0.0 -o CHANGELOG.md
 
 # Preview without writing
 git cliff --unreleased --dry-run

skills/clarity-gate/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: clarity-gate
+description: "Pre-ingestion verification for epistemic quality in RAG systems with 9-point verification and Two-Round HITL workflow"
+source: "https://github.com/frmoretto/clarity-gate"
+risk: safe
+---
+
+# Clarity Gate
+
+## Overview
+
+Pre-ingestion verification for epistemic quality in RAG systems with 9-point verification and Two-Round HITL workflow
+
+## When to Use This Skill
+
+Use this skill when you need to work with pre-ingestion verification for epistemic quality in rag systems with 9-point verification and two-round hitl workflow.
+
+## Instructions
+
+This skill provides guidance and patterns for pre-ingestion verification for epistemic quality in rag systems with 9-point verification and two-round hitl workflow.
+
+For more information, see the [source repository](https://github.com/frmoretto/clarity-gate).

skills/claude-ally-health/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: claude-ally-health
+description: "A health assistant skill for medical information analysis, symptom tracking, and wellness guidance."
+source: "https://github.com/huifer/Claude-Ally-Health"
+risk: safe
+---
+
+# Claude Ally Health
+
+## Overview
+
+A health assistant skill for medical information analysis, symptom tracking, and wellness guidance.
+
+## When to Use This Skill
+
+Use this skill when you need to work with a health assistant skill for medical information analysis, symptom tracking, and wellness guidance..
+
+## Instructions
+
+This skill provides guidance and patterns for a health assistant skill for medical information analysis, symptom tracking, and wellness guidance..
+
+For more information, see the [source repository](https://github.com/huifer/Claude-Ally-Health).

skills/claude-scientific-skills/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: claude-scientific-skills
+description: "Scientific research and analysis skills"
+source: "https://github.com/K-Dense-AI/claude-scientific-skills"
+risk: safe
+---
+
+# Claude Scientific Skills
+
+## Overview
+
+Scientific research and analysis skills
+
+## When to Use This Skill
+
+Use this skill when you need to work with scientific research and analysis skills.
+
+## Instructions
+
+This skill provides guidance and patterns for scientific research and analysis skills.
+
+For more information, see the [source repository](https://github.com/K-Dense-AI/claude-scientific-skills).

skills/claude-speed-reader/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: claude-speed-reader
+description: "-Speed read Claude's responses at 600+ WPM using RSVP with Spritz-style ORP highlighting"
+source: "https://github.com/SeanZoR/claude-speed-reader"
+risk: safe
+---
+
+# Claude Speed Reader
+
+## Overview
+
+-Speed read Claude's responses at 600+ WPM using RSVP with Spritz-style ORP highlighting
+
+## When to Use This Skill
+
+Use this skill when you need to work with -speed read claude's responses at 600+ wpm using rsvp with spritz-style orp highlighting.
+
+## Instructions
+
+This skill provides guidance and patterns for -speed read claude's responses at 600+ wpm using rsvp with spritz-style orp highlighting.
+
+For more information, see the [source repository](https://github.com/SeanZoR/claude-speed-reader).

skills/claude-win11-speckit-update-skill/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: claude-win11-speckit-update-skill
+description: "Windows 11 system management"
+source: "https://github.com/NotMyself/claude-win11-speckit-update-skill"
+risk: safe
+---
+
+# Claude Win11 Speckit Update Skill
+
+## Overview
+
+Windows 11 system management
+
+## When to Use This Skill
+
+Use this skill when you need to work with windows 11 system management.
+
+## Instructions
+
+This skill provides guidance and patterns for windows 11 system management.
+
+For more information, see the [source repository](https://github.com/NotMyself/claude-win11-speckit-update-skill).

skills/commit/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: commit
+description: "Create commit messages following Sentry conventions. Use when committing code changes, writing commit messages, or formatting git history. Follows conventional commits with Sentry-specific issue references."
+source: "https://github.com/getsentry/skills/tree/main/plugins/sentry-skills/skills/commit"
+risk: safe
+---
+
+# Sentry Commit Messages
+
+Follow these conventions when creating commits for Sentry projects.
+
+## When to Use This Skill
+
+Use this skill when:
+- Committing code changes
+- Writing commit messages
+- Formatting git history
+- Following Sentry commit conventions
+- Referencing Sentry issues in commits
+
+## Prerequisites
+
+Before committing, ensure you're working on a feature branch, not the main branch.
+
+```bash
+# Check current branch
+git branch --show-current
+```
+
+If you're on `main` or `master`, create a new branch first:
+
+```bash
+# Create and switch to a new branch
+git checkout -b <type>/<short-description>
+```
+
+Branch naming should follow the pattern: `<type>/<short-description>` where type matches the commit type (e.g., `feat/add-user-auth`, `fix/null-pointer-error`, `ref/extract-validation`).
+
+## Format
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+The header is required. Scope is optional. All lines must stay under 100 characters.
+
+## Commit Types
+
+| Type | Purpose |
+|------|---------|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `ref` | Refactoring (no behavior change) |
+| `perf` | Performance improvement |
+| `docs` | Documentation only |
+| `test` | Test additions or corrections |
+| `build` | Build system or dependencies |
+| `ci` | CI configuration |
+| `chore` | Maintenance tasks |
+| `style` | Code formatting (no logic change) |
+| `meta` | Repository metadata |
+| `license` | License changes |
+
+## Subject Line Rules
+
+- Use imperative, present tense: "Add feature" not "Added feature"
+- Capitalize the first letter
+- No period at the end
+- Maximum 70 characters
+
+## Body Guidelines
+
+- Explain **what** and **why**, not how
+- Use imperative mood and present tense
+- Include motivation for the change
+- Contrast with previous behavior when relevant
+
+## Footer: Issue References
+
+Reference issues in the footer using these patterns:
+
+```
+Fixes GH-1234
+Fixes #1234
+Fixes SENTRY-1234
+Refs LINEAR-ABC-123
+```
+
+- `Fixes` closes the issue when merged
+- `Refs` links without closing
+
+## AI-Generated Changes
+
+When changes were primarily generated by a coding agent (like Claude Code), include the Co-Authored-By attribution in the commit footer:
+
+```
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+This is the only indicator of AI involvement that should appear in commits. Do not add phrases like "Generated by AI", "Written with Claude", or similar markers in the subject, body, or anywhere else in the commit message.
+
+## Examples
+
+### Simple fix
+
+```
+fix(api): Handle null response in user endpoint
+
+The user API could return null for deleted accounts, causing a crash
+in the dashboard. Add null check before accessing user properties.
+
+Fixes SENTRY-5678
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+### Feature with scope
+
+```
+feat(alerts): Add Slack thread replies for alert updates
+
+When an alert is updated or resolved, post a reply to the original
+Slack thread instead of creating a new message. This keeps related
+notifications grouped together.
+
+Refs GH-1234
+```
+
+### Refactor
+
+```
+ref: Extract common validation logic to shared module
+
+Move duplicate validation code from three endpoints into a shared
+validator class. No behavior change.
+```
+
+### Breaking change
+
+```
+feat(api)!: Remove deprecated v1 endpoints
+
+Remove all v1 API endpoints that were deprecated in version 23.1.
+Clients should migrate to v2 endpoints.
+
+BREAKING CHANGE: v1 endpoints no longer available
+Fixes SENTRY-9999
+```
+
+## Revert Format
+
+```
+revert: feat(api): Add new endpoint
+
+This reverts commit abc123def456.
+
+Reason: Caused performance regression in production.
+```
+
+## Principles
+
+- Each commit should be a single, stable change
+- Commits should be independently reviewable
+- The repository should be in a working state after each commit
+
+## References
+
+- [Sentry Commit Messages](https://develop.sentry.dev/engineering-practices/commit-messages/)

skills/context-compression/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: context-compression
+description: "Design and evaluate compression strategies for long-running sessions"
+source: "https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering/tree/main/skills/context-compression"
+risk: safe
+---
+# Context Compression Strategies
+
+When agent sessions generate millions of tokens of conversation history, compression becomes mandatory. The naive approach is aggressive compression to minimize tokens per request. The correct optimization target is tokens per task: total tokens consumed to complete a task, including re-fetching costs when compression loses critical information.
+
+## When to Activate
+
+Activate this skill when:
+- Agent sessions exceed context window limits
+- Codebases exceed context windows (5M+ token systems)
+- Designing conversation summarization strategies
+- Debugging cases where agents "forget" what files they modified
+- Building evaluation frameworks for compression quality
+
+## Core Concepts
+
+Context compression trades token savings against information loss. Three production-ready approaches exist:
+
+1. **Anchored Iterative Summarization**: Maintain structured, persistent summaries with explicit sections for session intent, file modifications, decisions, and next steps. When compression triggers, summarize only the newly-truncated span and merge with the existing summary. Structure forces preservation by dedicating sections to specific information types.
+
+2. **Opaque Compression**: Produce compressed representations optimized for reconstruction fidelity. Achieves highest compression ratios (99%+) but sacrifices interpretability. Cannot verify what was preserved.
+
+3. **Regenerative Full Summary**: Generate detailed structured summaries on each compression. Produces readable output but may lose details across repeated compression cycles due to full regeneration rather than incremental merging.
+
+The critical insight: structure forces preservation. Dedicated sections act as checklists that the summarizer must populate, preventing silent information drift.
+
+## Detailed Topics
+
+### Why Tokens-Per-Task Matters
+
+Traditional compression metrics target tokens-per-request. This is the wrong optimization. When compression loses critical details like file paths or error messages, the agent must re-fetch information, re-explore approaches, and waste tokens recovering context.
+
+The right metric is tokens-per-task: total tokens consumed from task start to completion. A compression strategy saving 0.5% more tokens but causing 20% more re-fetching costs more overall.
+
+### The Artifact Trail Problem
+
+Artifact trail integrity is the weakest dimension across all compression methods, scoring 2.2-2.5 out of 5.0 in evaluations. Even structured summarization with explicit file sections struggles to maintain complete file tracking across long sessions.
+
+Coding agents need to know:
+- Which files were created
+- Which files were modified and what changed
+- Which files were read but not changed
+- Function names, variable names, error messages
+
+This problem likely requires specialized handling beyond general summarization: a separate artifact index or explicit file-state tracking in agent scaffolding.
+
+### Structured Summary Sections
+
+Effective structured summaries include explicit sections:
+
+```markdown
+## Session Intent
+[What the user is trying to accomplish]
+
+## Files Modified
+- auth.controller.ts: Fixed JWT token generation
+- config/redis.ts: Updated connection pooling
+- tests/auth.test.ts: Added mock setup for new config
+
+## Decisions Made
+- Using Redis connection pool instead of per-request connections
+- Retry logic with exponential backoff for transient failures
+
+## Current State
+- 14 tests passing, 2 failing
+- Remaining: mock setup for session service tests
+
+## Next Steps
+1. Fix remaining test failures
+2. Run full test suite
+3. Update documentation
+```
+
+This structure prevents silent loss of file paths or decisions because each section must be explicitly addressed.
+
+### Compression Trigger Strategies
+
+When to trigger compression matters as much as how to compress:
+
+| Strategy | Trigger Point | Trade-off |
+|----------|---------------|-----------|
+| Fixed threshold | 70-80% context utilization | Simple but may compress too early |
+| Sliding window | Keep last N turns + summary | Predictable context size |
+| Importance-based | Compress low-relevance sections first | Complex but preserves signal |
+| Task-boundary | Compress at logical task completions | Clean summaries but unpredictable timing |
+
+The sliding window approach with structured summaries provides the best balance of predictability and quality for most coding agent use cases.
+
+### Probe-Based Evaluation
+
+Traditional metrics like ROUGE or embedding similarity fail to capture functional compression quality. A summary may score high on lexical overlap while missing the one file path the agent needs.
+
+Probe-based evaluation directly measures functional quality by asking questions after compression:
+
+| Probe Type | What It Tests | Example Question |
+|------------|---------------|------------------|
+| Recall | Factual retention | "What was the original error message?" |
+| Artifact | File tracking | "Which files have we modified?" |
+| Continuation | Task planning | "What should we do next?" |
+| Decision | Reasoning chain | "What did we decide about the Redis issue?" |
+
+If compression preserved the right information, the agent answers correctly. If not, it guesses or hallucinates.
+
+### Evaluation Dimensions
+
+Six dimensions capture compression quality for coding agents:
+
+1. **Accuracy**: Are technical details correct? File paths, function names, error codes.
+2. **Context Awareness**: Does the response reflect current conversation state?
+3. **Artifact Trail**: Does the agent know which files were read or modified?
+4. **Completeness**: Does the response address all parts of the question?
+5. **Continuity**: Can work continue without re-fetching information?
+6. **Instruction Following**: Does the response respect stated constraints?
+
+Accuracy shows the largest variation between compression methods (0.6 point gap). Artifact trail is universally weak (2.2-2.5 range).
+
+## Practical Guidance
+
+### Three-Phase Compression Workflow
+
+For large codebases or agent systems exceeding context windows, apply compression through three phases:
+
+1. **Research Phase**: Produce a research document from architecture diagrams, documentation, and key interfaces. Compress exploration into a structured analysis of components and dependencies. Output: single research document.
+
+2. **Planning Phase**: Convert research into implementation specification with function signatures, type definitions, and data flow. A 5M token codebase compresses to approximately 2,000 words of specification.
+
+3. **Implementation Phase**: Execute against the specification. Context remains focused on the spec rather than raw codebase exploration.
+
+### Using Example Artifacts as Seeds
+
+When provided with a manual migration example or reference PR, use it as a template to understand the target pattern. The example reveals constraints that static analysis cannot surface: which invariants must hold, which services break on changes, and what a clean migration looks like.
+
+This is particularly important when the agent cannot distinguish essential complexity (business requirements) from accidental complexity (legacy workarounds). The example artifact encodes that distinction.
+
+### Implementing Anchored Iterative Summarization
+
+1. Define explicit summary sections matching your agent's needs
+2. On first compression trigger, summarize truncated history into sections
+3. On subsequent compressions, summarize only new truncated content
+4. Merge new summary into existing sections rather than regenerating
+5. Track which information came from which compression cycle for debugging
+
+### When to Use Each Approach
+
+**Use anchored iterative summarization when:**
+- Sessions are long-running (100+ messages)
+- File tracking matters (coding, debugging)
+- You need to verify what was preserved
+
+**Use opaque compression when:**
+- Maximum token savings required
+- Sessions are relatively short
+- Re-fetching costs are low
+
+**Use regenerative summaries when:**
+- Summary interpretability is critical
+- Sessions have clear phase boundaries
+- Full context review is acceptable on each compression
+
+### Compression Ratio Considerations
+
+| Method | Compression Ratio | Quality Score | Trade-off |
+|--------|-------------------|---------------|-----------|
+| Anchored Iterative | 98.6% | 3.70 | Best quality, slightly less compression |
+| Regenerative | 98.7% | 3.44 | Good quality, moderate compression |
+| Opaque | 99.3% | 3.35 | Best compression, quality loss |
+
+The 0.7% additional tokens retained by structured summarization buys 0.35 quality points. For any task where re-fetching costs matter, this trade-off favors structured approaches.
+
+## Examples
+
+**Example 1: Debugging Session Compression**
+
+Original context (89,000 tokens, 178 messages):
+- 401 error on /api/auth/login endpoint
+- Traced through auth controller, middleware, session store
+- Found stale Redis connection
+- Fixed connection pooling, added retry logic
+- 14 tests passing, 2 failing
+
+Structured summary after compression:
+
+```markdown
+## Session Intent
+Debug 401 Unauthorized error on /api/auth/login despite valid credentials.
+
+## Root Cause
+Stale Redis connection in session store. JWT generated correctly but session could not be persisted.
+
+## Files Modified
+- auth.controller.ts: No changes (read only)
+- middleware/cors.ts: No changes (examined)
+- config/redis.ts: Fixed connection pooling configuration
+- services/session.service.ts: Added retry logic for transient failures
+- tests/auth.test.ts: Updated mock setup
+
+## Test Status
+14 passing, 2 failing (mock setup issues)
+
+## Next Steps
+1. Fix remaining test failures (mock session service)
+2. Run full test suite
+3. Deploy to staging
+```
+
+**Example 2: Probe Response Quality**
+
+After compression, asking "What was the original error?":
+
+Good response (structured summarization):
+> "The original error was a 401 Unauthorized response from the /api/auth/login endpoint. Users received this error with valid credentials. Root cause was stale Redis connection in session store."
+
+Poor response (aggressive compression):
+> "We were debugging an authentication issue. The login was failing. We fixed some configuration problems."
+
+The structured response preserves endpoint, error code, and root cause. The aggressive response loses all technical detail.
+
+## Guidelines
+
+1. Optimize for tokens-per-task, not tokens-per-request
+2. Use structured summaries with explicit sections for file tracking
+3. Trigger compression at 70-80% context utilization
+4. Implement incremental merging rather than full regeneration
+5. Test compression quality with probe-based evaluation
+6. Track artifact trail separately if file tracking is critical
+7. Accept slightly lower compression ratios for better quality retention
+8. Monitor re-fetching frequency as a compression quality signal
+
+## Integration
+
+This skill connects to several others in the collection:
+
+- context-degradation - Compression is a mitigation strategy for degradation
+- context-optimization - Compression is one optimization technique among many
+- evaluation - Probe-based evaluation applies to compression testing
+- memory-systems - Compression relates to scratchpad and summary memory patterns
+
+## References
+
+Internal reference:
+- [Evaluation Framework Reference](./references/evaluation-framework.md) - Detailed probe types and scoring rubrics
+
+Related skills in this collection:
+- context-degradation - Understanding what compression prevents
+- context-optimization - Broader optimization strategies
+- evaluation - Building evaluation frameworks
+
+External resources:
+- Factory Research: Evaluating Context Compression for AI Agents (December 2025)
+- Research on LLM-as-judge evaluation methodology (Zheng et al., 2023)
+- Netflix Engineering: "The Infinite Software Crisis" - Three-phase workflow and context compression at scale (AI Summit 2025)
+
+---
+
+## Skill Metadata
+
+**Created**: 2025-12-22
+**Last Updated**: 2025-12-26
+**Author**: Agent Skills for Context Engineering Contributors
+**Version**: 1.1.0
+

skills/context-degradation/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: context-degradation
+description: "Recognize patterns of context failure: lost-in-middle, poisoning, distraction, and clash"
+source: "https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering/tree/main/skills/context-degradation"
+risk: safe
+---
+
+## When to Use This Skill
+
+Recognize patterns of context failure: lost-in-middle, poisoning, distraction, and clash
+
+Use this skill when working with recognize patterns of context failure: lost-in-middle, poisoning, distraction, and clash.
+# Context Degradation Patterns
+
+Language models exhibit predictable degradation patterns as context length increases. Understanding these patterns is essential for diagnosing failures and designing resilient systems. Context degradation is not a binary state but a continuum of performance degradation that manifests in several distinct ways.
+
+## When to Activate
+
+Activate this skill when:
+- Agent performance degrades unexpectedly during long conversations
+- Debugging cases where agents produce incorrect or irrelevant outputs
+- Designing systems that must handle large contexts reliably
+- Evaluating context engineering choices for production systems
+- Investigating "lost in middle" phenomena in agent outputs
+- Analyzing context-related failures in agent behavior
+
+## Core Concepts
+
+Context degradation manifests through several distinct patterns. The lost-in-middle phenomenon causes information in the center of context to receive less attention. Context poisoning occurs when errors compound through repeated reference. Context distraction happens when irrelevant information overwhelms relevant content. Context confusion arises when the model cannot determine which context applies. Context clash develops when accumulated information directly conflicts.
+
+These patterns are predictable and can be mitigated through architectural patterns like compaction, masking, partitioning, and isolation.
+
+## Detailed Topics
+
+### The Lost-in-Middle Phenomenon
+
+The most well-documented degradation pattern is the "lost-in-middle" effect, where models demonstrate U-shaped attention curves. Information at the beginning and end of context receives reliable attention, while information buried in the middle suffers from dramatically reduced recall accuracy.
+
+**Empirical Evidence**
+Research demonstrates that relevant information placed in the middle of context experiences 10-40% lower recall accuracy compared to the same information at the beginning or end. This is not a failure of the model but a consequence of attention mechanics and training data distributions.
+
+Models allocate massive attention to the first token (often the BOS token) to stabilize internal states. This creates an "attention sink" that soaks up attention budget. As context grows, the limited budget is stretched thinner, and middle tokens fail to garner sufficient attention weight for reliable retrieval.
+
+**Practical Implications**
+Design context placement with attention patterns in mind. Place critical information at the beginning or end of context. Consider whether information will be queried directly or needs to support reasoning—if the latter, placement matters less but overall signal quality matters more.
+
+For long documents or conversations, use summary structures that surface key information at attention-favored positions. Use explicit section headers and transitions to help models navigate structure.
+
+### Context Poisoning
+
+Context poisoning occurs when hallucinations, errors, or incorrect information enters context and compounds through repeated reference. Once poisoned, context creates feedback loops that reinforce incorrect beliefs.
+
+**How Poisoning Occurs**
+Poisoning typically enters through three pathways. First, tool outputs may contain errors or unexpected formats that models accept as ground truth. Second, retrieved documents may contain incorrect or outdated information that models incorporate into reasoning. Third, model-generated summaries or intermediate outputs may introduce hallucinations that persist in context.
+
+The compounding effect is severe. If an agent's goals section becomes poisoned, it develops strategies that take substantial effort to undo. Each subsequent decision references the poisoned content, reinforcing incorrect assumptions.
+
+**Detection and Recovery**
+Watch for symptoms including degraded output quality on tasks that previously succeeded, tool misalignment where agents call wrong tools or parameters, and hallucinations that persist despite correction attempts. When these symptoms appear, consider context poisoning.
+
+Recovery requires removing or replacing poisoned content. This may involve truncating context to before the poisoning point, explicitly noting the poisoning in context and asking for re-evaluation, or restarting with clean context and preserving only verified information.
+
+### Context Distraction
+
+Context distraction emerges when context grows so long that models over-focus on provided information at the expense of their training knowledge. The model attends to everything in context regardless of relevance, and this creates pressure to use provided information even when internal knowledge is more accurate.
+
+**The Distractor Effect**
+Research shows that even a single irrelevant document in context reduces performance on tasks involving relevant documents. Multiple distractors compound degradation. The effect is not about noise in absolute terms but about attention allocation—irrelevant information competes with relevant information for limited attention budget.
+
+Models do not have a mechanism to "skip" irrelevant context. They must attend to everything provided, and this obligation creates distraction even when the irrelevant information is clearly not useful.
+
+**Mitigation Strategies**
+Mitigate distraction through careful curation of what enters context. Apply relevance filtering before loading retrieved documents. Use namespacing and organization to make irrelevant sections easy to ignore structurally. Consider whether information truly needs to be in context or can be accessed through tool calls instead.
+
+### Context Confusion
+
+Context confusion arises when irrelevant information influences responses in ways that degrade quality. This is related to distraction but distinct—confusion concerns the influence of context on model behavior rather than attention allocation.
+
+If you put something in context, the model has to pay attention to it. The model may incorporate irrelevant information, use inappropriate tool definitions, or apply constraints that came from different contexts. Confusion is especially problematic when context contains multiple task types or when switching between tasks within a single session.
+
+**Signs of Confusion**
+Watch for responses that address the wrong aspect of a query, tool calls that seem appropriate for a different task, or outputs that mix requirements from multiple sources. These indicate confusion about what context applies to the current situation.
+
+**Architectural Solutions**
+Architectural solutions include explicit task segmentation where different tasks get different context windows, clear transitions between task contexts, and state management that isolates context for different objectives.
+
+### Context Clash
+
+Context clash develops when accumulated information directly conflicts, creating contradictory guidance that derails reasoning. This differs from poisoning where one piece of information is incorrect—in clash, multiple correct pieces of information contradict each other.
+
+**Sources of Clash**
+Clash commonly arises from multi-source retrieval where different sources have contradictory information, version conflicts where outdated and current information both appear in context, and perspective conflicts where different viewpoints are valid but incompatible.
+
+**Resolution Approaches**
+Resolution approaches include explicit conflict marking that identifies contradictions and requests clarification, priority rules that establish which source takes precedence, and version filtering that excludes outdated information from context.
+
+### Empirical Benchmarks and Thresholds
+
+Research provides concrete data on degradation patterns that inform design decisions.
+
+**RULER Benchmark Findings**
+The RULER benchmark delivers sobering findings: only 50% of models claiming 32K+ context maintain satisfactory performance at 32K tokens. GPT-5.2 shows the least degradation among current models, while many still drop 30+ points at extended contexts. Near-perfect scores on simple needle-in-haystack tests do not translate to real long-context understanding.
+
+**Model-Specific Degradation Thresholds**
+| Model | Degradation Onset | Severe Degradation | Notes |
+|-------|-------------------|-------------------|-------|
+| GPT-5.2 | ~64K tokens | ~200K tokens | Best overall degradation resistance with thinking mode |
+| Claude Opus 4.5 | ~100K tokens | ~180K tokens | 200K context window, strong attention management |
+| Claude Sonnet 4.5 | ~80K tokens | ~150K tokens | Optimized for agents and coding tasks |
+| Gemini 3 Pro | ~500K tokens | ~800K tokens | 1M context window, native multimodality |
+| Gemini 3 Flash | ~300K tokens | ~600K tokens | 3x speed of Gemini 2.5, 81.2% MMMU-Pro |
+
+**Model-Specific Behavior Patterns**
+Different models exhibit distinct failure modes under context pressure:
+
+- **Claude 4.5 series**: Lowest hallucination rates with calibrated uncertainty. Claude Opus 4.5 achieves 80.9% on SWE-bench Verified. Tends to refuse or ask clarification rather than fabricate.
+- **GPT-5.2**: Two modes available - instant (fast) and thinking (reasoning). Thinking mode reduces hallucination through step-by-step verification but increases latency.
+- **Gemini 3 Pro/Flash**: Native multimodality with 1M context window. Gemini 3 Flash offers 3x speed improvement over previous generation. Strong at multi-modal reasoning across text, code, images, audio, and video.
+
+These patterns inform model selection for different use cases. High-stakes tasks benefit from Claude 4.5's conservative approach or GPT-5.2's thinking mode; speed-critical tasks may use instant modes.
+
+### Counterintuitive Findings
+
+Research reveals several counterintuitive patterns that challenge assumptions about context management.
+
+**Shuffled Haystacks Outperform Coherent Ones**
+Studies found that shuffled (incoherent) haystacks produce better performance than logically coherent ones. This suggests that coherent context may create false associations that confuse retrieval, while incoherent context forces models to rely on exact matching.
+
+**Single Distractors Have Outsized Impact**
+Even a single irrelevant document reduces performance significantly. The effect is not proportional to the amount of noise but follows a step function where the presence of any distractor triggers degradation.
+
+**Needle-Question Similarity Correlation**
+Lower similarity between needle and question pairs shows faster degradation with context length. Tasks requiring inference across dissimilar content are particularly vulnerable.
+
+### When Larger Contexts Hurt
+
+Larger context windows do not uniformly improve performance. In many cases, larger contexts create new problems that outweigh benefits.
+
+**Performance Degradation Curves**
+Models exhibit non-linear degradation with context length. Performance remains stable up to a threshold, then degrades rapidly. The threshold varies by model and task complexity. For many models, meaningful degradation begins around 8,000-16,000 tokens even when context windows support much larger sizes.
+
+**Cost Implications**
+Processing cost grows disproportionately with context length. The cost to process a 400K token context is not double the cost of 200K—it increases exponentially in both time and computing resources. For many applications, this makes large-context processing economically impractical.
+
+**Cognitive Load Metaphor**
+Even with an infinite context, asking a single model to maintain consistent quality across dozens of independent tasks creates a cognitive bottleneck. The model must constantly switch context between items, maintain a comparative framework, and ensure stylistic consistency. This is not a problem that more context solves.
+
+## Practical Guidance
+
+### The Four-Bucket Approach
+
+Four strategies address different aspects of context degradation:
+
+**Write**: Save context outside the window using scratchpads, file systems, or external storage. This keeps active context lean while preserving information access.
+
+**Select**: Pull relevant context into the window through retrieval, filtering, and prioritization. This addresses distraction by excluding irrelevant information.
+
+**Compress**: Reduce tokens while preserving information through summarization, abstraction, and observation masking. This extends effective context capacity.
+
+**Isolate**: Split context across sub-agents or sessions to prevent any single context from growing large enough to degrade. This is the most aggressive strategy but often the most effective.
+
+### Architectural Patterns
+
+Implement these strategies through specific architectural patterns. Use just-in-time context loading to retrieve information only when needed. Use observation masking to replace verbose tool outputs with compact references. Use sub-agent architectures to isolate context for different tasks. Use compaction to summarize growing context before it exceeds limits.
+
+## Examples
+
+**Example 1: Detecting Degradation**
+```yaml
+# Context grows during long conversation
+turn_1: 1000 tokens
+turn_5: 8000 tokens
+turn_10: 25000 tokens
+turn_20: 60000 tokens (degradation begins)
+turn_30: 90000 tokens (significant degradation)
+```
+
+**Example 2: Mitigating Lost-in-Middle**
+```markdown
+# Organize context with critical info at edges
+
+[CURRENT TASK]                      # At start
+- Goal: Generate quarterly report
+- Deadline: End of week
+
+[DETAILED CONTEXT]                  # Middle (less attention)
+- 50 pages of data
+- Multiple analysis sections
+- Supporting evidence
+
+[KEY FINDINGS]                     # At end
+- Revenue up 15%
+- Costs down 8%
+- Growth in Region A
+```
+
+## Guidelines
+
+1. Monitor context length and performance correlation during development
+2. Place critical information at beginning or end of context
+3. Implement compaction triggers before degradation becomes severe
+4. Validate retrieved documents for accuracy before adding to context
+5. Use versioning to prevent outdated information from causing clash
+6. Segment tasks to prevent context confusion across different objectives
+7. Design for graceful degradation rather than assuming perfect conditions
+8. Test with progressively larger contexts to find degradation thresholds
+
+## Integration
+
+This skill builds on context-fundamentals and should be studied after understanding basic context concepts. It connects to:
+
+- context-optimization - Techniques for mitigating degradation
+- multi-agent-patterns - Using isolation to prevent degradation
+- evaluation - Measuring and detecting degradation in production
+
+## References
+
+Internal reference:
+- [Degradation Patterns Reference](./references/patterns.md) - Detailed technical reference
+
+Related skills in this collection:
+- context-fundamentals - Context basics
+- context-optimization - Mitigation techniques
+- evaluation - Detection and measurement
+
+External resources:
+- Research on attention mechanisms and context window limitations
+- Studies on the "lost-in-middle" phenomenon
+- Production engineering guides from AI labs
+
+---
+
+## Skill Metadata
+
+**Created**: 2025-12-20
+**Last Updated**: 2025-12-20
+**Author**: Agent Skills for Context Engineering Contributors
+**Version**: 1.0.0

skills/context-fundamentals/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: context-fundamentals
+description: "Understand what context is, why it matters, and the anatomy of context in agent systems"
+source: "https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering/tree/main/skills/context-fundamentals"
+risk: safe
+---
+
+## When to Use This Skill
+
+Understand what context is, why it matters, and the anatomy of context in agent systems
+
+Use this skill when working with understand what context is, why it matters, and the anatomy of context in agent systems.
+# Context Engineering Fundamentals
+
+Context is the complete state available to a language model at inference time. It includes everything the model can attend to when generating responses: system instructions, tool definitions, retrieved documents, message history, and tool outputs. Understanding context fundamentals is prerequisite to effective context engineering.
+
+## When to Activate
+
+Activate this skill when:
+- Designing new agent systems or modifying existing architectures
+- Debugging unexpected agent behavior that may relate to context
+- Optimizing context usage to reduce token costs or improve performance
+- Onboarding new team members to context engineering concepts
+- Reviewing context-related design decisions
+
+## Core Concepts
+
+Context comprises several distinct components, each with different characteristics and constraints. The attention mechanism creates a finite budget that constrains effective context usage. Progressive disclosure manages this constraint by loading information only as needed. The engineering discipline is curating the smallest high-signal token set that achieves desired outcomes.
+
+## Detailed Topics
+
+### The Anatomy of Context
+
+**System Prompts**
+System prompts establish the agent's core identity, constraints, and behavioral guidelines. They are loaded once at session start and typically persist throughout the conversation. System prompts should be extremely clear and use simple, direct language at the right altitude for the agent.
+
+The right altitude balances two failure modes. At one extreme, engineers hardcode complex brittle logic that creates fragility and maintenance burden. At the other extreme, engineers provide vague high-level guidance that fails to give concrete signals for desired outputs or falsely assumes shared context. The optimal altitude strikes a balance: specific enough to guide behavior effectively, yet flexible enough to provide strong heuristics.
+
+Organize prompts into distinct sections using XML tagging or Markdown headers to delineate background information, instructions, tool guidance, and output description. The exact formatting matters less as models become more capable, but structural clarity remains valuable.
+
+**Tool Definitions**
+Tool definitions specify the actions an agent can take. Each tool includes a name, description, parameters, and return format. Tool definitions live near the front of context after serialization, typically before or after the system prompt.
+
+Tool descriptions collectively steer agent behavior. Poor descriptions force agents to guess; optimized descriptions include usage context, examples, and defaults. The consolidation principle states that if a human engineer cannot definitively say which tool should be used in a given situation, an agent cannot be expected to do better.
+
+**Retrieved Documents**
+Retrieved documents provide domain-specific knowledge, reference materials, or task-relevant information. Agents use retrieval augmented generation to pull relevant documents into context at runtime rather than pre-loading all possible information.
+
+The just-in-time approach maintains lightweight identifiers (file paths, stored queries, web links) and uses these references to load data into context dynamically. This mirrors human cognition: we generally do not memorize entire corpuses of information but rather use external organization and indexing systems to retrieve relevant information on demand.
+
+**Message History**
+Message history contains the conversation between the user and agent, including previous queries, responses, and reasoning. For long-running tasks, message history can grow to dominate context usage.
+
+Message history serves as scratchpad memory where agents track progress, maintain task state, and preserve reasoning across turns. Effective management of message history is critical for long-horizon task completion.
+
+**Tool Outputs**
+Tool outputs are the results of agent actions: file contents, search results, command execution output, API responses, and similar data. Tool outputs comprise the majority of tokens in typical agent trajectories, with research showing observations (tool outputs) can reach 83.9% of total context usage.
+
+Tool outputs consume context whether they are relevant to current decisions or not. This creates pressure for strategies like observation masking, compaction, and selective tool result retention.
+
+### Context Windows and Attention Mechanics
+
+**The Attention Budget Constraint**
+Language models process tokens through attention mechanisms that create pairwise relationships between all tokens in context. For n tokens, this creates n² relationships that must be computed and stored. As context length increases, the model's ability to capture these relationships gets stretched thin.
+
+Models develop attention patterns from training data distributions where shorter sequences predominate. This means models have less experience with and fewer specialized parameters for context-wide dependencies. The result is an "attention budget" that depletes as context grows.
+
+**Position Encoding and Context Extension**
+Position encoding interpolation allows models to handle longer sequences by adapting them to originally trained smaller contexts. However, this adaptation introduces degradation in token position understanding. Models remain highly capable at longer contexts but show reduced precision for information retrieval and long-range reasoning compared to performance on shorter contexts.
+
+**The Progressive Disclosure Principle**
+Progressive disclosure manages context efficiently by loading information only as needed. At startup, agents load only skill names and descriptions—sufficient to know when a skill might be relevant. Full content loads only when a skill is activated for specific tasks.
+
+This approach keeps agents fast while giving them access to more context on demand. The principle applies at multiple levels: skill selection, document loading, and even tool result retrieval.
+
+### Context Quality Versus Context Quantity
+
+The assumption that larger context windows solve memory problems has been empirically debunked. Context engineering means finding the smallest possible set of high-signal tokens that maximize the likelihood of desired outcomes.
+
+Several factors create pressure for context efficiency. Processing cost grows disproportionately with context length—not just double the cost for double the tokens, but exponentially more in time and computing resources. Model performance degrades beyond certain context lengths even when the window technically supports more tokens. Long inputs remain expensive even with prefix caching.
+
+The guiding principle is informativity over exhaustiveness. Include what matters for the decision at hand, exclude what does not, and design systems that can access additional information on demand.
+
+### Context as Finite Resource
+
+Context must be treated as a finite resource with diminishing marginal returns. Like humans with limited working memory, language models have an attention budget drawn on when parsing large volumes of context.
+
+Every new token introduced depletes this budget by some amount. This creates the need for careful curation of available tokens. The engineering problem is optimizing utility against inherent constraints.
+
+Context engineering is iterative and the curation phase happens each time you decide what to pass to the model. It is not a one-time prompt writing exercise but an ongoing discipline of context management.
+
+## Practical Guidance
+
+### File-System-Based Access
+
+Agents with filesystem access can use progressive disclosure naturally. Store reference materials, documentation, and data externally. Load files only when needed using standard filesystem operations. This pattern avoids stuffing context with information that may not be relevant.
+
+The file system itself provides structure that agents can navigate. File sizes suggest complexity; naming conventions hint at purpose; timestamps serve as proxies for relevance. Metadata of file references provides a mechanism to efficiently refine behavior.
+
+### Hybrid Strategies
+
+The most effective agents employ hybrid strategies. Pre-load some context for speed (like CLAUDE.md files or project rules), but enable autonomous exploration for additional context as needed. The decision boundary depends on task characteristics and context dynamics.
+
+For contexts with less dynamic content, pre-loading more upfront makes sense. For rapidly changing or highly specific information, just-in-time loading avoids stale context.
+
+### Context Budgeting
+
+Design with explicit context budgets in mind. Know the effective context limit for your model and task. Monitor context usage during development. Implement compaction triggers at appropriate thresholds. Design systems assuming context will degrade rather than hoping it will not.
+
+Effective context budgeting requires understanding not just raw token counts but also attention distribution patterns. The middle of context receives less attention than the beginning and end. Place critical information at attention-favored positions.
+
+## Examples
+
+**Example 1: Organizing System Prompts**
+```markdown
+<BACKGROUND_INFORMATION>
+You are a Python expert helping a development team.
+Current project: Data processing pipeline in Python 3.9+
+</BACKGROUND_INFORMATION>
+
+<INSTRUCTIONS>
+- Write clean, idiomatic Python code
+- Include type hints for function signatures
+- Add docstrings for public functions
+- Follow PEP 8 style guidelines
+</INSTRUCTIONS>
+
+<TOOL_GUIDANCE>
+Use bash for shell operations, python for code tasks.
+File operations should use pathlib for cross-platform compatibility.
+</TOOL_GUIDANCE>
+
+<OUTPUT_DESCRIPTION>
+Provide code blocks with syntax highlighting.
+Explain non-obvious decisions in comments.
+</OUTPUT_DESCRIPTION>
+```
+
+**Example 2: Progressive Document Loading**
+```markdown
+# Instead of loading all documentation at once:
+
+# Step 1: Load summary
+docs/api_summary.md          # Lightweight overview
+
+# Step 2: Load specific section as needed
+docs/api/endpoints.md        # Only when API calls needed
+docs/api/authentication.md   # Only when auth context needed
+```
+
+## Guidelines
+
+1. Treat context as a finite resource with diminishing returns
+2. Place critical information at attention-favored positions (beginning and end)
+3. Use progressive disclosure to defer loading until needed
+4. Organize system prompts with clear section boundaries
+5. Monitor context usage during development
+6. Implement compaction triggers at 70-80% utilization
+7. Design for context degradation rather than hoping to avoid it
+8. Prefer smaller high-signal context over larger low-signal context
+
+## Integration
+
+This skill provides foundational context that all other skills build upon. It should be studied first before exploring:
+
+- context-degradation - Understanding how context fails
+- context-optimization - Techniques for extending context capacity
+- multi-agent-patterns - How context isolation enables multi-agent systems
+- tool-design - How tool definitions interact with context
+
+## References
+
+Internal reference:
+- [Context Components Reference](./references/context-components.md) - Detailed technical reference
+
+Related skills in this collection:
+- context-degradation - Understanding context failure patterns
+- context-optimization - Techniques for efficient context use
+
+External resources:
+- Research on transformer attention mechanisms
+- Production engineering guides from leading AI labs
+- Framework documentation on context window management
+
+---
+
+## Skill Metadata
+
+**Created**: 2025-12-20
+**Last Updated**: 2025-12-20
+**Author**: Agent Skills for Context Engineering Contributors
+**Version**: 1.0.0

skills/context-optimization/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: context-optimization
+description: "Apply compaction, masking, and caching strategies"
+source: "https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering/tree/main/skills/context-optimization"
+risk: safe
+---
+
+## When to Use This Skill
+
+Apply compaction, masking, and caching strategies
+
+Use this skill when working with apply compaction, masking, and caching strategies.
+# Context Optimization Techniques
+
+Context optimization extends the effective capacity of limited context windows through strategic compression, masking, caching, and partitioning. The goal is not to magically increase context windows but to make better use of available capacity. Effective optimization can double or triple effective context capacity without requiring larger models or longer contexts.
+
+## When to Activate
+
+Activate this skill when:
+- Context limits constrain task complexity
+- Optimizing for cost reduction (fewer tokens = lower costs)
+- Reducing latency for long conversations
+- Implementing long-running agent systems
+- Needing to handle larger documents or conversations
+- Building production systems at scale
+
+## Core Concepts
+
+Context optimization extends effective capacity through four primary strategies: compaction (summarizing context near limits), observation masking (replacing verbose outputs with references), KV-cache optimization (reusing cached computations), and context partitioning (splitting work across isolated contexts).
+
+The key insight is that context quality matters more than quantity. Optimization preserves signal while reducing noise. The art lies in selecting what to keep versus what to discard, and when to apply each technique.
+
+## Detailed Topics
+
+### Compaction Strategies
+
+**What is Compaction**
+Compaction is the practice of summarizing context contents when approaching limits, then reinitializing a new context window with the summary. This distills the contents of a context window in a high-fidelity manner, enabling the agent to continue with minimal performance degradation.
+
+Compaction typically serves as the first lever in context optimization. The art lies in selecting what to keep versus what to discard.
+
+**Compaction Implementation**
+Compaction works by identifying sections that can be compressed, generating summaries that capture essential points, and replacing full content with summaries. Priority for compression goes to tool outputs (replace with summaries), old turns (summarize early conversation), retrieved docs (summarize if recent versions exist), and never compress system prompt.
+
+**Summary Generation**
+Effective summaries preserve different elements depending on message type:
+
+Tool outputs: Preserve key findings, metrics, and conclusions. Remove verbose raw output.
+
+Conversational turns: Preserve key decisions, commitments, and context shifts. Remove filler and back-and-forth.
+
+Retrieved documents: Preserve key facts and claims. Remove supporting evidence and elaboration.
+
+### Observation Masking
+
+**The Observation Problem**
+Tool outputs can comprise 80%+ of token usage in agent trajectories. Much of this is verbose output that has already served its purpose. Once an agent has used a tool output to make a decision, keeping the full output provides diminishing value while consuming significant context.
+
+Observation masking replaces verbose tool outputs with compact references. The information remains accessible if needed but does not consume context continuously.
+
+**Masking Strategy Selection**
+Not all observations should be masked equally:
+
+Never mask: Observations critical to current task, observations from the most recent turn, observations used in active reasoning.
+
+Consider masking: Observations from 3+ turns ago, verbose outputs with key points extractable, observations whose purpose has been served.
+
+Always mask: Repeated outputs, boilerplate headers/footers, outputs already summarized in conversation.
+
+### KV-Cache Optimization
+
+**Understanding KV-Cache**
+The KV-cache stores Key and Value tensors computed during inference, growing linearly with sequence length. Caching the KV-cache across requests sharing identical prefixes avoids recomputation.
+
+Prefix caching reuses KV blocks across requests with identical prefixes using hash-based block matching. This dramatically reduces cost and latency for requests with common prefixes like system prompts.
+
+**Cache Optimization Patterns**
+Optimize for caching by reordering context elements to maximize cache hits. Place stable elements first (system prompt, tool definitions), then frequently reused elements, then unique elements last.
+
+Design prompts to maximize cache stability: avoid dynamic content like timestamps, use consistent formatting, keep structure stable across sessions.
+
+### Context Partitioning
+
+**Sub-Agent Partitioning**
+The most aggressive form of context optimization is partitioning work across sub-agents with isolated contexts. Each sub-agent operates in a clean context focused on its subtask without carrying accumulated context from other subtasks.
+
+This approach achieves separation of concerns—the detailed search context remains isolated within sub-agents while the coordinator focuses on synthesis and analysis.
+
+**Result Aggregation**
+Aggregate results from partitioned subtasks by validating all partitions completed, merging compatible results, and summarizing if still too large.
+
+### Budget Management
+
+**Context Budget Allocation**
+Design explicit context budgets. Allocate tokens to categories: system prompt, tool definitions, retrieved docs, message history, and reserved buffer. Monitor usage against budget and trigger optimization when approaching limits.
+
+**Trigger-Based Optimization**
+Monitor signals for optimization triggers: token utilization above 80%, degradation indicators, and performance drops. Apply appropriate optimization techniques based on context composition.
+
+## Practical Guidance
+
+### Optimization Decision Framework
+
+When to optimize:
+- Context utilization exceeds 70%
+- Response quality degrades as conversations extend
+- Costs increase due to long contexts
+- Latency increases with conversation length
+
+What to apply:
+- Tool outputs dominate: observation masking
+- Retrieved documents dominate: summarization or partitioning
+- Message history dominates: compaction with summarization
+- Multiple components: combine strategies
+
+### Performance Considerations
+
+Compaction should achieve 50-70% token reduction with less than 5% quality degradation. Masking should achieve 60-80% reduction in masked observations. Cache optimization should achieve 70%+ hit rate for stable workloads.
+
+Monitor and iterate on optimization strategies based on measured effectiveness.
+
+## Examples
+
+**Example 1: Compaction Trigger**
+```python
+if context_tokens / context_limit > 0.8:
+    context = compact_context(context)
+```
+
+**Example 2: Observation Masking**
+```python
+if len(observation) > max_length:
+    ref_id = store_observation(observation)
+    return f"[Obs:{ref_id} elided. Key: {extract_key(observation)}]"
+```
+
+**Example 3: Cache-Friendly Ordering**
+```python
+# Stable content first
+context = [system_prompt, tool_definitions]  # Cacheable
+context += [reused_templates]  # Reusable
+context += [unique_content]  # Unique
+```
+
+## Guidelines
+
+1. Measure before optimizing—know your current state
+2. Apply compaction before masking when possible
+3. Design for cache stability with consistent prompts
+4. Partition before context becomes problematic
+5. Monitor optimization effectiveness over time
+6. Balance token savings against quality preservation
+7. Test optimization at production scale
+8. Implement graceful degradation for edge cases
+
+## Integration
+
+This skill builds on context-fundamentals and context-degradation. It connects to:
+
+- multi-agent-patterns - Partitioning as isolation
+- evaluation - Measuring optimization effectiveness
+- memory-systems - Offloading context to memory
+
+## References
+
+Internal reference:
+- [Optimization Techniques Reference](./references/optimization_techniques.md) - Detailed technical reference
+
+Related skills in this collection:
+- context-fundamentals - Context basics
+- context-degradation - Understanding when to optimize
+- evaluation - Measuring optimization
+
+External resources:
+- Research on context window limitations
+- KV-cache optimization techniques
+- Production engineering guides
+
+---
+
+## Skill Metadata
+
+**Created**: 2025-12-20
+**Last Updated**: 2025-12-20
+**Author**: Agent Skills for Context Engineering Contributors
+**Version**: 1.0.0

skills/create-pr/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: create-pr
+description: "Create pull requests following Sentry conventions. Use when opening PRs, writing PR descriptions, or preparing changes for review. Follows Sentry's code review guidelines."
+source: "https://github.com/getsentry/skills/tree/main/plugins/sentry-skills/skills/create-pr"
+risk: safe
+---
+
+# Create Pull Request
+
+Create pull requests following Sentry's engineering practices.
+
+## When to Use This Skill
+
+Use this skill when:
+- Opening pull requests
+- Writing PR descriptions
+- Preparing changes for review
+- Following Sentry's code review guidelines
+- Creating PRs that follow best practices
+
+**Requires**: GitHub CLI (`gh`) authenticated and available.
+
+## Prerequisites
+
+Before creating a PR, ensure all changes are committed. If there are uncommitted changes, run the `sentry-skills:commit` skill first to commit them properly.
+
+```bash
+# Check for uncommitted changes
+git status --porcelain
+```
+
+If the output shows any uncommitted changes (modified, added, or untracked files that should be included), invoke the `sentry-skills:commit` skill before proceeding.
+
+## Process
+
+### Step 1: Verify Branch State
+
+```bash
+# Detect the default branch
+BASE=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')
+
+# Check current branch and status
+git status
+git log $BASE..HEAD --oneline
+```
+
+Ensure:
+- All changes are committed
+- Branch is up to date with remote
+- Changes are rebased on the base branch if needed
+
+### Step 2: Analyze Changes
+
+Review what will be included in the PR:
+
+```bash
+# See all commits that will be in the PR
+git log $BASE..HEAD
+
+# See the full diff
+git diff $BASE...HEAD
+```
+
+Understand the scope and purpose of all changes before writing the description.
+
+### Step 3: Write the PR Description
+
+Use this structure for PR descriptions (ignoring any repository PR templates):
+
+```markdown
+<brief description of what the PR does>
+
+<why these changes are being made - the motivation>
+
+<alternative approaches considered, if any>
+
+<any additional context reviewers need>
+```
+
+**Do NOT include:**
+- "Test plan" sections
+- Checkbox lists of testing steps
+- Redundant summaries of the diff
+
+**Do include:**
+- Clear explanation of what and why
+- Links to relevant issues or tickets
+- Context that isn't obvious from the code
+- Notes on specific areas that need careful review
+
+### Step 4: Create the PR
+
+```bash
+gh pr create --draft --title "<type>(<scope>): <description>" --body "$(cat <<'EOF'
+<description body here>
+EOF
+)"
+```
+
+**Title format** follows commit conventions:
+- `feat(scope): Add new feature`
+- `fix(scope): Fix the bug`
+- `ref: Refactor something`
+
+## PR Description Examples
+
+### Feature PR
+
+```markdown
+Add Slack thread replies for alert notifications
+
+When an alert is updated or resolved, we now post a reply to the original
+Slack thread instead of creating a new message. This keeps related
+notifications grouped and reduces channel noise.
+
+Previously considered posting edits to the original message, but threading
+better preserves the timeline of events and works when the original message
+is older than Slack's edit window.
+
+Refs SENTRY-1234
+```
+
+### Bug Fix PR
+
+```markdown
+Handle null response in user API endpoint
+
+The user endpoint could return null for soft-deleted accounts, causing
+dashboard crashes when accessing user properties. This adds a null check
+and returns a proper 404 response.
+
+Found while investigating SENTRY-5678.
+
+Fixes SENTRY-5678
+```
+
+### Refactor PR
+
+```markdown
+Extract validation logic to shared module
+
+Moves duplicate validation code from the alerts, issues, and projects
+endpoints into a shared validator class. No behavior change.
+
+This prepares for adding new validation rules in SENTRY-9999 without
+duplicating logic across endpoints.
+```
+
+## Issue References
+
+Reference issues in the PR body:
+
+| Syntax | Effect |
+|--------|--------|
+| `Fixes #1234` | Closes GitHub issue on merge |
+| `Fixes SENTRY-1234` | Closes Sentry issue |
+| `Refs GH-1234` | Links without closing |
+| `Refs LINEAR-ABC-123` | Links Linear issue |
+
+## Guidelines
+
+- **One PR per feature/fix** - Don't bundle unrelated changes
+- **Keep PRs reviewable** - Smaller PRs get faster, better reviews
+- **Explain the why** - Code shows what; description explains why
+- **Mark WIP early** - Use draft PRs for early feedback
+
+## Editing Existing PRs
+
+If you need to update a PR after creation, use `gh api` instead of `gh pr edit`:
+
+```bash
+# Update PR description
+gh api -X PATCH repos/{owner}/{repo}/pulls/PR_NUMBER -f body="$(cat <<'EOF'
+Updated description here
+EOF
+)"
+
+# Update PR title
+gh api -X PATCH repos/{owner}/{repo}/pulls/PR_NUMBER -f title='new: Title here'
+
+# Update both
+gh api -X PATCH repos/{owner}/{repo}/pulls/PR_NUMBER \
+  -f title='new: Title' \
+  -f body='New description'
+```
+
+Note: `gh pr edit` is currently broken due to GitHub's Projects (classic) deprecation.
+
+## References
+
+- [Sentry Code Review Guidelines](https://develop.sentry.dev/engineering-practices/code-review/)
+- [Sentry Commit Messages](https://develop.sentry.dev/engineering-practices/commit-messages/)

skills/culture-index/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: culture-index
+description: "Index and search culture documentation"
+source: "https://github.com/trailofbits/skills/tree/main/plugins/culture-index"
+risk: safe
+---
+
+# Culture Index
+
+## Overview
+
+Index and search culture documentation to help teams understand organizational values, practices, and guidelines.
+
+## When to Use This Skill
+
+Use this skill when you need to index and search culture documentation.
+
+Use this skill when:
+- You need to search through organizational culture documentation
+- You want to index culture-related documents for easy retrieval
+- You need to understand team values, practices, or guidelines
+- You're building a knowledge base for culture documentation
+
+## Instructions
+
+This skill provides capabilities for indexing and searching culture documentation. It helps teams:
+
+1. **Index Culture Documents**: Organize and index culture-related documentation
+2. **Search Functionality**: Quickly find relevant culture information
+3. **Knowledge Retrieval**: Access organizational values and practices efficiently
+
+## Usage
+
+When working with culture documentation:
+
+1. Identify the culture documents to index
+2. Use the indexing functionality to organize the content
+3. Search through indexed documents to find relevant information
+4. Retrieve specific culture guidelines or practices as needed
+
+## Resources
+
+For more information, see the [source repository](https://github.com/trailofbits/skills/tree/main/plugins/culture-index).

skills/deep-research/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: deep-research
+description: "Execute autonomous multi-step research using Google Gemini Deep Research Agent. Use for: market analysis, competitive landscaping, literature reviews, technical research, due diligence. Takes 2-10 minutes but produces detailed, cited reports. Costs $2-5 per task."
+source: "https://github.com/sanjay3290/ai-skills/tree/main/skills/deep-research"
+risk: safe
+---
+
+# Gemini Deep Research Skill
+
+Run autonomous research tasks that plan, search, read, and synthesize information into comprehensive reports.
+
+## When to Use This Skill
+
+Use this skill when:
+- Performing market analysis
+- Conducting competitive landscaping
+- Creating literature reviews
+- Doing technical research
+- Performing due diligence
+- Need detailed, cited research reports
+
+## Requirements
+
+- Python 3.8+
+- httpx: `pip install -r requirements.txt`
+- GEMINI_API_KEY environment variable
+
+## Setup
+
+1. Get a Gemini API key from [Google AI Studio](https://aistudio.google.com/)
+2. Set the environment variable:
+   ```bash
+   export GEMINI_API_KEY=your-api-key-here
+   ```
+   Or create a `.env` file in the skill directory.
+
+## Usage
+
+### Start a research task
+```bash
+python3 scripts/research.py --query "Research the history of Kubernetes"
+```
+
+### With structured output format
+```bash
+python3 scripts/research.py --query "Compare Python web frameworks" \
+  --format "1. Executive Summary\n2. Comparison Table\n3. Recommendations"
+```
+
+### Stream progress in real-time
+```bash
+python3 scripts/research.py --query "Analyze EV battery market" --stream
+```
+
+### Start without waiting
+```bash
+python3 scripts/research.py --query "Research topic" --no-wait
+```
+
+### Check status of running research
+```bash
+python3 scripts/research.py --status <interaction_id>
+```
+
+### Wait for completion
+```bash
+python3 scripts/research.py --wait <interaction_id>
+```
+
+### Continue from previous research
+```bash
+python3 scripts/research.py --query "Elaborate on point 2" --continue <interaction_id>
+```
+
+### List recent research
+```bash
+python3 scripts/research.py --list
+```
+
+## Output Formats
+
+- **Default**: Human-readable markdown report
+- **JSON** (`--json`): Structured data for programmatic use
+- **Raw** (`--raw`): Unprocessed API response
+
+## Cost & Time
+
+| Metric | Value |
+|--------|-------|
+| Time | 2-10 minutes per task |
+| Cost | $2-5 per task (varies by complexity) |
+| Token usage | ~250k-900k input, ~60k-80k output |
+
+## Best Use Cases
+
+- Market analysis and competitive landscaping
+- Technical literature reviews
+- Due diligence research
+- Historical research and timelines
+- Comparative analysis (frameworks, products, technologies)
+
+## Workflow
+
+1. User requests research → Run `--query "..."`
+2. Inform user of estimated time (2-10 minutes)
+3. Monitor with `--stream` or poll with `--status`
+4. Return formatted results
+5. Use `--continue` for follow-up questions
+
+## Exit Codes
+
+- **0**: Success
+- **1**: Error (API error, config issue, timeout)
+- **130**: Cancelled by user (Ctrl+C)

skills/design-md/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: design-md
+description: "Analyze Stitch projects and synthesize a semantic design system into DESIGN.md files"
+source: "https://github.com/google-labs-code/stitch-skills/tree/main/skills/design-md"
+risk: safe
+---
+
+# Stitch DESIGN.md Skill
+
+You are an expert Design Systems Lead. Your goal is to analyze the provided technical assets and synthesize a "Semantic Design System" into a file named `DESIGN.md`.
+
+## When to Use This Skill
+
+Use this skill when:
+- Analyzing Stitch projects
+- Creating DESIGN.md files
+- Synthesizing semantic design systems
+- Working with Stitch design language
+- Generating design documentation for Stitch projects
+
+## Overview
+
+This skill helps you create `DESIGN.md` files that serve as the "source of truth" for prompting Stitch to generate new screens that align perfectly with existing design language. Stitch interprets design through "Visual Descriptions" supported by specific color values.
+
+## Prerequisites
+
+- Access to the Stitch MCP Server
+- A Stitch project with at least one designed screen
+- Access to the Stitch Effective Prompting Guide: https://stitch.withgoogle.com/docs/learn/prompting/
+
+## The Goal
+
+The `DESIGN.md` file will serve as the "source of truth" for prompting Stitch to generate new screens that align perfectly with the existing design language. Stitch interprets design through "Visual Descriptions" supported by specific color values.
+
+## Retrieval and Networking
+
+To analyze a Stitch project, you must retrieve screen metadata and design assets using the Stitch MCP Server tools:
+
+1. **Namespace discovery**: Run `list_tools` to find the Stitch MCP prefix. Use this prefix (e.g., `mcp_stitch:`) for all subsequent calls.
+
+2. **Project lookup** (if Project ID is not provided):
+   - Call `[prefix]:list_projects` with `filter: "view=owned"` to retrieve all user projects
+   - Identify the target project by title or URL pattern
+   - Extract the Project ID from the `name` field (e.g., `projects/13534454087919359824`)
+
+3. **Screen lookup** (if Screen ID is not provided):
+   - Call `[prefix]:list_screens` with the `projectId` (just the numeric ID, not the full path)
+   - Review screen titles to identify the target screen (e.g., "Home", "Landing Page")
+   - Extract the Screen ID from the screen's `name` field
+
+4. **Metadata fetch**: 
+   - Call `[prefix]:get_screen` with both `projectId` and `screenId` (both as numeric IDs only)
+   - This returns the complete screen object including:
+     - `screenshot.downloadUrl` - Visual reference of the design
+     - `htmlCode.downloadUrl` - Full HTML/CSS source code
+     - `width`, `height`, `deviceType` - Screen dimensions and target platform
+     - Project metadata including `designTheme` with color and style information
+
+5. **Asset download**:
+   - Use `web_fetch` or `read_url_content` to download the HTML code from `htmlCode.downloadUrl`
+   - Optionally download the screenshot from `screenshot.downloadUrl` for visual reference
+   - Parse the HTML to extract Tailwind classes, custom CSS, and component patterns
+
+6. **Project metadata extraction**:
+   - Call `[prefix]:get_project` with the project `name` (full path: `projects/{id}`) to get:
+     - `designTheme` object with color mode, fonts, roundness, custom colors
+     - Project-level design guidelines and descriptions
+     - Device type preferences and layout principles
+
+## Analysis & Synthesis Instructions
+
+### 1. Extract Project Identity (JSON)
+- Locate the Project Title
+- Locate the specific Project ID (e.g., from the `name` field in the JSON)
+
+### 2. Define the Atmosphere (Image/HTML)
+Evaluate the screenshot and HTML structure to capture the overall "vibe." Use evocative adjectives to describe the mood (e.g., "Airy," "Dense," "Minimalist," "Utilitarian").
+
+### 3. Map the Color Palette (Tailwind Config/JSON)
+Identify the key colors in the system. For each color, provide:
+- A descriptive, natural language name that conveys its character (e.g., "Deep Muted Teal-Navy")
+- The specific hex code in parentheses for precision (e.g., "#294056")
+- Its specific functional role (e.g., "Used for primary actions")
+
+### 4. Translate Geometry & Shape (CSS/Tailwind)
+Convert technical `border-radius` and layout values into physical descriptions:
+- Describe `rounded-full` as "Pill-shaped"
+- Describe `rounded-lg` as "Subtly rounded corners"
+- Describe `rounded-none` as "Sharp, squared-off edges"
+
+### 5. Describe Depth & Elevation
+Explain how the UI handles layers. Describe the presence and quality of shadows (e.g., "Flat," "Whisper-soft diffused shadows," or "Heavy, high-contrast drop shadows").
+
+## Output Guidelines
+
+- **Language:** Use descriptive design terminology and natural language exclusively
+- **Format:** Generate a clean Markdown file following the structure below
+- **Precision:** Include exact hex codes for colors while using descriptive names
+- **Context:** Explain the "why" behind design decisions, not just the "what"
+
+## Output Format (DESIGN.md Structure)
+
+```markdown
+# Design System: [Project Title]
+**Project ID:** [Insert Project ID Here]
+
+## 1. Visual Theme & Atmosphere
+(Description of the mood, density, and aesthetic philosophy.)
+
+## 2. Color Palette & Roles
+(List colors by Descriptive Name + Hex Code + Functional Role.)
+
+## 3. Typography Rules
+(Description of font family, weight usage for headers vs. body, and letter-spacing character.)
+
+## 4. Component Stylings
+* **Buttons:** (Shape description, color assignment, behavior).
+* **Cards/Containers:** (Corner roundness description, background color, shadow depth).
+* **Inputs/Forms:** (Stroke style, background).
+
+## 5. Layout Principles
+(Description of whitespace strategy, margins, and grid alignment.)
+```
+
+## Usage Example
+
+To use this skill for the Furniture Collection project:
+
+1. **Retrieve project information:**
+   ```
+   Use the Stitch MCP Server to get the Furniture Collection project
+   ```
+
+2. **Get the Home page screen details:**
+   ```
+   Retrieve the Home page screen's code, image, and screen object information
+   ```
+
+3. **Reference best practices:**
+   ```
+   Review the Stitch Effective Prompting Guide at:
+   https://stitch.withgoogle.com/docs/learn/prompting/
+   ```
+
+4. **Analyze and synthesize:**
+   - Extract all relevant design tokens from the screen
+   - Translate technical values into descriptive language
+   - Organize information according to the DESIGN.md structure
+
+5. **Generate the file:**
+   - Create `DESIGN.md` in the project directory
+   - Follow the prescribed format exactly
+   - Ensure all color codes are accurate
+   - Use evocative, designer-friendly language
+
+## Best Practices
+
+- **Be Descriptive:** Avoid generic terms like "blue" or "rounded." Use "Ocean-deep Cerulean (#0077B6)" or "Gently curved edges"
+- **Be Functional:** Always explain what each design element is used for
+- **Be Consistent:** Use the same terminology throughout the document
+- **Be Visual:** Help readers visualize the design through your descriptions
+- **Be Precise:** Include exact values (hex codes, pixel values) in parentheses after natural language descriptions
+
+## Tips for Success
+
+1. **Start with the big picture:** Understand the overall aesthetic before diving into details
+2. **Look for patterns:** Identify consistent spacing, sizing, and styling patterns
+3. **Think semantically:** Name colors by their purpose, not just their appearance
+4. **Consider hierarchy:** Document how visual weight and importance are communicated
+5. **Reference the guide:** Use language and patterns from the Stitch Effective Prompting Guide
+
+## Common Pitfalls to Avoid
+
+- ❌ Using technical jargon without translation (e.g., "rounded-xl" instead of "generously rounded corners")
+- ❌ Omitting color codes or using only descriptive names
+- ❌ Forgetting to explain functional roles of design elements
+- ❌ Being too vague in atmosphere descriptions
+- ❌ Ignoring subtle design details like shadows or spacing patterns

skills/evaluation/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: evaluation
+description: "Build evaluation frameworks for agent systems"
+source: "https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering/tree/main/skills/evaluation"
+risk: safe
+---
+
+## When to Use This Skill
+
+Build evaluation frameworks for agent systems
+
+Use this skill when working with build evaluation frameworks for agent systems.
+# Evaluation Methods for Agent Systems
+
+Evaluation of agent systems requires different approaches than traditional software or even standard language model applications. Agents make dynamic decisions, are non-deterministic between runs, and often lack single correct answers. Effective evaluation must account for these characteristics while providing actionable feedback. A robust evaluation framework enables continuous improvement, catches regressions, and validates that context engineering choices achieve intended effects.
+
+## When to Activate
+
+Activate this skill when:
+- Testing agent performance systematically
+- Validating context engineering choices
+- Measuring improvements over time
+- Catching regressions before deployment
+- Building quality gates for agent pipelines
+- Comparing different agent configurations
+- Evaluating production systems continuously
+
+## Core Concepts
+
+Agent evaluation requires outcome-focused approaches that account for non-determinism and multiple valid paths. Multi-dimensional rubrics capture various quality aspects: factual accuracy, completeness, citation accuracy, source quality, and tool efficiency. LLM-as-judge provides scalable evaluation while human evaluation catches edge cases.
+
+The key insight is that agents may find alternative paths to goals—the evaluation should judge whether they achieve right outcomes while following reasonable processes.
+
+**Performance Drivers: The 95% Finding**
+Research on the BrowseComp evaluation (which tests browsing agents' ability to locate hard-to-find information) found that three factors explain 95% of performance variance:
+
+| Factor | Variance Explained | Implication |
+|--------|-------------------|-------------|
+| Token usage | 80% | More tokens = better performance |
+| Number of tool calls | ~10% | More exploration helps |
+| Model choice | ~5% | Better models multiply efficiency |
+
+This finding has significant implications for evaluation design:
+- **Token budgets matter**: Evaluate agents with realistic token budgets, not unlimited resources
+- **Model upgrades beat token increases**: Upgrading to Claude Sonnet 4.5 or GPT-5.2 provides larger gains than doubling token budgets on previous versions
+- **Multi-agent validation**: The finding validates architectures that distribute work across agents with separate context windows
+
+## Detailed Topics
+
+### Evaluation Challenges
+
+**Non-Determinism and Multiple Valid Paths**
+Agents may take completely different valid paths to reach goals. One agent might search three sources while another searches ten. They might use different tools to find the same answer. Traditional evaluations that check for specific steps fail in this context.
+
+The solution is outcome-focused evaluation that judges whether agents achieve right outcomes while following reasonable processes.
+
+**Context-Dependent Failures**
+Agent failures often depend on context in subtle ways. An agent might succeed on simple queries but fail on complex ones. It might work well with one tool set but fail with another. Failures may emerge only after extended interaction when context accumulates.
+
+Evaluation must cover a range of complexity levels and test extended interactions, not just isolated queries.
+
+**Composite Quality Dimensions**
+Agent quality is not a single dimension. It includes factual accuracy, completeness, coherence, tool efficiency, and process quality. An agent might score high on accuracy but low in efficiency, or vice versa.
+
+Evaluation rubrics must capture multiple dimensions with appropriate weighting for the use case.
+
+### Evaluation Rubric Design
+
+**Multi-Dimensional Rubric**
+Effective rubrics cover key dimensions with descriptive levels:
+
+Factual accuracy: Claims match ground truth (excellent to failed)
+
+Completeness: Output covers requested aspects (excellent to failed)
+
+Citation accuracy: Citations match claimed sources (excellent to failed)
+
+Source quality: Uses appropriate primary sources (excellent to failed)
+
+Tool efficiency: Uses right tools reasonable number of times (excellent to failed)
+
+**Rubric Scoring**
+Convert dimension assessments to numeric scores (0.0 to 1.0) with appropriate weighting. Calculate weighted overall scores. Determine passing threshold based on use case requirements.
+
+### Evaluation Methodologies
+
+**LLM-as-Judge**
+LLM-based evaluation scales to large test sets and provides consistent judgments. The key is designing effective evaluation prompts that capture the dimensions of interest.
+
+Provide clear task description, agent output, ground truth (if available), evaluation scale with level descriptions, and request structured judgment.
+
+**Human Evaluation**
+Human evaluation catches what automation misses. Humans notice hallucinated answers on unusual queries, system failures, and subtle biases that automated evaluation misses.
+
+Effective human evaluation covers edge cases, samples systematically, tracks patterns, and provides contextual understanding.
+
+**End-State Evaluation**
+For agents that mutate persistent state, end-state evaluation focuses on whether the final state matches expectations rather than how the agent got there.
+
+### Test Set Design
+
+**Sample Selection**
+Start with small samples during development. Early in agent development, changes have dramatic impacts because there is abundant low-hanging fruit. Small test sets reveal large effects.
+
+Sample from real usage patterns. Add known edge cases. Ensure coverage across complexity levels.
+
+**Complexity Stratification**
+Test sets should span complexity levels: simple (single tool call), medium (multiple tool calls), complex (many tool calls, significant ambiguity), and very complex (extended interaction, deep reasoning).
+
+### Context Engineering Evaluation
+
+**Testing Context Strategies**
+Context engineering choices should be validated through systematic evaluation. Run agents with different context strategies on the same test set. Compare quality scores, token usage, and efficiency metrics.
+
+**Degradation Testing**
+Test how context degradation affects performance by running agents at different context sizes. Identify performance cliffs where context becomes problematic. Establish safe operating limits.
+
+### Continuous Evaluation
+
+**Evaluation Pipeline**
+Build evaluation pipelines that run automatically on agent changes. Track results over time. Compare versions to identify improvements or regressions.
+
+**Monitoring Production**
+Track evaluation metrics in production by sampling interactions and evaluating randomly. Set alerts for quality drops. Maintain dashboards for trend analysis.
+
+## Practical Guidance
+
+### Building Evaluation Frameworks
+
+1. Define quality dimensions relevant to your use case
+2. Create rubrics with clear, actionable level descriptions
+3. Build test sets from real usage patterns and edge cases
+4. Implement automated evaluation pipelines
+5. Establish baseline metrics before making changes
+6. Run evaluations on all significant changes
+7. Track metrics over time for trend analysis
+8. Supplement automated evaluation with human review
+
+### Avoiding Evaluation Pitfalls
+
+Overfitting to specific paths: Evaluate outcomes, not specific steps.
+Ignoring edge cases: Include diverse test scenarios.
+Single-metric obsession: Use multi-dimensional rubrics.
+Neglecting context effects: Test with realistic context sizes.
+Skipping human evaluation: Automated evaluation misses subtle issues.
+
+## Examples
+
+**Example 1: Simple Evaluation**
+```python
+def evaluate_agent_response(response, expected):
+    rubric = load_rubric()
+    scores = {}
+    for dimension, config in rubric.items():
+        scores[dimension] = assess_dimension(response, expected, dimension)
+    overall = weighted_average(scores, config["weights"])
+    return {"passed": overall >= 0.7, "scores": scores}
+```
+
+**Example 2: Test Set Structure**
+
+Test sets should span multiple complexity levels to ensure comprehensive evaluation:
+
+```python
+test_set = [
+    {
+        "name": "simple_lookup",
+        "input": "What is the capital of France?",
+        "expected": {"type": "fact", "answer": "Paris"},
+        "complexity": "simple",
+        "description": "Single tool call, factual lookup"
+    },
+    {
+        "name": "medium_query",
+        "input": "Compare the revenue of Apple and Microsoft last quarter",
+        "complexity": "medium",
+        "description": "Multiple tool calls, comparison logic"
+    },
+    {
+        "name": "multi_step_reasoning",
+        "input": "Analyze sales data from Q1-Q4 and create a summary report with trends",
+        "complexity": "complex",
+        "description": "Many tool calls, aggregation, analysis"
+    },
+    {
+        "name": "research_synthesis",
+        "input": "Research emerging AI technologies, evaluate their potential impact, and recommend adoption strategy",
+        "complexity": "very_complex",
+        "description": "Extended interaction, deep reasoning, synthesis"
+    }
+]
+```
+
+## Guidelines
+
+1. Use multi-dimensional rubrics, not single metrics
+2. Evaluate outcomes, not specific execution paths
+3. Cover complexity levels from simple to complex
+4. Test with realistic context sizes and histories
+5. Run evaluations continuously, not just before release
+6. Supplement LLM evaluation with human review
+7. Track metrics over time for trend detection
+8. Set clear pass/fail thresholds based on use case
+
+## Integration
+
+This skill connects to all other skills as a cross-cutting concern:
+
+- context-fundamentals - Evaluating context usage
+- context-degradation - Detecting degradation
+- context-optimization - Measuring optimization effectiveness
+- multi-agent-patterns - Evaluating coordination
+- tool-design - Evaluating tool effectiveness
+- memory-systems - Evaluating memory quality
+
+## References
+
+Internal reference:
+- [Metrics Reference](./references/metrics.md) - Detailed evaluation metrics and implementation
+
+## References
+
+Internal skills:
+- All other skills connect to evaluation for quality measurement
+
+External resources:
+- LLM evaluation benchmarks
+- Agent evaluation research papers
+- Production monitoring practices
+
+---
+
+## Skill Metadata
+
+**Created**: 2025-12-20
+**Last Updated**: 2025-12-20
+**Author**: Agent Skills for Context Engineering Contributors
+**Version**: 1.0.0

skills/expo-deployment/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: expo-deployment
+description: "Deploy Expo apps to production"
+source: "https://github.com/expo/skills/tree/main/plugins/expo-deployment"
+risk: safe
+---
+
+# Expo Deployment
+
+## Overview
+
+Deploy Expo applications to production environments, including app stores and over-the-air updates.
+
+## When to Use This Skill
+
+Use this skill when you need to deploy Expo apps to production.
+
+Use this skill when:
+- Deploying Expo apps to production
+- Publishing to app stores (iOS App Store, Google Play)
+- Setting up over-the-air (OTA) updates
+- Configuring production build settings
+- Managing release channels and versions
+
+## Instructions
+
+This skill provides guidance for deploying Expo apps:
+
+1. **Build Configuration**: Set up production build settings
+2. **App Store Submission**: Prepare and submit to app stores
+3. **OTA Updates**: Configure over-the-air update channels
+4. **Release Management**: Manage versions and release channels
+5. **Production Optimization**: Optimize apps for production
+
+## Deployment Workflow
+
+### Pre-Deployment
+
+1. Ensure all tests pass
+2. Update version numbers
+3. Configure production environment variables
+4. Review and optimize app bundle size
+5. Test production builds locally
+
+### App Store Deployment
+
+1. Build production binaries (iOS/Android)
+2. Configure app store metadata
+3. Submit to App Store Connect / Google Play Console
+4. Manage app store listings and screenshots
+5. Handle app review process
+
+### OTA Updates
+
+1. Configure update channels (production, staging, etc.)
+2. Build and publish updates
+3. Manage rollout strategies
+4. Monitor update adoption
+5. Handle rollbacks if needed
+
+## Best Practices
+
+- Use EAS Build for reliable production builds
+- Test production builds before submission
+- Implement proper error tracking and analytics
+- Use release channels for staged rollouts
+- Keep app store metadata up to date
+- Monitor app performance in production
+
+## Resources
+
+For more information, see the [source repository](https://github.com/expo/skills/tree/main/plugins/expo-deployment).

skills/fal-audio/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: fal-audio
+description: "Text-to-speech and speech-to-text using fal.ai audio models"
+source: "https://github.com/fal-ai-community/skills/blob/main/skills/claude.ai/fal-audio/SKILL.md"
+risk: safe
+---
+
+# Fal Audio
+
+## Overview
+
+Text-to-speech and speech-to-text using fal.ai audio models
+
+## When to Use This Skill
+
+Use this skill when you need to work with text-to-speech and speech-to-text using fal.ai audio models.
+
+## Instructions
+
+This skill provides guidance and patterns for text-to-speech and speech-to-text using fal.ai audio models.
+
+For more information, see the [source repository](https://github.com/fal-ai-community/skills/blob/main/skills/claude.ai/fal-audio/SKILL.md).

skills/fal-generate/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: fal-generate
+description: "Generate images and videos using fal.ai AI models"
+source: "https://github.com/fal-ai-community/skills/blob/main/skills/claude.ai/fal-generate/SKILL.md"
+risk: safe
+---
+
+# Fal Generate
+
+## Overview
+
+Generate images and videos using fal.ai AI models
+
+## When to Use This Skill
+
+Use this skill when you need to work with generate images and videos using fal.ai ai models.
+
+## Instructions
+
+This skill provides guidance and patterns for generate images and videos using fal.ai ai models.
+
+For more information, see the [source repository](https://github.com/fal-ai-community/skills/blob/main/skills/claude.ai/fal-generate/SKILL.md).

skills/fal-image-edit/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: fal-image-edit
+description: "AI-powered image editing with style transfer and object removal"
+source: "https://github.com/fal-ai-community/skills/blob/main/skills/claude.ai/fal-image-edit/SKILL.md"
+risk: safe
+---
+
+# Fal Image Edit
+
+## Overview
+
+AI-powered image editing with style transfer and object removal
+
+## When to Use This Skill
+
+Use this skill when you need to work with ai-powered image editing with style transfer and object removal.
+
+## Instructions
+
+This skill provides guidance and patterns for ai-powered image editing with style transfer and object removal.
+
+For more information, see the [source repository](https://github.com/fal-ai-community/skills/blob/main/skills/claude.ai/fal-image-edit/SKILL.md).

skills/fal-platform/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: fal-platform
+description: "Platform APIs for model management, pricing, and usage tracking"
+source: "https://github.com/fal-ai-community/skills/blob/main/skills/claude.ai/fal-platform/SKILL.md"
+risk: safe
+---
+
+# Fal Platform
+
+## Overview
+
+Platform APIs for model management, pricing, and usage tracking
+
+## When to Use This Skill
+
+Use this skill when you need to work with platform apis for model management, pricing, and usage tracking.
+
+## Instructions
+
+This skill provides guidance and patterns for platform apis for model management, pricing, and usage tracking.
+
+For more information, see the [source repository](https://github.com/fal-ai-community/skills/blob/main/skills/claude.ai/fal-platform/SKILL.md).

skills/fal-upscale/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: fal-upscale
+description: "Upscale and enhance image and video resolution using AI"
+source: "https://github.com/fal-ai-community/skills/blob/main/skills/claude.ai/fal-upscale/SKILL.md"
+risk: safe
+---
+
+# Fal Upscale
+
+## Overview
+
+Upscale and enhance image and video resolution using AI
+
+## When to Use This Skill
+
+Use this skill when you need to work with upscale and enhance image and video resolution using ai.
+
+## Instructions
+
+This skill provides guidance and patterns for upscale and enhance image and video resolution using ai.
+
+For more information, see the [source repository](https://github.com/fal-ai-community/skills/blob/main/skills/claude.ai/fal-upscale/SKILL.md).

skills/fal-workflow/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: fal-workflow
+description: "Generate workflow JSON files for chaining AI models"
+source: "https://github.com/fal-ai-community/skills/blob/main/skills/claude.ai/fal-workflow/SKILL.md"
+risk: safe
+---
+
+# Fal Workflow
+
+## Overview
+
+Generate workflow JSON files for chaining AI models
+
+## When to Use This Skill
+
+Use this skill when you need to work with generate workflow json files for chaining ai models.
+
+## Instructions
+
+This skill provides guidance and patterns for generate workflow json files for chaining ai models.
+
+For more information, see the [source repository](https://github.com/fal-ai-community/skills/blob/main/skills/claude.ai/fal-workflow/SKILL.md).

skills/ffuf-claude-skill/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: ffuf-claude-skill
+description: "Web fuzzing with ffuf"
+source: "https://github.com/jthack/ffuf_claude_skill"
+risk: safe
+---
+
+# Ffuf Claude Skill
+
+## Overview
+
+Web fuzzing with ffuf
+
+## When to Use This Skill
+
+Use this skill when you need to work with web fuzzing with ffuf.
+
+## Instructions
+
+This skill provides guidance and patterns for web fuzzing with ffuf.
+
+For more information, see the [source repository](https://github.com/jthack/ffuf_claude_skill).

skills/find-bugs/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: find-bugs
+description: "Find bugs, security vulnerabilities, and code quality issues in local branch changes. Use when asked to review changes, find bugs, security review, or audit code on the current branch."
+source: "https://github.com/getsentry/skills/tree/main/plugins/sentry-skills/skills/find-bugs"
+risk: safe
+---
+
+# Find Bugs
+
+Review changes on this branch for bugs, security vulnerabilities, and code quality issues.
+
+## When to Use This Skill
+
+Use this skill when:
+- Asked to review changes
+- Finding bugs in code
+- Performing security reviews
+- Auditing code on the current branch
+- Reviewing pull request changes
+
+## Phase 1: Complete Input Gathering
+
+1. Get the FULL diff: `git diff $(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')...HEAD`
+2. If output is truncated, read each changed file individually until you have seen every changed line
+3. List all files modified in this branch before proceeding
+
+## Phase 2: Attack Surface Mapping
+
+For each changed file, identify and list:
+
+* All user inputs (request params, headers, body, URL components)
+* All database queries
+* All authentication/authorization checks
+* All session/state operations
+* All external calls
+* All cryptographic operations
+
+## Phase 3: Security Checklist (check EVERY item for EVERY file)
+
+* [ ] **Injection**: SQL, command, template, header injection
+* [ ] **XSS**: All outputs in templates properly escaped?
+* [ ] **Authentication**: Auth checks on all protected operations?
+* [ ] **Authorization/IDOR**: Access control verified, not just auth?
+* [ ] **CSRF**: State-changing operations protected?
+* [ ] **Race conditions**: TOCTOU in any read-then-write patterns?
+* [ ] **Session**: Fixation, expiration, secure flags?
+* [ ] **Cryptography**: Secure random, proper algorithms, no secrets in logs?
+* [ ] **Information disclosure**: Error messages, logs, timing attacks?
+* [ ] **DoS**: Unbounded operations, missing rate limits, resource exhaustion?
+* [ ] **Business logic**: Edge cases, state machine violations, numeric overflow?
+
+## Phase 4: Verification
+
+For each potential issue:
+
+* Check if it's already handled elsewhere in the changed code
+* Search for existing tests covering the scenario
+* Read surrounding context to verify the issue is real
+
+## Phase 5: Pre-Conclusion Audit
+
+Before finalizing, you MUST:
+
+1. List every file you reviewed and confirm you read it completely
+2. List every checklist item and note whether you found issues or confirmed it's clean
+3. List any areas you could NOT fully verify and why
+4. Only then provide your final findings
+
+## Output Format
+
+**Prioritize**: security vulnerabilities > bugs > code quality
+
+**Skip**: stylistic/formatting issues
+
+For each issue:
+
+* **File:Line** - Brief description
+* **Severity**: Critical/High/Medium/Low
+* **Problem**: What's wrong
+* **Evidence**: Why this is real (not already fixed, no existing test, etc.)
+* **Fix**: Concrete suggestion
+* **References**: OWASP, RFCs, or other standards if applicable
+
+If you find nothing significant, say so - don't invent issues.
+
+Do not make changes - just report findings. I'll decide what to address.

skills/fix-review/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: fix-review
+description: "Verify fix commits address audit findings without new bugs"
+source: "https://github.com/trailofbits/skills/tree/main/plugins/fix-review"
+risk: safe
+---
+
+# Fix Review
+
+## Overview
+
+Verify that fix commits properly address audit findings without introducing new bugs or security vulnerabilities.
+
+## When to Use This Skill
+
+Use this skill when you need to verify fix commits address audit findings without new bugs.
+
+Use this skill when:
+- Reviewing commits that address security audit findings
+- Verifying that fixes don't introduce new vulnerabilities
+- Ensuring code changes properly resolve identified issues
+- Validating that remediation efforts are complete and correct
+
+## Instructions
+
+This skill helps verify that fix commits properly address audit findings:
+
+1. **Review Fix Commits**: Analyze commits that claim to fix audit findings
+2. **Verify Resolution**: Ensure the original issue is properly addressed
+3. **Check for Regressions**: Verify no new bugs or vulnerabilities are introduced
+4. **Validate Completeness**: Ensure all aspects of the finding are resolved
+
+## Review Process
+
+When reviewing fix commits:
+
+1. Compare the fix against the original audit finding
+2. Verify the fix addresses the root cause, not just symptoms
+3. Check for potential side effects or new issues
+4. Validate that tests cover the fixed scenario
+5. Ensure no similar vulnerabilities exist elsewhere
+
+## Best Practices
+
+- Review fixes in context of the full codebase
+- Verify test coverage for the fixed issue
+- Check for similar patterns that might need fixing
+- Ensure fixes follow security best practices
+- Document the resolution approach
+
+## Resources
+
+For more information, see the [source repository](https://github.com/trailofbits/skills/tree/main/plugins/fix-review).

skills/fp-ts-errors/SKILL.md

@@ -0,0 +1,856 @@
+---
+name: fp-ts-errors
+description: Handle errors as values using fp-ts Either and TaskEither for cleaner, more predictable TypeScript code. Use when implementing error handling patterns with fp-ts.
+risk: safe
+source: https://github.com/whatiskadudoing/fp-ts-skills
+---
+
+# Practical Error Handling with fp-ts
+
+This skill teaches you how to handle errors without try/catch spaghetti. No academic jargon - just practical patterns for real problems.
+
+## When to Use This Skill
+
+- When you want type-safe error handling in TypeScript
+- When replacing try/catch with Either and TaskEither patterns
+- When building APIs or services that need explicit error types
+- When accumulating multiple validation errors
+
+The core idea: **Errors are just data**. Instead of throwing them into the void and hoping someone catches them, return them as values that TypeScript can track.
+
+---
+
+## 1. Stop Throwing Everywhere
+
+### The Problem with Exceptions
+
+Exceptions are invisible in your types. They break the contract between functions.
+
+```typescript
+// What this function signature promises:
+function getUser(id: string): User
+
+// What it actually does:
+function getUser(id: string): User {
+  if (!id) throw new Error('ID required')
+  const user = db.find(id)
+  if (!user) throw new Error('User not found')
+  return user
+}
+
+// The caller has no idea this can fail
+const user = getUser(id) // Might explode!
+```
+
+You end up with code like this:
+
+```typescript
+// MESSY: try/catch everywhere
+function processOrder(orderId: string) {
+  let order
+  try {
+    order = getOrder(orderId)
+  } catch (e) {
+    console.error('Failed to get order')
+    return null
+  }
+
+  let user
+  try {
+    user = getUser(order.userId)
+  } catch (e) {
+    console.error('Failed to get user')
+    return null
+  }
+
+  let payment
+  try {
+    payment = chargeCard(user.cardId, order.total)
+  } catch (e) {
+    console.error('Payment failed')
+    return null
+  }
+
+  return { order, user, payment }
+}
+```
+
+### The Solution: Return Errors as Values
+
+```typescript
+import * as E from 'fp-ts/Either'
+import { pipe } from 'fp-ts/function'
+
+// Now TypeScript KNOWS this can fail
+function getUser(id: string): E.Either<string, User> {
+  if (!id) return E.left('ID required')
+  const user = db.find(id)
+  if (!user) return E.left('User not found')
+  return E.right(user)
+}
+
+// The caller is forced to handle both cases
+const result = getUser(id)
+// result is Either<string, User> - error OR success, never both
+```
+
+---
+
+## 2. The Result Pattern (Either)
+
+`Either<E, A>` is simple: it holds either an error (`E`) or a value (`A`).
+
+- `Left` = error case
+- `Right` = success case (think "right" as in "correct")
+
+```typescript
+import * as E from 'fp-ts/Either'
+
+// Creating values
+const success = E.right(42)           // Right(42)
+const failure = E.left('Oops')        // Left('Oops')
+
+// Checking what you have
+if (E.isRight(result)) {
+  console.log(result.right) // The success value
+} else {
+  console.log(result.left)  // The error
+}
+
+// Better: pattern match with fold
+const message = pipe(
+  result,
+  E.fold(
+    (error) => `Failed: ${error}`,
+    (value) => `Got: ${value}`
+  )
+)
+```
+
+### Converting Throwing Code to Either
+
+```typescript
+// Wrap any throwing function with tryCatch
+const parseJSON = (json: string): E.Either<Error, unknown> =>
+  E.tryCatch(
+    () => JSON.parse(json),
+    (e) => (e instanceof Error ? e : new Error(String(e)))
+  )
+
+parseJSON('{"valid": true}')  // Right({ valid: true })
+parseJSON('not json')          // Left(SyntaxError: ...)
+
+// For functions you'll reuse, use tryCatchK
+const safeParseJSON = E.tryCatchK(
+  JSON.parse,
+  (e) => (e instanceof Error ? e : new Error(String(e)))
+)
+```
+
+### Common Either Operations
+
+```typescript
+import * as E from 'fp-ts/Either'
+import { pipe } from 'fp-ts/function'
+
+// Transform the success value
+const doubled = pipe(
+  E.right(21),
+  E.map(n => n * 2)
+) // Right(42)
+
+// Transform the error
+const betterError = pipe(
+  E.left('bad'),
+  E.mapLeft(e => `Error: ${e}`)
+) // Left('Error: bad')
+
+// Provide a default for errors
+const value = pipe(
+  E.left('failed'),
+  E.getOrElse(() => 0)
+) // 0
+
+// Convert nullable to Either
+const fromNullable = E.fromNullable('not found')
+fromNullable(user)  // Right(user) if exists, Left('not found') if null/undefined
+```
+
+---
+
+## 3. Chaining Operations That Might Fail
+
+The real power comes from chaining. Each step can fail, but you write it as a clean pipeline.
+
+### Before: Nested Try/Catch Hell
+
+```typescript
+// MESSY: Each step can fail, nested try/catch everywhere
+function processUserOrder(userId: string, productId: string): Result | null {
+  let user
+  try {
+    user = getUser(userId)
+  } catch (e) {
+    logError('User fetch failed', e)
+    return null
+  }
+
+  if (!user.isActive) {
+    logError('User not active')
+    return null
+  }
+
+  let product
+  try {
+    product = getProduct(productId)
+  } catch (e) {
+    logError('Product fetch failed', e)
+    return null
+  }
+
+  if (product.stock < 1) {
+    logError('Out of stock')
+    return null
+  }
+
+  let order
+  try {
+    order = createOrder(user, product)
+  } catch (e) {
+    logError('Order creation failed', e)
+    return null
+  }
+
+  return order
+}
+```
+
+### After: Clean Chain with Either
+
+```typescript
+import * as E from 'fp-ts/Either'
+import { pipe } from 'fp-ts/function'
+
+// Each function returns Either<Error, T>
+const getUser = (id: string): E.Either<string, User> => { ... }
+const getProduct = (id: string): E.Either<string, Product> => { ... }
+const createOrder = (user: User, product: Product): E.Either<string, Order> => { ... }
+
+// Chain them together - first error stops the chain
+const processUserOrder = (userId: string, productId: string): E.Either<string, Order> =>
+  pipe(
+    getUser(userId),
+    E.filterOrElse(
+      user => user.isActive,
+      () => 'User not active'
+    ),
+    E.chain(user =>
+      pipe(
+        getProduct(productId),
+        E.filterOrElse(
+          product => product.stock >= 1,
+          () => 'Out of stock'
+        ),
+        E.chain(product => createOrder(user, product))
+      )
+    )
+  )
+
+// Or use Do notation for cleaner access to intermediate values
+const processUserOrder = (userId: string, productId: string): E.Either<string, Order> =>
+  pipe(
+    E.Do,
+    E.bind('user', () => getUser(userId)),
+    E.filterOrElse(
+      ({ user }) => user.isActive,
+      () => 'User not active'
+    ),
+    E.bind('product', () => getProduct(productId)),
+    E.filterOrElse(
+      ({ product }) => product.stock >= 1,
+      () => 'Out of stock'
+    ),
+    E.chain(({ user, product }) => createOrder(user, product))
+  )
+```
+
+### Different Error Types? Use chainW
+
+```typescript
+type ValidationError = { type: 'validation'; message: string }
+type DbError = { type: 'db'; message: string }
+
+const validateInput = (id: string): E.Either<ValidationError, string> => { ... }
+const fetchFromDb = (id: string): E.Either<DbError, User> => { ... }
+
+// chainW (W = "wider") automatically unions the error types
+const process = (id: string): E.Either<ValidationError | DbError, User> =>
+  pipe(
+    validateInput(id),
+    E.chainW(validId => fetchFromDb(validId))
+  )
+```
+
+---
+
+## 4. Collecting Multiple Errors
+
+Sometimes you want ALL errors, not just the first one. Form validation is the classic example.
+
+### Before: Collecting Errors Manually
+
+```typescript
+// MESSY: Manual error accumulation
+function validateForm(form: FormData): { valid: boolean; errors: string[] } {
+  const errors: string[] = []
+
+  if (!form.email) {
+    errors.push('Email required')
+  } else if (!form.email.includes('@')) {
+    errors.push('Invalid email')
+  }
+
+  if (!form.password) {
+    errors.push('Password required')
+  } else if (form.password.length < 8) {
+    errors.push('Password too short')
+  }
+
+  if (!form.age) {
+    errors.push('Age required')
+  } else if (form.age < 18) {
+    errors.push('Must be 18+')
+  }
+
+  return { valid: errors.length === 0, errors }
+}
+```
+
+### After: Validation with Error Accumulation
+
+```typescript
+import * as E from 'fp-ts/Either'
+import * as NEA from 'fp-ts/NonEmptyArray'
+import { sequenceS } from 'fp-ts/Apply'
+import { pipe } from 'fp-ts/function'
+
+// Errors as a NonEmptyArray (always at least one)
+type Errors = NEA.NonEmptyArray<string>
+
+// Create the applicative that accumulates errors
+const validation = E.getApplicativeValidation(NEA.getSemigroup<string>())
+
+// Validators that return Either<Errors, T>
+const validateEmail = (email: string): E.Either<Errors, string> =>
+  !email ? E.left(NEA.of('Email required'))
+  : !email.includes('@') ? E.left(NEA.of('Invalid email'))
+  : E.right(email)
+
+const validatePassword = (password: string): E.Either<Errors, string> =>
+  !password ? E.left(NEA.of('Password required'))
+  : password.length < 8 ? E.left(NEA.of('Password too short'))
+  : E.right(password)
+
+const validateAge = (age: number | undefined): E.Either<Errors, number> =>
+  age === undefined ? E.left(NEA.of('Age required'))
+  : age < 18 ? E.left(NEA.of('Must be 18+'))
+  : E.right(age)
+
+// Combine all validations - collects ALL errors
+const validateForm = (form: FormData) =>
+  sequenceS(validation)({
+    email: validateEmail(form.email),
+    password: validatePassword(form.password),
+    age: validateAge(form.age)
+  })
+
+// Usage
+validateForm({ email: '', password: '123', age: 15 })
+// Left(['Email required', 'Password too short', 'Must be 18+'])
+
+validateForm({ email: 'a@b.com', password: 'longpassword', age: 25 })
+// Right({ email: 'a@b.com', password: 'longpassword', age: 25 })
+```
+
+### Field-Level Errors for Forms
+
+```typescript
+interface FieldError {
+  field: string
+  message: string
+}
+
+type FormErrors = NEA.NonEmptyArray<FieldError>
+
+const fieldError = (field: string, message: string): FormErrors =>
+  NEA.of({ field, message })
+
+const formValidation = E.getApplicativeValidation(NEA.getSemigroup<FieldError>())
+
+// Now errors know which field they belong to
+const validateEmail = (email: string): E.Either<FormErrors, string> =>
+  !email ? E.left(fieldError('email', 'Required'))
+  : !email.includes('@') ? E.left(fieldError('email', 'Invalid format'))
+  : E.right(email)
+
+// Easy to display in UI
+const getFieldError = (errors: FormErrors, field: string): string | undefined =>
+  errors.find(e => e.field === field)?.message
+```
+
+---
+
+## 5. Async Operations (TaskEither)
+
+For async operations that can fail, use `TaskEither`. It's like `Either` but for promises.
+
+- `TaskEither<E, A>` = a function that returns `Promise<Either<E, A>>`
+- Lazy: nothing runs until you execute it
+
+```typescript
+import * as TE from 'fp-ts/TaskEither'
+import { pipe } from 'fp-ts/function'
+
+// Wrap any async operation
+const fetchUser = (id: string): TE.TaskEither<Error, User> =>
+  TE.tryCatch(
+    () => fetch(`/api/users/${id}`).then(r => r.json()),
+    (e) => (e instanceof Error ? e : new Error(String(e)))
+  )
+
+// Chain async operations - just like Either
+const getUserPosts = (userId: string): TE.TaskEither<Error, Post[]> =>
+  pipe(
+    fetchUser(userId),
+    TE.chain(user => fetchPosts(user.id))
+  )
+
+// Execute when ready
+const result = await getUserPosts('123')() // Returns Either<Error, Post[]>
+```
+
+### Before: Promise Chain with Error Handling
+
+```typescript
+// MESSY: try/catch mixed with promise chains
+async function loadDashboard(userId: string) {
+  try {
+    const user = await fetchUser(userId)
+    if (!user) throw new Error('User not found')
+
+    let posts, notifications, settings
+    try {
+      [posts, notifications, settings] = await Promise.all([
+        fetchPosts(user.id),
+        fetchNotifications(user.id),
+        fetchSettings(user.id)
+      ])
+    } catch (e) {
+      // Which one failed? Who knows!
+      console.error('Failed to load data', e)
+      return null
+    }
+
+    return { user, posts, notifications, settings }
+  } catch (e) {
+    console.error('Failed to load user', e)
+    return null
+  }
+}
+```
+
+### After: Clean TaskEither Pipeline
+
+```typescript
+import * as TE from 'fp-ts/TaskEither'
+import { sequenceS } from 'fp-ts/Apply'
+import { pipe } from 'fp-ts/function'
+
+const loadDashboard = (userId: string) =>
+  pipe(
+    fetchUser(userId),
+    TE.chain(user =>
+      pipe(
+        // Parallel fetch with sequenceS
+        sequenceS(TE.ApplyPar)({
+          posts: fetchPosts(user.id),
+          notifications: fetchNotifications(user.id),
+          settings: fetchSettings(user.id)
+        }),
+        TE.map(data => ({ user, ...data }))
+      )
+    )
+  )
+
+// Execute and handle both cases
+pipe(
+  loadDashboard('123'),
+  TE.fold(
+    (error) => T.of(renderError(error)),
+    (data) => T.of(renderDashboard(data))
+  )
+)()
+```
+
+### Retry Failed Operations
+
+```typescript
+import * as T from 'fp-ts/Task'
+import * as TE from 'fp-ts/TaskEither'
+import { pipe } from 'fp-ts/function'
+
+const retry = <E, A>(
+  task: TE.TaskEither<E, A>,
+  attempts: number,
+  delayMs: number
+): TE.TaskEither<E, A> =>
+  pipe(
+    task,
+    TE.orElse((error) =>
+      attempts > 1
+        ? pipe(
+            T.delay(delayMs)(T.of(undefined)),
+            T.chain(() => retry(task, attempts - 1, delayMs * 2))
+          )
+        : TE.left(error)
+    )
+  )
+
+// Retry up to 3 times with exponential backoff
+const fetchWithRetry = retry(fetchUser('123'), 3, 1000)
+```
+
+### Fallback to Alternative
+
+```typescript
+// Try cache first, fall back to API
+const getUserData = (id: string) =>
+  pipe(
+    fetchFromCache(id),
+    TE.orElse(() => fetchFromApi(id)),
+    TE.orElse(() => TE.right(defaultUser)) // Last resort default
+  )
+```
+
+---
+
+## 6. Converting Between Patterns
+
+Real codebases have throwing functions, nullable values, and promises. Here's how to work with them.
+
+### From Nullable to Either
+
+```typescript
+import * as E from 'fp-ts/Either'
+import * as O from 'fp-ts/Option'
+
+// Direct conversion
+const user = users.find(u => u.id === id) // User | undefined
+const result = E.fromNullable('User not found')(user)
+
+// From Option
+const maybeUser: O.Option<User> = O.fromNullable(user)
+const eitherUser = pipe(
+  maybeUser,
+  E.fromOption(() => 'User not found')
+)
+```
+
+### From Throwing Function to Either
+
+```typescript
+// Wrap at the boundary
+const safeParse = <T>(schema: ZodSchema<T>) => (data: unknown): E.Either<ZodError, T> =>
+  E.tryCatch(
+    () => schema.parse(data),
+    (e) => e as ZodError
+  )
+
+// Use throughout your code
+const parseUser = safeParse(UserSchema)
+const result = parseUser(rawData) // Either<ZodError, User>
+```
+
+### From Promise to TaskEither
+
+```typescript
+import * as TE from 'fp-ts/TaskEither'
+
+// Wrap external async functions
+const fetchJson = <T>(url: string): TE.TaskEither<Error, T> =>
+  TE.tryCatch(
+    () => fetch(url).then(r => r.json()),
+    (e) => new Error(`Fetch failed: ${e}`)
+  )
+
+// Wrap axios, prisma, any async library
+const getUserFromDb = (id: string): TE.TaskEither<DbError, User> =>
+  TE.tryCatch(
+    () => prisma.user.findUniqueOrThrow({ where: { id } }),
+    (e) => ({ code: 'DB_ERROR', cause: e })
+  )
+```
+
+### Back to Promise (Escape Hatch)
+
+Sometimes you need a plain Promise for external APIs.
+
+```typescript
+import * as TE from 'fp-ts/TaskEither'
+import * as E from 'fp-ts/Either'
+
+const myTaskEither: TE.TaskEither<Error, User> = fetchUser('123')
+
+// Option 1: Get the Either (preserves both cases)
+const either: E.Either<Error, User> = await myTaskEither()
+
+// Option 2: Throw on error (for legacy code)
+const toThrowingPromise = <E, A>(te: TE.TaskEither<E, A>): Promise<A> =>
+  te().then(E.fold(
+    (error) => Promise.reject(error),
+    (value) => Promise.resolve(value)
+  ))
+
+const user = await toThrowingPromise(fetchUser('123')) // Throws if Left
+
+// Option 3: Default on error
+const user = await pipe(
+  fetchUser('123'),
+  TE.getOrElse(() => T.of(defaultUser))
+)()
+```
+
+---
+
+## Real Scenarios
+
+### Parse User Input Safely
+
+```typescript
+interface ParsedInput {
+  id: number
+  name: string
+  tags: string[]
+}
+
+const parseInput = (raw: unknown): E.Either<string, ParsedInput> =>
+  pipe(
+    E.Do,
+    E.bind('obj', () =>
+      typeof raw === 'object' && raw !== null
+        ? E.right(raw as Record<string, unknown>)
+        : E.left('Input must be an object')
+    ),
+    E.bind('id', ({ obj }) =>
+      typeof obj.id === 'number'
+        ? E.right(obj.id)
+        : E.left('id must be a number')
+    ),
+    E.bind('name', ({ obj }) =>
+      typeof obj.name === 'string' && obj.name.length > 0
+        ? E.right(obj.name)
+        : E.left('name must be a non-empty string')
+    ),
+    E.bind('tags', ({ obj }) =>
+      Array.isArray(obj.tags) && obj.tags.every(t => typeof t === 'string')
+        ? E.right(obj.tags as string[])
+        : E.left('tags must be an array of strings')
+    ),
+    E.map(({ id, name, tags }) => ({ id, name, tags }))
+  )
+
+// Usage
+parseInput({ id: 1, name: 'test', tags: ['a', 'b'] })
+// Right({ id: 1, name: 'test', tags: ['a', 'b'] })
+
+parseInput({ id: 'wrong', name: '', tags: null })
+// Left('id must be a number')
+```
+
+### API Call with Full Error Handling
+
+```typescript
+interface ApiError {
+  code: string
+  message: string
+  status?: number
+}
+
+const createApiError = (message: string, code = 'UNKNOWN', status?: number): ApiError =>
+  ({ code, message, status })
+
+const fetchWithErrorHandling = <T>(url: string): TE.TaskEither<ApiError, T> =>
+  pipe(
+    TE.tryCatch(
+      () => fetch(url),
+      () => createApiError('Network error', 'NETWORK')
+    ),
+    TE.chain(response =>
+      response.ok
+        ? TE.tryCatch(
+            () => response.json() as Promise<T>,
+            () => createApiError('Invalid JSON', 'PARSE')
+          )
+        : TE.left(createApiError(
+            `HTTP ${response.status}`,
+            response.status === 404 ? 'NOT_FOUND' : 'HTTP_ERROR',
+            response.status
+          ))
+    )
+  )
+
+// Usage with pattern matching on error codes
+const handleUserFetch = (userId: string) =>
+  pipe(
+    fetchWithErrorHandling<User>(`/api/users/${userId}`),
+    TE.fold(
+      (error) => {
+        switch (error.code) {
+          case 'NOT_FOUND': return T.of(showNotFoundPage())
+          case 'NETWORK': return T.of(showOfflineMessage())
+          default: return T.of(showGenericError(error.message))
+        }
+      },
+      (user) => T.of(showUserProfile(user))
+    )
+  )
+```
+
+### Process List Where Some Items Might Fail
+
+```typescript
+import * as A from 'fp-ts/Array'
+import * as E from 'fp-ts/Either'
+import { pipe } from 'fp-ts/function'
+
+interface ProcessResult<T> {
+  successes: T[]
+  failures: Array<{ item: unknown; error: string }>
+}
+
+// Process all, collect successes and failures separately
+const processAllCollectErrors = <T, R>(
+  items: T[],
+  process: (item: T) => E.Either<string, R>
+): ProcessResult<R> => {
+  const results = items.map((item, index) =>
+    pipe(
+      process(item),
+      E.mapLeft(error => ({ item, error, index }))
+    )
+  )
+
+  return {
+    successes: pipe(results, A.filterMap(E.toOption)),
+    failures: pipe(
+      results,
+      A.filterMap(r => E.isLeft(r) ? O.some(r.left) : O.none)
+    )
+  }
+}
+
+// Usage
+const parseNumbers = (inputs: string[]) =>
+  processAllCollectErrors(inputs, input => {
+    const n = parseInt(input, 10)
+    return isNaN(n) ? E.left(`Invalid number: ${input}`) : E.right(n)
+  })
+
+parseNumbers(['1', 'abc', '3', 'def'])
+// {
+//   successes: [1, 3],
+//   failures: [
+//     { item: 'abc', error: 'Invalid number: abc', index: 1 },
+//     { item: 'def', error: 'Invalid number: def', index: 3 }
+//   ]
+// }
+```
+
+### Bulk Operations with Partial Success
+
+```typescript
+import * as TE from 'fp-ts/TaskEither'
+import * as T from 'fp-ts/Task'
+import { pipe } from 'fp-ts/function'
+
+interface BulkResult<T> {
+  succeeded: T[]
+  failed: Array<{ id: string; error: string }>
+}
+
+const bulkProcess = <T>(
+  ids: string[],
+  process: (id: string) => TE.TaskEither<string, T>
+): T.Task<BulkResult<T>> =>
+  pipe(
+    ids,
+    A.map(id =>
+      pipe(
+        process(id),
+        TE.fold(
+          (error) => T.of({ type: 'failed' as const, id, error }),
+          (result) => T.of({ type: 'succeeded' as const, result })
+        )
+      )
+    ),
+    T.sequenceArray,
+    T.map(results => ({
+      succeeded: results
+        .filter((r): r is { type: 'succeeded'; result: T } => r.type === 'succeeded')
+        .map(r => r.result),
+      failed: results
+        .filter((r): r is { type: 'failed'; id: string; error: string } => r.type === 'failed')
+        .map(({ id, error }) => ({ id, error }))
+    }))
+  )
+
+// Usage
+const deleteUsers = (userIds: string[]) =>
+  bulkProcess(userIds, id =>
+    pipe(
+      deleteUser(id),
+      TE.mapLeft(e => e.message)
+    )
+  )
+
+// All operations run, you get a report of what worked and what didn't
+```
+
+---
+
+## Quick Reference
+
+| Pattern | Use When | Example |
+|---------|----------|---------|
+| `E.right(value)` | Creating a success | `E.right(42)` |
+| `E.left(error)` | Creating a failure | `E.left('not found')` |
+| `E.tryCatch(fn, onError)` | Wrapping throwing code | `E.tryCatch(() => JSON.parse(s), toError)` |
+| `E.fromNullable(error)` | Converting nullable | `E.fromNullable('missing')(maybeValue)` |
+| `E.map(fn)` | Transform success | `pipe(result, E.map(x => x * 2))` |
+| `E.mapLeft(fn)` | Transform error | `pipe(result, E.mapLeft(addContext))` |
+| `E.chain(fn)` | Chain operations | `pipe(getA(), E.chain(a => getB(a.id)))` |
+| `E.chainW(fn)` | Chain with different error type | `pipe(validate(), E.chainW(save))` |
+| `E.fold(onError, onSuccess)` | Handle both cases | `E.fold(showError, showData)` |
+| `E.getOrElse(onError)` | Extract with default | `E.getOrElse(() => 0)` |
+| `E.filterOrElse(pred, onFalse)` | Validate with error | `E.filterOrElse(x => x > 0, () => 'must be positive')` |
+| `sequenceS(validation)({...})` | Collect all errors | Form validation |
+
+### TaskEither Equivalents
+
+All Either operations have TaskEither equivalents:
+- `TE.right`, `TE.left`, `TE.tryCatch`
+- `TE.map`, `TE.mapLeft`, `TE.chain`, `TE.chainW`
+- `TE.fold`, `TE.getOrElse`, `TE.filterOrElse`
+- `TE.orElse` for fallbacks
+
+---
+
+## Summary
+
+1. **Return errors as values** - Use Either/TaskEither instead of throwing
+2. **Chain with confidence** - `chain` stops at first error automatically
+3. **Collect all errors when needed** - Use validation applicative for forms
+4. **Wrap at boundaries** - Convert throwing/Promise code at the edges
+5. **Match at the end** - Use `fold` to handle both cases when you're ready to act
+
+The payoff: TypeScript tracks your errors, no more forgotten try/catch, clear control flow, and composable error handling.

skills/fp-ts-pragmatic/SKILL.md

@@ -0,0 +1,598 @@
+---
+name: fp-ts-pragmatic
+description: A practical, jargon-free guide to fp-ts functional programming - the 80/20 approach that gets results without the academic overhead. Use when writing TypeScript with fp-ts library.
+risk: safe
+source: https://github.com/whatiskadudoing/fp-ts-skills
+---
+
+# Pragmatic Functional Programming
+
+**Read this first.** This guide cuts through the academic jargon and shows you what actually matters. No category theory. No abstract nonsense. Just patterns that make your code better.
+
+## When to Use This Skill
+
+- When starting with fp-ts and need practical guidance
+- When writing TypeScript code that handles nullable values, errors, or async operations
+- When you want cleaner, more maintainable functional code without the academic overhead
+- When refactoring imperative code to functional style
+
+## The Golden Rule
+
+> **If functional programming makes your code harder to read, don't use it.**
+
+FP is a tool, not a religion. Use it when it helps. Skip it when it doesn't.
+
+---
+
+## The 80/20 of FP
+
+These five patterns give you most of the benefits. Master these before exploring anything else.
+
+### 1. Pipe: Chain Operations Clearly
+
+Instead of nesting function calls or creating intermediate variables, chain operations in reading order.
+
+```typescript
+import { pipe } from 'fp-ts/function'
+
+// Before: Hard to read (inside-out)
+const result = format(validate(parse(input)))
+
+// Before: Too many variables
+const parsed = parse(input)
+const validated = validate(parsed)
+const result = format(validated)
+
+// After: Clear, linear flow
+const result = pipe(
+  input,
+  parse,
+  validate,
+  format
+)
+```
+
+**When to use pipe:**
+- 3+ transformations on the same data
+- You find yourself naming throwaway variables
+- Logic reads better top-to-bottom
+
+**When to skip pipe:**
+- Just 1-2 operations (direct call is fine)
+- The operations don't naturally chain
+
+### 2. Option: Handle Missing Values Without null Checks
+
+Stop writing `if (x !== null && x !== undefined)` everywhere.
+
+```typescript
+import * as O from 'fp-ts/Option'
+import { pipe } from 'fp-ts/function'
+
+// Before: Defensive null checking
+function getUserCity(user: User | null): string {
+  if (user === null) return 'Unknown'
+  if (user.address === null) return 'Unknown'
+  if (user.address.city === null) return 'Unknown'
+  return user.address.city
+}
+
+// After: Chain through potential missing values
+const getUserCity = (user: User | null): string =>
+  pipe(
+    O.fromNullable(user),
+    O.flatMap(u => O.fromNullable(u.address)),
+    O.flatMap(a => O.fromNullable(a.city)),
+    O.getOrElse(() => 'Unknown')
+  )
+```
+
+**Plain language translation:**
+- `O.fromNullable(x)` = "wrap this value, treating null/undefined as 'nothing'"
+- `O.flatMap(fn)` = "if we have something, apply this function"
+- `O.getOrElse(() => default)` = "unwrap, or use this default if nothing"
+
+### 3. Either: Make Errors Explicit
+
+Stop throwing exceptions for expected failures. Return errors as values.
+
+```typescript
+import * as E from 'fp-ts/Either'
+import { pipe } from 'fp-ts/function'
+
+// Before: Hidden failure mode
+function parseAge(input: string): number {
+  const age = parseInt(input, 10)
+  if (isNaN(age)) throw new Error('Invalid age')
+  if (age < 0) throw new Error('Age cannot be negative')
+  return age
+}
+
+// After: Errors are visible in the type
+function parseAge(input: string): E.Either<string, number> {
+  const age = parseInt(input, 10)
+  if (isNaN(age)) return E.left('Invalid age')
+  if (age < 0) return E.left('Age cannot be negative')
+  return E.right(age)
+}
+
+// Using it
+const result = parseAge(userInput)
+if (E.isRight(result)) {
+  console.log(`Age is ${result.right}`)
+} else {
+  console.log(`Error: ${result.left}`)
+}
+```
+
+**Plain language translation:**
+- `E.right(value)` = "success with this value"
+- `E.left(error)` = "failure with this error"
+- `E.isRight(x)` = "did it succeed?"
+
+### 4. Map: Transform Without Unpacking
+
+Transform values inside containers without extracting them first.
+
+```typescript
+import * as O from 'fp-ts/Option'
+import * as E from 'fp-ts/Either'
+import * as A from 'fp-ts/Array'
+import { pipe } from 'fp-ts/function'
+
+// Transform inside Option
+const maybeUser: O.Option<User> = O.some({ name: 'Alice', age: 30 })
+const maybeName: O.Option<string> = pipe(
+  maybeUser,
+  O.map(user => user.name)
+)
+
+// Transform inside Either
+const result: E.Either<Error, number> = E.right(5)
+const doubled: E.Either<Error, number> = pipe(
+  result,
+  E.map(n => n * 2)
+)
+
+// Transform arrays (same concept!)
+const numbers = [1, 2, 3]
+const doubled = pipe(
+  numbers,
+  A.map(n => n * 2)
+)
+```
+
+### 5. FlatMap: Chain Operations That Might Fail
+
+When each step might fail, chain them together.
+
+```typescript
+import * as E from 'fp-ts/Either'
+import { pipe } from 'fp-ts/function'
+
+const parseJSON = (s: string): E.Either<string, unknown> =>
+  E.tryCatch(() => JSON.parse(s), () => 'Invalid JSON')
+
+const extractEmail = (data: unknown): E.Either<string, string> => {
+  if (typeof data === 'object' && data !== null && 'email' in data) {
+    return E.right((data as { email: string }).email)
+  }
+  return E.left('No email field')
+}
+
+const validateEmail = (email: string): E.Either<string, string> =>
+  email.includes('@') ? E.right(email) : E.left('Invalid email format')
+
+// Chain all steps - if any fails, the whole thing fails
+const getValidEmail = (input: string): E.Either<string, string> =>
+  pipe(
+    parseJSON(input),
+    E.flatMap(extractEmail),
+    E.flatMap(validateEmail)
+  )
+
+// Success path: Right('user@example.com')
+// Any failure: Left('specific error message')
+```
+
+**Plain language:** `flatMap` means "if this succeeded, try the next thing"
+
+---
+
+## When NOT to Use FP
+
+Functional programming is not always the answer. Here's when to keep it simple.
+
+### Simple Null Checks
+
+```typescript
+// Just use optional chaining - it's built into the language
+const city = user?.address?.city ?? 'Unknown'
+
+// DON'T overcomplicate it
+const city = pipe(
+  O.fromNullable(user),
+  O.flatMap(u => O.fromNullable(u.address)),
+  O.flatMap(a => O.fromNullable(a.city)),
+  O.getOrElse(() => 'Unknown')
+)
+```
+
+### Simple Loops
+
+```typescript
+// A for loop is fine when you need early exit or complex logic
+function findFirst(items: Item[], predicate: (i: Item) => boolean): Item | null {
+  for (const item of items) {
+    if (predicate(item)) return item
+  }
+  return null
+}
+
+// DON'T force FP when it doesn't help
+const result = pipe(
+  items,
+  A.findFirst(predicate),
+  O.toNullable
+)
+```
+
+### Performance-Critical Code
+
+```typescript
+// For hot paths, imperative is faster (no intermediate arrays)
+function sumLarge(numbers: number[]): number {
+  let sum = 0
+  for (let i = 0; i < numbers.length; i++) {
+    sum += numbers[i]
+  }
+  return sum
+}
+
+// fp-ts creates intermediate structures
+const sum = pipe(numbers, A.reduce(0, (acc, n) => acc + n))
+```
+
+### When Your Team Doesn't Know FP
+
+If you're the only one who can read the code, it's not good code.
+
+```typescript
+// If your team knows this pattern
+async function getUser(id: string): Promise<User | null> {
+  try {
+    const response = await fetch(`/api/users/${id}`)
+    if (!response.ok) return null
+    return await response.json()
+  } catch {
+    return null
+  }
+}
+
+// Don't force this on them
+const getUser = (id: string): TE.TaskEither<Error, User> =>
+  pipe(
+    TE.tryCatch(() => fetch(`/api/users/${id}`), E.toError),
+    TE.flatMap(r => r.ok ? TE.right(r) : TE.left(new Error('Not found'))),
+    TE.flatMap(r => TE.tryCatch(() => r.json(), E.toError))
+  )
+```
+
+---
+
+## Quick Wins: Easy Changes That Improve Code Today
+
+### 1. Replace Nested Ternaries with pipe + fold
+
+```typescript
+// Before: Nested ternary nightmare
+const message = user === null
+  ? 'No user'
+  : user.isAdmin
+    ? `Admin: ${user.name}`
+    : `User: ${user.name}`
+
+// After: Clear case handling
+const message = pipe(
+  O.fromNullable(user),
+  O.fold(
+    () => 'No user',
+    (u) => u.isAdmin ? `Admin: ${u.name}` : `User: ${u.name}`
+  )
+)
+```
+
+### 2. Replace try-catch with tryCatch
+
+```typescript
+// Before: try-catch everywhere
+let config
+try {
+  config = JSON.parse(rawConfig)
+} catch {
+  config = defaultConfig
+}
+
+// After: One-liner
+const config = pipe(
+  E.tryCatch(() => JSON.parse(rawConfig), () => 'parse error'),
+  E.getOrElse(() => defaultConfig)
+)
+```
+
+### 3. Replace undefined Returns with Option
+
+```typescript
+// Before: Caller might forget to check
+function findUser(id: string): User | undefined {
+  return users.find(u => u.id === id)
+}
+
+// After: Type forces caller to handle missing case
+function findUser(id: string): O.Option<User> {
+  return O.fromNullable(users.find(u => u.id === id))
+}
+```
+
+### 4. Replace Error Strings with Typed Errors
+
+```typescript
+// Before: Just strings
+function validate(data: unknown): E.Either<string, User> {
+  // ...
+  return E.left('validation failed')
+}
+
+// After: Structured errors
+type ValidationError = {
+  field: string
+  message: string
+}
+
+function validate(data: unknown): E.Either<ValidationError, User> {
+  // ...
+  return E.left({ field: 'email', message: 'Invalid format' })
+}
+```
+
+### 5. Use const Assertions for Error Types
+
+```typescript
+// Create specific error types without classes
+const NotFound = (id: string) => ({ _tag: 'NotFound' as const, id })
+const Unauthorized = { _tag: 'Unauthorized' as const }
+const ValidationFailed = (errors: string[]) =>
+  ({ _tag: 'ValidationFailed' as const, errors })
+
+type AppError =
+  | ReturnType<typeof NotFound>
+  | typeof Unauthorized
+  | ReturnType<typeof ValidationFailed>
+
+// Now you can pattern match
+const handleError = (error: AppError): string => {
+  switch (error._tag) {
+    case 'NotFound': return `Item ${error.id} not found`
+    case 'Unauthorized': return 'Please log in'
+    case 'ValidationFailed': return error.errors.join(', ')
+  }
+}
+```
+
+---
+
+## Common Refactors: Before and After
+
+### Callback Hell to Pipe
+
+```typescript
+// Before
+fetchUser(id, (user) => {
+  if (!user) return handleNoUser()
+  fetchPosts(user.id, (posts) => {
+    if (!posts) return handleNoPosts()
+    fetchComments(posts[0].id, (comments) => {
+      render(user, posts, comments)
+    })
+  })
+})
+
+// After (with TaskEither for async)
+import * as TE from 'fp-ts/TaskEither'
+
+const loadData = (id: string) =>
+  pipe(
+    fetchUser(id),
+    TE.flatMap(user => pipe(
+      fetchPosts(user.id),
+      TE.map(posts => ({ user, posts }))
+    )),
+    TE.flatMap(({ user, posts }) => pipe(
+      fetchComments(posts[0].id),
+      TE.map(comments => ({ user, posts, comments }))
+    ))
+  )
+
+// Execute
+const result = await loadData('123')()
+pipe(
+  result,
+  E.fold(handleError, ({ user, posts, comments }) => render(user, posts, comments))
+)
+```
+
+### Multiple null Checks to Option Chain
+
+```typescript
+// Before
+function getManagerEmail(employee: Employee): string | null {
+  if (!employee.department) return null
+  if (!employee.department.manager) return null
+  if (!employee.department.manager.email) return null
+  return employee.department.manager.email
+}
+
+// After
+const getManagerEmail = (employee: Employee): O.Option<string> =>
+  pipe(
+    O.fromNullable(employee.department),
+    O.flatMap(d => O.fromNullable(d.manager)),
+    O.flatMap(m => O.fromNullable(m.email))
+  )
+
+// Use it
+pipe(
+  getManagerEmail(employee),
+  O.fold(
+    () => sendToDefault(),
+    (email) => sendTo(email)
+  )
+)
+```
+
+### Validation with Multiple Checks
+
+```typescript
+// Before: Throws on first error
+function validateUser(data: unknown): User {
+  if (!data || typeof data !== 'object') throw new Error('Must be object')
+  const obj = data as Record<string, unknown>
+  if (typeof obj.email !== 'string') throw new Error('Email required')
+  if (!obj.email.includes('@')) throw new Error('Invalid email')
+  if (typeof obj.age !== 'number') throw new Error('Age required')
+  if (obj.age < 0) throw new Error('Age must be positive')
+  return obj as User
+}
+
+// After: Returns first error, type-safe
+const validateUser = (data: unknown): E.Either<string, User> =>
+  pipe(
+    E.Do,
+    E.bind('obj', () =>
+      typeof data === 'object' && data !== null
+        ? E.right(data as Record<string, unknown>)
+        : E.left('Must be object')
+    ),
+    E.bind('email', ({ obj }) =>
+      typeof obj.email === 'string' && obj.email.includes('@')
+        ? E.right(obj.email)
+        : E.left('Valid email required')
+    ),
+    E.bind('age', ({ obj }) =>
+      typeof obj.age === 'number' && obj.age >= 0
+        ? E.right(obj.age)
+        : E.left('Valid age required')
+    ),
+    E.map(({ email, age }) => ({ email, age }))
+  )
+```
+
+### Promise Chain to TaskEither
+
+```typescript
+// Before
+async function processOrder(orderId: string): Promise<Receipt> {
+  const order = await fetchOrder(orderId)
+  if (!order) throw new Error('Order not found')
+
+  const validated = await validateOrder(order)
+  if (!validated.success) throw new Error(validated.error)
+
+  const payment = await processPayment(validated.order)
+  if (!payment.success) throw new Error('Payment failed')
+
+  return generateReceipt(payment)
+}
+
+// After
+const processOrder = (orderId: string): TE.TaskEither<string, Receipt> =>
+  pipe(
+    fetchOrderTE(orderId),
+    TE.flatMap(order =>
+      order ? TE.right(order) : TE.left('Order not found')
+    ),
+    TE.flatMap(validateOrderTE),
+    TE.flatMap(processPaymentTE),
+    TE.map(generateReceipt)
+  )
+```
+
+---
+
+## The Readability Rule
+
+Before using any FP pattern, ask: **"Would a junior developer understand this?"**
+
+### Too Clever (Avoid)
+
+```typescript
+const result = pipe(
+  data,
+  A.filter(flow(prop('status'), equals('active'))),
+  A.map(flow(prop('value'), multiply(2))),
+  A.reduce(monoid.concat, monoid.empty),
+  O.fromPredicate(gt(threshold))
+)
+```
+
+### Just Right (Prefer)
+
+```typescript
+const activeItems = data.filter(item => item.status === 'active')
+const doubledValues = activeItems.map(item => item.value * 2)
+const total = doubledValues.reduce((sum, val) => sum + val, 0)
+const result = total > threshold ? O.some(total) : O.none
+```
+
+### The Middle Ground (Often Best)
+
+```typescript
+const result = pipe(
+  data,
+  A.filter(item => item.status === 'active'),
+  A.map(item => item.value * 2),
+  A.reduce(0, (sum, val) => sum + val),
+  total => total > threshold ? O.some(total) : O.none
+)
+```
+
+---
+
+## Cheat Sheet
+
+| What you want | Plain language | fp-ts |
+|--------------|----------------|-------|
+| Handle null/undefined | "Wrap this nullable" | `O.fromNullable(x)` |
+| Default for missing | "Use this if nothing" | `O.getOrElse(() => default)` |
+| Transform if present | "If something, change it" | `O.map(fn)` |
+| Chain nullable operations | "If something, try this" | `O.flatMap(fn)` |
+| Return success | "Worked, here's the value" | `E.right(value)` |
+| Return failure | "Failed, here's why" | `E.left(error)` |
+| Wrap throwing function | "Try this, catch errors" | `E.tryCatch(fn, onError)` |
+| Handle both cases | "Do this for error, that for success" | `E.fold(onLeft, onRight)` |
+| Chain operations | "Then do this, then that" | `pipe(x, fn1, fn2, fn3)` |
+
+---
+
+## When to Level Up
+
+Once comfortable with these patterns, explore:
+
+1. **TaskEither** - Async operations that can fail (replaces Promise + try/catch)
+2. **Validation** - Collect ALL errors instead of stopping at first
+3. **Reader** - Dependency injection without classes
+4. **Do notation** - Cleaner syntax for multiple bindings
+
+But don't rush. The basics here will handle 80% of real-world scenarios. Get comfortable with these before adding more tools to your belt.
+
+---
+
+## Summary
+
+1. **Use pipe** for 3+ operations
+2. **Use Option** for nullable chains
+3. **Use Either** for operations that can fail
+4. **Use map** to transform wrapped values
+5. **Use flatMap** to chain operations that might fail
+6. **Skip FP** when it hurts readability
+7. **Keep it simple** - if your team can't read it, it's not good code

skills/fp-ts-react/SKILL.md

@@ -0,0 +1,796 @@
+---
+name: fp-ts-react
+description: Practical patterns for using fp-ts with React - hooks, state, forms, data fetching. Use when building React apps with functional programming patterns. Works with React 18/19, Next.js 14/15.
+risk: safe
+source: https://github.com/whatiskadudoing/fp-ts-skills
+---
+
+# Functional Programming in React
+
+Practical patterns for React apps. No jargon, just code that works.
+
+## When to Use This Skill
+
+- When building React apps with fp-ts for type-safe state management
+- When handling loading/error/success states in data fetching
+- When implementing form validation with error accumulation
+- When using React 18/19 or Next.js 14/15 with functional patterns
+
+---
+
+## Quick Reference
+
+| Pattern | Use When |
+|---------|----------|
+| `Option` | Value might be missing (user not loaded yet) |
+| `Either` | Operation might fail (form validation) |
+| `TaskEither` | Async operation might fail (API calls) |
+| `RemoteData` | Need to show loading/error/success states |
+| `pipe` | Chaining multiple transformations |
+
+---
+
+## 1. State with Option (Maybe It's There, Maybe Not)
+
+Use `Option` instead of `null | undefined` for clearer intent.
+
+### Basic Pattern
+
+```typescript
+import { useState } from 'react'
+import * as O from 'fp-ts/Option'
+import { pipe } from 'fp-ts/function'
+
+interface User {
+  id: string
+  name: string
+  email: string
+}
+
+function UserProfile() {
+  // Option says "this might not exist yet"
+  const [user, setUser] = useState<O.Option<User>>(O.none)
+
+  const handleLogin = (userData: User) => {
+    setUser(O.some(userData))
+  }
+
+  const handleLogout = () => {
+    setUser(O.none)
+  }
+
+  return pipe(
+    user,
+    O.match(
+      // When there's no user
+      () => <button onClick={() => handleLogin({ id: '1', name: 'Alice', email: 'alice@example.com' })}>
+        Log In
+      </button>,
+      // When there's a user
+      (u) => (
+        <div>
+          <p>Welcome, {u.name}!</p>
+          <button onClick={handleLogout}>Log Out</button>
+        </div>
+      )
+    )
+  )
+}
+```
+
+### Chaining Optional Values
+
+```typescript
+import * as O from 'fp-ts/Option'
+import { pipe } from 'fp-ts/function'
+
+interface Profile {
+  user: O.Option<{
+    name: string
+    settings: O.Option<{
+      theme: string
+    }>
+  }>
+}
+
+function getTheme(profile: Profile): string {
+  return pipe(
+    profile.user,
+    O.flatMap(u => u.settings),
+    O.map(s => s.theme),
+    O.getOrElse(() => 'light') // default
+  )
+}
+```
+
+---
+
+## 2. Form Validation with Either
+
+Either is perfect for validation: `Left` = errors, `Right` = valid data.
+
+### Simple Form Validation
+
+```typescript
+import * as E from 'fp-ts/Either'
+import * as A from 'fp-ts/Array'
+import { pipe } from 'fp-ts/function'
+
+// Validation functions return Either<ErrorMessage, ValidValue>
+const validateEmail = (email: string): E.Either<string, string> =>
+  email.includes('@')
+    ? E.right(email)
+    : E.left('Invalid email address')
+
+const validatePassword = (password: string): E.Either<string, string> =>
+  password.length >= 8
+    ? E.right(password)
+    : E.left('Password must be at least 8 characters')
+
+const validateName = (name: string): E.Either<string, string> =>
+  name.trim().length > 0
+    ? E.right(name.trim())
+    : E.left('Name is required')
+```
+
+### Collecting All Errors (Not Just First One)
+
+```typescript
+import * as E from 'fp-ts/Either'
+import { sequenceS } from 'fp-ts/Apply'
+import { getSemigroup } from 'fp-ts/NonEmptyArray'
+import { pipe } from 'fp-ts/function'
+
+// This collects ALL errors, not just the first one
+const validateAll = sequenceS(E.getApplicativeValidation(getSemigroup<string>()))
+
+interface SignupForm {
+  name: string
+  email: string
+  password: string
+}
+
+interface ValidatedForm {
+  name: string
+  email: string
+  password: string
+}
+
+function validateForm(form: SignupForm): E.Either<string[], ValidatedForm> {
+  return pipe(
+    validateAll({
+      name: pipe(validateName(form.name), E.mapLeft(e => [e])),
+      email: pipe(validateEmail(form.email), E.mapLeft(e => [e])),
+      password: pipe(validatePassword(form.password), E.mapLeft(e => [e])),
+    })
+  )
+}
+
+// Usage in component
+function SignupForm() {
+  const [form, setForm] = useState({ name: '', email: '', password: '' })
+  const [errors, setErrors] = useState<string[]>([])
+
+  const handleSubmit = () => {
+    pipe(
+      validateForm(form),
+      E.match(
+        (errs) => setErrors(errs),     // Show all errors
+        (valid) => {
+          setErrors([])
+          submitToServer(valid)         // Submit valid data
+        }
+      )
+    )
+  }
+
+  return (
+    <form onSubmit={e => { e.preventDefault(); handleSubmit() }}>
+      <input
+        value={form.name}
+        onChange={e => setForm(f => ({ ...f, name: e.target.value }))}
+        placeholder="Name"
+      />
+      <input
+        value={form.email}
+        onChange={e => setForm(f => ({ ...f, email: e.target.value }))}
+        placeholder="Email"
+      />
+      <input
+        type="password"
+        value={form.password}
+        onChange={e => setForm(f => ({ ...f, password: e.target.value }))}
+        placeholder="Password"
+      />
+
+      {errors.length > 0 && (
+        <ul style={{ color: 'red' }}>
+          {errors.map((err, i) => <li key={i}>{err}</li>)}
+        </ul>
+      )}
+
+      <button type="submit">Sign Up</button>
+    </form>
+  )
+}
+```
+
+### Field-Level Errors (Better UX)
+
+```typescript
+type FieldErrors = Partial<Record<keyof SignupForm, string>>
+
+function validateFormWithFieldErrors(form: SignupForm): E.Either<FieldErrors, ValidatedForm> {
+  const errors: FieldErrors = {}
+
+  pipe(validateName(form.name), E.mapLeft(e => { errors.name = e }))
+  pipe(validateEmail(form.email), E.mapLeft(e => { errors.email = e }))
+  pipe(validatePassword(form.password), E.mapLeft(e => { errors.password = e }))
+
+  return Object.keys(errors).length > 0
+    ? E.left(errors)
+    : E.right({ name: form.name.trim(), email: form.email, password: form.password })
+}
+
+// In component
+{errors.email && <span className="error">{errors.email}</span>}
+```
+
+---
+
+## 3. Data Fetching with TaskEither
+
+TaskEither = async operation that might fail. Perfect for API calls.
+
+### Basic Fetch Hook
+
+```typescript
+import { useState, useEffect } from 'react'
+import * as TE from 'fp-ts/TaskEither'
+import * as E from 'fp-ts/Either'
+import { pipe } from 'fp-ts/function'
+
+// Wrap fetch in TaskEither
+const fetchJson = <T>(url: string): TE.TaskEither<Error, T> =>
+  TE.tryCatch(
+    async () => {
+      const res = await fetch(url)
+      if (!res.ok) throw new Error(`HTTP ${res.status}`)
+      return res.json()
+    },
+    (err) => err instanceof Error ? err : new Error(String(err))
+  )
+
+// Custom hook
+function useFetch<T>(url: string) {
+  const [data, setData] = useState<T | null>(null)
+  const [error, setError] = useState<Error | null>(null)
+  const [loading, setLoading] = useState(true)
+
+  useEffect(() => {
+    setLoading(true)
+    setError(null)
+
+    pipe(
+      fetchJson<T>(url),
+      TE.match(
+        (err) => {
+          setError(err)
+          setLoading(false)
+        },
+        (result) => {
+          setData(result)
+          setLoading(false)
+        }
+      )
+    )()
+  }, [url])
+
+  return { data, error, loading }
+}
+
+// Usage
+function UserList() {
+  const { data, error, loading } = useFetch<User[]>('/api/users')
+
+  if (loading) return <div>Loading...</div>
+  if (error) return <div>Error: {error.message}</div>
+  return (
+    <ul>
+      {data?.map(user => <li key={user.id}>{user.name}</li>)}
+    </ul>
+  )
+}
+```
+
+### Chaining API Calls
+
+```typescript
+// Fetch user, then fetch their posts
+const fetchUserWithPosts = (userId: string) => pipe(
+  fetchJson<User>(`/api/users/${userId}`),
+  TE.flatMap(user => pipe(
+    fetchJson<Post[]>(`/api/users/${userId}/posts`),
+    TE.map(posts => ({ ...user, posts }))
+  ))
+)
+```
+
+### Parallel API Calls
+
+```typescript
+import { sequenceT } from 'fp-ts/Apply'
+
+// Fetch multiple things at once
+const fetchDashboardData = () => pipe(
+  sequenceT(TE.ApplyPar)(
+    fetchJson<User>('/api/user'),
+    fetchJson<Stats>('/api/stats'),
+    fetchJson<Notifications[]>('/api/notifications')
+  ),
+  TE.map(([user, stats, notifications]) => ({
+    user,
+    stats,
+    notifications
+  }))
+)
+```
+
+---
+
+## 4. RemoteData Pattern (The Right Way to Handle Async State)
+
+Stop using `{ data, loading, error }` booleans. Use a proper state machine.
+
+### The Pattern
+
+```typescript
+// RemoteData has exactly 4 states - no impossible combinations
+type RemoteData<E, A> =
+  | { _tag: 'NotAsked' }                    // Haven't started yet
+  | { _tag: 'Loading' }                     // In progress
+  | { _tag: 'Failure'; error: E }           // Failed
+  | { _tag: 'Success'; data: A }            // Got it!
+
+// Constructors
+const notAsked = <E, A>(): RemoteData<E, A> => ({ _tag: 'NotAsked' })
+const loading = <E, A>(): RemoteData<E, A> => ({ _tag: 'Loading' })
+const failure = <E, A>(error: E): RemoteData<E, A> => ({ _tag: 'Failure', error })
+const success = <E, A>(data: A): RemoteData<E, A> => ({ _tag: 'Success', data })
+
+// Pattern match all states
+function fold<E, A, R>(
+  rd: RemoteData<E, A>,
+  onNotAsked: () => R,
+  onLoading: () => R,
+  onFailure: (e: E) => R,
+  onSuccess: (a: A) => R
+): R {
+  switch (rd._tag) {
+    case 'NotAsked': return onNotAsked()
+    case 'Loading': return onLoading()
+    case 'Failure': return onFailure(rd.error)
+    case 'Success': return onSuccess(rd.data)
+  }
+}
+```
+
+### Hook with RemoteData
+
+```typescript
+function useRemoteData<T>(fetchFn: () => Promise<T>) {
+  const [state, setState] = useState<RemoteData<Error, T>>(notAsked())
+
+  const execute = async () => {
+    setState(loading())
+    try {
+      const data = await fetchFn()
+      setState(success(data))
+    } catch (err) {
+      setState(failure(err instanceof Error ? err : new Error(String(err))))
+    }
+  }
+
+  return { state, execute }
+}
+
+// Usage
+function UserProfile({ userId }: { userId: string }) {
+  const { state, execute } = useRemoteData(() =>
+    fetch(`/api/users/${userId}`).then(r => r.json())
+  )
+
+  useEffect(() => { execute() }, [userId])
+
+  return fold(
+    state,
+    () => <button onClick={execute}>Load User</button>,
+    () => <Spinner />,
+    (err) => <ErrorMessage message={err.message} onRetry={execute} />,
+    (user) => <UserCard user={user} />
+  )
+}
+```
+
+### Why RemoteData Beats Booleans
+
+```typescript
+// ❌ BAD: Impossible states are possible
+interface BadState {
+  data: User | null
+  loading: boolean
+  error: Error | null
+}
+// Can have: { data: user, loading: true, error: someError } - what does that mean?!
+
+// ✅ GOOD: Only valid states exist
+type GoodState = RemoteData<Error, User>
+// Can only be: NotAsked | Loading | Failure | Success
+```
+
+---
+
+## 5. Referential Stability (Preventing Re-renders)
+
+fp-ts values like `O.some(1)` create new objects each render. React sees them as "changed".
+
+### The Problem
+
+```typescript
+// ❌ BAD: Creates new Option every render
+function BadComponent() {
+  const [value, setValue] = useState(O.some(1))
+
+  useEffect(() => {
+    // This runs EVERY render because O.some(1) !== O.some(1)
+    console.log('value changed')
+  }, [value])
+}
+```
+
+### Solution 1: useMemo
+
+```typescript
+// ✅ GOOD: Memoize Option creation
+function GoodComponent() {
+  const [rawValue, setRawValue] = useState<number | null>(1)
+
+  const value = useMemo(
+    () => O.fromNullable(rawValue),
+    [rawValue]  // Only recreate when rawValue changes
+  )
+
+  useEffect(() => {
+    // Now this only runs when rawValue actually changes
+    console.log('value changed')
+  }, [rawValue])  // Depend on raw value, not Option
+}
+```
+
+### Solution 2: fp-ts-react-stable-hooks
+
+```bash
+npm install fp-ts-react-stable-hooks
+```
+
+```typescript
+import { useStableO, useStableEffect } from 'fp-ts-react-stable-hooks'
+import * as O from 'fp-ts/Option'
+import * as Eq from 'fp-ts/Eq'
+
+function StableComponent() {
+  // Uses fp-ts equality instead of reference equality
+  const [value, setValue] = useStableO(O.some(1))
+
+  // Effect that understands Option equality
+  useStableEffect(
+    () => { console.log('value changed') },
+    [value],
+    Eq.tuple(O.getEq(Eq.eqNumber))  // Custom equality
+  )
+}
+```
+
+---
+
+## 6. Dependency Injection with Context
+
+Use ReaderTaskEither for testable components with injected dependencies.
+
+### Setup Dependencies
+
+```typescript
+import * as RTE from 'fp-ts/ReaderTaskEither'
+import { pipe } from 'fp-ts/function'
+import { createContext, useContext, ReactNode } from 'react'
+
+// Define what services your app needs
+interface AppDependencies {
+  api: {
+    getUser: (id: string) => Promise<User>
+    updateUser: (id: string, data: Partial<User>) => Promise<User>
+  }
+  analytics: {
+    track: (event: string, data?: object) => void
+  }
+}
+
+// Create context
+const DepsContext = createContext<AppDependencies | null>(null)
+
+// Provider
+function AppProvider({ deps, children }: { deps: AppDependencies; children: ReactNode }) {
+  return <DepsContext.Provider value={deps}>{children}</DepsContext.Provider>
+}
+
+// Hook to use dependencies
+function useDeps(): AppDependencies {
+  const deps = useContext(DepsContext)
+  if (!deps) throw new Error('Missing AppProvider')
+  return deps
+}
+```
+
+### Use in Components
+
+```typescript
+function UserProfile({ userId }: { userId: string }) {
+  const { api, analytics } = useDeps()
+  const [user, setUser] = useState<RemoteData<Error, User>>(notAsked())
+
+  useEffect(() => {
+    setUser(loading())
+    api.getUser(userId)
+      .then(u => {
+        setUser(success(u))
+        analytics.track('user_viewed', { userId })
+      })
+      .catch(e => setUser(failure(e)))
+  }, [userId, api, analytics])
+
+  // render...
+}
+```
+
+### Testing with Mock Dependencies
+
+```typescript
+const mockDeps: AppDependencies = {
+  api: {
+    getUser: jest.fn().mockResolvedValue({ id: '1', name: 'Test User' }),
+    updateUser: jest.fn().mockResolvedValue({ id: '1', name: 'Updated' }),
+  },
+  analytics: {
+    track: jest.fn(),
+  },
+}
+
+test('loads user on mount', async () => {
+  render(
+    <AppProvider deps={mockDeps}>
+      <UserProfile userId="1" />
+    </AppProvider>
+  )
+
+  await screen.findByText('Test User')
+  expect(mockDeps.api.getUser).toHaveBeenCalledWith('1')
+})
+```
+
+---
+
+## 7. React 19 Patterns
+
+### use() for Promises (React 19+)
+
+```typescript
+import { use, Suspense } from 'react'
+
+// Instead of useEffect + useState for data fetching
+function UserProfile({ userPromise }: { userPromise: Promise<User> }) {
+  const user = use(userPromise)  // Suspends until resolved
+  return <div>{user.name}</div>
+}
+
+// Parent provides the promise
+function App() {
+  const userPromise = fetchUser('1')  // Start fetching immediately
+
+  return (
+    <Suspense fallback={<Spinner />}>
+      <UserProfile userPromise={userPromise} />
+    </Suspense>
+  )
+}
+```
+
+### useActionState for Forms (React 19+)
+
+```typescript
+import { useActionState } from 'react'
+import * as E from 'fp-ts/Either'
+
+interface FormState {
+  errors: string[]
+  success: boolean
+}
+
+async function submitForm(
+  prevState: FormState,
+  formData: FormData
+): Promise<FormState> {
+  const data = {
+    email: formData.get('email') as string,
+    password: formData.get('password') as string,
+  }
+
+  // Use Either for validation
+  const result = pipe(
+    validateForm(data),
+    E.match(
+      (errors) => ({ errors, success: false }),
+      async (valid) => {
+        await saveToServer(valid)
+        return { errors: [], success: true }
+      }
+    )
+  )
+
+  return result
+}
+
+function SignupForm() {
+  const [state, formAction, isPending] = useActionState(submitForm, {
+    errors: [],
+    success: false
+  })
+
+  return (
+    <form action={formAction}>
+      <input name="email" type="email" />
+      <input name="password" type="password" />
+
+      {state.errors.map(e => <p key={e} className="error">{e}</p>)}
+
+      <button disabled={isPending}>
+        {isPending ? 'Submitting...' : 'Sign Up'}
+      </button>
+    </form>
+  )
+}
+```
+
+### useOptimistic for Instant Feedback (React 19+)
+
+```typescript
+import { useOptimistic } from 'react'
+
+function TodoList({ todos }: { todos: Todo[] }) {
+  const [optimisticTodos, addOptimisticTodo] = useOptimistic(
+    todos,
+    (state, newTodo: Todo) => [...state, { ...newTodo, pending: true }]
+  )
+
+  const addTodo = async (text: string) => {
+    const newTodo = { id: crypto.randomUUID(), text, done: false }
+
+    // Immediately show in UI
+    addOptimisticTodo(newTodo)
+
+    // Actually save (will reconcile when done)
+    await saveTodo(newTodo)
+  }
+
+  return (
+    <ul>
+      {optimisticTodos.map(todo => (
+        <li key={todo.id} style={{ opacity: todo.pending ? 0.5 : 1 }}>
+          {todo.text}
+        </li>
+      ))}
+    </ul>
+  )
+}
+```
+
+---
+
+## 8. Common Patterns Cheat Sheet
+
+### Render Based on Option
+
+```typescript
+// Pattern 1: match
+pipe(
+  maybeUser,
+  O.match(
+    () => <LoginButton />,
+    (user) => <UserMenu user={user} />
+  )
+)
+
+// Pattern 2: fold (same as match)
+O.fold(
+  () => <LoginButton />,
+  (user) => <UserMenu user={user} />
+)(maybeUser)
+
+// Pattern 3: getOrElse for simple defaults
+const name = pipe(
+  maybeUser,
+  O.map(u => u.name),
+  O.getOrElse(() => 'Guest')
+)
+```
+
+### Render Based on Either
+
+```typescript
+pipe(
+  validationResult,
+  E.match(
+    (errors) => <ErrorList errors={errors} />,
+    (data) => <SuccessMessage data={data} />
+  )
+)
+```
+
+### Safe Array Rendering
+
+```typescript
+import * as A from 'fp-ts/Array'
+
+// Get first item safely
+const firstUser = pipe(
+  users,
+  A.head,
+  O.map(user => <Featured user={user} />),
+  O.getOrElse(() => <NoFeaturedUser />)
+)
+
+// Find specific item
+const adminUser = pipe(
+  users,
+  A.findFirst(u => u.role === 'admin'),
+  O.map(admin => <AdminBadge user={admin} />),
+  O.toNullable  // or O.getOrElse(() => null)
+)
+```
+
+### Conditional Props
+
+```typescript
+// Add props only if value exists
+const modalProps = {
+  isOpen: true,
+  ...pipe(
+    maybeTitle,
+    O.map(title => ({ title })),
+    O.getOrElse(() => ({}))
+  )
+}
+```
+
+---
+
+## When to Use What
+
+| Situation | Use |
+|-----------|-----|
+| Value might not exist | `Option<T>` |
+| Operation might fail (sync) | `Either<E, A>` |
+| Async operation might fail | `TaskEither<E, A>` |
+| Need loading/error/success UI | `RemoteData<E, A>` |
+| Form with multiple validations | `Either` with validation applicative |
+| Dependency injection | Context + `ReaderTaskEither` |
+| Prevent re-renders with fp-ts | `useMemo` or `fp-ts-react-stable-hooks` |
+
+---
+
+## Libraries
+
+- **[fp-ts](https://github.com/gcanti/fp-ts)** - Core library
+- **[fp-ts-react-stable-hooks](https://github.com/mblink/fp-ts-react-stable-hooks)** - Stable hooks
+- **[@devexperts/remote-data-ts](https://github.com/devexperts/remote-data-ts)** - RemoteData
+- **[io-ts](https://github.com/gcanti/io-ts)** - Runtime type validation
+- **[zod](https://github.com/colinhacks/zod)** - Schema validation (works great with fp-ts)

skills/frontend-slides/SKILL.md

@@ -0,0 +1,770 @@
+---
+name: frontend-slides
+description: Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.
+source: https://github.com/zarazhangrui/frontend-slides
+risk: safe
+---
+
+# Frontend Slides Skill
+
+Create zero-dependency, animation-rich HTML presentations that run entirely in the browser. This skill helps non-designers discover their preferred aesthetic through visual exploration ("show, don't tell"), then generates production-quality slide decks.
+
+## Core Philosophy
+
+1. **Zero Dependencies** — Single HTML files with inline CSS/JS. No npm, no build tools.
+2. **Show, Don't Tell** — People don't know what they want until they see it. Generate visual previews, not abstract choices.
+3. **Distinctive Design** — Avoid generic "AI slop" aesthetics. Every presentation should feel custom-crafted.
+4. **Production Quality** — Code should be well-commented, accessible, and performant.
+
+---
+
+## Phase 0: Detect Mode
+
+First, determine what the user wants:
+
+**Mode A: New Presentation**
+- User wants to create slides from scratch
+- Proceed to Phase 1 (Content Discovery)
+
+**Mode B: PPT Conversion**
+- User has a PowerPoint file (.ppt, .pptx) to convert
+- Proceed to Phase 4 (PPT Extraction)
+
+**Mode C: Existing Presentation Enhancement**
+- User has an HTML presentation and wants to improve it
+- Read the existing file, understand the structure, then enhance
+
+---
+
+## Phase 1: Content Discovery (New Presentations)
+
+Before designing, understand the content. Ask via AskUserQuestion:
+
+### Step 1.1: Presentation Context
+
+**Question 1: Purpose**
+- Header: "Purpose"
+- Question: "What is this presentation for?"
+- Options:
+  - "Pitch deck" — Selling an idea, product, or company to investors/clients
+  - "Teaching/Tutorial" — Explaining concepts, how-to guides, educational content
+  - "Conference talk" — Speaking at an event, tech talk, keynote
+  - "Internal presentation" — Team updates, strategy meetings, company updates
+
+**Question 2: Slide Count**
+- Header: "Length"
+- Question: "Approximately how many slides?"
+- Options:
+  - "Short (5-10)" — Quick pitch, lightning talk
+  - "Medium (10-20)" — Standard presentation
+  - "Long (20+)" — Deep dive, comprehensive talk
+
+**Question 3: Content**
+- Header: "Content"
+- Question: "Do you have the content ready, or do you need help structuring it?"
+- Options:
+  - "I have all content ready" — Just need to design the presentation
+  - "I have rough notes" — Need help organizing into slides
+  - "I have a topic only" — Need help creating the full outline
+
+If user has content, ask them to share it (text, bullet points, images, etc.).
+
+---
+
+## Phase 2: Style Discovery (Visual Exploration)
+
+**CRITICAL: This is the "show, don't tell" phase.**
+
+Most people can't articulate design preferences in words. Instead of asking "do you want minimalist or bold?", we generate mini-previews and let them react.
+
+### Step 2.1: Mood Selection
+
+**Question 1: Feeling**
+- Header: "Vibe"
+- Question: "What feeling should the audience have when viewing your slides?"
+- Options:
+  - "Impressed/Confident" — Professional, trustworthy, this team knows what they're doing
+  - "Excited/Energized" — Innovative, bold, this is the future
+  - "Calm/Focused" — Clear, thoughtful, easy to follow
+  - "Inspired/Moved" — Emotional, storytelling, memorable
+- multiSelect: true (can choose up to 2)
+
+### Step 2.2: Generate Style Previews
+
+Based on their mood selection, generate **3 distinct style previews** as mini HTML files in a temporary directory. Each preview should be a single title slide showing:
+
+- Typography (font choices, heading/body hierarchy)
+- Color palette (background, accent, text colors)
+- Animation style (how elements enter)
+- Overall aesthetic feel
+
+**Preview Styles to Consider (pick 3 based on mood):**
+
+| Mood | Style Options |
+|------|---------------|
+| Impressed/Confident | "Corporate Elegant", "Dark Executive", "Clean Minimal" |
+| Excited/Energized | "Neon Cyber", "Bold Gradients", "Kinetic Motion" |
+| Calm/Focused | "Paper & Ink", "Soft Muted", "Swiss Minimal" |
+| Inspired/Moved | "Cinematic Dark", "Warm Editorial", "Atmospheric" |
+
+**IMPORTANT: Never use these generic patterns:**
+- Purple gradients on white backgrounds
+- Inter, Roboto, or system fonts
+- Standard blue primary colors
+- Predictable hero layouts
+
+**Instead, use distinctive choices:**
+- Unique font pairings (Clash Display, Satoshi, Cormorant Garamond, DM Sans, etc.)
+- Cohesive color themes with personality
+- Atmospheric backgrounds (gradients, subtle patterns, depth)
+- Signature animation moments
+
+### Step 2.3: Present Previews
+
+Create the previews in: `.claude-design/slide-previews/`
+
+```
+.claude-design/slide-previews/
+├── style-a.html   # First style option
+├── style-b.html   # Second style option
+├── style-c.html   # Third style option
+└── assets/        # Any shared assets
+```
+
+Each preview file should be:
+- Self-contained (inline CSS/JS)
+- A single "title slide" showing the aesthetic
+- Animated to demonstrate motion style
+- ~50-100 lines, not a full presentation
+
+Present to user:
+```
+I've created 3 style previews for you to compare:
+
+**Style A: [Name]** — [1 sentence description]
+**Style B: [Name]** — [1 sentence description]
+**Style C: [Name]** — [1 sentence description]
+
+Open each file to see them in action:
+- .claude-design/slide-previews/style-a.html
+- .claude-design/slide-previews/style-b.html
+- .claude-design/slide-previews/style-c.html
+
+Take a look and tell me:
+1. Which style resonates most?
+2. What do you like about it?
+3. Anything you'd change?
+```
+
+Then use AskUserQuestion:
+
+**Question: Pick Your Style**
+- Header: "Style"
+- Question: "Which style preview do you prefer?"
+- Options:
+  - "Style A: [Name]" — [Brief description]
+  - "Style B: [Name]" — [Brief description]
+  - "Style C: [Name]" — [Brief description]
+  - "Mix elements" — Combine aspects from different styles
+
+If "Mix elements", ask for specifics.
+
+---
+
+## Phase 3: Generate Presentation
+
+Now generate the full presentation based on:
+- Content from Phase 1
+- Style from Phase 2
+
+### File Structure
+
+For single presentations:
+```
+presentation.html    # Self-contained presentation
+assets/              # Images, if any
+```
+
+For projects with multiple presentations:
+```
+[presentation-name].html
+[presentation-name]-assets/
+```
+
+### HTML Architecture
+
+Follow this structure for all presentations:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Presentation Title</title>
+
+    <!-- Fonts (use Fontshare or Google Fonts) -->
+    <link rel="stylesheet" href="https://api.fontshare.com/v2/css?f[]=...">
+
+    <style>
+        /* ===========================================
+           CSS CUSTOM PROPERTIES (THEME)
+           Easy to modify: change these to change the whole look
+           =========================================== */
+        :root {
+            /* Colors */
+            --bg-primary: #0a0f1c;
+            --bg-secondary: #111827;
+            --text-primary: #ffffff;
+            --text-secondary: #9ca3af;
+            --accent: #00ffcc;
+            --accent-glow: rgba(0, 255, 204, 0.3);
+
+            /* Typography */
+            --font-display: 'Clash Display', sans-serif;
+            --font-body: 'Satoshi', sans-serif;
+
+            /* Spacing */
+            --slide-padding: clamp(2rem, 5vw, 4rem);
+
+            /* Animation */
+            --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
+            --duration-normal: 0.6s;
+        }
+
+        /* ===========================================
+           BASE STYLES
+           =========================================== */
+        * {
+            margin: 0;
+            padding: 0;
+            box-sizing: border-box;
+        }
+
+        html {
+            scroll-behavior: smooth;
+            scroll-snap-type: y mandatory;
+        }
+
+        body {
+            font-family: var(--font-body);
+            background: var(--bg-primary);
+            color: var(--text-primary);
+            overflow-x: hidden;
+        }
+
+        /* ===========================================
+           SLIDE CONTAINER
+           Each section is one slide
+           =========================================== */
+        .slide {
+            min-height: 100vh;
+            padding: var(--slide-padding);
+            scroll-snap-align: start;
+            display: flex;
+            flex-direction: column;
+            justify-content: center;
+            position: relative;
+            overflow: hidden;
+        }
+
+        /* ===========================================
+           ANIMATIONS
+           Trigger via .visible class (added by JS on scroll)
+           =========================================== */
+        .reveal {
+            opacity: 0;
+            transform: translateY(30px);
+            transition: opacity var(--duration-normal) var(--ease-out-expo),
+                        transform var(--duration-normal) var(--ease-out-expo);
+        }
+
+        .slide.visible .reveal {
+            opacity: 1;
+            transform: translateY(0);
+        }
+
+        /* Stagger children */
+        .reveal:nth-child(1) { transition-delay: 0.1s; }
+        .reveal:nth-child(2) { transition-delay: 0.2s; }
+        .reveal:nth-child(3) { transition-delay: 0.3s; }
+        .reveal:nth-child(4) { transition-delay: 0.4s; }
+
+        /* ... more styles ... */
+    </style>
+</head>
+<body>
+    <!-- Progress bar (optional) -->
+    <div class="progress-bar"></div>
+
+    <!-- Navigation dots (optional) -->
+    <nav class="nav-dots">
+        <!-- Generated by JS -->
+    </nav>
+
+    <!-- Slides -->
+    <section class="slide title-slide">
+        <h1 class="reveal">Presentation Title</h1>
+        <p class="reveal">Subtitle or author</p>
+    </section>
+
+    <section class="slide">
+        <h2 class="reveal">Slide Title</h2>
+        <p class="reveal">Content...</p>
+    </section>
+
+    <!-- More slides... -->
+
+    <script>
+        /* ===========================================
+           SLIDE PRESENTATION CONTROLLER
+           Handles navigation, animations, and interactions
+           =========================================== */
+
+        class SlidePresentation {
+            constructor() {
+                // ... initialization
+            }
+
+            // ... methods
+        }
+
+        // Initialize
+        new SlidePresentation();
+    </script>
+</body>
+</html>
+```
+
+### Required JavaScript Features
+
+Every presentation should include:
+
+1. **SlidePresentation Class** — Main controller
+   - Keyboard navigation (arrows, space)
+   - Touch/swipe support
+   - Mouse wheel navigation
+   - Progress bar updates
+   - Navigation dots
+
+2. **Intersection Observer** — For scroll-triggered animations
+   - Add `.visible` class when slides enter viewport
+   - Trigger CSS animations efficiently
+
+3. **Optional Enhancements** (based on style):
+   - Custom cursor with trail
+   - Particle system background (canvas)
+   - Parallax effects
+   - 3D tilt on hover
+   - Magnetic buttons
+   - Counter animations
+
+### Code Quality Requirements
+
+**Comments:**
+Every section should have clear comments explaining:
+- What it does
+- Why it exists
+- How to modify it
+
+```javascript
+/* ===========================================
+   CUSTOM CURSOR
+   Creates a stylized cursor that follows mouse with a trail effect.
+   - Uses lerp (linear interpolation) for smooth movement
+   - Grows larger when hovering over interactive elements
+   =========================================== */
+class CustomCursor {
+    constructor() {
+        // ...
+    }
+}
+```
+
+**Accessibility:**
+- Semantic HTML (`<section>`, `<nav>`, `<main>`)
+- Keyboard navigation works
+- ARIA labels where needed
+- Reduced motion support
+
+```css
+@media (prefers-reduced-motion: reduce) {
+    .reveal {
+        transition: opacity 0.3s ease;
+        transform: none;
+    }
+}
+```
+
+**Responsive:**
+- Mobile-friendly (single column, adjusted spacing)
+- Disable heavy effects on mobile
+- Touch-friendly interactions
+
+```css
+@media (max-width: 768px) {
+    .nav-dots,
+    .keyboard-hint {
+        display: none;
+    }
+}
+```
+
+---
+
+## Phase 4: PPT Conversion
+
+When converting PowerPoint files:
+
+### Step 4.1: Extract Content
+
+Use Python with `python-pptx` to extract:
+
+```python
+from pptx import Presentation
+from pptx.util import Inches, Pt
+import json
+import os
+import base64
+
+def extract_pptx(file_path, output_dir):
+    """
+    Extract all content from a PowerPoint file.
+    Returns a JSON structure with slides, text, and images.
+    """
+    prs = Presentation(file_path)
+    slides_data = []
+
+    # Create assets directory
+    assets_dir = os.path.join(output_dir, 'assets')
+    os.makedirs(assets_dir, exist_ok=True)
+
+    for slide_num, slide in enumerate(prs.slides):
+        slide_data = {
+            'number': slide_num + 1,
+            'title': '',
+            'content': [],
+            'images': [],
+            'notes': ''
+        }
+
+        for shape in slide.shapes:
+            # Extract title
+            if shape.has_text_frame:
+                if shape == slide.shapes.title:
+                    slide_data['title'] = shape.text
+                else:
+                    slide_data['content'].append({
+                        'type': 'text',
+                        'content': shape.text
+                    })
+
+            # Extract images
+            if shape.shape_type == 13:  # Picture
+                image = shape.image
+                image_bytes = image.blob
+                image_ext = image.ext
+                image_name = f"slide{slide_num + 1}_img{len(slide_data['images']) + 1}.{image_ext}"
+                image_path = os.path.join(assets_dir, image_name)
+
+                with open(image_path, 'wb') as f:
+                    f.write(image_bytes)
+
+                slide_data['images'].append({
+                    'path': f"assets/{image_name}",
+                    'width': shape.width,
+                    'height': shape.height
+                })
+
+        # Extract notes
+        if slide.has_notes_slide:
+            notes_frame = slide.notes_slide.notes_text_frame
+            slide_data['notes'] = notes_frame.text
+
+        slides_data.append(slide_data)
+
+    return slides_data
+```
+
+### Step 4.2: Confirm Content Structure
+
+Present the extracted content to the user:
+
+```
+I've extracted the following from your PowerPoint:
+
+**Slide 1: [Title]**
+- [Content summary]
+- Images: [count]
+
+**Slide 2: [Title]**
+- [Content summary]
+- Images: [count]
+
+...
+
+All images have been saved to the assets folder.
+
+Does this look correct? Should I proceed with style selection?
+```
+
+### Step 4.3: Style Selection
+
+Proceed to Phase 2 (Style Discovery) with the extracted content in mind.
+
+### Step 4.4: Generate HTML
+
+Convert the extracted content into the chosen style, preserving:
+- All text content
+- All images (referenced from assets folder)
+- Slide order
+- Any speaker notes (as HTML comments or separate file)
+
+---
+
+## Phase 5: Delivery
+
+### Final Output
+
+When the presentation is complete:
+
+1. **Clean up temporary files**
+   - Delete `.claude-design/slide-previews/` if it exists
+
+2. **Open the presentation**
+   - Use `open [filename].html` to launch in browser
+
+3. **Provide summary**
+```
+Your presentation is ready!
+
+📁 File: [filename].html
+🎨 Style: [Style Name]
+📊 Slides: [count]
+
+**Navigation:**
+- Arrow keys (← →) or Space to navigate
+- Scroll/swipe also works
+- Click the dots on the right to jump to a slide
+
+**To customize:**
+- Colors: Look for `:root` CSS variables at the top
+- Fonts: Change the Fontshare/Google Fonts link
+- Animations: Modify `.reveal` class timings
+
+Would you like me to make any adjustments?
+```
+
+---
+
+## Style Reference: Effect → Feeling Mapping
+
+Use this guide to match animations to intended feelings:
+
+### Dramatic / Cinematic
+- Slow fade-ins (1-1.5s)
+- Large scale transitions (0.9 → 1)
+- Dark backgrounds with spotlight effects
+- Parallax scrolling
+- Full-bleed images
+
+### Techy / Futuristic
+- Neon glow effects (box-shadow with accent color)
+- Particle systems (canvas background)
+- Grid patterns
+- Monospace fonts for accents
+- Glitch or scramble text effects
+- Cyan, magenta, electric blue palette
+
+### Playful / Friendly
+- Bouncy easing (spring physics)
+- Rounded corners (large radius)
+- Pastel or bright colors
+- Floating/bobbing animations
+- Hand-drawn or illustrated elements
+
+### Professional / Corporate
+- Subtle, fast animations (200-300ms)
+- Clean sans-serif fonts
+- Navy, slate, or charcoal backgrounds
+- Precise spacing and alignment
+- Minimal decorative elements
+- Data visualization focus
+
+### Calm / Minimal
+- Very slow, subtle motion
+- High whitespace
+- Muted color palette
+- Serif typography
+- Generous padding
+- Content-focused, no distractions
+
+### Editorial / Magazine
+- Strong typography hierarchy
+- Pull quotes and callouts
+- Image-text interplay
+- Grid-breaking layouts
+- Serif headlines, sans-serif body
+- Black and white with one accent
+
+---
+
+## Animation Patterns Reference
+
+### Entrance Animations
+
+```css
+/* Fade + Slide Up (most common) */
+.reveal {
+    opacity: 0;
+    transform: translateY(30px);
+    transition: opacity 0.6s var(--ease-out-expo),
+                transform 0.6s var(--ease-out-expo);
+}
+
+.visible .reveal {
+    opacity: 1;
+    transform: translateY(0);
+}
+
+/* Scale In */
+.reveal-scale {
+    opacity: 0;
+    transform: scale(0.9);
+    transition: opacity 0.6s, transform 0.6s var(--ease-out-expo);
+}
+
+/* Slide from Left */
+.reveal-left {
+    opacity: 0;
+    transform: translateX(-50px);
+    transition: opacity 0.6s, transform 0.6s var(--ease-out-expo);
+}
+
+/* Blur In */
+.reveal-blur {
+    opacity: 0;
+    filter: blur(10px);
+    transition: opacity 0.8s, filter 0.8s var(--ease-out-expo);
+}
+```
+
+### Background Effects
+
+```css
+/* Gradient Mesh */
+.gradient-bg {
+    background:
+        radial-gradient(ellipse at 20% 80%, rgba(120, 0, 255, 0.3) 0%, transparent 50%),
+        radial-gradient(ellipse at 80% 20%, rgba(0, 255, 200, 0.2) 0%, transparent 50%),
+        var(--bg-primary);
+}
+
+/* Noise Texture */
+.noise-bg {
+    background-image: url("data:image/svg+xml,..."); /* Inline SVG noise */
+}
+
+/* Grid Pattern */
+.grid-bg {
+    background-image:
+        linear-gradient(rgba(255,255,255,0.03) 1px, transparent 1px),
+        linear-gradient(90deg, rgba(255,255,255,0.03) 1px, transparent 1px);
+    background-size: 50px 50px;
+}
+```
+
+### Interactive Effects
+
+```javascript
+/* 3D Tilt on Hover */
+class TiltEffect {
+    constructor(element) {
+        this.element = element;
+        this.element.style.transformStyle = 'preserve-3d';
+        this.element.style.perspective = '1000px';
+        this.bindEvents();
+    }
+
+    bindEvents() {
+        this.element.addEventListener('mousemove', (e) => {
+            const rect = this.element.getBoundingClientRect();
+            const x = (e.clientX - rect.left) / rect.width - 0.5;
+            const y = (e.clientY - rect.top) / rect.height - 0.5;
+
+            this.element.style.transform = `
+                rotateY(${x * 10}deg)
+                rotateX(${-y * 10}deg)
+            `;
+        });
+
+        this.element.addEventListener('mouseleave', () => {
+            this.element.style.transform = 'rotateY(0) rotateX(0)';
+        });
+    }
+}
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**Fonts not loading:**
+- Check Fontshare/Google Fonts URL
+- Ensure font names match in CSS
+
+**Animations not triggering:**
+- Verify Intersection Observer is running
+- Check that `.visible` class is being added
+
+**Scroll snap not working:**
+- Ensure `scroll-snap-type` on html/body
+- Each slide needs `scroll-snap-align: start`
+
+**Mobile issues:**
+- Disable heavy effects at 768px breakpoint
+- Test touch events
+- Reduce particle count or disable canvas
+
+**Performance issues:**
+- Use `will-change` sparingly
+- Prefer `transform` and `opacity` animations
+- Throttle scroll/mousemove handlers
+
+---
+
+## Related Skills
+
+- **learn** — Generate FORZARA.md documentation for the presentation
+- **frontend-design** — For more complex interactive pages beyond slides
+- **design-and-refine:design-lab** — For iterating on component designs
+
+---
+
+## Example Session Flow
+
+1. User: "I want to create a pitch deck for my AI startup"
+2. Skill asks about purpose, length, content
+3. User shares their bullet points and key messages
+4. Skill asks about desired feeling (Impressed + Excited)
+5. Skill generates 3 style previews
+6. User picks Style B (Neon Cyber), asks for darker background
+7. Skill generates full presentation with all slides
+8. Skill opens the presentation in browser
+9. User requests tweaks to specific slides
+10. Final presentation delivered
+
+---
+
+## Conversion Session Flow
+
+1. User: "Convert my slides.pptx to a web presentation"
+2. Skill extracts content and images from PPT
+3. Skill confirms extracted content with user
+4. Skill asks about desired feeling/style
+5. Skill generates style previews
+6. User picks a style
+7. Skill generates HTML presentation with preserved assets
+8. Final presentation delivered

skills/hugging-face-cli/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: hugging-face-cli
+description: "Execute Hugging Face Hub operations using the `hf` CLI. Use when the user needs to download models/datasets/spaces, upload files to Hub repositories, create repos, manage local cache, or run compute jobs on HF infrastructure. Covers authentication, file transfers, repository creation, cache operations, and cloud compute."
+source: "https://github.com/huggingface/skills/tree/main/skills/hugging-face-cli"
+risk: safe
+---
+
+# Hugging Face CLI
+
+The `hf` CLI provides direct terminal access to the Hugging Face Hub for downloading, uploading, and managing repositories, cache, and compute resources.
+
+## When to Use This Skill
+
+Use this skill when:
+- User needs to download models, datasets, or spaces
+- Uploading files to Hub repositories
+- Creating Hugging Face repositories
+- Managing local cache
+- Running compute jobs on HF infrastructure
+- Working with Hugging Face Hub authentication
+
+## Quick Command Reference
+
+| Task | Command |
+|------|---------|
+| Login | `hf auth login` |
+| Download model | `hf download <repo_id>` |
+| Download to folder | `hf download <repo_id> --local-dir ./path` |
+| Upload folder | `hf upload <repo_id> . .` |
+| Create repo | `hf repo create <name>` |
+| Create tag | `hf repo tag create <repo_id> <tag>` |
+| Delete files | `hf repo-files delete <repo_id> <files>` |
+| List cache | `hf cache ls` |
+| Remove from cache | `hf cache rm <repo_or_revision>` |
+| List models | `hf models ls` |
+| Get model info | `hf models info <model_id>` |
+| List datasets | `hf datasets ls` |
+| Get dataset info | `hf datasets info <dataset_id>` |
+| List spaces | `hf spaces ls` |
+| Get space info | `hf spaces info <space_id>` |
+| List endpoints | `hf endpoints ls` |
+| Run GPU job | `hf jobs run --flavor a10g-small <image> <cmd>` |
+| Environment info | `hf env` |
+
+## Core Commands
+
+### Authentication
+```bash
+hf auth login                    # Interactive login
+hf auth login --token $HF_TOKEN  # Non-interactive
+hf auth whoami                   # Check current user
+hf auth list                     # List stored tokens
+hf auth switch                   # Switch between tokens
+hf auth logout                   # Log out
+```
+
+### Download
+```bash
+hf download <repo_id>                              # Full repo to cache
+hf download <repo_id> file.safetensors             # Specific file
+hf download <repo_id> --local-dir ./models         # To local directory
+hf download <repo_id> --include "*.safetensors"    # Filter by pattern
+hf download <repo_id> --repo-type dataset          # Dataset
+hf download <repo_id> --revision v1.0              # Specific version
+```
+
+### Upload
+```bash
+hf upload <repo_id> . .                            # Current dir to root
+hf upload <repo_id> ./models /weights              # Folder to path
+hf upload <repo_id> model.safetensors              # Single file
+hf upload <repo_id> . . --repo-type dataset        # Dataset
+hf upload <repo_id> . . --create-pr                # Create PR
+hf upload <repo_id> . . --commit-message="msg"     # Custom message
+```
+
+### Repository Management
+```bash
+hf repo create <name>                              # Create model repo
+hf repo create <name> --repo-type dataset          # Create dataset
+hf repo create <name> --private                    # Private repo
+hf repo create <name> --repo-type space --space_sdk gradio  # Gradio space
+hf repo delete <repo_id>                           # Delete repo
+hf repo move <from_id> <to_id>                     # Move repo to new namespace
+hf repo settings <repo_id> --private true          # Update repo settings
+hf repo list --repo-type model                     # List repos
+hf repo branch create <repo_id> release-v1         # Create branch
+hf repo branch delete <repo_id> release-v1         # Delete branch
+hf repo tag create <repo_id> v1.0                  # Create tag
+hf repo tag list <repo_id>                         # List tags
+hf repo tag delete <repo_id> v1.0                  # Delete tag
+```
+
+### Delete Files from Repo
+```bash
+hf repo-files delete <repo_id> folder/             # Delete folder
+hf repo-files delete <repo_id> "*.txt"             # Delete with pattern
+```
+
+### Cache Management
+```bash
+hf cache ls                      # List cached repos
+hf cache ls --revisions          # Include individual revisions
+hf cache rm model/gpt2           # Remove cached repo
+hf cache rm <revision_hash>      # Remove cached revision
+hf cache prune                   # Remove detached revisions
+hf cache verify gpt2             # Verify checksums from cache
+```
+
+### Browse Hub
+```bash
+# Models
+hf models ls                                        # List top trending models
+hf models ls --search "MiniMax" --author MiniMaxAI  # Search models
+hf models ls --filter "text-generation" --limit 20  # Filter by task
+hf models info MiniMaxAI/MiniMax-M2.1               # Get model info
+
+# Datasets
+hf datasets ls                                      # List top trending datasets
+hf datasets ls --search "finepdfs" --sort downloads # Search datasets
+hf datasets info HuggingFaceFW/finepdfs             # Get dataset info
+
+# Spaces
+hf spaces ls                                        # List top trending spaces
+hf spaces ls --filter "3d" --limit 10               # Filter by 3D modeling spaces
+hf spaces info enzostvs/deepsite                    # Get space info
+```
+
+### Jobs (Cloud Compute)
+```bash
+hf jobs run python:3.12 python script.py           # Run on CPU
+hf jobs run --flavor a10g-small <image> <cmd>      # Run on GPU
+hf jobs run --secrets HF_TOKEN <image> <cmd>       # With HF token
+hf jobs ps                                         # List jobs
+hf jobs logs <job_id>                              # View logs
+hf jobs cancel <job_id>                            # Cancel job
+```
+
+### Inference Endpoints
+```bash
+hf endpoints ls                                     # List endpoints
+hf endpoints deploy my-endpoint \
+  --repo openai/gpt-oss-120b \
+  --framework vllm \
+  --accelerator gpu \
+  --instance-size x4 \
+  --instance-type nvidia-a10g \
+  --region us-east-1 \
+  --vendor aws
+hf endpoints describe my-endpoint                   # Show endpoint details
+hf endpoints pause my-endpoint                      # Pause endpoint
+hf endpoints resume my-endpoint                     # Resume endpoint
+hf endpoints scale-to-zero my-endpoint              # Scale to zero
+hf endpoints delete my-endpoint --yes               # Delete endpoint
+```
+**GPU Flavors:** `cpu-basic`, `cpu-upgrade`, `cpu-xl`, `t4-small`, `t4-medium`, `l4x1`, `l4x4`, `l40sx1`, `l40sx4`, `l40sx8`, `a10g-small`, `a10g-large`, `a10g-largex2`, `a10g-largex4`, `a100-large`, `h100`, `h100x8`
+
+## Common Patterns
+
+### Download and Use Model Locally
+```bash
+# Download to local directory for deployment
+hf download meta-llama/Llama-3.2-1B-Instruct --local-dir ./model
+
+# Or use cache and get path
+MODEL_PATH=$(hf download meta-llama/Llama-3.2-1B-Instruct --quiet)
+```
+
+### Publish Model/Dataset
+```bash
+hf repo create my-username/my-model --private
+hf upload my-username/my-model ./output . --commit-message="Initial release"
+hf repo tag create my-username/my-model v1.0
+```
+
+### Sync Space with Local
+```bash
+hf upload my-username/my-space . . --repo-type space \
+  --exclude="logs/*" --delete="*" --commit-message="Sync"
+```
+
+### Check Cache Usage
+```bash
+hf cache ls                      # See all cached repos and sizes
+hf cache rm model/gpt2           # Remove a repo from cache
+```
+
+## Key Options
+
+- `--repo-type`: `model` (default), `dataset`, `space`
+- `--revision`: Branch, tag, or commit hash
+- `--token`: Override authentication
+- `--quiet`: Output only essential info (paths/URLs)
+
+## References
+
+- **Complete command reference**: See [references/commands.md](references/commands.md)
+- **Workflow examples**: See [references/examples.md](references/examples.md)

skills/imagen/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: imagen
+description: |
+source: "https://github.com/sanjay3290/ai-skills/tree/main/skills/imagen"
+risk: safe
+---
+
+# Imagen - AI Image Generation Skill
+
+## Overview
+
+This skill generates images using Google Gemini's image generation model (`gemini-3-pro-image-preview`). It enables seamless image creation during any Claude Code session - whether you're building frontend UIs, creating documentation, or need visual representations of concepts.
+
+**Cross-Platform**: Works on Windows, macOS, and Linux.
+
+## When to Use This Skill
+
+Automatically activate this skill when:
+- User requests image generation (e.g., "generate an image of...", "create a picture...")
+- Frontend development requires placeholder or actual images
+- Documentation needs illustrations or diagrams
+- Visualizing concepts, architectures, or ideas
+- Creating icons, logos, or UI assets
+- Any task where an AI-generated image would be helpful
+
+## How It Works
+
+1. Takes a text prompt describing the desired image
+2. Calls Google Gemini API with image generation configuration
+3. Saves the generated image to a specified location (defaults to current directory)
+4. Returns the file path for use in your project
+
+## Usage
+
+### Python (Cross-Platform - Recommended)
+
+```bash
+# Basic usage
+python scripts/generate_image.py "A futuristic city skyline at sunset"
+
+# With custom output path
+python scripts/generate_image.py "A minimalist app icon for a music player" "./assets/icons/music-icon.png"
+
+# With custom size
+python scripts/generate_image.py --size 2K "High resolution landscape" "./wallpaper.png"
+```
+
+## Requirements
+
+- `GEMINI_API_KEY` environment variable must be set
+- Python 3.6+ (uses standard library only, no pip install needed)
+
+## Output
+
+Generated images are saved as PNG files. The script returns:
+- Success: Path to the generated image
+- Failure: Error message with details
+
+## Examples
+
+### Frontend Development
+```
+User: "I need a hero image for my landing page - something abstract and tech-focused"
+-> Generates and saves image, provides path for use in HTML/CSS
+```
+
+### Documentation
+```
+User: "Create a diagram showing microservices architecture"
+-> Generates visual representation, ready for README or docs
+```
+
+### UI Assets
+```
+User: "Generate a placeholder avatar image for the user profile component"
+-> Creates image in appropriate size for component use
+```

skills/iterate-pr/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: iterate-pr
+description: "Iterate on a PR until CI passes. Use when you need to fix CI failures, address review feedback, or continuously push fixes until all checks are green. Automates the feedback-fix-push-wait cycle."
+source: "https://github.com/getsentry/skills/tree/main/plugins/sentry-skills/skills/iterate-pr"
+risk: safe
+---
+
+# Iterate on PR Until CI Passes
+
+Continuously iterate on the current branch until all CI checks pass and review feedback is addressed.
+
+## When to Use This Skill
+
+Use this skill when:
+- Fixing CI failures
+- Addressing review feedback
+- Continuously pushing fixes until all checks are green
+- Automating the feedback-fix-push-wait cycle
+- Ensuring PR meets all quality gates
+
+**Requires**: GitHub CLI (`gh`) authenticated and available.
+
+## Process
+
+### Step 1: Identify the PR
+
+```bash
+gh pr view --json number,url,headRefName,baseRefName
+```
+
+If no PR exists for the current branch, stop and inform the user.
+
+### Step 2: Check CI Status First
+
+Always check CI/GitHub Actions status before looking at review feedback:
+
+```bash
+gh pr checks --json name,state,bucket,link,workflow
+```
+
+The `bucket` field categorizes state into: `pass`, `fail`, `pending`, `skipping`, or `cancel`.
+
+**Important:** If any of these checks are still `pending`, wait before proceeding:
+- `sentry` / `sentry-io`
+- `codecov`
+- `cursor` / `bugbot` / `seer`
+- Any linter or code analysis checks
+
+These bots may post additional feedback comments once their checks complete. Waiting avoids duplicate work.
+
+### Step 3: Gather Review Feedback
+
+Once CI checks have completed (or at least the bot-related checks), gather human and bot feedback:
+
+**Review Comments and Status:**
+```bash
+gh pr view --json reviews,comments,reviewDecision
+```
+
+**Inline Code Review Comments:**
+```bash
+gh api repos/{owner}/{repo}/pulls/{pr_number}/comments
+```
+
+**PR Conversation Comments (includes bot comments):**
+```bash
+gh api repos/{owner}/{repo}/issues/{pr_number}/comments
+```
+
+Look for bot comments from: Sentry, Codecov, Cursor, Bugbot, Seer, and other automated tools.
+
+### Step 4: Investigate Failures
+
+For each CI failure, get the actual logs:
+
+```bash
+# List recent runs for this branch
+gh run list --branch $(git branch --show-current) --limit 5 --json databaseId,name,status,conclusion
+
+# View failed logs for a specific run
+gh run view <run-id> --log-failed
+```
+
+Do NOT assume what failed based on the check name alone. Always read the actual logs.
+
+### Step 5: Validate Feedback
+
+For each piece of feedback (CI failure or review comment):
+
+1. **Read the relevant code** - Understand the context before making changes
+2. **Verify the issue is real** - Not all feedback is correct; reviewers and bots can be wrong
+3. **Check if already addressed** - The issue may have been fixed in a subsequent commit
+4. **Skip invalid feedback** - If the concern is not legitimate, move on
+
+### Step 6: Address Valid Issues
+
+Make minimal, targeted code changes. Only fix what is actually broken.
+
+### Step 7: Commit and Push
+
+```bash
+git add -A
+git commit -m "fix: <descriptive message of what was fixed>"
+git push origin $(git branch --show-current)
+```
+
+### Step 8: Wait for CI
+
+Use the built-in watch functionality:
+
+```bash
+gh pr checks --watch --interval 30
+```
+
+This waits until all checks complete. Exit code 0 means all passed, exit code 1 means failures.
+
+Alternatively, poll manually if you need more control:
+
+```bash
+gh pr checks --json name,state,bucket | jq '.[] | select(.bucket != "pass")'
+```
+
+### Step 9: Repeat
+
+Return to Step 2 if:
+- Any CI checks failed
+- New review feedback appeared
+
+Continue until all checks pass and no unaddressed feedback remains.
+
+## Exit Conditions
+
+**Success:**
+- All CI checks are green (`bucket: pass`)
+- No unaddressed human review feedback
+
+**Ask for Help:**
+- Same failure persists after 3 attempts (likely a flaky test or deeper issue)
+- Review feedback requires clarification or decision from the user
+- CI failure is unrelated to branch changes (infrastructure issue)
+
+**Stop Immediately:**
+- No PR exists for the current branch
+- Branch is out of sync and needs rebase (inform user)
+
+## Tips
+
+- Use `gh pr checks --required` to focus only on required checks
+- Use `gh run view <run-id> --verbose` to see all job steps, not just failures
+- If a check is from an external service, the `link` field in checks JSON provides the URL to investigate

skills/linear-claude-skill/SKILL.md

@@ -0,0 +1,543 @@
+---
+name: linear-claude-skill
+description: "Manage Linear issues, projects, and teams"
+allowed-tools: 
+- WebFetch(domain: linear.app)
+source: "https://github.com/wrsmith108/linear-claude-skill"
+risk: safe
+---
+
+## When to Use This Skill
+
+Manage Linear issues, projects, and teams
+
+Use this skill when working with manage linear issues, projects, and teams.
+# Linear
+
+Tools and workflows for managing issues, projects, and teams in Linear.
+
+---
+
+## ⚠️ Tool Availability (READ FIRST)
+
+**This skill supports multiple tool backends. Use whichever is available:**
+
+1. **MCP Tools (mcp__linear)** - Use if available in your tool set
+2. **Linear CLI (`linear` command)** - Always available via Bash
+3. **Helper Scripts** - For complex operations
+
+**If MCP tools are NOT available**, use the Linear CLI via Bash:
+
+```bash
+# View an issue
+linear issues view ENG-123
+
+# Create an issue
+linear issues create --title "Issue title" --description "Description"
+
+# Update issue status (get state IDs first)
+linear issues update ENG-123 -s "STATE_ID"
+
+# Add a comment
+linear issues comment add ENG-123 -m "Comment text"
+
+# List issues
+linear issues list
+```
+
+**Do NOT report "MCP tools not available" as a blocker** - use CLI instead.
+
+---
+
+
+## When to Use This Skill
+
+Manage Linear issues, projects, and teams
+
+Use this skill when working with manage linear issues, projects, and teams.
+## 🔐 Security: Varlock Integration
+
+**CRITICAL**: Never expose API keys in terminal output or Claude's context.
+
+### Safe Commands (Always Use)
+
+```bash
+# Validate LINEAR_API_KEY is set (masked output)
+varlock load 2>&1 | grep LINEAR
+
+# Run commands with secrets injected
+varlock run -- npx tsx scripts/query.ts "query { viewer { name } }"
+
+# Check schema (safe - no values)
+cat .env.schema | grep LINEAR
+```
+
+### Unsafe Commands (NEVER Use)
+
+```bash
+# ❌ NEVER - exposes key to Claude's context
+linear config show
+echo $LINEAR_API_KEY
+printenv | grep LINEAR
+cat .env
+```
+
+### Setup for New Projects
+
+1. Create `.env.schema` with `@sensitive` annotation:
+   ```bash
+   # @type=string(startsWith=lin_api_) @required @sensitive
+   LINEAR_API_KEY=
+   ```
+
+2. Add `LINEAR_API_KEY` to `.env` (never commit this file)
+
+3. Configure MCP to use environment variable:
+   ```json
+   {
+     "mcpServers": {
+       "linear": {
+         "env": { "LINEAR_API_KEY": "${LINEAR_API_KEY}" }
+       }
+     }
+   }
+   ```
+
+4. Use `varlock load` to validate before operations
+
+---
+
+## Quick Start (First-Time Users)
+
+### 1. Check Your Setup
+
+Run the setup check to verify your configuration:
+
+```bash
+npx tsx ~/.claude/skills/linear/scripts/setup.ts
+```
+
+This will check:
+- LINEAR_API_KEY is set and valid
+- @linear/sdk is installed
+- Linear CLI availability (optional)
+- MCP configuration (optional)
+
+### 2. Get API Key (If Needed)
+
+If setup reports a missing API key:
+
+1. Open [Linear](https://linear.app) in your browser
+2. Go to **Settings** (gear icon) -> **Security & access** -> **Personal API keys**
+3. Click **Create key** and copy the key (starts with `lin_api_`)
+4. Add to your environment:
+
+```bash
+# Option A: Add to shell profile (~/.zshrc or ~/.bashrc)
+export LINEAR_API_KEY="lin_api_your_key_here"
+
+# Option B: Add to Claude Code environment
+echo 'LINEAR_API_KEY=lin_api_your_key_here' >> ~/.claude/.env
+
+# Then reload your shell or restart Claude Code
+```
+
+### 3. Test Connection
+
+Verify everything works:
+
+```bash
+npx tsx ~/.claude/skills/linear/scripts/query.ts "query { viewer { name } }"
+```
+
+You should see your name from Linear.
+
+### 4. Common Operations
+
+```bash
+# Create issue in a project
+npx tsx scripts/linear-ops.ts create-issue "Project" "Title" "Description"
+
+# Update issue status
+npx tsx scripts/linear-ops.ts status Done ENG-123 ENG-124
+
+# Create sub-issue
+npx tsx scripts/linear-ops.ts create-sub-issue ENG-100 "Sub-task" "Details"
+
+# Update project status
+npx tsx scripts/linear-ops.ts project-status "Phase 1" completed
+
+# Show all commands
+npx tsx scripts/linear-ops.ts help
+```
+
+See [Project Management Commands](#project-management-commands) for full reference.
+
+---
+
+
+## When to Use This Skill
+
+Manage Linear issues, projects, and teams
+
+Use this skill when working with manage linear issues, projects, and teams.
+## Project Planning Workflow
+
+### Create Issues in the Correct Project from the Start
+
+**Best Practice**: When planning a new phase or initiative, create the project and its issues together in a single planning session. Avoid creating issues in a catch-all project and moving them later.
+
+#### Recommended Workflow
+
+1. **Create the project first**:
+   ```bash
+   npx tsx scripts/linear-ops.ts create-project "Phase X: Feature Name" "My Initiative"
+   ```
+
+2. **Set project state to Planned**:
+   ```bash
+   npx tsx scripts/linear-ops.ts project-status "Phase X: Feature Name" planned
+   ```
+
+3. **Create issues directly in the project**:
+   ```bash
+   npx tsx scripts/linear-ops.ts create-issue "Phase X: Feature Name" "Parent task" "Description"
+   npx tsx scripts/linear-ops.ts create-sub-issue ENG-XXX "Sub-task 1" "Description"
+   npx tsx scripts/linear-ops.ts create-sub-issue ENG-XXX "Sub-task 2" "Description"
+   ```
+
+4. **Update project state when work begins**:
+   ```bash
+   npx tsx scripts/linear-ops.ts project-status "Phase X: Feature Name" in-progress
+   ```
+
+#### Why This Matters
+
+- **Traceability**: Issues are linked to their project from creation
+- **Metrics**: Project progress tracking is accurate from day one
+- **Workflow**: No time wasted moving issues between projects
+- **Organization**: Linear views and filters work correctly
+
+#### Anti-Pattern to Avoid
+
+❌ Creating issues in a "holding" project and moving them later:
+```bash
+# Don't do this
+create-issue "Phase 6A" "New feature"  # Wrong project
+# Later: manually move to Phase X      # Extra work
+```
+
+---
+
+## Project Management Commands
+
+### project-status
+
+Update a project's state in Linear. Accepts user-friendly terminology that maps to Linear's API.
+
+```bash
+npx tsx scripts/linear-ops.ts project-status <project-name> <state>
+```
+
+**Valid States:**
+| Input | Description | API Value |
+|-------|-------------|-----------|
+| `backlog` | Not yet started | backlog |
+| `planned` | Scheduled for future | planned |
+| `in-progress` | Currently active | started |
+| `paused` | Temporarily on hold | paused |
+| `completed` | Successfully finished | completed |
+| `canceled` | Will not be done | canceled |
+
+**Examples:**
+```bash
+# Start working on a project
+npx tsx scripts/linear-ops.ts project-status "Phase 8: MCP Decision Engine" in-progress
+
+# Mark project complete
+npx tsx scripts/linear-ops.ts project-status "Phase 8" completed
+
+# Partial name matching works
+npx tsx scripts/linear-ops.ts project-status "Phase 8" paused
+```
+
+### link-initiative
+
+Link an existing project to an initiative.
+
+```bash
+npx tsx scripts/linear-ops.ts link-initiative <project-name> <initiative-name>
+```
+
+**Examples:**
+```bash
+# Link a project to an initiative
+npx tsx scripts/linear-ops.ts link-initiative "Phase 8: MCP Decision Engine" "Q1 Goals"
+
+# Partial matching works
+npx tsx scripts/linear-ops.ts link-initiative "Phase 8" "Q1 Goals"
+```
+
+### unlink-initiative
+
+Remove a project from an initiative.
+
+```bash
+npx tsx scripts/linear-ops.ts unlink-initiative <project-name> <initiative-name>
+```
+
+**Examples:**
+```bash
+# Remove incorrect link
+npx tsx scripts/linear-ops.ts unlink-initiative "Phase 8" "Linear Skill"
+
+# Clean up test links
+npx tsx scripts/linear-ops.ts unlink-initiative "Test Project" "Q1 Goals"
+```
+
+**Error Handling:**
+- Returns error if project is not linked to the specified initiative
+- Returns error if project or initiative not found
+
+### Complete Project Lifecycle Example
+
+```bash
+# 1. Create project linked to initiative
+npx tsx scripts/linear-ops.ts create-project "Phase 11: New Feature" "Q1 Goals"
+
+# 2. Set state to planned
+npx tsx scripts/linear-ops.ts project-status "Phase 11" planned
+
+# 3. Create issues in the project
+npx tsx scripts/linear-ops.ts create-issue "Phase 11" "Parent task" "Description"
+npx tsx scripts/linear-ops.ts create-sub-issue ENG-XXX "Sub-task 1" "Details"
+
+# 4. Start work - update to in-progress
+npx tsx scripts/linear-ops.ts project-status "Phase 11" in-progress
+
+# 5. Mark issues done
+npx tsx scripts/linear-ops.ts status Done ENG-XXX ENG-YYY
+
+# 6. Complete project
+npx tsx scripts/linear-ops.ts project-status "Phase 11" completed
+
+# 7. (Optional) Link to additional initiative
+npx tsx scripts/linear-ops.ts link-initiative "Phase 11" "Q2 Goals"
+```
+
+---
+
+
+## When to Use This Skill
+
+Manage Linear issues, projects, and teams
+
+Use this skill when working with manage linear issues, projects, and teams.
+## Tool Selection
+
+Choose the right tool for the task:
+
+| Tool | When to Use |
+|------|-------------|
+| **MCP (Official Server)** | Most operations - PREFERRED |
+| **Helper Scripts** | Bulk operations, when MCP unavailable |
+| **SDK scripts** | Complex operations (loops, conditionals) |
+| **GraphQL API** | Operations not supported by MCP/SDK |
+
+### MCP Server Configuration
+
+**Use the official Linear MCP server** at `mcp.linear.app`:
+
+```json
+{
+  "mcpServers": {
+    "linear": {
+      "command": "npx",
+      "args": ["mcp-remote", "https://mcp.linear.app/sse"],
+      "env": { "LINEAR_API_KEY": "your_api_key" }
+    }
+  }
+}
+```
+
+> **WARNING**: Do NOT use deprecated community servers. See [troubleshooting.md](troubleshooting.md) for details.
+
+### MCP Reliability (Official Server)
+
+| Operation | Reliability | Notes |
+|-----------|-------------|-------|
+| Create issue | ✅ High | Full support |
+| Update status | ✅ High | Use `state: "Done"` directly |
+| List/Search issues | ✅ High | Supports filters, queries |
+| Add comment | ✅ High | Works with issue IDs |
+
+### Quick Status Update
+
+```bash
+# Via MCP - use human-readable state names
+update_issue with id="issue-uuid", state="Done"
+
+# Via helper script (bulk operations)
+node scripts/linear-helpers.mjs update-status Done 123 124 125
+```
+
+### Helper Script Reference
+
+For detailed helper script usage, see **[troubleshooting.md](troubleshooting.md)**.
+
+### Parallel Agent Execution
+
+For bulk operations or background execution, use the `Linear-specialist` subagent:
+
+```javascript
+Task({
+  description: "Update Linear issues",
+  prompt: "Mark ENG-101, ENG-102, ENG-103 as Done",
+  subagent_type: "Linear-specialist"
+})
+```
+
+**When to use `Linear-specialist` (parallel):**
+- Bulk status updates (3+ issues)
+- Project status changes
+- Creating multiple issues
+- Sync operations after code changes
+
+**When to use direct execution:**
+- Single issue queries
+- Viewing issue details
+- Quick status checks
+- Operations needing immediate results
+
+See **[sync.md](sync.md)** for parallel execution patterns.
+
+## Critical Requirements
+
+### Issues → Projects → Initiatives
+
+**Every issue MUST be attached to a project. Every project MUST be linked to an initiative.**
+
+| Entity | Must Link To | If Missing |
+|--------|--------------|------------|
+| Issue | Project | Not visible in project board |
+| Project | Initiative | Not visible in roadmap |
+
+See **[projects.md](projects.md)** for complete project creation checklist.
+
+---
+
+## Conventions
+
+### Issue Status
+
+- **Assigned to me**: Set `state: "Todo"`
+- **Unassigned**: Set `state: "Backlog"`
+
+### Labels
+
+Uses **domain-based label taxonomy**. See [docs/labels.md](docs/labels.md).
+
+**Key rules:**
+- ONE Type label: `feature`, `bug`, `refactor`, `chore`, `spike`
+- 1-2 Domain labels: `security`, `backend`, `frontend`, etc.
+- Scope labels when applicable: `blocked`, `breaking-change`, `tech-debt`
+
+```bash
+# Validate labels
+npx tsx scripts/linear-ops.ts labels validate "feature,security"
+
+# Suggest labels for issue
+npx tsx scripts/linear-ops.ts labels suggest "Fix XSS vulnerability"
+```
+
+## SDK Automation Scripts
+
+**Use only when MCP tools are insufficient.** For complex operations involving loops, mapping, or bulk updates, write TypeScript scripts using `@linear/sdk`. See `sdk.md` for:
+
+- Complete script patterns and templates
+- Common automation examples (bulk updates, filtering, reporting)
+- Tool selection criteria
+
+Scripts provide full type hints and are easier to debug than raw GraphQL for multi-step operations.
+
+## GraphQL API
+
+**Fallback only.** Use when operations aren't supported by MCP or SDK.
+
+See **[api.md](api.md)** for complete documentation including:
+- Authentication and setup
+- Example queries and mutations
+- Timeout handling patterns
+- MCP timeout workarounds
+- Shell script compatibility
+
+**Quick ad-hoc query:**
+
+```bash
+npx tsx ~/.claude/skills/linear/scripts/query.ts "query { viewer { name } }"
+```
+
+## Projects & Initiatives
+
+For advanced project and initiative management patterns, see **[projects.md](projects.md)**.
+
+**Quick reference** - common project commands:
+
+```bash
+# Create project linked to initiative
+npx tsx scripts/linear-ops.ts create-project "Phase X: Name" "My Initiative"
+
+# Update project status
+npx tsx scripts/linear-ops.ts project-status "Phase X" in-progress
+npx tsx scripts/linear-ops.ts project-status "Phase X" completed
+
+# Link/unlink projects to initiatives
+npx tsx scripts/linear-ops.ts link-initiative "Phase X" "My Initiative"
+npx tsx scripts/linear-ops.ts unlink-initiative "Phase X" "Old Initiative"
+```
+
+**Key topics in projects.md:**
+- Project creation checklist (mandatory steps)
+- Content vs Description fields
+- Discovery before creation
+- Codebase verification before work
+- Sub-issue management
+- Project status updates
+- Project updates (status reports)
+
+---
+
+
+## When to Use This Skill
+
+Manage Linear issues, projects, and teams
+
+Use this skill when working with manage linear issues, projects, and teams.
+## Sync Patterns (Bulk Operations)
+
+For bulk synchronization of code changes to Linear, see **[sync.md](sync.md)**.
+
+**Quick sync commands:**
+
+```bash
+# Bulk update issues to Done
+npx tsx scripts/linear-ops.ts status Done ENG-101 ENG-102 ENG-103
+
+# Update project status
+npx tsx scripts/linear-ops.ts project-status "My Project" completed
+```
+
+---
+
+## Reference
+
+| Document | Purpose |
+|----------|---------|
+| [api.md](api.md) | GraphQL API reference, timeout handling |
+| [sdk.md](sdk.md) | SDK automation patterns |
+| [sync.md](sync.md) | Bulk sync patterns |
+| [projects.md](projects.md) | Project & initiative management |
+| [troubleshooting.md](troubleshooting.md) | Common issues, MCP debugging |
+| [docs/labels.md](docs/labels.md) | Label taxonomy |
+
+**External:** [Linear MCP Documentation](https://linear.app/docs/mcp.md)

skills/makepad-skills/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: makepad-skills
+description: "Makepad UI development skills for Rust apps: setup, patterns, shaders, packaging, and troubleshooting."
+source: "https://github.com/ZhangHanDong/makepad-skills"
+risk: safe
+---
+
+# Makepad Skills
+
+## Overview
+
+Makepad UI development skills for Rust apps: setup, patterns, shaders, packaging, and troubleshooting.
+
+## When to Use This Skill
+
+Use this skill when you need to work with makepad ui development skills for rust apps: setup, patterns, shaders, packaging, and troubleshooting..
+
+## Instructions
+
+This skill provides guidance and patterns for makepad ui development skills for rust apps: setup, patterns, shaders, packaging, and troubleshooting..
+
+For more information, see the [source repository](https://github.com/ZhangHanDong/makepad-skills).

skills/memory-systems/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: memory-systems
+description: "Design short-term, long-term, and graph-based memory architectures"
+source: "https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering/tree/main/skills/memory-systems"
+risk: safe
+---
+
+## When to Use This Skill
+
+Design short-term, long-term, and graph-based memory architectures
+
+Use this skill when working with design short-term, long-term, and graph-based memory architectures.
+# Memory System Design
+
+Memory provides the persistence layer that allows agents to maintain continuity across sessions and reason over accumulated knowledge. Simple agents rely entirely on context for memory, losing all state when sessions end. Sophisticated agents implement layered memory architectures that balance immediate context needs with long-term knowledge retention. The evolution from vector stores to knowledge graphs to temporal knowledge graphs represents increasing investment in structured memory for improved retrieval and reasoning.
+
+## When to Activate
+
+Activate this skill when:
+- Building agents that must persist across sessions
+- Needing to maintain entity consistency across conversations
+- Implementing reasoning over accumulated knowledge
+- Designing systems that learn from past interactions
+- Creating knowledge bases that grow over time
+- Building temporal-aware systems that track state changes
+
+## Core Concepts
+
+Memory exists on a spectrum from immediate context to permanent storage. At one extreme, working memory in the context window provides zero-latency access but vanishes when sessions end. At the other extreme, permanent storage persists indefinitely but requires retrieval to enter context.
+
+Simple vector stores lack relationship and temporal structure. Knowledge graphs preserve relationships for reasoning. Temporal knowledge graphs add validity periods for time-aware queries. Implementation choices depend on query complexity, infrastructure constraints, and accuracy requirements.
+
+## Detailed Topics
+
+### Memory Architecture Fundamentals
+
+**The Context-Memory Spectrum**
+Memory exists on a spectrum from immediate context to permanent storage. At one extreme, working memory in the context window provides zero-latency access but vanishes when sessions end. At the other extreme, permanent storage persists indefinitely but requires retrieval to enter context. Effective architectures use multiple layers along this spectrum.
+
+The spectrum includes working memory (context window, zero latency, volatile), short-term memory (session-persistent, searchable, volatile), long-term memory (cross-session persistent, structured, semi-permanent), and permanent memory (archival, queryable, permanent). Each layer has different latency, capacity, and persistence characteristics.
+
+**Why Simple Vector Stores Fall Short**
+Vector RAG provides semantic retrieval by embedding queries and documents in a shared embedding space. Similarity search retrieves the most semantically similar documents. This works well for document retrieval but lacks structure for agent memory.
+
+Vector stores lose relationship information. If an agent learns that "Customer X purchased Product Y on Date Z," a vector store can retrieve this fact if asked directly. But it cannot answer "What products did customers who purchased Product Y also buy?" because relationship structure is not preserved.
+
+Vector stores also struggle with temporal validity. Facts change over time, but vector stores provide no mechanism to distinguish "current fact" from "outdated fact" except through explicit metadata and filtering.
+
+**The Move to Graph-Based Memory**
+Knowledge graphs preserve relationships between entities. Instead of isolated document chunks, graphs encode that Entity A has Relationship R to Entity B. This enables queries that traverse relationships rather than just similarity.
+
+Temporal knowledge graphs add validity periods to facts. Each fact has a "valid from" and optionally "valid until" timestamp. This enables time-travel queries that reconstruct knowledge at specific points in time.
+
+**Benchmark Performance Comparison**
+The Deep Memory Retrieval (DMR) benchmark provides concrete performance data across memory architectures:
+
+| Memory System | DMR Accuracy | Retrieval Latency | Notes |
+|---------------|--------------|-------------------|-------|
+| Zep (Temporal KG) | 94.8% | 2.58s | Best accuracy, fast retrieval |
+| MemGPT | 93.4% | Variable | Good general performance |
+| GraphRAG | ~75-85% | Variable | 20-35% gains over baseline RAG |
+| Vector RAG | ~60-70% | Fast | Loses relationship structure |
+| Recursive Summarization | 35.3% | Low | Severe information loss |
+
+Zep demonstrated 90% reduction in retrieval latency compared to full-context baselines (2.58s vs 28.9s for GPT-5.2). This efficiency comes from retrieving only relevant subgraphs rather than entire context history.
+
+GraphRAG achieves approximately 20-35% accuracy gains over baseline RAG in complex reasoning tasks and reduces hallucination by up to 30% through community-based summarization.
+
+### Memory Layer Architecture
+
+**Layer 1: Working Memory**
+Working memory is the context window itself. It provides immediate access to information currently being processed but has limited capacity and vanishes when sessions end.
+
+Working memory usage patterns include scratchpad calculations where agents track intermediate results, conversation history that preserves dialogue for current task, current task state that tracks progress on active objectives, and active retrieved documents that hold information currently being used.
+
+Optimize working memory by keeping only active information, summarizing completed work before it falls out of attention, and using attention-favored positions for critical information.
+
+**Layer 2: Short-Term Memory**
+Short-term memory persists across the current session but not across sessions. It provides search and retrieval capabilities without the latency of permanent storage.
+
+Common implementations include session-scoped databases that persist until session end, file-system storage in designated session directories, and in-memory caches keyed by session ID.
+
+Short-term memory use cases include tracking conversation state across turns without stuffing context, storing intermediate results from tool calls that may be needed later, maintaining task checklists and progress tracking, and caching retrieved information within sessions.
+
+**Layer 3: Long-Term Memory**
+Long-term memory persists across sessions indefinitely. It enables agents to learn from past interactions and build knowledge over time.
+
+Long-term memory implementations range from simple key-value stores to sophisticated graph databases. The choice depends on complexity of relationships to model, query patterns required, and acceptable infrastructure complexity.
+
+Long-term memory use cases include learning user preferences across sessions, building domain knowledge bases that grow over time, maintaining entity registries with relationship history, and storing successful patterns that can be reused.
+
+**Layer 4: Entity Memory**
+Entity memory specifically tracks information about entities (people, places, concepts, objects) to maintain consistency. This creates a rudimentary knowledge graph where entities are recognized across multiple interactions.
+
+Entity memory maintains entity identity by tracking that "John Doe" mentioned in one conversation is the same person in another. It maintains entity properties by storing facts discovered about entities over time. It maintains entity relationships by tracking relationships between entities as they are discovered.
+
+**Layer 5: Temporal Knowledge Graphs**
+Temporal knowledge graphs extend entity memory with explicit validity periods. Facts are not just true or false but true during specific time ranges.
+
+This enables queries like "What was the user's address on Date X?" by retrieving facts valid during that date range. It prevents context clash when outdated information contradicts new data. It enables temporal reasoning about how entities changed over time.
+
+### Memory Implementation Patterns
+
+**Pattern 1: File-System-as-Memory**
+The file system itself can serve as a memory layer. This pattern is simple, requires no additional infrastructure, and enables the same just-in-time loading that makes file-system-based context effective.
+
+Implementation uses the file system hierarchy for organization. Use naming conventions that convey meaning. Store facts in structured formats (JSON, YAML). Use timestamps in filenames or metadata for temporal tracking.
+
+Advantages: Simplicity, transparency, portability.
+Disadvantages: No semantic search, no relationship tracking, manual organization required.
+
+**Pattern 2: Vector RAG with Metadata**
+Vector stores enhanced with rich metadata provide semantic search with filtering capabilities.
+
+Implementation embeds facts or documents and stores with metadata including entity tags, temporal validity, source attribution, and confidence scores. Query includes metadata filters alongside semantic search.
+
+**Pattern 3: Knowledge Graph**
+Knowledge graphs explicitly model entities and relationships. Implementation defines entity types and relationship types, uses graph database or property graph storage, and maintains indexes for common query patterns.
+
+**Pattern 4: Temporal Knowledge Graph**
+Temporal knowledge graphs add validity periods to facts, enabling time-travel queries and preventing context clash from outdated information.
+
+### Memory Retrieval Patterns
+
+**Semantic Retrieval**
+Retrieve memories semantically similar to current query using embedding similarity search.
+
+**Entity-Based Retrieval**
+Retrieve all memories related to specific entities by traversing graph relationships.
+
+**Temporal Retrieval**
+Retrieve memories valid at specific time or within time range using validity period filters.
+
+### Memory Consolidation
+
+Memories accumulate over time and require consolidation to prevent unbounded growth and remove outdated information.
+
+**Consolidation Triggers**
+Trigger consolidation after significant memory accumulation, when retrieval returns too many outdated results, periodically on a schedule, or when explicit consolidation is requested.
+
+**Consolidation Process**
+Identify outdated facts, merge related facts, update validity periods, archive or delete obsolete facts, and rebuild indexes.
+
+## Practical Guidance
+
+### Integration with Context
+
+Memories must integrate with context systems to be useful. Use just-in-time memory loading to retrieve relevant memories when needed. Use strategic injection to place memories in attention-favored positions.
+
+### Memory System Selection
+
+Choose memory architecture based on requirements:
+- Simple persistence needs: File-system memory
+- Semantic search needs: Vector RAG with metadata
+- Relationship reasoning needs: Knowledge graph
+- Temporal validity needs: Temporal knowledge graph
+
+## Examples
+
+**Example 1: Entity Tracking**
+```python
+# Track entity across conversations
+def remember_entity(entity_id, properties):
+    memory.store({
+        "type": "entity",
+        "id": entity_id,
+        "properties": properties,
+        "last_updated": now()
+    })
+
+def get_entity(entity_id):
+    return memory.retrieve_entity(entity_id)
+```
+
+**Example 2: Temporal Query**
+```python
+# What was the user's address on January 15, 2024?
+def query_address_at_time(user_id, query_time):
+    return temporal_graph.query("""
+        MATCH (user)-[r:LIVES_AT]->(address)
+        WHERE user.id = $user_id
+        AND r.valid_from <= $query_time
+        AND (r.valid_until IS NULL OR r.valid_until > $query_time)
+        RETURN address
+    """, {"user_id": user_id, "query_time": query_time})
+```
+
+## Guidelines
+
+1. Match memory architecture to query requirements
+2. Implement progressive disclosure for memory access
+3. Use temporal validity to prevent outdated information conflicts
+4. Consolidate memories periodically to prevent unbounded growth
+5. Design for memory retrieval failures gracefully
+6. Consider privacy implications of persistent memory
+7. Implement backup and recovery for critical memories
+8. Monitor memory growth and performance over time
+
+## Integration
+
+This skill builds on context-fundamentals. It connects to:
+
+- multi-agent-patterns - Shared memory across agents
+- context-optimization - Memory-based context loading
+- evaluation - Evaluating memory quality
+
+## References
+
+Internal reference:
+- [Implementation Reference](./references/implementation.md) - Detailed implementation patterns
+
+Related skills in this collection:
+- context-fundamentals - Context basics
+- multi-agent-patterns - Cross-agent memory
+
+External resources:
+- Graph database documentation (Neo4j, etc.)
+- Vector store documentation (Pinecone, Weaviate, etc.)
+- Research on knowledge graphs and reasoning
+
+---
+
+## Skill Metadata
+
+**Created**: 2025-12-20
+**Last Updated**: 2025-12-20
+**Author**: Agent Skills for Context Engineering Contributors
+**Version**: 1.0.0

skills/multi-agent-patterns/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: multi-agent-patterns
+description: "Master orchestrator, peer-to-peer, and hierarchical multi-agent architectures"
+source: "https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering/tree/main/skills/multi-agent-patterns"
+risk: safe
+---
+
+## When to Use This Skill
+
+Master orchestrator, peer-to-peer, and hierarchical multi-agent architectures
+
+Use this skill when working with master orchestrator, peer-to-peer, and hierarchical multi-agent architectures.
+# Multi-Agent Architecture Patterns
+
+Multi-agent architectures distribute work across multiple language model instances, each with its own context window. When designed well, this distribution enables capabilities beyond single-agent limits. When designed poorly, it introduces coordination overhead that negates benefits. The critical insight is that sub-agents exist primarily to isolate context, not to anthropomorphize role division.
+
+## When to Activate
+
+Activate this skill when:
+- Single-agent context limits constrain task complexity
+- Tasks decompose naturally into parallel subtasks
+- Different subtasks require different tool sets or system prompts
+- Building systems that must handle multiple domains simultaneously
+- Scaling agent capabilities beyond single-context limits
+- Designing production agent systems with multiple specialized components
+
+## Core Concepts
+
+Multi-agent systems address single-agent context limitations through distribution. Three dominant patterns exist: supervisor/orchestrator for centralized control, peer-to-peer/swarm for flexible handoffs, and hierarchical for layered abstraction. The critical design principle is context isolation—sub-agents exist primarily to partition context rather than to simulate organizational roles.
+
+Effective multi-agent systems require explicit coordination protocols, consensus mechanisms that avoid sycophancy, and careful attention to failure modes including bottlenecks, divergence, and error propagation.
+
+## Detailed Topics
+
+### Why Multi-Agent Architectures
+
+**The Context Bottleneck**
+Single agents face inherent ceilings in reasoning capability, context management, and tool coordination. As tasks grow more complex, context windows fill with accumulated history, retrieved documents, and tool outputs. Performance degrades according to predictable patterns: the lost-in-middle effect, attention scarcity, and context poisoning.
+
+Multi-agent architectures address these limitations by partitioning work across multiple context windows. Each agent operates in a clean context focused on its subtask. Results aggregate at a coordination layer without any single context bearing the full burden.
+
+**The Token Economics Reality**
+Multi-agent systems consume significantly more tokens than single-agent approaches. Production data shows:
+
+| Architecture | Token Multiplier | Use Case |
+|--------------|------------------|----------|
+| Single agent chat | 1× baseline | Simple queries |
+| Single agent with tools | ~4× baseline | Tool-using tasks |
+| Multi-agent system | ~15× baseline | Complex research/coordination |
+
+Research on the BrowseComp evaluation found that three factors explain 95% of performance variance: token usage (80% of variance), number of tool calls, and model choice. This validates the multi-agent approach of distributing work across agents with separate context windows to add capacity for parallel reasoning.
+
+Critically, upgrading to better models often provides larger performance gains than doubling token budgets. Claude Sonnet 4.5 showed larger gains than doubling tokens on earlier Sonnet versions. GPT-5.2's thinking mode similarly outperforms raw token increases. This suggests model selection and multi-agent architecture are complementary strategies.
+
+**The Parallelization Argument**
+Many tasks contain parallelizable subtasks that a single agent must execute sequentially. A research task might require searching multiple independent sources, analyzing different documents, or comparing competing approaches. A single agent processes these sequentially, accumulating context with each step.
+
+Multi-agent architectures assign each subtask to a dedicated agent with a fresh context. All agents work simultaneously, then return results to a coordinator. The total real-world time approaches the duration of the longest subtask rather than the sum of all subtasks.
+
+**The Specialization Argument**
+Different tasks benefit from different agent configurations: different system prompts, different tool sets, different context structures. A general-purpose agent must carry all possible configurations in context. Specialized agents carry only what they need.
+
+Multi-agent architectures enable specialization without combinatorial explosion. The coordinator routes to specialized agents; each agent operates with lean context optimized for its domain.
+
+### Architectural Patterns
+
+**Pattern 1: Supervisor/Orchestrator**
+The supervisor pattern places a central agent in control, delegating to specialists and synthesizing results. The supervisor maintains global state and trajectory, decomposes user objectives into subtasks, and routes to appropriate workers.
+
+```
+User Query -> Supervisor -> [Specialist, Specialist, Specialist] -> Aggregation -> Final Output
+```
+
+When to use: Complex tasks with clear decomposition, tasks requiring coordination across domains, tasks where human oversight is important.
+
+Advantages: Strict control over workflow, easier to implement human-in-the-loop interventions, ensures adherence to predefined plans.
+
+Disadvantages: Supervisor context becomes bottleneck, supervisor failures cascade to all workers, "telephone game" problem where supervisors paraphrase sub-agent responses incorrectly.
+
+**The Telephone Game Problem and Solution**
+LangGraph benchmarks found supervisor architectures initially performed 50% worse than optimized versions due to the "telephone game" problem where supervisors paraphrase sub-agent responses incorrectly, losing fidelity.
+
+The fix: implement a `forward_message` tool allowing sub-agents to pass responses directly to users:
+
+```python
+def forward_message(message: str, to_user: bool = True):
+    """
+    Forward sub-agent response directly to user without supervisor synthesis.
+    
+    Use when:
+    - Sub-agent response is final and complete
+    - Supervisor synthesis would lose important details
+    - Response format must be preserved exactly
+    """
+    if to_user:
+        return {"type": "direct_response", "content": message}
+    return {"type": "supervisor_input", "content": message}
+```
+
+With this pattern, swarm architectures slightly outperform supervisors because sub-agents respond directly to users, eliminating translation errors.
+
+Implementation note: Implement direct pass-through mechanisms allowing sub-agents to pass responses directly to users rather than through supervisor synthesis when appropriate.
+
+**Pattern 2: Peer-to-Peer/Swarm**
+The peer-to-peer pattern removes central control, allowing agents to communicate directly based on predefined protocols. Any agent can transfer control to any other through explicit handoff mechanisms.
+
+```python
+def transfer_to_agent_b():
+    return agent_b  # Handoff via function return
+
+agent_a = Agent(
+    name="Agent A",
+    functions=[transfer_to_agent_b]
+)
+```
+
+When to use: Tasks requiring flexible exploration, tasks where rigid planning is counterproductive, tasks with emergent requirements that defy upfront decomposition.
+
+Advantages: No single point of failure, scales effectively for breadth-first exploration, enables emergent problem-solving behaviors.
+
+Disadvantages: Coordination complexity increases with agent count, risk of divergence without central state keeper, requires robust convergence constraints.
+
+Implementation note: Define explicit handoff protocols with state passing. Ensure agents can communicate their context needs to receiving agents.
+
+**Pattern 3: Hierarchical**
+Hierarchical structures organize agents into layers of abstraction: strategic, planning, and execution layers. Strategy layer agents define goals and constraints; planning layer agents break goals into actionable plans; execution layer agents perform atomic tasks.
+
+```
+Strategy Layer (Goal Definition) -> Planning Layer (Task Decomposition) -> Execution Layer (Atomic Tasks)
+```
+
+When to use: Large-scale projects with clear hierarchical structure, enterprise workflows with management layers, tasks requiring both high-level planning and detailed execution.
+
+Advantages: Mirrors organizational structures, clear separation of concerns, enables different context structures at different levels.
+
+Disadvantages: Coordination overhead between layers, potential for misalignment between strategy and execution, complex error propagation.
+
+### Context Isolation as Design Principle
+
+The primary purpose of multi-agent architectures is context isolation. Each sub-agent operates in a clean context window focused on its subtask without carrying accumulated context from other subtasks.
+
+**Isolation Mechanisms**
+Full context delegation: For complex tasks where the sub-agent needs complete understanding, the planner shares its entire context. The sub-agent has its own tools and instructions but receives full context for its decisions.
+
+Instruction passing: For simple, well-defined subtasks, the planner creates instructions via function call. The sub-agent receives only the instructions needed for its specific task.
+
+File system memory: For complex tasks requiring shared state, agents read and write to persistent storage. The file system serves as the coordination mechanism, avoiding context bloat from shared state passing.
+
+**Isolation Trade-offs**
+Full context delegation provides maximum capability but defeats the purpose of sub-agents. Instruction passing maintains isolation but limits sub-agent flexibility. File system memory enables shared state without context passing but introduces latency and consistency challenges.
+
+The right choice depends on task complexity, coordination needs, and acceptable latency.
+
+### Consensus and Coordination
+
+**The Voting Problem**
+Simple majority voting treats hallucinations from weak models as equal to reasoning from strong models. Without intervention, multi-agent discussions devolve into consensus on false premises due to inherent bias toward agreement.
+
+**Weighted Voting**
+Weight agent votes by confidence or expertise. Agents with higher confidence or domain expertise carry more weight in final decisions.
+
+**Debate Protocols**
+Debate protocols require agents to critique each other's outputs over multiple rounds. Adversarial critique often yields higher accuracy on complex reasoning than collaborative consensus.
+
+**Trigger-Based Intervention**
+Monitor multi-agent interactions for specific behavioral markers. Stall triggers activate when discussions make no progress. Sycophancy triggers detect when agents mimic each other's answers without unique reasoning.
+
+### Framework Considerations
+
+Different frameworks implement these patterns with different philosophies. LangGraph uses graph-based state machines with explicit nodes and edges. AutoGen uses conversational/event-driven patterns with GroupChat. CrewAI uses role-based process flows with hierarchical crew structures.
+
+## Practical Guidance
+
+### Failure Modes and Mitigations
+
+**Failure: Supervisor Bottleneck**
+The supervisor accumulates context from all workers, becoming susceptible to saturation and degradation.
+
+Mitigation: Implement output schema constraints so workers return only distilled summaries. Use checkpointing to persist supervisor state without carrying full history.
+
+**Failure: Coordination Overhead**
+Agent communication consumes tokens and introduces latency. Complex coordination can negate parallelization benefits.
+
+Mitigation: Minimize communication through clear handoff protocols. Batch results where possible. Use asynchronous communication patterns.
+
+**Failure: Divergence**
+Agents pursuing different goals without central coordination can drift from intended objectives.
+
+Mitigation: Define clear objective boundaries for each agent. Implement convergence checks that verify progress toward shared goals. Use time-to-live limits on agent execution.
+
+**Failure: Error Propagation**
+Errors in one agent's output propagate to downstream agents that consume that output.
+
+Mitigation: Validate agent outputs before passing to consumers. Implement retry logic with circuit breakers. Use idempotent operations where possible.
+
+## Examples
+
+**Example 1: Research Team Architecture**
+```text
+Supervisor
+├── Researcher (web search, document retrieval)
+├── Analyzer (data analysis, statistics)
+├── Fact-checker (verification, validation)
+└── Writer (report generation, formatting)
+```
+
+**Example 2: Handoff Protocol**
+```python
+def handle_customer_request(request):
+    if request.type == "billing":
+        return transfer_to(billing_agent)
+    elif request.type == "technical":
+        return transfer_to(technical_agent)
+    elif request.type == "sales":
+        return transfer_to(sales_agent)
+    else:
+        return handle_general(request)
+```
+
+## Guidelines
+
+1. Design for context isolation as the primary benefit of multi-agent systems
+2. Choose architecture pattern based on coordination needs, not organizational metaphor
+3. Implement explicit handoff protocols with state passing
+4. Use weighted voting or debate protocols for consensus
+5. Monitor for supervisor bottlenecks and implement checkpointing
+6. Validate outputs before passing between agents
+7. Set time-to-live limits to prevent infinite loops
+8. Test failure scenarios explicitly
+
+## Integration
+
+This skill builds on context-fundamentals and context-degradation. It connects to:
+
+- memory-systems - Shared state management across agents
+- tool-design - Tool specialization per agent
+- context-optimization - Context partitioning strategies
+
+## References
+
+Internal reference:
+- [Frameworks Reference](./references/frameworks.md) - Detailed framework implementation patterns
+
+Related skills in this collection:
+- context-fundamentals - Context basics
+- memory-systems - Cross-agent memory
+- context-optimization - Partitioning strategies
+
+External resources:
+- [LangGraph Documentation](https://langchain-ai.github.io/langgraph/) - Multi-agent patterns and state management
+- [AutoGen Framework](https://microsoft.github.io/autogen/) - GroupChat and conversational patterns
+- [CrewAI Documentation](https://docs.crewai.com/) - Hierarchical agent processes
+- [Research on Multi-Agent Coordination](https://arxiv.org/abs/2308.00352) - Survey of multi-agent systems
+
+---
+
+## Skill Metadata
+
+**Created**: 2025-12-20
+**Last Updated**: 2025-12-20
+**Author**: Agent Skills for Context Engineering Contributors
+**Version**: 1.0.0

skills/n8n-code-python/SKILL.md

@@ -0,0 +1,750 @@
+---
+name: n8n-code-python
+description: "Write Python code in n8n Code nodes. Use when writing Python in n8n, using _input/_json/_node syntax, working with standard library, or need to understand Python limitations in n8n Code nodes."
+source: "https://github.com/czlonkowski/n8n-skills/tree/main/skills/n8n-code-python"
+risk: safe
+---
+
+# Python Code Node (Beta)
+
+Expert guidance for writing Python code in n8n Code nodes.
+
+---
+
+## ⚠️ Important: JavaScript First
+
+**Recommendation**: Use **JavaScript for 95% of use cases**. Only use Python when:
+- You need specific Python standard library functions
+- You're significantly more comfortable with Python syntax
+- You're doing data transformations better suited to Python
+
+**Why JavaScript is preferred:**
+- Full n8n helper functions ($helpers.httpRequest, etc.)
+- Luxon DateTime library for advanced date/time operations
+- No external library limitations
+- Better n8n documentation and community support
+
+---
+
+## Quick Start
+
+```python
+# Basic template for Python Code nodes
+items = _input.all()
+
+# Process data
+processed = []
+for item in items:
+    processed.append({
+        "json": {
+            **item["json"],
+            "processed": True,
+            "timestamp": datetime.now().isoformat()
+        }
+    })
+
+return processed
+```
+
+### Essential Rules
+
+1. **Consider JavaScript first** - Use Python only when necessary
+2. **Access data**: `_input.all()`, `_input.first()`, or `_input.item`
+3. **CRITICAL**: Must return `[{"json": {...}}]` format
+4. **CRITICAL**: Webhook data is under `_json["body"]` (not `_json` directly)
+5. **CRITICAL LIMITATION**: **No external libraries** (no requests, pandas, numpy)
+6. **Standard library only**: json, datetime, re, base64, hashlib, urllib.parse, math, random, statistics
+
+---
+
+## Mode Selection Guide
+
+Same as JavaScript - choose based on your use case:
+
+### Run Once for All Items (Recommended - Default)
+
+**Use this mode for:** 95% of use cases
+
+- **How it works**: Code executes **once** regardless of input count
+- **Data access**: `_input.all()` or `_items` array (Native mode)
+- **Best for**: Aggregation, filtering, batch processing, transformations
+- **Performance**: Faster for multiple items (single execution)
+
+```python
+# Example: Calculate total from all items
+all_items = _input.all()
+total = sum(item["json"].get("amount", 0) for item in all_items)
+
+return [{
+    "json": {
+        "total": total,
+        "count": len(all_items),
+        "average": total / len(all_items) if all_items else 0
+    }
+}]
+```
+
+### Run Once for Each Item
+
+**Use this mode for:** Specialized cases only
+
+- **How it works**: Code executes **separately** for each input item
+- **Data access**: `_input.item` or `_item` (Native mode)
+- **Best for**: Item-specific logic, independent operations, per-item validation
+- **Performance**: Slower for large datasets (multiple executions)
+
+```python
+# Example: Add processing timestamp to each item
+item = _input.item
+
+return [{
+    "json": {
+        **item["json"],
+        "processed": True,
+        "processed_at": datetime.now().isoformat()
+    }
+}]
+```
+
+---
+
+## Python Modes: Beta vs Native
+
+n8n offers two Python execution modes:
+
+### Python (Beta) - Recommended
+- **Use**: `_input`, `_json`, `_node` helper syntax
+- **Best for**: Most Python use cases
+- **Helpers available**: `_now`, `_today`, `_jmespath()`
+- **Import**: `from datetime import datetime`
+
+```python
+# Python (Beta) example
+items = _input.all()
+now = _now  # Built-in datetime object
+
+return [{
+    "json": {
+        "count": len(items),
+        "timestamp": now.isoformat()
+    }
+}]
+```
+
+### Python (Native) (Beta)
+- **Use**: `_items`, `_item` variables only
+- **No helpers**: No `_input`, `_now`, etc.
+- **More limited**: Standard Python only
+- **Use when**: Need pure Python without n8n helpers
+
+```python
+# Python (Native) example
+processed = []
+
+for item in _items:
+    processed.append({
+        "json": {
+            "id": item["json"].get("id"),
+            "processed": True
+        }
+    })
+
+return processed
+```
+
+**Recommendation**: Use **Python (Beta)** for better n8n integration.
+
+---
+
+## Data Access Patterns
+
+### Pattern 1: _input.all() - Most Common
+
+**Use when**: Processing arrays, batch operations, aggregations
+
+```python
+# Get all items from previous node
+all_items = _input.all()
+
+# Filter, transform as needed
+valid = [item for item in all_items if item["json"].get("status") == "active"]
+
+processed = []
+for item in valid:
+    processed.append({
+        "json": {
+            "id": item["json"]["id"],
+            "name": item["json"]["name"]
+        }
+    })
+
+return processed
+```
+
+### Pattern 2: _input.first() - Very Common
+
+**Use when**: Working with single objects, API responses
+
+```python
+# Get first item only
+first_item = _input.first()
+data = first_item["json"]
+
+return [{
+    "json": {
+        "result": process_data(data),
+        "processed_at": datetime.now().isoformat()
+    }
+}]
+```
+
+### Pattern 3: _input.item - Each Item Mode Only
+
+**Use when**: In "Run Once for Each Item" mode
+
+```python
+# Current item in loop (Each Item mode only)
+current_item = _input.item
+
+return [{
+    "json": {
+        **current_item["json"],
+        "item_processed": True
+    }
+}]
+```
+
+### Pattern 4: _node - Reference Other Nodes
+
+**Use when**: Need data from specific nodes in workflow
+
+```python
+# Get output from specific node
+webhook_data = _node["Webhook"]["json"]
+http_data = _node["HTTP Request"]["json"]
+
+return [{
+    "json": {
+        "combined": {
+            "webhook": webhook_data,
+            "api": http_data
+        }
+    }
+}]
+```
+
+**See**: [DATA_ACCESS.md](DATA_ACCESS.md) for comprehensive guide
+
+---
+
+## Critical: Webhook Data Structure
+
+**MOST COMMON MISTAKE**: Webhook data is nested under `["body"]`
+
+```python
+# ❌ WRONG - Will raise KeyError
+name = _json["name"]
+email = _json["email"]
+
+# ✅ CORRECT - Webhook data is under ["body"]
+name = _json["body"]["name"]
+email = _json["body"]["email"]
+
+# ✅ SAFER - Use .get() for safe access
+webhook_data = _json.get("body", {})
+name = webhook_data.get("name")
+```
+
+**Why**: Webhook node wraps all request data under `body` property. This includes POST data, query parameters, and JSON payloads.
+
+**See**: [DATA_ACCESS.md](DATA_ACCESS.md) for full webhook structure details
+
+---
+
+## Return Format Requirements
+
+**CRITICAL RULE**: Always return list of dictionaries with `"json"` key
+
+### Correct Return Formats
+
+```python
+# ✅ Single result
+return [{
+    "json": {
+        "field1": value1,
+        "field2": value2
+    }
+}]
+
+# ✅ Multiple results
+return [
+    {"json": {"id": 1, "data": "first"}},
+    {"json": {"id": 2, "data": "second"}}
+]
+
+# ✅ List comprehension
+transformed = [
+    {"json": {"id": item["json"]["id"], "processed": True}}
+    for item in _input.all()
+    if item["json"].get("valid")
+]
+return transformed
+
+# ✅ Empty result (when no data to return)
+return []
+
+# ✅ Conditional return
+if should_process:
+    return [{"json": processed_data}]
+else:
+    return []
+```
+
+### Incorrect Return Formats
+
+```python
+# ❌ WRONG: Dictionary without list wrapper
+return {
+    "json": {"field": value}
+}
+
+# ❌ WRONG: List without json wrapper
+return [{"field": value}]
+
+# ❌ WRONG: Plain string
+return "processed"
+
+# ❌ WRONG: Incomplete structure
+return [{"data": value}]  # Should be {"json": value}
+```
+
+**Why it matters**: Next nodes expect list format. Incorrect format causes workflow execution to fail.
+
+**See**: [ERROR_PATTERNS.md](ERROR_PATTERNS.md) #2 for detailed error solutions
+
+---
+
+## Critical Limitation: No External Libraries
+
+**MOST IMPORTANT PYTHON LIMITATION**: Cannot import external packages
+
+### What's NOT Available
+
+```python
+# ❌ NOT AVAILABLE - Will raise ModuleNotFoundError
+import requests  # ❌ No
+import pandas  # ❌ No
+import numpy  # ❌ No
+import scipy  # ❌ No
+from bs4 import BeautifulSoup  # ❌ No
+import lxml  # ❌ No
+```
+
+### What IS Available (Standard Library)
+
+```python
+# ✅ AVAILABLE - Standard library only
+import json  # ✅ JSON parsing
+import datetime  # ✅ Date/time operations
+import re  # ✅ Regular expressions
+import base64  # ✅ Base64 encoding/decoding
+import hashlib  # ✅ Hashing functions
+import urllib.parse  # ✅ URL parsing
+import math  # ✅ Math functions
+import random  # ✅ Random numbers
+import statistics  # ✅ Statistical functions
+```
+
+### Workarounds
+
+**Need HTTP requests?**
+- ✅ Use **HTTP Request node** before Code node
+- ✅ Or switch to **JavaScript** and use `$helpers.httpRequest()`
+
+**Need data analysis (pandas/numpy)?**
+- ✅ Use Python **statistics** module for basic stats
+- ✅ Or switch to **JavaScript** for most operations
+- ✅ Manual calculations with lists and dictionaries
+
+**Need web scraping (BeautifulSoup)?**
+- ✅ Use **HTTP Request node** + **HTML Extract node**
+- ✅ Or switch to **JavaScript** with regex/string methods
+
+**See**: [STANDARD_LIBRARY.md](STANDARD_LIBRARY.md) for complete reference
+
+---
+
+## Common Patterns Overview
+
+Based on production workflows, here are the most useful Python patterns:
+
+### 1. Data Transformation
+Transform all items with list comprehensions
+
+```python
+items = _input.all()
+
+return [
+    {
+        "json": {
+            "id": item["json"].get("id"),
+            "name": item["json"].get("name", "Unknown").upper(),
+            "processed": True
+        }
+    }
+    for item in items
+]
+```
+
+### 2. Filtering & Aggregation
+Sum, filter, count with built-in functions
+
+```python
+items = _input.all()
+total = sum(item["json"].get("amount", 0) for item in items)
+valid_items = [item for item in items if item["json"].get("amount", 0) > 0]
+
+return [{
+    "json": {
+        "total": total,
+        "count": len(valid_items)
+    }
+}]
+```
+
+### 3. String Processing with Regex
+Extract patterns from text
+
+```python
+import re
+
+items = _input.all()
+email_pattern = r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b'
+
+all_emails = []
+for item in items:
+    text = item["json"].get("text", "")
+    emails = re.findall(email_pattern, text)
+    all_emails.extend(emails)
+
+# Remove duplicates
+unique_emails = list(set(all_emails))
+
+return [{
+    "json": {
+        "emails": unique_emails,
+        "count": len(unique_emails)
+    }
+}]
+```
+
+### 4. Data Validation
+Validate and clean data
+
+```python
+items = _input.all()
+validated = []
+
+for item in items:
+    data = item["json"]
+    errors = []
+
+    # Validate fields
+    if not data.get("email"):
+        errors.append("Email required")
+    if not data.get("name"):
+        errors.append("Name required")
+
+    validated.append({
+        "json": {
+            **data,
+            "valid": len(errors) == 0,
+            "errors": errors if errors else None
+        }
+    })
+
+return validated
+```
+
+### 5. Statistical Analysis
+Calculate statistics with statistics module
+
+```python
+from statistics import mean, median, stdev
+
+items = _input.all()
+values = [item["json"].get("value", 0) for item in items if "value" in item["json"]]
+
+if values:
+    return [{
+        "json": {
+            "mean": mean(values),
+            "median": median(values),
+            "stdev": stdev(values) if len(values) > 1 else 0,
+            "min": min(values),
+            "max": max(values),
+            "count": len(values)
+        }
+    }]
+else:
+    return [{"json": {"error": "No values found"}}]
+```
+
+**See**: [COMMON_PATTERNS.md](COMMON_PATTERNS.md) for 10 detailed Python patterns
+
+---
+
+## Error Prevention - Top 5 Mistakes
+
+### #1: Importing External Libraries (Python-Specific!)
+
+```python
+# ❌ WRONG: Trying to import external library
+import requests  # ModuleNotFoundError!
+
+# ✅ CORRECT: Use HTTP Request node or JavaScript
+# Add HTTP Request node before Code node
+# OR switch to JavaScript and use $helpers.httpRequest()
+```
+
+### #2: Empty Code or Missing Return
+
+```python
+# ❌ WRONG: No return statement
+items = _input.all()
+# Processing...
+# Forgot to return!
+
+# ✅ CORRECT: Always return data
+items = _input.all()
+# Processing...
+return [{"json": item["json"]} for item in items]
+```
+
+### #3: Incorrect Return Format
+
+```python
+# ❌ WRONG: Returning dict instead of list
+return {"json": {"result": "success"}}
+
+# ✅ CORRECT: List wrapper required
+return [{"json": {"result": "success"}}]
+```
+
+### #4: KeyError on Dictionary Access
+
+```python
+# ❌ WRONG: Direct access crashes if missing
+name = _json["user"]["name"]  # KeyError!
+
+# ✅ CORRECT: Use .get() for safe access
+name = _json.get("user", {}).get("name", "Unknown")
+```
+
+### #5: Webhook Body Nesting
+
+```python
+# ❌ WRONG: Direct access to webhook data
+email = _json["email"]  # KeyError!
+
+# ✅ CORRECT: Webhook data under ["body"]
+email = _json["body"]["email"]
+
+# ✅ BETTER: Safe access with .get()
+email = _json.get("body", {}).get("email", "no-email")
+```
+
+**See**: [ERROR_PATTERNS.md](ERROR_PATTERNS.md) for comprehensive error guide
+
+---
+
+## Standard Library Reference
+
+### Most Useful Modules
+
+```python
+# JSON operations
+import json
+data = json.loads(json_string)
+json_output = json.dumps({"key": "value"})
+
+# Date/time
+from datetime import datetime, timedelta
+now = datetime.now()
+tomorrow = now + timedelta(days=1)
+formatted = now.strftime("%Y-%m-%d")
+
+# Regular expressions
+import re
+matches = re.findall(r'\d+', text)
+cleaned = re.sub(r'[^\w\s]', '', text)
+
+# Base64 encoding
+import base64
+encoded = base64.b64encode(data).decode()
+decoded = base64.b64decode(encoded)
+
+# Hashing
+import hashlib
+hash_value = hashlib.sha256(text.encode()).hexdigest()
+
+# URL parsing
+import urllib.parse
+params = urllib.parse.urlencode({"key": "value"})
+parsed = urllib.parse.urlparse(url)
+
+# Statistics
+from statistics import mean, median, stdev
+average = mean([1, 2, 3, 4, 5])
+```
+
+**See**: [STANDARD_LIBRARY.md](STANDARD_LIBRARY.md) for complete reference
+
+---
+
+## Best Practices
+
+### 1. Always Use .get() for Dictionary Access
+
+```python
+# ✅ SAFE: Won't crash if field missing
+value = item["json"].get("field", "default")
+
+# ❌ RISKY: Crashes if field doesn't exist
+value = item["json"]["field"]
+```
+
+### 2. Handle None/Null Values Explicitly
+
+```python
+# ✅ GOOD: Default to 0 if None
+amount = item["json"].get("amount") or 0
+
+# ✅ GOOD: Check for None explicitly
+text = item["json"].get("text")
+if text is None:
+    text = ""
+```
+
+### 3. Use List Comprehensions for Filtering
+
+```python
+# ✅ PYTHONIC: List comprehension
+valid = [item for item in items if item["json"].get("active")]
+
+# ❌ VERBOSE: Manual loop
+valid = []
+for item in items:
+    if item["json"].get("active"):
+        valid.append(item)
+```
+
+### 4. Return Consistent Structure
+
+```python
+# ✅ CONSISTENT: Always list with "json" key
+return [{"json": result}]  # Single result
+return results  # Multiple results (already formatted)
+return []  # No results
+```
+
+### 5. Debug with print() Statements
+
+```python
+# Debug statements appear in browser console (F12)
+items = _input.all()
+print(f"Processing {len(items)} items")
+print(f"First item: {items[0] if items else 'None'}")
+```
+
+---
+
+## When to Use Python vs JavaScript
+
+### Use Python When:
+- ✅ You need `statistics` module for statistical operations
+- ✅ You're significantly more comfortable with Python syntax
+- ✅ Your logic maps well to list comprehensions
+- ✅ You need specific standard library functions
+
+### Use JavaScript When:
+- ✅ You need HTTP requests ($helpers.httpRequest())
+- ✅ You need advanced date/time (DateTime/Luxon)
+- ✅ You want better n8n integration
+- ✅ **For 95% of use cases** (recommended)
+
+### Consider Other Nodes When:
+- ❌ Simple field mapping → Use **Set** node
+- ❌ Basic filtering → Use **Filter** node
+- ❌ Simple conditionals → Use **IF** or **Switch** node
+- ❌ HTTP requests only → Use **HTTP Request** node
+
+---
+
+## Integration with Other Skills
+
+### Works With:
+
+**n8n Expression Syntax**:
+- Expressions use `{{ }}` syntax in other nodes
+- Code nodes use Python directly (no `{{ }}`)
+- When to use expressions vs code
+
+**n8n MCP Tools Expert**:
+- How to find Code node: `search_nodes({query: "code"})`
+- Get configuration help: `get_node_essentials("nodes-base.code")`
+- Validate code: `validate_node_operation()`
+
+**n8n Node Configuration**:
+- Mode selection (All Items vs Each Item)
+- Language selection (Python vs JavaScript)
+- Understanding property dependencies
+
+**n8n Workflow Patterns**:
+- Code nodes in transformation step
+- When to use Python vs JavaScript in patterns
+
+**n8n Validation Expert**:
+- Validate Code node configuration
+- Handle validation errors
+- Auto-fix common issues
+
+**n8n Code JavaScript**:
+- When to use JavaScript instead
+- Comparison of JavaScript vs Python features
+- Migration from Python to JavaScript
+
+---
+
+## Quick Reference Checklist
+
+Before deploying Python Code nodes, verify:
+
+- [ ] **Considered JavaScript first** - Using Python only when necessary
+- [ ] **Code is not empty** - Must have meaningful logic
+- [ ] **Return statement exists** - Must return list of dictionaries
+- [ ] **Proper return format** - Each item: `{"json": {...}}`
+- [ ] **Data access correct** - Using `_input.all()`, `_input.first()`, or `_input.item`
+- [ ] **No external imports** - Only standard library (json, datetime, re, etc.)
+- [ ] **Safe dictionary access** - Using `.get()` to avoid KeyError
+- [ ] **Webhook data** - Access via `["body"]` if from webhook
+- [ ] **Mode selection** - "All Items" for most cases
+- [ ] **Output consistent** - All code paths return same structure
+
+---
+
+## Additional Resources
+
+### Related Files
+- [DATA_ACCESS.md](DATA_ACCESS.md) - Comprehensive Python data access patterns
+- [COMMON_PATTERNS.md](COMMON_PATTERNS.md) - 10 Python patterns for n8n
+- [ERROR_PATTERNS.md](ERROR_PATTERNS.md) - Top 5 errors and solutions
+- [STANDARD_LIBRARY.md](STANDARD_LIBRARY.md) - Complete standard library reference
+
+### n8n Documentation
+- Code Node Guide: https://docs.n8n.io/code/code-node/
+- Python in n8n: https://docs.n8n.io/code/builtin/python-modules/
+
+---
+
+**Ready to write Python in n8n Code nodes - but consider JavaScript first!** Use Python for specific needs, reference the error patterns guide to avoid common mistakes, and leverage the standard library effectively.

skills/n8n-mcp-tools-expert/SKILL.md

@@ -0,0 +1,654 @@
+---
+name: n8n-mcp-tools-expert
+description: "Expert guide for using n8n-mcp MCP tools effectively. Use when searching for nodes, validating configurations, accessing templates, managing workflows, or using any n8n-mcp tool. Provides tool selection guidance, parameter formats, and common patterns."
+source: "https://github.com/czlonkowski/n8n-skills/tree/main/skills/n8n-mcp-tools-expert"
+risk: safe
+---
+
+# n8n MCP Tools Expert
+
+Master guide for using n8n-mcp MCP server tools to build workflows.
+
+## When to Use This Skill
+
+Use this skill when:
+- Searching for n8n nodes
+- Validating n8n configurations
+- Accessing n8n templates
+- Managing n8n workflows
+- Using any n8n-mcp tool
+- Need guidance on tool selection or parameter formats
+
+---
+
+## Tool Categories
+
+n8n-mcp provides tools organized into categories:
+
+1. **Node Discovery** → [SEARCH_GUIDE.md](SEARCH_GUIDE.md)
+2. **Configuration Validation** → [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md)
+3. **Workflow Management** → [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md)
+4. **Template Library** - Search and deploy 2,700+ real workflows
+5. **Documentation & Guides** - Tool docs, AI agent guide, Code node guides
+
+---
+
+## Quick Reference
+
+### Most Used Tools (by success rate)
+
+| Tool | Use When | Speed |
+|------|----------|-------|
+| `search_nodes` | Finding nodes by keyword | <20ms |
+| `get_node` | Understanding node operations (detail="standard") | <10ms |
+| `validate_node` | Checking configurations (mode="full") | <100ms |
+| `n8n_create_workflow` | Creating workflows | 100-500ms |
+| `n8n_update_partial_workflow` | Editing workflows (MOST USED!) | 50-200ms |
+| `validate_workflow` | Checking complete workflow | 100-500ms |
+| `n8n_deploy_template` | Deploy template to n8n instance | 200-500ms |
+
+---
+
+## Tool Selection Guide
+
+### Finding the Right Node
+
+**Workflow**:
+```
+1. search_nodes({query: "keyword"})
+2. get_node({nodeType: "nodes-base.name"})
+3. [Optional] get_node({nodeType: "nodes-base.name", mode: "docs"})
+```
+
+**Example**:
+```javascript
+// Step 1: Search
+search_nodes({query: "slack"})
+// Returns: nodes-base.slack
+
+// Step 2: Get details
+get_node({nodeType: "nodes-base.slack"})
+// Returns: operations, properties, examples (standard detail)
+
+// Step 3: Get readable documentation
+get_node({nodeType: "nodes-base.slack", mode: "docs"})
+// Returns: markdown documentation
+```
+
+**Common pattern**: search → get_node (18s average)
+
+### Validating Configuration
+
+**Workflow**:
+```
+1. validate_node({nodeType, config: {}, mode: "minimal"}) - Check required fields
+2. validate_node({nodeType, config, profile: "runtime"}) - Full validation
+3. [Repeat] Fix errors, validate again
+```
+
+**Common pattern**: validate → fix → validate (23s thinking, 58s fixing per cycle)
+
+### Managing Workflows
+
+**Workflow**:
+```
+1. n8n_create_workflow({name, nodes, connections})
+2. n8n_validate_workflow({id})
+3. n8n_update_partial_workflow({id, operations: [...]})
+4. n8n_validate_workflow({id}) again
+5. n8n_update_partial_workflow({id, operations: [{type: "activateWorkflow"}]})
+```
+
+**Common pattern**: iterative updates (56s average between edits)
+
+---
+
+## Critical: nodeType Formats
+
+**Two different formats** for different tools!
+
+### Format 1: Search/Validate Tools
+```javascript
+// Use SHORT prefix
+"nodes-base.slack"
+"nodes-base.httpRequest"
+"nodes-base.webhook"
+"nodes-langchain.agent"
+```
+
+**Tools that use this**:
+- search_nodes (returns this format)
+- get_node
+- validate_node
+- validate_workflow
+
+### Format 2: Workflow Tools
+```javascript
+// Use FULL prefix
+"n8n-nodes-base.slack"
+"n8n-nodes-base.httpRequest"
+"n8n-nodes-base.webhook"
+"@n8n/n8n-nodes-langchain.agent"
+```
+
+**Tools that use this**:
+- n8n_create_workflow
+- n8n_update_partial_workflow
+
+### Conversion
+
+```javascript
+// search_nodes returns BOTH formats
+{
+  "nodeType": "nodes-base.slack",          // For search/validate tools
+  "workflowNodeType": "n8n-nodes-base.slack"  // For workflow tools
+}
+```
+
+---
+
+## Common Mistakes
+
+### Mistake 1: Wrong nodeType Format
+
+**Problem**: "Node not found" error
+
+```javascript
+// WRONG
+get_node({nodeType: "slack"})  // Missing prefix
+get_node({nodeType: "n8n-nodes-base.slack"})  // Wrong prefix
+
+// CORRECT
+get_node({nodeType: "nodes-base.slack"})
+```
+
+### Mistake 2: Using detail="full" by Default
+
+**Problem**: Huge payload, slower response, token waste
+
+```javascript
+// WRONG - Returns 3-8K tokens, use sparingly
+get_node({nodeType: "nodes-base.slack", detail: "full"})
+
+// CORRECT - Returns 1-2K tokens, covers 95% of use cases
+get_node({nodeType: "nodes-base.slack"})  // detail="standard" is default
+get_node({nodeType: "nodes-base.slack", detail: "standard"})
+```
+
+**When to use detail="full"**:
+- Debugging complex configuration issues
+- Need complete property schema with all nested options
+- Exploring advanced features
+
+**Better alternatives**:
+1. `get_node({detail: "standard"})` - for operations list (default)
+2. `get_node({mode: "docs"})` - for readable documentation
+3. `get_node({mode: "search_properties", propertyQuery: "auth"})` - for specific property
+
+### Mistake 3: Not Using Validation Profiles
+
+**Problem**: Too many false positives OR missing real errors
+
+**Profiles**:
+- `minimal` - Only required fields (fast, permissive)
+- `runtime` - Values + types (recommended for pre-deployment)
+- `ai-friendly` - Reduce false positives (for AI configuration)
+- `strict` - Maximum validation (for production)
+
+```javascript
+// WRONG - Uses default profile
+validate_node({nodeType, config})
+
+// CORRECT - Explicit profile
+validate_node({nodeType, config, profile: "runtime"})
+```
+
+### Mistake 4: Ignoring Auto-Sanitization
+
+**What happens**: ALL nodes sanitized on ANY workflow update
+
+**Auto-fixes**:
+- Binary operators (equals, contains) → removes singleValue
+- Unary operators (isEmpty, isNotEmpty) → adds singleValue: true
+- IF/Switch nodes → adds missing metadata
+
+**Cannot fix**:
+- Broken connections
+- Branch count mismatches
+- Paradoxical corrupt states
+
+```javascript
+// After ANY update, auto-sanitization runs on ALL nodes
+n8n_update_partial_workflow({id, operations: [...]})
+// → Automatically fixes operator structures
+```
+
+### Mistake 5: Not Using Smart Parameters
+
+**Problem**: Complex sourceIndex calculations for multi-output nodes
+
+**Old way** (manual):
+```javascript
+// IF node connection
+{
+  type: "addConnection",
+  source: "IF",
+  target: "Handler",
+  sourceIndex: 0  // Which output? Hard to remember!
+}
+```
+
+**New way** (smart parameters):
+```javascript
+// IF node - semantic branch names
+{
+  type: "addConnection",
+  source: "IF",
+  target: "True Handler",
+  branch: "true"  // Clear and readable!
+}
+
+{
+  type: "addConnection",
+  source: "IF",
+  target: "False Handler",
+  branch: "false"
+}
+
+// Switch node - semantic case numbers
+{
+  type: "addConnection",
+  source: "Switch",
+  target: "Handler A",
+  case: 0
+}
+```
+
+### Mistake 6: Not Using intent Parameter
+
+**Problem**: Less helpful tool responses
+
+```javascript
+// WRONG - No context for response
+n8n_update_partial_workflow({
+  id: "abc",
+  operations: [{type: "addNode", node: {...}}]
+})
+
+// CORRECT - Better AI responses
+n8n_update_partial_workflow({
+  id: "abc",
+  intent: "Add error handling for API failures",
+  operations: [{type: "addNode", node: {...}}]
+})
+```
+
+---
+
+## Tool Usage Patterns
+
+### Pattern 1: Node Discovery (Most Common)
+
+**Common workflow**: 18s average between steps
+
+```javascript
+// Step 1: Search (fast!)
+const results = await search_nodes({
+  query: "slack",
+  mode: "OR",  // Default: any word matches
+  limit: 20
+});
+// → Returns: nodes-base.slack, nodes-base.slackTrigger
+
+// Step 2: Get details (~18s later, user reviewing results)
+const details = await get_node({
+  nodeType: "nodes-base.slack",
+  includeExamples: true  // Get real template configs
+});
+// → Returns: operations, properties, metadata
+```
+
+### Pattern 2: Validation Loop
+
+**Typical cycle**: 23s thinking, 58s fixing
+
+```javascript
+// Step 1: Validate
+const result = await validate_node({
+  nodeType: "nodes-base.slack",
+  config: {
+    resource: "channel",
+    operation: "create"
+  },
+  profile: "runtime"
+});
+
+// Step 2: Check errors (~23s thinking)
+if (!result.valid) {
+  console.log(result.errors);  // "Missing required field: name"
+}
+
+// Step 3: Fix config (~58s fixing)
+config.name = "general";
+
+// Step 4: Validate again
+await validate_node({...});  // Repeat until clean
+```
+
+### Pattern 3: Workflow Editing
+
+**Most used update tool**: 99.0% success rate, 56s average between edits
+
+```javascript
+// Iterative workflow building (NOT one-shot!)
+// Edit 1
+await n8n_update_partial_workflow({
+  id: "workflow-id",
+  intent: "Add webhook trigger",
+  operations: [{type: "addNode", node: {...}}]
+});
+
+// ~56s later...
+
+// Edit 2
+await n8n_update_partial_workflow({
+  id: "workflow-id",
+  intent: "Connect webhook to processor",
+  operations: [{type: "addConnection", source: "...", target: "..."}]
+});
+
+// ~56s later...
+
+// Edit 3 (validation)
+await n8n_validate_workflow({id: "workflow-id"});
+
+// Ready? Activate!
+await n8n_update_partial_workflow({
+  id: "workflow-id",
+  intent: "Activate workflow for production",
+  operations: [{type: "activateWorkflow"}]
+});
+```
+
+---
+
+## Detailed Guides
+
+### Node Discovery Tools
+See [SEARCH_GUIDE.md](SEARCH_GUIDE.md) for:
+- search_nodes
+- get_node with detail levels (minimal, standard, full)
+- get_node modes (info, docs, search_properties, versions)
+
+### Validation Tools
+See [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md) for:
+- Validation profiles explained
+- validate_node with modes (minimal, full)
+- validate_workflow complete structure
+- Auto-sanitization system
+- Handling validation errors
+
+### Workflow Management
+See [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md) for:
+- n8n_create_workflow
+- n8n_update_partial_workflow (17 operation types!)
+- Smart parameters (branch, case)
+- AI connection types (8 types)
+- Workflow activation (activateWorkflow/deactivateWorkflow)
+- n8n_deploy_template
+- n8n_workflow_versions
+
+---
+
+## Template Usage
+
+### Search Templates
+
+```javascript
+// Search by keyword (default mode)
+search_templates({
+  query: "webhook slack",
+  limit: 20
+});
+
+// Search by node types
+search_templates({
+  searchMode: "by_nodes",
+  nodeTypes: ["n8n-nodes-base.httpRequest", "n8n-nodes-base.slack"]
+});
+
+// Search by task type
+search_templates({
+  searchMode: "by_task",
+  task: "webhook_processing"
+});
+
+// Search by metadata (complexity, setup time)
+search_templates({
+  searchMode: "by_metadata",
+  complexity: "simple",
+  maxSetupMinutes: 15
+});
+```
+
+### Get Template Details
+
+```javascript
+get_template({
+  templateId: 2947,
+  mode: "structure"  // nodes+connections only
+});
+
+get_template({
+  templateId: 2947,
+  mode: "full"  // complete workflow JSON
+});
+```
+
+### Deploy Template Directly
+
+```javascript
+// Deploy template to your n8n instance
+n8n_deploy_template({
+  templateId: 2947,
+  name: "My Weather to Slack",  // Custom name (optional)
+  autoFix: true,  // Auto-fix common issues (default)
+  autoUpgradeVersions: true  // Upgrade node versions (default)
+});
+// Returns: workflow ID, required credentials, fixes applied
+```
+
+---
+
+## Self-Help Tools
+
+### Get Tool Documentation
+
+```javascript
+// Overview of all tools
+tools_documentation()
+
+// Specific tool details
+tools_documentation({
+  topic: "search_nodes",
+  depth: "full"
+})
+
+// Code node guides
+tools_documentation({topic: "javascript_code_node_guide", depth: "full"})
+tools_documentation({topic: "python_code_node_guide", depth: "full"})
+```
+
+### AI Agent Guide
+
+```javascript
+// Comprehensive AI workflow guide
+ai_agents_guide()
+// Returns: Architecture, connections, tools, validation, best practices
+```
+
+### Health Check
+
+```javascript
+// Quick health check
+n8n_health_check()
+
+// Detailed diagnostics
+n8n_health_check({mode: "diagnostic"})
+// → Returns: status, env vars, tool status, API connectivity
+```
+
+---
+
+## Tool Availability
+
+**Always Available** (no n8n API needed):
+- search_nodes, get_node
+- validate_node, validate_workflow
+- search_templates, get_template
+- tools_documentation, ai_agents_guide
+
+**Requires n8n API** (N8N_API_URL + N8N_API_KEY):
+- n8n_create_workflow
+- n8n_update_partial_workflow
+- n8n_validate_workflow (by ID)
+- n8n_list_workflows, n8n_get_workflow
+- n8n_test_workflow
+- n8n_executions
+- n8n_deploy_template
+- n8n_workflow_versions
+- n8n_autofix_workflow
+
+If API tools unavailable, use templates and validation-only workflows.
+
+---
+
+## Unified Tool Reference
+
+### get_node (Unified Node Information)
+
+**Detail Levels** (mode="info", default):
+- `minimal` (~200 tokens) - Basic metadata only
+- `standard` (~1-2K tokens) - Essential properties + operations (RECOMMENDED)
+- `full` (~3-8K tokens) - Complete schema (use sparingly)
+
+**Operation Modes**:
+- `info` (default) - Node schema with detail level
+- `docs` - Readable markdown documentation
+- `search_properties` - Find specific properties (use with propertyQuery)
+- `versions` - List all versions with breaking changes
+- `compare` - Compare two versions
+- `breaking` - Show only breaking changes
+- `migrations` - Show auto-migratable changes
+
+```javascript
+// Standard (recommended)
+get_node({nodeType: "nodes-base.httpRequest"})
+
+// Get documentation
+get_node({nodeType: "nodes-base.webhook", mode: "docs"})
+
+// Search for properties
+get_node({nodeType: "nodes-base.httpRequest", mode: "search_properties", propertyQuery: "auth"})
+
+// Check versions
+get_node({nodeType: "nodes-base.executeWorkflow", mode: "versions"})
+```
+
+### validate_node (Unified Validation)
+
+**Modes**:
+- `full` (default) - Comprehensive validation with errors/warnings/suggestions
+- `minimal` - Quick required fields check only
+
+**Profiles** (for mode="full"):
+- `minimal` - Very lenient
+- `runtime` - Standard (default, recommended)
+- `ai-friendly` - Balanced for AI workflows
+- `strict` - Most thorough (production)
+
+```javascript
+// Full validation with runtime profile
+validate_node({nodeType: "nodes-base.slack", config: {...}, profile: "runtime"})
+
+// Quick required fields check
+validate_node({nodeType: "nodes-base.webhook", config: {}, mode: "minimal"})
+```
+
+---
+
+## Performance Characteristics
+
+| Tool | Response Time | Payload Size |
+|------|---------------|--------------|
+| search_nodes | <20ms | Small |
+| get_node (standard) | <10ms | ~1-2KB |
+| get_node (full) | <100ms | 3-8KB |
+| validate_node (minimal) | <50ms | Small |
+| validate_node (full) | <100ms | Medium |
+| validate_workflow | 100-500ms | Medium |
+| n8n_create_workflow | 100-500ms | Medium |
+| n8n_update_partial_workflow | 50-200ms | Small |
+| n8n_deploy_template | 200-500ms | Medium |
+
+---
+
+## Best Practices
+
+### Do
+- Use `get_node({detail: "standard"})` for most use cases
+- Specify validation profile explicitly (`profile: "runtime"`)
+- Use smart parameters (`branch`, `case`) for clarity
+- Include `intent` parameter in workflow updates
+- Follow search → get_node → validate workflow
+- Iterate workflows (avg 56s between edits)
+- Validate after every significant change
+- Use `includeExamples: true` for real configs
+- Use `n8n_deploy_template` for quick starts
+
+### Don't
+- Use `detail: "full"` unless necessary (wastes tokens)
+- Forget nodeType prefix (`nodes-base.*`)
+- Skip validation profiles
+- Try to build workflows in one shot (iterate!)
+- Ignore auto-sanitization behavior
+- Use full prefix (`n8n-nodes-base.*`) with search/validate tools
+- Forget to activate workflows after building
+
+---
+
+## Summary
+
+**Most Important**:
+1. Use **get_node** with `detail: "standard"` (default) - covers 95% of use cases
+2. nodeType formats differ: `nodes-base.*` (search/validate) vs `n8n-nodes-base.*` (workflows)
+3. Specify **validation profiles** (`runtime` recommended)
+4. Use **smart parameters** (`branch="true"`, `case=0`)
+5. Include **intent parameter** in workflow updates
+6. **Auto-sanitization** runs on ALL nodes during updates
+7. Workflows can be **activated via API** (`activateWorkflow` operation)
+8. Workflows are built **iteratively** (56s avg between edits)
+
+**Common Workflow**:
+1. search_nodes → find node
+2. get_node → understand config
+3. validate_node → check config
+4. n8n_create_workflow → build
+5. n8n_validate_workflow → verify
+6. n8n_update_partial_workflow → iterate
+7. activateWorkflow → go live!
+
+For details, see:
+- [SEARCH_GUIDE.md](SEARCH_GUIDE.md) - Node discovery
+- [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md) - Configuration validation
+- [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md) - Workflow management
+
+---
+
+**Related Skills**:
+- n8n Expression Syntax - Write expressions in workflow fields
+- n8n Workflow Patterns - Architectural patterns from templates
+- n8n Validation Expert - Interpret validation errors
+- n8n Node Configuration - Operation-specific requirements
+- n8n Code JavaScript - Write JavaScript in Code nodes
+- n8n Code Python - Write Python in Code nodes

skills/n8n-node-configuration/SKILL.md

@@ -0,0 +1,796 @@
+---
+name: n8n-node-configuration
+description: "Operation-aware node configuration guidance. Use when configuring nodes, understanding property dependencies, determining required fields, choosing between get_node detail levels, or learning common configuration patterns by node type."
+source: "https://github.com/czlonkowski/n8n-skills/tree/main/skills/n8n-node-configuration"
+risk: safe
+---
+
+# n8n Node Configuration
+
+Expert guidance for operation-aware node configuration with property dependencies.
+
+## When to Use This Skill
+
+Use this skill when:
+- Configuring n8n nodes
+- Understanding property dependencies
+- Determining required fields
+- Choosing between get_node detail levels
+- Learning common configuration patterns by node type
+
+---
+
+## Configuration Philosophy
+
+**Progressive disclosure**: Start minimal, add complexity as needed
+
+Configuration best practices:
+- `get_node` with `detail: "standard"` is the most used discovery pattern
+- 56 seconds average between configuration edits
+- Covers 95% of use cases with 1-2K tokens response
+
+**Key insight**: Most configurations need only standard detail, not full schema!
+
+---
+
+## Core Concepts
+
+### 1. Operation-Aware Configuration
+
+**Not all fields are always required** - it depends on operation!
+
+**Example**: Slack node
+```javascript
+// For operation='post'
+{
+  "resource": "message",
+  "operation": "post",
+  "channel": "#general",  // Required for post
+  "text": "Hello!"        // Required for post
+}
+
+// For operation='update'
+{
+  "resource": "message",
+  "operation": "update",
+  "messageId": "123",     // Required for update (different!)
+  "text": "Updated!"      // Required for update
+  // channel NOT required for update
+}
+```
+
+**Key**: Resource + operation determine which fields are required!
+
+### 2. Property Dependencies
+
+**Fields appear/disappear based on other field values**
+
+**Example**: HTTP Request node
+```javascript
+// When method='GET'
+{
+  "method": "GET",
+  "url": "https://api.example.com"
+  // sendBody not shown (GET doesn't have body)
+}
+
+// When method='POST'
+{
+  "method": "POST",
+  "url": "https://api.example.com",
+  "sendBody": true,       // Now visible!
+  "body": {               // Required when sendBody=true
+    "contentType": "json",
+    "content": {...}
+  }
+}
+```
+
+**Mechanism**: displayOptions control field visibility
+
+### 3. Progressive Discovery
+
+**Use the right detail level**:
+
+1. **get_node({detail: "standard"})** - DEFAULT
+   - Quick overview (~1-2K tokens)
+   - Required fields + common options
+   - **Use first** - covers 95% of needs
+
+2. **get_node({mode: "search_properties", propertyQuery: "..."})** (for finding specific fields)
+   - Find properties by name
+   - Use when looking for auth, body, headers, etc.
+
+3. **get_node({detail: "full"})** (complete schema)
+   - All properties (~3-8K tokens)
+   - Use only when standard detail is insufficient
+
+---
+
+## Configuration Workflow
+
+### Standard Process
+
+```
+1. Identify node type and operation
+   ↓
+2. Use get_node (standard detail is default)
+   ↓
+3. Configure required fields
+   ↓
+4. Validate configuration
+   ↓
+5. If field unclear → get_node({mode: "search_properties"})
+   ↓
+6. Add optional fields as needed
+   ↓
+7. Validate again
+   ↓
+8. Deploy
+```
+
+### Example: Configuring HTTP Request
+
+**Step 1**: Identify what you need
+```javascript
+// Goal: POST JSON to API
+```
+
+**Step 2**: Get node info
+```javascript
+const info = get_node({
+  nodeType: "nodes-base.httpRequest"
+});
+
+// Returns: method, url, sendBody, body, authentication required/optional
+```
+
+**Step 3**: Minimal config
+```javascript
+{
+  "method": "POST",
+  "url": "https://api.example.com/create",
+  "authentication": "none"
+}
+```
+
+**Step 4**: Validate
+```javascript
+validate_node({
+  nodeType: "nodes-base.httpRequest",
+  config,
+  profile: "runtime"
+});
+// → Error: "sendBody required for POST"
+```
+
+**Step 5**: Add required field
+```javascript
+{
+  "method": "POST",
+  "url": "https://api.example.com/create",
+  "authentication": "none",
+  "sendBody": true
+}
+```
+
+**Step 6**: Validate again
+```javascript
+validate_node({...});
+// → Error: "body required when sendBody=true"
+```
+
+**Step 7**: Complete configuration
+```javascript
+{
+  "method": "POST",
+  "url": "https://api.example.com/create",
+  "authentication": "none",
+  "sendBody": true,
+  "body": {
+    "contentType": "json",
+    "content": {
+      "name": "={{$json.name}}",
+      "email": "={{$json.email}}"
+    }
+  }
+}
+```
+
+**Step 8**: Final validation
+```javascript
+validate_node({...});
+// → Valid! ✅
+```
+
+---
+
+## get_node Detail Levels
+
+### Standard Detail (DEFAULT - Use This!)
+
+**✅ Starting configuration**
+```javascript
+get_node({
+  nodeType: "nodes-base.slack"
+});
+// detail="standard" is the default
+```
+
+**Returns** (~1-2K tokens):
+- Required fields
+- Common options
+- Operation list
+- Metadata
+
+**Use**: 95% of configuration needs
+
+### Full Detail (Use Sparingly)
+
+**✅ When standard isn't enough**
+```javascript
+get_node({
+  nodeType: "nodes-base.slack",
+  detail: "full"
+});
+```
+
+**Returns** (~3-8K tokens):
+- Complete schema
+- All properties
+- All nested options
+
+**Warning**: Large response, use only when standard insufficient
+
+### Search Properties Mode
+
+**✅ Looking for specific field**
+```javascript
+get_node({
+  nodeType: "nodes-base.httpRequest",
+  mode: "search_properties",
+  propertyQuery: "auth"
+});
+```
+
+**Use**: Find authentication, headers, body fields, etc.
+
+### Decision Tree
+
+```
+┌─────────────────────────────────┐
+│ Starting new node config?       │
+├─────────────────────────────────┤
+│ YES → get_node (standard)       │
+└─────────────────────────────────┘
+         ↓
+┌─────────────────────────────────┐
+│ Standard has what you need?     │
+├─────────────────────────────────┤
+│ YES → Configure with it         │
+│ NO  → Continue                  │
+└─────────────────────────────────┘
+         ↓
+┌─────────────────────────────────┐
+│ Looking for specific field?     │
+├─────────────────────────────────┤
+│ YES → search_properties mode    │
+│ NO  → Continue                  │
+└─────────────────────────────────┘
+         ↓
+┌─────────────────────────────────┐
+│ Still need more details?        │
+├─────────────────────────────────┤
+│ YES → get_node({detail: "full"})│
+└─────────────────────────────────┘
+```
+
+---
+
+## Property Dependencies Deep Dive
+
+### displayOptions Mechanism
+
+**Fields have visibility rules**:
+
+```javascript
+{
+  "name": "body",
+  "displayOptions": {
+    "show": {
+      "sendBody": [true],
+      "method": ["POST", "PUT", "PATCH"]
+    }
+  }
+}
+```
+
+**Translation**: "body" field shows when:
+- sendBody = true AND
+- method = POST, PUT, or PATCH
+
+### Common Dependency Patterns
+
+#### Pattern 1: Boolean Toggle
+
+**Example**: HTTP Request sendBody
+```javascript
+// sendBody controls body visibility
+{
+  "sendBody": true   // → body field appears
+}
+```
+
+#### Pattern 2: Operation Switch
+
+**Example**: Slack resource/operation
+```javascript
+// Different operations → different fields
+{
+  "resource": "message",
+  "operation": "post"
+  // → Shows: channel, text, attachments, etc.
+}
+
+{
+  "resource": "message",
+  "operation": "update"
+  // → Shows: messageId, text (different fields!)
+}
+```
+
+#### Pattern 3: Type Selection
+
+**Example**: IF node conditions
+```javascript
+{
+  "type": "string",
+  "operation": "contains"
+  // → Shows: value1, value2
+}
+
+{
+  "type": "boolean",
+  "operation": "equals"
+  // → Shows: value1, value2, different operators
+}
+```
+
+### Finding Property Dependencies
+
+**Use get_node with search_properties mode**:
+```javascript
+get_node({
+  nodeType: "nodes-base.httpRequest",
+  mode: "search_properties",
+  propertyQuery: "body"
+});
+
+// Returns property paths matching "body" with descriptions
+```
+
+**Or use full detail for complete schema**:
+```javascript
+get_node({
+  nodeType: "nodes-base.httpRequest",
+  detail: "full"
+});
+
+// Returns complete schema with displayOptions rules
+```
+
+**Use this when**: Validation fails and you don't understand why field is missing/required
+
+---
+
+## Common Node Patterns
+
+### Pattern 1: Resource/Operation Nodes
+
+**Examples**: Slack, Google Sheets, Airtable
+
+**Structure**:
+```javascript
+{
+  "resource": "<entity>",      // What type of thing
+  "operation": "<action>",     // What to do with it
+  // ... operation-specific fields
+}
+```
+
+**How to configure**:
+1. Choose resource
+2. Choose operation
+3. Use get_node to see operation-specific requirements
+4. Configure required fields
+
+### Pattern 2: HTTP-Based Nodes
+
+**Examples**: HTTP Request, Webhook
+
+**Structure**:
+```javascript
+{
+  "method": "<HTTP_METHOD>",
+  "url": "<endpoint>",
+  "authentication": "<type>",
+  // ... method-specific fields
+}
+```
+
+**Dependencies**:
+- POST/PUT/PATCH → sendBody available
+- sendBody=true → body required
+- authentication != "none" → credentials required
+
+### Pattern 3: Database Nodes
+
+**Examples**: Postgres, MySQL, MongoDB
+
+**Structure**:
+```javascript
+{
+  "operation": "<query|insert|update|delete>",
+  // ... operation-specific fields
+}
+```
+
+**Dependencies**:
+- operation="executeQuery" → query required
+- operation="insert" → table + values required
+- operation="update" → table + values + where required
+
+### Pattern 4: Conditional Logic Nodes
+
+**Examples**: IF, Switch, Merge
+
+**Structure**:
+```javascript
+{
+  "conditions": {
+    "<type>": [
+      {
+        "operation": "<operator>",
+        "value1": "...",
+        "value2": "..."  // Only for binary operators
+      }
+    ]
+  }
+}
+```
+
+**Dependencies**:
+- Binary operators (equals, contains, etc.) → value1 + value2
+- Unary operators (isEmpty, isNotEmpty) → value1 only + singleValue: true
+
+---
+
+## Operation-Specific Configuration
+
+### Slack Node Examples
+
+#### Post Message
+```javascript
+{
+  "resource": "message",
+  "operation": "post",
+  "channel": "#general",      // Required
+  "text": "Hello!",           // Required
+  "attachments": [],          // Optional
+  "blocks": []                // Optional
+}
+```
+
+#### Update Message
+```javascript
+{
+  "resource": "message",
+  "operation": "update",
+  "messageId": "1234567890",  // Required (different from post!)
+  "text": "Updated!",         // Required
+  "channel": "#general"       // Optional (can be inferred)
+}
+```
+
+#### Create Channel
+```javascript
+{
+  "resource": "channel",
+  "operation": "create",
+  "name": "new-channel",      // Required
+  "isPrivate": false          // Optional
+  // Note: text NOT required for this operation
+}
+```
+
+### HTTP Request Node Examples
+
+#### GET Request
+```javascript
+{
+  "method": "GET",
+  "url": "https://api.example.com/users",
+  "authentication": "predefinedCredentialType",
+  "nodeCredentialType": "httpHeaderAuth",
+  "sendQuery": true,                    // Optional
+  "queryParameters": {                  // Shows when sendQuery=true
+    "parameters": [
+      {
+        "name": "limit",
+        "value": "100"
+      }
+    ]
+  }
+}
+```
+
+#### POST with JSON
+```javascript
+{
+  "method": "POST",
+  "url": "https://api.example.com/users",
+  "authentication": "none",
+  "sendBody": true,                     // Required for POST
+  "body": {                             // Required when sendBody=true
+    "contentType": "json",
+    "content": {
+      "name": "John Doe",
+      "email": "john@example.com"
+    }
+  }
+}
+```
+
+### IF Node Examples
+
+#### String Comparison (Binary)
+```javascript
+{
+  "conditions": {
+    "string": [
+      {
+        "value1": "={{$json.status}}",
+        "operation": "equals",
+        "value2": "active"              // Binary: needs value2
+      }
+    ]
+  }
+}
+```
+
+#### Empty Check (Unary)
+```javascript
+{
+  "conditions": {
+    "string": [
+      {
+        "value1": "={{$json.email}}",
+        "operation": "isEmpty",
+        // No value2 - unary operator
+        "singleValue": true             // Auto-added by sanitization
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Handling Conditional Requirements
+
+### Example: HTTP Request Body
+
+**Scenario**: body field required, but only sometimes
+
+**Rule**:
+```
+body is required when:
+  - sendBody = true AND
+  - method IN (POST, PUT, PATCH, DELETE)
+```
+
+**How to discover**:
+```javascript
+// Option 1: Read validation error
+validate_node({...});
+// Error: "body required when sendBody=true"
+
+// Option 2: Search for the property
+get_node({
+  nodeType: "nodes-base.httpRequest",
+  mode: "search_properties",
+  propertyQuery: "body"
+});
+// Shows: body property with displayOptions rules
+
+// Option 3: Try minimal config and iterate
+// Start without body, validation will tell you if needed
+```
+
+### Example: IF Node singleValue
+
+**Scenario**: singleValue property appears for unary operators
+
+**Rule**:
+```
+singleValue should be true when:
+  - operation IN (isEmpty, isNotEmpty, true, false)
+```
+
+**Good news**: Auto-sanitization fixes this!
+
+**Manual check**:
+```javascript
+get_node({
+  nodeType: "nodes-base.if",
+  detail: "full"
+});
+// Shows complete schema with operator-specific rules
+```
+
+---
+
+## Configuration Anti-Patterns
+
+### ❌ Don't: Over-configure Upfront
+
+**Bad**:
+```javascript
+// Adding every possible field
+{
+  "method": "GET",
+  "url": "...",
+  "sendQuery": false,
+  "sendHeaders": false,
+  "sendBody": false,
+  "timeout": 10000,
+  "ignoreResponseCode": false,
+  // ... 20 more optional fields
+}
+```
+
+**Good**:
+```javascript
+// Start minimal
+{
+  "method": "GET",
+  "url": "...",
+  "authentication": "none"
+}
+// Add fields only when needed
+```
+
+### ❌ Don't: Skip Validation
+
+**Bad**:
+```javascript
+// Configure and deploy without validating
+const config = {...};
+n8n_update_partial_workflow({...});  // YOLO
+```
+
+**Good**:
+```javascript
+// Validate before deploying
+const config = {...};
+const result = validate_node({...});
+if (result.valid) {
+  n8n_update_partial_workflow({...});
+}
+```
+
+### ❌ Don't: Ignore Operation Context
+
+**Bad**:
+```javascript
+// Same config for all Slack operations
+{
+  "resource": "message",
+  "operation": "post",
+  "channel": "#general",
+  "text": "..."
+}
+
+// Then switching operation without updating config
+{
+  "resource": "message",
+  "operation": "update",  // Changed
+  "channel": "#general",  // Wrong field for update!
+  "text": "..."
+}
+```
+
+**Good**:
+```javascript
+// Check requirements when changing operation
+get_node({
+  nodeType: "nodes-base.slack"
+});
+// See what update operation needs (messageId, not channel)
+```
+
+---
+
+## Best Practices
+
+### ✅ Do
+
+1. **Start with get_node (standard detail)**
+   - ~1-2K tokens response
+   - Covers 95% of configuration needs
+   - Default detail level
+
+2. **Validate iteratively**
+   - Configure → Validate → Fix → Repeat
+   - Average 2-3 iterations is normal
+   - Read validation errors carefully
+
+3. **Use search_properties mode when stuck**
+   - If field seems missing, search for it
+   - Understand what controls field visibility
+   - `get_node({mode: "search_properties", propertyQuery: "..."})`
+
+4. **Respect operation context**
+   - Different operations = different requirements
+   - Always check get_node when changing operation
+   - Don't assume configs are transferable
+
+5. **Trust auto-sanitization**
+   - Operator structure fixed automatically
+   - Don't manually add/remove singleValue
+   - IF/Switch metadata added on save
+
+### ❌ Don't
+
+1. **Jump to detail="full" immediately**
+   - Try standard detail first
+   - Only escalate if needed
+   - Full schema is 3-8K tokens
+
+2. **Configure blindly**
+   - Always validate before deploying
+   - Understand why fields are required
+   - Use search_properties for conditional fields
+
+3. **Copy configs without understanding**
+   - Different operations need different fields
+   - Validate after copying
+   - Adjust for new context
+
+4. **Manually fix auto-sanitization issues**
+   - Let auto-sanitization handle operator structure
+   - Focus on business logic
+   - Save and let system fix structure
+
+---
+
+## Detailed References
+
+For comprehensive guides on specific topics:
+
+- **[DEPENDENCIES.md](DEPENDENCIES.md)** - Deep dive into property dependencies and displayOptions
+- **[OPERATION_PATTERNS.md](OPERATION_PATTERNS.md)** - Common configuration patterns by node type
+
+---
+
+## Summary
+
+**Configuration Strategy**:
+1. Start with `get_node` (standard detail is default)
+2. Configure required fields for operation
+3. Validate configuration
+4. Search properties if stuck
+5. Iterate until valid (avg 2-3 cycles)
+6. Deploy with confidence
+
+**Key Principles**:
+- **Operation-aware**: Different operations = different requirements
+- **Progressive disclosure**: Start minimal, add as needed
+- **Dependency-aware**: Understand field visibility rules
+- **Validation-driven**: Let validation guide configuration
+
+**Related Skills**:
+- **n8n MCP Tools Expert** - How to use discovery tools correctly
+- **n8n Validation Expert** - Interpret validation errors
+- **n8n Expression Syntax** - Configure expression fields
+- **n8n Workflow Patterns** - Apply patterns with proper configuration

skills/nanobanana-ppt-skills/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: nanobanana-ppt-skills
+description: "AI-powered PPT generation with document analysis and styled images"
+source: "https://github.com/op7418/NanoBanana-PPT-Skills"
+risk: safe
+---
+
+# Nanobanana Ppt Skills
+
+## Overview
+
+AI-powered PPT generation with document analysis and styled images
+
+## When to Use This Skill
+
+Use this skill when you need to work with ai-powered ppt generation with document analysis and styled images.
+
+## Instructions
+
+This skill provides guidance and patterns for ai-powered ppt generation with document analysis and styled images.
+
+For more information, see the [source repository](https://github.com/op7418/NanoBanana-PPT-Skills).

skills/observe-whatsapp/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: observe-whatsapp
+description: "Observe and troubleshoot WhatsApp in Kapso: debug message delivery, inspect webhook deliveries/retries, triage API errors, and run health checks. Use when investigating production issues, message failures, or webhook delivery problems."
+source: "https://github.com/gokapso/agent-skills/tree/master/skills/observe-whatsapp"
+risk: safe
+---
+
+# Observe WhatsApp
+
+## When to use
+
+Use this skill for operational diagnostics: message delivery investigation, webhook delivery debugging, error triage, and WhatsApp health checks.
+
+## Setup
+
+Env vars:
+- `KAPSO_API_BASE_URL` (host only, no `/platform/v1`)
+- `KAPSO_API_KEY`
+
+## How to
+
+### Investigate message delivery
+
+1. List messages: `node scripts/messages.js --phone-number-id <id>`
+2. Inspect message: `node scripts/message-details.js --message-id <id>`
+3. Find conversation: `node scripts/lookup-conversation.js --phone-number <e164>`
+
+### Triage errors
+
+1. Message errors: `node scripts/errors.js`
+2. API logs: `node scripts/api-logs.js`
+3. Webhook deliveries: `node scripts/webhook-deliveries.js`
+
+### Run health checks
+
+1. Project overview: `node scripts/overview.js`
+2. Phone number health: `node scripts/whatsapp-health.js --phone-number-id <id>`
+
+## Scripts
+
+### Messages
+
+| Script | Purpose |
+|--------|---------|
+| `messages.js` | List messages |
+| `message-details.js` | Get message details |
+| `lookup-conversation.js` | Find conversation by phone or ID |
+
+### Errors and logs
+
+| Script | Purpose |
+|--------|---------|
+| `errors.js` | List message errors |
+| `api-logs.js` | List external API logs |
+| `webhook-deliveries.js` | List webhook delivery attempts |
+
+### Health
+
+| Script | Purpose |
+|--------|---------|
+| `overview.js` | Project overview |
+| `whatsapp-health.js` | Phone number health check |
+
+### OpenAPI
+
+| Script | Purpose |
+|--------|---------|
+| `openapi-explore.mjs` | Explore OpenAPI (search/op/schema/where) |
+
+Install deps (once):
+```bash
+npm i
+```
+
+Examples:
+```bash
+node scripts/openapi-explore.mjs --spec platform search "webhook deliveries"
+node scripts/openapi-explore.mjs --spec platform op listWebhookDeliveries
+node scripts/openapi-explore.mjs --spec platform schema WebhookDelivery
+```
+
+## Notes
+
+- For webhook setup (create/update/delete, signature verification, event types), use `integrate-whatsapp`.
+
+## References
+
+- [references/message-debugging-reference.md](references/message-debugging-reference.md) - Message debugging guide
+- [references/triage-reference.md](references/triage-reference.md) - Error triage guide
+- [references/health-reference.md](references/health-reference.md) - Health check guide
+
+## Related skills
+
+- `integrate-whatsapp` - Onboarding, webhooks, messaging, templates, flows
+- `automate-whatsapp` - Workflows, agents, and automations
+
+<!-- FILEMAP:BEGIN -->
+```text
+[observe-whatsapp file map]|root: .
+|.:{package.json,SKILL.md}
+|assets:{health-example.json,message-debugging-example.json,triage-example.json}
+|references:{health-reference.md,message-debugging-reference.md,triage-reference.md}
+|scripts:{api-logs.js,errors.js,lookup-conversation.js,message-details.js,messages.js,openapi-explore.mjs,overview.js,webhook-deliveries.js,whatsapp-health.js}
+|scripts/lib/messages:{args.js,kapso-api.js}
+|scripts/lib/status:{args.js,kapso-api.js}
+|scripts/lib/triage:{args.js,kapso-api.js}
+```
+<!-- FILEMAP:END -->
+

skills/pypict-skill/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: pypict-skill
+description: "Pairwise test generation"
+source: "https://github.com/omkamal/pypict-claude-skill/blob/main/SKILL.md"
+risk: safe
+---
+
+# Pypict Skill
+
+## Overview
+
+Pairwise test generation
+
+## When to Use This Skill
+
+Use this skill when you need to work with pairwise test generation.
+
+## Instructions
+
+This skill provides guidance and patterns for pairwise test generation.
+
+For more information, see the [source repository](https://github.com/omkamal/pypict-claude-skill/blob/main/SKILL.md).

skills/radix-ui-design-system/SKILL.md

@@ -0,0 +1,847 @@
+---
+name: radix-ui-design-system
+description: Build accessible design systems with Radix UI primitives. Headless component customization, theming strategies, and compound component patterns for production-grade UI libraries.
+risk: safe
+source: self
+---
+
+# Radix UI Design System
+
+Build production-ready, accessible design systems using Radix UI primitives with full customization control and zero style opinions.
+
+## Overview
+
+Radix UI provides unstyled, accessible components (primitives) that you can customize to match any design system. This skill guides you through building scalable component libraries with Radix UI, focusing on accessibility-first design, theming architecture, and composable patterns.
+
+**Key Strengths:**
+- **Headless by design**: Full styling control without fighting defaults
+- **Accessibility built-in**: WAI-ARIA compliant, keyboard navigation, screen reader support
+- **Composable primitives**: Build complex components from simple building blocks
+- **Framework agnostic**: Works with React, but styles work anywhere
+
+## When to Use This Skill
+
+- Creating a custom design system from scratch
+- Building accessible UI component libraries
+- Implementing complex interactive components (Dialog, Dropdown, Tabs, etc.)
+- Migrating from styled component libraries to unstyled primitives
+- Setting up theming systems with CSS variables or Tailwind
+- Need full control over component behavior and styling
+- Building applications requiring WCAG 2.1 AA/AAA compliance
+
+## Do not use this skill when
+
+- You need pre-styled components out of the box (use shadcn/ui, Mantine, etc.)
+- Building simple static pages without interactivity
+- The project doesn't use React 16.8+ (Radix requires hooks)
+- You need components for frameworks other than React
+
+---
+
+## Core Principles
+
+### 1. Accessibility First
+
+Every Radix primitive is built with accessibility as the foundation:
+
+- **Keyboard Navigation**: Full keyboard support (Tab, Arrow keys, Enter, Escape)
+- **Screen Readers**: Proper ARIA attributes and live regions
+- **Focus Management**: Automatic focus trapping and restoration
+- **Disabled States**: Proper handling of disabled and aria-disabled
+
+**Rule**: Never override accessibility features. Enhance, don't replace.
+
+### 2. Headless Architecture
+
+Radix provides **behavior**, you provide **appearance**:
+
+```tsx
+// ❌ Don't fight pre-styled components
+<Button className="override-everything" />
+
+// ✅ Radix gives you behavior, you add styling
+<Dialog.Root>
+  <Dialog.Trigger className="your-button-styles" />
+  <Dialog.Content className="your-modal-styles" />
+</Dialog.Root>
+```
+
+### 3. Composition Over Configuration
+
+Build complex components from simple primitives:
+
+```tsx
+// Primitive components compose naturally
+<Tabs.Root>
+  <Tabs.List>
+    <Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
+    <Tabs.Trigger value="tab2">Tab 2</Tabs.Trigger>
+  </Tabs.List>
+  <Tabs.Content value="tab1">Content 1</Tabs.Content>
+  <Tabs.Content value="tab2">Content 2</Tabs.Content>
+</Tabs.Root>
+```
+
+---
+
+## Getting Started
+
+### Installation
+
+```bash
+# Install individual primitives (recommended)
+npm install @radix-ui/react-dialog @radix-ui/react-dropdown-menu
+
+# Or install multiple at once
+npm install @radix-ui/react-{dialog,dropdown-menu,tabs,tooltip}
+
+# For styling (optional but common)
+npm install clsx tailwind-merge class-variance-authority
+```
+
+### Basic Component Pattern
+
+Every Radix component follows this pattern:
+
+```tsx
+import * as Dialog from '@radix-ui/react-dialog';
+
+export function MyDialog() {
+  return (
+    <Dialog.Root>
+      {/* Trigger the dialog */}
+      <Dialog.Trigger asChild>
+        <button className="trigger-styles">Open</button>
+      </Dialog.Trigger>
+
+      {/* Portal renders outside DOM hierarchy */}
+      <Dialog.Portal>
+        {/* Overlay (backdrop) */}
+        <Dialog.Overlay className="overlay-styles" />
+        
+        {/* Content (modal) */}
+        <Dialog.Content className="content-styles">
+          <Dialog.Title>Title</Dialog.Title>
+          <Dialog.Description>Description</Dialog.Description>
+          
+          {/* Your content here */}
+          
+          <Dialog.Close asChild>
+            <button>Close</button>
+          </Dialog.Close>
+        </Dialog.Content>
+      </Dialog.Portal>
+    </Dialog.Root>
+  );
+}
+```
+
+---
+
+## Theming Strategies
+
+### Strategy 1: CSS Variables (Framework-Agnostic)
+
+**Best for**: Maximum portability, SSR-friendly
+
+```css
+/* globals.css */
+:root {
+  --color-primary: 220 90% 56%;
+  --color-surface: 0 0% 100%;
+  --radius-base: 0.5rem;
+  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1);
+}
+
+[data-theme="dark"] {
+  --color-primary: 220 90% 66%;
+  --color-surface: 222 47% 11%;
+}
+```
+
+```tsx
+// Component.tsx
+<Dialog.Content 
+  className="
+    bg-[hsl(var(--color-surface))]
+    rounded-[var(--radius-base)]
+    shadow-[var(--shadow-lg)]
+  "
+/>
+```
+
+### Strategy 2: Tailwind + CVA (Class Variance Authority)
+
+**Best for**: Tailwind projects, variant-heavy components
+
+```tsx
+// button.tsx
+import { cva, type VariantProps } from 'class-variance-authority';
+import { cn } from '@/lib/utils';
+
+const buttonVariants = cva(
+  // Base styles
+  "inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none disabled:pointer-events-none disabled:opacity-50",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground hover:bg-primary/90",
+        destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
+        outline: "border border-input bg-background hover:bg-accent",
+        ghost: "hover:bg-accent hover:text-accent-foreground",
+      },
+      size: {
+        default: "h-10 px-4 py-2",
+        sm: "h-9 rounded-md px-3",
+        lg: "h-11 rounded-md px-8",
+        icon: "h-10 w-10",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+);
+
+interface ButtonProps extends VariantProps<typeof buttonVariants> {
+  children: React.ReactNode;
+}
+
+export function Button({ variant, size, children }: ButtonProps) {
+  return (
+    <button className={cn(buttonVariants({ variant, size }))}>
+      {children}
+    </button>
+  );
+}
+```
+
+### Strategy 3: Stitches (CSS-in-JS)
+
+**Best for**: Runtime theming, scoped styles
+
+```tsx
+import { styled } from '@stitches/react';
+import * as Dialog from '@radix-ui/react-dialog';
+
+const StyledContent = styled(Dialog.Content, {
+  backgroundColor: '$surface',
+  borderRadius: '$md',
+  padding: '$6',
+  
+  variants: {
+    size: {
+      small: { width: '300px' },
+      medium: { width: '500px' },
+      large: { width: '700px' },
+    },
+  },
+  
+  defaultVariants: {
+    size: 'medium',
+  },
+});
+```
+
+---
+
+## Component Patterns
+
+### Pattern 1: Compound Components with Context
+
+**Use case**: Share state between primitive parts
+
+```tsx
+// Select.tsx
+import * as Select from '@radix-ui/react-select';
+import { CheckIcon, ChevronDownIcon } from '@radix-ui/react-icons';
+
+export function CustomSelect({ items, placeholder, onValueChange }) {
+  return (
+    <Select.Root onValueChange={onValueChange}>
+      <Select.Trigger className="select-trigger">
+        <Select.Value placeholder={placeholder} />
+        <Select.Icon>
+          <ChevronDownIcon />
+        </Select.Icon>
+      </Select.Trigger>
+
+      <Select.Portal>
+        <Select.Content className="select-content">
+          <Select.Viewport>
+            {items.map((item) => (
+              <Select.Item 
+                key={item.value} 
+                value={item.value}
+                className="select-item"
+              >
+                <Select.ItemText>{item.label}</Select.ItemText>
+                <Select.ItemIndicator>
+                  <CheckIcon />
+                </Select.ItemIndicator>
+              </Select.Item>
+            ))}
+          </Select.Viewport>
+        </Select.Content>
+      </Select.Portal>
+    </Select.Root>
+  );
+}
+```
+
+### Pattern 2: Polymorphic Components with `asChild`
+
+**Use case**: Render as different elements without losing behavior
+
+```tsx
+// ✅ Render as Next.js Link but keep Radix behavior
+<Dialog.Trigger asChild>
+  <Link href="/settings">Open Settings</Link>
+</Dialog.Trigger>
+
+// ✅ Render as custom component
+<DropdownMenu.Item asChild>
+  <YourCustomButton icon={<Icon />}>Action</YourCustomButton>
+</DropdownMenu.Item>
+```
+
+**Why `asChild` matters**: Prevents nested button/link issues in accessibility tree.
+
+### Pattern 3: Controlled vs Uncontrolled
+
+```tsx
+// Uncontrolled (Radix manages state)
+<Tabs.Root defaultValue="tab1">
+  <Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
+</Tabs.Root>
+
+// Controlled (You manage state)
+const [activeTab, setActiveTab] = useState('tab1');
+
+<Tabs.Root value={activeTab} onValueChange={setActiveTab}>
+  <Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
+</Tabs.Root>
+```
+
+**Rule**: Use controlled when you need to sync with external state (URL, Redux, etc.).
+
+### Pattern 4: Animation with Framer Motion
+
+```tsx
+import * as Dialog from '@radix-ui/react-dialog';
+import { motion, AnimatePresence } from 'framer-motion';
+
+export function AnimatedDialog({ open, onOpenChange }) {
+  return (
+    <Dialog.Root open={open} onOpenChange={onOpenChange}>
+      <Dialog.Portal forceMount>
+        <AnimatePresence>
+          {open && (
+            <>
+              <Dialog.Overlay asChild>
+                <motion.div
+                  initial={{ opacity: 0 }}
+                  animate={{ opacity: 1 }}
+                  exit={{ opacity: 0 }}
+                  className="dialog-overlay"
+                />
+              </Dialog.Overlay>
+              
+              <Dialog.Content asChild>
+                <motion.div
+                  initial={{ opacity: 0, scale: 0.95 }}
+                  animate={{ opacity: 1, scale: 1 }}
+                  exit={{ opacity: 0, scale: 0.95 }}
+                  className="dialog-content"
+                >
+                  {/* Content */}
+                </motion.div>
+              </Dialog.Content>
+            </>
+          )}
+        </AnimatePresence>
+      </Dialog.Portal>
+    </Dialog.Root>
+  );
+}
+```
+
+---
+
+## Common Primitives Reference
+
+### Dialog (Modal)
+
+```tsx
+<Dialog.Root> {/* State container */}
+  <Dialog.Trigger /> {/* Opens dialog */}
+  <Dialog.Portal> {/* Renders in portal */}
+    <Dialog.Overlay /> {/* Backdrop */}
+    <Dialog.Content> {/* Modal content */}
+      <Dialog.Title /> {/* Required for a11y */}
+      <Dialog.Description /> {/* Required for a11y */}
+      <Dialog.Close /> {/* Closes dialog */}
+    </Dialog.Content>
+  </Dialog.Portal>
+</Dialog.Root>
+```
+
+### Dropdown Menu
+
+```tsx
+<DropdownMenu.Root>
+  <DropdownMenu.Trigger />
+  <DropdownMenu.Portal>
+    <DropdownMenu.Content>
+      <DropdownMenu.Item />
+      <DropdownMenu.Separator />
+      <DropdownMenu.CheckboxItem />
+      <DropdownMenu.RadioGroup>
+        <DropdownMenu.RadioItem />
+      </DropdownMenu.RadioGroup>
+      <DropdownMenu.Sub> {/* Nested menus */}
+        <DropdownMenu.SubTrigger />
+        <DropdownMenu.SubContent />
+      </DropdownMenu.Sub>
+    </DropdownMenu.Content>
+  </DropdownMenu.Portal>
+</DropdownMenu.Root>
+```
+
+### Tabs
+
+```tsx
+<Tabs.Root defaultValue="tab1">
+  <Tabs.List>
+    <Tabs.Trigger value="tab1" />
+    <Tabs.Trigger value="tab2" />
+  </Tabs.List>
+  <Tabs.Content value="tab1" />
+  <Tabs.Content value="tab2" />
+</Tabs.Root>
+```
+
+### Tooltip
+
+```tsx
+<Tooltip.Provider delayDuration={200}>
+  <Tooltip.Root>
+    <Tooltip.Trigger />
+    <Tooltip.Portal>
+      <Tooltip.Content side="top" align="center">
+        Tooltip text
+        <Tooltip.Arrow />
+      </Tooltip.Content>
+    </Tooltip.Portal>
+  </Tooltip.Root>
+</Tooltip.Provider>
+```
+
+### Popover
+
+```tsx
+<Popover.Root>
+  <Popover.Trigger />
+  <Popover.Portal>
+    <Popover.Content side="bottom" align="start">
+      Content
+      <Popover.Arrow />
+      <Popover.Close />
+    </Popover.Content>
+  </Popover.Portal>
+</Popover.Root>
+```
+
+---
+
+## Accessibility Checklist
+
+### Every Component Must Have:
+
+- [ ] **Focus Management**: Visible focus indicators on all interactive elements
+- [ ] **Keyboard Navigation**: Full keyboard support (Tab, Arrows, Enter, Esc)
+- [ ] **ARIA Labels**: Meaningful labels for screen readers
+- [ ] **Color Contrast**: WCAG AA minimum (4.5:1 for text, 3:1 for UI)
+- [ ] **Error States**: Clear error messages with `aria-invalid` and `aria-describedby`
+- [ ] **Loading States**: Proper `aria-busy` during async operations
+
+### Dialog-Specific:
+- [ ] `Dialog.Title` is present (required for screen readers)
+- [ ] `Dialog.Description` provides context
+- [ ] Focus trapped inside modal when open
+- [ ] Escape key closes dialog
+- [ ] Focus returns to trigger on close
+
+### Dropdown-Specific:
+- [ ] Arrow keys navigate items
+- [ ] Type-ahead search works
+- [ ] First/last item wrapping behavior
+- [ ] Selected state indicated visually and with ARIA
+
+---
+
+## Best Practices
+
+### ✅ Do This
+
+1. **Always use `asChild` to avoid wrapper divs**
+   ```tsx
+   <Dialog.Trigger asChild>
+     <button>Open</button>
+   </Dialog.Trigger>
+   ```
+
+2. **Provide semantic HTML**
+   ```tsx
+   <Dialog.Content asChild>
+     <article role="dialog" aria-labelledby="title">
+       {/* content */}
+     </article>
+   </Dialog.Content>
+   ```
+
+3. **Use CSS variables for theming**
+   ```css
+   .dialog-content {
+     background: hsl(var(--surface));
+     color: hsl(var(--on-surface));
+   }
+   ```
+
+4. **Compose primitives for complex components**
+   ```tsx
+   function CommandPalette() {
+     return (
+       <Dialog.Root>
+         <Dialog.Content>
+           <Combobox /> {/* Radix Combobox inside Dialog */}
+         </Dialog.Content>
+       </Dialog.Root>
+     );
+   }
+   ```
+
+### ❌ Don't Do This
+
+1. **Don't skip accessibility parts**
+   ```tsx
+   // ❌ Missing Title and Description
+   <Dialog.Content>
+     <div>Content</div>
+   </Dialog.Content>
+   ```
+
+2. **Don't fight the primitives**
+   ```tsx
+   // ❌ Overriding internal behavior
+   <Dialog.Content onClick={(e) => e.stopPropagation()}>
+   ```
+
+3. **Don't mix controlled and uncontrolled**
+   ```tsx
+   // ❌ Inconsistent state management
+   <Tabs.Root defaultValue="tab1" value={activeTab}>
+   ```
+
+4. **Don't ignore keyboard navigation**
+   ```tsx
+   // ❌ Disabling keyboard behavior
+   <DropdownMenu.Item onKeyDown={(e) => e.preventDefault()}>
+   ```
+
+---
+
+## Real-World Examples
+
+### Example 1: Command Palette (Combo Dialog)
+
+```tsx
+import * as Dialog from '@radix-ui/react-dialog';
+import { Command } from 'cmdk';
+
+export function CommandPalette() {
+  const [open, setOpen] = useState(false);
+
+  useEffect(() => {
+    const down = (e: KeyboardEvent) => {
+      if (e.key === 'k' && (e.metaKey || e.ctrlKey)) {
+        e.preventDefault();
+        setOpen((open) => !open);
+      }
+    };
+    document.addEventListener('keydown', down);
+    return () => document.removeEventListener('keydown', down);
+  }, []);
+
+  return (
+    <Dialog.Root open={open} onOpenChange={setOpen}>
+      <Dialog.Portal>
+        <Dialog.Overlay className="fixed inset-0 bg-black/50" />
+        <Dialog.Content className="fixed left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2">
+          <Command>
+            <Command.Input placeholder="Type a command..." />
+            <Command.List>
+              <Command.Empty>No results found.</Command.Empty>
+              <Command.Group heading="Suggestions">
+                <Command.Item>Calendar</Command.Item>
+                <Command.Item>Search Emoji</Command.Item>
+              </Command.Group>
+            </Command.List>
+          </Command>
+        </Dialog.Content>
+      </Dialog.Portal>
+    </Dialog.Root>
+  );
+}
+```
+
+### Example 2: Dropdown Menu with Icons
+
+```tsx
+import * as DropdownMenu from '@radix-ui/react-dropdown-menu';
+import { DotsHorizontalIcon } from '@radix-ui/react-icons';
+
+export function ActionsMenu() {
+  return (
+    <DropdownMenu.Root>
+      <DropdownMenu.Trigger asChild>
+        <button className="icon-button" aria-label="Actions">
+          <DotsHorizontalIcon />
+        </button>
+      </DropdownMenu.Trigger>
+
+      <DropdownMenu.Portal>
+        <DropdownMenu.Content className="dropdown-content" align="end">
+          <DropdownMenu.Item className="dropdown-item">
+            Edit
+          </DropdownMenu.Item>
+          <DropdownMenu.Item className="dropdown-item">
+            Duplicate
+          </DropdownMenu.Item>
+          <DropdownMenu.Separator className="dropdown-separator" />
+          <DropdownMenu.Item className="dropdown-item text-red-500">
+            Delete
+          </DropdownMenu.Item>
+        </DropdownMenu.Content>
+      </DropdownMenu.Portal>
+    </DropdownMenu.Root>
+  );
+}
+```
+
+### Example 3: Form with Radix Select + React Hook Form
+
+```tsx
+import * as Select from '@radix-ui/react-select';
+import { useForm, Controller } from 'react-hook-form';
+
+interface FormData {
+  country: string;
+}
+
+export function CountryForm() {
+  const { control, handleSubmit } = useForm<FormData>();
+
+  return (
+    <form onSubmit={handleSubmit((data) => console.log(data))}>
+      <Controller
+        name="country"
+        control={control}
+        render={({ field }) => (
+          <Select.Root onValueChange={field.onChange} value={field.value}>
+            <Select.Trigger className="select-trigger">
+              <Select.Value placeholder="Select a country" />
+              <Select.Icon />
+            </Select.Trigger>
+            
+            <Select.Portal>
+              <Select.Content className="select-content">
+                <Select.Viewport>
+                  <Select.Item value="us">United States</Select.Item>
+                  <Select.Item value="ca">Canada</Select.Item>
+                  <Select.Item value="uk">United Kingdom</Select.Item>
+                </Select.Viewport>
+              </Select.Content>
+            </Select.Portal>
+          </Select.Root>
+        )}
+      />
+      <button type="submit">Submit</button>
+    </form>
+  );
+}
+```
+
+---
+
+## Troubleshooting
+
+### Problem: Dialog doesn't close on Escape key
+
+**Cause**: `onEscapeKeyDown` event prevented or `open` state not synced
+
+**Solution**:
+```tsx
+<Dialog.Root open={open} onOpenChange={setOpen}>
+  {/* Don't prevent default on escape */}
+</Dialog.Root>
+```
+
+### Problem: Dropdown menu positioning is off
+
+**Cause**: Parent container has `overflow: hidden` or transform
+
+**Solution**:
+```tsx
+// Use Portal to render outside overflow container
+<DropdownMenu.Portal>
+  <DropdownMenu.Content />
+</DropdownMenu.Portal>
+```
+
+### Problem: Animations don't work
+
+**Cause**: Portal content unmounts immediately
+
+**Solution**:
+```tsx
+// Use forceMount + AnimatePresence
+<Dialog.Portal forceMount>
+  <AnimatePresence>
+    {open && <Dialog.Content />}
+  </AnimatePresence>
+</Dialog.Portal>
+```
+
+### Problem: TypeScript errors with `asChild`
+
+**Cause**: Type inference issues with polymorphic components
+
+**Solution**:
+```tsx
+// Explicitly type your component
+<Dialog.Trigger asChild>
+  <button type="button">Open</button>
+</Dialog.Trigger>
+```
+
+---
+
+## Performance Optimization
+
+### 1. Code Splitting
+
+```tsx
+// Lazy load heavy primitives
+const Dialog = lazy(() => import('@radix-ui/react-dialog'));
+const DropdownMenu = lazy(() => import('@radix-ui/react-dropdown-menu'));
+```
+
+### 2. Portal Container Reuse
+
+```tsx
+// Create portal container once
+<Tooltip.Provider>
+  {/* All tooltips share portal container */}
+  <Tooltip.Root>...</Tooltip.Root>
+  <Tooltip.Root>...</Tooltip.Root>
+</Tooltip.Provider>
+```
+
+### 3. Memoization
+
+```tsx
+// Memoize expensive render functions
+const SelectItems = memo(({ items }) => (
+  items.map((item) => <Select.Item key={item.value} value={item.value} />)
+));
+```
+
+---
+
+## Integration with Popular Tools
+
+### shadcn/ui (Built on Radix)
+
+shadcn/ui is a collection of copy-paste components built with Radix + Tailwind.
+
+```bash
+npx shadcn-ui@latest init
+npx shadcn-ui@latest add dialog
+```
+
+**When to use shadcn vs raw Radix**:
+- Use shadcn: Quick prototyping, standard designs
+- Use raw Radix: Full customization, unique designs
+
+### Radix Themes (Official Styled System)
+
+```tsx
+import { Theme, Button, Dialog } from '@radix-ui/themes';
+
+function App() {
+  return (
+    <Theme accentColor="crimson" grayColor="sand">
+      <Button>Click me</Button>
+    </Theme>
+  );
+}
+```
+
+---
+
+## Related Skills
+
+- `@tailwind-design-system` - Tailwind + Radix integration patterns
+- `@react-patterns` - React composition patterns
+- `@frontend-design` - Overall frontend architecture
+- `@accessibility-compliance` - WCAG compliance testing
+
+---
+
+## Resources
+
+### Official Documentation
+- [Radix UI Docs](https://www.radix-ui.com/primitives)
+- [Radix Colors](https://www.radix-ui.com/colors) - Accessible color system
+- [Radix Icons](https://www.radix-ui.com/icons) - Icon library
+
+### Community Resources
+- [shadcn/ui](https://ui.shadcn.com) - Component collection
+- [Radix UI Discord](https://discord.com/invite/7Xb99uG) - Community support
+- [CVA Documentation](https://cva.style/docs) - Variant management
+
+### Examples
+- [Radix Playground](https://www.radix-ui.com/primitives/docs/overview/introduction#try-it-out)
+- [shadcn/ui Source](https://github.com/shadcn-ui/ui) - Production examples
+
+---
+
+## Quick Reference
+
+### Installation
+```bash
+npm install @radix-ui/react-{primitive-name}
+```
+
+### Basic Pattern
+```tsx
+<Primitive.Root>
+  <Primitive.Trigger />
+  <Primitive.Portal>
+    <Primitive.Content />
+  </Primitive.Portal>
+</Primitive.Root>
+```
+
+### Key Props
+- `asChild` - Render as child element
+- `defaultValue` - Uncontrolled default
+- `value` / `onValueChange` - Controlled state
+- `open` / `onOpenChange` - Open state
+- `side` / `align` - Positioning
+
+---
+
+**Remember**: Radix gives you **behavior**, you give it **beauty**. Accessibility is built-in, customization is unlimited.

skills/radix-ui-design-system/examples/README.md

@@ -0,0 +1,63 @@
+# Radix UI Design System - Skill Examples
+
+This folder contains practical examples demonstrating how to use Radix UI primitives to build accessible, customizable components.
+
+## Examples
+
+### `dialog-example.tsx`
+
+Demonstrates Dialog (Modal) component patterns:
+- **BasicDialog**: Standard modal with form
+- **ControlledDialog**: Externally controlled modal state
+
+**Key Concepts**:
+- Portal rendering outside DOM hierarchy
+- Overlay (backdrop) handling
+- Accessibility requirements (Title, Description)
+- Custom styling with CSS
+
+### `dropdown-example.tsx`
+
+Complete dropdown menu implementation:
+- **CompleteDropdown**: Full-featured menu with all Radix primitives
+  - Regular items
+  - Separators and labels
+  - Checkbox items
+  - Radio groups
+  - Sub-menus
+- **ActionsMenu**: Simple actions menu for data tables/cards
+
+**Key Concepts**:
+- Compound component architecture
+- Keyboard navigation
+- Item indicators (checkboxes, radio buttons)
+- Nested sub-menus
+
+## Usage
+
+```tsx
+import { BasicDialog } from './examples/dialog-example';
+import { CompleteDropdown } from './examples/dropdown-example';
+
+function App() {
+  return (
+    <>
+      <BasicDialog />
+      <CompleteDropdown />
+    </>
+  );
+}
+```
+
+## Styling
+
+These examples use CSS classes. You can:
+1. Copy the CSS from each file
+2. Replace with Tailwind classes
+3. Use CSS-in-JS (Stitches, Emotion, etc.)
+
+## Learn More
+
+- [Main SKILL.md](../SKILL.md) - Complete guide
+- [Component Template](../templates/component-template.tsx) - Boilerplate
+- [Radix UI Docs](https://www.radix-ui.com/primitives)

skills/radix-ui-design-system/examples/dialog-example.tsx

@@ -0,0 +1,128 @@
+import * as Dialog from '@radix-ui/react-dialog';
+import { Cross2Icon } from '@radix-ui/react-icons';
+import './dialog.css';
+
+/**
+ * Example: Basic Dialog Component
+ * 
+ * Demonstrates:
+ * - Compound component pattern
+ * - Portal rendering
+ * - Accessibility features (Title, Description)
+ * - Custom styling with CSS
+ */
+export function BasicDialog() {
+  return (
+    <Dialog.Root>
+      <Dialog.Trigger asChild>
+        <button className="button-primary">
+          Open Dialog
+        </button>
+      </Dialog.Trigger>
+
+      <Dialog.Portal>
+        {/* Overlay (backdrop) */}
+        <Dialog.Overlay className="dialog-overlay" />
+        
+        {/* Content (modal) */}
+        <Dialog.Content className="dialog-content">
+          {/* Title - Required for accessibility */}
+          <Dialog.Title className="dialog-title">
+            Edit Profile
+          </Dialog.Title>
+
+          {/* Description - Recommended for accessibility */}
+          <Dialog.Description className="dialog-description">
+            Make changes to your profile here. Click save when you're done.
+          </Dialog.Description>
+
+          {/* Form Content */}
+          <form className="dialog-form">
+            <fieldset className="fieldset">
+              <label className="label" htmlFor="name">
+                Name
+              </label>
+              <input
+                className="input"
+                id="name"
+                defaultValue="John Doe"
+              />
+            </fieldset>
+
+            <fieldset className="fieldset">
+              <label className="label" htmlFor="email">
+                Email
+              </label>
+              <input
+                className="input"
+                id="email"
+                type="email"
+                defaultValue="john@example.com"
+              />
+            </fieldset>
+
+            <div className="dialog-actions">
+              <Dialog.Close asChild>
+                <button className="button-secondary" type="button">
+                  Cancel
+                </button>
+              </Dialog.Close>
+              <button className="button-primary" type="submit">
+                Save Changes
+              </button>
+            </div>
+          </form>
+
+          {/* Close button */}
+          <Dialog.Close asChild>
+            <button className="icon-button" aria-label="Close">
+              <Cross2Icon />
+            </button>
+          </Dialog.Close>
+        </Dialog.Content>
+      </Dialog.Portal>
+    </Dialog.Root>
+  );
+}
+
+/**
+ * Example: Controlled Dialog
+ * 
+ * Use when you need to:
+ * - Sync dialog state with external state
+ * - Programmatically open/close dialog
+ * - Track dialog open state
+ */
+export function ControlledDialog() {
+  const [open, setOpen] = React.useState(false);
+
+  const handleSave = () => {
+    // Your save logic here
+    console.log('Saving...');
+    setOpen(false); // Close after save
+  };
+
+  return (
+    <Dialog.Root open={open} onOpenChange={setOpen}>
+      <Dialog.Trigger asChild>
+        <button className="button-primary">
+          Open Controlled Dialog
+        </button>
+      </Dialog.Trigger>
+
+      <Dialog.Portal>
+        <Dialog.Overlay className="dialog-overlay" />
+        <Dialog.Content className="dialog-content">
+          <Dialog.Title>Controlled Dialog</Dialog.Title>
+          <Dialog.Description>
+            This dialog's state is managed externally.
+          </Dialog.Description>
+
+          <p>Dialog is {open ? 'open' : 'closed'}</p>
+
+          <button onClick={handleSave}>Save and Close</button>
+        </Dialog.Content>
+      </Dialog.Portal>
+    </Dialog.Root>
+  );
+}

skills/radix-ui-design-system/examples/dropdown-example.tsx

@@ -0,0 +1,162 @@
+import * as DropdownMenu from '@radix-ui/react-dropdown-menu';
+import {
+  HamburgerMenuIcon,
+  DotFilledIcon,
+  CheckIcon,
+  ChevronRightIcon,
+} from '@radix-ui/react-icons';
+import './dropdown.css';
+
+/**
+ * Example: Complete Dropdown Menu
+ * 
+ * Features:
+ * - Items, separators, labels
+ * - Checkbox items
+ * - Radio group items
+ * - Sub-menus
+ * - Keyboard navigation
+ */
+export function CompleteDropdown() {
+  const [bookmarksChecked, setBookmarksChecked] = React.useState(true);
+  const [urlsChecked, setUrlsChecked] = React.useState(false);
+  const [person, setPerson] = React.useState('pedro');
+
+  return (
+    <DropdownMenu.Root>
+      <DropdownMenu.Trigger asChild>
+        <button className="icon-button" aria-label="Customise options">
+          <HamburgerMenuIcon />
+        </button>
+      </DropdownMenu.Trigger>
+
+      <DropdownMenu.Portal>
+        <DropdownMenu.Content className="dropdown-content" sideOffset={5}>
+          {/* Regular items */}
+          <DropdownMenu.Item className="dropdown-item">
+            New Tab <div className="right-slot">⌘+T</div>
+          </DropdownMenu.Item>
+          <DropdownMenu.Item className="dropdown-item">
+            New Window <div className="right-slot">⌘+N</div>
+          </DropdownMenu.Item>
+          <DropdownMenu.Item className="dropdown-item" disabled>
+            New Private Window <div className="right-slot">⇧+⌘+N</div>
+          </DropdownMenu.Item>
+
+          {/* Sub-menu */}
+          <DropdownMenu.Sub>
+            <DropdownMenu.SubTrigger className="dropdown-subtrigger">
+              More Tools
+              <div className="right-slot">
+                <ChevronRightIcon />
+              </div>
+            </DropdownMenu.SubTrigger>
+            <DropdownMenu.Portal>
+              <DropdownMenu.SubContent
+                className="dropdown-subcontent"
+                sideOffset={2}
+                alignOffset={-5}
+              >
+                <DropdownMenu.Item className="dropdown-item">
+                  Save Page As… <div className="right-slot">⌘+S</div>
+                </DropdownMenu.Item>
+                <DropdownMenu.Item className="dropdown-item">
+                  Create Shortcut…
+                </DropdownMenu.Item>
+                <DropdownMenu.Item className="dropdown-item">
+                  Name Window…
+                </DropdownMenu.Item>
+                <DropdownMenu.Separator className="dropdown-separator" />
+                <DropdownMenu.Item className="dropdown-item">
+                  Developer Tools
+                </DropdownMenu.Item>
+              </DropdownMenu.SubContent>
+            </DropdownMenu.Portal>
+          </DropdownMenu.Sub>
+
+          <DropdownMenu.Separator className="dropdown-separator" />
+
+          {/* Checkbox items */}
+          <DropdownMenu.CheckboxItem
+            className="dropdown-checkbox-item"
+            checked={bookmarksChecked}
+            onCheckedChange={setBookmarksChecked}
+          >
+            <DropdownMenu.ItemIndicator className="dropdown-item-indicator">
+              <CheckIcon />
+            </DropdownMenu.ItemIndicator>
+            Show Bookmarks <div className="right-slot">⌘+B</div>
+          </DropdownMenu.CheckboxItem>
+          <DropdownMenu.CheckboxItem
+            className="dropdown-checkbox-item"
+            checked={urlsChecked}
+            onCheckedChange={setUrlsChecked}
+          >
+            <DropdownMenu.ItemIndicator className="dropdown-item-indicator">
+              <CheckIcon />
+            </DropdownMenu.ItemIndicator>
+            Show Full URLs
+          </DropdownMenu.CheckboxItem>
+
+          <DropdownMenu.Separator className="dropdown-separator" />
+
+          {/* Radio group */}
+          <DropdownMenu.Label className="dropdown-label">
+            People
+          </DropdownMenu.Label>
+          <DropdownMenu.RadioGroup value={person} onValueChange={setPerson}>
+            <DropdownMenu.RadioItem className="dropdown-radio-item" value="pedro">
+              <DropdownMenu.ItemIndicator className="dropdown-item-indicator">
+                <DotFilledIcon />
+              </DropdownMenu.ItemIndicator>
+              Pedro Duarte
+            </DropdownMenu.RadioItem>
+            <DropdownMenu.RadioItem className="dropdown-radio-item" value="colm">
+              <DropdownMenu.ItemIndicator className="dropdown-item-indicator">
+                <DotFilledIcon />
+              </DropdownMenu.ItemIndicator>
+              Colm Tuite
+            </DropdownMenu.RadioItem>
+          </DropdownMenu.RadioGroup>
+
+          <DropdownMenu.Arrow className="dropdown-arrow" />
+        </DropdownMenu.Content>
+      </DropdownMenu.Portal>
+    </DropdownMenu.Root>
+  );
+}
+
+/**
+ * Example: Simple Actions Menu
+ * 
+ * Common use case for data tables, cards, etc.
+ */
+export function ActionsMenu({ onEdit, onDuplicate, onDelete }) {
+  return (
+    <DropdownMenu.Root>
+      <DropdownMenu.Trigger asChild>
+        <button className="icon-button" aria-label="Actions">
+          <DotsHorizontalIcon />
+        </button>
+      </DropdownMenu.Trigger>
+
+      <DropdownMenu.Portal>
+        <DropdownMenu.Content className="dropdown-content" align="end">
+          <DropdownMenu.Item className="dropdown-item" onSelect={onEdit}>
+            Edit
+          </DropdownMenu.Item>
+          <DropdownMenu.Item className="dropdown-item" onSelect={onDuplicate}>
+            Duplicate
+          </DropdownMenu.Item>
+          <DropdownMenu.Separator className="dropdown-separator" />
+          <DropdownMenu.Item
+            className="dropdown-item dropdown-item-danger"
+            onSelect={onDelete}
+          >
+            Delete
+          </DropdownMenu.Item>
+        </DropdownMenu.Content>
+      </DropdownMenu.Portal>
+    </DropdownMenu.Root>
+  );
+}

skills/radix-ui-design-system/templates/component-template.tsx

@@ -0,0 +1,148 @@
+/**
+ * Radix UI Component Template
+ * 
+ * This template provides a starting point for creating
+ * custom components with Radix UI primitives.
+ * 
+ * Replace [PRIMITIVE] with actual primitive name:
+ * Dialog, DropdownMenu, Select, Tabs, Tooltip, etc.
+ */
+
+import * as [PRIMITIVE] from '@radix-ui/react-[primitive]';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { cn } from '@/lib/utils';
+
+// ============================================================================
+// Variants Definition (using CVA)
+// ============================================================================
+
+const [component]Variants = cva(
+  // Base styles (always applied)
+  "base-styles-here",
+  {
+    variants: {
+      // Define your variants
+      variant: {
+        default: "default-styles",
+        secondary: "secondary-styles",
+        destructive: "destructive-styles",
+      },
+      size: {
+        sm: "small-size-styles",
+        md: "medium-size-styles",
+        lg: "large-size-styles",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "md",
+    },
+  }
+);
+
+// ============================================================================
+// TypeScript Interfaces
+// ============================================================================
+
+interface [Component]Props 
+  extends React.ComponentPropsWithoutRef<typeof [PRIMITIVE].Root>,
+          VariantProps<typeof [component]Variants> {
+  // Add custom props here
+}
+
+// ============================================================================
+// Component Implementation
+// ============================================================================
+
+export function [Component]({
+  variant,
+  size,
+  className,
+  children,
+  ...props
+}: [Component]Props) {
+  return (
+    <[PRIMITIVE].Root {...props}>
+      {/* Trigger */}
+      <[PRIMITIVE].Trigger asChild>
+        <button className={cn([component]Variants({ variant, size }), className)}>
+          {children}
+        </button>
+      </[PRIMITIVE].Trigger>
+
+      {/* Portal (if needed) */}
+      <[PRIMITIVE].Portal>
+        {/* Overlay (for Dialog, etc.) */}
+        <[PRIMITIVE].Overlay className="overlay-styles" />
+        
+        {/* Content */}
+        <[PRIMITIVE].Content className="content-styles">
+          {/* Required accessibility parts */}
+          <[PRIMITIVE].Title className="title-styles">
+            Title
+          </[PRIMITIVE].Title>
+          
+          <[PRIMITIVE].Description className="description-styles">
+            Description
+          </[PRIMITIVE].Description>
+
+          {/* Your content */}
+          <div className="content-body">
+            {/* ... */}
+          </div>
+
+          {/* Close button */}
+          <[PRIMITIVE].Close asChild>
+            <button className="close-button">Close</button>
+          </[PRIMITIVE].Close>
+        </[PRIMITIVE].Content>
+      </[PRIMITIVE].Portal>
+    </[PRIMITIVE].Root>
+  );
+}
+
+// ============================================================================
+// Sub-components (if needed)
+// ============================================================================
+
+[Component].[SubComponent] = function [SubComponent]({
+  className,
+  ...props
+}: React.ComponentPropsWithoutRef<typeof [PRIMITIVE].[SubComponent]>) {
+  return (
+    <[PRIMITIVE].[SubComponent]
+      className={cn("subcomponent-styles", className)}
+      {...props}
+    />
+  );
+};
+
+// ============================================================================
+// Usage Example
+// ============================================================================
+
+/*
+import { [Component] } from './[component]';
+
+function App() {
+  return (
+    <[Component] variant="default" size="md">
+      Trigger Content
+    </[Component]
+  );
+}
+*/
+
+// ============================================================================
+// Accessibility Checklist
+// ============================================================================
+
+/*
+[ ] Keyboard navigation works (Tab, Arrow keys, Enter, Esc)
+[ ] Focus visible on all interactive elements
+[ ] Screen reader announces all states
+[ ] ARIA attributes are correct
+[ ] Color contrast meets WCAG AA (4.5:1 for text)
+[ ] Focus trapped when needed (modals)
+[ ] Focus restored after close
+*/

skills/readme/SKILL.md

@@ -0,0 +1,775 @@
+---
+name: readme
+description: "When the user wants to create or update a README.md file for a project. Also use when the user says "write readme," "create readme," "document this project," "project documentation," or asks for help with README.md. This skill creates absurdly thorough documentation covering local setup, architecture, and deployment."
+source: "https://github.com/Shpigford/skills/tree/main/readme"
+risk: safe
+---
+
+# README Generator
+
+You are an expert technical writer creating comprehensive project documentation. Your goal is to write a README.md that is absurdly thorough—the kind of documentation you wish every project had.
+
+## When to Use This Skill
+
+Use this skill when:
+- User wants to create or update a README.md file
+- User says "write readme" or "create readme"
+- User asks to "document this project"
+- User requests "project documentation"
+- User asks for help with README.md
+
+## The Three Purposes of a README
+
+1. **Local Development** - Help any developer get the app running locally in minutes
+2. **Understanding the System** - Explain in great detail how the app works
+3. **Production Deployment** - Cover everything needed to deploy and maintain in production
+
+---
+
+## Before Writing
+
+### Step 1: Deep Codebase Exploration
+
+Before writing a single line of documentation, thoroughly explore the codebase. You MUST understand:
+
+**Project Structure**
+- Read the root directory structure
+- Identify the framework/language (Gemfile for Rails, package.json, go.mod, requirements.txt, etc.)
+- Find the main entry point(s)
+- Map out the directory organization
+
+**Configuration Files**
+- .env.example, .env.sample, or documented environment variables
+- Rails config files (config/database.yml, config/application.rb, config/environments/)
+- Credentials setup (config/credentials.yml.enc, config/master.key)
+- Docker files (Dockerfile, docker-compose.yml)
+- CI/CD configs (.github/workflows/, .gitlab-ci.yml, etc.)
+- Deployment configs (config/deploy.yml for Kamal, fly.toml, render.yaml, Procfile, etc.)
+
+**Database**
+- db/schema.rb or db/structure.sql
+- Migrations in db/migrate/
+- Seeds in db/seeds.rb
+- Database type from config/database.yml
+
+**Key Dependencies**
+- Gemfile and Gemfile.lock for Ruby gems
+- package.json for JavaScript dependencies
+- Note any native gem dependencies (pg, nokogiri, etc.)
+
+**Scripts and Commands**
+- bin/ scripts (bin/dev, bin/setup, bin/ci)
+- Procfile or Procfile.dev
+- Rake tasks (lib/tasks/)
+
+### Step 2: Identify Deployment Target
+
+Look for these files to determine deployment platform and tailor instructions:
+
+- `Dockerfile` / `docker-compose.yml` → Docker-based deployment
+- `vercel.json` / `.vercel/` → Vercel
+- `netlify.toml` → Netlify
+- `fly.toml` → Fly.io
+- `railway.json` / `railway.toml` → Railway
+- `render.yaml` → Render
+- `app.yaml` → Google App Engine
+- `Procfile` → Heroku or Heroku-like platforms
+- `.ebextensions/` → AWS Elastic Beanstalk
+- `serverless.yml` → Serverless Framework
+- `terraform/` / `*.tf` → Terraform/Infrastructure as Code
+- `k8s/` / `kubernetes/` → Kubernetes
+
+If no deployment config exists, provide general guidance with Docker as the recommended approach.
+
+### Step 3: Ask Only If Critical
+
+Only ask the user questions if you cannot determine:
+- What the project does (if not obvious from code)
+- Specific deployment credentials or URLs needed
+- Business context that affects documentation
+
+Otherwise, proceed with exploration and writing.
+
+---
+
+## README Structure
+
+Write the README with these sections in order:
+
+### 1. Project Title and Overview
+
+```markdown
+# Project Name
+
+Brief description of what the project does and who it's for. 2-3 sentences max.
+
+## Key Features
+
+- Feature 1
+- Feature 2
+- Feature 3
+```
+
+### 2. Tech Stack
+
+List all major technologies:
+
+```markdown
+## Tech Stack
+
+- **Language**: Ruby 3.3+
+- **Framework**: Rails 7.2+
+- **Frontend**: Inertia.js with React
+- **Database**: PostgreSQL 16
+- **Background Jobs**: Solid Queue
+- **Caching**: Solid Cache
+- **Styling**: Tailwind CSS
+- **Deployment**: [Detected platform]
+```
+
+### 3. Prerequisites
+
+What must be installed before starting:
+
+```markdown
+## Prerequisites
+
+- Node.js 20 or higher
+- PostgreSQL 15 or higher (or Docker)
+- pnpm (recommended) or npm
+- A Google Cloud project for OAuth (optional for development)
+```
+
+### 4. Getting Started
+
+The complete local development guide:
+
+```markdown
+## Getting Started
+
+### 1. Clone the Repository
+
+\`\`\`bash
+git clone https://github.com/user/repo.git
+cd repo
+\`\`\`
+
+### 2. Install Ruby Dependencies
+
+Ensure you have Ruby 3.3+ installed (via rbenv, asdf, or mise):
+
+\`\`\`bash
+bundle install
+\`\`\`
+
+### 3. Install JavaScript Dependencies
+
+\`\`\`bash
+yarn install
+\`\`\`
+
+### 4. Environment Setup
+
+Copy the example environment file:
+
+\`\`\`bash
+cp .env.example .env
+\`\`\`
+
+Configure the following variables:
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `DATABASE_URL` | PostgreSQL connection string | `postgresql://localhost/myapp_development` |
+| `REDIS_URL` | Redis connection (if used) | `redis://localhost:6379/0` |
+| `SECRET_KEY_BASE` | Rails secret key | `bin/rails secret` |
+| `RAILS_MASTER_KEY` | For credentials encryption | Check `config/master.key` |
+
+### 5. Database Setup
+
+Start PostgreSQL (if using Docker):
+
+\`\`\`bash
+docker run --name postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres:16
+\`\`\`
+
+Create and set up the database:
+
+\`\`\`bash
+bin/rails db:setup
+\`\`\`
+
+This runs `db:create`, `db:schema:load`, and `db:seed`.
+
+For existing databases, run migrations:
+
+\`\`\`bash
+bin/rails db:migrate
+\`\`\`
+
+### 6. Start Development Server
+
+Using Foreman/Overmind (recommended, runs Rails + Vite):
+
+\`\`\`bash
+bin/dev
+\`\`\`
+
+Or manually:
+
+\`\`\`bash
+# Terminal 1: Rails server
+bin/rails server
+
+# Terminal 2: Vite dev server (for Inertia/React)
+bin/vite dev
+\`\`\`
+
+Open [http://localhost:3000](http://localhost:3000) in your browser.
+```
+
+Include every step. Assume the reader is setting up on a fresh machine.
+
+### 5. Architecture Overview
+
+This is where you go absurdly deep:
+
+```markdown
+## Architecture
+
+### Directory Structure
+
+\`\`\`
+├── app/
+│   ├── controllers/         # Rails controllers
+│   │   ├── concerns/        # Shared controller modules
+│   │   └── api/             # API-specific controllers
+│   ├── models/              # ActiveRecord models
+│   │   └── concerns/        # Shared model modules
+│   ├── jobs/                # Background jobs (Solid Queue)
+│   ├── mailers/             # Email templates
+│   ├── views/               # Rails views (minimal with Inertia)
+│   └── frontend/            # Inertia.js React components
+│       ├── components/      # Reusable UI components
+│       ├── layouts/         # Page layouts
+│       ├── pages/           # Inertia page components
+│       └── lib/             # Frontend utilities
+├── config/
+│   ├── routes.rb            # Route definitions
+│   ├── database.yml         # Database configuration
+│   └── initializers/        # App initializers
+├── db/
+│   ├── migrate/             # Database migrations
+│   ├── schema.rb            # Current schema
+│   └── seeds.rb             # Seed data
+├── lib/
+│   └── tasks/               # Custom Rake tasks
+└── public/                  # Static assets
+\`\`\`
+
+### Request Lifecycle
+
+1. Request hits Rails router (`config/routes.rb`)
+2. Middleware stack processes request (authentication, sessions, etc.)
+3. Controller action executes
+4. Models interact with PostgreSQL via ActiveRecord
+5. Inertia renders React component with props
+6. Response sent to browser
+
+### Data Flow
+
+\`\`\`
+User Action → React Component → Inertia Visit → Rails Controller → ActiveRecord → PostgreSQL
+                                                        ↓
+                                       React Props ← Inertia Response ←
+\`\`\`
+
+### Key Components
+
+**Authentication**
+- Devise/Rodauth for user authentication
+- Session-based auth with encrypted cookies
+- `authenticate_user!` before_action for protected routes
+
+**Inertia.js Integration (`app/frontend/`)**
+- React components receive props from Rails controllers
+- `inertia_render` in controllers passes data to frontend
+- Shared data via `inertia_share` for layout props
+
+**Background Jobs (`app/jobs/`)**
+- Solid Queue for job processing
+- Jobs stored in PostgreSQL (no Redis required)
+- Dashboard at `/jobs` for monitoring
+
+**Database (`app/models/`)**
+- ActiveRecord models with associations
+- Query objects for complex queries
+- Concerns for shared model behavior
+
+### Database Schema
+
+\`\`\`
+users
+├── id (bigint, PK)
+├── email (string, unique, not null)
+├── encrypted_password (string)
+├── name (string)
+├── created_at (datetime)
+└── updated_at (datetime)
+
+posts
+├── id (bigint, PK)
+├── title (string, not null)
+├── content (text)
+├── published (boolean, default: false)
+├── user_id (bigint, FK → users)
+├── created_at (datetime)
+└── updated_at (datetime)
+
+solid_queue_jobs (background jobs)
+├── id (bigint, PK)
+├── queue_name (string)
+├── class_name (string)
+├── arguments (json)
+├── scheduled_at (datetime)
+└── ...
+\`\`\`
+```
+
+### 6. Environment Variables
+
+Complete reference for all env vars:
+
+```markdown
+## Environment Variables
+
+### Required
+
+| Variable | Description | How to Get |
+|----------|-------------|------------|
+| `DATABASE_URL` | PostgreSQL connection string | Your database provider |
+| `SECRET_KEY_BASE` | Rails secret for sessions/cookies | Run `bin/rails secret` |
+| `RAILS_MASTER_KEY` | Decrypts credentials file | Check `config/master.key` (not in git) |
+
+### Optional
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `REDIS_URL` | Redis connection string (for caching/ActionCable) | - |
+| `RAILS_LOG_LEVEL` | Logging verbosity | `debug` (dev), `info` (prod) |
+| `RAILS_MAX_THREADS` | Puma thread count | `5` |
+| `WEB_CONCURRENCY` | Puma worker count | `2` |
+| `SMTP_ADDRESS` | Mail server hostname | - |
+| `SMTP_PORT` | Mail server port | `587` |
+
+### Rails Credentials
+
+Sensitive values should be stored in Rails encrypted credentials:
+
+\`\`\`bash
+# Edit credentials (opens in $EDITOR)
+bin/rails credentials:edit
+
+# Or for environment-specific credentials
+RAILS_ENV=production bin/rails credentials:edit
+\`\`\`
+
+Credentials file structure:
+\`\`\`yaml
+secret_key_base: xxx
+stripe:
+  public_key: pk_xxx
+  secret_key: sk_xxx
+google:
+  client_id: xxx
+  client_secret: xxx
+\`\`\`
+
+Access in code: `Rails.application.credentials.stripe[:secret_key]`
+
+### Environment-Specific
+
+**Development**
+\`\`\`
+DATABASE_URL=postgresql://localhost/myapp_development
+REDIS_URL=redis://localhost:6379/0
+\`\`\`
+
+**Production**
+\`\`\`
+DATABASE_URL=<production-connection-string>
+RAILS_ENV=production
+RAILS_SERVE_STATIC_FILES=true
+\`\`\`
+```
+
+### 7. Available Scripts
+
+```markdown
+## Available Scripts
+
+| Command | Description |
+|---------|-------------|
+| `bin/dev` | Start development server (Rails + Vite via Foreman) |
+| `bin/rails server` | Start Rails server only |
+| `bin/vite dev` | Start Vite dev server only |
+| `bin/rails console` | Open Rails console (IRB with app loaded) |
+| `bin/rails db:migrate` | Run pending database migrations |
+| `bin/rails db:rollback` | Rollback last migration |
+| `bin/rails db:seed` | Run database seeds |
+| `bin/rails db:reset` | Drop, create, migrate, and seed database |
+| `bin/rails routes` | List all routes |
+| `bin/rails test` | Run test suite (Minitest) |
+| `bundle exec rspec` | Run test suite (RSpec, if used) |
+| `bin/rails assets:precompile` | Compile assets for production |
+| `bin/rubocop` | Run Ruby linter |
+| `yarn lint` | Run JavaScript/TypeScript linter |
+```
+
+### 8. Testing
+
+```markdown
+## Testing
+
+### Running Tests
+
+\`\`\`bash
+# Run all tests (Minitest)
+bin/rails test
+
+# Run all tests (RSpec, if used)
+bundle exec rspec
+
+# Run specific test file
+bin/rails test test/models/user_test.rb
+bundle exec rspec spec/models/user_spec.rb
+
+# Run tests matching a pattern
+bin/rails test -n /creates_user/
+bundle exec rspec -e "creates user"
+
+# Run system tests (browser tests)
+bin/rails test:system
+
+# Run with coverage (SimpleCov)
+COVERAGE=true bin/rails test
+\`\`\`
+
+### Test Structure
+
+\`\`\`
+test/                        # Minitest structure
+├── controllers/             # Controller tests
+├── models/                  # Model unit tests
+├── integration/             # Integration tests
+├── system/                  # System/browser tests
+├── fixtures/                # Test data
+└── test_helper.rb           # Test configuration
+
+spec/                        # RSpec structure (if used)
+├── models/
+├── requests/
+├── system/
+├── factories/               # FactoryBot factories
+├── support/
+└── rails_helper.rb
+\`\`\`
+
+### Writing Tests
+
+**Minitest example:**
+\`\`\`ruby
+require "test_helper"
+
+class UserTest < ActiveSupport::TestCase
+  test "creates user with valid attributes" do
+    user = User.new(email: "test@example.com", name: "Test User")
+    assert user.valid?
+  end
+
+  test "requires email" do
+    user = User.new(name: "Test User")
+    assert_not user.valid?
+    assert_includes user.errors[:email], "can't be blank"
+  end
+end
+\`\`\`
+
+**RSpec example:**
+\`\`\`ruby
+require "rails_helper"
+
+RSpec.describe User, type: :model do
+  describe "validations" do
+    it "is valid with valid attributes" do
+      user = build(:user)
+      expect(user).to be_valid
+    end
+
+    it "requires an email" do
+      user = build(:user, email: nil)
+      expect(user).not_to be_valid
+      expect(user.errors[:email]).to include("can't be blank")
+    end
+  end
+end
+\`\`\`
+
+### Frontend Testing
+
+For Inertia/React components:
+
+\`\`\`bash
+yarn test
+\`\`\`
+
+\`\`\`typescript
+import { render, screen } from '@testing-library/react'
+import { Dashboard } from './Dashboard'
+
+describe('Dashboard', () => {
+  it('renders user name', () => {
+    render(<Dashboard user={{ name: 'Josh' }} />)
+    expect(screen.getByText('Josh')).toBeInTheDocument()
+  })
+})
+\`\`\`
+```
+
+### 9. Deployment
+
+Tailor this to detected platform (look for Dockerfile, fly.toml, render.yaml, kamal/, etc.):
+
+```markdown
+## Deployment
+
+### Kamal (Recommended for Rails)
+
+If using Kamal for deployment:
+
+\`\`\`bash
+# Setup Kamal (first time)
+kamal setup
+
+# Deploy
+kamal deploy
+
+# Rollback to previous version
+kamal rollback
+
+# View logs
+kamal app logs
+
+# Run console on production
+kamal app exec --interactive 'bin/rails console'
+\`\`\`
+
+Configuration lives in `config/deploy.yml`.
+
+### Docker
+
+Build and run:
+
+\`\`\`bash
+# Build image
+docker build -t myapp .
+
+# Run with environment variables
+docker run -p 3000:3000 \
+  -e DATABASE_URL=postgresql://... \
+  -e SECRET_KEY_BASE=... \
+  -e RAILS_ENV=production \
+  myapp
+\`\`\`
+
+### Heroku
+
+\`\`\`bash
+# Create app
+heroku create myapp
+
+# Add PostgreSQL
+heroku addons:create heroku-postgresql:mini
+
+# Set environment variables
+heroku config:set SECRET_KEY_BASE=$(bin/rails secret)
+heroku config:set RAILS_MASTER_KEY=$(cat config/master.key)
+
+# Deploy
+git push heroku main
+
+# Run migrations
+heroku run bin/rails db:migrate
+\`\`\`
+
+### Fly.io
+
+\`\`\`bash
+# Launch (first time)
+fly launch
+
+# Deploy
+fly deploy
+
+# Run migrations
+fly ssh console -C "bin/rails db:migrate"
+
+# Open console
+fly ssh console -C "bin/rails console"
+\`\`\`
+
+### Render
+
+If `render.yaml` exists, connect your repo to Render and it will auto-deploy.
+
+Manual setup:
+1. Create new Web Service
+2. Connect GitHub repository
+3. Set build command: `bundle install && bin/rails assets:precompile`
+4. Set start command: `bin/rails server`
+5. Add environment variables in dashboard
+
+### Manual/VPS Deployment
+
+\`\`\`bash
+# On the server:
+
+# Pull latest code
+git pull origin main
+
+# Install dependencies
+bundle install --deployment
+
+# Compile assets
+RAILS_ENV=production bin/rails assets:precompile
+
+# Run migrations
+RAILS_ENV=production bin/rails db:migrate
+
+# Restart application server (e.g., Puma via systemd)
+sudo systemctl restart myapp
+\`\`\`
+```
+
+### 10. Troubleshooting
+
+```markdown
+## Troubleshooting
+
+### Database Connection Issues
+
+**Error:** `could not connect to server: Connection refused`
+
+**Solution:**
+1. Verify PostgreSQL is running: `pg_isready` or `docker ps`
+2. Check `DATABASE_URL` format: `postgresql://USER:PASSWORD@HOST:PORT/DATABASE`
+3. Ensure database exists: `bin/rails db:create`
+
+### Pending Migrations
+
+**Error:** `Migrations are pending`
+
+**Solution:**
+\`\`\`bash
+bin/rails db:migrate
+\`\`\`
+
+### Asset Compilation Issues
+
+**Error:** `The asset "application.css" is not present in the asset pipeline`
+
+**Solution:**
+\`\`\`bash
+# Clear and recompile assets
+bin/rails assets:clobber
+bin/rails assets:precompile
+\`\`\`
+
+### Bundle Install Failures
+
+**Error:** Native extension build failures
+
+**Solution:**
+1. Ensure system dependencies are installed:
+   \`\`\`bash
+   # macOS
+   brew install postgresql libpq
+
+   # Ubuntu
+   sudo apt-get install libpq-dev
+   \`\`\`
+2. Try again: `bundle install`
+
+### Credentials Issues
+
+**Error:** `ActiveSupport::MessageEncryptor::InvalidMessage`
+
+**Solution:**
+The master key doesn't match the credentials file. Either:
+1. Get the correct `config/master.key` from another team member
+2. Or regenerate credentials: `rm config/credentials.yml.enc && bin/rails credentials:edit`
+
+### Vite/Inertia Issues
+
+**Error:** `Vite Ruby - Build failed`
+
+**Solution:**
+\`\`\`bash
+# Clear Vite cache
+rm -rf node_modules/.vite
+
+# Reinstall JS dependencies
+rm -rf node_modules && yarn install
+\`\`\`
+
+### Solid Queue Issues
+
+**Error:** Jobs not processing
+
+**Solution:**
+Ensure the queue worker is running:
+\`\`\`bash
+bin/jobs
+# or
+bin/rails solid_queue:start
+\`\`\`
+```
+
+### 11. Contributing (Optional)
+
+Include if open source or team project.
+
+### 12. License (Optional)
+
+---
+
+## Writing Principles
+
+1. **Be Absurdly Thorough** - When in doubt, include it. More detail is always better.
+
+2. **Use Code Blocks Liberally** - Every command should be copy-pasteable.
+
+3. **Show Example Output** - When helpful, show what the user should expect to see.
+
+4. **Explain the Why** - Don't just say "run this command," explain what it does.
+
+5. **Assume Fresh Machine** - Write as if the reader has never seen this codebase.
+
+6. **Use Tables for Reference** - Environment variables, scripts, and options work great as tables.
+
+7. **Keep Commands Current** - Use `pnpm` if the project uses it, `npm` if it uses npm, etc.
+
+8. **Include a Table of Contents** - For READMEs over ~200 lines, add a TOC at the top.
+
+---
+
+## Output Format
+
+Generate a complete README.md file with:
+- Proper markdown formatting
+- Code blocks with language hints (```bash, ```typescript, etc.)
+- Tables where appropriate
+- Clear section hierarchy
+- Linked table of contents for long documents
+
+Write the README directly to `README.md` in the project root.

skills/screenshots/SKILL.md

@@ -0,0 +1,401 @@
+---
+name: screenshots
+description: "Generate marketing screenshots of your app using Playwright. Use when the user wants to create screenshots for Product Hunt, social media, landing pages, or documentation."
+source: "https://github.com/Shpigford/skills/tree/main/screenshots"
+risk: safe
+---
+
+# Screenshots
+
+Generate marketing-quality screenshots of your app using Playwright directly. Screenshots are captured at true HiDPI (2x retina) resolution using `deviceScaleFactor: 2`.
+
+## When to Use This Skill
+
+Use this skill when:
+- User wants to create screenshots for Product Hunt
+- Creating screenshots for social media
+- Generating images for landing pages
+- Creating documentation screenshots
+- User requests marketing-quality app screenshots
+
+## Prerequisites
+
+Playwright must be available. Check for it:
+```bash
+npx playwright --version 2>/dev/null || npm ls playwright 2>/dev/null | grep playwright
+```
+
+If not found, inform the user:
+> Playwright is required. Install it with: `npm install -D playwright` or `npm install -D @playwright/test`
+
+## Step 1: Determine App URL
+
+If `$1` is provided, use it as the app URL.
+
+If no URL is provided:
+1. Check if a dev server is likely running by looking for `package.json` scripts
+2. Use `AskUserQuestion` to ask the user for the URL or offer to help start the dev server
+
+Common default URLs to suggest:
+- `http://localhost:3000` (Next.js, Create React App, Rails)
+- `http://localhost:5173` (Vite)
+- `http://localhost:4000` (Phoenix)
+- `http://localhost:8080` (Vue CLI, generic)
+
+## Step 2: Gather Requirements
+
+Use `AskUserQuestion` with the following questions:
+
+**Question 1: Screenshot count**
+- Header: "Count"
+- Question: "How many screenshots do you need?"
+- Options:
+  - "3-5" - Quick set of key features
+  - "5-10" - Comprehensive feature coverage
+  - "10+" - Full marketing suite
+
+**Question 2: Purpose**
+- Header: "Purpose"
+- Question: "What will these screenshots be used for?"
+- Options:
+  - "Product Hunt" - Hero shots and feature highlights
+  - "Social media" - Eye-catching feature demos
+  - "Landing page" - Marketing sections and benefits
+  - "Documentation" - UI reference and tutorials
+
+**Question 3: Authentication**
+- Header: "Auth"
+- Question: "Does the app require login to access the features you want to screenshot?"
+- Options:
+  - "No login needed" - Public pages only
+  - "Yes, I'll provide credentials" - Need to log in first
+
+If user selects "Yes, I'll provide credentials", ask follow-up questions:
+- "What is the login page URL?" (e.g., `/login`, `/sign-in`)
+- "What is the email/username?"
+- "What is the password?"
+
+The script will automatically detect login form fields using Playwright's smart locators.
+
+## Step 3: Analyze Codebase for Features
+
+Thoroughly explore the codebase to understand the app and identify screenshot opportunities.
+
+### 3.1: Read Documentation First
+
+**Always start by reading these files** to understand what the app does:
+
+1. **README.md** (and any README files in subdirectories) - Read the full README to understand:
+   - What the app is and what problem it solves
+   - Key features and capabilities
+   - Screenshots or feature descriptions already documented
+
+2. **CHANGELOG.md** or **HISTORY.md** - Recent features worth highlighting
+
+3. **docs/** directory - Any additional documentation about features
+
+### 3.2: Analyze Routes to Find Pages
+
+Read the routing configuration to discover all available pages:
+
+| Framework | File to Read | What to Look For |
+|-----------|--------------|------------------|
+| **Next.js App Router** | `app/` directory structure | Each folder with `page.tsx` is a route |
+| **Next.js Pages Router** | `pages/` directory | Each file is a route |
+| **Rails** | `config/routes.rb` | Read the entire file for all routes |
+| **React Router** | Search for `createBrowserRouter` or `<Route` | Route definitions with paths |
+| **Vue Router** | `src/router/index.js` or `router.js` | Routes array with path definitions |
+| **SvelteKit** | `src/routes/` directory | Each folder with `+page.svelte` is a route |
+| **Remix** | `app/routes/` directory | File-based routing |
+| **Laravel** | `routes/web.php` | Route definitions |
+| **Django** | `urls.py` files | URL patterns |
+| **Express** | Search for `app.get`, `router.get` | Route handlers |
+
+**Important**: Actually read these files, don't just check if they exist. The route definitions tell you what pages are available for screenshots.
+
+### 3.3: Identify Key Components
+
+Look for components that represent screenshottable features:
+
+- Dashboard components
+- Feature sections with distinct UI
+- Forms and interactive inputs
+- Data visualizations (charts, graphs, tables)
+- Modals and dialogs
+- Navigation and sidebars
+- Settings panels
+- User profile sections
+
+### 3.4: Check for Marketing Assets
+
+Look for existing marketing content that hints at key features:
+- Landing page components (often in `components/landing/` or `components/marketing/`)
+- Feature list components
+- Pricing tables
+- Testimonial sections
+
+### 3.5: Build Feature List
+
+Create a comprehensive list of discovered features with:
+- Feature name (from README or component name)
+- URL path (from routes)
+- CSS selector to focus on (from component structure)
+- Required UI state (logged in, data populated, modal open, specific tab selected)
+
+## Step 4: Plan Screenshots with User
+
+Present the discovered features to the user and ask them to confirm or modify the list.
+
+Use `AskUserQuestion`:
+- Header: "Features"
+- Question: "I found these features in your codebase. Which would you like to screenshot?"
+- Options: List 3-4 key features discovered, plus "Let me pick specific ones"
+
+If user wants specific ones, ask follow-up questions to clarify exactly what to capture.
+
+## Step 5: Create Screenshots Directory
+
+```bash
+mkdir -p screenshots
+```
+
+## Step 6: Generate and Run Playwright Script
+
+Create a Node.js script that uses Playwright with proper HiDPI settings. The script should:
+
+1. **Use `deviceScaleFactor: 2`** for true retina resolution
+2. **Set viewport to 1440x900** (produces 2880x1800 pixel images)
+3. **Handle authentication** if credentials were provided
+4. **Navigate to each page** and capture screenshots
+
+### Script Template
+
+Write this script to a temporary file (e.g., `screenshot-script.mjs`) and execute it:
+
+```javascript
+import { chromium } from 'playwright';
+
+const BASE_URL = '[APP_URL]';
+const SCREENSHOTS_DIR = './screenshots';
+
+// Authentication config (if needed)
+const AUTH = {
+  needed: [true|false],
+  loginUrl: '[LOGIN_URL]',
+  email: '[EMAIL]',
+  password: '[PASSWORD]',
+};
+
+// Screenshots to capture
+const SCREENSHOTS = [
+  { name: '01-feature-name', url: '/path', waitFor: '[optional-selector]' },
+  { name: '02-another-feature', url: '/another-path' },
+  // ... add all planned screenshots
+];
+
+async function main() {
+  const browser = await chromium.launch();
+
+  // Create context with HiDPI settings
+  const context = await browser.newContext({
+    viewport: { width: 1440, height: 900 },
+    deviceScaleFactor: 2,  // This is the key for true retina screenshots
+  });
+
+  const page = await context.newPage();
+
+  // Handle authentication if needed
+  if (AUTH.needed) {
+    console.log('Logging in...');
+    await page.goto(AUTH.loginUrl);
+
+    // Smart login: try multiple common patterns for email/username field
+    const emailField = page.locator([
+      'input[type="email"]',
+      'input[name="email"]',
+      'input[id="email"]',
+      'input[placeholder*="email" i]',
+      'input[name="username"]',
+      'input[id="username"]',
+      'input[type="text"]',
+    ].join(', ')).first();
+    await emailField.fill(AUTH.email);
+
+    // Smart login: try multiple common patterns for password field
+    const passwordField = page.locator([
+      'input[type="password"]',
+      'input[name="password"]',
+      'input[id="password"]',
+    ].join(', ')).first();
+    await passwordField.fill(AUTH.password);
+
+    // Smart login: try multiple common patterns for submit button
+    const submitButton = page.locator([
+      'button[type="submit"]',
+      'input[type="submit"]',
+      'button:has-text("Sign in")',
+      'button:has-text("Log in")',
+      'button:has-text("Login")',
+      'button:has-text("Submit")',
+    ].join(', ')).first();
+    await submitButton.click();
+
+    await page.waitForLoadState('networkidle');
+    console.log('Login complete');
+  }
+
+  // Capture each screenshot
+  for (const shot of SCREENSHOTS) {
+    console.log(`Capturing: ${shot.name}`);
+    await page.goto(`${BASE_URL}${shot.url}`);
+    await page.waitForLoadState('networkidle');
+
+    // Optional: wait for specific element
+    if (shot.waitFor) {
+      await page.waitForSelector(shot.waitFor);
+    }
+
+    // Optional: perform actions before screenshot
+    if (shot.actions) {
+      for (const action of shot.actions) {
+        if (action.click) await page.click(action.click);
+        if (action.fill) await page.fill(action.fill.selector, action.fill.value);
+        if (action.wait) await page.waitForTimeout(action.wait);
+      }
+    }
+
+    await page.screenshot({
+      path: `${SCREENSHOTS_DIR}/${shot.name}.png`,
+      fullPage: shot.fullPage || false,
+    });
+    console.log(`  Saved: ${shot.name}.png`);
+  }
+
+  await browser.close();
+  console.log('Done!');
+}
+
+main().catch(console.error);
+```
+
+### Running the Script
+
+```bash
+node screenshot-script.mjs
+```
+
+After running, clean up the temporary script:
+```bash
+rm screenshot-script.mjs
+```
+
+## Step 7: Advanced Screenshot Options
+
+### Element-Focused Screenshots
+
+To screenshot a specific element instead of the full viewport:
+
+```javascript
+const element = await page.locator('[CSS_SELECTOR]');
+await element.screenshot({ path: `${SCREENSHOTS_DIR}/element.png` });
+```
+
+### Full Page Screenshots
+
+For scrollable content, capture the entire page:
+
+```javascript
+await page.screenshot({
+  path: `${SCREENSHOTS_DIR}/full-page.png`,
+  fullPage: true
+});
+```
+
+### Waiting for Animations
+
+If the page has animations, wait for them to complete:
+
+```javascript
+await page.waitForTimeout(500); // Wait 500ms for animations
+```
+
+### Clicking Elements Before Screenshot
+
+To capture a modal, dropdown, or hover state:
+
+```javascript
+await page.click('button.open-modal');
+await page.waitForSelector('.modal-content');
+await page.screenshot({ path: `${SCREENSHOTS_DIR}/modal.png` });
+```
+
+### Dark Mode Screenshots
+
+If the app supports dark mode:
+
+```javascript
+// Set dark mode preference
+const context = await browser.newContext({
+  viewport: { width: 1440, height: 900 },
+  deviceScaleFactor: 2,
+  colorScheme: 'dark',
+});
+```
+
+## Step 8: File Naming Convention
+
+Use descriptive, kebab-case filenames with numeric prefixes for ordering:
+
+| Feature | Filename |
+|---------|----------|
+| Dashboard overview | `01-dashboard-overview.png` |
+| Link management | `02-link-inbox.png` |
+| Edition editor | `03-edition-editor.png` |
+| Analytics | `04-analytics.png` |
+| Settings | `05-settings.png` |
+
+## Step 9: Verify and Summarize
+
+After capturing all screenshots, verify the results:
+
+```bash
+ls -la screenshots/*.png
+sips -g pixelWidth -g pixelHeight screenshots/*.png 2>/dev/null || file screenshots/*.png
+```
+
+Provide a summary to the user:
+
+1. List all generated files with their paths
+2. Confirm the resolution (should be 2880x1800 for 2x retina at 1440x900 viewport)
+3. Mention total file sizes
+4. Suggest any follow-up actions
+
+Example output:
+```
+Generated 5 marketing screenshots:
+
+screenshots/
+├── 01-dashboard-overview.png (1.2 MB, 2880x1800 @ 2x)
+├── 02-link-inbox.png (456 KB, 2880x1800 @ 2x)
+├── 03-edition-editor.png (890 KB, 2880x1800 @ 2x)
+├── 04-analytics.png (567 KB, 2880x1800 @ 2x)
+└── 05-settings.png (234 KB, 2880x1800 @ 2x)
+
+All screenshots are true retina-quality (2x deviceScaleFactor) and ready for marketing use.
+```
+
+## Error Handling
+
+- **Playwright not found**: Suggest `npm install -D playwright`
+- **Page not loading**: Check if the dev server is running, suggest starting it
+- **Login failed**: The smart locators try common patterns but may fail on unusual login forms. If login fails, analyze the login page HTML to find the correct selectors and customize the script.
+- **Element not found**: Verify the CSS selector, offer to take a full page screenshot instead
+- **Screenshot failed**: Check disk space, verify write permissions to screenshots directory
+
+## Tips for Best Results
+
+1. **Clean UI state**: Use demo/seed data for realistic content
+2. **Consistent sizing**: Use the same viewport for all screenshots
+3. **Wait for content**: Use `waitForLoadState('networkidle')` to ensure all content loads
+4. **Hide dev tools**: Ensure no browser extensions or dev overlays are visible
+5. **Dark mode variants**: Consider capturing both light and dark mode if supported

skills/security-bluebook-builder/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: security-bluebook-builder
+description: "Build security Blue Books for sensitive apps"
+source: "https://github.com/SHADOWPR0/security-bluebook-builder"
+risk: safe
+---
+
+# Security Bluebook Builder
+
+## Overview
+
+Build security Blue Books for sensitive apps
+
+## When to Use This Skill
+
+Use this skill when you need to work with build security blue books for sensitive apps.
+
+## Instructions
+
+This skill provides guidance and patterns for build security blue books for sensitive apps.
+
+For more information, see the [source repository](https://github.com/SHADOWPR0/security-bluebook-builder).

skills/sharp-edges/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: sharp-edges
+description: "Identify error-prone APIs and dangerous configurations"
+source: "https://github.com/trailofbits/skills/tree/main/plugins/sharp-edges"
+risk: safe
+---
+
+# Sharp Edges
+
+## Overview
+
+Identify error-prone APIs and dangerous configurations that could lead to bugs, security vulnerabilities, or system failures.
+
+## When to Use This Skill
+
+Use this skill when you need to identify error-prone APIs and dangerous configurations.
+
+Use this skill when:
+- Reviewing code for potentially dangerous API usage
+- Identifying configurations that could cause issues
+- Analyzing code for error-prone patterns
+- Assessing risk in API design or configuration choices
+- Performing security audits focused on API misuse
+
+## Instructions
+
+This skill helps identify problematic APIs and configurations:
+
+1. **API Analysis**: Review API usage for error-prone patterns
+2. **Configuration Review**: Identify dangerous or risky configurations
+3. **Pattern Recognition**: Spot common mistakes and pitfalls
+4. **Risk Assessment**: Evaluate the potential impact of identified issues
+
+## Common Sharp Edges
+
+### Error-Prone APIs
+
+- APIs with complex parameter requirements
+- APIs with non-obvious failure modes
+- APIs that require careful resource management
+- APIs with timing or concurrency issues
+- APIs with unclear error handling
+
+### Dangerous Configurations
+
+- Default settings that are insecure
+- Configurations that bypass security controls
+- Settings that enable dangerous features
+- Options that reduce system reliability
+- Parameters that affect performance negatively
+
+## Detection Strategies
+
+1. **Code Review**: Look for known problematic patterns
+2. **Static Analysis**: Use tools to identify risky API usage
+3. **Configuration Audits**: Review configuration files for dangerous settings
+4. **Documentation Review**: Check for warnings about API usage
+5. **Experience-Based**: Leverage knowledge of common pitfalls
+
+## Best Practices
+
+- Document identified sharp edges
+- Provide clear guidance on safe usage
+- Create examples of correct vs incorrect usage
+- Recommend safer alternatives when available
+- Update documentation with findings
+
+## Resources
+
+For more information, see the [source repository](https://github.com/trailofbits/skills/tree/main/plugins/sharp-edges).

skills/skill-rails-upgrade/SKILL.md

@@ -0,0 +1,408 @@
+---
+name: skill-rails-upgrade
+description: "Analyze Rails apps and provide upgrade assessments"
+source: "https://github.com/robzolkos/skill-rails-upgrade"
+risk: safe
+---
+
+## When to Use This Skill
+
+Analyze Rails apps and provide upgrade assessments
+
+Use this skill when working with analyze rails apps and provide upgrade assessments.
+# Rails Upgrade Analyzer
+
+Analyze the current Rails application and provide a comprehensive upgrade assessment with selective file merging.
+
+## Step 1: Verify Rails Application
+
+Check that we're in a Rails application by looking for these files:
+- `Gemfile` (must exist and contain 'rails')
+- `config/application.rb` (Rails application config)
+- `config/environment.rb` (Rails environment)
+
+If any of these are missing or don't indicate a Rails app, stop and inform the user this doesn't appear to be a Rails application.
+
+## Step 2: Get Current Rails Version
+
+Extract the current Rails version from:
+1. First, check `Gemfile.lock` for the exact installed version (look for `rails (x.y.z)`)
+2. If not found, check `Gemfile` for the version constraint
+
+Report the exact current version (e.g., `7.1.3`).
+
+## Step 3: Find Latest Rails Version
+
+Use the GitHub CLI to fetch the latest Rails release:
+
+```bash
+gh api repos/rails/rails/releases/latest --jq '.tag_name'
+```
+
+This returns the latest stable version tag (e.g., `v8.0.1`). Strip the 'v' prefix for comparison.
+
+Also check recent tags to understand the release landscape:
+
+```bash
+gh api repos/rails/rails/tags --jq '.[0:10] | .[].name'
+```
+
+## Step 4: Determine Upgrade Type
+
+Compare current and latest versions to classify the upgrade:
+
+- **Patch upgrade**: Same major.minor, different patch (e.g., 7.1.3 → 7.1.5)
+- **Minor upgrade**: Same major, different minor (e.g., 7.1.3 → 7.2.0)
+- **Major upgrade**: Different major version (e.g., 7.1.3 → 8.0.0)
+
+## Step 5: Fetch Upgrade Guide
+
+Use WebFetch to get the official Rails upgrade guide:
+
+URL: `https://guides.rubyonrails.org/upgrading_ruby_on_rails.html`
+
+Look for sections relevant to the version jump. The guide is organized by target version with sections like:
+- "Upgrading from Rails X.Y to Rails X.Z"
+- Breaking changes
+- Deprecation warnings
+- Configuration changes
+- Required migrations
+
+Extract and summarize the relevant sections for the user's specific upgrade path.
+
+## Step 6: Fetch Rails Diff
+
+Use WebFetch to get the diff between versions from railsdiff.org:
+
+URL: `https://railsdiff.org/{current_version}/{target_version}`
+
+For example: `https://railsdiff.org/7.1.3/8.0.0`
+
+This shows:
+- Changes to default configuration files
+- New files that need to be added
+- Modified initializers
+- Updated dependencies
+- Changes to bin/ scripts
+
+Summarize the key file changes.
+
+## Step 7: Check JavaScript Dependencies
+
+Rails applications often include JavaScript packages that should be updated alongside Rails. Check for and report on these dependencies.
+
+### 7.1: Identify JS Package Manager
+
+Check which package manager the app uses:
+
+```bash
+# Check for package.json (npm/yarn)
+ls package.json 2>/dev/null
+
+# Check for importmap (Rails 7+)
+ls config/importmap.rb 2>/dev/null
+```
+
+### 7.2: Check Rails-Related JS Packages
+
+If `package.json` exists, check for these Rails-related packages:
+
+```bash
+# Extract current versions of Rails-related packages
+cat package.json | grep -E '"@hotwired/|"@rails/|"stimulus"|"turbo-rails"' || echo "No Rails JS packages found"
+```
+
+**Key packages to check:**
+
+| Package | Purpose | Version Alignment |
+|---------|---------|-------------------|
+| `@hotwired/turbo-rails` | Turbo Drive/Frames/Streams | Should match Rails version era |
+| `@hotwired/stimulus` | Stimulus JS framework | Generally stable across Rails versions |
+| `@rails/actioncable` | WebSocket support | Should match Rails version |
+| `@rails/activestorage` | Direct uploads | Should match Rails version |
+| `@rails/actiontext` | Rich text editing | Should match Rails version |
+| `@rails/request.js` | Rails UJS replacement | Should match Rails version era |
+
+### 7.3: Check for Updates
+
+For npm/yarn projects, check for available updates:
+
+```bash
+# Using npm
+npm outdated @hotwired/turbo-rails @hotwired/stimulus @rails/actioncable @rails/activestorage 2>/dev/null
+
+# Or check latest versions directly
+npm view @hotwired/turbo-rails version 2>/dev/null
+npm view @rails/actioncable version 2>/dev/null
+```
+
+### 7.4: Check Importmap Pins (if applicable)
+
+If the app uses importmap-rails, check `config/importmap.rb` for pinned versions:
+
+```bash
+cat config/importmap.rb | grep -E 'pin.*turbo|pin.*stimulus|pin.*@rails' || echo "No importmap pins found"
+```
+
+To update importmap pins:
+```bash
+bin/importmap pin @hotwired/turbo-rails
+bin/importmap pin @hotwired/stimulus
+```
+
+### 7.5: JS Dependency Summary
+
+Include in the upgrade summary:
+
+```
+### JavaScript Dependencies
+
+**Package Manager**: [npm/yarn/importmap/none]
+
+| Package | Current | Latest | Action |
+|---------|---------|--------|--------|
+| @hotwired/turbo-rails | 8.0.4 | 8.0.12 | Update recommended |
+| @rails/actioncable | 7.1.0 | 8.0.0 | Update with Rails |
+| ... | ... | ... | ... |
+
+**Recommended JS Updates:**
+- Run `npm update @hotwired/turbo-rails` (or yarn equivalent)
+- Run `npm update @rails/actioncable @rails/activestorage` to match Rails version
+```
+
+---
+
+## Step 8: Generate Upgrade Summary
+
+Provide a comprehensive summary including all findings from Steps 1-7:
+
+### Version Information
+- Current version: X.Y.Z
+- Latest version: A.B.C
+- Upgrade type: [Patch/Minor/Major]
+
+### Upgrade Complexity Assessment
+
+Rate the upgrade as **Small**, **Medium**, or **Large** based on:
+
+| Factor | Small | Medium | Large |
+|--------|-------|--------|-------|
+| Version jump | Patch only | Minor version | Major version |
+| Breaking changes | None | Few, well-documented | Many, significant |
+| Config changes | Minimal | Moderate | Extensive |
+| Deprecations | None active | Some to address | Many requiring refactoring |
+| Dependencies | Compatible | Some updates needed | Major dependency updates |
+
+### Key Changes to Address
+
+List the most important changes the user needs to handle:
+1. Configuration file updates
+2. Deprecated methods/features to update
+3. New required dependencies
+4. Database migrations needed
+5. Breaking API changes
+
+### Recommended Upgrade Steps
+
+1. Update test suite and ensure passing
+2. Review deprecation warnings in current version
+3. Update Gemfile with new Rails version
+4. Run `bundle update rails`
+5. Update JavaScript dependencies (see JS Dependencies section)
+6. **DO NOT run `rails app:update` directly** - use the selective merge process below
+7. Run database migrations
+8. Run test suite
+9. Review and update deprecated code
+
+### Resources
+
+- Rails Upgrade Guide: https://guides.rubyonrails.org/upgrading_ruby_on_rails.html
+- Rails Diff: https://railsdiff.org/{current}/{target}
+- Release Notes: https://github.com/rails/rails/releases/tag/v{target}
+
+---
+
+
+## When to Use This Skill
+
+Analyze Rails apps and provide upgrade assessments
+
+Use this skill when working with analyze rails apps and provide upgrade assessments.
+## Step 9: Selective File Update (replaces `rails app:update`)
+
+**IMPORTANT:** Do NOT run `rails app:update` as it overwrites files without considering local customizations. Instead, follow this selective merge process:
+
+### 9.1: Detect Local Customizations
+
+Before any upgrade, identify files with local customizations:
+
+```bash
+# Check for uncommitted changes
+git status
+
+# List config files that differ from a fresh Rails app
+# These are the files we need to be careful with
+git diff HEAD --name-only -- config/ bin/ public/
+```
+
+Create a mental list of files in these categories:
+- **Custom config files**: Files with project-specific settings (i18n, mailer, etc.)
+- **Modified bin scripts**: Scripts with custom behavior (bin/dev with foreman, etc.)
+- **Standard files**: Files that haven't been customized
+
+### 9.2: Analyze Required Changes from Railsdiff
+
+Based on the railsdiff output from Step 6, categorize each changed file:
+
+| Category | Action | Example |
+|----------|--------|---------|
+| **New files** | Create directly | `config/initializers/new_framework_defaults_X_Y.rb` |
+| **Unchanged locally** | Safe to overwrite | `public/404.html` (if not customized) |
+| **Customized locally** | Manual merge needed | `config/application.rb`, `bin/dev` |
+| **Comment-only changes** | Usually skip | Minor comment updates in config files |
+
+### 9.3: Create Upgrade Plan
+
+Present the user with a clear upgrade plan:
+
+```
+## Upgrade Plan: Rails X.Y.Z → A.B.C
+
+### New Files (will be created):
+- config/initializers/new_framework_defaults_A_B.rb
+- bin/ci (new CI script)
+
+### Safe to Update (no local customizations):
+- public/400.html
+- public/404.html
+- public/500.html
+
+### Needs Manual Merge (local customizations detected):
+- config/application.rb
+  └─ Local: i18n configuration
+  └─ Rails: [describe new Rails changes if any]
+
+- config/environments/development.rb
+  └─ Local: letter_opener mailer config
+  └─ Rails: [describe new Rails changes]
+
+- bin/dev
+  └─ Local: foreman + Procfile.dev setup
+  └─ Rails: changed to simple ruby script
+
+### Skip (comment-only or irrelevant changes):
+- config/puma.rb (only comment changes)
+```
+
+### 9.4: Execute Upgrade Plan
+
+After user confirms the plan:
+
+#### For New Files:
+Create them directly using the content from railsdiff or by extracting from a fresh Rails app:
+
+```bash
+# Generate a temporary fresh Rails app to extract new files
+cd /tmp && rails new rails_template --skip-git --skip-bundle
+# Then copy needed files
+```
+
+Or use the Rails generator for specific files:
+```bash
+bin/rails app:update:configs  # Only updates config files, still interactive
+```
+
+#### For Safe Updates:
+Overwrite these files as they have no local customizations.
+
+#### For Manual Merges:
+For each file needing merge, show the user:
+
+1. **Current local version** (their customizations)
+2. **New Rails default** (from railsdiff)
+3. **Suggested merged version** that:
+   - Keeps all local customizations
+   - Adds only essential new Rails functionality
+   - Removes deprecated settings
+
+Example merge for `config/application.rb`:
+```ruby
+# KEEP local customizations:
+config.i18n.available_locales = [:de, :en]
+config.i18n.default_locale = :de
+config.i18n.fallbacks = [:en]
+
+# ADD new Rails 8.1 settings if needed:
+# (usually none required - new defaults come via new_framework_defaults file)
+```
+
+### 9.5: Handle Active Storage Migrations
+
+After file updates, run any new migrations:
+
+```bash
+bin/rails db:migrate
+```
+
+Check for new migrations that were added:
+```bash
+ls -la db/migrate/ | tail -10
+```
+
+### 9.6: Verify Upgrade
+
+After completing the merge:
+
+1. Start the Rails server and check for errors:
+   ```bash
+   bin/dev  # or bin/rails server
+   ```
+
+2. Check the Rails console:
+   ```bash
+   bin/rails console
+   ```
+
+3. Run the test suite:
+   ```bash
+   bin/rails test
+   ```
+
+4. Review deprecation warnings in logs
+
+---
+
+## Step 10: Finalize Framework Defaults
+
+After verifying the app works:
+
+1. Review `config/initializers/new_framework_defaults_X_Y.rb`
+2. Enable each new default one by one, testing after each
+3. Once all defaults are enabled and tested, update `config/application.rb`:
+   ```ruby
+   config.load_defaults X.Y  # Update to new version
+   ```
+4. Delete the `new_framework_defaults_X_Y.rb` file
+
+---
+
+
+## When to Use This Skill
+
+Analyze Rails apps and provide upgrade assessments
+
+Use this skill when working with analyze rails apps and provide upgrade assessments.
+## Error Handling
+
+- If `gh` CLI is not authenticated, instruct the user to run `gh auth login`
+- If railsdiff.org doesn't have the exact versions, try with major.minor.0 versions
+- If the app is already on the latest version, congratulate the user and note any upcoming releases
+- If local customizations would be lost, ALWAYS stop and show the user what would be overwritten before proceeding
+
+## Key Principles
+
+1. **Never overwrite without checking** - Always check for local customizations first
+2. **Preserve user intent** - Local customizations exist for a reason
+3. **Minimal changes** - Only add what's necessary for the new Rails version
+4. **Transparency** - Show the user exactly what will change before doing it
+5. **Reversibility** - User should be able to `git checkout` to restore if needed

skills/skill-seekers/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: skill-seekers
+description: "-Automatically convert documentation websites, GitHub repositories, and PDFs into Claude AI skills in minutes."
+source: "https://github.com/yusufkaraaslan/Skill_Seekers"
+risk: safe
+---
+
+# Skill Seekers
+
+## Overview
+
+-Automatically convert documentation websites, GitHub repositories, and PDFs into Claude AI skills in minutes.
+
+## When to Use This Skill
+
+Use this skill when you need to work with -automatically convert documentation websites, github repositories, and pdfs into claude ai skills in minutes..
+
+## Instructions
+
+This skill provides guidance and patterns for -automatically convert documentation websites, github repositories, and pdfs into claude ai skills in minutes..
+
+For more information, see the [source repository](https://github.com/yusufkaraaslan/Skill_Seekers).

skills/stitch-ui-design/README.md

@@ -0,0 +1,165 @@
+# Stitch UI Design Skill
+
+Expert guidance for creating effective prompts in Google Stitch, the AI-powered UI design tool.
+
+## Overview
+
+This skill provides comprehensive guidance for crafting precise, actionable prompts that generate high-quality UI designs in Google Stitch. It covers prompt structure, specificity techniques, iteration strategies, and design-to-code workflows.
+
+## What's Included
+
+### SKILL.md
+Core prompting principles and techniques:
+- Specificity and detail requirements
+- Visual style definition
+- Multi-screen flow structuring
+- Platform and responsive specifications
+- Functional requirements
+- Prompt templates
+- Iteration strategies
+- Common use cases
+- Anti-patterns to avoid
+
+### References
+
+#### prompt-examples.md
+Comprehensive library of effective Stitch prompts organized by category:
+- Landing pages
+- Mobile apps
+- Dashboards
+- E-commerce
+- Forms & authentication
+- Content platforms
+- SaaS applications
+
+Each example includes detailed component breakdowns, style specifications, and platform requirements.
+
+#### advanced-techniques.md
+Advanced strategies for production-ready designs:
+- Image-to-UI workflows
+- Design system integration
+- Responsive design strategies
+- Accessibility considerations
+- Performance optimization
+- Component reusability
+- Atomic design methodology
+- Export and handoff best practices
+
+## When to Use This Skill
+
+Use this skill when:
+- Creating UI designs in Google Stitch
+- Generating mobile or web app interfaces
+- Crafting effective Stitch prompts
+- Converting sketches or wireframes to digital UI
+- Building design systems
+- Creating responsive layouts
+- Ensuring accessibility compliance
+- Optimizing design-to-code workflows
+
+## Key Principles
+
+1. **Be Specific** - Generic prompts yield generic results
+2. **Define Visual Style** - Always include colors, aesthetics, and design direction
+3. **Structure Clearly** - List components and sections explicitly
+4. **Specify Platform** - Indicate mobile, tablet, desktop, or responsive
+5. **Include Functionality** - Describe interactions, states, and user flows
+6. **Iterate Incrementally** - Make focused changes rather than complete redesigns
+
+## Quick Start
+
+### Basic Prompt Template
+
+```
+[Screen/Component Type] for [User/Context]
+
+Key Features:
+- [Feature 1 with specific details]
+- [Feature 2 with specific details]
+- [Feature 3 with specific details]
+
+Visual Style:
+- [Color scheme]
+- [Design aesthetic]
+- [Layout approach]
+
+Platform: [Mobile/Web/Responsive]
+```
+
+### Example Usage
+
+```
+Dashboard for SaaS analytics platform
+
+Key Features:
+- Top metrics cards showing MRR, active users, churn rate
+- Line chart for revenue trends (last 30 days)
+- Recent activity feed with user actions
+- Quick action buttons for reports and exports
+
+Visual Style:
+- Dark mode with blue/purple gradient accents
+- Modern glassmorphic cards with subtle shadows
+- Clean data visualization with accessible colors
+
+Platform: Responsive web (desktop-first)
+```
+
+## Best Practices
+
+### Do's ✅
+- Provide specific component details
+- Define clear visual direction
+- Specify responsive behavior
+- Include interaction states
+- Use design terminology
+- Reference existing designs when helpful
+- Iterate with annotations
+- Consider accessibility from the start
+
+### Don'ts ❌
+- Use vague descriptions ("nice website")
+- Omit visual style guidance
+- Forget platform specifications
+- Ignore responsive requirements
+- Skip accessibility considerations
+- Make complete redesigns instead of incremental changes
+
+## Integration with Development
+
+### Stitch → Figma → Code
+1. Generate UI in Stitch with detailed prompts
+2. Export to Figma for design system integration
+3. Hand off to developers with design specs
+4. Implement with production-ready code
+
+### Stitch → HTML → Framework
+1. Generate and refine UI in Stitch
+2. Export HTML/CSS code
+3. Convert to React/Vue/Svelte components
+4. Integrate into application codebase
+
+## Resources
+
+- **SKILL.md** - Core prompting guide
+- **prompt-examples.md** - 30+ detailed prompt examples
+- **advanced-techniques.md** - Production-ready design strategies
+
+## Tips for Success
+
+1. Start with clear requirements and context
+2. Use the prompt template for consistency
+3. Reference examples for similar use cases
+4. Iterate incrementally with annotations
+5. Generate variants to explore options
+6. Always specify visual style and platform
+7. Consider accessibility in every prompt
+8. Refine exports before production use
+
+## About Google Stitch
+
+Google Stitch is an experimental AI UI generator powered by Gemini 2.5 Flash that transforms text prompts and visual references into functional UI designs. It supports text-to-UI generation, image-to-UI conversion, multi-screen flows, and exports to HTML/CSS, Figma, and code.
+
+---
+
+**Note:** This skill is designed to help you create effective prompts for Stitch. The quality of your output depends on the specificity and clarity of your prompts. Use the templates and examples as starting points, then customize for your unique requirements.

skills/stitch-ui-design/SKILL.md

@@ -0,0 +1,378 @@
+---
+name: stitch-ui-design
+description: Expert guide for creating effective prompts for Google Stitch AI UI design tool. Use when user wants to design UI/UX in Stitch, create app interfaces, generate mobile/web designs, or needs help crafting Stitch prompts. Covers prompt structure, specificity techniques, iteration strategies, and design-to-code workflows for Stitch by Google.
+risk: safe
+source: "self"
+---
+
+# Stitch UI Design Prompting
+
+Expert guidance for crafting effective prompts in Google Stitch, the AI-powered UI design tool by Google Labs. This skill helps create precise, actionable prompts that generate high-quality UI designs for web and mobile applications.
+
+## What is Google Stitch?
+
+Google Stitch is an experimental AI UI generator powered by Gemini 2.5 Flash that transforms text prompts and visual references into functional UI designs. It supports:
+
+- Text-to-UI generation from natural language prompts
+- Image-to-UI conversion from sketches, wireframes, or screenshots
+- Multi-screen app flows and responsive layouts
+- Export to HTML/CSS, Figma, and code
+- Iterative refinement with variants and annotations
+
+## Core Prompting Principles
+
+### 1. Be Specific and Detailed
+
+Generic prompts yield generic results. Specific prompts with clear requirements produce tailored, professional designs.
+
+**Poor prompt:**
+```
+Create a dashboard
+```
+
+**Effective prompt:**
+```
+Member dashboard with course modules grid, progress tracking bar, 
+and community feed sidebar using purple theme and card-based layout
+```
+
+**Why it works:** Specifies components (modules, progress, feed), layout structure (grid, sidebar), visual style (purple theme, cards), and context (member dashboard).
+
+### 2. Define Visual Style and Theme
+
+Always include color schemes, design aesthetics, and visual direction to avoid generic AI outputs.
+
+**Components to specify:**
+- Color palette (primary colors, accent colors)
+- Design style (minimalist, modern, playful, professional, glassmorphic)
+- Typography preferences (if any)
+- Spacing and density (compact, spacious, balanced)
+
+**Example:**
+```
+E-commerce product page with hero image gallery, add-to-cart CTA, 
+reviews section, and related products carousel. Use clean minimalist 
+design with sage green accents and generous white space.
+```
+
+### 3. Structure Multi-Screen Flows Clearly
+
+For apps with multiple screens, list each screen as bullet points before generation.
+
+**Approach:**
+```
+Fitness tracking app with:
+- Onboarding screen with goal selection
+- Home dashboard with daily stats and activity rings
+- Workout library with category filters
+- Profile screen with achievements and settings
+```
+
+Stitch will ask for confirmation before generating multiple screens, ensuring alignment with your vision.
+
+### 4. Specify Platform and Responsive Behavior
+
+Indicate whether the design is for mobile, tablet, desktop, or responsive web.
+
+**Examples:**
+```
+Mobile app login screen (iOS style) with email/password fields and social auth buttons
+
+Responsive landing page that adapts from mobile (320px) to desktop (1440px) 
+with collapsible navigation
+```
+
+### 5. Include Functional Requirements
+
+Describe interactive elements, states, and user flows to generate more complete designs.
+
+**Elements to specify:**
+- Button actions and CTAs
+- Form fields and validation
+- Navigation patterns
+- Loading states
+- Empty states
+- Error handling
+
+**Example:**
+```
+Checkout flow with:
+- Cart summary with quantity adjusters
+- Shipping address form with validation
+- Payment method selection (cards, PayPal, Apple Pay)
+- Order confirmation with tracking number
+```
+
+## Prompt Structure Template
+
+Use this template for comprehensive prompts:
+
+```
+[Screen/Component Type] for [User/Context]
+
+Key Features:
+- [Feature 1 with specific details]
+- [Feature 2 with specific details]
+- [Feature 3 with specific details]
+
+Visual Style:
+- [Color scheme]
+- [Design aesthetic]
+- [Layout approach]
+
+Platform: [Mobile/Web/Responsive]
+```
+
+**Example:**
+```
+Dashboard for SaaS analytics platform
+
+Key Features:
+- Top metrics cards showing MRR, active users, churn rate
+- Line chart for revenue trends (last 30 days)
+- Recent activity feed with user actions
+- Quick action buttons for reports and exports
+
+Visual Style:
+- Dark mode with blue/purple gradient accents
+- Modern glassmorphic cards with subtle shadows
+- Clean data visualization with accessible colors
+
+Platform: Responsive web (desktop-first)
+```
+
+## Iteration Strategies
+
+### Refine with Annotations
+
+Use Stitch's "annotate to edit" feature to make targeted changes without rewriting the entire prompt.
+
+**Workflow:**
+1. Generate initial design from prompt
+2. Annotate specific elements that need changes
+3. Describe modifications in natural language
+4. Stitch updates only the annotated areas
+
+**Example annotations:**
+- "Make this button larger and use primary color"
+- "Add more spacing between these cards"
+- "Change this to a horizontal layout"
+
+### Generate Variants
+
+Request multiple variations to explore different design directions:
+
+```
+Generate 3 variants of this hero section:
+1. Image-focused with minimal text
+2. Text-heavy with supporting graphics
+3. Video background with overlay content
+```
+
+### Progressive Refinement
+
+Start broad, then add specificity in follow-up prompts:
+
+**Initial:**
+```
+E-commerce homepage
+```
+
+**Refinement 1:**
+```
+Add featured products section with 4-column grid and hover effects
+```
+
+**Refinement 2:**
+```
+Update color scheme to earth tones (terracotta, sage, cream) 
+and add promotional banner at top
+```
+
+## Common Use Cases
+
+### Landing Pages
+
+```
+SaaS landing page for [product name]
+
+Sections:
+- Hero with headline, subheadline, CTA, and product screenshot
+- Social proof with customer logos
+- Features grid (3 columns) with icons
+- Testimonials carousel
+- Pricing table (3 tiers)
+- FAQ accordion
+- Footer with links and newsletter signup
+
+Style: Modern, professional, trust-building
+Colors: Navy blue primary, light blue accents, white background
+```
+
+### Mobile Apps
+
+```
+Food delivery app home screen
+
+Components:
+- Search bar with location selector
+- Category chips (Pizza, Burgers, Sushi, etc.)
+- Restaurant cards with image, name, rating, delivery time, and price range
+- Bottom navigation (Home, Search, Orders, Profile)
+
+Style: Vibrant, appetite-appealing, easy to scan
+Colors: Orange primary, white background, food photography
+Platform: iOS mobile (375px width)
+```
+
+### Dashboards
+
+```
+Admin dashboard for content management system
+
+Layout:
+- Left sidebar navigation with collapsible menu
+- Top bar with search, notifications, and user profile
+- Main content area with:
+  - Stats overview (4 metric cards)
+  - Recent posts table with actions
+  - Activity timeline
+  - Quick actions panel
+
+Style: Clean, data-focused, professional
+Colors: Neutral grays with blue accents
+Platform: Desktop web (1440px)
+```
+
+### Forms and Inputs
+
+```
+Multi-step signup form for B2B platform
+
+Steps:
+1. Account details (company name, email, password)
+2. Company information (industry, size, role)
+3. Team setup (invite members)
+4. Confirmation with success message
+
+Features:
+- Progress indicator at top
+- Field validation with inline errors
+- Back/Next navigation
+- Skip option for step 3
+
+Style: Minimal, focused, low-friction
+Colors: White background, green for success states
+```
+
+## Design-to-Code Workflow
+
+### Export Options
+
+Stitch provides multiple export formats:
+
+1. **HTML/CSS** - Clean, semantic markup for web projects
+2. **Figma** - "Paste to Figma" for design system integration
+3. **Code snippets** - Component-level exports for frameworks
+
+### Best Practices for Export
+
+**Before exporting:**
+- Verify responsive breakpoints
+- Check color contrast for accessibility
+- Ensure interactive states are defined
+- Review component naming and structure
+
+**After export:**
+- Refactor generated code for production standards
+- Add proper semantic HTML tags
+- Implement accessibility attributes (ARIA labels, alt text)
+- Optimize images and assets
+- Add animations and micro-interactions
+
+## Anti-Patterns to Avoid
+
+### ❌ Vague Prompts
+```
+Make a nice website
+```
+
+### ✅ Specific Prompts
+```
+Portfolio website for photographer with full-screen image gallery, 
+project case studies, and contact form. Minimalist black and white 
+aesthetic with serif typography.
+```
+
+---
+
+### ❌ Missing Context
+```
+Create a login page
+```
+
+### ✅ Context-Rich Prompts
+```
+Login page for healthcare portal with email/password fields, 
+"Remember me" checkbox, "Forgot password" link, and SSO options 
+(Google, Microsoft). Professional, trustworthy design with 
+blue medical theme.
+```
+
+---
+
+### ❌ No Visual Direction
+```
+Design an app for task management
+```
+
+### ✅ Clear Visual Direction
+```
+Task management app with kanban board layout, drag-and-drop cards, 
+priority labels, and due date indicators. Modern, productivity-focused 
+design with purple/teal gradient accents and dark mode support.
+```
+
+## Tips for Better Results
+
+1. **Reference existing designs** - Upload screenshots or sketches as visual references alongside text prompts
+
+2. **Use design terminology** - Terms like "hero section," "card layout," "glassmorphic," "bento grid" help Stitch understand your intent
+
+3. **Specify interactions** - Describe hover states, click actions, and transitions for more complete designs
+
+4. **Think in components** - Break complex screens into reusable components (header, card, form, etc.)
+
+5. **Iterate incrementally** - Make small, focused changes rather than complete redesigns
+
+6. **Test responsiveness** - Always verify designs at multiple breakpoints (mobile, tablet, desktop)
+
+7. **Consider accessibility** - Mention color contrast, font sizes, and touch target sizes in prompts
+
+8. **Leverage variants** - Generate multiple options to explore different design directions quickly
+
+## Integration with Development Workflow
+
+### Stitch → Figma → Code
+1. Generate UI in Stitch with detailed prompts
+2. Export to Figma for design system integration
+3. Hand off to developers with design specs
+4. Implement with production-ready code
+
+### Stitch → HTML → Framework
+1. Generate and refine UI in Stitch
+2. Export HTML/CSS code
+3. Convert to React/Vue/Svelte components
+4. Integrate into application codebase
+
+### Rapid Prototyping
+1. Create multiple screen variations quickly
+2. Test with users or stakeholders
+3. Iterate based on feedback
+4. Finalize design for development
+
+## Conclusion
+
+Effective Stitch prompts are specific, context-rich, and visually descriptive. By following these principles and templates, you can generate professional UI designs that serve as strong foundations for production applications.
+
+**Remember:** Stitch is a starting point, not a final product. Use it to accelerate the design process, explore ideas quickly, and establish visual direction—then refine with human judgment and production standards.

skills/stitch-ui-design/references/advanced-techniques.md

@@ -0,0 +1,541 @@
+# Advanced Stitch Techniques
+
+Advanced strategies for maximizing Stitch's capabilities and creating production-ready designs.
+
+## Table of Contents
+
+1. [Image-to-UI Workflows](#image-to-ui-workflows)
+2. [Design System Integration](#design-system-integration)
+3. [Responsive Design Strategies](#responsive-design-strategies)
+4. [Accessibility Considerations](#accessibility-considerations)
+5. [Performance Optimization](#performance-optimization)
+6. [Component Reusability](#component-reusability)
+
+---
+
+## Image-to-UI Workflows
+
+### Converting Sketches to Digital UI
+
+Stitch can interpret hand-drawn sketches, wireframes, and rough mockups.
+
+**Best practices:**
+
+1. **Clear structure** - Draw distinct boxes for components
+2. **Label elements** - Annotate buttons, inputs, sections
+3. **Show hierarchy** - Use size and position to indicate importance
+4. **Include notes** - Add text describing interactions or states
+
+**Example workflow:**
+```
+1. Sketch wireframe on paper or tablet
+2. Take clear photo or scan
+3. Upload to Stitch with prompt:
+   "Convert this wireframe to a modern web interface with 
+   glassmorphic design and purple gradient accents"
+4. Refine generated design with annotations
+```
+
+### Reference-Based Design
+
+Upload screenshots of existing designs to create similar layouts with your own branding.
+
+**Prompt structure:**
+```
+Create a [type] similar to this reference image, but with:
+- [Your color scheme]
+- [Your content/copy]
+- [Your brand style]
+- [Specific modifications]
+```
+
+**Example:**
+```
+Create a pricing page similar to this reference, but with:
+- Navy blue and gold color scheme
+- 4 pricing tiers instead of 3
+- Annual/monthly toggle
+- Feature comparison table below
+- Testimonials section at bottom
+```
+
+---
+
+## Design System Integration
+
+### Establishing Design Tokens
+
+Define reusable design tokens in your initial prompt for consistency across screens.
+
+**Token categories:**
+- Colors (primary, secondary, accent, neutral, semantic)
+- Typography (font families, sizes, weights, line heights)
+- Spacing (scale: 4px, 8px, 16px, 24px, 32px, 48px, 64px)
+- Border radius (none, sm, md, lg, full)
+- Shadows (elevation levels)
+
+**Example prompt:**
+```
+Dashboard using this design system:
+
+Colors:
+- Primary: #2563EB (blue)
+- Secondary: #7C3AED (purple)
+- Success: #10B981 (green)
+- Warning: #F59E0B (amber)
+- Error: #EF4444 (red)
+- Neutral: #6B7280 (gray)
+
+Typography:
+- Headings: Inter Bold
+- Body: Inter Regular
+- Code: JetBrains Mono
+
+Spacing: 8px base unit
+Border radius: 8px for cards, 4px for buttons
+Shadows: Subtle elevation with 0 4px 6px rgba(0,0,0,0.1)
+```
+
+### Component Library Approach
+
+Create a component library by generating individual components first, then composing them into full screens.
+
+**Workflow:**
+```
+1. Generate base components:
+   - Button variants (primary, secondary, outline, ghost)
+   - Input fields (text, email, password, search)
+   - Cards (basic, with image, with actions)
+   - Navigation (header, sidebar, tabs)
+
+2. Document component specs:
+   - States (default, hover, active, disabled)
+   - Sizes (sm, md, lg)
+   - Variants
+
+3. Compose screens using established components:
+   "Create a settings page using the button and input 
+   components from previous generations"
+```
+
+---
+
+## Responsive Design Strategies
+
+### Mobile-First Approach
+
+Start with mobile design, then scale up to tablet and desktop.
+
+**Prompt sequence:**
+
+**Step 1 - Mobile (375px):**
+```
+Mobile app home screen for recipe platform
+
+Layout:
+- Stacked vertical sections
+- Full-width cards
+- Bottom navigation
+- Hamburger menu
+
+Content:
+- Search bar at top
+- Featured recipe hero card
+- Category chips (horizontal scroll)
+- Recipe grid (1 column)
+```
+
+**Step 2 - Tablet (768px):**
+```
+Adapt the mobile recipe home screen for tablet:
+- 2-column recipe grid
+- Persistent sidebar navigation (replaces hamburger)
+- Larger featured hero with side-by-side layout
+- Category chips remain scrollable
+```
+
+**Step 3 - Desktop (1440px):**
+```
+Adapt for desktop:
+- 3-column recipe grid
+- Full sidebar with categories expanded
+- Hero section with 3 featured recipes
+- Top navigation bar with search and user menu
+```
+
+### Breakpoint-Specific Prompts
+
+Specify exact breakpoints and layout changes.
+
+**Example:**
+```
+Responsive product grid:
+
+Mobile (< 640px):
+- 1 column
+- Full-width cards
+- Vertical image orientation
+
+Tablet (640px - 1024px):
+- 2 columns
+- Square images
+- Compact card layout
+
+Desktop (> 1024px):
+- 4 columns
+- Hover effects with overlay
+- Quick view button
+```
+
+---
+
+## Accessibility Considerations
+
+### WCAG Compliance Prompts
+
+Include accessibility requirements directly in prompts.
+
+**Key areas to specify:**
+
+1. **Color Contrast**
+```
+Ensure all text meets WCAG AA standards:
+- Normal text: 4.5:1 contrast ratio minimum
+- Large text (18pt+): 3:1 contrast ratio minimum
+- Interactive elements: clear focus states with 3:1 contrast
+```
+
+2. **Touch Targets**
+```
+All interactive elements minimum 44x44px touch target size
+Adequate spacing between clickable elements (8px minimum)
+```
+
+3. **Keyboard Navigation**
+```
+Clear focus indicators on all interactive elements
+Logical tab order following visual flow
+Skip navigation link for keyboard users
+```
+
+4. **Screen Reader Support**
+```
+Descriptive button labels (not just "Click here")
+Alt text for all meaningful images
+Form labels properly associated with inputs
+Heading hierarchy (H1 → H2 → H3)
+```
+
+**Comprehensive accessibility prompt:**
+```
+Create an accessible contact form:
+
+Fields:
+- Name (required, with aria-required)
+- Email (required, with validation and error message)
+- Subject (dropdown with clear labels)
+- Message (textarea with character count)
+
+Accessibility features:
+- All inputs have visible labels
+- Required fields marked with asterisk and aria-required
+- Error messages with role="alert"
+- Submit button with descriptive text
+- Focus indicators with 3px blue outline
+- Color contrast meets WCAG AA
+- Touch targets 44x44px minimum
+
+Style: Clean, form-focused, high contrast
+Colors: Dark text on light background, red for errors
+```
+
+### Inclusive Design Patterns
+
+**Consider diverse users:**
+
+```
+Design a video player interface that supports:
+- Captions/subtitles toggle
+- Audio description option
+- Keyboard shortcuts (space to play/pause, arrows to seek)
+- Playback speed control
+- High contrast mode
+- Reduced motion option (disable animations)
+```
+
+---
+
+## Performance Optimization
+
+### Optimized Asset Prompts
+
+Request performance-conscious designs from the start.
+
+**Image optimization:**
+```
+E-commerce product gallery with performance optimization:
+- Lazy loading for images below fold
+- Thumbnail images (200x200px) for grid
+- Full-size images (1200x1200px) only on click
+- WebP format with JPEG fallback
+- Blur placeholder while loading
+```
+
+**Code efficiency:**
+```
+Generate lightweight HTML/CSS without:
+- Unnecessary wrapper divs
+- Inline styles (use classes)
+- Large external dependencies
+- Redundant CSS rules
+```
+
+### Progressive Enhancement
+
+Design for core functionality first, then enhance.
+
+**Example:**
+```
+Create a filterable product list with progressive enhancement:
+
+Base (no JavaScript):
+- Server-rendered product grid
+- Form-based filters with submit button
+- Pagination links
+
+Enhanced (with JavaScript):
+- AJAX filter updates without page reload
+- Infinite scroll
+- Smooth animations
+- Real-time search
+```
+
+---
+
+## Component Reusability
+
+### Atomic Design Methodology
+
+Build from atoms → molecules → organisms → templates → pages.
+
+**Atoms (basic elements):**
+```
+Generate design system atoms:
+- Button (primary, secondary, outline, ghost, danger)
+- Input field (text, email, password, search, textarea)
+- Label, Badge, Tag
+- Icon set (24x24px, consistent style)
+- Avatar (circle, square, with status indicator)
+```
+
+**Molecules (simple combinations):**
+```
+Create molecules using atoms:
+- Search bar (input + button + icon)
+- Form field (label + input + error message)
+- Card header (avatar + name + timestamp + menu)
+- Stat card (icon + label + value + trend)
+```
+
+**Organisms (complex components):**
+```
+Build organisms from molecules:
+- Navigation bar (logo + search bar + user menu)
+- Product card (image + title + price + rating + button)
+- Comment thread (avatar + name + timestamp + text + actions)
+- Data table (headers + rows + pagination + filters)
+```
+
+**Templates (page layouts):**
+```
+Compose templates from organisms:
+- Dashboard layout (sidebar + header + content grid)
+- Article layout (header + hero + content + sidebar)
+- Checkout flow (progress + form + summary)
+```
+
+### Variant Generation
+
+Create systematic variations of components.
+
+**Button variants prompt:**
+```
+Generate button component with all variants:
+
+Sizes: Small (32px), Medium (40px), Large (48px)
+
+Types:
+- Primary (filled, brand color)
+- Secondary (filled, gray)
+- Outline (border only)
+- Ghost (transparent, hover background)
+- Danger (filled, red)
+
+States for each:
+- Default
+- Hover
+- Active (pressed)
+- Disabled
+- Loading (with spinner)
+
+Include: Icon support (left/right), full-width option
+```
+
+---
+
+## Advanced Iteration Techniques
+
+### Conditional Variations
+
+Generate multiple versions based on different conditions.
+
+**Example:**
+```
+Create 3 hero section variants for A/B testing:
+
+Variant A - Image-focused:
+- Large background image
+- Minimal text overlay
+- Single CTA button
+
+Variant B - Text-focused:
+- Solid color background
+- Detailed copy with bullet points
+- Two CTA buttons (primary + secondary)
+
+Variant C - Video-focused:
+- Background video
+- Minimal text
+- Play button + CTA
+
+All variants use same brand colors and maintain mobile responsiveness
+```
+
+### State-Based Design
+
+Design for all possible states, not just the happy path.
+
+**Comprehensive state prompt:**
+```
+Design a data table with all states:
+
+Default state:
+- 10 rows of data
+- Sortable columns
+- Pagination
+
+Loading state:
+- Skeleton loaders for rows
+- Disabled controls
+
+Empty state:
+- Illustration
+- "No data found" message
+- "Add new" CTA button
+
+Error state:
+- Error icon
+- Error message
+- "Retry" button
+
+Search/Filter active:
+- Applied filters shown as chips
+- Clear filters option
+- Result count
+
+Selected rows:
+- Checkbox selection
+- Bulk action toolbar
+- Select all option
+```
+
+---
+
+## Export and Handoff Best Practices
+
+### Preparing for Development
+
+Before exporting, ensure designs are developer-ready.
+
+**Pre-export checklist:**
+
+1. **Naming conventions**
+   - Use semantic class names
+   - Follow BEM or consistent methodology
+   - Name components clearly
+
+2. **Documentation**
+   - Add comments for complex interactions
+   - Document responsive breakpoints
+   - Note any required JavaScript behavior
+
+3. **Asset organization**
+   - Export images at correct sizes
+   - Provide SVG for icons
+   - Include font files or CDN links
+
+4. **Specifications**
+   - Document spacing values
+   - List color hex codes
+   - Specify font sizes and weights
+
+### Figma Integration
+
+Optimize Stitch → Figma workflow.
+
+**Steps:**
+```
+1. Generate design in Stitch with detailed specifications
+2. Use "Paste to Figma" export
+3. In Figma:
+   - Organize layers with clear naming
+   - Create components from repeated elements
+   - Set up auto-layout for responsive behavior
+   - Define color and text styles
+   - Add design system documentation
+4. Share with developers using Figma's inspect mode
+```
+
+### Code Export Refinement
+
+Improve exported HTML/CSS for production.
+
+**Post-export tasks:**
+
+1. **Semantic HTML**
+   - Replace divs with semantic tags (header, nav, main, article, section, footer)
+   - Add ARIA labels where needed
+   - Ensure proper heading hierarchy
+
+2. **CSS optimization**
+   - Extract repeated styles into utility classes
+   - Use CSS custom properties for theme values
+   - Organize with methodology (BEM, SMACSS, etc.)
+   - Add responsive media queries if missing
+
+3. **Accessibility**
+   - Add alt text to images
+   - Ensure form labels are associated
+   - Add focus styles
+   - Test with screen reader
+
+4. **Performance**
+   - Optimize images
+   - Minify CSS
+   - Remove unused styles
+   - Add loading strategies
+
+---
+
+## Conclusion
+
+These advanced techniques help you move beyond basic Stitch usage to create production-ready, accessible, and performant designs. Combine these strategies with the core prompting principles to maximize your efficiency and output quality.
+
+**Key takeaways:**
+- Use images and references to accelerate design
+- Establish design systems early for consistency
+- Design responsively from the start
+- Prioritize accessibility in every prompt
+- Think in reusable components
+- Plan for all states, not just happy paths
+- Refine exports before production use

skills/stitch-ui-design/references/prompt-examples.md

@@ -0,0 +1,601 @@
+# Stitch Prompt Examples Library
+
+Comprehensive collection of effective Stitch prompts organized by use case and complexity level.
+
+## Table of Contents
+
+1. [Landing Pages](#landing-pages)
+2. [Mobile Apps](#mobile-apps)
+3. [Dashboards](#dashboards)
+4. [E-commerce](#e-commerce)
+5. [Forms & Authentication](#forms--authentication)
+6. [Content Platforms](#content-platforms)
+7. [SaaS Applications](#saas-applications)
+
+---
+
+## Landing Pages
+
+### Startup Landing Page
+
+```
+Landing page for AI writing assistant startup
+
+Hero Section:
+- Bold headline: "Write Better, Faster with AI"
+- Subheadline explaining value proposition
+- Primary CTA button "Start Free Trial"
+- Secondary CTA "Watch Demo"
+- Hero illustration showing product interface
+
+Features Section:
+- 3-column grid with icons
+- Feature 1: AI-powered suggestions
+- Feature 2: Multi-language support
+- Feature 3: Team collaboration
+
+Social Proof:
+- Customer logos (6 companies)
+- Testimonial cards with photos and quotes
+
+Pricing:
+- 3-tier pricing table (Free, Pro, Enterprise)
+- Feature comparison
+- Annual/Monthly toggle
+
+Style: Modern, tech-forward, trustworthy
+Colors: Deep purple primary, cyan accents, white background
+Typography: Sans-serif, clean and readable
+Platform: Responsive web
+```
+
+### Service Business Landing
+
+```
+Landing page for boutique yoga studio
+
+Above Fold:
+- Full-width hero image of studio space
+- Centered headline: "Find Your Balance"
+- Class schedule CTA button
+- Location and hours overlay
+
+Class Offerings:
+- Card grid (2x3) with class types
+- Each card: class name, duration, difficulty level, instructor photo
+- Hover effect reveals class description
+
+Instructor Profiles:
+- Horizontal scrolling carousel
+- Circular photos with names and specialties
+
+Testimonials:
+- Large quote format with student photos
+- 5-star ratings
+
+Call-to-Action:
+- "Book Your First Class Free" banner
+- Contact form with name, email, phone
+
+Style: Calm, organic, welcoming
+Colors: Sage green, warm beige, soft white
+Typography: Serif headings, sans-serif body
+Platform: Responsive web with mobile-first approach
+```
+
+---
+
+## Mobile Apps
+
+### Fitness Tracking App
+
+```
+Fitness tracking app - Home screen (iOS)
+
+Top Section:
+- Greeting with user name and current date
+- Daily goal progress ring (calories, steps, active minutes)
+- Motivational message based on progress
+
+Quick Stats Cards:
+- Today's steps with trend arrow
+- Active calories burned
+- Distance covered
+- Active time
+
+Recent Workouts:
+- List of last 3 workouts with type, duration, calories
+- Thumbnail icons for workout type
+- Swipe actions for details/delete
+
+Bottom Section:
+- "Start Workout" prominent button
+- Quick access to workout types (Run, Cycle, Strength, Yoga)
+
+Bottom Navigation:
+- Home (active), Workouts, Progress, Profile
+
+Style: Energetic, motivating, data-focused
+Colors: Vibrant orange primary, dark mode background, neon accents
+Typography: Bold headings, clear metrics
+Platform: iOS mobile (375x812px)
+```
+
+### Food Delivery App
+
+```
+Restaurant detail screen for food delivery app
+
+Header:
+- Restaurant cover photo
+- Back button and favorite icon
+- Restaurant name, rating (4.5 stars), delivery time (25-35 min)
+- Cuisine tags (Italian, Pizza, Pasta)
+
+Info Bar:
+- Delivery fee, minimum order, distance
+- Promo badge if applicable
+
+Menu Categories:
+- Sticky horizontal scroll tabs (Popular, Pizza, Pasta, Salads, Drinks)
+
+Menu Items:
+- Card layout with food photo, name, description, price
+- Add button with quantity selector
+- Dietary icons (vegetarian, spicy, etc.)
+
+Floating Cart:
+- Bottom sheet showing cart summary
+- Item count and total price
+- "View Cart" button
+
+Style: Appetite-appealing, easy to scan, vibrant
+Colors: Red primary (hunger-inducing), white background, food photography
+Typography: Friendly sans-serif
+Platform: Android mobile (360x800px)
+```
+
+---
+
+## Dashboards
+
+### Analytics Dashboard
+
+```
+Web analytics dashboard for marketing team
+
+Top Bar:
+- Date range selector (last 7 days, 30 days, custom)
+- Export button
+- Notification bell
+- User profile dropdown
+
+Key Metrics Row:
+- 4 metric cards in a row
+- Card 1: Total visitors (with % change)
+- Card 2: Conversion rate (with trend sparkline)
+- Card 3: Bounce rate (with comparison to previous period)
+- Card 4: Average session duration
+
+Main Chart:
+- Line chart showing traffic over time
+- Multiple lines for different sources (Organic, Paid, Social, Direct)
+- Interactive legend to toggle lines
+- Hover tooltips with exact values
+
+Secondary Panels:
+- Left: Top pages table (page, views, avg time, bounce rate)
+- Right: Traffic sources pie chart with percentages
+
+Bottom Section:
+- Recent conversions table with user, source, value, timestamp
+
+Style: Clean, data-focused, professional
+Colors: Navy blue sidebar, white main area, colorful chart lines
+Typography: Monospace for numbers, sans-serif for labels
+Platform: Desktop web (1440px+)
+```
+
+### Project Management Dashboard
+
+```
+Project management dashboard - Team view
+
+Sidebar:
+- Workspace selector dropdown
+- Navigation: Dashboard, Projects, Tasks, Team, Reports
+- Create new project button
+
+Header:
+- Project name and status badge
+- Team member avatars (max 5, then +N)
+- Search bar
+- View options (Board, List, Calendar)
+
+Kanban Board:
+- 4 columns: To Do, In Progress, Review, Done
+- Drag-and-drop cards
+- Each card shows: title, assignee avatar, due date, priority label, comment count
+- Add card button at bottom of each column
+
+Right Panel:
+- Task details when card is selected
+- Description, attachments, comments, activity log
+
+Quick Stats:
+- Progress bar showing completion percentage
+- Tasks by status mini chart
+- Upcoming deadlines list
+
+Style: Modern, organized, collaborative
+Colors: Purple primary, light gray background, status color coding
+Typography: Clear sans-serif, readable at all sizes
+Platform: Desktop web (1280px+)
+```
+
+---
+
+## E-commerce
+
+### Product Detail Page
+
+```
+Product detail page for fashion e-commerce
+
+Image Gallery:
+- Main product image (large, zoomable)
+- Thumbnail strip below (5-6 images)
+- 360° view option
+- Video thumbnail if available
+
+Product Info:
+- Brand name
+- Product title
+- Star rating (4.8) with review count (234 reviews)
+- Price with original price struck through if on sale
+- Sale badge if applicable
+
+Options:
+- Size selector (XS, S, M, L, XL) with availability indicators
+- Color swatches with product image preview on hover
+- Quantity selector
+
+Actions:
+- Add to Cart button (prominent)
+- Add to Wishlist button (outline)
+- Size guide link
+- Shipping calculator
+
+Product Details:
+- Tabbed interface (Description, Specifications, Reviews, Shipping)
+- Expandable sections on mobile
+
+Recommendations:
+- "You May Also Like" carousel
+- "Complete the Look" suggestions
+
+Style: Clean, product-focused, trustworthy
+Colors: Black and white with brand accent color (burgundy)
+Typography: Elegant serif for headings, sans-serif for body
+Platform: Responsive web
+```
+
+### Shopping Cart
+
+```
+Shopping cart page with checkout flow
+
+Cart Items:
+- List of products with thumbnail, name, size/color, price
+- Quantity adjuster (+/- buttons)
+- Remove item link
+- Save for later option
+
+Order Summary:
+- Sticky sidebar on desktop, bottom sheet on mobile
+- Subtotal
+- Shipping (calculated or "Free over $50")
+- Tax (estimated)
+- Discount code input field
+- Total (prominent)
+- Checkout button (large, primary color)
+
+Trust Signals:
+- Secure checkout badge
+- Free returns policy
+- Customer service contact
+
+Recommendations:
+- "Frequently Bought Together" section
+- Promotional banner for free shipping threshold
+
+Empty State:
+- Illustration
+- "Your cart is empty" message
+- "Continue Shopping" button
+- Recently viewed items
+
+Style: Clean, conversion-focused, reassuring
+Colors: Green for checkout CTA, neutral grays, trust badges
+Typography: Clear pricing, readable product names
+Platform: Responsive web
+```
+
+---
+
+## Forms & Authentication
+
+### Multi-Step Signup Form
+
+```
+B2B SaaS signup flow - 3 steps
+
+Progress Indicator:
+- Step 1: Account (active)
+- Step 2: Company
+- Step 3: Team
+
+Step 1 - Account Details:
+- Email input with validation
+- Password input with strength indicator
+- Confirm password
+- Terms and conditions checkbox
+- "Continue" button
+- "Already have an account? Sign in" link
+
+Step 2 - Company Information:
+- Company name
+- Industry dropdown
+- Company size radio buttons (1-10, 11-50, 51-200, 201+)
+- Role/Title input
+- "Back" and "Continue" buttons
+
+Step 3 - Invite Team:
+- Email input fields (dynamic, add more)
+- Role selector for each invite
+- "Skip for now" option
+- "Finish Setup" button
+
+Success State:
+- Checkmark animation
+- "Welcome to [Product]!" message
+- "Go to Dashboard" button
+
+Style: Minimal, focused, low-friction
+Colors: Blue primary, white background, green success states
+Typography: Clear labels, helpful microcopy
+Platform: Responsive web, mobile-optimized
+```
+
+### Login Page
+
+```
+Login page for enterprise software
+
+Left Panel (Desktop):
+- Brand logo
+- Hero image or illustration
+- Value proposition headline
+- Key benefits (3 bullet points)
+
+Right Panel (Form):
+- "Welcome back" heading
+- Email input field
+- Password input field with show/hide toggle
+- "Remember me" checkbox
+- "Forgot password?" link
+- "Sign In" button (full width)
+- Divider with "OR"
+- SSO options (Google, Microsoft, Okta) as buttons with logos
+- "Don't have an account? Sign up" link at bottom
+
+Security Indicators:
+- SSL badge
+- "Your data is secure" message
+
+Style: Professional, trustworthy, enterprise-grade
+Colors: Corporate blue, white, subtle grays
+Typography: Professional sans-serif
+Platform: Responsive (left panel hidden on mobile)
+```
+
+---
+
+## Content Platforms
+
+### Blog Post Layout
+
+```
+Blog article page for tech publication
+
+Header:
+- Site navigation (logo, categories, search, subscribe)
+
+Article Header:
+- Category tag
+- Article title (large, bold)
+- Subtitle/excerpt
+- Author info (photo, name, bio link, publish date)
+- Social share buttons
+- Reading time estimate
+
+Article Body:
+- Readable column width (max 680px)
+- Paragraph text with proper line height
+- H2 and H3 subheadings
+- Pull quotes (styled distinctly)
+- Inline images with captions
+- Code blocks with syntax highlighting
+- Embedded videos
+- Table of contents (sticky sidebar on desktop)
+
+Article Footer:
+- Tags
+- Share buttons
+- Author card (expanded)
+- Related articles (3 cards)
+- Comments section
+
+Sidebar (Desktop):
+- Newsletter signup
+- Popular posts
+- Ad placement
+
+Style: Editorial, readable, content-first
+Colors: Black text on white, accent color for links
+Typography: Serif for body text, sans-serif for UI
+Platform: Responsive web
+```
+
+### Video Platform Interface
+
+```
+Video streaming platform - Watch page
+
+Video Player:
+- Full-width video player with controls
+- Quality selector, playback speed, captions, fullscreen
+- Progress bar with thumbnail preview on hover
+
+Video Info:
+- Video title
+- View count and upload date
+- Like/Dislike buttons
+- Share button
+- Save to playlist button
+
+Channel Info:
+- Channel avatar and name
+- Subscriber count
+- Subscribe button (prominent if not subscribed)
+
+Description:
+- Expandable description text
+- Show more/less toggle
+- Hashtags and links
+
+Comments Section:
+- Sort options (Top, Newest)
+- Comment input with user avatar
+- Comment cards with avatar, name, timestamp, text
+- Like/Reply buttons
+- Nested replies (indented)
+
+Sidebar:
+- Up next autoplay preview
+- Recommended videos list (thumbnail, title, channel, views)
+
+Style: Dark mode, video-focused, minimal distractions
+Colors: Dark gray background, white text, red accent for CTAs
+Typography: Sans-serif, readable at distance
+Platform: Responsive web
+```
+
+---
+
+## SaaS Applications
+
+### Email Client Interface
+
+```
+Email client - Inbox view
+
+Left Sidebar:
+- Compose button (prominent)
+- Folder list (Inbox, Sent, Drafts, Spam, Trash)
+- Labels/Tags with color coding
+- Storage usage indicator
+
+Email List (Center):
+- Search bar with filters
+- Sort and view options
+- Email rows showing:
+  - Sender avatar/initial
+  - Sender name (bold if unread)
+  - Subject line
+  - Preview text (truncated)
+  - Timestamp
+  - Attachment icon if present
+  - Star/flag icons
+- Checkbox for bulk actions
+- Pagination or infinite scroll
+
+Email Detail (Right):
+- Email header (from, to, cc, timestamp)
+- Subject line
+- Email body with formatting preserved
+- Attachments section
+- Action buttons (Reply, Reply All, Forward, Archive, Delete)
+- Previous emails in thread (collapsed)
+
+Top Bar:
+- Refresh button
+- Settings icon
+- User profile dropdown
+
+Style: Clean, productivity-focused, organized
+Colors: Blue accents, white background, gray dividers
+Typography: Sans-serif, scannable
+Platform: Desktop web (1280px+)
+```
+
+### CRM Contact Detail
+
+```
+CRM contact detail page
+
+Header:
+- Contact name and company
+- Contact photo/avatar
+- Status badge (Lead, Customer, Inactive)
+- Quick actions (Email, Call, Schedule Meeting, Edit)
+
+Info Tabs:
+- Overview (active), Activity, Deals, Notes, Files
+
+Overview Tab:
+- Contact information card (email, phone, address, social links)
+- Company information card
+- Tags and custom fields
+- Assigned to (team member)
+
+Activity Timeline:
+- Chronological list of interactions
+- Icons for type (email, call, meeting, note)
+- Timestamp and description
+- Filter by activity type
+
+Deals Section:
+- Active deals table (deal name, value, stage, close date)
+- Won/Lost deals summary
+
+Notes Section:
+- Add note input with rich text editor
+- Note cards with author, timestamp, content
+- Pin important notes
+
+Right Sidebar:
+- Next scheduled activity
+- Recent emails
+- Related contacts
+- Deal pipeline stage
+
+Style: Professional, data-rich, organized
+Colors: Navy blue, white, status color coding
+Typography: Clear hierarchy, readable data
+Platform: Desktop web (1440px+)
+```
+
+---
+
+## Tips for Using These Examples
+
+1. **Customize for your needs** - Replace placeholder content with your specific requirements
+2. **Combine elements** - Mix and match components from different examples
+3. **Adjust complexity** - Simplify or expand based on your project scope
+4. **Specify your brand** - Add your color palette, fonts, and visual style
+5. **Consider platform** - Adapt layouts for your target device (mobile/desktop)
+6. **Add context** - Include user personas or use cases for better results
+7. **Iterate** - Start with a basic prompt, then refine with annotations
+
+Remember: These are starting points. Stitch works best when you provide specific details relevant to your unique project.

skills/superpowers-lab/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: superpowers-lab
+description: "Lab environment for Claude superpowers"
+source: "https://github.com/obra/superpowers-lab"
+risk: safe
+---
+
+# Superpowers Lab
+
+## Overview
+
+Lab environment for Claude superpowers
+
+## When to Use This Skill
+
+Use this skill when you need to work with lab environment for claude superpowers.
+
+## Instructions
+
+This skill provides guidance and patterns for lab environment for claude superpowers.
+
+For more information, see the [source repository](https://github.com/obra/superpowers-lab).

skills/swiftui-expert-skill/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: swiftui-expert-skill
+description: "Write, review, or improve SwiftUI code following best practices for state management, view composition, performance, modern APIs, Swift concurrency, and iOS 26+ Liquid Glass adoption. Use when building new SwiftUI features, refactoring existing views, reviewing code quality, or adopting modern SwiftUI patterns."
+source: "https://github.com/AvdLee/SwiftUI-Agent-Skill/tree/main/swiftui-expert-skill"
+risk: safe
+---
+
+# SwiftUI Expert Skill
+
+## Overview
+Use this skill to build, review, or improve SwiftUI features with correct state management, modern API usage, Swift concurrency best practices, optimal view composition, and iOS 26+ Liquid Glass styling. Prioritize native APIs, Apple design guidance, and performance-conscious patterns. This skill focuses on facts and best practices without enforcing specific architectural patterns.
+
+## When to Use This Skill
+
+Use this skill when:
+- Building new SwiftUI features
+- Refactoring existing SwiftUI views
+- Reviewing SwiftUI code quality
+- Adopting modern SwiftUI patterns
+- Working with SwiftUI state management
+- Implementing iOS 26+ Liquid Glass styling
+
+## Workflow Decision Tree
+
+### 1) Review existing SwiftUI code
+- Check property wrapper usage against the selection guide (see `references/state-management.md`)
+- Verify modern API usage (see `references/modern-apis.md`)
+- Verify view composition follows extraction rules (see `references/view-structure.md`)
+- Check performance patterns are applied (see `references/performance-patterns.md`)
+- Verify list patterns use stable identity (see `references/list-patterns.md`)
+- Inspect Liquid Glass usage for correctness and consistency (see `references/liquid-glass.md`)
+- Validate iOS 26+ availability handling with sensible fallbacks
+
+### 2) Improve existing SwiftUI code
+- Audit state management for correct wrapper selection (prefer `@Observable` over `ObservableObject`)
+- Replace deprecated APIs with modern equivalents (see `references/modern-apis.md`)
+- Extract complex views into separate subviews (see `references/view-structure.md`)
+- Refactor hot paths to minimize redundant state updates (see `references/performance-patterns.md`)
+- Ensure ForEach uses stable identity (see `references/list-patterns.md`)
+- Suggest image downsampling when `UIImage(data:)` is used (as optional optimization, see `references/image-optimization.md`)
+- Adopt Liquid Glass only when explicitly requested by the user
+
+### 3) Implement new SwiftUI feature
+- Design data flow first: identify owned vs injected state (see `references/state-management.md`)
+- Use modern APIs (no deprecated modifiers or patterns, see `references/modern-apis.md`)
+- Use `@Observable` for shared state (with `@MainActor` if not using default actor isolation)
+- Structure views for optimal diffing (extract subviews early, keep views small, see `references/view-structure.md`)
+- Separate business logic into testable models (see `references/layout-best-practices.md`)
+- Apply glass effects after layout/appearance modifiers (see `references/liquid-glass.md`)
+- Gate iOS 26+ features with `#available` and provide fallbacks
+
+## Core Guidelines
+
+### State Management
+- **Always prefer `@Observable` over `ObservableObject`** for new code
+- **Mark `@Observable` classes with `@MainActor`** unless using default actor isolation
+- **Always mark `@State` and `@StateObject` as `private`** (makes dependencies clear)
+- **Never declare passed values as `@State` or `@StateObject`** (they only accept initial values)
+- Use `@State` with `@Observable` classes (not `@StateObject`)
+- `@Binding` only when child needs to **modify** parent state
+- `@Bindable` for injected `@Observable` objects needing bindings
+- Use `let` for read-only values; `var` + `.onChange()` for reactive reads
+- Legacy: `@StateObject` for owned `ObservableObject`; `@ObservedObject` for injected
+- Nested `ObservableObject` doesn't work (pass nested objects directly); `@Observable` handles nesting fine
+
+### Modern APIs
+- Use `foregroundStyle()` instead of `foregroundColor()`
+- Use `clipShape(.rect(cornerRadius:))` instead of `cornerRadius()`
+- Use `Tab` API instead of `tabItem()`
+- Use `Button` instead of `onTapGesture()` (unless need location/count)
+- Use `NavigationStack` instead of `NavigationView`
+- Use `navigationDestination(for:)` for type-safe navigation
+- Use two-parameter or no-parameter `onChange()` variant
+- Use `ImageRenderer` for rendering SwiftUI views
+- Use `.sheet(item:)` instead of `.sheet(isPresented:)` for model-based content
+- Sheets should own their actions and call `dismiss()` internally
+- Use `ScrollViewReader` for programmatic scrolling with stable IDs
+- Avoid `UIScreen.main.bounds` for sizing
+- Avoid `GeometryReader` when alternatives exist (e.g., `containerRelativeFrame()`)
+
+### Swift Best Practices
+- Use modern Text formatting (`.format` parameters, not `String(format:)`)
+- Use `localizedStandardContains()` for user-input filtering (not `contains()`)
+- Prefer static member lookup (`.blue` vs `Color.blue`)
+- Use `.task` modifier for automatic cancellation of async work
+- Use `.task(id:)` for value-dependent tasks
+
+### View Composition
+- **Prefer modifiers over conditional views** for state changes (maintains view identity)
+- Extract complex views into separate subviews for better readability and performance
+- Keep views small for optimal performance
+- Keep view `body` simple and pure (no side effects or complex logic)
+- Use `@ViewBuilder` functions only for small, simple sections
+- Prefer `@ViewBuilder let content: Content` over closure-based content properties
+- Separate business logic into testable models (not about enforcing architectures)
+- Action handlers should reference methods, not contain inline logic
+- Use relative layout over hard-coded constants
+- Views should work in any context (don't assume screen size or presentation style)
+
+### Performance
+- Pass only needed values to views (avoid large "config" or "context" objects)
+- Eliminate unnecessary dependencies to reduce update fan-out
+- Check for value changes before assigning state in hot paths
+- Avoid redundant state updates in `onReceive`, `onChange`, scroll handlers
+- Minimize work in frequently executed code paths
+- Use `LazyVStack`/`LazyHStack` for large lists
+- Use stable identity for `ForEach` (never `.indices` for dynamic content)
+- Ensure constant number of views per `ForEach` element
+- Avoid inline filtering in `ForEach` (prefilter and cache)
+- Avoid `AnyView` in list rows
+- Consider POD views for fast diffing (or wrap expensive views in POD parents)
+- Suggest image downsampling when `UIImage(data:)` is encountered (as optional optimization)
+- Avoid layout thrash (deep hierarchies, excessive `GeometryReader`)
+- Gate frequent geometry updates by thresholds
+- Use `Self._printChanges()` to debug unexpected view updates
+
+### Liquid Glass (iOS 26+)
+**Only adopt when explicitly requested by the user.**
+- Use native `glassEffect`, `GlassEffectContainer`, and glass button styles
+- Wrap multiple glass elements in `GlassEffectContainer`
+- Apply `.glassEffect()` after layout and visual modifiers
+- Use `.interactive()` only for tappable/focusable elements
+- Use `glassEffectID` with `@Namespace` for morphing transitions
+
+## Quick Reference
+
+### Property Wrapper Selection (Modern)
+| Wrapper | Use When |
+|---------|----------|
+| `@State` | Internal view state (must be `private`), or owned `@Observable` class |
+| `@Binding` | Child modifies parent's state |
+| `@Bindable` | Injected `@Observable` needing bindings |
+| `let` | Read-only value from parent |
+| `var` | Read-only value watched via `.onChange()` |
+
+**Legacy (Pre-iOS 17):**
+| Wrapper | Use When |
+|---------|----------|
+| `@StateObject` | View owns an `ObservableObject` (use `@State` with `@Observable` instead) |
+| `@ObservedObject` | View receives an `ObservableObject` |
+
+### Modern API Replacements
+| Deprecated | Modern Alternative |
+|------------|-------------------|
+| `foregroundColor()` | `foregroundStyle()` |
+| `cornerRadius()` | `clipShape(.rect(cornerRadius:))` |
+| `tabItem()` | `Tab` API |
+| `onTapGesture()` | `Button` (unless need location/count) |
+| `NavigationView` | `NavigationStack` |
+| `onChange(of:) { value in }` | `onChange(of:) { old, new in }` or `onChange(of:) { }` |
+| `fontWeight(.bold)` | `bold()` |
+| `GeometryReader` | `containerRelativeFrame()` or `visualEffect()` |
+| `showsIndicators: false` | `.scrollIndicators(.hidden)` |
+| `String(format: "%.2f", value)` | `Text(value, format: .number.precision(.fractionLength(2)))` |
+| `string.contains(search)` | `string.localizedStandardContains(search)` (for user input) |
+
+### Liquid Glass Patterns
+```swift
+// Basic glass effect with fallback
+if #available(iOS 26, *) {
+    content
+        .padding()
+        .glassEffect(.regular.interactive(), in: .rect(cornerRadius: 16))
+} else {
+    content
+        .padding()
+        .background(.ultraThinMaterial, in: RoundedRectangle(cornerRadius: 16))
+}
+
+// Grouped glass elements
+GlassEffectContainer(spacing: 24) {
+    HStack(spacing: 24) {
+        GlassButton1()
+        GlassButton2()
+    }
+}
+
+// Glass buttons
+Button("Confirm") { }
+    .buttonStyle(.glassProminent)
+```
+
+## Review Checklist
+
+### State Management
+- [ ] Using `@Observable` instead of `ObservableObject` for new code
+- [ ] `@Observable` classes marked with `@MainActor` (if needed)
+- [ ] Using `@State` with `@Observable` classes (not `@StateObject`)
+- [ ] `@State` and `@StateObject` properties are `private`
+- [ ] Passed values NOT declared as `@State` or `@StateObject`
+- [ ] `@Binding` only where child modifies parent state
+- [ ] `@Bindable` for injected `@Observable` needing bindings
+- [ ] Nested `ObservableObject` avoided (or passed directly to child views)
+
+### Modern APIs (see `references/modern-apis.md`)
+- [ ] Using `foregroundStyle()` instead of `foregroundColor()`
+- [ ] Using `clipShape(.rect(cornerRadius:))` instead of `cornerRadius()`
+- [ ] Using `Tab` API instead of `tabItem()`
+- [ ] Using `Button` instead of `onTapGesture()` (unless need location/count)
+- [ ] Using `NavigationStack` instead of `NavigationView`
+- [ ] Avoiding `UIScreen.main.bounds`
+- [ ] Using alternatives to `GeometryReader` when possible
+- [ ] Button images include text labels for accessibility
+
+### Sheets & Navigation (see `references/sheet-navigation-patterns.md`)
+- [ ] Using `.sheet(item:)` for model-based sheets
+- [ ] Sheets own their actions and dismiss internally
+- [ ] Using `navigationDestination(for:)` for type-safe navigation
+
+### ScrollView (see `references/scroll-patterns.md`)
+- [ ] Using `ScrollViewReader` with stable IDs for programmatic scrolling
+- [ ] Using `.scrollIndicators(.hidden)` instead of initializer parameter
+
+### Text & Formatting (see `references/text-formatting.md`)
+- [ ] Using modern Text formatting (not `String(format:)`)
+- [ ] Using `localizedStandardContains()` for search filtering
+
+### View Structure (see `references/view-structure.md`)
+- [ ] Using modifiers instead of conditionals for state changes
+- [ ] Complex views extracted to separate subviews
+- [ ] Views kept small for performance
+- [ ] Container views use `@ViewBuilder let content: Content`
+
+### Performance (see `references/performance-patterns.md`)
+- [ ] View `body` kept simple and pure (no side effects)
+- [ ] Passing only needed values (not large config objects)
+- [ ] Eliminating unnecessary dependencies
+- [ ] State updates check for value changes before assigning
+- [ ] Hot paths minimize state updates
+- [ ] No object creation in `body`
+- [ ] Heavy computation moved out of `body`
+
+### List Patterns (see `references/list-patterns.md`)
+- [ ] ForEach uses stable identity (not `.indices`)
+- [ ] Constant number of views per ForEach element
+- [ ] No inline filtering in ForEach
+- [ ] No `AnyView` in list rows
+
+### Layout (see `references/layout-best-practices.md`)
+- [ ] Avoiding layout thrash (deep hierarchies, excessive GeometryReader)
+- [ ] Gating frequent geometry updates by thresholds
+- [ ] Business logic separated into testable models
+- [ ] Action handlers reference methods (not inline logic)
+- [ ] Using relative layout (not hard-coded constants)
+- [ ] Views work in any context (context-agnostic)
+
+### Liquid Glass (iOS 26+)
+- [ ] `#available(iOS 26, *)` with fallback for Liquid Glass
+- [ ] Multiple glass views wrapped in `GlassEffectContainer`
+- [ ] `.glassEffect()` applied after layout/appearance modifiers
+- [ ] `.interactive()` only on user-interactable elements
+- [ ] Shapes and tints consistent across related elements
+
+## References
+- `references/state-management.md` - Property wrappers and data flow (prefer `@Observable`)
+- `references/view-structure.md` - View composition, extraction, and container patterns
+- `references/performance-patterns.md` - Performance optimization techniques and anti-patterns
+- `references/list-patterns.md` - ForEach identity, stability, and list best practices
+- `references/layout-best-practices.md` - Layout patterns, context-agnostic views, and testability
+- `references/modern-apis.md` - Modern API usage and deprecated replacements
+- `references/sheet-navigation-patterns.md` - Sheet presentation and navigation patterns
+- `references/scroll-patterns.md` - ScrollView patterns and programmatic scrolling
+- `references/text-formatting.md` - Modern text formatting and string operations
+- `references/image-optimization.md` - AsyncImage, image downsampling, and optimization
+- `references/liquid-glass.md` - iOS 26+ Liquid Glass API
+
+## Philosophy
+
+This skill focuses on **facts and best practices**, not architectural opinions:
+- We don't enforce specific architectures (e.g., MVVM, VIPER)
+- We do encourage separating business logic for testability
+- We prioritize modern APIs over deprecated ones
+- We emphasize thread safety with `@MainActor` and `@Observable`
+- We optimize for performance and maintainability
+- We follow Apple's Human Interface Guidelines and API design patterns

skills/terraform-skill/SKILL.md

@@ -0,0 +1,517 @@
+---
+name: terraform-skill
+description: "Terraform infrastructure as code best practices"
+license: Apache-2.0
+metadata: 
+author: "Anton Babenko"
+version: 1.5.0
+source: "https://github.com/antonbabenko/terraform-skill"
+risk: safe
+---
+# Terraform Skill for Claude
+
+Comprehensive Terraform and OpenTofu guidance covering testing, modules, CI/CD, and production patterns. Based on terraform-best-practices.com and enterprise experience.
+
+## When to Use This Skill
+
+**Activate this skill when:**
+- Creating new Terraform or OpenTofu configurations or modules
+- Setting up testing infrastructure for IaC code
+- Deciding between testing approaches (validate, plan, frameworks)
+- Structuring multi-environment deployments
+- Implementing CI/CD for infrastructure-as-code
+- Reviewing or refactoring existing Terraform/OpenTofu projects
+- Choosing between module patterns or state management approaches
+
+**Don't use this skill for:**
+- Basic Terraform/OpenTofu syntax questions (Claude knows this)
+- Provider-specific API reference (link to docs instead)
+- Cloud platform questions unrelated to Terraform/OpenTofu
+
+## Core Principles
+
+### 1. Code Structure Philosophy
+
+**Module Hierarchy:**
+
+| Type | When to Use | Scope |
+|------|-------------|-------|
+| **Resource Module** | Single logical group of connected resources | VPC + subnets, Security group + rules |
+| **Infrastructure Module** | Collection of resource modules for a purpose | Multiple resource modules in one region/account |
+| **Composition** | Complete infrastructure | Spans multiple regions/accounts |
+
+**Hierarchy:** Resource → Resource Module → Infrastructure Module → Composition
+
+**Directory Structure:**
+```
+environments/        # Environment-specific configurations
+├── prod/
+├── staging/
+└── dev/
+
+modules/            # Reusable modules
+├── networking/
+├── compute/
+└── data/
+
+examples/           # Module usage examples (also serve as tests)
+├── complete/
+└── minimal/
+```
+
+**Key principle from terraform-best-practices.com:**
+- Separate **environments** (prod, staging) from **modules** (reusable components)
+- Use **examples/** as both documentation and integration test fixtures
+- Keep modules small and focused (single responsibility)
+
+**For detailed module architecture, see:** [Code Patterns: Module Types & Hierarchy](references/code-patterns.md)
+
+### 2. Naming Conventions
+
+**Resources:**
+```hcl
+# Good: Descriptive, contextual
+resource "aws_instance" "web_server" { }
+resource "aws_s3_bucket" "application_logs" { }
+
+# Good: "this" for singleton resources (only one of that type)
+resource "aws_vpc" "this" { }
+resource "aws_security_group" "this" { }
+
+# Avoid: Generic names for non-singletons
+resource "aws_instance" "main" { }
+resource "aws_s3_bucket" "bucket" { }
+```
+
+**Singleton Resources:**
+
+Use `"this"` when your module creates only one resource of that type:
+
+✅ DO:
+```hcl
+resource "aws_vpc" "this" {}           # Module creates one VPC
+resource "aws_security_group" "this" {}  # Module creates one SG
+```
+
+❌ DON'T use "this" for multiple resources:
+```hcl
+resource "aws_subnet" "this" {}  # If creating multiple subnets
+```
+
+Use descriptive names when creating multiple resources of the same type.
+
+**Variables:**
+```hcl
+# Prefix with context when needed
+var.vpc_cidr_block          # Not just "cidr"
+var.database_instance_class # Not just "instance_class"
+```
+
+**Files:**
+- `main.tf` - Primary resources
+- `variables.tf` - Input variables
+- `outputs.tf` - Output values
+- `versions.tf` - Provider versions
+- `data.tf` - Data sources (optional)
+
+## Testing Strategy Framework
+
+### Decision Matrix: Which Testing Approach?
+
+| Your Situation | Recommended Approach | Tools | Cost |
+|----------------|---------------------|-------|------|
+| **Quick syntax check** | Static analysis | `terraform validate`, `fmt` | Free |
+| **Pre-commit validation** | Static + lint | `validate`, `tflint`, `trivy`, `checkov` | Free |
+| **Terraform 1.6+, simple logic** | Native test framework | Built-in `terraform test` | Free-Low |
+| **Pre-1.6, or Go expertise** | Integration testing | Terratest | Low-Med |
+| **Security/compliance focus** | Policy as code | OPA, Sentinel | Free |
+| **Cost-sensitive workflow** | Mock providers (1.7+) | Native tests + mocking | Free |
+| **Multi-cloud, complex** | Full integration | Terratest + real infra | Med-High |
+
+### Testing Pyramid for Infrastructure
+
+```
+        /\
+       /  \          End-to-End Tests (Expensive)
+      /____\         - Full environment deployment
+     /      \        - Production-like setup
+    /________\
+   /          \      Integration Tests (Moderate)
+  /____________\     - Module testing in isolation
+ /              \    - Real resources in test account
+/________________\   Static Analysis (Cheap)
+                     - validate, fmt, lint
+                     - Security scanning
+```
+
+### Native Test Best Practices (1.6+)
+
+**Before generating test code:**
+
+1. **Validate schemas with Terraform MCP:**
+   ```
+   Search provider docs → Get resource schema → Identify block types
+   ```
+
+2. **Choose correct command mode:**
+   - `command = plan` - Fast, for input validation
+   - `command = apply` - Required for computed values and set-type blocks
+
+3. **Handle set-type blocks correctly:**
+   - Cannot index with `[0]`
+   - Use `for` expressions to iterate
+   - Or use `command = apply` to materialize
+
+**Common patterns:**
+- S3 encryption rules: **set** (use for expressions)
+- Lifecycle transitions: **set** (use for expressions)
+- IAM policy statements: **set** (use for expressions)
+
+**For detailed testing guides, see:**
+- **[Testing Frameworks Guide](references/testing-frameworks.md)** - Deep dive into static analysis, native tests, and Terratest
+- **[Quick Reference](references/quick-reference.md#testing-approach-selection)** - Decision flowchart and command cheat sheet
+
+## Code Structure Standards
+
+### Resource Block Ordering
+
+**Strict ordering for consistency:**
+1. `count` or `for_each` FIRST (blank line after)
+2. Other arguments
+3. `tags` as last real argument
+4. `depends_on` after tags (if needed)
+5. `lifecycle` at the very end (if needed)
+
+```hcl
+# ✅ GOOD - Correct ordering
+resource "aws_nat_gateway" "this" {
+  count = var.create_nat_gateway ? 1 : 0
+
+  allocation_id = aws_eip.this[0].id
+  subnet_id     = aws_subnet.public[0].id
+
+  tags = {
+    Name = "${var.name}-nat"
+  }
+
+  depends_on = [aws_internet_gateway.this]
+
+  lifecycle {
+    create_before_destroy = true
+  }
+}
+```
+
+### Variable Block Ordering
+
+1. `description` (ALWAYS required)
+2. `type`
+3. `default`
+4. `validation`
+5. `nullable` (when setting to false)
+
+```hcl
+variable "environment" {
+  description = "Environment name for resource tagging"
+  type        = string
+  default     = "dev"
+
+  validation {
+    condition     = contains(["dev", "staging", "prod"], var.environment)
+    error_message = "Environment must be one of: dev, staging, prod."
+  }
+
+  nullable = false
+}
+```
+
+**For complete structure guidelines, see:** [Code Patterns: Block Ordering & Structure](references/code-patterns.md#block-ordering--structure)
+
+## Count vs For_Each: When to Use Each
+
+### Quick Decision Guide
+
+| Scenario | Use | Why |
+|----------|-----|-----|
+| Boolean condition (create or don't) | `count = condition ? 1 : 0` | Simple on/off toggle |
+| Simple numeric replication | `count = 3` | Fixed number of identical resources |
+| Items may be reordered/removed | `for_each = toset(list)` | Stable resource addresses |
+| Reference by key | `for_each = map` | Named access to resources |
+| Multiple named resources | `for_each` | Better maintainability |
+
+### Common Patterns
+
+**Boolean conditions:**
+```hcl
+# ✅ GOOD - Boolean condition
+resource "aws_nat_gateway" "this" {
+  count = var.create_nat_gateway ? 1 : 0
+  # ...
+}
+```
+
+**Stable addressing with for_each:**
+```hcl
+# ✅ GOOD - Removing "us-east-1b" only affects that subnet
+resource "aws_subnet" "private" {
+  for_each = toset(var.availability_zones)
+
+  availability_zone = each.key
+  # ...
+}
+
+# ❌ BAD - Removing middle AZ recreates all subsequent subnets
+resource "aws_subnet" "private" {
+  count = length(var.availability_zones)
+
+  availability_zone = var.availability_zones[count.index]
+  # ...
+}
+```
+
+**For migration guides and detailed examples, see:** [Code Patterns: Count vs For_Each](references/code-patterns.md#count-vs-for_each-deep-dive)
+
+## Locals for Dependency Management
+
+**Use locals to ensure correct resource deletion order:**
+
+```hcl
+# Problem: Subnets might be deleted after CIDR blocks, causing errors
+# Solution: Use try() in locals to hint deletion order
+
+locals {
+  # References secondary CIDR first, falling back to VPC
+  # Forces Terraform to delete subnets before CIDR association
+  vpc_id = try(
+    aws_vpc_ipv4_cidr_block_association.this[0].vpc_id,
+    aws_vpc.this.id,
+    ""
+  )
+}
+
+resource "aws_vpc" "this" {
+  cidr_block = "10.0.0.0/16"
+}
+
+resource "aws_vpc_ipv4_cidr_block_association" "this" {
+  count = var.add_secondary_cidr ? 1 : 0
+
+  vpc_id     = aws_vpc.this.id
+  cidr_block = "10.1.0.0/16"
+}
+
+resource "aws_subnet" "public" {
+  vpc_id     = local.vpc_id  # Uses local, not direct reference
+  cidr_block = "10.1.0.0/24"
+}
+```
+
+**Why this matters:**
+- Prevents deletion errors when destroying infrastructure
+- Ensures correct dependency order without explicit `depends_on`
+- Particularly useful for VPC configurations with secondary CIDR blocks
+
+**For detailed examples, see:** [Code Patterns: Locals for Dependency Management](references/code-patterns.md#locals-for-dependency-management)
+
+## Module Development
+
+### Standard Module Structure
+
+```
+my-module/
+├── README.md           # Usage documentation
+├── main.tf             # Primary resources
+├── variables.tf        # Input variables with descriptions
+├── outputs.tf          # Output values
+├── versions.tf         # Provider version constraints
+├── examples/
+│   ├── minimal/        # Minimal working example
+│   └── complete/       # Full-featured example
+└── tests/              # Test files
+    └── module_test.tftest.hcl  # Or .go
+```
+
+### Best Practices Summary
+
+**Variables:**
+- ✅ Always include `description`
+- ✅ Use explicit `type` constraints
+- ✅ Provide sensible `default` values where appropriate
+- ✅ Add `validation` blocks for complex constraints
+- ✅ Use `sensitive = true` for secrets
+
+**Outputs:**
+- ✅ Always include `description`
+- ✅ Mark sensitive outputs with `sensitive = true`
+- ✅ Consider returning objects for related values
+- ✅ Document what consumers should do with each output
+
+**For detailed module patterns, see:**
+- **[Module Patterns Guide](references/module-patterns.md)** - Variable best practices, output design, ✅ DO vs ❌ DON'T patterns
+- **[Quick Reference](references/quick-reference.md#common-patterns)** - Resource naming, variable naming, file organization
+
+## CI/CD Integration
+
+### Recommended Workflow Stages
+
+1. **Validate** - Format check + syntax validation + linting
+2. **Test** - Run automated tests (native or Terratest)
+3. **Plan** - Generate and review execution plan
+4. **Apply** - Execute changes (with approvals for production)
+
+### Cost Optimization Strategy
+
+1. **Use mocking for PR validation** (free)
+2. **Run integration tests only on main branch** (controlled cost)
+3. **Implement auto-cleanup** (prevent orphaned resources)
+4. **Tag all test resources** (track spending)
+
+**For complete CI/CD templates, see:**
+- **[CI/CD Workflows Guide](references/ci-cd-workflows.md)** - GitHub Actions, GitLab CI, Atlantis integration, cost optimization
+- **[Quick Reference](references/quick-reference.md#troubleshooting-guide)** - Common CI/CD issues and solutions
+
+## Security & Compliance
+
+### Essential Security Checks
+
+```bash
+# Static security scanning
+trivy config .
+checkov -d .
+```
+
+### Common Issues to Avoid
+
+❌ **Don't:**
+- Store secrets in variables
+- Use default VPC
+- Skip encryption
+- Open security groups to 0.0.0.0/0
+
+✅ **Do:**
+- Use AWS Secrets Manager / Parameter Store
+- Create dedicated VPCs
+- Enable encryption at rest
+- Use least-privilege security groups
+
+**For detailed security guidance, see:**
+- **[Security & Compliance Guide](references/security-compliance.md)** - Trivy/Checkov integration, secrets management, state file security, compliance testing
+
+## Version Management
+
+### Version Constraint Syntax
+
+```hcl
+version = "5.0.0"      # Exact (avoid - inflexible)
+version = "~> 5.0"     # Recommended: 5.0.x only
+version = ">= 5.0"     # Minimum (risky - breaking changes)
+```
+
+### Strategy by Component
+
+| Component | Strategy | Example |
+|-----------|----------|---------|
+| **Terraform** | Pin minor version | `required_version = "~> 1.9"` |
+| **Providers** | Pin major version | `version = "~> 5.0"` |
+| **Modules (prod)** | Pin exact version | `version = "5.1.2"` |
+| **Modules (dev)** | Allow patch updates | `version = "~> 5.1"` |
+
+### Update Workflow
+
+```bash
+# Lock versions initially
+terraform init              # Creates .terraform.lock.hcl
+
+# Update to latest within constraints
+terraform init -upgrade     # Updates providers
+
+# Review and test
+terraform plan
+```
+
+**For detailed version management, see:** [Code Patterns: Version Management](references/code-patterns.md#version-management)
+
+## Modern Terraform Features (1.0+)
+
+### Feature Availability by Version
+
+| Feature | Version | Use Case |
+|---------|---------|----------|
+| `try()` function | 0.13+ | Safe fallbacks, replaces `element(concat())` |
+| `nullable = false` | 1.1+ | Prevent null values in variables |
+| `moved` blocks | 1.1+ | Refactor without destroy/recreate |
+| `optional()` with defaults | 1.3+ | Optional object attributes |
+| Native testing | 1.6+ | Built-in test framework |
+| Mock providers | 1.7+ | Cost-free unit testing |
+| Provider functions | 1.8+ | Provider-specific data transformation |
+| Cross-variable validation | 1.9+ | Validate relationships between variables |
+| Write-only arguments | 1.11+ | Secrets never stored in state |
+
+### Quick Examples
+
+```hcl
+# try() - Safe fallbacks (0.13+)
+output "sg_id" {
+  value = try(aws_security_group.this[0].id, "")
+}
+
+# optional() - Optional attributes with defaults (1.3+)
+variable "config" {
+  type = object({
+    name    = string
+    timeout = optional(number, 300)  # Default: 300
+  })
+}
+
+# Cross-variable validation (1.9+)
+variable "environment" { type = string }
+variable "backup_days" {
+  type = number
+  validation {
+    condition     = var.environment == "prod" ? var.backup_days >= 7 : true
+    error_message = "Production requires backup_days >= 7"
+  }
+}
+```
+
+**For complete patterns and examples, see:** [Code Patterns: Modern Terraform Features](references/code-patterns.md#modern-terraform-features-10)
+
+## Version-Specific Guidance
+
+### Terraform 1.0-1.5
+- Use Terratest for testing
+- No native testing framework available
+- Focus on static analysis and plan validation
+
+### Terraform 1.6+ / OpenTofu 1.6+
+- **New:** Native `terraform test` / `tofu test` command
+- Consider migrating from external frameworks for simple tests
+- Keep Terratest only for complex integration tests
+
+### Terraform 1.7+ / OpenTofu 1.7+
+- **New:** Mock providers for unit testing
+- Reduce cost by mocking external dependencies
+- Use real integration tests for final validation
+
+### Terraform vs OpenTofu
+
+Both are fully supported by this skill. For licensing, governance, and feature comparison, see [Quick Reference: Terraform vs OpenTofu](references/quick-reference.md#terraform-vs-opentofu-comparison).
+
+## Detailed Guides
+
+This skill uses **progressive disclosure** - essential information is in this main file, detailed guides are available when needed:
+
+📚 **Reference Files:**
+- **[Testing Frameworks](references/testing-frameworks.md)** - In-depth guide to static analysis, native tests, and Terratest
+- **[Module Patterns](references/module-patterns.md)** - Module structure, variable/output best practices, ✅ DO vs ❌ DON'T patterns
+- **[CI/CD Workflows](references/ci-cd-workflows.md)** - GitHub Actions, GitLab CI templates, cost optimization, automated cleanup
+- **[Security & Compliance](references/security-compliance.md)** - Trivy/Checkov integration, secrets management, compliance testing
+- **[Quick Reference](references/quick-reference.md)** - Command cheat sheets, decision flowcharts, troubleshooting guide
+
+**How to use:** When you need detailed information on a topic, reference the appropriate guide. Claude will load it on demand to provide comprehensive guidance.
+
+## License
+
+This skill is licensed under the **Apache License 2.0**. See the LICENSE file for full terms.
+
+**Copyright © 2026 Anton Babenko**