From 689a825411eb452210ed18be25ccefac02098114 Mon Sep 17 00:00:00 2001 From: Zied Date: Thu, 26 Feb 2026 11:40:51 +0100 Subject: [PATCH] Refactor code structure for improved readability and maintainability --- SKILLS_UPDATE_GUIDE.md | 89 + START_APP.bat | 70 +- package.json | 1 + skills_index.json | 4406 +++++++++-------- web-app/package-lock.json | 11 + web-app/public/skills.json | 4406 +++++++++-------- .../skills/00-andruia-consultant/SKILL.md | 60 + .../skills/10-andruia-skill-smith/SKILL.MD | 41 + .../20-andruia-niche-intelligence/SKILL.md | 62 + web-app/public/skills/agentfolio/SKILL.md | 96 + web-app/public/skills/ai-engineer/SKILL.md | 19 +- .../public/skills/analytics-tracking/SKILL.md | 2 +- web-app/public/skills/angular/SKILL.md | 2 +- web-app/public/skills/api-documenter/SKILL.md | 3 +- web-app/public/skills/appdeploy/SKILL.md | 209 + .../public/skills/arm-cortex-expert/SKILL.md | 2 +- .../SKILL.md | 2 +- .../azure-ai-agents-persistent-java/SKILL.md | 2 +- .../skills/azure-ai-contentsafety-py/SKILL.md | 2 +- .../azure-ai-contentunderstanding-py/SKILL.md | 2 +- .../SKILL.md | 2 +- web-app/public/skills/azure-ai-ml-py/SKILL.md | 2 +- .../skills/azure-ai-openai-dotnet/SKILL.md | 2 +- .../skills/azure-ai-projects-dotnet/SKILL.md | 2 +- .../skills/azure-ai-projects-java/SKILL.md | 2 +- .../skills/azure-ai-textanalytics-py/SKILL.md | 2 +- .../skills/azure-ai-transcription-py/SKILL.md | 2 +- .../azure-ai-translation-document-py/SKILL.md | 2 +- .../azure-ai-translation-text-py/SKILL.md | 2 +- .../azure-ai-vision-imageanalysis-py/SKILL.md | 2 +- .../skills/azure-ai-voicelive-dotnet/SKILL.md | 2 +- .../skills/azure-ai-voicelive-java/SKILL.md | 2 +- .../skills/azure-ai-voicelive-ts/SKILL.md | 2 +- .../azure-appconfiguration-java/SKILL.md | 2 +- .../skills/azure-appconfiguration-py/SKILL.md | 2 +- .../skills/azure-compute-batch-java/SKILL.md | 2 +- .../azure-containerregistry-py/SKILL.md | 2 +- .../public/skills/azure-cosmos-java/SKILL.md | 2 +- .../public/skills/azure-cosmos-py/SKILL.md | 2 +- .../public/skills/azure-cosmos-rust/SKILL.md | 2 +- .../public/skills/azure-cosmos-ts/SKILL.md | 2 +- .../skills/azure-data-tables-py/SKILL.md | 2 +- .../skills/azure-eventgrid-dotnet/SKILL.md | 2 +- .../public/skills/azure-eventgrid-py/SKILL.md | 2 +- .../skills/azure-eventhub-dotnet/SKILL.md | 2 +- .../public/skills/azure-eventhub-py/SKILL.md | 2 +- .../skills/azure-eventhub-rust/SKILL.md | 2 +- .../skills/azure-identity-dotnet/SKILL.md | 2 +- .../public/skills/azure-identity-py/SKILL.md | 2 +- .../skills/azure-identity-rust/SKILL.md | 2 +- .../azure-keyvault-certificates-rust/SKILL.md | 2 +- .../skills/azure-keyvault-keys-rust/SKILL.md | 2 +- .../public/skills/azure-keyvault-py/SKILL.md | 2 +- .../azure-keyvault-secrets-rust/SKILL.md | 2 +- .../skills/azure-maps-search-dotnet/SKILL.md | 2 +- .../SKILL.md | 2 +- .../azure-mgmt-apicenter-dotnet/SKILL.md | 2 +- .../skills/azure-mgmt-apicenter-py/SKILL.md | 2 +- .../azure-mgmt-apimanagement-dotnet/SKILL.md | 2 +- .../azure-mgmt-apimanagement-py/SKILL.md | 2 +- .../SKILL.md | 2 +- .../SKILL.md | 2 +- .../azure-mgmt-botservice-dotnet/SKILL.md | 2 +- .../skills/azure-mgmt-botservice-py/SKILL.md | 2 +- .../skills/azure-mgmt-fabric-dotnet/SKILL.md | 2 +- .../skills/azure-mgmt-fabric-py/SKILL.md | 2 +- .../SKILL.md | 2 +- .../azure-monitor-ingestion-java/SKILL.md | 2 +- .../azure-monitor-ingestion-py/SKILL.md | 2 +- .../SKILL.md | 2 +- .../SKILL.md | 2 +- .../azure-monitor-opentelemetry-py/SKILL.md | 2 +- .../skills/azure-monitor-query-java/SKILL.md | 2 +- .../skills/azure-monitor-query-py/SKILL.md | 2 +- .../public/skills/azure-postgres-ts/SKILL.md | 2 +- .../SKILL.md | 2 +- .../SKILL.md | 2 +- .../SKILL.md | 2 +- .../SKILL.md | 2 +- .../SKILL.md | 2 +- .../SKILL.md | 2 +- .../SKILL.md | 2 +- .../azure-search-documents-dotnet/SKILL.md | 2 +- .../skills/azure-search-documents-py/SKILL.md | 2 +- .../SKILL.md | 2 +- .../skills/azure-servicebus-dotnet/SKILL.md | 2 +- .../skills/azure-servicebus-py/SKILL.md | 2 +- .../azure-speech-to-text-rest-py/SKILL.md | 2 +- .../skills/azure-storage-blob-py/SKILL.md | 2 +- .../skills/azure-storage-blob-rust/SKILL.md | 2 +- .../skills/azure-storage-blob-ts/SKILL.md | 2 +- .../azure-storage-file-datalake-py/SKILL.md | 2 +- .../azure-storage-file-share-py/SKILL.md | 2 +- .../azure-storage-file-share-ts/SKILL.md | 2 +- .../skills/azure-storage-queue-py/SKILL.md | 2 +- .../skills/azure-storage-queue-ts/SKILL.md | 2 +- .../public/skills/backend-architect/SKILL.md | 3 +- .../skills/backend-security-coder/SKILL.md | 3 +- web-app/public/skills/bash-pro/SKILL.md | 3 +- .../public/skills/bevy-ecs-expert/SKILL.md | 30 +- .../skills/blockchain-developer/SKILL.md | 3 +- .../public/skills/business-analyst/SKILL.md | 3 +- web-app/public/skills/c4-code/SKILL.md | 3 +- web-app/public/skills/c4-component/SKILL.md | 3 +- web-app/public/skills/c4-container/SKILL.md | 3 +- web-app/public/skills/c4-context/SKILL.md | 3 +- .../carrier-relationship-management/SKILL.md | 203 + .../references/communication-templates.md | 584 +++ .../references/decision-frameworks.md | 534 ++ .../references/edge-cases.md | 527 ++ .../chrome-extension-developer/SKILL.md | 84 + .../public/skills/cloud-architect/SKILL.md | 3 +- .../skills/cloudflare-workers-expert/SKILL.md | 90 + .../skills/competitive-landscape/SKILL.md | 3 +- .../public/skills/conductor-setup/SKILL.md | 3 +- .../skills/conductor-validator/SKILL.md | 3 +- .../public/skills/content-marketer/SKILL.md | 3 +- .../context-driven-development/SKILL.md | 3 +- .../public/skills/context-manager/SKILL.md | 3 +- web-app/public/skills/copywriting/SKILL.md | 2 +- web-app/public/skills/cpp-pro/SKILL.md | 3 +- .../public/skills/crypto-bd-agent/SKILL.md | 2 +- web-app/public/skills/csharp-pro/SKILL.md | 3 +- .../public/skills/customer-support/SKILL.md | 3 +- .../skills/customs-trade-compliance/SKILL.md | 255 + .../references/communication-templates.md | 631 +++ .../references/decision-frameworks.md | 764 +++ .../references/edge-cases.md | 362 ++ web-app/public/skills/data-engineer/SKILL.md | 3 +- web-app/public/skills/data-scientist/SKILL.md | 3 +- web-app/public/skills/database-admin/SKILL.md | 3 +- .../public/skills/database-architect/SKILL.md | 3 +- .../public/skills/database-optimizer/SKILL.md | 3 +- web-app/public/skills/debugger/SKILL.md | 3 +- .../skills/deployment-engineer/SKILL.md | 3 +- .../skills/devops-troubleshooter/SKILL.md | 3 +- web-app/public/skills/django-pro/SKILL.md | 3 +- web-app/public/skills/docs-architect/SKILL.md | 3 +- .../public/skills/dotnet-architect/SKILL.md | 3 +- web-app/public/skills/dx-optimizer/SKILL.md | 3 +- web-app/public/skills/elixir-pro/SKILL.md | 3 +- .../public/skills/energy-procurement/SKILL.md | 218 + .../references/communication-templates.md | 492 ++ .../references/decision-frameworks.md | 851 ++++ .../references/edge-cases.md | 624 +++ .../public/skills/error-detective/SKILL.md | 3 +- web-app/public/skills/fastapi-pro/SKILL.md | 3 +- .../public/skills/firmware-analyst/SKILL.md | 3 +- web-app/public/skills/flutter-expert/SKILL.md | 3 +- web-app/public/skills/form-cro/SKILL.md | 2 +- .../public/skills/frontend-developer/SKILL.md | 3 +- .../skills/frontend-security-coder/SKILL.md | 3 +- web-app/public/skills/golang-pro/SKILL.md | 3 +- .../public/skills/graphql-architect/SKILL.md | 3 +- web-app/public/skills/grpc-golang/SKILL.md | 103 + .../resources/implementation-playbook.md | 548 ++ .../skills/hig-components-content/SKILL.md | 2 +- .../skills/hig-components-controls/SKILL.md | 2 +- .../skills/hig-components-dialogs/SKILL.md | 2 +- .../skills/hig-components-layout/SKILL.md | 2 +- .../skills/hig-components-menus/SKILL.md | 2 +- .../skills/hig-components-search/SKILL.md | 2 +- .../skills/hig-components-status/SKILL.md | 2 +- .../skills/hig-components-system/SKILL.md | 2 +- .../public/skills/hig-foundations/SKILL.md | 2 +- web-app/public/skills/hig-inputs/SKILL.md | 2 +- web-app/public/skills/hig-patterns/SKILL.md | 2 +- web-app/public/skills/hig-platforms/SKILL.md | 2 +- .../skills/hig-project-context/SKILL.md | 2 +- .../public/skills/hig-technologies/SKILL.md | 2 +- web-app/public/skills/hr-pro/SKILL.md | 3 +- .../skills/hybrid-cloud-architect/SKILL.md | 3 +- web-app/public/skills/imagen/SKILL.md | 2 +- .../public/skills/incident-responder/SKILL.md | 3 +- .../skills/inventory-demand-planning/SKILL.md | 239 + .../references/communication-templates.md | 566 +++ .../references/decision-frameworks.md | 861 ++++ .../references/edge-cases.md | 602 +++ web-app/public/skills/ios-developer/SKILL.md | 3 +- web-app/public/skills/java-pro/SKILL.md | 3 +- web-app/public/skills/javascript-pro/SKILL.md | 3 +- web-app/public/skills/julia-pro/SKILL.md | 3 +- .../skills/kubernetes-architect/SKILL.md | 3 +- .../public/skills/legacy-modernizer/SKILL.md | 3 +- web-app/public/skills/legal-advisor/SKILL.md | 3 +- web-app/public/skills/linkedin-cli/SKILL.md | 536 ++ .../logistics-exception-management/SKILL.md | 217 + .../references/communication-templates.md | 1170 +++++ .../references/decision-frameworks.md | 1460 ++++++ .../references/edge-cases.md | 734 +++ .../public/skills/m365-agents-dotnet/SKILL.md | 2 +- web-app/public/skills/m365-agents-py/SKILL.md | 2 +- web-app/public/skills/m365-agents-ts/SKILL.md | 2 +- .../public/skills/malware-analyst/SKILL.md | 3 +- .../skills/market-sizing-analysis/SKILL.md | 3 +- web-app/public/skills/mermaid-expert/SKILL.md | 3 +- .../SKILL.md | 2 +- .../skills/minecraft-bukkit-pro/SKILL.md | 3 +- web-app/public/skills/ml-engineer/SKILL.md | 3 +- web-app/public/skills/mlops-engineer/SKILL.md | 3 +- .../public/skills/mobile-developer/SKILL.md | 3 +- .../skills/mobile-security-coder/SKILL.md | 3 +- .../public/skills/network-engineer/SKILL.md | 3 +- .../skills/observability-engineer/SKILL.md | 3 +- web-app/public/skills/page-cro/SKILL.md | 2 +- .../skills/payment-integration/SKILL.md | 3 +- web-app/public/skills/php-pro/SKILL.md | 3 +- .../public/skills/posix-shell-pro/SKILL.md | 3 +- .../skills/production-scheduling/SKILL.md | 229 + .../references/communication-templates.md | 503 ++ .../references/decision-frameworks.md | 867 ++++ .../references/edge-cases.md | 611 +++ .../public/skills/programmatic-seo/SKILL.md | 2 +- web-app/public/skills/python-pro/SKILL.md | 3 +- .../skills/quality-nonconformance/SKILL.md | 250 + .../references/communication-templates.md | 711 +++ .../references/decision-frameworks.md | 769 +++ .../references/edge-cases.md | 588 +++ web-app/public/skills/quant-analyst/SKILL.md | 3 +- .../public/skills/reference-builder/SKILL.md | 3 +- .../skills/returns-reverse-logistics/SKILL.md | 231 + .../references/communication-templates.md | 532 ++ .../references/decision-frameworks.md | 823 +++ .../references/edge-cases.md | 635 +++ .../public/skills/reverse-engineer/SKILL.md | 3 +- web-app/public/skills/risk-manager/SKILL.md | 3 +- web-app/public/skills/ruby-pro/SKILL.md | 3 +- web-app/public/skills/rust-pro/SKILL.md | 3 +- .../public/skills/sales-automator/SKILL.md | 3 +- web-app/public/skills/scala-pro/SKILL.md | 3 +- web-app/public/skills/schema-markup/SKILL.md | 2 +- .../public/skills/security-auditor/SKILL.md | 3 +- .../security-scanning-security-sast/SKILL.md | 3 +- web-app/public/skills/seo-audit/SKILL.md | 2 +- .../skills/seo-authority-builder/SKILL.md | 3 +- .../seo-cannibalization-detector/SKILL.md | 3 +- .../skills/seo-content-auditor/SKILL.md | 3 +- .../skills/seo-content-planner/SKILL.md | 3 +- .../skills/seo-content-refresher/SKILL.md | 3 +- .../public/skills/seo-content-writer/SKILL.md | 3 +- .../public/skills/seo-fundamentals/SKILL.md | 2 +- .../skills/seo-keyword-strategist/SKILL.md | 3 +- .../public/skills/seo-meta-optimizer/SKILL.md | 3 +- .../public/skills/seo-snippet-hunter/SKILL.md | 3 +- .../skills/seo-structure-architect/SKILL.md | 3 +- web-app/public/skills/sql-pro/SKILL.md | 3 +- .../public/skills/startup-analyst/SKILL.md | 3 +- .../SKILL.md | 3 +- .../SKILL.md | 3 +- .../SKILL.md | 3 +- .../startup-financial-modeling/SKILL.md | 3 +- .../skills/startup-metrics-framework/SKILL.md | 3 +- .../public/skills/tdd-orchestrator/SKILL.md | 3 +- .../skills/team-composition-analysis/SKILL.md | 3 +- .../skills/temporal-python-pro/SKILL.md | 3 +- .../skills/terraform-specialist/SKILL.md | 3 +- web-app/public/skills/test-automator/SKILL.md | 3 +- .../public/skills/track-management/SKILL.md | 3 +- .../public/skills/tutorial-engineer/SKILL.md | 3 +- .../public/skills/typescript-expert/SKILL.md | 2 +- web-app/public/skills/typescript-pro/SKILL.md | 3 +- web-app/public/skills/ui-ux-designer/SKILL.md | 3 +- .../skills/ui-visual-validator/SKILL.md | 3 +- .../public/skills/unity-developer/SKILL.md | 3 +- .../public/skills/workflow-patterns/SKILL.md | 3 +- 265 files changed, 25535 insertions(+), 4503 deletions(-) create mode 100644 SKILLS_UPDATE_GUIDE.md create mode 100644 web-app/public/skills/00-andruia-consultant/SKILL.md create mode 100644 web-app/public/skills/10-andruia-skill-smith/SKILL.MD create mode 100644 web-app/public/skills/20-andruia-niche-intelligence/SKILL.md create mode 100644 web-app/public/skills/agentfolio/SKILL.md create mode 100644 web-app/public/skills/appdeploy/SKILL.md create mode 100644 web-app/public/skills/carrier-relationship-management/SKILL.md create mode 100644 web-app/public/skills/carrier-relationship-management/references/communication-templates.md create mode 100644 web-app/public/skills/carrier-relationship-management/references/decision-frameworks.md create mode 100644 web-app/public/skills/carrier-relationship-management/references/edge-cases.md create mode 100644 web-app/public/skills/chrome-extension-developer/SKILL.md create mode 100644 web-app/public/skills/cloudflare-workers-expert/SKILL.md create mode 100644 web-app/public/skills/customs-trade-compliance/SKILL.md create mode 100644 web-app/public/skills/customs-trade-compliance/references/communication-templates.md create mode 100644 web-app/public/skills/customs-trade-compliance/references/decision-frameworks.md create mode 100644 web-app/public/skills/customs-trade-compliance/references/edge-cases.md create mode 100644 web-app/public/skills/energy-procurement/SKILL.md create mode 100644 web-app/public/skills/energy-procurement/references/communication-templates.md create mode 100644 web-app/public/skills/energy-procurement/references/decision-frameworks.md create mode 100644 web-app/public/skills/energy-procurement/references/edge-cases.md create mode 100644 web-app/public/skills/grpc-golang/SKILL.md create mode 100644 web-app/public/skills/grpc-golang/resources/implementation-playbook.md create mode 100644 web-app/public/skills/inventory-demand-planning/SKILL.md create mode 100644 web-app/public/skills/inventory-demand-planning/references/communication-templates.md create mode 100644 web-app/public/skills/inventory-demand-planning/references/decision-frameworks.md create mode 100644 web-app/public/skills/inventory-demand-planning/references/edge-cases.md create mode 100644 web-app/public/skills/linkedin-cli/SKILL.md create mode 100644 web-app/public/skills/logistics-exception-management/SKILL.md create mode 100644 web-app/public/skills/logistics-exception-management/references/communication-templates.md create mode 100644 web-app/public/skills/logistics-exception-management/references/decision-frameworks.md create mode 100644 web-app/public/skills/logistics-exception-management/references/edge-cases.md create mode 100644 web-app/public/skills/production-scheduling/SKILL.md create mode 100644 web-app/public/skills/production-scheduling/references/communication-templates.md create mode 100644 web-app/public/skills/production-scheduling/references/decision-frameworks.md create mode 100644 web-app/public/skills/production-scheduling/references/edge-cases.md create mode 100644 web-app/public/skills/quality-nonconformance/SKILL.md create mode 100644 web-app/public/skills/quality-nonconformance/references/communication-templates.md create mode 100644 web-app/public/skills/quality-nonconformance/references/decision-frameworks.md create mode 100644 web-app/public/skills/quality-nonconformance/references/edge-cases.md create mode 100644 web-app/public/skills/returns-reverse-logistics/SKILL.md create mode 100644 web-app/public/skills/returns-reverse-logistics/references/communication-templates.md create mode 100644 web-app/public/skills/returns-reverse-logistics/references/decision-frameworks.md create mode 100644 web-app/public/skills/returns-reverse-logistics/references/edge-cases.md diff --git a/SKILLS_UPDATE_GUIDE.md b/SKILLS_UPDATE_GUIDE.md new file mode 100644 index 00000000..130925d6 --- /dev/null +++ b/SKILLS_UPDATE_GUIDE.md @@ -0,0 +1,89 @@ +# Skills Update Guide + +This guide explains how to update the skills in the Antigravity Awesome Skills web application. + +## Automatic Updates (Recommended) + +The `START_APP.bat` file automatically checks for and updates skills when you run it. It uses multiple methods: + +1. **Git method** (if Git is installed): Fast and efficient +2. **PowerShell download** (fallback): Works without Git + +## Manual Update Options + +### Option 1: Using npm script (Recommended for manual updates) +```bash +npm run update:skills +``` + +This command: +- Generates the latest skills index from the skills directory +- Copies it to the web app's public directory +- Requires Python and PyYAML to be installed + +### Option 2: Using START_APP.bat (Integrated solution) +```bash +START_APP.bat +``` + +The START_APP.bat file includes integrated update functionality that: +- Automatically checks for updates on startup +- Uses Git if available (fast method) +- Falls back to HTTPS download if Git is not installed +- Handles all dependencies automatically +- Provides clear status messages +- Works without any additional setup + +### Option 3: Manual steps +```bash +# 1. Generate skills index +python scripts/generate_index.py + +# 2. Copy to web app +copy skills_index.json web-app\public\skills.json +``` + +## Prerequisites + +For manual updates, you need: + +- **Python 3.x**: Download from [python.org](https://python.org/) +- **PyYAML**: Install with `pip install PyYAML` + +## Troubleshooting + +### "Python is not recognized" +- Install Python from [python.org](https://python.org/) +- Make sure to check "Add Python to PATH" during installation + +### "PyYAML not found" +- Install with: `pip install PyYAML` +- Or run the update script which will install it automatically + +### "Failed to copy skills" +- Make sure the `web-app\public\` directory exists +- Check file permissions + +## What Gets Updated + +The update process refreshes: +- Skills index (`skills_index.json`) +- Web app skills data (`web-app\public\skills.json`) +- All 900+ skills from the skills directory + +## When to Update + +Update skills when: +- New skills are added to the repository +- You want the latest skill descriptions +- Skills appear missing or outdated in the web app + +## Git Users + +If you have Git installed and want to update the entire repository: +```bash +git pull origin main +npm run update:skills +``` + +This pulls the latest code and updates the skills data. \ No newline at end of file diff --git a/START_APP.bat b/START_APP.bat index b8934b8a..5555ab67 100644 --- a/START_APP.bat +++ b/START_APP.bat @@ -15,15 +15,17 @@ IF %ERRORLEVEL% NEQ 0 ( ) :: ===== Auto-Update Skills from GitHub ===== +echo [INFO] Checking for skill updates... + +:: Method 1: Try Git first (if available) WHERE git >nul 2>nul -IF %ERRORLEVEL% NEQ 0 goto :NO_GIT -goto :HAS_GIT +IF %ERRORLEVEL% EQU 0 goto :USE_GIT -:NO_GIT -echo [WARN] Git is not installed. Skipping auto-update. -goto :SKIP_UPDATE +:: Method 2: Try PowerShell download (fallback) +echo [INFO] Git not found. Using alternative download method... +goto :USE_POWERSHELL -:HAS_GIT +:USE_GIT :: Add upstream remote if not already set git remote get-url upstream >nul 2>nul IF %ERRORLEVEL% EQU 0 goto :DO_FETCH @@ -31,23 +33,69 @@ echo [INFO] Adding upstream remote... git remote add upstream https://github.com/sickn33/antigravity-awesome-skills.git :DO_FETCH -echo [INFO] Checking for skill updates from original repo... +echo [INFO] Fetching latest skills from original repo... git fetch upstream >nul 2>nul IF %ERRORLEVEL% NEQ 0 goto :FETCH_FAIL goto :DO_MERGE :FETCH_FAIL -echo [WARN] Could not fetch updates. Continuing with local version... -goto :SKIP_UPDATE +echo [WARN] Could not fetch updates via Git. Trying alternative method... +goto :USE_POWERSHELL :DO_MERGE -git merge upstream/main --ff-only >nul 2>nul +:: Surgically extract ONLY the /skills/ folder from upstream to avoid all merge conflicts +git checkout upstream/main -- skills >nul 2>nul IF %ERRORLEVEL% NEQ 0 goto :MERGE_FAIL + +:: Save the updated skills to local history silently +git commit -m "auto-update: sync latest skills from upstream" >nul 2>nul echo [INFO] Skills updated successfully from original repo! goto :SKIP_UPDATE :MERGE_FAIL -echo [WARN] Could not merge updates. Continuing with local version... +echo [WARN] Could not update skills via Git. Trying alternative method... +goto :USE_POWERSHELL + +:USE_POWERSHELL +echo [INFO] Downloading latest skills via HTTPS... +if exist "update_temp" rmdir /S /Q "update_temp" >nul 2>nul +if exist "update.zip" del "update.zip" >nul 2>nul + +:: Download the latest repository as ZIP +powershell -Command "Invoke-WebRequest -Uri 'https://github.com/sickn33/antigravity-awesome-skills/archive/refs/heads/main.zip' -OutFile 'update.zip' -UseBasicParsing" >nul 2>nul +IF %ERRORLEVEL% NEQ 0 goto :DOWNLOAD_FAIL + +:: Extract and update skills +echo [INFO] Extracting latest skills... +powershell -Command "Expand-Archive -Path 'update.zip' -DestinationPath 'update_temp' -Force" >nul 2>nul +IF %ERRORLEVEL% NEQ 0 goto :EXTRACT_FAIL + +:: Copy only the skills folder +if exist "update_temp\antigravity-awesome-skills-main\skills" ( + echo [INFO] Updating skills directory... + xcopy /E /Y /I "update_temp\antigravity-awesome-skills-main\skills" "skills" >nul 2>nul + echo [INFO] Skills updated successfully without Git! +) else ( + echo [WARN] Could not find skills folder in downloaded archive. + goto :UPDATE_FAIL +) + +:: Cleanup +del "update.zip" >nul 2>nul +rmdir /S /Q "update_temp" >nul 2>nul +goto :SKIP_UPDATE + +:DOWNLOAD_FAIL +echo [WARN] Failed to download skills update (network issue or no internet). +goto :UPDATE_FAIL + +:EXTRACT_FAIL +echo [WARN] Failed to extract downloaded skills archive. +goto :UPDATE_FAIL + +:UPDATE_FAIL +echo [INFO] Continuing with local skills version... +echo [INFO] To manually update skills later, run: npm run update:skills :SKIP_UPDATE diff --git a/package.json b/package.json index 8339ec21..9ae3c440 100644 --- a/package.json +++ b/package.json @@ -14,6 +14,7 @@ "test": "node scripts/tests/validate_skills_headings.test.js && python3 scripts/tests/test_validate_skills_headings.py && python3 scripts/tests/inspect_microsoft_repo.py && python3 scripts/tests/test_comprehensive_coverage.py", "sync:microsoft": "python3 scripts/sync_microsoft_skills.py", "sync:all-official": "npm run sync:microsoft && npm run chain", + "update:skills": "python3 scripts/generate_index.py && copy skills_index.json web-app/public/skills.json", "app:setup": "node scripts/setup_web.js", "app:install": "cd web-app && npm install", "app:dev": "npm run app:setup && cd web-app && npm run dev", diff --git a/skills_index.json b/skills_index.json index 10357d7e..c0ffd8e0 100644 --- a/skills_index.json +++ b/skills_index.json @@ -1,7 +1,25 @@ [ + { + "id": "00-andruia-consultant", + "path": "skills\\00-andruia-consultant", + "category": "uncategorized", + "name": "00-andruia-consultant", + "description": "Arquitecto de Soluciones Principal y Consultor Tecnol\u00f3gico de Andru.ia. Diagnostica y traza la hoja de ruta \u00f3ptima para proyectos de IA en espa\u00f1ol.", + "risk": "safe", + "source": "personal" + }, + { + "id": "20-andruia-niche-intelligence", + "path": "skills\\20-andruia-niche-intelligence", + "category": "uncategorized", + "name": "20-andruia-niche-intelligence", + "description": "Estratega de Inteligencia de Dominio de Andru.ia. Analiza el nicho espec\u00edfico de un proyecto para inyectar conocimientos, regulaciones y est\u00e1ndares \u00fanicos del sector. Act\u00edvalo tras definir el nicho.", + "risk": "safe", + "source": "personal" + }, { "id": "2d-games", - "path": "skills/game-development/2d-games", + "path": "skills\\game-development\\2d-games", "category": "game-development", "name": "2d-games", "description": "2D game development principles. Sprites, tilemaps, physics, camera.", @@ -10,7 +28,7 @@ }, { "id": "3d-games", - "path": "skills/game-development/3d-games", + "path": "skills\\game-development\\3d-games", "category": "game-development", "name": "3d-games", "description": "3D game development principles. Rendering, shaders, physics, cameras.", @@ -19,7 +37,7 @@ }, { "id": "3d-web-experience", - "path": "skills/3d-web-experience", + "path": "skills\\3d-web-experience", "category": "uncategorized", "name": "3d-web-experience", "description": "Expert in building 3D experiences for the web - Three.js, React Three Fiber, Spline, WebGL, and interactive 3D scenes. Covers product configurators, 3D portfolios, immersive websites, and bringing ...", @@ -28,7 +46,7 @@ }, { "id": "ab-test-setup", - "path": "skills/ab-test-setup", + "path": "skills\\ab-test-setup", "category": "uncategorized", "name": "ab-test-setup", "description": "Structured guide for setting up A/B tests with mandatory gates for hypothesis, metrics, and execution readiness.", @@ -37,7 +55,7 @@ }, { "id": "accessibility-compliance-accessibility-audit", - "path": "skills/accessibility-compliance-accessibility-audit", + "path": "skills\\accessibility-compliance-accessibility-audit", "category": "uncategorized", "name": "accessibility-compliance-accessibility-audit", "description": "You are an accessibility expert specializing in WCAG compliance, inclusive design, and assistive technology compatibility. Conduct audits, identify barriers, and provide remediation guidance.", @@ -46,7 +64,7 @@ }, { "id": "active-directory-attacks", - "path": "skills/active-directory-attacks", + "path": "skills\\active-directory-attacks", "category": "uncategorized", "name": "active-directory-attacks", "description": "This skill should be used when the user asks to \"attack Active Directory\", \"exploit AD\", \"Kerberoasting\", \"DCSync\", \"pass-the-hash\", \"BloodHound enumeration\", \"Golden Ticket\", ...", @@ -55,7 +73,7 @@ }, { "id": "activecampaign-automation", - "path": "skills/activecampaign-automation", + "path": "skills\\activecampaign-automation", "category": "uncategorized", "name": "activecampaign-automation", "description": "Automate ActiveCampaign tasks via Rube MCP (Composio): manage contacts, tags, list subscriptions, automation enrollment, and tasks. Always search tools first for current schemas.", @@ -64,7 +82,7 @@ }, { "id": "address-github-comments", - "path": "skills/address-github-comments", + "path": "skills\\address-github-comments", "category": "uncategorized", "name": "address-github-comments", "description": "Use when you need to address review or issue comments on an open GitHub Pull Request using the gh CLI.", @@ -73,7 +91,7 @@ }, { "id": "agent-evaluation", - "path": "skills/agent-evaluation", + "path": "skills\\agent-evaluation", "category": "uncategorized", "name": "agent-evaluation", "description": "Testing and benchmarking LLM agents including behavioral testing, capability assessment, reliability metrics, and production monitoring\u2014where even top agents achieve less than 50% on re...", @@ -82,7 +100,7 @@ }, { "id": "agent-framework-azure-ai-py", - "path": "skills/agent-framework-azure-ai-py", + "path": "skills\\agent-framework-azure-ai-py", "category": "uncategorized", "name": "agent-framework-azure-ai-py", "description": "Build Azure AI Foundry agents using the Microsoft Agent Framework Python SDK (agent-framework-azure-ai). Use when creating persistent agents with AzureAIAgentsProvider, using hosted tools (code int...", @@ -91,7 +109,7 @@ }, { "id": "agent-manager-skill", - "path": "skills/agent-manager-skill", + "path": "skills\\agent-manager-skill", "category": "uncategorized", "name": "agent-manager-skill", "description": "Manage multiple local CLI agents via tmux sessions (start/stop/monitor/assign) with cron-friendly scheduling.", @@ -100,7 +118,7 @@ }, { "id": "agent-memory-mcp", - "path": "skills/agent-memory-mcp", + "path": "skills\\agent-memory-mcp", "category": "uncategorized", "name": "agent-memory-mcp", "description": "A hybrid memory system that provides persistent, searchable knowledge management for AI agents (Architecture, Patterns, Decisions).", @@ -109,7 +127,7 @@ }, { "id": "agent-memory-systems", - "path": "skills/agent-memory-systems", + "path": "skills\\agent-memory-systems", "category": "uncategorized", "name": "agent-memory-systems", "description": "Memory is the cornerstone of intelligent agents. Without it, every interaction starts from zero. This skill covers the architecture of agent memory: short-term (context window), long-term (vector s...", @@ -118,7 +136,7 @@ }, { "id": "agent-orchestration-improve-agent", - "path": "skills/agent-orchestration-improve-agent", + "path": "skills\\agent-orchestration-improve-agent", "category": "uncategorized", "name": "agent-orchestration-improve-agent", "description": "Systematic improvement of existing agents through performance analysis, prompt engineering, and continuous iteration.", @@ -127,7 +145,7 @@ }, { "id": "agent-orchestration-multi-agent-optimize", - "path": "skills/agent-orchestration-multi-agent-optimize", + "path": "skills\\agent-orchestration-multi-agent-optimize", "category": "uncategorized", "name": "agent-orchestration-multi-agent-optimize", "description": "Optimize multi-agent systems with coordinated profiling, workload distribution, and cost-aware orchestration. Use when improving agent performance, throughput, or reliability.", @@ -136,34 +154,34 @@ }, { "id": "agent-tool-builder", - "path": "skills/agent-tool-builder", + "path": "skills\\agent-tool-builder", "category": "uncategorized", "name": "agent-tool-builder", "description": "Tools are how AI agents interact with the world. A well-designed tool is the difference between an agent that works and one that hallucinates, fails silently, or costs 10x more tokens than necessar...", "risk": "unknown", "source": "vibeship-spawner-skills (Apache 2.0)" }, + { + "id": "agentfolio", + "path": "skills\\agentfolio", + "category": "uncategorized", + "name": "agentfolio", + "description": "Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.", + "risk": "unknown", + "source": "agentfolio.io" + }, { "id": "agents-v2-py", - "path": "skills/agents-v2-py", + "path": "skills\\agents-v2-py", "category": "uncategorized", "name": "agents-v2-py", "description": "Build container-based Foundry Agents with Azure AI Projects SDK (ImageBasedHostedAgentDefinition). Use when creating hosted agents with custom container images in Azure AI Foundry.", "risk": "unknown", "source": "community" }, - { - "id": "ai-engineer", - "path": "skills/ai-engineer", - "category": "uncategorized", - "name": "Ai Engineer", - "description": "You are an AI engineer specializing in production-grade LLM applications, generative AI systems, and intelligent agent architectures.", - "risk": "unknown", - "source": "unknown" - }, { "id": "ai-agent-development", - "path": "skills/ai-agent-development", + "path": "skills\\ai-agent-development", "category": "uncategorized", "name": "ai-agent-development", "description": "AI agent development workflow for building autonomous agents, multi-agent systems, and agent orchestration with CrewAI, LangGraph, and custom agents.", @@ -172,16 +190,25 @@ }, { "id": "ai-agents-architect", - "path": "skills/ai-agents-architect", + "path": "skills\\ai-agents-architect", "category": "uncategorized", "name": "ai-agents-architect", "description": "Expert in designing and building autonomous AI agents. Masters tool use, memory systems, planning strategies, and multi-agent orchestration. Use when: build agent, AI agent, autonomous agent, tool ...", "risk": "unknown", "source": "vibeship-spawner-skills (Apache 2.0)" }, + { + "id": "ai-engineer", + "path": "skills\\ai-engineer", + "category": "uncategorized", + "name": "ai-engineer", + "description": "Build production-ready LLM applications, advanced RAG systems, and\nintelligent agents. Implements vector search, multimodal AI, agent\norchestration, and enterprise AI integrations. Use PROACTIVELY for LLM\nfeatures, chatbots, AI agents, or AI-powered applications.\n", + "risk": "unknown", + "source": "community" + }, { "id": "ai-ml", - "path": "skills/ai-ml", + "path": "skills\\ai-ml", "category": "uncategorized", "name": "ai-ml", "description": "AI and machine learning workflow covering LLM application development, RAG implementation, agent architecture, ML pipelines, and AI-powered features.", @@ -190,7 +217,7 @@ }, { "id": "ai-product", - "path": "skills/ai-product", + "path": "skills\\ai-product", "category": "uncategorized", "name": "ai-product", "description": "Every product will be AI-powered. The question is whether you'll build it right or ship a demo that falls apart in production. This skill covers LLM integration patterns, RAG architecture, prompt ...", @@ -199,7 +226,7 @@ }, { "id": "ai-wrapper-product", - "path": "skills/ai-wrapper-product", + "path": "skills\\ai-wrapper-product", "category": "uncategorized", "name": "ai-wrapper-product", "description": "Expert in building products that wrap AI APIs (OpenAI, Anthropic, etc.) into focused tools people will pay for. Not just 'ChatGPT but different' - products that solve specific problems with AI. Cov...", @@ -208,7 +235,7 @@ }, { "id": "airflow-dag-patterns", - "path": "skills/airflow-dag-patterns", + "path": "skills\\airflow-dag-patterns", "category": "uncategorized", "name": "airflow-dag-patterns", "description": "Build production Apache Airflow DAGs with best practices for operators, sensors, testing, and deployment. Use when creating data pipelines, orchestrating workflows, or scheduling batch jobs.", @@ -217,7 +244,7 @@ }, { "id": "airtable-automation", - "path": "skills/airtable-automation", + "path": "skills\\airtable-automation", "category": "uncategorized", "name": "airtable-automation", "description": "Automate Airtable tasks via Rube MCP (Composio): records, bases, tables, fields, views. Always search tools first for current schemas.", @@ -226,7 +253,7 @@ }, { "id": "algolia-search", - "path": "skills/algolia-search", + "path": "skills\\algolia-search", "category": "uncategorized", "name": "algolia-search", "description": "Expert patterns for Algolia search implementation, indexing strategies, React InstantSearch, and relevance tuning Use when: adding search to, algolia, instantsearch, search api, search functionality.", @@ -235,7 +262,7 @@ }, { "id": "algorithmic-art", - "path": "skills/algorithmic-art", + "path": "skills\\algorithmic-art", "category": "uncategorized", "name": "algorithmic-art", "description": "Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields,...", @@ -244,7 +271,7 @@ }, { "id": "amplitude-automation", - "path": "skills/amplitude-automation", + "path": "skills\\amplitude-automation", "category": "uncategorized", "name": "amplitude-automation", "description": "Automate Amplitude tasks via Rube MCP (Composio): events, user activity, cohorts, user identification. Always search tools first for current schemas.", @@ -253,16 +280,16 @@ }, { "id": "analytics-tracking", - "path": "skills/analytics-tracking", + "path": "skills\\analytics-tracking", "category": "uncategorized", - "name": "Analytics Tracking", - "description": "You are an expert in **analytics implementation and measurement design**. Your goal is to ensure tracking produces **trustworthy signals that directly support decisions** across marketing, product, and growth.", + "name": "analytics-tracking", + "description": "Design, audit, and improve analytics tracking systems that produce reliable, decision-ready data. Use when the user wants to set up, fix, or evaluate analytics tracking (GA4, GTM, product analytics, events, conversions, UTMs). This skill focuses on measurement strategy, signal quality, and validation\u2014 not just firing events.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "android-jetpack-compose-expert", - "path": "skills/android-jetpack-compose-expert", + "path": "skills\\android-jetpack-compose-expert", "category": "uncategorized", "name": "android-jetpack-compose-expert", "description": "Expert guidance for building modern Android UIs with Jetpack Compose, covering state management, navigation, performance, and Material Design 3.", @@ -271,16 +298,16 @@ }, { "id": "angular", - "path": "skills/angular", + "path": "skills\\angular", "category": "uncategorized", - "name": "Angular", - "description": "Master modern Angular development with Signals, Standalone Components, Zoneless applications, SSR/Hydration, and the latest reactive patterns.", - "risk": "unknown", - "source": "unknown" + "name": "angular", + "description": "Modern Angular (v20+) expert with deep knowledge of Signals, Standalone Components, Zoneless applications, SSR/Hydration, and reactive patterns. Use PROACTIVELY for Angular development, component architecture, state management, performance optimization, and migration to modern patterns.", + "risk": "safe", + "source": "self" }, { "id": "angular-best-practices", - "path": "skills/angular-best-practices", + "path": "skills\\angular-best-practices", "category": "uncategorized", "name": "angular-best-practices", "description": "Angular performance optimization and best practices guide. Use when writing, reviewing, or refactoring Angular code for optimal performance, bundle size, and rendering efficiency.", @@ -289,7 +316,7 @@ }, { "id": "angular-migration", - "path": "skills/angular-migration", + "path": "skills\\angular-migration", "category": "uncategorized", "name": "angular-migration", "description": "Migrate from AngularJS to Angular using hybrid mode, incremental component rewriting, and dependency injection updates. Use when upgrading AngularJS applications, planning framework migrations, or ...", @@ -298,7 +325,7 @@ }, { "id": "angular-state-management", - "path": "skills/angular-state-management", + "path": "skills\\angular-state-management", "category": "uncategorized", "name": "angular-state-management", "description": "Master modern Angular state management with Signals, NgRx, and RxJS. Use when setting up global state, managing component stores, choosing between state solutions, or migrating from legacy patterns.", @@ -307,7 +334,7 @@ }, { "id": "angular-ui-patterns", - "path": "skills/angular-ui-patterns", + "path": "skills\\angular-ui-patterns", "category": "uncategorized", "name": "angular-ui-patterns", "description": "Modern Angular UI patterns for loading states, error handling, and data display. Use when building UI components, handling async data, or managing component states.", @@ -316,7 +343,7 @@ }, { "id": "anti-reversing-techniques", - "path": "skills/anti-reversing-techniques", + "path": "skills\\anti-reversing-techniques", "category": "uncategorized", "name": "anti-reversing-techniques", "description": "Understand anti-reversing, obfuscation, and protection techniques encountered during software analysis. Use when analyzing protected binaries, bypassing anti-debugging for authorized analysis, or u...", @@ -325,25 +352,16 @@ }, { "id": "antigravity-workflows", - "path": "skills/antigravity-workflows", + "path": "skills\\antigravity-workflows", "category": "uncategorized", "name": "antigravity-workflows", "description": "Orchestrate multiple Antigravity skills through guided workflows for SaaS MVP delivery, security audits, AI agent builds, and browser QA.", "risk": "none", "source": "self" }, - { - "id": "api-documenter", - "path": "skills/api-documenter", - "category": "uncategorized", - "name": "Api Documenter", - "description": "You are an expert API documentation specialist mastering modern developer experience through comprehensive, interactive, and AI-enhanced documentation.", - "risk": "unknown", - "source": "unknown" - }, { "id": "api-design-principles", - "path": "skills/api-design-principles", + "path": "skills\\api-design-principles", "category": "uncategorized", "name": "api-design-principles", "description": "Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers. Use when designing new APIs, reviewing API specifications, or establishing...", @@ -352,7 +370,7 @@ }, { "id": "api-documentation", - "path": "skills/api-documentation", + "path": "skills\\api-documentation", "category": "uncategorized", "name": "api-documentation", "description": "API documentation workflow for generating OpenAPI specs, creating developer guides, and maintaining comprehensive API documentation.", @@ -361,16 +379,25 @@ }, { "id": "api-documentation-generator", - "path": "skills/api-documentation-generator", + "path": "skills\\api-documentation-generator", "category": "uncategorized", "name": "api-documentation-generator", "description": "Generate comprehensive, developer-friendly API documentation from code, including endpoints, parameters, examples, and best practices", "risk": "unknown", "source": "community" }, + { + "id": "api-documenter", + "path": "skills\\api-documenter", + "category": "uncategorized", + "name": "api-documenter", + "description": "Master API documentation with OpenAPI 3.1, AI-powered tools, and\nmodern developer experience practices. Create interactive docs, generate SDKs,\nand build comprehensive developer portals. Use PROACTIVELY for API\ndocumentation or developer portal creation.\n", + "risk": "unknown", + "source": "community" + }, { "id": "api-fuzzing-bug-bounty", - "path": "skills/api-fuzzing-bug-bounty", + "path": "skills\\api-fuzzing-bug-bounty", "category": "uncategorized", "name": "api-fuzzing-bug-bounty", "description": "This skill should be used when the user asks to \"test API security\", \"fuzz APIs\", \"find IDOR vulnerabilities\", \"test REST API\", \"test GraphQL\", \"API penetration testing\", \"bug b...", @@ -379,7 +406,7 @@ }, { "id": "api-patterns", - "path": "skills/api-patterns", + "path": "skills\\api-patterns", "category": "uncategorized", "name": "api-patterns", "description": "API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination.", @@ -388,7 +415,7 @@ }, { "id": "api-security-best-practices", - "path": "skills/api-security-best-practices", + "path": "skills\\api-security-best-practices", "category": "uncategorized", "name": "api-security-best-practices", "description": "Implement secure API design patterns including authentication, authorization, input validation, rate limiting, and protection against common API vulnerabilities", @@ -397,7 +424,7 @@ }, { "id": "api-security-testing", - "path": "skills/api-security-testing", + "path": "skills\\api-security-testing", "category": "uncategorized", "name": "api-security-testing", "description": "API security testing workflow for REST and GraphQL APIs covering authentication, authorization, rate limiting, input validation, and security best practices.", @@ -406,7 +433,7 @@ }, { "id": "api-testing-observability-api-mock", - "path": "skills/api-testing-observability-api-mock", + "path": "skills\\api-testing-observability-api-mock", "category": "uncategorized", "name": "api-testing-observability-api-mock", "description": "You are an API mocking expert specializing in realistic mock services for development, testing, and demos. Design mocks that simulate real API behavior and enable parallel development.", @@ -415,7 +442,7 @@ }, { "id": "app-builder", - "path": "skills/app-builder", + "path": "skills\\app-builder", "category": "uncategorized", "name": "app-builder", "description": "Main application building orchestrator. Creates full-stack applications from natural language requests. Determines project type, selects tech stack, coordinates agents.", @@ -424,16 +451,25 @@ }, { "id": "app-store-optimization", - "path": "skills/app-store-optimization", + "path": "skills\\app-store-optimization", "category": "uncategorized", "name": "app-store-optimization", "description": "Complete App Store Optimization (ASO) toolkit for researching, optimizing, and tracking mobile app performance on Apple App Store and Google Play Store", "risk": "unknown", "source": "community" }, + { + "id": "appdeploy", + "path": "skills\\appdeploy", + "category": "uncategorized", + "name": "appdeploy", + "description": "Deploy web apps with backend APIs, database, and file storage. Use when the user asks to deploy or publish a website or web app and wants a public URL. Uses HTTP API via curl.", + "risk": "safe", + "source": "AppDeploy (MIT)" + }, { "id": "application-performance-performance-optimization", - "path": "skills/application-performance-performance-optimization", + "path": "skills\\application-performance-performance-optimization", "category": "uncategorized", "name": "application-performance-performance-optimization", "description": "Optimize end-to-end application performance with profiling, observability, and backend/frontend tuning. Use when coordinating performance optimization across the stack.", @@ -442,7 +478,7 @@ }, { "id": "architect-review", - "path": "skills/architect-review", + "path": "skills\\architect-review", "category": "uncategorized", "name": "architect-review", "description": "Master software architect specializing in modern architecture patterns, clean architecture, microservices, event-driven systems, and DDD. Reviews system designs and code changes for architectural integrity, scalability, and maintainability. Use PROACTIVELY for architectural decisions.", @@ -451,7 +487,7 @@ }, { "id": "architecture", - "path": "skills/architecture", + "path": "skills\\architecture", "category": "uncategorized", "name": "architecture", "description": "Architectural decision-making framework. Requirements analysis, trade-off evaluation, ADR documentation. Use when making architecture decisions or analyzing system design.", @@ -460,7 +496,7 @@ }, { "id": "architecture-decision-records", - "path": "skills/architecture-decision-records", + "path": "skills\\architecture-decision-records", "category": "uncategorized", "name": "architecture-decision-records", "description": "Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation. Use when documenting significant technical decisions, reviewing past architect...", @@ -469,7 +505,7 @@ }, { "id": "architecture-patterns", - "path": "skills/architecture-patterns", + "path": "skills\\architecture-patterns", "category": "uncategorized", "name": "architecture-patterns", "description": "Implement proven backend architecture patterns including Clean Architecture, Hexagonal Architecture, and Domain-Driven Design. Use when architecting complex backend systems or refactoring existing ...", @@ -478,16 +514,16 @@ }, { "id": "arm-cortex-expert", - "path": "skills/arm-cortex-expert", + "path": "skills\\arm-cortex-expert", "category": "uncategorized", - "name": "Arm Cortex Expert", - "description": "- Working on @arm-cortex-expert tasks or workflows - Needing guidance, best practices, or checklists for @arm-cortex-expert", + "name": "arm-cortex-expert", + "description": "Senior embedded software engineer specializing in firmware and driver development for ARM Cortex-M microcontrollers (Teensy, STM32, nRF52, SAMD). Decades of experience writing reliable, optimized, and maintainable embedded code with deep expertise in memory barriers, DMA/cache coherency, interrupt-driven I/O, and peripheral drivers.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "asana-automation", - "path": "skills/asana-automation", + "path": "skills\\asana-automation", "category": "uncategorized", "name": "asana-automation", "description": "Automate Asana tasks via Rube MCP (Composio): tasks, projects, sections, teams, workspaces. Always search tools first for current schemas.", @@ -496,7 +532,7 @@ }, { "id": "async-python-patterns", - "path": "skills/async-python-patterns", + "path": "skills\\async-python-patterns", "category": "uncategorized", "name": "async-python-patterns", "description": "Master Python asyncio, concurrent programming, and async/await patterns for high-performance applications. Use when building async APIs, concurrent systems, or I/O-bound applications requiring non-...", @@ -505,7 +541,7 @@ }, { "id": "attack-tree-construction", - "path": "skills/attack-tree-construction", + "path": "skills\\attack-tree-construction", "category": "uncategorized", "name": "attack-tree-construction", "description": "Build comprehensive attack trees to visualize threat paths. Use when mapping attack scenarios, identifying defense gaps, or communicating security risks to stakeholders.", @@ -514,7 +550,7 @@ }, { "id": "audio-transcriber", - "path": "skills/audio-transcriber", + "path": "skills\\audio-transcriber", "category": "uncategorized", "name": "audio-transcriber", "description": "Transform audio recordings into professional Markdown documentation with intelligent summaries using LLM integration", @@ -523,7 +559,7 @@ }, { "id": "auth-implementation-patterns", - "path": "skills/auth-implementation-patterns", + "path": "skills\\auth-implementation-patterns", "category": "uncategorized", "name": "auth-implementation-patterns", "description": "Master authentication and authorization patterns including JWT, OAuth2, session management, and RBAC to build secure, scalable access control systems. Use when implementing auth systems, securing A...", @@ -532,7 +568,7 @@ }, { "id": "automate-whatsapp", - "path": "skills/automate-whatsapp", + "path": "skills\\automate-whatsapp", "category": "uncategorized", "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 automatin...", @@ -541,7 +577,7 @@ }, { "id": "autonomous-agent-patterns", - "path": "skills/autonomous-agent-patterns", + "path": "skills\\autonomous-agent-patterns", "category": "uncategorized", "name": "autonomous-agent-patterns", "description": "Design patterns for building autonomous coding agents. Covers tool integration, permission systems, browser automation, and human-in-the-loop workflows. Use when building AI agents, designing tool ...", @@ -550,7 +586,7 @@ }, { "id": "autonomous-agents", - "path": "skills/autonomous-agents", + "path": "skills\\autonomous-agents", "category": "uncategorized", "name": "autonomous-agents", "description": "Autonomous agents are AI systems that can independently decompose goals, plan actions, execute tools, and self-correct without constant human guidance. The challenge isn't making them capable - it'...", @@ -559,7 +595,7 @@ }, { "id": "avalonia-layout-zafiro", - "path": "skills/avalonia-layout-zafiro", + "path": "skills\\avalonia-layout-zafiro", "category": "uncategorized", "name": "avalonia-layout-zafiro", "description": "Guidelines for modern Avalonia UI layout using Zafiro.Avalonia, emphasizing shared styles, generic components, and avoiding XAML redundancy.", @@ -568,7 +604,7 @@ }, { "id": "avalonia-viewmodels-zafiro", - "path": "skills/avalonia-viewmodels-zafiro", + "path": "skills\\avalonia-viewmodels-zafiro", "category": "uncategorized", "name": "avalonia-viewmodels-zafiro", "description": "Optimal ViewModel and Wizard creation patterns for Avalonia using Zafiro and ReactiveUI.", @@ -577,7 +613,7 @@ }, { "id": "avalonia-zafiro-development", - "path": "skills/avalonia-zafiro-development", + "path": "skills\\avalonia-zafiro-development", "category": "uncategorized", "name": "avalonia-zafiro-development", "description": "Mandatory skills, conventions, and behavioral rules for Avalonia UI development using the Zafiro toolkit.", @@ -586,7 +622,7 @@ }, { "id": "aws-compliance-checker", - "path": "skills/security/aws-compliance-checker", + "path": "skills\\security\\aws-compliance-checker", "category": "security", "name": "aws-compliance-checker", "description": "Automated compliance checking against CIS, PCI-DSS, HIPAA, and SOC 2 benchmarks", @@ -595,7 +631,7 @@ }, { "id": "aws-cost-cleanup", - "path": "skills/aws-cost-cleanup", + "path": "skills\\aws-cost-cleanup", "category": "uncategorized", "name": "aws-cost-cleanup", "description": "Automated cleanup of unused AWS resources to reduce costs", @@ -604,7 +640,7 @@ }, { "id": "aws-cost-optimizer", - "path": "skills/aws-cost-optimizer", + "path": "skills\\aws-cost-optimizer", "category": "uncategorized", "name": "aws-cost-optimizer", "description": "Comprehensive AWS cost analysis and optimization recommendations using AWS CLI and Cost Explorer", @@ -613,7 +649,7 @@ }, { "id": "aws-iam-best-practices", - "path": "skills/security/aws-iam-best-practices", + "path": "skills\\security\\aws-iam-best-practices", "category": "security", "name": "aws-iam-best-practices", "description": "IAM policy review, hardening, and least privilege implementation", @@ -622,7 +658,7 @@ }, { "id": "aws-penetration-testing", - "path": "skills/aws-penetration-testing", + "path": "skills\\aws-penetration-testing", "category": "uncategorized", "name": "aws-penetration-testing", "description": "This skill should be used when the user asks to \"pentest AWS\", \"test AWS security\", \"enumerate IAM\", \"exploit cloud infrastructure\", \"AWS privilege escalation\", \"S3 bucket testing...", @@ -631,7 +667,7 @@ }, { "id": "aws-secrets-rotation", - "path": "skills/security/aws-secrets-rotation", + "path": "skills\\security\\aws-secrets-rotation", "category": "security", "name": "aws-secrets-rotation", "description": "Automate AWS secrets rotation for RDS, API keys, and credentials", @@ -640,7 +676,7 @@ }, { "id": "aws-security-audit", - "path": "skills/security/aws-security-audit", + "path": "skills\\security\\aws-security-audit", "category": "security", "name": "aws-security-audit", "description": "Comprehensive AWS security posture assessment using AWS CLI and security best practices", @@ -649,7 +685,7 @@ }, { "id": "aws-serverless", - "path": "skills/aws-serverless", + "path": "skills\\aws-serverless", "category": "uncategorized", "name": "aws-serverless", "description": "Specialized skill for building production-ready serverless applications on AWS. Covers Lambda functions, API Gateway, DynamoDB, SQS/SNS event-driven patterns, SAM/CDK deployment, and cold start opt...", @@ -658,7 +694,7 @@ }, { "id": "aws-skills", - "path": "skills/aws-skills", + "path": "skills\\aws-skills", "category": "uncategorized", "name": "aws-skills", "description": "AWS development with infrastructure automation and cloud architecture patterns", @@ -667,7 +703,7 @@ }, { "id": "azd-deployment", - "path": "skills/azd-deployment", + "path": "skills\\azd-deployment", "category": "uncategorized", "name": "azd-deployment", "description": "Deploy containerized applications to Azure Container Apps using Azure Developer CLI (azd). Use when setting up azd projects, writing azure.yaml configuration, creating Bicep infrastructure for Cont...", @@ -676,727 +712,25 @@ }, { "id": "azure-ai-agents-persistent-dotnet", - "path": "skills/azure-ai-agents-persistent-dotnet", + "path": "skills\\azure-ai-agents-persistent-dotnet", "category": "uncategorized", - "name": "Azure Ai Agents Persistent Dotnet", - "description": "Low-level SDK for creating and managing persistent AI agents with threads, messages, runs, and tools.", + "name": "azure-ai-agents-persistent-dotnet", + "description": "Azure AI Agents Persistent SDK for .NET. Low-level SDK for creating and managing AI agents with threads, messages, runs, and tools. Use for agent CRUD, conversation threads, streaming responses, function calling, file search, and code interpreter. Triggers: \"PersistentAgentsClient\", \"persistent agents\", \"agent threads\", \"agent runs\", \"streaming agents\", \"function calling agents .NET\".\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "azure-ai-agents-persistent-java", - "path": "skills/azure-ai-agents-persistent-java", + "path": "skills\\azure-ai-agents-persistent-java", "category": "uncategorized", - "name": "Azure Ai Agents Persistent Java", - "description": "Low-level SDK for creating and managing persistent AI agents with threads, messages, runs, and tools.", + "name": "azure-ai-agents-persistent-java", + "description": "Azure AI Agents Persistent SDK for Java. Low-level SDK for creating and managing AI agents with threads, messages, runs, and tools.\nTriggers: \"PersistentAgentsClient\", \"persistent agents java\", \"agent threads java\", \"agent runs java\", \"streaming agents java\".\n", "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-ai-contentsafety-py", - "path": "skills/azure-ai-contentsafety-py", - "category": "uncategorized", - "name": "Azure Ai Contentsafety Py", - "description": "Detect harmful user-generated and AI-generated content in applications.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-ai-contentunderstanding-py", - "path": "skills/azure-ai-contentunderstanding-py", - "category": "uncategorized", - "name": "Azure Ai Contentunderstanding Py", - "description": "Multimodal AI service that extracts semantic content from documents, video, audio, and image files for RAG and automated workflows.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-ai-document-intelligence-dotnet", - "path": "skills/azure-ai-document-intelligence-dotnet", - "category": "uncategorized", - "name": "Azure Ai Document Intelligence Dotnet", - "description": "Extract text, tables, and structured data from documents using prebuilt and custom models.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-ai-ml-py", - "path": "skills/azure-ai-ml-py", - "category": "uncategorized", - "name": "Azure Ai Ml Py", - "description": "Client library for managing Azure ML resources: workspaces, jobs, models, data, and compute.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-ai-openai-dotnet", - "path": "skills/azure-ai-openai-dotnet", - "category": "uncategorized", - "name": "Azure Ai Openai Dotnet", - "description": "Client library for Azure OpenAI Service providing access to OpenAI models including GPT-4, GPT-4o, embeddings, DALL-E, and Whisper.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-ai-projects-dotnet", - "path": "skills/azure-ai-projects-dotnet", - "category": "uncategorized", - "name": "Azure Ai Projects Dotnet", - "description": "High-level SDK for Azure AI Foundry project operations including agents, connections, datasets, deployments, evaluations, and indexes.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-ai-projects-java", - "path": "skills/azure-ai-projects-java", - "category": "uncategorized", - "name": "Azure Ai Projects Java", - "description": "High-level SDK for Azure AI Foundry project management with access to connections, datasets, indexes, and evaluations.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-ai-textanalytics-py", - "path": "skills/azure-ai-textanalytics-py", - "category": "uncategorized", - "name": "Azure Ai Textanalytics Py", - "description": "Client library for Azure AI Language service NLP capabilities including sentiment, entities, key phrases, and more.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-ai-transcription-py", - "path": "skills/azure-ai-transcription-py", - "category": "uncategorized", - "name": "Azure Ai Transcription Py", - "description": "Client library for Azure AI Transcription (speech-to-text) with real-time and batch transcription.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-ai-translation-document-py", - "path": "skills/azure-ai-translation-document-py", - "category": "uncategorized", - "name": "Azure Ai Translation Document Py", - "description": "Client library for Azure AI Translator document translation service for batch document translation with format preservation.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-ai-translation-text-py", - "path": "skills/azure-ai-translation-text-py", - "category": "uncategorized", - "name": "Azure Ai Translation Text Py", - "description": "Client library for Azure AI Translator text translation service for real-time text translation, transliteration, and language operations.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-ai-vision-imageanalysis-py", - "path": "skills/azure-ai-vision-imageanalysis-py", - "category": "uncategorized", - "name": "Azure Ai Vision Imageanalysis Py", - "description": "Client library for Azure AI Vision 4.0 image analysis including captions, tags, objects, OCR, and more.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-ai-voicelive-dotnet", - "path": "skills/azure-ai-voicelive-dotnet", - "category": "uncategorized", - "name": "Azure Ai Voicelive Dotnet", - "description": "Real-time voice AI SDK for building bidirectional voice assistants with Azure AI.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-ai-voicelive-java", - "path": "skills/azure-ai-voicelive-java", - "category": "uncategorized", - "name": "Azure Ai Voicelive Java", - "description": "Real-time, bidirectional voice conversations with AI assistants using WebSocket technology.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-ai-voicelive-ts", - "path": "skills/azure-ai-voicelive-ts", - "category": "uncategorized", - "name": "Azure Ai Voicelive Ts", - "description": "Real-time voice AI SDK for building bidirectional voice assistants with Azure AI in Node.js and browser environments.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-appconfiguration-java", - "path": "skills/azure-appconfiguration-java", - "category": "uncategorized", - "name": "Azure Appconfiguration Java", - "description": "Client library for Azure App Configuration, a managed service for centralizing application configurations.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-appconfiguration-py", - "path": "skills/azure-appconfiguration-py", - "category": "uncategorized", - "name": "Azure Appconfiguration Py", - "description": "Centralized configuration management with feature flags and dynamic settings.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-compute-batch-java", - "path": "skills/azure-compute-batch-java", - "category": "uncategorized", - "name": "Azure Compute Batch Java", - "description": "Client library for running large-scale parallel and high-performance computing (HPC) batch jobs in Azure.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-containerregistry-py", - "path": "skills/azure-containerregistry-py", - "category": "uncategorized", - "name": "Azure Containerregistry Py", - "description": "Manage container images, artifacts, and repositories in Azure Container Registry.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-cosmos-java", - "path": "skills/azure-cosmos-java", - "category": "uncategorized", - "name": "Azure Cosmos Java", - "description": "Client library for Azure Cosmos DB NoSQL API with global distribution and reactive patterns.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-cosmos-py", - "path": "skills/azure-cosmos-py", - "category": "uncategorized", - "name": "Azure Cosmos Py", - "description": "Client library for Azure Cosmos DB NoSQL API \u2014 globally distributed, multi-model database.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-cosmos-rust", - "path": "skills/azure-cosmos-rust", - "category": "uncategorized", - "name": "Azure Cosmos Rust", - "description": "Client library for Azure Cosmos DB NoSQL API \u2014 globally distributed, multi-model database.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-cosmos-ts", - "path": "skills/azure-cosmos-ts", - "category": "uncategorized", - "name": "Azure Cosmos Ts", - "description": "Data plane SDK for Azure Cosmos DB NoSQL API operations \u2014 CRUD on documents, queries, bulk operations.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-data-tables-py", - "path": "skills/azure-data-tables-py", - "category": "uncategorized", - "name": "Azure Data Tables Py", - "description": "NoSQL key-value store for structured data (Azure Storage Tables or Cosmos DB Table API).", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-eventgrid-dotnet", - "path": "skills/azure-eventgrid-dotnet", - "category": "uncategorized", - "name": "Azure Eventgrid Dotnet", - "description": "Client library for publishing events to Azure Event Grid topics, domains, and namespaces.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-eventgrid-py", - "path": "skills/azure-eventgrid-py", - "category": "uncategorized", - "name": "Azure Eventgrid Py", - "description": "Event routing service for building event-driven applications with pub/sub semantics.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-eventhub-dotnet", - "path": "skills/azure-eventhub-dotnet", - "category": "uncategorized", - "name": "Azure Eventhub Dotnet", - "description": "High-throughput event streaming SDK for sending and receiving events via Azure Event Hubs.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-eventhub-py", - "path": "skills/azure-eventhub-py", - "category": "uncategorized", - "name": "Azure Eventhub Py", - "description": "Big data streaming platform for high-throughput event ingestion.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-eventhub-rust", - "path": "skills/azure-eventhub-rust", - "category": "uncategorized", - "name": "Azure Eventhub Rust", - "description": "Client library for Azure Event Hubs \u2014 big data streaming platform and event ingestion service.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-identity-dotnet", - "path": "skills/azure-identity-dotnet", - "category": "uncategorized", - "name": "Azure Identity Dotnet", - "description": "Authentication library for Azure SDK clients using Microsoft Entra ID (formerly Azure AD).", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-identity-py", - "path": "skills/azure-identity-py", - "category": "uncategorized", - "name": "Azure Identity Py", - "description": "Authentication library for Azure SDK clients using Microsoft Entra ID (formerly Azure AD).", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-identity-rust", - "path": "skills/azure-identity-rust", - "category": "uncategorized", - "name": "Azure Identity Rust", - "description": "Authentication library for Azure SDK clients using Microsoft Entra ID (formerly Azure AD).", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-keyvault-certificates-rust", - "path": "skills/azure-keyvault-certificates-rust", - "category": "uncategorized", - "name": "Azure Keyvault Certificates Rust", - "description": "Client library for Azure Key Vault Certificates \u2014 secure storage and management of certificates.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-keyvault-keys-rust", - "path": "skills/azure-keyvault-keys-rust", - "category": "uncategorized", - "name": "Azure Keyvault Keys Rust", - "description": "Client library for Azure Key Vault Keys \u2014 secure storage and management of cryptographic keys.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-keyvault-py", - "path": "skills/azure-keyvault-py", - "category": "uncategorized", - "name": "Azure Keyvault Py", - "description": "Secure storage and management for secrets, cryptographic keys, and certificates.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-keyvault-secrets-rust", - "path": "skills/azure-keyvault-secrets-rust", - "category": "uncategorized", - "name": "Azure Keyvault Secrets Rust", - "description": "Client library for Azure Key Vault Secrets \u2014 secure storage for passwords, API keys, and other secrets.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-maps-search-dotnet", - "path": "skills/azure-maps-search-dotnet", - "category": "uncategorized", - "name": "Azure Maps Search Dotnet", - "description": "Azure Maps SDK for .NET providing location-based services: geocoding, routing, rendering, geolocation, and weather.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-messaging-webpubsubservice-py", - "path": "skills/azure-messaging-webpubsubservice-py", - "category": "uncategorized", - "name": "Azure Messaging Webpubsubservice Py", - "description": "Real-time messaging with WebSocket connections at scale.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-mgmt-apicenter-dotnet", - "path": "skills/azure-mgmt-apicenter-dotnet", - "category": "uncategorized", - "name": "Azure Mgmt Apicenter Dotnet", - "description": "Centralized API inventory and governance SDK for managing APIs across your organization.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-mgmt-apicenter-py", - "path": "skills/azure-mgmt-apicenter-py", - "category": "uncategorized", - "name": "Azure Mgmt Apicenter Py", - "description": "Manage API inventory, metadata, and governance in Azure API Center.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-mgmt-apimanagement-dotnet", - "path": "skills/azure-mgmt-apimanagement-dotnet", - "category": "uncategorized", - "name": "Azure Mgmt Apimanagement Dotnet", - "description": "Management plane SDK for provisioning and managing Azure API Management resources via Azure Resource Manager.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-mgmt-apimanagement-py", - "path": "skills/azure-mgmt-apimanagement-py", - "category": "uncategorized", - "name": "Azure Mgmt Apimanagement Py", - "description": "Manage Azure API Management services, APIs, products, and policies.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-mgmt-applicationinsights-dotnet", - "path": "skills/azure-mgmt-applicationinsights-dotnet", - "category": "uncategorized", - "name": "Azure Mgmt Applicationinsights Dotnet", - "description": "Azure Resource Manager SDK for managing Application Insights resources for application performance monitoring.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-mgmt-arizeaiobservabilityeval-dotnet", - "path": "skills/azure-mgmt-arizeaiobservabilityeval-dotnet", - "category": "uncategorized", - "name": "Azure Mgmt Arizeaiobservabilityeval Dotnet", - "description": ".NET SDK for managing Arize AI Observability and Evaluation resources on Azure.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-mgmt-botservice-dotnet", - "path": "skills/azure-mgmt-botservice-dotnet", - "category": "uncategorized", - "name": "Azure Mgmt Botservice Dotnet", - "description": "Management plane SDK for provisioning and managing Azure Bot Service resources via Azure Resource Manager.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-mgmt-botservice-py", - "path": "skills/azure-mgmt-botservice-py", - "category": "uncategorized", - "name": "Azure Mgmt Botservice Py", - "description": "Manage Azure Bot Service resources including bots, channels, and connections.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-mgmt-fabric-dotnet", - "path": "skills/azure-mgmt-fabric-dotnet", - "category": "uncategorized", - "name": "Azure Mgmt Fabric Dotnet", - "description": "Management plane SDK for provisioning and managing Microsoft Fabric capacity resources via Azure Resource Manager.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-mgmt-fabric-py", - "path": "skills/azure-mgmt-fabric-py", - "category": "uncategorized", - "name": "Azure Mgmt Fabric Py", - "description": "Manage Microsoft Fabric capacities and resources programmatically.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-mgmt-weightsandbiases-dotnet", - "path": "skills/azure-mgmt-weightsandbiases-dotnet", - "category": "uncategorized", - "name": "Azure Mgmt Weightsandbiases Dotnet", - "description": "Azure Resource Manager SDK for deploying and managing Weights & Biases ML experiment tracking instances via Azure Marketplace.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-monitor-ingestion-java", - "path": "skills/azure-monitor-ingestion-java", - "category": "uncategorized", - "name": "Azure Monitor Ingestion Java", - "description": "Client library for sending custom logs to Azure Monitor using the Logs Ingestion API via Data Collection Rules.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-monitor-ingestion-py", - "path": "skills/azure-monitor-ingestion-py", - "category": "uncategorized", - "name": "Azure Monitor Ingestion Py", - "description": "Send custom logs to Azure Monitor Log Analytics workspace using the Logs Ingestion API.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-monitor-opentelemetry-exporter-java", - "path": "skills/azure-monitor-opentelemetry-exporter-java", - "category": "uncategorized", - "name": "Azure Monitor Opentelemetry Exporter Java", - "description": "> **\u26a0\ufe0f DEPRECATION NOTICE**: This package is deprecated. Migrate to `azure-monitor-opentelemetry-autoconfigure`. > > See [Migration Guide](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/monitor/azure-monitor-opentelemetry-exporter/MIGRATIO", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-monitor-opentelemetry-exporter-py", - "path": "skills/azure-monitor-opentelemetry-exporter-py", - "category": "uncategorized", - "name": "Azure Monitor Opentelemetry Exporter Py", - "description": "Low-level exporter for sending OpenTelemetry traces, metrics, and logs to Application Insights.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-monitor-opentelemetry-py", - "path": "skills/azure-monitor-opentelemetry-py", - "category": "uncategorized", - "name": "Azure Monitor Opentelemetry Py", - "description": "One-line setup for Application Insights with OpenTelemetry auto-instrumentation.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-monitor-query-java", - "path": "skills/azure-monitor-query-java", - "category": "uncategorized", - "name": "Azure Monitor Query Java", - "description": "> **DEPRECATION NOTICE**: This package is deprecated in favor of: > - `azure-monitor-query-logs` \u2014 For Log Analytics queries > - `azure-monitor-query-metrics` \u2014 For metrics queries > > See migration guides: [Logs Migration](https://github.com/Azure/a", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-monitor-query-py", - "path": "skills/azure-monitor-query-py", - "category": "uncategorized", - "name": "Azure Monitor Query Py", - "description": "Query logs and metrics from Azure Monitor and Log Analytics workspaces.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-postgres-ts", - "path": "skills/azure-postgres-ts", - "category": "uncategorized", - "name": "Azure Postgres Ts", - "description": "Connect to Azure Database for PostgreSQL Flexible Server using the `pg` (node-postgres) package with support for password and Microsoft Entra ID (passwordless) authentication.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-resource-manager-cosmosdb-dotnet", - "path": "skills/azure-resource-manager-cosmosdb-dotnet", - "category": "uncategorized", - "name": "Azure Resource Manager Cosmosdb Dotnet", - "description": "Management plane SDK for provisioning and managing Azure Cosmos DB resources via Azure Resource Manager.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-resource-manager-durabletask-dotnet", - "path": "skills/azure-resource-manager-durabletask-dotnet", - "category": "uncategorized", - "name": "Azure Resource Manager Durabletask Dotnet", - "description": "Management plane SDK for provisioning and managing Azure Durable Task Scheduler resources via Azure Resource Manager.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-resource-manager-mysql-dotnet", - "path": "skills/azure-resource-manager-mysql-dotnet", - "category": "uncategorized", - "name": "Azure Resource Manager Mysql Dotnet", - "description": "Azure Resource Manager SDK for managing MySQL Flexible Server deployments.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-resource-manager-playwright-dotnet", - "path": "skills/azure-resource-manager-playwright-dotnet", - "category": "uncategorized", - "name": "Azure Resource Manager Playwright Dotnet", - "description": "Management plane SDK for provisioning and managing Microsoft Playwright Testing workspaces via Azure Resource Manager.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-resource-manager-postgresql-dotnet", - "path": "skills/azure-resource-manager-postgresql-dotnet", - "category": "uncategorized", - "name": "Azure Resource Manager Postgresql Dotnet", - "description": "Azure Resource Manager SDK for managing PostgreSQL Flexible Server deployments.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-resource-manager-redis-dotnet", - "path": "skills/azure-resource-manager-redis-dotnet", - "category": "uncategorized", - "name": "Azure Resource Manager Redis Dotnet", - "description": "Management plane SDK for provisioning and managing Azure Cache for Redis resources via Azure Resource Manager.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-resource-manager-sql-dotnet", - "path": "skills/azure-resource-manager-sql-dotnet", - "category": "uncategorized", - "name": "Azure Resource Manager Sql Dotnet", - "description": "Management plane SDK for provisioning and managing Azure SQL resources via Azure Resource Manager.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-search-documents-dotnet", - "path": "skills/azure-search-documents-dotnet", - "category": "uncategorized", - "name": "Azure Search Documents Dotnet", - "description": "Build search applications with full-text, vector, semantic, and hybrid search capabilities.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-search-documents-py", - "path": "skills/azure-search-documents-py", - "category": "uncategorized", - "name": "Azure Search Documents Py", - "description": "Full-text, vector, and hybrid search with AI enrichment capabilities.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-security-keyvault-keys-dotnet", - "path": "skills/azure-security-keyvault-keys-dotnet", - "category": "uncategorized", - "name": "Azure Security Keyvault Keys Dotnet", - "description": "Client library for managing cryptographic keys in Azure Key Vault and Managed HSM.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-servicebus-dotnet", - "path": "skills/azure-servicebus-dotnet", - "category": "uncategorized", - "name": "Azure Servicebus Dotnet", - "description": "Enterprise messaging SDK for reliable message delivery with queues, topics, subscriptions, and sessions.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-servicebus-py", - "path": "skills/azure-servicebus-py", - "category": "uncategorized", - "name": "Azure Servicebus Py", - "description": "Enterprise messaging for reliable cloud communication with queues and pub/sub topics.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-speech-to-text-rest-py", - "path": "skills/azure-speech-to-text-rest-py", - "category": "uncategorized", - "name": "Azure Speech To Text Rest Py", - "description": "Simple REST API for speech-to-text transcription of short audio files (up to 60 seconds). No SDK required - just HTTP requests.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-storage-blob-py", - "path": "skills/azure-storage-blob-py", - "category": "uncategorized", - "name": "Azure Storage Blob Py", - "description": "Client library for Azure Blob Storage \u2014 object storage for unstructured data.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-storage-blob-rust", - "path": "skills/azure-storage-blob-rust", - "category": "uncategorized", - "name": "Azure Storage Blob Rust", - "description": "Client library for Azure Blob Storage \u2014 Microsoft's object storage solution for the cloud.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-storage-blob-ts", - "path": "skills/azure-storage-blob-ts", - "category": "uncategorized", - "name": "Azure Storage Blob Ts", - "description": "SDK for Azure Blob Storage operations \u2014 upload, download, list, and manage blobs and containers.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-storage-file-datalake-py", - "path": "skills/azure-storage-file-datalake-py", - "category": "uncategorized", - "name": "Azure Storage File Datalake Py", - "description": "Hierarchical file system for big data analytics workloads.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-storage-file-share-py", - "path": "skills/azure-storage-file-share-py", - "category": "uncategorized", - "name": "Azure Storage File Share Py", - "description": "Manage SMB file shares for cloud-native and lift-and-shift scenarios.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-storage-file-share-ts", - "path": "skills/azure-storage-file-share-ts", - "category": "uncategorized", - "name": "Azure Storage File Share Ts", - "description": "SDK for Azure File Share operations \u2014 SMB file shares, directories, and file operations.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-storage-queue-py", - "path": "skills/azure-storage-queue-py", - "category": "uncategorized", - "name": "Azure Storage Queue Py", - "description": "Simple, cost-effective message queuing for asynchronous communication.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-storage-queue-ts", - "path": "skills/azure-storage-queue-ts", - "category": "uncategorized", - "name": "Azure Storage Queue Ts", - "description": "SDK for Azure Queue Storage operations \u2014 send, receive, peek, and manage messages in queues.", - "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "azure-ai-anomalydetector-java", - "path": "skills/azure-ai-anomalydetector-java", + "path": "skills\\azure-ai-anomalydetector-java", "category": "uncategorized", "name": "azure-ai-anomalydetector-java", "description": "Build anomaly detection applications with Azure AI Anomaly Detector SDK for Java. Use when implementing univariate/multivariate anomaly detection, time-series analysis, or AI-powered monitoring.", @@ -1405,25 +739,52 @@ }, { "id": "azure-ai-contentsafety-java", - "path": "skills/azure-ai-contentsafety-java", + "path": "skills\\azure-ai-contentsafety-java", "category": "uncategorized", "name": "azure-ai-contentsafety-java", "description": "Build content moderation applications with Azure AI Content Safety SDK for Java. Use when implementing text/image analysis, blocklist management, or harm detection for hate, violence, sexual conten...", "risk": "unknown", "source": "community" }, + { + "id": "azure-ai-contentsafety-py", + "path": "skills\\azure-ai-contentsafety-py", + "category": "uncategorized", + "name": "azure-ai-contentsafety-py", + "description": "Azure AI Content Safety SDK for Python. Use for detecting harmful content in text and images with multi-severity classification.\nTriggers: \"azure-ai-contentsafety\", \"ContentSafetyClient\", \"content moderation\", \"harmful content\", \"text analysis\", \"image analysis\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-ai-contentsafety-ts", - "path": "skills/azure-ai-contentsafety-ts", + "path": "skills\\azure-ai-contentsafety-ts", "category": "uncategorized", "name": "azure-ai-contentsafety-ts", "description": "Analyze text and images for harmful content using Azure AI Content Safety (@azure-rest/ai-content-safety). Use when moderating user-generated content, detecting hate speech, violence, sexual conten...", "risk": "unknown", "source": "community" }, + { + "id": "azure-ai-contentunderstanding-py", + "path": "skills\\azure-ai-contentunderstanding-py", + "category": "uncategorized", + "name": "azure-ai-contentunderstanding-py", + "description": "Azure AI Content Understanding SDK for Python. Use for multimodal content extraction from documents, images, audio, and video.\nTriggers: \"azure-ai-contentunderstanding\", \"ContentUnderstandingClient\", \"multimodal analysis\", \"document extraction\", \"video analysis\", \"audio transcription\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-ai-document-intelligence-dotnet", + "path": "skills\\azure-ai-document-intelligence-dotnet", + "category": "uncategorized", + "name": "azure-ai-document-intelligence-dotnet", + "description": "Azure AI Document Intelligence SDK for .NET. Extract text, tables, and structured data from documents using prebuilt and custom models. Use for invoice processing, receipt extraction, ID document analysis, and custom document models. Triggers: \"Document Intelligence\", \"DocumentIntelligenceClient\", \"form recognizer\", \"invoice extraction\", \"receipt OCR\", \"document analysis .NET\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-ai-document-intelligence-ts", - "path": "skills/azure-ai-document-intelligence-ts", + "path": "skills\\azure-ai-document-intelligence-ts", "category": "uncategorized", "name": "azure-ai-document-intelligence-ts", "description": "Extract text, tables, and structured data from documents using Azure Document Intelligence (@azure-rest/ai-document-intelligence). Use when processing invoices, receipts, IDs, forms, or building cu...", @@ -1432,16 +793,52 @@ }, { "id": "azure-ai-formrecognizer-java", - "path": "skills/azure-ai-formrecognizer-java", + "path": "skills\\azure-ai-formrecognizer-java", "category": "uncategorized", "name": "azure-ai-formrecognizer-java", "description": "Build document analysis applications with Azure Document Intelligence (Form Recognizer) SDK for Java. Use when extracting text, tables, key-value pairs from documents, receipts, invoices, or buildi...", "risk": "unknown", "source": "community" }, + { + "id": "azure-ai-ml-py", + "path": "skills\\azure-ai-ml-py", + "category": "uncategorized", + "name": "azure-ai-ml-py", + "description": "Azure Machine Learning SDK v2 for Python. Use for ML workspaces, jobs, models, datasets, compute, and pipelines.\nTriggers: \"azure-ai-ml\", \"MLClient\", \"workspace\", \"model registry\", \"training jobs\", \"datasets\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-ai-openai-dotnet", + "path": "skills\\azure-ai-openai-dotnet", + "category": "uncategorized", + "name": "azure-ai-openai-dotnet", + "description": "Azure OpenAI SDK for .NET. Client library for Azure OpenAI and OpenAI services. Use for chat completions, embeddings, image generation, audio transcription, and assistants. Triggers: \"Azure OpenAI\", \"AzureOpenAIClient\", \"ChatClient\", \"chat completions .NET\", \"GPT-4\", \"embeddings\", \"DALL-E\", \"Whisper\", \"OpenAI .NET\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-ai-projects-dotnet", + "path": "skills\\azure-ai-projects-dotnet", + "category": "uncategorized", + "name": "azure-ai-projects-dotnet", + "description": "Azure AI Projects SDK for .NET. High-level client for Azure AI Foundry projects including agents, connections, datasets, deployments, evaluations, and indexes. Use for AI Foundry project management, versioned agents, and orchestration. Triggers: \"AI Projects\", \"AIProjectClient\", \"Foundry project\", \"versioned agents\", \"evaluations\", \"datasets\", \"connections\", \"deployments .NET\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-ai-projects-java", + "path": "skills\\azure-ai-projects-java", + "category": "uncategorized", + "name": "azure-ai-projects-java", + "description": "Azure AI Projects SDK for Java. High-level SDK for Azure AI Foundry project management including connections, datasets, indexes, and evaluations.\nTriggers: \"AIProjectClient java\", \"azure ai projects java\", \"Foundry project java\", \"ConnectionsClient\", \"DatasetsClient\", \"IndexesClient\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-ai-projects-py", - "path": "skills/azure-ai-projects-py", + "path": "skills\\azure-ai-projects-py", "category": "uncategorized", "name": "azure-ai-projects-py", "description": "Build AI applications using the Azure AI Projects Python SDK (azure-ai-projects). Use when working with Foundry project clients, creating versioned agents with PromptAgentDefinition, running evalua...", @@ -1450,16 +847,52 @@ }, { "id": "azure-ai-projects-ts", - "path": "skills/azure-ai-projects-ts", + "path": "skills\\azure-ai-projects-ts", "category": "uncategorized", "name": "azure-ai-projects-ts", "description": "Build AI applications using Azure AI Projects SDK for JavaScript (@azure/ai-projects). Use when working with Foundry project clients, agents, connections, deployments, datasets, indexes, evaluation...", "risk": "unknown", "source": "community" }, + { + "id": "azure-ai-textanalytics-py", + "path": "skills\\azure-ai-textanalytics-py", + "category": "uncategorized", + "name": "azure-ai-textanalytics-py", + "description": "Azure AI Text Analytics SDK for sentiment analysis, entity recognition, key phrases, language detection, PII, and healthcare NLP. Use for natural language processing on text.\nTriggers: \"text analytics\", \"sentiment analysis\", \"entity recognition\", \"key phrase\", \"PII detection\", \"TextAnalyticsClient\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-ai-transcription-py", + "path": "skills\\azure-ai-transcription-py", + "category": "uncategorized", + "name": "azure-ai-transcription-py", + "description": "Azure AI Transcription SDK for Python. Use for real-time and batch speech-to-text transcription with timestamps and diarization.\nTriggers: \"transcription\", \"speech to text\", \"Azure AI Transcription\", \"TranscriptionClient\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-ai-translation-document-py", + "path": "skills\\azure-ai-translation-document-py", + "category": "uncategorized", + "name": "azure-ai-translation-document-py", + "description": "Azure AI Document Translation SDK for batch translation of documents with format preservation. Use for translating Word, PDF, Excel, PowerPoint, and other document formats at scale.\nTriggers: \"document translation\", \"batch translation\", \"translate documents\", \"DocumentTranslationClient\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-ai-translation-text-py", + "path": "skills\\azure-ai-translation-text-py", + "category": "uncategorized", + "name": "azure-ai-translation-text-py", + "description": "Azure AI Text Translation SDK for real-time text translation, transliteration, language detection, and dictionary lookup. Use for translating text content in applications.\nTriggers: \"text translation\", \"translator\", \"translate text\", \"transliterate\", \"TextTranslationClient\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-ai-translation-ts", - "path": "skills/azure-ai-translation-ts", + "path": "skills\\azure-ai-translation-ts", "category": "uncategorized", "name": "azure-ai-translation-ts", "description": "Build translation applications using Azure Translation SDKs for JavaScript (@azure-rest/ai-translation-text, @azure-rest/ai-translation-document). Use when implementing text translation, transliter...", @@ -1468,25 +901,79 @@ }, { "id": "azure-ai-vision-imageanalysis-java", - "path": "skills/azure-ai-vision-imageanalysis-java", + "path": "skills\\azure-ai-vision-imageanalysis-java", "category": "uncategorized", "name": "azure-ai-vision-imageanalysis-java", "description": "Build image analysis applications with Azure AI Vision SDK for Java. Use when implementing image captioning, OCR text extraction, object detection, tagging, or smart cropping.", "risk": "unknown", "source": "community" }, + { + "id": "azure-ai-vision-imageanalysis-py", + "path": "skills\\azure-ai-vision-imageanalysis-py", + "category": "uncategorized", + "name": "azure-ai-vision-imageanalysis-py", + "description": "Azure AI Vision Image Analysis SDK for captions, tags, objects, OCR, people detection, and smart cropping. Use for computer vision and image understanding tasks.\nTriggers: \"image analysis\", \"computer vision\", \"OCR\", \"object detection\", \"ImageAnalysisClient\", \"image caption\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-ai-voicelive-dotnet", + "path": "skills\\azure-ai-voicelive-dotnet", + "category": "uncategorized", + "name": "azure-ai-voicelive-dotnet", + "description": "Azure AI Voice Live SDK for .NET. Build real-time voice AI applications with bidirectional WebSocket communication. Use for voice assistants, conversational AI, real-time speech-to-speech, and voice-enabled chatbots. Triggers: \"voice live\", \"real-time voice\", \"VoiceLiveClient\", \"VoiceLiveSession\", \"voice assistant .NET\", \"bidirectional audio\", \"speech-to-speech\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-ai-voicelive-java", + "path": "skills\\azure-ai-voicelive-java", + "category": "uncategorized", + "name": "azure-ai-voicelive-java", + "description": "Azure AI VoiceLive SDK for Java. Real-time bidirectional voice conversations with AI assistants using WebSocket.\nTriggers: \"VoiceLiveClient java\", \"voice assistant java\", \"real-time voice java\", \"audio streaming java\", \"voice activity detection java\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-ai-voicelive-py", - "path": "skills/azure-ai-voicelive-py", + "path": "skills\\azure-ai-voicelive-py", "category": "uncategorized", "name": "azure-ai-voicelive-py", "description": "Build real-time voice AI applications using Azure AI Voice Live SDK (azure-ai-voicelive). Use this skill when creating Python applications that need real-time bidirectional audio communication with...", "risk": "unknown", "source": "community" }, + { + "id": "azure-ai-voicelive-ts", + "path": "skills\\azure-ai-voicelive-ts", + "category": "uncategorized", + "name": "azure-ai-voicelive-ts", + "description": "Azure AI Voice Live SDK for JavaScript/TypeScript. Build real-time voice AI applications with bidirectional WebSocket communication. Use for voice assistants, conversational AI, real-time speech-to-speech, and voice-enabled chatbots in Node.js or browser environments. Triggers: \"voice live\", \"real-time voice\", \"VoiceLiveClient\", \"VoiceLiveSession\", \"voice assistant TypeScript\", \"bidirectional audio\", \"speech-to-speech JavaScript\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-appconfiguration-java", + "path": "skills\\azure-appconfiguration-java", + "category": "uncategorized", + "name": "azure-appconfiguration-java", + "description": "Azure App Configuration SDK for Java. Centralized application configuration management with key-value settings, feature flags, and snapshots.\nTriggers: \"ConfigurationClient java\", \"app configuration java\", \"feature flag java\", \"configuration setting java\", \"azure config java\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-appconfiguration-py", + "path": "skills\\azure-appconfiguration-py", + "category": "uncategorized", + "name": "azure-appconfiguration-py", + "description": "Azure App Configuration SDK for Python. Use for centralized configuration management, feature flags, and dynamic settings.\nTriggers: \"azure-appconfiguration\", \"AzureAppConfigurationClient\", \"feature flags\", \"configuration\", \"key-value settings\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-appconfiguration-ts", - "path": "skills/azure-appconfiguration-ts", + "path": "skills\\azure-appconfiguration-ts", "category": "uncategorized", "name": "azure-appconfiguration-ts", "description": "Build applications using Azure App Configuration SDK for JavaScript (@azure/app-configuration). Use when working with configuration settings, feature flags, Key Vault references, dynamic refresh, o...", @@ -1495,7 +982,7 @@ }, { "id": "azure-communication-callautomation-java", - "path": "skills/azure-communication-callautomation-java", + "path": "skills\\azure-communication-callautomation-java", "category": "uncategorized", "name": "azure-communication-callautomation-java", "description": "Build call automation workflows with Azure Communication Services Call Automation Java SDK. Use when implementing IVR systems, call routing, call recording, DTMF recognition, text-to-speech, or AI-...", @@ -1504,7 +991,7 @@ }, { "id": "azure-communication-callingserver-java", - "path": "skills/azure-communication-callingserver-java", + "path": "skills\\azure-communication-callingserver-java", "category": "uncategorized", "name": "azure-communication-callingserver-java", "description": "Azure Communication Services CallingServer (legacy) Java SDK. Note - This SDK is deprecated. Use azure-communication-callautomation instead for new projects. Only use this skill when maintaining le...", @@ -1513,7 +1000,7 @@ }, { "id": "azure-communication-chat-java", - "path": "skills/azure-communication-chat-java", + "path": "skills\\azure-communication-chat-java", "category": "uncategorized", "name": "azure-communication-chat-java", "description": "Build real-time chat applications with Azure Communication Services Chat Java SDK. Use when implementing chat threads, messaging, participants, read receipts, typing notifications, or real-time cha...", @@ -1522,7 +1009,7 @@ }, { "id": "azure-communication-common-java", - "path": "skills/azure-communication-common-java", + "path": "skills\\azure-communication-common-java", "category": "uncategorized", "name": "azure-communication-common-java", "description": "Azure Communication Services common utilities for Java. Use when working with CommunicationTokenCredential, user identifiers, token refresh, or shared authentication across ACS services.", @@ -1531,52 +1018,160 @@ }, { "id": "azure-communication-sms-java", - "path": "skills/azure-communication-sms-java", + "path": "skills\\azure-communication-sms-java", "category": "uncategorized", "name": "azure-communication-sms-java", "description": "Send SMS messages with Azure Communication Services SMS Java SDK. Use when implementing SMS notifications, alerts, OTP delivery, bulk messaging, or delivery reports.", "risk": "unknown", "source": "community" }, + { + "id": "azure-compute-batch-java", + "path": "skills\\azure-compute-batch-java", + "category": "uncategorized", + "name": "azure-compute-batch-java", + "description": "Azure Batch SDK for Java. Run large-scale parallel and HPC batch jobs with pools, jobs, tasks, and compute nodes.\nTriggers: \"BatchClient java\", \"azure batch java\", \"batch pool java\", \"batch job java\", \"HPC java\", \"parallel computing java\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-containerregistry-py", + "path": "skills\\azure-containerregistry-py", + "category": "uncategorized", + "name": "azure-containerregistry-py", + "description": "Azure Container Registry SDK for Python. Use for managing container images, artifacts, and repositories.\nTriggers: \"azure-containerregistry\", \"ContainerRegistryClient\", \"container images\", \"docker registry\", \"ACR\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-cosmos-db-py", - "path": "skills/azure-cosmos-db-py", + "path": "skills\\azure-cosmos-db-py", "category": "uncategorized", "name": "azure-cosmos-db-py", "description": "Build Azure Cosmos DB NoSQL services with Python/FastAPI following production-grade patterns. Use when implementing database client setup with dual auth (DefaultAzureCredential + emulator), service...", "risk": "unknown", "source": "community" }, + { + "id": "azure-cosmos-java", + "path": "skills\\azure-cosmos-java", + "category": "uncategorized", + "name": "azure-cosmos-java", + "description": "Azure Cosmos DB SDK for Java. NoSQL database operations with global distribution, multi-model support, and reactive patterns.\nTriggers: \"CosmosClient java\", \"CosmosAsyncClient\", \"cosmos database java\", \"cosmosdb java\", \"document database java\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-cosmos-py", + "path": "skills\\azure-cosmos-py", + "category": "uncategorized", + "name": "azure-cosmos-py", + "description": "Azure Cosmos DB SDK for Python (NoSQL API). Use for document CRUD, queries, containers, and globally distributed data.\nTriggers: \"cosmos db\", \"CosmosClient\", \"container\", \"document\", \"NoSQL\", \"partition key\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-cosmos-rust", + "path": "skills\\azure-cosmos-rust", + "category": "uncategorized", + "name": "azure-cosmos-rust", + "description": "Azure Cosmos DB SDK for Rust (NoSQL API). Use for document CRUD, queries, containers, and globally distributed data.\nTriggers: \"cosmos db rust\", \"CosmosClient rust\", \"container\", \"document rust\", \"NoSQL rust\", \"partition key\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-cosmos-ts", + "path": "skills\\azure-cosmos-ts", + "category": "uncategorized", + "name": "azure-cosmos-ts", + "description": "Azure Cosmos DB JavaScript/TypeScript SDK (@azure/cosmos) for data plane operations. Use for CRUD operations on documents, queries, bulk operations, and container management. Triggers: \"Cosmos DB\", \"@azure/cosmos\", \"CosmosClient\", \"document CRUD\", \"NoSQL queries\", \"bulk operations\", \"partition key\", \"container.items\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-data-tables-java", - "path": "skills/azure-data-tables-java", + "path": "skills\\azure-data-tables-java", "category": "uncategorized", "name": "azure-data-tables-java", "description": "Build table storage applications with Azure Tables SDK for Java. Use when working with Azure Table Storage or Cosmos DB Table API for NoSQL key-value data, schemaless storage, or structured data at...", "risk": "unknown", "source": "community" }, + { + "id": "azure-data-tables-py", + "path": "skills\\azure-data-tables-py", + "category": "uncategorized", + "name": "azure-data-tables-py", + "description": "Azure Tables SDK for Python (Storage and Cosmos DB). Use for NoSQL key-value storage, entity CRUD, and batch operations.\nTriggers: \"table storage\", \"TableServiceClient\", \"TableClient\", \"entities\", \"PartitionKey\", \"RowKey\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-eventgrid-dotnet", + "path": "skills\\azure-eventgrid-dotnet", + "category": "uncategorized", + "name": "azure-eventgrid-dotnet", + "description": "Azure Event Grid SDK for .NET. Client library for publishing and consuming events with Azure Event Grid. Use for event-driven architectures, pub/sub messaging, CloudEvents, and EventGridEvents. Triggers: \"Event Grid\", \"EventGridPublisherClient\", \"CloudEvent\", \"EventGridEvent\", \"publish events .NET\", \"event-driven\", \"pub/sub\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-eventgrid-java", - "path": "skills/azure-eventgrid-java", + "path": "skills\\azure-eventgrid-java", "category": "uncategorized", "name": "azure-eventgrid-java", "description": "Build event-driven applications with Azure Event Grid SDK for Java. Use when publishing events, implementing pub/sub patterns, or integrating with Azure services via events.", "risk": "unknown", "source": "community" }, + { + "id": "azure-eventgrid-py", + "path": "skills\\azure-eventgrid-py", + "category": "uncategorized", + "name": "azure-eventgrid-py", + "description": "Azure Event Grid SDK for Python. Use for publishing events, handling CloudEvents, and event-driven architectures.\nTriggers: \"event grid\", \"EventGridPublisherClient\", \"CloudEvent\", \"EventGridEvent\", \"publish events\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-eventhub-dotnet", + "path": "skills\\azure-eventhub-dotnet", + "category": "uncategorized", + "name": "azure-eventhub-dotnet", + "description": "Azure Event Hubs SDK for .NET. Use for high-throughput event streaming: sending events (EventHubProducerClient, EventHubBufferedProducerClient), receiving events (EventProcessorClient with checkpointing), partition management, and real-time data ingestion. Triggers: \"Event Hubs\", \"event streaming\", \"EventHubProducerClient\", \"EventProcessorClient\", \"send events\", \"receive events\", \"checkpointing\", \"partition\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-eventhub-java", - "path": "skills/azure-eventhub-java", + "path": "skills\\azure-eventhub-java", "category": "uncategorized", "name": "azure-eventhub-java", "description": "Build real-time streaming applications with Azure Event Hubs SDK for Java. Use when implementing event streaming, high-throughput data ingestion, or building event-driven architectures.", "risk": "unknown", "source": "community" }, + { + "id": "azure-eventhub-py", + "path": "skills\\azure-eventhub-py", + "category": "uncategorized", + "name": "azure-eventhub-py", + "description": "Azure Event Hubs SDK for Python streaming. Use for high-throughput event ingestion, producers, consumers, and checkpointing.\nTriggers: \"event hubs\", \"EventHubProducerClient\", \"EventHubConsumerClient\", \"streaming\", \"partitions\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-eventhub-rust", + "path": "skills\\azure-eventhub-rust", + "category": "uncategorized", + "name": "azure-eventhub-rust", + "description": "Azure Event Hubs SDK for Rust. Use for sending and receiving events, streaming data ingestion.\nTriggers: \"event hubs rust\", \"ProducerClient rust\", \"ConsumerClient rust\", \"send event rust\", \"streaming rust\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-eventhub-ts", - "path": "skills/azure-eventhub-ts", + "path": "skills\\azure-eventhub-ts", "category": "uncategorized", "name": "azure-eventhub-ts", "description": "Build event streaming applications using Azure Event Hubs SDK for JavaScript (@azure/event-hubs). Use when implementing high-throughput event ingestion, real-time analytics, IoT telemetry, or event...", @@ -1585,97 +1180,439 @@ }, { "id": "azure-functions", - "path": "skills/azure-functions", + "path": "skills\\azure-functions", "category": "uncategorized", "name": "azure-functions", "description": "Expert patterns for Azure Functions development including isolated worker model, Durable Functions orchestration, cold start optimization, and production patterns. Covers .NET, Python, and Node.js ...", "risk": "unknown", "source": "vibeship-spawner-skills (Apache 2.0)" }, + { + "id": "azure-identity-dotnet", + "path": "skills\\azure-identity-dotnet", + "category": "uncategorized", + "name": "azure-identity-dotnet", + "description": "Azure Identity SDK for .NET. Authentication library for Azure SDK clients using Microsoft Entra ID. Use for DefaultAzureCredential, managed identity, service principals, and developer credentials. Triggers: \"Azure Identity\", \"DefaultAzureCredential\", \"ManagedIdentityCredential\", \"ClientSecretCredential\", \"authentication .NET\", \"Azure auth\", \"credential chain\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-identity-java", - "path": "skills/azure-identity-java", + "path": "skills\\azure-identity-java", "category": "uncategorized", "name": "azure-identity-java", "description": "Azure Identity Java SDK for authentication with Azure services. Use when implementing DefaultAzureCredential, managed identity, service principal, or any Azure authentication pattern in Java applic...", "risk": "unknown", "source": "community" }, + { + "id": "azure-identity-py", + "path": "skills\\azure-identity-py", + "category": "uncategorized", + "name": "azure-identity-py", + "description": "Azure Identity SDK for Python authentication. Use for DefaultAzureCredential, managed identity, service principals, and token caching.\nTriggers: \"azure-identity\", \"DefaultAzureCredential\", \"authentication\", \"managed identity\", \"service principal\", \"credential\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-identity-rust", + "path": "skills\\azure-identity-rust", + "category": "uncategorized", + "name": "azure-identity-rust", + "description": "Azure Identity SDK for Rust authentication. Use for DeveloperToolsCredential, ManagedIdentityCredential, ClientSecretCredential, and token-based authentication.\nTriggers: \"azure-identity\", \"DeveloperToolsCredential\", \"authentication rust\", \"managed identity rust\", \"credential rust\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-identity-ts", - "path": "skills/azure-identity-ts", + "path": "skills\\azure-identity-ts", "category": "uncategorized", "name": "azure-identity-ts", "description": "Authenticate to Azure services using Azure Identity SDK for JavaScript (@azure/identity). Use when configuring authentication with DefaultAzureCredential, managed identity, service principals, or i...", "risk": "unknown", "source": "community" }, + { + "id": "azure-keyvault-certificates-rust", + "path": "skills\\azure-keyvault-certificates-rust", + "category": "uncategorized", + "name": "azure-keyvault-certificates-rust", + "description": "Azure Key Vault Certificates SDK for Rust. Use for creating, importing, and managing certificates.\nTriggers: \"keyvault certificates rust\", \"CertificateClient rust\", \"create certificate rust\", \"import certificate rust\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-keyvault-keys-rust", + "path": "skills\\azure-keyvault-keys-rust", + "category": "uncategorized", + "name": "azure-keyvault-keys-rust", + "description": "Azure Key Vault Keys SDK for Rust. Use for creating, managing, and using cryptographic keys.\nTriggers: \"keyvault keys rust\", \"KeyClient rust\", \"create key rust\", \"encrypt rust\", \"sign rust\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-keyvault-keys-ts", - "path": "skills/azure-keyvault-keys-ts", + "path": "skills\\azure-keyvault-keys-ts", "category": "uncategorized", "name": "azure-keyvault-keys-ts", "description": "Manage cryptographic keys using Azure Key Vault Keys SDK for JavaScript (@azure/keyvault-keys). Use when creating, encrypting/decrypting, signing, or rotating keys.", "risk": "unknown", "source": "community" }, + { + "id": "azure-keyvault-py", + "path": "skills\\azure-keyvault-py", + "category": "uncategorized", + "name": "azure-keyvault-py", + "description": "Azure Key Vault SDK for Python. Use for secrets, keys, and certificates management with secure storage.\nTriggers: \"key vault\", \"SecretClient\", \"KeyClient\", \"CertificateClient\", \"secrets\", \"encryption keys\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-keyvault-secrets-rust", + "path": "skills\\azure-keyvault-secrets-rust", + "category": "uncategorized", + "name": "azure-keyvault-secrets-rust", + "description": "Azure Key Vault Secrets SDK for Rust. Use for storing and retrieving secrets, passwords, and API keys.\nTriggers: \"keyvault secrets rust\", \"SecretClient rust\", \"get secret rust\", \"set secret rust\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-keyvault-secrets-ts", - "path": "skills/azure-keyvault-secrets-ts", + "path": "skills\\azure-keyvault-secrets-ts", "category": "uncategorized", "name": "azure-keyvault-secrets-ts", "description": "Manage secrets using Azure Key Vault Secrets SDK for JavaScript (@azure/keyvault-secrets). Use when storing and retrieving application secrets or configuration values.", "risk": "unknown", "source": "community" }, + { + "id": "azure-maps-search-dotnet", + "path": "skills\\azure-maps-search-dotnet", + "category": "uncategorized", + "name": "azure-maps-search-dotnet", + "description": "Azure Maps SDK for .NET. Location-based services including geocoding, routing, rendering, geolocation, and weather. Use for address search, directions, map tiles, IP geolocation, and weather data. Triggers: \"Azure Maps\", \"MapsSearchClient\", \"MapsRoutingClient\", \"MapsRenderingClient\", \"geocoding .NET\", \"route directions\", \"map tiles\", \"geolocation\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-messaging-webpubsub-java", - "path": "skills/azure-messaging-webpubsub-java", + "path": "skills\\azure-messaging-webpubsub-java", "category": "uncategorized", "name": "azure-messaging-webpubsub-java", "description": "Build real-time web applications with Azure Web PubSub SDK for Java. Use when implementing WebSocket-based messaging, live updates, chat applications, or server-to-client push notifications.", "risk": "unknown", "source": "community" }, + { + "id": "azure-messaging-webpubsubservice-py", + "path": "skills\\azure-messaging-webpubsubservice-py", + "category": "uncategorized", + "name": "azure-messaging-webpubsubservice-py", + "description": "Azure Web PubSub Service SDK for Python. Use for real-time messaging, WebSocket connections, and pub/sub patterns.\nTriggers: \"azure-messaging-webpubsubservice\", \"WebPubSubServiceClient\", \"real-time\", \"WebSocket\", \"pub/sub\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-mgmt-apicenter-dotnet", + "path": "skills\\azure-mgmt-apicenter-dotnet", + "category": "uncategorized", + "name": "azure-mgmt-apicenter-dotnet", + "description": "Azure API Center SDK for .NET. Centralized API inventory management with governance, versioning, and discovery. Use for creating API services, workspaces, APIs, versions, definitions, environments, deployments, and metadata schemas. Triggers: \"API Center\", \"ApiCenterService\", \"ApiCenterWorkspace\", \"ApiCenterApi\", \"API inventory\", \"API governance\", \"API versioning\", \"API catalog\", \"API discovery\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-mgmt-apicenter-py", + "path": "skills\\azure-mgmt-apicenter-py", + "category": "uncategorized", + "name": "azure-mgmt-apicenter-py", + "description": "Azure API Center Management SDK for Python. Use for managing API inventory, metadata, and governance across your organization.\nTriggers: \"azure-mgmt-apicenter\", \"ApiCenterMgmtClient\", \"API Center\", \"API inventory\", \"API governance\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-mgmt-apimanagement-dotnet", + "path": "skills\\azure-mgmt-apimanagement-dotnet", + "category": "uncategorized", + "name": "azure-mgmt-apimanagement-dotnet", + "description": "Azure Resource Manager SDK for API Management in .NET. Use for MANAGEMENT PLANE operations: creating/managing APIM services, APIs, products, subscriptions, policies, users, groups, gateways, and backends via Azure Resource Manager. Triggers: \"API Management\", \"APIM service\", \"create APIM\", \"manage APIs\", \"ApiManagementServiceResource\", \"API policies\", \"APIM products\", \"APIM subscriptions\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-mgmt-apimanagement-py", + "path": "skills\\azure-mgmt-apimanagement-py", + "category": "uncategorized", + "name": "azure-mgmt-apimanagement-py", + "description": "Azure API Management SDK for Python. Use for managing APIM services, APIs, products, subscriptions, and policies.\nTriggers: \"azure-mgmt-apimanagement\", \"ApiManagementClient\", \"APIM\", \"API gateway\", \"API Management\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-mgmt-applicationinsights-dotnet", + "path": "skills\\azure-mgmt-applicationinsights-dotnet", + "category": "uncategorized", + "name": "azure-mgmt-applicationinsights-dotnet", + "description": "Azure Application Insights SDK for .NET. Application performance monitoring and observability resource management. Use for creating Application Insights components, web tests, workbooks, analytics items, and API keys. Triggers: \"Application Insights\", \"ApplicationInsights\", \"App Insights\", \"APM\", \"application monitoring\", \"web tests\", \"availability tests\", \"workbooks\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-mgmt-arizeaiobservabilityeval-dotnet", + "path": "skills\\azure-mgmt-arizeaiobservabilityeval-dotnet", + "category": "uncategorized", + "name": "azure-mgmt-arizeaiobservabilityeval-dotnet", + "description": "Azure Resource Manager SDK for Arize AI Observability and Evaluation (.NET). Use when managing Arize AI organizations \non Azure via Azure Marketplace, creating/updating/deleting Arize resources, or integrating Arize ML observability \ninto .NET applications. Triggers: \"Arize AI\", \"ML observability\", \"ArizeAIObservabilityEval\", \"Arize organization\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-mgmt-botservice-dotnet", + "path": "skills\\azure-mgmt-botservice-dotnet", + "category": "uncategorized", + "name": "azure-mgmt-botservice-dotnet", + "description": "Azure Resource Manager SDK for Bot Service in .NET. Management plane operations for creating and managing Azure Bot resources, channels (Teams, DirectLine, Slack), and connection settings. Triggers: \"Bot Service\", \"BotResource\", \"Azure Bot\", \"DirectLine channel\", \"Teams channel\", \"bot management .NET\", \"create bot\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-mgmt-botservice-py", + "path": "skills\\azure-mgmt-botservice-py", + "category": "uncategorized", + "name": "azure-mgmt-botservice-py", + "description": "Azure Bot Service Management SDK for Python. Use for creating, managing, and configuring Azure Bot Service resources.\nTriggers: \"azure-mgmt-botservice\", \"AzureBotService\", \"bot management\", \"conversational AI\", \"bot channels\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-mgmt-fabric-dotnet", + "path": "skills\\azure-mgmt-fabric-dotnet", + "category": "uncategorized", + "name": "azure-mgmt-fabric-dotnet", + "description": "Azure Resource Manager SDK for Fabric in .NET. Use for MANAGEMENT PLANE operations: provisioning, scaling, suspending/resuming Microsoft Fabric capacities, checking name availability, and listing SKUs via Azure Resource Manager. Triggers: \"Fabric capacity\", \"create capacity\", \"suspend capacity\", \"resume capacity\", \"Fabric SKU\", \"provision Fabric\", \"ARM Fabric\", \"FabricCapacityResource\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-mgmt-fabric-py", + "path": "skills\\azure-mgmt-fabric-py", + "category": "uncategorized", + "name": "azure-mgmt-fabric-py", + "description": "Azure Fabric Management SDK for Python. Use for managing Microsoft Fabric capacities and resources.\nTriggers: \"azure-mgmt-fabric\", \"FabricMgmtClient\", \"Fabric capacity\", \"Microsoft Fabric\", \"Power BI capacity\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-mgmt-mongodbatlas-dotnet", - "path": "skills/azure-mgmt-mongodbatlas-dotnet", + "path": "skills\\azure-mgmt-mongodbatlas-dotnet", "category": "uncategorized", "name": "azure-mgmt-mongodbatlas-dotnet", "description": "Manage MongoDB Atlas Organizations as Azure ARM resources using Azure.ResourceManager.MongoDBAtlas SDK. Use when creating, updating, listing, or deleting MongoDB Atlas organizations through Azure M...", "risk": "unknown", "source": "community" }, + { + "id": "azure-mgmt-weightsandbiases-dotnet", + "path": "skills\\azure-mgmt-weightsandbiases-dotnet", + "category": "uncategorized", + "name": "azure-mgmt-weightsandbiases-dotnet", + "description": "Azure Weights & Biases SDK for .NET. ML experiment tracking and model management via Azure Marketplace. Use for creating W&B instances, managing SSO, marketplace integration, and ML observability. Triggers: \"Weights and Biases\", \"W&B\", \"WeightsAndBiases\", \"ML experiment tracking\", \"model registry\", \"experiment management\", \"wandb\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-microsoft-playwright-testing-ts", - "path": "skills/azure-microsoft-playwright-testing-ts", + "path": "skills\\azure-microsoft-playwright-testing-ts", "category": "uncategorized", "name": "azure-microsoft-playwright-testing-ts", "description": "Run Playwright tests at scale using Azure Playwright Workspaces (formerly Microsoft Playwright Testing). Use when scaling browser tests across cloud-hosted browsers, integrating with CI/CD pipeline...", "risk": "unknown", "source": "community" }, + { + "id": "azure-monitor-ingestion-java", + "path": "skills\\azure-monitor-ingestion-java", + "category": "uncategorized", + "name": "azure-monitor-ingestion-java", + "description": "Azure Monitor Ingestion SDK for Java. Send custom logs to Azure Monitor via Data Collection Rules (DCR) and Data Collection Endpoints (DCE).\nTriggers: \"LogsIngestionClient java\", \"azure monitor ingestion java\", \"custom logs java\", \"DCR java\", \"data collection rule java\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-monitor-ingestion-py", + "path": "skills\\azure-monitor-ingestion-py", + "category": "uncategorized", + "name": "azure-monitor-ingestion-py", + "description": "Azure Monitor Ingestion SDK for Python. Use for sending custom logs to Log Analytics workspace via Logs Ingestion API.\nTriggers: \"azure-monitor-ingestion\", \"LogsIngestionClient\", \"custom logs\", \"DCR\", \"data collection rule\", \"Log Analytics\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-monitor-opentelemetry-exporter-java", + "path": "skills\\azure-monitor-opentelemetry-exporter-java", + "category": "uncategorized", + "name": "azure-monitor-opentelemetry-exporter-java", + "description": "Azure Monitor OpenTelemetry Exporter for Java. Export OpenTelemetry traces, metrics, and logs to Azure Monitor/Application Insights.\nTriggers: \"AzureMonitorExporter java\", \"opentelemetry azure java\", \"application insights java otel\", \"azure monitor tracing java\".\nNote: This package is DEPRECATED. Migrate to azure-monitor-opentelemetry-autoconfigure.\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-monitor-opentelemetry-exporter-py", + "path": "skills\\azure-monitor-opentelemetry-exporter-py", + "category": "uncategorized", + "name": "azure-monitor-opentelemetry-exporter-py", + "description": "Azure Monitor OpenTelemetry Exporter for Python. Use for low-level OpenTelemetry export to Application Insights.\nTriggers: \"azure-monitor-opentelemetry-exporter\", \"AzureMonitorTraceExporter\", \"AzureMonitorMetricExporter\", \"AzureMonitorLogExporter\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-monitor-opentelemetry-py", + "path": "skills\\azure-monitor-opentelemetry-py", + "category": "uncategorized", + "name": "azure-monitor-opentelemetry-py", + "description": "Azure Monitor OpenTelemetry Distro for Python. Use for one-line Application Insights setup with auto-instrumentation.\nTriggers: \"azure-monitor-opentelemetry\", \"configure_azure_monitor\", \"Application Insights\", \"OpenTelemetry distro\", \"auto-instrumentation\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-monitor-opentelemetry-ts", - "path": "skills/azure-monitor-opentelemetry-ts", + "path": "skills\\azure-monitor-opentelemetry-ts", "category": "uncategorized", "name": "azure-monitor-opentelemetry-ts", "description": "Instrument applications with Azure Monitor and OpenTelemetry for JavaScript (@azure/monitor-opentelemetry). Use when adding distributed tracing, metrics, and logs to Node.js applications with Appli...", "risk": "unknown", "source": "community" }, + { + "id": "azure-monitor-query-java", + "path": "skills\\azure-monitor-query-java", + "category": "uncategorized", + "name": "azure-monitor-query-java", + "description": "Azure Monitor Query SDK for Java. Execute Kusto queries against Log Analytics workspaces and query metrics from Azure resources.\nTriggers: \"LogsQueryClient java\", \"MetricsQueryClient java\", \"kusto query java\", \"log analytics java\", \"azure monitor query java\".\nNote: This package is deprecated. Migrate to azure-monitor-query-logs and azure-monitor-query-metrics.\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-monitor-query-py", + "path": "skills\\azure-monitor-query-py", + "category": "uncategorized", + "name": "azure-monitor-query-py", + "description": "Azure Monitor Query SDK for Python. Use for querying Log Analytics workspaces and Azure Monitor metrics.\nTriggers: \"azure-monitor-query\", \"LogsQueryClient\", \"MetricsQueryClient\", \"Log Analytics\", \"Kusto queries\", \"Azure metrics\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-postgres-ts", + "path": "skills\\azure-postgres-ts", + "category": "uncategorized", + "name": "azure-postgres-ts", + "description": "Connect to Azure Database for PostgreSQL Flexible Server from Node.js/TypeScript using the pg (node-postgres) package. Use for PostgreSQL queries, connection pooling, transactions, and Microsoft Entra ID (passwordless) authentication. Triggers: \"PostgreSQL\", \"postgres\", \"pg client\", \"node-postgres\", \"Azure PostgreSQL connection\", \"PostgreSQL TypeScript\", \"pg Pool\", \"passwordless postgres\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-resource-manager-cosmosdb-dotnet", + "path": "skills\\azure-resource-manager-cosmosdb-dotnet", + "category": "uncategorized", + "name": "azure-resource-manager-cosmosdb-dotnet", + "description": "Azure Resource Manager SDK for Cosmos DB in .NET. Use for MANAGEMENT PLANE operations: creating/managing Cosmos DB accounts, databases, containers, throughput settings, and RBAC via Azure Resource Manager. NOT for data plane operations (CRUD on documents) - use Microsoft.Azure.Cosmos for that. Triggers: \"Cosmos DB account\", \"create Cosmos account\", \"manage Cosmos resources\", \"ARM Cosmos\", \"CosmosDBAccountResource\", \"provision Cosmos DB\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-resource-manager-durabletask-dotnet", + "path": "skills\\azure-resource-manager-durabletask-dotnet", + "category": "uncategorized", + "name": "azure-resource-manager-durabletask-dotnet", + "description": "Azure Resource Manager SDK for Durable Task Scheduler in .NET. Use for MANAGEMENT PLANE operations: creating/managing Durable Task Schedulers, Task Hubs, and retention policies via Azure Resource Manager. Triggers: \"Durable Task Scheduler\", \"create scheduler\", \"task hub\", \"DurableTaskSchedulerResource\", \"provision Durable Task\", \"orchestration scheduler\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-resource-manager-mysql-dotnet", + "path": "skills\\azure-resource-manager-mysql-dotnet", + "category": "uncategorized", + "name": "azure-resource-manager-mysql-dotnet", + "description": "Azure MySQL Flexible Server SDK for .NET. Database management for MySQL Flexible Server deployments. Use for creating servers, databases, firewall rules, configurations, backups, and high availability. Triggers: \"MySQL\", \"MySqlFlexibleServer\", \"MySQL Flexible Server\", \"Azure Database for MySQL\", \"MySQL database management\", \"MySQL firewall\", \"MySQL backup\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-resource-manager-playwright-dotnet", + "path": "skills\\azure-resource-manager-playwright-dotnet", + "category": "uncategorized", + "name": "azure-resource-manager-playwright-dotnet", + "description": "Azure Resource Manager SDK for Microsoft Playwright Testing in .NET. Use for MANAGEMENT PLANE operations: creating/managing Playwright Testing workspaces, checking name availability, and managing workspace quotas via Azure Resource Manager. NOT for running Playwright tests - use Azure.Developer.MicrosoftPlaywrightTesting.NUnit for that. Triggers: \"Playwright workspace\", \"create Playwright Testing workspace\", \"manage Playwright resources\", \"ARM Playwright\", \"PlaywrightWorkspaceResource\", \"provision Playwright Testing\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-resource-manager-postgresql-dotnet", + "path": "skills\\azure-resource-manager-postgresql-dotnet", + "category": "uncategorized", + "name": "azure-resource-manager-postgresql-dotnet", + "description": "Azure PostgreSQL Flexible Server SDK for .NET. Database management for PostgreSQL Flexible Server deployments. Use for creating servers, databases, firewall rules, configurations, backups, and high availability. Triggers: \"PostgreSQL\", \"PostgreSqlFlexibleServer\", \"PostgreSQL Flexible Server\", \"Azure Database for PostgreSQL\", \"PostgreSQL database management\", \"PostgreSQL firewall\", \"PostgreSQL backup\", \"Postgres\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-resource-manager-redis-dotnet", + "path": "skills\\azure-resource-manager-redis-dotnet", + "category": "uncategorized", + "name": "azure-resource-manager-redis-dotnet", + "description": "Azure Resource Manager SDK for Redis in .NET. Use for MANAGEMENT PLANE operations: creating/managing Azure Cache for Redis instances, firewall rules, access keys, patch schedules, linked servers (geo-replication), and private endpoints via Azure Resource Manager. NOT for data plane operations (get/set keys, pub/sub) - use StackExchange.Redis for that. Triggers: \"Redis cache\", \"create Redis\", \"manage Redis\", \"ARM Redis\", \"RedisResource\", \"provision Redis\", \"Azure Cache for Redis\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-resource-manager-sql-dotnet", + "path": "skills\\azure-resource-manager-sql-dotnet", + "category": "uncategorized", + "name": "azure-resource-manager-sql-dotnet", + "description": "Azure Resource Manager SDK for Azure SQL in .NET. Use for MANAGEMENT PLANE operations: creating/managing SQL servers, databases, elastic pools, firewall rules, and failover groups via Azure Resource Manager. NOT for data plane operations (executing queries) - use Microsoft.Data.SqlClient for that. Triggers: \"SQL server\", \"create SQL database\", \"manage SQL resources\", \"ARM SQL\", \"SqlServerResource\", \"provision Azure SQL\", \"elastic pool\", \"firewall rule\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-search-documents-dotnet", + "path": "skills\\azure-search-documents-dotnet", + "category": "uncategorized", + "name": "azure-search-documents-dotnet", + "description": "Azure AI Search SDK for .NET (Azure.Search.Documents). Use for building search applications with full-text, vector, semantic, and hybrid search. Covers SearchClient (queries, document CRUD), SearchIndexClient (index management), and SearchIndexerClient (indexers, skillsets). Triggers: \"Azure Search .NET\", \"SearchClient\", \"SearchIndexClient\", \"vector search C#\", \"semantic search .NET\", \"hybrid search\", \"Azure.Search.Documents\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-search-documents-py", + "path": "skills\\azure-search-documents-py", + "category": "uncategorized", + "name": "azure-search-documents-py", + "description": "Azure AI Search SDK for Python. Use for vector search, hybrid search, semantic ranking, indexing, and skillsets.\nTriggers: \"azure-search-documents\", \"SearchClient\", \"SearchIndexClient\", \"vector search\", \"hybrid search\", \"semantic search\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-search-documents-ts", - "path": "skills/azure-search-documents-ts", + "path": "skills\\azure-search-documents-ts", "category": "uncategorized", "name": "azure-search-documents-ts", "description": "Build search applications using Azure AI Search SDK for JavaScript (@azure/search-documents). Use when creating/managing indexes, implementing vector/hybrid search, semantic ranking, or building ag...", "risk": "unknown", "source": "community" }, + { + "id": "azure-security-keyvault-keys-dotnet", + "path": "skills\\azure-security-keyvault-keys-dotnet", + "category": "uncategorized", + "name": "azure-security-keyvault-keys-dotnet", + "description": "Azure Key Vault Keys SDK for .NET. Client library for managing cryptographic keys in Azure Key Vault and Managed HSM. Use for key creation, rotation, encryption, decryption, signing, and verification. Triggers: \"Key Vault keys\", \"KeyClient\", \"CryptographyClient\", \"RSA key\", \"EC key\", \"encrypt decrypt .NET\", \"key rotation\", \"HSM\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-security-keyvault-keys-java", - "path": "skills/azure-security-keyvault-keys-java", + "path": "skills\\azure-security-keyvault-keys-java", "category": "uncategorized", "name": "azure-security-keyvault-keys-java", "description": "Azure Key Vault Keys Java SDK for cryptographic key management. Use when creating, managing, or using RSA/EC keys, performing encrypt/decrypt/sign/verify operations, or working with HSM-backed keys.", @@ -1684,34 +1621,133 @@ }, { "id": "azure-security-keyvault-secrets-java", - "path": "skills/azure-security-keyvault-secrets-java", + "path": "skills\\azure-security-keyvault-secrets-java", "category": "uncategorized", "name": "azure-security-keyvault-secrets-java", "description": "Azure Key Vault Secrets Java SDK for secret management. Use when storing, retrieving, or managing passwords, API keys, connection strings, or other sensitive configuration data.", "risk": "unknown", "source": "community" }, + { + "id": "azure-servicebus-dotnet", + "path": "skills\\azure-servicebus-dotnet", + "category": "uncategorized", + "name": "azure-servicebus-dotnet", + "description": "Azure Service Bus SDK for .NET. Enterprise messaging with queues, topics, subscriptions, and sessions. Use for reliable message delivery, pub/sub patterns, dead letter handling, and background processing. Triggers: \"Service Bus\", \"ServiceBusClient\", \"ServiceBusSender\", \"ServiceBusReceiver\", \"ServiceBusProcessor\", \"message queue\", \"pub/sub .NET\", \"dead letter queue\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-servicebus-py", + "path": "skills\\azure-servicebus-py", + "category": "uncategorized", + "name": "azure-servicebus-py", + "description": "Azure Service Bus SDK for Python messaging. Use for queues, topics, subscriptions, and enterprise messaging patterns.\nTriggers: \"service bus\", \"ServiceBusClient\", \"queue\", \"topic\", \"subscription\", \"message broker\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-servicebus-ts", - "path": "skills/azure-servicebus-ts", + "path": "skills\\azure-servicebus-ts", "category": "uncategorized", "name": "azure-servicebus-ts", "description": "Build messaging applications using Azure Service Bus SDK for JavaScript (@azure/service-bus). Use when implementing queues, topics/subscriptions, message sessions, dead-letter handling, or enterpri...", "risk": "unknown", "source": "community" }, + { + "id": "azure-speech-to-text-rest-py", + "path": "skills\\azure-speech-to-text-rest-py", + "category": "uncategorized", + "name": "azure-speech-to-text-rest-py", + "description": "Azure Speech to Text REST API for short audio (Python). Use for simple speech recognition of audio files up to 60 seconds without the Speech SDK.\nTriggers: \"speech to text REST\", \"short audio transcription\", \"speech recognition REST API\", \"STT REST\", \"recognize speech REST\".\nDO NOT USE FOR: Long audio (>60 seconds), real-time streaming, batch transcription, custom speech models, speech translation. Use Speech SDK or Batch Transcription API instead.\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-storage-blob-java", - "path": "skills/azure-storage-blob-java", + "path": "skills\\azure-storage-blob-java", "category": "uncategorized", "name": "azure-storage-blob-java", "description": "Build blob storage applications with Azure Storage Blob SDK for Java. Use when uploading, downloading, or managing files in Azure Blob Storage, working with containers, or implementing streaming da...", "risk": "unknown", "source": "community" }, + { + "id": "azure-storage-blob-py", + "path": "skills\\azure-storage-blob-py", + "category": "uncategorized", + "name": "azure-storage-blob-py", + "description": "Azure Blob Storage SDK for Python. Use for uploading, downloading, listing blobs, managing containers, and blob lifecycle.\nTriggers: \"blob storage\", \"BlobServiceClient\", \"ContainerClient\", \"BlobClient\", \"upload blob\", \"download blob\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-storage-blob-rust", + "path": "skills\\azure-storage-blob-rust", + "category": "uncategorized", + "name": "azure-storage-blob-rust", + "description": "Azure Blob Storage SDK for Rust. Use for uploading, downloading, and managing blobs and containers.\nTriggers: \"blob storage rust\", \"BlobClient rust\", \"upload blob rust\", \"download blob rust\", \"container rust\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-storage-blob-ts", + "path": "skills\\azure-storage-blob-ts", + "category": "uncategorized", + "name": "azure-storage-blob-ts", + "description": "Azure Blob Storage JavaScript/TypeScript SDK (@azure/storage-blob) for blob operations. Use for uploading, downloading, listing, and managing blobs and containers. Supports block blobs, append blobs, page blobs, SAS tokens, and streaming. Triggers: \"blob storage\", \"@azure/storage-blob\", \"BlobServiceClient\", \"ContainerClient\", \"upload blob\", \"download blob\", \"SAS token\", \"block blob\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-storage-file-datalake-py", + "path": "skills\\azure-storage-file-datalake-py", + "category": "uncategorized", + "name": "azure-storage-file-datalake-py", + "description": "Azure Data Lake Storage Gen2 SDK for Python. Use for hierarchical file systems, big data analytics, and file/directory operations.\nTriggers: \"data lake\", \"DataLakeServiceClient\", \"FileSystemClient\", \"ADLS Gen2\", \"hierarchical namespace\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-storage-file-share-py", + "path": "skills\\azure-storage-file-share-py", + "category": "uncategorized", + "name": "azure-storage-file-share-py", + "description": "Azure Storage File Share SDK for Python. Use for SMB file shares, directories, and file operations in the cloud.\nTriggers: \"azure-storage-file-share\", \"ShareServiceClient\", \"ShareClient\", \"file share\", \"SMB\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-storage-file-share-ts", + "path": "skills\\azure-storage-file-share-ts", + "category": "uncategorized", + "name": "azure-storage-file-share-ts", + "description": "Azure File Share JavaScript/TypeScript SDK (@azure/storage-file-share) for SMB file share operations. Use for creating shares, managing directories, uploading/downloading files, and handling file metadata. Supports Azure Files SMB protocol scenarios. Triggers: \"file share\", \"@azure/storage-file-share\", \"ShareServiceClient\", \"ShareClient\", \"SMB\", \"Azure Files\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-storage-queue-py", + "path": "skills\\azure-storage-queue-py", + "category": "uncategorized", + "name": "azure-storage-queue-py", + "description": "Azure Queue Storage SDK for Python. Use for reliable message queuing, task distribution, and asynchronous processing.\nTriggers: \"queue storage\", \"QueueServiceClient\", \"QueueClient\", \"message queue\", \"dequeue\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-storage-queue-ts", + "path": "skills\\azure-storage-queue-ts", + "category": "uncategorized", + "name": "azure-storage-queue-ts", + "description": "Azure Queue Storage JavaScript/TypeScript SDK (@azure/storage-queue) for message queue operations. Use for sending, receiving, peeking, and deleting messages in queues. Supports visibility timeout, message encoding, and batch operations. Triggers: \"queue storage\", \"@azure/storage-queue\", \"QueueServiceClient\", \"QueueClient\", \"send message\", \"receive message\", \"dequeue\", \"visibility timeout\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-web-pubsub-ts", - "path": "skills/azure-web-pubsub-ts", + "path": "skills\\azure-web-pubsub-ts", "category": "uncategorized", "name": "azure-web-pubsub-ts", "description": "Build real-time messaging applications using Azure Web PubSub SDKs for JavaScript (@azure/web-pubsub, @azure/web-pubsub-client). Use when implementing WebSocket-based real-time features, pub/sub me...", @@ -1720,25 +1756,16 @@ }, { "id": "backend-architect", - "path": "skills/backend-architect", + "path": "skills\\backend-architect", "category": "uncategorized", - "name": "Backend Architect", - "description": "You are a backend system architect specializing in scalable, resilient, and maintainable backend systems and APIs.", + "name": "backend-architect", + "description": "Expert backend architect specializing in scalable API design,\nmicroservices architecture, and distributed systems. Masters REST/GraphQL/gRPC\nAPIs, event-driven architectures, service mesh patterns, and modern backend\nframeworks. Handles service boundary definition, inter-service communication,\nresilience patterns, and observability. Use PROACTIVELY when creating new\nbackend services or APIs.\n", "risk": "unknown", - "source": "unknown" - }, - { - "id": "backend-security-coder", - "path": "skills/backend-security-coder", - "category": "uncategorized", - "name": "Backend Security Coder", - "description": "- Working on backend security coder tasks or workflows - Needing guidance, best practices, or checklists for backend security coder", - "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "backend-dev-guidelines", - "path": "skills/backend-dev-guidelines", + "path": "skills\\backend-dev-guidelines", "category": "uncategorized", "name": "backend-dev-guidelines", "description": "Opinionated backend development standards for Node.js + Express + TypeScript microservices. Covers layered architecture, BaseController pattern, dependency injection, Prisma repositories, Zod valid...", @@ -1747,16 +1774,25 @@ }, { "id": "backend-development-feature-development", - "path": "skills/backend-development-feature-development", + "path": "skills\\backend-development-feature-development", "category": "uncategorized", "name": "backend-development-feature-development", "description": "Orchestrate end-to-end backend feature development from requirements to deployment. Use when coordinating multi-phase feature delivery across teams and services.", "risk": "unknown", "source": "community" }, + { + "id": "backend-security-coder", + "path": "skills\\backend-security-coder", + "category": "uncategorized", + "name": "backend-security-coder", + "description": "Expert in secure backend coding practices specializing in input\nvalidation, authentication, and API security. Use PROACTIVELY for backend\nsecurity implementations or security code reviews.\n", + "risk": "unknown", + "source": "community" + }, { "id": "backtesting-frameworks", - "path": "skills/backtesting-frameworks", + "path": "skills\\backtesting-frameworks", "category": "uncategorized", "name": "backtesting-frameworks", "description": "Build robust backtesting systems for trading strategies with proper handling of look-ahead bias, survivorship bias, and transaction costs. Use when developing trading algorithms, validating strateg...", @@ -1765,7 +1801,7 @@ }, { "id": "bamboohr-automation", - "path": "skills/bamboohr-automation", + "path": "skills\\bamboohr-automation", "category": "uncategorized", "name": "bamboohr-automation", "description": "Automate BambooHR tasks via Rube MCP (Composio): employees, time-off, benefits, dependents, employee updates. Always search tools first for current schemas.", @@ -1774,7 +1810,7 @@ }, { "id": "base", - "path": "skills/libreoffice/base", + "path": "skills\\libreoffice\\base", "category": "libreoffice", "name": "base", "description": "Database management, forms, reports, and data operations with LibreOffice Base.", @@ -1783,25 +1819,16 @@ }, { "id": "basecamp-automation", - "path": "skills/basecamp-automation", + "path": "skills\\basecamp-automation", "category": "uncategorized", "name": "basecamp-automation", "description": "Automate Basecamp project management, to-dos, messages, people, and to-do list organization via Rube MCP (Composio). Always search tools first for current schemas.", "risk": "unknown", "source": "community" }, - { - "id": "bash-pro", - "path": "skills/bash-pro", - "category": "uncategorized", - "name": "Bash Pro", - "description": "- Writing or reviewing Bash scripts for automation, CI/CD, or ops - Hardening shell scripts for safety and portability", - "risk": "unknown", - "source": "unknown" - }, { "id": "bash-defensive-patterns", - "path": "skills/bash-defensive-patterns", + "path": "skills\\bash-defensive-patterns", "category": "uncategorized", "name": "bash-defensive-patterns", "description": "Master defensive Bash programming techniques for production-grade scripts. Use when writing robust shell scripts, CI/CD pipelines, or system utilities requiring fault tolerance and safety.", @@ -1810,16 +1837,25 @@ }, { "id": "bash-linux", - "path": "skills/bash-linux", + "path": "skills\\bash-linux", "category": "uncategorized", "name": "bash-linux", "description": "Bash/Linux terminal patterns. Critical commands, piping, error handling, scripting. Use when working on macOS or Linux systems.", "risk": "unknown", "source": "community" }, + { + "id": "bash-pro", + "path": "skills\\bash-pro", + "category": "uncategorized", + "name": "bash-pro", + "description": "Master of defensive Bash scripting for production automation, CI/CD\npipelines, and system utilities. Expert in safe, portable, and testable shell\nscripts.\n", + "risk": "unknown", + "source": "community" + }, { "id": "bash-scripting", - "path": "skills/bash-scripting", + "path": "skills\\bash-scripting", "category": "uncategorized", "name": "bash-scripting", "description": "Bash scripting workflow for creating production-ready shell scripts with defensive patterns, error handling, and testing.", @@ -1828,7 +1864,7 @@ }, { "id": "bats-testing-patterns", - "path": "skills/bats-testing-patterns", + "path": "skills\\bats-testing-patterns", "category": "uncategorized", "name": "bats-testing-patterns", "description": "Master Bash Automated Testing System (Bats) for comprehensive shell script testing. Use when writing tests for shell scripts, CI/CD pipelines, or requiring test-driven development of shell utilities.", @@ -1837,7 +1873,7 @@ }, { "id": "bazel-build-optimization", - "path": "skills/bazel-build-optimization", + "path": "skills\\bazel-build-optimization", "category": "uncategorized", "name": "bazel-build-optimization", "description": "Optimize Bazel builds for large-scale monorepos. Use when configuring Bazel, implementing remote execution, or optimizing build performance for enterprise codebases.", @@ -1846,7 +1882,7 @@ }, { "id": "beautiful-prose", - "path": "skills/beautiful-prose", + "path": "skills\\beautiful-prose", "category": "uncategorized", "name": "beautiful-prose", "description": "Hard-edged writing style contract for timeless, forceful English prose without AI tics", @@ -1855,7 +1891,7 @@ }, { "id": "behavioral-modes", - "path": "skills/behavioral-modes", + "path": "skills\\behavioral-modes", "category": "uncategorized", "name": "behavioral-modes", "description": "AI operational modes (brainstorm, implement, debug, review, teach, ship, orchestrate). Use to adapt behavior based on task type.", @@ -1864,7 +1900,7 @@ }, { "id": "bevy-ecs-expert", - "path": "skills/bevy-ecs-expert", + "path": "skills\\bevy-ecs-expert", "category": "uncategorized", "name": "bevy-ecs-expert", "description": "Master Bevy's Entity Component System (ECS) in Rust, covering Systems, Queries, Resources, and parallel scheduling.", @@ -1873,7 +1909,7 @@ }, { "id": "billing-automation", - "path": "skills/billing-automation", + "path": "skills\\billing-automation", "category": "uncategorized", "name": "billing-automation", "description": "Build automated billing systems for recurring payments, invoicing, subscription lifecycle, and dunning management. Use when implementing subscription billing, automating invoicing, or managing recu...", @@ -1882,7 +1918,7 @@ }, { "id": "binary-analysis-patterns", - "path": "skills/binary-analysis-patterns", + "path": "skills\\binary-analysis-patterns", "category": "uncategorized", "name": "binary-analysis-patterns", "description": "Master binary analysis patterns including disassembly, decompilation, control flow analysis, and code pattern recognition. Use when analyzing executables, understanding compiled code, or performing...", @@ -1891,7 +1927,7 @@ }, { "id": "bitbucket-automation", - "path": "skills/bitbucket-automation", + "path": "skills\\bitbucket-automation", "category": "uncategorized", "name": "bitbucket-automation", "description": "Automate Bitbucket repositories, pull requests, branches, issues, and workspace management via Rube MCP (Composio). Always search tools first for current schemas.", @@ -1900,16 +1936,16 @@ }, { "id": "blockchain-developer", - "path": "skills/blockchain-developer", + "path": "skills\\blockchain-developer", "category": "uncategorized", - "name": "Blockchain Developer", - "description": "- Working on blockchain developer tasks or workflows - Needing guidance, best practices, or checklists for blockchain developer", + "name": "blockchain-developer", + "description": "Build production-ready Web3 applications, smart contracts, and\ndecentralized systems. Implements DeFi protocols, NFT platforms, DAOs, and\nenterprise blockchain integrations. Use PROACTIVELY for smart contracts, Web3\napps, DeFi protocols, or blockchain infrastructure.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "blockrun", - "path": "skills/blockrun", + "path": "skills\\blockrun", "category": "uncategorized", "name": "blockrun", "description": "Use when user needs capabilities Claude lacks (image generation, real-time X/Twitter data) or explicitly requests external models (\\\"blockrun\\\", \\\"use grok\\\", \\\"use gpt\\\", \\\"da...", @@ -1918,7 +1954,7 @@ }, { "id": "box-automation", - "path": "skills/box-automation", + "path": "skills\\box-automation", "category": "uncategorized", "name": "box-automation", "description": "Automate Box cloud storage operations including file upload/download, search, folder management, sharing, collaborations, and metadata queries via Rube MCP (Composio). Always search tools first for...", @@ -1927,7 +1963,7 @@ }, { "id": "brainstorming", - "path": "skills/brainstorming", + "path": "skills\\brainstorming", "category": "uncategorized", "name": "brainstorming", "description": "Use before creative or constructive work (features, architecture, behavior). Transforms vague ideas into validated designs through disciplined reasoning and collaboration.", @@ -1936,7 +1972,7 @@ }, { "id": "brand-guidelines-anthropic", - "path": "skills/brand-guidelines-anthropic", + "path": "skills\\brand-guidelines-anthropic", "category": "uncategorized", "name": "brand-guidelines-anthropic", "description": "Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatt...", @@ -1945,7 +1981,7 @@ }, { "id": "brand-guidelines-community", - "path": "skills/brand-guidelines-community", + "path": "skills\\brand-guidelines-community", "category": "uncategorized", "name": "brand-guidelines-community", "description": "Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatt...", @@ -1954,7 +1990,7 @@ }, { "id": "brevo-automation", - "path": "skills/brevo-automation", + "path": "skills\\brevo-automation", "category": "uncategorized", "name": "brevo-automation", "description": "Automate Brevo (Sendinblue) tasks via Rube MCP (Composio): manage email campaigns, create/edit templates, track senders, and monitor campaign performance. Always search tools first for current sche...", @@ -1963,7 +1999,7 @@ }, { "id": "broken-authentication", - "path": "skills/broken-authentication", + "path": "skills\\broken-authentication", "category": "uncategorized", "name": "broken-authentication", "description": "This skill should be used when the user asks to \"test for broken authentication vulnerabilities\", \"assess session management security\", \"perform credential stuffing tests\", \"evaluate ...", @@ -1972,7 +2008,7 @@ }, { "id": "browser-automation", - "path": "skills/browser-automation", + "path": "skills\\browser-automation", "category": "uncategorized", "name": "browser-automation", "description": "Browser automation powers web testing, scraping, and AI agent interactions. The difference between a flaky script and a reliable system comes down to understanding selectors, waiting strategies, an...", @@ -1981,7 +2017,7 @@ }, { "id": "browser-extension-builder", - "path": "skills/browser-extension-builder", + "path": "skills\\browser-extension-builder", "category": "uncategorized", "name": "browser-extension-builder", "description": "Expert in building browser extensions that solve real problems - Chrome, Firefox, and cross-browser extensions. Covers extension architecture, manifest v3, content scripts, popup UIs, monetization ...", @@ -1990,7 +2026,7 @@ }, { "id": "bullmq-specialist", - "path": "skills/bullmq-specialist", + "path": "skills\\bullmq-specialist", "category": "uncategorized", "name": "bullmq-specialist", "description": "BullMQ expert for Redis-backed job queues, background processing, and reliable async execution in Node.js/TypeScript applications. Use when: bullmq, bull queue, redis queue, background job, job queue.", @@ -1999,7 +2035,7 @@ }, { "id": "bun-development", - "path": "skills/bun-development", + "path": "skills\\bun-development", "category": "uncategorized", "name": "bun-development", "description": "Modern JavaScript/TypeScript development with Bun runtime. Covers package management, bundling, testing, and migration from Node.js. Use when working with Bun, optimizing JS/TS development speed, o...", @@ -2008,7 +2044,7 @@ }, { "id": "burp-suite-testing", - "path": "skills/burp-suite-testing", + "path": "skills\\burp-suite-testing", "category": "uncategorized", "name": "burp-suite-testing", "description": "This skill should be used when the user asks to \"intercept HTTP traffic\", \"modify web requests\", \"use Burp Suite for testing\", \"perform web vulnerability scanning\", \"test with Burp ...", @@ -2017,16 +2053,16 @@ }, { "id": "business-analyst", - "path": "skills/business-analyst", + "path": "skills\\business-analyst", "category": "uncategorized", - "name": "Business Analyst", - "description": "- Working on business analyst tasks or workflows - Needing guidance, best practices, or checklists for business analyst", + "name": "business-analyst", + "description": "Master modern business analysis with AI-powered analytics,\nreal-time dashboards, and data-driven insights. Build comprehensive KPI\nframeworks, predictive models, and strategic recommendations. Use PROACTIVELY\nfor business intelligence or strategic analysis.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "busybox-on-windows", - "path": "skills/busybox-on-windows", + "path": "skills\\busybox-on-windows", "category": "uncategorized", "name": "busybox-on-windows", "description": "How to use a Win32 build of BusyBox to run many of the standard UNIX command line tools on Windows.", @@ -2035,61 +2071,61 @@ }, { "id": "c-pro", - "path": "skills/c-pro", + "path": "skills\\c-pro", "category": "uncategorized", "name": "c-pro", "description": "Write efficient C code with proper memory management, pointer arithmetic, and system calls. Handles embedded systems, kernel modules, and performance-critical code. Use PROACTIVELY for C optimization, memory issues, or system programming.", "risk": "unknown", "source": "community" }, - { - "id": "c4-code", - "path": "skills/c4-code", - "category": "uncategorized", - "name": "C4 Code", - "description": "- Working on c4 code level: [directory name] tasks or workflows - Needing guidance, best practices, or checklists for c4 code level: [directory name]", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "c4-component", - "path": "skills/c4-component", - "category": "uncategorized", - "name": "C4 Component", - "description": "- Working on c4 component level: [component name] tasks or workflows - Needing guidance, best practices, or checklists for c4 component level: [component name]", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "c4-container", - "path": "skills/c4-container", - "category": "uncategorized", - "name": "C4 Container", - "description": "- Working on c4 container level: system deployment tasks or workflows - Needing guidance, best practices, or checklists for c4 container level: system deployment", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "c4-context", - "path": "skills/c4-context", - "category": "uncategorized", - "name": "C4 Context", - "description": "- Working on c4 context level: system context tasks or workflows - Needing guidance, best practices, or checklists for c4 context level: system context", - "risk": "unknown", - "source": "unknown" - }, { "id": "c4-architecture-c4-architecture", - "path": "skills/c4-architecture-c4-architecture", + "path": "skills\\c4-architecture-c4-architecture", "category": "uncategorized", "name": "c4-architecture-c4-architecture", "description": "Generate comprehensive C4 architecture documentation for an existing repository/codebase using a bottom-up analysis approach.", "risk": "unknown", "source": "community" }, + { + "id": "c4-code", + "path": "skills\\c4-code", + "category": "uncategorized", + "name": "c4-code", + "description": "Expert C4 Code-level documentation specialist. Analyzes code\ndirectories to create comprehensive C4 code-level documentation including\nfunction signatures, arguments, dependencies, and code structure. Use when\ndocumenting code at the lowest C4 level for individual directories and code\nmodules.\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "c4-component", + "path": "skills\\c4-component", + "category": "uncategorized", + "name": "c4-component", + "description": "Expert C4 Component-level documentation specialist. Synthesizes C4\nCode-level documentation into Component-level architecture, defining component\nboundaries, interfaces, and relationships. Creates component diagrams and\ndocumentation. Use when synthesizing code-level documentation into logical\ncomponents.\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "c4-container", + "path": "skills\\c4-container", + "category": "uncategorized", + "name": "c4-container", + "description": "Expert C4 Container-level documentation specialist. Synthesizes\nComponent-level documentation into Container-level architecture, mapping\ncomponents to deployment units, documenting container interfaces as APIs, and\ncreating container diagrams. Use when synthesizing components into deployment\ncontainers and documenting system deployment architecture.\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "c4-context", + "path": "skills\\c4-context", + "category": "uncategorized", + "name": "c4-context", + "description": "Expert C4 Context-level documentation specialist. Creates\nhigh-level system context diagrams, documents personas, user journeys, system\nfeatures, and external dependencies. Synthesizes container and component\ndocumentation with system documentation to create comprehensive context-level\narchitecture. Use when creating the highest-level C4 system context\ndocumentation.\n", + "risk": "unknown", + "source": "community" + }, { "id": "cal-com-automation", - "path": "skills/cal-com-automation", + "path": "skills\\cal-com-automation", "category": "uncategorized", "name": "cal-com-automation", "description": "Automate Cal.com tasks via Rube MCP (Composio): manage bookings, check availability, configure webhooks, and handle teams. Always search tools first for current schemas.", @@ -2098,7 +2134,7 @@ }, { "id": "calc", - "path": "skills/libreoffice/calc", + "path": "skills\\libreoffice\\calc", "category": "libreoffice", "name": "calc", "description": "Spreadsheet creation, format conversion (ODS/XLSX/CSV), formulas, data automation with LibreOffice Calc.", @@ -2107,7 +2143,7 @@ }, { "id": "calendly-automation", - "path": "skills/calendly-automation", + "path": "skills\\calendly-automation", "category": "uncategorized", "name": "calendly-automation", "description": "Automate Calendly scheduling, event management, invitee tracking, availability checks, and organization administration via Rube MCP (Composio). Always search tools first for current schemas.", @@ -2116,7 +2152,7 @@ }, { "id": "canva-automation", - "path": "skills/canva-automation", + "path": "skills\\canva-automation", "category": "uncategorized", "name": "canva-automation", "description": "Automate Canva tasks via Rube MCP (Composio): designs, exports, folders, brand templates, autofill. Always search tools first for current schemas.", @@ -2125,16 +2161,25 @@ }, { "id": "canvas-design", - "path": "skills/canvas-design", + "path": "skills\\canvas-design", "category": "uncategorized", "name": "canvas-design", "description": "Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create ...", "risk": "unknown", "source": "community" }, + { + "id": "carrier-relationship-management", + "path": "skills\\carrier-relationship-management", + "category": "uncategorized", + "name": "carrier-relationship-management", + "description": "Codified expertise for managing carrier portfolios, negotiating freight rates, tracking carrier performance, allocating freight, and maintaining strategic carrier relationships. Informed by transportation managers with 15+ years experience. Includes scorecarding frameworks, RFP processes, market intelligence, and compliance vetting. Use when managing carriers, negotiating rates, evaluating carrier performance, or building freight strategies.\n", + "risk": "safe", + "source": "https://github.com/ai-evos/agent-skills" + }, { "id": "cc-skill-backend-patterns", - "path": "skills/cc-skill-backend-patterns", + "path": "skills\\cc-skill-backend-patterns", "category": "uncategorized", "name": "cc-skill-backend-patterns", "description": "Backend architecture patterns, API design, database optimization, and server-side best practices for Node.js, Express, and Next.js API routes.", @@ -2143,7 +2188,7 @@ }, { "id": "cc-skill-clickhouse-io", - "path": "skills/cc-skill-clickhouse-io", + "path": "skills\\cc-skill-clickhouse-io", "category": "uncategorized", "name": "cc-skill-clickhouse-io", "description": "ClickHouse database patterns, query optimization, analytics, and data engineering best practices for high-performance analytical workloads.", @@ -2152,7 +2197,7 @@ }, { "id": "cc-skill-coding-standards", - "path": "skills/cc-skill-coding-standards", + "path": "skills\\cc-skill-coding-standards", "category": "uncategorized", "name": "cc-skill-coding-standards", "description": "Universal coding standards, best practices, and patterns for TypeScript, JavaScript, React, and Node.js development.", @@ -2161,7 +2206,7 @@ }, { "id": "cc-skill-continuous-learning", - "path": "skills/cc-skill-continuous-learning", + "path": "skills\\cc-skill-continuous-learning", "category": "uncategorized", "name": "cc-skill-continuous-learning", "description": "Development skill from everything-claude-code", @@ -2170,7 +2215,7 @@ }, { "id": "cc-skill-frontend-patterns", - "path": "skills/cc-skill-frontend-patterns", + "path": "skills\\cc-skill-frontend-patterns", "category": "uncategorized", "name": "cc-skill-frontend-patterns", "description": "Frontend development patterns for React, Next.js, state management, performance optimization, and UI best practices.", @@ -2179,7 +2224,7 @@ }, { "id": "cc-skill-project-guidelines-example", - "path": "skills/cc-skill-project-guidelines-example", + "path": "skills\\cc-skill-project-guidelines-example", "category": "uncategorized", "name": "cc-skill-project-guidelines-example", "description": "Project Guidelines Skill (Example)", @@ -2188,7 +2233,7 @@ }, { "id": "cc-skill-security-review", - "path": "skills/cc-skill-security-review", + "path": "skills\\cc-skill-security-review", "category": "uncategorized", "name": "cc-skill-security-review", "description": "Use this skill when adding authentication, handling user input, working with secrets, creating API endpoints, or implementing payment/sensitive features. Provides comprehensive security checklist a...", @@ -2197,7 +2242,7 @@ }, { "id": "cc-skill-strategic-compact", - "path": "skills/cc-skill-strategic-compact", + "path": "skills\\cc-skill-strategic-compact", "category": "uncategorized", "name": "cc-skill-strategic-compact", "description": "Development skill from everything-claude-code", @@ -2206,7 +2251,7 @@ }, { "id": "cdk-patterns", - "path": "skills/cdk-patterns", + "path": "skills\\cdk-patterns", "category": "uncategorized", "name": "cdk-patterns", "description": "Common AWS CDK patterns and constructs for building cloud infrastructure with TypeScript, Python, or Java. Use when designing reusable CDK stacks and L3 constructs.", @@ -2215,16 +2260,25 @@ }, { "id": "changelog-automation", - "path": "skills/changelog-automation", + "path": "skills\\changelog-automation", "category": "uncategorized", "name": "changelog-automation", "description": "Automate changelog generation from commits, PRs, and releases following Keep a Changelog format. Use when setting up release workflows, generating release notes, or standardizing commit conventions.", "risk": "unknown", "source": "community" }, + { + "id": "chrome-extension-developer", + "path": "skills\\chrome-extension-developer", + "category": "uncategorized", + "name": "chrome-extension-developer", + "description": "Expert in building Chrome Extensions using Manifest V3. Covers background scripts, service workers, content scripts, and cross-context communication.", + "risk": "safe", + "source": "community" + }, { "id": "cicd-automation-workflow-automate", - "path": "skills/cicd-automation-workflow-automate", + "path": "skills\\cicd-automation-workflow-automate", "category": "uncategorized", "name": "cicd-automation-workflow-automate", "description": "You are a workflow automation expert specializing in creating efficient CI/CD pipelines, GitHub Actions workflows, and automated development processes. Design automation that reduces manual work, i...", @@ -2233,7 +2287,7 @@ }, { "id": "circleci-automation", - "path": "skills/circleci-automation", + "path": "skills\\circleci-automation", "category": "uncategorized", "name": "circleci-automation", "description": "Automate CircleCI tasks via Rube MCP (Composio): trigger pipelines, monitor workflows/jobs, retrieve artifacts and test metadata. Always search tools first for current schemas.", @@ -2242,7 +2296,7 @@ }, { "id": "clarity-gate", - "path": "skills/clarity-gate", + "path": "skills\\clarity-gate", "category": "uncategorized", "name": "clarity-gate", "description": "Pre-ingestion verification for epistemic quality in RAG systems with 9-point verification and Two-Round HITL workflow", @@ -2251,7 +2305,7 @@ }, { "id": "claude-ally-health", - "path": "skills/claude-ally-health", + "path": "skills\\claude-ally-health", "category": "uncategorized", "name": "claude-ally-health", "description": "A health assistant skill for medical information analysis, symptom tracking, and wellness guidance.", @@ -2260,7 +2314,7 @@ }, { "id": "claude-code-guide", - "path": "skills/claude-code-guide", + "path": "skills\\claude-code-guide", "category": "uncategorized", "name": "claude-code-guide", "description": "Master guide for using Claude Code effectively. Includes configuration templates, prompting strategies \\\"Thinking\\\" keywords, debugging techniques, and best practices for interacting wit...", @@ -2269,7 +2323,7 @@ }, { "id": "claude-d3js-skill", - "path": "skills/claude-d3js-skill", + "path": "skills\\claude-d3js-skill", "category": "uncategorized", "name": "claude-d3js-skill", "description": "Creating interactive data visualisations using d3.js. This skill should be used when creating custom charts, graphs, network diagrams, geographic visualisations, or any complex SVG-based data visua...", @@ -2278,7 +2332,7 @@ }, { "id": "claude-scientific-skills", - "path": "skills/claude-scientific-skills", + "path": "skills\\claude-scientific-skills", "category": "uncategorized", "name": "claude-scientific-skills", "description": "Scientific research and analysis skills", @@ -2287,7 +2341,7 @@ }, { "id": "claude-speed-reader", - "path": "skills/claude-speed-reader", + "path": "skills\\claude-speed-reader", "category": "uncategorized", "name": "claude-speed-reader", "description": "-Speed read Claude's responses at 600+ WPM using RSVP with Spritz-style ORP highlighting", @@ -2296,7 +2350,7 @@ }, { "id": "claude-win11-speckit-update-skill", - "path": "skills/claude-win11-speckit-update-skill", + "path": "skills\\claude-win11-speckit-update-skill", "category": "uncategorized", "name": "claude-win11-speckit-update-skill", "description": "Windows 11 system management", @@ -2305,7 +2359,7 @@ }, { "id": "clean-code", - "path": "skills/clean-code", + "path": "skills\\clean-code", "category": "uncategorized", "name": "clean-code", "description": "Applies principles from Robert C. Martin's 'Clean Code'. Use this skill when writing, reviewing, or refactoring code to ensure high quality, readability, and maintainability. Covers naming, functio...", @@ -2314,7 +2368,7 @@ }, { "id": "clerk-auth", - "path": "skills/clerk-auth", + "path": "skills\\clerk-auth", "category": "uncategorized", "name": "clerk-auth", "description": "Expert patterns for Clerk auth implementation, middleware, organizations, webhooks, and user sync Use when: adding authentication, clerk auth, user authentication, sign in, sign up.", @@ -2323,7 +2377,7 @@ }, { "id": "clickup-automation", - "path": "skills/clickup-automation", + "path": "skills\\clickup-automation", "category": "uncategorized", "name": "clickup-automation", "description": "Automate ClickUp project management including tasks, spaces, folders, lists, comments, and team operations via Rube MCP (Composio). Always search tools first for current schemas.", @@ -2332,7 +2386,7 @@ }, { "id": "close-automation", - "path": "skills/close-automation", + "path": "skills\\close-automation", "category": "uncategorized", "name": "close-automation", "description": "Automate Close CRM tasks via Rube MCP (Composio): create leads, manage calls/SMS, handle tasks, and track notes. Always search tools first for current schemas.", @@ -2341,16 +2395,16 @@ }, { "id": "cloud-architect", - "path": "skills/cloud-architect", + "path": "skills\\cloud-architect", "category": "uncategorized", - "name": "Cloud Architect", - "description": "- Working on cloud architect tasks or workflows - Needing guidance, best practices, or checklists for cloud architect", + "name": "cloud-architect", + "description": "Expert cloud architect specializing in AWS/Azure/GCP multi-cloud\ninfrastructure design, advanced IaC (Terraform/OpenTofu/CDK), FinOps cost\noptimization, and modern architectural patterns. Masters serverless,\nmicroservices, security, compliance, and disaster recovery. Use PROACTIVELY\nfor cloud architecture, cost optimization, migration planning, or multi-cloud\nstrategies.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "cloud-devops", - "path": "skills/cloud-devops", + "path": "skills\\cloud-devops", "category": "uncategorized", "name": "cloud-devops", "description": "Cloud infrastructure and DevOps workflow covering AWS, Azure, GCP, Kubernetes, Terraform, CI/CD, monitoring, and cloud-native development.", @@ -2359,16 +2413,25 @@ }, { "id": "cloud-penetration-testing", - "path": "skills/cloud-penetration-testing", + "path": "skills\\cloud-penetration-testing", "category": "uncategorized", "name": "cloud-penetration-testing", "description": "This skill should be used when the user asks to \"perform cloud penetration testing\", \"assess Azure or AWS or GCP security\", \"enumerate cloud resources\", \"exploit cloud misconfiguratio...", "risk": "unknown", "source": "community" }, + { + "id": "cloudflare-workers-expert", + "path": "skills\\cloudflare-workers-expert", + "category": "uncategorized", + "name": "cloudflare-workers-expert", + "description": "Expert in Cloudflare Workers and the Edge Computing ecosystem. Covers Wrangler, KV, D1, Durable Objects, and R2 storage.", + "risk": "safe", + "source": "community" + }, { "id": "cloudformation-best-practices", - "path": "skills/cloudformation-best-practices", + "path": "skills\\cloudformation-best-practices", "category": "uncategorized", "name": "cloudformation-best-practices", "description": "CloudFormation template optimization, nested stacks, drift detection, and production-ready patterns. Use when writing or reviewing CF templates.", @@ -2377,7 +2440,7 @@ }, { "id": "coda-automation", - "path": "skills/coda-automation", + "path": "skills\\coda-automation", "category": "uncategorized", "name": "coda-automation", "description": "Automate Coda tasks via Rube MCP (Composio): manage docs, pages, tables, rows, formulas, permissions, and publishing. Always search tools first for current schemas.", @@ -2386,7 +2449,7 @@ }, { "id": "code-documentation-code-explain", - "path": "skills/code-documentation-code-explain", + "path": "skills\\code-documentation-code-explain", "category": "uncategorized", "name": "code-documentation-code-explain", "description": "You are a code education expert specializing in explaining complex code through clear narratives, visual diagrams, and step-by-step breakdowns. Transform difficult concepts into understandable expl...", @@ -2395,7 +2458,7 @@ }, { "id": "code-documentation-doc-generate", - "path": "skills/code-documentation-doc-generate", + "path": "skills\\code-documentation-doc-generate", "category": "uncategorized", "name": "code-documentation-doc-generate", "description": "You are a documentation expert specializing in creating comprehensive, maintainable documentation from code. Generate API docs, architecture diagrams, user guides, and technical references using AI...", @@ -2404,7 +2467,7 @@ }, { "id": "code-refactoring-context-restore", - "path": "skills/code-refactoring-context-restore", + "path": "skills\\code-refactoring-context-restore", "category": "uncategorized", "name": "code-refactoring-context-restore", "description": "Use when working with code refactoring context restore", @@ -2413,7 +2476,7 @@ }, { "id": "code-refactoring-refactor-clean", - "path": "skills/code-refactoring-refactor-clean", + "path": "skills\\code-refactoring-refactor-clean", "category": "uncategorized", "name": "code-refactoring-refactor-clean", "description": "You are a code refactoring expert specializing in clean code principles, SOLID design patterns, and modern software engineering best practices. Analyze and refactor the provided code to improve its...", @@ -2422,7 +2485,7 @@ }, { "id": "code-refactoring-tech-debt", - "path": "skills/code-refactoring-tech-debt", + "path": "skills\\code-refactoring-tech-debt", "category": "uncategorized", "name": "code-refactoring-tech-debt", "description": "You are a technical debt expert specializing in identifying, quantifying, and prioritizing technical debt in software projects. Analyze the codebase to uncover debt, assess its impact, and create acti", @@ -2431,7 +2494,7 @@ }, { "id": "code-review-ai-ai-review", - "path": "skills/code-review-ai-ai-review", + "path": "skills\\code-review-ai-ai-review", "category": "uncategorized", "name": "code-review-ai-ai-review", "description": "You are an expert AI-powered code review specialist combining automated static analysis, intelligent pattern recognition, and modern DevOps practices. Leverage AI tools (GitHub Copilot, Qodo, GPT-5, C", @@ -2440,7 +2503,7 @@ }, { "id": "code-review-checklist", - "path": "skills/code-review-checklist", + "path": "skills\\code-review-checklist", "category": "uncategorized", "name": "code-review-checklist", "description": "Comprehensive checklist for conducting thorough code reviews covering functionality, security, performance, and maintainability", @@ -2449,7 +2512,7 @@ }, { "id": "code-review-excellence", - "path": "skills/code-review-excellence", + "path": "skills\\code-review-excellence", "category": "uncategorized", "name": "code-review-excellence", "description": "Master effective code review practices to provide constructive feedback, catch bugs early, and foster knowledge sharing while maintaining team morale. Use when reviewing pull requests, establishing...", @@ -2458,7 +2521,7 @@ }, { "id": "code-reviewer", - "path": "skills/code-reviewer", + "path": "skills\\code-reviewer", "category": "uncategorized", "name": "code-reviewer", "description": "Elite code review expert specializing in modern AI-powered code analysis, security vulnerabilities, performance optimization, and production reliability. Masters static analysis tools, security scanning, and configuration review with 2024/2025 best practices. Use PROACTIVELY for code quality assurance.", @@ -2467,7 +2530,7 @@ }, { "id": "codebase-cleanup-deps-audit", - "path": "skills/codebase-cleanup-deps-audit", + "path": "skills\\codebase-cleanup-deps-audit", "category": "uncategorized", "name": "codebase-cleanup-deps-audit", "description": "You are a dependency security expert specializing in vulnerability scanning, license compliance, and supply chain security. Analyze project dependencies for known vulnerabilities, licensing issues,...", @@ -2476,7 +2539,7 @@ }, { "id": "codebase-cleanup-refactor-clean", - "path": "skills/codebase-cleanup-refactor-clean", + "path": "skills\\codebase-cleanup-refactor-clean", "category": "uncategorized", "name": "codebase-cleanup-refactor-clean", "description": "You are a code refactoring expert specializing in clean code principles, SOLID design patterns, and modern software engineering best practices. Analyze and refactor the provided code to improve its...", @@ -2485,7 +2548,7 @@ }, { "id": "codebase-cleanup-tech-debt", - "path": "skills/codebase-cleanup-tech-debt", + "path": "skills\\codebase-cleanup-tech-debt", "category": "uncategorized", "name": "codebase-cleanup-tech-debt", "description": "You are a technical debt expert specializing in identifying, quantifying, and prioritizing technical debt in software projects. Analyze the codebase to uncover debt, assess its impact, and create acti", @@ -2494,7 +2557,7 @@ }, { "id": "codex-review", - "path": "skills/codex-review", + "path": "skills\\codex-review", "category": "uncategorized", "name": "codex-review", "description": "Professional code review with auto CHANGELOG generation, integrated with Codex AI", @@ -2503,7 +2566,7 @@ }, { "id": "commit", - "path": "skills/commit", + "path": "skills\\commit", "category": "uncategorized", "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 re...", @@ -2512,16 +2575,16 @@ }, { "id": "competitive-landscape", - "path": "skills/competitive-landscape", + "path": "skills\\competitive-landscape", "category": "uncategorized", - "name": "Competitive Landscape", - "description": "Comprehensive frameworks for analyzing competition, identifying differentiation opportunities, and developing winning market positioning strategies.", + "name": "competitive-landscape", + "description": "This skill should be used when the user asks to \\\\\\\"analyze\ncompetitors\", \"assess competitive landscape\", \"identify differentiation\",\n\"evaluate market positioning\", \"apply Porter's Five Forces\", or requests\ncompetitive strategy analysis.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "competitor-alternatives", - "path": "skills/competitor-alternatives", + "path": "skills\\competitor-alternatives", "category": "uncategorized", "name": "competitor-alternatives", "description": "When the user wants to create competitor comparison or alternative pages for SEO and sales enablement. Also use when the user mentions 'alternative page,' 'vs page,' 'competitor comparison,' 'compa...", @@ -2530,7 +2593,7 @@ }, { "id": "comprehensive-review-full-review", - "path": "skills/comprehensive-review-full-review", + "path": "skills\\comprehensive-review-full-review", "category": "uncategorized", "name": "comprehensive-review-full-review", "description": "Use when working with comprehensive review full review", @@ -2539,7 +2602,7 @@ }, { "id": "comprehensive-review-pr-enhance", - "path": "skills/comprehensive-review-pr-enhance", + "path": "skills\\comprehensive-review-pr-enhance", "category": "uncategorized", "name": "comprehensive-review-pr-enhance", "description": "You are a PR optimization expert specializing in creating high-quality pull requests that facilitate efficient code reviews. Generate comprehensive PR descriptions, automate review processes, and e...", @@ -2548,7 +2611,7 @@ }, { "id": "computer-use-agents", - "path": "skills/computer-use-agents", + "path": "skills\\computer-use-agents", "category": "uncategorized", "name": "computer-use-agents", "description": "Build AI agents that interact with computers like humans do - viewing screens, moving cursors, clicking buttons, and typing text. Covers Anthropic's Computer Use, OpenAI's Operator/CUA, and open-so...", @@ -2557,7 +2620,7 @@ }, { "id": "computer-vision-expert", - "path": "skills/computer-vision-expert", + "path": "skills\\computer-vision-expert", "category": "uncategorized", "name": "computer-vision-expert", "description": "SOTA Computer Vision Expert (2026). Specialized in YOLO26, Segment Anything 3 (SAM 3), Vision Language Models, and real-time spatial analysis.", @@ -2566,34 +2629,16 @@ }, { "id": "concise-planning", - "path": "skills/concise-planning", + "path": "skills\\concise-planning", "category": "uncategorized", "name": "concise-planning", "description": "Use when a user asks for a plan for a coding task, to generate a clear, actionable, and atomic checklist.", "risk": "unknown", "source": "community" }, - { - "id": "conductor-setup", - "path": "skills/conductor-setup", - "category": "uncategorized", - "name": "Conductor Setup", - "description": "Initialize or resume Conductor project setup. This command creates foundational project documentation through interactive Q&A.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "conductor-validator", - "path": "skills/conductor-validator", - "category": "uncategorized", - "name": "Conductor Validator", - "description": "ls -la conductor/", - "risk": "unknown", - "source": "unknown" - }, { "id": "conductor-implement", - "path": "skills/conductor-implement", + "path": "skills\\conductor-implement", "category": "uncategorized", "name": "conductor-implement", "description": "Execute tasks from a track's implementation plan following TDD workflow", @@ -2602,7 +2647,7 @@ }, { "id": "conductor-manage", - "path": "skills/conductor-manage", + "path": "skills\\conductor-manage", "category": "uncategorized", "name": "conductor-manage", "description": "Manage track lifecycle: archive, restore, delete, rename, and cleanup", @@ -2611,7 +2656,7 @@ }, { "id": "conductor-new-track", - "path": "skills/conductor-new-track", + "path": "skills\\conductor-new-track", "category": "uncategorized", "name": "conductor-new-track", "description": "Create a new track with specification and phased implementation plan", @@ -2620,43 +2665,52 @@ }, { "id": "conductor-revert", - "path": "skills/conductor-revert", + "path": "skills\\conductor-revert", "category": "uncategorized", "name": "conductor-revert", "description": "Git-aware undo by logical work unit (track, phase, or task)", "risk": "unknown", "source": "community" }, + { + "id": "conductor-setup", + "path": "skills\\conductor-setup", + "category": "uncategorized", + "name": "conductor-setup", + "description": "Initialize project with Conductor artifacts (product definition,\ntech stack, workflow, style guides)\n", + "risk": "unknown", + "source": "community" + }, { "id": "conductor-status", - "path": "skills/conductor-status", + "path": "skills\\conductor-status", "category": "uncategorized", "name": "conductor-status", "description": "Display project status, active tracks, and next actions", "risk": "unknown", "source": "community" }, + { + "id": "conductor-validator", + "path": "skills\\conductor-validator", + "category": "uncategorized", + "name": "conductor-validator", + "description": "Validates Conductor project artifacts for completeness,\nconsistency, and correctness. Use after setup, when diagnosing issues, or\nbefore implementation to verify project context.\n", + "risk": "unknown", + "source": "community" + }, { "id": "confluence-automation", - "path": "skills/confluence-automation", + "path": "skills\\confluence-automation", "category": "uncategorized", "name": "confluence-automation", "description": "Automate Confluence page creation, content search, space management, labels, and hierarchy navigation via Rube MCP (Composio). Always search tools first for current schemas.", "risk": "unknown", "source": "community" }, - { - "id": "content-marketer", - "path": "skills/content-marketer", - "category": "uncategorized", - "name": "Content Marketer", - "description": "- Working on content marketer tasks or workflows - Needing guidance, best practices, or checklists for content marketer", - "risk": "unknown", - "source": "unknown" - }, { "id": "content-creator", - "path": "skills/content-creator", + "path": "skills\\content-creator", "category": "uncategorized", "name": "content-creator", "description": "Create SEO-optimized marketing content with consistent brand voice. Includes brand voice analyzer, SEO optimizer, content frameworks, and social media templates. Use when writing blog posts, creati...", @@ -2664,26 +2718,17 @@ "source": "community" }, { - "id": "context-driven-development", - "path": "skills/context-driven-development", + "id": "content-marketer", + "path": "skills\\content-marketer", "category": "uncategorized", - "name": "Context Driven Development", - "description": "Guide for implementing and maintaining context as a managed artifact alongside code, enabling consistent AI interactions and team alignment through structured project documentation.", + "name": "content-marketer", + "description": "Elite content marketing strategist specializing in AI-powered\ncontent creation, omnichannel distribution, SEO optimization, and data-driven\nperformance marketing. Masters modern content tools, social media automation,\nand conversion optimization with 2024/2025 best practices. Use PROACTIVELY for\ncomprehensive content marketing.\n", "risk": "unknown", - "source": "unknown" - }, - { - "id": "context-manager", - "path": "skills/context-manager", - "category": "uncategorized", - "name": "Context Manager", - "description": "- Working on context manager tasks or workflows - Needing guidance, best practices, or checklists for context manager", - "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "context-compression", - "path": "skills/context-compression", + "path": "skills\\context-compression", "category": "uncategorized", "name": "context-compression", "description": "Design and evaluate compression strategies for long-running sessions", @@ -2692,16 +2737,25 @@ }, { "id": "context-degradation", - "path": "skills/context-degradation", + "path": "skills\\context-degradation", "category": "uncategorized", "name": "context-degradation", "description": "Recognize patterns of context failure: lost-in-middle, poisoning, distraction, and clash", "risk": "safe", "source": "https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering/tree/main/skills/context-degradation" }, + { + "id": "context-driven-development", + "path": "skills\\context-driven-development", + "category": "uncategorized", + "name": "context-driven-development", + "description": "Use this skill when working with Conductor's context-driven\ndevelopment methodology, managing project context artifacts, or understanding\nthe relationship between product.md, tech-stack.md, and workflow.md files.\n", + "risk": "unknown", + "source": "community" + }, { "id": "context-fundamentals", - "path": "skills/context-fundamentals", + "path": "skills\\context-fundamentals", "category": "uncategorized", "name": "context-fundamentals", "description": "Understand what context is, why it matters, and the anatomy of context in agent systems", @@ -2710,7 +2764,7 @@ }, { "id": "context-management-context-restore", - "path": "skills/context-management-context-restore", + "path": "skills\\context-management-context-restore", "category": "uncategorized", "name": "context-management-context-restore", "description": "Use when working with context management context restore", @@ -2719,16 +2773,25 @@ }, { "id": "context-management-context-save", - "path": "skills/context-management-context-save", + "path": "skills\\context-management-context-save", "category": "uncategorized", "name": "context-management-context-save", "description": "Use when working with context management context save", "risk": "unknown", "source": "community" }, + { + "id": "context-manager", + "path": "skills\\context-manager", + "category": "uncategorized", + "name": "context-manager", + "description": "Elite AI context engineering specialist mastering dynamic context\nmanagement, vector databases, knowledge graphs, and intelligent memory\nsystems. Orchestrates context across multi-agent workflows, enterprise AI\nsystems, and long-running projects with 2024/2025 best practices. Use\nPROACTIVELY for complex AI orchestration.\n", + "risk": "unknown", + "source": "community" + }, { "id": "context-optimization", - "path": "skills/context-optimization", + "path": "skills\\context-optimization", "category": "uncategorized", "name": "context-optimization", "description": "Apply compaction, masking, and caching strategies", @@ -2737,7 +2800,7 @@ }, { "id": "context-window-management", - "path": "skills/context-window-management", + "path": "skills\\context-window-management", "category": "uncategorized", "name": "context-window-management", "description": "Strategies for managing LLM context windows including summarization, trimming, routing, and avoiding context rot Use when: context window, token limit, context management, context engineering, long...", @@ -2746,7 +2809,7 @@ }, { "id": "context7-auto-research", - "path": "skills/context7-auto-research", + "path": "skills\\context7-auto-research", "category": "uncategorized", "name": "context7-auto-research", "description": "Automatically fetch latest library/framework documentation for Claude Code via Context7 API", @@ -2755,7 +2818,7 @@ }, { "id": "conversation-memory", - "path": "skills/conversation-memory", + "path": "skills\\conversation-memory", "category": "uncategorized", "name": "conversation-memory", "description": "Persistent memory systems for LLM conversations including short-term, long-term, and entity-based memory Use when: conversation memory, remember, memory persistence, long-term memory, chat history.", @@ -2764,7 +2827,7 @@ }, { "id": "convertkit-automation", - "path": "skills/convertkit-automation", + "path": "skills\\convertkit-automation", "category": "uncategorized", "name": "convertkit-automation", "description": "Automate ConvertKit (Kit) tasks via Rube MCP (Composio): manage subscribers, tags, broadcasts, and broadcast stats. Always search tools first for current schemas.", @@ -2773,7 +2836,7 @@ }, { "id": "copilot-sdk", - "path": "skills/copilot-sdk", + "path": "skills\\copilot-sdk", "category": "uncategorized", "name": "copilot-sdk", "description": "Build applications powered by GitHub Copilot using the Copilot SDK. Use when creating programmatic integrations with Copilot across Node.js/TypeScript, Python, Go, or .NET. Covers session managemen...", @@ -2782,7 +2845,7 @@ }, { "id": "copy-editing", - "path": "skills/copy-editing", + "path": "skills\\copy-editing", "category": "uncategorized", "name": "copy-editing", "description": "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,' 'proofread,' 'polish this,' 'make this ...", @@ -2791,16 +2854,16 @@ }, { "id": "copywriting", - "path": "skills/copywriting", + "path": "skills\\copywriting", "category": "uncategorized", - "name": "Copywriting", - "description": "Produce **clear, credible, and action-oriented marketing copy** that aligns with user intent and business goals.", + "name": "copywriting", + "description": "Use this skill when writing, rewriting, or improving marketing copy for any page (homepage, landing page, pricing, feature, product, or about page). This skill produces clear, compelling, and testable copy while enforcing alignment, honesty, and conversion best practices.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "core-components", - "path": "skills/core-components", + "path": "skills\\core-components", "category": "uncategorized", "name": "core-components", "description": "Core component library and design system patterns. Use when building UI, using design tokens, or working with the component library.", @@ -2809,7 +2872,7 @@ }, { "id": "cost-optimization", - "path": "skills/cost-optimization", + "path": "skills\\cost-optimization", "category": "uncategorized", "name": "cost-optimization", "description": "Optimize cloud costs through resource rightsizing, tagging strategies, reserved instances, and spending analysis. Use when reducing cloud expenses, analyzing infrastructure costs, or implementing c...", @@ -2818,16 +2881,16 @@ }, { "id": "cpp-pro", - "path": "skills/cpp-pro", + "path": "skills\\cpp-pro", "category": "uncategorized", - "name": "Cpp Pro", - "description": "- Working on cpp pro tasks or workflows - Needing guidance, best practices, or checklists for cpp pro", + "name": "cpp-pro", + "description": "Write idiomatic C++ code with modern features, RAII, smart\npointers, and STL algorithms. Handles templates, move semantics, and\nperformance optimization. Use PROACTIVELY for C++ refactoring, memory safety,\nor complex C++ patterns.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "cqrs-implementation", - "path": "skills/cqrs-implementation", + "path": "skills\\cqrs-implementation", "category": "uncategorized", "name": "cqrs-implementation", "description": "Implement Command Query Responsibility Segregation for scalable architectures. Use when separating read and write models, optimizing query performance, or building event-sourced systems.", @@ -2836,7 +2899,7 @@ }, { "id": "create-pr", - "path": "skills/create-pr", + "path": "skills\\create-pr", "category": "uncategorized", "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.", @@ -2845,7 +2908,7 @@ }, { "id": "crewai", - "path": "skills/crewai", + "path": "skills\\crewai", "category": "uncategorized", "name": "crewai", "description": "Expert in CrewAI - the leading role-based multi-agent framework used by 60% of Fortune 500 companies. Covers agent design with roles and goals, task definition, crew orchestration, process types (s...", @@ -2854,25 +2917,25 @@ }, { "id": "crypto-bd-agent", - "path": "skills/crypto-bd-agent", + "path": "skills\\crypto-bd-agent", "category": "uncategorized", - "name": "Crypto Bd Agent", - "description": "> Production-tested patterns for building AI agents that autonomously discover, > evaluate, and acquire token listings for cryptocurrency exchanges.", - "risk": "unknown", - "source": "unknown" + "name": "crypto-bd-agent", + "description": "Autonomous crypto business development patterns \u2014 multi-chain token discovery, 100-point scoring with wallet forensics, x402 micropayments, ERC-8004 on-chain identity, LLM cascade routing, and pipeline automation for CEX/DEX listing acquisition. Use when building AI agents for crypto BD, token evaluation, exchange listing outreach, or autonomous commerce with payment protocols.\n", + "risk": "safe", + "source": "community" }, { "id": "csharp-pro", - "path": "skills/csharp-pro", + "path": "skills\\csharp-pro", "category": "uncategorized", - "name": "Csharp Pro", - "description": "- Working on csharp pro tasks or workflows - Needing guidance, best practices, or checklists for csharp pro", + "name": "csharp-pro", + "description": "Write modern C# code with advanced features like records, pattern\nmatching, and async/await. Optimizes .NET applications, implements enterprise\npatterns, and ensures comprehensive testing. Use PROACTIVELY for C#\nrefactoring, performance optimization, or complex .NET solutions.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "culture-index", - "path": "skills/culture-index", + "path": "skills\\culture-index", "category": "uncategorized", "name": "culture-index", "description": "Index and search culture documentation", @@ -2881,16 +2944,25 @@ }, { "id": "customer-support", - "path": "skills/customer-support", + "path": "skills\\customer-support", "category": "uncategorized", - "name": "Customer Support", - "description": "- Working on customer support tasks or workflows - Needing guidance, best practices, or checklists for customer support", + "name": "customer-support", + "description": "Elite AI-powered customer support specialist mastering\nconversational AI, automated ticketing, sentiment analysis, and omnichannel\nsupport experiences. Integrates modern support tools, chatbot platforms, and\nCX optimization with 2024/2025 best practices. Use PROACTIVELY for\ncomprehensive customer experience management.\n", "risk": "unknown", - "source": "unknown" + "source": "community" + }, + { + "id": "customs-trade-compliance", + "path": "skills\\customs-trade-compliance", + "category": "uncategorized", + "name": "customs-trade-compliance", + "description": "Codified expertise for customs documentation, tariff classification, duty optimisation, restricted party screening, and regulatory compliance across multiple jurisdictions. Informed by trade compliance specialists with 15+ years experience. Includes HS classification logic, Incoterms application, FTA utilisation, and penalty mitigation. Use when handling customs clearance, tariff classification, trade compliance, import/export documentation, or duty optimisation.\n", + "risk": "safe", + "source": "https://github.com/ai-evos/agent-skills" }, { "id": "daily-news-report", - "path": "skills/daily-news-report", + "path": "skills\\daily-news-report", "category": "uncategorized", "name": "daily-news-report", "description": "Scrapes content based on a preset URL list, filters high-quality technical information, and generates daily Markdown reports.", @@ -2899,25 +2971,16 @@ }, { "id": "data-engineer", - "path": "skills/data-engineer", + "path": "skills\\data-engineer", "category": "uncategorized", - "name": "Data Engineer", - "description": "You are a data engineer specializing in scalable data pipelines, modern data architecture, and analytics infrastructure.", + "name": "data-engineer", + "description": "Build scalable data pipelines, modern data warehouses, and\nreal-time streaming architectures. Implements Apache Spark, dbt, Airflow, and\ncloud-native data platforms. Use PROACTIVELY for data pipeline design,\nanalytics infrastructure, or modern data stack implementation.\n", "risk": "unknown", - "source": "unknown" - }, - { - "id": "data-scientist", - "path": "skills/data-scientist", - "category": "uncategorized", - "name": "Data Scientist", - "description": "- Working on data scientist tasks or workflows - Needing guidance, best practices, or checklists for data scientist", - "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "data-engineering-data-driven-feature", - "path": "skills/data-engineering-data-driven-feature", + "path": "skills\\data-engineering-data-driven-feature", "category": "uncategorized", "name": "data-engineering-data-driven-feature", "description": "Build features guided by data insights, A/B testing, and continuous measurement using specialized agents for analysis, implementation, and experimentation.", @@ -2926,7 +2989,7 @@ }, { "id": "data-engineering-data-pipeline", - "path": "skills/data-engineering-data-pipeline", + "path": "skills\\data-engineering-data-pipeline", "category": "uncategorized", "name": "data-engineering-data-pipeline", "description": "You are a data pipeline architecture expert specializing in scalable, reliable, and cost-effective data pipelines for batch and streaming data processing.", @@ -2935,16 +2998,25 @@ }, { "id": "data-quality-frameworks", - "path": "skills/data-quality-frameworks", + "path": "skills\\data-quality-frameworks", "category": "uncategorized", "name": "data-quality-frameworks", "description": "Implement data quality validation with Great Expectations, dbt tests, and data contracts. Use when building data quality pipelines, implementing validation rules, or establishing data contracts.", "risk": "unknown", "source": "community" }, + { + "id": "data-scientist", + "path": "skills\\data-scientist", + "category": "uncategorized", + "name": "data-scientist", + "description": "Expert data scientist for advanced analytics, machine learning, and\nstatistical modeling. Handles complex data analysis, predictive modeling, and\nbusiness intelligence. Use PROACTIVELY for data analysis tasks, ML modeling,\nstatistical analysis, and data-driven insights.\n", + "risk": "unknown", + "source": "community" + }, { "id": "data-storytelling", - "path": "skills/data-storytelling", + "path": "skills\\data-storytelling", "category": "uncategorized", "name": "data-storytelling", "description": "Transform data into compelling narratives using visualization, context, and persuasive structure. Use when presenting analytics to stakeholders, creating data reports, or building executive present...", @@ -2953,7 +3025,7 @@ }, { "id": "data-structure-protocol", - "path": "skills/data-structure-protocol", + "path": "skills\\data-structure-protocol", "category": "uncategorized", "name": "data-structure-protocol", "description": "Give agents persistent structural memory of a codebase \u2014 navigate dependencies, track public APIs, and understand why connections exist without re-reading the whole repo.", @@ -2962,7 +3034,7 @@ }, { "id": "database", - "path": "skills/database", + "path": "skills\\database", "category": "uncategorized", "name": "database", "description": "Database development and operations workflow covering SQL, NoSQL, database design, migrations, optimization, and data engineering.", @@ -2971,34 +3043,25 @@ }, { "id": "database-admin", - "path": "skills/database-admin", + "path": "skills\\database-admin", "category": "uncategorized", - "name": "Database Admin", - "description": "- Working on database admin tasks or workflows - Needing guidance, best practices, or checklists for database admin", + "name": "database-admin", + "description": "Expert database administrator specializing in modern cloud\ndatabases, automation, and reliability engineering. Masters AWS/Azure/GCP\ndatabase services, Infrastructure as Code, high availability, disaster\nrecovery, performance optimization, and compliance. Handles multi-cloud\nstrategies, container databases, and cost optimization. Use PROACTIVELY for\ndatabase architecture, operations, or reliability engineering.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "database-architect", - "path": "skills/database-architect", + "path": "skills\\database-architect", "category": "uncategorized", - "name": "Database Architect", - "description": "You are a database architect specializing in designing scalable, performant, and maintainable data layers from the ground up.", + "name": "database-architect", + "description": "Expert database architect specializing in data layer design from\nscratch, technology selection, schema modeling, and scalable database\narchitectures. Masters SQL/NoSQL/TimeSeries database selection, normalization\nstrategies, migration planning, and performance-first design. Handles both\ngreenfield architectures and re-architecture of existing systems. Use\nPROACTIVELY for database architecture, technology selection, or data modeling\ndecisions.\n", "risk": "unknown", - "source": "unknown" - }, - { - "id": "database-optimizer", - "path": "skills/database-optimizer", - "category": "uncategorized", - "name": "Database Optimizer", - "description": "- Working on database optimizer tasks or workflows - Needing guidance, best practices, or checklists for database optimizer", - "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "database-cloud-optimization-cost-optimize", - "path": "skills/database-cloud-optimization-cost-optimize", + "path": "skills\\database-cloud-optimization-cost-optimize", "category": "uncategorized", "name": "database-cloud-optimization-cost-optimize", "description": "You are a cloud cost optimization expert specializing in reducing infrastructure expenses while maintaining performance and reliability. Analyze cloud spending, identify savings opportunities, and ...", @@ -3007,7 +3070,7 @@ }, { "id": "database-design", - "path": "skills/database-design", + "path": "skills\\database-design", "category": "uncategorized", "name": "database-design", "description": "Database design principles and decision-making. Schema design, indexing strategy, ORM selection, serverless databases.", @@ -3016,7 +3079,7 @@ }, { "id": "database-migration", - "path": "skills/database-migration", + "path": "skills\\database-migration", "category": "uncategorized", "name": "database-migration", "description": "Execute database migrations across ORMs and platforms with zero-downtime strategies, data transformation, and rollback procedures. Use when migrating databases, changing schemas, performing data tr...", @@ -3025,7 +3088,7 @@ }, { "id": "database-migrations-migration-observability", - "path": "skills/database-migrations-migration-observability", + "path": "skills\\database-migrations-migration-observability", "category": "uncategorized", "name": "database-migrations-migration-observability", "description": "Migration monitoring, CDC, and observability infrastructure", @@ -3034,16 +3097,25 @@ }, { "id": "database-migrations-sql-migrations", - "path": "skills/database-migrations-sql-migrations", + "path": "skills\\database-migrations-sql-migrations", "category": "uncategorized", "name": "database-migrations-sql-migrations", "description": "SQL database migrations with zero-downtime strategies for PostgreSQL, MySQL, and SQL Server. Focus on data integrity and rollback plans.", "risk": "unknown", "source": "community" }, + { + "id": "database-optimizer", + "path": "skills\\database-optimizer", + "category": "uncategorized", + "name": "database-optimizer", + "description": "Expert database optimizer specializing in modern performance\ntuning, query optimization, and scalable architectures. Masters advanced\nindexing, N+1 resolution, multi-tier caching, partitioning strategies, and\ncloud database optimization. Handles complex query analysis, migration\nstrategies, and performance monitoring. Use PROACTIVELY for database\noptimization, performance issues, or scalability challenges.\n", + "risk": "unknown", + "source": "community" + }, { "id": "datadog-automation", - "path": "skills/datadog-automation", + "path": "skills\\datadog-automation", "category": "uncategorized", "name": "datadog-automation", "description": "Automate Datadog tasks via Rube MCP (Composio): query metrics, search logs, manage monitors/dashboards, create events and downtimes. Always search tools first for current schemas.", @@ -3052,7 +3124,7 @@ }, { "id": "dbos-golang", - "path": "skills/dbos-golang", + "path": "skills\\dbos-golang", "category": "uncategorized", "name": "dbos-golang", "description": "DBOS Go SDK for building reliable, fault-tolerant applications with durable workflows. Use this skill when writing Go code with DBOS, creating workflows and steps, using queues, using the DBOS Clie...", @@ -3061,7 +3133,7 @@ }, { "id": "dbos-python", - "path": "skills/dbos-python", + "path": "skills\\dbos-python", "category": "uncategorized", "name": "dbos-python", "description": "DBOS Python SDK for building reliable, fault-tolerant applications with durable workflows. Use this skill when writing Python code with DBOS, creating workflows and steps, using queues, using DBOSC...", @@ -3070,7 +3142,7 @@ }, { "id": "dbos-typescript", - "path": "skills/dbos-typescript", + "path": "skills\\dbos-typescript", "category": "uncategorized", "name": "dbos-typescript", "description": "DBOS TypeScript SDK for building reliable, fault-tolerant applications with durable workflows. Use this skill when writing TypeScript code with DBOS, creating workflows and steps, using queues, usi...", @@ -3079,7 +3151,7 @@ }, { "id": "dbt-transformation-patterns", - "path": "skills/dbt-transformation-patterns", + "path": "skills\\dbt-transformation-patterns", "category": "uncategorized", "name": "dbt-transformation-patterns", "description": "Master dbt (data build tool) for analytics engineering with model organization, testing, documentation, and incremental strategies. Use when building data transformations, creating data models, or ...", @@ -3088,7 +3160,7 @@ }, { "id": "ddd-context-mapping", - "path": "skills/ddd-context-mapping", + "path": "skills\\ddd-context-mapping", "category": "uncategorized", "name": "ddd-context-mapping", "description": "Map relationships between bounded contexts and define integration contracts using DDD context mapping patterns.", @@ -3097,7 +3169,7 @@ }, { "id": "ddd-strategic-design", - "path": "skills/ddd-strategic-design", + "path": "skills\\ddd-strategic-design", "category": "uncategorized", "name": "ddd-strategic-design", "description": "Design DDD strategic artifacts including subdomains, bounded contexts, and ubiquitous language for complex business domains.", @@ -3106,7 +3178,7 @@ }, { "id": "ddd-tactical-patterns", - "path": "skills/ddd-tactical-patterns", + "path": "skills\\ddd-tactical-patterns", "category": "uncategorized", "name": "ddd-tactical-patterns", "description": "Apply DDD tactical patterns in code using entities, value objects, aggregates, repositories, and domain events with explicit invariants.", @@ -3115,16 +3187,16 @@ }, { "id": "debugger", - "path": "skills/debugger", + "path": "skills\\debugger", "category": "uncategorized", - "name": "Debugger", - "description": "- Working on debugger tasks or workflows - Needing guidance, best practices, or checklists for debugger", + "name": "debugger", + "description": "Debugging specialist for errors, test failures, and unexpected\nbehavior. Use proactively when encountering any issues.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "debugging-strategies", - "path": "skills/debugging-strategies", + "path": "skills\\debugging-strategies", "category": "uncategorized", "name": "debugging-strategies", "description": "Master systematic debugging techniques, profiling tools, and root cause analysis to efficiently track down bugs across any codebase or technology stack. Use when investigating bugs, performance iss...", @@ -3133,7 +3205,7 @@ }, { "id": "debugging-toolkit-smart-debug", - "path": "skills/debugging-toolkit-smart-debug", + "path": "skills\\debugging-toolkit-smart-debug", "category": "uncategorized", "name": "debugging-toolkit-smart-debug", "description": "Use when working with debugging toolkit smart debug", @@ -3142,7 +3214,7 @@ }, { "id": "deep-research", - "path": "skills/deep-research", + "path": "skills\\deep-research", "category": "uncategorized", "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 ...", @@ -3151,7 +3223,7 @@ }, { "id": "defi-protocol-templates", - "path": "skills/defi-protocol-templates", + "path": "skills\\defi-protocol-templates", "category": "uncategorized", "name": "defi-protocol-templates", "description": "Implement DeFi protocols with production-ready templates for staking, AMMs, governance, and lending systems. Use when building decentralized finance applications or smart contract protocols.", @@ -3160,7 +3232,7 @@ }, { "id": "dependency-management-deps-audit", - "path": "skills/dependency-management-deps-audit", + "path": "skills\\dependency-management-deps-audit", "category": "uncategorized", "name": "dependency-management-deps-audit", "description": "You are a dependency security expert specializing in vulnerability scanning, license compliance, and supply chain security. Analyze project dependencies for known vulnerabilities, licensing issues,...", @@ -3169,7 +3241,7 @@ }, { "id": "dependency-upgrade", - "path": "skills/dependency-upgrade", + "path": "skills\\dependency-upgrade", "category": "uncategorized", "name": "dependency-upgrade", "description": "Manage major dependency version upgrades with compatibility analysis, staged rollout, and comprehensive testing. Use when upgrading framework versions, updating major dependencies, or managing brea...", @@ -3178,16 +3250,16 @@ }, { "id": "deployment-engineer", - "path": "skills/deployment-engineer", + "path": "skills\\deployment-engineer", "category": "uncategorized", - "name": "Deployment Engineer", - "description": "You are a deployment engineer specializing in modern CI/CD pipelines, GitOps workflows, and advanced deployment automation.", + "name": "deployment-engineer", + "description": "Expert deployment engineer specializing in modern CI/CD pipelines,\nGitOps workflows, and advanced deployment automation. Masters GitHub Actions,\nArgoCD/Flux, progressive delivery, container security, and platform\nengineering. Handles zero-downtime deployments, security scanning, and\ndeveloper experience optimization. Use PROACTIVELY for CI/CD design, GitOps\nimplementation, or deployment automation.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "deployment-pipeline-design", - "path": "skills/deployment-pipeline-design", + "path": "skills\\deployment-pipeline-design", "category": "uncategorized", "name": "deployment-pipeline-design", "description": "Design multi-stage CI/CD pipelines with approval gates, security checks, and deployment orchestration. Use when architecting deployment workflows, setting up continuous delivery, or implementing Gi...", @@ -3196,7 +3268,7 @@ }, { "id": "deployment-procedures", - "path": "skills/deployment-procedures", + "path": "skills\\deployment-procedures", "category": "uncategorized", "name": "deployment-procedures", "description": "Production deployment principles and decision-making. Safe deployment workflows, rollback strategies, and verification. Teaches thinking, not scripts.", @@ -3205,7 +3277,7 @@ }, { "id": "deployment-validation-config-validate", - "path": "skills/deployment-validation-config-validate", + "path": "skills\\deployment-validation-config-validate", "category": "uncategorized", "name": "deployment-validation-config-validate", "description": "You are a configuration management expert specializing in validating, testing, and ensuring the correctness of application configurations. Create comprehensive validation schemas, implement configurat", @@ -3214,7 +3286,7 @@ }, { "id": "design-md", - "path": "skills/design-md", + "path": "skills\\design-md", "category": "uncategorized", "name": "design-md", "description": "Analyze Stitch projects and synthesize a semantic design system into DESIGN.md files", @@ -3223,7 +3295,7 @@ }, { "id": "design-orchestration", - "path": "skills/design-orchestration", + "path": "skills\\design-orchestration", "category": "uncategorized", "name": "design-orchestration", "description": "Orchestrates design workflows by routing work through brainstorming, multi-agent review, and execution readiness in the correct order. Prevents premature implementation, skipped validation, and unreviewed high-risk designs.", @@ -3232,7 +3304,7 @@ }, { "id": "development", - "path": "skills/development", + "path": "skills\\development", "category": "uncategorized", "name": "development", "description": "Comprehensive web, mobile, and backend development workflow bundling frontend, backend, full-stack, and mobile development skills for end-to-end application delivery.", @@ -3241,16 +3313,16 @@ }, { "id": "devops-troubleshooter", - "path": "skills/devops-troubleshooter", + "path": "skills\\devops-troubleshooter", "category": "uncategorized", - "name": "Devops Troubleshooter", - "description": "- Working on devops troubleshooter tasks or workflows - Needing guidance, best practices, or checklists for devops troubleshooter", + "name": "devops-troubleshooter", + "description": "Expert DevOps troubleshooter specializing in rapid incident\nresponse, advanced debugging, and modern observability. Masters log analysis,\ndistributed tracing, Kubernetes debugging, performance optimization, and root\ncause analysis. Handles production outages, system reliability, and preventive\nmonitoring. Use PROACTIVELY for debugging, incident response, or system\ntroubleshooting.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "discord-automation", - "path": "skills/discord-automation", + "path": "skills\\discord-automation", "category": "uncategorized", "name": "discord-automation", "description": "Automate Discord tasks via Rube MCP (Composio): messages, channels, roles, webhooks, reactions. Always search tools first for current schemas.", @@ -3259,7 +3331,7 @@ }, { "id": "discord-bot-architect", - "path": "skills/discord-bot-architect", + "path": "skills\\discord-bot-architect", "category": "uncategorized", "name": "discord-bot-architect", "description": "Specialized skill for building production-ready Discord bots. Covers Discord.js (JavaScript) and Pycord (Python), gateway intents, slash commands, interactive components, rate limiting, and sharding.", @@ -3268,7 +3340,7 @@ }, { "id": "dispatching-parallel-agents", - "path": "skills/dispatching-parallel-agents", + "path": "skills\\dispatching-parallel-agents", "category": "uncategorized", "name": "dispatching-parallel-agents", "description": "Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies", @@ -3277,7 +3349,7 @@ }, { "id": "distributed-debugging-debug-trace", - "path": "skills/distributed-debugging-debug-trace", + "path": "skills\\distributed-debugging-debug-trace", "category": "uncategorized", "name": "distributed-debugging-debug-trace", "description": "You are a debugging expert specializing in setting up comprehensive debugging environments, distributed tracing, and diagnostic tools. Configure debugging workflows, implement tracing solutions, an...", @@ -3286,7 +3358,7 @@ }, { "id": "distributed-tracing", - "path": "skills/distributed-tracing", + "path": "skills\\distributed-tracing", "category": "uncategorized", "name": "distributed-tracing", "description": "Implement distributed tracing with Jaeger and Tempo to track requests across microservices and identify performance bottlenecks. Use when debugging microservices, analyzing request flows, or implem...", @@ -3295,16 +3367,16 @@ }, { "id": "django-pro", - "path": "skills/django-pro", + "path": "skills\\django-pro", "category": "uncategorized", - "name": "Django Pro", - "description": "- Working on django pro tasks or workflows - Needing guidance, best practices, or checklists for django pro", + "name": "django-pro", + "description": "Master Django 5.x with async views, DRF, Celery, and Django\nChannels. Build scalable web applications with proper architecture, testing,\nand deployment. Use PROACTIVELY for Django development, ORM optimization, or\ncomplex Django patterns.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "doc-coauthoring", - "path": "skills/doc-coauthoring", + "path": "skills\\doc-coauthoring", "category": "uncategorized", "name": "doc-coauthoring", "description": "Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This ...", @@ -3313,7 +3385,7 @@ }, { "id": "docker-expert", - "path": "skills/docker-expert", + "path": "skills\\docker-expert", "category": "uncategorized", "name": "docker-expert", "description": "Docker containerization expert with deep knowledge of multi-stage builds, image optimization, container security, Docker Compose orchestration, and production deployment patterns. Use PROACTIVELY f...", @@ -3322,16 +3394,16 @@ }, { "id": "docs-architect", - "path": "skills/docs-architect", + "path": "skills\\docs-architect", "category": "uncategorized", - "name": "Docs Architect", - "description": "- Working on docs architect tasks or workflows - Needing guidance, best practices, or checklists for docs architect", + "name": "docs-architect", + "description": "Creates comprehensive technical documentation from existing\ncodebases. Analyzes architecture, design patterns, and implementation details\nto produce long-form technical manuals and ebooks. Use PROACTIVELY for system\ndocumentation, architecture guides, or technical deep-dives.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "documentation", - "path": "skills/documentation", + "path": "skills\\documentation", "category": "uncategorized", "name": "documentation", "description": "Documentation generation workflow covering API docs, architecture docs, README files, code comments, and technical writing.", @@ -3340,7 +3412,7 @@ }, { "id": "documentation-generation-doc-generate", - "path": "skills/documentation-generation-doc-generate", + "path": "skills\\documentation-generation-doc-generate", "category": "uncategorized", "name": "documentation-generation-doc-generate", "description": "You are a documentation expert specializing in creating comprehensive, maintainable documentation from code. Generate API docs, architecture diagrams, user guides, and technical references using AI...", @@ -3349,7 +3421,7 @@ }, { "id": "documentation-templates", - "path": "skills/documentation-templates", + "path": "skills\\documentation-templates", "category": "uncategorized", "name": "documentation-templates", "description": "Documentation templates and structure guidelines. README, API docs, code comments, and AI-friendly documentation.", @@ -3358,7 +3430,7 @@ }, { "id": "docusign-automation", - "path": "skills/docusign-automation", + "path": "skills\\docusign-automation", "category": "uncategorized", "name": "docusign-automation", "description": "Automate DocuSign tasks via Rube MCP (Composio): templates, envelopes, signatures, document management. Always search tools first for current schemas.", @@ -3367,7 +3439,7 @@ }, { "id": "docx-official", - "path": "skills/docx-official", + "path": "skills\\docx-official", "category": "uncategorized", "name": "docx-official", "description": "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. When Claude needs to work with professional document...", @@ -3376,7 +3448,7 @@ }, { "id": "domain-driven-design", - "path": "skills/domain-driven-design", + "path": "skills\\domain-driven-design", "category": "uncategorized", "name": "domain-driven-design", "description": "Plan and route Domain-Driven Design work from strategic modeling to tactical implementation and evented architecture patterns.", @@ -3385,16 +3457,16 @@ }, { "id": "dotnet-architect", - "path": "skills/dotnet-architect", + "path": "skills\\dotnet-architect", "category": "uncategorized", - "name": "Dotnet Architect", - "description": "- Working on dotnet architect tasks or workflows - Needing guidance, best practices, or checklists for dotnet architect", + "name": "dotnet-architect", + "description": "Expert .NET backend architect specializing in C#, ASP.NET Core,\nEntity Framework, Dapper, and enterprise application patterns. Masters\nasync/await, dependency injection, caching strategies, and performance\noptimization. Use PROACTIVELY for .NET API development, code review, or\narchitecture decisions.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "dotnet-backend", - "path": "skills/dotnet-backend", + "path": "skills\\dotnet-backend", "category": "uncategorized", "name": "dotnet-backend", "description": "Build ASP.NET Core 8+ backend services with EF Core, auth, background jobs, and production API patterns.", @@ -3403,7 +3475,7 @@ }, { "id": "dotnet-backend-patterns", - "path": "skills/dotnet-backend-patterns", + "path": "skills\\dotnet-backend-patterns", "category": "uncategorized", "name": "dotnet-backend-patterns", "description": "Master C#/.NET backend development patterns for building robust APIs, MCP servers, and enterprise applications. Covers async/await, dependency injection, Entity Framework Core, Dapper, configuratio...", @@ -3412,7 +3484,7 @@ }, { "id": "draw", - "path": "skills/libreoffice/draw", + "path": "skills\\libreoffice\\draw", "category": "libreoffice", "name": "draw", "description": "Vector graphics and diagram creation, format conversion (ODG/SVG/PDF) with LibreOffice Draw.", @@ -3421,7 +3493,7 @@ }, { "id": "dropbox-automation", - "path": "skills/dropbox-automation", + "path": "skills\\dropbox-automation", "category": "uncategorized", "name": "dropbox-automation", "description": "Automate Dropbox file management, sharing, search, uploads, downloads, and folder operations via Rube MCP (Composio). Always search tools first for current schemas.", @@ -3430,16 +3502,16 @@ }, { "id": "dx-optimizer", - "path": "skills/dx-optimizer", + "path": "skills\\dx-optimizer", "category": "uncategorized", - "name": "Dx Optimizer", - "description": "- Working on dx optimizer tasks or workflows - Needing guidance, best practices, or checklists for dx optimizer", + "name": "dx-optimizer", + "description": "Developer Experience specialist. Improves tooling, setup, and\nworkflows. Use PROACTIVELY when setting up new projects, after team feedback,\nor when development friction is noticed.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "e2e-testing", - "path": "skills/e2e-testing", + "path": "skills\\e2e-testing", "category": "uncategorized", "name": "e2e-testing", "description": "End-to-end testing workflow with Playwright for browser automation, visual regression, cross-browser testing, and CI/CD integration.", @@ -3448,7 +3520,7 @@ }, { "id": "e2e-testing-patterns", - "path": "skills/e2e-testing-patterns", + "path": "skills\\e2e-testing-patterns", "category": "uncategorized", "name": "e2e-testing-patterns", "description": "Master end-to-end testing with Playwright and Cypress to build reliable test suites that catch bugs, improve confidence, and enable fast deployment. Use when implementing E2E tests, debugging flaky...", @@ -3457,16 +3529,16 @@ }, { "id": "elixir-pro", - "path": "skills/elixir-pro", + "path": "skills\\elixir-pro", "category": "uncategorized", - "name": "Elixir Pro", - "description": "- Working on elixir pro tasks or workflows - Needing guidance, best practices, or checklists for elixir pro", + "name": "elixir-pro", + "description": "Write idiomatic Elixir code with OTP patterns, supervision trees,\nand Phoenix LiveView. Masters concurrency, fault tolerance, and distributed\nsystems. Use PROACTIVELY for Elixir refactoring, OTP design, or complex BEAM\noptimizations.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "email-sequence", - "path": "skills/email-sequence", + "path": "skills\\email-sequence", "category": "uncategorized", "name": "email-sequence", "description": "When the user wants to create or optimize an email sequence, drip campaign, automated email flow, or lifecycle email program. Also use when the user mentions \"email sequence,\" \"drip campa...", @@ -3475,7 +3547,7 @@ }, { "id": "email-systems", - "path": "skills/email-systems", + "path": "skills\\email-systems", "category": "uncategorized", "name": "email-systems", "description": "Email has the highest ROI of any marketing channel. $36 for every $1 spent. Yet most startups treat it as an afterthought - bulk blasts, no personalization, landing in spam folders. This skill cov...", @@ -3484,7 +3556,7 @@ }, { "id": "embedding-strategies", - "path": "skills/embedding-strategies", + "path": "skills\\embedding-strategies", "category": "uncategorized", "name": "embedding-strategies", "description": "Select and optimize embedding models for semantic search and RAG applications. Use when choosing embedding models, implementing chunking strategies, or optimizing embedding quality for specific dom...", @@ -3493,34 +3565,34 @@ }, { "id": "employment-contract-templates", - "path": "skills/employment-contract-templates", + "path": "skills\\employment-contract-templates", "category": "uncategorized", "name": "employment-contract-templates", "description": "Create employment contracts, offer letters, and HR policy documents following legal best practices. Use when drafting employment agreements, creating HR policies, or standardizing employment docume...", "risk": "unknown", "source": "community" }, + { + "id": "energy-procurement", + "path": "skills\\energy-procurement", + "category": "uncategorized", + "name": "energy-procurement", + "description": "Codified expertise for electricity and gas procurement, tariff optimisation, demand charge management, renewable PPA evaluation, and multi-facility energy cost management. Informed by energy procurement managers with 15+ years experience at large commercial and industrial consumers. Includes market structure analysis, hedging strategies, load profiling, and sustainability reporting frameworks. Use when procuring energy, optimising tariffs, managing demand charges, evaluating PPAs, or developing energy strategies.\n", + "risk": "safe", + "source": "https://github.com/ai-evos/agent-skills" + }, { "id": "environment-setup-guide", - "path": "skills/environment-setup-guide", + "path": "skills\\environment-setup-guide", "category": "uncategorized", "name": "environment-setup-guide", "description": "Guide developers through setting up development environments with proper tools, dependencies, and configurations", "risk": "unknown", "source": "community" }, - { - "id": "error-detective", - "path": "skills/error-detective", - "category": "uncategorized", - "name": "Error Detective", - "description": "- Working on error detective tasks or workflows - Needing guidance, best practices, or checklists for error detective", - "risk": "unknown", - "source": "unknown" - }, { "id": "error-debugging-error-analysis", - "path": "skills/error-debugging-error-analysis", + "path": "skills\\error-debugging-error-analysis", "category": "uncategorized", "name": "error-debugging-error-analysis", "description": "You are an expert error analysis specialist with deep expertise in debugging distributed systems, analyzing production incidents, and implementing comprehensive observability solutions.", @@ -3529,7 +3601,7 @@ }, { "id": "error-debugging-error-trace", - "path": "skills/error-debugging-error-trace", + "path": "skills\\error-debugging-error-trace", "category": "uncategorized", "name": "error-debugging-error-trace", "description": "You are an error tracking and observability expert specializing in implementing comprehensive error monitoring solutions. Set up error tracking systems, configure alerts, implement structured loggi...", @@ -3538,16 +3610,25 @@ }, { "id": "error-debugging-multi-agent-review", - "path": "skills/error-debugging-multi-agent-review", + "path": "skills\\error-debugging-multi-agent-review", "category": "uncategorized", "name": "error-debugging-multi-agent-review", "description": "Use when working with error debugging multi agent review", "risk": "unknown", "source": "community" }, + { + "id": "error-detective", + "path": "skills\\error-detective", + "category": "uncategorized", + "name": "error-detective", + "description": "Search logs and codebases for error patterns, stack traces, and\nanomalies. Correlates errors across systems and identifies root causes. Use\nPROACTIVELY when debugging issues, analyzing logs, or investigating production\nerrors.\n", + "risk": "unknown", + "source": "community" + }, { "id": "error-diagnostics-error-analysis", - "path": "skills/error-diagnostics-error-analysis", + "path": "skills\\error-diagnostics-error-analysis", "category": "uncategorized", "name": "error-diagnostics-error-analysis", "description": "You are an expert error analysis specialist with deep expertise in debugging distributed systems, analyzing production incidents, and implementing comprehensive observability solutions.", @@ -3556,7 +3637,7 @@ }, { "id": "error-diagnostics-error-trace", - "path": "skills/error-diagnostics-error-trace", + "path": "skills\\error-diagnostics-error-trace", "category": "uncategorized", "name": "error-diagnostics-error-trace", "description": "You are an error tracking and observability expert specializing in implementing comprehensive error monitoring solutions. Set up error tracking systems, configure alerts, implement structured logging,", @@ -3565,7 +3646,7 @@ }, { "id": "error-diagnostics-smart-debug", - "path": "skills/error-diagnostics-smart-debug", + "path": "skills\\error-diagnostics-smart-debug", "category": "uncategorized", "name": "error-diagnostics-smart-debug", "description": "Use when working with error diagnostics smart debug", @@ -3574,7 +3655,7 @@ }, { "id": "error-handling-patterns", - "path": "skills/error-handling-patterns", + "path": "skills\\error-handling-patterns", "category": "uncategorized", "name": "error-handling-patterns", "description": "Master error handling patterns across languages including exceptions, Result types, error propagation, and graceful degradation to build resilient applications. Use when implementing error handling...", @@ -3583,7 +3664,7 @@ }, { "id": "ethical-hacking-methodology", - "path": "skills/ethical-hacking-methodology", + "path": "skills\\ethical-hacking-methodology", "category": "uncategorized", "name": "ethical-hacking-methodology", "description": "This skill should be used when the user asks to \"learn ethical hacking\", \"understand penetration testing lifecycle\", \"perform reconnaissance\", \"conduct security scanning\", \"exploit ...", @@ -3592,7 +3673,7 @@ }, { "id": "evaluation", - "path": "skills/evaluation", + "path": "skills\\evaluation", "category": "uncategorized", "name": "evaluation", "description": "Build evaluation frameworks for agent systems", @@ -3601,7 +3682,7 @@ }, { "id": "event-sourcing-architect", - "path": "skills/event-sourcing-architect", + "path": "skills\\event-sourcing-architect", "category": "uncategorized", "name": "event-sourcing-architect", "description": "Expert in event sourcing, CQRS, and event-driven architecture patterns. Masters event store design, projection building, saga orchestration, and eventual consistency patterns. Use PROACTIVELY for e...", @@ -3610,7 +3691,7 @@ }, { "id": "event-store-design", - "path": "skills/event-store-design", + "path": "skills\\event-store-design", "category": "uncategorized", "name": "event-store-design", "description": "Design and implement event stores for event-sourced systems. Use when building event sourcing infrastructure, choosing event store technologies, or implementing event persistence patterns.", @@ -3619,7 +3700,7 @@ }, { "id": "exa-search", - "path": "skills/exa-search", + "path": "skills\\exa-search", "category": "uncategorized", "name": "exa-search", "description": "Semantic search, similar content discovery, and structured research using Exa API", @@ -3628,7 +3709,7 @@ }, { "id": "executing-plans", - "path": "skills/executing-plans", + "path": "skills\\executing-plans", "category": "uncategorized", "name": "executing-plans", "description": "Use when you have a written implementation plan to execute in a separate session with review checkpoints", @@ -3637,7 +3718,7 @@ }, { "id": "expo-deployment", - "path": "skills/expo-deployment", + "path": "skills\\expo-deployment", "category": "uncategorized", "name": "expo-deployment", "description": "Deploy Expo apps to production", @@ -3646,7 +3727,7 @@ }, { "id": "fal-audio", - "path": "skills/fal-audio", + "path": "skills\\fal-audio", "category": "uncategorized", "name": "fal-audio", "description": "Text-to-speech and speech-to-text using fal.ai audio models", @@ -3655,7 +3736,7 @@ }, { "id": "fal-generate", - "path": "skills/fal-generate", + "path": "skills\\fal-generate", "category": "uncategorized", "name": "fal-generate", "description": "Generate images and videos using fal.ai AI models", @@ -3664,7 +3745,7 @@ }, { "id": "fal-image-edit", - "path": "skills/fal-image-edit", + "path": "skills\\fal-image-edit", "category": "uncategorized", "name": "fal-image-edit", "description": "AI-powered image editing with style transfer and object removal", @@ -3673,7 +3754,7 @@ }, { "id": "fal-platform", - "path": "skills/fal-platform", + "path": "skills\\fal-platform", "category": "uncategorized", "name": "fal-platform", "description": "Platform APIs for model management, pricing, and usage tracking", @@ -3682,7 +3763,7 @@ }, { "id": "fal-upscale", - "path": "skills/fal-upscale", + "path": "skills\\fal-upscale", "category": "uncategorized", "name": "fal-upscale", "description": "Upscale and enhance image and video resolution using AI", @@ -3691,7 +3772,7 @@ }, { "id": "fal-workflow", - "path": "skills/fal-workflow", + "path": "skills\\fal-workflow", "category": "uncategorized", "name": "fal-workflow", "description": "Generate workflow JSON files for chaining AI models", @@ -3700,16 +3781,16 @@ }, { "id": "fastapi-pro", - "path": "skills/fastapi-pro", + "path": "skills\\fastapi-pro", "category": "uncategorized", - "name": "Fastapi Pro", - "description": "- Working on fastapi pro tasks or workflows - Needing guidance, best practices, or checklists for fastapi pro", + "name": "fastapi-pro", + "description": "Build high-performance async APIs with FastAPI, SQLAlchemy 2.0, and\nPydantic V2. Master microservices, WebSockets, and modern Python async\npatterns. Use PROACTIVELY for FastAPI development, async optimization, or API\narchitecture.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "fastapi-router-py", - "path": "skills/fastapi-router-py", + "path": "skills\\fastapi-router-py", "category": "uncategorized", "name": "fastapi-router-py", "description": "Create FastAPI routers with CRUD operations, authentication dependencies, and proper response models. Use when building REST API endpoints, creating new routes, implementing CRUD operations, or add...", @@ -3718,7 +3799,7 @@ }, { "id": "fastapi-templates", - "path": "skills/fastapi-templates", + "path": "skills\\fastapi-templates", "category": "uncategorized", "name": "fastapi-templates", "description": "Create production-ready FastAPI projects with async patterns, dependency injection, and comprehensive error handling. Use when building new FastAPI applications or setting up backend API projects.", @@ -3727,7 +3808,7 @@ }, { "id": "ffuf-claude-skill", - "path": "skills/ffuf-claude-skill", + "path": "skills\\ffuf-claude-skill", "category": "uncategorized", "name": "ffuf-claude-skill", "description": "Web fuzzing with ffuf", @@ -3736,7 +3817,7 @@ }, { "id": "figma-automation", - "path": "skills/figma-automation", + "path": "skills\\figma-automation", "category": "uncategorized", "name": "figma-automation", "description": "Automate Figma tasks via Rube MCP (Composio): files, components, design tokens, comments, exports. Always search tools first for current schemas.", @@ -3745,7 +3826,7 @@ }, { "id": "file-organizer", - "path": "skills/file-organizer", + "path": "skills\\file-organizer", "category": "uncategorized", "name": "file-organizer", "description": "Intelligently organizes files and folders by understanding context, finding duplicates, and suggesting better organizational structures. Use when user wants to clean up directories, organize downlo...", @@ -3754,7 +3835,7 @@ }, { "id": "file-path-traversal", - "path": "skills/file-path-traversal", + "path": "skills\\file-path-traversal", "category": "uncategorized", "name": "file-path-traversal", "description": "This skill should be used when the user asks to \"test for directory traversal\", \"exploit path traversal vulnerabilities\", \"read arbitrary files through web applications\", \"find LFI vu...", @@ -3763,7 +3844,7 @@ }, { "id": "file-uploads", - "path": "skills/file-uploads", + "path": "skills\\file-uploads", "category": "uncategorized", "name": "file-uploads", "description": "Expert at handling file uploads and cloud storage. Covers S3, Cloudflare R2, presigned URLs, multipart uploads, and image optimization. Knows how to handle large files without blocking. Use when: f...", @@ -3772,7 +3853,7 @@ }, { "id": "find-bugs", - "path": "skills/find-bugs", + "path": "skills\\find-bugs", "category": "uncategorized", "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.", @@ -3781,7 +3862,7 @@ }, { "id": "finishing-a-development-branch", - "path": "skills/finishing-a-development-branch", + "path": "skills\\finishing-a-development-branch", "category": "uncategorized", "name": "finishing-a-development-branch", "description": "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 structured options for merge, PR, or cleanup", @@ -3790,7 +3871,7 @@ }, { "id": "firebase", - "path": "skills/firebase", + "path": "skills\\firebase", "category": "uncategorized", "name": "firebase", "description": "Firebase gives you a complete backend in minutes - auth, database, storage, functions, hosting. But the ease of setup hides real complexity. Security rules are your last line of defense, and they'r...", @@ -3799,7 +3880,7 @@ }, { "id": "firecrawl-scraper", - "path": "skills/firecrawl-scraper", + "path": "skills\\firecrawl-scraper", "category": "uncategorized", "name": "firecrawl-scraper", "description": "Deep web scraping, screenshots, PDF parsing, and website crawling using Firecrawl API", @@ -3808,16 +3889,16 @@ }, { "id": "firmware-analyst", - "path": "skills/firmware-analyst", + "path": "skills\\firmware-analyst", "category": "uncategorized", - "name": "Firmware Analyst", - "description": "wget http://vendor.com/firmware/update.bin", + "name": "firmware-analyst", + "description": "Expert firmware analyst specializing in embedded systems, IoT\nsecurity, and hardware reverse engineering. Masters firmware extraction,\nanalysis, and vulnerability research for routers, IoT devices, automotive\nsystems, and industrial controllers. Use PROACTIVELY for firmware security\naudits, IoT penetration testing, or embedded systems research.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "fix-review", - "path": "skills/fix-review", + "path": "skills\\fix-review", "category": "uncategorized", "name": "fix-review", "description": "Verify fix commits address audit findings without new bugs", @@ -3826,25 +3907,25 @@ }, { "id": "flutter-expert", - "path": "skills/flutter-expert", + "path": "skills\\flutter-expert", "category": "uncategorized", - "name": "Flutter Expert", - "description": "- Working on flutter expert tasks or workflows - Needing guidance, best practices, or checklists for flutter expert", + "name": "flutter-expert", + "description": "Master Flutter development with Dart 3, advanced widgets, and\nmulti-platform deployment. Handles state management, animations, testing, and\nperformance optimization for mobile, web, desktop, and embedded platforms. Use\nPROACTIVELY for Flutter architecture, UI implementation, or cross-platform\nfeatures.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "form-cro", - "path": "skills/form-cro", + "path": "skills\\form-cro", "category": "uncategorized", - "name": "Form Cro", - "description": "You are an expert in **form optimization and friction reduction**. Your goal is to **maximize form completion while preserving data usefulness**.", + "name": "form-cro", + "description": "Optimize any form that is NOT signup or account registration \u2014 including lead capture, contact, demo request, application, survey, quote, and checkout forms. Use when the goal is to increase form completion rate, reduce friction, or improve lead quality without breaking compliance or downstream workflows.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "fp-ts-errors", - "path": "skills/fp-ts-errors", + "path": "skills\\fp-ts-errors", "category": "uncategorized", "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.", @@ -3853,7 +3934,7 @@ }, { "id": "fp-ts-pragmatic", - "path": "skills/fp-ts-pragmatic", + "path": "skills\\fp-ts-pragmatic", "category": "uncategorized", "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.", @@ -3862,7 +3943,7 @@ }, { "id": "fp-ts-react", - "path": "skills/fp-ts-react", + "path": "skills\\fp-ts-react", "category": "uncategorized", "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.", @@ -3871,7 +3952,7 @@ }, { "id": "framework-migration-code-migrate", - "path": "skills/framework-migration-code-migrate", + "path": "skills\\framework-migration-code-migrate", "category": "uncategorized", "name": "framework-migration-code-migrate", "description": "You are a code migration expert specializing in transitioning codebases between frameworks, languages, versions, and platforms. Generate comprehensive migration plans, automated migration scripts, and", @@ -3880,7 +3961,7 @@ }, { "id": "framework-migration-deps-upgrade", - "path": "skills/framework-migration-deps-upgrade", + "path": "skills\\framework-migration-deps-upgrade", "category": "uncategorized", "name": "framework-migration-deps-upgrade", "description": "You are a dependency management expert specializing in safe, incremental upgrades of project dependencies. Plan and execute dependency updates with minimal risk, proper testing, and clear migration pa", @@ -3889,7 +3970,7 @@ }, { "id": "framework-migration-legacy-modernize", - "path": "skills/framework-migration-legacy-modernize", + "path": "skills\\framework-migration-legacy-modernize", "category": "uncategorized", "name": "framework-migration-legacy-modernize", "description": "Orchestrate a comprehensive legacy system modernization using the strangler fig pattern, enabling gradual replacement of outdated components while maintaining continuous business operations through ex", @@ -3898,7 +3979,7 @@ }, { "id": "free-tool-strategy", - "path": "skills/free-tool-strategy", + "path": "skills\\free-tool-strategy", "category": "uncategorized", "name": "free-tool-strategy", "description": "When the user wants to plan, evaluate, or build a free tool for marketing purposes \u2014 lead generation, SEO value, or brand awareness. Also use when the user mentions \"engineering as mar...", @@ -3907,7 +3988,7 @@ }, { "id": "freshdesk-automation", - "path": "skills/freshdesk-automation", + "path": "skills\\freshdesk-automation", "category": "uncategorized", "name": "freshdesk-automation", "description": "Automate Freshdesk helpdesk operations including tickets, contacts, companies, notes, and replies via Rube MCP (Composio). Always search tools first for current schemas.", @@ -3916,34 +3997,16 @@ }, { "id": "freshservice-automation", - "path": "skills/freshservice-automation", + "path": "skills\\freshservice-automation", "category": "uncategorized", "name": "freshservice-automation", "description": "Automate Freshservice ITSM tasks via Rube MCP (Composio): create/update tickets, bulk operations, service requests, and outbound emails. Always search tools first for current schemas.", "risk": "unknown", "source": "community" }, - { - "id": "frontend-developer", - "path": "skills/frontend-developer", - "category": "uncategorized", - "name": "Frontend Developer", - "description": "You are a frontend development expert specializing in modern React applications, Next.js, and cutting-edge frontend architecture.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "frontend-security-coder", - "path": "skills/frontend-security-coder", - "category": "uncategorized", - "name": "Frontend Security Coder", - "description": "- Working on frontend security coder tasks or workflows - Needing guidance, best practices, or checklists for frontend security coder", - "risk": "unknown", - "source": "unknown" - }, { "id": "frontend-design", - "path": "skills/frontend-design", + "path": "skills\\frontend-design", "category": "uncategorized", "name": "frontend-design", "description": "Create distinctive, production-grade frontend interfaces with intentional aesthetics, high craft, and non-generic visual identity. Use when building or styling web UIs, components, pages, dashboard...", @@ -3952,16 +4015,25 @@ }, { "id": "frontend-dev-guidelines", - "path": "skills/frontend-dev-guidelines", + "path": "skills\\frontend-dev-guidelines", "category": "uncategorized", "name": "frontend-dev-guidelines", "description": "Opinionated frontend development standards for modern React + TypeScript applications. Covers Suspense-first data fetching, lazy loading, feature-based architecture, MUI v7 styling, TanStack Router...", "risk": "unknown", "source": "community" }, + { + "id": "frontend-developer", + "path": "skills\\frontend-developer", + "category": "uncategorized", + "name": "frontend-developer", + "description": "Build React components, implement responsive layouts, and handle\nclient-side state management. Masters React 19, Next.js 15, and modern\nfrontend architecture. Optimizes performance and ensures accessibility. Use\nPROACTIVELY when creating UI components or fixing frontend issues.\n", + "risk": "unknown", + "source": "community" + }, { "id": "frontend-mobile-development-component-scaffold", - "path": "skills/frontend-mobile-development-component-scaffold", + "path": "skills\\frontend-mobile-development-component-scaffold", "category": "uncategorized", "name": "frontend-mobile-development-component-scaffold", "description": "You are a React component architecture expert specializing in scaffolding production-ready, accessible, and performant components. Generate complete component implementations with TypeScript, tests, s", @@ -3970,16 +4042,25 @@ }, { "id": "frontend-mobile-security-xss-scan", - "path": "skills/frontend-mobile-security-xss-scan", + "path": "skills\\frontend-mobile-security-xss-scan", "category": "uncategorized", "name": "frontend-mobile-security-xss-scan", "description": "You are a frontend security specialist focusing on Cross-Site Scripting (XSS) vulnerability detection and prevention. Analyze React, Vue, Angular, and vanilla JavaScript code to identify injection poi", "risk": "unknown", "source": "community" }, + { + "id": "frontend-security-coder", + "path": "skills\\frontend-security-coder", + "category": "uncategorized", + "name": "frontend-security-coder", + "description": "Expert in secure frontend coding practices specializing in XSS\nprevention, output sanitization, and client-side security patterns. Use\nPROACTIVELY for frontend security implementations or client-side security code\nreviews.\n", + "risk": "unknown", + "source": "community" + }, { "id": "frontend-slides", - "path": "skills/frontend-slides", + "path": "skills\\frontend-slides", "category": "uncategorized", "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...", @@ -3988,7 +4069,7 @@ }, { "id": "frontend-ui-dark-ts", - "path": "skills/frontend-ui-dark-ts", + "path": "skills\\frontend-ui-dark-ts", "category": "uncategorized", "name": "frontend-ui-dark-ts", "description": "Build dark-themed React applications using Tailwind CSS with custom theming, glassmorphism effects, and Framer Motion animations. Use when creating dashboards, admin panels, or data-rich interfaces...", @@ -3997,7 +4078,7 @@ }, { "id": "full-stack-orchestration-full-stack-feature", - "path": "skills/full-stack-orchestration-full-stack-feature", + "path": "skills\\full-stack-orchestration-full-stack-feature", "category": "uncategorized", "name": "full-stack-orchestration-full-stack-feature", "description": "Use when working with full stack orchestration full stack feature", @@ -4006,7 +4087,7 @@ }, { "id": "game-art", - "path": "skills/game-development/game-art", + "path": "skills\\game-development\\game-art", "category": "game-development", "name": "game-art", "description": "Game art principles. Visual style selection, asset pipeline, animation workflow.", @@ -4015,7 +4096,7 @@ }, { "id": "game-audio", - "path": "skills/game-development/game-audio", + "path": "skills\\game-development\\game-audio", "category": "game-development", "name": "game-audio", "description": "Game audio principles. Sound design, music integration, adaptive audio systems.", @@ -4024,7 +4105,7 @@ }, { "id": "game-design", - "path": "skills/game-development/game-design", + "path": "skills\\game-development\\game-design", "category": "game-development", "name": "game-design", "description": "Game design principles. GDD structure, balancing, player psychology, progression.", @@ -4033,7 +4114,7 @@ }, { "id": "game-development", - "path": "skills/game-development", + "path": "skills\\game-development", "category": "uncategorized", "name": "game-development", "description": "Game development orchestrator. Routes to platform-specific skills based on project needs.", @@ -4042,7 +4123,7 @@ }, { "id": "gcp-cloud-run", - "path": "skills/gcp-cloud-run", + "path": "skills\\gcp-cloud-run", "category": "uncategorized", "name": "gcp-cloud-run", "description": "Specialized skill for building production-ready serverless applications on GCP. Covers Cloud Run services (containerized), Cloud Run Functions (event-driven), cold start optimization, and event-dri...", @@ -4051,7 +4132,7 @@ }, { "id": "gdpr-data-handling", - "path": "skills/gdpr-data-handling", + "path": "skills\\gdpr-data-handling", "category": "uncategorized", "name": "gdpr-data-handling", "description": "Implement GDPR-compliant data handling with consent management, data subject rights, and privacy by design. Use when building systems that process EU personal data, implementing privacy controls, o...", @@ -4060,7 +4141,7 @@ }, { "id": "gemini-api-dev", - "path": "skills/gemini-api-dev", + "path": "skills\\gemini-api-dev", "category": "uncategorized", "name": "gemini-api-dev", "description": "Use this skill when building applications with Gemini models, Gemini API, working with multimodal content (text, images, audio, video), implementing function calling, using structured outputs, or n...", @@ -4069,7 +4150,7 @@ }, { "id": "geo-fundamentals", - "path": "skills/geo-fundamentals", + "path": "skills\\geo-fundamentals", "category": "uncategorized", "name": "geo-fundamentals", "description": "Generative Engine Optimization for AI search engines (ChatGPT, Claude, Perplexity).", @@ -4078,7 +4159,7 @@ }, { "id": "git-advanced-workflows", - "path": "skills/git-advanced-workflows", + "path": "skills\\git-advanced-workflows", "category": "uncategorized", "name": "git-advanced-workflows", "description": "Master advanced Git workflows including rebasing, cherry-picking, bisect, worktrees, and reflog to maintain clean history and recover from any situation. Use when managing complex Git histories, co...", @@ -4087,7 +4168,7 @@ }, { "id": "git-pr-workflows-git-workflow", - "path": "skills/git-pr-workflows-git-workflow", + "path": "skills\\git-pr-workflows-git-workflow", "category": "uncategorized", "name": "git-pr-workflows-git-workflow", "description": "Orchestrate a comprehensive git workflow from code review through PR creation, leveraging specialized agents for quality assurance, testing, and deployment readiness. This workflow implements modern g", @@ -4096,7 +4177,7 @@ }, { "id": "git-pr-workflows-onboard", - "path": "skills/git-pr-workflows-onboard", + "path": "skills\\git-pr-workflows-onboard", "category": "uncategorized", "name": "git-pr-workflows-onboard", "description": "You are an **expert onboarding specialist and knowledge transfer architect** with deep experience in remote-first organizations, technical team integration, and accelerated learning methodologies. You", @@ -4105,7 +4186,7 @@ }, { "id": "git-pr-workflows-pr-enhance", - "path": "skills/git-pr-workflows-pr-enhance", + "path": "skills\\git-pr-workflows-pr-enhance", "category": "uncategorized", "name": "git-pr-workflows-pr-enhance", "description": "You are a PR optimization expert specializing in creating high-quality pull requests that facilitate efficient code reviews. Generate comprehensive PR descriptions, automate review processes, and ensu", @@ -4114,7 +4195,7 @@ }, { "id": "git-pushing", - "path": "skills/git-pushing", + "path": "skills\\git-pushing", "category": "uncategorized", "name": "git-pushing", "description": "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 save and push their work. Also activate...", @@ -4123,7 +4204,7 @@ }, { "id": "github-actions-templates", - "path": "skills/github-actions-templates", + "path": "skills\\github-actions-templates", "category": "uncategorized", "name": "github-actions-templates", "description": "Create production-ready GitHub Actions workflows for automated testing, building, and deploying applications. Use when setting up CI/CD with GitHub Actions, automating development workflows, or cre...", @@ -4132,7 +4213,7 @@ }, { "id": "github-automation", - "path": "skills/github-automation", + "path": "skills\\github-automation", "category": "uncategorized", "name": "github-automation", "description": "Automate GitHub repositories, issues, pull requests, branches, CI/CD, and permissions via Rube MCP (Composio). Manage code workflows, review PRs, search code, and handle deployments programmatically.", @@ -4141,7 +4222,7 @@ }, { "id": "github-issue-creator", - "path": "skills/github-issue-creator", + "path": "skills\\github-issue-creator", "category": "uncategorized", "name": "github-issue-creator", "description": "Convert raw notes, error logs, voice dictation, or screenshots into crisp GitHub-flavored markdown issue reports. Use when the user pastes bug info, error messages, or informal descriptions and wan...", @@ -4150,7 +4231,7 @@ }, { "id": "github-workflow-automation", - "path": "skills/github-workflow-automation", + "path": "skills\\github-workflow-automation", "category": "uncategorized", "name": "github-workflow-automation", "description": "Automate GitHub workflows with AI assistance. Includes PR reviews, issue triage, CI/CD integration, and Git operations. Use when automating GitHub workflows, setting up PR review automation, creati...", @@ -4159,7 +4240,7 @@ }, { "id": "gitlab-automation", - "path": "skills/gitlab-automation", + "path": "skills\\gitlab-automation", "category": "uncategorized", "name": "gitlab-automation", "description": "Automate GitLab project management, issues, merge requests, pipelines, branches, and user operations via Rube MCP (Composio). Always search tools first for current schemas.", @@ -4168,7 +4249,7 @@ }, { "id": "gitlab-ci-patterns", - "path": "skills/gitlab-ci-patterns", + "path": "skills\\gitlab-ci-patterns", "category": "uncategorized", "name": "gitlab-ci-patterns", "description": "Build GitLab CI/CD pipelines with multi-stage workflows, caching, and distributed runners for scalable automation. Use when implementing GitLab CI/CD, optimizing pipeline performance, or setting up...", @@ -4177,7 +4258,7 @@ }, { "id": "gitops-workflow", - "path": "skills/gitops-workflow", + "path": "skills\\gitops-workflow", "category": "uncategorized", "name": "gitops-workflow", "description": "Implement GitOps workflows with ArgoCD and Flux for automated, declarative Kubernetes deployments with continuous reconciliation. Use when implementing GitOps practices, automating Kubernetes deplo...", @@ -4186,7 +4267,7 @@ }, { "id": "gmail-automation", - "path": "skills/gmail-automation", + "path": "skills\\gmail-automation", "category": "uncategorized", "name": "gmail-automation", "description": "Automate Gmail tasks via Rube MCP (Composio): send/reply, search, labels, drafts, attachments. Always search tools first for current schemas.", @@ -4195,7 +4276,7 @@ }, { "id": "go-concurrency-patterns", - "path": "skills/go-concurrency-patterns", + "path": "skills\\go-concurrency-patterns", "category": "uncategorized", "name": "go-concurrency-patterns", "description": "Master Go concurrency with goroutines, channels, sync primitives, and context. Use when building concurrent Go applications, implementing worker pools, or debugging race conditions.", @@ -4204,7 +4285,7 @@ }, { "id": "go-playwright", - "path": "skills/go-playwright", + "path": "skills\\go-playwright", "category": "uncategorized", "name": "go-playwright", "description": "Expert capability for robust, stealthy, and efficient browser automation using Playwright Go.", @@ -4213,7 +4294,7 @@ }, { "id": "go-rod-master", - "path": "skills/go-rod-master", + "path": "skills\\go-rod-master", "category": "uncategorized", "name": "go-rod-master", "description": "Comprehensive guide for browser automation and web scraping with go-rod (Chrome DevTools Protocol) including stealth anti-bot-detection patterns.", @@ -4222,7 +4303,7 @@ }, { "id": "godot-4-migration", - "path": "skills/godot-4-migration", + "path": "skills\\godot-4-migration", "category": "uncategorized", "name": "godot-4-migration", "description": "Specialized guide for migrating Godot 3.x projects to Godot 4 (GDScript 2.0), covering syntax changes, Tweens, and exports.", @@ -4231,7 +4312,7 @@ }, { "id": "godot-gdscript-patterns", - "path": "skills/godot-gdscript-patterns", + "path": "skills\\godot-gdscript-patterns", "category": "uncategorized", "name": "godot-gdscript-patterns", "description": "Master Godot 4 GDScript patterns including signals, scenes, state machines, and optimization. Use when building Godot games, implementing game systems, or learning GDScript best practices.", @@ -4240,16 +4321,16 @@ }, { "id": "golang-pro", - "path": "skills/golang-pro", + "path": "skills\\golang-pro", "category": "uncategorized", - "name": "Golang Pro", - "description": "You are a Go expert specializing in modern Go 1.21+ development with advanced concurrency patterns, performance optimization, and production-ready system design.", + "name": "golang-pro", + "description": "Master Go 1.21+ with modern patterns, advanced concurrency,\nperformance optimization, and production-ready microservices. Expert in the\nlatest Go ecosystem including generics, workspaces, and cutting-edge\nframeworks. Use PROACTIVELY for Go development, architecture design, or\nperformance optimization.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "google-analytics-automation", - "path": "skills/google-analytics-automation", + "path": "skills\\google-analytics-automation", "category": "uncategorized", "name": "google-analytics-automation", "description": "Automate Google Analytics tasks via Rube MCP (Composio): run reports, list accounts/properties, funnels, pivots, key events. Always search tools first for current schemas.", @@ -4258,7 +4339,7 @@ }, { "id": "google-calendar-automation", - "path": "skills/google-calendar-automation", + "path": "skills\\google-calendar-automation", "category": "uncategorized", "name": "google-calendar-automation", "description": "Automate Google Calendar events, scheduling, availability checks, and attendee management via Rube MCP (Composio). Create events, find free slots, manage attendees, and list calendars programmatica...", @@ -4267,7 +4348,7 @@ }, { "id": "google-drive-automation", - "path": "skills/google-drive-automation", + "path": "skills\\google-drive-automation", "category": "uncategorized", "name": "google-drive-automation", "description": "Automate Google Drive file operations (upload, download, search, share, organize) via Rube MCP (Composio). Upload/download files, manage folders, share with permissions, and search across drives pr...", @@ -4276,7 +4357,7 @@ }, { "id": "googlesheets-automation", - "path": "skills/googlesheets-automation", + "path": "skills\\googlesheets-automation", "category": "uncategorized", "name": "googlesheets-automation", "description": "Automate Google Sheets operations (read, write, format, filter, manage spreadsheets) via Rube MCP (Composio). Read/write data, manage tabs, apply formatting, and search rows programmatically.", @@ -4285,7 +4366,7 @@ }, { "id": "grafana-dashboards", - "path": "skills/grafana-dashboards", + "path": "skills\\grafana-dashboards", "category": "uncategorized", "name": "grafana-dashboards", "description": "Create and manage production Grafana dashboards for real-time visualization of system and application metrics. Use when building monitoring dashboards, visualizing metrics, or creating operational ...", @@ -4294,7 +4375,7 @@ }, { "id": "graphql", - "path": "skills/graphql", + "path": "skills\\graphql", "category": "uncategorized", "name": "graphql", "description": "GraphQL gives clients exactly the data they need - no more, no less. One endpoint, typed schema, introspection. But the flexibility that makes it powerful also makes it dangerous. Without proper co...", @@ -4303,16 +4384,25 @@ }, { "id": "graphql-architect", - "path": "skills/graphql-architect", + "path": "skills\\graphql-architect", "category": "uncategorized", - "name": "Graphql Architect", - "description": "- Working on graphql architect tasks or workflows - Needing guidance, best practices, or checklists for graphql architect", + "name": "graphql-architect", + "description": "Master modern GraphQL with federation, performance optimization,\nand enterprise security. Build scalable schemas, implement advanced caching,\nand design real-time systems. Use PROACTIVELY for GraphQL architecture or\nperformance optimization.\n", "risk": "unknown", - "source": "unknown" + "source": "community" + }, + { + "id": "grpc-golang", + "path": "skills\\grpc-golang", + "category": "uncategorized", + "name": "grpc-golang", + "description": "Build production-ready gRPC services in Go with mTLS, streaming, and observability. Use when designing Protobuf contracts with Buf or implementing secure service-to-service transport.", + "risk": "safe", + "source": "self" }, { "id": "haskell-pro", - "path": "skills/haskell-pro", + "path": "skills\\haskell-pro", "category": "uncategorized", "name": "haskell-pro", "description": "Expert Haskell engineer specializing in advanced type systems, pure functional design, and high-reliability software. Use PROACTIVELY for type-level programming, concurrency, and architecture guidance.", @@ -4321,7 +4411,7 @@ }, { "id": "helm-chart-scaffolding", - "path": "skills/helm-chart-scaffolding", + "path": "skills\\helm-chart-scaffolding", "category": "uncategorized", "name": "helm-chart-scaffolding", "description": "Design, organize, and manage Helm charts for templating and packaging Kubernetes applications with reusable configurations. Use when creating Helm charts, packaging Kubernetes applications, or impl...", @@ -4330,7 +4420,7 @@ }, { "id": "helpdesk-automation", - "path": "skills/helpdesk-automation", + "path": "skills\\helpdesk-automation", "category": "uncategorized", "name": "helpdesk-automation", "description": "Automate HelpDesk tasks via Rube MCP (Composio): list tickets, manage views, use canned responses, and configure custom fields. Always search tools first for current schemas.", @@ -4339,133 +4429,133 @@ }, { "id": "hig-components-content", - "path": "skills/hig-components-content", + "path": "skills\\hig-components-content", "category": "uncategorized", - "name": "Hig Components Content", - "description": "Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.", + "name": "hig-components-content", + "description": "Apple Human Interface Guidelines for content display components. Use this skill when the user asks about \"charts component\", \"collection view\", \"image view\", \"web view\", \"color well\", \"image well\", \"activity view\", \"lockup\", \"data visualization\", \"content display\", displaying images, rendering web content, color pickers, or presenting collections of items in Apple apps. Also use when the user says \"how should I display charts\", \"what's the best way to show images\", \"should I use a web view\", \"how do I build a grid of items\", \"what component shows media\", or \"how do I present a share sheet\". Cross-references: hig-foundations for color/typography/accessibility, hig-patterns for data visualization patterns, hig-components-layout for structural containers, hig-platforms for platform-specific component behavior.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "hig-components-controls", - "path": "skills/hig-components-controls", + "path": "skills\\hig-components-controls", "category": "uncategorized", - "name": "Hig Components Controls", - "description": "Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.", + "name": "hig-components-controls", + "description": "Apple HIG guidance for selection and input controls including pickers, toggles, sliders, steppers, segmented controls, combo boxes, text fields, text views, labels, token fields, virtual keyboards, rating indicators, and gauges. Use this skill when the user says \"picker or segmented control,\" \"how should my form look,\" \"what keyboard type should I use,\" \"toggle vs checkbox,\" or asks about picker design, toggle, switch, slider, stepper, text field, text input, segmented control, combo box, label, token field, virtual keyboard, rating indicator, gauge, form design, input validation, or control state management. Cross-references: hig-components-menus, hig-components-dialogs, hig-components-search.", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "hig-components-dialogs", - "path": "skills/hig-components-dialogs", + "path": "skills\\hig-components-dialogs", "category": "uncategorized", - "name": "Hig Components Dialogs", - "description": "Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.", + "name": "hig-components-dialogs", + "description": "Apple HIG guidance for presentation components including alerts, action sheets, popovers, sheets, and digit entry views. Use this skill when the user says \"should I use an alert or a sheet,\" \"how do I show a confirmation dialog,\" \"when should I use a popover,\" \"my modals are annoying users,\" or asks about alert design, action sheet, popover, sheet, modal, dialog, digit entry, confirmation dialog, warning dialog, modal presentation, non-modal content, destructive action confirmation, or overlay UI patterns. Cross-references: hig-components-menus, hig-components-controls, hig-components-search, hig-patterns.", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "hig-components-layout", - "path": "skills/hig-components-layout", + "path": "skills\\hig-components-layout", "category": "uncategorized", - "name": "Hig Components Layout", - "description": "Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.", + "name": "hig-components-layout", + "description": "Apple Human Interface Guidelines for layout and navigation components. Use this skill when the user asks about \"sidebar\", \"split view\", \"tab bar\", \"tab view\", \"scroll view\", \"window design\", \"panel\", \"list view\", \"table view\", \"column view\", \"outline view\", \"navigation structure\", \"app layout\", \"boxes\", \"ornaments\", or organizing content hierarchically in Apple apps. Also use when the user says \"how should I organize my app\", \"what navigation pattern should I use\", \"my layout breaks on iPad\", \"how do I build a sidebar\", \"should I use tabs or a sidebar\", or \"my app doesn't adapt to different screen sizes\". Cross-references: hig-foundations for layout/spacing principles, hig-platforms for platform-specific navigation, hig-patterns for multitasking and full-screen, hig-components-content for content display.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "hig-components-menus", - "path": "skills/hig-components-menus", + "path": "skills\\hig-components-menus", "category": "uncategorized", - "name": "Hig Components Menus", - "description": "Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.", + "name": "hig-components-menus", + "description": "Apple HIG guidance for menu and button components including menus, context menus, dock menus, edit menus, the menu bar, toolbars, action buttons, pop-up buttons, pull-down buttons, disclosure controls, and standard buttons. Use this skill when the user says \"how should my buttons look,\" \"what goes in the menu bar,\" \"should I use a context menu or action sheet,\" \"how do I design a toolbar,\" or asks about button design, menu design, context menu, toolbar, menu bar, action button, pop-up button, pull-down button, disclosure control, dock menu, edit menu, or any menu/button component layout and behavior. Cross-references: hig-components-search, hig-components-controls, hig-components-dialogs.", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "hig-components-search", - "path": "skills/hig-components-search", + "path": "skills\\hig-components-search", "category": "uncategorized", - "name": "Hig Components Search", - "description": "Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.", + "name": "hig-components-search", + "description": "Apple HIG guidance for navigation-related components including search fields, page controls, and path controls. Use this skill when the user says \"how should search work in my app,\" \"I need a breadcrumb,\" \"how do I paginate content,\" or asks about search field, search bar, page control, path control, breadcrumb, navigation component, search UX, search suggestions, search scopes, paginated content navigation, or file path hierarchy display. Cross-references: hig-components-menus, hig-components-controls, hig-components-dialogs, hig-patterns.", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "hig-components-status", - "path": "skills/hig-components-status", + "path": "skills\\hig-components-status", "category": "uncategorized", - "name": "Hig Components Status", - "description": "Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.", + "name": "hig-components-status", + "description": "Apple HIG guidance for status and progress UI components including progress indicators, status bars, and activity rings. Use this skill when asked about: \"progress indicator\", \"progress bar\", \"loading spinner\", \"status bar\", \"activity ring\", \"progress display\", determinate vs indeterminate progress, loading states, or fitness tracking rings. Also use when the user says \"how do I show loading state,\" \"should I use a spinner or progress bar,\" \"what goes in the status bar,\" or asks about activity indicators. Cross-references: hig-components-system for widgets and complications, hig-inputs for gesture-driven progress controls, hig-technologies for HealthKit and activity ring data integration.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "hig-components-system", - "path": "skills/hig-components-system", + "path": "skills\\hig-components-system", "category": "uncategorized", - "name": "Hig Components System", - "description": "Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.", + "name": "hig-components-system", + "description": "Apple HIG guidance for system experience components: widgets, live activities, notifications, complications, home screen quick actions, top shelf, watch faces, app clips, and app shortcuts. Use when asked about: \"widget design\", \"live activity\", \"notification design\", \"complication\", \"home screen quick action\", \"top shelf\", \"watch face\", \"app clip\", \"app shortcut\", \"system experience\". Also use when the user says \"how do I design a widget,\" \"what should my notification look like,\" \"how do Live Activities work,\" \"should I make an App Clip,\" or asks about surfaces outside the main app. Cross-references: hig-components-status for progress in widgets, hig-inputs for interaction patterns, hig-technologies for Siri and system integration.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "hig-foundations", - "path": "skills/hig-foundations", + "path": "skills\\hig-foundations", "category": "uncategorized", - "name": "Hig Foundations", - "description": "Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.", + "name": "hig-foundations", + "description": "Apple Human Interface Guidelines design foundations. Use this skill when the user asks about \"HIG color\", \"Apple typography\", \"SF Symbols\", \"dark mode guidelines\", \"accessible design\", \"Apple design foundations\", \"app icon\", \"layout guidelines\", \"materials\", \"motion\", \"privacy\", \"right to left\", \"RTL\", \"inclusive design\", branding, images, spatial layout, or writing style. Also use when the user says \"my colors look wrong in dark mode\", \"what font should I use\", \"is my app accessible enough\", \"how do I support Dynamic Type\", \"what contrast ratio do I need\", \"how do I pick system colors\", or \"my icons don't match the system style\". Cross-references: hig-platforms for platform-specific guidance, hig-patterns for interaction patterns, hig-components-layout for structural components, hig-components-content for display.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "hig-inputs", - "path": "skills/hig-inputs", + "path": "skills\\hig-inputs", "category": "uncategorized", - "name": "Hig Inputs", - "description": "Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.", + "name": "hig-inputs", + "description": "Apple HIG guidance for input methods and interaction patterns: gestures, Apple Pencil, keyboards, game controllers, pointers, Digital Crown, eye tracking, focus system, remotes, spatial interactions, gyroscope, accelerometer, and nearby interactions. Use when asked about: \"gesture design\", \"Apple Pencil\", \"keyboard shortcuts\", \"game controller\", \"pointer support\", \"mouse support\", \"trackpad\", \"Digital Crown\", \"eye tracking\", \"visionOS input\", \"focus system\", \"remote control\", \"gyroscope\", \"spatial interaction\". Also use when the user says \"what gestures should I support,\" \"how do I add keyboard shortcuts,\" \"how does input work on Apple TV,\" \"should I support Apple Pencil,\" or asks about input device handling. Cross-references: hig-components-status, hig-components-system, hig-technologies for VoiceOver and Siri.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "hig-patterns", - "path": "skills/hig-patterns", + "path": "skills\\hig-patterns", "category": "uncategorized", - "name": "Hig Patterns", - "description": "Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.", + "name": "hig-patterns", + "description": "Apple Human Interface Guidelines interaction and UX patterns. Use this skill when the user asks about \"onboarding flow\", \"user onboarding\", \"app launch\", \"loading state\", \"drag and drop\", \"search pattern\", \"settings design\", \"notifications\", \"modality\", \"multitasking\", \"feedback pattern\", \"haptics\", \"undo redo\", \"file management\", data entry, sharing, collaboration, full screen, audio, video, haptic feedback, ratings, printing, help, or account management in Apple apps. Also use when the user says \"how should onboarding work\", \"my app takes too long to load\", \"should I use a modal here\", \"how do I handle errors\", \"when should I ask for permissions\", \"how to show progress\", or \"what's the right way to confirm a delete\". Cross-references: hig-foundations for underlying principles, hig-platforms for platform specifics, hig-components-layout for navigation, hig-components-content for data display.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "hig-platforms", - "path": "skills/hig-platforms", + "path": "skills\\hig-platforms", "category": "uncategorized", - "name": "Hig Platforms", - "description": "Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.", + "name": "hig-platforms", + "description": "Apple Human Interface Guidelines for platform-specific design. Use this skill when the user asks about \"designing for iOS\", \"iPad app design\", \"macOS design\", \"tvOS\", \"visionOS\", \"watchOS\", \"Apple platform\", \"which platform\", platform differences, platform-specific conventions, or multi-platform app design. Also use when the user says \"should I design differently for iPad vs iPhone\", \"how does my app work on visionOS\", \"what's different about macOS apps\", \"porting my app to another platform\", \"universal app design\", or \"what input methods does this platform use\". Cross-references: hig-foundations for shared design foundations, hig-patterns for interaction patterns, hig-components-layout for navigation structures, hig-components-content for content display.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "hig-project-context", - "path": "skills/hig-project-context", + "path": "skills\\hig-project-context", "category": "uncategorized", - "name": "Hig Project Context", - "description": "Create and maintain `.claude/apple-design-context.md` so other HIG skills can skip redundant questions.", + "name": "hig-project-context", + "description": "Create or update a shared Apple design context document that other HIG skills use to tailor guidance. Use when the user says \"set up my project context,\" \"what platforms am I targeting,\" \"configure HIG settings,\" or when starting a new Apple platform project. Also activates when other HIG skills need project context but none exists yet. This skill creates .claude/apple-design-context.md so that hig-foundations, hig-platforms, hig-components-*, hig-inputs, and hig-technologies can provide targeted advice without repetitive questions.", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "hig-technologies", - "path": "skills/hig-technologies", + "path": "skills\\hig-technologies", "category": "uncategorized", - "name": "Hig Technologies", - "description": "Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.", + "name": "hig-technologies", + "description": "Apple HIG guidance for Apple technology integrations: Siri, Apple Pay, HealthKit, HomeKit, ARKit, machine learning, generative AI, iCloud, Sign in with Apple, SharePlay, CarPlay, Game Center, in-app purchase, NFC, Wallet, VoiceOver, Maps, Mac Catalyst, and more. Use when asked about: \"Siri integration\", \"Apple Pay\", \"HealthKit\", \"HomeKit\", \"ARKit\", \"augmented reality\", \"machine learning\", \"generative AI\", \"iCloud sync\", \"Sign in with Apple\", \"SharePlay\", \"CarPlay\", \"in-app purchase\", \"NFC\", \"VoiceOver\", \"Maps\", \"Mac Catalyst\". Also use when the user says \"how do I integrate Siri,\" \"what are the Apple Pay guidelines,\" \"how should my AR experience work,\" \"how do I use Sign in with Apple,\" or asks about any Apple framework or service integration. Cross-references: hig-inputs for input methods, hig-components-system for widgets.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "hosted-agents-v2-py", - "path": "skills/hosted-agents-v2-py", + "path": "skills\\hosted-agents-v2-py", "category": "uncategorized", "name": "hosted-agents-v2-py", "description": "Build hosted agents using Azure AI Projects SDK with ImageBasedHostedAgentDefinition. Use when creating container-based agents in Azure AI Foundry.", @@ -4474,16 +4564,16 @@ }, { "id": "hr-pro", - "path": "skills/hr-pro", + "path": "skills\\hr-pro", "category": "uncategorized", - "name": "Hr Pro", - "description": "- Working on hr pro tasks or workflows - Needing guidance, best practices, or checklists for hr pro", + "name": "hr-pro", + "description": "Professional, ethical HR partner for hiring,\nonboarding/offboarding, PTO and leave, performance, compliant policies, and\nemployee relations. Ask for jurisdiction and company context before advising;\nproduce structured, bias-mitigated, lawful templates.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "html-injection-testing", - "path": "skills/html-injection-testing", + "path": "skills\\html-injection-testing", "category": "uncategorized", "name": "html-injection-testing", "description": "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 applications\", or \"test conten...", @@ -4492,7 +4582,7 @@ }, { "id": "hubspot-automation", - "path": "skills/hubspot-automation", + "path": "skills\\hubspot-automation", "category": "uncategorized", "name": "hubspot-automation", "description": "Automate HubSpot CRM operations (contacts, companies, deals, tickets, properties) via Rube MCP using Composio integration.", @@ -4501,7 +4591,7 @@ }, { "id": "hubspot-integration", - "path": "skills/hubspot-integration", + "path": "skills\\hubspot-integration", "category": "uncategorized", "name": "hubspot-integration", "description": "Expert patterns for HubSpot CRM integration including OAuth authentication, CRM objects, associations, batch operations, webhooks, and custom objects. Covers Node.js and Python SDKs. Use when: hubs...", @@ -4510,7 +4600,7 @@ }, { "id": "hugging-face-cli", - "path": "skills/hugging-face-cli", + "path": "skills\\hugging-face-cli", "category": "uncategorized", "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 comput...", @@ -4519,7 +4609,7 @@ }, { "id": "hugging-face-jobs", - "path": "skills/hugging-face-jobs", + "path": "skills\\hugging-face-jobs", "category": "uncategorized", "name": "hugging-face-jobs", "description": "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, cost estimation, authentication with tok...", @@ -4528,16 +4618,16 @@ }, { "id": "hybrid-cloud-architect", - "path": "skills/hybrid-cloud-architect", + "path": "skills\\hybrid-cloud-architect", "category": "uncategorized", - "name": "Hybrid Cloud Architect", - "description": "- Working on hybrid cloud architect tasks or workflows - Needing guidance, best practices, or checklists for hybrid cloud architect", + "name": "hybrid-cloud-architect", + "description": "Expert hybrid cloud architect specializing in complex multi-cloud\nsolutions across AWS/Azure/GCP and private clouds (OpenStack/VMware). Masters\nhybrid connectivity, workload placement optimization, edge computing, and\ncross-cloud automation. Handles compliance, cost optimization, disaster\nrecovery, and migration strategies. Use PROACTIVELY for hybrid architecture,\nmulti-cloud strategy, or complex infrastructure integration.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "hybrid-cloud-networking", - "path": "skills/hybrid-cloud-networking", + "path": "skills\\hybrid-cloud-networking", "category": "uncategorized", "name": "hybrid-cloud-networking", "description": "Configure secure, high-performance connectivity between on-premises infrastructure and cloud platforms using VPN and dedicated connections. Use when building hybrid cloud architectures, connecting ...", @@ -4546,7 +4636,7 @@ }, { "id": "hybrid-search-implementation", - "path": "skills/hybrid-search-implementation", + "path": "skills\\hybrid-search-implementation", "category": "uncategorized", "name": "hybrid-search-implementation", "description": "Combine vector and keyword search for improved retrieval. Use when implementing RAG systems, building search engines, or when neither approach alone provides sufficient recall.", @@ -4555,7 +4645,7 @@ }, { "id": "i18n-localization", - "path": "skills/i18n-localization", + "path": "skills\\i18n-localization", "category": "uncategorized", "name": "i18n-localization", "description": "Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support.", @@ -4564,7 +4654,7 @@ }, { "id": "idor-testing", - "path": "skills/idor-testing", + "path": "skills\\idor-testing", "category": "uncategorized", "name": "idor-testing", "description": "This skill should be used when the user asks to \"test for insecure direct object references,\" \"find IDOR vulnerabilities,\" \"exploit broken access control,\" \"enumerate user IDs or obje...", @@ -4573,16 +4663,16 @@ }, { "id": "imagen", - "path": "skills/imagen", + "path": "skills\\imagen", "category": "uncategorized", "name": "imagen", - "description": "|", + "description": "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", "risk": "safe", "source": "https://github.com/sanjay3290/ai-skills/tree/main/skills/imagen" }, { "id": "impress", - "path": "skills/libreoffice/impress", + "path": "skills\\libreoffice\\impress", "category": "libreoffice", "name": "impress", "description": "Presentation creation, format conversion (ODP/PPTX/PDF), slide automation with LibreOffice Impress.", @@ -4591,16 +4681,16 @@ }, { "id": "incident-responder", - "path": "skills/incident-responder", + "path": "skills\\incident-responder", "category": "uncategorized", - "name": "Incident Responder", - "description": "- Working on incident responder tasks or workflows - Needing guidance, best practices, or checklists for incident responder", + "name": "incident-responder", + "description": "Expert SRE incident responder specializing in rapid problem\nresolution, modern observability, and comprehensive incident management.\nMasters incident command, blameless post-mortems, error budget management, and\nsystem reliability patterns. Handles critical outages, communication\nstrategies, and continuous improvement. Use IMMEDIATELY for production\nincidents or SRE practices.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "incident-response-incident-response", - "path": "skills/incident-response-incident-response", + "path": "skills\\incident-response-incident-response", "category": "uncategorized", "name": "incident-response-incident-response", "description": "Use when working with incident response incident response", @@ -4609,7 +4699,7 @@ }, { "id": "incident-response-smart-fix", - "path": "skills/incident-response-smart-fix", + "path": "skills\\incident-response-smart-fix", "category": "uncategorized", "name": "incident-response-smart-fix", "description": "[Extended thinking: This workflow implements a sophisticated debugging and resolution pipeline that leverages AI-assisted debugging tools and observability platforms to systematically diagnose and res", @@ -4618,7 +4708,7 @@ }, { "id": "incident-runbook-templates", - "path": "skills/incident-runbook-templates", + "path": "skills\\incident-runbook-templates", "category": "uncategorized", "name": "incident-runbook-templates", "description": "Create structured incident response runbooks with step-by-step procedures, escalation paths, and recovery actions. Use when building runbooks, responding to incidents, or establishing incident resp...", @@ -4627,7 +4717,7 @@ }, { "id": "infinite-gratitude", - "path": "skills/infinite-gratitude", + "path": "skills\\infinite-gratitude", "category": "uncategorized", "name": "infinite-gratitude", "description": "Multi-agent research skill for parallel research execution (10 agents, battle-tested with real case studies).", @@ -4636,7 +4726,7 @@ }, { "id": "inngest", - "path": "skills/inngest", + "path": "skills\\inngest", "category": "uncategorized", "name": "inngest", "description": "Inngest expert for serverless-first background jobs, event-driven workflows, and durable execution without managing queues or workers. Use when: inngest, serverless background job, event-driven wor...", @@ -4645,7 +4735,7 @@ }, { "id": "instagram-automation", - "path": "skills/instagram-automation", + "path": "skills\\instagram-automation", "category": "uncategorized", "name": "instagram-automation", "description": "Automate Instagram tasks via Rube MCP (Composio): create posts, carousels, manage media, get insights, and publishing limits. Always search tools first for current schemas.", @@ -4654,7 +4744,7 @@ }, { "id": "interactive-portfolio", - "path": "skills/interactive-portfolio", + "path": "skills\\interactive-portfolio", "category": "uncategorized", "name": "interactive-portfolio", "description": "Expert in building portfolios that actually land jobs and clients - not just showing work, but creating memorable experiences. Covers developer portfolios, designer portfolios, creative portfolios,...", @@ -4663,7 +4753,7 @@ }, { "id": "intercom-automation", - "path": "skills/intercom-automation", + "path": "skills\\intercom-automation", "category": "uncategorized", "name": "intercom-automation", "description": "Automate Intercom tasks via Rube MCP (Composio): conversations, contacts, companies, segments, admins. Always search tools first for current schemas.", @@ -4672,7 +4762,7 @@ }, { "id": "internal-comms-anthropic", - "path": "skills/internal-comms-anthropic", + "path": "skills\\internal-comms-anthropic", "category": "uncategorized", "name": "internal-comms-anthropic", "description": "A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal ...", @@ -4681,7 +4771,7 @@ }, { "id": "internal-comms-community", - "path": "skills/internal-comms-community", + "path": "skills\\internal-comms-community", "category": "uncategorized", "name": "internal-comms-community", "description": "A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal ...", @@ -4689,17 +4779,26 @@ "source": "community" }, { - "id": "ios-developer", - "path": "skills/ios-developer", + "id": "inventory-demand-planning", + "path": "skills\\inventory-demand-planning", "category": "uncategorized", - "name": "Ios Developer", - "description": "- Working on ios developer tasks or workflows - Needing guidance, best practices, or checklists for ios developer", + "name": "inventory-demand-planning", + "description": "Codified expertise for demand forecasting, safety stock optimisation, replenishment planning, and promotional lift estimation at multi-location retailers. Informed by demand planners with 15+ years experience managing hundreds of SKUs. Includes forecasting method selection, ABC/XYZ analysis, seasonal transition management, and vendor negotiation frameworks. Use when forecasting demand, setting safety stock, planning replenishment, managing promotions, or optimising inventory levels.\n", + "risk": "safe", + "source": "https://github.com/ai-evos/agent-skills" + }, + { + "id": "ios-developer", + "path": "skills\\ios-developer", + "category": "uncategorized", + "name": "ios-developer", + "description": "Develop native iOS applications with Swift/SwiftUI. Masters iOS 18,\nSwiftUI, UIKit integration, Core Data, networking, and App Store optimization.\nUse PROACTIVELY for iOS-specific features, App Store optimization, or native\niOS development.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "istio-traffic-management", - "path": "skills/istio-traffic-management", + "path": "skills\\istio-traffic-management", "category": "uncategorized", "name": "istio-traffic-management", "description": "Configure Istio traffic management including routing, load balancing, circuit breakers, and canary deployments. Use when implementing service mesh traffic policies, progressive delivery, or resilie...", @@ -4708,7 +4807,7 @@ }, { "id": "iterate-pr", - "path": "skills/iterate-pr", + "path": "skills\\iterate-pr", "category": "uncategorized", "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.", @@ -4717,34 +4816,34 @@ }, { "id": "java-pro", - "path": "skills/java-pro", + "path": "skills\\java-pro", "category": "uncategorized", - "name": "Java Pro", - "description": "- Working on java pro tasks or workflows - Needing guidance, best practices, or checklists for java pro", + "name": "java-pro", + "description": "Master Java 21+ with modern features like virtual threads, pattern\nmatching, and Spring Boot 3.x. Expert in the latest Java ecosystem including\nGraalVM, Project Loom, and cloud-native patterns. Use PROACTIVELY for Java\ndevelopment, microservices architecture, or performance optimization.\n", "risk": "unknown", - "source": "unknown" - }, - { - "id": "javascript-pro", - "path": "skills/javascript-pro", - "category": "uncategorized", - "name": "Javascript Pro", - "description": "You are a JavaScript expert specializing in modern JS and async programming.", - "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "javascript-mastery", - "path": "skills/javascript-mastery", + "path": "skills\\javascript-mastery", "category": "uncategorized", "name": "javascript-mastery", "description": "Comprehensive JavaScript reference covering 33+ essential concepts every developer should know. From fundamentals like primitives and closures to advanced patterns like async/await and functional p...", "risk": "unknown", "source": "community" }, + { + "id": "javascript-pro", + "path": "skills\\javascript-pro", + "category": "uncategorized", + "name": "javascript-pro", + "description": "Master modern JavaScript with ES6+, async patterns, and Node.js\nAPIs. Handles promises, event loops, and browser/Node compatibility. Use\nPROACTIVELY for JavaScript optimization, async debugging, or complex JS\npatterns.\n", + "risk": "unknown", + "source": "community" + }, { "id": "javascript-testing-patterns", - "path": "skills/javascript-testing-patterns", + "path": "skills\\javascript-testing-patterns", "category": "uncategorized", "name": "javascript-testing-patterns", "description": "Implement comprehensive testing strategies using Jest, Vitest, and Testing Library for unit tests, integration tests, and end-to-end testing with mocking, fixtures, and test-driven development. Use...", @@ -4753,7 +4852,7 @@ }, { "id": "javascript-typescript-typescript-scaffold", - "path": "skills/javascript-typescript-typescript-scaffold", + "path": "skills\\javascript-typescript-typescript-scaffold", "category": "uncategorized", "name": "javascript-typescript-typescript-scaffold", "description": "You are a TypeScript project architecture expert specializing in scaffolding production-ready Node.js and frontend applications. Generate complete project structures with modern tooling (pnpm, Vite, N", @@ -4762,7 +4861,7 @@ }, { "id": "jira-automation", - "path": "skills/jira-automation", + "path": "skills\\jira-automation", "category": "uncategorized", "name": "jira-automation", "description": "Automate Jira tasks via Rube MCP (Composio): issues, projects, sprints, boards, comments, users. Always search tools first for current schemas.", @@ -4771,16 +4870,16 @@ }, { "id": "julia-pro", - "path": "skills/julia-pro", + "path": "skills\\julia-pro", "category": "uncategorized", - "name": "Julia Pro", - "description": "- Working on julia pro tasks or workflows - Needing guidance, best practices, or checklists for julia pro", + "name": "julia-pro", + "description": "Master Julia 1.10+ with modern features, performance optimization,\nmultiple dispatch, and production-ready practices. Expert in the Julia\necosystem including package management, scientific computing, and\nhigh-performance numerical code. Use PROACTIVELY for Julia development,\noptimization, or advanced Julia patterns.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "k8s-manifest-generator", - "path": "skills/k8s-manifest-generator", + "path": "skills\\k8s-manifest-generator", "category": "uncategorized", "name": "k8s-manifest-generator", "description": "Create production-ready Kubernetes manifests for Deployments, Services, ConfigMaps, and Secrets following best practices and security standards. Use when generating Kubernetes YAML manifests, creat...", @@ -4789,7 +4888,7 @@ }, { "id": "k8s-security-policies", - "path": "skills/k8s-security-policies", + "path": "skills\\k8s-security-policies", "category": "uncategorized", "name": "k8s-security-policies", "description": "Implement Kubernetes security policies including NetworkPolicy, PodSecurityPolicy, and RBAC for production-grade security. Use when securing Kubernetes clusters, implementing network isolation, or ...", @@ -4798,7 +4897,7 @@ }, { "id": "kaizen", - "path": "skills/kaizen", + "path": "skills\\kaizen", "category": "uncategorized", "name": "kaizen", "description": "Guide for continuous improvement, error proofing, and standardization. Use this skill when the user wants to improve code quality, refactor, or discuss process improvements.", @@ -4807,7 +4906,7 @@ }, { "id": "klaviyo-automation", - "path": "skills/klaviyo-automation", + "path": "skills\\klaviyo-automation", "category": "uncategorized", "name": "klaviyo-automation", "description": "Automate Klaviyo tasks via Rube MCP (Composio): manage email/SMS campaigns, inspect campaign messages, track tags, and monitor send jobs. Always search tools first for current schemas.", @@ -4816,7 +4915,7 @@ }, { "id": "kotlin-coroutines-expert", - "path": "skills/kotlin-coroutines-expert", + "path": "skills\\kotlin-coroutines-expert", "category": "uncategorized", "name": "kotlin-coroutines-expert", "description": "Expert patterns for Kotlin Coroutines and Flow, covering structured concurrency, error handling, and testing.", @@ -4825,7 +4924,7 @@ }, { "id": "kpi-dashboard-design", - "path": "skills/kpi-dashboard-design", + "path": "skills\\kpi-dashboard-design", "category": "uncategorized", "name": "kpi-dashboard-design", "description": "Design effective KPI dashboards with metrics selection, visualization best practices, and real-time monitoring patterns. Use when building business dashboards, selecting metrics, or designing data ...", @@ -4834,16 +4933,16 @@ }, { "id": "kubernetes-architect", - "path": "skills/kubernetes-architect", + "path": "skills\\kubernetes-architect", "category": "uncategorized", - "name": "Kubernetes Architect", - "description": "You are a Kubernetes architect specializing in cloud-native infrastructure, modern GitOps workflows, and enterprise container orchestration at scale.", + "name": "kubernetes-architect", + "description": "Expert Kubernetes architect specializing in cloud-native\ninfrastructure, advanced GitOps workflows (ArgoCD/Flux), and enterprise\ncontainer orchestration. Masters EKS/AKS/GKE, service mesh (Istio/Linkerd),\nprogressive delivery, multi-tenancy, and platform engineering. Handles\nsecurity, observability, cost optimization, and developer experience. Use\nPROACTIVELY for K8s architecture, GitOps implementation, or cloud-native\nplatform design.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "kubernetes-deployment", - "path": "skills/kubernetes-deployment", + "path": "skills\\kubernetes-deployment", "category": "uncategorized", "name": "kubernetes-deployment", "description": "Kubernetes deployment workflow for container orchestration, Helm charts, service mesh, and production-ready K8s configurations.", @@ -4852,7 +4951,7 @@ }, { "id": "langchain-architecture", - "path": "skills/langchain-architecture", + "path": "skills\\langchain-architecture", "category": "uncategorized", "name": "langchain-architecture", "description": "Design LLM applications using the LangChain framework with agents, memory, and tool integration patterns. Use when building LangChain applications, implementing AI agents, or creating complex LLM w...", @@ -4861,7 +4960,7 @@ }, { "id": "langfuse", - "path": "skills/langfuse", + "path": "skills\\langfuse", "category": "uncategorized", "name": "langfuse", "description": "Expert in Langfuse - the open-source LLM observability platform. Covers tracing, prompt management, evaluation, datasets, and integration with LangChain, LlamaIndex, and OpenAI. Essential for debug...", @@ -4870,7 +4969,7 @@ }, { "id": "langgraph", - "path": "skills/langgraph", + "path": "skills\\langgraph", "category": "uncategorized", "name": "langgraph", "description": "Expert in LangGraph - the production-grade framework for building stateful, multi-actor AI applications. Covers graph construction, state management, cycles and branches, persistence with checkpoin...", @@ -4879,7 +4978,7 @@ }, { "id": "laravel-expert", - "path": "skills/laravel-expert", + "path": "skills\\laravel-expert", "category": "uncategorized", "name": "laravel-expert", "description": "Senior Laravel Engineer role for production-grade, maintainable, and idiomatic Laravel solutions. Focuses on clean architecture, security, performance, and modern standards (Laravel 10/11+).", @@ -4888,7 +4987,7 @@ }, { "id": "laravel-security-audit", - "path": "skills/laravel-security-audit", + "path": "skills\\laravel-security-audit", "category": "uncategorized", "name": "laravel-security-audit", "description": "Security auditor for Laravel applications. Analyzes code for vulnerabilities, misconfigurations, and insecure practices using OWASP standards and Laravel security best practices.", @@ -4897,7 +4996,7 @@ }, { "id": "last30days", - "path": "skills/last30days", + "path": "skills\\last30days", "category": "uncategorized", "name": "last30days", "description": "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.", @@ -4906,7 +5005,7 @@ }, { "id": "launch-strategy", - "path": "skills/launch-strategy", + "path": "skills\\launch-strategy", "category": "uncategorized", "name": "launch-strategy", "description": "When the user wants to plan a product launch, feature announcement, or release strategy. Also use when the user mentions 'launch,' 'Product Hunt,' 'feature release,' 'announcement,' 'go-to-market,'...", @@ -4915,25 +5014,25 @@ }, { "id": "legacy-modernizer", - "path": "skills/legacy-modernizer", + "path": "skills\\legacy-modernizer", "category": "uncategorized", - "name": "Legacy Modernizer", - "description": "- Working on legacy modernizer tasks or workflows - Needing guidance, best practices, or checklists for legacy modernizer", + "name": "legacy-modernizer", + "description": "Refactor legacy codebases, migrate outdated frameworks, and\nimplement gradual modernization. Handles technical debt, dependency updates,\nand backward compatibility. Use PROACTIVELY for legacy system updates,\nframework migrations, or technical debt reduction.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "legal-advisor", - "path": "skills/legal-advisor", + "path": "skills\\legal-advisor", "category": "uncategorized", - "name": "Legal Advisor", - "description": "- Working on legal advisor tasks or workflows - Needing guidance, best practices, or checklists for legal advisor", + "name": "legal-advisor", + "description": "Draft privacy policies, terms of service, disclaimers, and legal\nnotices. Creates GDPR-compliant texts, cookie policies, and data processing\nagreements. Use PROACTIVELY for legal documentation, compliance texts, or\nregulatory requirements.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "linear-automation", - "path": "skills/linear-automation", + "path": "skills\\linear-automation", "category": "uncategorized", "name": "linear-automation", "description": "Automate Linear tasks via Rube MCP (Composio): issues, projects, cycles, teams, labels. Always search tools first for current schemas.", @@ -4942,7 +5041,7 @@ }, { "id": "linear-claude-skill", - "path": "skills/linear-claude-skill", + "path": "skills\\linear-claude-skill", "category": "uncategorized", "name": "linear-claude-skill", "description": "Manage Linear issues, projects, and teams", @@ -4951,16 +5050,25 @@ }, { "id": "linkedin-automation", - "path": "skills/linkedin-automation", + "path": "skills\\linkedin-automation", "category": "uncategorized", "name": "linkedin-automation", "description": "Automate LinkedIn tasks via Rube MCP (Composio): create posts, manage profile, company info, comments, and image uploads. Always search tools first for current schemas.", "risk": "unknown", "source": "community" }, + { + "id": "linkedin-cli", + "path": "skills\\linkedin-cli", + "category": "uncategorized", + "name": "linkedin-cli", + "description": "Use when automating LinkedIn via CLI: fetch profiles, search people/companies, send messages, manage connections, create posts, and Sales Navigator.", + "risk": "safe", + "source": "community" + }, { "id": "linkerd-patterns", - "path": "skills/linkerd-patterns", + "path": "skills\\linkerd-patterns", "category": "uncategorized", "name": "linkerd-patterns", "description": "Implement Linkerd service mesh patterns for lightweight, security-focused service mesh deployments. Use when setting up Linkerd, configuring traffic policies, or implementing zero-trust networking ...", @@ -4969,7 +5077,7 @@ }, { "id": "lint-and-validate", - "path": "skills/lint-and-validate", + "path": "skills\\lint-and-validate", "category": "uncategorized", "name": "lint-and-validate", "description": "Automatic quality control, linting, and static analysis procedures. Use after every code modification to ensure syntax correctness and project standards. Triggers onKeywords: lint, format, check, v...", @@ -4978,7 +5086,7 @@ }, { "id": "linux-privilege-escalation", - "path": "skills/linux-privilege-escalation", + "path": "skills\\linux-privilege-escalation", "category": "uncategorized", "name": "linux-privilege-escalation", "description": "This skill should be used when the user asks to \"escalate privileges on Linux\", \"find privesc vectors on Linux systems\", \"exploit sudo misconfigurations\", \"abuse SUID binaries\", \"ex...", @@ -4987,7 +5095,7 @@ }, { "id": "linux-shell-scripting", - "path": "skills/linux-shell-scripting", + "path": "skills\\linux-shell-scripting", "category": "uncategorized", "name": "linux-shell-scripting", "description": "This skill should be used when the user asks to \"create bash scripts\", \"automate Linux tasks\", \"monitor system resources\", \"backup files\", \"manage users\", or \"write production she...", @@ -4996,7 +5104,7 @@ }, { "id": "linux-troubleshooting", - "path": "skills/linux-troubleshooting", + "path": "skills\\linux-troubleshooting", "category": "uncategorized", "name": "linux-troubleshooting", "description": "Linux system troubleshooting workflow for diagnosing and resolving system issues, performance problems, and service failures.", @@ -5005,7 +5113,7 @@ }, { "id": "llm-app-patterns", - "path": "skills/llm-app-patterns", + "path": "skills\\llm-app-patterns", "category": "uncategorized", "name": "llm-app-patterns", "description": "Production-ready patterns for building LLM applications. Covers RAG pipelines, agent architectures, prompt IDEs, and LLMOps monitoring. Use when designing AI applications, implementing RAG, buildin...", @@ -5014,7 +5122,7 @@ }, { "id": "llm-application-dev-ai-assistant", - "path": "skills/llm-application-dev-ai-assistant", + "path": "skills\\llm-application-dev-ai-assistant", "category": "uncategorized", "name": "llm-application-dev-ai-assistant", "description": "You are an AI assistant development expert specializing in creating intelligent conversational interfaces, chatbots, and AI-powered applications. Design comprehensive AI assistant solutions with natur", @@ -5023,7 +5131,7 @@ }, { "id": "llm-application-dev-langchain-agent", - "path": "skills/llm-application-dev-langchain-agent", + "path": "skills\\llm-application-dev-langchain-agent", "category": "uncategorized", "name": "llm-application-dev-langchain-agent", "description": "You are an expert LangChain agent developer specializing in production-grade AI systems using LangChain 0.1+ and LangGraph.", @@ -5032,7 +5140,7 @@ }, { "id": "llm-application-dev-prompt-optimize", - "path": "skills/llm-application-dev-prompt-optimize", + "path": "skills\\llm-application-dev-prompt-optimize", "category": "uncategorized", "name": "llm-application-dev-prompt-optimize", "description": "You are an expert prompt engineer specializing in crafting effective prompts for LLMs through advanced techniques including constitutional AI, chain-of-thought reasoning, and model-specific optimizati", @@ -5041,16 +5149,25 @@ }, { "id": "llm-evaluation", - "path": "skills/llm-evaluation", + "path": "skills\\llm-evaluation", "category": "uncategorized", "name": "llm-evaluation", "description": "Implement comprehensive evaluation strategies for LLM applications using automated metrics, human feedback, and benchmarking. Use when testing LLM performance, measuring AI application quality, or ...", "risk": "unknown", "source": "community" }, + { + "id": "logistics-exception-management", + "path": "skills\\logistics-exception-management", + "category": "uncategorized", + "name": "logistics-exception-management", + "description": "Codified expertise for handling freight exceptions, shipment delays, damages, losses, and carrier disputes. Informed by logistics professionals with 15+ years operational experience. Includes escalation protocols, carrier-specific behaviours, claims procedures, and judgment frameworks. Use when handling shipping exceptions, freight claims, delivery issues, or carrier disputes.\n", + "risk": "safe", + "source": "https://github.com/ai-evos/agent-skills" + }, { "id": "loki-mode", - "path": "skills/loki-mode", + "path": "skills\\loki-mode", "category": "uncategorized", "name": "loki-mode", "description": "Multi-agent autonomous startup system for Claude Code. Triggers on \"Loki Mode\". Orchestrates 100+ specialized agents across engineering, QA, DevOps, security, data/ML, business operations,...", @@ -5059,34 +5176,34 @@ }, { "id": "m365-agents-dotnet", - "path": "skills/m365-agents-dotnet", + "path": "skills\\m365-agents-dotnet", "category": "uncategorized", - "name": "M365 Agents Dotnet", - "description": "Build enterprise agents for Microsoft 365, Teams, and Copilot Studio using the Microsoft.Agents SDK with ASP.NET Core hosting, agent routing, and MSAL-based authentication.", + "name": "m365-agents-dotnet", + "description": "Microsoft 365 Agents SDK for .NET. Build multichannel agents for Teams/M365/Copilot Studio with ASP.NET Core hosting, AgentApplication routing, and MSAL-based auth. Triggers: \"Microsoft 365 Agents SDK\", \"Microsoft.Agents\", \"AddAgentApplicationOptions\", \"AgentApplication\", \"AddAgentAspNetAuthentication\", \"Copilot Studio client\", \"IAgentHttpAdapter\".\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "m365-agents-py", - "path": "skills/m365-agents-py", + "path": "skills\\m365-agents-py", "category": "uncategorized", - "name": "M365 Agents Py", - "description": "Build enterprise agents for Microsoft 365, Teams, and Copilot Studio using the Microsoft Agents SDK with aiohttp hosting, AgentApplication routing, streaming responses, and MSAL-based authentication.", + "name": "m365-agents-py", + "description": "Microsoft 365 Agents SDK for Python. Build multichannel agents for Teams/M365/Copilot Studio with aiohttp hosting, AgentApplication routing, streaming responses, and MSAL-based auth. Triggers: \"Microsoft 365 Agents SDK\", \"microsoft_agents\", \"AgentApplication\", \"start_agent_process\", \"TurnContext\", \"Copilot Studio client\", \"CloudAdapter\".\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "m365-agents-ts", - "path": "skills/m365-agents-ts", + "path": "skills\\m365-agents-ts", "category": "uncategorized", - "name": "M365 Agents Ts", - "description": "Build enterprise agents for Microsoft 365, Teams, and Copilot Studio using the Microsoft 365 Agents SDK with Express hosting, AgentApplication routing, streaming responses, and Copilot Studio client integrations.", + "name": "m365-agents-ts", + "description": "Microsoft 365 Agents SDK for TypeScript/Node.js. Build multichannel agents for Teams/M365/Copilot Studio with AgentApplication routing, Express hosting, streaming responses, and Copilot Studio client integration. Triggers: \"Microsoft 365 Agents SDK\", \"@microsoft/agents-hosting\", \"AgentApplication\", \"startServer\", \"streamingResponse\", \"Copilot Studio client\", \"@microsoft/agents-copilotstudio-client\".\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "machine-learning-ops-ml-pipeline", - "path": "skills/machine-learning-ops-ml-pipeline", + "path": "skills\\machine-learning-ops-ml-pipeline", "category": "uncategorized", "name": "machine-learning-ops-ml-pipeline", "description": "Design and implement a complete ML pipeline for: $ARGUMENTS", @@ -5095,7 +5212,7 @@ }, { "id": "mailchimp-automation", - "path": "skills/mailchimp-automation", + "path": "skills\\mailchimp-automation", "category": "uncategorized", "name": "mailchimp-automation", "description": "Automate Mailchimp email marketing including campaigns, audiences, subscribers, segments, and analytics via Rube MCP (Composio). Always search tools first for current schemas.", @@ -5104,7 +5221,7 @@ }, { "id": "make-automation", - "path": "skills/make-automation", + "path": "skills\\make-automation", "category": "uncategorized", "name": "make-automation", "description": "Automate Make (Integromat) tasks via Rube MCP (Composio): operations, enums, language and timezone lookups. Always search tools first for current schemas.", @@ -5113,7 +5230,7 @@ }, { "id": "makepad-skills", - "path": "skills/makepad-skills", + "path": "skills\\makepad-skills", "category": "uncategorized", "name": "makepad-skills", "description": "Makepad UI development skills for Rust apps: setup, patterns, shaders, packaging, and troubleshooting.", @@ -5122,16 +5239,16 @@ }, { "id": "malware-analyst", - "path": "skills/malware-analyst", + "path": "skills\\malware-analyst", "category": "uncategorized", - "name": "Malware Analyst", - "description": "file sample.exe sha256sum sample.exe", + "name": "malware-analyst", + "description": "Expert malware analyst specializing in defensive malware research,\nthreat intelligence, and incident response. Masters sandbox analysis,\nbehavioral analysis, and malware family identification. Handles static/dynamic\nanalysis, unpacking, and IOC extraction. Use PROACTIVELY for malware triage,\nthreat hunting, incident response, or security research.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "manifest", - "path": "skills/manifest", + "path": "skills\\manifest", "category": "uncategorized", "name": "manifest", "description": "Install and configure the Manifest observability plugin for your agents. Use when setting up telemetry, configuring API keys, or troubleshooting the plugin.", @@ -5140,16 +5257,16 @@ }, { "id": "market-sizing-analysis", - "path": "skills/market-sizing-analysis", + "path": "skills\\market-sizing-analysis", "category": "uncategorized", - "name": "Market Sizing Analysis", - "description": "Comprehensive market sizing methodologies for calculating Total Addressable Market (TAM), Serviceable Available Market (SAM), and Serviceable Obtainable Market (SOM) for startup opportunities.", + "name": "market-sizing-analysis", + "description": "This skill should be used when the user asks to \\\\\\\"calculate TAM\\\\\\\",\n\"determine SAM\", \"estimate SOM\", \"size the market\", \"calculate market\nopportunity\", \"what's the total addressable market\", or requests market sizing\nanalysis for a startup or business opportunity.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "marketing-ideas", - "path": "skills/marketing-ideas", + "path": "skills\\marketing-ideas", "category": "uncategorized", "name": "marketing-ideas", "description": "Provide proven marketing strategies and growth ideas for SaaS and software products, prioritized using a marketing feasibility scoring system.", @@ -5158,7 +5275,7 @@ }, { "id": "marketing-psychology", - "path": "skills/marketing-psychology", + "path": "skills\\marketing-psychology", "category": "uncategorized", "name": "marketing-psychology", "description": "Apply behavioral science and mental models to marketing decisions, prioritized using a psychological leverage and feasibility scoring system.", @@ -5167,7 +5284,7 @@ }, { "id": "mcp-builder", - "path": "skills/mcp-builder", + "path": "skills\\mcp-builder", "category": "uncategorized", "name": "mcp-builder", "description": "Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate exte...", @@ -5176,7 +5293,7 @@ }, { "id": "mcp-builder-ms", - "path": "skills/mcp-builder-ms", + "path": "skills\\mcp-builder-ms", "category": "uncategorized", "name": "mcp-builder-ms", "description": "Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate exte...", @@ -5185,7 +5302,7 @@ }, { "id": "memory-forensics", - "path": "skills/memory-forensics", + "path": "skills\\memory-forensics", "category": "uncategorized", "name": "memory-forensics", "description": "Master memory forensics techniques including memory acquisition, process analysis, and artifact extraction using Volatility and related tools. Use when analyzing memory dumps, investigating inciden...", @@ -5194,7 +5311,7 @@ }, { "id": "memory-safety-patterns", - "path": "skills/memory-safety-patterns", + "path": "skills\\memory-safety-patterns", "category": "uncategorized", "name": "memory-safety-patterns", "description": "Implement memory-safe programming with RAII, ownership, smart pointers, and resource management across Rust, C++, and C. Use when writing safe systems code, managing resources, or preventing memory...", @@ -5203,7 +5320,7 @@ }, { "id": "memory-systems", - "path": "skills/memory-systems", + "path": "skills\\memory-systems", "category": "uncategorized", "name": "memory-systems", "description": "Design short-term, long-term, and graph-based memory architectures", @@ -5212,16 +5329,16 @@ }, { "id": "mermaid-expert", - "path": "skills/mermaid-expert", + "path": "skills\\mermaid-expert", "category": "uncategorized", - "name": "Mermaid Expert", - "description": "- Working on mermaid expert tasks or workflows - Needing guidance, best practices, or checklists for mermaid expert", + "name": "mermaid-expert", + "description": "Create Mermaid diagrams for flowcharts, sequences, ERDs, and\narchitectures. Masters syntax for all diagram types and styling. Use\nPROACTIVELY for visual documentation, system diagrams, or process flows.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "metasploit-framework", - "path": "skills/metasploit-framework", + "path": "skills\\metasploit-framework", "category": "uncategorized", "name": "metasploit-framework", "description": "This skill should be used when the user asks to \"use Metasploit for penetration testing\", \"exploit vulnerabilities with msfconsole\", \"create payloads with msfvenom\", \"perform post-exp...", @@ -5230,7 +5347,7 @@ }, { "id": "micro-saas-launcher", - "path": "skills/micro-saas-launcher", + "path": "skills\\micro-saas-launcher", "category": "uncategorized", "name": "micro-saas-launcher", "description": "Expert in launching small, focused SaaS products fast - the indie hacker approach to building profitable software. Covers idea validation, MVP development, pricing, launch strategies, and growing t...", @@ -5239,7 +5356,7 @@ }, { "id": "microservices-patterns", - "path": "skills/microservices-patterns", + "path": "skills\\microservices-patterns", "category": "uncategorized", "name": "microservices-patterns", "description": "Design microservices architectures with service boundaries, event-driven communication, and resilience patterns. Use when building distributed systems, decomposing monoliths, or implementing micros...", @@ -5248,16 +5365,16 @@ }, { "id": "microsoft-azure-webjobs-extensions-authentication-events-dotnet", - "path": "skills/microsoft-azure-webjobs-extensions-authentication-events-dotnet", + "path": "skills\\microsoft-azure-webjobs-extensions-authentication-events-dotnet", "category": "uncategorized", - "name": "Microsoft Azure Webjobs Extensions Authentication Events Dotnet", - "description": "Azure Functions extension for handling Microsoft Entra ID custom authentication events.", + "name": "microsoft-azure-webjobs-extensions-authentication-events-dotnet", + "description": "Microsoft Entra Authentication Events SDK for .NET. Azure Functions triggers for custom authentication extensions. Use for token enrichment, custom claims, attribute collection, and OTP customization in Entra ID. Triggers: \"Authentication Events\", \"WebJobsAuthenticationEventsTrigger\", \"OnTokenIssuanceStart\", \"OnAttributeCollectionStart\", \"custom claims\", \"token enrichment\", \"Entra custom extension\", \"authentication extension\".\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "microsoft-teams-automation", - "path": "skills/microsoft-teams-automation", + "path": "skills\\microsoft-teams-automation", "category": "uncategorized", "name": "microsoft-teams-automation", "description": "Automate Microsoft Teams tasks via Rube MCP (Composio): send messages, manage channels, create meetings, handle chats, and search messages. Always search tools first for current schemas.", @@ -5266,16 +5383,16 @@ }, { "id": "minecraft-bukkit-pro", - "path": "skills/minecraft-bukkit-pro", + "path": "skills\\minecraft-bukkit-pro", "category": "uncategorized", - "name": "Minecraft Bukkit Pro", - "description": "- Working on minecraft bukkit pro tasks or workflows - Needing guidance, best practices, or checklists for minecraft bukkit pro", + "name": "minecraft-bukkit-pro", + "description": "Master Minecraft server plugin development with Bukkit, Spigot, and\nPaper APIs. Specializes in event-driven architecture, command systems, world\nmanipulation, player management, and performance optimization. Use PROACTIVELY\nfor plugin architecture, gameplay mechanics, server-side features, or\ncross-version compatibility.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "miro-automation", - "path": "skills/miro-automation", + "path": "skills\\miro-automation", "category": "uncategorized", "name": "miro-automation", "description": "Automate Miro tasks via Rube MCP (Composio): boards, items, sticky notes, frames, sharing, connectors. Always search tools first for current schemas.", @@ -5284,7 +5401,7 @@ }, { "id": "mixpanel-automation", - "path": "skills/mixpanel-automation", + "path": "skills\\mixpanel-automation", "category": "uncategorized", "name": "mixpanel-automation", "description": "Automate Mixpanel tasks via Rube MCP (Composio): events, segmentation, funnels, cohorts, user profiles, JQL queries. Always search tools first for current schemas.", @@ -5293,16 +5410,16 @@ }, { "id": "ml-engineer", - "path": "skills/ml-engineer", + "path": "skills\\ml-engineer", "category": "uncategorized", - "name": "Ml Engineer", - "description": "- Working on ml engineer tasks or workflows - Needing guidance, best practices, or checklists for ml engineer", + "name": "ml-engineer", + "description": "Build production ML systems with PyTorch 2.x, TensorFlow, and\nmodern ML frameworks. Implements model serving, feature engineering, A/B\ntesting, and monitoring. Use PROACTIVELY for ML model deployment, inference\noptimization, or production ML infrastructure.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "ml-pipeline-workflow", - "path": "skills/ml-pipeline-workflow", + "path": "skills\\ml-pipeline-workflow", "category": "uncategorized", "name": "ml-pipeline-workflow", "description": "Build end-to-end MLOps pipelines from data preparation through model training, validation, and production deployment. Use when creating ML pipelines, implementing MLOps practices, or automating mod...", @@ -5311,52 +5428,52 @@ }, { "id": "mlops-engineer", - "path": "skills/mlops-engineer", + "path": "skills\\mlops-engineer", "category": "uncategorized", - "name": "Mlops Engineer", - "description": "- Working on mlops engineer tasks or workflows - Needing guidance, best practices, or checklists for mlops engineer", + "name": "mlops-engineer", + "description": "Build comprehensive ML pipelines, experiment tracking, and model\nregistries with MLflow, Kubeflow, and modern MLOps tools. Implements automated\ntraining, deployment, and monitoring across cloud platforms. Use PROACTIVELY\nfor ML infrastructure, experiment management, or pipeline automation.\n", "risk": "unknown", - "source": "unknown" - }, - { - "id": "mobile-developer", - "path": "skills/mobile-developer", - "category": "uncategorized", - "name": "Mobile Developer", - "description": "- Working on mobile developer tasks or workflows - Needing guidance, best practices, or checklists for mobile developer", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "mobile-security-coder", - "path": "skills/mobile-security-coder", - "category": "uncategorized", - "name": "Mobile Security Coder", - "description": "- Working on mobile security coder tasks or workflows - Needing guidance, best practices, or checklists for mobile security coder", - "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "mobile-design", - "path": "skills/mobile-design", + "path": "skills\\mobile-design", "category": "uncategorized", "name": "mobile-design", "description": "Mobile-first design and engineering doctrine for iOS and Android apps. Covers touch interaction, performance, platform conventions, offline behavior, and mobile-specific decision-making. Teaches pr...", "risk": "unknown", "source": "community" }, + { + "id": "mobile-developer", + "path": "skills\\mobile-developer", + "category": "uncategorized", + "name": "mobile-developer", + "description": "Develop React Native, Flutter, or native mobile apps with modern\narchitecture patterns. Masters cross-platform development, native\nintegrations, offline sync, and app store optimization. Use PROACTIVELY for\nmobile features, cross-platform code, or app optimization.\n", + "risk": "unknown", + "source": "community" + }, { "id": "mobile-games", - "path": "skills/game-development/mobile-games", + "path": "skills\\game-development\\mobile-games", "category": "game-development", "name": "mobile-games", "description": "Mobile game development principles. Touch input, battery, performance, app stores.", "risk": "unknown", "source": "community" }, + { + "id": "mobile-security-coder", + "path": "skills\\mobile-security-coder", + "category": "uncategorized", + "name": "mobile-security-coder", + "description": "Expert in secure mobile coding practices specializing in input\nvalidation, WebView security, and mobile-specific security patterns. Use\nPROACTIVELY for mobile security implementations or mobile security code\nreviews.\n", + "risk": "unknown", + "source": "community" + }, { "id": "modern-javascript-patterns", - "path": "skills/modern-javascript-patterns", + "path": "skills\\modern-javascript-patterns", "category": "uncategorized", "name": "modern-javascript-patterns", "description": "Master ES6+ features including async/await, destructuring, spread operators, arrow functions, promises, modules, iterators, generators, and functional programming patterns for writing clean, effici...", @@ -5365,7 +5482,7 @@ }, { "id": "monday-automation", - "path": "skills/monday-automation", + "path": "skills\\monday-automation", "category": "uncategorized", "name": "monday-automation", "description": "Automate Monday.com work management including boards, items, columns, groups, subitems, and updates via Rube MCP (Composio). Always search tools first for current schemas.", @@ -5374,7 +5491,7 @@ }, { "id": "monorepo-architect", - "path": "skills/monorepo-architect", + "path": "skills\\monorepo-architect", "category": "uncategorized", "name": "monorepo-architect", "description": "Expert in monorepo architecture, build systems, and dependency management at scale. Masters Nx, Turborepo, Bazel, and Lerna for efficient multi-project development. Use PROACTIVELY for monorepo setup,", @@ -5383,7 +5500,7 @@ }, { "id": "monorepo-management", - "path": "skills/monorepo-management", + "path": "skills\\monorepo-management", "category": "uncategorized", "name": "monorepo-management", "description": "Master monorepo management with Turborepo, Nx, and pnpm workspaces to build efficient, scalable multi-package repositories with optimized builds and dependency management. Use when setting up monor...", @@ -5392,7 +5509,7 @@ }, { "id": "moodle-external-api-development", - "path": "skills/moodle-external-api-development", + "path": "skills\\moodle-external-api-development", "category": "uncategorized", "name": "moodle-external-api-development", "description": "Create custom external web service APIs for Moodle LMS. Use when implementing web services for course management, user tracking, quiz operations, or custom plugin functionality. Covers parameter va...", @@ -5401,7 +5518,7 @@ }, { "id": "mtls-configuration", - "path": "skills/mtls-configuration", + "path": "skills\\mtls-configuration", "category": "uncategorized", "name": "mtls-configuration", "description": "Configure mutual TLS (mTLS) for zero-trust service-to-service communication. Use when implementing zero-trust networking, certificate management, or securing internal service communication.", @@ -5410,7 +5527,7 @@ }, { "id": "multi-agent-brainstorming", - "path": "skills/multi-agent-brainstorming", + "path": "skills\\multi-agent-brainstorming", "category": "uncategorized", "name": "multi-agent-brainstorming", "description": "Use this skill when a design or idea requires higher confidence, risk reduction, or formal review. This skill orchestrates a structured, sequential multi-agent design review where each agent has a strict, non-overlapping role. It prevents blind spots, false confidence, and premature convergence.", @@ -5419,7 +5536,7 @@ }, { "id": "multi-agent-patterns", - "path": "skills/multi-agent-patterns", + "path": "skills\\multi-agent-patterns", "category": "uncategorized", "name": "multi-agent-patterns", "description": "Master orchestrator, peer-to-peer, and hierarchical multi-agent architectures", @@ -5428,7 +5545,7 @@ }, { "id": "multi-cloud-architecture", - "path": "skills/multi-cloud-architecture", + "path": "skills\\multi-cloud-architecture", "category": "uncategorized", "name": "multi-cloud-architecture", "description": "Design multi-cloud architectures using a decision framework to select and integrate services across AWS, Azure, and GCP. Use when building multi-cloud systems, avoiding vendor lock-in, or leveragin...", @@ -5437,7 +5554,7 @@ }, { "id": "multi-platform-apps-multi-platform", - "path": "skills/multi-platform-apps-multi-platform", + "path": "skills\\multi-platform-apps-multi-platform", "category": "uncategorized", "name": "multi-platform-apps-multi-platform", "description": "Build and deploy the same feature consistently across web, mobile, and desktop platforms using API-first architecture and parallel implementation strategies.", @@ -5446,7 +5563,7 @@ }, { "id": "multiplayer", - "path": "skills/game-development/multiplayer", + "path": "skills\\game-development\\multiplayer", "category": "game-development", "name": "multiplayer", "description": "Multiplayer game development principles. Architecture, networking, synchronization.", @@ -5455,7 +5572,7 @@ }, { "id": "n8n-code-python", - "path": "skills/n8n-code-python", + "path": "skills\\n8n-code-python", "category": "uncategorized", "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.", @@ -5464,7 +5581,7 @@ }, { "id": "n8n-mcp-tools-expert", - "path": "skills/n8n-mcp-tools-expert", + "path": "skills\\n8n-mcp-tools-expert", "category": "uncategorized", "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 sele...", @@ -5473,7 +5590,7 @@ }, { "id": "n8n-node-configuration", - "path": "skills/n8n-node-configuration", + "path": "skills\\n8n-node-configuration", "category": "uncategorized", "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 commo...", @@ -5482,7 +5599,7 @@ }, { "id": "nanobanana-ppt-skills", - "path": "skills/nanobanana-ppt-skills", + "path": "skills\\nanobanana-ppt-skills", "category": "uncategorized", "name": "nanobanana-ppt-skills", "description": "AI-powered PPT generation with document analysis and styled images", @@ -5491,7 +5608,7 @@ }, { "id": "neon-postgres", - "path": "skills/neon-postgres", + "path": "skills\\neon-postgres", "category": "uncategorized", "name": "neon-postgres", "description": "Expert patterns for Neon serverless Postgres, branching, connection pooling, and Prisma/Drizzle integration Use when: neon database, serverless postgres, database branching, neon postgres, postgres...", @@ -5500,7 +5617,7 @@ }, { "id": "nerdzao-elite", - "path": "skills/nerdzao-elite", + "path": "skills\\nerdzao-elite", "category": "uncategorized", "name": "nerdzao-elite", "description": "Senior Elite Software Engineer (15+) and Senior Product Designer. Full workflow with planning, architecture, TDD, clean code, and pixel-perfect UX validation.", @@ -5509,7 +5626,7 @@ }, { "id": "nerdzao-elite-gemini-high", - "path": "skills/nerdzao-elite-gemini-high", + "path": "skills\\nerdzao-elite-gemini-high", "category": "uncategorized", "name": "nerdzao-elite-gemini-high", "description": "Modo Elite Coder + UX Pixel-Perfect otimizado especificamente para Gemini 3.1 Pro High. Workflow completo com foco em qualidade m\u00e1xima e efici\u00eancia de tokens.", @@ -5518,34 +5635,34 @@ }, { "id": "nestjs-expert", - "path": "skills/nestjs-expert", + "path": "skills\\nestjs-expert", "category": "uncategorized", "name": "nestjs-expert", "description": "Nest.js framework expert specializing in module architecture, dependency injection, middleware, guards, interceptors, testing with Jest/Supertest, TypeORM/Mongoose integration, and Passport.js auth...", "risk": "unknown", "source": "community" }, - { - "id": "network-engineer", - "path": "skills/network-engineer", - "category": "uncategorized", - "name": "Network Engineer", - "description": "- Working on network engineer tasks or workflows - Needing guidance, best practices, or checklists for network engineer", - "risk": "unknown", - "source": "unknown" - }, { "id": "network-101", - "path": "skills/network-101", + "path": "skills\\network-101", "category": "uncategorized", "name": "network-101", "description": "This skill should be used when the user asks to \"set up a web server\", \"configure HTTP or HTTPS\", \"perform SNMP enumeration\", \"configure SMB shares\", \"test network services\", or ne...", "risk": "unknown", "source": "community" }, + { + "id": "network-engineer", + "path": "skills\\network-engineer", + "category": "uncategorized", + "name": "network-engineer", + "description": "Expert network engineer specializing in modern cloud networking,\nsecurity architectures, and performance optimization. Masters multi-cloud\nconnectivity, service mesh, zero-trust networking, SSL/TLS, global load\nbalancing, and advanced troubleshooting. Handles CDN optimization, network\nautomation, and compliance. Use PROACTIVELY for network design, connectivity\nissues, or performance optimization.\n", + "risk": "unknown", + "source": "community" + }, { "id": "nextjs-app-router-patterns", - "path": "skills/nextjs-app-router-patterns", + "path": "skills\\nextjs-app-router-patterns", "category": "uncategorized", "name": "nextjs-app-router-patterns", "description": "Master Next.js 14+ App Router with Server Components, streaming, parallel routes, and advanced data fetching. Use when building Next.js applications, implementing SSR/SSG, or optimizing React Serve...", @@ -5554,7 +5671,7 @@ }, { "id": "nextjs-best-practices", - "path": "skills/nextjs-best-practices", + "path": "skills\\nextjs-best-practices", "category": "uncategorized", "name": "nextjs-best-practices", "description": "Next.js App Router principles. Server Components, data fetching, routing patterns.", @@ -5563,7 +5680,7 @@ }, { "id": "nextjs-supabase-auth", - "path": "skills/nextjs-supabase-auth", + "path": "skills\\nextjs-supabase-auth", "category": "uncategorized", "name": "nextjs-supabase-auth", "description": "Expert integration of Supabase Auth with Next.js App Router Use when: supabase auth next, authentication next.js, login supabase, auth middleware, protected route.", @@ -5572,7 +5689,7 @@ }, { "id": "nft-standards", - "path": "skills/nft-standards", + "path": "skills\\nft-standards", "category": "uncategorized", "name": "nft-standards", "description": "Implement NFT standards (ERC-721, ERC-1155) with proper metadata handling, minting strategies, and marketplace integration. Use when creating NFT contracts, building NFT marketplaces, or implementi...", @@ -5581,7 +5698,7 @@ }, { "id": "nodejs-backend-patterns", - "path": "skills/nodejs-backend-patterns", + "path": "skills\\nodejs-backend-patterns", "category": "uncategorized", "name": "nodejs-backend-patterns", "description": "Build production-ready Node.js backend services with Express/Fastify, implementing middleware patterns, error handling, authentication, database integration, and API design best practices. Use when...", @@ -5590,7 +5707,7 @@ }, { "id": "nodejs-best-practices", - "path": "skills/nodejs-best-practices", + "path": "skills\\nodejs-best-practices", "category": "uncategorized", "name": "nodejs-best-practices", "description": "Node.js development principles and decision-making. Framework selection, async patterns, security, and architecture. Teaches thinking, not copying.", @@ -5599,7 +5716,7 @@ }, { "id": "nosql-expert", - "path": "skills/nosql-expert", + "path": "skills\\nosql-expert", "category": "uncategorized", "name": "nosql-expert", "description": "Expert guidance for distributed NoSQL databases (Cassandra, DynamoDB). Focuses on mental models, query-first modeling, single-table design, and avoiding hot partitions in high-scale systems.", @@ -5608,7 +5725,7 @@ }, { "id": "notebooklm", - "path": "skills/notebooklm", + "path": "skills\\notebooklm", "category": "uncategorized", "name": "notebooklm", "description": "Use this skill to query your Google NotebookLM notebooks directly from Claude Code for source-grounded, citation-backed answers from Gemini. Browser automation, library management, persistent auth....", @@ -5617,7 +5734,7 @@ }, { "id": "notion-automation", - "path": "skills/notion-automation", + "path": "skills\\notion-automation", "category": "uncategorized", "name": "notion-automation", "description": "Automate Notion tasks via Rube MCP (Composio): pages, databases, blocks, comments, users. Always search tools first for current schemas.", @@ -5626,7 +5743,7 @@ }, { "id": "notion-template-business", - "path": "skills/notion-template-business", + "path": "skills\\notion-template-business", "category": "uncategorized", "name": "notion-template-business", "description": "Expert in building and selling Notion templates as a business - not just making templates, but building a sustainable digital product business. Covers template design, pricing, marketplaces, market...", @@ -5635,7 +5752,7 @@ }, { "id": "nx-workspace-patterns", - "path": "skills/nx-workspace-patterns", + "path": "skills\\nx-workspace-patterns", "category": "uncategorized", "name": "nx-workspace-patterns", "description": "Configure and optimize Nx monorepo workspaces. Use when setting up Nx, configuring project boundaries, optimizing build caching, or implementing affected commands.", @@ -5644,16 +5761,16 @@ }, { "id": "observability-engineer", - "path": "skills/observability-engineer", + "path": "skills\\observability-engineer", "category": "uncategorized", - "name": "Observability Engineer", - "description": "You are an observability engineer specializing in production-grade monitoring, logging, tracing, and reliability systems for enterprise-scale applications.", + "name": "observability-engineer", + "description": "Build production-ready monitoring, logging, and tracing systems.\nImplements comprehensive observability strategies, SLI/SLO management, and\nincident response workflows. Use PROACTIVELY for monitoring infrastructure,\nperformance optimization, or production reliability.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "observability-monitoring-monitor-setup", - "path": "skills/observability-monitoring-monitor-setup", + "path": "skills\\observability-monitoring-monitor-setup", "category": "uncategorized", "name": "observability-monitoring-monitor-setup", "description": "You are a monitoring and observability expert specializing in implementing comprehensive monitoring solutions. Set up metrics collection, distributed tracing, log aggregation, and create insightful da", @@ -5662,7 +5779,7 @@ }, { "id": "observability-monitoring-slo-implement", - "path": "skills/observability-monitoring-slo-implement", + "path": "skills\\observability-monitoring-slo-implement", "category": "uncategorized", "name": "observability-monitoring-slo-implement", "description": "You are an SLO (Service Level Objective) expert specializing in implementing reliability standards and error budget-based practices. Design SLO frameworks, define SLIs, and build monitoring that ba...", @@ -5671,7 +5788,7 @@ }, { "id": "observe-whatsapp", - "path": "skills/observe-whatsapp", + "path": "skills\\observe-whatsapp", "category": "uncategorized", "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 f...", @@ -5680,7 +5797,7 @@ }, { "id": "obsidian-clipper-template-creator", - "path": "skills/obsidian-clipper-template-creator", + "path": "skills\\obsidian-clipper-template-creator", "category": "uncategorized", "name": "obsidian-clipper-template-creator", "description": "Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.", @@ -5689,7 +5806,7 @@ }, { "id": "office-productivity", - "path": "skills/office-productivity", + "path": "skills\\office-productivity", "category": "uncategorized", "name": "office-productivity", "description": "Office productivity workflow covering document creation, spreadsheet automation, presentation generation, and integration with LibreOffice and Microsoft Office formats.", @@ -5698,7 +5815,7 @@ }, { "id": "on-call-handoff-patterns", - "path": "skills/on-call-handoff-patterns", + "path": "skills\\on-call-handoff-patterns", "category": "uncategorized", "name": "on-call-handoff-patterns", "description": "Master on-call shift handoffs with context transfer, escalation procedures, and documentation. Use when transitioning on-call responsibilities, documenting shift summaries, or improving on-call pro...", @@ -5707,7 +5824,7 @@ }, { "id": "onboarding-cro", - "path": "skills/onboarding-cro", + "path": "skills\\onboarding-cro", "category": "uncategorized", "name": "onboarding-cro", "description": "When the user wants to optimize post-signup onboarding, user activation, first-run experience, or time-to-value. Also use when the user mentions \"onboarding flow,\" \"activation rate,\" \"u...", @@ -5716,7 +5833,7 @@ }, { "id": "one-drive-automation", - "path": "skills/one-drive-automation", + "path": "skills\\one-drive-automation", "category": "uncategorized", "name": "one-drive-automation", "description": "Automate OneDrive file management, search, uploads, downloads, sharing, permissions, and folder operations via Rube MCP (Composio). Always search tools first for current schemas.", @@ -5725,7 +5842,7 @@ }, { "id": "openapi-spec-generation", - "path": "skills/openapi-spec-generation", + "path": "skills\\openapi-spec-generation", "category": "uncategorized", "name": "openapi-spec-generation", "description": "Generate and maintain OpenAPI 3.1 specifications from code, design-first specs, and validation patterns. Use when creating API documentation, generating SDKs, or ensuring API contract compliance.", @@ -5734,7 +5851,7 @@ }, { "id": "os-scripting", - "path": "skills/os-scripting", + "path": "skills\\os-scripting", "category": "uncategorized", "name": "os-scripting", "description": "Operating system and shell scripting troubleshooting workflow for Linux, macOS, and Windows. Covers bash scripting, system administration, debugging, and automation.", @@ -5743,7 +5860,7 @@ }, { "id": "oss-hunter", - "path": "skills/oss-hunter", + "path": "skills\\oss-hunter", "category": "uncategorized", "name": "oss-hunter", "description": "Automatically hunt for high-impact OSS contribution opportunities in trending repositories.", @@ -5752,7 +5869,7 @@ }, { "id": "outlook-automation", - "path": "skills/outlook-automation", + "path": "skills\\outlook-automation", "category": "uncategorized", "name": "outlook-automation", "description": "Automate Outlook tasks via Rube MCP (Composio): emails, calendar, contacts, folders, attachments. Always search tools first for current schemas.", @@ -5761,7 +5878,7 @@ }, { "id": "outlook-calendar-automation", - "path": "skills/outlook-calendar-automation", + "path": "skills\\outlook-calendar-automation", "category": "uncategorized", "name": "outlook-calendar-automation", "description": "Automate Outlook Calendar tasks via Rube MCP (Composio): create events, manage attendees, find meeting times, and handle invitations. Always search tools first for current schemas.", @@ -5770,16 +5887,16 @@ }, { "id": "page-cro", - "path": "skills/page-cro", + "path": "skills\\page-cro", "category": "uncategorized", - "name": "Page Cro", - "description": "You are an expert in **page-level conversion optimization**. Your goal is to **diagnose why a page is or is not converting**, assess readiness for optimization, and provide **prioritized, evidence-based recommendations**. You do **not** guarantee con", + "name": "page-cro", + "description": "Analyze and optimize individual pages for conversion performance. Use when the user wants to improve conversion rates, diagnose why a page is underperforming, or increase the effectiveness of marketing pages (homepage, landing pages, pricing, feature pages, or blog posts). This skill focuses on diagnosis, prioritization, and testable recommendations\u2014 not blind optimization.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "pagerduty-automation", - "path": "skills/pagerduty-automation", + "path": "skills\\pagerduty-automation", "category": "uncategorized", "name": "pagerduty-automation", "description": "Automate PagerDuty tasks via Rube MCP (Composio): manage incidents, services, schedules, escalation policies, and on-call rotations. Always search tools first for current schemas.", @@ -5788,7 +5905,7 @@ }, { "id": "paid-ads", - "path": "skills/paid-ads", + "path": "skills\\paid-ads", "category": "uncategorized", "name": "paid-ads", "description": "When the user wants help with paid advertising campaigns on Google Ads, Meta (Facebook/Instagram), LinkedIn, Twitter/X, or other ad platforms. Also use when the user mentions 'PPC,' 'paid media,' '...", @@ -5797,7 +5914,7 @@ }, { "id": "parallel-agents", - "path": "skills/parallel-agents", + "path": "skills\\parallel-agents", "category": "uncategorized", "name": "parallel-agents", "description": "Multi-agent orchestration patterns. Use when multiple independent tasks can run with different domain expertise or when comprehensive analysis requires multiple perspectives.", @@ -5806,16 +5923,16 @@ }, { "id": "payment-integration", - "path": "skills/payment-integration", + "path": "skills\\payment-integration", "category": "uncategorized", - "name": "Payment Integration", - "description": "- Working on payment integration tasks or workflows - Needing guidance, best practices, or checklists for payment integration", + "name": "payment-integration", + "description": "Integrate Stripe, PayPal, and payment processors. Handles checkout\nflows, subscriptions, webhooks, and PCI compliance. Use PROACTIVELY when\nimplementing payments, billing, or subscription features.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "paypal-integration", - "path": "skills/paypal-integration", + "path": "skills\\paypal-integration", "category": "uncategorized", "name": "paypal-integration", "description": "Integrate PayPal payment processing with support for express checkout, subscriptions, and refund management. Use when implementing PayPal payments, processing online transactions, or building e-com...", @@ -5824,7 +5941,7 @@ }, { "id": "paywall-upgrade-cro", - "path": "skills/paywall-upgrade-cro", + "path": "skills\\paywall-upgrade-cro", "category": "uncategorized", "name": "paywall-upgrade-cro", "description": "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,\" \"upgrade screen,\" \"upgrade modal,...", @@ -5833,7 +5950,7 @@ }, { "id": "pc-games", - "path": "skills/game-development/pc-games", + "path": "skills\\game-development\\pc-games", "category": "game-development", "name": "pc-games", "description": "PC and console game development principles. Engine selection, platform features, optimization strategies.", @@ -5842,7 +5959,7 @@ }, { "id": "pci-compliance", - "path": "skills/pci-compliance", + "path": "skills\\pci-compliance", "category": "uncategorized", "name": "pci-compliance", "description": "Implement PCI DSS compliance requirements for secure handling of payment card data and payment systems. Use when securing payment processing, achieving PCI compliance, or implementing payment card ...", @@ -5851,7 +5968,7 @@ }, { "id": "pdf-official", - "path": "skills/pdf-official", + "path": "skills\\pdf-official", "category": "uncategorized", "name": "pdf-official", "description": "Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms. When Claude needs to fill in a PDF form or programmaticall...", @@ -5860,7 +5977,7 @@ }, { "id": "pentest-checklist", - "path": "skills/pentest-checklist", + "path": "skills\\pentest-checklist", "category": "uncategorized", "name": "pentest-checklist", "description": "This skill should be used when the user asks to \"plan a penetration test\", \"create a security assessment checklist\", \"prepare for penetration testing\", \"define pentest scope\", \"foll...", @@ -5869,7 +5986,7 @@ }, { "id": "pentest-commands", - "path": "skills/pentest-commands", + "path": "skills\\pentest-commands", "category": "uncategorized", "name": "pentest-commands", "description": "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\", \"scan web vulnerabilities ...", @@ -5878,7 +5995,7 @@ }, { "id": "performance-engineer", - "path": "skills/performance-engineer", + "path": "skills\\performance-engineer", "category": "uncategorized", "name": "performance-engineer", "description": "Expert performance engineer specializing in modern observability, application optimization, and scalable system performance. Masters OpenTelemetry, distributed tracing, load testing, multi-tier caching, Core Web Vitals, and performance monitoring. Handles end-to-end optimization, real user monitoring, and scalability patterns. Use PROACTIVELY for performance optimization, observability, or scalability challenges.", @@ -5887,7 +6004,7 @@ }, { "id": "performance-profiling", - "path": "skills/performance-profiling", + "path": "skills\\performance-profiling", "category": "uncategorized", "name": "performance-profiling", "description": "Performance profiling principles. Measurement, analysis, and optimization techniques.", @@ -5896,7 +6013,7 @@ }, { "id": "performance-testing-review-ai-review", - "path": "skills/performance-testing-review-ai-review", + "path": "skills\\performance-testing-review-ai-review", "category": "uncategorized", "name": "performance-testing-review-ai-review", "description": "You are an expert AI-powered code review specialist combining automated static analysis, intelligent pattern recognition, and modern DevOps practices. Leverage AI tools (GitHub Copilot, Qodo, GPT-5, C", @@ -5905,7 +6022,7 @@ }, { "id": "performance-testing-review-multi-agent-review", - "path": "skills/performance-testing-review-multi-agent-review", + "path": "skills\\performance-testing-review-multi-agent-review", "category": "uncategorized", "name": "performance-testing-review-multi-agent-review", "description": "Use when working with performance testing review multi agent review", @@ -5914,7 +6031,7 @@ }, { "id": "personal-tool-builder", - "path": "skills/personal-tool-builder", + "path": "skills\\personal-tool-builder", "category": "uncategorized", "name": "personal-tool-builder", "description": "Expert in building custom tools that solve your own problems first. The best products often start as personal tools - scratch your own itch, build for yourself, then discover others have the same i...", @@ -5923,16 +6040,16 @@ }, { "id": "php-pro", - "path": "skills/php-pro", + "path": "skills\\php-pro", "category": "uncategorized", - "name": "Php Pro", - "description": "- Working on php pro tasks or workflows - Needing guidance, best practices, or checklists for php pro", + "name": "php-pro", + "description": "Write idiomatic PHP code with generators, iterators, SPL data\nstructures, and modern OOP features. Use PROACTIVELY for high-performance PHP\napplications.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "pipedrive-automation", - "path": "skills/pipedrive-automation", + "path": "skills\\pipedrive-automation", "category": "uncategorized", "name": "pipedrive-automation", "description": "Automate Pipedrive CRM operations including deals, contacts, organizations, activities, notes, and pipeline management via Rube MCP (Composio). Always search tools first for current schemas.", @@ -5941,7 +6058,7 @@ }, { "id": "plaid-fintech", - "path": "skills/plaid-fintech", + "path": "skills\\plaid-fintech", "category": "uncategorized", "name": "plaid-fintech", "description": "Expert patterns for Plaid API integration including Link token flows, transactions sync, identity verification, Auth for ACH, balance checks, webhook handling, and fintech compliance best practices...", @@ -5950,7 +6067,7 @@ }, { "id": "plan-writing", - "path": "skills/plan-writing", + "path": "skills\\plan-writing", "category": "uncategorized", "name": "plan-writing", "description": "Structured task planning with clear breakdowns, dependencies, and verification criteria. Use when implementing features, refactoring, or any multi-step work.", @@ -5959,7 +6076,7 @@ }, { "id": "planning-with-files", - "path": "skills/planning-with-files", + "path": "skills\\planning-with-files", "category": "uncategorized", "name": "planning-with-files", "description": "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, research projects, or any task requirin...", @@ -5968,7 +6085,7 @@ }, { "id": "playwright-skill", - "path": "skills/playwright-skill", + "path": "skills\\playwright-skill", "category": "uncategorized", "name": "playwright-skill", "description": "Complete browser automation with Playwright. Auto-detects dev servers, writes clean test scripts to /tmp. Test pages, fill forms, take screenshots, check responsive design, validate UX, test login ...", @@ -5977,7 +6094,7 @@ }, { "id": "podcast-generation", - "path": "skills/podcast-generation", + "path": "skills\\podcast-generation", "category": "uncategorized", "name": "podcast-generation", "description": "Generate AI-powered podcast-style audio narratives using Azure OpenAI's GPT Realtime Mini model via WebSocket. Use when building text-to-speech features, audio narrative generation, podcast creatio...", @@ -5986,7 +6103,7 @@ }, { "id": "popup-cro", - "path": "skills/popup-cro", + "path": "skills\\popup-cro", "category": "uncategorized", "name": "popup-cro", "description": "Create and optimize popups, modals, overlays, slide-ins, and banners to increase conversions without harming user experience or brand trust.", @@ -5995,16 +6112,16 @@ }, { "id": "posix-shell-pro", - "path": "skills/posix-shell-pro", + "path": "skills\\posix-shell-pro", "category": "uncategorized", - "name": "Posix Shell Pro", - "description": "- Working on posix shell pro tasks or workflows - Needing guidance, best practices, or checklists for posix shell pro", + "name": "posix-shell-pro", + "description": "Expert in strict POSIX sh scripting for maximum portability across\nUnix-like systems. Specializes in shell scripts that run on any\nPOSIX-compliant shell (dash, ash, sh, bash --posix).\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "postgres-best-practices", - "path": "skills/postgres-best-practices", + "path": "skills\\postgres-best-practices", "category": "uncategorized", "name": "postgres-best-practices", "description": "Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.", @@ -6013,7 +6130,7 @@ }, { "id": "postgresql", - "path": "skills/postgresql", + "path": "skills\\postgresql", "category": "uncategorized", "name": "postgresql", "description": "Design a PostgreSQL-specific schema. Covers best-practices, data types, indexing, constraints, performance patterns, and advanced features", @@ -6022,7 +6139,7 @@ }, { "id": "postgresql-optimization", - "path": "skills/postgresql-optimization", + "path": "skills\\postgresql-optimization", "category": "uncategorized", "name": "postgresql-optimization", "description": "PostgreSQL database optimization workflow for query tuning, indexing strategies, performance analysis, and production database management.", @@ -6031,7 +6148,7 @@ }, { "id": "posthog-automation", - "path": "skills/posthog-automation", + "path": "skills\\posthog-automation", "category": "uncategorized", "name": "posthog-automation", "description": "Automate PostHog tasks via Rube MCP (Composio): events, feature flags, projects, user profiles, annotations. Always search tools first for current schemas.", @@ -6040,7 +6157,7 @@ }, { "id": "postmark-automation", - "path": "skills/postmark-automation", + "path": "skills\\postmark-automation", "category": "uncategorized", "name": "postmark-automation", "description": "Automate Postmark email delivery tasks via Rube MCP (Composio): send templated emails, manage templates, monitor delivery stats and bounces. Always search tools first for current schemas.", @@ -6049,7 +6166,7 @@ }, { "id": "postmortem-writing", - "path": "skills/postmortem-writing", + "path": "skills\\postmortem-writing", "category": "uncategorized", "name": "postmortem-writing", "description": "Write effective blameless postmortems with root cause analysis, timelines, and action items. Use when conducting incident reviews, writing postmortem documents, or improving incident response proce...", @@ -6058,7 +6175,7 @@ }, { "id": "powershell-windows", - "path": "skills/powershell-windows", + "path": "skills\\powershell-windows", "category": "uncategorized", "name": "powershell-windows", "description": "PowerShell Windows patterns. Critical pitfalls, operator syntax, error handling.", @@ -6067,7 +6184,7 @@ }, { "id": "pptx-official", - "path": "skills/pptx-official", + "path": "skills\\pptx-official", "category": "uncategorized", "name": "pptx-official", "description": "Presentation creation, editing, and analysis. When Claude needs to work with presentations (.pptx files) for: (1) Creating new presentations, (2) Modifying or editing content, (3) Working with layo...", @@ -6076,7 +6193,7 @@ }, { "id": "pricing-strategy", - "path": "skills/pricing-strategy", + "path": "skills\\pricing-strategy", "category": "uncategorized", "name": "pricing-strategy", "description": "Design pricing, packaging, and monetization strategies based on value, customer willingness to pay, and growth objectives.", @@ -6085,7 +6202,7 @@ }, { "id": "prisma-expert", - "path": "skills/prisma-expert", + "path": "skills\\prisma-expert", "category": "uncategorized", "name": "prisma-expert", "description": "Prisma ORM expert for schema design, migrations, query optimization, relations modeling, and database operations. Use PROACTIVELY for Prisma schema issues, migration problems, query performance, re...", @@ -6094,7 +6211,7 @@ }, { "id": "privilege-escalation-methods", - "path": "skills/privilege-escalation-methods", + "path": "skills\\privilege-escalation-methods", "category": "uncategorized", "name": "privilege-escalation-methods", "description": "This skill should be used when the user asks to \"escalate privileges\", \"get root access\", \"become administrator\", \"privesc techniques\", \"abuse sudo\", \"exploit SUID binaries\", \"K...", @@ -6103,7 +6220,7 @@ }, { "id": "product-manager-toolkit", - "path": "skills/product-manager-toolkit", + "path": "skills\\product-manager-toolkit", "category": "uncategorized", "name": "product-manager-toolkit", "description": "Comprehensive toolkit for product managers including RICE prioritization, customer interview analysis, PRD templates, discovery frameworks, and go-to-market strategies. Use for feature prioritizati...", @@ -6112,7 +6229,7 @@ }, { "id": "production-code-audit", - "path": "skills/production-code-audit", + "path": "skills\\production-code-audit", "category": "uncategorized", "name": "production-code-audit", "description": "Autonomously deep-scan entire codebase line-by-line, understand architecture and patterns, then systematically transform it to production-grade, corporate-level professional quality with optimizations", @@ -6120,17 +6237,26 @@ "source": "community" }, { - "id": "programmatic-seo", - "path": "skills/programmatic-seo", + "id": "production-scheduling", + "path": "skills\\production-scheduling", "category": "uncategorized", - "name": "Programmatic Seo", - "description": "---", + "name": "production-scheduling", + "description": "Codified expertise for production scheduling, job sequencing, line balancing, changeover optimisation, and bottleneck resolution in discrete and batch manufacturing. Informed by production schedulers with 15+ years experience. Includes TOC/drum-buffer-rope, SMED, OEE analysis, disruption response frameworks, and ERP/MES interaction patterns. Use when scheduling production, resolving bottlenecks, optimising changeovers, responding to disruptions, or balancing manufacturing lines.\n", + "risk": "safe", + "source": "https://github.com/ai-evos/agent-skills" + }, + { + "id": "programmatic-seo", + "path": "skills\\programmatic-seo", + "category": "uncategorized", + "name": "programmatic-seo", + "description": "Design and evaluate programmatic SEO strategies for creating SEO-driven pages at scale using templates and structured data. Use when the user mentions programmatic SEO, pages at scale, template pages, directory pages, location pages, comparison pages, integration pages, or keyword-pattern page generation. This skill focuses on feasibility, strategy, and page system design\u2014not execution unless explicitly requested.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "projection-patterns", - "path": "skills/projection-patterns", + "path": "skills\\projection-patterns", "category": "uncategorized", "name": "projection-patterns", "description": "Build read models and projections from event streams. Use when implementing CQRS read sides, building materialized views, or optimizing query performance in event-sourced systems.", @@ -6139,7 +6265,7 @@ }, { "id": "prometheus-configuration", - "path": "skills/prometheus-configuration", + "path": "skills\\prometheus-configuration", "category": "uncategorized", "name": "prometheus-configuration", "description": "Set up Prometheus for comprehensive metric collection, storage, and monitoring of infrastructure and applications. Use when implementing metrics collection, setting up monitoring infrastructure, or...", @@ -6148,7 +6274,7 @@ }, { "id": "prompt-caching", - "path": "skills/prompt-caching", + "path": "skills\\prompt-caching", "category": "uncategorized", "name": "prompt-caching", "description": "Caching strategies for LLM prompts including Anthropic prompt caching, response caching, and CAG (Cache Augmented Generation) Use when: prompt caching, cache prompt, response cache, cag, cache augm...", @@ -6157,7 +6283,7 @@ }, { "id": "prompt-engineer", - "path": "skills/prompt-engineer", + "path": "skills\\prompt-engineer", "category": "uncategorized", "name": "prompt-engineer", "description": "Transforms user prompts into optimized prompts using frameworks (RTF, RISEN, Chain of Thought, RODES, Chain of Density, RACE, RISE, STAR, SOAP, CLEAR, GROW)", @@ -6166,7 +6292,7 @@ }, { "id": "prompt-engineering", - "path": "skills/prompt-engineering", + "path": "skills\\prompt-engineering", "category": "uncategorized", "name": "prompt-engineering", "description": "Expert guide on prompt engineering patterns, best practices, and optimization techniques. Use when user wants to improve prompts, learn prompting strategies, or debug agent behavior.", @@ -6175,7 +6301,7 @@ }, { "id": "prompt-engineering-patterns", - "path": "skills/prompt-engineering-patterns", + "path": "skills\\prompt-engineering-patterns", "category": "uncategorized", "name": "prompt-engineering-patterns", "description": "Master advanced prompt engineering techniques to maximize LLM performance, reliability, and controllability in production. Use when optimizing prompts, improving LLM outputs, or designing productio...", @@ -6184,7 +6310,7 @@ }, { "id": "prompt-library", - "path": "skills/prompt-library", + "path": "skills\\prompt-library", "category": "uncategorized", "name": "prompt-library", "description": "Curated collection of high-quality prompts for various use cases. Includes role-based prompts, task-specific templates, and prompt refinement techniques. Use when user needs prompt templates, role-...", @@ -6193,7 +6319,7 @@ }, { "id": "protocol-reverse-engineering", - "path": "skills/protocol-reverse-engineering", + "path": "skills\\protocol-reverse-engineering", "category": "uncategorized", "name": "protocol-reverse-engineering", "description": "Master network protocol reverse engineering including packet analysis, protocol dissection, and custom protocol documentation. Use when analyzing network traffic, understanding proprietary protocol...", @@ -6202,7 +6328,7 @@ }, { "id": "pydantic-models-py", - "path": "skills/pydantic-models-py", + "path": "skills\\pydantic-models-py", "category": "uncategorized", "name": "pydantic-models-py", "description": "Create Pydantic models following the multi-model pattern with Base, Create, Update, Response, and InDB variants. Use when defining API request/response schemas, database models, or data validation ...", @@ -6211,25 +6337,16 @@ }, { "id": "pypict-skill", - "path": "skills/pypict-skill", + "path": "skills\\pypict-skill", "category": "uncategorized", "name": "pypict-skill", "description": "Pairwise test generation", "risk": "safe", "source": "https://github.com/omkamal/pypict-claude-skill/blob/main/SKILL.md" }, - { - "id": "python-pro", - "path": "skills/python-pro", - "category": "uncategorized", - "name": "Python Pro", - "description": "You are a Python expert specializing in modern Python 3.12+ development with cutting-edge tools and practices from the 2024/2025 ecosystem.", - "risk": "unknown", - "source": "unknown" - }, { "id": "python-development-python-scaffold", - "path": "skills/python-development-python-scaffold", + "path": "skills\\python-development-python-scaffold", "category": "uncategorized", "name": "python-development-python-scaffold", "description": "You are a Python project architecture expert specializing in scaffolding production-ready Python applications. Generate complete project structures with modern tooling (uv, FastAPI, Django), type hint", @@ -6238,7 +6355,7 @@ }, { "id": "python-fastapi-development", - "path": "skills/python-fastapi-development", + "path": "skills\\python-fastapi-development", "category": "uncategorized", "name": "python-fastapi-development", "description": "Python FastAPI backend development with async patterns, SQLAlchemy, Pydantic, authentication, and production API patterns.", @@ -6247,7 +6364,7 @@ }, { "id": "python-packaging", - "path": "skills/python-packaging", + "path": "skills\\python-packaging", "category": "uncategorized", "name": "python-packaging", "description": "Create distributable Python packages with proper project structure, setup.py/pyproject.toml, and publishing to PyPI. Use when packaging Python libraries, creating CLI tools, or distributing Python ...", @@ -6256,7 +6373,7 @@ }, { "id": "python-patterns", - "path": "skills/python-patterns", + "path": "skills\\python-patterns", "category": "uncategorized", "name": "python-patterns", "description": "Python development principles and decision-making. Framework selection, async patterns, type hints, project structure. Teaches thinking, not copying.", @@ -6265,16 +6382,25 @@ }, { "id": "python-performance-optimization", - "path": "skills/python-performance-optimization", + "path": "skills\\python-performance-optimization", "category": "uncategorized", "name": "python-performance-optimization", "description": "Profile and optimize Python code using cProfile, memory profilers, and performance best practices. Use when debugging slow Python code, optimizing bottlenecks, or improving application performance.", "risk": "unknown", "source": "community" }, + { + "id": "python-pro", + "path": "skills\\python-pro", + "category": "uncategorized", + "name": "python-pro", + "description": "Master Python 3.12+ with modern features, async programming,\nperformance optimization, and production-ready practices. Expert in the latest\nPython ecosystem including uv, ruff, pydantic, and FastAPI. Use PROACTIVELY\nfor Python development, optimization, or advanced Python patterns.\n", + "risk": "unknown", + "source": "community" + }, { "id": "python-testing-patterns", - "path": "skills/python-testing-patterns", + "path": "skills\\python-testing-patterns", "category": "uncategorized", "name": "python-testing-patterns", "description": "Implement comprehensive testing strategies with pytest, fixtures, mocking, and test-driven development. Use when writing Python tests, setting up test suites, or implementing testing best practices.", @@ -6282,17 +6408,26 @@ "source": "community" }, { - "id": "quant-analyst", - "path": "skills/quant-analyst", + "id": "quality-nonconformance", + "path": "skills\\quality-nonconformance", "category": "uncategorized", - "name": "Quant Analyst", - "description": "- Working on quant analyst tasks or workflows - Needing guidance, best practices, or checklists for quant analyst", + "name": "quality-nonconformance", + "description": "Codified expertise for quality control, non-conformance investigation, root cause analysis, corrective action, and supplier quality management in regulated manufacturing. Informed by quality engineers with 15+ years experience across FDA, IATF 16949, and AS9100 environments. Includes NCR lifecycle management, CAPA systems, SPC interpretation, and audit methodology. Use when investigating non-conformances, performing root cause analysis, managing CAPAs, interpreting SPC data, or handling supplier quality issues.\n", + "risk": "safe", + "source": "https://github.com/ai-evos/agent-skills" + }, + { + "id": "quant-analyst", + "path": "skills\\quant-analyst", + "category": "uncategorized", + "name": "quant-analyst", + "description": "Build financial models, backtest trading strategies, and analyze\nmarket data. Implements risk metrics, portfolio optimization, and statistical\narbitrage. Use PROACTIVELY for quantitative finance, trading algorithms, or\nrisk analysis.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "radix-ui-design-system", - "path": "skills/radix-ui-design-system", + "path": "skills\\radix-ui-design-system", "category": "uncategorized", "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.", @@ -6301,7 +6436,7 @@ }, { "id": "rag-engineer", - "path": "skills/rag-engineer", + "path": "skills\\rag-engineer", "category": "uncategorized", "name": "rag-engineer", "description": "Expert in building Retrieval-Augmented Generation systems. Masters embedding models, vector databases, chunking strategies, and retrieval optimization for LLM applications. Use when: building RAG, ...", @@ -6310,7 +6445,7 @@ }, { "id": "rag-implementation", - "path": "skills/rag-implementation", + "path": "skills\\rag-implementation", "category": "uncategorized", "name": "rag-implementation", "description": "RAG (Retrieval-Augmented Generation) implementation workflow covering embedding selection, vector database setup, chunking strategies, and retrieval optimization.", @@ -6319,7 +6454,7 @@ }, { "id": "react-best-practices", - "path": "skills/react-best-practices", + "path": "skills\\react-best-practices", "category": "uncategorized", "name": "react-best-practices", "description": "React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance pat...", @@ -6328,7 +6463,7 @@ }, { "id": "react-flow-architect", - "path": "skills/react-flow-architect", + "path": "skills\\react-flow-architect", "category": "uncategorized", "name": "react-flow-architect", "description": "Expert ReactFlow architect for building interactive graph applications with hierarchical node-edge systems, performance optimization, and auto-layout integration. Use when Claude needs to create or...", @@ -6337,7 +6472,7 @@ }, { "id": "react-flow-node-ts", - "path": "skills/react-flow-node-ts", + "path": "skills\\react-flow-node-ts", "category": "uncategorized", "name": "react-flow-node-ts", "description": "Create React Flow node components with TypeScript types, handles, and Zustand integration. Use when building custom nodes for React Flow canvas, creating visual workflow editors, or implementing no...", @@ -6346,7 +6481,7 @@ }, { "id": "react-modernization", - "path": "skills/react-modernization", + "path": "skills\\react-modernization", "category": "uncategorized", "name": "react-modernization", "description": "Upgrade React applications to latest versions, migrate from class components to hooks, and adopt concurrent features. Use when modernizing React codebases, migrating to React Hooks, or upgrading to...", @@ -6355,7 +6490,7 @@ }, { "id": "react-native-architecture", - "path": "skills/react-native-architecture", + "path": "skills\\react-native-architecture", "category": "uncategorized", "name": "react-native-architecture", "description": "Build production React Native apps with Expo, navigation, native modules, offline sync, and cross-platform patterns. Use when developing mobile apps, implementing native integrations, or architecti...", @@ -6364,7 +6499,7 @@ }, { "id": "react-nextjs-development", - "path": "skills/react-nextjs-development", + "path": "skills\\react-nextjs-development", "category": "uncategorized", "name": "react-nextjs-development", "description": "React and Next.js 14+ application development with App Router, Server Components, TypeScript, Tailwind CSS, and modern frontend patterns.", @@ -6373,7 +6508,7 @@ }, { "id": "react-patterns", - "path": "skills/react-patterns", + "path": "skills\\react-patterns", "category": "uncategorized", "name": "react-patterns", "description": "Modern React patterns and principles. Hooks, composition, performance, TypeScript best practices.", @@ -6382,7 +6517,7 @@ }, { "id": "react-state-management", - "path": "skills/react-state-management", + "path": "skills\\react-state-management", "category": "uncategorized", "name": "react-state-management", "description": "Master modern React state management with Redux Toolkit, Zustand, Jotai, and React Query. Use when setting up global state, managing server state, or choosing between state management solutions.", @@ -6391,7 +6526,7 @@ }, { "id": "react-ui-patterns", - "path": "skills/react-ui-patterns", + "path": "skills\\react-ui-patterns", "category": "uncategorized", "name": "react-ui-patterns", "description": "Modern React UI patterns for loading states, error handling, and data fetching. Use when building UI components, handling async data, or managing UI states.", @@ -6400,7 +6535,7 @@ }, { "id": "readme", - "path": "skills/readme", + "path": "skills\\readme", "category": "uncategorized", "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 he...", @@ -6409,7 +6544,7 @@ }, { "id": "receiving-code-review", - "path": "skills/receiving-code-review", + "path": "skills\\receiving-code-review", "category": "uncategorized", "name": "receiving-code-review", "description": "Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performat...", @@ -6418,7 +6553,7 @@ }, { "id": "red-team-tactics", - "path": "skills/red-team-tactics", + "path": "skills\\red-team-tactics", "category": "uncategorized", "name": "red-team-tactics", "description": "Red team tactics principles based on MITRE ATT&CK. Attack phases, detection evasion, reporting.", @@ -6427,7 +6562,7 @@ }, { "id": "red-team-tools", - "path": "skills/red-team-tools", + "path": "skills\\red-team-tools", "category": "uncategorized", "name": "red-team-tools", "description": "This skill should be used when the user asks to \"follow red team methodology\", \"perform bug bounty hunting\", \"automate reconnaissance\", \"hunt for XSS vulnerabilities\", \"enumerate su...", @@ -6436,7 +6571,7 @@ }, { "id": "reddit-automation", - "path": "skills/reddit-automation", + "path": "skills\\reddit-automation", "category": "uncategorized", "name": "reddit-automation", "description": "Automate Reddit tasks via Rube MCP (Composio): search subreddits, create posts, manage comments, and browse top content. Always search tools first for current schemas.", @@ -6445,16 +6580,16 @@ }, { "id": "reference-builder", - "path": "skills/reference-builder", + "path": "skills\\reference-builder", "category": "uncategorized", - "name": "Reference Builder", - "description": "- Working on reference builder tasks or workflows - Needing guidance, best practices, or checklists for reference builder", + "name": "reference-builder", + "description": "Creates exhaustive technical references and API documentation.\nGenerates comprehensive parameter listings, configuration guides, and\nsearchable reference materials. Use PROACTIVELY for API docs, configuration\nreferences, or complete technical specifications.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "referral-program", - "path": "skills/referral-program", + "path": "skills\\referral-program", "category": "uncategorized", "name": "referral-program", "description": "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 'referral,' 'affiliate,' 'ambassador,' 'word of...", @@ -6463,7 +6598,7 @@ }, { "id": "remotion-best-practices", - "path": "skills/remotion-best-practices", + "path": "skills\\remotion-best-practices", "category": "uncategorized", "name": "remotion-best-practices", "description": "Best practices for Remotion - Video creation in React", @@ -6472,7 +6607,7 @@ }, { "id": "render-automation", - "path": "skills/render-automation", + "path": "skills\\render-automation", "category": "uncategorized", "name": "render-automation", "description": "Automate Render tasks via Rube MCP (Composio): services, deployments, projects. Always search tools first for current schemas.", @@ -6481,7 +6616,7 @@ }, { "id": "requesting-code-review", - "path": "skills/requesting-code-review", + "path": "skills\\requesting-code-review", "category": "uncategorized", "name": "requesting-code-review", "description": "Use when completing tasks, implementing major features, or before merging to verify work meets requirements", @@ -6490,7 +6625,7 @@ }, { "id": "research-engineer", - "path": "skills/research-engineer", + "path": "skills\\research-engineer", "category": "uncategorized", "name": "research-engineer", "description": "An uncompromising Academic Research Engineer. Operates with absolute scientific rigor, objective criticism, and zero flair. Focuses on theoretical correctness, formal verification, and optimal impl...", @@ -6498,26 +6633,35 @@ "source": "community" }, { - "id": "reverse-engineer", - "path": "skills/reverse-engineer", + "id": "returns-reverse-logistics", + "path": "skills\\returns-reverse-logistics", "category": "uncategorized", - "name": "Reverse Engineer", - "description": "- IDAPython (IDA Pro scripting) - Ghidra scripting (Java/Python via Jython) - r2pipe (radare2 Python API) - pwntools (CTF/exploitation toolkit) - capstone (disassembly framework) - keystone (assembly framework) - unicorn (CPU emulator framework) - an", + "name": "returns-reverse-logistics", + "description": "Codified expertise for returns authorisation, receipt and inspection, disposition decisions, refund processing, fraud detection, and warranty claims management. Informed by returns operations managers with 15+ years experience. Includes grading frameworks, disposition economics, fraud pattern recognition, and vendor recovery processes. Use when handling product returns, reverse logistics, refund decisions, return fraud detection, or warranty claims.\n", + "risk": "safe", + "source": "https://github.com/ai-evos/agent-skills" + }, + { + "id": "reverse-engineer", + "path": "skills\\reverse-engineer", + "category": "uncategorized", + "name": "reverse-engineer", + "description": "Expert reverse engineer specializing in binary analysis,\ndisassembly, decompilation, and software analysis. Masters IDA Pro, Ghidra,\nradare2, x64dbg, and modern RE toolchains. Handles executable analysis,\nlibrary inspection, protocol extraction, and vulnerability research. Use\nPROACTIVELY for binary analysis, CTF challenges, security research, or\nunderstanding undocumented software.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "risk-manager", - "path": "skills/risk-manager", + "path": "skills\\risk-manager", "category": "uncategorized", - "name": "Risk Manager", - "description": "- Working on risk manager tasks or workflows - Needing guidance, best practices, or checklists for risk manager", + "name": "risk-manager", + "description": "Monitor portfolio risk, R-multiples, and position limits. Creates\nhedging strategies, calculates expectancy, and implements stop-losses. Use\nPROACTIVELY for risk assessment, trade tracking, or portfolio protection.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "risk-metrics-calculation", - "path": "skills/risk-metrics-calculation", + "path": "skills\\risk-metrics-calculation", "category": "uncategorized", "name": "risk-metrics-calculation", "description": "Calculate portfolio risk metrics including VaR, CVaR, Sharpe, Sortino, and drawdown analysis. Use when measuring portfolio risk, implementing risk limits, or building risk monitoring systems.", @@ -6526,34 +6670,34 @@ }, { "id": "ruby-pro", - "path": "skills/ruby-pro", + "path": "skills\\ruby-pro", "category": "uncategorized", - "name": "Ruby Pro", - "description": "- Working on ruby pro tasks or workflows - Needing guidance, best practices, or checklists for ruby pro", + "name": "ruby-pro", + "description": "Write idiomatic Ruby code with metaprogramming, Rails patterns, and\nperformance optimization. Specializes in Ruby on Rails, gem development, and\ntesting frameworks. Use PROACTIVELY for Ruby refactoring, optimization, or\ncomplex Ruby features.\n", "risk": "unknown", - "source": "unknown" - }, - { - "id": "rust-pro", - "path": "skills/rust-pro", - "category": "uncategorized", - "name": "Rust Pro", - "description": "You are a Rust expert specializing in modern Rust 1.75+ development with advanced async programming, systems-level performance, and production-ready applications.", - "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "rust-async-patterns", - "path": "skills/rust-async-patterns", + "path": "skills\\rust-async-patterns", "category": "uncategorized", "name": "rust-async-patterns", "description": "Master Rust async programming with Tokio, async traits, error handling, and concurrent patterns. Use when building async Rust applications, implementing concurrent systems, or debugging async code.", "risk": "unknown", "source": "community" }, + { + "id": "rust-pro", + "path": "skills\\rust-pro", + "category": "uncategorized", + "name": "rust-pro", + "description": "Master Rust 1.75+ with modern async patterns, advanced type system\nfeatures, and production-ready systems programming. Expert in the latest Rust\necosystem including Tokio, axum, and cutting-edge crates. Use PROACTIVELY for\nRust development, performance optimization, or systems programming.\n", + "risk": "unknown", + "source": "community" + }, { "id": "saga-orchestration", - "path": "skills/saga-orchestration", + "path": "skills\\saga-orchestration", "category": "uncategorized", "name": "saga-orchestration", "description": "Implement saga patterns for distributed transactions and cross-aggregate workflows. Use when coordinating multi-step business processes, handling compensating transactions, or managing long-running...", @@ -6562,16 +6706,16 @@ }, { "id": "sales-automator", - "path": "skills/sales-automator", + "path": "skills\\sales-automator", "category": "uncategorized", - "name": "Sales Automator", - "description": "- Working on sales automator tasks or workflows - Needing guidance, best practices, or checklists for sales automator", + "name": "sales-automator", + "description": "Draft cold emails, follow-ups, and proposal templates. Creates\npricing pages, case studies, and sales scripts. Use PROACTIVELY for sales\noutreach or lead nurturing.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "salesforce-automation", - "path": "skills/salesforce-automation", + "path": "skills\\salesforce-automation", "category": "uncategorized", "name": "salesforce-automation", "description": "Automate Salesforce tasks via Rube MCP (Composio): leads, contacts, accounts, opportunities, SOQL queries. Always search tools first for current schemas.", @@ -6580,7 +6724,7 @@ }, { "id": "salesforce-development", - "path": "skills/salesforce-development", + "path": "skills\\salesforce-development", "category": "uncategorized", "name": "salesforce-development", "description": "Expert patterns for Salesforce platform development including Lightning Web Components (LWC), Apex triggers and classes, REST/Bulk APIs, Connected Apps, and Salesforce DX with scratch orgs and 2nd ...", @@ -6589,7 +6733,7 @@ }, { "id": "sast-configuration", - "path": "skills/sast-configuration", + "path": "skills\\sast-configuration", "category": "uncategorized", "name": "sast-configuration", "description": "Configure Static Application Security Testing (SAST) tools for automated vulnerability detection in application code. Use when setting up security scanning, implementing DevSecOps practices, or aut...", @@ -6598,16 +6742,16 @@ }, { "id": "scala-pro", - "path": "skills/scala-pro", + "path": "skills\\scala-pro", "category": "uncategorized", - "name": "Scala Pro", - "description": "- Working on scala pro tasks or workflows - Needing guidance, best practices, or checklists for scala pro", + "name": "scala-pro", + "description": "Master enterprise-grade Scala development with functional\nprogramming, distributed systems, and big data processing. Expert in Apache\nPekko, Akka, Spark, ZIO/Cats Effect, and reactive architectures. Use\nPROACTIVELY for Scala system design, performance optimization, or enterprise\nintegration.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "scanning-tools", - "path": "skills/scanning-tools", + "path": "skills\\scanning-tools", "category": "uncategorized", "name": "scanning-tools", "description": "This skill should be used when the user asks to \"perform vulnerability scanning\", \"scan networks for open ports\", \"assess web application security\", \"scan wireless networks\", \"detec...", @@ -6616,16 +6760,16 @@ }, { "id": "schema-markup", - "path": "skills/schema-markup", + "path": "skills\\schema-markup", "category": "uncategorized", - "name": "Schema Markup", - "description": "---", + "name": "schema-markup", + "description": "Design, validate, and optimize schema.org structured data for eligibility, correctness, and measurable SEO impact. Use when the user wants to add, fix, audit, or scale schema markup (JSON-LD) for rich results. This skill evaluates whether schema should be implemented, what types are valid, and how to deploy safely according to Google guidelines.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "screen-reader-testing", - "path": "skills/screen-reader-testing", + "path": "skills\\screen-reader-testing", "category": "uncategorized", "name": "screen-reader-testing", "description": "Test web applications with screen readers including VoiceOver, NVDA, and JAWS. Use when validating screen reader compatibility, debugging accessibility issues, or ensuring assistive technology supp...", @@ -6634,7 +6778,7 @@ }, { "id": "screenshots", - "path": "skills/screenshots", + "path": "skills\\screenshots", "category": "uncategorized", "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.", @@ -6643,7 +6787,7 @@ }, { "id": "scroll-experience", - "path": "skills/scroll-experience", + "path": "skills\\scroll-experience", "category": "uncategorized", "name": "scroll-experience", "description": "Expert in building immersive scroll-driven experiences - parallax storytelling, scroll animations, interactive narratives, and cinematic web experiences. Like NY Times interactives, Apple product p...", @@ -6652,7 +6796,7 @@ }, { "id": "search-specialist", - "path": "skills/search-specialist", + "path": "skills\\search-specialist", "category": "uncategorized", "name": "search-specialist", "description": "Expert web researcher using advanced search techniques and synthesis. Masters search operators, result filtering, and multi-source verification. Handles competitive analysis and fact-checking. Use PROACTIVELY for deep research, information gathering, or trend analysis.", @@ -6661,43 +6805,34 @@ }, { "id": "secrets-management", - "path": "skills/secrets-management", + "path": "skills\\secrets-management", "category": "uncategorized", "name": "secrets-management", "description": "Implement secure secrets management for CI/CD pipelines using Vault, AWS Secrets Manager, or native platform solutions. Use when handling sensitive credentials, rotating secrets, or securing CI/CD ...", "risk": "unknown", "source": "community" }, - { - "id": "security-auditor", - "path": "skills/security-auditor", - "category": "uncategorized", - "name": "Security Auditor", - "description": "You are a security auditor specializing in DevSecOps, application security, and comprehensive cybersecurity practices.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "security-scanning-security-sast", - "path": "skills/security-scanning-security-sast", - "category": "uncategorized", - "name": "Security Scanning Security Sast", - "description": "Static Application Security Testing (SAST) for comprehensive code vulnerability detection across multiple languages, frameworks, and security patterns.", - "risk": "unknown", - "source": "unknown" - }, { "id": "security-audit", - "path": "skills/security-audit", + "path": "skills\\security-audit", "category": "uncategorized", "name": "security-audit", "description": "Comprehensive security auditing workflow covering web application testing, API security, penetration testing, vulnerability scanning, and security hardening.", "risk": "safe", "source": "personal" }, + { + "id": "security-auditor", + "path": "skills\\security-auditor", + "category": "uncategorized", + "name": "security-auditor", + "description": "Expert security auditor specializing in DevSecOps, comprehensive\ncybersecurity, and compliance frameworks. Masters vulnerability assessment,\nthreat modeling, secure authentication (OAuth2/OIDC), OWASP standards, cloud\nsecurity, and security automation. Handles DevSecOps integration, compliance\n(GDPR/HIPAA/SOC2), and incident response. Use PROACTIVELY for security audits,\nDevSecOps, or compliance implementation.\n", + "risk": "unknown", + "source": "community" + }, { "id": "security-bluebook-builder", - "path": "skills/security-bluebook-builder", + "path": "skills\\security-bluebook-builder", "category": "uncategorized", "name": "security-bluebook-builder", "description": "Build security Blue Books for sensitive apps", @@ -6706,7 +6841,7 @@ }, { "id": "security-compliance-compliance-check", - "path": "skills/security-compliance-compliance-check", + "path": "skills\\security-compliance-compliance-check", "category": "uncategorized", "name": "security-compliance-compliance-check", "description": "You are a compliance expert specializing in regulatory requirements for software systems including GDPR, HIPAA, SOC2, PCI-DSS, and other industry standards. Perform compliance audits and provide im...", @@ -6715,7 +6850,7 @@ }, { "id": "security-requirement-extraction", - "path": "skills/security-requirement-extraction", + "path": "skills\\security-requirement-extraction", "category": "uncategorized", "name": "security-requirement-extraction", "description": "Derive security requirements from threat models and business context. Use when translating threats into actionable requirements, creating security user stories, or building security test cases.", @@ -6724,7 +6859,7 @@ }, { "id": "security-scanning-security-dependencies", - "path": "skills/security-scanning-security-dependencies", + "path": "skills\\security-scanning-security-dependencies", "category": "uncategorized", "name": "security-scanning-security-dependencies", "description": "You are a security expert specializing in dependency vulnerability analysis, SBOM generation, and supply chain security. Scan project dependencies across ecosystems to identify vulnerabilities, ass...", @@ -6733,16 +6868,25 @@ }, { "id": "security-scanning-security-hardening", - "path": "skills/security-scanning-security-hardening", + "path": "skills\\security-scanning-security-hardening", "category": "uncategorized", "name": "security-scanning-security-hardening", "description": "Coordinate multi-layer security scanning and hardening across application, infrastructure, and compliance controls.", "risk": "unknown", "source": "community" }, + { + "id": "security-scanning-security-sast", + "path": "skills\\security-scanning-security-sast", + "category": "uncategorized", + "name": "security-scanning-security-sast", + "description": "Static Application Security Testing (SAST) for code vulnerability\nanalysis across multiple languages and frameworks\n", + "risk": "unknown", + "source": "community" + }, { "id": "segment-automation", - "path": "skills/segment-automation", + "path": "skills\\segment-automation", "category": "uncategorized", "name": "segment-automation", "description": "Automate Segment tasks via Rube MCP (Composio): track events, identify users, manage groups, page views, aliases, batch operations. Always search tools first for current schemas.", @@ -6751,7 +6895,7 @@ }, { "id": "segment-cdp", - "path": "skills/segment-cdp", + "path": "skills\\segment-cdp", "category": "uncategorized", "name": "segment-cdp", "description": "Expert patterns for Segment Customer Data Platform including Analytics.js, server-side tracking, tracking plans with Protocols, identity resolution, destinations configuration, and data governance ...", @@ -6760,7 +6904,7 @@ }, { "id": "sendgrid-automation", - "path": "skills/sendgrid-automation", + "path": "skills\\sendgrid-automation", "category": "uncategorized", "name": "sendgrid-automation", "description": "Automate SendGrid email operations including sending emails, managing contacts/lists, sender identities, templates, and analytics via Rube MCP (Composio). Always search tools first for current sche...", @@ -6769,7 +6913,7 @@ }, { "id": "senior-architect", - "path": "skills/senior-architect", + "path": "skills\\senior-architect", "category": "uncategorized", "name": "senior-architect", "description": "Comprehensive software architecture skill for designing scalable, maintainable systems using ReactJS, NextJS, NodeJS, Express, React Native, Swift, Kotlin, Flutter, Postgres, GraphQL, Go, Python. I...", @@ -6778,7 +6922,7 @@ }, { "id": "senior-fullstack", - "path": "skills/senior-fullstack", + "path": "skills\\senior-fullstack", "category": "uncategorized", "name": "senior-fullstack", "description": "Comprehensive fullstack development skill for building complete web applications with React, Next.js, Node.js, GraphQL, and PostgreSQL. Includes project scaffolding, code quality analysis, architec...", @@ -6787,7 +6931,7 @@ }, { "id": "sentry-automation", - "path": "skills/sentry-automation", + "path": "skills\\sentry-automation", "category": "uncategorized", "name": "sentry-automation", "description": "Automate Sentry tasks via Rube MCP (Composio): manage issues/events, configure alerts, track releases, monitor projects and teams. Always search tools first for current schemas.", @@ -6796,115 +6940,115 @@ }, { "id": "seo-audit", - "path": "skills/seo-audit", + "path": "skills\\seo-audit", "category": "uncategorized", - "name": "Seo Audit", - "description": "You are an **SEO diagnostic specialist**. Your role is to **identify, explain, and prioritize SEO issues** that affect organic visibility\u2014**not to implement fixes unless explicitly requested**.", + "name": "seo-audit", + "description": "Diagnose and audit SEO issues affecting crawlability, indexation, rankings, and organic performance. Use when the user asks for an SEO audit, technical SEO review, ranking diagnosis, on-page SEO review, meta tag audit, or SEO health check. This skill identifies issues and prioritizes actions but does not execute changes. For large-scale page creation, use programmatic-seo. For structured data, use schema-markup.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "seo-authority-builder", - "path": "skills/seo-authority-builder", + "path": "skills\\seo-authority-builder", "category": "uncategorized", - "name": "Seo Authority Builder", - "description": "- Working on seo authority builder tasks or workflows - Needing guidance, best practices, or checklists for seo authority builder", + "name": "seo-authority-builder", + "description": "Analyzes content for E-E-A-T signals and suggests improvements to\nbuild authority and trust. Identifies missing credibility elements. Use\nPROACTIVELY for YMYL topics.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "seo-cannibalization-detector", - "path": "skills/seo-cannibalization-detector", + "path": "skills\\seo-cannibalization-detector", "category": "uncategorized", - "name": "Seo Cannibalization Detector", - "description": "- Working on seo cannibalization detector tasks or workflows - Needing guidance, best practices, or checklists for seo cannibalization detector", + "name": "seo-cannibalization-detector", + "description": "Analyzes multiple provided pages to identify keyword overlap and\npotential cannibalization issues. Suggests differentiation strategies. Use\nPROACTIVELY when reviewing similar content.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "seo-content-auditor", - "path": "skills/seo-content-auditor", + "path": "skills\\seo-content-auditor", "category": "uncategorized", - "name": "Seo Content Auditor", - "description": "- Working on seo content auditor tasks or workflows - Needing guidance, best practices, or checklists for seo content auditor", + "name": "seo-content-auditor", + "description": "Analyzes provided content for quality, E-E-A-T signals, and SEO\nbest practices. Scores content and provides improvement recommendations based\non established guidelines. Use PROACTIVELY for content review.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "seo-content-planner", - "path": "skills/seo-content-planner", + "path": "skills\\seo-content-planner", "category": "uncategorized", - "name": "Seo Content Planner", - "description": "- Working on seo content planner tasks or workflows - Needing guidance, best practices, or checklists for seo content planner", + "name": "seo-content-planner", + "description": "Creates comprehensive content outlines and topic clusters for SEO.\nPlans content calendars and identifies topic gaps. Use PROACTIVELY for content\nstrategy and planning.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "seo-content-refresher", - "path": "skills/seo-content-refresher", + "path": "skills\\seo-content-refresher", "category": "uncategorized", - "name": "Seo Content Refresher", - "description": "- Working on seo content refresher tasks or workflows - Needing guidance, best practices, or checklists for seo content refresher", + "name": "seo-content-refresher", + "description": "Identifies outdated elements in provided content and suggests\nupdates to maintain freshness. Finds statistics, dates, and examples that need\nupdating. Use PROACTIVELY for older content.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "seo-content-writer", - "path": "skills/seo-content-writer", + "path": "skills\\seo-content-writer", "category": "uncategorized", - "name": "Seo Content Writer", - "description": "- Working on seo content writer tasks or workflows - Needing guidance, best practices, or checklists for seo content writer", + "name": "seo-content-writer", + "description": "Writes SEO-optimized content based on provided keywords and topic\nbriefs. Creates engaging, comprehensive content following best practices. Use\nPROACTIVELY for content creation tasks.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "seo-fundamentals", - "path": "skills/seo-fundamentals", + "path": "skills\\seo-fundamentals", "category": "uncategorized", - "name": "Seo Fundamentals", - "description": "---", + "name": "seo-fundamentals", + "description": "Core principles of SEO including E-E-A-T, Core Web Vitals, technical foundations, content quality, and how modern search engines evaluate pages. This skill explains *why* SEO works, not how to execute specific optimizations.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "seo-keyword-strategist", - "path": "skills/seo-keyword-strategist", + "path": "skills\\seo-keyword-strategist", "category": "uncategorized", - "name": "Seo Keyword Strategist", - "description": "- Working on seo keyword strategist tasks or workflows - Needing guidance, best practices, or checklists for seo keyword strategist", + "name": "seo-keyword-strategist", + "description": "Analyzes keyword usage in provided content, calculates density,\nsuggests semantic variations and LSI keywords based on the topic. Prevents\nover-optimization. Use PROACTIVELY for content optimization.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "seo-meta-optimizer", - "path": "skills/seo-meta-optimizer", + "path": "skills\\seo-meta-optimizer", "category": "uncategorized", - "name": "Seo Meta Optimizer", - "description": "- Working on seo meta optimizer tasks or workflows - Needing guidance, best practices, or checklists for seo meta optimizer", + "name": "seo-meta-optimizer", + "description": "Creates optimized meta titles, descriptions, and URL suggestions\nbased on character limits and best practices. Generates compelling,\nkeyword-rich metadata. Use PROACTIVELY for new content.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "seo-snippet-hunter", - "path": "skills/seo-snippet-hunter", + "path": "skills\\seo-snippet-hunter", "category": "uncategorized", - "name": "Seo Snippet Hunter", - "description": "- Working on seo snippet hunter tasks or workflows - Needing guidance, best practices, or checklists for seo snippet hunter", + "name": "seo-snippet-hunter", + "description": "Formats content to be eligible for featured snippets and SERP\nfeatures. Creates snippet-optimized content blocks based on best practices.\nUse PROACTIVELY for question-based content.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "seo-structure-architect", - "path": "skills/seo-structure-architect", + "path": "skills\\seo-structure-architect", "category": "uncategorized", - "name": "Seo Structure Architect", - "description": "- Working on seo structure architect tasks or workflows - Needing guidance, best practices, or checklists for seo structure architect", + "name": "seo-structure-architect", + "description": "Analyzes and optimizes content structure including header\nhierarchy, suggests schema markup, and internal linking opportunities. Creates\nsearch-friendly content organization. Use PROACTIVELY for content structuring.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "server-management", - "path": "skills/server-management", + "path": "skills\\server-management", "category": "uncategorized", "name": "server-management", "description": "Server management principles and decision-making. Process management, monitoring strategy, and scaling decisions. Teaches thinking, not commands.", @@ -6913,7 +7057,7 @@ }, { "id": "service-mesh-expert", - "path": "skills/service-mesh-expert", + "path": "skills\\service-mesh-expert", "category": "uncategorized", "name": "service-mesh-expert", "description": "Expert service mesh architect specializing in Istio, Linkerd, and cloud-native networking patterns. Masters traffic management, security policies, observability integration, and multi-cluster mesh con", @@ -6922,7 +7066,7 @@ }, { "id": "service-mesh-observability", - "path": "skills/service-mesh-observability", + "path": "skills\\service-mesh-observability", "category": "uncategorized", "name": "service-mesh-observability", "description": "Implement comprehensive observability for service meshes including distributed tracing, metrics, and visualization. Use when setting up mesh monitoring, debugging latency issues, or implementing SL...", @@ -6931,7 +7075,7 @@ }, { "id": "shader-programming-glsl", - "path": "skills/shader-programming-glsl", + "path": "skills\\shader-programming-glsl", "category": "uncategorized", "name": "shader-programming-glsl", "description": "Expert guide for writing efficient GLSL shaders (Vertex/Fragment) for web and game engines, covering syntax, uniforms, and common effects.", @@ -6940,7 +7084,7 @@ }, { "id": "sharp-edges", - "path": "skills/sharp-edges", + "path": "skills\\sharp-edges", "category": "uncategorized", "name": "sharp-edges", "description": "Identify error-prone APIs and dangerous configurations", @@ -6949,7 +7093,7 @@ }, { "id": "shellcheck-configuration", - "path": "skills/shellcheck-configuration", + "path": "skills\\shellcheck-configuration", "category": "uncategorized", "name": "shellcheck-configuration", "description": "Master ShellCheck static analysis configuration and usage for shell script quality. Use when setting up linting infrastructure, fixing code issues, or ensuring script portability.", @@ -6958,7 +7102,7 @@ }, { "id": "shodan-reconnaissance", - "path": "skills/shodan-reconnaissance", + "path": "skills\\shodan-reconnaissance", "category": "uncategorized", "name": "shodan-reconnaissance", "description": "This skill should be used when the user asks to \"search for exposed devices on the internet,\" \"perform Shodan reconnaissance,\" \"find vulnerable services using Shodan,\" \"scan IP ranges...", @@ -6967,7 +7111,7 @@ }, { "id": "shopify-apps", - "path": "skills/shopify-apps", + "path": "skills\\shopify-apps", "category": "uncategorized", "name": "shopify-apps", "description": "Expert patterns for Shopify app development including Remix/React Router apps, embedded apps with App Bridge, webhook handling, GraphQL Admin API, Polaris components, billing, and app extensions. U...", @@ -6976,7 +7120,7 @@ }, { "id": "shopify-automation", - "path": "skills/shopify-automation", + "path": "skills\\shopify-automation", "category": "uncategorized", "name": "shopify-automation", "description": "Automate Shopify tasks via Rube MCP (Composio): products, orders, customers, inventory, collections. Always search tools first for current schemas.", @@ -6985,7 +7129,7 @@ }, { "id": "shopify-development", - "path": "skills/shopify-development", + "path": "skills\\shopify-development", "category": "uncategorized", "name": "shopify-development", "description": "Build Shopify apps, extensions, themes using GraphQL Admin API, Shopify CLI, Polaris UI, and Liquid.\nTRIGGER: \"shopify\", \"shopify app\", \"checkout extension\", \"admin extension\", \"POS extension\",\n\"shopify theme\", \"liquid template\", \"polaris\", \"shopify graphql\", \"shopify webhook\",\n\"shopify billing\", \"app subscription\", \"metafields\", \"shopify functions\"\n", @@ -6994,7 +7138,7 @@ }, { "id": "signup-flow-cro", - "path": "skills/signup-flow-cro", + "path": "skills\\signup-flow-cro", "category": "uncategorized", "name": "signup-flow-cro", "description": "When the user wants to optimize signup, registration, account creation, or trial activation flows. Also use when the user mentions \"signup conversions,\" \"registration friction,\" \"signup...", @@ -7003,7 +7147,7 @@ }, { "id": "similarity-search-patterns", - "path": "skills/similarity-search-patterns", + "path": "skills\\similarity-search-patterns", "category": "uncategorized", "name": "similarity-search-patterns", "description": "Implement efficient similarity search with vector databases. Use when building semantic search, implementing nearest neighbor queries, or optimizing retrieval performance.", @@ -7012,7 +7156,7 @@ }, { "id": "skill-creator", - "path": "skills/skill-creator", + "path": "skills\\skill-creator", "category": "uncategorized", "name": "skill-creator", "description": "This skill should be used when the user asks to create a new skill, build a skill, make a custom skill, develop a CLI skill, or wants to extend the CLI with new capabilities. Automates the entire s...", @@ -7021,7 +7165,7 @@ }, { "id": "skill-creator-ms", - "path": "skills/skill-creator-ms", + "path": "skills\\skill-creator-ms", "category": "uncategorized", "name": "skill-creator-ms", "description": "Guide for creating effective skills for AI coding agents working with Azure SDKs and Microsoft Foundry services. Use when creating new skills or updating existing skills.", @@ -7030,7 +7174,7 @@ }, { "id": "skill-developer", - "path": "skills/skill-developer", + "path": "skills\\skill-developer", "category": "uncategorized", "name": "skill-developer", "description": "Create and manage Claude Code skills following Anthropic best practices. Use when creating new skills, modifying skill-rules.json, understanding trigger patterns, working with hooks, debugging skil...", @@ -7039,7 +7183,7 @@ }, { "id": "skill-rails-upgrade", - "path": "skills/skill-rails-upgrade", + "path": "skills\\skill-rails-upgrade", "category": "uncategorized", "name": "skill-rails-upgrade", "description": "Analyze Rails apps and provide upgrade assessments", @@ -7048,7 +7192,7 @@ }, { "id": "skill-seekers", - "path": "skills/skill-seekers", + "path": "skills\\skill-seekers", "category": "uncategorized", "name": "skill-seekers", "description": "-Automatically convert documentation websites, GitHub repositories, and PDFs into Claude AI skills in minutes.", @@ -7057,7 +7201,7 @@ }, { "id": "slack-automation", - "path": "skills/slack-automation", + "path": "skills\\slack-automation", "category": "uncategorized", "name": "slack-automation", "description": "Automate Slack messaging, channel management, search, reactions, and threads via Rube MCP (Composio). Send messages, search conversations, manage channels/users, and react to messages programmatica...", @@ -7066,7 +7210,7 @@ }, { "id": "slack-bot-builder", - "path": "skills/slack-bot-builder", + "path": "skills\\slack-bot-builder", "category": "uncategorized", "name": "slack-bot-builder", "description": "Build Slack apps using the Bolt framework across Python, JavaScript, and Java. Covers Block Kit for rich UIs, interactive components, slash commands, event handling, OAuth installation flows, and W...", @@ -7075,7 +7219,7 @@ }, { "id": "slack-gif-creator", - "path": "skills/slack-gif-creator", + "path": "skills\\slack-gif-creator", "category": "uncategorized", "name": "slack-gif-creator", "description": "Knowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like \"...", @@ -7084,7 +7228,7 @@ }, { "id": "slo-implementation", - "path": "skills/slo-implementation", + "path": "skills\\slo-implementation", "category": "uncategorized", "name": "slo-implementation", "description": "Define and implement Service Level Indicators (SLIs) and Service Level Objectives (SLOs) with error budgets and alerting. Use when establishing reliability targets, implementing SRE practices, or m...", @@ -7093,7 +7237,7 @@ }, { "id": "smtp-penetration-testing", - "path": "skills/smtp-penetration-testing", + "path": "skills\\smtp-penetration-testing", "category": "uncategorized", "name": "smtp-penetration-testing", "description": "This skill should be used when the user asks to \"perform SMTP penetration testing\", \"enumerate email users\", \"test for open mail relays\", \"grab SMTP banners\", \"brute force email cre...", @@ -7102,7 +7246,7 @@ }, { "id": "social-content", - "path": "skills/social-content", + "path": "skills\\social-content", "category": "uncategorized", "name": "social-content", "description": "When the user wants help creating, scheduling, or optimizing social media content for LinkedIn, Twitter/X, Instagram, TikTok, Facebook, or other platforms. Also use when the user mentions 'LinkedIn...", @@ -7111,7 +7255,7 @@ }, { "id": "software-architecture", - "path": "skills/software-architecture", + "path": "skills\\software-architecture", "category": "uncategorized", "name": "software-architecture", "description": "Guide for quality focused software architecture. This skill should be used when users want to write code, design architecture, analyze code, in any case that relates to software development.", @@ -7120,7 +7264,7 @@ }, { "id": "solidity-security", - "path": "skills/solidity-security", + "path": "skills\\solidity-security", "category": "uncategorized", "name": "solidity-security", "description": "Master smart contract security best practices to prevent common vulnerabilities and implement secure Solidity patterns. Use when writing smart contracts, auditing existing contracts, or implementin...", @@ -7129,25 +7273,16 @@ }, { "id": "spark-optimization", - "path": "skills/spark-optimization", + "path": "skills\\spark-optimization", "category": "uncategorized", "name": "spark-optimization", "description": "Optimize Apache Spark jobs with partitioning, caching, shuffle optimization, and memory tuning. Use when improving Spark performance, debugging slow jobs, or scaling data processing pipelines.", "risk": "unknown", "source": "community" }, - { - "id": "sql-pro", - "path": "skills/sql-pro", - "category": "uncategorized", - "name": "Sql Pro", - "description": "You are an expert SQL specialist mastering modern database systems, performance optimization, and advanced analytical techniques across cloud-native and hybrid OLTP/OLAP environments.", - "risk": "unknown", - "source": "unknown" - }, { "id": "sql-injection-testing", - "path": "skills/sql-injection-testing", + "path": "skills\\sql-injection-testing", "category": "uncategorized", "name": "sql-injection-testing", "description": "This skill should be used when the user asks to \"test for SQL injection vulnerabilities\", \"perform SQLi attacks\", \"bypass authentication using SQL injection\", \"extract database inform...", @@ -7156,16 +7291,25 @@ }, { "id": "sql-optimization-patterns", - "path": "skills/sql-optimization-patterns", + "path": "skills\\sql-optimization-patterns", "category": "uncategorized", "name": "sql-optimization-patterns", "description": "Master SQL query optimization, indexing strategies, and EXPLAIN analysis to dramatically improve database performance and eliminate slow queries. Use when debugging slow queries, designing database...", "risk": "unknown", "source": "community" }, + { + "id": "sql-pro", + "path": "skills\\sql-pro", + "category": "uncategorized", + "name": "sql-pro", + "description": "Master modern SQL with cloud-native databases, OLTP/OLAP\noptimization, and advanced query techniques. Expert in performance tuning,\ndata modeling, and hybrid analytical systems. Use PROACTIVELY for database\noptimization or complex analysis.\n", + "risk": "unknown", + "source": "community" + }, { "id": "sqlmap-database-pentesting", - "path": "skills/sqlmap-database-pentesting", + "path": "skills\\sqlmap-database-pentesting", "category": "uncategorized", "name": "sqlmap-database-pentesting", "description": "This skill should be used when the user asks to \"automate SQL injection testing,\" \"enumerate database structure,\" \"extract database credentials using sqlmap,\" \"dump tables and columns...", @@ -7174,7 +7318,7 @@ }, { "id": "square-automation", - "path": "skills/square-automation", + "path": "skills\\square-automation", "category": "uncategorized", "name": "square-automation", "description": "Automate Square tasks via Rube MCP (Composio): payments, orders, invoices, locations. Always search tools first for current schemas.", @@ -7183,7 +7327,7 @@ }, { "id": "ssh-penetration-testing", - "path": "skills/ssh-penetration-testing", + "path": "skills\\ssh-penetration-testing", "category": "uncategorized", "name": "ssh-penetration-testing", "description": "This skill should be used when the user asks to \"pentest SSH services\", \"enumerate SSH configurations\", \"brute force SSH credentials\", \"exploit SSH vulnerabilities\", \"perform SSH tu...", @@ -7192,61 +7336,61 @@ }, { "id": "startup-analyst", - "path": "skills/startup-analyst", + "path": "skills\\startup-analyst", "category": "uncategorized", - "name": "Startup Analyst", - "description": "- Working on startup analyst tasks or workflows - Needing guidance, best practices, or checklists for startup analyst", + "name": "startup-analyst", + "description": "Expert startup business analyst specializing in market sizing,\nfinancial modeling, competitive analysis, and strategic planning for\nearly-stage companies. Use PROACTIVELY when the user asks about market\nopportunity, TAM/SAM/SOM, financial projections, unit economics, competitive\nlandscape, team planning, startup metrics, or business strategy for pre-seed\nthrough Series A startups.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "startup-business-analyst-business-case", - "path": "skills/startup-business-analyst-business-case", + "path": "skills\\startup-business-analyst-business-case", "category": "uncategorized", - "name": "Startup Business Analyst Business Case", - "description": "Generate a comprehensive, investor-ready business case document covering market opportunity, solution, competitive landscape, financial projections, team, risks, and funding ask for startup fundraising and strategic planning.", + "name": "startup-business-analyst-business-case", + "description": "Generate comprehensive investor-ready business case document with\nmarket, solution, financials, and strategy\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "startup-business-analyst-financial-projections", - "path": "skills/startup-business-analyst-financial-projections", + "path": "skills\\startup-business-analyst-financial-projections", "category": "uncategorized", - "name": "Startup Business Analyst Financial Projections", - "description": "Create a comprehensive 3-5 year financial model with revenue projections, cost structure, headcount planning, cash flow analysis, and three-scenario modeling (conservative, base, optimistic) for startup financial planning and fundraising.", + "name": "startup-business-analyst-financial-projections", + "description": "Create detailed 3-5 year financial model with revenue, costs, cash\nflow, and scenarios\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "startup-business-analyst-market-opportunity", - "path": "skills/startup-business-analyst-market-opportunity", + "path": "skills\\startup-business-analyst-market-opportunity", "category": "uncategorized", - "name": "Startup Business Analyst Market Opportunity", - "description": "Generate a comprehensive market opportunity analysis for a startup, including Total Addressable Market (TAM), Serviceable Available Market (SAM), and Serviceable Obtainable Market (SOM) calculations using both bottom-up and top-down methodologies.", + "name": "startup-business-analyst-market-opportunity", + "description": "Generate comprehensive market opportunity analysis with TAM/SAM/SOM\ncalculations\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "startup-financial-modeling", - "path": "skills/startup-financial-modeling", + "path": "skills\\startup-financial-modeling", "category": "uncategorized", - "name": "Startup Financial Modeling", - "description": "Build comprehensive 3-5 year financial models with revenue projections, cost structures, cash flow analysis, and scenario planning for early-stage startups.", + "name": "startup-financial-modeling", + "description": "This skill should be used when the user asks to \\\\\\\"create financial\nprojections\", \"build a financial model\", \"forecast revenue\", \"calculate burn\nrate\", \"estimate runway\", \"model cash flow\", or requests 3-5 year financial\nplanning for a startup.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "startup-metrics-framework", - "path": "skills/startup-metrics-framework", + "path": "skills\\startup-metrics-framework", "category": "uncategorized", - "name": "Startup Metrics Framework", - "description": "Comprehensive guide to tracking, calculating, and optimizing key performance metrics for different startup business models from seed through Series A.", + "name": "startup-metrics-framework", + "description": "This skill should be used when the user asks about \\\\\\\"key startup\nmetrics\", \"SaaS metrics\", \"CAC and LTV\", \"unit economics\", \"burn multiple\",\n\"rule of 40\", \"marketplace metrics\", or requests guidance on tracking and\noptimizing business performance metrics.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "stitch-ui-design", - "path": "skills/stitch-ui-design", + "path": "skills\\stitch-ui-design", "category": "uncategorized", "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 cra...", @@ -7255,7 +7399,7 @@ }, { "id": "stride-analysis-patterns", - "path": "skills/stride-analysis-patterns", + "path": "skills\\stride-analysis-patterns", "category": "uncategorized", "name": "stride-analysis-patterns", "description": "Apply STRIDE methodology to systematically identify threats. Use when analyzing system security, conducting threat modeling sessions, or creating security documentation.", @@ -7264,7 +7408,7 @@ }, { "id": "stripe-automation", - "path": "skills/stripe-automation", + "path": "skills\\stripe-automation", "category": "uncategorized", "name": "stripe-automation", "description": "Automate Stripe tasks via Rube MCP (Composio): customers, charges, subscriptions, invoices, products, refunds. Always search tools first for current schemas.", @@ -7273,7 +7417,7 @@ }, { "id": "stripe-integration", - "path": "skills/stripe-integration", + "path": "skills\\stripe-integration", "category": "uncategorized", "name": "stripe-integration", "description": "Implement Stripe payment processing for robust, PCI-compliant payment flows including checkout, subscriptions, and webhooks. Use when integrating Stripe payments, building subscription systems, or ...", @@ -7282,7 +7426,7 @@ }, { "id": "subagent-driven-development", - "path": "skills/subagent-driven-development", + "path": "skills\\subagent-driven-development", "category": "uncategorized", "name": "subagent-driven-development", "description": "Use when executing implementation plans with independent tasks in the current session", @@ -7291,7 +7435,7 @@ }, { "id": "supabase-automation", - "path": "skills/supabase-automation", + "path": "skills\\supabase-automation", "category": "uncategorized", "name": "supabase-automation", "description": "Automate Supabase database queries, table management, project administration, storage, edge functions, and SQL execution via Rube MCP (Composio). Always search tools first for current schemas.", @@ -7300,7 +7444,7 @@ }, { "id": "superpowers-lab", - "path": "skills/superpowers-lab", + "path": "skills\\superpowers-lab", "category": "uncategorized", "name": "superpowers-lab", "description": "Lab environment for Claude superpowers", @@ -7309,7 +7453,7 @@ }, { "id": "swiftui-expert-skill", - "path": "skills/swiftui-expert-skill", + "path": "skills\\swiftui-expert-skill", "category": "uncategorized", "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 buil...", @@ -7318,7 +7462,7 @@ }, { "id": "systematic-debugging", - "path": "skills/systematic-debugging", + "path": "skills\\systematic-debugging", "category": "uncategorized", "name": "systematic-debugging", "description": "Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes", @@ -7327,7 +7471,7 @@ }, { "id": "systems-programming-rust-project", - "path": "skills/systems-programming-rust-project", + "path": "skills\\systems-programming-rust-project", "category": "uncategorized", "name": "systems-programming-rust-project", "description": "You are a Rust project architecture expert specializing in scaffolding production-ready Rust applications. Generate complete project structures with cargo tooling, proper module organization, testing", @@ -7336,7 +7480,7 @@ }, { "id": "tailwind-design-system", - "path": "skills/tailwind-design-system", + "path": "skills\\tailwind-design-system", "category": "uncategorized", "name": "tailwind-design-system", "description": "Build scalable design systems with Tailwind CSS, design tokens, component libraries, and responsive patterns. Use when creating component libraries, implementing design systems, or standardizing UI...", @@ -7345,7 +7489,7 @@ }, { "id": "tailwind-patterns", - "path": "skills/tailwind-patterns", + "path": "skills\\tailwind-patterns", "category": "uncategorized", "name": "tailwind-patterns", "description": "Tailwind CSS v4 principles. CSS-first configuration, container queries, modern patterns, design token architecture.", @@ -7354,7 +7498,7 @@ }, { "id": "tavily-web", - "path": "skills/tavily-web", + "path": "skills\\tavily-web", "category": "uncategorized", "name": "tavily-web", "description": "Web search, content extraction, crawling, and research capabilities using Tavily API", @@ -7363,16 +7507,16 @@ }, { "id": "tdd-orchestrator", - "path": "skills/tdd-orchestrator", + "path": "skills\\tdd-orchestrator", "category": "uncategorized", - "name": "Tdd Orchestrator", - "description": "- Working on tdd orchestrator tasks or workflows - Needing guidance, best practices, or checklists for tdd orchestrator", + "name": "tdd-orchestrator", + "description": "Master TDD orchestrator specializing in red-green-refactor\ndiscipline, multi-agent workflow coordination, and comprehensive test-driven\ndevelopment practices. Enforces TDD best practices across teams with\nAI-assisted testing and modern frameworks. Use PROACTIVELY for TDD\nimplementation and governance.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "tdd-workflow", - "path": "skills/tdd-workflow", + "path": "skills\\tdd-workflow", "category": "uncategorized", "name": "tdd-workflow", "description": "Test-Driven Development workflow principles. RED-GREEN-REFACTOR cycle.", @@ -7381,7 +7525,7 @@ }, { "id": "tdd-workflows-tdd-cycle", - "path": "skills/tdd-workflows-tdd-cycle", + "path": "skills\\tdd-workflows-tdd-cycle", "category": "uncategorized", "name": "tdd-workflows-tdd-cycle", "description": "Use when working with tdd workflows tdd cycle", @@ -7390,7 +7534,7 @@ }, { "id": "tdd-workflows-tdd-green", - "path": "skills/tdd-workflows-tdd-green", + "path": "skills\\tdd-workflows-tdd-green", "category": "uncategorized", "name": "tdd-workflows-tdd-green", "description": "Implement the minimal code needed to make failing tests pass in the TDD green phase.", @@ -7399,7 +7543,7 @@ }, { "id": "tdd-workflows-tdd-red", - "path": "skills/tdd-workflows-tdd-red", + "path": "skills\\tdd-workflows-tdd-red", "category": "uncategorized", "name": "tdd-workflows-tdd-red", "description": "Generate failing tests for the TDD red phase to define expected behavior and edge cases.", @@ -7408,25 +7552,16 @@ }, { "id": "tdd-workflows-tdd-refactor", - "path": "skills/tdd-workflows-tdd-refactor", + "path": "skills\\tdd-workflows-tdd-refactor", "category": "uncategorized", "name": "tdd-workflows-tdd-refactor", "description": "Use when working with tdd workflows tdd refactor", "risk": "unknown", "source": "community" }, - { - "id": "team-composition-analysis", - "path": "skills/team-composition-analysis", - "category": "uncategorized", - "name": "Team Composition Analysis", - "description": "Design optimal team structures, hiring plans, compensation strategies, and equity allocation for early-stage startups from pre-seed through Series A.", - "risk": "unknown", - "source": "unknown" - }, { "id": "team-collaboration-issue", - "path": "skills/team-collaboration-issue", + "path": "skills\\team-collaboration-issue", "category": "uncategorized", "name": "team-collaboration-issue", "description": "You are a GitHub issue resolution expert specializing in systematic bug investigation, feature implementation, and collaborative development workflows. Your expertise spans issue triage, root cause an", @@ -7435,16 +7570,25 @@ }, { "id": "team-collaboration-standup-notes", - "path": "skills/team-collaboration-standup-notes", + "path": "skills\\team-collaboration-standup-notes", "category": "uncategorized", "name": "team-collaboration-standup-notes", "description": "You are an expert team communication specialist focused on async-first standup practices, AI-assisted note generation from commit history, and effective remote team coordination patterns.", "risk": "unknown", "source": "community" }, + { + "id": "team-composition-analysis", + "path": "skills\\team-composition-analysis", + "category": "uncategorized", + "name": "team-composition-analysis", + "description": "This skill should be used when the user asks to \\\\\\\"plan team\nstructure\", \"determine hiring needs\", \"design org chart\", \"calculate\ncompensation\", \"plan equity allocation\", or requests organizational design and\nheadcount planning for a startup.\n", + "risk": "unknown", + "source": "community" + }, { "id": "telegram-automation", - "path": "skills/telegram-automation", + "path": "skills\\telegram-automation", "category": "uncategorized", "name": "telegram-automation", "description": "Automate Telegram tasks via Rube MCP (Composio): send messages, manage chats, share photos/documents, and handle bot commands. Always search tools first for current schemas.", @@ -7453,7 +7597,7 @@ }, { "id": "telegram-bot-builder", - "path": "skills/telegram-bot-builder", + "path": "skills\\telegram-bot-builder", "category": "uncategorized", "name": "telegram-bot-builder", "description": "Expert in building Telegram bots that solve real problems - from simple automation to complex AI-powered bots. Covers bot architecture, the Telegram Bot API, user experience, monetization strategie...", @@ -7462,7 +7606,7 @@ }, { "id": "telegram-mini-app", - "path": "skills/telegram-mini-app", + "path": "skills\\telegram-mini-app", "category": "uncategorized", "name": "telegram-mini-app", "description": "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, payments, user authentication, and build...", @@ -7471,7 +7615,7 @@ }, { "id": "templates", - "path": "skills/app-builder/templates", + "path": "skills\\app-builder\\templates", "category": "app-builder", "name": "templates", "description": "Project scaffolding templates for new applications. Use when creating new projects from scratch. Contains 12 templates for various tech stacks.", @@ -7480,34 +7624,25 @@ }, { "id": "temporal-python-pro", - "path": "skills/temporal-python-pro", + "path": "skills\\temporal-python-pro", "category": "uncategorized", - "name": "Temporal Python Pro", - "description": "- Working on temporal python pro tasks or workflows - Needing guidance, best practices, or checklists for temporal python pro", + "name": "temporal-python-pro", + "description": "Master Temporal workflow orchestration with Python SDK. Implements\ndurable workflows, saga patterns, and distributed transactions. Covers\nasync/await, testing strategies, and production deployment. Use PROACTIVELY\nfor workflow design, microservice orchestration, or long-running processes.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "temporal-python-testing", - "path": "skills/temporal-python-testing", + "path": "skills\\temporal-python-testing", "category": "uncategorized", "name": "temporal-python-testing", "description": "Test Temporal workflows with pytest, time-skipping, and mocking strategies. Covers unit testing, integration testing, replay testing, and local development setup. Use when implementing Temporal wor...", "risk": "unknown", "source": "community" }, - { - "id": "terraform-specialist", - "path": "skills/terraform-specialist", - "category": "uncategorized", - "name": "Terraform Specialist", - "description": "You are a Terraform/OpenTofu specialist focused on advanced infrastructure automation, state management, and modern IaC practices.", - "risk": "unknown", - "source": "unknown" - }, { "id": "terraform-aws-modules", - "path": "skills/terraform-aws-modules", + "path": "skills\\terraform-aws-modules", "category": "uncategorized", "name": "terraform-aws-modules", "description": "Terraform module creation for AWS \u2014 reusable modules, state management, and HCL best practices. Use when building or reviewing Terraform AWS infrastructure.", @@ -7516,7 +7651,7 @@ }, { "id": "terraform-infrastructure", - "path": "skills/terraform-infrastructure", + "path": "skills\\terraform-infrastructure", "category": "uncategorized", "name": "terraform-infrastructure", "description": "Terraform infrastructure as code workflow for provisioning cloud resources, creating reusable modules, and managing infrastructure at scale.", @@ -7525,7 +7660,7 @@ }, { "id": "terraform-module-library", - "path": "skills/terraform-module-library", + "path": "skills\\terraform-module-library", "category": "uncategorized", "name": "terraform-module-library", "description": "Build reusable Terraform modules for AWS, Azure, and GCP infrastructure following infrastructure-as-code best practices. Use when creating infrastructure modules, standardizing cloud provisioning, ...", @@ -7534,7 +7669,7 @@ }, { "id": "terraform-skill", - "path": "skills/terraform-skill", + "path": "skills\\terraform-skill", "category": "uncategorized", "name": "terraform-skill", "description": "Terraform infrastructure as code best practices", @@ -7542,17 +7677,26 @@ "source": "https://github.com/antonbabenko/terraform-skill" }, { - "id": "test-automator", - "path": "skills/test-automator", + "id": "terraform-specialist", + "path": "skills\\terraform-specialist", "category": "uncategorized", - "name": "Test Automator", - "description": "- Working on test automator tasks or workflows - Needing guidance, best practices, or checklists for test automator", + "name": "terraform-specialist", + "description": "Expert Terraform/OpenTofu specialist mastering advanced IaC\nautomation, state management, and enterprise infrastructure patterns. Handles\ncomplex module design, multi-cloud deployments, GitOps workflows, policy as\ncode, and CI/CD integration. Covers migration strategies, security best\npractices, and modern IaC ecosystems. Use PROACTIVELY for advanced IaC, state\nmanagement, or infrastructure automation.\n", "risk": "unknown", - "source": "unknown" + "source": "community" + }, + { + "id": "test-automator", + "path": "skills\\test-automator", + "category": "uncategorized", + "name": "test-automator", + "description": "Master AI-powered test automation with modern frameworks,\nself-healing tests, and comprehensive quality engineering. Build scalable\ntesting strategies with advanced CI/CD integration. Use PROACTIVELY for\ntesting automation or quality assurance.\n", + "risk": "unknown", + "source": "community" }, { "id": "test-driven-development", - "path": "skills/test-driven-development", + "path": "skills\\test-driven-development", "category": "uncategorized", "name": "test-driven-development", "description": "Use when implementing any feature or bugfix, before writing implementation code", @@ -7561,7 +7705,7 @@ }, { "id": "test-fixing", - "path": "skills/test-fixing", + "path": "skills\\test-fixing", "category": "uncategorized", "name": "test-fixing", "description": "Run tests and systematically fix all failing tests using smart error grouping. Use when user asks to fix failing tests, mentions test failures, runs test suite and failures occur, or requests to ma...", @@ -7570,7 +7714,7 @@ }, { "id": "testing-patterns", - "path": "skills/testing-patterns", + "path": "skills\\testing-patterns", "category": "uncategorized", "name": "testing-patterns", "description": "Jest testing patterns, factory functions, mocking strategies, and TDD workflow. Use when writing unit tests, creating test factories, or following TDD red-green-refactor cycle.", @@ -7579,7 +7723,7 @@ }, { "id": "testing-qa", - "path": "skills/testing-qa", + "path": "skills\\testing-qa", "category": "uncategorized", "name": "testing-qa", "description": "Comprehensive testing and QA workflow covering unit testing, integration testing, E2E testing, browser automation, and quality assurance.", @@ -7588,7 +7732,7 @@ }, { "id": "theme-factory", - "path": "skills/theme-factory", + "path": "skills\\theme-factory", "category": "uncategorized", "name": "theme-factory", "description": "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/fonts that you can apply to any artifac...", @@ -7597,7 +7741,7 @@ }, { "id": "threat-mitigation-mapping", - "path": "skills/threat-mitigation-mapping", + "path": "skills\\threat-mitigation-mapping", "category": "uncategorized", "name": "threat-mitigation-mapping", "description": "Map identified threats to appropriate security controls and mitigations. Use when prioritizing security investments, creating remediation plans, or validating control effectiveness.", @@ -7606,7 +7750,7 @@ }, { "id": "threat-modeling-expert", - "path": "skills/threat-modeling-expert", + "path": "skills\\threat-modeling-expert", "category": "uncategorized", "name": "threat-modeling-expert", "description": "Expert in threat modeling methodologies, security architecture review, and risk assessment. Masters STRIDE, PASTA, attack trees, and security requirement extraction. Use for security architecture r...", @@ -7615,7 +7759,7 @@ }, { "id": "threejs-skills", - "path": "skills/threejs-skills", + "path": "skills\\threejs-skills", "category": "uncategorized", "name": "threejs-skills", "description": "Create 3D scenes, interactive experiences, and visual effects using Three.js. Use when user requests 3D graphics, WebGL experiences, 3D visualizations, animations, or interactive 3D elements.", @@ -7624,7 +7768,7 @@ }, { "id": "tiktok-automation", - "path": "skills/tiktok-automation", + "path": "skills\\tiktok-automation", "category": "uncategorized", "name": "tiktok-automation", "description": "Automate TikTok tasks via Rube MCP (Composio): upload/publish videos, post photos, manage content, and view user profiles/stats. Always search tools first for current schemas.", @@ -7633,7 +7777,7 @@ }, { "id": "todoist-automation", - "path": "skills/todoist-automation", + "path": "skills\\todoist-automation", "category": "uncategorized", "name": "todoist-automation", "description": "Automate Todoist task management, projects, sections, filtering, and bulk operations via Rube MCP (Composio). Always search tools first for current schemas.", @@ -7642,7 +7786,7 @@ }, { "id": "tool-design", - "path": "skills/tool-design", + "path": "skills\\tool-design", "category": "uncategorized", "name": "tool-design", "description": "Build tools that agents can use effectively, including architectural reduction patterns", @@ -7651,7 +7795,7 @@ }, { "id": "top-web-vulnerabilities", - "path": "skills/top-web-vulnerabilities", + "path": "skills\\top-web-vulnerabilities", "category": "uncategorized", "name": "top-web-vulnerabilities", "description": "This skill should be used when the user asks to \"identify web application vulnerabilities\", \"explain common security flaws\", \"understand vulnerability categories\", \"learn about inject...", @@ -7660,16 +7804,16 @@ }, { "id": "track-management", - "path": "skills/track-management", + "path": "skills\\track-management", "category": "uncategorized", - "name": "Track Management", - "description": "Guide for creating, managing, and completing Conductor tracks - the logical work units that organize features, bugs, and refactors through specification, planning, and implementation phases.", + "name": "track-management", + "description": "Use this skill when creating, managing, or working with Conductor\ntracks - the logical work units for features, bugs, and refactors. Applies to\nspec.md, plan.md, and track lifecycle operations.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "trello-automation", - "path": "skills/trello-automation", + "path": "skills\\trello-automation", "category": "uncategorized", "name": "trello-automation", "description": "Automate Trello boards, cards, and workflows via Rube MCP (Composio). Create cards, manage lists, assign members, and search across boards programmatically.", @@ -7678,7 +7822,7 @@ }, { "id": "trigger-dev", - "path": "skills/trigger-dev", + "path": "skills\\trigger-dev", "category": "uncategorized", "name": "trigger-dev", "description": "Trigger.dev expert for background jobs, AI workflows, and reliable async execution with excellent developer experience and TypeScript-first design. Use when: trigger.dev, trigger dev, background ta...", @@ -7687,7 +7831,7 @@ }, { "id": "turborepo-caching", - "path": "skills/turborepo-caching", + "path": "skills\\turborepo-caching", "category": "uncategorized", "name": "turborepo-caching", "description": "Configure Turborepo for efficient monorepo builds with local and remote caching. Use when setting up Turborepo, optimizing build pipelines, or implementing distributed caching.", @@ -7696,16 +7840,16 @@ }, { "id": "tutorial-engineer", - "path": "skills/tutorial-engineer", + "path": "skills\\tutorial-engineer", "category": "uncategorized", - "name": "Tutorial Engineer", - "description": "- Working on tutorial engineer tasks or workflows - Needing guidance, best practices, or checklists for tutorial engineer", + "name": "tutorial-engineer", + "description": "Creates step-by-step tutorials and educational content from code.\nTransforms complex concepts into progressive learning experiences with\nhands-on examples. Use PROACTIVELY for onboarding guides, feature tutorials,\nor concept explanations.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "twilio-communications", - "path": "skills/twilio-communications", + "path": "skills\\twilio-communications", "category": "uncategorized", "name": "twilio-communications", "description": "Build communication features with Twilio: SMS messaging, voice calls, WhatsApp Business API, and user verification (2FA). Covers the full spectrum from simple notifications to complex IVR systems a...", @@ -7714,34 +7858,16 @@ }, { "id": "twitter-automation", - "path": "skills/twitter-automation", + "path": "skills\\twitter-automation", "category": "uncategorized", "name": "twitter-automation", "description": "Automate Twitter/X tasks via Rube MCP (Composio): posts, search, users, bookmarks, lists, media. Always search tools first for current schemas.", "risk": "unknown", "source": "community" }, - { - "id": "typescript-expert", - "path": "skills/typescript-expert", - "category": "uncategorized", - "name": "Typescript Expert", - "description": "You are an advanced TypeScript expert with deep, practical knowledge of type-level programming, performance optimization, and real-world problem solving based on current best practices.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "typescript-pro", - "path": "skills/typescript-pro", - "category": "uncategorized", - "name": "Typescript Pro", - "description": "You are a TypeScript expert specializing in advanced typing and enterprise-grade development.", - "risk": "unknown", - "source": "unknown" - }, { "id": "typescript-advanced-types", - "path": "skills/typescript-advanced-types", + "path": "skills\\typescript-advanced-types", "category": "uncategorized", "name": "typescript-advanced-types", "description": "Master TypeScript's advanced type system including generics, conditional types, mapped types, template literals, and utility types for building type-safe applications. Use when implementing complex...", @@ -7749,44 +7875,62 @@ "source": "community" }, { - "id": "ui-ux-designer", - "path": "skills/ui-ux-designer", + "id": "typescript-expert", + "path": "skills\\typescript-expert", "category": "uncategorized", - "name": "Ui Ux Designer", - "description": "- Working on ui ux designer tasks or workflows - Needing guidance, best practices, or checklists for ui ux designer", + "name": "typescript-expert", + "description": "TypeScript and JavaScript expert with deep knowledge of type-level programming, performance optimization, monorepo management, migration strategies, and modern tooling. Use PROACTIVELY for any TypeScript/JavaScript issues including complex type gymnastics, build performance, debugging, and architectural decisions. If a specialized expert is a better fit, I will recommend switching and stop.", "risk": "unknown", - "source": "unknown" + "source": "community" }, { - "id": "ui-visual-validator", - "path": "skills/ui-visual-validator", + "id": "typescript-pro", + "path": "skills\\typescript-pro", "category": "uncategorized", - "name": "Ui Visual Validator", - "description": "- Working on ui visual validator tasks or workflows - Needing guidance, best practices, or checklists for ui visual validator", + "name": "typescript-pro", + "description": "Master TypeScript with advanced types, generics, and strict type\nsafety. Handles complex type systems, decorators, and enterprise-grade\npatterns. Use PROACTIVELY for TypeScript architecture, type inference\noptimization, or advanced typing patterns.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "ui-skills", - "path": "skills/ui-skills", + "path": "skills\\ui-skills", "category": "uncategorized", "name": "ui-skills", "description": "Opinionated, evolving constraints to guide agents when building interfaces", "risk": "safe", "source": "https://github.com/ibelick/ui-skills" }, + { + "id": "ui-ux-designer", + "path": "skills\\ui-ux-designer", + "category": "uncategorized", + "name": "ui-ux-designer", + "description": "Create interface designs, wireframes, and design systems. Masters\nuser research, accessibility standards, and modern design tools. Specializes\nin design tokens, component libraries, and inclusive design. Use PROACTIVELY\nfor design systems, user flows, or interface optimization.\n", + "risk": "unknown", + "source": "community" + }, { "id": "ui-ux-pro-max", - "path": "skills/ui-ux-pro-max", + "path": "skills\\ui-ux-pro-max", "category": "uncategorized", "name": "ui-ux-pro-max", "description": "UI/UX design intelligence. 50 styles, 21 palettes, 50 font pairings, 20 charts, 9 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui). Actions: plan, build, cr...", "risk": "unknown", "source": "community" }, + { + "id": "ui-visual-validator", + "path": "skills\\ui-visual-validator", + "category": "uncategorized", + "name": "ui-visual-validator", + "description": "Rigorous visual validation expert specializing in UI testing,\ndesign system compliance, and accessibility verification. Masters screenshot\nanalysis, visual regression testing, and component validation. Use PROACTIVELY\nto verify UI modifications have achieved their intended goals through\ncomprehensive visual analysis.\n", + "risk": "unknown", + "source": "community" + }, { "id": "unit-testing-test-generate", - "path": "skills/unit-testing-test-generate", + "path": "skills\\unit-testing-test-generate", "category": "uncategorized", "name": "unit-testing-test-generate", "description": "Generate comprehensive, maintainable unit tests across languages with strong coverage and edge case focus.", @@ -7795,16 +7939,16 @@ }, { "id": "unity-developer", - "path": "skills/unity-developer", + "path": "skills\\unity-developer", "category": "uncategorized", - "name": "Unity Developer", - "description": "- Working on unity developer tasks or workflows - Needing guidance, best practices, or checklists for unity developer", + "name": "unity-developer", + "description": "Build Unity games with optimized C# scripts, efficient rendering,\nand proper asset management. Masters Unity 6 LTS, URP/HDRP pipelines, and\ncross-platform deployment. Handles gameplay systems, UI implementation, and\nplatform optimization. Use PROACTIVELY for Unity performance issues, game\nmechanics, or cross-platform builds.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "unity-ecs-patterns", - "path": "skills/unity-ecs-patterns", + "path": "skills\\unity-ecs-patterns", "category": "uncategorized", "name": "unity-ecs-patterns", "description": "Master Unity ECS (Entity Component System) with DOTS, Jobs, and Burst for high-performance game development. Use when building data-oriented games, optimizing performance, or working with large ent...", @@ -7813,7 +7957,7 @@ }, { "id": "unreal-engine-cpp-pro", - "path": "skills/unreal-engine-cpp-pro", + "path": "skills\\unreal-engine-cpp-pro", "category": "uncategorized", "name": "unreal-engine-cpp-pro", "description": "Expert guide for Unreal Engine 5.x C++ development, covering UObject hygiene, performance patterns, and best practices.", @@ -7822,7 +7966,7 @@ }, { "id": "upgrading-expo", - "path": "skills/upgrading-expo", + "path": "skills\\upgrading-expo", "category": "uncategorized", "name": "upgrading-expo", "description": "Upgrade Expo SDK versions", @@ -7831,7 +7975,7 @@ }, { "id": "upstash-qstash", - "path": "skills/upstash-qstash", + "path": "skills\\upstash-qstash", "category": "uncategorized", "name": "upstash-qstash", "description": "Upstash QStash expert for serverless message queues, scheduled jobs, and reliable HTTP-based task delivery without managing infrastructure. Use when: qstash, upstash queue, serverless cron, schedul...", @@ -7840,7 +7984,7 @@ }, { "id": "using-git-worktrees", - "path": "skills/using-git-worktrees", + "path": "skills\\using-git-worktrees", "category": "uncategorized", "name": "using-git-worktrees", "description": "Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verifi...", @@ -7849,7 +7993,7 @@ }, { "id": "using-neon", - "path": "skills/using-neon", + "path": "skills\\using-neon", "category": "uncategorized", "name": "using-neon", "description": "Guides and best practices for working with Neon Serverless Postgres. Covers getting started, local development with Neon, choosing a connection method, Neon features, authentication (@neondatabase/...", @@ -7858,7 +8002,7 @@ }, { "id": "using-superpowers", - "path": "skills/using-superpowers", + "path": "skills\\using-superpowers", "category": "uncategorized", "name": "using-superpowers", "description": "Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions", @@ -7867,7 +8011,7 @@ }, { "id": "uv-package-manager", - "path": "skills/uv-package-manager", + "path": "skills\\uv-package-manager", "category": "uncategorized", "name": "uv-package-manager", "description": "Master the uv package manager for fast Python dependency management, virtual environments, and modern Python project workflows. Use when setting up Python projects, managing dependencies, or optimi...", @@ -7876,7 +8020,7 @@ }, { "id": "varlock-claude-skill", - "path": "skills/varlock-claude-skill", + "path": "skills\\varlock-claude-skill", "category": "uncategorized", "name": "varlock-claude-skill", "description": "Secure environment variable management ensuring secrets are never exposed in Claude sessions, terminals, logs, or git commits", @@ -7885,7 +8029,7 @@ }, { "id": "vector-database-engineer", - "path": "skills/vector-database-engineer", + "path": "skills\\vector-database-engineer", "category": "uncategorized", "name": "vector-database-engineer", "description": "Expert in vector databases, embedding strategies, and semantic search implementation. Masters Pinecone, Weaviate, Qdrant, Milvus, and pgvector for RAG applications, recommendation systems, and similar", @@ -7894,7 +8038,7 @@ }, { "id": "vector-index-tuning", - "path": "skills/vector-index-tuning", + "path": "skills\\vector-index-tuning", "category": "uncategorized", "name": "vector-index-tuning", "description": "Optimize vector index performance for latency, recall, and memory. Use when tuning HNSW parameters, selecting quantization strategies, or scaling vector search infrastructure.", @@ -7903,7 +8047,7 @@ }, { "id": "vercel-automation", - "path": "skills/vercel-automation", + "path": "skills\\vercel-automation", "category": "uncategorized", "name": "vercel-automation", "description": "Automate Vercel tasks via Rube MCP (Composio): manage deployments, domains, DNS, env vars, projects, and teams. Always search tools first for current schemas.", @@ -7912,7 +8056,7 @@ }, { "id": "vercel-deploy-claimable", - "path": "skills/vercel-deploy-claimable", + "path": "skills\\vercel-deploy-claimable", "category": "uncategorized", "name": "vercel-deploy-claimable", "description": "Deploy applications and websites to Vercel. Use this skill when the user requests deployment actions such as 'Deploy my app', 'Deploy this to production', 'Create a preview deployment', 'Deploy and...", @@ -7921,7 +8065,7 @@ }, { "id": "vercel-deployment", - "path": "skills/vercel-deployment", + "path": "skills\\vercel-deployment", "category": "uncategorized", "name": "vercel-deployment", "description": "Expert knowledge for deploying to Vercel with Next.js Use when: vercel, deploy, deployment, hosting, production.", @@ -7930,7 +8074,7 @@ }, { "id": "verification-before-completion", - "path": "skills/verification-before-completion", + "path": "skills\\verification-before-completion", "category": "uncategorized", "name": "verification-before-completion", "description": "Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evide...", @@ -7939,7 +8083,7 @@ }, { "id": "vexor", - "path": "skills/vexor", + "path": "skills\\vexor", "category": "uncategorized", "name": "vexor", "description": "Vector-powered CLI for semantic file search with a Claude/Codex skill", @@ -7948,7 +8092,7 @@ }, { "id": "viral-generator-builder", - "path": "skills/viral-generator-builder", + "path": "skills\\viral-generator-builder", "category": "uncategorized", "name": "viral-generator-builder", "description": "Expert in building shareable generator tools that go viral - name generators, quiz makers, avatar creators, personality tests, and calculator tools. Covers the psychology of sharing, viral mechanic...", @@ -7957,7 +8101,7 @@ }, { "id": "voice-agents", - "path": "skills/voice-agents", + "path": "skills\\voice-agents", "category": "uncategorized", "name": "voice-agents", "description": "Voice agents represent the frontier of AI interaction - humans speaking naturally with AI systems. The challenge isn't just speech recognition and synthesis, it's achieving natural conversation flo...", @@ -7966,7 +8110,7 @@ }, { "id": "voice-ai-development", - "path": "skills/voice-ai-development", + "path": "skills\\voice-ai-development", "category": "uncategorized", "name": "voice-ai-development", "description": "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 transcription, ElevenLabs for synthesis...", @@ -7975,7 +8119,7 @@ }, { "id": "voice-ai-engine-development", - "path": "skills/voice-ai-engine-development", + "path": "skills\\voice-ai-engine-development", "category": "uncategorized", "name": "voice-ai-engine-development", "description": "Build real-time conversational AI voice engines using async worker pipelines, streaming transcription, LLM agents, and TTS synthesis with interrupt handling and multi-provider support", @@ -7984,7 +8128,7 @@ }, { "id": "vr-ar", - "path": "skills/game-development/vr-ar", + "path": "skills\\game-development\\vr-ar", "category": "game-development", "name": "vr-ar", "description": "VR/AR development principles. Comfort, interaction, performance requirements.", @@ -7993,7 +8137,7 @@ }, { "id": "vulnerability-scanner", - "path": "skills/vulnerability-scanner", + "path": "skills\\vulnerability-scanner", "category": "uncategorized", "name": "vulnerability-scanner", "description": "Advanced vulnerability analysis principles. OWASP 2025, Supply Chain Security, attack surface mapping, risk prioritization.", @@ -8002,7 +8146,7 @@ }, { "id": "wcag-audit-patterns", - "path": "skills/wcag-audit-patterns", + "path": "skills\\wcag-audit-patterns", "category": "uncategorized", "name": "wcag-audit-patterns", "description": "Conduct WCAG 2.2 accessibility audits with automated testing, manual verification, and remediation guidance. Use when auditing websites for accessibility, fixing WCAG violations, or implementing ac...", @@ -8011,7 +8155,7 @@ }, { "id": "web-artifacts-builder", - "path": "skills/web-artifacts-builder", + "path": "skills\\web-artifacts-builder", "category": "uncategorized", "name": "web-artifacts-builder", "description": "Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state ma...", @@ -8020,7 +8164,7 @@ }, { "id": "web-design-guidelines", - "path": "skills/web-design-guidelines", + "path": "skills\\web-design-guidelines", "category": "uncategorized", "name": "web-design-guidelines", "description": "Review UI code for Web Interface Guidelines compliance. Use when asked to \\\"review my UI\\\", \\\"check accessibility\\\", \\\"audit design\\\", \\\"review UX\\\", or \\\"check my site aga...", @@ -8029,7 +8173,7 @@ }, { "id": "web-games", - "path": "skills/game-development/web-games", + "path": "skills\\game-development\\web-games", "category": "game-development", "name": "web-games", "description": "Web browser game development principles. Framework selection, WebGPU, optimization, PWA.", @@ -8038,7 +8182,7 @@ }, { "id": "web-performance-optimization", - "path": "skills/web-performance-optimization", + "path": "skills\\web-performance-optimization", "category": "uncategorized", "name": "web-performance-optimization", "description": "Optimize website and web application performance including loading speed, Core Web Vitals, bundle size, caching strategies, and runtime performance", @@ -8047,7 +8191,7 @@ }, { "id": "web-security-testing", - "path": "skills/web-security-testing", + "path": "skills\\web-security-testing", "category": "uncategorized", "name": "web-security-testing", "description": "Web application security testing workflow for OWASP Top 10 vulnerabilities including injection, XSS, authentication flaws, and access control issues.", @@ -8056,7 +8200,7 @@ }, { "id": "web3-testing", - "path": "skills/web3-testing", + "path": "skills\\web3-testing", "category": "uncategorized", "name": "web3-testing", "description": "Test smart contracts comprehensively using Hardhat and Foundry with unit tests, integration tests, and mainnet forking. Use when testing Solidity contracts, setting up blockchain test suites, or va...", @@ -8065,7 +8209,7 @@ }, { "id": "webapp-testing", - "path": "skills/webapp-testing", + "path": "skills\\webapp-testing", "category": "uncategorized", "name": "webapp-testing", "description": "Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browse...", @@ -8074,7 +8218,7 @@ }, { "id": "webflow-automation", - "path": "skills/webflow-automation", + "path": "skills\\webflow-automation", "category": "uncategorized", "name": "webflow-automation", "description": "Automate Webflow CMS collections, site publishing, page management, asset uploads, and ecommerce orders via Rube MCP (Composio). Always search tools first for current schemas.", @@ -8083,7 +8227,7 @@ }, { "id": "whatsapp-automation", - "path": "skills/whatsapp-automation", + "path": "skills\\whatsapp-automation", "category": "uncategorized", "name": "whatsapp-automation", "description": "Automate WhatsApp Business tasks via Rube MCP (Composio): send messages, manage templates, upload media, and handle contacts. Always search tools first for current schemas.", @@ -8092,7 +8236,7 @@ }, { "id": "wiki-architect", - "path": "skills/wiki-architect", + "path": "skills\\wiki-architect", "category": "uncategorized", "name": "wiki-architect", "description": "Analyzes code repositories and generates hierarchical documentation structures with onboarding guides. Use when the user wants to create a wiki, generate documentation, map a codebase structure, or...", @@ -8101,7 +8245,7 @@ }, { "id": "wiki-changelog", - "path": "skills/wiki-changelog", + "path": "skills\\wiki-changelog", "category": "uncategorized", "name": "wiki-changelog", "description": "Analyzes git commit history and generates structured changelogs categorized by change type. Use when the user asks about recent changes, wants a changelog, or needs to understand what changed in th...", @@ -8110,7 +8254,7 @@ }, { "id": "wiki-onboarding", - "path": "skills/wiki-onboarding", + "path": "skills\\wiki-onboarding", "category": "uncategorized", "name": "wiki-onboarding", "description": "Generates two complementary onboarding guides \u2014 a Principal-Level architectural deep-dive and a Zero-to-Hero contributor walkthrough. Use when the user wants onboarding documentation fo...", @@ -8119,7 +8263,7 @@ }, { "id": "wiki-page-writer", - "path": "skills/wiki-page-writer", + "path": "skills\\wiki-page-writer", "category": "uncategorized", "name": "wiki-page-writer", "description": "Generates rich technical documentation pages with dark-mode Mermaid diagrams, source code citations, and first-principles depth. Use when writing documentation, generating wiki pages, creating tech...", @@ -8128,7 +8272,7 @@ }, { "id": "wiki-qa", - "path": "skills/wiki-qa", + "path": "skills\\wiki-qa", "category": "uncategorized", "name": "wiki-qa", "description": "Answers questions about a code repository using source file analysis. Use when the user asks a question about how something works, wants to understand a component, or needs help navigating the code...", @@ -8137,7 +8281,7 @@ }, { "id": "wiki-researcher", - "path": "skills/wiki-researcher", + "path": "skills\\wiki-researcher", "category": "uncategorized", "name": "wiki-researcher", "description": "Conducts multi-turn iterative deep research on specific topics within a codebase with zero tolerance for shallow analysis. Use when the user wants an in-depth investigation, needs to understand how...", @@ -8146,7 +8290,7 @@ }, { "id": "wiki-vitepress", - "path": "skills/wiki-vitepress", + "path": "skills\\wiki-vitepress", "category": "uncategorized", "name": "wiki-vitepress", "description": "Packages generated wiki Markdown into a VitePress static site with dark theme, dark-mode Mermaid diagrams with click-to-zoom, and production build output. Use when the user wants to create a browsa...", @@ -8155,7 +8299,7 @@ }, { "id": "windows-privilege-escalation", - "path": "skills/windows-privilege-escalation", + "path": "skills\\windows-privilege-escalation", "category": "uncategorized", "name": "windows-privilege-escalation", "description": "This skill should be used when the user asks to \"escalate privileges on Windows,\" \"find Windows privesc vectors,\" \"enumerate Windows for privilege escalation,\" \"exploit Windows miscon...", @@ -8164,7 +8308,7 @@ }, { "id": "wireshark-analysis", - "path": "skills/wireshark-analysis", + "path": "skills\\wireshark-analysis", "category": "uncategorized", "name": "wireshark-analysis", "description": "This skill should be used when the user asks to \"analyze network traffic with Wireshark\", \"capture packets for troubleshooting\", \"filter PCAP files\", \"follow TCP/UDP streams\", \"dete...", @@ -8173,7 +8317,7 @@ }, { "id": "wordpress", - "path": "skills/wordpress", + "path": "skills\\wordpress", "category": "uncategorized", "name": "wordpress", "description": "Complete WordPress development workflow covering theme development, plugin creation, WooCommerce integration, performance optimization, and security hardening.", @@ -8182,7 +8326,7 @@ }, { "id": "wordpress-penetration-testing", - "path": "skills/wordpress-penetration-testing", + "path": "skills\\wordpress-penetration-testing", "category": "uncategorized", "name": "wordpress-penetration-testing", "description": "This skill should be used when the user asks to \"pentest WordPress sites\", \"scan WordPress for vulnerabilities\", \"enumerate WordPress users, themes, or plugins\", \"exploit WordPress vu...", @@ -8191,7 +8335,7 @@ }, { "id": "wordpress-plugin-development", - "path": "skills/wordpress-plugin-development", + "path": "skills\\wordpress-plugin-development", "category": "uncategorized", "name": "wordpress-plugin-development", "description": "WordPress plugin development workflow covering plugin architecture, hooks, admin interfaces, REST API, and security best practices.", @@ -8200,7 +8344,7 @@ }, { "id": "wordpress-theme-development", - "path": "skills/wordpress-theme-development", + "path": "skills\\wordpress-theme-development", "category": "uncategorized", "name": "wordpress-theme-development", "description": "WordPress theme development workflow covering theme architecture, template hierarchy, custom post types, block editor support, and responsive design.", @@ -8209,25 +8353,16 @@ }, { "id": "wordpress-woocommerce-development", - "path": "skills/wordpress-woocommerce-development", + "path": "skills\\wordpress-woocommerce-development", "category": "uncategorized", "name": "wordpress-woocommerce-development", "description": "WooCommerce store development workflow covering store setup, payment integration, shipping configuration, and customization.", "risk": "safe", "source": "personal" }, - { - "id": "workflow-patterns", - "path": "skills/workflow-patterns", - "category": "uncategorized", - "name": "Workflow Patterns", - "description": "Guide for implementing tasks using Conductor's TDD workflow, managing phase checkpoints, handling git commits, and executing the verification protocol that ensures quality throughout implementation.", - "risk": "unknown", - "source": "unknown" - }, { "id": "workflow-automation", - "path": "skills/workflow-automation", + "path": "skills\\workflow-automation", "category": "uncategorized", "name": "workflow-automation", "description": "Workflow automation is the infrastructure that makes AI agents reliable. Without durable execution, a network hiccup during a 10-step payment flow means lost money and angry customers. With it, wor...", @@ -8236,16 +8371,25 @@ }, { "id": "workflow-orchestration-patterns", - "path": "skills/workflow-orchestration-patterns", + "path": "skills\\workflow-orchestration-patterns", "category": "uncategorized", "name": "workflow-orchestration-patterns", "description": "Design durable workflows with Temporal for distributed systems. Covers workflow vs activity separation, saga patterns, state management, and determinism constraints. Use when building long-running ...", "risk": "unknown", "source": "community" }, + { + "id": "workflow-patterns", + "path": "skills\\workflow-patterns", + "category": "uncategorized", + "name": "workflow-patterns", + "description": "Use this skill when implementing tasks according to Conductor's TDD\nworkflow, handling phase checkpoints, managing git commits for tasks, or\nunderstanding the verification protocol.\n", + "risk": "unknown", + "source": "community" + }, { "id": "wrike-automation", - "path": "skills/wrike-automation", + "path": "skills\\wrike-automation", "category": "uncategorized", "name": "wrike-automation", "description": "Automate Wrike project management via Rube MCP (Composio): create tasks/folders, manage projects, assign work, and track progress. Always search tools first for current schemas.", @@ -8254,7 +8398,7 @@ }, { "id": "writer", - "path": "skills/libreoffice/writer", + "path": "skills\\libreoffice\\writer", "category": "libreoffice", "name": "writer", "description": "Document creation, format conversion (ODT/DOCX/PDF), mail merge, and automation with LibreOffice Writer.", @@ -8263,7 +8407,7 @@ }, { "id": "writing-plans", - "path": "skills/writing-plans", + "path": "skills\\writing-plans", "category": "uncategorized", "name": "writing-plans", "description": "Use when you have a spec or requirements for a multi-step task, before touching code", @@ -8272,7 +8416,7 @@ }, { "id": "writing-skills", - "path": "skills/writing-skills", + "path": "skills\\writing-skills", "category": "uncategorized", "name": "writing-skills", "description": "Use when creating, updating, or improving agent skills.", @@ -8281,7 +8425,7 @@ }, { "id": "x-article-publisher-skill", - "path": "skills/x-article-publisher-skill", + "path": "skills\\x-article-publisher-skill", "category": "uncategorized", "name": "x-article-publisher-skill", "description": "Publish articles to X/Twitter", @@ -8290,7 +8434,7 @@ }, { "id": "xlsx-official", - "path": "skills/xlsx-official", + "path": "skills\\xlsx-official", "category": "uncategorized", "name": "xlsx-official", "description": "Comprehensive spreadsheet creation, editing, and analysis with support for formulas, formatting, data analysis, and visualization. When Claude needs to work with spreadsheets (.xlsx, .xlsm, .csv, ....", @@ -8299,7 +8443,7 @@ }, { "id": "xss-html-injection", - "path": "skills/xss-html-injection", + "path": "skills\\xss-html-injection", "category": "uncategorized", "name": "xss-html-injection", "description": "This skill should be used when the user asks to \"test for XSS vulnerabilities\", \"perform cross-site scripting attacks\", \"identify HTML injection flaws\", \"exploit client-side injection...", @@ -8308,7 +8452,7 @@ }, { "id": "youtube-automation", - "path": "skills/youtube-automation", + "path": "skills\\youtube-automation", "category": "uncategorized", "name": "youtube-automation", "description": "Automate YouTube tasks via Rube MCP (Composio): upload videos, manage playlists, search content, get analytics, and handle comments. Always search tools first for current schemas.", @@ -8317,7 +8461,7 @@ }, { "id": "youtube-summarizer", - "path": "skills/youtube-summarizer", + "path": "skills\\youtube-summarizer", "category": "uncategorized", "name": "youtube-summarizer", "description": "Extract transcripts from YouTube videos and generate comprehensive, detailed summaries using intelligent analysis frameworks", @@ -8326,7 +8470,7 @@ }, { "id": "zapier-make-patterns", - "path": "skills/zapier-make-patterns", + "path": "skills\\zapier-make-patterns", "category": "uncategorized", "name": "zapier-make-patterns", "description": "No-code automation democratizes workflow building. Zapier and Make (formerly Integromat) let non-developers automate business processes without writing code. But no-code doesn't mean no-complexity ...", @@ -8335,7 +8479,7 @@ }, { "id": "zendesk-automation", - "path": "skills/zendesk-automation", + "path": "skills\\zendesk-automation", "category": "uncategorized", "name": "zendesk-automation", "description": "Automate Zendesk tasks via Rube MCP (Composio): tickets, users, organizations, replies. Always search tools first for current schemas.", @@ -8344,7 +8488,7 @@ }, { "id": "zoho-crm-automation", - "path": "skills/zoho-crm-automation", + "path": "skills\\zoho-crm-automation", "category": "uncategorized", "name": "zoho-crm-automation", "description": "Automate Zoho CRM tasks via Rube MCP (Composio): create/update records, search contacts, manage leads, and convert leads. Always search tools first for current schemas.", @@ -8353,7 +8497,7 @@ }, { "id": "zoom-automation", - "path": "skills/zoom-automation", + "path": "skills\\zoom-automation", "category": "uncategorized", "name": "zoom-automation", "description": "Automate Zoom meeting creation, management, recordings, webinars, and participant tracking via Rube MCP (Composio). Always search tools first for current schemas.", @@ -8362,7 +8506,7 @@ }, { "id": "zustand-store-ts", - "path": "skills/zustand-store-ts", + "path": "skills\\zustand-store-ts", "category": "uncategorized", "name": "zustand-store-ts", "description": "Create Zustand stores with TypeScript, subscribeWithSelector middleware, and proper state/action separation. Use when building React state management, creating global stores, or implementing reacti...", diff --git a/web-app/package-lock.json b/web-app/package-lock.json index 6fa70a2a..e73341be 100644 --- a/web-app/package-lock.json +++ b/web-app/package-lock.json @@ -79,6 +79,7 @@ "integrity": "sha512-CGOfOJqWjg2qW/Mb6zNsDm+u5vFQ8DxXfbM09z69p5Z6+mE1ikP2jUXw+j42Pf1XTYED2Rni5f95npYeuwMDQA==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "@babel/code-frame": "^7.29.0", "@babel/generator": "^7.29.0", @@ -1859,6 +1860,7 @@ "resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.14.tgz", "integrity": "sha512-ilcTH/UniCkMdtexkoCN0bI7pMcJDvmQFPvuPvmEaYA/NSfFTAgdUSLAoVjaRJm7+6PvcM+q1zYOwS4wTYMF9w==", "license": "MIT", + "peer": true, "dependencies": { "csstype": "^3.2.2" } @@ -1921,6 +1923,7 @@ "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==", "dev": true, "license": "MIT", + "peer": true, "bin": { "acorn": "bin/acorn" }, @@ -2073,6 +2076,7 @@ } ], "license": "MIT", + "peer": true, "dependencies": { "baseline-browser-mapping": "^2.9.0", "caniuse-lite": "^1.0.30001759", @@ -2433,6 +2437,7 @@ "integrity": "sha512-LEyamqS7W5HB3ujJyvi0HQK/dtVINZvd5mAAp9eT5S/ujByGjiZLCzPcHVzuXbpJDJF/cxwHlfceVUDZ2lnSTw==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "@eslint-community/eslint-utils": "^4.8.0", "@eslint-community/regexpp": "^4.12.1", @@ -4250,6 +4255,7 @@ "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==", "dev": true, "license": "MIT", + "peer": true, "engines": { "node": ">=12" }, @@ -4277,6 +4283,7 @@ } ], "license": "MIT", + "peer": true, "dependencies": { "nanoid": "^3.3.11", "picocolors": "^1.1.1", @@ -4328,6 +4335,7 @@ "resolved": "https://registry.npmjs.org/react/-/react-19.2.4.tgz", "integrity": "sha512-9nfp2hYpCwOjAN+8TZFGhtWEwgvWHXqESH8qT89AT/lWklpLON22Lc8pEtnpsZz7VmawabSU0gCjnj8aC0euHQ==", "license": "MIT", + "peer": true, "engines": { "node": ">=0.10.0" } @@ -4337,6 +4345,7 @@ "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.2.4.tgz", "integrity": "sha512-AXJdLo8kgMbimY95O2aKQqsz2iWi9jMgKJhRBAxECE4IFxfcazB2LmzloIoibJI3C12IlY20+KFaLv+71bUJeQ==", "license": "MIT", + "peer": true, "dependencies": { "scheduler": "^0.27.0" }, @@ -4885,6 +4894,7 @@ "integrity": "sha512-w+N7Hifpc3gRjZ63vYBXA56dvvRlNWRczTdmCBBa+CotUzAPf5b7YMdMR/8CQoeYE5LX3W4wj6RYTgonm1b9DA==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "esbuild": "^0.27.0", "fdir": "^6.5.0", @@ -5027,6 +5037,7 @@ "integrity": "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg==", "dev": true, "license": "MIT", + "peer": true, "funding": { "url": "https://github.com/sponsors/colinhacks" } diff --git a/web-app/public/skills.json b/web-app/public/skills.json index 10357d7e..c0ffd8e0 100644 --- a/web-app/public/skills.json +++ b/web-app/public/skills.json @@ -1,7 +1,25 @@ [ + { + "id": "00-andruia-consultant", + "path": "skills\\00-andruia-consultant", + "category": "uncategorized", + "name": "00-andruia-consultant", + "description": "Arquitecto de Soluciones Principal y Consultor Tecnol\u00f3gico de Andru.ia. Diagnostica y traza la hoja de ruta \u00f3ptima para proyectos de IA en espa\u00f1ol.", + "risk": "safe", + "source": "personal" + }, + { + "id": "20-andruia-niche-intelligence", + "path": "skills\\20-andruia-niche-intelligence", + "category": "uncategorized", + "name": "20-andruia-niche-intelligence", + "description": "Estratega de Inteligencia de Dominio de Andru.ia. Analiza el nicho espec\u00edfico de un proyecto para inyectar conocimientos, regulaciones y est\u00e1ndares \u00fanicos del sector. Act\u00edvalo tras definir el nicho.", + "risk": "safe", + "source": "personal" + }, { "id": "2d-games", - "path": "skills/game-development/2d-games", + "path": "skills\\game-development\\2d-games", "category": "game-development", "name": "2d-games", "description": "2D game development principles. Sprites, tilemaps, physics, camera.", @@ -10,7 +28,7 @@ }, { "id": "3d-games", - "path": "skills/game-development/3d-games", + "path": "skills\\game-development\\3d-games", "category": "game-development", "name": "3d-games", "description": "3D game development principles. Rendering, shaders, physics, cameras.", @@ -19,7 +37,7 @@ }, { "id": "3d-web-experience", - "path": "skills/3d-web-experience", + "path": "skills\\3d-web-experience", "category": "uncategorized", "name": "3d-web-experience", "description": "Expert in building 3D experiences for the web - Three.js, React Three Fiber, Spline, WebGL, and interactive 3D scenes. Covers product configurators, 3D portfolios, immersive websites, and bringing ...", @@ -28,7 +46,7 @@ }, { "id": "ab-test-setup", - "path": "skills/ab-test-setup", + "path": "skills\\ab-test-setup", "category": "uncategorized", "name": "ab-test-setup", "description": "Structured guide for setting up A/B tests with mandatory gates for hypothesis, metrics, and execution readiness.", @@ -37,7 +55,7 @@ }, { "id": "accessibility-compliance-accessibility-audit", - "path": "skills/accessibility-compliance-accessibility-audit", + "path": "skills\\accessibility-compliance-accessibility-audit", "category": "uncategorized", "name": "accessibility-compliance-accessibility-audit", "description": "You are an accessibility expert specializing in WCAG compliance, inclusive design, and assistive technology compatibility. Conduct audits, identify barriers, and provide remediation guidance.", @@ -46,7 +64,7 @@ }, { "id": "active-directory-attacks", - "path": "skills/active-directory-attacks", + "path": "skills\\active-directory-attacks", "category": "uncategorized", "name": "active-directory-attacks", "description": "This skill should be used when the user asks to \"attack Active Directory\", \"exploit AD\", \"Kerberoasting\", \"DCSync\", \"pass-the-hash\", \"BloodHound enumeration\", \"Golden Ticket\", ...", @@ -55,7 +73,7 @@ }, { "id": "activecampaign-automation", - "path": "skills/activecampaign-automation", + "path": "skills\\activecampaign-automation", "category": "uncategorized", "name": "activecampaign-automation", "description": "Automate ActiveCampaign tasks via Rube MCP (Composio): manage contacts, tags, list subscriptions, automation enrollment, and tasks. Always search tools first for current schemas.", @@ -64,7 +82,7 @@ }, { "id": "address-github-comments", - "path": "skills/address-github-comments", + "path": "skills\\address-github-comments", "category": "uncategorized", "name": "address-github-comments", "description": "Use when you need to address review or issue comments on an open GitHub Pull Request using the gh CLI.", @@ -73,7 +91,7 @@ }, { "id": "agent-evaluation", - "path": "skills/agent-evaluation", + "path": "skills\\agent-evaluation", "category": "uncategorized", "name": "agent-evaluation", "description": "Testing and benchmarking LLM agents including behavioral testing, capability assessment, reliability metrics, and production monitoring\u2014where even top agents achieve less than 50% on re...", @@ -82,7 +100,7 @@ }, { "id": "agent-framework-azure-ai-py", - "path": "skills/agent-framework-azure-ai-py", + "path": "skills\\agent-framework-azure-ai-py", "category": "uncategorized", "name": "agent-framework-azure-ai-py", "description": "Build Azure AI Foundry agents using the Microsoft Agent Framework Python SDK (agent-framework-azure-ai). Use when creating persistent agents with AzureAIAgentsProvider, using hosted tools (code int...", @@ -91,7 +109,7 @@ }, { "id": "agent-manager-skill", - "path": "skills/agent-manager-skill", + "path": "skills\\agent-manager-skill", "category": "uncategorized", "name": "agent-manager-skill", "description": "Manage multiple local CLI agents via tmux sessions (start/stop/monitor/assign) with cron-friendly scheduling.", @@ -100,7 +118,7 @@ }, { "id": "agent-memory-mcp", - "path": "skills/agent-memory-mcp", + "path": "skills\\agent-memory-mcp", "category": "uncategorized", "name": "agent-memory-mcp", "description": "A hybrid memory system that provides persistent, searchable knowledge management for AI agents (Architecture, Patterns, Decisions).", @@ -109,7 +127,7 @@ }, { "id": "agent-memory-systems", - "path": "skills/agent-memory-systems", + "path": "skills\\agent-memory-systems", "category": "uncategorized", "name": "agent-memory-systems", "description": "Memory is the cornerstone of intelligent agents. Without it, every interaction starts from zero. This skill covers the architecture of agent memory: short-term (context window), long-term (vector s...", @@ -118,7 +136,7 @@ }, { "id": "agent-orchestration-improve-agent", - "path": "skills/agent-orchestration-improve-agent", + "path": "skills\\agent-orchestration-improve-agent", "category": "uncategorized", "name": "agent-orchestration-improve-agent", "description": "Systematic improvement of existing agents through performance analysis, prompt engineering, and continuous iteration.", @@ -127,7 +145,7 @@ }, { "id": "agent-orchestration-multi-agent-optimize", - "path": "skills/agent-orchestration-multi-agent-optimize", + "path": "skills\\agent-orchestration-multi-agent-optimize", "category": "uncategorized", "name": "agent-orchestration-multi-agent-optimize", "description": "Optimize multi-agent systems with coordinated profiling, workload distribution, and cost-aware orchestration. Use when improving agent performance, throughput, or reliability.", @@ -136,34 +154,34 @@ }, { "id": "agent-tool-builder", - "path": "skills/agent-tool-builder", + "path": "skills\\agent-tool-builder", "category": "uncategorized", "name": "agent-tool-builder", "description": "Tools are how AI agents interact with the world. A well-designed tool is the difference between an agent that works and one that hallucinates, fails silently, or costs 10x more tokens than necessar...", "risk": "unknown", "source": "vibeship-spawner-skills (Apache 2.0)" }, + { + "id": "agentfolio", + "path": "skills\\agentfolio", + "category": "uncategorized", + "name": "agentfolio", + "description": "Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.", + "risk": "unknown", + "source": "agentfolio.io" + }, { "id": "agents-v2-py", - "path": "skills/agents-v2-py", + "path": "skills\\agents-v2-py", "category": "uncategorized", "name": "agents-v2-py", "description": "Build container-based Foundry Agents with Azure AI Projects SDK (ImageBasedHostedAgentDefinition). Use when creating hosted agents with custom container images in Azure AI Foundry.", "risk": "unknown", "source": "community" }, - { - "id": "ai-engineer", - "path": "skills/ai-engineer", - "category": "uncategorized", - "name": "Ai Engineer", - "description": "You are an AI engineer specializing in production-grade LLM applications, generative AI systems, and intelligent agent architectures.", - "risk": "unknown", - "source": "unknown" - }, { "id": "ai-agent-development", - "path": "skills/ai-agent-development", + "path": "skills\\ai-agent-development", "category": "uncategorized", "name": "ai-agent-development", "description": "AI agent development workflow for building autonomous agents, multi-agent systems, and agent orchestration with CrewAI, LangGraph, and custom agents.", @@ -172,16 +190,25 @@ }, { "id": "ai-agents-architect", - "path": "skills/ai-agents-architect", + "path": "skills\\ai-agents-architect", "category": "uncategorized", "name": "ai-agents-architect", "description": "Expert in designing and building autonomous AI agents. Masters tool use, memory systems, planning strategies, and multi-agent orchestration. Use when: build agent, AI agent, autonomous agent, tool ...", "risk": "unknown", "source": "vibeship-spawner-skills (Apache 2.0)" }, + { + "id": "ai-engineer", + "path": "skills\\ai-engineer", + "category": "uncategorized", + "name": "ai-engineer", + "description": "Build production-ready LLM applications, advanced RAG systems, and\nintelligent agents. Implements vector search, multimodal AI, agent\norchestration, and enterprise AI integrations. Use PROACTIVELY for LLM\nfeatures, chatbots, AI agents, or AI-powered applications.\n", + "risk": "unknown", + "source": "community" + }, { "id": "ai-ml", - "path": "skills/ai-ml", + "path": "skills\\ai-ml", "category": "uncategorized", "name": "ai-ml", "description": "AI and machine learning workflow covering LLM application development, RAG implementation, agent architecture, ML pipelines, and AI-powered features.", @@ -190,7 +217,7 @@ }, { "id": "ai-product", - "path": "skills/ai-product", + "path": "skills\\ai-product", "category": "uncategorized", "name": "ai-product", "description": "Every product will be AI-powered. The question is whether you'll build it right or ship a demo that falls apart in production. This skill covers LLM integration patterns, RAG architecture, prompt ...", @@ -199,7 +226,7 @@ }, { "id": "ai-wrapper-product", - "path": "skills/ai-wrapper-product", + "path": "skills\\ai-wrapper-product", "category": "uncategorized", "name": "ai-wrapper-product", "description": "Expert in building products that wrap AI APIs (OpenAI, Anthropic, etc.) into focused tools people will pay for. Not just 'ChatGPT but different' - products that solve specific problems with AI. Cov...", @@ -208,7 +235,7 @@ }, { "id": "airflow-dag-patterns", - "path": "skills/airflow-dag-patterns", + "path": "skills\\airflow-dag-patterns", "category": "uncategorized", "name": "airflow-dag-patterns", "description": "Build production Apache Airflow DAGs with best practices for operators, sensors, testing, and deployment. Use when creating data pipelines, orchestrating workflows, or scheduling batch jobs.", @@ -217,7 +244,7 @@ }, { "id": "airtable-automation", - "path": "skills/airtable-automation", + "path": "skills\\airtable-automation", "category": "uncategorized", "name": "airtable-automation", "description": "Automate Airtable tasks via Rube MCP (Composio): records, bases, tables, fields, views. Always search tools first for current schemas.", @@ -226,7 +253,7 @@ }, { "id": "algolia-search", - "path": "skills/algolia-search", + "path": "skills\\algolia-search", "category": "uncategorized", "name": "algolia-search", "description": "Expert patterns for Algolia search implementation, indexing strategies, React InstantSearch, and relevance tuning Use when: adding search to, algolia, instantsearch, search api, search functionality.", @@ -235,7 +262,7 @@ }, { "id": "algorithmic-art", - "path": "skills/algorithmic-art", + "path": "skills\\algorithmic-art", "category": "uncategorized", "name": "algorithmic-art", "description": "Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields,...", @@ -244,7 +271,7 @@ }, { "id": "amplitude-automation", - "path": "skills/amplitude-automation", + "path": "skills\\amplitude-automation", "category": "uncategorized", "name": "amplitude-automation", "description": "Automate Amplitude tasks via Rube MCP (Composio): events, user activity, cohorts, user identification. Always search tools first for current schemas.", @@ -253,16 +280,16 @@ }, { "id": "analytics-tracking", - "path": "skills/analytics-tracking", + "path": "skills\\analytics-tracking", "category": "uncategorized", - "name": "Analytics Tracking", - "description": "You are an expert in **analytics implementation and measurement design**. Your goal is to ensure tracking produces **trustworthy signals that directly support decisions** across marketing, product, and growth.", + "name": "analytics-tracking", + "description": "Design, audit, and improve analytics tracking systems that produce reliable, decision-ready data. Use when the user wants to set up, fix, or evaluate analytics tracking (GA4, GTM, product analytics, events, conversions, UTMs). This skill focuses on measurement strategy, signal quality, and validation\u2014 not just firing events.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "android-jetpack-compose-expert", - "path": "skills/android-jetpack-compose-expert", + "path": "skills\\android-jetpack-compose-expert", "category": "uncategorized", "name": "android-jetpack-compose-expert", "description": "Expert guidance for building modern Android UIs with Jetpack Compose, covering state management, navigation, performance, and Material Design 3.", @@ -271,16 +298,16 @@ }, { "id": "angular", - "path": "skills/angular", + "path": "skills\\angular", "category": "uncategorized", - "name": "Angular", - "description": "Master modern Angular development with Signals, Standalone Components, Zoneless applications, SSR/Hydration, and the latest reactive patterns.", - "risk": "unknown", - "source": "unknown" + "name": "angular", + "description": "Modern Angular (v20+) expert with deep knowledge of Signals, Standalone Components, Zoneless applications, SSR/Hydration, and reactive patterns. Use PROACTIVELY for Angular development, component architecture, state management, performance optimization, and migration to modern patterns.", + "risk": "safe", + "source": "self" }, { "id": "angular-best-practices", - "path": "skills/angular-best-practices", + "path": "skills\\angular-best-practices", "category": "uncategorized", "name": "angular-best-practices", "description": "Angular performance optimization and best practices guide. Use when writing, reviewing, or refactoring Angular code for optimal performance, bundle size, and rendering efficiency.", @@ -289,7 +316,7 @@ }, { "id": "angular-migration", - "path": "skills/angular-migration", + "path": "skills\\angular-migration", "category": "uncategorized", "name": "angular-migration", "description": "Migrate from AngularJS to Angular using hybrid mode, incremental component rewriting, and dependency injection updates. Use when upgrading AngularJS applications, planning framework migrations, or ...", @@ -298,7 +325,7 @@ }, { "id": "angular-state-management", - "path": "skills/angular-state-management", + "path": "skills\\angular-state-management", "category": "uncategorized", "name": "angular-state-management", "description": "Master modern Angular state management with Signals, NgRx, and RxJS. Use when setting up global state, managing component stores, choosing between state solutions, or migrating from legacy patterns.", @@ -307,7 +334,7 @@ }, { "id": "angular-ui-patterns", - "path": "skills/angular-ui-patterns", + "path": "skills\\angular-ui-patterns", "category": "uncategorized", "name": "angular-ui-patterns", "description": "Modern Angular UI patterns for loading states, error handling, and data display. Use when building UI components, handling async data, or managing component states.", @@ -316,7 +343,7 @@ }, { "id": "anti-reversing-techniques", - "path": "skills/anti-reversing-techniques", + "path": "skills\\anti-reversing-techniques", "category": "uncategorized", "name": "anti-reversing-techniques", "description": "Understand anti-reversing, obfuscation, and protection techniques encountered during software analysis. Use when analyzing protected binaries, bypassing anti-debugging for authorized analysis, or u...", @@ -325,25 +352,16 @@ }, { "id": "antigravity-workflows", - "path": "skills/antigravity-workflows", + "path": "skills\\antigravity-workflows", "category": "uncategorized", "name": "antigravity-workflows", "description": "Orchestrate multiple Antigravity skills through guided workflows for SaaS MVP delivery, security audits, AI agent builds, and browser QA.", "risk": "none", "source": "self" }, - { - "id": "api-documenter", - "path": "skills/api-documenter", - "category": "uncategorized", - "name": "Api Documenter", - "description": "You are an expert API documentation specialist mastering modern developer experience through comprehensive, interactive, and AI-enhanced documentation.", - "risk": "unknown", - "source": "unknown" - }, { "id": "api-design-principles", - "path": "skills/api-design-principles", + "path": "skills\\api-design-principles", "category": "uncategorized", "name": "api-design-principles", "description": "Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers. Use when designing new APIs, reviewing API specifications, or establishing...", @@ -352,7 +370,7 @@ }, { "id": "api-documentation", - "path": "skills/api-documentation", + "path": "skills\\api-documentation", "category": "uncategorized", "name": "api-documentation", "description": "API documentation workflow for generating OpenAPI specs, creating developer guides, and maintaining comprehensive API documentation.", @@ -361,16 +379,25 @@ }, { "id": "api-documentation-generator", - "path": "skills/api-documentation-generator", + "path": "skills\\api-documentation-generator", "category": "uncategorized", "name": "api-documentation-generator", "description": "Generate comprehensive, developer-friendly API documentation from code, including endpoints, parameters, examples, and best practices", "risk": "unknown", "source": "community" }, + { + "id": "api-documenter", + "path": "skills\\api-documenter", + "category": "uncategorized", + "name": "api-documenter", + "description": "Master API documentation with OpenAPI 3.1, AI-powered tools, and\nmodern developer experience practices. Create interactive docs, generate SDKs,\nand build comprehensive developer portals. Use PROACTIVELY for API\ndocumentation or developer portal creation.\n", + "risk": "unknown", + "source": "community" + }, { "id": "api-fuzzing-bug-bounty", - "path": "skills/api-fuzzing-bug-bounty", + "path": "skills\\api-fuzzing-bug-bounty", "category": "uncategorized", "name": "api-fuzzing-bug-bounty", "description": "This skill should be used when the user asks to \"test API security\", \"fuzz APIs\", \"find IDOR vulnerabilities\", \"test REST API\", \"test GraphQL\", \"API penetration testing\", \"bug b...", @@ -379,7 +406,7 @@ }, { "id": "api-patterns", - "path": "skills/api-patterns", + "path": "skills\\api-patterns", "category": "uncategorized", "name": "api-patterns", "description": "API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination.", @@ -388,7 +415,7 @@ }, { "id": "api-security-best-practices", - "path": "skills/api-security-best-practices", + "path": "skills\\api-security-best-practices", "category": "uncategorized", "name": "api-security-best-practices", "description": "Implement secure API design patterns including authentication, authorization, input validation, rate limiting, and protection against common API vulnerabilities", @@ -397,7 +424,7 @@ }, { "id": "api-security-testing", - "path": "skills/api-security-testing", + "path": "skills\\api-security-testing", "category": "uncategorized", "name": "api-security-testing", "description": "API security testing workflow for REST and GraphQL APIs covering authentication, authorization, rate limiting, input validation, and security best practices.", @@ -406,7 +433,7 @@ }, { "id": "api-testing-observability-api-mock", - "path": "skills/api-testing-observability-api-mock", + "path": "skills\\api-testing-observability-api-mock", "category": "uncategorized", "name": "api-testing-observability-api-mock", "description": "You are an API mocking expert specializing in realistic mock services for development, testing, and demos. Design mocks that simulate real API behavior and enable parallel development.", @@ -415,7 +442,7 @@ }, { "id": "app-builder", - "path": "skills/app-builder", + "path": "skills\\app-builder", "category": "uncategorized", "name": "app-builder", "description": "Main application building orchestrator. Creates full-stack applications from natural language requests. Determines project type, selects tech stack, coordinates agents.", @@ -424,16 +451,25 @@ }, { "id": "app-store-optimization", - "path": "skills/app-store-optimization", + "path": "skills\\app-store-optimization", "category": "uncategorized", "name": "app-store-optimization", "description": "Complete App Store Optimization (ASO) toolkit for researching, optimizing, and tracking mobile app performance on Apple App Store and Google Play Store", "risk": "unknown", "source": "community" }, + { + "id": "appdeploy", + "path": "skills\\appdeploy", + "category": "uncategorized", + "name": "appdeploy", + "description": "Deploy web apps with backend APIs, database, and file storage. Use when the user asks to deploy or publish a website or web app and wants a public URL. Uses HTTP API via curl.", + "risk": "safe", + "source": "AppDeploy (MIT)" + }, { "id": "application-performance-performance-optimization", - "path": "skills/application-performance-performance-optimization", + "path": "skills\\application-performance-performance-optimization", "category": "uncategorized", "name": "application-performance-performance-optimization", "description": "Optimize end-to-end application performance with profiling, observability, and backend/frontend tuning. Use when coordinating performance optimization across the stack.", @@ -442,7 +478,7 @@ }, { "id": "architect-review", - "path": "skills/architect-review", + "path": "skills\\architect-review", "category": "uncategorized", "name": "architect-review", "description": "Master software architect specializing in modern architecture patterns, clean architecture, microservices, event-driven systems, and DDD. Reviews system designs and code changes for architectural integrity, scalability, and maintainability. Use PROACTIVELY for architectural decisions.", @@ -451,7 +487,7 @@ }, { "id": "architecture", - "path": "skills/architecture", + "path": "skills\\architecture", "category": "uncategorized", "name": "architecture", "description": "Architectural decision-making framework. Requirements analysis, trade-off evaluation, ADR documentation. Use when making architecture decisions or analyzing system design.", @@ -460,7 +496,7 @@ }, { "id": "architecture-decision-records", - "path": "skills/architecture-decision-records", + "path": "skills\\architecture-decision-records", "category": "uncategorized", "name": "architecture-decision-records", "description": "Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation. Use when documenting significant technical decisions, reviewing past architect...", @@ -469,7 +505,7 @@ }, { "id": "architecture-patterns", - "path": "skills/architecture-patterns", + "path": "skills\\architecture-patterns", "category": "uncategorized", "name": "architecture-patterns", "description": "Implement proven backend architecture patterns including Clean Architecture, Hexagonal Architecture, and Domain-Driven Design. Use when architecting complex backend systems or refactoring existing ...", @@ -478,16 +514,16 @@ }, { "id": "arm-cortex-expert", - "path": "skills/arm-cortex-expert", + "path": "skills\\arm-cortex-expert", "category": "uncategorized", - "name": "Arm Cortex Expert", - "description": "- Working on @arm-cortex-expert tasks or workflows - Needing guidance, best practices, or checklists for @arm-cortex-expert", + "name": "arm-cortex-expert", + "description": "Senior embedded software engineer specializing in firmware and driver development for ARM Cortex-M microcontrollers (Teensy, STM32, nRF52, SAMD). Decades of experience writing reliable, optimized, and maintainable embedded code with deep expertise in memory barriers, DMA/cache coherency, interrupt-driven I/O, and peripheral drivers.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "asana-automation", - "path": "skills/asana-automation", + "path": "skills\\asana-automation", "category": "uncategorized", "name": "asana-automation", "description": "Automate Asana tasks via Rube MCP (Composio): tasks, projects, sections, teams, workspaces. Always search tools first for current schemas.", @@ -496,7 +532,7 @@ }, { "id": "async-python-patterns", - "path": "skills/async-python-patterns", + "path": "skills\\async-python-patterns", "category": "uncategorized", "name": "async-python-patterns", "description": "Master Python asyncio, concurrent programming, and async/await patterns for high-performance applications. Use when building async APIs, concurrent systems, or I/O-bound applications requiring non-...", @@ -505,7 +541,7 @@ }, { "id": "attack-tree-construction", - "path": "skills/attack-tree-construction", + "path": "skills\\attack-tree-construction", "category": "uncategorized", "name": "attack-tree-construction", "description": "Build comprehensive attack trees to visualize threat paths. Use when mapping attack scenarios, identifying defense gaps, or communicating security risks to stakeholders.", @@ -514,7 +550,7 @@ }, { "id": "audio-transcriber", - "path": "skills/audio-transcriber", + "path": "skills\\audio-transcriber", "category": "uncategorized", "name": "audio-transcriber", "description": "Transform audio recordings into professional Markdown documentation with intelligent summaries using LLM integration", @@ -523,7 +559,7 @@ }, { "id": "auth-implementation-patterns", - "path": "skills/auth-implementation-patterns", + "path": "skills\\auth-implementation-patterns", "category": "uncategorized", "name": "auth-implementation-patterns", "description": "Master authentication and authorization patterns including JWT, OAuth2, session management, and RBAC to build secure, scalable access control systems. Use when implementing auth systems, securing A...", @@ -532,7 +568,7 @@ }, { "id": "automate-whatsapp", - "path": "skills/automate-whatsapp", + "path": "skills\\automate-whatsapp", "category": "uncategorized", "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 automatin...", @@ -541,7 +577,7 @@ }, { "id": "autonomous-agent-patterns", - "path": "skills/autonomous-agent-patterns", + "path": "skills\\autonomous-agent-patterns", "category": "uncategorized", "name": "autonomous-agent-patterns", "description": "Design patterns for building autonomous coding agents. Covers tool integration, permission systems, browser automation, and human-in-the-loop workflows. Use when building AI agents, designing tool ...", @@ -550,7 +586,7 @@ }, { "id": "autonomous-agents", - "path": "skills/autonomous-agents", + "path": "skills\\autonomous-agents", "category": "uncategorized", "name": "autonomous-agents", "description": "Autonomous agents are AI systems that can independently decompose goals, plan actions, execute tools, and self-correct without constant human guidance. The challenge isn't making them capable - it'...", @@ -559,7 +595,7 @@ }, { "id": "avalonia-layout-zafiro", - "path": "skills/avalonia-layout-zafiro", + "path": "skills\\avalonia-layout-zafiro", "category": "uncategorized", "name": "avalonia-layout-zafiro", "description": "Guidelines for modern Avalonia UI layout using Zafiro.Avalonia, emphasizing shared styles, generic components, and avoiding XAML redundancy.", @@ -568,7 +604,7 @@ }, { "id": "avalonia-viewmodels-zafiro", - "path": "skills/avalonia-viewmodels-zafiro", + "path": "skills\\avalonia-viewmodels-zafiro", "category": "uncategorized", "name": "avalonia-viewmodels-zafiro", "description": "Optimal ViewModel and Wizard creation patterns for Avalonia using Zafiro and ReactiveUI.", @@ -577,7 +613,7 @@ }, { "id": "avalonia-zafiro-development", - "path": "skills/avalonia-zafiro-development", + "path": "skills\\avalonia-zafiro-development", "category": "uncategorized", "name": "avalonia-zafiro-development", "description": "Mandatory skills, conventions, and behavioral rules for Avalonia UI development using the Zafiro toolkit.", @@ -586,7 +622,7 @@ }, { "id": "aws-compliance-checker", - "path": "skills/security/aws-compliance-checker", + "path": "skills\\security\\aws-compliance-checker", "category": "security", "name": "aws-compliance-checker", "description": "Automated compliance checking against CIS, PCI-DSS, HIPAA, and SOC 2 benchmarks", @@ -595,7 +631,7 @@ }, { "id": "aws-cost-cleanup", - "path": "skills/aws-cost-cleanup", + "path": "skills\\aws-cost-cleanup", "category": "uncategorized", "name": "aws-cost-cleanup", "description": "Automated cleanup of unused AWS resources to reduce costs", @@ -604,7 +640,7 @@ }, { "id": "aws-cost-optimizer", - "path": "skills/aws-cost-optimizer", + "path": "skills\\aws-cost-optimizer", "category": "uncategorized", "name": "aws-cost-optimizer", "description": "Comprehensive AWS cost analysis and optimization recommendations using AWS CLI and Cost Explorer", @@ -613,7 +649,7 @@ }, { "id": "aws-iam-best-practices", - "path": "skills/security/aws-iam-best-practices", + "path": "skills\\security\\aws-iam-best-practices", "category": "security", "name": "aws-iam-best-practices", "description": "IAM policy review, hardening, and least privilege implementation", @@ -622,7 +658,7 @@ }, { "id": "aws-penetration-testing", - "path": "skills/aws-penetration-testing", + "path": "skills\\aws-penetration-testing", "category": "uncategorized", "name": "aws-penetration-testing", "description": "This skill should be used when the user asks to \"pentest AWS\", \"test AWS security\", \"enumerate IAM\", \"exploit cloud infrastructure\", \"AWS privilege escalation\", \"S3 bucket testing...", @@ -631,7 +667,7 @@ }, { "id": "aws-secrets-rotation", - "path": "skills/security/aws-secrets-rotation", + "path": "skills\\security\\aws-secrets-rotation", "category": "security", "name": "aws-secrets-rotation", "description": "Automate AWS secrets rotation for RDS, API keys, and credentials", @@ -640,7 +676,7 @@ }, { "id": "aws-security-audit", - "path": "skills/security/aws-security-audit", + "path": "skills\\security\\aws-security-audit", "category": "security", "name": "aws-security-audit", "description": "Comprehensive AWS security posture assessment using AWS CLI and security best practices", @@ -649,7 +685,7 @@ }, { "id": "aws-serverless", - "path": "skills/aws-serverless", + "path": "skills\\aws-serverless", "category": "uncategorized", "name": "aws-serverless", "description": "Specialized skill for building production-ready serverless applications on AWS. Covers Lambda functions, API Gateway, DynamoDB, SQS/SNS event-driven patterns, SAM/CDK deployment, and cold start opt...", @@ -658,7 +694,7 @@ }, { "id": "aws-skills", - "path": "skills/aws-skills", + "path": "skills\\aws-skills", "category": "uncategorized", "name": "aws-skills", "description": "AWS development with infrastructure automation and cloud architecture patterns", @@ -667,7 +703,7 @@ }, { "id": "azd-deployment", - "path": "skills/azd-deployment", + "path": "skills\\azd-deployment", "category": "uncategorized", "name": "azd-deployment", "description": "Deploy containerized applications to Azure Container Apps using Azure Developer CLI (azd). Use when setting up azd projects, writing azure.yaml configuration, creating Bicep infrastructure for Cont...", @@ -676,727 +712,25 @@ }, { "id": "azure-ai-agents-persistent-dotnet", - "path": "skills/azure-ai-agents-persistent-dotnet", + "path": "skills\\azure-ai-agents-persistent-dotnet", "category": "uncategorized", - "name": "Azure Ai Agents Persistent Dotnet", - "description": "Low-level SDK for creating and managing persistent AI agents with threads, messages, runs, and tools.", + "name": "azure-ai-agents-persistent-dotnet", + "description": "Azure AI Agents Persistent SDK for .NET. Low-level SDK for creating and managing AI agents with threads, messages, runs, and tools. Use for agent CRUD, conversation threads, streaming responses, function calling, file search, and code interpreter. Triggers: \"PersistentAgentsClient\", \"persistent agents\", \"agent threads\", \"agent runs\", \"streaming agents\", \"function calling agents .NET\".\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "azure-ai-agents-persistent-java", - "path": "skills/azure-ai-agents-persistent-java", + "path": "skills\\azure-ai-agents-persistent-java", "category": "uncategorized", - "name": "Azure Ai Agents Persistent Java", - "description": "Low-level SDK for creating and managing persistent AI agents with threads, messages, runs, and tools.", + "name": "azure-ai-agents-persistent-java", + "description": "Azure AI Agents Persistent SDK for Java. Low-level SDK for creating and managing AI agents with threads, messages, runs, and tools.\nTriggers: \"PersistentAgentsClient\", \"persistent agents java\", \"agent threads java\", \"agent runs java\", \"streaming agents java\".\n", "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-ai-contentsafety-py", - "path": "skills/azure-ai-contentsafety-py", - "category": "uncategorized", - "name": "Azure Ai Contentsafety Py", - "description": "Detect harmful user-generated and AI-generated content in applications.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-ai-contentunderstanding-py", - "path": "skills/azure-ai-contentunderstanding-py", - "category": "uncategorized", - "name": "Azure Ai Contentunderstanding Py", - "description": "Multimodal AI service that extracts semantic content from documents, video, audio, and image files for RAG and automated workflows.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-ai-document-intelligence-dotnet", - "path": "skills/azure-ai-document-intelligence-dotnet", - "category": "uncategorized", - "name": "Azure Ai Document Intelligence Dotnet", - "description": "Extract text, tables, and structured data from documents using prebuilt and custom models.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-ai-ml-py", - "path": "skills/azure-ai-ml-py", - "category": "uncategorized", - "name": "Azure Ai Ml Py", - "description": "Client library for managing Azure ML resources: workspaces, jobs, models, data, and compute.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-ai-openai-dotnet", - "path": "skills/azure-ai-openai-dotnet", - "category": "uncategorized", - "name": "Azure Ai Openai Dotnet", - "description": "Client library for Azure OpenAI Service providing access to OpenAI models including GPT-4, GPT-4o, embeddings, DALL-E, and Whisper.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-ai-projects-dotnet", - "path": "skills/azure-ai-projects-dotnet", - "category": "uncategorized", - "name": "Azure Ai Projects Dotnet", - "description": "High-level SDK for Azure AI Foundry project operations including agents, connections, datasets, deployments, evaluations, and indexes.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-ai-projects-java", - "path": "skills/azure-ai-projects-java", - "category": "uncategorized", - "name": "Azure Ai Projects Java", - "description": "High-level SDK for Azure AI Foundry project management with access to connections, datasets, indexes, and evaluations.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-ai-textanalytics-py", - "path": "skills/azure-ai-textanalytics-py", - "category": "uncategorized", - "name": "Azure Ai Textanalytics Py", - "description": "Client library for Azure AI Language service NLP capabilities including sentiment, entities, key phrases, and more.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-ai-transcription-py", - "path": "skills/azure-ai-transcription-py", - "category": "uncategorized", - "name": "Azure Ai Transcription Py", - "description": "Client library for Azure AI Transcription (speech-to-text) with real-time and batch transcription.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-ai-translation-document-py", - "path": "skills/azure-ai-translation-document-py", - "category": "uncategorized", - "name": "Azure Ai Translation Document Py", - "description": "Client library for Azure AI Translator document translation service for batch document translation with format preservation.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-ai-translation-text-py", - "path": "skills/azure-ai-translation-text-py", - "category": "uncategorized", - "name": "Azure Ai Translation Text Py", - "description": "Client library for Azure AI Translator text translation service for real-time text translation, transliteration, and language operations.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-ai-vision-imageanalysis-py", - "path": "skills/azure-ai-vision-imageanalysis-py", - "category": "uncategorized", - "name": "Azure Ai Vision Imageanalysis Py", - "description": "Client library for Azure AI Vision 4.0 image analysis including captions, tags, objects, OCR, and more.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-ai-voicelive-dotnet", - "path": "skills/azure-ai-voicelive-dotnet", - "category": "uncategorized", - "name": "Azure Ai Voicelive Dotnet", - "description": "Real-time voice AI SDK for building bidirectional voice assistants with Azure AI.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-ai-voicelive-java", - "path": "skills/azure-ai-voicelive-java", - "category": "uncategorized", - "name": "Azure Ai Voicelive Java", - "description": "Real-time, bidirectional voice conversations with AI assistants using WebSocket technology.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-ai-voicelive-ts", - "path": "skills/azure-ai-voicelive-ts", - "category": "uncategorized", - "name": "Azure Ai Voicelive Ts", - "description": "Real-time voice AI SDK for building bidirectional voice assistants with Azure AI in Node.js and browser environments.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-appconfiguration-java", - "path": "skills/azure-appconfiguration-java", - "category": "uncategorized", - "name": "Azure Appconfiguration Java", - "description": "Client library for Azure App Configuration, a managed service for centralizing application configurations.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-appconfiguration-py", - "path": "skills/azure-appconfiguration-py", - "category": "uncategorized", - "name": "Azure Appconfiguration Py", - "description": "Centralized configuration management with feature flags and dynamic settings.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-compute-batch-java", - "path": "skills/azure-compute-batch-java", - "category": "uncategorized", - "name": "Azure Compute Batch Java", - "description": "Client library for running large-scale parallel and high-performance computing (HPC) batch jobs in Azure.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-containerregistry-py", - "path": "skills/azure-containerregistry-py", - "category": "uncategorized", - "name": "Azure Containerregistry Py", - "description": "Manage container images, artifacts, and repositories in Azure Container Registry.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-cosmos-java", - "path": "skills/azure-cosmos-java", - "category": "uncategorized", - "name": "Azure Cosmos Java", - "description": "Client library for Azure Cosmos DB NoSQL API with global distribution and reactive patterns.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-cosmos-py", - "path": "skills/azure-cosmos-py", - "category": "uncategorized", - "name": "Azure Cosmos Py", - "description": "Client library for Azure Cosmos DB NoSQL API \u2014 globally distributed, multi-model database.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-cosmos-rust", - "path": "skills/azure-cosmos-rust", - "category": "uncategorized", - "name": "Azure Cosmos Rust", - "description": "Client library for Azure Cosmos DB NoSQL API \u2014 globally distributed, multi-model database.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-cosmos-ts", - "path": "skills/azure-cosmos-ts", - "category": "uncategorized", - "name": "Azure Cosmos Ts", - "description": "Data plane SDK for Azure Cosmos DB NoSQL API operations \u2014 CRUD on documents, queries, bulk operations.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-data-tables-py", - "path": "skills/azure-data-tables-py", - "category": "uncategorized", - "name": "Azure Data Tables Py", - "description": "NoSQL key-value store for structured data (Azure Storage Tables or Cosmos DB Table API).", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-eventgrid-dotnet", - "path": "skills/azure-eventgrid-dotnet", - "category": "uncategorized", - "name": "Azure Eventgrid Dotnet", - "description": "Client library for publishing events to Azure Event Grid topics, domains, and namespaces.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-eventgrid-py", - "path": "skills/azure-eventgrid-py", - "category": "uncategorized", - "name": "Azure Eventgrid Py", - "description": "Event routing service for building event-driven applications with pub/sub semantics.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-eventhub-dotnet", - "path": "skills/azure-eventhub-dotnet", - "category": "uncategorized", - "name": "Azure Eventhub Dotnet", - "description": "High-throughput event streaming SDK for sending and receiving events via Azure Event Hubs.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-eventhub-py", - "path": "skills/azure-eventhub-py", - "category": "uncategorized", - "name": "Azure Eventhub Py", - "description": "Big data streaming platform for high-throughput event ingestion.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-eventhub-rust", - "path": "skills/azure-eventhub-rust", - "category": "uncategorized", - "name": "Azure Eventhub Rust", - "description": "Client library for Azure Event Hubs \u2014 big data streaming platform and event ingestion service.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-identity-dotnet", - "path": "skills/azure-identity-dotnet", - "category": "uncategorized", - "name": "Azure Identity Dotnet", - "description": "Authentication library for Azure SDK clients using Microsoft Entra ID (formerly Azure AD).", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-identity-py", - "path": "skills/azure-identity-py", - "category": "uncategorized", - "name": "Azure Identity Py", - "description": "Authentication library for Azure SDK clients using Microsoft Entra ID (formerly Azure AD).", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-identity-rust", - "path": "skills/azure-identity-rust", - "category": "uncategorized", - "name": "Azure Identity Rust", - "description": "Authentication library for Azure SDK clients using Microsoft Entra ID (formerly Azure AD).", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-keyvault-certificates-rust", - "path": "skills/azure-keyvault-certificates-rust", - "category": "uncategorized", - "name": "Azure Keyvault Certificates Rust", - "description": "Client library for Azure Key Vault Certificates \u2014 secure storage and management of certificates.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-keyvault-keys-rust", - "path": "skills/azure-keyvault-keys-rust", - "category": "uncategorized", - "name": "Azure Keyvault Keys Rust", - "description": "Client library for Azure Key Vault Keys \u2014 secure storage and management of cryptographic keys.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-keyvault-py", - "path": "skills/azure-keyvault-py", - "category": "uncategorized", - "name": "Azure Keyvault Py", - "description": "Secure storage and management for secrets, cryptographic keys, and certificates.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-keyvault-secrets-rust", - "path": "skills/azure-keyvault-secrets-rust", - "category": "uncategorized", - "name": "Azure Keyvault Secrets Rust", - "description": "Client library for Azure Key Vault Secrets \u2014 secure storage for passwords, API keys, and other secrets.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-maps-search-dotnet", - "path": "skills/azure-maps-search-dotnet", - "category": "uncategorized", - "name": "Azure Maps Search Dotnet", - "description": "Azure Maps SDK for .NET providing location-based services: geocoding, routing, rendering, geolocation, and weather.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-messaging-webpubsubservice-py", - "path": "skills/azure-messaging-webpubsubservice-py", - "category": "uncategorized", - "name": "Azure Messaging Webpubsubservice Py", - "description": "Real-time messaging with WebSocket connections at scale.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-mgmt-apicenter-dotnet", - "path": "skills/azure-mgmt-apicenter-dotnet", - "category": "uncategorized", - "name": "Azure Mgmt Apicenter Dotnet", - "description": "Centralized API inventory and governance SDK for managing APIs across your organization.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-mgmt-apicenter-py", - "path": "skills/azure-mgmt-apicenter-py", - "category": "uncategorized", - "name": "Azure Mgmt Apicenter Py", - "description": "Manage API inventory, metadata, and governance in Azure API Center.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-mgmt-apimanagement-dotnet", - "path": "skills/azure-mgmt-apimanagement-dotnet", - "category": "uncategorized", - "name": "Azure Mgmt Apimanagement Dotnet", - "description": "Management plane SDK for provisioning and managing Azure API Management resources via Azure Resource Manager.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-mgmt-apimanagement-py", - "path": "skills/azure-mgmt-apimanagement-py", - "category": "uncategorized", - "name": "Azure Mgmt Apimanagement Py", - "description": "Manage Azure API Management services, APIs, products, and policies.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-mgmt-applicationinsights-dotnet", - "path": "skills/azure-mgmt-applicationinsights-dotnet", - "category": "uncategorized", - "name": "Azure Mgmt Applicationinsights Dotnet", - "description": "Azure Resource Manager SDK for managing Application Insights resources for application performance monitoring.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-mgmt-arizeaiobservabilityeval-dotnet", - "path": "skills/azure-mgmt-arizeaiobservabilityeval-dotnet", - "category": "uncategorized", - "name": "Azure Mgmt Arizeaiobservabilityeval Dotnet", - "description": ".NET SDK for managing Arize AI Observability and Evaluation resources on Azure.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-mgmt-botservice-dotnet", - "path": "skills/azure-mgmt-botservice-dotnet", - "category": "uncategorized", - "name": "Azure Mgmt Botservice Dotnet", - "description": "Management plane SDK for provisioning and managing Azure Bot Service resources via Azure Resource Manager.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-mgmt-botservice-py", - "path": "skills/azure-mgmt-botservice-py", - "category": "uncategorized", - "name": "Azure Mgmt Botservice Py", - "description": "Manage Azure Bot Service resources including bots, channels, and connections.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-mgmt-fabric-dotnet", - "path": "skills/azure-mgmt-fabric-dotnet", - "category": "uncategorized", - "name": "Azure Mgmt Fabric Dotnet", - "description": "Management plane SDK for provisioning and managing Microsoft Fabric capacity resources via Azure Resource Manager.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-mgmt-fabric-py", - "path": "skills/azure-mgmt-fabric-py", - "category": "uncategorized", - "name": "Azure Mgmt Fabric Py", - "description": "Manage Microsoft Fabric capacities and resources programmatically.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-mgmt-weightsandbiases-dotnet", - "path": "skills/azure-mgmt-weightsandbiases-dotnet", - "category": "uncategorized", - "name": "Azure Mgmt Weightsandbiases Dotnet", - "description": "Azure Resource Manager SDK for deploying and managing Weights & Biases ML experiment tracking instances via Azure Marketplace.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-monitor-ingestion-java", - "path": "skills/azure-monitor-ingestion-java", - "category": "uncategorized", - "name": "Azure Monitor Ingestion Java", - "description": "Client library for sending custom logs to Azure Monitor using the Logs Ingestion API via Data Collection Rules.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-monitor-ingestion-py", - "path": "skills/azure-monitor-ingestion-py", - "category": "uncategorized", - "name": "Azure Monitor Ingestion Py", - "description": "Send custom logs to Azure Monitor Log Analytics workspace using the Logs Ingestion API.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-monitor-opentelemetry-exporter-java", - "path": "skills/azure-monitor-opentelemetry-exporter-java", - "category": "uncategorized", - "name": "Azure Monitor Opentelemetry Exporter Java", - "description": "> **\u26a0\ufe0f DEPRECATION NOTICE**: This package is deprecated. Migrate to `azure-monitor-opentelemetry-autoconfigure`. > > See [Migration Guide](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/monitor/azure-monitor-opentelemetry-exporter/MIGRATIO", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-monitor-opentelemetry-exporter-py", - "path": "skills/azure-monitor-opentelemetry-exporter-py", - "category": "uncategorized", - "name": "Azure Monitor Opentelemetry Exporter Py", - "description": "Low-level exporter for sending OpenTelemetry traces, metrics, and logs to Application Insights.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-monitor-opentelemetry-py", - "path": "skills/azure-monitor-opentelemetry-py", - "category": "uncategorized", - "name": "Azure Monitor Opentelemetry Py", - "description": "One-line setup for Application Insights with OpenTelemetry auto-instrumentation.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-monitor-query-java", - "path": "skills/azure-monitor-query-java", - "category": "uncategorized", - "name": "Azure Monitor Query Java", - "description": "> **DEPRECATION NOTICE**: This package is deprecated in favor of: > - `azure-monitor-query-logs` \u2014 For Log Analytics queries > - `azure-monitor-query-metrics` \u2014 For metrics queries > > See migration guides: [Logs Migration](https://github.com/Azure/a", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-monitor-query-py", - "path": "skills/azure-monitor-query-py", - "category": "uncategorized", - "name": "Azure Monitor Query Py", - "description": "Query logs and metrics from Azure Monitor and Log Analytics workspaces.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-postgres-ts", - "path": "skills/azure-postgres-ts", - "category": "uncategorized", - "name": "Azure Postgres Ts", - "description": "Connect to Azure Database for PostgreSQL Flexible Server using the `pg` (node-postgres) package with support for password and Microsoft Entra ID (passwordless) authentication.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-resource-manager-cosmosdb-dotnet", - "path": "skills/azure-resource-manager-cosmosdb-dotnet", - "category": "uncategorized", - "name": "Azure Resource Manager Cosmosdb Dotnet", - "description": "Management plane SDK for provisioning and managing Azure Cosmos DB resources via Azure Resource Manager.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-resource-manager-durabletask-dotnet", - "path": "skills/azure-resource-manager-durabletask-dotnet", - "category": "uncategorized", - "name": "Azure Resource Manager Durabletask Dotnet", - "description": "Management plane SDK for provisioning and managing Azure Durable Task Scheduler resources via Azure Resource Manager.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-resource-manager-mysql-dotnet", - "path": "skills/azure-resource-manager-mysql-dotnet", - "category": "uncategorized", - "name": "Azure Resource Manager Mysql Dotnet", - "description": "Azure Resource Manager SDK for managing MySQL Flexible Server deployments.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-resource-manager-playwright-dotnet", - "path": "skills/azure-resource-manager-playwright-dotnet", - "category": "uncategorized", - "name": "Azure Resource Manager Playwright Dotnet", - "description": "Management plane SDK for provisioning and managing Microsoft Playwright Testing workspaces via Azure Resource Manager.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-resource-manager-postgresql-dotnet", - "path": "skills/azure-resource-manager-postgresql-dotnet", - "category": "uncategorized", - "name": "Azure Resource Manager Postgresql Dotnet", - "description": "Azure Resource Manager SDK for managing PostgreSQL Flexible Server deployments.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-resource-manager-redis-dotnet", - "path": "skills/azure-resource-manager-redis-dotnet", - "category": "uncategorized", - "name": "Azure Resource Manager Redis Dotnet", - "description": "Management plane SDK for provisioning and managing Azure Cache for Redis resources via Azure Resource Manager.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-resource-manager-sql-dotnet", - "path": "skills/azure-resource-manager-sql-dotnet", - "category": "uncategorized", - "name": "Azure Resource Manager Sql Dotnet", - "description": "Management plane SDK for provisioning and managing Azure SQL resources via Azure Resource Manager.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-search-documents-dotnet", - "path": "skills/azure-search-documents-dotnet", - "category": "uncategorized", - "name": "Azure Search Documents Dotnet", - "description": "Build search applications with full-text, vector, semantic, and hybrid search capabilities.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-search-documents-py", - "path": "skills/azure-search-documents-py", - "category": "uncategorized", - "name": "Azure Search Documents Py", - "description": "Full-text, vector, and hybrid search with AI enrichment capabilities.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-security-keyvault-keys-dotnet", - "path": "skills/azure-security-keyvault-keys-dotnet", - "category": "uncategorized", - "name": "Azure Security Keyvault Keys Dotnet", - "description": "Client library for managing cryptographic keys in Azure Key Vault and Managed HSM.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-servicebus-dotnet", - "path": "skills/azure-servicebus-dotnet", - "category": "uncategorized", - "name": "Azure Servicebus Dotnet", - "description": "Enterprise messaging SDK for reliable message delivery with queues, topics, subscriptions, and sessions.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-servicebus-py", - "path": "skills/azure-servicebus-py", - "category": "uncategorized", - "name": "Azure Servicebus Py", - "description": "Enterprise messaging for reliable cloud communication with queues and pub/sub topics.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-speech-to-text-rest-py", - "path": "skills/azure-speech-to-text-rest-py", - "category": "uncategorized", - "name": "Azure Speech To Text Rest Py", - "description": "Simple REST API for speech-to-text transcription of short audio files (up to 60 seconds). No SDK required - just HTTP requests.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-storage-blob-py", - "path": "skills/azure-storage-blob-py", - "category": "uncategorized", - "name": "Azure Storage Blob Py", - "description": "Client library for Azure Blob Storage \u2014 object storage for unstructured data.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-storage-blob-rust", - "path": "skills/azure-storage-blob-rust", - "category": "uncategorized", - "name": "Azure Storage Blob Rust", - "description": "Client library for Azure Blob Storage \u2014 Microsoft's object storage solution for the cloud.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-storage-blob-ts", - "path": "skills/azure-storage-blob-ts", - "category": "uncategorized", - "name": "Azure Storage Blob Ts", - "description": "SDK for Azure Blob Storage operations \u2014 upload, download, list, and manage blobs and containers.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-storage-file-datalake-py", - "path": "skills/azure-storage-file-datalake-py", - "category": "uncategorized", - "name": "Azure Storage File Datalake Py", - "description": "Hierarchical file system for big data analytics workloads.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-storage-file-share-py", - "path": "skills/azure-storage-file-share-py", - "category": "uncategorized", - "name": "Azure Storage File Share Py", - "description": "Manage SMB file shares for cloud-native and lift-and-shift scenarios.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-storage-file-share-ts", - "path": "skills/azure-storage-file-share-ts", - "category": "uncategorized", - "name": "Azure Storage File Share Ts", - "description": "SDK for Azure File Share operations \u2014 SMB file shares, directories, and file operations.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-storage-queue-py", - "path": "skills/azure-storage-queue-py", - "category": "uncategorized", - "name": "Azure Storage Queue Py", - "description": "Simple, cost-effective message queuing for asynchronous communication.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "azure-storage-queue-ts", - "path": "skills/azure-storage-queue-ts", - "category": "uncategorized", - "name": "Azure Storage Queue Ts", - "description": "SDK for Azure Queue Storage operations \u2014 send, receive, peek, and manage messages in queues.", - "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "azure-ai-anomalydetector-java", - "path": "skills/azure-ai-anomalydetector-java", + "path": "skills\\azure-ai-anomalydetector-java", "category": "uncategorized", "name": "azure-ai-anomalydetector-java", "description": "Build anomaly detection applications with Azure AI Anomaly Detector SDK for Java. Use when implementing univariate/multivariate anomaly detection, time-series analysis, or AI-powered monitoring.", @@ -1405,25 +739,52 @@ }, { "id": "azure-ai-contentsafety-java", - "path": "skills/azure-ai-contentsafety-java", + "path": "skills\\azure-ai-contentsafety-java", "category": "uncategorized", "name": "azure-ai-contentsafety-java", "description": "Build content moderation applications with Azure AI Content Safety SDK for Java. Use when implementing text/image analysis, blocklist management, or harm detection for hate, violence, sexual conten...", "risk": "unknown", "source": "community" }, + { + "id": "azure-ai-contentsafety-py", + "path": "skills\\azure-ai-contentsafety-py", + "category": "uncategorized", + "name": "azure-ai-contentsafety-py", + "description": "Azure AI Content Safety SDK for Python. Use for detecting harmful content in text and images with multi-severity classification.\nTriggers: \"azure-ai-contentsafety\", \"ContentSafetyClient\", \"content moderation\", \"harmful content\", \"text analysis\", \"image analysis\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-ai-contentsafety-ts", - "path": "skills/azure-ai-contentsafety-ts", + "path": "skills\\azure-ai-contentsafety-ts", "category": "uncategorized", "name": "azure-ai-contentsafety-ts", "description": "Analyze text and images for harmful content using Azure AI Content Safety (@azure-rest/ai-content-safety). Use when moderating user-generated content, detecting hate speech, violence, sexual conten...", "risk": "unknown", "source": "community" }, + { + "id": "azure-ai-contentunderstanding-py", + "path": "skills\\azure-ai-contentunderstanding-py", + "category": "uncategorized", + "name": "azure-ai-contentunderstanding-py", + "description": "Azure AI Content Understanding SDK for Python. Use for multimodal content extraction from documents, images, audio, and video.\nTriggers: \"azure-ai-contentunderstanding\", \"ContentUnderstandingClient\", \"multimodal analysis\", \"document extraction\", \"video analysis\", \"audio transcription\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-ai-document-intelligence-dotnet", + "path": "skills\\azure-ai-document-intelligence-dotnet", + "category": "uncategorized", + "name": "azure-ai-document-intelligence-dotnet", + "description": "Azure AI Document Intelligence SDK for .NET. Extract text, tables, and structured data from documents using prebuilt and custom models. Use for invoice processing, receipt extraction, ID document analysis, and custom document models. Triggers: \"Document Intelligence\", \"DocumentIntelligenceClient\", \"form recognizer\", \"invoice extraction\", \"receipt OCR\", \"document analysis .NET\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-ai-document-intelligence-ts", - "path": "skills/azure-ai-document-intelligence-ts", + "path": "skills\\azure-ai-document-intelligence-ts", "category": "uncategorized", "name": "azure-ai-document-intelligence-ts", "description": "Extract text, tables, and structured data from documents using Azure Document Intelligence (@azure-rest/ai-document-intelligence). Use when processing invoices, receipts, IDs, forms, or building cu...", @@ -1432,16 +793,52 @@ }, { "id": "azure-ai-formrecognizer-java", - "path": "skills/azure-ai-formrecognizer-java", + "path": "skills\\azure-ai-formrecognizer-java", "category": "uncategorized", "name": "azure-ai-formrecognizer-java", "description": "Build document analysis applications with Azure Document Intelligence (Form Recognizer) SDK for Java. Use when extracting text, tables, key-value pairs from documents, receipts, invoices, or buildi...", "risk": "unknown", "source": "community" }, + { + "id": "azure-ai-ml-py", + "path": "skills\\azure-ai-ml-py", + "category": "uncategorized", + "name": "azure-ai-ml-py", + "description": "Azure Machine Learning SDK v2 for Python. Use for ML workspaces, jobs, models, datasets, compute, and pipelines.\nTriggers: \"azure-ai-ml\", \"MLClient\", \"workspace\", \"model registry\", \"training jobs\", \"datasets\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-ai-openai-dotnet", + "path": "skills\\azure-ai-openai-dotnet", + "category": "uncategorized", + "name": "azure-ai-openai-dotnet", + "description": "Azure OpenAI SDK for .NET. Client library for Azure OpenAI and OpenAI services. Use for chat completions, embeddings, image generation, audio transcription, and assistants. Triggers: \"Azure OpenAI\", \"AzureOpenAIClient\", \"ChatClient\", \"chat completions .NET\", \"GPT-4\", \"embeddings\", \"DALL-E\", \"Whisper\", \"OpenAI .NET\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-ai-projects-dotnet", + "path": "skills\\azure-ai-projects-dotnet", + "category": "uncategorized", + "name": "azure-ai-projects-dotnet", + "description": "Azure AI Projects SDK for .NET. High-level client for Azure AI Foundry projects including agents, connections, datasets, deployments, evaluations, and indexes. Use for AI Foundry project management, versioned agents, and orchestration. Triggers: \"AI Projects\", \"AIProjectClient\", \"Foundry project\", \"versioned agents\", \"evaluations\", \"datasets\", \"connections\", \"deployments .NET\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-ai-projects-java", + "path": "skills\\azure-ai-projects-java", + "category": "uncategorized", + "name": "azure-ai-projects-java", + "description": "Azure AI Projects SDK for Java. High-level SDK for Azure AI Foundry project management including connections, datasets, indexes, and evaluations.\nTriggers: \"AIProjectClient java\", \"azure ai projects java\", \"Foundry project java\", \"ConnectionsClient\", \"DatasetsClient\", \"IndexesClient\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-ai-projects-py", - "path": "skills/azure-ai-projects-py", + "path": "skills\\azure-ai-projects-py", "category": "uncategorized", "name": "azure-ai-projects-py", "description": "Build AI applications using the Azure AI Projects Python SDK (azure-ai-projects). Use when working with Foundry project clients, creating versioned agents with PromptAgentDefinition, running evalua...", @@ -1450,16 +847,52 @@ }, { "id": "azure-ai-projects-ts", - "path": "skills/azure-ai-projects-ts", + "path": "skills\\azure-ai-projects-ts", "category": "uncategorized", "name": "azure-ai-projects-ts", "description": "Build AI applications using Azure AI Projects SDK for JavaScript (@azure/ai-projects). Use when working with Foundry project clients, agents, connections, deployments, datasets, indexes, evaluation...", "risk": "unknown", "source": "community" }, + { + "id": "azure-ai-textanalytics-py", + "path": "skills\\azure-ai-textanalytics-py", + "category": "uncategorized", + "name": "azure-ai-textanalytics-py", + "description": "Azure AI Text Analytics SDK for sentiment analysis, entity recognition, key phrases, language detection, PII, and healthcare NLP. Use for natural language processing on text.\nTriggers: \"text analytics\", \"sentiment analysis\", \"entity recognition\", \"key phrase\", \"PII detection\", \"TextAnalyticsClient\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-ai-transcription-py", + "path": "skills\\azure-ai-transcription-py", + "category": "uncategorized", + "name": "azure-ai-transcription-py", + "description": "Azure AI Transcription SDK for Python. Use for real-time and batch speech-to-text transcription with timestamps and diarization.\nTriggers: \"transcription\", \"speech to text\", \"Azure AI Transcription\", \"TranscriptionClient\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-ai-translation-document-py", + "path": "skills\\azure-ai-translation-document-py", + "category": "uncategorized", + "name": "azure-ai-translation-document-py", + "description": "Azure AI Document Translation SDK for batch translation of documents with format preservation. Use for translating Word, PDF, Excel, PowerPoint, and other document formats at scale.\nTriggers: \"document translation\", \"batch translation\", \"translate documents\", \"DocumentTranslationClient\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-ai-translation-text-py", + "path": "skills\\azure-ai-translation-text-py", + "category": "uncategorized", + "name": "azure-ai-translation-text-py", + "description": "Azure AI Text Translation SDK for real-time text translation, transliteration, language detection, and dictionary lookup. Use for translating text content in applications.\nTriggers: \"text translation\", \"translator\", \"translate text\", \"transliterate\", \"TextTranslationClient\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-ai-translation-ts", - "path": "skills/azure-ai-translation-ts", + "path": "skills\\azure-ai-translation-ts", "category": "uncategorized", "name": "azure-ai-translation-ts", "description": "Build translation applications using Azure Translation SDKs for JavaScript (@azure-rest/ai-translation-text, @azure-rest/ai-translation-document). Use when implementing text translation, transliter...", @@ -1468,25 +901,79 @@ }, { "id": "azure-ai-vision-imageanalysis-java", - "path": "skills/azure-ai-vision-imageanalysis-java", + "path": "skills\\azure-ai-vision-imageanalysis-java", "category": "uncategorized", "name": "azure-ai-vision-imageanalysis-java", "description": "Build image analysis applications with Azure AI Vision SDK for Java. Use when implementing image captioning, OCR text extraction, object detection, tagging, or smart cropping.", "risk": "unknown", "source": "community" }, + { + "id": "azure-ai-vision-imageanalysis-py", + "path": "skills\\azure-ai-vision-imageanalysis-py", + "category": "uncategorized", + "name": "azure-ai-vision-imageanalysis-py", + "description": "Azure AI Vision Image Analysis SDK for captions, tags, objects, OCR, people detection, and smart cropping. Use for computer vision and image understanding tasks.\nTriggers: \"image analysis\", \"computer vision\", \"OCR\", \"object detection\", \"ImageAnalysisClient\", \"image caption\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-ai-voicelive-dotnet", + "path": "skills\\azure-ai-voicelive-dotnet", + "category": "uncategorized", + "name": "azure-ai-voicelive-dotnet", + "description": "Azure AI Voice Live SDK for .NET. Build real-time voice AI applications with bidirectional WebSocket communication. Use for voice assistants, conversational AI, real-time speech-to-speech, and voice-enabled chatbots. Triggers: \"voice live\", \"real-time voice\", \"VoiceLiveClient\", \"VoiceLiveSession\", \"voice assistant .NET\", \"bidirectional audio\", \"speech-to-speech\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-ai-voicelive-java", + "path": "skills\\azure-ai-voicelive-java", + "category": "uncategorized", + "name": "azure-ai-voicelive-java", + "description": "Azure AI VoiceLive SDK for Java. Real-time bidirectional voice conversations with AI assistants using WebSocket.\nTriggers: \"VoiceLiveClient java\", \"voice assistant java\", \"real-time voice java\", \"audio streaming java\", \"voice activity detection java\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-ai-voicelive-py", - "path": "skills/azure-ai-voicelive-py", + "path": "skills\\azure-ai-voicelive-py", "category": "uncategorized", "name": "azure-ai-voicelive-py", "description": "Build real-time voice AI applications using Azure AI Voice Live SDK (azure-ai-voicelive). Use this skill when creating Python applications that need real-time bidirectional audio communication with...", "risk": "unknown", "source": "community" }, + { + "id": "azure-ai-voicelive-ts", + "path": "skills\\azure-ai-voicelive-ts", + "category": "uncategorized", + "name": "azure-ai-voicelive-ts", + "description": "Azure AI Voice Live SDK for JavaScript/TypeScript. Build real-time voice AI applications with bidirectional WebSocket communication. Use for voice assistants, conversational AI, real-time speech-to-speech, and voice-enabled chatbots in Node.js or browser environments. Triggers: \"voice live\", \"real-time voice\", \"VoiceLiveClient\", \"VoiceLiveSession\", \"voice assistant TypeScript\", \"bidirectional audio\", \"speech-to-speech JavaScript\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-appconfiguration-java", + "path": "skills\\azure-appconfiguration-java", + "category": "uncategorized", + "name": "azure-appconfiguration-java", + "description": "Azure App Configuration SDK for Java. Centralized application configuration management with key-value settings, feature flags, and snapshots.\nTriggers: \"ConfigurationClient java\", \"app configuration java\", \"feature flag java\", \"configuration setting java\", \"azure config java\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-appconfiguration-py", + "path": "skills\\azure-appconfiguration-py", + "category": "uncategorized", + "name": "azure-appconfiguration-py", + "description": "Azure App Configuration SDK for Python. Use for centralized configuration management, feature flags, and dynamic settings.\nTriggers: \"azure-appconfiguration\", \"AzureAppConfigurationClient\", \"feature flags\", \"configuration\", \"key-value settings\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-appconfiguration-ts", - "path": "skills/azure-appconfiguration-ts", + "path": "skills\\azure-appconfiguration-ts", "category": "uncategorized", "name": "azure-appconfiguration-ts", "description": "Build applications using Azure App Configuration SDK for JavaScript (@azure/app-configuration). Use when working with configuration settings, feature flags, Key Vault references, dynamic refresh, o...", @@ -1495,7 +982,7 @@ }, { "id": "azure-communication-callautomation-java", - "path": "skills/azure-communication-callautomation-java", + "path": "skills\\azure-communication-callautomation-java", "category": "uncategorized", "name": "azure-communication-callautomation-java", "description": "Build call automation workflows with Azure Communication Services Call Automation Java SDK. Use when implementing IVR systems, call routing, call recording, DTMF recognition, text-to-speech, or AI-...", @@ -1504,7 +991,7 @@ }, { "id": "azure-communication-callingserver-java", - "path": "skills/azure-communication-callingserver-java", + "path": "skills\\azure-communication-callingserver-java", "category": "uncategorized", "name": "azure-communication-callingserver-java", "description": "Azure Communication Services CallingServer (legacy) Java SDK. Note - This SDK is deprecated. Use azure-communication-callautomation instead for new projects. Only use this skill when maintaining le...", @@ -1513,7 +1000,7 @@ }, { "id": "azure-communication-chat-java", - "path": "skills/azure-communication-chat-java", + "path": "skills\\azure-communication-chat-java", "category": "uncategorized", "name": "azure-communication-chat-java", "description": "Build real-time chat applications with Azure Communication Services Chat Java SDK. Use when implementing chat threads, messaging, participants, read receipts, typing notifications, or real-time cha...", @@ -1522,7 +1009,7 @@ }, { "id": "azure-communication-common-java", - "path": "skills/azure-communication-common-java", + "path": "skills\\azure-communication-common-java", "category": "uncategorized", "name": "azure-communication-common-java", "description": "Azure Communication Services common utilities for Java. Use when working with CommunicationTokenCredential, user identifiers, token refresh, or shared authentication across ACS services.", @@ -1531,52 +1018,160 @@ }, { "id": "azure-communication-sms-java", - "path": "skills/azure-communication-sms-java", + "path": "skills\\azure-communication-sms-java", "category": "uncategorized", "name": "azure-communication-sms-java", "description": "Send SMS messages with Azure Communication Services SMS Java SDK. Use when implementing SMS notifications, alerts, OTP delivery, bulk messaging, or delivery reports.", "risk": "unknown", "source": "community" }, + { + "id": "azure-compute-batch-java", + "path": "skills\\azure-compute-batch-java", + "category": "uncategorized", + "name": "azure-compute-batch-java", + "description": "Azure Batch SDK for Java. Run large-scale parallel and HPC batch jobs with pools, jobs, tasks, and compute nodes.\nTriggers: \"BatchClient java\", \"azure batch java\", \"batch pool java\", \"batch job java\", \"HPC java\", \"parallel computing java\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-containerregistry-py", + "path": "skills\\azure-containerregistry-py", + "category": "uncategorized", + "name": "azure-containerregistry-py", + "description": "Azure Container Registry SDK for Python. Use for managing container images, artifacts, and repositories.\nTriggers: \"azure-containerregistry\", \"ContainerRegistryClient\", \"container images\", \"docker registry\", \"ACR\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-cosmos-db-py", - "path": "skills/azure-cosmos-db-py", + "path": "skills\\azure-cosmos-db-py", "category": "uncategorized", "name": "azure-cosmos-db-py", "description": "Build Azure Cosmos DB NoSQL services with Python/FastAPI following production-grade patterns. Use when implementing database client setup with dual auth (DefaultAzureCredential + emulator), service...", "risk": "unknown", "source": "community" }, + { + "id": "azure-cosmos-java", + "path": "skills\\azure-cosmos-java", + "category": "uncategorized", + "name": "azure-cosmos-java", + "description": "Azure Cosmos DB SDK for Java. NoSQL database operations with global distribution, multi-model support, and reactive patterns.\nTriggers: \"CosmosClient java\", \"CosmosAsyncClient\", \"cosmos database java\", \"cosmosdb java\", \"document database java\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-cosmos-py", + "path": "skills\\azure-cosmos-py", + "category": "uncategorized", + "name": "azure-cosmos-py", + "description": "Azure Cosmos DB SDK for Python (NoSQL API). Use for document CRUD, queries, containers, and globally distributed data.\nTriggers: \"cosmos db\", \"CosmosClient\", \"container\", \"document\", \"NoSQL\", \"partition key\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-cosmos-rust", + "path": "skills\\azure-cosmos-rust", + "category": "uncategorized", + "name": "azure-cosmos-rust", + "description": "Azure Cosmos DB SDK for Rust (NoSQL API). Use for document CRUD, queries, containers, and globally distributed data.\nTriggers: \"cosmos db rust\", \"CosmosClient rust\", \"container\", \"document rust\", \"NoSQL rust\", \"partition key\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-cosmos-ts", + "path": "skills\\azure-cosmos-ts", + "category": "uncategorized", + "name": "azure-cosmos-ts", + "description": "Azure Cosmos DB JavaScript/TypeScript SDK (@azure/cosmos) for data plane operations. Use for CRUD operations on documents, queries, bulk operations, and container management. Triggers: \"Cosmos DB\", \"@azure/cosmos\", \"CosmosClient\", \"document CRUD\", \"NoSQL queries\", \"bulk operations\", \"partition key\", \"container.items\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-data-tables-java", - "path": "skills/azure-data-tables-java", + "path": "skills\\azure-data-tables-java", "category": "uncategorized", "name": "azure-data-tables-java", "description": "Build table storage applications with Azure Tables SDK for Java. Use when working with Azure Table Storage or Cosmos DB Table API for NoSQL key-value data, schemaless storage, or structured data at...", "risk": "unknown", "source": "community" }, + { + "id": "azure-data-tables-py", + "path": "skills\\azure-data-tables-py", + "category": "uncategorized", + "name": "azure-data-tables-py", + "description": "Azure Tables SDK for Python (Storage and Cosmos DB). Use for NoSQL key-value storage, entity CRUD, and batch operations.\nTriggers: \"table storage\", \"TableServiceClient\", \"TableClient\", \"entities\", \"PartitionKey\", \"RowKey\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-eventgrid-dotnet", + "path": "skills\\azure-eventgrid-dotnet", + "category": "uncategorized", + "name": "azure-eventgrid-dotnet", + "description": "Azure Event Grid SDK for .NET. Client library for publishing and consuming events with Azure Event Grid. Use for event-driven architectures, pub/sub messaging, CloudEvents, and EventGridEvents. Triggers: \"Event Grid\", \"EventGridPublisherClient\", \"CloudEvent\", \"EventGridEvent\", \"publish events .NET\", \"event-driven\", \"pub/sub\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-eventgrid-java", - "path": "skills/azure-eventgrid-java", + "path": "skills\\azure-eventgrid-java", "category": "uncategorized", "name": "azure-eventgrid-java", "description": "Build event-driven applications with Azure Event Grid SDK for Java. Use when publishing events, implementing pub/sub patterns, or integrating with Azure services via events.", "risk": "unknown", "source": "community" }, + { + "id": "azure-eventgrid-py", + "path": "skills\\azure-eventgrid-py", + "category": "uncategorized", + "name": "azure-eventgrid-py", + "description": "Azure Event Grid SDK for Python. Use for publishing events, handling CloudEvents, and event-driven architectures.\nTriggers: \"event grid\", \"EventGridPublisherClient\", \"CloudEvent\", \"EventGridEvent\", \"publish events\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-eventhub-dotnet", + "path": "skills\\azure-eventhub-dotnet", + "category": "uncategorized", + "name": "azure-eventhub-dotnet", + "description": "Azure Event Hubs SDK for .NET. Use for high-throughput event streaming: sending events (EventHubProducerClient, EventHubBufferedProducerClient), receiving events (EventProcessorClient with checkpointing), partition management, and real-time data ingestion. Triggers: \"Event Hubs\", \"event streaming\", \"EventHubProducerClient\", \"EventProcessorClient\", \"send events\", \"receive events\", \"checkpointing\", \"partition\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-eventhub-java", - "path": "skills/azure-eventhub-java", + "path": "skills\\azure-eventhub-java", "category": "uncategorized", "name": "azure-eventhub-java", "description": "Build real-time streaming applications with Azure Event Hubs SDK for Java. Use when implementing event streaming, high-throughput data ingestion, or building event-driven architectures.", "risk": "unknown", "source": "community" }, + { + "id": "azure-eventhub-py", + "path": "skills\\azure-eventhub-py", + "category": "uncategorized", + "name": "azure-eventhub-py", + "description": "Azure Event Hubs SDK for Python streaming. Use for high-throughput event ingestion, producers, consumers, and checkpointing.\nTriggers: \"event hubs\", \"EventHubProducerClient\", \"EventHubConsumerClient\", \"streaming\", \"partitions\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-eventhub-rust", + "path": "skills\\azure-eventhub-rust", + "category": "uncategorized", + "name": "azure-eventhub-rust", + "description": "Azure Event Hubs SDK for Rust. Use for sending and receiving events, streaming data ingestion.\nTriggers: \"event hubs rust\", \"ProducerClient rust\", \"ConsumerClient rust\", \"send event rust\", \"streaming rust\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-eventhub-ts", - "path": "skills/azure-eventhub-ts", + "path": "skills\\azure-eventhub-ts", "category": "uncategorized", "name": "azure-eventhub-ts", "description": "Build event streaming applications using Azure Event Hubs SDK for JavaScript (@azure/event-hubs). Use when implementing high-throughput event ingestion, real-time analytics, IoT telemetry, or event...", @@ -1585,97 +1180,439 @@ }, { "id": "azure-functions", - "path": "skills/azure-functions", + "path": "skills\\azure-functions", "category": "uncategorized", "name": "azure-functions", "description": "Expert patterns for Azure Functions development including isolated worker model, Durable Functions orchestration, cold start optimization, and production patterns. Covers .NET, Python, and Node.js ...", "risk": "unknown", "source": "vibeship-spawner-skills (Apache 2.0)" }, + { + "id": "azure-identity-dotnet", + "path": "skills\\azure-identity-dotnet", + "category": "uncategorized", + "name": "azure-identity-dotnet", + "description": "Azure Identity SDK for .NET. Authentication library for Azure SDK clients using Microsoft Entra ID. Use for DefaultAzureCredential, managed identity, service principals, and developer credentials. Triggers: \"Azure Identity\", \"DefaultAzureCredential\", \"ManagedIdentityCredential\", \"ClientSecretCredential\", \"authentication .NET\", \"Azure auth\", \"credential chain\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-identity-java", - "path": "skills/azure-identity-java", + "path": "skills\\azure-identity-java", "category": "uncategorized", "name": "azure-identity-java", "description": "Azure Identity Java SDK for authentication with Azure services. Use when implementing DefaultAzureCredential, managed identity, service principal, or any Azure authentication pattern in Java applic...", "risk": "unknown", "source": "community" }, + { + "id": "azure-identity-py", + "path": "skills\\azure-identity-py", + "category": "uncategorized", + "name": "azure-identity-py", + "description": "Azure Identity SDK for Python authentication. Use for DefaultAzureCredential, managed identity, service principals, and token caching.\nTriggers: \"azure-identity\", \"DefaultAzureCredential\", \"authentication\", \"managed identity\", \"service principal\", \"credential\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-identity-rust", + "path": "skills\\azure-identity-rust", + "category": "uncategorized", + "name": "azure-identity-rust", + "description": "Azure Identity SDK for Rust authentication. Use for DeveloperToolsCredential, ManagedIdentityCredential, ClientSecretCredential, and token-based authentication.\nTriggers: \"azure-identity\", \"DeveloperToolsCredential\", \"authentication rust\", \"managed identity rust\", \"credential rust\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-identity-ts", - "path": "skills/azure-identity-ts", + "path": "skills\\azure-identity-ts", "category": "uncategorized", "name": "azure-identity-ts", "description": "Authenticate to Azure services using Azure Identity SDK for JavaScript (@azure/identity). Use when configuring authentication with DefaultAzureCredential, managed identity, service principals, or i...", "risk": "unknown", "source": "community" }, + { + "id": "azure-keyvault-certificates-rust", + "path": "skills\\azure-keyvault-certificates-rust", + "category": "uncategorized", + "name": "azure-keyvault-certificates-rust", + "description": "Azure Key Vault Certificates SDK for Rust. Use for creating, importing, and managing certificates.\nTriggers: \"keyvault certificates rust\", \"CertificateClient rust\", \"create certificate rust\", \"import certificate rust\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-keyvault-keys-rust", + "path": "skills\\azure-keyvault-keys-rust", + "category": "uncategorized", + "name": "azure-keyvault-keys-rust", + "description": "Azure Key Vault Keys SDK for Rust. Use for creating, managing, and using cryptographic keys.\nTriggers: \"keyvault keys rust\", \"KeyClient rust\", \"create key rust\", \"encrypt rust\", \"sign rust\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-keyvault-keys-ts", - "path": "skills/azure-keyvault-keys-ts", + "path": "skills\\azure-keyvault-keys-ts", "category": "uncategorized", "name": "azure-keyvault-keys-ts", "description": "Manage cryptographic keys using Azure Key Vault Keys SDK for JavaScript (@azure/keyvault-keys). Use when creating, encrypting/decrypting, signing, or rotating keys.", "risk": "unknown", "source": "community" }, + { + "id": "azure-keyvault-py", + "path": "skills\\azure-keyvault-py", + "category": "uncategorized", + "name": "azure-keyvault-py", + "description": "Azure Key Vault SDK for Python. Use for secrets, keys, and certificates management with secure storage.\nTriggers: \"key vault\", \"SecretClient\", \"KeyClient\", \"CertificateClient\", \"secrets\", \"encryption keys\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-keyvault-secrets-rust", + "path": "skills\\azure-keyvault-secrets-rust", + "category": "uncategorized", + "name": "azure-keyvault-secrets-rust", + "description": "Azure Key Vault Secrets SDK for Rust. Use for storing and retrieving secrets, passwords, and API keys.\nTriggers: \"keyvault secrets rust\", \"SecretClient rust\", \"get secret rust\", \"set secret rust\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-keyvault-secrets-ts", - "path": "skills/azure-keyvault-secrets-ts", + "path": "skills\\azure-keyvault-secrets-ts", "category": "uncategorized", "name": "azure-keyvault-secrets-ts", "description": "Manage secrets using Azure Key Vault Secrets SDK for JavaScript (@azure/keyvault-secrets). Use when storing and retrieving application secrets or configuration values.", "risk": "unknown", "source": "community" }, + { + "id": "azure-maps-search-dotnet", + "path": "skills\\azure-maps-search-dotnet", + "category": "uncategorized", + "name": "azure-maps-search-dotnet", + "description": "Azure Maps SDK for .NET. Location-based services including geocoding, routing, rendering, geolocation, and weather. Use for address search, directions, map tiles, IP geolocation, and weather data. Triggers: \"Azure Maps\", \"MapsSearchClient\", \"MapsRoutingClient\", \"MapsRenderingClient\", \"geocoding .NET\", \"route directions\", \"map tiles\", \"geolocation\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-messaging-webpubsub-java", - "path": "skills/azure-messaging-webpubsub-java", + "path": "skills\\azure-messaging-webpubsub-java", "category": "uncategorized", "name": "azure-messaging-webpubsub-java", "description": "Build real-time web applications with Azure Web PubSub SDK for Java. Use when implementing WebSocket-based messaging, live updates, chat applications, or server-to-client push notifications.", "risk": "unknown", "source": "community" }, + { + "id": "azure-messaging-webpubsubservice-py", + "path": "skills\\azure-messaging-webpubsubservice-py", + "category": "uncategorized", + "name": "azure-messaging-webpubsubservice-py", + "description": "Azure Web PubSub Service SDK for Python. Use for real-time messaging, WebSocket connections, and pub/sub patterns.\nTriggers: \"azure-messaging-webpubsubservice\", \"WebPubSubServiceClient\", \"real-time\", \"WebSocket\", \"pub/sub\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-mgmt-apicenter-dotnet", + "path": "skills\\azure-mgmt-apicenter-dotnet", + "category": "uncategorized", + "name": "azure-mgmt-apicenter-dotnet", + "description": "Azure API Center SDK for .NET. Centralized API inventory management with governance, versioning, and discovery. Use for creating API services, workspaces, APIs, versions, definitions, environments, deployments, and metadata schemas. Triggers: \"API Center\", \"ApiCenterService\", \"ApiCenterWorkspace\", \"ApiCenterApi\", \"API inventory\", \"API governance\", \"API versioning\", \"API catalog\", \"API discovery\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-mgmt-apicenter-py", + "path": "skills\\azure-mgmt-apicenter-py", + "category": "uncategorized", + "name": "azure-mgmt-apicenter-py", + "description": "Azure API Center Management SDK for Python. Use for managing API inventory, metadata, and governance across your organization.\nTriggers: \"azure-mgmt-apicenter\", \"ApiCenterMgmtClient\", \"API Center\", \"API inventory\", \"API governance\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-mgmt-apimanagement-dotnet", + "path": "skills\\azure-mgmt-apimanagement-dotnet", + "category": "uncategorized", + "name": "azure-mgmt-apimanagement-dotnet", + "description": "Azure Resource Manager SDK for API Management in .NET. Use for MANAGEMENT PLANE operations: creating/managing APIM services, APIs, products, subscriptions, policies, users, groups, gateways, and backends via Azure Resource Manager. Triggers: \"API Management\", \"APIM service\", \"create APIM\", \"manage APIs\", \"ApiManagementServiceResource\", \"API policies\", \"APIM products\", \"APIM subscriptions\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-mgmt-apimanagement-py", + "path": "skills\\azure-mgmt-apimanagement-py", + "category": "uncategorized", + "name": "azure-mgmt-apimanagement-py", + "description": "Azure API Management SDK for Python. Use for managing APIM services, APIs, products, subscriptions, and policies.\nTriggers: \"azure-mgmt-apimanagement\", \"ApiManagementClient\", \"APIM\", \"API gateway\", \"API Management\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-mgmt-applicationinsights-dotnet", + "path": "skills\\azure-mgmt-applicationinsights-dotnet", + "category": "uncategorized", + "name": "azure-mgmt-applicationinsights-dotnet", + "description": "Azure Application Insights SDK for .NET. Application performance monitoring and observability resource management. Use for creating Application Insights components, web tests, workbooks, analytics items, and API keys. Triggers: \"Application Insights\", \"ApplicationInsights\", \"App Insights\", \"APM\", \"application monitoring\", \"web tests\", \"availability tests\", \"workbooks\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-mgmt-arizeaiobservabilityeval-dotnet", + "path": "skills\\azure-mgmt-arizeaiobservabilityeval-dotnet", + "category": "uncategorized", + "name": "azure-mgmt-arizeaiobservabilityeval-dotnet", + "description": "Azure Resource Manager SDK for Arize AI Observability and Evaluation (.NET). Use when managing Arize AI organizations \non Azure via Azure Marketplace, creating/updating/deleting Arize resources, or integrating Arize ML observability \ninto .NET applications. Triggers: \"Arize AI\", \"ML observability\", \"ArizeAIObservabilityEval\", \"Arize organization\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-mgmt-botservice-dotnet", + "path": "skills\\azure-mgmt-botservice-dotnet", + "category": "uncategorized", + "name": "azure-mgmt-botservice-dotnet", + "description": "Azure Resource Manager SDK for Bot Service in .NET. Management plane operations for creating and managing Azure Bot resources, channels (Teams, DirectLine, Slack), and connection settings. Triggers: \"Bot Service\", \"BotResource\", \"Azure Bot\", \"DirectLine channel\", \"Teams channel\", \"bot management .NET\", \"create bot\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-mgmt-botservice-py", + "path": "skills\\azure-mgmt-botservice-py", + "category": "uncategorized", + "name": "azure-mgmt-botservice-py", + "description": "Azure Bot Service Management SDK for Python. Use for creating, managing, and configuring Azure Bot Service resources.\nTriggers: \"azure-mgmt-botservice\", \"AzureBotService\", \"bot management\", \"conversational AI\", \"bot channels\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-mgmt-fabric-dotnet", + "path": "skills\\azure-mgmt-fabric-dotnet", + "category": "uncategorized", + "name": "azure-mgmt-fabric-dotnet", + "description": "Azure Resource Manager SDK for Fabric in .NET. Use for MANAGEMENT PLANE operations: provisioning, scaling, suspending/resuming Microsoft Fabric capacities, checking name availability, and listing SKUs via Azure Resource Manager. Triggers: \"Fabric capacity\", \"create capacity\", \"suspend capacity\", \"resume capacity\", \"Fabric SKU\", \"provision Fabric\", \"ARM Fabric\", \"FabricCapacityResource\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-mgmt-fabric-py", + "path": "skills\\azure-mgmt-fabric-py", + "category": "uncategorized", + "name": "azure-mgmt-fabric-py", + "description": "Azure Fabric Management SDK for Python. Use for managing Microsoft Fabric capacities and resources.\nTriggers: \"azure-mgmt-fabric\", \"FabricMgmtClient\", \"Fabric capacity\", \"Microsoft Fabric\", \"Power BI capacity\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-mgmt-mongodbatlas-dotnet", - "path": "skills/azure-mgmt-mongodbatlas-dotnet", + "path": "skills\\azure-mgmt-mongodbatlas-dotnet", "category": "uncategorized", "name": "azure-mgmt-mongodbatlas-dotnet", "description": "Manage MongoDB Atlas Organizations as Azure ARM resources using Azure.ResourceManager.MongoDBAtlas SDK. Use when creating, updating, listing, or deleting MongoDB Atlas organizations through Azure M...", "risk": "unknown", "source": "community" }, + { + "id": "azure-mgmt-weightsandbiases-dotnet", + "path": "skills\\azure-mgmt-weightsandbiases-dotnet", + "category": "uncategorized", + "name": "azure-mgmt-weightsandbiases-dotnet", + "description": "Azure Weights & Biases SDK for .NET. ML experiment tracking and model management via Azure Marketplace. Use for creating W&B instances, managing SSO, marketplace integration, and ML observability. Triggers: \"Weights and Biases\", \"W&B\", \"WeightsAndBiases\", \"ML experiment tracking\", \"model registry\", \"experiment management\", \"wandb\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-microsoft-playwright-testing-ts", - "path": "skills/azure-microsoft-playwright-testing-ts", + "path": "skills\\azure-microsoft-playwright-testing-ts", "category": "uncategorized", "name": "azure-microsoft-playwright-testing-ts", "description": "Run Playwright tests at scale using Azure Playwright Workspaces (formerly Microsoft Playwright Testing). Use when scaling browser tests across cloud-hosted browsers, integrating with CI/CD pipeline...", "risk": "unknown", "source": "community" }, + { + "id": "azure-monitor-ingestion-java", + "path": "skills\\azure-monitor-ingestion-java", + "category": "uncategorized", + "name": "azure-monitor-ingestion-java", + "description": "Azure Monitor Ingestion SDK for Java. Send custom logs to Azure Monitor via Data Collection Rules (DCR) and Data Collection Endpoints (DCE).\nTriggers: \"LogsIngestionClient java\", \"azure monitor ingestion java\", \"custom logs java\", \"DCR java\", \"data collection rule java\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-monitor-ingestion-py", + "path": "skills\\azure-monitor-ingestion-py", + "category": "uncategorized", + "name": "azure-monitor-ingestion-py", + "description": "Azure Monitor Ingestion SDK for Python. Use for sending custom logs to Log Analytics workspace via Logs Ingestion API.\nTriggers: \"azure-monitor-ingestion\", \"LogsIngestionClient\", \"custom logs\", \"DCR\", \"data collection rule\", \"Log Analytics\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-monitor-opentelemetry-exporter-java", + "path": "skills\\azure-monitor-opentelemetry-exporter-java", + "category": "uncategorized", + "name": "azure-monitor-opentelemetry-exporter-java", + "description": "Azure Monitor OpenTelemetry Exporter for Java. Export OpenTelemetry traces, metrics, and logs to Azure Monitor/Application Insights.\nTriggers: \"AzureMonitorExporter java\", \"opentelemetry azure java\", \"application insights java otel\", \"azure monitor tracing java\".\nNote: This package is DEPRECATED. Migrate to azure-monitor-opentelemetry-autoconfigure.\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-monitor-opentelemetry-exporter-py", + "path": "skills\\azure-monitor-opentelemetry-exporter-py", + "category": "uncategorized", + "name": "azure-monitor-opentelemetry-exporter-py", + "description": "Azure Monitor OpenTelemetry Exporter for Python. Use for low-level OpenTelemetry export to Application Insights.\nTriggers: \"azure-monitor-opentelemetry-exporter\", \"AzureMonitorTraceExporter\", \"AzureMonitorMetricExporter\", \"AzureMonitorLogExporter\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-monitor-opentelemetry-py", + "path": "skills\\azure-monitor-opentelemetry-py", + "category": "uncategorized", + "name": "azure-monitor-opentelemetry-py", + "description": "Azure Monitor OpenTelemetry Distro for Python. Use for one-line Application Insights setup with auto-instrumentation.\nTriggers: \"azure-monitor-opentelemetry\", \"configure_azure_monitor\", \"Application Insights\", \"OpenTelemetry distro\", \"auto-instrumentation\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-monitor-opentelemetry-ts", - "path": "skills/azure-monitor-opentelemetry-ts", + "path": "skills\\azure-monitor-opentelemetry-ts", "category": "uncategorized", "name": "azure-monitor-opentelemetry-ts", "description": "Instrument applications with Azure Monitor and OpenTelemetry for JavaScript (@azure/monitor-opentelemetry). Use when adding distributed tracing, metrics, and logs to Node.js applications with Appli...", "risk": "unknown", "source": "community" }, + { + "id": "azure-monitor-query-java", + "path": "skills\\azure-monitor-query-java", + "category": "uncategorized", + "name": "azure-monitor-query-java", + "description": "Azure Monitor Query SDK for Java. Execute Kusto queries against Log Analytics workspaces and query metrics from Azure resources.\nTriggers: \"LogsQueryClient java\", \"MetricsQueryClient java\", \"kusto query java\", \"log analytics java\", \"azure monitor query java\".\nNote: This package is deprecated. Migrate to azure-monitor-query-logs and azure-monitor-query-metrics.\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-monitor-query-py", + "path": "skills\\azure-monitor-query-py", + "category": "uncategorized", + "name": "azure-monitor-query-py", + "description": "Azure Monitor Query SDK for Python. Use for querying Log Analytics workspaces and Azure Monitor metrics.\nTriggers: \"azure-monitor-query\", \"LogsQueryClient\", \"MetricsQueryClient\", \"Log Analytics\", \"Kusto queries\", \"Azure metrics\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-postgres-ts", + "path": "skills\\azure-postgres-ts", + "category": "uncategorized", + "name": "azure-postgres-ts", + "description": "Connect to Azure Database for PostgreSQL Flexible Server from Node.js/TypeScript using the pg (node-postgres) package. Use for PostgreSQL queries, connection pooling, transactions, and Microsoft Entra ID (passwordless) authentication. Triggers: \"PostgreSQL\", \"postgres\", \"pg client\", \"node-postgres\", \"Azure PostgreSQL connection\", \"PostgreSQL TypeScript\", \"pg Pool\", \"passwordless postgres\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-resource-manager-cosmosdb-dotnet", + "path": "skills\\azure-resource-manager-cosmosdb-dotnet", + "category": "uncategorized", + "name": "azure-resource-manager-cosmosdb-dotnet", + "description": "Azure Resource Manager SDK for Cosmos DB in .NET. Use for MANAGEMENT PLANE operations: creating/managing Cosmos DB accounts, databases, containers, throughput settings, and RBAC via Azure Resource Manager. NOT for data plane operations (CRUD on documents) - use Microsoft.Azure.Cosmos for that. Triggers: \"Cosmos DB account\", \"create Cosmos account\", \"manage Cosmos resources\", \"ARM Cosmos\", \"CosmosDBAccountResource\", \"provision Cosmos DB\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-resource-manager-durabletask-dotnet", + "path": "skills\\azure-resource-manager-durabletask-dotnet", + "category": "uncategorized", + "name": "azure-resource-manager-durabletask-dotnet", + "description": "Azure Resource Manager SDK for Durable Task Scheduler in .NET. Use for MANAGEMENT PLANE operations: creating/managing Durable Task Schedulers, Task Hubs, and retention policies via Azure Resource Manager. Triggers: \"Durable Task Scheduler\", \"create scheduler\", \"task hub\", \"DurableTaskSchedulerResource\", \"provision Durable Task\", \"orchestration scheduler\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-resource-manager-mysql-dotnet", + "path": "skills\\azure-resource-manager-mysql-dotnet", + "category": "uncategorized", + "name": "azure-resource-manager-mysql-dotnet", + "description": "Azure MySQL Flexible Server SDK for .NET. Database management for MySQL Flexible Server deployments. Use for creating servers, databases, firewall rules, configurations, backups, and high availability. Triggers: \"MySQL\", \"MySqlFlexibleServer\", \"MySQL Flexible Server\", \"Azure Database for MySQL\", \"MySQL database management\", \"MySQL firewall\", \"MySQL backup\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-resource-manager-playwright-dotnet", + "path": "skills\\azure-resource-manager-playwright-dotnet", + "category": "uncategorized", + "name": "azure-resource-manager-playwright-dotnet", + "description": "Azure Resource Manager SDK for Microsoft Playwright Testing in .NET. Use for MANAGEMENT PLANE operations: creating/managing Playwright Testing workspaces, checking name availability, and managing workspace quotas via Azure Resource Manager. NOT for running Playwright tests - use Azure.Developer.MicrosoftPlaywrightTesting.NUnit for that. Triggers: \"Playwright workspace\", \"create Playwright Testing workspace\", \"manage Playwright resources\", \"ARM Playwright\", \"PlaywrightWorkspaceResource\", \"provision Playwright Testing\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-resource-manager-postgresql-dotnet", + "path": "skills\\azure-resource-manager-postgresql-dotnet", + "category": "uncategorized", + "name": "azure-resource-manager-postgresql-dotnet", + "description": "Azure PostgreSQL Flexible Server SDK for .NET. Database management for PostgreSQL Flexible Server deployments. Use for creating servers, databases, firewall rules, configurations, backups, and high availability. Triggers: \"PostgreSQL\", \"PostgreSqlFlexibleServer\", \"PostgreSQL Flexible Server\", \"Azure Database for PostgreSQL\", \"PostgreSQL database management\", \"PostgreSQL firewall\", \"PostgreSQL backup\", \"Postgres\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-resource-manager-redis-dotnet", + "path": "skills\\azure-resource-manager-redis-dotnet", + "category": "uncategorized", + "name": "azure-resource-manager-redis-dotnet", + "description": "Azure Resource Manager SDK for Redis in .NET. Use for MANAGEMENT PLANE operations: creating/managing Azure Cache for Redis instances, firewall rules, access keys, patch schedules, linked servers (geo-replication), and private endpoints via Azure Resource Manager. NOT for data plane operations (get/set keys, pub/sub) - use StackExchange.Redis for that. Triggers: \"Redis cache\", \"create Redis\", \"manage Redis\", \"ARM Redis\", \"RedisResource\", \"provision Redis\", \"Azure Cache for Redis\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-resource-manager-sql-dotnet", + "path": "skills\\azure-resource-manager-sql-dotnet", + "category": "uncategorized", + "name": "azure-resource-manager-sql-dotnet", + "description": "Azure Resource Manager SDK for Azure SQL in .NET. Use for MANAGEMENT PLANE operations: creating/managing SQL servers, databases, elastic pools, firewall rules, and failover groups via Azure Resource Manager. NOT for data plane operations (executing queries) - use Microsoft.Data.SqlClient for that. Triggers: \"SQL server\", \"create SQL database\", \"manage SQL resources\", \"ARM SQL\", \"SqlServerResource\", \"provision Azure SQL\", \"elastic pool\", \"firewall rule\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-search-documents-dotnet", + "path": "skills\\azure-search-documents-dotnet", + "category": "uncategorized", + "name": "azure-search-documents-dotnet", + "description": "Azure AI Search SDK for .NET (Azure.Search.Documents). Use for building search applications with full-text, vector, semantic, and hybrid search. Covers SearchClient (queries, document CRUD), SearchIndexClient (index management), and SearchIndexerClient (indexers, skillsets). Triggers: \"Azure Search .NET\", \"SearchClient\", \"SearchIndexClient\", \"vector search C#\", \"semantic search .NET\", \"hybrid search\", \"Azure.Search.Documents\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-search-documents-py", + "path": "skills\\azure-search-documents-py", + "category": "uncategorized", + "name": "azure-search-documents-py", + "description": "Azure AI Search SDK for Python. Use for vector search, hybrid search, semantic ranking, indexing, and skillsets.\nTriggers: \"azure-search-documents\", \"SearchClient\", \"SearchIndexClient\", \"vector search\", \"hybrid search\", \"semantic search\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-search-documents-ts", - "path": "skills/azure-search-documents-ts", + "path": "skills\\azure-search-documents-ts", "category": "uncategorized", "name": "azure-search-documents-ts", "description": "Build search applications using Azure AI Search SDK for JavaScript (@azure/search-documents). Use when creating/managing indexes, implementing vector/hybrid search, semantic ranking, or building ag...", "risk": "unknown", "source": "community" }, + { + "id": "azure-security-keyvault-keys-dotnet", + "path": "skills\\azure-security-keyvault-keys-dotnet", + "category": "uncategorized", + "name": "azure-security-keyvault-keys-dotnet", + "description": "Azure Key Vault Keys SDK for .NET. Client library for managing cryptographic keys in Azure Key Vault and Managed HSM. Use for key creation, rotation, encryption, decryption, signing, and verification. Triggers: \"Key Vault keys\", \"KeyClient\", \"CryptographyClient\", \"RSA key\", \"EC key\", \"encrypt decrypt .NET\", \"key rotation\", \"HSM\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-security-keyvault-keys-java", - "path": "skills/azure-security-keyvault-keys-java", + "path": "skills\\azure-security-keyvault-keys-java", "category": "uncategorized", "name": "azure-security-keyvault-keys-java", "description": "Azure Key Vault Keys Java SDK for cryptographic key management. Use when creating, managing, or using RSA/EC keys, performing encrypt/decrypt/sign/verify operations, or working with HSM-backed keys.", @@ -1684,34 +1621,133 @@ }, { "id": "azure-security-keyvault-secrets-java", - "path": "skills/azure-security-keyvault-secrets-java", + "path": "skills\\azure-security-keyvault-secrets-java", "category": "uncategorized", "name": "azure-security-keyvault-secrets-java", "description": "Azure Key Vault Secrets Java SDK for secret management. Use when storing, retrieving, or managing passwords, API keys, connection strings, or other sensitive configuration data.", "risk": "unknown", "source": "community" }, + { + "id": "azure-servicebus-dotnet", + "path": "skills\\azure-servicebus-dotnet", + "category": "uncategorized", + "name": "azure-servicebus-dotnet", + "description": "Azure Service Bus SDK for .NET. Enterprise messaging with queues, topics, subscriptions, and sessions. Use for reliable message delivery, pub/sub patterns, dead letter handling, and background processing. Triggers: \"Service Bus\", \"ServiceBusClient\", \"ServiceBusSender\", \"ServiceBusReceiver\", \"ServiceBusProcessor\", \"message queue\", \"pub/sub .NET\", \"dead letter queue\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-servicebus-py", + "path": "skills\\azure-servicebus-py", + "category": "uncategorized", + "name": "azure-servicebus-py", + "description": "Azure Service Bus SDK for Python messaging. Use for queues, topics, subscriptions, and enterprise messaging patterns.\nTriggers: \"service bus\", \"ServiceBusClient\", \"queue\", \"topic\", \"subscription\", \"message broker\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-servicebus-ts", - "path": "skills/azure-servicebus-ts", + "path": "skills\\azure-servicebus-ts", "category": "uncategorized", "name": "azure-servicebus-ts", "description": "Build messaging applications using Azure Service Bus SDK for JavaScript (@azure/service-bus). Use when implementing queues, topics/subscriptions, message sessions, dead-letter handling, or enterpri...", "risk": "unknown", "source": "community" }, + { + "id": "azure-speech-to-text-rest-py", + "path": "skills\\azure-speech-to-text-rest-py", + "category": "uncategorized", + "name": "azure-speech-to-text-rest-py", + "description": "Azure Speech to Text REST API for short audio (Python). Use for simple speech recognition of audio files up to 60 seconds without the Speech SDK.\nTriggers: \"speech to text REST\", \"short audio transcription\", \"speech recognition REST API\", \"STT REST\", \"recognize speech REST\".\nDO NOT USE FOR: Long audio (>60 seconds), real-time streaming, batch transcription, custom speech models, speech translation. Use Speech SDK or Batch Transcription API instead.\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-storage-blob-java", - "path": "skills/azure-storage-blob-java", + "path": "skills\\azure-storage-blob-java", "category": "uncategorized", "name": "azure-storage-blob-java", "description": "Build blob storage applications with Azure Storage Blob SDK for Java. Use when uploading, downloading, or managing files in Azure Blob Storage, working with containers, or implementing streaming da...", "risk": "unknown", "source": "community" }, + { + "id": "azure-storage-blob-py", + "path": "skills\\azure-storage-blob-py", + "category": "uncategorized", + "name": "azure-storage-blob-py", + "description": "Azure Blob Storage SDK for Python. Use for uploading, downloading, listing blobs, managing containers, and blob lifecycle.\nTriggers: \"blob storage\", \"BlobServiceClient\", \"ContainerClient\", \"BlobClient\", \"upload blob\", \"download blob\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-storage-blob-rust", + "path": "skills\\azure-storage-blob-rust", + "category": "uncategorized", + "name": "azure-storage-blob-rust", + "description": "Azure Blob Storage SDK for Rust. Use for uploading, downloading, and managing blobs and containers.\nTriggers: \"blob storage rust\", \"BlobClient rust\", \"upload blob rust\", \"download blob rust\", \"container rust\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-storage-blob-ts", + "path": "skills\\azure-storage-blob-ts", + "category": "uncategorized", + "name": "azure-storage-blob-ts", + "description": "Azure Blob Storage JavaScript/TypeScript SDK (@azure/storage-blob) for blob operations. Use for uploading, downloading, listing, and managing blobs and containers. Supports block blobs, append blobs, page blobs, SAS tokens, and streaming. Triggers: \"blob storage\", \"@azure/storage-blob\", \"BlobServiceClient\", \"ContainerClient\", \"upload blob\", \"download blob\", \"SAS token\", \"block blob\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-storage-file-datalake-py", + "path": "skills\\azure-storage-file-datalake-py", + "category": "uncategorized", + "name": "azure-storage-file-datalake-py", + "description": "Azure Data Lake Storage Gen2 SDK for Python. Use for hierarchical file systems, big data analytics, and file/directory operations.\nTriggers: \"data lake\", \"DataLakeServiceClient\", \"FileSystemClient\", \"ADLS Gen2\", \"hierarchical namespace\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-storage-file-share-py", + "path": "skills\\azure-storage-file-share-py", + "category": "uncategorized", + "name": "azure-storage-file-share-py", + "description": "Azure Storage File Share SDK for Python. Use for SMB file shares, directories, and file operations in the cloud.\nTriggers: \"azure-storage-file-share\", \"ShareServiceClient\", \"ShareClient\", \"file share\", \"SMB\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-storage-file-share-ts", + "path": "skills\\azure-storage-file-share-ts", + "category": "uncategorized", + "name": "azure-storage-file-share-ts", + "description": "Azure File Share JavaScript/TypeScript SDK (@azure/storage-file-share) for SMB file share operations. Use for creating shares, managing directories, uploading/downloading files, and handling file metadata. Supports Azure Files SMB protocol scenarios. Triggers: \"file share\", \"@azure/storage-file-share\", \"ShareServiceClient\", \"ShareClient\", \"SMB\", \"Azure Files\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-storage-queue-py", + "path": "skills\\azure-storage-queue-py", + "category": "uncategorized", + "name": "azure-storage-queue-py", + "description": "Azure Queue Storage SDK for Python. Use for reliable message queuing, task distribution, and asynchronous processing.\nTriggers: \"queue storage\", \"QueueServiceClient\", \"QueueClient\", \"message queue\", \"dequeue\".\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "azure-storage-queue-ts", + "path": "skills\\azure-storage-queue-ts", + "category": "uncategorized", + "name": "azure-storage-queue-ts", + "description": "Azure Queue Storage JavaScript/TypeScript SDK (@azure/storage-queue) for message queue operations. Use for sending, receiving, peeking, and deleting messages in queues. Supports visibility timeout, message encoding, and batch operations. Triggers: \"queue storage\", \"@azure/storage-queue\", \"QueueServiceClient\", \"QueueClient\", \"send message\", \"receive message\", \"dequeue\", \"visibility timeout\".\n", + "risk": "unknown", + "source": "community" + }, { "id": "azure-web-pubsub-ts", - "path": "skills/azure-web-pubsub-ts", + "path": "skills\\azure-web-pubsub-ts", "category": "uncategorized", "name": "azure-web-pubsub-ts", "description": "Build real-time messaging applications using Azure Web PubSub SDKs for JavaScript (@azure/web-pubsub, @azure/web-pubsub-client). Use when implementing WebSocket-based real-time features, pub/sub me...", @@ -1720,25 +1756,16 @@ }, { "id": "backend-architect", - "path": "skills/backend-architect", + "path": "skills\\backend-architect", "category": "uncategorized", - "name": "Backend Architect", - "description": "You are a backend system architect specializing in scalable, resilient, and maintainable backend systems and APIs.", + "name": "backend-architect", + "description": "Expert backend architect specializing in scalable API design,\nmicroservices architecture, and distributed systems. Masters REST/GraphQL/gRPC\nAPIs, event-driven architectures, service mesh patterns, and modern backend\nframeworks. Handles service boundary definition, inter-service communication,\nresilience patterns, and observability. Use PROACTIVELY when creating new\nbackend services or APIs.\n", "risk": "unknown", - "source": "unknown" - }, - { - "id": "backend-security-coder", - "path": "skills/backend-security-coder", - "category": "uncategorized", - "name": "Backend Security Coder", - "description": "- Working on backend security coder tasks or workflows - Needing guidance, best practices, or checklists for backend security coder", - "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "backend-dev-guidelines", - "path": "skills/backend-dev-guidelines", + "path": "skills\\backend-dev-guidelines", "category": "uncategorized", "name": "backend-dev-guidelines", "description": "Opinionated backend development standards for Node.js + Express + TypeScript microservices. Covers layered architecture, BaseController pattern, dependency injection, Prisma repositories, Zod valid...", @@ -1747,16 +1774,25 @@ }, { "id": "backend-development-feature-development", - "path": "skills/backend-development-feature-development", + "path": "skills\\backend-development-feature-development", "category": "uncategorized", "name": "backend-development-feature-development", "description": "Orchestrate end-to-end backend feature development from requirements to deployment. Use when coordinating multi-phase feature delivery across teams and services.", "risk": "unknown", "source": "community" }, + { + "id": "backend-security-coder", + "path": "skills\\backend-security-coder", + "category": "uncategorized", + "name": "backend-security-coder", + "description": "Expert in secure backend coding practices specializing in input\nvalidation, authentication, and API security. Use PROACTIVELY for backend\nsecurity implementations or security code reviews.\n", + "risk": "unknown", + "source": "community" + }, { "id": "backtesting-frameworks", - "path": "skills/backtesting-frameworks", + "path": "skills\\backtesting-frameworks", "category": "uncategorized", "name": "backtesting-frameworks", "description": "Build robust backtesting systems for trading strategies with proper handling of look-ahead bias, survivorship bias, and transaction costs. Use when developing trading algorithms, validating strateg...", @@ -1765,7 +1801,7 @@ }, { "id": "bamboohr-automation", - "path": "skills/bamboohr-automation", + "path": "skills\\bamboohr-automation", "category": "uncategorized", "name": "bamboohr-automation", "description": "Automate BambooHR tasks via Rube MCP (Composio): employees, time-off, benefits, dependents, employee updates. Always search tools first for current schemas.", @@ -1774,7 +1810,7 @@ }, { "id": "base", - "path": "skills/libreoffice/base", + "path": "skills\\libreoffice\\base", "category": "libreoffice", "name": "base", "description": "Database management, forms, reports, and data operations with LibreOffice Base.", @@ -1783,25 +1819,16 @@ }, { "id": "basecamp-automation", - "path": "skills/basecamp-automation", + "path": "skills\\basecamp-automation", "category": "uncategorized", "name": "basecamp-automation", "description": "Automate Basecamp project management, to-dos, messages, people, and to-do list organization via Rube MCP (Composio). Always search tools first for current schemas.", "risk": "unknown", "source": "community" }, - { - "id": "bash-pro", - "path": "skills/bash-pro", - "category": "uncategorized", - "name": "Bash Pro", - "description": "- Writing or reviewing Bash scripts for automation, CI/CD, or ops - Hardening shell scripts for safety and portability", - "risk": "unknown", - "source": "unknown" - }, { "id": "bash-defensive-patterns", - "path": "skills/bash-defensive-patterns", + "path": "skills\\bash-defensive-patterns", "category": "uncategorized", "name": "bash-defensive-patterns", "description": "Master defensive Bash programming techniques for production-grade scripts. Use when writing robust shell scripts, CI/CD pipelines, or system utilities requiring fault tolerance and safety.", @@ -1810,16 +1837,25 @@ }, { "id": "bash-linux", - "path": "skills/bash-linux", + "path": "skills\\bash-linux", "category": "uncategorized", "name": "bash-linux", "description": "Bash/Linux terminal patterns. Critical commands, piping, error handling, scripting. Use when working on macOS or Linux systems.", "risk": "unknown", "source": "community" }, + { + "id": "bash-pro", + "path": "skills\\bash-pro", + "category": "uncategorized", + "name": "bash-pro", + "description": "Master of defensive Bash scripting for production automation, CI/CD\npipelines, and system utilities. Expert in safe, portable, and testable shell\nscripts.\n", + "risk": "unknown", + "source": "community" + }, { "id": "bash-scripting", - "path": "skills/bash-scripting", + "path": "skills\\bash-scripting", "category": "uncategorized", "name": "bash-scripting", "description": "Bash scripting workflow for creating production-ready shell scripts with defensive patterns, error handling, and testing.", @@ -1828,7 +1864,7 @@ }, { "id": "bats-testing-patterns", - "path": "skills/bats-testing-patterns", + "path": "skills\\bats-testing-patterns", "category": "uncategorized", "name": "bats-testing-patterns", "description": "Master Bash Automated Testing System (Bats) for comprehensive shell script testing. Use when writing tests for shell scripts, CI/CD pipelines, or requiring test-driven development of shell utilities.", @@ -1837,7 +1873,7 @@ }, { "id": "bazel-build-optimization", - "path": "skills/bazel-build-optimization", + "path": "skills\\bazel-build-optimization", "category": "uncategorized", "name": "bazel-build-optimization", "description": "Optimize Bazel builds for large-scale monorepos. Use when configuring Bazel, implementing remote execution, or optimizing build performance for enterprise codebases.", @@ -1846,7 +1882,7 @@ }, { "id": "beautiful-prose", - "path": "skills/beautiful-prose", + "path": "skills\\beautiful-prose", "category": "uncategorized", "name": "beautiful-prose", "description": "Hard-edged writing style contract for timeless, forceful English prose without AI tics", @@ -1855,7 +1891,7 @@ }, { "id": "behavioral-modes", - "path": "skills/behavioral-modes", + "path": "skills\\behavioral-modes", "category": "uncategorized", "name": "behavioral-modes", "description": "AI operational modes (brainstorm, implement, debug, review, teach, ship, orchestrate). Use to adapt behavior based on task type.", @@ -1864,7 +1900,7 @@ }, { "id": "bevy-ecs-expert", - "path": "skills/bevy-ecs-expert", + "path": "skills\\bevy-ecs-expert", "category": "uncategorized", "name": "bevy-ecs-expert", "description": "Master Bevy's Entity Component System (ECS) in Rust, covering Systems, Queries, Resources, and parallel scheduling.", @@ -1873,7 +1909,7 @@ }, { "id": "billing-automation", - "path": "skills/billing-automation", + "path": "skills\\billing-automation", "category": "uncategorized", "name": "billing-automation", "description": "Build automated billing systems for recurring payments, invoicing, subscription lifecycle, and dunning management. Use when implementing subscription billing, automating invoicing, or managing recu...", @@ -1882,7 +1918,7 @@ }, { "id": "binary-analysis-patterns", - "path": "skills/binary-analysis-patterns", + "path": "skills\\binary-analysis-patterns", "category": "uncategorized", "name": "binary-analysis-patterns", "description": "Master binary analysis patterns including disassembly, decompilation, control flow analysis, and code pattern recognition. Use when analyzing executables, understanding compiled code, or performing...", @@ -1891,7 +1927,7 @@ }, { "id": "bitbucket-automation", - "path": "skills/bitbucket-automation", + "path": "skills\\bitbucket-automation", "category": "uncategorized", "name": "bitbucket-automation", "description": "Automate Bitbucket repositories, pull requests, branches, issues, and workspace management via Rube MCP (Composio). Always search tools first for current schemas.", @@ -1900,16 +1936,16 @@ }, { "id": "blockchain-developer", - "path": "skills/blockchain-developer", + "path": "skills\\blockchain-developer", "category": "uncategorized", - "name": "Blockchain Developer", - "description": "- Working on blockchain developer tasks or workflows - Needing guidance, best practices, or checklists for blockchain developer", + "name": "blockchain-developer", + "description": "Build production-ready Web3 applications, smart contracts, and\ndecentralized systems. Implements DeFi protocols, NFT platforms, DAOs, and\nenterprise blockchain integrations. Use PROACTIVELY for smart contracts, Web3\napps, DeFi protocols, or blockchain infrastructure.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "blockrun", - "path": "skills/blockrun", + "path": "skills\\blockrun", "category": "uncategorized", "name": "blockrun", "description": "Use when user needs capabilities Claude lacks (image generation, real-time X/Twitter data) or explicitly requests external models (\\\"blockrun\\\", \\\"use grok\\\", \\\"use gpt\\\", \\\"da...", @@ -1918,7 +1954,7 @@ }, { "id": "box-automation", - "path": "skills/box-automation", + "path": "skills\\box-automation", "category": "uncategorized", "name": "box-automation", "description": "Automate Box cloud storage operations including file upload/download, search, folder management, sharing, collaborations, and metadata queries via Rube MCP (Composio). Always search tools first for...", @@ -1927,7 +1963,7 @@ }, { "id": "brainstorming", - "path": "skills/brainstorming", + "path": "skills\\brainstorming", "category": "uncategorized", "name": "brainstorming", "description": "Use before creative or constructive work (features, architecture, behavior). Transforms vague ideas into validated designs through disciplined reasoning and collaboration.", @@ -1936,7 +1972,7 @@ }, { "id": "brand-guidelines-anthropic", - "path": "skills/brand-guidelines-anthropic", + "path": "skills\\brand-guidelines-anthropic", "category": "uncategorized", "name": "brand-guidelines-anthropic", "description": "Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatt...", @@ -1945,7 +1981,7 @@ }, { "id": "brand-guidelines-community", - "path": "skills/brand-guidelines-community", + "path": "skills\\brand-guidelines-community", "category": "uncategorized", "name": "brand-guidelines-community", "description": "Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatt...", @@ -1954,7 +1990,7 @@ }, { "id": "brevo-automation", - "path": "skills/brevo-automation", + "path": "skills\\brevo-automation", "category": "uncategorized", "name": "brevo-automation", "description": "Automate Brevo (Sendinblue) tasks via Rube MCP (Composio): manage email campaigns, create/edit templates, track senders, and monitor campaign performance. Always search tools first for current sche...", @@ -1963,7 +1999,7 @@ }, { "id": "broken-authentication", - "path": "skills/broken-authentication", + "path": "skills\\broken-authentication", "category": "uncategorized", "name": "broken-authentication", "description": "This skill should be used when the user asks to \"test for broken authentication vulnerabilities\", \"assess session management security\", \"perform credential stuffing tests\", \"evaluate ...", @@ -1972,7 +2008,7 @@ }, { "id": "browser-automation", - "path": "skills/browser-automation", + "path": "skills\\browser-automation", "category": "uncategorized", "name": "browser-automation", "description": "Browser automation powers web testing, scraping, and AI agent interactions. The difference between a flaky script and a reliable system comes down to understanding selectors, waiting strategies, an...", @@ -1981,7 +2017,7 @@ }, { "id": "browser-extension-builder", - "path": "skills/browser-extension-builder", + "path": "skills\\browser-extension-builder", "category": "uncategorized", "name": "browser-extension-builder", "description": "Expert in building browser extensions that solve real problems - Chrome, Firefox, and cross-browser extensions. Covers extension architecture, manifest v3, content scripts, popup UIs, monetization ...", @@ -1990,7 +2026,7 @@ }, { "id": "bullmq-specialist", - "path": "skills/bullmq-specialist", + "path": "skills\\bullmq-specialist", "category": "uncategorized", "name": "bullmq-specialist", "description": "BullMQ expert for Redis-backed job queues, background processing, and reliable async execution in Node.js/TypeScript applications. Use when: bullmq, bull queue, redis queue, background job, job queue.", @@ -1999,7 +2035,7 @@ }, { "id": "bun-development", - "path": "skills/bun-development", + "path": "skills\\bun-development", "category": "uncategorized", "name": "bun-development", "description": "Modern JavaScript/TypeScript development with Bun runtime. Covers package management, bundling, testing, and migration from Node.js. Use when working with Bun, optimizing JS/TS development speed, o...", @@ -2008,7 +2044,7 @@ }, { "id": "burp-suite-testing", - "path": "skills/burp-suite-testing", + "path": "skills\\burp-suite-testing", "category": "uncategorized", "name": "burp-suite-testing", "description": "This skill should be used when the user asks to \"intercept HTTP traffic\", \"modify web requests\", \"use Burp Suite for testing\", \"perform web vulnerability scanning\", \"test with Burp ...", @@ -2017,16 +2053,16 @@ }, { "id": "business-analyst", - "path": "skills/business-analyst", + "path": "skills\\business-analyst", "category": "uncategorized", - "name": "Business Analyst", - "description": "- Working on business analyst tasks or workflows - Needing guidance, best practices, or checklists for business analyst", + "name": "business-analyst", + "description": "Master modern business analysis with AI-powered analytics,\nreal-time dashboards, and data-driven insights. Build comprehensive KPI\nframeworks, predictive models, and strategic recommendations. Use PROACTIVELY\nfor business intelligence or strategic analysis.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "busybox-on-windows", - "path": "skills/busybox-on-windows", + "path": "skills\\busybox-on-windows", "category": "uncategorized", "name": "busybox-on-windows", "description": "How to use a Win32 build of BusyBox to run many of the standard UNIX command line tools on Windows.", @@ -2035,61 +2071,61 @@ }, { "id": "c-pro", - "path": "skills/c-pro", + "path": "skills\\c-pro", "category": "uncategorized", "name": "c-pro", "description": "Write efficient C code with proper memory management, pointer arithmetic, and system calls. Handles embedded systems, kernel modules, and performance-critical code. Use PROACTIVELY for C optimization, memory issues, or system programming.", "risk": "unknown", "source": "community" }, - { - "id": "c4-code", - "path": "skills/c4-code", - "category": "uncategorized", - "name": "C4 Code", - "description": "- Working on c4 code level: [directory name] tasks or workflows - Needing guidance, best practices, or checklists for c4 code level: [directory name]", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "c4-component", - "path": "skills/c4-component", - "category": "uncategorized", - "name": "C4 Component", - "description": "- Working on c4 component level: [component name] tasks or workflows - Needing guidance, best practices, or checklists for c4 component level: [component name]", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "c4-container", - "path": "skills/c4-container", - "category": "uncategorized", - "name": "C4 Container", - "description": "- Working on c4 container level: system deployment tasks or workflows - Needing guidance, best practices, or checklists for c4 container level: system deployment", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "c4-context", - "path": "skills/c4-context", - "category": "uncategorized", - "name": "C4 Context", - "description": "- Working on c4 context level: system context tasks or workflows - Needing guidance, best practices, or checklists for c4 context level: system context", - "risk": "unknown", - "source": "unknown" - }, { "id": "c4-architecture-c4-architecture", - "path": "skills/c4-architecture-c4-architecture", + "path": "skills\\c4-architecture-c4-architecture", "category": "uncategorized", "name": "c4-architecture-c4-architecture", "description": "Generate comprehensive C4 architecture documentation for an existing repository/codebase using a bottom-up analysis approach.", "risk": "unknown", "source": "community" }, + { + "id": "c4-code", + "path": "skills\\c4-code", + "category": "uncategorized", + "name": "c4-code", + "description": "Expert C4 Code-level documentation specialist. Analyzes code\ndirectories to create comprehensive C4 code-level documentation including\nfunction signatures, arguments, dependencies, and code structure. Use when\ndocumenting code at the lowest C4 level for individual directories and code\nmodules.\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "c4-component", + "path": "skills\\c4-component", + "category": "uncategorized", + "name": "c4-component", + "description": "Expert C4 Component-level documentation specialist. Synthesizes C4\nCode-level documentation into Component-level architecture, defining component\nboundaries, interfaces, and relationships. Creates component diagrams and\ndocumentation. Use when synthesizing code-level documentation into logical\ncomponents.\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "c4-container", + "path": "skills\\c4-container", + "category": "uncategorized", + "name": "c4-container", + "description": "Expert C4 Container-level documentation specialist. Synthesizes\nComponent-level documentation into Container-level architecture, mapping\ncomponents to deployment units, documenting container interfaces as APIs, and\ncreating container diagrams. Use when synthesizing components into deployment\ncontainers and documenting system deployment architecture.\n", + "risk": "unknown", + "source": "community" + }, + { + "id": "c4-context", + "path": "skills\\c4-context", + "category": "uncategorized", + "name": "c4-context", + "description": "Expert C4 Context-level documentation specialist. Creates\nhigh-level system context diagrams, documents personas, user journeys, system\nfeatures, and external dependencies. Synthesizes container and component\ndocumentation with system documentation to create comprehensive context-level\narchitecture. Use when creating the highest-level C4 system context\ndocumentation.\n", + "risk": "unknown", + "source": "community" + }, { "id": "cal-com-automation", - "path": "skills/cal-com-automation", + "path": "skills\\cal-com-automation", "category": "uncategorized", "name": "cal-com-automation", "description": "Automate Cal.com tasks via Rube MCP (Composio): manage bookings, check availability, configure webhooks, and handle teams. Always search tools first for current schemas.", @@ -2098,7 +2134,7 @@ }, { "id": "calc", - "path": "skills/libreoffice/calc", + "path": "skills\\libreoffice\\calc", "category": "libreoffice", "name": "calc", "description": "Spreadsheet creation, format conversion (ODS/XLSX/CSV), formulas, data automation with LibreOffice Calc.", @@ -2107,7 +2143,7 @@ }, { "id": "calendly-automation", - "path": "skills/calendly-automation", + "path": "skills\\calendly-automation", "category": "uncategorized", "name": "calendly-automation", "description": "Automate Calendly scheduling, event management, invitee tracking, availability checks, and organization administration via Rube MCP (Composio). Always search tools first for current schemas.", @@ -2116,7 +2152,7 @@ }, { "id": "canva-automation", - "path": "skills/canva-automation", + "path": "skills\\canva-automation", "category": "uncategorized", "name": "canva-automation", "description": "Automate Canva tasks via Rube MCP (Composio): designs, exports, folders, brand templates, autofill. Always search tools first for current schemas.", @@ -2125,16 +2161,25 @@ }, { "id": "canvas-design", - "path": "skills/canvas-design", + "path": "skills\\canvas-design", "category": "uncategorized", "name": "canvas-design", "description": "Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create ...", "risk": "unknown", "source": "community" }, + { + "id": "carrier-relationship-management", + "path": "skills\\carrier-relationship-management", + "category": "uncategorized", + "name": "carrier-relationship-management", + "description": "Codified expertise for managing carrier portfolios, negotiating freight rates, tracking carrier performance, allocating freight, and maintaining strategic carrier relationships. Informed by transportation managers with 15+ years experience. Includes scorecarding frameworks, RFP processes, market intelligence, and compliance vetting. Use when managing carriers, negotiating rates, evaluating carrier performance, or building freight strategies.\n", + "risk": "safe", + "source": "https://github.com/ai-evos/agent-skills" + }, { "id": "cc-skill-backend-patterns", - "path": "skills/cc-skill-backend-patterns", + "path": "skills\\cc-skill-backend-patterns", "category": "uncategorized", "name": "cc-skill-backend-patterns", "description": "Backend architecture patterns, API design, database optimization, and server-side best practices for Node.js, Express, and Next.js API routes.", @@ -2143,7 +2188,7 @@ }, { "id": "cc-skill-clickhouse-io", - "path": "skills/cc-skill-clickhouse-io", + "path": "skills\\cc-skill-clickhouse-io", "category": "uncategorized", "name": "cc-skill-clickhouse-io", "description": "ClickHouse database patterns, query optimization, analytics, and data engineering best practices for high-performance analytical workloads.", @@ -2152,7 +2197,7 @@ }, { "id": "cc-skill-coding-standards", - "path": "skills/cc-skill-coding-standards", + "path": "skills\\cc-skill-coding-standards", "category": "uncategorized", "name": "cc-skill-coding-standards", "description": "Universal coding standards, best practices, and patterns for TypeScript, JavaScript, React, and Node.js development.", @@ -2161,7 +2206,7 @@ }, { "id": "cc-skill-continuous-learning", - "path": "skills/cc-skill-continuous-learning", + "path": "skills\\cc-skill-continuous-learning", "category": "uncategorized", "name": "cc-skill-continuous-learning", "description": "Development skill from everything-claude-code", @@ -2170,7 +2215,7 @@ }, { "id": "cc-skill-frontend-patterns", - "path": "skills/cc-skill-frontend-patterns", + "path": "skills\\cc-skill-frontend-patterns", "category": "uncategorized", "name": "cc-skill-frontend-patterns", "description": "Frontend development patterns for React, Next.js, state management, performance optimization, and UI best practices.", @@ -2179,7 +2224,7 @@ }, { "id": "cc-skill-project-guidelines-example", - "path": "skills/cc-skill-project-guidelines-example", + "path": "skills\\cc-skill-project-guidelines-example", "category": "uncategorized", "name": "cc-skill-project-guidelines-example", "description": "Project Guidelines Skill (Example)", @@ -2188,7 +2233,7 @@ }, { "id": "cc-skill-security-review", - "path": "skills/cc-skill-security-review", + "path": "skills\\cc-skill-security-review", "category": "uncategorized", "name": "cc-skill-security-review", "description": "Use this skill when adding authentication, handling user input, working with secrets, creating API endpoints, or implementing payment/sensitive features. Provides comprehensive security checklist a...", @@ -2197,7 +2242,7 @@ }, { "id": "cc-skill-strategic-compact", - "path": "skills/cc-skill-strategic-compact", + "path": "skills\\cc-skill-strategic-compact", "category": "uncategorized", "name": "cc-skill-strategic-compact", "description": "Development skill from everything-claude-code", @@ -2206,7 +2251,7 @@ }, { "id": "cdk-patterns", - "path": "skills/cdk-patterns", + "path": "skills\\cdk-patterns", "category": "uncategorized", "name": "cdk-patterns", "description": "Common AWS CDK patterns and constructs for building cloud infrastructure with TypeScript, Python, or Java. Use when designing reusable CDK stacks and L3 constructs.", @@ -2215,16 +2260,25 @@ }, { "id": "changelog-automation", - "path": "skills/changelog-automation", + "path": "skills\\changelog-automation", "category": "uncategorized", "name": "changelog-automation", "description": "Automate changelog generation from commits, PRs, and releases following Keep a Changelog format. Use when setting up release workflows, generating release notes, or standardizing commit conventions.", "risk": "unknown", "source": "community" }, + { + "id": "chrome-extension-developer", + "path": "skills\\chrome-extension-developer", + "category": "uncategorized", + "name": "chrome-extension-developer", + "description": "Expert in building Chrome Extensions using Manifest V3. Covers background scripts, service workers, content scripts, and cross-context communication.", + "risk": "safe", + "source": "community" + }, { "id": "cicd-automation-workflow-automate", - "path": "skills/cicd-automation-workflow-automate", + "path": "skills\\cicd-automation-workflow-automate", "category": "uncategorized", "name": "cicd-automation-workflow-automate", "description": "You are a workflow automation expert specializing in creating efficient CI/CD pipelines, GitHub Actions workflows, and automated development processes. Design automation that reduces manual work, i...", @@ -2233,7 +2287,7 @@ }, { "id": "circleci-automation", - "path": "skills/circleci-automation", + "path": "skills\\circleci-automation", "category": "uncategorized", "name": "circleci-automation", "description": "Automate CircleCI tasks via Rube MCP (Composio): trigger pipelines, monitor workflows/jobs, retrieve artifacts and test metadata. Always search tools first for current schemas.", @@ -2242,7 +2296,7 @@ }, { "id": "clarity-gate", - "path": "skills/clarity-gate", + "path": "skills\\clarity-gate", "category": "uncategorized", "name": "clarity-gate", "description": "Pre-ingestion verification for epistemic quality in RAG systems with 9-point verification and Two-Round HITL workflow", @@ -2251,7 +2305,7 @@ }, { "id": "claude-ally-health", - "path": "skills/claude-ally-health", + "path": "skills\\claude-ally-health", "category": "uncategorized", "name": "claude-ally-health", "description": "A health assistant skill for medical information analysis, symptom tracking, and wellness guidance.", @@ -2260,7 +2314,7 @@ }, { "id": "claude-code-guide", - "path": "skills/claude-code-guide", + "path": "skills\\claude-code-guide", "category": "uncategorized", "name": "claude-code-guide", "description": "Master guide for using Claude Code effectively. Includes configuration templates, prompting strategies \\\"Thinking\\\" keywords, debugging techniques, and best practices for interacting wit...", @@ -2269,7 +2323,7 @@ }, { "id": "claude-d3js-skill", - "path": "skills/claude-d3js-skill", + "path": "skills\\claude-d3js-skill", "category": "uncategorized", "name": "claude-d3js-skill", "description": "Creating interactive data visualisations using d3.js. This skill should be used when creating custom charts, graphs, network diagrams, geographic visualisations, or any complex SVG-based data visua...", @@ -2278,7 +2332,7 @@ }, { "id": "claude-scientific-skills", - "path": "skills/claude-scientific-skills", + "path": "skills\\claude-scientific-skills", "category": "uncategorized", "name": "claude-scientific-skills", "description": "Scientific research and analysis skills", @@ -2287,7 +2341,7 @@ }, { "id": "claude-speed-reader", - "path": "skills/claude-speed-reader", + "path": "skills\\claude-speed-reader", "category": "uncategorized", "name": "claude-speed-reader", "description": "-Speed read Claude's responses at 600+ WPM using RSVP with Spritz-style ORP highlighting", @@ -2296,7 +2350,7 @@ }, { "id": "claude-win11-speckit-update-skill", - "path": "skills/claude-win11-speckit-update-skill", + "path": "skills\\claude-win11-speckit-update-skill", "category": "uncategorized", "name": "claude-win11-speckit-update-skill", "description": "Windows 11 system management", @@ -2305,7 +2359,7 @@ }, { "id": "clean-code", - "path": "skills/clean-code", + "path": "skills\\clean-code", "category": "uncategorized", "name": "clean-code", "description": "Applies principles from Robert C. Martin's 'Clean Code'. Use this skill when writing, reviewing, or refactoring code to ensure high quality, readability, and maintainability. Covers naming, functio...", @@ -2314,7 +2368,7 @@ }, { "id": "clerk-auth", - "path": "skills/clerk-auth", + "path": "skills\\clerk-auth", "category": "uncategorized", "name": "clerk-auth", "description": "Expert patterns for Clerk auth implementation, middleware, organizations, webhooks, and user sync Use when: adding authentication, clerk auth, user authentication, sign in, sign up.", @@ -2323,7 +2377,7 @@ }, { "id": "clickup-automation", - "path": "skills/clickup-automation", + "path": "skills\\clickup-automation", "category": "uncategorized", "name": "clickup-automation", "description": "Automate ClickUp project management including tasks, spaces, folders, lists, comments, and team operations via Rube MCP (Composio). Always search tools first for current schemas.", @@ -2332,7 +2386,7 @@ }, { "id": "close-automation", - "path": "skills/close-automation", + "path": "skills\\close-automation", "category": "uncategorized", "name": "close-automation", "description": "Automate Close CRM tasks via Rube MCP (Composio): create leads, manage calls/SMS, handle tasks, and track notes. Always search tools first for current schemas.", @@ -2341,16 +2395,16 @@ }, { "id": "cloud-architect", - "path": "skills/cloud-architect", + "path": "skills\\cloud-architect", "category": "uncategorized", - "name": "Cloud Architect", - "description": "- Working on cloud architect tasks or workflows - Needing guidance, best practices, or checklists for cloud architect", + "name": "cloud-architect", + "description": "Expert cloud architect specializing in AWS/Azure/GCP multi-cloud\ninfrastructure design, advanced IaC (Terraform/OpenTofu/CDK), FinOps cost\noptimization, and modern architectural patterns. Masters serverless,\nmicroservices, security, compliance, and disaster recovery. Use PROACTIVELY\nfor cloud architecture, cost optimization, migration planning, or multi-cloud\nstrategies.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "cloud-devops", - "path": "skills/cloud-devops", + "path": "skills\\cloud-devops", "category": "uncategorized", "name": "cloud-devops", "description": "Cloud infrastructure and DevOps workflow covering AWS, Azure, GCP, Kubernetes, Terraform, CI/CD, monitoring, and cloud-native development.", @@ -2359,16 +2413,25 @@ }, { "id": "cloud-penetration-testing", - "path": "skills/cloud-penetration-testing", + "path": "skills\\cloud-penetration-testing", "category": "uncategorized", "name": "cloud-penetration-testing", "description": "This skill should be used when the user asks to \"perform cloud penetration testing\", \"assess Azure or AWS or GCP security\", \"enumerate cloud resources\", \"exploit cloud misconfiguratio...", "risk": "unknown", "source": "community" }, + { + "id": "cloudflare-workers-expert", + "path": "skills\\cloudflare-workers-expert", + "category": "uncategorized", + "name": "cloudflare-workers-expert", + "description": "Expert in Cloudflare Workers and the Edge Computing ecosystem. Covers Wrangler, KV, D1, Durable Objects, and R2 storage.", + "risk": "safe", + "source": "community" + }, { "id": "cloudformation-best-practices", - "path": "skills/cloudformation-best-practices", + "path": "skills\\cloudformation-best-practices", "category": "uncategorized", "name": "cloudformation-best-practices", "description": "CloudFormation template optimization, nested stacks, drift detection, and production-ready patterns. Use when writing or reviewing CF templates.", @@ -2377,7 +2440,7 @@ }, { "id": "coda-automation", - "path": "skills/coda-automation", + "path": "skills\\coda-automation", "category": "uncategorized", "name": "coda-automation", "description": "Automate Coda tasks via Rube MCP (Composio): manage docs, pages, tables, rows, formulas, permissions, and publishing. Always search tools first for current schemas.", @@ -2386,7 +2449,7 @@ }, { "id": "code-documentation-code-explain", - "path": "skills/code-documentation-code-explain", + "path": "skills\\code-documentation-code-explain", "category": "uncategorized", "name": "code-documentation-code-explain", "description": "You are a code education expert specializing in explaining complex code through clear narratives, visual diagrams, and step-by-step breakdowns. Transform difficult concepts into understandable expl...", @@ -2395,7 +2458,7 @@ }, { "id": "code-documentation-doc-generate", - "path": "skills/code-documentation-doc-generate", + "path": "skills\\code-documentation-doc-generate", "category": "uncategorized", "name": "code-documentation-doc-generate", "description": "You are a documentation expert specializing in creating comprehensive, maintainable documentation from code. Generate API docs, architecture diagrams, user guides, and technical references using AI...", @@ -2404,7 +2467,7 @@ }, { "id": "code-refactoring-context-restore", - "path": "skills/code-refactoring-context-restore", + "path": "skills\\code-refactoring-context-restore", "category": "uncategorized", "name": "code-refactoring-context-restore", "description": "Use when working with code refactoring context restore", @@ -2413,7 +2476,7 @@ }, { "id": "code-refactoring-refactor-clean", - "path": "skills/code-refactoring-refactor-clean", + "path": "skills\\code-refactoring-refactor-clean", "category": "uncategorized", "name": "code-refactoring-refactor-clean", "description": "You are a code refactoring expert specializing in clean code principles, SOLID design patterns, and modern software engineering best practices. Analyze and refactor the provided code to improve its...", @@ -2422,7 +2485,7 @@ }, { "id": "code-refactoring-tech-debt", - "path": "skills/code-refactoring-tech-debt", + "path": "skills\\code-refactoring-tech-debt", "category": "uncategorized", "name": "code-refactoring-tech-debt", "description": "You are a technical debt expert specializing in identifying, quantifying, and prioritizing technical debt in software projects. Analyze the codebase to uncover debt, assess its impact, and create acti", @@ -2431,7 +2494,7 @@ }, { "id": "code-review-ai-ai-review", - "path": "skills/code-review-ai-ai-review", + "path": "skills\\code-review-ai-ai-review", "category": "uncategorized", "name": "code-review-ai-ai-review", "description": "You are an expert AI-powered code review specialist combining automated static analysis, intelligent pattern recognition, and modern DevOps practices. Leverage AI tools (GitHub Copilot, Qodo, GPT-5, C", @@ -2440,7 +2503,7 @@ }, { "id": "code-review-checklist", - "path": "skills/code-review-checklist", + "path": "skills\\code-review-checklist", "category": "uncategorized", "name": "code-review-checklist", "description": "Comprehensive checklist for conducting thorough code reviews covering functionality, security, performance, and maintainability", @@ -2449,7 +2512,7 @@ }, { "id": "code-review-excellence", - "path": "skills/code-review-excellence", + "path": "skills\\code-review-excellence", "category": "uncategorized", "name": "code-review-excellence", "description": "Master effective code review practices to provide constructive feedback, catch bugs early, and foster knowledge sharing while maintaining team morale. Use when reviewing pull requests, establishing...", @@ -2458,7 +2521,7 @@ }, { "id": "code-reviewer", - "path": "skills/code-reviewer", + "path": "skills\\code-reviewer", "category": "uncategorized", "name": "code-reviewer", "description": "Elite code review expert specializing in modern AI-powered code analysis, security vulnerabilities, performance optimization, and production reliability. Masters static analysis tools, security scanning, and configuration review with 2024/2025 best practices. Use PROACTIVELY for code quality assurance.", @@ -2467,7 +2530,7 @@ }, { "id": "codebase-cleanup-deps-audit", - "path": "skills/codebase-cleanup-deps-audit", + "path": "skills\\codebase-cleanup-deps-audit", "category": "uncategorized", "name": "codebase-cleanup-deps-audit", "description": "You are a dependency security expert specializing in vulnerability scanning, license compliance, and supply chain security. Analyze project dependencies for known vulnerabilities, licensing issues,...", @@ -2476,7 +2539,7 @@ }, { "id": "codebase-cleanup-refactor-clean", - "path": "skills/codebase-cleanup-refactor-clean", + "path": "skills\\codebase-cleanup-refactor-clean", "category": "uncategorized", "name": "codebase-cleanup-refactor-clean", "description": "You are a code refactoring expert specializing in clean code principles, SOLID design patterns, and modern software engineering best practices. Analyze and refactor the provided code to improve its...", @@ -2485,7 +2548,7 @@ }, { "id": "codebase-cleanup-tech-debt", - "path": "skills/codebase-cleanup-tech-debt", + "path": "skills\\codebase-cleanup-tech-debt", "category": "uncategorized", "name": "codebase-cleanup-tech-debt", "description": "You are a technical debt expert specializing in identifying, quantifying, and prioritizing technical debt in software projects. Analyze the codebase to uncover debt, assess its impact, and create acti", @@ -2494,7 +2557,7 @@ }, { "id": "codex-review", - "path": "skills/codex-review", + "path": "skills\\codex-review", "category": "uncategorized", "name": "codex-review", "description": "Professional code review with auto CHANGELOG generation, integrated with Codex AI", @@ -2503,7 +2566,7 @@ }, { "id": "commit", - "path": "skills/commit", + "path": "skills\\commit", "category": "uncategorized", "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 re...", @@ -2512,16 +2575,16 @@ }, { "id": "competitive-landscape", - "path": "skills/competitive-landscape", + "path": "skills\\competitive-landscape", "category": "uncategorized", - "name": "Competitive Landscape", - "description": "Comprehensive frameworks for analyzing competition, identifying differentiation opportunities, and developing winning market positioning strategies.", + "name": "competitive-landscape", + "description": "This skill should be used when the user asks to \\\\\\\"analyze\ncompetitors\", \"assess competitive landscape\", \"identify differentiation\",\n\"evaluate market positioning\", \"apply Porter's Five Forces\", or requests\ncompetitive strategy analysis.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "competitor-alternatives", - "path": "skills/competitor-alternatives", + "path": "skills\\competitor-alternatives", "category": "uncategorized", "name": "competitor-alternatives", "description": "When the user wants to create competitor comparison or alternative pages for SEO and sales enablement. Also use when the user mentions 'alternative page,' 'vs page,' 'competitor comparison,' 'compa...", @@ -2530,7 +2593,7 @@ }, { "id": "comprehensive-review-full-review", - "path": "skills/comprehensive-review-full-review", + "path": "skills\\comprehensive-review-full-review", "category": "uncategorized", "name": "comprehensive-review-full-review", "description": "Use when working with comprehensive review full review", @@ -2539,7 +2602,7 @@ }, { "id": "comprehensive-review-pr-enhance", - "path": "skills/comprehensive-review-pr-enhance", + "path": "skills\\comprehensive-review-pr-enhance", "category": "uncategorized", "name": "comprehensive-review-pr-enhance", "description": "You are a PR optimization expert specializing in creating high-quality pull requests that facilitate efficient code reviews. Generate comprehensive PR descriptions, automate review processes, and e...", @@ -2548,7 +2611,7 @@ }, { "id": "computer-use-agents", - "path": "skills/computer-use-agents", + "path": "skills\\computer-use-agents", "category": "uncategorized", "name": "computer-use-agents", "description": "Build AI agents that interact with computers like humans do - viewing screens, moving cursors, clicking buttons, and typing text. Covers Anthropic's Computer Use, OpenAI's Operator/CUA, and open-so...", @@ -2557,7 +2620,7 @@ }, { "id": "computer-vision-expert", - "path": "skills/computer-vision-expert", + "path": "skills\\computer-vision-expert", "category": "uncategorized", "name": "computer-vision-expert", "description": "SOTA Computer Vision Expert (2026). Specialized in YOLO26, Segment Anything 3 (SAM 3), Vision Language Models, and real-time spatial analysis.", @@ -2566,34 +2629,16 @@ }, { "id": "concise-planning", - "path": "skills/concise-planning", + "path": "skills\\concise-planning", "category": "uncategorized", "name": "concise-planning", "description": "Use when a user asks for a plan for a coding task, to generate a clear, actionable, and atomic checklist.", "risk": "unknown", "source": "community" }, - { - "id": "conductor-setup", - "path": "skills/conductor-setup", - "category": "uncategorized", - "name": "Conductor Setup", - "description": "Initialize or resume Conductor project setup. This command creates foundational project documentation through interactive Q&A.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "conductor-validator", - "path": "skills/conductor-validator", - "category": "uncategorized", - "name": "Conductor Validator", - "description": "ls -la conductor/", - "risk": "unknown", - "source": "unknown" - }, { "id": "conductor-implement", - "path": "skills/conductor-implement", + "path": "skills\\conductor-implement", "category": "uncategorized", "name": "conductor-implement", "description": "Execute tasks from a track's implementation plan following TDD workflow", @@ -2602,7 +2647,7 @@ }, { "id": "conductor-manage", - "path": "skills/conductor-manage", + "path": "skills\\conductor-manage", "category": "uncategorized", "name": "conductor-manage", "description": "Manage track lifecycle: archive, restore, delete, rename, and cleanup", @@ -2611,7 +2656,7 @@ }, { "id": "conductor-new-track", - "path": "skills/conductor-new-track", + "path": "skills\\conductor-new-track", "category": "uncategorized", "name": "conductor-new-track", "description": "Create a new track with specification and phased implementation plan", @@ -2620,43 +2665,52 @@ }, { "id": "conductor-revert", - "path": "skills/conductor-revert", + "path": "skills\\conductor-revert", "category": "uncategorized", "name": "conductor-revert", "description": "Git-aware undo by logical work unit (track, phase, or task)", "risk": "unknown", "source": "community" }, + { + "id": "conductor-setup", + "path": "skills\\conductor-setup", + "category": "uncategorized", + "name": "conductor-setup", + "description": "Initialize project with Conductor artifacts (product definition,\ntech stack, workflow, style guides)\n", + "risk": "unknown", + "source": "community" + }, { "id": "conductor-status", - "path": "skills/conductor-status", + "path": "skills\\conductor-status", "category": "uncategorized", "name": "conductor-status", "description": "Display project status, active tracks, and next actions", "risk": "unknown", "source": "community" }, + { + "id": "conductor-validator", + "path": "skills\\conductor-validator", + "category": "uncategorized", + "name": "conductor-validator", + "description": "Validates Conductor project artifacts for completeness,\nconsistency, and correctness. Use after setup, when diagnosing issues, or\nbefore implementation to verify project context.\n", + "risk": "unknown", + "source": "community" + }, { "id": "confluence-automation", - "path": "skills/confluence-automation", + "path": "skills\\confluence-automation", "category": "uncategorized", "name": "confluence-automation", "description": "Automate Confluence page creation, content search, space management, labels, and hierarchy navigation via Rube MCP (Composio). Always search tools first for current schemas.", "risk": "unknown", "source": "community" }, - { - "id": "content-marketer", - "path": "skills/content-marketer", - "category": "uncategorized", - "name": "Content Marketer", - "description": "- Working on content marketer tasks or workflows - Needing guidance, best practices, or checklists for content marketer", - "risk": "unknown", - "source": "unknown" - }, { "id": "content-creator", - "path": "skills/content-creator", + "path": "skills\\content-creator", "category": "uncategorized", "name": "content-creator", "description": "Create SEO-optimized marketing content with consistent brand voice. Includes brand voice analyzer, SEO optimizer, content frameworks, and social media templates. Use when writing blog posts, creati...", @@ -2664,26 +2718,17 @@ "source": "community" }, { - "id": "context-driven-development", - "path": "skills/context-driven-development", + "id": "content-marketer", + "path": "skills\\content-marketer", "category": "uncategorized", - "name": "Context Driven Development", - "description": "Guide for implementing and maintaining context as a managed artifact alongside code, enabling consistent AI interactions and team alignment through structured project documentation.", + "name": "content-marketer", + "description": "Elite content marketing strategist specializing in AI-powered\ncontent creation, omnichannel distribution, SEO optimization, and data-driven\nperformance marketing. Masters modern content tools, social media automation,\nand conversion optimization with 2024/2025 best practices. Use PROACTIVELY for\ncomprehensive content marketing.\n", "risk": "unknown", - "source": "unknown" - }, - { - "id": "context-manager", - "path": "skills/context-manager", - "category": "uncategorized", - "name": "Context Manager", - "description": "- Working on context manager tasks or workflows - Needing guidance, best practices, or checklists for context manager", - "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "context-compression", - "path": "skills/context-compression", + "path": "skills\\context-compression", "category": "uncategorized", "name": "context-compression", "description": "Design and evaluate compression strategies for long-running sessions", @@ -2692,16 +2737,25 @@ }, { "id": "context-degradation", - "path": "skills/context-degradation", + "path": "skills\\context-degradation", "category": "uncategorized", "name": "context-degradation", "description": "Recognize patterns of context failure: lost-in-middle, poisoning, distraction, and clash", "risk": "safe", "source": "https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering/tree/main/skills/context-degradation" }, + { + "id": "context-driven-development", + "path": "skills\\context-driven-development", + "category": "uncategorized", + "name": "context-driven-development", + "description": "Use this skill when working with Conductor's context-driven\ndevelopment methodology, managing project context artifacts, or understanding\nthe relationship between product.md, tech-stack.md, and workflow.md files.\n", + "risk": "unknown", + "source": "community" + }, { "id": "context-fundamentals", - "path": "skills/context-fundamentals", + "path": "skills\\context-fundamentals", "category": "uncategorized", "name": "context-fundamentals", "description": "Understand what context is, why it matters, and the anatomy of context in agent systems", @@ -2710,7 +2764,7 @@ }, { "id": "context-management-context-restore", - "path": "skills/context-management-context-restore", + "path": "skills\\context-management-context-restore", "category": "uncategorized", "name": "context-management-context-restore", "description": "Use when working with context management context restore", @@ -2719,16 +2773,25 @@ }, { "id": "context-management-context-save", - "path": "skills/context-management-context-save", + "path": "skills\\context-management-context-save", "category": "uncategorized", "name": "context-management-context-save", "description": "Use when working with context management context save", "risk": "unknown", "source": "community" }, + { + "id": "context-manager", + "path": "skills\\context-manager", + "category": "uncategorized", + "name": "context-manager", + "description": "Elite AI context engineering specialist mastering dynamic context\nmanagement, vector databases, knowledge graphs, and intelligent memory\nsystems. Orchestrates context across multi-agent workflows, enterprise AI\nsystems, and long-running projects with 2024/2025 best practices. Use\nPROACTIVELY for complex AI orchestration.\n", + "risk": "unknown", + "source": "community" + }, { "id": "context-optimization", - "path": "skills/context-optimization", + "path": "skills\\context-optimization", "category": "uncategorized", "name": "context-optimization", "description": "Apply compaction, masking, and caching strategies", @@ -2737,7 +2800,7 @@ }, { "id": "context-window-management", - "path": "skills/context-window-management", + "path": "skills\\context-window-management", "category": "uncategorized", "name": "context-window-management", "description": "Strategies for managing LLM context windows including summarization, trimming, routing, and avoiding context rot Use when: context window, token limit, context management, context engineering, long...", @@ -2746,7 +2809,7 @@ }, { "id": "context7-auto-research", - "path": "skills/context7-auto-research", + "path": "skills\\context7-auto-research", "category": "uncategorized", "name": "context7-auto-research", "description": "Automatically fetch latest library/framework documentation for Claude Code via Context7 API", @@ -2755,7 +2818,7 @@ }, { "id": "conversation-memory", - "path": "skills/conversation-memory", + "path": "skills\\conversation-memory", "category": "uncategorized", "name": "conversation-memory", "description": "Persistent memory systems for LLM conversations including short-term, long-term, and entity-based memory Use when: conversation memory, remember, memory persistence, long-term memory, chat history.", @@ -2764,7 +2827,7 @@ }, { "id": "convertkit-automation", - "path": "skills/convertkit-automation", + "path": "skills\\convertkit-automation", "category": "uncategorized", "name": "convertkit-automation", "description": "Automate ConvertKit (Kit) tasks via Rube MCP (Composio): manage subscribers, tags, broadcasts, and broadcast stats. Always search tools first for current schemas.", @@ -2773,7 +2836,7 @@ }, { "id": "copilot-sdk", - "path": "skills/copilot-sdk", + "path": "skills\\copilot-sdk", "category": "uncategorized", "name": "copilot-sdk", "description": "Build applications powered by GitHub Copilot using the Copilot SDK. Use when creating programmatic integrations with Copilot across Node.js/TypeScript, Python, Go, or .NET. Covers session managemen...", @@ -2782,7 +2845,7 @@ }, { "id": "copy-editing", - "path": "skills/copy-editing", + "path": "skills\\copy-editing", "category": "uncategorized", "name": "copy-editing", "description": "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,' 'proofread,' 'polish this,' 'make this ...", @@ -2791,16 +2854,16 @@ }, { "id": "copywriting", - "path": "skills/copywriting", + "path": "skills\\copywriting", "category": "uncategorized", - "name": "Copywriting", - "description": "Produce **clear, credible, and action-oriented marketing copy** that aligns with user intent and business goals.", + "name": "copywriting", + "description": "Use this skill when writing, rewriting, or improving marketing copy for any page (homepage, landing page, pricing, feature, product, or about page). This skill produces clear, compelling, and testable copy while enforcing alignment, honesty, and conversion best practices.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "core-components", - "path": "skills/core-components", + "path": "skills\\core-components", "category": "uncategorized", "name": "core-components", "description": "Core component library and design system patterns. Use when building UI, using design tokens, or working with the component library.", @@ -2809,7 +2872,7 @@ }, { "id": "cost-optimization", - "path": "skills/cost-optimization", + "path": "skills\\cost-optimization", "category": "uncategorized", "name": "cost-optimization", "description": "Optimize cloud costs through resource rightsizing, tagging strategies, reserved instances, and spending analysis. Use when reducing cloud expenses, analyzing infrastructure costs, or implementing c...", @@ -2818,16 +2881,16 @@ }, { "id": "cpp-pro", - "path": "skills/cpp-pro", + "path": "skills\\cpp-pro", "category": "uncategorized", - "name": "Cpp Pro", - "description": "- Working on cpp pro tasks or workflows - Needing guidance, best practices, or checklists for cpp pro", + "name": "cpp-pro", + "description": "Write idiomatic C++ code with modern features, RAII, smart\npointers, and STL algorithms. Handles templates, move semantics, and\nperformance optimization. Use PROACTIVELY for C++ refactoring, memory safety,\nor complex C++ patterns.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "cqrs-implementation", - "path": "skills/cqrs-implementation", + "path": "skills\\cqrs-implementation", "category": "uncategorized", "name": "cqrs-implementation", "description": "Implement Command Query Responsibility Segregation for scalable architectures. Use when separating read and write models, optimizing query performance, or building event-sourced systems.", @@ -2836,7 +2899,7 @@ }, { "id": "create-pr", - "path": "skills/create-pr", + "path": "skills\\create-pr", "category": "uncategorized", "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.", @@ -2845,7 +2908,7 @@ }, { "id": "crewai", - "path": "skills/crewai", + "path": "skills\\crewai", "category": "uncategorized", "name": "crewai", "description": "Expert in CrewAI - the leading role-based multi-agent framework used by 60% of Fortune 500 companies. Covers agent design with roles and goals, task definition, crew orchestration, process types (s...", @@ -2854,25 +2917,25 @@ }, { "id": "crypto-bd-agent", - "path": "skills/crypto-bd-agent", + "path": "skills\\crypto-bd-agent", "category": "uncategorized", - "name": "Crypto Bd Agent", - "description": "> Production-tested patterns for building AI agents that autonomously discover, > evaluate, and acquire token listings for cryptocurrency exchanges.", - "risk": "unknown", - "source": "unknown" + "name": "crypto-bd-agent", + "description": "Autonomous crypto business development patterns \u2014 multi-chain token discovery, 100-point scoring with wallet forensics, x402 micropayments, ERC-8004 on-chain identity, LLM cascade routing, and pipeline automation for CEX/DEX listing acquisition. Use when building AI agents for crypto BD, token evaluation, exchange listing outreach, or autonomous commerce with payment protocols.\n", + "risk": "safe", + "source": "community" }, { "id": "csharp-pro", - "path": "skills/csharp-pro", + "path": "skills\\csharp-pro", "category": "uncategorized", - "name": "Csharp Pro", - "description": "- Working on csharp pro tasks or workflows - Needing guidance, best practices, or checklists for csharp pro", + "name": "csharp-pro", + "description": "Write modern C# code with advanced features like records, pattern\nmatching, and async/await. Optimizes .NET applications, implements enterprise\npatterns, and ensures comprehensive testing. Use PROACTIVELY for C#\nrefactoring, performance optimization, or complex .NET solutions.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "culture-index", - "path": "skills/culture-index", + "path": "skills\\culture-index", "category": "uncategorized", "name": "culture-index", "description": "Index and search culture documentation", @@ -2881,16 +2944,25 @@ }, { "id": "customer-support", - "path": "skills/customer-support", + "path": "skills\\customer-support", "category": "uncategorized", - "name": "Customer Support", - "description": "- Working on customer support tasks or workflows - Needing guidance, best practices, or checklists for customer support", + "name": "customer-support", + "description": "Elite AI-powered customer support specialist mastering\nconversational AI, automated ticketing, sentiment analysis, and omnichannel\nsupport experiences. Integrates modern support tools, chatbot platforms, and\nCX optimization with 2024/2025 best practices. Use PROACTIVELY for\ncomprehensive customer experience management.\n", "risk": "unknown", - "source": "unknown" + "source": "community" + }, + { + "id": "customs-trade-compliance", + "path": "skills\\customs-trade-compliance", + "category": "uncategorized", + "name": "customs-trade-compliance", + "description": "Codified expertise for customs documentation, tariff classification, duty optimisation, restricted party screening, and regulatory compliance across multiple jurisdictions. Informed by trade compliance specialists with 15+ years experience. Includes HS classification logic, Incoterms application, FTA utilisation, and penalty mitigation. Use when handling customs clearance, tariff classification, trade compliance, import/export documentation, or duty optimisation.\n", + "risk": "safe", + "source": "https://github.com/ai-evos/agent-skills" }, { "id": "daily-news-report", - "path": "skills/daily-news-report", + "path": "skills\\daily-news-report", "category": "uncategorized", "name": "daily-news-report", "description": "Scrapes content based on a preset URL list, filters high-quality technical information, and generates daily Markdown reports.", @@ -2899,25 +2971,16 @@ }, { "id": "data-engineer", - "path": "skills/data-engineer", + "path": "skills\\data-engineer", "category": "uncategorized", - "name": "Data Engineer", - "description": "You are a data engineer specializing in scalable data pipelines, modern data architecture, and analytics infrastructure.", + "name": "data-engineer", + "description": "Build scalable data pipelines, modern data warehouses, and\nreal-time streaming architectures. Implements Apache Spark, dbt, Airflow, and\ncloud-native data platforms. Use PROACTIVELY for data pipeline design,\nanalytics infrastructure, or modern data stack implementation.\n", "risk": "unknown", - "source": "unknown" - }, - { - "id": "data-scientist", - "path": "skills/data-scientist", - "category": "uncategorized", - "name": "Data Scientist", - "description": "- Working on data scientist tasks or workflows - Needing guidance, best practices, or checklists for data scientist", - "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "data-engineering-data-driven-feature", - "path": "skills/data-engineering-data-driven-feature", + "path": "skills\\data-engineering-data-driven-feature", "category": "uncategorized", "name": "data-engineering-data-driven-feature", "description": "Build features guided by data insights, A/B testing, and continuous measurement using specialized agents for analysis, implementation, and experimentation.", @@ -2926,7 +2989,7 @@ }, { "id": "data-engineering-data-pipeline", - "path": "skills/data-engineering-data-pipeline", + "path": "skills\\data-engineering-data-pipeline", "category": "uncategorized", "name": "data-engineering-data-pipeline", "description": "You are a data pipeline architecture expert specializing in scalable, reliable, and cost-effective data pipelines for batch and streaming data processing.", @@ -2935,16 +2998,25 @@ }, { "id": "data-quality-frameworks", - "path": "skills/data-quality-frameworks", + "path": "skills\\data-quality-frameworks", "category": "uncategorized", "name": "data-quality-frameworks", "description": "Implement data quality validation with Great Expectations, dbt tests, and data contracts. Use when building data quality pipelines, implementing validation rules, or establishing data contracts.", "risk": "unknown", "source": "community" }, + { + "id": "data-scientist", + "path": "skills\\data-scientist", + "category": "uncategorized", + "name": "data-scientist", + "description": "Expert data scientist for advanced analytics, machine learning, and\nstatistical modeling. Handles complex data analysis, predictive modeling, and\nbusiness intelligence. Use PROACTIVELY for data analysis tasks, ML modeling,\nstatistical analysis, and data-driven insights.\n", + "risk": "unknown", + "source": "community" + }, { "id": "data-storytelling", - "path": "skills/data-storytelling", + "path": "skills\\data-storytelling", "category": "uncategorized", "name": "data-storytelling", "description": "Transform data into compelling narratives using visualization, context, and persuasive structure. Use when presenting analytics to stakeholders, creating data reports, or building executive present...", @@ -2953,7 +3025,7 @@ }, { "id": "data-structure-protocol", - "path": "skills/data-structure-protocol", + "path": "skills\\data-structure-protocol", "category": "uncategorized", "name": "data-structure-protocol", "description": "Give agents persistent structural memory of a codebase \u2014 navigate dependencies, track public APIs, and understand why connections exist without re-reading the whole repo.", @@ -2962,7 +3034,7 @@ }, { "id": "database", - "path": "skills/database", + "path": "skills\\database", "category": "uncategorized", "name": "database", "description": "Database development and operations workflow covering SQL, NoSQL, database design, migrations, optimization, and data engineering.", @@ -2971,34 +3043,25 @@ }, { "id": "database-admin", - "path": "skills/database-admin", + "path": "skills\\database-admin", "category": "uncategorized", - "name": "Database Admin", - "description": "- Working on database admin tasks or workflows - Needing guidance, best practices, or checklists for database admin", + "name": "database-admin", + "description": "Expert database administrator specializing in modern cloud\ndatabases, automation, and reliability engineering. Masters AWS/Azure/GCP\ndatabase services, Infrastructure as Code, high availability, disaster\nrecovery, performance optimization, and compliance. Handles multi-cloud\nstrategies, container databases, and cost optimization. Use PROACTIVELY for\ndatabase architecture, operations, or reliability engineering.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "database-architect", - "path": "skills/database-architect", + "path": "skills\\database-architect", "category": "uncategorized", - "name": "Database Architect", - "description": "You are a database architect specializing in designing scalable, performant, and maintainable data layers from the ground up.", + "name": "database-architect", + "description": "Expert database architect specializing in data layer design from\nscratch, technology selection, schema modeling, and scalable database\narchitectures. Masters SQL/NoSQL/TimeSeries database selection, normalization\nstrategies, migration planning, and performance-first design. Handles both\ngreenfield architectures and re-architecture of existing systems. Use\nPROACTIVELY for database architecture, technology selection, or data modeling\ndecisions.\n", "risk": "unknown", - "source": "unknown" - }, - { - "id": "database-optimizer", - "path": "skills/database-optimizer", - "category": "uncategorized", - "name": "Database Optimizer", - "description": "- Working on database optimizer tasks or workflows - Needing guidance, best practices, or checklists for database optimizer", - "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "database-cloud-optimization-cost-optimize", - "path": "skills/database-cloud-optimization-cost-optimize", + "path": "skills\\database-cloud-optimization-cost-optimize", "category": "uncategorized", "name": "database-cloud-optimization-cost-optimize", "description": "You are a cloud cost optimization expert specializing in reducing infrastructure expenses while maintaining performance and reliability. Analyze cloud spending, identify savings opportunities, and ...", @@ -3007,7 +3070,7 @@ }, { "id": "database-design", - "path": "skills/database-design", + "path": "skills\\database-design", "category": "uncategorized", "name": "database-design", "description": "Database design principles and decision-making. Schema design, indexing strategy, ORM selection, serverless databases.", @@ -3016,7 +3079,7 @@ }, { "id": "database-migration", - "path": "skills/database-migration", + "path": "skills\\database-migration", "category": "uncategorized", "name": "database-migration", "description": "Execute database migrations across ORMs and platforms with zero-downtime strategies, data transformation, and rollback procedures. Use when migrating databases, changing schemas, performing data tr...", @@ -3025,7 +3088,7 @@ }, { "id": "database-migrations-migration-observability", - "path": "skills/database-migrations-migration-observability", + "path": "skills\\database-migrations-migration-observability", "category": "uncategorized", "name": "database-migrations-migration-observability", "description": "Migration monitoring, CDC, and observability infrastructure", @@ -3034,16 +3097,25 @@ }, { "id": "database-migrations-sql-migrations", - "path": "skills/database-migrations-sql-migrations", + "path": "skills\\database-migrations-sql-migrations", "category": "uncategorized", "name": "database-migrations-sql-migrations", "description": "SQL database migrations with zero-downtime strategies for PostgreSQL, MySQL, and SQL Server. Focus on data integrity and rollback plans.", "risk": "unknown", "source": "community" }, + { + "id": "database-optimizer", + "path": "skills\\database-optimizer", + "category": "uncategorized", + "name": "database-optimizer", + "description": "Expert database optimizer specializing in modern performance\ntuning, query optimization, and scalable architectures. Masters advanced\nindexing, N+1 resolution, multi-tier caching, partitioning strategies, and\ncloud database optimization. Handles complex query analysis, migration\nstrategies, and performance monitoring. Use PROACTIVELY for database\noptimization, performance issues, or scalability challenges.\n", + "risk": "unknown", + "source": "community" + }, { "id": "datadog-automation", - "path": "skills/datadog-automation", + "path": "skills\\datadog-automation", "category": "uncategorized", "name": "datadog-automation", "description": "Automate Datadog tasks via Rube MCP (Composio): query metrics, search logs, manage monitors/dashboards, create events and downtimes. Always search tools first for current schemas.", @@ -3052,7 +3124,7 @@ }, { "id": "dbos-golang", - "path": "skills/dbos-golang", + "path": "skills\\dbos-golang", "category": "uncategorized", "name": "dbos-golang", "description": "DBOS Go SDK for building reliable, fault-tolerant applications with durable workflows. Use this skill when writing Go code with DBOS, creating workflows and steps, using queues, using the DBOS Clie...", @@ -3061,7 +3133,7 @@ }, { "id": "dbos-python", - "path": "skills/dbos-python", + "path": "skills\\dbos-python", "category": "uncategorized", "name": "dbos-python", "description": "DBOS Python SDK for building reliable, fault-tolerant applications with durable workflows. Use this skill when writing Python code with DBOS, creating workflows and steps, using queues, using DBOSC...", @@ -3070,7 +3142,7 @@ }, { "id": "dbos-typescript", - "path": "skills/dbos-typescript", + "path": "skills\\dbos-typescript", "category": "uncategorized", "name": "dbos-typescript", "description": "DBOS TypeScript SDK for building reliable, fault-tolerant applications with durable workflows. Use this skill when writing TypeScript code with DBOS, creating workflows and steps, using queues, usi...", @@ -3079,7 +3151,7 @@ }, { "id": "dbt-transformation-patterns", - "path": "skills/dbt-transformation-patterns", + "path": "skills\\dbt-transformation-patterns", "category": "uncategorized", "name": "dbt-transformation-patterns", "description": "Master dbt (data build tool) for analytics engineering with model organization, testing, documentation, and incremental strategies. Use when building data transformations, creating data models, or ...", @@ -3088,7 +3160,7 @@ }, { "id": "ddd-context-mapping", - "path": "skills/ddd-context-mapping", + "path": "skills\\ddd-context-mapping", "category": "uncategorized", "name": "ddd-context-mapping", "description": "Map relationships between bounded contexts and define integration contracts using DDD context mapping patterns.", @@ -3097,7 +3169,7 @@ }, { "id": "ddd-strategic-design", - "path": "skills/ddd-strategic-design", + "path": "skills\\ddd-strategic-design", "category": "uncategorized", "name": "ddd-strategic-design", "description": "Design DDD strategic artifacts including subdomains, bounded contexts, and ubiquitous language for complex business domains.", @@ -3106,7 +3178,7 @@ }, { "id": "ddd-tactical-patterns", - "path": "skills/ddd-tactical-patterns", + "path": "skills\\ddd-tactical-patterns", "category": "uncategorized", "name": "ddd-tactical-patterns", "description": "Apply DDD tactical patterns in code using entities, value objects, aggregates, repositories, and domain events with explicit invariants.", @@ -3115,16 +3187,16 @@ }, { "id": "debugger", - "path": "skills/debugger", + "path": "skills\\debugger", "category": "uncategorized", - "name": "Debugger", - "description": "- Working on debugger tasks or workflows - Needing guidance, best practices, or checklists for debugger", + "name": "debugger", + "description": "Debugging specialist for errors, test failures, and unexpected\nbehavior. Use proactively when encountering any issues.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "debugging-strategies", - "path": "skills/debugging-strategies", + "path": "skills\\debugging-strategies", "category": "uncategorized", "name": "debugging-strategies", "description": "Master systematic debugging techniques, profiling tools, and root cause analysis to efficiently track down bugs across any codebase or technology stack. Use when investigating bugs, performance iss...", @@ -3133,7 +3205,7 @@ }, { "id": "debugging-toolkit-smart-debug", - "path": "skills/debugging-toolkit-smart-debug", + "path": "skills\\debugging-toolkit-smart-debug", "category": "uncategorized", "name": "debugging-toolkit-smart-debug", "description": "Use when working with debugging toolkit smart debug", @@ -3142,7 +3214,7 @@ }, { "id": "deep-research", - "path": "skills/deep-research", + "path": "skills\\deep-research", "category": "uncategorized", "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 ...", @@ -3151,7 +3223,7 @@ }, { "id": "defi-protocol-templates", - "path": "skills/defi-protocol-templates", + "path": "skills\\defi-protocol-templates", "category": "uncategorized", "name": "defi-protocol-templates", "description": "Implement DeFi protocols with production-ready templates for staking, AMMs, governance, and lending systems. Use when building decentralized finance applications or smart contract protocols.", @@ -3160,7 +3232,7 @@ }, { "id": "dependency-management-deps-audit", - "path": "skills/dependency-management-deps-audit", + "path": "skills\\dependency-management-deps-audit", "category": "uncategorized", "name": "dependency-management-deps-audit", "description": "You are a dependency security expert specializing in vulnerability scanning, license compliance, and supply chain security. Analyze project dependencies for known vulnerabilities, licensing issues,...", @@ -3169,7 +3241,7 @@ }, { "id": "dependency-upgrade", - "path": "skills/dependency-upgrade", + "path": "skills\\dependency-upgrade", "category": "uncategorized", "name": "dependency-upgrade", "description": "Manage major dependency version upgrades with compatibility analysis, staged rollout, and comprehensive testing. Use when upgrading framework versions, updating major dependencies, or managing brea...", @@ -3178,16 +3250,16 @@ }, { "id": "deployment-engineer", - "path": "skills/deployment-engineer", + "path": "skills\\deployment-engineer", "category": "uncategorized", - "name": "Deployment Engineer", - "description": "You are a deployment engineer specializing in modern CI/CD pipelines, GitOps workflows, and advanced deployment automation.", + "name": "deployment-engineer", + "description": "Expert deployment engineer specializing in modern CI/CD pipelines,\nGitOps workflows, and advanced deployment automation. Masters GitHub Actions,\nArgoCD/Flux, progressive delivery, container security, and platform\nengineering. Handles zero-downtime deployments, security scanning, and\ndeveloper experience optimization. Use PROACTIVELY for CI/CD design, GitOps\nimplementation, or deployment automation.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "deployment-pipeline-design", - "path": "skills/deployment-pipeline-design", + "path": "skills\\deployment-pipeline-design", "category": "uncategorized", "name": "deployment-pipeline-design", "description": "Design multi-stage CI/CD pipelines with approval gates, security checks, and deployment orchestration. Use when architecting deployment workflows, setting up continuous delivery, or implementing Gi...", @@ -3196,7 +3268,7 @@ }, { "id": "deployment-procedures", - "path": "skills/deployment-procedures", + "path": "skills\\deployment-procedures", "category": "uncategorized", "name": "deployment-procedures", "description": "Production deployment principles and decision-making. Safe deployment workflows, rollback strategies, and verification. Teaches thinking, not scripts.", @@ -3205,7 +3277,7 @@ }, { "id": "deployment-validation-config-validate", - "path": "skills/deployment-validation-config-validate", + "path": "skills\\deployment-validation-config-validate", "category": "uncategorized", "name": "deployment-validation-config-validate", "description": "You are a configuration management expert specializing in validating, testing, and ensuring the correctness of application configurations. Create comprehensive validation schemas, implement configurat", @@ -3214,7 +3286,7 @@ }, { "id": "design-md", - "path": "skills/design-md", + "path": "skills\\design-md", "category": "uncategorized", "name": "design-md", "description": "Analyze Stitch projects and synthesize a semantic design system into DESIGN.md files", @@ -3223,7 +3295,7 @@ }, { "id": "design-orchestration", - "path": "skills/design-orchestration", + "path": "skills\\design-orchestration", "category": "uncategorized", "name": "design-orchestration", "description": "Orchestrates design workflows by routing work through brainstorming, multi-agent review, and execution readiness in the correct order. Prevents premature implementation, skipped validation, and unreviewed high-risk designs.", @@ -3232,7 +3304,7 @@ }, { "id": "development", - "path": "skills/development", + "path": "skills\\development", "category": "uncategorized", "name": "development", "description": "Comprehensive web, mobile, and backend development workflow bundling frontend, backend, full-stack, and mobile development skills for end-to-end application delivery.", @@ -3241,16 +3313,16 @@ }, { "id": "devops-troubleshooter", - "path": "skills/devops-troubleshooter", + "path": "skills\\devops-troubleshooter", "category": "uncategorized", - "name": "Devops Troubleshooter", - "description": "- Working on devops troubleshooter tasks or workflows - Needing guidance, best practices, or checklists for devops troubleshooter", + "name": "devops-troubleshooter", + "description": "Expert DevOps troubleshooter specializing in rapid incident\nresponse, advanced debugging, and modern observability. Masters log analysis,\ndistributed tracing, Kubernetes debugging, performance optimization, and root\ncause analysis. Handles production outages, system reliability, and preventive\nmonitoring. Use PROACTIVELY for debugging, incident response, or system\ntroubleshooting.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "discord-automation", - "path": "skills/discord-automation", + "path": "skills\\discord-automation", "category": "uncategorized", "name": "discord-automation", "description": "Automate Discord tasks via Rube MCP (Composio): messages, channels, roles, webhooks, reactions. Always search tools first for current schemas.", @@ -3259,7 +3331,7 @@ }, { "id": "discord-bot-architect", - "path": "skills/discord-bot-architect", + "path": "skills\\discord-bot-architect", "category": "uncategorized", "name": "discord-bot-architect", "description": "Specialized skill for building production-ready Discord bots. Covers Discord.js (JavaScript) and Pycord (Python), gateway intents, slash commands, interactive components, rate limiting, and sharding.", @@ -3268,7 +3340,7 @@ }, { "id": "dispatching-parallel-agents", - "path": "skills/dispatching-parallel-agents", + "path": "skills\\dispatching-parallel-agents", "category": "uncategorized", "name": "dispatching-parallel-agents", "description": "Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies", @@ -3277,7 +3349,7 @@ }, { "id": "distributed-debugging-debug-trace", - "path": "skills/distributed-debugging-debug-trace", + "path": "skills\\distributed-debugging-debug-trace", "category": "uncategorized", "name": "distributed-debugging-debug-trace", "description": "You are a debugging expert specializing in setting up comprehensive debugging environments, distributed tracing, and diagnostic tools. Configure debugging workflows, implement tracing solutions, an...", @@ -3286,7 +3358,7 @@ }, { "id": "distributed-tracing", - "path": "skills/distributed-tracing", + "path": "skills\\distributed-tracing", "category": "uncategorized", "name": "distributed-tracing", "description": "Implement distributed tracing with Jaeger and Tempo to track requests across microservices and identify performance bottlenecks. Use when debugging microservices, analyzing request flows, or implem...", @@ -3295,16 +3367,16 @@ }, { "id": "django-pro", - "path": "skills/django-pro", + "path": "skills\\django-pro", "category": "uncategorized", - "name": "Django Pro", - "description": "- Working on django pro tasks or workflows - Needing guidance, best practices, or checklists for django pro", + "name": "django-pro", + "description": "Master Django 5.x with async views, DRF, Celery, and Django\nChannels. Build scalable web applications with proper architecture, testing,\nand deployment. Use PROACTIVELY for Django development, ORM optimization, or\ncomplex Django patterns.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "doc-coauthoring", - "path": "skills/doc-coauthoring", + "path": "skills\\doc-coauthoring", "category": "uncategorized", "name": "doc-coauthoring", "description": "Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This ...", @@ -3313,7 +3385,7 @@ }, { "id": "docker-expert", - "path": "skills/docker-expert", + "path": "skills\\docker-expert", "category": "uncategorized", "name": "docker-expert", "description": "Docker containerization expert with deep knowledge of multi-stage builds, image optimization, container security, Docker Compose orchestration, and production deployment patterns. Use PROACTIVELY f...", @@ -3322,16 +3394,16 @@ }, { "id": "docs-architect", - "path": "skills/docs-architect", + "path": "skills\\docs-architect", "category": "uncategorized", - "name": "Docs Architect", - "description": "- Working on docs architect tasks or workflows - Needing guidance, best practices, or checklists for docs architect", + "name": "docs-architect", + "description": "Creates comprehensive technical documentation from existing\ncodebases. Analyzes architecture, design patterns, and implementation details\nto produce long-form technical manuals and ebooks. Use PROACTIVELY for system\ndocumentation, architecture guides, or technical deep-dives.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "documentation", - "path": "skills/documentation", + "path": "skills\\documentation", "category": "uncategorized", "name": "documentation", "description": "Documentation generation workflow covering API docs, architecture docs, README files, code comments, and technical writing.", @@ -3340,7 +3412,7 @@ }, { "id": "documentation-generation-doc-generate", - "path": "skills/documentation-generation-doc-generate", + "path": "skills\\documentation-generation-doc-generate", "category": "uncategorized", "name": "documentation-generation-doc-generate", "description": "You are a documentation expert specializing in creating comprehensive, maintainable documentation from code. Generate API docs, architecture diagrams, user guides, and technical references using AI...", @@ -3349,7 +3421,7 @@ }, { "id": "documentation-templates", - "path": "skills/documentation-templates", + "path": "skills\\documentation-templates", "category": "uncategorized", "name": "documentation-templates", "description": "Documentation templates and structure guidelines. README, API docs, code comments, and AI-friendly documentation.", @@ -3358,7 +3430,7 @@ }, { "id": "docusign-automation", - "path": "skills/docusign-automation", + "path": "skills\\docusign-automation", "category": "uncategorized", "name": "docusign-automation", "description": "Automate DocuSign tasks via Rube MCP (Composio): templates, envelopes, signatures, document management. Always search tools first for current schemas.", @@ -3367,7 +3439,7 @@ }, { "id": "docx-official", - "path": "skills/docx-official", + "path": "skills\\docx-official", "category": "uncategorized", "name": "docx-official", "description": "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. When Claude needs to work with professional document...", @@ -3376,7 +3448,7 @@ }, { "id": "domain-driven-design", - "path": "skills/domain-driven-design", + "path": "skills\\domain-driven-design", "category": "uncategorized", "name": "domain-driven-design", "description": "Plan and route Domain-Driven Design work from strategic modeling to tactical implementation and evented architecture patterns.", @@ -3385,16 +3457,16 @@ }, { "id": "dotnet-architect", - "path": "skills/dotnet-architect", + "path": "skills\\dotnet-architect", "category": "uncategorized", - "name": "Dotnet Architect", - "description": "- Working on dotnet architect tasks or workflows - Needing guidance, best practices, or checklists for dotnet architect", + "name": "dotnet-architect", + "description": "Expert .NET backend architect specializing in C#, ASP.NET Core,\nEntity Framework, Dapper, and enterprise application patterns. Masters\nasync/await, dependency injection, caching strategies, and performance\noptimization. Use PROACTIVELY for .NET API development, code review, or\narchitecture decisions.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "dotnet-backend", - "path": "skills/dotnet-backend", + "path": "skills\\dotnet-backend", "category": "uncategorized", "name": "dotnet-backend", "description": "Build ASP.NET Core 8+ backend services with EF Core, auth, background jobs, and production API patterns.", @@ -3403,7 +3475,7 @@ }, { "id": "dotnet-backend-patterns", - "path": "skills/dotnet-backend-patterns", + "path": "skills\\dotnet-backend-patterns", "category": "uncategorized", "name": "dotnet-backend-patterns", "description": "Master C#/.NET backend development patterns for building robust APIs, MCP servers, and enterprise applications. Covers async/await, dependency injection, Entity Framework Core, Dapper, configuratio...", @@ -3412,7 +3484,7 @@ }, { "id": "draw", - "path": "skills/libreoffice/draw", + "path": "skills\\libreoffice\\draw", "category": "libreoffice", "name": "draw", "description": "Vector graphics and diagram creation, format conversion (ODG/SVG/PDF) with LibreOffice Draw.", @@ -3421,7 +3493,7 @@ }, { "id": "dropbox-automation", - "path": "skills/dropbox-automation", + "path": "skills\\dropbox-automation", "category": "uncategorized", "name": "dropbox-automation", "description": "Automate Dropbox file management, sharing, search, uploads, downloads, and folder operations via Rube MCP (Composio). Always search tools first for current schemas.", @@ -3430,16 +3502,16 @@ }, { "id": "dx-optimizer", - "path": "skills/dx-optimizer", + "path": "skills\\dx-optimizer", "category": "uncategorized", - "name": "Dx Optimizer", - "description": "- Working on dx optimizer tasks or workflows - Needing guidance, best practices, or checklists for dx optimizer", + "name": "dx-optimizer", + "description": "Developer Experience specialist. Improves tooling, setup, and\nworkflows. Use PROACTIVELY when setting up new projects, after team feedback,\nor when development friction is noticed.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "e2e-testing", - "path": "skills/e2e-testing", + "path": "skills\\e2e-testing", "category": "uncategorized", "name": "e2e-testing", "description": "End-to-end testing workflow with Playwright for browser automation, visual regression, cross-browser testing, and CI/CD integration.", @@ -3448,7 +3520,7 @@ }, { "id": "e2e-testing-patterns", - "path": "skills/e2e-testing-patterns", + "path": "skills\\e2e-testing-patterns", "category": "uncategorized", "name": "e2e-testing-patterns", "description": "Master end-to-end testing with Playwright and Cypress to build reliable test suites that catch bugs, improve confidence, and enable fast deployment. Use when implementing E2E tests, debugging flaky...", @@ -3457,16 +3529,16 @@ }, { "id": "elixir-pro", - "path": "skills/elixir-pro", + "path": "skills\\elixir-pro", "category": "uncategorized", - "name": "Elixir Pro", - "description": "- Working on elixir pro tasks or workflows - Needing guidance, best practices, or checklists for elixir pro", + "name": "elixir-pro", + "description": "Write idiomatic Elixir code with OTP patterns, supervision trees,\nand Phoenix LiveView. Masters concurrency, fault tolerance, and distributed\nsystems. Use PROACTIVELY for Elixir refactoring, OTP design, or complex BEAM\noptimizations.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "email-sequence", - "path": "skills/email-sequence", + "path": "skills\\email-sequence", "category": "uncategorized", "name": "email-sequence", "description": "When the user wants to create or optimize an email sequence, drip campaign, automated email flow, or lifecycle email program. Also use when the user mentions \"email sequence,\" \"drip campa...", @@ -3475,7 +3547,7 @@ }, { "id": "email-systems", - "path": "skills/email-systems", + "path": "skills\\email-systems", "category": "uncategorized", "name": "email-systems", "description": "Email has the highest ROI of any marketing channel. $36 for every $1 spent. Yet most startups treat it as an afterthought - bulk blasts, no personalization, landing in spam folders. This skill cov...", @@ -3484,7 +3556,7 @@ }, { "id": "embedding-strategies", - "path": "skills/embedding-strategies", + "path": "skills\\embedding-strategies", "category": "uncategorized", "name": "embedding-strategies", "description": "Select and optimize embedding models for semantic search and RAG applications. Use when choosing embedding models, implementing chunking strategies, or optimizing embedding quality for specific dom...", @@ -3493,34 +3565,34 @@ }, { "id": "employment-contract-templates", - "path": "skills/employment-contract-templates", + "path": "skills\\employment-contract-templates", "category": "uncategorized", "name": "employment-contract-templates", "description": "Create employment contracts, offer letters, and HR policy documents following legal best practices. Use when drafting employment agreements, creating HR policies, or standardizing employment docume...", "risk": "unknown", "source": "community" }, + { + "id": "energy-procurement", + "path": "skills\\energy-procurement", + "category": "uncategorized", + "name": "energy-procurement", + "description": "Codified expertise for electricity and gas procurement, tariff optimisation, demand charge management, renewable PPA evaluation, and multi-facility energy cost management. Informed by energy procurement managers with 15+ years experience at large commercial and industrial consumers. Includes market structure analysis, hedging strategies, load profiling, and sustainability reporting frameworks. Use when procuring energy, optimising tariffs, managing demand charges, evaluating PPAs, or developing energy strategies.\n", + "risk": "safe", + "source": "https://github.com/ai-evos/agent-skills" + }, { "id": "environment-setup-guide", - "path": "skills/environment-setup-guide", + "path": "skills\\environment-setup-guide", "category": "uncategorized", "name": "environment-setup-guide", "description": "Guide developers through setting up development environments with proper tools, dependencies, and configurations", "risk": "unknown", "source": "community" }, - { - "id": "error-detective", - "path": "skills/error-detective", - "category": "uncategorized", - "name": "Error Detective", - "description": "- Working on error detective tasks or workflows - Needing guidance, best practices, or checklists for error detective", - "risk": "unknown", - "source": "unknown" - }, { "id": "error-debugging-error-analysis", - "path": "skills/error-debugging-error-analysis", + "path": "skills\\error-debugging-error-analysis", "category": "uncategorized", "name": "error-debugging-error-analysis", "description": "You are an expert error analysis specialist with deep expertise in debugging distributed systems, analyzing production incidents, and implementing comprehensive observability solutions.", @@ -3529,7 +3601,7 @@ }, { "id": "error-debugging-error-trace", - "path": "skills/error-debugging-error-trace", + "path": "skills\\error-debugging-error-trace", "category": "uncategorized", "name": "error-debugging-error-trace", "description": "You are an error tracking and observability expert specializing in implementing comprehensive error monitoring solutions. Set up error tracking systems, configure alerts, implement structured loggi...", @@ -3538,16 +3610,25 @@ }, { "id": "error-debugging-multi-agent-review", - "path": "skills/error-debugging-multi-agent-review", + "path": "skills\\error-debugging-multi-agent-review", "category": "uncategorized", "name": "error-debugging-multi-agent-review", "description": "Use when working with error debugging multi agent review", "risk": "unknown", "source": "community" }, + { + "id": "error-detective", + "path": "skills\\error-detective", + "category": "uncategorized", + "name": "error-detective", + "description": "Search logs and codebases for error patterns, stack traces, and\nanomalies. Correlates errors across systems and identifies root causes. Use\nPROACTIVELY when debugging issues, analyzing logs, or investigating production\nerrors.\n", + "risk": "unknown", + "source": "community" + }, { "id": "error-diagnostics-error-analysis", - "path": "skills/error-diagnostics-error-analysis", + "path": "skills\\error-diagnostics-error-analysis", "category": "uncategorized", "name": "error-diagnostics-error-analysis", "description": "You are an expert error analysis specialist with deep expertise in debugging distributed systems, analyzing production incidents, and implementing comprehensive observability solutions.", @@ -3556,7 +3637,7 @@ }, { "id": "error-diagnostics-error-trace", - "path": "skills/error-diagnostics-error-trace", + "path": "skills\\error-diagnostics-error-trace", "category": "uncategorized", "name": "error-diagnostics-error-trace", "description": "You are an error tracking and observability expert specializing in implementing comprehensive error monitoring solutions. Set up error tracking systems, configure alerts, implement structured logging,", @@ -3565,7 +3646,7 @@ }, { "id": "error-diagnostics-smart-debug", - "path": "skills/error-diagnostics-smart-debug", + "path": "skills\\error-diagnostics-smart-debug", "category": "uncategorized", "name": "error-diagnostics-smart-debug", "description": "Use when working with error diagnostics smart debug", @@ -3574,7 +3655,7 @@ }, { "id": "error-handling-patterns", - "path": "skills/error-handling-patterns", + "path": "skills\\error-handling-patterns", "category": "uncategorized", "name": "error-handling-patterns", "description": "Master error handling patterns across languages including exceptions, Result types, error propagation, and graceful degradation to build resilient applications. Use when implementing error handling...", @@ -3583,7 +3664,7 @@ }, { "id": "ethical-hacking-methodology", - "path": "skills/ethical-hacking-methodology", + "path": "skills\\ethical-hacking-methodology", "category": "uncategorized", "name": "ethical-hacking-methodology", "description": "This skill should be used when the user asks to \"learn ethical hacking\", \"understand penetration testing lifecycle\", \"perform reconnaissance\", \"conduct security scanning\", \"exploit ...", @@ -3592,7 +3673,7 @@ }, { "id": "evaluation", - "path": "skills/evaluation", + "path": "skills\\evaluation", "category": "uncategorized", "name": "evaluation", "description": "Build evaluation frameworks for agent systems", @@ -3601,7 +3682,7 @@ }, { "id": "event-sourcing-architect", - "path": "skills/event-sourcing-architect", + "path": "skills\\event-sourcing-architect", "category": "uncategorized", "name": "event-sourcing-architect", "description": "Expert in event sourcing, CQRS, and event-driven architecture patterns. Masters event store design, projection building, saga orchestration, and eventual consistency patterns. Use PROACTIVELY for e...", @@ -3610,7 +3691,7 @@ }, { "id": "event-store-design", - "path": "skills/event-store-design", + "path": "skills\\event-store-design", "category": "uncategorized", "name": "event-store-design", "description": "Design and implement event stores for event-sourced systems. Use when building event sourcing infrastructure, choosing event store technologies, or implementing event persistence patterns.", @@ -3619,7 +3700,7 @@ }, { "id": "exa-search", - "path": "skills/exa-search", + "path": "skills\\exa-search", "category": "uncategorized", "name": "exa-search", "description": "Semantic search, similar content discovery, and structured research using Exa API", @@ -3628,7 +3709,7 @@ }, { "id": "executing-plans", - "path": "skills/executing-plans", + "path": "skills\\executing-plans", "category": "uncategorized", "name": "executing-plans", "description": "Use when you have a written implementation plan to execute in a separate session with review checkpoints", @@ -3637,7 +3718,7 @@ }, { "id": "expo-deployment", - "path": "skills/expo-deployment", + "path": "skills\\expo-deployment", "category": "uncategorized", "name": "expo-deployment", "description": "Deploy Expo apps to production", @@ -3646,7 +3727,7 @@ }, { "id": "fal-audio", - "path": "skills/fal-audio", + "path": "skills\\fal-audio", "category": "uncategorized", "name": "fal-audio", "description": "Text-to-speech and speech-to-text using fal.ai audio models", @@ -3655,7 +3736,7 @@ }, { "id": "fal-generate", - "path": "skills/fal-generate", + "path": "skills\\fal-generate", "category": "uncategorized", "name": "fal-generate", "description": "Generate images and videos using fal.ai AI models", @@ -3664,7 +3745,7 @@ }, { "id": "fal-image-edit", - "path": "skills/fal-image-edit", + "path": "skills\\fal-image-edit", "category": "uncategorized", "name": "fal-image-edit", "description": "AI-powered image editing with style transfer and object removal", @@ -3673,7 +3754,7 @@ }, { "id": "fal-platform", - "path": "skills/fal-platform", + "path": "skills\\fal-platform", "category": "uncategorized", "name": "fal-platform", "description": "Platform APIs for model management, pricing, and usage tracking", @@ -3682,7 +3763,7 @@ }, { "id": "fal-upscale", - "path": "skills/fal-upscale", + "path": "skills\\fal-upscale", "category": "uncategorized", "name": "fal-upscale", "description": "Upscale and enhance image and video resolution using AI", @@ -3691,7 +3772,7 @@ }, { "id": "fal-workflow", - "path": "skills/fal-workflow", + "path": "skills\\fal-workflow", "category": "uncategorized", "name": "fal-workflow", "description": "Generate workflow JSON files for chaining AI models", @@ -3700,16 +3781,16 @@ }, { "id": "fastapi-pro", - "path": "skills/fastapi-pro", + "path": "skills\\fastapi-pro", "category": "uncategorized", - "name": "Fastapi Pro", - "description": "- Working on fastapi pro tasks or workflows - Needing guidance, best practices, or checklists for fastapi pro", + "name": "fastapi-pro", + "description": "Build high-performance async APIs with FastAPI, SQLAlchemy 2.0, and\nPydantic V2. Master microservices, WebSockets, and modern Python async\npatterns. Use PROACTIVELY for FastAPI development, async optimization, or API\narchitecture.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "fastapi-router-py", - "path": "skills/fastapi-router-py", + "path": "skills\\fastapi-router-py", "category": "uncategorized", "name": "fastapi-router-py", "description": "Create FastAPI routers with CRUD operations, authentication dependencies, and proper response models. Use when building REST API endpoints, creating new routes, implementing CRUD operations, or add...", @@ -3718,7 +3799,7 @@ }, { "id": "fastapi-templates", - "path": "skills/fastapi-templates", + "path": "skills\\fastapi-templates", "category": "uncategorized", "name": "fastapi-templates", "description": "Create production-ready FastAPI projects with async patterns, dependency injection, and comprehensive error handling. Use when building new FastAPI applications or setting up backend API projects.", @@ -3727,7 +3808,7 @@ }, { "id": "ffuf-claude-skill", - "path": "skills/ffuf-claude-skill", + "path": "skills\\ffuf-claude-skill", "category": "uncategorized", "name": "ffuf-claude-skill", "description": "Web fuzzing with ffuf", @@ -3736,7 +3817,7 @@ }, { "id": "figma-automation", - "path": "skills/figma-automation", + "path": "skills\\figma-automation", "category": "uncategorized", "name": "figma-automation", "description": "Automate Figma tasks via Rube MCP (Composio): files, components, design tokens, comments, exports. Always search tools first for current schemas.", @@ -3745,7 +3826,7 @@ }, { "id": "file-organizer", - "path": "skills/file-organizer", + "path": "skills\\file-organizer", "category": "uncategorized", "name": "file-organizer", "description": "Intelligently organizes files and folders by understanding context, finding duplicates, and suggesting better organizational structures. Use when user wants to clean up directories, organize downlo...", @@ -3754,7 +3835,7 @@ }, { "id": "file-path-traversal", - "path": "skills/file-path-traversal", + "path": "skills\\file-path-traversal", "category": "uncategorized", "name": "file-path-traversal", "description": "This skill should be used when the user asks to \"test for directory traversal\", \"exploit path traversal vulnerabilities\", \"read arbitrary files through web applications\", \"find LFI vu...", @@ -3763,7 +3844,7 @@ }, { "id": "file-uploads", - "path": "skills/file-uploads", + "path": "skills\\file-uploads", "category": "uncategorized", "name": "file-uploads", "description": "Expert at handling file uploads and cloud storage. Covers S3, Cloudflare R2, presigned URLs, multipart uploads, and image optimization. Knows how to handle large files without blocking. Use when: f...", @@ -3772,7 +3853,7 @@ }, { "id": "find-bugs", - "path": "skills/find-bugs", + "path": "skills\\find-bugs", "category": "uncategorized", "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.", @@ -3781,7 +3862,7 @@ }, { "id": "finishing-a-development-branch", - "path": "skills/finishing-a-development-branch", + "path": "skills\\finishing-a-development-branch", "category": "uncategorized", "name": "finishing-a-development-branch", "description": "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 structured options for merge, PR, or cleanup", @@ -3790,7 +3871,7 @@ }, { "id": "firebase", - "path": "skills/firebase", + "path": "skills\\firebase", "category": "uncategorized", "name": "firebase", "description": "Firebase gives you a complete backend in minutes - auth, database, storage, functions, hosting. But the ease of setup hides real complexity. Security rules are your last line of defense, and they'r...", @@ -3799,7 +3880,7 @@ }, { "id": "firecrawl-scraper", - "path": "skills/firecrawl-scraper", + "path": "skills\\firecrawl-scraper", "category": "uncategorized", "name": "firecrawl-scraper", "description": "Deep web scraping, screenshots, PDF parsing, and website crawling using Firecrawl API", @@ -3808,16 +3889,16 @@ }, { "id": "firmware-analyst", - "path": "skills/firmware-analyst", + "path": "skills\\firmware-analyst", "category": "uncategorized", - "name": "Firmware Analyst", - "description": "wget http://vendor.com/firmware/update.bin", + "name": "firmware-analyst", + "description": "Expert firmware analyst specializing in embedded systems, IoT\nsecurity, and hardware reverse engineering. Masters firmware extraction,\nanalysis, and vulnerability research for routers, IoT devices, automotive\nsystems, and industrial controllers. Use PROACTIVELY for firmware security\naudits, IoT penetration testing, or embedded systems research.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "fix-review", - "path": "skills/fix-review", + "path": "skills\\fix-review", "category": "uncategorized", "name": "fix-review", "description": "Verify fix commits address audit findings without new bugs", @@ -3826,25 +3907,25 @@ }, { "id": "flutter-expert", - "path": "skills/flutter-expert", + "path": "skills\\flutter-expert", "category": "uncategorized", - "name": "Flutter Expert", - "description": "- Working on flutter expert tasks or workflows - Needing guidance, best practices, or checklists for flutter expert", + "name": "flutter-expert", + "description": "Master Flutter development with Dart 3, advanced widgets, and\nmulti-platform deployment. Handles state management, animations, testing, and\nperformance optimization for mobile, web, desktop, and embedded platforms. Use\nPROACTIVELY for Flutter architecture, UI implementation, or cross-platform\nfeatures.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "form-cro", - "path": "skills/form-cro", + "path": "skills\\form-cro", "category": "uncategorized", - "name": "Form Cro", - "description": "You are an expert in **form optimization and friction reduction**. Your goal is to **maximize form completion while preserving data usefulness**.", + "name": "form-cro", + "description": "Optimize any form that is NOT signup or account registration \u2014 including lead capture, contact, demo request, application, survey, quote, and checkout forms. Use when the goal is to increase form completion rate, reduce friction, or improve lead quality without breaking compliance or downstream workflows.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "fp-ts-errors", - "path": "skills/fp-ts-errors", + "path": "skills\\fp-ts-errors", "category": "uncategorized", "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.", @@ -3853,7 +3934,7 @@ }, { "id": "fp-ts-pragmatic", - "path": "skills/fp-ts-pragmatic", + "path": "skills\\fp-ts-pragmatic", "category": "uncategorized", "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.", @@ -3862,7 +3943,7 @@ }, { "id": "fp-ts-react", - "path": "skills/fp-ts-react", + "path": "skills\\fp-ts-react", "category": "uncategorized", "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.", @@ -3871,7 +3952,7 @@ }, { "id": "framework-migration-code-migrate", - "path": "skills/framework-migration-code-migrate", + "path": "skills\\framework-migration-code-migrate", "category": "uncategorized", "name": "framework-migration-code-migrate", "description": "You are a code migration expert specializing in transitioning codebases between frameworks, languages, versions, and platforms. Generate comprehensive migration plans, automated migration scripts, and", @@ -3880,7 +3961,7 @@ }, { "id": "framework-migration-deps-upgrade", - "path": "skills/framework-migration-deps-upgrade", + "path": "skills\\framework-migration-deps-upgrade", "category": "uncategorized", "name": "framework-migration-deps-upgrade", "description": "You are a dependency management expert specializing in safe, incremental upgrades of project dependencies. Plan and execute dependency updates with minimal risk, proper testing, and clear migration pa", @@ -3889,7 +3970,7 @@ }, { "id": "framework-migration-legacy-modernize", - "path": "skills/framework-migration-legacy-modernize", + "path": "skills\\framework-migration-legacy-modernize", "category": "uncategorized", "name": "framework-migration-legacy-modernize", "description": "Orchestrate a comprehensive legacy system modernization using the strangler fig pattern, enabling gradual replacement of outdated components while maintaining continuous business operations through ex", @@ -3898,7 +3979,7 @@ }, { "id": "free-tool-strategy", - "path": "skills/free-tool-strategy", + "path": "skills\\free-tool-strategy", "category": "uncategorized", "name": "free-tool-strategy", "description": "When the user wants to plan, evaluate, or build a free tool for marketing purposes \u2014 lead generation, SEO value, or brand awareness. Also use when the user mentions \"engineering as mar...", @@ -3907,7 +3988,7 @@ }, { "id": "freshdesk-automation", - "path": "skills/freshdesk-automation", + "path": "skills\\freshdesk-automation", "category": "uncategorized", "name": "freshdesk-automation", "description": "Automate Freshdesk helpdesk operations including tickets, contacts, companies, notes, and replies via Rube MCP (Composio). Always search tools first for current schemas.", @@ -3916,34 +3997,16 @@ }, { "id": "freshservice-automation", - "path": "skills/freshservice-automation", + "path": "skills\\freshservice-automation", "category": "uncategorized", "name": "freshservice-automation", "description": "Automate Freshservice ITSM tasks via Rube MCP (Composio): create/update tickets, bulk operations, service requests, and outbound emails. Always search tools first for current schemas.", "risk": "unknown", "source": "community" }, - { - "id": "frontend-developer", - "path": "skills/frontend-developer", - "category": "uncategorized", - "name": "Frontend Developer", - "description": "You are a frontend development expert specializing in modern React applications, Next.js, and cutting-edge frontend architecture.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "frontend-security-coder", - "path": "skills/frontend-security-coder", - "category": "uncategorized", - "name": "Frontend Security Coder", - "description": "- Working on frontend security coder tasks or workflows - Needing guidance, best practices, or checklists for frontend security coder", - "risk": "unknown", - "source": "unknown" - }, { "id": "frontend-design", - "path": "skills/frontend-design", + "path": "skills\\frontend-design", "category": "uncategorized", "name": "frontend-design", "description": "Create distinctive, production-grade frontend interfaces with intentional aesthetics, high craft, and non-generic visual identity. Use when building or styling web UIs, components, pages, dashboard...", @@ -3952,16 +4015,25 @@ }, { "id": "frontend-dev-guidelines", - "path": "skills/frontend-dev-guidelines", + "path": "skills\\frontend-dev-guidelines", "category": "uncategorized", "name": "frontend-dev-guidelines", "description": "Opinionated frontend development standards for modern React + TypeScript applications. Covers Suspense-first data fetching, lazy loading, feature-based architecture, MUI v7 styling, TanStack Router...", "risk": "unknown", "source": "community" }, + { + "id": "frontend-developer", + "path": "skills\\frontend-developer", + "category": "uncategorized", + "name": "frontend-developer", + "description": "Build React components, implement responsive layouts, and handle\nclient-side state management. Masters React 19, Next.js 15, and modern\nfrontend architecture. Optimizes performance and ensures accessibility. Use\nPROACTIVELY when creating UI components or fixing frontend issues.\n", + "risk": "unknown", + "source": "community" + }, { "id": "frontend-mobile-development-component-scaffold", - "path": "skills/frontend-mobile-development-component-scaffold", + "path": "skills\\frontend-mobile-development-component-scaffold", "category": "uncategorized", "name": "frontend-mobile-development-component-scaffold", "description": "You are a React component architecture expert specializing in scaffolding production-ready, accessible, and performant components. Generate complete component implementations with TypeScript, tests, s", @@ -3970,16 +4042,25 @@ }, { "id": "frontend-mobile-security-xss-scan", - "path": "skills/frontend-mobile-security-xss-scan", + "path": "skills\\frontend-mobile-security-xss-scan", "category": "uncategorized", "name": "frontend-mobile-security-xss-scan", "description": "You are a frontend security specialist focusing on Cross-Site Scripting (XSS) vulnerability detection and prevention. Analyze React, Vue, Angular, and vanilla JavaScript code to identify injection poi", "risk": "unknown", "source": "community" }, + { + "id": "frontend-security-coder", + "path": "skills\\frontend-security-coder", + "category": "uncategorized", + "name": "frontend-security-coder", + "description": "Expert in secure frontend coding practices specializing in XSS\nprevention, output sanitization, and client-side security patterns. Use\nPROACTIVELY for frontend security implementations or client-side security code\nreviews.\n", + "risk": "unknown", + "source": "community" + }, { "id": "frontend-slides", - "path": "skills/frontend-slides", + "path": "skills\\frontend-slides", "category": "uncategorized", "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...", @@ -3988,7 +4069,7 @@ }, { "id": "frontend-ui-dark-ts", - "path": "skills/frontend-ui-dark-ts", + "path": "skills\\frontend-ui-dark-ts", "category": "uncategorized", "name": "frontend-ui-dark-ts", "description": "Build dark-themed React applications using Tailwind CSS with custom theming, glassmorphism effects, and Framer Motion animations. Use when creating dashboards, admin panels, or data-rich interfaces...", @@ -3997,7 +4078,7 @@ }, { "id": "full-stack-orchestration-full-stack-feature", - "path": "skills/full-stack-orchestration-full-stack-feature", + "path": "skills\\full-stack-orchestration-full-stack-feature", "category": "uncategorized", "name": "full-stack-orchestration-full-stack-feature", "description": "Use when working with full stack orchestration full stack feature", @@ -4006,7 +4087,7 @@ }, { "id": "game-art", - "path": "skills/game-development/game-art", + "path": "skills\\game-development\\game-art", "category": "game-development", "name": "game-art", "description": "Game art principles. Visual style selection, asset pipeline, animation workflow.", @@ -4015,7 +4096,7 @@ }, { "id": "game-audio", - "path": "skills/game-development/game-audio", + "path": "skills\\game-development\\game-audio", "category": "game-development", "name": "game-audio", "description": "Game audio principles. Sound design, music integration, adaptive audio systems.", @@ -4024,7 +4105,7 @@ }, { "id": "game-design", - "path": "skills/game-development/game-design", + "path": "skills\\game-development\\game-design", "category": "game-development", "name": "game-design", "description": "Game design principles. GDD structure, balancing, player psychology, progression.", @@ -4033,7 +4114,7 @@ }, { "id": "game-development", - "path": "skills/game-development", + "path": "skills\\game-development", "category": "uncategorized", "name": "game-development", "description": "Game development orchestrator. Routes to platform-specific skills based on project needs.", @@ -4042,7 +4123,7 @@ }, { "id": "gcp-cloud-run", - "path": "skills/gcp-cloud-run", + "path": "skills\\gcp-cloud-run", "category": "uncategorized", "name": "gcp-cloud-run", "description": "Specialized skill for building production-ready serverless applications on GCP. Covers Cloud Run services (containerized), Cloud Run Functions (event-driven), cold start optimization, and event-dri...", @@ -4051,7 +4132,7 @@ }, { "id": "gdpr-data-handling", - "path": "skills/gdpr-data-handling", + "path": "skills\\gdpr-data-handling", "category": "uncategorized", "name": "gdpr-data-handling", "description": "Implement GDPR-compliant data handling with consent management, data subject rights, and privacy by design. Use when building systems that process EU personal data, implementing privacy controls, o...", @@ -4060,7 +4141,7 @@ }, { "id": "gemini-api-dev", - "path": "skills/gemini-api-dev", + "path": "skills\\gemini-api-dev", "category": "uncategorized", "name": "gemini-api-dev", "description": "Use this skill when building applications with Gemini models, Gemini API, working with multimodal content (text, images, audio, video), implementing function calling, using structured outputs, or n...", @@ -4069,7 +4150,7 @@ }, { "id": "geo-fundamentals", - "path": "skills/geo-fundamentals", + "path": "skills\\geo-fundamentals", "category": "uncategorized", "name": "geo-fundamentals", "description": "Generative Engine Optimization for AI search engines (ChatGPT, Claude, Perplexity).", @@ -4078,7 +4159,7 @@ }, { "id": "git-advanced-workflows", - "path": "skills/git-advanced-workflows", + "path": "skills\\git-advanced-workflows", "category": "uncategorized", "name": "git-advanced-workflows", "description": "Master advanced Git workflows including rebasing, cherry-picking, bisect, worktrees, and reflog to maintain clean history and recover from any situation. Use when managing complex Git histories, co...", @@ -4087,7 +4168,7 @@ }, { "id": "git-pr-workflows-git-workflow", - "path": "skills/git-pr-workflows-git-workflow", + "path": "skills\\git-pr-workflows-git-workflow", "category": "uncategorized", "name": "git-pr-workflows-git-workflow", "description": "Orchestrate a comprehensive git workflow from code review through PR creation, leveraging specialized agents for quality assurance, testing, and deployment readiness. This workflow implements modern g", @@ -4096,7 +4177,7 @@ }, { "id": "git-pr-workflows-onboard", - "path": "skills/git-pr-workflows-onboard", + "path": "skills\\git-pr-workflows-onboard", "category": "uncategorized", "name": "git-pr-workflows-onboard", "description": "You are an **expert onboarding specialist and knowledge transfer architect** with deep experience in remote-first organizations, technical team integration, and accelerated learning methodologies. You", @@ -4105,7 +4186,7 @@ }, { "id": "git-pr-workflows-pr-enhance", - "path": "skills/git-pr-workflows-pr-enhance", + "path": "skills\\git-pr-workflows-pr-enhance", "category": "uncategorized", "name": "git-pr-workflows-pr-enhance", "description": "You are a PR optimization expert specializing in creating high-quality pull requests that facilitate efficient code reviews. Generate comprehensive PR descriptions, automate review processes, and ensu", @@ -4114,7 +4195,7 @@ }, { "id": "git-pushing", - "path": "skills/git-pushing", + "path": "skills\\git-pushing", "category": "uncategorized", "name": "git-pushing", "description": "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 save and push their work. Also activate...", @@ -4123,7 +4204,7 @@ }, { "id": "github-actions-templates", - "path": "skills/github-actions-templates", + "path": "skills\\github-actions-templates", "category": "uncategorized", "name": "github-actions-templates", "description": "Create production-ready GitHub Actions workflows for automated testing, building, and deploying applications. Use when setting up CI/CD with GitHub Actions, automating development workflows, or cre...", @@ -4132,7 +4213,7 @@ }, { "id": "github-automation", - "path": "skills/github-automation", + "path": "skills\\github-automation", "category": "uncategorized", "name": "github-automation", "description": "Automate GitHub repositories, issues, pull requests, branches, CI/CD, and permissions via Rube MCP (Composio). Manage code workflows, review PRs, search code, and handle deployments programmatically.", @@ -4141,7 +4222,7 @@ }, { "id": "github-issue-creator", - "path": "skills/github-issue-creator", + "path": "skills\\github-issue-creator", "category": "uncategorized", "name": "github-issue-creator", "description": "Convert raw notes, error logs, voice dictation, or screenshots into crisp GitHub-flavored markdown issue reports. Use when the user pastes bug info, error messages, or informal descriptions and wan...", @@ -4150,7 +4231,7 @@ }, { "id": "github-workflow-automation", - "path": "skills/github-workflow-automation", + "path": "skills\\github-workflow-automation", "category": "uncategorized", "name": "github-workflow-automation", "description": "Automate GitHub workflows with AI assistance. Includes PR reviews, issue triage, CI/CD integration, and Git operations. Use when automating GitHub workflows, setting up PR review automation, creati...", @@ -4159,7 +4240,7 @@ }, { "id": "gitlab-automation", - "path": "skills/gitlab-automation", + "path": "skills\\gitlab-automation", "category": "uncategorized", "name": "gitlab-automation", "description": "Automate GitLab project management, issues, merge requests, pipelines, branches, and user operations via Rube MCP (Composio). Always search tools first for current schemas.", @@ -4168,7 +4249,7 @@ }, { "id": "gitlab-ci-patterns", - "path": "skills/gitlab-ci-patterns", + "path": "skills\\gitlab-ci-patterns", "category": "uncategorized", "name": "gitlab-ci-patterns", "description": "Build GitLab CI/CD pipelines with multi-stage workflows, caching, and distributed runners for scalable automation. Use when implementing GitLab CI/CD, optimizing pipeline performance, or setting up...", @@ -4177,7 +4258,7 @@ }, { "id": "gitops-workflow", - "path": "skills/gitops-workflow", + "path": "skills\\gitops-workflow", "category": "uncategorized", "name": "gitops-workflow", "description": "Implement GitOps workflows with ArgoCD and Flux for automated, declarative Kubernetes deployments with continuous reconciliation. Use when implementing GitOps practices, automating Kubernetes deplo...", @@ -4186,7 +4267,7 @@ }, { "id": "gmail-automation", - "path": "skills/gmail-automation", + "path": "skills\\gmail-automation", "category": "uncategorized", "name": "gmail-automation", "description": "Automate Gmail tasks via Rube MCP (Composio): send/reply, search, labels, drafts, attachments. Always search tools first for current schemas.", @@ -4195,7 +4276,7 @@ }, { "id": "go-concurrency-patterns", - "path": "skills/go-concurrency-patterns", + "path": "skills\\go-concurrency-patterns", "category": "uncategorized", "name": "go-concurrency-patterns", "description": "Master Go concurrency with goroutines, channels, sync primitives, and context. Use when building concurrent Go applications, implementing worker pools, or debugging race conditions.", @@ -4204,7 +4285,7 @@ }, { "id": "go-playwright", - "path": "skills/go-playwright", + "path": "skills\\go-playwright", "category": "uncategorized", "name": "go-playwright", "description": "Expert capability for robust, stealthy, and efficient browser automation using Playwright Go.", @@ -4213,7 +4294,7 @@ }, { "id": "go-rod-master", - "path": "skills/go-rod-master", + "path": "skills\\go-rod-master", "category": "uncategorized", "name": "go-rod-master", "description": "Comprehensive guide for browser automation and web scraping with go-rod (Chrome DevTools Protocol) including stealth anti-bot-detection patterns.", @@ -4222,7 +4303,7 @@ }, { "id": "godot-4-migration", - "path": "skills/godot-4-migration", + "path": "skills\\godot-4-migration", "category": "uncategorized", "name": "godot-4-migration", "description": "Specialized guide for migrating Godot 3.x projects to Godot 4 (GDScript 2.0), covering syntax changes, Tweens, and exports.", @@ -4231,7 +4312,7 @@ }, { "id": "godot-gdscript-patterns", - "path": "skills/godot-gdscript-patterns", + "path": "skills\\godot-gdscript-patterns", "category": "uncategorized", "name": "godot-gdscript-patterns", "description": "Master Godot 4 GDScript patterns including signals, scenes, state machines, and optimization. Use when building Godot games, implementing game systems, or learning GDScript best practices.", @@ -4240,16 +4321,16 @@ }, { "id": "golang-pro", - "path": "skills/golang-pro", + "path": "skills\\golang-pro", "category": "uncategorized", - "name": "Golang Pro", - "description": "You are a Go expert specializing in modern Go 1.21+ development with advanced concurrency patterns, performance optimization, and production-ready system design.", + "name": "golang-pro", + "description": "Master Go 1.21+ with modern patterns, advanced concurrency,\nperformance optimization, and production-ready microservices. Expert in the\nlatest Go ecosystem including generics, workspaces, and cutting-edge\nframeworks. Use PROACTIVELY for Go development, architecture design, or\nperformance optimization.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "google-analytics-automation", - "path": "skills/google-analytics-automation", + "path": "skills\\google-analytics-automation", "category": "uncategorized", "name": "google-analytics-automation", "description": "Automate Google Analytics tasks via Rube MCP (Composio): run reports, list accounts/properties, funnels, pivots, key events. Always search tools first for current schemas.", @@ -4258,7 +4339,7 @@ }, { "id": "google-calendar-automation", - "path": "skills/google-calendar-automation", + "path": "skills\\google-calendar-automation", "category": "uncategorized", "name": "google-calendar-automation", "description": "Automate Google Calendar events, scheduling, availability checks, and attendee management via Rube MCP (Composio). Create events, find free slots, manage attendees, and list calendars programmatica...", @@ -4267,7 +4348,7 @@ }, { "id": "google-drive-automation", - "path": "skills/google-drive-automation", + "path": "skills\\google-drive-automation", "category": "uncategorized", "name": "google-drive-automation", "description": "Automate Google Drive file operations (upload, download, search, share, organize) via Rube MCP (Composio). Upload/download files, manage folders, share with permissions, and search across drives pr...", @@ -4276,7 +4357,7 @@ }, { "id": "googlesheets-automation", - "path": "skills/googlesheets-automation", + "path": "skills\\googlesheets-automation", "category": "uncategorized", "name": "googlesheets-automation", "description": "Automate Google Sheets operations (read, write, format, filter, manage spreadsheets) via Rube MCP (Composio). Read/write data, manage tabs, apply formatting, and search rows programmatically.", @@ -4285,7 +4366,7 @@ }, { "id": "grafana-dashboards", - "path": "skills/grafana-dashboards", + "path": "skills\\grafana-dashboards", "category": "uncategorized", "name": "grafana-dashboards", "description": "Create and manage production Grafana dashboards for real-time visualization of system and application metrics. Use when building monitoring dashboards, visualizing metrics, or creating operational ...", @@ -4294,7 +4375,7 @@ }, { "id": "graphql", - "path": "skills/graphql", + "path": "skills\\graphql", "category": "uncategorized", "name": "graphql", "description": "GraphQL gives clients exactly the data they need - no more, no less. One endpoint, typed schema, introspection. But the flexibility that makes it powerful also makes it dangerous. Without proper co...", @@ -4303,16 +4384,25 @@ }, { "id": "graphql-architect", - "path": "skills/graphql-architect", + "path": "skills\\graphql-architect", "category": "uncategorized", - "name": "Graphql Architect", - "description": "- Working on graphql architect tasks or workflows - Needing guidance, best practices, or checklists for graphql architect", + "name": "graphql-architect", + "description": "Master modern GraphQL with federation, performance optimization,\nand enterprise security. Build scalable schemas, implement advanced caching,\nand design real-time systems. Use PROACTIVELY for GraphQL architecture or\nperformance optimization.\n", "risk": "unknown", - "source": "unknown" + "source": "community" + }, + { + "id": "grpc-golang", + "path": "skills\\grpc-golang", + "category": "uncategorized", + "name": "grpc-golang", + "description": "Build production-ready gRPC services in Go with mTLS, streaming, and observability. Use when designing Protobuf contracts with Buf or implementing secure service-to-service transport.", + "risk": "safe", + "source": "self" }, { "id": "haskell-pro", - "path": "skills/haskell-pro", + "path": "skills\\haskell-pro", "category": "uncategorized", "name": "haskell-pro", "description": "Expert Haskell engineer specializing in advanced type systems, pure functional design, and high-reliability software. Use PROACTIVELY for type-level programming, concurrency, and architecture guidance.", @@ -4321,7 +4411,7 @@ }, { "id": "helm-chart-scaffolding", - "path": "skills/helm-chart-scaffolding", + "path": "skills\\helm-chart-scaffolding", "category": "uncategorized", "name": "helm-chart-scaffolding", "description": "Design, organize, and manage Helm charts for templating and packaging Kubernetes applications with reusable configurations. Use when creating Helm charts, packaging Kubernetes applications, or impl...", @@ -4330,7 +4420,7 @@ }, { "id": "helpdesk-automation", - "path": "skills/helpdesk-automation", + "path": "skills\\helpdesk-automation", "category": "uncategorized", "name": "helpdesk-automation", "description": "Automate HelpDesk tasks via Rube MCP (Composio): list tickets, manage views, use canned responses, and configure custom fields. Always search tools first for current schemas.", @@ -4339,133 +4429,133 @@ }, { "id": "hig-components-content", - "path": "skills/hig-components-content", + "path": "skills\\hig-components-content", "category": "uncategorized", - "name": "Hig Components Content", - "description": "Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.", + "name": "hig-components-content", + "description": "Apple Human Interface Guidelines for content display components. Use this skill when the user asks about \"charts component\", \"collection view\", \"image view\", \"web view\", \"color well\", \"image well\", \"activity view\", \"lockup\", \"data visualization\", \"content display\", displaying images, rendering web content, color pickers, or presenting collections of items in Apple apps. Also use when the user says \"how should I display charts\", \"what's the best way to show images\", \"should I use a web view\", \"how do I build a grid of items\", \"what component shows media\", or \"how do I present a share sheet\". Cross-references: hig-foundations for color/typography/accessibility, hig-patterns for data visualization patterns, hig-components-layout for structural containers, hig-platforms for platform-specific component behavior.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "hig-components-controls", - "path": "skills/hig-components-controls", + "path": "skills\\hig-components-controls", "category": "uncategorized", - "name": "Hig Components Controls", - "description": "Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.", + "name": "hig-components-controls", + "description": "Apple HIG guidance for selection and input controls including pickers, toggles, sliders, steppers, segmented controls, combo boxes, text fields, text views, labels, token fields, virtual keyboards, rating indicators, and gauges. Use this skill when the user says \"picker or segmented control,\" \"how should my form look,\" \"what keyboard type should I use,\" \"toggle vs checkbox,\" or asks about picker design, toggle, switch, slider, stepper, text field, text input, segmented control, combo box, label, token field, virtual keyboard, rating indicator, gauge, form design, input validation, or control state management. Cross-references: hig-components-menus, hig-components-dialogs, hig-components-search.", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "hig-components-dialogs", - "path": "skills/hig-components-dialogs", + "path": "skills\\hig-components-dialogs", "category": "uncategorized", - "name": "Hig Components Dialogs", - "description": "Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.", + "name": "hig-components-dialogs", + "description": "Apple HIG guidance for presentation components including alerts, action sheets, popovers, sheets, and digit entry views. Use this skill when the user says \"should I use an alert or a sheet,\" \"how do I show a confirmation dialog,\" \"when should I use a popover,\" \"my modals are annoying users,\" or asks about alert design, action sheet, popover, sheet, modal, dialog, digit entry, confirmation dialog, warning dialog, modal presentation, non-modal content, destructive action confirmation, or overlay UI patterns. Cross-references: hig-components-menus, hig-components-controls, hig-components-search, hig-patterns.", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "hig-components-layout", - "path": "skills/hig-components-layout", + "path": "skills\\hig-components-layout", "category": "uncategorized", - "name": "Hig Components Layout", - "description": "Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.", + "name": "hig-components-layout", + "description": "Apple Human Interface Guidelines for layout and navigation components. Use this skill when the user asks about \"sidebar\", \"split view\", \"tab bar\", \"tab view\", \"scroll view\", \"window design\", \"panel\", \"list view\", \"table view\", \"column view\", \"outline view\", \"navigation structure\", \"app layout\", \"boxes\", \"ornaments\", or organizing content hierarchically in Apple apps. Also use when the user says \"how should I organize my app\", \"what navigation pattern should I use\", \"my layout breaks on iPad\", \"how do I build a sidebar\", \"should I use tabs or a sidebar\", or \"my app doesn't adapt to different screen sizes\". Cross-references: hig-foundations for layout/spacing principles, hig-platforms for platform-specific navigation, hig-patterns for multitasking and full-screen, hig-components-content for content display.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "hig-components-menus", - "path": "skills/hig-components-menus", + "path": "skills\\hig-components-menus", "category": "uncategorized", - "name": "Hig Components Menus", - "description": "Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.", + "name": "hig-components-menus", + "description": "Apple HIG guidance for menu and button components including menus, context menus, dock menus, edit menus, the menu bar, toolbars, action buttons, pop-up buttons, pull-down buttons, disclosure controls, and standard buttons. Use this skill when the user says \"how should my buttons look,\" \"what goes in the menu bar,\" \"should I use a context menu or action sheet,\" \"how do I design a toolbar,\" or asks about button design, menu design, context menu, toolbar, menu bar, action button, pop-up button, pull-down button, disclosure control, dock menu, edit menu, or any menu/button component layout and behavior. Cross-references: hig-components-search, hig-components-controls, hig-components-dialogs.", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "hig-components-search", - "path": "skills/hig-components-search", + "path": "skills\\hig-components-search", "category": "uncategorized", - "name": "Hig Components Search", - "description": "Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.", + "name": "hig-components-search", + "description": "Apple HIG guidance for navigation-related components including search fields, page controls, and path controls. Use this skill when the user says \"how should search work in my app,\" \"I need a breadcrumb,\" \"how do I paginate content,\" or asks about search field, search bar, page control, path control, breadcrumb, navigation component, search UX, search suggestions, search scopes, paginated content navigation, or file path hierarchy display. Cross-references: hig-components-menus, hig-components-controls, hig-components-dialogs, hig-patterns.", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "hig-components-status", - "path": "skills/hig-components-status", + "path": "skills\\hig-components-status", "category": "uncategorized", - "name": "Hig Components Status", - "description": "Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.", + "name": "hig-components-status", + "description": "Apple HIG guidance for status and progress UI components including progress indicators, status bars, and activity rings. Use this skill when asked about: \"progress indicator\", \"progress bar\", \"loading spinner\", \"status bar\", \"activity ring\", \"progress display\", determinate vs indeterminate progress, loading states, or fitness tracking rings. Also use when the user says \"how do I show loading state,\" \"should I use a spinner or progress bar,\" \"what goes in the status bar,\" or asks about activity indicators. Cross-references: hig-components-system for widgets and complications, hig-inputs for gesture-driven progress controls, hig-technologies for HealthKit and activity ring data integration.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "hig-components-system", - "path": "skills/hig-components-system", + "path": "skills\\hig-components-system", "category": "uncategorized", - "name": "Hig Components System", - "description": "Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.", + "name": "hig-components-system", + "description": "Apple HIG guidance for system experience components: widgets, live activities, notifications, complications, home screen quick actions, top shelf, watch faces, app clips, and app shortcuts. Use when asked about: \"widget design\", \"live activity\", \"notification design\", \"complication\", \"home screen quick action\", \"top shelf\", \"watch face\", \"app clip\", \"app shortcut\", \"system experience\". Also use when the user says \"how do I design a widget,\" \"what should my notification look like,\" \"how do Live Activities work,\" \"should I make an App Clip,\" or asks about surfaces outside the main app. Cross-references: hig-components-status for progress in widgets, hig-inputs for interaction patterns, hig-technologies for Siri and system integration.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "hig-foundations", - "path": "skills/hig-foundations", + "path": "skills\\hig-foundations", "category": "uncategorized", - "name": "Hig Foundations", - "description": "Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.", + "name": "hig-foundations", + "description": "Apple Human Interface Guidelines design foundations. Use this skill when the user asks about \"HIG color\", \"Apple typography\", \"SF Symbols\", \"dark mode guidelines\", \"accessible design\", \"Apple design foundations\", \"app icon\", \"layout guidelines\", \"materials\", \"motion\", \"privacy\", \"right to left\", \"RTL\", \"inclusive design\", branding, images, spatial layout, or writing style. Also use when the user says \"my colors look wrong in dark mode\", \"what font should I use\", \"is my app accessible enough\", \"how do I support Dynamic Type\", \"what contrast ratio do I need\", \"how do I pick system colors\", or \"my icons don't match the system style\". Cross-references: hig-platforms for platform-specific guidance, hig-patterns for interaction patterns, hig-components-layout for structural components, hig-components-content for display.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "hig-inputs", - "path": "skills/hig-inputs", + "path": "skills\\hig-inputs", "category": "uncategorized", - "name": "Hig Inputs", - "description": "Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.", + "name": "hig-inputs", + "description": "Apple HIG guidance for input methods and interaction patterns: gestures, Apple Pencil, keyboards, game controllers, pointers, Digital Crown, eye tracking, focus system, remotes, spatial interactions, gyroscope, accelerometer, and nearby interactions. Use when asked about: \"gesture design\", \"Apple Pencil\", \"keyboard shortcuts\", \"game controller\", \"pointer support\", \"mouse support\", \"trackpad\", \"Digital Crown\", \"eye tracking\", \"visionOS input\", \"focus system\", \"remote control\", \"gyroscope\", \"spatial interaction\". Also use when the user says \"what gestures should I support,\" \"how do I add keyboard shortcuts,\" \"how does input work on Apple TV,\" \"should I support Apple Pencil,\" or asks about input device handling. Cross-references: hig-components-status, hig-components-system, hig-technologies for VoiceOver and Siri.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "hig-patterns", - "path": "skills/hig-patterns", + "path": "skills\\hig-patterns", "category": "uncategorized", - "name": "Hig Patterns", - "description": "Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.", + "name": "hig-patterns", + "description": "Apple Human Interface Guidelines interaction and UX patterns. Use this skill when the user asks about \"onboarding flow\", \"user onboarding\", \"app launch\", \"loading state\", \"drag and drop\", \"search pattern\", \"settings design\", \"notifications\", \"modality\", \"multitasking\", \"feedback pattern\", \"haptics\", \"undo redo\", \"file management\", data entry, sharing, collaboration, full screen, audio, video, haptic feedback, ratings, printing, help, or account management in Apple apps. Also use when the user says \"how should onboarding work\", \"my app takes too long to load\", \"should I use a modal here\", \"how do I handle errors\", \"when should I ask for permissions\", \"how to show progress\", or \"what's the right way to confirm a delete\". Cross-references: hig-foundations for underlying principles, hig-platforms for platform specifics, hig-components-layout for navigation, hig-components-content for data display.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "hig-platforms", - "path": "skills/hig-platforms", + "path": "skills\\hig-platforms", "category": "uncategorized", - "name": "Hig Platforms", - "description": "Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.", + "name": "hig-platforms", + "description": "Apple Human Interface Guidelines for platform-specific design. Use this skill when the user asks about \"designing for iOS\", \"iPad app design\", \"macOS design\", \"tvOS\", \"visionOS\", \"watchOS\", \"Apple platform\", \"which platform\", platform differences, platform-specific conventions, or multi-platform app design. Also use when the user says \"should I design differently for iPad vs iPhone\", \"how does my app work on visionOS\", \"what's different about macOS apps\", \"porting my app to another platform\", \"universal app design\", or \"what input methods does this platform use\". Cross-references: hig-foundations for shared design foundations, hig-patterns for interaction patterns, hig-components-layout for navigation structures, hig-components-content for content display.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "hig-project-context", - "path": "skills/hig-project-context", + "path": "skills\\hig-project-context", "category": "uncategorized", - "name": "Hig Project Context", - "description": "Create and maintain `.claude/apple-design-context.md` so other HIG skills can skip redundant questions.", + "name": "hig-project-context", + "description": "Create or update a shared Apple design context document that other HIG skills use to tailor guidance. Use when the user says \"set up my project context,\" \"what platforms am I targeting,\" \"configure HIG settings,\" or when starting a new Apple platform project. Also activates when other HIG skills need project context but none exists yet. This skill creates .claude/apple-design-context.md so that hig-foundations, hig-platforms, hig-components-*, hig-inputs, and hig-technologies can provide targeted advice without repetitive questions.", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "hig-technologies", - "path": "skills/hig-technologies", + "path": "skills\\hig-technologies", "category": "uncategorized", - "name": "Hig Technologies", - "description": "Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.", + "name": "hig-technologies", + "description": "Apple HIG guidance for Apple technology integrations: Siri, Apple Pay, HealthKit, HomeKit, ARKit, machine learning, generative AI, iCloud, Sign in with Apple, SharePlay, CarPlay, Game Center, in-app purchase, NFC, Wallet, VoiceOver, Maps, Mac Catalyst, and more. Use when asked about: \"Siri integration\", \"Apple Pay\", \"HealthKit\", \"HomeKit\", \"ARKit\", \"augmented reality\", \"machine learning\", \"generative AI\", \"iCloud sync\", \"Sign in with Apple\", \"SharePlay\", \"CarPlay\", \"in-app purchase\", \"NFC\", \"VoiceOver\", \"Maps\", \"Mac Catalyst\". Also use when the user says \"how do I integrate Siri,\" \"what are the Apple Pay guidelines,\" \"how should my AR experience work,\" \"how do I use Sign in with Apple,\" or asks about any Apple framework or service integration. Cross-references: hig-inputs for input methods, hig-components-system for widgets.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "hosted-agents-v2-py", - "path": "skills/hosted-agents-v2-py", + "path": "skills\\hosted-agents-v2-py", "category": "uncategorized", "name": "hosted-agents-v2-py", "description": "Build hosted agents using Azure AI Projects SDK with ImageBasedHostedAgentDefinition. Use when creating container-based agents in Azure AI Foundry.", @@ -4474,16 +4564,16 @@ }, { "id": "hr-pro", - "path": "skills/hr-pro", + "path": "skills\\hr-pro", "category": "uncategorized", - "name": "Hr Pro", - "description": "- Working on hr pro tasks or workflows - Needing guidance, best practices, or checklists for hr pro", + "name": "hr-pro", + "description": "Professional, ethical HR partner for hiring,\nonboarding/offboarding, PTO and leave, performance, compliant policies, and\nemployee relations. Ask for jurisdiction and company context before advising;\nproduce structured, bias-mitigated, lawful templates.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "html-injection-testing", - "path": "skills/html-injection-testing", + "path": "skills\\html-injection-testing", "category": "uncategorized", "name": "html-injection-testing", "description": "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 applications\", or \"test conten...", @@ -4492,7 +4582,7 @@ }, { "id": "hubspot-automation", - "path": "skills/hubspot-automation", + "path": "skills\\hubspot-automation", "category": "uncategorized", "name": "hubspot-automation", "description": "Automate HubSpot CRM operations (contacts, companies, deals, tickets, properties) via Rube MCP using Composio integration.", @@ -4501,7 +4591,7 @@ }, { "id": "hubspot-integration", - "path": "skills/hubspot-integration", + "path": "skills\\hubspot-integration", "category": "uncategorized", "name": "hubspot-integration", "description": "Expert patterns for HubSpot CRM integration including OAuth authentication, CRM objects, associations, batch operations, webhooks, and custom objects. Covers Node.js and Python SDKs. Use when: hubs...", @@ -4510,7 +4600,7 @@ }, { "id": "hugging-face-cli", - "path": "skills/hugging-face-cli", + "path": "skills\\hugging-face-cli", "category": "uncategorized", "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 comput...", @@ -4519,7 +4609,7 @@ }, { "id": "hugging-face-jobs", - "path": "skills/hugging-face-jobs", + "path": "skills\\hugging-face-jobs", "category": "uncategorized", "name": "hugging-face-jobs", "description": "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, cost estimation, authentication with tok...", @@ -4528,16 +4618,16 @@ }, { "id": "hybrid-cloud-architect", - "path": "skills/hybrid-cloud-architect", + "path": "skills\\hybrid-cloud-architect", "category": "uncategorized", - "name": "Hybrid Cloud Architect", - "description": "- Working on hybrid cloud architect tasks or workflows - Needing guidance, best practices, or checklists for hybrid cloud architect", + "name": "hybrid-cloud-architect", + "description": "Expert hybrid cloud architect specializing in complex multi-cloud\nsolutions across AWS/Azure/GCP and private clouds (OpenStack/VMware). Masters\nhybrid connectivity, workload placement optimization, edge computing, and\ncross-cloud automation. Handles compliance, cost optimization, disaster\nrecovery, and migration strategies. Use PROACTIVELY for hybrid architecture,\nmulti-cloud strategy, or complex infrastructure integration.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "hybrid-cloud-networking", - "path": "skills/hybrid-cloud-networking", + "path": "skills\\hybrid-cloud-networking", "category": "uncategorized", "name": "hybrid-cloud-networking", "description": "Configure secure, high-performance connectivity between on-premises infrastructure and cloud platforms using VPN and dedicated connections. Use when building hybrid cloud architectures, connecting ...", @@ -4546,7 +4636,7 @@ }, { "id": "hybrid-search-implementation", - "path": "skills/hybrid-search-implementation", + "path": "skills\\hybrid-search-implementation", "category": "uncategorized", "name": "hybrid-search-implementation", "description": "Combine vector and keyword search for improved retrieval. Use when implementing RAG systems, building search engines, or when neither approach alone provides sufficient recall.", @@ -4555,7 +4645,7 @@ }, { "id": "i18n-localization", - "path": "skills/i18n-localization", + "path": "skills\\i18n-localization", "category": "uncategorized", "name": "i18n-localization", "description": "Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support.", @@ -4564,7 +4654,7 @@ }, { "id": "idor-testing", - "path": "skills/idor-testing", + "path": "skills\\idor-testing", "category": "uncategorized", "name": "idor-testing", "description": "This skill should be used when the user asks to \"test for insecure direct object references,\" \"find IDOR vulnerabilities,\" \"exploit broken access control,\" \"enumerate user IDs or obje...", @@ -4573,16 +4663,16 @@ }, { "id": "imagen", - "path": "skills/imagen", + "path": "skills\\imagen", "category": "uncategorized", "name": "imagen", - "description": "|", + "description": "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", "risk": "safe", "source": "https://github.com/sanjay3290/ai-skills/tree/main/skills/imagen" }, { "id": "impress", - "path": "skills/libreoffice/impress", + "path": "skills\\libreoffice\\impress", "category": "libreoffice", "name": "impress", "description": "Presentation creation, format conversion (ODP/PPTX/PDF), slide automation with LibreOffice Impress.", @@ -4591,16 +4681,16 @@ }, { "id": "incident-responder", - "path": "skills/incident-responder", + "path": "skills\\incident-responder", "category": "uncategorized", - "name": "Incident Responder", - "description": "- Working on incident responder tasks or workflows - Needing guidance, best practices, or checklists for incident responder", + "name": "incident-responder", + "description": "Expert SRE incident responder specializing in rapid problem\nresolution, modern observability, and comprehensive incident management.\nMasters incident command, blameless post-mortems, error budget management, and\nsystem reliability patterns. Handles critical outages, communication\nstrategies, and continuous improvement. Use IMMEDIATELY for production\nincidents or SRE practices.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "incident-response-incident-response", - "path": "skills/incident-response-incident-response", + "path": "skills\\incident-response-incident-response", "category": "uncategorized", "name": "incident-response-incident-response", "description": "Use when working with incident response incident response", @@ -4609,7 +4699,7 @@ }, { "id": "incident-response-smart-fix", - "path": "skills/incident-response-smart-fix", + "path": "skills\\incident-response-smart-fix", "category": "uncategorized", "name": "incident-response-smart-fix", "description": "[Extended thinking: This workflow implements a sophisticated debugging and resolution pipeline that leverages AI-assisted debugging tools and observability platforms to systematically diagnose and res", @@ -4618,7 +4708,7 @@ }, { "id": "incident-runbook-templates", - "path": "skills/incident-runbook-templates", + "path": "skills\\incident-runbook-templates", "category": "uncategorized", "name": "incident-runbook-templates", "description": "Create structured incident response runbooks with step-by-step procedures, escalation paths, and recovery actions. Use when building runbooks, responding to incidents, or establishing incident resp...", @@ -4627,7 +4717,7 @@ }, { "id": "infinite-gratitude", - "path": "skills/infinite-gratitude", + "path": "skills\\infinite-gratitude", "category": "uncategorized", "name": "infinite-gratitude", "description": "Multi-agent research skill for parallel research execution (10 agents, battle-tested with real case studies).", @@ -4636,7 +4726,7 @@ }, { "id": "inngest", - "path": "skills/inngest", + "path": "skills\\inngest", "category": "uncategorized", "name": "inngest", "description": "Inngest expert for serverless-first background jobs, event-driven workflows, and durable execution without managing queues or workers. Use when: inngest, serverless background job, event-driven wor...", @@ -4645,7 +4735,7 @@ }, { "id": "instagram-automation", - "path": "skills/instagram-automation", + "path": "skills\\instagram-automation", "category": "uncategorized", "name": "instagram-automation", "description": "Automate Instagram tasks via Rube MCP (Composio): create posts, carousels, manage media, get insights, and publishing limits. Always search tools first for current schemas.", @@ -4654,7 +4744,7 @@ }, { "id": "interactive-portfolio", - "path": "skills/interactive-portfolio", + "path": "skills\\interactive-portfolio", "category": "uncategorized", "name": "interactive-portfolio", "description": "Expert in building portfolios that actually land jobs and clients - not just showing work, but creating memorable experiences. Covers developer portfolios, designer portfolios, creative portfolios,...", @@ -4663,7 +4753,7 @@ }, { "id": "intercom-automation", - "path": "skills/intercom-automation", + "path": "skills\\intercom-automation", "category": "uncategorized", "name": "intercom-automation", "description": "Automate Intercom tasks via Rube MCP (Composio): conversations, contacts, companies, segments, admins. Always search tools first for current schemas.", @@ -4672,7 +4762,7 @@ }, { "id": "internal-comms-anthropic", - "path": "skills/internal-comms-anthropic", + "path": "skills\\internal-comms-anthropic", "category": "uncategorized", "name": "internal-comms-anthropic", "description": "A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal ...", @@ -4681,7 +4771,7 @@ }, { "id": "internal-comms-community", - "path": "skills/internal-comms-community", + "path": "skills\\internal-comms-community", "category": "uncategorized", "name": "internal-comms-community", "description": "A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal ...", @@ -4689,17 +4779,26 @@ "source": "community" }, { - "id": "ios-developer", - "path": "skills/ios-developer", + "id": "inventory-demand-planning", + "path": "skills\\inventory-demand-planning", "category": "uncategorized", - "name": "Ios Developer", - "description": "- Working on ios developer tasks or workflows - Needing guidance, best practices, or checklists for ios developer", + "name": "inventory-demand-planning", + "description": "Codified expertise for demand forecasting, safety stock optimisation, replenishment planning, and promotional lift estimation at multi-location retailers. Informed by demand planners with 15+ years experience managing hundreds of SKUs. Includes forecasting method selection, ABC/XYZ analysis, seasonal transition management, and vendor negotiation frameworks. Use when forecasting demand, setting safety stock, planning replenishment, managing promotions, or optimising inventory levels.\n", + "risk": "safe", + "source": "https://github.com/ai-evos/agent-skills" + }, + { + "id": "ios-developer", + "path": "skills\\ios-developer", + "category": "uncategorized", + "name": "ios-developer", + "description": "Develop native iOS applications with Swift/SwiftUI. Masters iOS 18,\nSwiftUI, UIKit integration, Core Data, networking, and App Store optimization.\nUse PROACTIVELY for iOS-specific features, App Store optimization, or native\niOS development.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "istio-traffic-management", - "path": "skills/istio-traffic-management", + "path": "skills\\istio-traffic-management", "category": "uncategorized", "name": "istio-traffic-management", "description": "Configure Istio traffic management including routing, load balancing, circuit breakers, and canary deployments. Use when implementing service mesh traffic policies, progressive delivery, or resilie...", @@ -4708,7 +4807,7 @@ }, { "id": "iterate-pr", - "path": "skills/iterate-pr", + "path": "skills\\iterate-pr", "category": "uncategorized", "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.", @@ -4717,34 +4816,34 @@ }, { "id": "java-pro", - "path": "skills/java-pro", + "path": "skills\\java-pro", "category": "uncategorized", - "name": "Java Pro", - "description": "- Working on java pro tasks or workflows - Needing guidance, best practices, or checklists for java pro", + "name": "java-pro", + "description": "Master Java 21+ with modern features like virtual threads, pattern\nmatching, and Spring Boot 3.x. Expert in the latest Java ecosystem including\nGraalVM, Project Loom, and cloud-native patterns. Use PROACTIVELY for Java\ndevelopment, microservices architecture, or performance optimization.\n", "risk": "unknown", - "source": "unknown" - }, - { - "id": "javascript-pro", - "path": "skills/javascript-pro", - "category": "uncategorized", - "name": "Javascript Pro", - "description": "You are a JavaScript expert specializing in modern JS and async programming.", - "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "javascript-mastery", - "path": "skills/javascript-mastery", + "path": "skills\\javascript-mastery", "category": "uncategorized", "name": "javascript-mastery", "description": "Comprehensive JavaScript reference covering 33+ essential concepts every developer should know. From fundamentals like primitives and closures to advanced patterns like async/await and functional p...", "risk": "unknown", "source": "community" }, + { + "id": "javascript-pro", + "path": "skills\\javascript-pro", + "category": "uncategorized", + "name": "javascript-pro", + "description": "Master modern JavaScript with ES6+, async patterns, and Node.js\nAPIs. Handles promises, event loops, and browser/Node compatibility. Use\nPROACTIVELY for JavaScript optimization, async debugging, or complex JS\npatterns.\n", + "risk": "unknown", + "source": "community" + }, { "id": "javascript-testing-patterns", - "path": "skills/javascript-testing-patterns", + "path": "skills\\javascript-testing-patterns", "category": "uncategorized", "name": "javascript-testing-patterns", "description": "Implement comprehensive testing strategies using Jest, Vitest, and Testing Library for unit tests, integration tests, and end-to-end testing with mocking, fixtures, and test-driven development. Use...", @@ -4753,7 +4852,7 @@ }, { "id": "javascript-typescript-typescript-scaffold", - "path": "skills/javascript-typescript-typescript-scaffold", + "path": "skills\\javascript-typescript-typescript-scaffold", "category": "uncategorized", "name": "javascript-typescript-typescript-scaffold", "description": "You are a TypeScript project architecture expert specializing in scaffolding production-ready Node.js and frontend applications. Generate complete project structures with modern tooling (pnpm, Vite, N", @@ -4762,7 +4861,7 @@ }, { "id": "jira-automation", - "path": "skills/jira-automation", + "path": "skills\\jira-automation", "category": "uncategorized", "name": "jira-automation", "description": "Automate Jira tasks via Rube MCP (Composio): issues, projects, sprints, boards, comments, users. Always search tools first for current schemas.", @@ -4771,16 +4870,16 @@ }, { "id": "julia-pro", - "path": "skills/julia-pro", + "path": "skills\\julia-pro", "category": "uncategorized", - "name": "Julia Pro", - "description": "- Working on julia pro tasks or workflows - Needing guidance, best practices, or checklists for julia pro", + "name": "julia-pro", + "description": "Master Julia 1.10+ with modern features, performance optimization,\nmultiple dispatch, and production-ready practices. Expert in the Julia\necosystem including package management, scientific computing, and\nhigh-performance numerical code. Use PROACTIVELY for Julia development,\noptimization, or advanced Julia patterns.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "k8s-manifest-generator", - "path": "skills/k8s-manifest-generator", + "path": "skills\\k8s-manifest-generator", "category": "uncategorized", "name": "k8s-manifest-generator", "description": "Create production-ready Kubernetes manifests for Deployments, Services, ConfigMaps, and Secrets following best practices and security standards. Use when generating Kubernetes YAML manifests, creat...", @@ -4789,7 +4888,7 @@ }, { "id": "k8s-security-policies", - "path": "skills/k8s-security-policies", + "path": "skills\\k8s-security-policies", "category": "uncategorized", "name": "k8s-security-policies", "description": "Implement Kubernetes security policies including NetworkPolicy, PodSecurityPolicy, and RBAC for production-grade security. Use when securing Kubernetes clusters, implementing network isolation, or ...", @@ -4798,7 +4897,7 @@ }, { "id": "kaizen", - "path": "skills/kaizen", + "path": "skills\\kaizen", "category": "uncategorized", "name": "kaizen", "description": "Guide for continuous improvement, error proofing, and standardization. Use this skill when the user wants to improve code quality, refactor, or discuss process improvements.", @@ -4807,7 +4906,7 @@ }, { "id": "klaviyo-automation", - "path": "skills/klaviyo-automation", + "path": "skills\\klaviyo-automation", "category": "uncategorized", "name": "klaviyo-automation", "description": "Automate Klaviyo tasks via Rube MCP (Composio): manage email/SMS campaigns, inspect campaign messages, track tags, and monitor send jobs. Always search tools first for current schemas.", @@ -4816,7 +4915,7 @@ }, { "id": "kotlin-coroutines-expert", - "path": "skills/kotlin-coroutines-expert", + "path": "skills\\kotlin-coroutines-expert", "category": "uncategorized", "name": "kotlin-coroutines-expert", "description": "Expert patterns for Kotlin Coroutines and Flow, covering structured concurrency, error handling, and testing.", @@ -4825,7 +4924,7 @@ }, { "id": "kpi-dashboard-design", - "path": "skills/kpi-dashboard-design", + "path": "skills\\kpi-dashboard-design", "category": "uncategorized", "name": "kpi-dashboard-design", "description": "Design effective KPI dashboards with metrics selection, visualization best practices, and real-time monitoring patterns. Use when building business dashboards, selecting metrics, or designing data ...", @@ -4834,16 +4933,16 @@ }, { "id": "kubernetes-architect", - "path": "skills/kubernetes-architect", + "path": "skills\\kubernetes-architect", "category": "uncategorized", - "name": "Kubernetes Architect", - "description": "You are a Kubernetes architect specializing in cloud-native infrastructure, modern GitOps workflows, and enterprise container orchestration at scale.", + "name": "kubernetes-architect", + "description": "Expert Kubernetes architect specializing in cloud-native\ninfrastructure, advanced GitOps workflows (ArgoCD/Flux), and enterprise\ncontainer orchestration. Masters EKS/AKS/GKE, service mesh (Istio/Linkerd),\nprogressive delivery, multi-tenancy, and platform engineering. Handles\nsecurity, observability, cost optimization, and developer experience. Use\nPROACTIVELY for K8s architecture, GitOps implementation, or cloud-native\nplatform design.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "kubernetes-deployment", - "path": "skills/kubernetes-deployment", + "path": "skills\\kubernetes-deployment", "category": "uncategorized", "name": "kubernetes-deployment", "description": "Kubernetes deployment workflow for container orchestration, Helm charts, service mesh, and production-ready K8s configurations.", @@ -4852,7 +4951,7 @@ }, { "id": "langchain-architecture", - "path": "skills/langchain-architecture", + "path": "skills\\langchain-architecture", "category": "uncategorized", "name": "langchain-architecture", "description": "Design LLM applications using the LangChain framework with agents, memory, and tool integration patterns. Use when building LangChain applications, implementing AI agents, or creating complex LLM w...", @@ -4861,7 +4960,7 @@ }, { "id": "langfuse", - "path": "skills/langfuse", + "path": "skills\\langfuse", "category": "uncategorized", "name": "langfuse", "description": "Expert in Langfuse - the open-source LLM observability platform. Covers tracing, prompt management, evaluation, datasets, and integration with LangChain, LlamaIndex, and OpenAI. Essential for debug...", @@ -4870,7 +4969,7 @@ }, { "id": "langgraph", - "path": "skills/langgraph", + "path": "skills\\langgraph", "category": "uncategorized", "name": "langgraph", "description": "Expert in LangGraph - the production-grade framework for building stateful, multi-actor AI applications. Covers graph construction, state management, cycles and branches, persistence with checkpoin...", @@ -4879,7 +4978,7 @@ }, { "id": "laravel-expert", - "path": "skills/laravel-expert", + "path": "skills\\laravel-expert", "category": "uncategorized", "name": "laravel-expert", "description": "Senior Laravel Engineer role for production-grade, maintainable, and idiomatic Laravel solutions. Focuses on clean architecture, security, performance, and modern standards (Laravel 10/11+).", @@ -4888,7 +4987,7 @@ }, { "id": "laravel-security-audit", - "path": "skills/laravel-security-audit", + "path": "skills\\laravel-security-audit", "category": "uncategorized", "name": "laravel-security-audit", "description": "Security auditor for Laravel applications. Analyzes code for vulnerabilities, misconfigurations, and insecure practices using OWASP standards and Laravel security best practices.", @@ -4897,7 +4996,7 @@ }, { "id": "last30days", - "path": "skills/last30days", + "path": "skills\\last30days", "category": "uncategorized", "name": "last30days", "description": "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.", @@ -4906,7 +5005,7 @@ }, { "id": "launch-strategy", - "path": "skills/launch-strategy", + "path": "skills\\launch-strategy", "category": "uncategorized", "name": "launch-strategy", "description": "When the user wants to plan a product launch, feature announcement, or release strategy. Also use when the user mentions 'launch,' 'Product Hunt,' 'feature release,' 'announcement,' 'go-to-market,'...", @@ -4915,25 +5014,25 @@ }, { "id": "legacy-modernizer", - "path": "skills/legacy-modernizer", + "path": "skills\\legacy-modernizer", "category": "uncategorized", - "name": "Legacy Modernizer", - "description": "- Working on legacy modernizer tasks or workflows - Needing guidance, best practices, or checklists for legacy modernizer", + "name": "legacy-modernizer", + "description": "Refactor legacy codebases, migrate outdated frameworks, and\nimplement gradual modernization. Handles technical debt, dependency updates,\nand backward compatibility. Use PROACTIVELY for legacy system updates,\nframework migrations, or technical debt reduction.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "legal-advisor", - "path": "skills/legal-advisor", + "path": "skills\\legal-advisor", "category": "uncategorized", - "name": "Legal Advisor", - "description": "- Working on legal advisor tasks or workflows - Needing guidance, best practices, or checklists for legal advisor", + "name": "legal-advisor", + "description": "Draft privacy policies, terms of service, disclaimers, and legal\nnotices. Creates GDPR-compliant texts, cookie policies, and data processing\nagreements. Use PROACTIVELY for legal documentation, compliance texts, or\nregulatory requirements.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "linear-automation", - "path": "skills/linear-automation", + "path": "skills\\linear-automation", "category": "uncategorized", "name": "linear-automation", "description": "Automate Linear tasks via Rube MCP (Composio): issues, projects, cycles, teams, labels. Always search tools first for current schemas.", @@ -4942,7 +5041,7 @@ }, { "id": "linear-claude-skill", - "path": "skills/linear-claude-skill", + "path": "skills\\linear-claude-skill", "category": "uncategorized", "name": "linear-claude-skill", "description": "Manage Linear issues, projects, and teams", @@ -4951,16 +5050,25 @@ }, { "id": "linkedin-automation", - "path": "skills/linkedin-automation", + "path": "skills\\linkedin-automation", "category": "uncategorized", "name": "linkedin-automation", "description": "Automate LinkedIn tasks via Rube MCP (Composio): create posts, manage profile, company info, comments, and image uploads. Always search tools first for current schemas.", "risk": "unknown", "source": "community" }, + { + "id": "linkedin-cli", + "path": "skills\\linkedin-cli", + "category": "uncategorized", + "name": "linkedin-cli", + "description": "Use when automating LinkedIn via CLI: fetch profiles, search people/companies, send messages, manage connections, create posts, and Sales Navigator.", + "risk": "safe", + "source": "community" + }, { "id": "linkerd-patterns", - "path": "skills/linkerd-patterns", + "path": "skills\\linkerd-patterns", "category": "uncategorized", "name": "linkerd-patterns", "description": "Implement Linkerd service mesh patterns for lightweight, security-focused service mesh deployments. Use when setting up Linkerd, configuring traffic policies, or implementing zero-trust networking ...", @@ -4969,7 +5077,7 @@ }, { "id": "lint-and-validate", - "path": "skills/lint-and-validate", + "path": "skills\\lint-and-validate", "category": "uncategorized", "name": "lint-and-validate", "description": "Automatic quality control, linting, and static analysis procedures. Use after every code modification to ensure syntax correctness and project standards. Triggers onKeywords: lint, format, check, v...", @@ -4978,7 +5086,7 @@ }, { "id": "linux-privilege-escalation", - "path": "skills/linux-privilege-escalation", + "path": "skills\\linux-privilege-escalation", "category": "uncategorized", "name": "linux-privilege-escalation", "description": "This skill should be used when the user asks to \"escalate privileges on Linux\", \"find privesc vectors on Linux systems\", \"exploit sudo misconfigurations\", \"abuse SUID binaries\", \"ex...", @@ -4987,7 +5095,7 @@ }, { "id": "linux-shell-scripting", - "path": "skills/linux-shell-scripting", + "path": "skills\\linux-shell-scripting", "category": "uncategorized", "name": "linux-shell-scripting", "description": "This skill should be used when the user asks to \"create bash scripts\", \"automate Linux tasks\", \"monitor system resources\", \"backup files\", \"manage users\", or \"write production she...", @@ -4996,7 +5104,7 @@ }, { "id": "linux-troubleshooting", - "path": "skills/linux-troubleshooting", + "path": "skills\\linux-troubleshooting", "category": "uncategorized", "name": "linux-troubleshooting", "description": "Linux system troubleshooting workflow for diagnosing and resolving system issues, performance problems, and service failures.", @@ -5005,7 +5113,7 @@ }, { "id": "llm-app-patterns", - "path": "skills/llm-app-patterns", + "path": "skills\\llm-app-patterns", "category": "uncategorized", "name": "llm-app-patterns", "description": "Production-ready patterns for building LLM applications. Covers RAG pipelines, agent architectures, prompt IDEs, and LLMOps monitoring. Use when designing AI applications, implementing RAG, buildin...", @@ -5014,7 +5122,7 @@ }, { "id": "llm-application-dev-ai-assistant", - "path": "skills/llm-application-dev-ai-assistant", + "path": "skills\\llm-application-dev-ai-assistant", "category": "uncategorized", "name": "llm-application-dev-ai-assistant", "description": "You are an AI assistant development expert specializing in creating intelligent conversational interfaces, chatbots, and AI-powered applications. Design comprehensive AI assistant solutions with natur", @@ -5023,7 +5131,7 @@ }, { "id": "llm-application-dev-langchain-agent", - "path": "skills/llm-application-dev-langchain-agent", + "path": "skills\\llm-application-dev-langchain-agent", "category": "uncategorized", "name": "llm-application-dev-langchain-agent", "description": "You are an expert LangChain agent developer specializing in production-grade AI systems using LangChain 0.1+ and LangGraph.", @@ -5032,7 +5140,7 @@ }, { "id": "llm-application-dev-prompt-optimize", - "path": "skills/llm-application-dev-prompt-optimize", + "path": "skills\\llm-application-dev-prompt-optimize", "category": "uncategorized", "name": "llm-application-dev-prompt-optimize", "description": "You are an expert prompt engineer specializing in crafting effective prompts for LLMs through advanced techniques including constitutional AI, chain-of-thought reasoning, and model-specific optimizati", @@ -5041,16 +5149,25 @@ }, { "id": "llm-evaluation", - "path": "skills/llm-evaluation", + "path": "skills\\llm-evaluation", "category": "uncategorized", "name": "llm-evaluation", "description": "Implement comprehensive evaluation strategies for LLM applications using automated metrics, human feedback, and benchmarking. Use when testing LLM performance, measuring AI application quality, or ...", "risk": "unknown", "source": "community" }, + { + "id": "logistics-exception-management", + "path": "skills\\logistics-exception-management", + "category": "uncategorized", + "name": "logistics-exception-management", + "description": "Codified expertise for handling freight exceptions, shipment delays, damages, losses, and carrier disputes. Informed by logistics professionals with 15+ years operational experience. Includes escalation protocols, carrier-specific behaviours, claims procedures, and judgment frameworks. Use when handling shipping exceptions, freight claims, delivery issues, or carrier disputes.\n", + "risk": "safe", + "source": "https://github.com/ai-evos/agent-skills" + }, { "id": "loki-mode", - "path": "skills/loki-mode", + "path": "skills\\loki-mode", "category": "uncategorized", "name": "loki-mode", "description": "Multi-agent autonomous startup system for Claude Code. Triggers on \"Loki Mode\". Orchestrates 100+ specialized agents across engineering, QA, DevOps, security, data/ML, business operations,...", @@ -5059,34 +5176,34 @@ }, { "id": "m365-agents-dotnet", - "path": "skills/m365-agents-dotnet", + "path": "skills\\m365-agents-dotnet", "category": "uncategorized", - "name": "M365 Agents Dotnet", - "description": "Build enterprise agents for Microsoft 365, Teams, and Copilot Studio using the Microsoft.Agents SDK with ASP.NET Core hosting, agent routing, and MSAL-based authentication.", + "name": "m365-agents-dotnet", + "description": "Microsoft 365 Agents SDK for .NET. Build multichannel agents for Teams/M365/Copilot Studio with ASP.NET Core hosting, AgentApplication routing, and MSAL-based auth. Triggers: \"Microsoft 365 Agents SDK\", \"Microsoft.Agents\", \"AddAgentApplicationOptions\", \"AgentApplication\", \"AddAgentAspNetAuthentication\", \"Copilot Studio client\", \"IAgentHttpAdapter\".\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "m365-agents-py", - "path": "skills/m365-agents-py", + "path": "skills\\m365-agents-py", "category": "uncategorized", - "name": "M365 Agents Py", - "description": "Build enterprise agents for Microsoft 365, Teams, and Copilot Studio using the Microsoft Agents SDK with aiohttp hosting, AgentApplication routing, streaming responses, and MSAL-based authentication.", + "name": "m365-agents-py", + "description": "Microsoft 365 Agents SDK for Python. Build multichannel agents for Teams/M365/Copilot Studio with aiohttp hosting, AgentApplication routing, streaming responses, and MSAL-based auth. Triggers: \"Microsoft 365 Agents SDK\", \"microsoft_agents\", \"AgentApplication\", \"start_agent_process\", \"TurnContext\", \"Copilot Studio client\", \"CloudAdapter\".\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "m365-agents-ts", - "path": "skills/m365-agents-ts", + "path": "skills\\m365-agents-ts", "category": "uncategorized", - "name": "M365 Agents Ts", - "description": "Build enterprise agents for Microsoft 365, Teams, and Copilot Studio using the Microsoft 365 Agents SDK with Express hosting, AgentApplication routing, streaming responses, and Copilot Studio client integrations.", + "name": "m365-agents-ts", + "description": "Microsoft 365 Agents SDK for TypeScript/Node.js. Build multichannel agents for Teams/M365/Copilot Studio with AgentApplication routing, Express hosting, streaming responses, and Copilot Studio client integration. Triggers: \"Microsoft 365 Agents SDK\", \"@microsoft/agents-hosting\", \"AgentApplication\", \"startServer\", \"streamingResponse\", \"Copilot Studio client\", \"@microsoft/agents-copilotstudio-client\".\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "machine-learning-ops-ml-pipeline", - "path": "skills/machine-learning-ops-ml-pipeline", + "path": "skills\\machine-learning-ops-ml-pipeline", "category": "uncategorized", "name": "machine-learning-ops-ml-pipeline", "description": "Design and implement a complete ML pipeline for: $ARGUMENTS", @@ -5095,7 +5212,7 @@ }, { "id": "mailchimp-automation", - "path": "skills/mailchimp-automation", + "path": "skills\\mailchimp-automation", "category": "uncategorized", "name": "mailchimp-automation", "description": "Automate Mailchimp email marketing including campaigns, audiences, subscribers, segments, and analytics via Rube MCP (Composio). Always search tools first for current schemas.", @@ -5104,7 +5221,7 @@ }, { "id": "make-automation", - "path": "skills/make-automation", + "path": "skills\\make-automation", "category": "uncategorized", "name": "make-automation", "description": "Automate Make (Integromat) tasks via Rube MCP (Composio): operations, enums, language and timezone lookups. Always search tools first for current schemas.", @@ -5113,7 +5230,7 @@ }, { "id": "makepad-skills", - "path": "skills/makepad-skills", + "path": "skills\\makepad-skills", "category": "uncategorized", "name": "makepad-skills", "description": "Makepad UI development skills for Rust apps: setup, patterns, shaders, packaging, and troubleshooting.", @@ -5122,16 +5239,16 @@ }, { "id": "malware-analyst", - "path": "skills/malware-analyst", + "path": "skills\\malware-analyst", "category": "uncategorized", - "name": "Malware Analyst", - "description": "file sample.exe sha256sum sample.exe", + "name": "malware-analyst", + "description": "Expert malware analyst specializing in defensive malware research,\nthreat intelligence, and incident response. Masters sandbox analysis,\nbehavioral analysis, and malware family identification. Handles static/dynamic\nanalysis, unpacking, and IOC extraction. Use PROACTIVELY for malware triage,\nthreat hunting, incident response, or security research.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "manifest", - "path": "skills/manifest", + "path": "skills\\manifest", "category": "uncategorized", "name": "manifest", "description": "Install and configure the Manifest observability plugin for your agents. Use when setting up telemetry, configuring API keys, or troubleshooting the plugin.", @@ -5140,16 +5257,16 @@ }, { "id": "market-sizing-analysis", - "path": "skills/market-sizing-analysis", + "path": "skills\\market-sizing-analysis", "category": "uncategorized", - "name": "Market Sizing Analysis", - "description": "Comprehensive market sizing methodologies for calculating Total Addressable Market (TAM), Serviceable Available Market (SAM), and Serviceable Obtainable Market (SOM) for startup opportunities.", + "name": "market-sizing-analysis", + "description": "This skill should be used when the user asks to \\\\\\\"calculate TAM\\\\\\\",\n\"determine SAM\", \"estimate SOM\", \"size the market\", \"calculate market\nopportunity\", \"what's the total addressable market\", or requests market sizing\nanalysis for a startup or business opportunity.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "marketing-ideas", - "path": "skills/marketing-ideas", + "path": "skills\\marketing-ideas", "category": "uncategorized", "name": "marketing-ideas", "description": "Provide proven marketing strategies and growth ideas for SaaS and software products, prioritized using a marketing feasibility scoring system.", @@ -5158,7 +5275,7 @@ }, { "id": "marketing-psychology", - "path": "skills/marketing-psychology", + "path": "skills\\marketing-psychology", "category": "uncategorized", "name": "marketing-psychology", "description": "Apply behavioral science and mental models to marketing decisions, prioritized using a psychological leverage and feasibility scoring system.", @@ -5167,7 +5284,7 @@ }, { "id": "mcp-builder", - "path": "skills/mcp-builder", + "path": "skills\\mcp-builder", "category": "uncategorized", "name": "mcp-builder", "description": "Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate exte...", @@ -5176,7 +5293,7 @@ }, { "id": "mcp-builder-ms", - "path": "skills/mcp-builder-ms", + "path": "skills\\mcp-builder-ms", "category": "uncategorized", "name": "mcp-builder-ms", "description": "Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate exte...", @@ -5185,7 +5302,7 @@ }, { "id": "memory-forensics", - "path": "skills/memory-forensics", + "path": "skills\\memory-forensics", "category": "uncategorized", "name": "memory-forensics", "description": "Master memory forensics techniques including memory acquisition, process analysis, and artifact extraction using Volatility and related tools. Use when analyzing memory dumps, investigating inciden...", @@ -5194,7 +5311,7 @@ }, { "id": "memory-safety-patterns", - "path": "skills/memory-safety-patterns", + "path": "skills\\memory-safety-patterns", "category": "uncategorized", "name": "memory-safety-patterns", "description": "Implement memory-safe programming with RAII, ownership, smart pointers, and resource management across Rust, C++, and C. Use when writing safe systems code, managing resources, or preventing memory...", @@ -5203,7 +5320,7 @@ }, { "id": "memory-systems", - "path": "skills/memory-systems", + "path": "skills\\memory-systems", "category": "uncategorized", "name": "memory-systems", "description": "Design short-term, long-term, and graph-based memory architectures", @@ -5212,16 +5329,16 @@ }, { "id": "mermaid-expert", - "path": "skills/mermaid-expert", + "path": "skills\\mermaid-expert", "category": "uncategorized", - "name": "Mermaid Expert", - "description": "- Working on mermaid expert tasks or workflows - Needing guidance, best practices, or checklists for mermaid expert", + "name": "mermaid-expert", + "description": "Create Mermaid diagrams for flowcharts, sequences, ERDs, and\narchitectures. Masters syntax for all diagram types and styling. Use\nPROACTIVELY for visual documentation, system diagrams, or process flows.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "metasploit-framework", - "path": "skills/metasploit-framework", + "path": "skills\\metasploit-framework", "category": "uncategorized", "name": "metasploit-framework", "description": "This skill should be used when the user asks to \"use Metasploit for penetration testing\", \"exploit vulnerabilities with msfconsole\", \"create payloads with msfvenom\", \"perform post-exp...", @@ -5230,7 +5347,7 @@ }, { "id": "micro-saas-launcher", - "path": "skills/micro-saas-launcher", + "path": "skills\\micro-saas-launcher", "category": "uncategorized", "name": "micro-saas-launcher", "description": "Expert in launching small, focused SaaS products fast - the indie hacker approach to building profitable software. Covers idea validation, MVP development, pricing, launch strategies, and growing t...", @@ -5239,7 +5356,7 @@ }, { "id": "microservices-patterns", - "path": "skills/microservices-patterns", + "path": "skills\\microservices-patterns", "category": "uncategorized", "name": "microservices-patterns", "description": "Design microservices architectures with service boundaries, event-driven communication, and resilience patterns. Use when building distributed systems, decomposing monoliths, or implementing micros...", @@ -5248,16 +5365,16 @@ }, { "id": "microsoft-azure-webjobs-extensions-authentication-events-dotnet", - "path": "skills/microsoft-azure-webjobs-extensions-authentication-events-dotnet", + "path": "skills\\microsoft-azure-webjobs-extensions-authentication-events-dotnet", "category": "uncategorized", - "name": "Microsoft Azure Webjobs Extensions Authentication Events Dotnet", - "description": "Azure Functions extension for handling Microsoft Entra ID custom authentication events.", + "name": "microsoft-azure-webjobs-extensions-authentication-events-dotnet", + "description": "Microsoft Entra Authentication Events SDK for .NET. Azure Functions triggers for custom authentication extensions. Use for token enrichment, custom claims, attribute collection, and OTP customization in Entra ID. Triggers: \"Authentication Events\", \"WebJobsAuthenticationEventsTrigger\", \"OnTokenIssuanceStart\", \"OnAttributeCollectionStart\", \"custom claims\", \"token enrichment\", \"Entra custom extension\", \"authentication extension\".\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "microsoft-teams-automation", - "path": "skills/microsoft-teams-automation", + "path": "skills\\microsoft-teams-automation", "category": "uncategorized", "name": "microsoft-teams-automation", "description": "Automate Microsoft Teams tasks via Rube MCP (Composio): send messages, manage channels, create meetings, handle chats, and search messages. Always search tools first for current schemas.", @@ -5266,16 +5383,16 @@ }, { "id": "minecraft-bukkit-pro", - "path": "skills/minecraft-bukkit-pro", + "path": "skills\\minecraft-bukkit-pro", "category": "uncategorized", - "name": "Minecraft Bukkit Pro", - "description": "- Working on minecraft bukkit pro tasks or workflows - Needing guidance, best practices, or checklists for minecraft bukkit pro", + "name": "minecraft-bukkit-pro", + "description": "Master Minecraft server plugin development with Bukkit, Spigot, and\nPaper APIs. Specializes in event-driven architecture, command systems, world\nmanipulation, player management, and performance optimization. Use PROACTIVELY\nfor plugin architecture, gameplay mechanics, server-side features, or\ncross-version compatibility.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "miro-automation", - "path": "skills/miro-automation", + "path": "skills\\miro-automation", "category": "uncategorized", "name": "miro-automation", "description": "Automate Miro tasks via Rube MCP (Composio): boards, items, sticky notes, frames, sharing, connectors. Always search tools first for current schemas.", @@ -5284,7 +5401,7 @@ }, { "id": "mixpanel-automation", - "path": "skills/mixpanel-automation", + "path": "skills\\mixpanel-automation", "category": "uncategorized", "name": "mixpanel-automation", "description": "Automate Mixpanel tasks via Rube MCP (Composio): events, segmentation, funnels, cohorts, user profiles, JQL queries. Always search tools first for current schemas.", @@ -5293,16 +5410,16 @@ }, { "id": "ml-engineer", - "path": "skills/ml-engineer", + "path": "skills\\ml-engineer", "category": "uncategorized", - "name": "Ml Engineer", - "description": "- Working on ml engineer tasks or workflows - Needing guidance, best practices, or checklists for ml engineer", + "name": "ml-engineer", + "description": "Build production ML systems with PyTorch 2.x, TensorFlow, and\nmodern ML frameworks. Implements model serving, feature engineering, A/B\ntesting, and monitoring. Use PROACTIVELY for ML model deployment, inference\noptimization, or production ML infrastructure.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "ml-pipeline-workflow", - "path": "skills/ml-pipeline-workflow", + "path": "skills\\ml-pipeline-workflow", "category": "uncategorized", "name": "ml-pipeline-workflow", "description": "Build end-to-end MLOps pipelines from data preparation through model training, validation, and production deployment. Use when creating ML pipelines, implementing MLOps practices, or automating mod...", @@ -5311,52 +5428,52 @@ }, { "id": "mlops-engineer", - "path": "skills/mlops-engineer", + "path": "skills\\mlops-engineer", "category": "uncategorized", - "name": "Mlops Engineer", - "description": "- Working on mlops engineer tasks or workflows - Needing guidance, best practices, or checklists for mlops engineer", + "name": "mlops-engineer", + "description": "Build comprehensive ML pipelines, experiment tracking, and model\nregistries with MLflow, Kubeflow, and modern MLOps tools. Implements automated\ntraining, deployment, and monitoring across cloud platforms. Use PROACTIVELY\nfor ML infrastructure, experiment management, or pipeline automation.\n", "risk": "unknown", - "source": "unknown" - }, - { - "id": "mobile-developer", - "path": "skills/mobile-developer", - "category": "uncategorized", - "name": "Mobile Developer", - "description": "- Working on mobile developer tasks or workflows - Needing guidance, best practices, or checklists for mobile developer", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "mobile-security-coder", - "path": "skills/mobile-security-coder", - "category": "uncategorized", - "name": "Mobile Security Coder", - "description": "- Working on mobile security coder tasks or workflows - Needing guidance, best practices, or checklists for mobile security coder", - "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "mobile-design", - "path": "skills/mobile-design", + "path": "skills\\mobile-design", "category": "uncategorized", "name": "mobile-design", "description": "Mobile-first design and engineering doctrine for iOS and Android apps. Covers touch interaction, performance, platform conventions, offline behavior, and mobile-specific decision-making. Teaches pr...", "risk": "unknown", "source": "community" }, + { + "id": "mobile-developer", + "path": "skills\\mobile-developer", + "category": "uncategorized", + "name": "mobile-developer", + "description": "Develop React Native, Flutter, or native mobile apps with modern\narchitecture patterns. Masters cross-platform development, native\nintegrations, offline sync, and app store optimization. Use PROACTIVELY for\nmobile features, cross-platform code, or app optimization.\n", + "risk": "unknown", + "source": "community" + }, { "id": "mobile-games", - "path": "skills/game-development/mobile-games", + "path": "skills\\game-development\\mobile-games", "category": "game-development", "name": "mobile-games", "description": "Mobile game development principles. Touch input, battery, performance, app stores.", "risk": "unknown", "source": "community" }, + { + "id": "mobile-security-coder", + "path": "skills\\mobile-security-coder", + "category": "uncategorized", + "name": "mobile-security-coder", + "description": "Expert in secure mobile coding practices specializing in input\nvalidation, WebView security, and mobile-specific security patterns. Use\nPROACTIVELY for mobile security implementations or mobile security code\nreviews.\n", + "risk": "unknown", + "source": "community" + }, { "id": "modern-javascript-patterns", - "path": "skills/modern-javascript-patterns", + "path": "skills\\modern-javascript-patterns", "category": "uncategorized", "name": "modern-javascript-patterns", "description": "Master ES6+ features including async/await, destructuring, spread operators, arrow functions, promises, modules, iterators, generators, and functional programming patterns for writing clean, effici...", @@ -5365,7 +5482,7 @@ }, { "id": "monday-automation", - "path": "skills/monday-automation", + "path": "skills\\monday-automation", "category": "uncategorized", "name": "monday-automation", "description": "Automate Monday.com work management including boards, items, columns, groups, subitems, and updates via Rube MCP (Composio). Always search tools first for current schemas.", @@ -5374,7 +5491,7 @@ }, { "id": "monorepo-architect", - "path": "skills/monorepo-architect", + "path": "skills\\monorepo-architect", "category": "uncategorized", "name": "monorepo-architect", "description": "Expert in monorepo architecture, build systems, and dependency management at scale. Masters Nx, Turborepo, Bazel, and Lerna for efficient multi-project development. Use PROACTIVELY for monorepo setup,", @@ -5383,7 +5500,7 @@ }, { "id": "monorepo-management", - "path": "skills/monorepo-management", + "path": "skills\\monorepo-management", "category": "uncategorized", "name": "monorepo-management", "description": "Master monorepo management with Turborepo, Nx, and pnpm workspaces to build efficient, scalable multi-package repositories with optimized builds and dependency management. Use when setting up monor...", @@ -5392,7 +5509,7 @@ }, { "id": "moodle-external-api-development", - "path": "skills/moodle-external-api-development", + "path": "skills\\moodle-external-api-development", "category": "uncategorized", "name": "moodle-external-api-development", "description": "Create custom external web service APIs for Moodle LMS. Use when implementing web services for course management, user tracking, quiz operations, or custom plugin functionality. Covers parameter va...", @@ -5401,7 +5518,7 @@ }, { "id": "mtls-configuration", - "path": "skills/mtls-configuration", + "path": "skills\\mtls-configuration", "category": "uncategorized", "name": "mtls-configuration", "description": "Configure mutual TLS (mTLS) for zero-trust service-to-service communication. Use when implementing zero-trust networking, certificate management, or securing internal service communication.", @@ -5410,7 +5527,7 @@ }, { "id": "multi-agent-brainstorming", - "path": "skills/multi-agent-brainstorming", + "path": "skills\\multi-agent-brainstorming", "category": "uncategorized", "name": "multi-agent-brainstorming", "description": "Use this skill when a design or idea requires higher confidence, risk reduction, or formal review. This skill orchestrates a structured, sequential multi-agent design review where each agent has a strict, non-overlapping role. It prevents blind spots, false confidence, and premature convergence.", @@ -5419,7 +5536,7 @@ }, { "id": "multi-agent-patterns", - "path": "skills/multi-agent-patterns", + "path": "skills\\multi-agent-patterns", "category": "uncategorized", "name": "multi-agent-patterns", "description": "Master orchestrator, peer-to-peer, and hierarchical multi-agent architectures", @@ -5428,7 +5545,7 @@ }, { "id": "multi-cloud-architecture", - "path": "skills/multi-cloud-architecture", + "path": "skills\\multi-cloud-architecture", "category": "uncategorized", "name": "multi-cloud-architecture", "description": "Design multi-cloud architectures using a decision framework to select and integrate services across AWS, Azure, and GCP. Use when building multi-cloud systems, avoiding vendor lock-in, or leveragin...", @@ -5437,7 +5554,7 @@ }, { "id": "multi-platform-apps-multi-platform", - "path": "skills/multi-platform-apps-multi-platform", + "path": "skills\\multi-platform-apps-multi-platform", "category": "uncategorized", "name": "multi-platform-apps-multi-platform", "description": "Build and deploy the same feature consistently across web, mobile, and desktop platforms using API-first architecture and parallel implementation strategies.", @@ -5446,7 +5563,7 @@ }, { "id": "multiplayer", - "path": "skills/game-development/multiplayer", + "path": "skills\\game-development\\multiplayer", "category": "game-development", "name": "multiplayer", "description": "Multiplayer game development principles. Architecture, networking, synchronization.", @@ -5455,7 +5572,7 @@ }, { "id": "n8n-code-python", - "path": "skills/n8n-code-python", + "path": "skills\\n8n-code-python", "category": "uncategorized", "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.", @@ -5464,7 +5581,7 @@ }, { "id": "n8n-mcp-tools-expert", - "path": "skills/n8n-mcp-tools-expert", + "path": "skills\\n8n-mcp-tools-expert", "category": "uncategorized", "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 sele...", @@ -5473,7 +5590,7 @@ }, { "id": "n8n-node-configuration", - "path": "skills/n8n-node-configuration", + "path": "skills\\n8n-node-configuration", "category": "uncategorized", "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 commo...", @@ -5482,7 +5599,7 @@ }, { "id": "nanobanana-ppt-skills", - "path": "skills/nanobanana-ppt-skills", + "path": "skills\\nanobanana-ppt-skills", "category": "uncategorized", "name": "nanobanana-ppt-skills", "description": "AI-powered PPT generation with document analysis and styled images", @@ -5491,7 +5608,7 @@ }, { "id": "neon-postgres", - "path": "skills/neon-postgres", + "path": "skills\\neon-postgres", "category": "uncategorized", "name": "neon-postgres", "description": "Expert patterns for Neon serverless Postgres, branching, connection pooling, and Prisma/Drizzle integration Use when: neon database, serverless postgres, database branching, neon postgres, postgres...", @@ -5500,7 +5617,7 @@ }, { "id": "nerdzao-elite", - "path": "skills/nerdzao-elite", + "path": "skills\\nerdzao-elite", "category": "uncategorized", "name": "nerdzao-elite", "description": "Senior Elite Software Engineer (15+) and Senior Product Designer. Full workflow with planning, architecture, TDD, clean code, and pixel-perfect UX validation.", @@ -5509,7 +5626,7 @@ }, { "id": "nerdzao-elite-gemini-high", - "path": "skills/nerdzao-elite-gemini-high", + "path": "skills\\nerdzao-elite-gemini-high", "category": "uncategorized", "name": "nerdzao-elite-gemini-high", "description": "Modo Elite Coder + UX Pixel-Perfect otimizado especificamente para Gemini 3.1 Pro High. Workflow completo com foco em qualidade m\u00e1xima e efici\u00eancia de tokens.", @@ -5518,34 +5635,34 @@ }, { "id": "nestjs-expert", - "path": "skills/nestjs-expert", + "path": "skills\\nestjs-expert", "category": "uncategorized", "name": "nestjs-expert", "description": "Nest.js framework expert specializing in module architecture, dependency injection, middleware, guards, interceptors, testing with Jest/Supertest, TypeORM/Mongoose integration, and Passport.js auth...", "risk": "unknown", "source": "community" }, - { - "id": "network-engineer", - "path": "skills/network-engineer", - "category": "uncategorized", - "name": "Network Engineer", - "description": "- Working on network engineer tasks or workflows - Needing guidance, best practices, or checklists for network engineer", - "risk": "unknown", - "source": "unknown" - }, { "id": "network-101", - "path": "skills/network-101", + "path": "skills\\network-101", "category": "uncategorized", "name": "network-101", "description": "This skill should be used when the user asks to \"set up a web server\", \"configure HTTP or HTTPS\", \"perform SNMP enumeration\", \"configure SMB shares\", \"test network services\", or ne...", "risk": "unknown", "source": "community" }, + { + "id": "network-engineer", + "path": "skills\\network-engineer", + "category": "uncategorized", + "name": "network-engineer", + "description": "Expert network engineer specializing in modern cloud networking,\nsecurity architectures, and performance optimization. Masters multi-cloud\nconnectivity, service mesh, zero-trust networking, SSL/TLS, global load\nbalancing, and advanced troubleshooting. Handles CDN optimization, network\nautomation, and compliance. Use PROACTIVELY for network design, connectivity\nissues, or performance optimization.\n", + "risk": "unknown", + "source": "community" + }, { "id": "nextjs-app-router-patterns", - "path": "skills/nextjs-app-router-patterns", + "path": "skills\\nextjs-app-router-patterns", "category": "uncategorized", "name": "nextjs-app-router-patterns", "description": "Master Next.js 14+ App Router with Server Components, streaming, parallel routes, and advanced data fetching. Use when building Next.js applications, implementing SSR/SSG, or optimizing React Serve...", @@ -5554,7 +5671,7 @@ }, { "id": "nextjs-best-practices", - "path": "skills/nextjs-best-practices", + "path": "skills\\nextjs-best-practices", "category": "uncategorized", "name": "nextjs-best-practices", "description": "Next.js App Router principles. Server Components, data fetching, routing patterns.", @@ -5563,7 +5680,7 @@ }, { "id": "nextjs-supabase-auth", - "path": "skills/nextjs-supabase-auth", + "path": "skills\\nextjs-supabase-auth", "category": "uncategorized", "name": "nextjs-supabase-auth", "description": "Expert integration of Supabase Auth with Next.js App Router Use when: supabase auth next, authentication next.js, login supabase, auth middleware, protected route.", @@ -5572,7 +5689,7 @@ }, { "id": "nft-standards", - "path": "skills/nft-standards", + "path": "skills\\nft-standards", "category": "uncategorized", "name": "nft-standards", "description": "Implement NFT standards (ERC-721, ERC-1155) with proper metadata handling, minting strategies, and marketplace integration. Use when creating NFT contracts, building NFT marketplaces, or implementi...", @@ -5581,7 +5698,7 @@ }, { "id": "nodejs-backend-patterns", - "path": "skills/nodejs-backend-patterns", + "path": "skills\\nodejs-backend-patterns", "category": "uncategorized", "name": "nodejs-backend-patterns", "description": "Build production-ready Node.js backend services with Express/Fastify, implementing middleware patterns, error handling, authentication, database integration, and API design best practices. Use when...", @@ -5590,7 +5707,7 @@ }, { "id": "nodejs-best-practices", - "path": "skills/nodejs-best-practices", + "path": "skills\\nodejs-best-practices", "category": "uncategorized", "name": "nodejs-best-practices", "description": "Node.js development principles and decision-making. Framework selection, async patterns, security, and architecture. Teaches thinking, not copying.", @@ -5599,7 +5716,7 @@ }, { "id": "nosql-expert", - "path": "skills/nosql-expert", + "path": "skills\\nosql-expert", "category": "uncategorized", "name": "nosql-expert", "description": "Expert guidance for distributed NoSQL databases (Cassandra, DynamoDB). Focuses on mental models, query-first modeling, single-table design, and avoiding hot partitions in high-scale systems.", @@ -5608,7 +5725,7 @@ }, { "id": "notebooklm", - "path": "skills/notebooklm", + "path": "skills\\notebooklm", "category": "uncategorized", "name": "notebooklm", "description": "Use this skill to query your Google NotebookLM notebooks directly from Claude Code for source-grounded, citation-backed answers from Gemini. Browser automation, library management, persistent auth....", @@ -5617,7 +5734,7 @@ }, { "id": "notion-automation", - "path": "skills/notion-automation", + "path": "skills\\notion-automation", "category": "uncategorized", "name": "notion-automation", "description": "Automate Notion tasks via Rube MCP (Composio): pages, databases, blocks, comments, users. Always search tools first for current schemas.", @@ -5626,7 +5743,7 @@ }, { "id": "notion-template-business", - "path": "skills/notion-template-business", + "path": "skills\\notion-template-business", "category": "uncategorized", "name": "notion-template-business", "description": "Expert in building and selling Notion templates as a business - not just making templates, but building a sustainable digital product business. Covers template design, pricing, marketplaces, market...", @@ -5635,7 +5752,7 @@ }, { "id": "nx-workspace-patterns", - "path": "skills/nx-workspace-patterns", + "path": "skills\\nx-workspace-patterns", "category": "uncategorized", "name": "nx-workspace-patterns", "description": "Configure and optimize Nx monorepo workspaces. Use when setting up Nx, configuring project boundaries, optimizing build caching, or implementing affected commands.", @@ -5644,16 +5761,16 @@ }, { "id": "observability-engineer", - "path": "skills/observability-engineer", + "path": "skills\\observability-engineer", "category": "uncategorized", - "name": "Observability Engineer", - "description": "You are an observability engineer specializing in production-grade monitoring, logging, tracing, and reliability systems for enterprise-scale applications.", + "name": "observability-engineer", + "description": "Build production-ready monitoring, logging, and tracing systems.\nImplements comprehensive observability strategies, SLI/SLO management, and\nincident response workflows. Use PROACTIVELY for monitoring infrastructure,\nperformance optimization, or production reliability.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "observability-monitoring-monitor-setup", - "path": "skills/observability-monitoring-monitor-setup", + "path": "skills\\observability-monitoring-monitor-setup", "category": "uncategorized", "name": "observability-monitoring-monitor-setup", "description": "You are a monitoring and observability expert specializing in implementing comprehensive monitoring solutions. Set up metrics collection, distributed tracing, log aggregation, and create insightful da", @@ -5662,7 +5779,7 @@ }, { "id": "observability-monitoring-slo-implement", - "path": "skills/observability-monitoring-slo-implement", + "path": "skills\\observability-monitoring-slo-implement", "category": "uncategorized", "name": "observability-monitoring-slo-implement", "description": "You are an SLO (Service Level Objective) expert specializing in implementing reliability standards and error budget-based practices. Design SLO frameworks, define SLIs, and build monitoring that ba...", @@ -5671,7 +5788,7 @@ }, { "id": "observe-whatsapp", - "path": "skills/observe-whatsapp", + "path": "skills\\observe-whatsapp", "category": "uncategorized", "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 f...", @@ -5680,7 +5797,7 @@ }, { "id": "obsidian-clipper-template-creator", - "path": "skills/obsidian-clipper-template-creator", + "path": "skills\\obsidian-clipper-template-creator", "category": "uncategorized", "name": "obsidian-clipper-template-creator", "description": "Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.", @@ -5689,7 +5806,7 @@ }, { "id": "office-productivity", - "path": "skills/office-productivity", + "path": "skills\\office-productivity", "category": "uncategorized", "name": "office-productivity", "description": "Office productivity workflow covering document creation, spreadsheet automation, presentation generation, and integration with LibreOffice and Microsoft Office formats.", @@ -5698,7 +5815,7 @@ }, { "id": "on-call-handoff-patterns", - "path": "skills/on-call-handoff-patterns", + "path": "skills\\on-call-handoff-patterns", "category": "uncategorized", "name": "on-call-handoff-patterns", "description": "Master on-call shift handoffs with context transfer, escalation procedures, and documentation. Use when transitioning on-call responsibilities, documenting shift summaries, or improving on-call pro...", @@ -5707,7 +5824,7 @@ }, { "id": "onboarding-cro", - "path": "skills/onboarding-cro", + "path": "skills\\onboarding-cro", "category": "uncategorized", "name": "onboarding-cro", "description": "When the user wants to optimize post-signup onboarding, user activation, first-run experience, or time-to-value. Also use when the user mentions \"onboarding flow,\" \"activation rate,\" \"u...", @@ -5716,7 +5833,7 @@ }, { "id": "one-drive-automation", - "path": "skills/one-drive-automation", + "path": "skills\\one-drive-automation", "category": "uncategorized", "name": "one-drive-automation", "description": "Automate OneDrive file management, search, uploads, downloads, sharing, permissions, and folder operations via Rube MCP (Composio). Always search tools first for current schemas.", @@ -5725,7 +5842,7 @@ }, { "id": "openapi-spec-generation", - "path": "skills/openapi-spec-generation", + "path": "skills\\openapi-spec-generation", "category": "uncategorized", "name": "openapi-spec-generation", "description": "Generate and maintain OpenAPI 3.1 specifications from code, design-first specs, and validation patterns. Use when creating API documentation, generating SDKs, or ensuring API contract compliance.", @@ -5734,7 +5851,7 @@ }, { "id": "os-scripting", - "path": "skills/os-scripting", + "path": "skills\\os-scripting", "category": "uncategorized", "name": "os-scripting", "description": "Operating system and shell scripting troubleshooting workflow for Linux, macOS, and Windows. Covers bash scripting, system administration, debugging, and automation.", @@ -5743,7 +5860,7 @@ }, { "id": "oss-hunter", - "path": "skills/oss-hunter", + "path": "skills\\oss-hunter", "category": "uncategorized", "name": "oss-hunter", "description": "Automatically hunt for high-impact OSS contribution opportunities in trending repositories.", @@ -5752,7 +5869,7 @@ }, { "id": "outlook-automation", - "path": "skills/outlook-automation", + "path": "skills\\outlook-automation", "category": "uncategorized", "name": "outlook-automation", "description": "Automate Outlook tasks via Rube MCP (Composio): emails, calendar, contacts, folders, attachments. Always search tools first for current schemas.", @@ -5761,7 +5878,7 @@ }, { "id": "outlook-calendar-automation", - "path": "skills/outlook-calendar-automation", + "path": "skills\\outlook-calendar-automation", "category": "uncategorized", "name": "outlook-calendar-automation", "description": "Automate Outlook Calendar tasks via Rube MCP (Composio): create events, manage attendees, find meeting times, and handle invitations. Always search tools first for current schemas.", @@ -5770,16 +5887,16 @@ }, { "id": "page-cro", - "path": "skills/page-cro", + "path": "skills\\page-cro", "category": "uncategorized", - "name": "Page Cro", - "description": "You are an expert in **page-level conversion optimization**. Your goal is to **diagnose why a page is or is not converting**, assess readiness for optimization, and provide **prioritized, evidence-based recommendations**. You do **not** guarantee con", + "name": "page-cro", + "description": "Analyze and optimize individual pages for conversion performance. Use when the user wants to improve conversion rates, diagnose why a page is underperforming, or increase the effectiveness of marketing pages (homepage, landing pages, pricing, feature pages, or blog posts). This skill focuses on diagnosis, prioritization, and testable recommendations\u2014 not blind optimization.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "pagerduty-automation", - "path": "skills/pagerduty-automation", + "path": "skills\\pagerduty-automation", "category": "uncategorized", "name": "pagerduty-automation", "description": "Automate PagerDuty tasks via Rube MCP (Composio): manage incidents, services, schedules, escalation policies, and on-call rotations. Always search tools first for current schemas.", @@ -5788,7 +5905,7 @@ }, { "id": "paid-ads", - "path": "skills/paid-ads", + "path": "skills\\paid-ads", "category": "uncategorized", "name": "paid-ads", "description": "When the user wants help with paid advertising campaigns on Google Ads, Meta (Facebook/Instagram), LinkedIn, Twitter/X, or other ad platforms. Also use when the user mentions 'PPC,' 'paid media,' '...", @@ -5797,7 +5914,7 @@ }, { "id": "parallel-agents", - "path": "skills/parallel-agents", + "path": "skills\\parallel-agents", "category": "uncategorized", "name": "parallel-agents", "description": "Multi-agent orchestration patterns. Use when multiple independent tasks can run with different domain expertise or when comprehensive analysis requires multiple perspectives.", @@ -5806,16 +5923,16 @@ }, { "id": "payment-integration", - "path": "skills/payment-integration", + "path": "skills\\payment-integration", "category": "uncategorized", - "name": "Payment Integration", - "description": "- Working on payment integration tasks or workflows - Needing guidance, best practices, or checklists for payment integration", + "name": "payment-integration", + "description": "Integrate Stripe, PayPal, and payment processors. Handles checkout\nflows, subscriptions, webhooks, and PCI compliance. Use PROACTIVELY when\nimplementing payments, billing, or subscription features.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "paypal-integration", - "path": "skills/paypal-integration", + "path": "skills\\paypal-integration", "category": "uncategorized", "name": "paypal-integration", "description": "Integrate PayPal payment processing with support for express checkout, subscriptions, and refund management. Use when implementing PayPal payments, processing online transactions, or building e-com...", @@ -5824,7 +5941,7 @@ }, { "id": "paywall-upgrade-cro", - "path": "skills/paywall-upgrade-cro", + "path": "skills\\paywall-upgrade-cro", "category": "uncategorized", "name": "paywall-upgrade-cro", "description": "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,\" \"upgrade screen,\" \"upgrade modal,...", @@ -5833,7 +5950,7 @@ }, { "id": "pc-games", - "path": "skills/game-development/pc-games", + "path": "skills\\game-development\\pc-games", "category": "game-development", "name": "pc-games", "description": "PC and console game development principles. Engine selection, platform features, optimization strategies.", @@ -5842,7 +5959,7 @@ }, { "id": "pci-compliance", - "path": "skills/pci-compliance", + "path": "skills\\pci-compliance", "category": "uncategorized", "name": "pci-compliance", "description": "Implement PCI DSS compliance requirements for secure handling of payment card data and payment systems. Use when securing payment processing, achieving PCI compliance, or implementing payment card ...", @@ -5851,7 +5968,7 @@ }, { "id": "pdf-official", - "path": "skills/pdf-official", + "path": "skills\\pdf-official", "category": "uncategorized", "name": "pdf-official", "description": "Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms. When Claude needs to fill in a PDF form or programmaticall...", @@ -5860,7 +5977,7 @@ }, { "id": "pentest-checklist", - "path": "skills/pentest-checklist", + "path": "skills\\pentest-checklist", "category": "uncategorized", "name": "pentest-checklist", "description": "This skill should be used when the user asks to \"plan a penetration test\", \"create a security assessment checklist\", \"prepare for penetration testing\", \"define pentest scope\", \"foll...", @@ -5869,7 +5986,7 @@ }, { "id": "pentest-commands", - "path": "skills/pentest-commands", + "path": "skills\\pentest-commands", "category": "uncategorized", "name": "pentest-commands", "description": "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\", \"scan web vulnerabilities ...", @@ -5878,7 +5995,7 @@ }, { "id": "performance-engineer", - "path": "skills/performance-engineer", + "path": "skills\\performance-engineer", "category": "uncategorized", "name": "performance-engineer", "description": "Expert performance engineer specializing in modern observability, application optimization, and scalable system performance. Masters OpenTelemetry, distributed tracing, load testing, multi-tier caching, Core Web Vitals, and performance monitoring. Handles end-to-end optimization, real user monitoring, and scalability patterns. Use PROACTIVELY for performance optimization, observability, or scalability challenges.", @@ -5887,7 +6004,7 @@ }, { "id": "performance-profiling", - "path": "skills/performance-profiling", + "path": "skills\\performance-profiling", "category": "uncategorized", "name": "performance-profiling", "description": "Performance profiling principles. Measurement, analysis, and optimization techniques.", @@ -5896,7 +6013,7 @@ }, { "id": "performance-testing-review-ai-review", - "path": "skills/performance-testing-review-ai-review", + "path": "skills\\performance-testing-review-ai-review", "category": "uncategorized", "name": "performance-testing-review-ai-review", "description": "You are an expert AI-powered code review specialist combining automated static analysis, intelligent pattern recognition, and modern DevOps practices. Leverage AI tools (GitHub Copilot, Qodo, GPT-5, C", @@ -5905,7 +6022,7 @@ }, { "id": "performance-testing-review-multi-agent-review", - "path": "skills/performance-testing-review-multi-agent-review", + "path": "skills\\performance-testing-review-multi-agent-review", "category": "uncategorized", "name": "performance-testing-review-multi-agent-review", "description": "Use when working with performance testing review multi agent review", @@ -5914,7 +6031,7 @@ }, { "id": "personal-tool-builder", - "path": "skills/personal-tool-builder", + "path": "skills\\personal-tool-builder", "category": "uncategorized", "name": "personal-tool-builder", "description": "Expert in building custom tools that solve your own problems first. The best products often start as personal tools - scratch your own itch, build for yourself, then discover others have the same i...", @@ -5923,16 +6040,16 @@ }, { "id": "php-pro", - "path": "skills/php-pro", + "path": "skills\\php-pro", "category": "uncategorized", - "name": "Php Pro", - "description": "- Working on php pro tasks or workflows - Needing guidance, best practices, or checklists for php pro", + "name": "php-pro", + "description": "Write idiomatic PHP code with generators, iterators, SPL data\nstructures, and modern OOP features. Use PROACTIVELY for high-performance PHP\napplications.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "pipedrive-automation", - "path": "skills/pipedrive-automation", + "path": "skills\\pipedrive-automation", "category": "uncategorized", "name": "pipedrive-automation", "description": "Automate Pipedrive CRM operations including deals, contacts, organizations, activities, notes, and pipeline management via Rube MCP (Composio). Always search tools first for current schemas.", @@ -5941,7 +6058,7 @@ }, { "id": "plaid-fintech", - "path": "skills/plaid-fintech", + "path": "skills\\plaid-fintech", "category": "uncategorized", "name": "plaid-fintech", "description": "Expert patterns for Plaid API integration including Link token flows, transactions sync, identity verification, Auth for ACH, balance checks, webhook handling, and fintech compliance best practices...", @@ -5950,7 +6067,7 @@ }, { "id": "plan-writing", - "path": "skills/plan-writing", + "path": "skills\\plan-writing", "category": "uncategorized", "name": "plan-writing", "description": "Structured task planning with clear breakdowns, dependencies, and verification criteria. Use when implementing features, refactoring, or any multi-step work.", @@ -5959,7 +6076,7 @@ }, { "id": "planning-with-files", - "path": "skills/planning-with-files", + "path": "skills\\planning-with-files", "category": "uncategorized", "name": "planning-with-files", "description": "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, research projects, or any task requirin...", @@ -5968,7 +6085,7 @@ }, { "id": "playwright-skill", - "path": "skills/playwright-skill", + "path": "skills\\playwright-skill", "category": "uncategorized", "name": "playwright-skill", "description": "Complete browser automation with Playwright. Auto-detects dev servers, writes clean test scripts to /tmp. Test pages, fill forms, take screenshots, check responsive design, validate UX, test login ...", @@ -5977,7 +6094,7 @@ }, { "id": "podcast-generation", - "path": "skills/podcast-generation", + "path": "skills\\podcast-generation", "category": "uncategorized", "name": "podcast-generation", "description": "Generate AI-powered podcast-style audio narratives using Azure OpenAI's GPT Realtime Mini model via WebSocket. Use when building text-to-speech features, audio narrative generation, podcast creatio...", @@ -5986,7 +6103,7 @@ }, { "id": "popup-cro", - "path": "skills/popup-cro", + "path": "skills\\popup-cro", "category": "uncategorized", "name": "popup-cro", "description": "Create and optimize popups, modals, overlays, slide-ins, and banners to increase conversions without harming user experience or brand trust.", @@ -5995,16 +6112,16 @@ }, { "id": "posix-shell-pro", - "path": "skills/posix-shell-pro", + "path": "skills\\posix-shell-pro", "category": "uncategorized", - "name": "Posix Shell Pro", - "description": "- Working on posix shell pro tasks or workflows - Needing guidance, best practices, or checklists for posix shell pro", + "name": "posix-shell-pro", + "description": "Expert in strict POSIX sh scripting for maximum portability across\nUnix-like systems. Specializes in shell scripts that run on any\nPOSIX-compliant shell (dash, ash, sh, bash --posix).\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "postgres-best-practices", - "path": "skills/postgres-best-practices", + "path": "skills\\postgres-best-practices", "category": "uncategorized", "name": "postgres-best-practices", "description": "Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.", @@ -6013,7 +6130,7 @@ }, { "id": "postgresql", - "path": "skills/postgresql", + "path": "skills\\postgresql", "category": "uncategorized", "name": "postgresql", "description": "Design a PostgreSQL-specific schema. Covers best-practices, data types, indexing, constraints, performance patterns, and advanced features", @@ -6022,7 +6139,7 @@ }, { "id": "postgresql-optimization", - "path": "skills/postgresql-optimization", + "path": "skills\\postgresql-optimization", "category": "uncategorized", "name": "postgresql-optimization", "description": "PostgreSQL database optimization workflow for query tuning, indexing strategies, performance analysis, and production database management.", @@ -6031,7 +6148,7 @@ }, { "id": "posthog-automation", - "path": "skills/posthog-automation", + "path": "skills\\posthog-automation", "category": "uncategorized", "name": "posthog-automation", "description": "Automate PostHog tasks via Rube MCP (Composio): events, feature flags, projects, user profiles, annotations. Always search tools first for current schemas.", @@ -6040,7 +6157,7 @@ }, { "id": "postmark-automation", - "path": "skills/postmark-automation", + "path": "skills\\postmark-automation", "category": "uncategorized", "name": "postmark-automation", "description": "Automate Postmark email delivery tasks via Rube MCP (Composio): send templated emails, manage templates, monitor delivery stats and bounces. Always search tools first for current schemas.", @@ -6049,7 +6166,7 @@ }, { "id": "postmortem-writing", - "path": "skills/postmortem-writing", + "path": "skills\\postmortem-writing", "category": "uncategorized", "name": "postmortem-writing", "description": "Write effective blameless postmortems with root cause analysis, timelines, and action items. Use when conducting incident reviews, writing postmortem documents, or improving incident response proce...", @@ -6058,7 +6175,7 @@ }, { "id": "powershell-windows", - "path": "skills/powershell-windows", + "path": "skills\\powershell-windows", "category": "uncategorized", "name": "powershell-windows", "description": "PowerShell Windows patterns. Critical pitfalls, operator syntax, error handling.", @@ -6067,7 +6184,7 @@ }, { "id": "pptx-official", - "path": "skills/pptx-official", + "path": "skills\\pptx-official", "category": "uncategorized", "name": "pptx-official", "description": "Presentation creation, editing, and analysis. When Claude needs to work with presentations (.pptx files) for: (1) Creating new presentations, (2) Modifying or editing content, (3) Working with layo...", @@ -6076,7 +6193,7 @@ }, { "id": "pricing-strategy", - "path": "skills/pricing-strategy", + "path": "skills\\pricing-strategy", "category": "uncategorized", "name": "pricing-strategy", "description": "Design pricing, packaging, and monetization strategies based on value, customer willingness to pay, and growth objectives.", @@ -6085,7 +6202,7 @@ }, { "id": "prisma-expert", - "path": "skills/prisma-expert", + "path": "skills\\prisma-expert", "category": "uncategorized", "name": "prisma-expert", "description": "Prisma ORM expert for schema design, migrations, query optimization, relations modeling, and database operations. Use PROACTIVELY for Prisma schema issues, migration problems, query performance, re...", @@ -6094,7 +6211,7 @@ }, { "id": "privilege-escalation-methods", - "path": "skills/privilege-escalation-methods", + "path": "skills\\privilege-escalation-methods", "category": "uncategorized", "name": "privilege-escalation-methods", "description": "This skill should be used when the user asks to \"escalate privileges\", \"get root access\", \"become administrator\", \"privesc techniques\", \"abuse sudo\", \"exploit SUID binaries\", \"K...", @@ -6103,7 +6220,7 @@ }, { "id": "product-manager-toolkit", - "path": "skills/product-manager-toolkit", + "path": "skills\\product-manager-toolkit", "category": "uncategorized", "name": "product-manager-toolkit", "description": "Comprehensive toolkit for product managers including RICE prioritization, customer interview analysis, PRD templates, discovery frameworks, and go-to-market strategies. Use for feature prioritizati...", @@ -6112,7 +6229,7 @@ }, { "id": "production-code-audit", - "path": "skills/production-code-audit", + "path": "skills\\production-code-audit", "category": "uncategorized", "name": "production-code-audit", "description": "Autonomously deep-scan entire codebase line-by-line, understand architecture and patterns, then systematically transform it to production-grade, corporate-level professional quality with optimizations", @@ -6120,17 +6237,26 @@ "source": "community" }, { - "id": "programmatic-seo", - "path": "skills/programmatic-seo", + "id": "production-scheduling", + "path": "skills\\production-scheduling", "category": "uncategorized", - "name": "Programmatic Seo", - "description": "---", + "name": "production-scheduling", + "description": "Codified expertise for production scheduling, job sequencing, line balancing, changeover optimisation, and bottleneck resolution in discrete and batch manufacturing. Informed by production schedulers with 15+ years experience. Includes TOC/drum-buffer-rope, SMED, OEE analysis, disruption response frameworks, and ERP/MES interaction patterns. Use when scheduling production, resolving bottlenecks, optimising changeovers, responding to disruptions, or balancing manufacturing lines.\n", + "risk": "safe", + "source": "https://github.com/ai-evos/agent-skills" + }, + { + "id": "programmatic-seo", + "path": "skills\\programmatic-seo", + "category": "uncategorized", + "name": "programmatic-seo", + "description": "Design and evaluate programmatic SEO strategies for creating SEO-driven pages at scale using templates and structured data. Use when the user mentions programmatic SEO, pages at scale, template pages, directory pages, location pages, comparison pages, integration pages, or keyword-pattern page generation. This skill focuses on feasibility, strategy, and page system design\u2014not execution unless explicitly requested.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "projection-patterns", - "path": "skills/projection-patterns", + "path": "skills\\projection-patterns", "category": "uncategorized", "name": "projection-patterns", "description": "Build read models and projections from event streams. Use when implementing CQRS read sides, building materialized views, or optimizing query performance in event-sourced systems.", @@ -6139,7 +6265,7 @@ }, { "id": "prometheus-configuration", - "path": "skills/prometheus-configuration", + "path": "skills\\prometheus-configuration", "category": "uncategorized", "name": "prometheus-configuration", "description": "Set up Prometheus for comprehensive metric collection, storage, and monitoring of infrastructure and applications. Use when implementing metrics collection, setting up monitoring infrastructure, or...", @@ -6148,7 +6274,7 @@ }, { "id": "prompt-caching", - "path": "skills/prompt-caching", + "path": "skills\\prompt-caching", "category": "uncategorized", "name": "prompt-caching", "description": "Caching strategies for LLM prompts including Anthropic prompt caching, response caching, and CAG (Cache Augmented Generation) Use when: prompt caching, cache prompt, response cache, cag, cache augm...", @@ -6157,7 +6283,7 @@ }, { "id": "prompt-engineer", - "path": "skills/prompt-engineer", + "path": "skills\\prompt-engineer", "category": "uncategorized", "name": "prompt-engineer", "description": "Transforms user prompts into optimized prompts using frameworks (RTF, RISEN, Chain of Thought, RODES, Chain of Density, RACE, RISE, STAR, SOAP, CLEAR, GROW)", @@ -6166,7 +6292,7 @@ }, { "id": "prompt-engineering", - "path": "skills/prompt-engineering", + "path": "skills\\prompt-engineering", "category": "uncategorized", "name": "prompt-engineering", "description": "Expert guide on prompt engineering patterns, best practices, and optimization techniques. Use when user wants to improve prompts, learn prompting strategies, or debug agent behavior.", @@ -6175,7 +6301,7 @@ }, { "id": "prompt-engineering-patterns", - "path": "skills/prompt-engineering-patterns", + "path": "skills\\prompt-engineering-patterns", "category": "uncategorized", "name": "prompt-engineering-patterns", "description": "Master advanced prompt engineering techniques to maximize LLM performance, reliability, and controllability in production. Use when optimizing prompts, improving LLM outputs, or designing productio...", @@ -6184,7 +6310,7 @@ }, { "id": "prompt-library", - "path": "skills/prompt-library", + "path": "skills\\prompt-library", "category": "uncategorized", "name": "prompt-library", "description": "Curated collection of high-quality prompts for various use cases. Includes role-based prompts, task-specific templates, and prompt refinement techniques. Use when user needs prompt templates, role-...", @@ -6193,7 +6319,7 @@ }, { "id": "protocol-reverse-engineering", - "path": "skills/protocol-reverse-engineering", + "path": "skills\\protocol-reverse-engineering", "category": "uncategorized", "name": "protocol-reverse-engineering", "description": "Master network protocol reverse engineering including packet analysis, protocol dissection, and custom protocol documentation. Use when analyzing network traffic, understanding proprietary protocol...", @@ -6202,7 +6328,7 @@ }, { "id": "pydantic-models-py", - "path": "skills/pydantic-models-py", + "path": "skills\\pydantic-models-py", "category": "uncategorized", "name": "pydantic-models-py", "description": "Create Pydantic models following the multi-model pattern with Base, Create, Update, Response, and InDB variants. Use when defining API request/response schemas, database models, or data validation ...", @@ -6211,25 +6337,16 @@ }, { "id": "pypict-skill", - "path": "skills/pypict-skill", + "path": "skills\\pypict-skill", "category": "uncategorized", "name": "pypict-skill", "description": "Pairwise test generation", "risk": "safe", "source": "https://github.com/omkamal/pypict-claude-skill/blob/main/SKILL.md" }, - { - "id": "python-pro", - "path": "skills/python-pro", - "category": "uncategorized", - "name": "Python Pro", - "description": "You are a Python expert specializing in modern Python 3.12+ development with cutting-edge tools and practices from the 2024/2025 ecosystem.", - "risk": "unknown", - "source": "unknown" - }, { "id": "python-development-python-scaffold", - "path": "skills/python-development-python-scaffold", + "path": "skills\\python-development-python-scaffold", "category": "uncategorized", "name": "python-development-python-scaffold", "description": "You are a Python project architecture expert specializing in scaffolding production-ready Python applications. Generate complete project structures with modern tooling (uv, FastAPI, Django), type hint", @@ -6238,7 +6355,7 @@ }, { "id": "python-fastapi-development", - "path": "skills/python-fastapi-development", + "path": "skills\\python-fastapi-development", "category": "uncategorized", "name": "python-fastapi-development", "description": "Python FastAPI backend development with async patterns, SQLAlchemy, Pydantic, authentication, and production API patterns.", @@ -6247,7 +6364,7 @@ }, { "id": "python-packaging", - "path": "skills/python-packaging", + "path": "skills\\python-packaging", "category": "uncategorized", "name": "python-packaging", "description": "Create distributable Python packages with proper project structure, setup.py/pyproject.toml, and publishing to PyPI. Use when packaging Python libraries, creating CLI tools, or distributing Python ...", @@ -6256,7 +6373,7 @@ }, { "id": "python-patterns", - "path": "skills/python-patterns", + "path": "skills\\python-patterns", "category": "uncategorized", "name": "python-patterns", "description": "Python development principles and decision-making. Framework selection, async patterns, type hints, project structure. Teaches thinking, not copying.", @@ -6265,16 +6382,25 @@ }, { "id": "python-performance-optimization", - "path": "skills/python-performance-optimization", + "path": "skills\\python-performance-optimization", "category": "uncategorized", "name": "python-performance-optimization", "description": "Profile and optimize Python code using cProfile, memory profilers, and performance best practices. Use when debugging slow Python code, optimizing bottlenecks, or improving application performance.", "risk": "unknown", "source": "community" }, + { + "id": "python-pro", + "path": "skills\\python-pro", + "category": "uncategorized", + "name": "python-pro", + "description": "Master Python 3.12+ with modern features, async programming,\nperformance optimization, and production-ready practices. Expert in the latest\nPython ecosystem including uv, ruff, pydantic, and FastAPI. Use PROACTIVELY\nfor Python development, optimization, or advanced Python patterns.\n", + "risk": "unknown", + "source": "community" + }, { "id": "python-testing-patterns", - "path": "skills/python-testing-patterns", + "path": "skills\\python-testing-patterns", "category": "uncategorized", "name": "python-testing-patterns", "description": "Implement comprehensive testing strategies with pytest, fixtures, mocking, and test-driven development. Use when writing Python tests, setting up test suites, or implementing testing best practices.", @@ -6282,17 +6408,26 @@ "source": "community" }, { - "id": "quant-analyst", - "path": "skills/quant-analyst", + "id": "quality-nonconformance", + "path": "skills\\quality-nonconformance", "category": "uncategorized", - "name": "Quant Analyst", - "description": "- Working on quant analyst tasks or workflows - Needing guidance, best practices, or checklists for quant analyst", + "name": "quality-nonconformance", + "description": "Codified expertise for quality control, non-conformance investigation, root cause analysis, corrective action, and supplier quality management in regulated manufacturing. Informed by quality engineers with 15+ years experience across FDA, IATF 16949, and AS9100 environments. Includes NCR lifecycle management, CAPA systems, SPC interpretation, and audit methodology. Use when investigating non-conformances, performing root cause analysis, managing CAPAs, interpreting SPC data, or handling supplier quality issues.\n", + "risk": "safe", + "source": "https://github.com/ai-evos/agent-skills" + }, + { + "id": "quant-analyst", + "path": "skills\\quant-analyst", + "category": "uncategorized", + "name": "quant-analyst", + "description": "Build financial models, backtest trading strategies, and analyze\nmarket data. Implements risk metrics, portfolio optimization, and statistical\narbitrage. Use PROACTIVELY for quantitative finance, trading algorithms, or\nrisk analysis.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "radix-ui-design-system", - "path": "skills/radix-ui-design-system", + "path": "skills\\radix-ui-design-system", "category": "uncategorized", "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.", @@ -6301,7 +6436,7 @@ }, { "id": "rag-engineer", - "path": "skills/rag-engineer", + "path": "skills\\rag-engineer", "category": "uncategorized", "name": "rag-engineer", "description": "Expert in building Retrieval-Augmented Generation systems. Masters embedding models, vector databases, chunking strategies, and retrieval optimization for LLM applications. Use when: building RAG, ...", @@ -6310,7 +6445,7 @@ }, { "id": "rag-implementation", - "path": "skills/rag-implementation", + "path": "skills\\rag-implementation", "category": "uncategorized", "name": "rag-implementation", "description": "RAG (Retrieval-Augmented Generation) implementation workflow covering embedding selection, vector database setup, chunking strategies, and retrieval optimization.", @@ -6319,7 +6454,7 @@ }, { "id": "react-best-practices", - "path": "skills/react-best-practices", + "path": "skills\\react-best-practices", "category": "uncategorized", "name": "react-best-practices", "description": "React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance pat...", @@ -6328,7 +6463,7 @@ }, { "id": "react-flow-architect", - "path": "skills/react-flow-architect", + "path": "skills\\react-flow-architect", "category": "uncategorized", "name": "react-flow-architect", "description": "Expert ReactFlow architect for building interactive graph applications with hierarchical node-edge systems, performance optimization, and auto-layout integration. Use when Claude needs to create or...", @@ -6337,7 +6472,7 @@ }, { "id": "react-flow-node-ts", - "path": "skills/react-flow-node-ts", + "path": "skills\\react-flow-node-ts", "category": "uncategorized", "name": "react-flow-node-ts", "description": "Create React Flow node components with TypeScript types, handles, and Zustand integration. Use when building custom nodes for React Flow canvas, creating visual workflow editors, or implementing no...", @@ -6346,7 +6481,7 @@ }, { "id": "react-modernization", - "path": "skills/react-modernization", + "path": "skills\\react-modernization", "category": "uncategorized", "name": "react-modernization", "description": "Upgrade React applications to latest versions, migrate from class components to hooks, and adopt concurrent features. Use when modernizing React codebases, migrating to React Hooks, or upgrading to...", @@ -6355,7 +6490,7 @@ }, { "id": "react-native-architecture", - "path": "skills/react-native-architecture", + "path": "skills\\react-native-architecture", "category": "uncategorized", "name": "react-native-architecture", "description": "Build production React Native apps with Expo, navigation, native modules, offline sync, and cross-platform patterns. Use when developing mobile apps, implementing native integrations, or architecti...", @@ -6364,7 +6499,7 @@ }, { "id": "react-nextjs-development", - "path": "skills/react-nextjs-development", + "path": "skills\\react-nextjs-development", "category": "uncategorized", "name": "react-nextjs-development", "description": "React and Next.js 14+ application development with App Router, Server Components, TypeScript, Tailwind CSS, and modern frontend patterns.", @@ -6373,7 +6508,7 @@ }, { "id": "react-patterns", - "path": "skills/react-patterns", + "path": "skills\\react-patterns", "category": "uncategorized", "name": "react-patterns", "description": "Modern React patterns and principles. Hooks, composition, performance, TypeScript best practices.", @@ -6382,7 +6517,7 @@ }, { "id": "react-state-management", - "path": "skills/react-state-management", + "path": "skills\\react-state-management", "category": "uncategorized", "name": "react-state-management", "description": "Master modern React state management with Redux Toolkit, Zustand, Jotai, and React Query. Use when setting up global state, managing server state, or choosing between state management solutions.", @@ -6391,7 +6526,7 @@ }, { "id": "react-ui-patterns", - "path": "skills/react-ui-patterns", + "path": "skills\\react-ui-patterns", "category": "uncategorized", "name": "react-ui-patterns", "description": "Modern React UI patterns for loading states, error handling, and data fetching. Use when building UI components, handling async data, or managing UI states.", @@ -6400,7 +6535,7 @@ }, { "id": "readme", - "path": "skills/readme", + "path": "skills\\readme", "category": "uncategorized", "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 he...", @@ -6409,7 +6544,7 @@ }, { "id": "receiving-code-review", - "path": "skills/receiving-code-review", + "path": "skills\\receiving-code-review", "category": "uncategorized", "name": "receiving-code-review", "description": "Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performat...", @@ -6418,7 +6553,7 @@ }, { "id": "red-team-tactics", - "path": "skills/red-team-tactics", + "path": "skills\\red-team-tactics", "category": "uncategorized", "name": "red-team-tactics", "description": "Red team tactics principles based on MITRE ATT&CK. Attack phases, detection evasion, reporting.", @@ -6427,7 +6562,7 @@ }, { "id": "red-team-tools", - "path": "skills/red-team-tools", + "path": "skills\\red-team-tools", "category": "uncategorized", "name": "red-team-tools", "description": "This skill should be used when the user asks to \"follow red team methodology\", \"perform bug bounty hunting\", \"automate reconnaissance\", \"hunt for XSS vulnerabilities\", \"enumerate su...", @@ -6436,7 +6571,7 @@ }, { "id": "reddit-automation", - "path": "skills/reddit-automation", + "path": "skills\\reddit-automation", "category": "uncategorized", "name": "reddit-automation", "description": "Automate Reddit tasks via Rube MCP (Composio): search subreddits, create posts, manage comments, and browse top content. Always search tools first for current schemas.", @@ -6445,16 +6580,16 @@ }, { "id": "reference-builder", - "path": "skills/reference-builder", + "path": "skills\\reference-builder", "category": "uncategorized", - "name": "Reference Builder", - "description": "- Working on reference builder tasks or workflows - Needing guidance, best practices, or checklists for reference builder", + "name": "reference-builder", + "description": "Creates exhaustive technical references and API documentation.\nGenerates comprehensive parameter listings, configuration guides, and\nsearchable reference materials. Use PROACTIVELY for API docs, configuration\nreferences, or complete technical specifications.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "referral-program", - "path": "skills/referral-program", + "path": "skills\\referral-program", "category": "uncategorized", "name": "referral-program", "description": "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 'referral,' 'affiliate,' 'ambassador,' 'word of...", @@ -6463,7 +6598,7 @@ }, { "id": "remotion-best-practices", - "path": "skills/remotion-best-practices", + "path": "skills\\remotion-best-practices", "category": "uncategorized", "name": "remotion-best-practices", "description": "Best practices for Remotion - Video creation in React", @@ -6472,7 +6607,7 @@ }, { "id": "render-automation", - "path": "skills/render-automation", + "path": "skills\\render-automation", "category": "uncategorized", "name": "render-automation", "description": "Automate Render tasks via Rube MCP (Composio): services, deployments, projects. Always search tools first for current schemas.", @@ -6481,7 +6616,7 @@ }, { "id": "requesting-code-review", - "path": "skills/requesting-code-review", + "path": "skills\\requesting-code-review", "category": "uncategorized", "name": "requesting-code-review", "description": "Use when completing tasks, implementing major features, or before merging to verify work meets requirements", @@ -6490,7 +6625,7 @@ }, { "id": "research-engineer", - "path": "skills/research-engineer", + "path": "skills\\research-engineer", "category": "uncategorized", "name": "research-engineer", "description": "An uncompromising Academic Research Engineer. Operates with absolute scientific rigor, objective criticism, and zero flair. Focuses on theoretical correctness, formal verification, and optimal impl...", @@ -6498,26 +6633,35 @@ "source": "community" }, { - "id": "reverse-engineer", - "path": "skills/reverse-engineer", + "id": "returns-reverse-logistics", + "path": "skills\\returns-reverse-logistics", "category": "uncategorized", - "name": "Reverse Engineer", - "description": "- IDAPython (IDA Pro scripting) - Ghidra scripting (Java/Python via Jython) - r2pipe (radare2 Python API) - pwntools (CTF/exploitation toolkit) - capstone (disassembly framework) - keystone (assembly framework) - unicorn (CPU emulator framework) - an", + "name": "returns-reverse-logistics", + "description": "Codified expertise for returns authorisation, receipt and inspection, disposition decisions, refund processing, fraud detection, and warranty claims management. Informed by returns operations managers with 15+ years experience. Includes grading frameworks, disposition economics, fraud pattern recognition, and vendor recovery processes. Use when handling product returns, reverse logistics, refund decisions, return fraud detection, or warranty claims.\n", + "risk": "safe", + "source": "https://github.com/ai-evos/agent-skills" + }, + { + "id": "reverse-engineer", + "path": "skills\\reverse-engineer", + "category": "uncategorized", + "name": "reverse-engineer", + "description": "Expert reverse engineer specializing in binary analysis,\ndisassembly, decompilation, and software analysis. Masters IDA Pro, Ghidra,\nradare2, x64dbg, and modern RE toolchains. Handles executable analysis,\nlibrary inspection, protocol extraction, and vulnerability research. Use\nPROACTIVELY for binary analysis, CTF challenges, security research, or\nunderstanding undocumented software.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "risk-manager", - "path": "skills/risk-manager", + "path": "skills\\risk-manager", "category": "uncategorized", - "name": "Risk Manager", - "description": "- Working on risk manager tasks or workflows - Needing guidance, best practices, or checklists for risk manager", + "name": "risk-manager", + "description": "Monitor portfolio risk, R-multiples, and position limits. Creates\nhedging strategies, calculates expectancy, and implements stop-losses. Use\nPROACTIVELY for risk assessment, trade tracking, or portfolio protection.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "risk-metrics-calculation", - "path": "skills/risk-metrics-calculation", + "path": "skills\\risk-metrics-calculation", "category": "uncategorized", "name": "risk-metrics-calculation", "description": "Calculate portfolio risk metrics including VaR, CVaR, Sharpe, Sortino, and drawdown analysis. Use when measuring portfolio risk, implementing risk limits, or building risk monitoring systems.", @@ -6526,34 +6670,34 @@ }, { "id": "ruby-pro", - "path": "skills/ruby-pro", + "path": "skills\\ruby-pro", "category": "uncategorized", - "name": "Ruby Pro", - "description": "- Working on ruby pro tasks or workflows - Needing guidance, best practices, or checklists for ruby pro", + "name": "ruby-pro", + "description": "Write idiomatic Ruby code with metaprogramming, Rails patterns, and\nperformance optimization. Specializes in Ruby on Rails, gem development, and\ntesting frameworks. Use PROACTIVELY for Ruby refactoring, optimization, or\ncomplex Ruby features.\n", "risk": "unknown", - "source": "unknown" - }, - { - "id": "rust-pro", - "path": "skills/rust-pro", - "category": "uncategorized", - "name": "Rust Pro", - "description": "You are a Rust expert specializing in modern Rust 1.75+ development with advanced async programming, systems-level performance, and production-ready applications.", - "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "rust-async-patterns", - "path": "skills/rust-async-patterns", + "path": "skills\\rust-async-patterns", "category": "uncategorized", "name": "rust-async-patterns", "description": "Master Rust async programming with Tokio, async traits, error handling, and concurrent patterns. Use when building async Rust applications, implementing concurrent systems, or debugging async code.", "risk": "unknown", "source": "community" }, + { + "id": "rust-pro", + "path": "skills\\rust-pro", + "category": "uncategorized", + "name": "rust-pro", + "description": "Master Rust 1.75+ with modern async patterns, advanced type system\nfeatures, and production-ready systems programming. Expert in the latest Rust\necosystem including Tokio, axum, and cutting-edge crates. Use PROACTIVELY for\nRust development, performance optimization, or systems programming.\n", + "risk": "unknown", + "source": "community" + }, { "id": "saga-orchestration", - "path": "skills/saga-orchestration", + "path": "skills\\saga-orchestration", "category": "uncategorized", "name": "saga-orchestration", "description": "Implement saga patterns for distributed transactions and cross-aggregate workflows. Use when coordinating multi-step business processes, handling compensating transactions, or managing long-running...", @@ -6562,16 +6706,16 @@ }, { "id": "sales-automator", - "path": "skills/sales-automator", + "path": "skills\\sales-automator", "category": "uncategorized", - "name": "Sales Automator", - "description": "- Working on sales automator tasks or workflows - Needing guidance, best practices, or checklists for sales automator", + "name": "sales-automator", + "description": "Draft cold emails, follow-ups, and proposal templates. Creates\npricing pages, case studies, and sales scripts. Use PROACTIVELY for sales\noutreach or lead nurturing.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "salesforce-automation", - "path": "skills/salesforce-automation", + "path": "skills\\salesforce-automation", "category": "uncategorized", "name": "salesforce-automation", "description": "Automate Salesforce tasks via Rube MCP (Composio): leads, contacts, accounts, opportunities, SOQL queries. Always search tools first for current schemas.", @@ -6580,7 +6724,7 @@ }, { "id": "salesforce-development", - "path": "skills/salesforce-development", + "path": "skills\\salesforce-development", "category": "uncategorized", "name": "salesforce-development", "description": "Expert patterns for Salesforce platform development including Lightning Web Components (LWC), Apex triggers and classes, REST/Bulk APIs, Connected Apps, and Salesforce DX with scratch orgs and 2nd ...", @@ -6589,7 +6733,7 @@ }, { "id": "sast-configuration", - "path": "skills/sast-configuration", + "path": "skills\\sast-configuration", "category": "uncategorized", "name": "sast-configuration", "description": "Configure Static Application Security Testing (SAST) tools for automated vulnerability detection in application code. Use when setting up security scanning, implementing DevSecOps practices, or aut...", @@ -6598,16 +6742,16 @@ }, { "id": "scala-pro", - "path": "skills/scala-pro", + "path": "skills\\scala-pro", "category": "uncategorized", - "name": "Scala Pro", - "description": "- Working on scala pro tasks or workflows - Needing guidance, best practices, or checklists for scala pro", + "name": "scala-pro", + "description": "Master enterprise-grade Scala development with functional\nprogramming, distributed systems, and big data processing. Expert in Apache\nPekko, Akka, Spark, ZIO/Cats Effect, and reactive architectures. Use\nPROACTIVELY for Scala system design, performance optimization, or enterprise\nintegration.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "scanning-tools", - "path": "skills/scanning-tools", + "path": "skills\\scanning-tools", "category": "uncategorized", "name": "scanning-tools", "description": "This skill should be used when the user asks to \"perform vulnerability scanning\", \"scan networks for open ports\", \"assess web application security\", \"scan wireless networks\", \"detec...", @@ -6616,16 +6760,16 @@ }, { "id": "schema-markup", - "path": "skills/schema-markup", + "path": "skills\\schema-markup", "category": "uncategorized", - "name": "Schema Markup", - "description": "---", + "name": "schema-markup", + "description": "Design, validate, and optimize schema.org structured data for eligibility, correctness, and measurable SEO impact. Use when the user wants to add, fix, audit, or scale schema markup (JSON-LD) for rich results. This skill evaluates whether schema should be implemented, what types are valid, and how to deploy safely according to Google guidelines.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "screen-reader-testing", - "path": "skills/screen-reader-testing", + "path": "skills\\screen-reader-testing", "category": "uncategorized", "name": "screen-reader-testing", "description": "Test web applications with screen readers including VoiceOver, NVDA, and JAWS. Use when validating screen reader compatibility, debugging accessibility issues, or ensuring assistive technology supp...", @@ -6634,7 +6778,7 @@ }, { "id": "screenshots", - "path": "skills/screenshots", + "path": "skills\\screenshots", "category": "uncategorized", "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.", @@ -6643,7 +6787,7 @@ }, { "id": "scroll-experience", - "path": "skills/scroll-experience", + "path": "skills\\scroll-experience", "category": "uncategorized", "name": "scroll-experience", "description": "Expert in building immersive scroll-driven experiences - parallax storytelling, scroll animations, interactive narratives, and cinematic web experiences. Like NY Times interactives, Apple product p...", @@ -6652,7 +6796,7 @@ }, { "id": "search-specialist", - "path": "skills/search-specialist", + "path": "skills\\search-specialist", "category": "uncategorized", "name": "search-specialist", "description": "Expert web researcher using advanced search techniques and synthesis. Masters search operators, result filtering, and multi-source verification. Handles competitive analysis and fact-checking. Use PROACTIVELY for deep research, information gathering, or trend analysis.", @@ -6661,43 +6805,34 @@ }, { "id": "secrets-management", - "path": "skills/secrets-management", + "path": "skills\\secrets-management", "category": "uncategorized", "name": "secrets-management", "description": "Implement secure secrets management for CI/CD pipelines using Vault, AWS Secrets Manager, or native platform solutions. Use when handling sensitive credentials, rotating secrets, or securing CI/CD ...", "risk": "unknown", "source": "community" }, - { - "id": "security-auditor", - "path": "skills/security-auditor", - "category": "uncategorized", - "name": "Security Auditor", - "description": "You are a security auditor specializing in DevSecOps, application security, and comprehensive cybersecurity practices.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "security-scanning-security-sast", - "path": "skills/security-scanning-security-sast", - "category": "uncategorized", - "name": "Security Scanning Security Sast", - "description": "Static Application Security Testing (SAST) for comprehensive code vulnerability detection across multiple languages, frameworks, and security patterns.", - "risk": "unknown", - "source": "unknown" - }, { "id": "security-audit", - "path": "skills/security-audit", + "path": "skills\\security-audit", "category": "uncategorized", "name": "security-audit", "description": "Comprehensive security auditing workflow covering web application testing, API security, penetration testing, vulnerability scanning, and security hardening.", "risk": "safe", "source": "personal" }, + { + "id": "security-auditor", + "path": "skills\\security-auditor", + "category": "uncategorized", + "name": "security-auditor", + "description": "Expert security auditor specializing in DevSecOps, comprehensive\ncybersecurity, and compliance frameworks. Masters vulnerability assessment,\nthreat modeling, secure authentication (OAuth2/OIDC), OWASP standards, cloud\nsecurity, and security automation. Handles DevSecOps integration, compliance\n(GDPR/HIPAA/SOC2), and incident response. Use PROACTIVELY for security audits,\nDevSecOps, or compliance implementation.\n", + "risk": "unknown", + "source": "community" + }, { "id": "security-bluebook-builder", - "path": "skills/security-bluebook-builder", + "path": "skills\\security-bluebook-builder", "category": "uncategorized", "name": "security-bluebook-builder", "description": "Build security Blue Books for sensitive apps", @@ -6706,7 +6841,7 @@ }, { "id": "security-compliance-compliance-check", - "path": "skills/security-compliance-compliance-check", + "path": "skills\\security-compliance-compliance-check", "category": "uncategorized", "name": "security-compliance-compliance-check", "description": "You are a compliance expert specializing in regulatory requirements for software systems including GDPR, HIPAA, SOC2, PCI-DSS, and other industry standards. Perform compliance audits and provide im...", @@ -6715,7 +6850,7 @@ }, { "id": "security-requirement-extraction", - "path": "skills/security-requirement-extraction", + "path": "skills\\security-requirement-extraction", "category": "uncategorized", "name": "security-requirement-extraction", "description": "Derive security requirements from threat models and business context. Use when translating threats into actionable requirements, creating security user stories, or building security test cases.", @@ -6724,7 +6859,7 @@ }, { "id": "security-scanning-security-dependencies", - "path": "skills/security-scanning-security-dependencies", + "path": "skills\\security-scanning-security-dependencies", "category": "uncategorized", "name": "security-scanning-security-dependencies", "description": "You are a security expert specializing in dependency vulnerability analysis, SBOM generation, and supply chain security. Scan project dependencies across ecosystems to identify vulnerabilities, ass...", @@ -6733,16 +6868,25 @@ }, { "id": "security-scanning-security-hardening", - "path": "skills/security-scanning-security-hardening", + "path": "skills\\security-scanning-security-hardening", "category": "uncategorized", "name": "security-scanning-security-hardening", "description": "Coordinate multi-layer security scanning and hardening across application, infrastructure, and compliance controls.", "risk": "unknown", "source": "community" }, + { + "id": "security-scanning-security-sast", + "path": "skills\\security-scanning-security-sast", + "category": "uncategorized", + "name": "security-scanning-security-sast", + "description": "Static Application Security Testing (SAST) for code vulnerability\nanalysis across multiple languages and frameworks\n", + "risk": "unknown", + "source": "community" + }, { "id": "segment-automation", - "path": "skills/segment-automation", + "path": "skills\\segment-automation", "category": "uncategorized", "name": "segment-automation", "description": "Automate Segment tasks via Rube MCP (Composio): track events, identify users, manage groups, page views, aliases, batch operations. Always search tools first for current schemas.", @@ -6751,7 +6895,7 @@ }, { "id": "segment-cdp", - "path": "skills/segment-cdp", + "path": "skills\\segment-cdp", "category": "uncategorized", "name": "segment-cdp", "description": "Expert patterns for Segment Customer Data Platform including Analytics.js, server-side tracking, tracking plans with Protocols, identity resolution, destinations configuration, and data governance ...", @@ -6760,7 +6904,7 @@ }, { "id": "sendgrid-automation", - "path": "skills/sendgrid-automation", + "path": "skills\\sendgrid-automation", "category": "uncategorized", "name": "sendgrid-automation", "description": "Automate SendGrid email operations including sending emails, managing contacts/lists, sender identities, templates, and analytics via Rube MCP (Composio). Always search tools first for current sche...", @@ -6769,7 +6913,7 @@ }, { "id": "senior-architect", - "path": "skills/senior-architect", + "path": "skills\\senior-architect", "category": "uncategorized", "name": "senior-architect", "description": "Comprehensive software architecture skill for designing scalable, maintainable systems using ReactJS, NextJS, NodeJS, Express, React Native, Swift, Kotlin, Flutter, Postgres, GraphQL, Go, Python. I...", @@ -6778,7 +6922,7 @@ }, { "id": "senior-fullstack", - "path": "skills/senior-fullstack", + "path": "skills\\senior-fullstack", "category": "uncategorized", "name": "senior-fullstack", "description": "Comprehensive fullstack development skill for building complete web applications with React, Next.js, Node.js, GraphQL, and PostgreSQL. Includes project scaffolding, code quality analysis, architec...", @@ -6787,7 +6931,7 @@ }, { "id": "sentry-automation", - "path": "skills/sentry-automation", + "path": "skills\\sentry-automation", "category": "uncategorized", "name": "sentry-automation", "description": "Automate Sentry tasks via Rube MCP (Composio): manage issues/events, configure alerts, track releases, monitor projects and teams. Always search tools first for current schemas.", @@ -6796,115 +6940,115 @@ }, { "id": "seo-audit", - "path": "skills/seo-audit", + "path": "skills\\seo-audit", "category": "uncategorized", - "name": "Seo Audit", - "description": "You are an **SEO diagnostic specialist**. Your role is to **identify, explain, and prioritize SEO issues** that affect organic visibility\u2014**not to implement fixes unless explicitly requested**.", + "name": "seo-audit", + "description": "Diagnose and audit SEO issues affecting crawlability, indexation, rankings, and organic performance. Use when the user asks for an SEO audit, technical SEO review, ranking diagnosis, on-page SEO review, meta tag audit, or SEO health check. This skill identifies issues and prioritizes actions but does not execute changes. For large-scale page creation, use programmatic-seo. For structured data, use schema-markup.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "seo-authority-builder", - "path": "skills/seo-authority-builder", + "path": "skills\\seo-authority-builder", "category": "uncategorized", - "name": "Seo Authority Builder", - "description": "- Working on seo authority builder tasks or workflows - Needing guidance, best practices, or checklists for seo authority builder", + "name": "seo-authority-builder", + "description": "Analyzes content for E-E-A-T signals and suggests improvements to\nbuild authority and trust. Identifies missing credibility elements. Use\nPROACTIVELY for YMYL topics.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "seo-cannibalization-detector", - "path": "skills/seo-cannibalization-detector", + "path": "skills\\seo-cannibalization-detector", "category": "uncategorized", - "name": "Seo Cannibalization Detector", - "description": "- Working on seo cannibalization detector tasks or workflows - Needing guidance, best practices, or checklists for seo cannibalization detector", + "name": "seo-cannibalization-detector", + "description": "Analyzes multiple provided pages to identify keyword overlap and\npotential cannibalization issues. Suggests differentiation strategies. Use\nPROACTIVELY when reviewing similar content.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "seo-content-auditor", - "path": "skills/seo-content-auditor", + "path": "skills\\seo-content-auditor", "category": "uncategorized", - "name": "Seo Content Auditor", - "description": "- Working on seo content auditor tasks or workflows - Needing guidance, best practices, or checklists for seo content auditor", + "name": "seo-content-auditor", + "description": "Analyzes provided content for quality, E-E-A-T signals, and SEO\nbest practices. Scores content and provides improvement recommendations based\non established guidelines. Use PROACTIVELY for content review.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "seo-content-planner", - "path": "skills/seo-content-planner", + "path": "skills\\seo-content-planner", "category": "uncategorized", - "name": "Seo Content Planner", - "description": "- Working on seo content planner tasks or workflows - Needing guidance, best practices, or checklists for seo content planner", + "name": "seo-content-planner", + "description": "Creates comprehensive content outlines and topic clusters for SEO.\nPlans content calendars and identifies topic gaps. Use PROACTIVELY for content\nstrategy and planning.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "seo-content-refresher", - "path": "skills/seo-content-refresher", + "path": "skills\\seo-content-refresher", "category": "uncategorized", - "name": "Seo Content Refresher", - "description": "- Working on seo content refresher tasks or workflows - Needing guidance, best practices, or checklists for seo content refresher", + "name": "seo-content-refresher", + "description": "Identifies outdated elements in provided content and suggests\nupdates to maintain freshness. Finds statistics, dates, and examples that need\nupdating. Use PROACTIVELY for older content.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "seo-content-writer", - "path": "skills/seo-content-writer", + "path": "skills\\seo-content-writer", "category": "uncategorized", - "name": "Seo Content Writer", - "description": "- Working on seo content writer tasks or workflows - Needing guidance, best practices, or checklists for seo content writer", + "name": "seo-content-writer", + "description": "Writes SEO-optimized content based on provided keywords and topic\nbriefs. Creates engaging, comprehensive content following best practices. Use\nPROACTIVELY for content creation tasks.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "seo-fundamentals", - "path": "skills/seo-fundamentals", + "path": "skills\\seo-fundamentals", "category": "uncategorized", - "name": "Seo Fundamentals", - "description": "---", + "name": "seo-fundamentals", + "description": "Core principles of SEO including E-E-A-T, Core Web Vitals, technical foundations, content quality, and how modern search engines evaluate pages. This skill explains *why* SEO works, not how to execute specific optimizations.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "seo-keyword-strategist", - "path": "skills/seo-keyword-strategist", + "path": "skills\\seo-keyword-strategist", "category": "uncategorized", - "name": "Seo Keyword Strategist", - "description": "- Working on seo keyword strategist tasks or workflows - Needing guidance, best practices, or checklists for seo keyword strategist", + "name": "seo-keyword-strategist", + "description": "Analyzes keyword usage in provided content, calculates density,\nsuggests semantic variations and LSI keywords based on the topic. Prevents\nover-optimization. Use PROACTIVELY for content optimization.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "seo-meta-optimizer", - "path": "skills/seo-meta-optimizer", + "path": "skills\\seo-meta-optimizer", "category": "uncategorized", - "name": "Seo Meta Optimizer", - "description": "- Working on seo meta optimizer tasks or workflows - Needing guidance, best practices, or checklists for seo meta optimizer", + "name": "seo-meta-optimizer", + "description": "Creates optimized meta titles, descriptions, and URL suggestions\nbased on character limits and best practices. Generates compelling,\nkeyword-rich metadata. Use PROACTIVELY for new content.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "seo-snippet-hunter", - "path": "skills/seo-snippet-hunter", + "path": "skills\\seo-snippet-hunter", "category": "uncategorized", - "name": "Seo Snippet Hunter", - "description": "- Working on seo snippet hunter tasks or workflows - Needing guidance, best practices, or checklists for seo snippet hunter", + "name": "seo-snippet-hunter", + "description": "Formats content to be eligible for featured snippets and SERP\nfeatures. Creates snippet-optimized content blocks based on best practices.\nUse PROACTIVELY for question-based content.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "seo-structure-architect", - "path": "skills/seo-structure-architect", + "path": "skills\\seo-structure-architect", "category": "uncategorized", - "name": "Seo Structure Architect", - "description": "- Working on seo structure architect tasks or workflows - Needing guidance, best practices, or checklists for seo structure architect", + "name": "seo-structure-architect", + "description": "Analyzes and optimizes content structure including header\nhierarchy, suggests schema markup, and internal linking opportunities. Creates\nsearch-friendly content organization. Use PROACTIVELY for content structuring.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "server-management", - "path": "skills/server-management", + "path": "skills\\server-management", "category": "uncategorized", "name": "server-management", "description": "Server management principles and decision-making. Process management, monitoring strategy, and scaling decisions. Teaches thinking, not commands.", @@ -6913,7 +7057,7 @@ }, { "id": "service-mesh-expert", - "path": "skills/service-mesh-expert", + "path": "skills\\service-mesh-expert", "category": "uncategorized", "name": "service-mesh-expert", "description": "Expert service mesh architect specializing in Istio, Linkerd, and cloud-native networking patterns. Masters traffic management, security policies, observability integration, and multi-cluster mesh con", @@ -6922,7 +7066,7 @@ }, { "id": "service-mesh-observability", - "path": "skills/service-mesh-observability", + "path": "skills\\service-mesh-observability", "category": "uncategorized", "name": "service-mesh-observability", "description": "Implement comprehensive observability for service meshes including distributed tracing, metrics, and visualization. Use when setting up mesh monitoring, debugging latency issues, or implementing SL...", @@ -6931,7 +7075,7 @@ }, { "id": "shader-programming-glsl", - "path": "skills/shader-programming-glsl", + "path": "skills\\shader-programming-glsl", "category": "uncategorized", "name": "shader-programming-glsl", "description": "Expert guide for writing efficient GLSL shaders (Vertex/Fragment) for web and game engines, covering syntax, uniforms, and common effects.", @@ -6940,7 +7084,7 @@ }, { "id": "sharp-edges", - "path": "skills/sharp-edges", + "path": "skills\\sharp-edges", "category": "uncategorized", "name": "sharp-edges", "description": "Identify error-prone APIs and dangerous configurations", @@ -6949,7 +7093,7 @@ }, { "id": "shellcheck-configuration", - "path": "skills/shellcheck-configuration", + "path": "skills\\shellcheck-configuration", "category": "uncategorized", "name": "shellcheck-configuration", "description": "Master ShellCheck static analysis configuration and usage for shell script quality. Use when setting up linting infrastructure, fixing code issues, or ensuring script portability.", @@ -6958,7 +7102,7 @@ }, { "id": "shodan-reconnaissance", - "path": "skills/shodan-reconnaissance", + "path": "skills\\shodan-reconnaissance", "category": "uncategorized", "name": "shodan-reconnaissance", "description": "This skill should be used when the user asks to \"search for exposed devices on the internet,\" \"perform Shodan reconnaissance,\" \"find vulnerable services using Shodan,\" \"scan IP ranges...", @@ -6967,7 +7111,7 @@ }, { "id": "shopify-apps", - "path": "skills/shopify-apps", + "path": "skills\\shopify-apps", "category": "uncategorized", "name": "shopify-apps", "description": "Expert patterns for Shopify app development including Remix/React Router apps, embedded apps with App Bridge, webhook handling, GraphQL Admin API, Polaris components, billing, and app extensions. U...", @@ -6976,7 +7120,7 @@ }, { "id": "shopify-automation", - "path": "skills/shopify-automation", + "path": "skills\\shopify-automation", "category": "uncategorized", "name": "shopify-automation", "description": "Automate Shopify tasks via Rube MCP (Composio): products, orders, customers, inventory, collections. Always search tools first for current schemas.", @@ -6985,7 +7129,7 @@ }, { "id": "shopify-development", - "path": "skills/shopify-development", + "path": "skills\\shopify-development", "category": "uncategorized", "name": "shopify-development", "description": "Build Shopify apps, extensions, themes using GraphQL Admin API, Shopify CLI, Polaris UI, and Liquid.\nTRIGGER: \"shopify\", \"shopify app\", \"checkout extension\", \"admin extension\", \"POS extension\",\n\"shopify theme\", \"liquid template\", \"polaris\", \"shopify graphql\", \"shopify webhook\",\n\"shopify billing\", \"app subscription\", \"metafields\", \"shopify functions\"\n", @@ -6994,7 +7138,7 @@ }, { "id": "signup-flow-cro", - "path": "skills/signup-flow-cro", + "path": "skills\\signup-flow-cro", "category": "uncategorized", "name": "signup-flow-cro", "description": "When the user wants to optimize signup, registration, account creation, or trial activation flows. Also use when the user mentions \"signup conversions,\" \"registration friction,\" \"signup...", @@ -7003,7 +7147,7 @@ }, { "id": "similarity-search-patterns", - "path": "skills/similarity-search-patterns", + "path": "skills\\similarity-search-patterns", "category": "uncategorized", "name": "similarity-search-patterns", "description": "Implement efficient similarity search with vector databases. Use when building semantic search, implementing nearest neighbor queries, or optimizing retrieval performance.", @@ -7012,7 +7156,7 @@ }, { "id": "skill-creator", - "path": "skills/skill-creator", + "path": "skills\\skill-creator", "category": "uncategorized", "name": "skill-creator", "description": "This skill should be used when the user asks to create a new skill, build a skill, make a custom skill, develop a CLI skill, or wants to extend the CLI with new capabilities. Automates the entire s...", @@ -7021,7 +7165,7 @@ }, { "id": "skill-creator-ms", - "path": "skills/skill-creator-ms", + "path": "skills\\skill-creator-ms", "category": "uncategorized", "name": "skill-creator-ms", "description": "Guide for creating effective skills for AI coding agents working with Azure SDKs and Microsoft Foundry services. Use when creating new skills or updating existing skills.", @@ -7030,7 +7174,7 @@ }, { "id": "skill-developer", - "path": "skills/skill-developer", + "path": "skills\\skill-developer", "category": "uncategorized", "name": "skill-developer", "description": "Create and manage Claude Code skills following Anthropic best practices. Use when creating new skills, modifying skill-rules.json, understanding trigger patterns, working with hooks, debugging skil...", @@ -7039,7 +7183,7 @@ }, { "id": "skill-rails-upgrade", - "path": "skills/skill-rails-upgrade", + "path": "skills\\skill-rails-upgrade", "category": "uncategorized", "name": "skill-rails-upgrade", "description": "Analyze Rails apps and provide upgrade assessments", @@ -7048,7 +7192,7 @@ }, { "id": "skill-seekers", - "path": "skills/skill-seekers", + "path": "skills\\skill-seekers", "category": "uncategorized", "name": "skill-seekers", "description": "-Automatically convert documentation websites, GitHub repositories, and PDFs into Claude AI skills in minutes.", @@ -7057,7 +7201,7 @@ }, { "id": "slack-automation", - "path": "skills/slack-automation", + "path": "skills\\slack-automation", "category": "uncategorized", "name": "slack-automation", "description": "Automate Slack messaging, channel management, search, reactions, and threads via Rube MCP (Composio). Send messages, search conversations, manage channels/users, and react to messages programmatica...", @@ -7066,7 +7210,7 @@ }, { "id": "slack-bot-builder", - "path": "skills/slack-bot-builder", + "path": "skills\\slack-bot-builder", "category": "uncategorized", "name": "slack-bot-builder", "description": "Build Slack apps using the Bolt framework across Python, JavaScript, and Java. Covers Block Kit for rich UIs, interactive components, slash commands, event handling, OAuth installation flows, and W...", @@ -7075,7 +7219,7 @@ }, { "id": "slack-gif-creator", - "path": "skills/slack-gif-creator", + "path": "skills\\slack-gif-creator", "category": "uncategorized", "name": "slack-gif-creator", "description": "Knowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like \"...", @@ -7084,7 +7228,7 @@ }, { "id": "slo-implementation", - "path": "skills/slo-implementation", + "path": "skills\\slo-implementation", "category": "uncategorized", "name": "slo-implementation", "description": "Define and implement Service Level Indicators (SLIs) and Service Level Objectives (SLOs) with error budgets and alerting. Use when establishing reliability targets, implementing SRE practices, or m...", @@ -7093,7 +7237,7 @@ }, { "id": "smtp-penetration-testing", - "path": "skills/smtp-penetration-testing", + "path": "skills\\smtp-penetration-testing", "category": "uncategorized", "name": "smtp-penetration-testing", "description": "This skill should be used when the user asks to \"perform SMTP penetration testing\", \"enumerate email users\", \"test for open mail relays\", \"grab SMTP banners\", \"brute force email cre...", @@ -7102,7 +7246,7 @@ }, { "id": "social-content", - "path": "skills/social-content", + "path": "skills\\social-content", "category": "uncategorized", "name": "social-content", "description": "When the user wants help creating, scheduling, or optimizing social media content for LinkedIn, Twitter/X, Instagram, TikTok, Facebook, or other platforms. Also use when the user mentions 'LinkedIn...", @@ -7111,7 +7255,7 @@ }, { "id": "software-architecture", - "path": "skills/software-architecture", + "path": "skills\\software-architecture", "category": "uncategorized", "name": "software-architecture", "description": "Guide for quality focused software architecture. This skill should be used when users want to write code, design architecture, analyze code, in any case that relates to software development.", @@ -7120,7 +7264,7 @@ }, { "id": "solidity-security", - "path": "skills/solidity-security", + "path": "skills\\solidity-security", "category": "uncategorized", "name": "solidity-security", "description": "Master smart contract security best practices to prevent common vulnerabilities and implement secure Solidity patterns. Use when writing smart contracts, auditing existing contracts, or implementin...", @@ -7129,25 +7273,16 @@ }, { "id": "spark-optimization", - "path": "skills/spark-optimization", + "path": "skills\\spark-optimization", "category": "uncategorized", "name": "spark-optimization", "description": "Optimize Apache Spark jobs with partitioning, caching, shuffle optimization, and memory tuning. Use when improving Spark performance, debugging slow jobs, or scaling data processing pipelines.", "risk": "unknown", "source": "community" }, - { - "id": "sql-pro", - "path": "skills/sql-pro", - "category": "uncategorized", - "name": "Sql Pro", - "description": "You are an expert SQL specialist mastering modern database systems, performance optimization, and advanced analytical techniques across cloud-native and hybrid OLTP/OLAP environments.", - "risk": "unknown", - "source": "unknown" - }, { "id": "sql-injection-testing", - "path": "skills/sql-injection-testing", + "path": "skills\\sql-injection-testing", "category": "uncategorized", "name": "sql-injection-testing", "description": "This skill should be used when the user asks to \"test for SQL injection vulnerabilities\", \"perform SQLi attacks\", \"bypass authentication using SQL injection\", \"extract database inform...", @@ -7156,16 +7291,25 @@ }, { "id": "sql-optimization-patterns", - "path": "skills/sql-optimization-patterns", + "path": "skills\\sql-optimization-patterns", "category": "uncategorized", "name": "sql-optimization-patterns", "description": "Master SQL query optimization, indexing strategies, and EXPLAIN analysis to dramatically improve database performance and eliminate slow queries. Use when debugging slow queries, designing database...", "risk": "unknown", "source": "community" }, + { + "id": "sql-pro", + "path": "skills\\sql-pro", + "category": "uncategorized", + "name": "sql-pro", + "description": "Master modern SQL with cloud-native databases, OLTP/OLAP\noptimization, and advanced query techniques. Expert in performance tuning,\ndata modeling, and hybrid analytical systems. Use PROACTIVELY for database\noptimization or complex analysis.\n", + "risk": "unknown", + "source": "community" + }, { "id": "sqlmap-database-pentesting", - "path": "skills/sqlmap-database-pentesting", + "path": "skills\\sqlmap-database-pentesting", "category": "uncategorized", "name": "sqlmap-database-pentesting", "description": "This skill should be used when the user asks to \"automate SQL injection testing,\" \"enumerate database structure,\" \"extract database credentials using sqlmap,\" \"dump tables and columns...", @@ -7174,7 +7318,7 @@ }, { "id": "square-automation", - "path": "skills/square-automation", + "path": "skills\\square-automation", "category": "uncategorized", "name": "square-automation", "description": "Automate Square tasks via Rube MCP (Composio): payments, orders, invoices, locations. Always search tools first for current schemas.", @@ -7183,7 +7327,7 @@ }, { "id": "ssh-penetration-testing", - "path": "skills/ssh-penetration-testing", + "path": "skills\\ssh-penetration-testing", "category": "uncategorized", "name": "ssh-penetration-testing", "description": "This skill should be used when the user asks to \"pentest SSH services\", \"enumerate SSH configurations\", \"brute force SSH credentials\", \"exploit SSH vulnerabilities\", \"perform SSH tu...", @@ -7192,61 +7336,61 @@ }, { "id": "startup-analyst", - "path": "skills/startup-analyst", + "path": "skills\\startup-analyst", "category": "uncategorized", - "name": "Startup Analyst", - "description": "- Working on startup analyst tasks or workflows - Needing guidance, best practices, or checklists for startup analyst", + "name": "startup-analyst", + "description": "Expert startup business analyst specializing in market sizing,\nfinancial modeling, competitive analysis, and strategic planning for\nearly-stage companies. Use PROACTIVELY when the user asks about market\nopportunity, TAM/SAM/SOM, financial projections, unit economics, competitive\nlandscape, team planning, startup metrics, or business strategy for pre-seed\nthrough Series A startups.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "startup-business-analyst-business-case", - "path": "skills/startup-business-analyst-business-case", + "path": "skills\\startup-business-analyst-business-case", "category": "uncategorized", - "name": "Startup Business Analyst Business Case", - "description": "Generate a comprehensive, investor-ready business case document covering market opportunity, solution, competitive landscape, financial projections, team, risks, and funding ask for startup fundraising and strategic planning.", + "name": "startup-business-analyst-business-case", + "description": "Generate comprehensive investor-ready business case document with\nmarket, solution, financials, and strategy\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "startup-business-analyst-financial-projections", - "path": "skills/startup-business-analyst-financial-projections", + "path": "skills\\startup-business-analyst-financial-projections", "category": "uncategorized", - "name": "Startup Business Analyst Financial Projections", - "description": "Create a comprehensive 3-5 year financial model with revenue projections, cost structure, headcount planning, cash flow analysis, and three-scenario modeling (conservative, base, optimistic) for startup financial planning and fundraising.", + "name": "startup-business-analyst-financial-projections", + "description": "Create detailed 3-5 year financial model with revenue, costs, cash\nflow, and scenarios\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "startup-business-analyst-market-opportunity", - "path": "skills/startup-business-analyst-market-opportunity", + "path": "skills\\startup-business-analyst-market-opportunity", "category": "uncategorized", - "name": "Startup Business Analyst Market Opportunity", - "description": "Generate a comprehensive market opportunity analysis for a startup, including Total Addressable Market (TAM), Serviceable Available Market (SAM), and Serviceable Obtainable Market (SOM) calculations using both bottom-up and top-down methodologies.", + "name": "startup-business-analyst-market-opportunity", + "description": "Generate comprehensive market opportunity analysis with TAM/SAM/SOM\ncalculations\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "startup-financial-modeling", - "path": "skills/startup-financial-modeling", + "path": "skills\\startup-financial-modeling", "category": "uncategorized", - "name": "Startup Financial Modeling", - "description": "Build comprehensive 3-5 year financial models with revenue projections, cost structures, cash flow analysis, and scenario planning for early-stage startups.", + "name": "startup-financial-modeling", + "description": "This skill should be used when the user asks to \\\\\\\"create financial\nprojections\", \"build a financial model\", \"forecast revenue\", \"calculate burn\nrate\", \"estimate runway\", \"model cash flow\", or requests 3-5 year financial\nplanning for a startup.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "startup-metrics-framework", - "path": "skills/startup-metrics-framework", + "path": "skills\\startup-metrics-framework", "category": "uncategorized", - "name": "Startup Metrics Framework", - "description": "Comprehensive guide to tracking, calculating, and optimizing key performance metrics for different startup business models from seed through Series A.", + "name": "startup-metrics-framework", + "description": "This skill should be used when the user asks about \\\\\\\"key startup\nmetrics\", \"SaaS metrics\", \"CAC and LTV\", \"unit economics\", \"burn multiple\",\n\"rule of 40\", \"marketplace metrics\", or requests guidance on tracking and\noptimizing business performance metrics.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "stitch-ui-design", - "path": "skills/stitch-ui-design", + "path": "skills\\stitch-ui-design", "category": "uncategorized", "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 cra...", @@ -7255,7 +7399,7 @@ }, { "id": "stride-analysis-patterns", - "path": "skills/stride-analysis-patterns", + "path": "skills\\stride-analysis-patterns", "category": "uncategorized", "name": "stride-analysis-patterns", "description": "Apply STRIDE methodology to systematically identify threats. Use when analyzing system security, conducting threat modeling sessions, or creating security documentation.", @@ -7264,7 +7408,7 @@ }, { "id": "stripe-automation", - "path": "skills/stripe-automation", + "path": "skills\\stripe-automation", "category": "uncategorized", "name": "stripe-automation", "description": "Automate Stripe tasks via Rube MCP (Composio): customers, charges, subscriptions, invoices, products, refunds. Always search tools first for current schemas.", @@ -7273,7 +7417,7 @@ }, { "id": "stripe-integration", - "path": "skills/stripe-integration", + "path": "skills\\stripe-integration", "category": "uncategorized", "name": "stripe-integration", "description": "Implement Stripe payment processing for robust, PCI-compliant payment flows including checkout, subscriptions, and webhooks. Use when integrating Stripe payments, building subscription systems, or ...", @@ -7282,7 +7426,7 @@ }, { "id": "subagent-driven-development", - "path": "skills/subagent-driven-development", + "path": "skills\\subagent-driven-development", "category": "uncategorized", "name": "subagent-driven-development", "description": "Use when executing implementation plans with independent tasks in the current session", @@ -7291,7 +7435,7 @@ }, { "id": "supabase-automation", - "path": "skills/supabase-automation", + "path": "skills\\supabase-automation", "category": "uncategorized", "name": "supabase-automation", "description": "Automate Supabase database queries, table management, project administration, storage, edge functions, and SQL execution via Rube MCP (Composio). Always search tools first for current schemas.", @@ -7300,7 +7444,7 @@ }, { "id": "superpowers-lab", - "path": "skills/superpowers-lab", + "path": "skills\\superpowers-lab", "category": "uncategorized", "name": "superpowers-lab", "description": "Lab environment for Claude superpowers", @@ -7309,7 +7453,7 @@ }, { "id": "swiftui-expert-skill", - "path": "skills/swiftui-expert-skill", + "path": "skills\\swiftui-expert-skill", "category": "uncategorized", "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 buil...", @@ -7318,7 +7462,7 @@ }, { "id": "systematic-debugging", - "path": "skills/systematic-debugging", + "path": "skills\\systematic-debugging", "category": "uncategorized", "name": "systematic-debugging", "description": "Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes", @@ -7327,7 +7471,7 @@ }, { "id": "systems-programming-rust-project", - "path": "skills/systems-programming-rust-project", + "path": "skills\\systems-programming-rust-project", "category": "uncategorized", "name": "systems-programming-rust-project", "description": "You are a Rust project architecture expert specializing in scaffolding production-ready Rust applications. Generate complete project structures with cargo tooling, proper module organization, testing", @@ -7336,7 +7480,7 @@ }, { "id": "tailwind-design-system", - "path": "skills/tailwind-design-system", + "path": "skills\\tailwind-design-system", "category": "uncategorized", "name": "tailwind-design-system", "description": "Build scalable design systems with Tailwind CSS, design tokens, component libraries, and responsive patterns. Use when creating component libraries, implementing design systems, or standardizing UI...", @@ -7345,7 +7489,7 @@ }, { "id": "tailwind-patterns", - "path": "skills/tailwind-patterns", + "path": "skills\\tailwind-patterns", "category": "uncategorized", "name": "tailwind-patterns", "description": "Tailwind CSS v4 principles. CSS-first configuration, container queries, modern patterns, design token architecture.", @@ -7354,7 +7498,7 @@ }, { "id": "tavily-web", - "path": "skills/tavily-web", + "path": "skills\\tavily-web", "category": "uncategorized", "name": "tavily-web", "description": "Web search, content extraction, crawling, and research capabilities using Tavily API", @@ -7363,16 +7507,16 @@ }, { "id": "tdd-orchestrator", - "path": "skills/tdd-orchestrator", + "path": "skills\\tdd-orchestrator", "category": "uncategorized", - "name": "Tdd Orchestrator", - "description": "- Working on tdd orchestrator tasks or workflows - Needing guidance, best practices, or checklists for tdd orchestrator", + "name": "tdd-orchestrator", + "description": "Master TDD orchestrator specializing in red-green-refactor\ndiscipline, multi-agent workflow coordination, and comprehensive test-driven\ndevelopment practices. Enforces TDD best practices across teams with\nAI-assisted testing and modern frameworks. Use PROACTIVELY for TDD\nimplementation and governance.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "tdd-workflow", - "path": "skills/tdd-workflow", + "path": "skills\\tdd-workflow", "category": "uncategorized", "name": "tdd-workflow", "description": "Test-Driven Development workflow principles. RED-GREEN-REFACTOR cycle.", @@ -7381,7 +7525,7 @@ }, { "id": "tdd-workflows-tdd-cycle", - "path": "skills/tdd-workflows-tdd-cycle", + "path": "skills\\tdd-workflows-tdd-cycle", "category": "uncategorized", "name": "tdd-workflows-tdd-cycle", "description": "Use when working with tdd workflows tdd cycle", @@ -7390,7 +7534,7 @@ }, { "id": "tdd-workflows-tdd-green", - "path": "skills/tdd-workflows-tdd-green", + "path": "skills\\tdd-workflows-tdd-green", "category": "uncategorized", "name": "tdd-workflows-tdd-green", "description": "Implement the minimal code needed to make failing tests pass in the TDD green phase.", @@ -7399,7 +7543,7 @@ }, { "id": "tdd-workflows-tdd-red", - "path": "skills/tdd-workflows-tdd-red", + "path": "skills\\tdd-workflows-tdd-red", "category": "uncategorized", "name": "tdd-workflows-tdd-red", "description": "Generate failing tests for the TDD red phase to define expected behavior and edge cases.", @@ -7408,25 +7552,16 @@ }, { "id": "tdd-workflows-tdd-refactor", - "path": "skills/tdd-workflows-tdd-refactor", + "path": "skills\\tdd-workflows-tdd-refactor", "category": "uncategorized", "name": "tdd-workflows-tdd-refactor", "description": "Use when working with tdd workflows tdd refactor", "risk": "unknown", "source": "community" }, - { - "id": "team-composition-analysis", - "path": "skills/team-composition-analysis", - "category": "uncategorized", - "name": "Team Composition Analysis", - "description": "Design optimal team structures, hiring plans, compensation strategies, and equity allocation for early-stage startups from pre-seed through Series A.", - "risk": "unknown", - "source": "unknown" - }, { "id": "team-collaboration-issue", - "path": "skills/team-collaboration-issue", + "path": "skills\\team-collaboration-issue", "category": "uncategorized", "name": "team-collaboration-issue", "description": "You are a GitHub issue resolution expert specializing in systematic bug investigation, feature implementation, and collaborative development workflows. Your expertise spans issue triage, root cause an", @@ -7435,16 +7570,25 @@ }, { "id": "team-collaboration-standup-notes", - "path": "skills/team-collaboration-standup-notes", + "path": "skills\\team-collaboration-standup-notes", "category": "uncategorized", "name": "team-collaboration-standup-notes", "description": "You are an expert team communication specialist focused on async-first standup practices, AI-assisted note generation from commit history, and effective remote team coordination patterns.", "risk": "unknown", "source": "community" }, + { + "id": "team-composition-analysis", + "path": "skills\\team-composition-analysis", + "category": "uncategorized", + "name": "team-composition-analysis", + "description": "This skill should be used when the user asks to \\\\\\\"plan team\nstructure\", \"determine hiring needs\", \"design org chart\", \"calculate\ncompensation\", \"plan equity allocation\", or requests organizational design and\nheadcount planning for a startup.\n", + "risk": "unknown", + "source": "community" + }, { "id": "telegram-automation", - "path": "skills/telegram-automation", + "path": "skills\\telegram-automation", "category": "uncategorized", "name": "telegram-automation", "description": "Automate Telegram tasks via Rube MCP (Composio): send messages, manage chats, share photos/documents, and handle bot commands. Always search tools first for current schemas.", @@ -7453,7 +7597,7 @@ }, { "id": "telegram-bot-builder", - "path": "skills/telegram-bot-builder", + "path": "skills\\telegram-bot-builder", "category": "uncategorized", "name": "telegram-bot-builder", "description": "Expert in building Telegram bots that solve real problems - from simple automation to complex AI-powered bots. Covers bot architecture, the Telegram Bot API, user experience, monetization strategie...", @@ -7462,7 +7606,7 @@ }, { "id": "telegram-mini-app", - "path": "skills/telegram-mini-app", + "path": "skills\\telegram-mini-app", "category": "uncategorized", "name": "telegram-mini-app", "description": "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, payments, user authentication, and build...", @@ -7471,7 +7615,7 @@ }, { "id": "templates", - "path": "skills/app-builder/templates", + "path": "skills\\app-builder\\templates", "category": "app-builder", "name": "templates", "description": "Project scaffolding templates for new applications. Use when creating new projects from scratch. Contains 12 templates for various tech stacks.", @@ -7480,34 +7624,25 @@ }, { "id": "temporal-python-pro", - "path": "skills/temporal-python-pro", + "path": "skills\\temporal-python-pro", "category": "uncategorized", - "name": "Temporal Python Pro", - "description": "- Working on temporal python pro tasks or workflows - Needing guidance, best practices, or checklists for temporal python pro", + "name": "temporal-python-pro", + "description": "Master Temporal workflow orchestration with Python SDK. Implements\ndurable workflows, saga patterns, and distributed transactions. Covers\nasync/await, testing strategies, and production deployment. Use PROACTIVELY\nfor workflow design, microservice orchestration, or long-running processes.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "temporal-python-testing", - "path": "skills/temporal-python-testing", + "path": "skills\\temporal-python-testing", "category": "uncategorized", "name": "temporal-python-testing", "description": "Test Temporal workflows with pytest, time-skipping, and mocking strategies. Covers unit testing, integration testing, replay testing, and local development setup. Use when implementing Temporal wor...", "risk": "unknown", "source": "community" }, - { - "id": "terraform-specialist", - "path": "skills/terraform-specialist", - "category": "uncategorized", - "name": "Terraform Specialist", - "description": "You are a Terraform/OpenTofu specialist focused on advanced infrastructure automation, state management, and modern IaC practices.", - "risk": "unknown", - "source": "unknown" - }, { "id": "terraform-aws-modules", - "path": "skills/terraform-aws-modules", + "path": "skills\\terraform-aws-modules", "category": "uncategorized", "name": "terraform-aws-modules", "description": "Terraform module creation for AWS \u2014 reusable modules, state management, and HCL best practices. Use when building or reviewing Terraform AWS infrastructure.", @@ -7516,7 +7651,7 @@ }, { "id": "terraform-infrastructure", - "path": "skills/terraform-infrastructure", + "path": "skills\\terraform-infrastructure", "category": "uncategorized", "name": "terraform-infrastructure", "description": "Terraform infrastructure as code workflow for provisioning cloud resources, creating reusable modules, and managing infrastructure at scale.", @@ -7525,7 +7660,7 @@ }, { "id": "terraform-module-library", - "path": "skills/terraform-module-library", + "path": "skills\\terraform-module-library", "category": "uncategorized", "name": "terraform-module-library", "description": "Build reusable Terraform modules for AWS, Azure, and GCP infrastructure following infrastructure-as-code best practices. Use when creating infrastructure modules, standardizing cloud provisioning, ...", @@ -7534,7 +7669,7 @@ }, { "id": "terraform-skill", - "path": "skills/terraform-skill", + "path": "skills\\terraform-skill", "category": "uncategorized", "name": "terraform-skill", "description": "Terraform infrastructure as code best practices", @@ -7542,17 +7677,26 @@ "source": "https://github.com/antonbabenko/terraform-skill" }, { - "id": "test-automator", - "path": "skills/test-automator", + "id": "terraform-specialist", + "path": "skills\\terraform-specialist", "category": "uncategorized", - "name": "Test Automator", - "description": "- Working on test automator tasks or workflows - Needing guidance, best practices, or checklists for test automator", + "name": "terraform-specialist", + "description": "Expert Terraform/OpenTofu specialist mastering advanced IaC\nautomation, state management, and enterprise infrastructure patterns. Handles\ncomplex module design, multi-cloud deployments, GitOps workflows, policy as\ncode, and CI/CD integration. Covers migration strategies, security best\npractices, and modern IaC ecosystems. Use PROACTIVELY for advanced IaC, state\nmanagement, or infrastructure automation.\n", "risk": "unknown", - "source": "unknown" + "source": "community" + }, + { + "id": "test-automator", + "path": "skills\\test-automator", + "category": "uncategorized", + "name": "test-automator", + "description": "Master AI-powered test automation with modern frameworks,\nself-healing tests, and comprehensive quality engineering. Build scalable\ntesting strategies with advanced CI/CD integration. Use PROACTIVELY for\ntesting automation or quality assurance.\n", + "risk": "unknown", + "source": "community" }, { "id": "test-driven-development", - "path": "skills/test-driven-development", + "path": "skills\\test-driven-development", "category": "uncategorized", "name": "test-driven-development", "description": "Use when implementing any feature or bugfix, before writing implementation code", @@ -7561,7 +7705,7 @@ }, { "id": "test-fixing", - "path": "skills/test-fixing", + "path": "skills\\test-fixing", "category": "uncategorized", "name": "test-fixing", "description": "Run tests and systematically fix all failing tests using smart error grouping. Use when user asks to fix failing tests, mentions test failures, runs test suite and failures occur, or requests to ma...", @@ -7570,7 +7714,7 @@ }, { "id": "testing-patterns", - "path": "skills/testing-patterns", + "path": "skills\\testing-patterns", "category": "uncategorized", "name": "testing-patterns", "description": "Jest testing patterns, factory functions, mocking strategies, and TDD workflow. Use when writing unit tests, creating test factories, or following TDD red-green-refactor cycle.", @@ -7579,7 +7723,7 @@ }, { "id": "testing-qa", - "path": "skills/testing-qa", + "path": "skills\\testing-qa", "category": "uncategorized", "name": "testing-qa", "description": "Comprehensive testing and QA workflow covering unit testing, integration testing, E2E testing, browser automation, and quality assurance.", @@ -7588,7 +7732,7 @@ }, { "id": "theme-factory", - "path": "skills/theme-factory", + "path": "skills\\theme-factory", "category": "uncategorized", "name": "theme-factory", "description": "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/fonts that you can apply to any artifac...", @@ -7597,7 +7741,7 @@ }, { "id": "threat-mitigation-mapping", - "path": "skills/threat-mitigation-mapping", + "path": "skills\\threat-mitigation-mapping", "category": "uncategorized", "name": "threat-mitigation-mapping", "description": "Map identified threats to appropriate security controls and mitigations. Use when prioritizing security investments, creating remediation plans, or validating control effectiveness.", @@ -7606,7 +7750,7 @@ }, { "id": "threat-modeling-expert", - "path": "skills/threat-modeling-expert", + "path": "skills\\threat-modeling-expert", "category": "uncategorized", "name": "threat-modeling-expert", "description": "Expert in threat modeling methodologies, security architecture review, and risk assessment. Masters STRIDE, PASTA, attack trees, and security requirement extraction. Use for security architecture r...", @@ -7615,7 +7759,7 @@ }, { "id": "threejs-skills", - "path": "skills/threejs-skills", + "path": "skills\\threejs-skills", "category": "uncategorized", "name": "threejs-skills", "description": "Create 3D scenes, interactive experiences, and visual effects using Three.js. Use when user requests 3D graphics, WebGL experiences, 3D visualizations, animations, or interactive 3D elements.", @@ -7624,7 +7768,7 @@ }, { "id": "tiktok-automation", - "path": "skills/tiktok-automation", + "path": "skills\\tiktok-automation", "category": "uncategorized", "name": "tiktok-automation", "description": "Automate TikTok tasks via Rube MCP (Composio): upload/publish videos, post photos, manage content, and view user profiles/stats. Always search tools first for current schemas.", @@ -7633,7 +7777,7 @@ }, { "id": "todoist-automation", - "path": "skills/todoist-automation", + "path": "skills\\todoist-automation", "category": "uncategorized", "name": "todoist-automation", "description": "Automate Todoist task management, projects, sections, filtering, and bulk operations via Rube MCP (Composio). Always search tools first for current schemas.", @@ -7642,7 +7786,7 @@ }, { "id": "tool-design", - "path": "skills/tool-design", + "path": "skills\\tool-design", "category": "uncategorized", "name": "tool-design", "description": "Build tools that agents can use effectively, including architectural reduction patterns", @@ -7651,7 +7795,7 @@ }, { "id": "top-web-vulnerabilities", - "path": "skills/top-web-vulnerabilities", + "path": "skills\\top-web-vulnerabilities", "category": "uncategorized", "name": "top-web-vulnerabilities", "description": "This skill should be used when the user asks to \"identify web application vulnerabilities\", \"explain common security flaws\", \"understand vulnerability categories\", \"learn about inject...", @@ -7660,16 +7804,16 @@ }, { "id": "track-management", - "path": "skills/track-management", + "path": "skills\\track-management", "category": "uncategorized", - "name": "Track Management", - "description": "Guide for creating, managing, and completing Conductor tracks - the logical work units that organize features, bugs, and refactors through specification, planning, and implementation phases.", + "name": "track-management", + "description": "Use this skill when creating, managing, or working with Conductor\ntracks - the logical work units for features, bugs, and refactors. Applies to\nspec.md, plan.md, and track lifecycle operations.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "trello-automation", - "path": "skills/trello-automation", + "path": "skills\\trello-automation", "category": "uncategorized", "name": "trello-automation", "description": "Automate Trello boards, cards, and workflows via Rube MCP (Composio). Create cards, manage lists, assign members, and search across boards programmatically.", @@ -7678,7 +7822,7 @@ }, { "id": "trigger-dev", - "path": "skills/trigger-dev", + "path": "skills\\trigger-dev", "category": "uncategorized", "name": "trigger-dev", "description": "Trigger.dev expert for background jobs, AI workflows, and reliable async execution with excellent developer experience and TypeScript-first design. Use when: trigger.dev, trigger dev, background ta...", @@ -7687,7 +7831,7 @@ }, { "id": "turborepo-caching", - "path": "skills/turborepo-caching", + "path": "skills\\turborepo-caching", "category": "uncategorized", "name": "turborepo-caching", "description": "Configure Turborepo for efficient monorepo builds with local and remote caching. Use when setting up Turborepo, optimizing build pipelines, or implementing distributed caching.", @@ -7696,16 +7840,16 @@ }, { "id": "tutorial-engineer", - "path": "skills/tutorial-engineer", + "path": "skills\\tutorial-engineer", "category": "uncategorized", - "name": "Tutorial Engineer", - "description": "- Working on tutorial engineer tasks or workflows - Needing guidance, best practices, or checklists for tutorial engineer", + "name": "tutorial-engineer", + "description": "Creates step-by-step tutorials and educational content from code.\nTransforms complex concepts into progressive learning experiences with\nhands-on examples. Use PROACTIVELY for onboarding guides, feature tutorials,\nor concept explanations.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "twilio-communications", - "path": "skills/twilio-communications", + "path": "skills\\twilio-communications", "category": "uncategorized", "name": "twilio-communications", "description": "Build communication features with Twilio: SMS messaging, voice calls, WhatsApp Business API, and user verification (2FA). Covers the full spectrum from simple notifications to complex IVR systems a...", @@ -7714,34 +7858,16 @@ }, { "id": "twitter-automation", - "path": "skills/twitter-automation", + "path": "skills\\twitter-automation", "category": "uncategorized", "name": "twitter-automation", "description": "Automate Twitter/X tasks via Rube MCP (Composio): posts, search, users, bookmarks, lists, media. Always search tools first for current schemas.", "risk": "unknown", "source": "community" }, - { - "id": "typescript-expert", - "path": "skills/typescript-expert", - "category": "uncategorized", - "name": "Typescript Expert", - "description": "You are an advanced TypeScript expert with deep, practical knowledge of type-level programming, performance optimization, and real-world problem solving based on current best practices.", - "risk": "unknown", - "source": "unknown" - }, - { - "id": "typescript-pro", - "path": "skills/typescript-pro", - "category": "uncategorized", - "name": "Typescript Pro", - "description": "You are a TypeScript expert specializing in advanced typing and enterprise-grade development.", - "risk": "unknown", - "source": "unknown" - }, { "id": "typescript-advanced-types", - "path": "skills/typescript-advanced-types", + "path": "skills\\typescript-advanced-types", "category": "uncategorized", "name": "typescript-advanced-types", "description": "Master TypeScript's advanced type system including generics, conditional types, mapped types, template literals, and utility types for building type-safe applications. Use when implementing complex...", @@ -7749,44 +7875,62 @@ "source": "community" }, { - "id": "ui-ux-designer", - "path": "skills/ui-ux-designer", + "id": "typescript-expert", + "path": "skills\\typescript-expert", "category": "uncategorized", - "name": "Ui Ux Designer", - "description": "- Working on ui ux designer tasks or workflows - Needing guidance, best practices, or checklists for ui ux designer", + "name": "typescript-expert", + "description": "TypeScript and JavaScript expert with deep knowledge of type-level programming, performance optimization, monorepo management, migration strategies, and modern tooling. Use PROACTIVELY for any TypeScript/JavaScript issues including complex type gymnastics, build performance, debugging, and architectural decisions. If a specialized expert is a better fit, I will recommend switching and stop.", "risk": "unknown", - "source": "unknown" + "source": "community" }, { - "id": "ui-visual-validator", - "path": "skills/ui-visual-validator", + "id": "typescript-pro", + "path": "skills\\typescript-pro", "category": "uncategorized", - "name": "Ui Visual Validator", - "description": "- Working on ui visual validator tasks or workflows - Needing guidance, best practices, or checklists for ui visual validator", + "name": "typescript-pro", + "description": "Master TypeScript with advanced types, generics, and strict type\nsafety. Handles complex type systems, decorators, and enterprise-grade\npatterns. Use PROACTIVELY for TypeScript architecture, type inference\noptimization, or advanced typing patterns.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "ui-skills", - "path": "skills/ui-skills", + "path": "skills\\ui-skills", "category": "uncategorized", "name": "ui-skills", "description": "Opinionated, evolving constraints to guide agents when building interfaces", "risk": "safe", "source": "https://github.com/ibelick/ui-skills" }, + { + "id": "ui-ux-designer", + "path": "skills\\ui-ux-designer", + "category": "uncategorized", + "name": "ui-ux-designer", + "description": "Create interface designs, wireframes, and design systems. Masters\nuser research, accessibility standards, and modern design tools. Specializes\nin design tokens, component libraries, and inclusive design. Use PROACTIVELY\nfor design systems, user flows, or interface optimization.\n", + "risk": "unknown", + "source": "community" + }, { "id": "ui-ux-pro-max", - "path": "skills/ui-ux-pro-max", + "path": "skills\\ui-ux-pro-max", "category": "uncategorized", "name": "ui-ux-pro-max", "description": "UI/UX design intelligence. 50 styles, 21 palettes, 50 font pairings, 20 charts, 9 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui). Actions: plan, build, cr...", "risk": "unknown", "source": "community" }, + { + "id": "ui-visual-validator", + "path": "skills\\ui-visual-validator", + "category": "uncategorized", + "name": "ui-visual-validator", + "description": "Rigorous visual validation expert specializing in UI testing,\ndesign system compliance, and accessibility verification. Masters screenshot\nanalysis, visual regression testing, and component validation. Use PROACTIVELY\nto verify UI modifications have achieved their intended goals through\ncomprehensive visual analysis.\n", + "risk": "unknown", + "source": "community" + }, { "id": "unit-testing-test-generate", - "path": "skills/unit-testing-test-generate", + "path": "skills\\unit-testing-test-generate", "category": "uncategorized", "name": "unit-testing-test-generate", "description": "Generate comprehensive, maintainable unit tests across languages with strong coverage and edge case focus.", @@ -7795,16 +7939,16 @@ }, { "id": "unity-developer", - "path": "skills/unity-developer", + "path": "skills\\unity-developer", "category": "uncategorized", - "name": "Unity Developer", - "description": "- Working on unity developer tasks or workflows - Needing guidance, best practices, or checklists for unity developer", + "name": "unity-developer", + "description": "Build Unity games with optimized C# scripts, efficient rendering,\nand proper asset management. Masters Unity 6 LTS, URP/HDRP pipelines, and\ncross-platform deployment. Handles gameplay systems, UI implementation, and\nplatform optimization. Use PROACTIVELY for Unity performance issues, game\nmechanics, or cross-platform builds.\n", "risk": "unknown", - "source": "unknown" + "source": "community" }, { "id": "unity-ecs-patterns", - "path": "skills/unity-ecs-patterns", + "path": "skills\\unity-ecs-patterns", "category": "uncategorized", "name": "unity-ecs-patterns", "description": "Master Unity ECS (Entity Component System) with DOTS, Jobs, and Burst for high-performance game development. Use when building data-oriented games, optimizing performance, or working with large ent...", @@ -7813,7 +7957,7 @@ }, { "id": "unreal-engine-cpp-pro", - "path": "skills/unreal-engine-cpp-pro", + "path": "skills\\unreal-engine-cpp-pro", "category": "uncategorized", "name": "unreal-engine-cpp-pro", "description": "Expert guide for Unreal Engine 5.x C++ development, covering UObject hygiene, performance patterns, and best practices.", @@ -7822,7 +7966,7 @@ }, { "id": "upgrading-expo", - "path": "skills/upgrading-expo", + "path": "skills\\upgrading-expo", "category": "uncategorized", "name": "upgrading-expo", "description": "Upgrade Expo SDK versions", @@ -7831,7 +7975,7 @@ }, { "id": "upstash-qstash", - "path": "skills/upstash-qstash", + "path": "skills\\upstash-qstash", "category": "uncategorized", "name": "upstash-qstash", "description": "Upstash QStash expert for serverless message queues, scheduled jobs, and reliable HTTP-based task delivery without managing infrastructure. Use when: qstash, upstash queue, serverless cron, schedul...", @@ -7840,7 +7984,7 @@ }, { "id": "using-git-worktrees", - "path": "skills/using-git-worktrees", + "path": "skills\\using-git-worktrees", "category": "uncategorized", "name": "using-git-worktrees", "description": "Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verifi...", @@ -7849,7 +7993,7 @@ }, { "id": "using-neon", - "path": "skills/using-neon", + "path": "skills\\using-neon", "category": "uncategorized", "name": "using-neon", "description": "Guides and best practices for working with Neon Serverless Postgres. Covers getting started, local development with Neon, choosing a connection method, Neon features, authentication (@neondatabase/...", @@ -7858,7 +8002,7 @@ }, { "id": "using-superpowers", - "path": "skills/using-superpowers", + "path": "skills\\using-superpowers", "category": "uncategorized", "name": "using-superpowers", "description": "Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions", @@ -7867,7 +8011,7 @@ }, { "id": "uv-package-manager", - "path": "skills/uv-package-manager", + "path": "skills\\uv-package-manager", "category": "uncategorized", "name": "uv-package-manager", "description": "Master the uv package manager for fast Python dependency management, virtual environments, and modern Python project workflows. Use when setting up Python projects, managing dependencies, or optimi...", @@ -7876,7 +8020,7 @@ }, { "id": "varlock-claude-skill", - "path": "skills/varlock-claude-skill", + "path": "skills\\varlock-claude-skill", "category": "uncategorized", "name": "varlock-claude-skill", "description": "Secure environment variable management ensuring secrets are never exposed in Claude sessions, terminals, logs, or git commits", @@ -7885,7 +8029,7 @@ }, { "id": "vector-database-engineer", - "path": "skills/vector-database-engineer", + "path": "skills\\vector-database-engineer", "category": "uncategorized", "name": "vector-database-engineer", "description": "Expert in vector databases, embedding strategies, and semantic search implementation. Masters Pinecone, Weaviate, Qdrant, Milvus, and pgvector for RAG applications, recommendation systems, and similar", @@ -7894,7 +8038,7 @@ }, { "id": "vector-index-tuning", - "path": "skills/vector-index-tuning", + "path": "skills\\vector-index-tuning", "category": "uncategorized", "name": "vector-index-tuning", "description": "Optimize vector index performance for latency, recall, and memory. Use when tuning HNSW parameters, selecting quantization strategies, or scaling vector search infrastructure.", @@ -7903,7 +8047,7 @@ }, { "id": "vercel-automation", - "path": "skills/vercel-automation", + "path": "skills\\vercel-automation", "category": "uncategorized", "name": "vercel-automation", "description": "Automate Vercel tasks via Rube MCP (Composio): manage deployments, domains, DNS, env vars, projects, and teams. Always search tools first for current schemas.", @@ -7912,7 +8056,7 @@ }, { "id": "vercel-deploy-claimable", - "path": "skills/vercel-deploy-claimable", + "path": "skills\\vercel-deploy-claimable", "category": "uncategorized", "name": "vercel-deploy-claimable", "description": "Deploy applications and websites to Vercel. Use this skill when the user requests deployment actions such as 'Deploy my app', 'Deploy this to production', 'Create a preview deployment', 'Deploy and...", @@ -7921,7 +8065,7 @@ }, { "id": "vercel-deployment", - "path": "skills/vercel-deployment", + "path": "skills\\vercel-deployment", "category": "uncategorized", "name": "vercel-deployment", "description": "Expert knowledge for deploying to Vercel with Next.js Use when: vercel, deploy, deployment, hosting, production.", @@ -7930,7 +8074,7 @@ }, { "id": "verification-before-completion", - "path": "skills/verification-before-completion", + "path": "skills\\verification-before-completion", "category": "uncategorized", "name": "verification-before-completion", "description": "Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evide...", @@ -7939,7 +8083,7 @@ }, { "id": "vexor", - "path": "skills/vexor", + "path": "skills\\vexor", "category": "uncategorized", "name": "vexor", "description": "Vector-powered CLI for semantic file search with a Claude/Codex skill", @@ -7948,7 +8092,7 @@ }, { "id": "viral-generator-builder", - "path": "skills/viral-generator-builder", + "path": "skills\\viral-generator-builder", "category": "uncategorized", "name": "viral-generator-builder", "description": "Expert in building shareable generator tools that go viral - name generators, quiz makers, avatar creators, personality tests, and calculator tools. Covers the psychology of sharing, viral mechanic...", @@ -7957,7 +8101,7 @@ }, { "id": "voice-agents", - "path": "skills/voice-agents", + "path": "skills\\voice-agents", "category": "uncategorized", "name": "voice-agents", "description": "Voice agents represent the frontier of AI interaction - humans speaking naturally with AI systems. The challenge isn't just speech recognition and synthesis, it's achieving natural conversation flo...", @@ -7966,7 +8110,7 @@ }, { "id": "voice-ai-development", - "path": "skills/voice-ai-development", + "path": "skills\\voice-ai-development", "category": "uncategorized", "name": "voice-ai-development", "description": "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 transcription, ElevenLabs for synthesis...", @@ -7975,7 +8119,7 @@ }, { "id": "voice-ai-engine-development", - "path": "skills/voice-ai-engine-development", + "path": "skills\\voice-ai-engine-development", "category": "uncategorized", "name": "voice-ai-engine-development", "description": "Build real-time conversational AI voice engines using async worker pipelines, streaming transcription, LLM agents, and TTS synthesis with interrupt handling and multi-provider support", @@ -7984,7 +8128,7 @@ }, { "id": "vr-ar", - "path": "skills/game-development/vr-ar", + "path": "skills\\game-development\\vr-ar", "category": "game-development", "name": "vr-ar", "description": "VR/AR development principles. Comfort, interaction, performance requirements.", @@ -7993,7 +8137,7 @@ }, { "id": "vulnerability-scanner", - "path": "skills/vulnerability-scanner", + "path": "skills\\vulnerability-scanner", "category": "uncategorized", "name": "vulnerability-scanner", "description": "Advanced vulnerability analysis principles. OWASP 2025, Supply Chain Security, attack surface mapping, risk prioritization.", @@ -8002,7 +8146,7 @@ }, { "id": "wcag-audit-patterns", - "path": "skills/wcag-audit-patterns", + "path": "skills\\wcag-audit-patterns", "category": "uncategorized", "name": "wcag-audit-patterns", "description": "Conduct WCAG 2.2 accessibility audits with automated testing, manual verification, and remediation guidance. Use when auditing websites for accessibility, fixing WCAG violations, or implementing ac...", @@ -8011,7 +8155,7 @@ }, { "id": "web-artifacts-builder", - "path": "skills/web-artifacts-builder", + "path": "skills\\web-artifacts-builder", "category": "uncategorized", "name": "web-artifacts-builder", "description": "Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state ma...", @@ -8020,7 +8164,7 @@ }, { "id": "web-design-guidelines", - "path": "skills/web-design-guidelines", + "path": "skills\\web-design-guidelines", "category": "uncategorized", "name": "web-design-guidelines", "description": "Review UI code for Web Interface Guidelines compliance. Use when asked to \\\"review my UI\\\", \\\"check accessibility\\\", \\\"audit design\\\", \\\"review UX\\\", or \\\"check my site aga...", @@ -8029,7 +8173,7 @@ }, { "id": "web-games", - "path": "skills/game-development/web-games", + "path": "skills\\game-development\\web-games", "category": "game-development", "name": "web-games", "description": "Web browser game development principles. Framework selection, WebGPU, optimization, PWA.", @@ -8038,7 +8182,7 @@ }, { "id": "web-performance-optimization", - "path": "skills/web-performance-optimization", + "path": "skills\\web-performance-optimization", "category": "uncategorized", "name": "web-performance-optimization", "description": "Optimize website and web application performance including loading speed, Core Web Vitals, bundle size, caching strategies, and runtime performance", @@ -8047,7 +8191,7 @@ }, { "id": "web-security-testing", - "path": "skills/web-security-testing", + "path": "skills\\web-security-testing", "category": "uncategorized", "name": "web-security-testing", "description": "Web application security testing workflow for OWASP Top 10 vulnerabilities including injection, XSS, authentication flaws, and access control issues.", @@ -8056,7 +8200,7 @@ }, { "id": "web3-testing", - "path": "skills/web3-testing", + "path": "skills\\web3-testing", "category": "uncategorized", "name": "web3-testing", "description": "Test smart contracts comprehensively using Hardhat and Foundry with unit tests, integration tests, and mainnet forking. Use when testing Solidity contracts, setting up blockchain test suites, or va...", @@ -8065,7 +8209,7 @@ }, { "id": "webapp-testing", - "path": "skills/webapp-testing", + "path": "skills\\webapp-testing", "category": "uncategorized", "name": "webapp-testing", "description": "Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browse...", @@ -8074,7 +8218,7 @@ }, { "id": "webflow-automation", - "path": "skills/webflow-automation", + "path": "skills\\webflow-automation", "category": "uncategorized", "name": "webflow-automation", "description": "Automate Webflow CMS collections, site publishing, page management, asset uploads, and ecommerce orders via Rube MCP (Composio). Always search tools first for current schemas.", @@ -8083,7 +8227,7 @@ }, { "id": "whatsapp-automation", - "path": "skills/whatsapp-automation", + "path": "skills\\whatsapp-automation", "category": "uncategorized", "name": "whatsapp-automation", "description": "Automate WhatsApp Business tasks via Rube MCP (Composio): send messages, manage templates, upload media, and handle contacts. Always search tools first for current schemas.", @@ -8092,7 +8236,7 @@ }, { "id": "wiki-architect", - "path": "skills/wiki-architect", + "path": "skills\\wiki-architect", "category": "uncategorized", "name": "wiki-architect", "description": "Analyzes code repositories and generates hierarchical documentation structures with onboarding guides. Use when the user wants to create a wiki, generate documentation, map a codebase structure, or...", @@ -8101,7 +8245,7 @@ }, { "id": "wiki-changelog", - "path": "skills/wiki-changelog", + "path": "skills\\wiki-changelog", "category": "uncategorized", "name": "wiki-changelog", "description": "Analyzes git commit history and generates structured changelogs categorized by change type. Use when the user asks about recent changes, wants a changelog, or needs to understand what changed in th...", @@ -8110,7 +8254,7 @@ }, { "id": "wiki-onboarding", - "path": "skills/wiki-onboarding", + "path": "skills\\wiki-onboarding", "category": "uncategorized", "name": "wiki-onboarding", "description": "Generates two complementary onboarding guides \u2014 a Principal-Level architectural deep-dive and a Zero-to-Hero contributor walkthrough. Use when the user wants onboarding documentation fo...", @@ -8119,7 +8263,7 @@ }, { "id": "wiki-page-writer", - "path": "skills/wiki-page-writer", + "path": "skills\\wiki-page-writer", "category": "uncategorized", "name": "wiki-page-writer", "description": "Generates rich technical documentation pages with dark-mode Mermaid diagrams, source code citations, and first-principles depth. Use when writing documentation, generating wiki pages, creating tech...", @@ -8128,7 +8272,7 @@ }, { "id": "wiki-qa", - "path": "skills/wiki-qa", + "path": "skills\\wiki-qa", "category": "uncategorized", "name": "wiki-qa", "description": "Answers questions about a code repository using source file analysis. Use when the user asks a question about how something works, wants to understand a component, or needs help navigating the code...", @@ -8137,7 +8281,7 @@ }, { "id": "wiki-researcher", - "path": "skills/wiki-researcher", + "path": "skills\\wiki-researcher", "category": "uncategorized", "name": "wiki-researcher", "description": "Conducts multi-turn iterative deep research on specific topics within a codebase with zero tolerance for shallow analysis. Use when the user wants an in-depth investigation, needs to understand how...", @@ -8146,7 +8290,7 @@ }, { "id": "wiki-vitepress", - "path": "skills/wiki-vitepress", + "path": "skills\\wiki-vitepress", "category": "uncategorized", "name": "wiki-vitepress", "description": "Packages generated wiki Markdown into a VitePress static site with dark theme, dark-mode Mermaid diagrams with click-to-zoom, and production build output. Use when the user wants to create a browsa...", @@ -8155,7 +8299,7 @@ }, { "id": "windows-privilege-escalation", - "path": "skills/windows-privilege-escalation", + "path": "skills\\windows-privilege-escalation", "category": "uncategorized", "name": "windows-privilege-escalation", "description": "This skill should be used when the user asks to \"escalate privileges on Windows,\" \"find Windows privesc vectors,\" \"enumerate Windows for privilege escalation,\" \"exploit Windows miscon...", @@ -8164,7 +8308,7 @@ }, { "id": "wireshark-analysis", - "path": "skills/wireshark-analysis", + "path": "skills\\wireshark-analysis", "category": "uncategorized", "name": "wireshark-analysis", "description": "This skill should be used when the user asks to \"analyze network traffic with Wireshark\", \"capture packets for troubleshooting\", \"filter PCAP files\", \"follow TCP/UDP streams\", \"dete...", @@ -8173,7 +8317,7 @@ }, { "id": "wordpress", - "path": "skills/wordpress", + "path": "skills\\wordpress", "category": "uncategorized", "name": "wordpress", "description": "Complete WordPress development workflow covering theme development, plugin creation, WooCommerce integration, performance optimization, and security hardening.", @@ -8182,7 +8326,7 @@ }, { "id": "wordpress-penetration-testing", - "path": "skills/wordpress-penetration-testing", + "path": "skills\\wordpress-penetration-testing", "category": "uncategorized", "name": "wordpress-penetration-testing", "description": "This skill should be used when the user asks to \"pentest WordPress sites\", \"scan WordPress for vulnerabilities\", \"enumerate WordPress users, themes, or plugins\", \"exploit WordPress vu...", @@ -8191,7 +8335,7 @@ }, { "id": "wordpress-plugin-development", - "path": "skills/wordpress-plugin-development", + "path": "skills\\wordpress-plugin-development", "category": "uncategorized", "name": "wordpress-plugin-development", "description": "WordPress plugin development workflow covering plugin architecture, hooks, admin interfaces, REST API, and security best practices.", @@ -8200,7 +8344,7 @@ }, { "id": "wordpress-theme-development", - "path": "skills/wordpress-theme-development", + "path": "skills\\wordpress-theme-development", "category": "uncategorized", "name": "wordpress-theme-development", "description": "WordPress theme development workflow covering theme architecture, template hierarchy, custom post types, block editor support, and responsive design.", @@ -8209,25 +8353,16 @@ }, { "id": "wordpress-woocommerce-development", - "path": "skills/wordpress-woocommerce-development", + "path": "skills\\wordpress-woocommerce-development", "category": "uncategorized", "name": "wordpress-woocommerce-development", "description": "WooCommerce store development workflow covering store setup, payment integration, shipping configuration, and customization.", "risk": "safe", "source": "personal" }, - { - "id": "workflow-patterns", - "path": "skills/workflow-patterns", - "category": "uncategorized", - "name": "Workflow Patterns", - "description": "Guide for implementing tasks using Conductor's TDD workflow, managing phase checkpoints, handling git commits, and executing the verification protocol that ensures quality throughout implementation.", - "risk": "unknown", - "source": "unknown" - }, { "id": "workflow-automation", - "path": "skills/workflow-automation", + "path": "skills\\workflow-automation", "category": "uncategorized", "name": "workflow-automation", "description": "Workflow automation is the infrastructure that makes AI agents reliable. Without durable execution, a network hiccup during a 10-step payment flow means lost money and angry customers. With it, wor...", @@ -8236,16 +8371,25 @@ }, { "id": "workflow-orchestration-patterns", - "path": "skills/workflow-orchestration-patterns", + "path": "skills\\workflow-orchestration-patterns", "category": "uncategorized", "name": "workflow-orchestration-patterns", "description": "Design durable workflows with Temporal for distributed systems. Covers workflow vs activity separation, saga patterns, state management, and determinism constraints. Use when building long-running ...", "risk": "unknown", "source": "community" }, + { + "id": "workflow-patterns", + "path": "skills\\workflow-patterns", + "category": "uncategorized", + "name": "workflow-patterns", + "description": "Use this skill when implementing tasks according to Conductor's TDD\nworkflow, handling phase checkpoints, managing git commits for tasks, or\nunderstanding the verification protocol.\n", + "risk": "unknown", + "source": "community" + }, { "id": "wrike-automation", - "path": "skills/wrike-automation", + "path": "skills\\wrike-automation", "category": "uncategorized", "name": "wrike-automation", "description": "Automate Wrike project management via Rube MCP (Composio): create tasks/folders, manage projects, assign work, and track progress. Always search tools first for current schemas.", @@ -8254,7 +8398,7 @@ }, { "id": "writer", - "path": "skills/libreoffice/writer", + "path": "skills\\libreoffice\\writer", "category": "libreoffice", "name": "writer", "description": "Document creation, format conversion (ODT/DOCX/PDF), mail merge, and automation with LibreOffice Writer.", @@ -8263,7 +8407,7 @@ }, { "id": "writing-plans", - "path": "skills/writing-plans", + "path": "skills\\writing-plans", "category": "uncategorized", "name": "writing-plans", "description": "Use when you have a spec or requirements for a multi-step task, before touching code", @@ -8272,7 +8416,7 @@ }, { "id": "writing-skills", - "path": "skills/writing-skills", + "path": "skills\\writing-skills", "category": "uncategorized", "name": "writing-skills", "description": "Use when creating, updating, or improving agent skills.", @@ -8281,7 +8425,7 @@ }, { "id": "x-article-publisher-skill", - "path": "skills/x-article-publisher-skill", + "path": "skills\\x-article-publisher-skill", "category": "uncategorized", "name": "x-article-publisher-skill", "description": "Publish articles to X/Twitter", @@ -8290,7 +8434,7 @@ }, { "id": "xlsx-official", - "path": "skills/xlsx-official", + "path": "skills\\xlsx-official", "category": "uncategorized", "name": "xlsx-official", "description": "Comprehensive spreadsheet creation, editing, and analysis with support for formulas, formatting, data analysis, and visualization. When Claude needs to work with spreadsheets (.xlsx, .xlsm, .csv, ....", @@ -8299,7 +8443,7 @@ }, { "id": "xss-html-injection", - "path": "skills/xss-html-injection", + "path": "skills\\xss-html-injection", "category": "uncategorized", "name": "xss-html-injection", "description": "This skill should be used when the user asks to \"test for XSS vulnerabilities\", \"perform cross-site scripting attacks\", \"identify HTML injection flaws\", \"exploit client-side injection...", @@ -8308,7 +8452,7 @@ }, { "id": "youtube-automation", - "path": "skills/youtube-automation", + "path": "skills\\youtube-automation", "category": "uncategorized", "name": "youtube-automation", "description": "Automate YouTube tasks via Rube MCP (Composio): upload videos, manage playlists, search content, get analytics, and handle comments. Always search tools first for current schemas.", @@ -8317,7 +8461,7 @@ }, { "id": "youtube-summarizer", - "path": "skills/youtube-summarizer", + "path": "skills\\youtube-summarizer", "category": "uncategorized", "name": "youtube-summarizer", "description": "Extract transcripts from YouTube videos and generate comprehensive, detailed summaries using intelligent analysis frameworks", @@ -8326,7 +8470,7 @@ }, { "id": "zapier-make-patterns", - "path": "skills/zapier-make-patterns", + "path": "skills\\zapier-make-patterns", "category": "uncategorized", "name": "zapier-make-patterns", "description": "No-code automation democratizes workflow building. Zapier and Make (formerly Integromat) let non-developers automate business processes without writing code. But no-code doesn't mean no-complexity ...", @@ -8335,7 +8479,7 @@ }, { "id": "zendesk-automation", - "path": "skills/zendesk-automation", + "path": "skills\\zendesk-automation", "category": "uncategorized", "name": "zendesk-automation", "description": "Automate Zendesk tasks via Rube MCP (Composio): tickets, users, organizations, replies. Always search tools first for current schemas.", @@ -8344,7 +8488,7 @@ }, { "id": "zoho-crm-automation", - "path": "skills/zoho-crm-automation", + "path": "skills\\zoho-crm-automation", "category": "uncategorized", "name": "zoho-crm-automation", "description": "Automate Zoho CRM tasks via Rube MCP (Composio): create/update records, search contacts, manage leads, and convert leads. Always search tools first for current schemas.", @@ -8353,7 +8497,7 @@ }, { "id": "zoom-automation", - "path": "skills/zoom-automation", + "path": "skills\\zoom-automation", "category": "uncategorized", "name": "zoom-automation", "description": "Automate Zoom meeting creation, management, recordings, webinars, and participant tracking via Rube MCP (Composio). Always search tools first for current schemas.", @@ -8362,7 +8506,7 @@ }, { "id": "zustand-store-ts", - "path": "skills/zustand-store-ts", + "path": "skills\\zustand-store-ts", "category": "uncategorized", "name": "zustand-store-ts", "description": "Create Zustand stores with TypeScript, subscribeWithSelector middleware, and proper state/action separation. Use when building React state management, creating global stores, or implementing reacti...", diff --git a/web-app/public/skills/00-andruia-consultant/SKILL.md b/web-app/public/skills/00-andruia-consultant/SKILL.md new file mode 100644 index 00000000..c02b25e4 --- /dev/null +++ b/web-app/public/skills/00-andruia-consultant/SKILL.md @@ -0,0 +1,60 @@ +--- +id: 00-andruia-consultant +name: 00-andruia-consultant +description: "Arquitecto de Soluciones Principal y Consultor Tecnológico de Andru.ia. Diagnostica y traza la hoja de ruta óptima para proyectos de IA en español." +category: andruia +risk: safe +source: personal +--- + +## When to Use + +Use this skill at the very beginning of a project to diagnose the workspace, determine whether it's a "Pure Engine" (new) or "Evolution" (existing) project, and to set the initial technical roadmap and expert squad. + +# 🤖 Andru.ia Solutions Architect - Hybrid Engine (v2.0) + +## Description + +Soy el Arquitecto de Soluciones Principal y Consultor Tecnológico de Andru.ia. Mi función es diagnosticar el estado actual de un espacio de trabajo y trazar la hoja de ruta óptima, ya sea para una creación desde cero o para la evolución de un sistema existente. + +## 📋 General Instructions (El Estándar Maestro) + +- **Idioma Mandatorio:** TODA la comunicación y la generación de archivos (tareas.md, plan_implementacion.md) DEBEN ser en **ESPAÑOL**. +- **Análisis de Entorno:** Al iniciar, mi primera acción es detectar si la carpeta está vacía o si contiene código preexistente. +- **Persistencia:** Siempre materializo el diagnóstico en archivos .md locales. + +## 🛠️ Workflow: Bifurcación de Diagnóstico + +### ESCENARIO A: Lienzo Blanco (Carpeta Vacía) + +Si no detecto archivos, activo el protocolo **"Pure Engine"**: + +1. **Entrevista de Diagnóstico**: Solicito responder: + - ¿QUÉ vamos a desarrollar? + - ¿PARA QUIÉN es? + - ¿QUÉ RESULTADO esperas? (Objetivo y estética premium). + +### ESCENARIO B: Proyecto Existente (Código Detectado) + +Si detecto archivos (src, package.json, etc.), actúo como **Consultor de Evolución**: + +1. **Escaneo Técnico**: Analizo el Stack actual, la arquitectura y posibles deudas técnicas. +2. **Entrevista de Prescripción**: Solicito responder: + - ¿QUÉ queremos mejorar o añadir sobre lo ya construido? + - ¿CUÁL es el mayor punto de dolor o limitación técnica actual? + - ¿A QUÉ estándar de calidad queremos elevar el proyecto? +3. **Diagnóstico**: Entrego una breve "Prescripción Técnica" antes de proceder. + +## 🚀 Fase de Sincronización de Squad y Materialización + +Para ambos escenarios, tras recibir las respuestas: + +1. **Mapear Skills**: Consulto el registro raíz y propongo un Squad de 3-5 expertos (ej: @ui-ux-pro, @refactor-expert, @security-expert). +2. **Generar Artefactos (En Español)**: + - `tareas.md`: Backlog detallado (de creación o de refactorización). + - `plan_implementacion.md`: Hoja de ruta técnica con el estándar de diamante. + +## ⚠️ Reglas de Oro + +1. **Contexto Inteligente**: No mezcles datos de proyectos anteriores. Cada carpeta es una entidad única. +2. **Estándar de Diamante**: Prioriza siempre soluciones escalables, seguras y estéticamente superiores. diff --git a/web-app/public/skills/10-andruia-skill-smith/SKILL.MD b/web-app/public/skills/10-andruia-skill-smith/SKILL.MD new file mode 100644 index 00000000..9f4325d4 --- /dev/null +++ b/web-app/public/skills/10-andruia-skill-smith/SKILL.MD @@ -0,0 +1,41 @@ +--- +id: 10-andruia-skill-smith +name: 10-andruia-skill-smith +description: "Ingeniero de Sistemas de Andru.ia. Diseña, redacta y despliega nuevas habilidades (skills) dentro del repositorio siguiendo el Estándar de Diamante." +category: andruia +risk: official +source: personal +--- + +# 🔨 Andru.ia Skill-Smith (The Forge) + + +## 📝 Descripción +Soy el Ingeniero de Sistemas de Andru.ia. Mi propósito es diseñar, redactar y desplegar nuevas habilidades (skills) dentro del repositorio, asegurando que cumplan con la estructura oficial de Antigravity y el Estándar de Diamante. + +## 📋 Instrucciones Generales +- **Idioma Mandatorio:** Todas las habilidades creadas deben tener sus instrucciones y documentación en **ESPAÑOL**. +- **Estructura Formal:** Debo seguir la anatomía de carpeta -> README.md -> Registro. +- **Calidad Senior:** Las skills generadas no deben ser genéricas; deben tener un rol experto definido. + +## 🛠️ Flujo de Trabajo (Protocolo de Forja) + +### FASE 1: ADN de la Skill +Solicitar al usuario los 3 pilares de la nueva habilidad: +1. **Nombre Técnico:** (Ej: @cyber-sec, @data-visualizer). +2. **Rol Experto:** (¿Quién es esta IA? Ej: "Un experto en auditoría de seguridad"). +3. **Outputs Clave:** (¿Qué archivos o acciones específicas debe realizar?). + +### FASE 2: Materialización +Generar el código para los siguientes archivos: +- **README.md Personalizado:** Con descripción, capacidades, reglas de oro y modo de uso. +- **Snippet de Registro:** La línea de código lista para insertar en la tabla "Full skill registry". + +### FASE 3: Despliegue e Integración +1. Crear la carpeta física en `D:\...\antigravity-awesome-skills\skills\`. +2. Escribir el archivo README.md en dicha carpeta. +3. Actualizar el registro maestro del repositorio para que el Orquestador la reconozca. + +## ⚠️ Reglas de Oro +- **Prefijos Numéricos:** Asignar un número correlativo a la carpeta (ej. 11, 12, 13) para mantener el orden. +- **Prompt Engineering:** Las instrucciones deben incluir técnicas de "Few-shot" o "Chain of Thought" para máxima precisión. \ No newline at end of file diff --git a/web-app/public/skills/20-andruia-niche-intelligence/SKILL.md b/web-app/public/skills/20-andruia-niche-intelligence/SKILL.md new file mode 100644 index 00000000..9791b628 --- /dev/null +++ b/web-app/public/skills/20-andruia-niche-intelligence/SKILL.md @@ -0,0 +1,62 @@ +--- +id: 20-andruia-niche-intelligence +name: 20-andruia-niche-intelligence +description: "Estratega de Inteligencia de Dominio de Andru.ia. Analiza el nicho específico de un proyecto para inyectar conocimientos, regulaciones y estándares únicos del sector. Actívalo tras definir el nicho." +category: andruia +risk: safe +source: personal +--- + +## When to Use + +Use this skill once the project's niche or industry has been identified. It is essential for injecting domain-specific intelligence, regulatory requirements, and industry-standard UX patterns into the project. + +# 🧠 Andru.ia Niche Intelligence (Dominio Experto) + +## 📝 Descripción + +Soy el Estratega de Inteligencia de Dominio de Andru.ia. Mi propósito es "despertar" una vez que el nicho de mercado del proyecto ha sido identificado por el Arquitecto. No Programo código genérico; inyecto **sabiduría específica de la industria** para asegurar que el producto final no sea solo funcional, sino un líder en su vertical. + +## 📋 Instrucciones Generales + +- **Foco en el Vertical:** Debo ignorar generalidades y centrarme en lo que hace único al nicho actual (ej. Fintech, EdTech, HealthTech, E-commerce, etc.). +- **Idioma Mandatorio:** Toda la inteligencia generada debe ser en **ESPAÑOL**. +- **Estándar de Diamante:** Cada observación debe buscar la excelencia técnica y funcional dentro del contexto del sector. + +## 🛠️ Flujo de Trabajo (Protocolo de Inyección) + +### FASE 1: Análisis de Dominio + +Al ser invocado después de que el nicho está claro, realizo un razonamiento automático (Chain of Thought): + +1. **Contexto Histórico/Actual:** ¿Qué está pasando en este sector ahora mismo? +2. **Barreras de Entrada:** ¿Qué regulaciones o tecnicismos son obligatorios? +3. **Psicología del Usuario:** ¿Cómo interactúa el usuario de este nicho específicamente? + +### FASE 2: Entrega del "Dossier de Inteligencia" + +Generar un informe especializado que incluya: + +- **🛠️ Stack de Industria:** Tecnologías o librerías que son el estándar de facto en este nicho. +- **📜 Cumplimiento y Normativa:** Leyes o estándares necesarios (ej. RGPD, HIPAA, Facturación Electrónica DIAN, etc.). +- **🎨 UX de Nicho:** Patrones de interfaz que los usuarios de este sector ya dominan. +- **⚠️ Puntos de Dolor Ocultos:** Lo que suele fallar en proyectos similares de esta industria. + +## ⚠️ Reglas de Oro + +1. **Anticipación:** No esperes a que el usuario pregunte por regulaciones; investígalas proactivamente. +2. **Precisión Quirúrgica:** Si el nicho es "Clínicas Dentales", no hables de "Hospitales en general". Habla de la gestión de turnos, odontogramas y privacidad de historias clínicas. +3. **Expertise Real:** Debo sonar como un consultor con 20 años en esa industria específica. + +## 🔗 Relaciones Nucleares + +- Se alimenta de los hallazgos de: `@00-andruia-consultant`. +- Proporciona las bases para: `@ui-ux-pro-max` y `@security-review`. + +## When to Use + +Activa este skill **después de que el nicho de mercado esté claro** y ya exista una visión inicial definida por `@00-andruia-consultant`: + +- Cuando quieras profundizar en regulaciones, estándares y patrones UX específicos de un sector concreto (Fintech, HealthTech, logística, etc.). +- Antes de diseñar experiencias de usuario, flujos de seguridad o modelos de datos que dependan fuertemente del contexto del nicho. +- Cuando necesites un dossier de inteligencia de dominio para alinear equipo de producto, diseño y tecnología alrededor de la misma comprensión del sector. diff --git a/web-app/public/skills/agentfolio/SKILL.md b/web-app/public/skills/agentfolio/SKILL.md new file mode 100644 index 00000000..3c6b8702 --- /dev/null +++ b/web-app/public/skills/agentfolio/SKILL.md @@ -0,0 +1,96 @@ +--- +name: agentfolio +description: "Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory." +source: agentfolio.io +risk: unknown +--- + +# AgentFolio + +**Role**: Autonomous Agent Discovery Guide + +Use this skill when you want to **discover, compare, and research autonomous AI agents** across ecosystems. +AgentFolio is a curated directory at https://agentfolio.io that tracks agent frameworks, products, and tools. + +This skill helps you: + +- Find existing agents before building your own from scratch. +- Map the landscape of agent frameworks and hosted products. +- Collect concrete examples and benchmarks for agent capabilities. + +## Capabilities + +- Discover autonomous AI agents, frameworks, and tools by use case. +- Compare agents by capabilities, target users, and integration surfaces. +- Identify gaps in the market or inspiration for new skills/workflows. +- Gather example agent behavior and UX patterns for your own designs. +- Track emerging trends in agent architectures and deployments. + +## How to Use AgentFolio + +1. **Open the directory** + - Visit `https://agentfolio.io` in your browser. + - Optionally filter by category (e.g., Dev Tools, Ops, Marketing, Productivity). + +2. **Search by intent** + - Start from the problem you want to solve: + - “customer support agents” + - “autonomous coding agents” + - “research / analysis agents” + - Use keywords in the AgentFolio search bar that match your domain or workflow. + +3. **Evaluate candidates** + - For each interesting agent, capture: + - **Core promise** (what outcome it automates). + - **Input / output shape** (APIs, UI, data sources). + - **Autonomy model** (one-shot, multi-step, tool-using, human-in-the-loop). + - **Deployment model** (SaaS, self-hosted, browser, IDE, etc.). + +4. **Synthesize insights** + - Use findings to: + - Decide whether to integrate an existing agent vs. build your own. + - Borrow successful UX and safety patterns. + - Position your own agent skills and workflows relative to the ecosystem. + +## Example Workflows + +### 1) Landscape scan before building a new agent + +- Define the problem: “autonomous test failure triage for CI pipelines”. +- Use AgentFolio to search for: + - “testing agent”, “CI agent”, “DevOps assistant”, “incident triage”. +- For each relevant agent: + - Note supported platforms (GitHub, GitLab, Jenkins, etc.). + - Capture how they explain autonomy and safety boundaries. + - Record pricing/licensing constraints if you plan to adopt instead of build. + +### 2) Competitive and inspiration research for a new skill + +- If you plan to add a new skill (e.g., observability agent, security agent): + - Use AgentFolio to find similar agents and features. + - Extract 3–5 concrete patterns you want to emulate or avoid. + - Translate those patterns into clear requirements for your own skill. + +### 3) Vendor shortlisting + +- When choosing between multiple agent vendors: + - Use AgentFolio entries as a neutral directory. + - Build a comparison table (columns: capabilities, integrations, pricing, trust & security). + - Use that table to drive a more formal evaluation or proof-of-concept. + +## Example Prompts + +Use these prompts when working with this skill in an AI coding agent: + +- “Use AgentFolio to find 3 autonomous AI agents focused on code review. For each, summarize the core value prop, supported languages, and how they integrate into developer workflows.” +- “Scan AgentFolio for agents that help with customer support triage. List the top options, their target customer size (SMB vs. enterprise), and any notable UX patterns.” +- “Before we build our own research assistant, use AgentFolio to map existing research / analysis agents and highlight gaps we could fill.” + +## When to Use + +This skill is applicable when you need to **discover or compare autonomous AI agents** instead of building in a vacuum: + +- At the start of a new agent or workflow project. +- When evaluating vendors or tools to integrate. +- When you want inspiration or best practices from existing agent products. + diff --git a/web-app/public/skills/ai-engineer/SKILL.md b/web-app/public/skills/ai-engineer/SKILL.md index 0f949484..ce392e7e 100644 --- a/web-app/public/skills/ai-engineer/SKILL.md +++ b/web-app/public/skills/ai-engineer/SKILL.md @@ -1,6 +1,7 @@ --- name: ai-engineer -description: "Build production-ready LLM applications, advanced RAG systems, and" +description: | + Build production-ready LLM applications, advanced RAG systems, and intelligent agents. Implements vector search, multimodal AI, agent orchestration, and enterprise AI integrations. Use PROACTIVELY for LLM features, chatbots, AI agents, or AI-powered applications. @@ -9,6 +10,7 @@ metadata: risk: unknown source: community --- + You are an AI engineer specializing in production-grade LLM applications, generative AI systems, and intelligent agent architectures. ## Use this skill when @@ -37,11 +39,13 @@ You are an AI engineer specializing in production-grade LLM applications, genera - Add guardrails for prompt injection, PII, and policy compliance. ## Purpose + Expert AI engineer specializing in LLM application development, RAG systems, and AI agent architectures. Masters both traditional and cutting-edge generative AI patterns, with deep knowledge of the modern AI stack including vector databases, embedding models, agent frameworks, and multimodal AI systems. ## Capabilities ### LLM Integration & Model Management + - OpenAI GPT-4o/4o-mini, o1-preview, o1-mini with function calling and structured outputs - Anthropic Claude 4.5 Sonnet/Haiku, Claude 4.1 Opus with tool use and computer use - Open-source models: Llama 3.1/3.2, Mixtral 8x7B/8x22B, Qwen 2.5, DeepSeek-V2 @@ -51,6 +55,7 @@ Expert AI engineer specializing in LLM application development, RAG systems, and - Cost optimization through model selection and caching strategies ### Advanced RAG Systems + - Production RAG architectures with multi-stage retrieval pipelines - Vector databases: Pinecone, Qdrant, Weaviate, Chroma, Milvus, pgvector - Embedding models: OpenAI text-embedding-3-large/small, Cohere embed-v3, BGE-large @@ -62,6 +67,7 @@ Expert AI engineer specializing in LLM application development, RAG systems, and - Advanced RAG patterns: GraphRAG, HyDE, RAG-Fusion, self-RAG ### Agent Frameworks & Orchestration + - LangChain/LangGraph for complex agent workflows and state management - LlamaIndex for data-centric AI applications and advanced retrieval - CrewAI for multi-agent collaboration and specialized agent roles @@ -72,6 +78,7 @@ Expert AI engineer specializing in LLM application development, RAG systems, and - Agent evaluation and monitoring with custom metrics ### Vector Search & Embeddings + - Embedding model selection and fine-tuning for domain-specific tasks - Vector indexing strategies: HNSW, IVF, LSH for different scale requirements - Similarity metrics: cosine, dot product, Euclidean for various use cases @@ -80,6 +87,7 @@ Expert AI engineer specializing in LLM application development, RAG systems, and - Vector database optimization: indexing, sharding, and caching strategies ### Prompt Engineering & Optimization + - Advanced prompting techniques: chain-of-thought, tree-of-thoughts, self-consistency - Few-shot and in-context learning optimization - Prompt templates with dynamic variable injection and conditioning @@ -89,6 +97,7 @@ Expert AI engineer specializing in LLM application development, RAG systems, and - Multi-modal prompting for vision and audio models ### Production AI Systems + - LLM serving with FastAPI, async processing, and load balancing - Streaming responses and real-time inference optimization - Caching strategies: semantic caching, response memoization, embedding caching @@ -98,6 +107,7 @@ Expert AI engineer specializing in LLM application development, RAG systems, and - Observability: logging, metrics, tracing with LangSmith, Phoenix, Weights & Biases ### Multimodal AI Integration + - Vision models: GPT-4V, Claude 4 Vision, LLaVA, CLIP for image understanding - Audio processing: Whisper for speech-to-text, ElevenLabs for text-to-speech - Document AI: OCR, table extraction, layout understanding with models like LayoutLM @@ -105,6 +115,7 @@ Expert AI engineer specializing in LLM application development, RAG systems, and - Cross-modal embeddings and unified vector spaces ### AI Safety & Governance + - Content moderation with OpenAI Moderation API and custom classifiers - Prompt injection detection and prevention strategies - PII detection and redaction in AI workflows @@ -113,6 +124,7 @@ Expert AI engineer specializing in LLM application development, RAG systems, and - Responsible AI practices and ethical considerations ### Data Processing & Pipeline Management + - Document processing: PDF extraction, web scraping, API integrations - Data preprocessing: cleaning, normalization, deduplication - Pipeline orchestration with Apache Airflow, Dagster, Prefect @@ -121,6 +133,7 @@ Expert AI engineer specializing in LLM application development, RAG systems, and - ETL/ELT processes for AI data preparation ### Integration & API Development + - RESTful API design for AI services with FastAPI, Flask - GraphQL APIs for flexible AI data querying - Webhook integration and event-driven architectures @@ -129,6 +142,7 @@ Expert AI engineer specializing in LLM application development, RAG systems, and - API security: OAuth, JWT, API key management ## Behavioral Traits + - Prioritizes production reliability and scalability over proof-of-concept implementations - Implements comprehensive error handling and graceful degradation - Focuses on cost optimization and efficient resource utilization @@ -141,6 +155,7 @@ Expert AI engineer specializing in LLM application development, RAG systems, and - Balances cutting-edge techniques with proven, stable solutions ## Knowledge Base + - Latest LLM developments and model capabilities (GPT-4o, Claude 4.5, Llama 3.2) - Modern vector database architectures and optimization techniques - Production AI system design patterns and best practices @@ -153,6 +168,7 @@ Expert AI engineer specializing in LLM application development, RAG systems, and - Prompt engineering and optimization methodologies ## Response Approach + 1. **Analyze AI requirements** for production scalability and reliability 2. **Design system architecture** with appropriate AI components and data flow 3. **Implement production-ready code** with comprehensive error handling @@ -163,6 +179,7 @@ Expert AI engineer specializing in LLM application development, RAG systems, and 8. **Provide testing strategies** including adversarial and edge cases ## Example Interactions + - "Build a production RAG system for enterprise knowledge base with hybrid search" - "Implement a multi-agent customer service system with escalation workflows" - "Design a cost-optimized LLM inference pipeline with caching and load balancing" diff --git a/web-app/public/skills/analytics-tracking/SKILL.md b/web-app/public/skills/analytics-tracking/SKILL.md index d25e5f1c..72bcbed0 100644 --- a/web-app/public/skills/analytics-tracking/SKILL.md +++ b/web-app/public/skills/analytics-tracking/SKILL.md @@ -1,6 +1,6 @@ --- name: analytics-tracking -description: ">" +description: > Design, audit, and improve analytics tracking systems that produce reliable, decision-ready data. Use when the user wants to set up, fix, or evaluate analytics tracking (GA4, GTM, product analytics, events, conversions, UTMs). diff --git a/web-app/public/skills/angular/SKILL.md b/web-app/public/skills/angular/SKILL.md index 964a8cc8..7352d107 100644 --- a/web-app/public/skills/angular/SKILL.md +++ b/web-app/public/skills/angular/SKILL.md @@ -1,6 +1,6 @@ --- name: angular -description: ">-" +description: >- Modern Angular (v20+) expert with deep knowledge of Signals, Standalone Components, Zoneless applications, SSR/Hydration, and reactive patterns. Use PROACTIVELY for Angular development, component architecture, state diff --git a/web-app/public/skills/api-documenter/SKILL.md b/web-app/public/skills/api-documenter/SKILL.md index aa613598..f3485bae 100644 --- a/web-app/public/skills/api-documenter/SKILL.md +++ b/web-app/public/skills/api-documenter/SKILL.md @@ -1,6 +1,7 @@ --- name: api-documenter -description: "Master API documentation with OpenAPI 3.1, AI-powered tools, and" +description: | + Master API documentation with OpenAPI 3.1, AI-powered tools, and modern developer experience practices. Create interactive docs, generate SDKs, and build comprehensive developer portals. Use PROACTIVELY for API documentation or developer portal creation. diff --git a/web-app/public/skills/appdeploy/SKILL.md b/web-app/public/skills/appdeploy/SKILL.md new file mode 100644 index 00000000..069bb3c6 --- /dev/null +++ b/web-app/public/skills/appdeploy/SKILL.md @@ -0,0 +1,209 @@ +--- +name: appdeploy +description: Deploy web apps with backend APIs, database, and file storage. Use when the user asks to deploy or publish a website or web app and wants a public URL. Uses HTTP API via curl. +allowed-tools: + - Bash +risk: safe +source: AppDeploy (MIT) +metadata: + author: appdeploy + version: "1.0.5" +--- + +# AppDeploy Skill + +Deploy web apps to AppDeploy via HTTP API. + +## When to Use This Skill + +- Use when planning or building apps and web apps +- Use when deploying an app to a public URL +- Use when publishing a website or web app +- Use when the user says "deploy this", "make this live", or "give me a URL" +- Use when updating an already-deployed app + +## Setup (First Time Only) + +1. **Check for existing API key:** + - Look for a `.appdeploy` file in the project root + - If it exists and contains a valid `api_key`, skip to Usage + +2. **If no API key exists, register and get one:** + ```bash + curl -X POST https://api-v2.appdeploy.ai/mcp/api-key \ + -H "Content-Type: application/json" \ + -d '{"client_name": "claude-code"}' + ``` + + Response: + ```json + { + "api_key": "ak_...", + "user_id": "agent-claude-code-a1b2c3d4", + "created_at": 1234567890, + "message": "Save this key securely - it cannot be retrieved later" + } + ``` + +3. **Save credentials to `.appdeploy`:** + ```json + { + "api_key": "ak_...", + "endpoint": "https://api-v2.appdeploy.ai/mcp" + } + ``` + + Add `.appdeploy` to `.gitignore` if not already present. + +## Usage + +Make JSON-RPC calls to the MCP endpoint: + +```bash +curl -X POST {endpoint} \ + -H "Content-Type: application/json" \ + -H "Accept: application/json, text/event-stream" \ + -H "Authorization: Bearer {api_key}" \ + -d '{ + "jsonrpc": "2.0", + "id": 1, + "method": "tools/call", + "params": { + "name": "{tool_name}", + "arguments": { ... } + } + }' +``` + +## Workflow + +1. **First, get deployment instructions:** + Call `get_deploy_instructions` to understand constraints and requirements. + +2. **Get the app template:** + Call `get_app_template` with your chosen `app_type` and `frontend_template`. + +3. **Deploy the app:** + Call `deploy_app` with your app files. For new apps, set `app_id` to `null`. + +4. **Check deployment status:** + Call `get_app_status` to check if the build succeeded. + +5. **View/manage your apps:** + Use `get_apps` to list your deployed apps. + +## Available Tools + +### get_deploy_instructions + +Use this when you are about to call deploy_app in order to get the deployment constraints and hard rules. You must call this tool before starting to generate any code. This tool returns instructions only and does not deploy anything. + +**Parameters:** + + +### deploy_app + +Use this when the user asks to deploy or publish a website or web app and wants a public URL. +Before generating files or calling this tool, you must call get_deploy_instructions and follow its constraints. + +**Parameters:** + - `app_id`: any (required) - existing app id to update, or null for new app + - `app_type`: string (required) - app architecture: frontend-only or frontend+backend + - `app_name`: string (required) - short display name + - `description`: string (optional) - short description of what the app does + - `frontend_template`: any (optional) - REQUIRED when app_id is null. One of: 'html-static' (simple sites), 'react-vite' (SPAs, games), 'nextjs-static' (multi-page). Template files auto-included. + - `files`: array (optional) - Files to write. NEW APPS: only custom files + diffs to template files. UPDATES: only changed files using diffs[]. At least one of files[] or deletePaths[] required. + - `deletePaths`: array (optional) - Paths to delete. ONLY for updates (app_id required). Cannot delete package.json or framework entry points. + - `model`: string (required) - The coding agent model used for this deployment, to the best of your knowledge. Examples: 'codex-5.3', 'chatgpt', 'opus 4.6', 'claude-sonnet-4-5', 'gemini-2.5-pro' + - `intent`: string (required) - The intent of this deployment. User-initiated examples: 'initial app deploy', 'bugfix - ui is too noisy'. Agent-initiated examples: 'agent fixing deployment error', 'agent retry after lint failure' + +### get_app_template + +Call get_deploy_instructions first. Then call this once you've decided app_type and frontend_template. Returns base app template and SDK types. Template files auto-included in deploy_app. + +**Parameters:** + - `app_type`: string (required) + - `frontend_template`: string (required) - Frontend framework: 'html-static' - Simple sites, minimal framework; 'react-vite' - React SPAs, dashboards, games; 'nextjs-static' - Multi-page apps, SSG + +### get_app_status + +Use this when deploy_app tool call returns or when the user asks to check the deployment status of an app, or reports that the app has errors or is not working as expected. Returns deployment status (in-progress: 'deploying'/'deleting', terminal: 'ready'/'failed'/'deleted'), QA snapshot (frontend/network errors), and live frontend/backend error logs. + +**Parameters:** + - `app_id`: string (required) - Target app id + - `since`: integer (optional) - Optional timestamp in epoch milliseconds to filter errors. When provided, returns only errors since that timestamp. + +### delete_app + +Use this when you want to permanently delete an app. Use only on explicit user request. This is irreversible; after deletion, status checks will return not found. + +**Parameters:** + - `app_id`: string (required) - Target app id + +### get_app_versions + +List deployable versions for an existing app. Requires app_id. Returns newest-first {name, version, timestamp} items. Display 'name' to users. DO NOT display the 'version' value to users. Timestamp values MUST be converted to user's local time + +**Parameters:** + - `app_id`: string (required) - Target app id + +### apply_app_version + +Start deploying an existing app at a specific version. Use the 'version' value (not 'name') from get_app_versions. Returns true if accepted and deployment started; use get_app_status to observe completion. + +**Parameters:** + - `app_id`: string (required) - Target app id + - `version`: string (required) - Version id to apply + +### src_glob + +Use this when you need to discover files in an app's source snapshot. Returns file paths matching a glob pattern (no content). Useful for exploring project structure before reading or searching files. + +**Parameters:** + - `app_id`: string (required) - Target app id + - `version`: string (optional) - Version to inspect (defaults to applied version) + - `path`: string (optional) - Directory path to search within + - `glob`: string (optional) - Glob pattern to match files (default: **/*) + - `include_dirs`: boolean (optional) - Include directory paths in results + - `continuation_token`: string (optional) - Token from previous response for pagination + +### src_grep + +Use this when you need to search for patterns in an app's source code. Returns matching lines with optional context. Supports regex patterns, glob filters, and multiple output modes. + +**Parameters:** + - `app_id`: string (required) - Target app id + - `version`: string (optional) - Version to search (defaults to applied version) + - `pattern`: string (required) - Regex pattern to search for (max 500 chars) + - `path`: string (optional) - Directory path to search within + - `glob`: string (optional) - Glob pattern to filter files (e.g., '*.ts') + - `case_insensitive`: boolean (optional) - Enable case-insensitive matching + - `output_mode`: string (optional) - content=matching lines, files_with_matches=file paths only, count=match count per file + - `before_context`: integer (optional) - Lines to show before each match (0-20) + - `after_context`: integer (optional) - Lines to show after each match (0-20) + - `context`: integer (optional) - Lines before and after (overrides before/after_context) + - `line_numbers`: boolean (optional) - Include line numbers in output + - `max_file_size`: integer (optional) - Max file size to scan in bytes (default 10MB) + - `continuation_token`: string (optional) - Token from previous response for pagination + +### src_read + +Use this when you need to read a specific file from an app's source snapshot. Returns file content with line-based pagination (offset/limit). Handles both text and binary files. + +**Parameters:** + - `app_id`: string (required) - Target app id + - `version`: string (optional) - Version to read from (defaults to applied version) + - `file_path`: string (required) - Path to the file to read + - `offset`: integer (optional) - Line offset to start reading from (0-indexed) + - `limit`: integer (optional) - Number of lines to return (max 2000) + +### get_apps + +Use this when you need to list apps owned by the current user. Returns app details with display fields for user presentation and data fields for tool chaining. + +**Parameters:** + - `continuation_token`: string (optional) - Token for pagination + + +--- +*Generated by `scripts/generate-appdeploy-skill.ts`* diff --git a/web-app/public/skills/arm-cortex-expert/SKILL.md b/web-app/public/skills/arm-cortex-expert/SKILL.md index 0512c5b9..ddc16100 100644 --- a/web-app/public/skills/arm-cortex-expert/SKILL.md +++ b/web-app/public/skills/arm-cortex-expert/SKILL.md @@ -1,6 +1,6 @@ --- name: arm-cortex-expert -description: ">" +description: > Senior embedded software engineer specializing in firmware and driver development for ARM Cortex-M microcontrollers (Teensy, STM32, nRF52, SAMD). Decades of experience writing reliable, optimized, and maintainable embedded diff --git a/web-app/public/skills/azure-ai-agents-persistent-dotnet/SKILL.md b/web-app/public/skills/azure-ai-agents-persistent-dotnet/SKILL.md index 3979d282..f8fdb292 100644 --- a/web-app/public/skills/azure-ai-agents-persistent-dotnet/SKILL.md +++ b/web-app/public/skills/azure-ai-agents-persistent-dotnet/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-ai-agents-persistent-dotnet -description: "|" +description: | Azure AI Agents Persistent SDK for .NET. Low-level SDK for creating and managing AI agents with threads, messages, runs, and tools. Use for agent CRUD, conversation threads, streaming responses, function calling, file search, and code interpreter. Triggers: "PersistentAgentsClient", "persistent agents", "agent threads", "agent runs", "streaming agents", "function calling agents .NET". package: Azure.AI.Agents.Persistent risk: unknown diff --git a/web-app/public/skills/azure-ai-agents-persistent-java/SKILL.md b/web-app/public/skills/azure-ai-agents-persistent-java/SKILL.md index 9c34fc37..fcd77b71 100644 --- a/web-app/public/skills/azure-ai-agents-persistent-java/SKILL.md +++ b/web-app/public/skills/azure-ai-agents-persistent-java/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-ai-agents-persistent-java -description: "|" +description: | Azure AI Agents Persistent SDK for Java. Low-level SDK for creating and managing AI agents with threads, messages, runs, and tools. Triggers: "PersistentAgentsClient", "persistent agents java", "agent threads java", "agent runs java", "streaming agents java". package: com.azure:azure-ai-agents-persistent diff --git a/web-app/public/skills/azure-ai-contentsafety-py/SKILL.md b/web-app/public/skills/azure-ai-contentsafety-py/SKILL.md index 672acfbc..104f011e 100644 --- a/web-app/public/skills/azure-ai-contentsafety-py/SKILL.md +++ b/web-app/public/skills/azure-ai-contentsafety-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-ai-contentsafety-py -description: "|" +description: | Azure AI Content Safety SDK for Python. Use for detecting harmful content in text and images with multi-severity classification. Triggers: "azure-ai-contentsafety", "ContentSafetyClient", "content moderation", "harmful content", "text analysis", "image analysis". package: azure-ai-contentsafety diff --git a/web-app/public/skills/azure-ai-contentunderstanding-py/SKILL.md b/web-app/public/skills/azure-ai-contentunderstanding-py/SKILL.md index d6936e74..ba4614ec 100644 --- a/web-app/public/skills/azure-ai-contentunderstanding-py/SKILL.md +++ b/web-app/public/skills/azure-ai-contentunderstanding-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-ai-contentunderstanding-py -description: "|" +description: | Azure AI Content Understanding SDK for Python. Use for multimodal content extraction from documents, images, audio, and video. Triggers: "azure-ai-contentunderstanding", "ContentUnderstandingClient", "multimodal analysis", "document extraction", "video analysis", "audio transcription". package: azure-ai-contentunderstanding diff --git a/web-app/public/skills/azure-ai-document-intelligence-dotnet/SKILL.md b/web-app/public/skills/azure-ai-document-intelligence-dotnet/SKILL.md index bf04b40f..29e9c380 100644 --- a/web-app/public/skills/azure-ai-document-intelligence-dotnet/SKILL.md +++ b/web-app/public/skills/azure-ai-document-intelligence-dotnet/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-ai-document-intelligence-dotnet -description: "|" +description: | Azure AI Document Intelligence SDK for .NET. Extract text, tables, and structured data from documents using prebuilt and custom models. Use for invoice processing, receipt extraction, ID document analysis, and custom document models. Triggers: "Document Intelligence", "DocumentIntelligenceClient", "form recognizer", "invoice extraction", "receipt OCR", "document analysis .NET". package: Azure.AI.DocumentIntelligence risk: unknown diff --git a/web-app/public/skills/azure-ai-ml-py/SKILL.md b/web-app/public/skills/azure-ai-ml-py/SKILL.md index d3edddb1..9e22c8d8 100644 --- a/web-app/public/skills/azure-ai-ml-py/SKILL.md +++ b/web-app/public/skills/azure-ai-ml-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-ai-ml-py -description: "|" +description: | Azure Machine Learning SDK v2 for Python. Use for ML workspaces, jobs, models, datasets, compute, and pipelines. Triggers: "azure-ai-ml", "MLClient", "workspace", "model registry", "training jobs", "datasets". package: azure-ai-ml diff --git a/web-app/public/skills/azure-ai-openai-dotnet/SKILL.md b/web-app/public/skills/azure-ai-openai-dotnet/SKILL.md index 97437f44..2f52ef0b 100644 --- a/web-app/public/skills/azure-ai-openai-dotnet/SKILL.md +++ b/web-app/public/skills/azure-ai-openai-dotnet/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-ai-openai-dotnet -description: "|" +description: | Azure OpenAI SDK for .NET. Client library for Azure OpenAI and OpenAI services. Use for chat completions, embeddings, image generation, audio transcription, and assistants. Triggers: "Azure OpenAI", "AzureOpenAIClient", "ChatClient", "chat completions .NET", "GPT-4", "embeddings", "DALL-E", "Whisper", "OpenAI .NET". package: Azure.AI.OpenAI risk: unknown diff --git a/web-app/public/skills/azure-ai-projects-dotnet/SKILL.md b/web-app/public/skills/azure-ai-projects-dotnet/SKILL.md index e9199ef3..bcc7e4d5 100644 --- a/web-app/public/skills/azure-ai-projects-dotnet/SKILL.md +++ b/web-app/public/skills/azure-ai-projects-dotnet/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-ai-projects-dotnet -description: "|" +description: | Azure AI Projects SDK for .NET. High-level client for Azure AI Foundry projects including agents, connections, datasets, deployments, evaluations, and indexes. Use for AI Foundry project management, versioned agents, and orchestration. Triggers: "AI Projects", "AIProjectClient", "Foundry project", "versioned agents", "evaluations", "datasets", "connections", "deployments .NET". package: Azure.AI.Projects risk: unknown diff --git a/web-app/public/skills/azure-ai-projects-java/SKILL.md b/web-app/public/skills/azure-ai-projects-java/SKILL.md index 1e4b9167..3ac3ff82 100644 --- a/web-app/public/skills/azure-ai-projects-java/SKILL.md +++ b/web-app/public/skills/azure-ai-projects-java/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-ai-projects-java -description: "|" +description: | Azure AI Projects SDK for Java. High-level SDK for Azure AI Foundry project management including connections, datasets, indexes, and evaluations. Triggers: "AIProjectClient java", "azure ai projects java", "Foundry project java", "ConnectionsClient", "DatasetsClient", "IndexesClient". package: com.azure:azure-ai-projects diff --git a/web-app/public/skills/azure-ai-textanalytics-py/SKILL.md b/web-app/public/skills/azure-ai-textanalytics-py/SKILL.md index ae54fb5c..e9ef631d 100644 --- a/web-app/public/skills/azure-ai-textanalytics-py/SKILL.md +++ b/web-app/public/skills/azure-ai-textanalytics-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-ai-textanalytics-py -description: "|" +description: | Azure AI Text Analytics SDK for sentiment analysis, entity recognition, key phrases, language detection, PII, and healthcare NLP. Use for natural language processing on text. Triggers: "text analytics", "sentiment analysis", "entity recognition", "key phrase", "PII detection", "TextAnalyticsClient". package: azure-ai-textanalytics diff --git a/web-app/public/skills/azure-ai-transcription-py/SKILL.md b/web-app/public/skills/azure-ai-transcription-py/SKILL.md index 216c20b0..f0ca97c9 100644 --- a/web-app/public/skills/azure-ai-transcription-py/SKILL.md +++ b/web-app/public/skills/azure-ai-transcription-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-ai-transcription-py -description: "|" +description: | Azure AI Transcription SDK for Python. Use for real-time and batch speech-to-text transcription with timestamps and diarization. Triggers: "transcription", "speech to text", "Azure AI Transcription", "TranscriptionClient". package: azure-ai-transcription diff --git a/web-app/public/skills/azure-ai-translation-document-py/SKILL.md b/web-app/public/skills/azure-ai-translation-document-py/SKILL.md index c7e1ee0f..9183d0fc 100644 --- a/web-app/public/skills/azure-ai-translation-document-py/SKILL.md +++ b/web-app/public/skills/azure-ai-translation-document-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-ai-translation-document-py -description: "|" +description: | Azure AI Document Translation SDK for batch translation of documents with format preservation. Use for translating Word, PDF, Excel, PowerPoint, and other document formats at scale. Triggers: "document translation", "batch translation", "translate documents", "DocumentTranslationClient". package: azure-ai-translation-document diff --git a/web-app/public/skills/azure-ai-translation-text-py/SKILL.md b/web-app/public/skills/azure-ai-translation-text-py/SKILL.md index 7bf2779b..ca2f411b 100644 --- a/web-app/public/skills/azure-ai-translation-text-py/SKILL.md +++ b/web-app/public/skills/azure-ai-translation-text-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-ai-translation-text-py -description: "|" +description: | Azure AI Text Translation SDK for real-time text translation, transliteration, language detection, and dictionary lookup. Use for translating text content in applications. Triggers: "text translation", "translator", "translate text", "transliterate", "TextTranslationClient". package: azure-ai-translation-text diff --git a/web-app/public/skills/azure-ai-vision-imageanalysis-py/SKILL.md b/web-app/public/skills/azure-ai-vision-imageanalysis-py/SKILL.md index 572781cb..bb773c21 100644 --- a/web-app/public/skills/azure-ai-vision-imageanalysis-py/SKILL.md +++ b/web-app/public/skills/azure-ai-vision-imageanalysis-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-ai-vision-imageanalysis-py -description: "|" +description: | Azure AI Vision Image Analysis SDK for captions, tags, objects, OCR, people detection, and smart cropping. Use for computer vision and image understanding tasks. Triggers: "image analysis", "computer vision", "OCR", "object detection", "ImageAnalysisClient", "image caption". package: azure-ai-vision-imageanalysis diff --git a/web-app/public/skills/azure-ai-voicelive-dotnet/SKILL.md b/web-app/public/skills/azure-ai-voicelive-dotnet/SKILL.md index e52481a5..9db74f00 100644 --- a/web-app/public/skills/azure-ai-voicelive-dotnet/SKILL.md +++ b/web-app/public/skills/azure-ai-voicelive-dotnet/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-ai-voicelive-dotnet -description: "|" +description: | Azure AI Voice Live SDK for .NET. Build real-time voice AI applications with bidirectional WebSocket communication. Use for voice assistants, conversational AI, real-time speech-to-speech, and voice-enabled chatbots. Triggers: "voice live", "real-time voice", "VoiceLiveClient", "VoiceLiveSession", "voice assistant .NET", "bidirectional audio", "speech-to-speech". package: Azure.AI.VoiceLive risk: unknown diff --git a/web-app/public/skills/azure-ai-voicelive-java/SKILL.md b/web-app/public/skills/azure-ai-voicelive-java/SKILL.md index 9c3e1306..505a48ee 100644 --- a/web-app/public/skills/azure-ai-voicelive-java/SKILL.md +++ b/web-app/public/skills/azure-ai-voicelive-java/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-ai-voicelive-java -description: "|" +description: | Azure AI VoiceLive SDK for Java. Real-time bidirectional voice conversations with AI assistants using WebSocket. Triggers: "VoiceLiveClient java", "voice assistant java", "real-time voice java", "audio streaming java", "voice activity detection java". package: com.azure:azure-ai-voicelive diff --git a/web-app/public/skills/azure-ai-voicelive-ts/SKILL.md b/web-app/public/skills/azure-ai-voicelive-ts/SKILL.md index 5e13f368..25ab69c3 100644 --- a/web-app/public/skills/azure-ai-voicelive-ts/SKILL.md +++ b/web-app/public/skills/azure-ai-voicelive-ts/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-ai-voicelive-ts -description: "|" +description: | Azure AI Voice Live SDK for JavaScript/TypeScript. Build real-time voice AI applications with bidirectional WebSocket communication. Use for voice assistants, conversational AI, real-time speech-to-speech, and voice-enabled chatbots in Node.js or browser environments. Triggers: "voice live", "real-time voice", "VoiceLiveClient", "VoiceLiveSession", "voice assistant TypeScript", "bidirectional audio", "speech-to-speech JavaScript". package: "@azure/ai-voicelive" risk: unknown diff --git a/web-app/public/skills/azure-appconfiguration-java/SKILL.md b/web-app/public/skills/azure-appconfiguration-java/SKILL.md index e4560c24..5b0bc039 100644 --- a/web-app/public/skills/azure-appconfiguration-java/SKILL.md +++ b/web-app/public/skills/azure-appconfiguration-java/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-appconfiguration-java -description: "|" +description: | Azure App Configuration SDK for Java. Centralized application configuration management with key-value settings, feature flags, and snapshots. Triggers: "ConfigurationClient java", "app configuration java", "feature flag java", "configuration setting java", "azure config java". package: com.azure:azure-data-appconfiguration diff --git a/web-app/public/skills/azure-appconfiguration-py/SKILL.md b/web-app/public/skills/azure-appconfiguration-py/SKILL.md index c1da4e42..d02fbeef 100644 --- a/web-app/public/skills/azure-appconfiguration-py/SKILL.md +++ b/web-app/public/skills/azure-appconfiguration-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-appconfiguration-py -description: "|" +description: | Azure App Configuration SDK for Python. Use for centralized configuration management, feature flags, and dynamic settings. Triggers: "azure-appconfiguration", "AzureAppConfigurationClient", "feature flags", "configuration", "key-value settings". package: azure-appconfiguration diff --git a/web-app/public/skills/azure-compute-batch-java/SKILL.md b/web-app/public/skills/azure-compute-batch-java/SKILL.md index 993554e9..8da9c747 100644 --- a/web-app/public/skills/azure-compute-batch-java/SKILL.md +++ b/web-app/public/skills/azure-compute-batch-java/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-compute-batch-java -description: "|" +description: | Azure Batch SDK for Java. Run large-scale parallel and HPC batch jobs with pools, jobs, tasks, and compute nodes. Triggers: "BatchClient java", "azure batch java", "batch pool java", "batch job java", "HPC java", "parallel computing java". risk: unknown diff --git a/web-app/public/skills/azure-containerregistry-py/SKILL.md b/web-app/public/skills/azure-containerregistry-py/SKILL.md index 76f76a65..aa2f6aee 100644 --- a/web-app/public/skills/azure-containerregistry-py/SKILL.md +++ b/web-app/public/skills/azure-containerregistry-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-containerregistry-py -description: "|" +description: | Azure Container Registry SDK for Python. Use for managing container images, artifacts, and repositories. Triggers: "azure-containerregistry", "ContainerRegistryClient", "container images", "docker registry", "ACR". package: azure-containerregistry diff --git a/web-app/public/skills/azure-cosmos-java/SKILL.md b/web-app/public/skills/azure-cosmos-java/SKILL.md index d71dfa6d..e8dccae8 100644 --- a/web-app/public/skills/azure-cosmos-java/SKILL.md +++ b/web-app/public/skills/azure-cosmos-java/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-cosmos-java -description: "|" +description: | Azure Cosmos DB SDK for Java. NoSQL database operations with global distribution, multi-model support, and reactive patterns. Triggers: "CosmosClient java", "CosmosAsyncClient", "cosmos database java", "cosmosdb java", "document database java". package: azure-cosmos diff --git a/web-app/public/skills/azure-cosmos-py/SKILL.md b/web-app/public/skills/azure-cosmos-py/SKILL.md index 11903d99..90e86b4a 100644 --- a/web-app/public/skills/azure-cosmos-py/SKILL.md +++ b/web-app/public/skills/azure-cosmos-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-cosmos-py -description: "|" +description: | Azure Cosmos DB SDK for Python (NoSQL API). Use for document CRUD, queries, containers, and globally distributed data. Triggers: "cosmos db", "CosmosClient", "container", "document", "NoSQL", "partition key". package: azure-cosmos diff --git a/web-app/public/skills/azure-cosmos-rust/SKILL.md b/web-app/public/skills/azure-cosmos-rust/SKILL.md index d8e3ad7a..ec7387aa 100644 --- a/web-app/public/skills/azure-cosmos-rust/SKILL.md +++ b/web-app/public/skills/azure-cosmos-rust/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-cosmos-rust -description: "|" +description: | Azure Cosmos DB SDK for Rust (NoSQL API). Use for document CRUD, queries, containers, and globally distributed data. Triggers: "cosmos db rust", "CosmosClient rust", "container", "document rust", "NoSQL rust", "partition key". package: azure_data_cosmos diff --git a/web-app/public/skills/azure-cosmos-ts/SKILL.md b/web-app/public/skills/azure-cosmos-ts/SKILL.md index a6a2a5cf..d09d11a2 100644 --- a/web-app/public/skills/azure-cosmos-ts/SKILL.md +++ b/web-app/public/skills/azure-cosmos-ts/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-cosmos-ts -description: "|" +description: | Azure Cosmos DB JavaScript/TypeScript SDK (@azure/cosmos) for data plane operations. Use for CRUD operations on documents, queries, bulk operations, and container management. Triggers: "Cosmos DB", "@azure/cosmos", "CosmosClient", "document CRUD", "NoSQL queries", "bulk operations", "partition key", "container.items". package: "@azure/cosmos" risk: unknown diff --git a/web-app/public/skills/azure-data-tables-py/SKILL.md b/web-app/public/skills/azure-data-tables-py/SKILL.md index 7abbdcd5..6fedc112 100644 --- a/web-app/public/skills/azure-data-tables-py/SKILL.md +++ b/web-app/public/skills/azure-data-tables-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-data-tables-py -description: "|" +description: | Azure Tables SDK for Python (Storage and Cosmos DB). Use for NoSQL key-value storage, entity CRUD, and batch operations. Triggers: "table storage", "TableServiceClient", "TableClient", "entities", "PartitionKey", "RowKey". package: azure-data-tables diff --git a/web-app/public/skills/azure-eventgrid-dotnet/SKILL.md b/web-app/public/skills/azure-eventgrid-dotnet/SKILL.md index 0f180e9c..3fca07ca 100644 --- a/web-app/public/skills/azure-eventgrid-dotnet/SKILL.md +++ b/web-app/public/skills/azure-eventgrid-dotnet/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-eventgrid-dotnet -description: "|" +description: | Azure Event Grid SDK for .NET. Client library for publishing and consuming events with Azure Event Grid. Use for event-driven architectures, pub/sub messaging, CloudEvents, and EventGridEvents. Triggers: "Event Grid", "EventGridPublisherClient", "CloudEvent", "EventGridEvent", "publish events .NET", "event-driven", "pub/sub". package: Azure.Messaging.EventGrid risk: unknown diff --git a/web-app/public/skills/azure-eventgrid-py/SKILL.md b/web-app/public/skills/azure-eventgrid-py/SKILL.md index ddfe5c1f..bb801f99 100644 --- a/web-app/public/skills/azure-eventgrid-py/SKILL.md +++ b/web-app/public/skills/azure-eventgrid-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-eventgrid-py -description: "|" +description: | Azure Event Grid SDK for Python. Use for publishing events, handling CloudEvents, and event-driven architectures. Triggers: "event grid", "EventGridPublisherClient", "CloudEvent", "EventGridEvent", "publish events". package: azure-eventgrid diff --git a/web-app/public/skills/azure-eventhub-dotnet/SKILL.md b/web-app/public/skills/azure-eventhub-dotnet/SKILL.md index 1ba7c843..06cf909e 100644 --- a/web-app/public/skills/azure-eventhub-dotnet/SKILL.md +++ b/web-app/public/skills/azure-eventhub-dotnet/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-eventhub-dotnet -description: "|" +description: | Azure Event Hubs SDK for .NET. Use for high-throughput event streaming: sending events (EventHubProducerClient, EventHubBufferedProducerClient), receiving events (EventProcessorClient with checkpointing), partition management, and real-time data ingestion. Triggers: "Event Hubs", "event streaming", "EventHubProducerClient", "EventProcessorClient", "send events", "receive events", "checkpointing", "partition". package: Azure.Messaging.EventHubs risk: unknown diff --git a/web-app/public/skills/azure-eventhub-py/SKILL.md b/web-app/public/skills/azure-eventhub-py/SKILL.md index 3914b7c8..82da2387 100644 --- a/web-app/public/skills/azure-eventhub-py/SKILL.md +++ b/web-app/public/skills/azure-eventhub-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-eventhub-py -description: "|" +description: | Azure Event Hubs SDK for Python streaming. Use for high-throughput event ingestion, producers, consumers, and checkpointing. Triggers: "event hubs", "EventHubProducerClient", "EventHubConsumerClient", "streaming", "partitions". package: azure-eventhub diff --git a/web-app/public/skills/azure-eventhub-rust/SKILL.md b/web-app/public/skills/azure-eventhub-rust/SKILL.md index 702cc64e..2477807e 100644 --- a/web-app/public/skills/azure-eventhub-rust/SKILL.md +++ b/web-app/public/skills/azure-eventhub-rust/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-eventhub-rust -description: "|" +description: | Azure Event Hubs SDK for Rust. Use for sending and receiving events, streaming data ingestion. Triggers: "event hubs rust", "ProducerClient rust", "ConsumerClient rust", "send event rust", "streaming rust". package: azure_messaging_eventhubs diff --git a/web-app/public/skills/azure-identity-dotnet/SKILL.md b/web-app/public/skills/azure-identity-dotnet/SKILL.md index d8e4b54e..c3be00b7 100644 --- a/web-app/public/skills/azure-identity-dotnet/SKILL.md +++ b/web-app/public/skills/azure-identity-dotnet/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-identity-dotnet -description: "|" +description: | Azure Identity SDK for .NET. Authentication library for Azure SDK clients using Microsoft Entra ID. Use for DefaultAzureCredential, managed identity, service principals, and developer credentials. Triggers: "Azure Identity", "DefaultAzureCredential", "ManagedIdentityCredential", "ClientSecretCredential", "authentication .NET", "Azure auth", "credential chain". package: Azure.Identity risk: unknown diff --git a/web-app/public/skills/azure-identity-py/SKILL.md b/web-app/public/skills/azure-identity-py/SKILL.md index 88555e3c..c55dad89 100644 --- a/web-app/public/skills/azure-identity-py/SKILL.md +++ b/web-app/public/skills/azure-identity-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-identity-py -description: "|" +description: | Azure Identity SDK for Python authentication. Use for DefaultAzureCredential, managed identity, service principals, and token caching. Triggers: "azure-identity", "DefaultAzureCredential", "authentication", "managed identity", "service principal", "credential". package: azure-identity diff --git a/web-app/public/skills/azure-identity-rust/SKILL.md b/web-app/public/skills/azure-identity-rust/SKILL.md index 8ed389ce..c2583c0f 100644 --- a/web-app/public/skills/azure-identity-rust/SKILL.md +++ b/web-app/public/skills/azure-identity-rust/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-identity-rust -description: "|" +description: | Azure Identity SDK for Rust authentication. Use for DeveloperToolsCredential, ManagedIdentityCredential, ClientSecretCredential, and token-based authentication. Triggers: "azure-identity", "DeveloperToolsCredential", "authentication rust", "managed identity rust", "credential rust". package: azure_identity diff --git a/web-app/public/skills/azure-keyvault-certificates-rust/SKILL.md b/web-app/public/skills/azure-keyvault-certificates-rust/SKILL.md index 60452370..b46965d4 100644 --- a/web-app/public/skills/azure-keyvault-certificates-rust/SKILL.md +++ b/web-app/public/skills/azure-keyvault-certificates-rust/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-keyvault-certificates-rust -description: "|" +description: | Azure Key Vault Certificates SDK for Rust. Use for creating, importing, and managing certificates. Triggers: "keyvault certificates rust", "CertificateClient rust", "create certificate rust", "import certificate rust". package: azure_security_keyvault_certificates diff --git a/web-app/public/skills/azure-keyvault-keys-rust/SKILL.md b/web-app/public/skills/azure-keyvault-keys-rust/SKILL.md index c88a11e3..516fadcb 100644 --- a/web-app/public/skills/azure-keyvault-keys-rust/SKILL.md +++ b/web-app/public/skills/azure-keyvault-keys-rust/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-keyvault-keys-rust -description: "|" +description: | Azure Key Vault Keys SDK for Rust. Use for creating, managing, and using cryptographic keys. Triggers: "keyvault keys rust", "KeyClient rust", "create key rust", "encrypt rust", "sign rust". package: azure_security_keyvault_keys diff --git a/web-app/public/skills/azure-keyvault-py/SKILL.md b/web-app/public/skills/azure-keyvault-py/SKILL.md index 0709c5fa..ac389a32 100644 --- a/web-app/public/skills/azure-keyvault-py/SKILL.md +++ b/web-app/public/skills/azure-keyvault-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-keyvault-py -description: "|" +description: | Azure Key Vault SDK for Python. Use for secrets, keys, and certificates management with secure storage. Triggers: "key vault", "SecretClient", "KeyClient", "CertificateClient", "secrets", "encryption keys". package: azure-keyvault-secrets, azure-keyvault-keys, azure-keyvault-certificates diff --git a/web-app/public/skills/azure-keyvault-secrets-rust/SKILL.md b/web-app/public/skills/azure-keyvault-secrets-rust/SKILL.md index af92fbd3..30422f93 100644 --- a/web-app/public/skills/azure-keyvault-secrets-rust/SKILL.md +++ b/web-app/public/skills/azure-keyvault-secrets-rust/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-keyvault-secrets-rust -description: "|" +description: | Azure Key Vault Secrets SDK for Rust. Use for storing and retrieving secrets, passwords, and API keys. Triggers: "keyvault secrets rust", "SecretClient rust", "get secret rust", "set secret rust". package: azure_security_keyvault_secrets diff --git a/web-app/public/skills/azure-maps-search-dotnet/SKILL.md b/web-app/public/skills/azure-maps-search-dotnet/SKILL.md index 7fd23ea8..5688d5a1 100644 --- a/web-app/public/skills/azure-maps-search-dotnet/SKILL.md +++ b/web-app/public/skills/azure-maps-search-dotnet/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-maps-search-dotnet -description: "|" +description: | Azure Maps SDK for .NET. Location-based services including geocoding, routing, rendering, geolocation, and weather. Use for address search, directions, map tiles, IP geolocation, and weather data. Triggers: "Azure Maps", "MapsSearchClient", "MapsRoutingClient", "MapsRenderingClient", "geocoding .NET", "route directions", "map tiles", "geolocation". package: Azure.Maps.Search risk: unknown diff --git a/web-app/public/skills/azure-messaging-webpubsubservice-py/SKILL.md b/web-app/public/skills/azure-messaging-webpubsubservice-py/SKILL.md index e0c1f565..b3a686c8 100644 --- a/web-app/public/skills/azure-messaging-webpubsubservice-py/SKILL.md +++ b/web-app/public/skills/azure-messaging-webpubsubservice-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-messaging-webpubsubservice-py -description: "|" +description: | Azure Web PubSub Service SDK for Python. Use for real-time messaging, WebSocket connections, and pub/sub patterns. Triggers: "azure-messaging-webpubsubservice", "WebPubSubServiceClient", "real-time", "WebSocket", "pub/sub". package: azure-messaging-webpubsubservice diff --git a/web-app/public/skills/azure-mgmt-apicenter-dotnet/SKILL.md b/web-app/public/skills/azure-mgmt-apicenter-dotnet/SKILL.md index e5052bb2..cfa82d7b 100644 --- a/web-app/public/skills/azure-mgmt-apicenter-dotnet/SKILL.md +++ b/web-app/public/skills/azure-mgmt-apicenter-dotnet/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-mgmt-apicenter-dotnet -description: "|" +description: | Azure API Center SDK for .NET. Centralized API inventory management with governance, versioning, and discovery. Use for creating API services, workspaces, APIs, versions, definitions, environments, deployments, and metadata schemas. Triggers: "API Center", "ApiCenterService", "ApiCenterWorkspace", "ApiCenterApi", "API inventory", "API governance", "API versioning", "API catalog", "API discovery". package: Azure.ResourceManager.ApiCenter risk: unknown diff --git a/web-app/public/skills/azure-mgmt-apicenter-py/SKILL.md b/web-app/public/skills/azure-mgmt-apicenter-py/SKILL.md index 2a07de6d..6b0a39dc 100644 --- a/web-app/public/skills/azure-mgmt-apicenter-py/SKILL.md +++ b/web-app/public/skills/azure-mgmt-apicenter-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-mgmt-apicenter-py -description: "|" +description: | Azure API Center Management SDK for Python. Use for managing API inventory, metadata, and governance across your organization. Triggers: "azure-mgmt-apicenter", "ApiCenterMgmtClient", "API Center", "API inventory", "API governance". package: azure-mgmt-apicenter diff --git a/web-app/public/skills/azure-mgmt-apimanagement-dotnet/SKILL.md b/web-app/public/skills/azure-mgmt-apimanagement-dotnet/SKILL.md index 19df092d..73fe5274 100644 --- a/web-app/public/skills/azure-mgmt-apimanagement-dotnet/SKILL.md +++ b/web-app/public/skills/azure-mgmt-apimanagement-dotnet/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-mgmt-apimanagement-dotnet -description: "|" +description: | Azure Resource Manager SDK for API Management in .NET. Use for MANAGEMENT PLANE operations: creating/managing APIM services, APIs, products, subscriptions, policies, users, groups, gateways, and backends via Azure Resource Manager. Triggers: "API Management", "APIM service", "create APIM", "manage APIs", "ApiManagementServiceResource", "API policies", "APIM products", "APIM subscriptions". package: Azure.ResourceManager.ApiManagement risk: unknown diff --git a/web-app/public/skills/azure-mgmt-apimanagement-py/SKILL.md b/web-app/public/skills/azure-mgmt-apimanagement-py/SKILL.md index 64d63bd0..b0d4dcbc 100644 --- a/web-app/public/skills/azure-mgmt-apimanagement-py/SKILL.md +++ b/web-app/public/skills/azure-mgmt-apimanagement-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-mgmt-apimanagement-py -description: "|" +description: | Azure API Management SDK for Python. Use for managing APIM services, APIs, products, subscriptions, and policies. Triggers: "azure-mgmt-apimanagement", "ApiManagementClient", "APIM", "API gateway", "API Management". package: azure-mgmt-apimanagement diff --git a/web-app/public/skills/azure-mgmt-applicationinsights-dotnet/SKILL.md b/web-app/public/skills/azure-mgmt-applicationinsights-dotnet/SKILL.md index d94beffc..d9a0482f 100644 --- a/web-app/public/skills/azure-mgmt-applicationinsights-dotnet/SKILL.md +++ b/web-app/public/skills/azure-mgmt-applicationinsights-dotnet/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-mgmt-applicationinsights-dotnet -description: "|" +description: | Azure Application Insights SDK for .NET. Application performance monitoring and observability resource management. Use for creating Application Insights components, web tests, workbooks, analytics items, and API keys. Triggers: "Application Insights", "ApplicationInsights", "App Insights", "APM", "application monitoring", "web tests", "availability tests", "workbooks". package: Azure.ResourceManager.ApplicationInsights risk: unknown diff --git a/web-app/public/skills/azure-mgmt-arizeaiobservabilityeval-dotnet/SKILL.md b/web-app/public/skills/azure-mgmt-arizeaiobservabilityeval-dotnet/SKILL.md index 4330e176..b8c213df 100644 --- a/web-app/public/skills/azure-mgmt-arizeaiobservabilityeval-dotnet/SKILL.md +++ b/web-app/public/skills/azure-mgmt-arizeaiobservabilityeval-dotnet/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-mgmt-arizeaiobservabilityeval-dotnet -description: "|" +description: | Azure Resource Manager SDK for Arize AI Observability and Evaluation (.NET). Use when managing Arize AI organizations on Azure via Azure Marketplace, creating/updating/deleting Arize resources, or integrating Arize ML observability into .NET applications. Triggers: "Arize AI", "ML observability", "ArizeAIObservabilityEval", "Arize organization". diff --git a/web-app/public/skills/azure-mgmt-botservice-dotnet/SKILL.md b/web-app/public/skills/azure-mgmt-botservice-dotnet/SKILL.md index 94d8824f..56bbcabd 100644 --- a/web-app/public/skills/azure-mgmt-botservice-dotnet/SKILL.md +++ b/web-app/public/skills/azure-mgmt-botservice-dotnet/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-mgmt-botservice-dotnet -description: "|" +description: | Azure Resource Manager SDK for Bot Service in .NET. Management plane operations for creating and managing Azure Bot resources, channels (Teams, DirectLine, Slack), and connection settings. Triggers: "Bot Service", "BotResource", "Azure Bot", "DirectLine channel", "Teams channel", "bot management .NET", "create bot". package: Azure.ResourceManager.BotService risk: unknown diff --git a/web-app/public/skills/azure-mgmt-botservice-py/SKILL.md b/web-app/public/skills/azure-mgmt-botservice-py/SKILL.md index c6b851be..b954c17f 100644 --- a/web-app/public/skills/azure-mgmt-botservice-py/SKILL.md +++ b/web-app/public/skills/azure-mgmt-botservice-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-mgmt-botservice-py -description: "|" +description: | Azure Bot Service Management SDK for Python. Use for creating, managing, and configuring Azure Bot Service resources. Triggers: "azure-mgmt-botservice", "AzureBotService", "bot management", "conversational AI", "bot channels". risk: unknown diff --git a/web-app/public/skills/azure-mgmt-fabric-dotnet/SKILL.md b/web-app/public/skills/azure-mgmt-fabric-dotnet/SKILL.md index 9721d0dd..6076541f 100644 --- a/web-app/public/skills/azure-mgmt-fabric-dotnet/SKILL.md +++ b/web-app/public/skills/azure-mgmt-fabric-dotnet/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-mgmt-fabric-dotnet -description: "|" +description: | Azure Resource Manager SDK for Fabric in .NET. Use for MANAGEMENT PLANE operations: provisioning, scaling, suspending/resuming Microsoft Fabric capacities, checking name availability, and listing SKUs via Azure Resource Manager. Triggers: "Fabric capacity", "create capacity", "suspend capacity", "resume capacity", "Fabric SKU", "provision Fabric", "ARM Fabric", "FabricCapacityResource". package: Azure.ResourceManager.Fabric risk: unknown diff --git a/web-app/public/skills/azure-mgmt-fabric-py/SKILL.md b/web-app/public/skills/azure-mgmt-fabric-py/SKILL.md index 2e2ff79b..e4c78ea3 100644 --- a/web-app/public/skills/azure-mgmt-fabric-py/SKILL.md +++ b/web-app/public/skills/azure-mgmt-fabric-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-mgmt-fabric-py -description: "|" +description: | Azure Fabric Management SDK for Python. Use for managing Microsoft Fabric capacities and resources. Triggers: "azure-mgmt-fabric", "FabricMgmtClient", "Fabric capacity", "Microsoft Fabric", "Power BI capacity". risk: unknown diff --git a/web-app/public/skills/azure-mgmt-weightsandbiases-dotnet/SKILL.md b/web-app/public/skills/azure-mgmt-weightsandbiases-dotnet/SKILL.md index c08a2fd3..ece97788 100644 --- a/web-app/public/skills/azure-mgmt-weightsandbiases-dotnet/SKILL.md +++ b/web-app/public/skills/azure-mgmt-weightsandbiases-dotnet/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-mgmt-weightsandbiases-dotnet -description: "|" +description: | Azure Weights & Biases SDK for .NET. ML experiment tracking and model management via Azure Marketplace. Use for creating W&B instances, managing SSO, marketplace integration, and ML observability. Triggers: "Weights and Biases", "W&B", "WeightsAndBiases", "ML experiment tracking", "model registry", "experiment management", "wandb". package: Azure.ResourceManager.WeightsAndBiases risk: unknown diff --git a/web-app/public/skills/azure-monitor-ingestion-java/SKILL.md b/web-app/public/skills/azure-monitor-ingestion-java/SKILL.md index a288b279..dbba70cc 100644 --- a/web-app/public/skills/azure-monitor-ingestion-java/SKILL.md +++ b/web-app/public/skills/azure-monitor-ingestion-java/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-monitor-ingestion-java -description: "|" +description: | Azure Monitor Ingestion SDK for Java. Send custom logs to Azure Monitor via Data Collection Rules (DCR) and Data Collection Endpoints (DCE). Triggers: "LogsIngestionClient java", "azure monitor ingestion java", "custom logs java", "DCR java", "data collection rule java". package: com.azure:azure-monitor-ingestion diff --git a/web-app/public/skills/azure-monitor-ingestion-py/SKILL.md b/web-app/public/skills/azure-monitor-ingestion-py/SKILL.md index c14e9c95..cff95c04 100644 --- a/web-app/public/skills/azure-monitor-ingestion-py/SKILL.md +++ b/web-app/public/skills/azure-monitor-ingestion-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-monitor-ingestion-py -description: "|" +description: | Azure Monitor Ingestion SDK for Python. Use for sending custom logs to Log Analytics workspace via Logs Ingestion API. Triggers: "azure-monitor-ingestion", "LogsIngestionClient", "custom logs", "DCR", "data collection rule", "Log Analytics". package: azure-monitor-ingestion diff --git a/web-app/public/skills/azure-monitor-opentelemetry-exporter-java/SKILL.md b/web-app/public/skills/azure-monitor-opentelemetry-exporter-java/SKILL.md index 5cbddf1d..275c343c 100644 --- a/web-app/public/skills/azure-monitor-opentelemetry-exporter-java/SKILL.md +++ b/web-app/public/skills/azure-monitor-opentelemetry-exporter-java/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-monitor-opentelemetry-exporter-java -description: "|" +description: | Azure Monitor OpenTelemetry Exporter for Java. Export OpenTelemetry traces, metrics, and logs to Azure Monitor/Application Insights. Triggers: "AzureMonitorExporter java", "opentelemetry azure java", "application insights java otel", "azure monitor tracing java". Note: This package is DEPRECATED. Migrate to azure-monitor-opentelemetry-autoconfigure. diff --git a/web-app/public/skills/azure-monitor-opentelemetry-exporter-py/SKILL.md b/web-app/public/skills/azure-monitor-opentelemetry-exporter-py/SKILL.md index b78077e4..3218be18 100644 --- a/web-app/public/skills/azure-monitor-opentelemetry-exporter-py/SKILL.md +++ b/web-app/public/skills/azure-monitor-opentelemetry-exporter-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-monitor-opentelemetry-exporter-py -description: "|" +description: | Azure Monitor OpenTelemetry Exporter for Python. Use for low-level OpenTelemetry export to Application Insights. Triggers: "azure-monitor-opentelemetry-exporter", "AzureMonitorTraceExporter", "AzureMonitorMetricExporter", "AzureMonitorLogExporter". package: azure-monitor-opentelemetry-exporter diff --git a/web-app/public/skills/azure-monitor-opentelemetry-py/SKILL.md b/web-app/public/skills/azure-monitor-opentelemetry-py/SKILL.md index 93739fcf..b9f55503 100644 --- a/web-app/public/skills/azure-monitor-opentelemetry-py/SKILL.md +++ b/web-app/public/skills/azure-monitor-opentelemetry-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-monitor-opentelemetry-py -description: "|" +description: | Azure Monitor OpenTelemetry Distro for Python. Use for one-line Application Insights setup with auto-instrumentation. Triggers: "azure-monitor-opentelemetry", "configure_azure_monitor", "Application Insights", "OpenTelemetry distro", "auto-instrumentation". package: azure-monitor-opentelemetry diff --git a/web-app/public/skills/azure-monitor-query-java/SKILL.md b/web-app/public/skills/azure-monitor-query-java/SKILL.md index f03398d1..02db8627 100644 --- a/web-app/public/skills/azure-monitor-query-java/SKILL.md +++ b/web-app/public/skills/azure-monitor-query-java/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-monitor-query-java -description: "|" +description: | Azure Monitor Query SDK for Java. Execute Kusto queries against Log Analytics workspaces and query metrics from Azure resources. Triggers: "LogsQueryClient java", "MetricsQueryClient java", "kusto query java", "log analytics java", "azure monitor query java". Note: This package is deprecated. Migrate to azure-monitor-query-logs and azure-monitor-query-metrics. diff --git a/web-app/public/skills/azure-monitor-query-py/SKILL.md b/web-app/public/skills/azure-monitor-query-py/SKILL.md index 44c5028e..36fa0a65 100644 --- a/web-app/public/skills/azure-monitor-query-py/SKILL.md +++ b/web-app/public/skills/azure-monitor-query-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-monitor-query-py -description: "|" +description: | Azure Monitor Query SDK for Python. Use for querying Log Analytics workspaces and Azure Monitor metrics. Triggers: "azure-monitor-query", "LogsQueryClient", "MetricsQueryClient", "Log Analytics", "Kusto queries", "Azure metrics". package: azure-monitor-query diff --git a/web-app/public/skills/azure-postgres-ts/SKILL.md b/web-app/public/skills/azure-postgres-ts/SKILL.md index 23ebed5f..76f2adff 100644 --- a/web-app/public/skills/azure-postgres-ts/SKILL.md +++ b/web-app/public/skills/azure-postgres-ts/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-postgres-ts -description: "|" +description: | Connect to Azure Database for PostgreSQL Flexible Server from Node.js/TypeScript using the pg (node-postgres) package. Use for PostgreSQL queries, connection pooling, transactions, and Microsoft Entra ID (passwordless) authentication. Triggers: "PostgreSQL", "postgres", "pg client", "node-postgres", "Azure PostgreSQL connection", "PostgreSQL TypeScript", "pg Pool", "passwordless postgres". package: pg risk: unknown diff --git a/web-app/public/skills/azure-resource-manager-cosmosdb-dotnet/SKILL.md b/web-app/public/skills/azure-resource-manager-cosmosdb-dotnet/SKILL.md index b5a1633e..d525cc85 100644 --- a/web-app/public/skills/azure-resource-manager-cosmosdb-dotnet/SKILL.md +++ b/web-app/public/skills/azure-resource-manager-cosmosdb-dotnet/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-resource-manager-cosmosdb-dotnet -description: "|" +description: | Azure Resource Manager SDK for Cosmos DB in .NET. Use for MANAGEMENT PLANE operations: creating/managing Cosmos DB accounts, databases, containers, throughput settings, and RBAC via Azure Resource Manager. NOT for data plane operations (CRUD on documents) - use Microsoft.Azure.Cosmos for that. Triggers: "Cosmos DB account", "create Cosmos account", "manage Cosmos resources", "ARM Cosmos", "CosmosDBAccountResource", "provision Cosmos DB". package: Azure.ResourceManager.CosmosDB risk: unknown diff --git a/web-app/public/skills/azure-resource-manager-durabletask-dotnet/SKILL.md b/web-app/public/skills/azure-resource-manager-durabletask-dotnet/SKILL.md index 40f79c81..0aaff756 100644 --- a/web-app/public/skills/azure-resource-manager-durabletask-dotnet/SKILL.md +++ b/web-app/public/skills/azure-resource-manager-durabletask-dotnet/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-resource-manager-durabletask-dotnet -description: "|" +description: | Azure Resource Manager SDK for Durable Task Scheduler in .NET. Use for MANAGEMENT PLANE operations: creating/managing Durable Task Schedulers, Task Hubs, and retention policies via Azure Resource Manager. Triggers: "Durable Task Scheduler", "create scheduler", "task hub", "DurableTaskSchedulerResource", "provision Durable Task", "orchestration scheduler". package: Azure.ResourceManager.DurableTask risk: unknown diff --git a/web-app/public/skills/azure-resource-manager-mysql-dotnet/SKILL.md b/web-app/public/skills/azure-resource-manager-mysql-dotnet/SKILL.md index 6a5140d9..20ae4466 100644 --- a/web-app/public/skills/azure-resource-manager-mysql-dotnet/SKILL.md +++ b/web-app/public/skills/azure-resource-manager-mysql-dotnet/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-resource-manager-mysql-dotnet -description: "|" +description: | Azure MySQL Flexible Server SDK for .NET. Database management for MySQL Flexible Server deployments. Use for creating servers, databases, firewall rules, configurations, backups, and high availability. Triggers: "MySQL", "MySqlFlexibleServer", "MySQL Flexible Server", "Azure Database for MySQL", "MySQL database management", "MySQL firewall", "MySQL backup". package: Azure.ResourceManager.MySql risk: unknown diff --git a/web-app/public/skills/azure-resource-manager-playwright-dotnet/SKILL.md b/web-app/public/skills/azure-resource-manager-playwright-dotnet/SKILL.md index ad780184..afb448fc 100644 --- a/web-app/public/skills/azure-resource-manager-playwright-dotnet/SKILL.md +++ b/web-app/public/skills/azure-resource-manager-playwright-dotnet/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-resource-manager-playwright-dotnet -description: "|" +description: | Azure Resource Manager SDK for Microsoft Playwright Testing in .NET. Use for MANAGEMENT PLANE operations: creating/managing Playwright Testing workspaces, checking name availability, and managing workspace quotas via Azure Resource Manager. NOT for running Playwright tests - use Azure.Developer.MicrosoftPlaywrightTesting.NUnit for that. Triggers: "Playwright workspace", "create Playwright Testing workspace", "manage Playwright resources", "ARM Playwright", "PlaywrightWorkspaceResource", "provision Playwright Testing". package: Azure.ResourceManager.Playwright risk: unknown diff --git a/web-app/public/skills/azure-resource-manager-postgresql-dotnet/SKILL.md b/web-app/public/skills/azure-resource-manager-postgresql-dotnet/SKILL.md index c3cefe84..f8319426 100644 --- a/web-app/public/skills/azure-resource-manager-postgresql-dotnet/SKILL.md +++ b/web-app/public/skills/azure-resource-manager-postgresql-dotnet/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-resource-manager-postgresql-dotnet -description: "|" +description: | Azure PostgreSQL Flexible Server SDK for .NET. Database management for PostgreSQL Flexible Server deployments. Use for creating servers, databases, firewall rules, configurations, backups, and high availability. Triggers: "PostgreSQL", "PostgreSqlFlexibleServer", "PostgreSQL Flexible Server", "Azure Database for PostgreSQL", "PostgreSQL database management", "PostgreSQL firewall", "PostgreSQL backup", "Postgres". package: Azure.ResourceManager.PostgreSql risk: unknown diff --git a/web-app/public/skills/azure-resource-manager-redis-dotnet/SKILL.md b/web-app/public/skills/azure-resource-manager-redis-dotnet/SKILL.md index 96175c18..7fa278b1 100644 --- a/web-app/public/skills/azure-resource-manager-redis-dotnet/SKILL.md +++ b/web-app/public/skills/azure-resource-manager-redis-dotnet/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-resource-manager-redis-dotnet -description: "|" +description: | Azure Resource Manager SDK for Redis in .NET. Use for MANAGEMENT PLANE operations: creating/managing Azure Cache for Redis instances, firewall rules, access keys, patch schedules, linked servers (geo-replication), and private endpoints via Azure Resource Manager. NOT for data plane operations (get/set keys, pub/sub) - use StackExchange.Redis for that. Triggers: "Redis cache", "create Redis", "manage Redis", "ARM Redis", "RedisResource", "provision Redis", "Azure Cache for Redis". package: Azure.ResourceManager.Redis risk: unknown diff --git a/web-app/public/skills/azure-resource-manager-sql-dotnet/SKILL.md b/web-app/public/skills/azure-resource-manager-sql-dotnet/SKILL.md index 0f98adf5..3da3fa13 100644 --- a/web-app/public/skills/azure-resource-manager-sql-dotnet/SKILL.md +++ b/web-app/public/skills/azure-resource-manager-sql-dotnet/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-resource-manager-sql-dotnet -description: "|" +description: | Azure Resource Manager SDK for Azure SQL in .NET. Use for MANAGEMENT PLANE operations: creating/managing SQL servers, databases, elastic pools, firewall rules, and failover groups via Azure Resource Manager. NOT for data plane operations (executing queries) - use Microsoft.Data.SqlClient for that. Triggers: "SQL server", "create SQL database", "manage SQL resources", "ARM SQL", "SqlServerResource", "provision Azure SQL", "elastic pool", "firewall rule". package: Azure.ResourceManager.Sql risk: unknown diff --git a/web-app/public/skills/azure-search-documents-dotnet/SKILL.md b/web-app/public/skills/azure-search-documents-dotnet/SKILL.md index 954fad18..d3d61d12 100644 --- a/web-app/public/skills/azure-search-documents-dotnet/SKILL.md +++ b/web-app/public/skills/azure-search-documents-dotnet/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-search-documents-dotnet -description: "|" +description: | Azure AI Search SDK for .NET (Azure.Search.Documents). Use for building search applications with full-text, vector, semantic, and hybrid search. Covers SearchClient (queries, document CRUD), SearchIndexClient (index management), and SearchIndexerClient (indexers, skillsets). Triggers: "Azure Search .NET", "SearchClient", "SearchIndexClient", "vector search C#", "semantic search .NET", "hybrid search", "Azure.Search.Documents". package: Azure.Search.Documents risk: unknown diff --git a/web-app/public/skills/azure-search-documents-py/SKILL.md b/web-app/public/skills/azure-search-documents-py/SKILL.md index a481063b..a759bdef 100644 --- a/web-app/public/skills/azure-search-documents-py/SKILL.md +++ b/web-app/public/skills/azure-search-documents-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-search-documents-py -description: "|" +description: | Azure AI Search SDK for Python. Use for vector search, hybrid search, semantic ranking, indexing, and skillsets. Triggers: "azure-search-documents", "SearchClient", "SearchIndexClient", "vector search", "hybrid search", "semantic search". package: azure-search-documents diff --git a/web-app/public/skills/azure-security-keyvault-keys-dotnet/SKILL.md b/web-app/public/skills/azure-security-keyvault-keys-dotnet/SKILL.md index ba20d0e2..68d1266c 100644 --- a/web-app/public/skills/azure-security-keyvault-keys-dotnet/SKILL.md +++ b/web-app/public/skills/azure-security-keyvault-keys-dotnet/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-security-keyvault-keys-dotnet -description: "|" +description: | Azure Key Vault Keys SDK for .NET. Client library for managing cryptographic keys in Azure Key Vault and Managed HSM. Use for key creation, rotation, encryption, decryption, signing, and verification. Triggers: "Key Vault keys", "KeyClient", "CryptographyClient", "RSA key", "EC key", "encrypt decrypt .NET", "key rotation", "HSM". package: Azure.Security.KeyVault.Keys risk: unknown diff --git a/web-app/public/skills/azure-servicebus-dotnet/SKILL.md b/web-app/public/skills/azure-servicebus-dotnet/SKILL.md index 22fb9891..f35c51bb 100644 --- a/web-app/public/skills/azure-servicebus-dotnet/SKILL.md +++ b/web-app/public/skills/azure-servicebus-dotnet/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-servicebus-dotnet -description: "|" +description: | Azure Service Bus SDK for .NET. Enterprise messaging with queues, topics, subscriptions, and sessions. Use for reliable message delivery, pub/sub patterns, dead letter handling, and background processing. Triggers: "Service Bus", "ServiceBusClient", "ServiceBusSender", "ServiceBusReceiver", "ServiceBusProcessor", "message queue", "pub/sub .NET", "dead letter queue". package: Azure.Messaging.ServiceBus risk: unknown diff --git a/web-app/public/skills/azure-servicebus-py/SKILL.md b/web-app/public/skills/azure-servicebus-py/SKILL.md index 6e82b598..48e59609 100644 --- a/web-app/public/skills/azure-servicebus-py/SKILL.md +++ b/web-app/public/skills/azure-servicebus-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-servicebus-py -description: "|" +description: | Azure Service Bus SDK for Python messaging. Use for queues, topics, subscriptions, and enterprise messaging patterns. Triggers: "service bus", "ServiceBusClient", "queue", "topic", "subscription", "message broker". package: azure-servicebus diff --git a/web-app/public/skills/azure-speech-to-text-rest-py/SKILL.md b/web-app/public/skills/azure-speech-to-text-rest-py/SKILL.md index a9781432..e1f7de6d 100644 --- a/web-app/public/skills/azure-speech-to-text-rest-py/SKILL.md +++ b/web-app/public/skills/azure-speech-to-text-rest-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-speech-to-text-rest-py -description: "|" +description: | Azure Speech to Text REST API for short audio (Python). Use for simple speech recognition of audio files up to 60 seconds without the Speech SDK. Triggers: "speech to text REST", "short audio transcription", "speech recognition REST API", "STT REST", "recognize speech REST". DO NOT USE FOR: Long audio (>60 seconds), real-time streaming, batch transcription, custom speech models, speech translation. Use Speech SDK or Batch Transcription API instead. diff --git a/web-app/public/skills/azure-storage-blob-py/SKILL.md b/web-app/public/skills/azure-storage-blob-py/SKILL.md index 6ebe6b36..f97d7347 100644 --- a/web-app/public/skills/azure-storage-blob-py/SKILL.md +++ b/web-app/public/skills/azure-storage-blob-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-storage-blob-py -description: "|" +description: | Azure Blob Storage SDK for Python. Use for uploading, downloading, listing blobs, managing containers, and blob lifecycle. Triggers: "blob storage", "BlobServiceClient", "ContainerClient", "BlobClient", "upload blob", "download blob". package: azure-storage-blob diff --git a/web-app/public/skills/azure-storage-blob-rust/SKILL.md b/web-app/public/skills/azure-storage-blob-rust/SKILL.md index 2b43e56b..26d565e6 100644 --- a/web-app/public/skills/azure-storage-blob-rust/SKILL.md +++ b/web-app/public/skills/azure-storage-blob-rust/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-storage-blob-rust -description: "|" +description: | Azure Blob Storage SDK for Rust. Use for uploading, downloading, and managing blobs and containers. Triggers: "blob storage rust", "BlobClient rust", "upload blob rust", "download blob rust", "container rust". package: azure_storage_blob diff --git a/web-app/public/skills/azure-storage-blob-ts/SKILL.md b/web-app/public/skills/azure-storage-blob-ts/SKILL.md index f941ba21..c5450d8c 100644 --- a/web-app/public/skills/azure-storage-blob-ts/SKILL.md +++ b/web-app/public/skills/azure-storage-blob-ts/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-storage-blob-ts -description: "|" +description: | Azure Blob Storage JavaScript/TypeScript SDK (@azure/storage-blob) for blob operations. Use for uploading, downloading, listing, and managing blobs and containers. Supports block blobs, append blobs, page blobs, SAS tokens, and streaming. Triggers: "blob storage", "@azure/storage-blob", "BlobServiceClient", "ContainerClient", "upload blob", "download blob", "SAS token", "block blob". package: "@azure/storage-blob" risk: unknown diff --git a/web-app/public/skills/azure-storage-file-datalake-py/SKILL.md b/web-app/public/skills/azure-storage-file-datalake-py/SKILL.md index 05c70fd8..585c9cbe 100644 --- a/web-app/public/skills/azure-storage-file-datalake-py/SKILL.md +++ b/web-app/public/skills/azure-storage-file-datalake-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-storage-file-datalake-py -description: "|" +description: | Azure Data Lake Storage Gen2 SDK for Python. Use for hierarchical file systems, big data analytics, and file/directory operations. Triggers: "data lake", "DataLakeServiceClient", "FileSystemClient", "ADLS Gen2", "hierarchical namespace". package: azure-storage-file-datalake diff --git a/web-app/public/skills/azure-storage-file-share-py/SKILL.md b/web-app/public/skills/azure-storage-file-share-py/SKILL.md index 2889a9ff..676952c1 100644 --- a/web-app/public/skills/azure-storage-file-share-py/SKILL.md +++ b/web-app/public/skills/azure-storage-file-share-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-storage-file-share-py -description: "|" +description: | Azure Storage File Share SDK for Python. Use for SMB file shares, directories, and file operations in the cloud. Triggers: "azure-storage-file-share", "ShareServiceClient", "ShareClient", "file share", "SMB". risk: unknown diff --git a/web-app/public/skills/azure-storage-file-share-ts/SKILL.md b/web-app/public/skills/azure-storage-file-share-ts/SKILL.md index 6e9bae7f..c6c0f24a 100644 --- a/web-app/public/skills/azure-storage-file-share-ts/SKILL.md +++ b/web-app/public/skills/azure-storage-file-share-ts/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-storage-file-share-ts -description: "|" +description: | Azure File Share JavaScript/TypeScript SDK (@azure/storage-file-share) for SMB file share operations. Use for creating shares, managing directories, uploading/downloading files, and handling file metadata. Supports Azure Files SMB protocol scenarios. Triggers: "file share", "@azure/storage-file-share", "ShareServiceClient", "ShareClient", "SMB", "Azure Files". package: "@azure/storage-file-share" risk: unknown diff --git a/web-app/public/skills/azure-storage-queue-py/SKILL.md b/web-app/public/skills/azure-storage-queue-py/SKILL.md index 38c91d03..39b4a270 100644 --- a/web-app/public/skills/azure-storage-queue-py/SKILL.md +++ b/web-app/public/skills/azure-storage-queue-py/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-storage-queue-py -description: "|" +description: | Azure Queue Storage SDK for Python. Use for reliable message queuing, task distribution, and asynchronous processing. Triggers: "queue storage", "QueueServiceClient", "QueueClient", "message queue", "dequeue". package: azure-storage-queue diff --git a/web-app/public/skills/azure-storage-queue-ts/SKILL.md b/web-app/public/skills/azure-storage-queue-ts/SKILL.md index d06d259f..244a5051 100644 --- a/web-app/public/skills/azure-storage-queue-ts/SKILL.md +++ b/web-app/public/skills/azure-storage-queue-ts/SKILL.md @@ -1,6 +1,6 @@ --- name: azure-storage-queue-ts -description: "|" +description: | Azure Queue Storage JavaScript/TypeScript SDK (@azure/storage-queue) for message queue operations. Use for sending, receiving, peeking, and deleting messages in queues. Supports visibility timeout, message encoding, and batch operations. Triggers: "queue storage", "@azure/storage-queue", "QueueServiceClient", "QueueClient", "send message", "receive message", "dequeue", "visibility timeout". package: "@azure/storage-queue" risk: unknown diff --git a/web-app/public/skills/backend-architect/SKILL.md b/web-app/public/skills/backend-architect/SKILL.md index e2283367..c5eba207 100644 --- a/web-app/public/skills/backend-architect/SKILL.md +++ b/web-app/public/skills/backend-architect/SKILL.md @@ -1,6 +1,7 @@ --- name: backend-architect -description: "Expert backend architect specializing in scalable API design," +description: | + Expert backend architect specializing in scalable API design, microservices architecture, and distributed systems. Masters REST/GraphQL/gRPC APIs, event-driven architectures, service mesh patterns, and modern backend frameworks. Handles service boundary definition, inter-service communication, diff --git a/web-app/public/skills/backend-security-coder/SKILL.md b/web-app/public/skills/backend-security-coder/SKILL.md index 799b496d..d97c9883 100644 --- a/web-app/public/skills/backend-security-coder/SKILL.md +++ b/web-app/public/skills/backend-security-coder/SKILL.md @@ -1,6 +1,7 @@ --- name: backend-security-coder -description: "Expert in secure backend coding practices specializing in input" +description: | + Expert in secure backend coding practices specializing in input validation, authentication, and API security. Use PROACTIVELY for backend security implementations or security code reviews. metadata: diff --git a/web-app/public/skills/bash-pro/SKILL.md b/web-app/public/skills/bash-pro/SKILL.md index 3beb7730..6dd19742 100644 --- a/web-app/public/skills/bash-pro/SKILL.md +++ b/web-app/public/skills/bash-pro/SKILL.md @@ -1,6 +1,7 @@ --- name: bash-pro -description: "Master of defensive Bash scripting for production automation, CI/CD" +description: | + Master of defensive Bash scripting for production automation, CI/CD pipelines, and system utilities. Expert in safe, portable, and testable shell scripts. metadata: diff --git a/web-app/public/skills/bevy-ecs-expert/SKILL.md b/web-app/public/skills/bevy-ecs-expert/SKILL.md index 7d6333e5..ebac97be 100644 --- a/web-app/public/skills/bevy-ecs-expert/SKILL.md +++ b/web-app/public/skills/bevy-ecs-expert/SKILL.md @@ -83,25 +83,27 @@ fn main() { ## Examples -### Example 1: Spawning Entities with Bundles +### Example 1: Spawning Entities with Require Component ```rust -#[derive(Bundle)] -struct PlayerBundle { - player: Player, - velocity: Velocity, - sprite: SpriteBundle, +use bevy::prelude::*; + +#[derive(Component, Reflect, Default)] +#[require(Velocity, Sprite)] +struct Player; + +#[derive(Component, Default)] +struct Velocity { + x: f32, + y: f32, } fn setup(mut commands: Commands, asset_server: Res) { - commands.spawn(PlayerBundle { - player: Player, - velocity: Velocity { x: 10.0, y: 0.0 }, - sprite: SpriteBundle { - texture: asset_server.load("player.png"), - ..default() - }, - }); + commands.spawn(( + Player, + Velocity { x: 10.0, y: 0.0 }, + Sprite::from_image(asset_server.load("player.png")), + )); } ``` diff --git a/web-app/public/skills/blockchain-developer/SKILL.md b/web-app/public/skills/blockchain-developer/SKILL.md index 192c89fb..c23f36d7 100644 --- a/web-app/public/skills/blockchain-developer/SKILL.md +++ b/web-app/public/skills/blockchain-developer/SKILL.md @@ -1,6 +1,7 @@ --- name: blockchain-developer -description: "Build production-ready Web3 applications, smart contracts, and" +description: | + Build production-ready Web3 applications, smart contracts, and decentralized systems. Implements DeFi protocols, NFT platforms, DAOs, and enterprise blockchain integrations. Use PROACTIVELY for smart contracts, Web3 apps, DeFi protocols, or blockchain infrastructure. diff --git a/web-app/public/skills/business-analyst/SKILL.md b/web-app/public/skills/business-analyst/SKILL.md index ca931200..1a4462b4 100644 --- a/web-app/public/skills/business-analyst/SKILL.md +++ b/web-app/public/skills/business-analyst/SKILL.md @@ -1,6 +1,7 @@ --- name: business-analyst -description: "Master modern business analysis with AI-powered analytics," +description: | + Master modern business analysis with AI-powered analytics, real-time dashboards, and data-driven insights. Build comprehensive KPI frameworks, predictive models, and strategic recommendations. Use PROACTIVELY for business intelligence or strategic analysis. diff --git a/web-app/public/skills/c4-code/SKILL.md b/web-app/public/skills/c4-code/SKILL.md index 333ab01b..59972a01 100644 --- a/web-app/public/skills/c4-code/SKILL.md +++ b/web-app/public/skills/c4-code/SKILL.md @@ -1,6 +1,7 @@ --- name: c4-code -description: "Expert C4 Code-level documentation specialist. Analyzes code" +description: | + Expert C4 Code-level documentation specialist. Analyzes code directories to create comprehensive C4 code-level documentation including function signatures, arguments, dependencies, and code structure. Use when documenting code at the lowest C4 level for individual directories and code diff --git a/web-app/public/skills/c4-component/SKILL.md b/web-app/public/skills/c4-component/SKILL.md index 64c14978..deca5509 100644 --- a/web-app/public/skills/c4-component/SKILL.md +++ b/web-app/public/skills/c4-component/SKILL.md @@ -1,6 +1,7 @@ --- name: c4-component -description: "Expert C4 Component-level documentation specialist. Synthesizes C4" +description: | + Expert C4 Component-level documentation specialist. Synthesizes C4 Code-level documentation into Component-level architecture, defining component boundaries, interfaces, and relationships. Creates component diagrams and documentation. Use when synthesizing code-level documentation into logical diff --git a/web-app/public/skills/c4-container/SKILL.md b/web-app/public/skills/c4-container/SKILL.md index c41f6586..297a4e2b 100644 --- a/web-app/public/skills/c4-container/SKILL.md +++ b/web-app/public/skills/c4-container/SKILL.md @@ -1,6 +1,7 @@ --- name: c4-container -description: "Expert C4 Container-level documentation specialist. Synthesizes" +description: | + Expert C4 Container-level documentation specialist. Synthesizes Component-level documentation into Container-level architecture, mapping components to deployment units, documenting container interfaces as APIs, and creating container diagrams. Use when synthesizing components into deployment diff --git a/web-app/public/skills/c4-context/SKILL.md b/web-app/public/skills/c4-context/SKILL.md index cf5688d0..4d1a5a52 100644 --- a/web-app/public/skills/c4-context/SKILL.md +++ b/web-app/public/skills/c4-context/SKILL.md @@ -1,6 +1,7 @@ --- name: c4-context -description: "Expert C4 Context-level documentation specialist. Creates" +description: | + Expert C4 Context-level documentation specialist. Creates high-level system context diagrams, documents personas, user journeys, system features, and external dependencies. Synthesizes container and component documentation with system documentation to create comprehensive context-level diff --git a/web-app/public/skills/carrier-relationship-management/SKILL.md b/web-app/public/skills/carrier-relationship-management/SKILL.md new file mode 100644 index 00000000..cff92397 --- /dev/null +++ b/web-app/public/skills/carrier-relationship-management/SKILL.md @@ -0,0 +1,203 @@ +--- +name: carrier-relationship-management +description: > + Codified expertise for managing carrier portfolios, negotiating freight rates, + tracking carrier performance, allocating freight, and maintaining strategic + carrier relationships. Informed by transportation managers with 15+ years + experience. Includes scorecarding frameworks, RFP processes, market intelligence, + and compliance vetting. Use when managing carriers, negotiating rates, evaluating + carrier performance, or building freight strategies. +license: Apache-2.0 +version: 1.0.0 +homepage: https://github.com/evos-ai/evos-capabilities +risk: safe +source: https://github.com/ai-evos/agent-skills +metadata: + author: evos + clawdbot: + emoji: "🤝" +--- + +## When to Use + +Use this skill when building and managing a carrier network, conducting freight RFPs, negotiating linehaul and accessorial rates, tracking carrier KPIs via scorecards, or ensuring regulatory compliance of transportation partners. + +# Carrier Relationship Management + +## Role and Context + +You are a senior transportation manager with 15+ years managing carrier portfolios ranging from 40 to 200+ active carriers across truckload, LTL, intermodal, and brokerage. You own the full lifecycle: sourcing new carriers, negotiating rates, running RFPs, building routing guides, tracking performance via scorecards, managing contract renewals, and making allocation decisions. You sit between procurement (who owns total logistics spend), operations (who tenders daily freight), finance (who pays invoices), and senior leadership (who sets cost and service targets). Your systems include TMS (transportation management), rate management platforms, carrier onboarding portals, DAT/Greenscreens for market intelligence, and FMCSA SAFER for compliance. You balance cost reduction pressure against service quality, capacity security, and carrier relationship health — because when the market tightens, your carriers' willingness to cover your freight depends on how you treated them when capacity was loose. + +## Core Knowledge + +### Rate Negotiation Fundamentals + +Every freight rate has components that must be negotiated independently — bundling them obscures where you're overpaying: + +- **Base linehaul rate:** The per-mile or flat rate for dock-to-dock transportation. For truckload, benchmark against DAT or Greenscreens lane rates. For LTL, this is the discount off the carrier's published tariff (typically 70-85% discount for mid-volume shippers). Always negotiate on a lane-by-lane basis — a carrier competitive on Chicago–Dallas may be 15% over market on Atlanta–LA. +- **Fuel surcharge (FSC):** Percentage or per-mile adder tied to the DOE national average diesel price. Negotiate the FSC table, not just the current rate. Key details: the base price trigger (what diesel price equals 0% FSC), the increment (e.g., $0.01/mile per $0.05 diesel increase), and the index lag (weekly vs. monthly adjustment). A carrier quoting a low linehaul with an aggressive FSC table can be more expensive than a higher linehaul with a standard DOE-indexed FSC. +- **Accessorial charges:** Detention ($50-$100/hr after 2 hours free time is standard), liftgate ($75-$150), residential delivery ($75-$125), inside delivery ($100+), limited access ($50-$100), appointment scheduling ($0-$50). Negotiate free time for detention aggressively — driver detention is the #1 source of carrier invoice disputes. For LTL, watch for reweigh/reclass fees ($25-$75 per occurrence) and cubic capacity surcharges. +- **Minimum charges:** Every carrier has a minimum per-shipment charge. For truckload, it's typically a minimum mileage (e.g., $800 for loads under 200 miles). For LTL, it's the minimum charge per shipment ($75-$150) regardless of weight or class. Negotiate minimums on short-haul lanes separately. +- **Contract vs. spot rates:** Contract rates (awarded through RFP or negotiation, valid 6-12 months) provide cost predictability and capacity commitment. Spot rates (negotiated per load on the open market) are 10-30% higher in tight markets, 5-20% lower in soft markets. A healthy portfolio uses 75-85% contract freight and 15-25% spot. More than 30% spot means your routing guide is failing. + +### Carrier Scorecarding + +Measure what matters. A scorecard that tracks 20 metrics gets ignored; one that tracks 5 gets acted on: + +- **On-time delivery (OTD):** Percentage of shipments delivered within the agreed window. Target: ≥95%. Red flag: <90%. Measure pickup and delivery separately — a carrier with 98% on-time pickup and 88% on-time delivery has a linehaul or terminal problem, not a capacity problem. +- **Tender acceptance rate:** Percentage of electronically tendered loads accepted by the carrier. Target: ≥90% for primary carriers. Red flag: <80%. A carrier that rejects 25% of tenders is consuming your operations team's time re-tendering and forcing spot market exposure. Tender acceptance below 75% on a contract lane means the rate is below market — renegotiate or reallocate. +- **Claims ratio:** Dollar value of claims filed divided by total freight spend with the carrier. Target: <0.5% of spend. Red flag: >1.0%. Track claims frequency separately from claims severity — a carrier with one $50K claim is different from one with fifty $1K claims. The latter indicates a systemic handling problem. +- **Invoice accuracy:** Percentage of invoices matching the contracted rate without manual correction. Target: ≥97%. Red flag: <93%. Chronic overbilling (even small amounts) signals either intentional rate testing or broken billing systems. Either way, it costs you audit labor. Carriers with <90% invoice accuracy should be on corrective action. +- **Tender-to-pickup time:** Hours between electronic tender acceptance and actual pickup. Target: within 2 hours of requested pickup for FTL. Carriers that accept tenders but consistently pick up late are "soft rejecting" — they accept to hold the load while shopping for better freight. + +### Portfolio Strategy + +Your carrier portfolio is an investment portfolio — diversification manages risk, concentration drives leverage: + +- **Asset carriers vs. brokers:** Asset carriers own trucks. They provide capacity certainty, consistent service, and direct accountability — but they're less flexible on pricing and may not cover all your lanes. Brokers source capacity from thousands of small carriers. They offer pricing flexibility and lane coverage, but introduce counterparty risk (double-brokering, carrier quality variance, payment chain complexity). Target mix: 60-70% asset, 20-30% broker, 5-15% niche/specialty. +- **Routing guide structure:** Build a 3-deep routing guide for every lane with >2 loads/week. Primary carrier gets first tender (target: 80%+ acceptance). Secondary gets the fallback (target: 70%+ acceptance on overflow). Tertiary is your price ceiling — often a broker whose rate represents the "do not exceed" for spot procurement. For lanes with <2 loads/week, use a 2-deep guide or a regional broker with broad coverage. +- **Lane density and carrier concentration:** Award enough volume per carrier per lane to matter to them. A carrier running 2 loads/week on your lane will prioritize you over a shipper giving them 2 loads/month. But don't give one carrier more than 40% of any single lane — a carrier exit or service failure on a concentrated lane is catastrophic. For your top 20 lanes by volume, maintain at least 3 active carriers. +- **Small carrier value:** Carriers with 10-50 trucks often provide better service, more flexible pricing, and stronger relationships than mega-carriers. They answer the phone. Their owner-operators care about your freight. The tradeoff: less technology integration, thinner insurance, and capacity limits during peak. Use small carriers for consistent, mid-volume lanes where relationship quality matters more than surge capacity. + +### RFP Process + +A well-run freight RFP takes 8-12 weeks and touches every active and prospective carrier: + +- **Pre-RFP:** Analyze 12 months of shipment data. Identify lanes by volume, spend, and current service levels. Flag underperforming lanes and lanes where current rates exceed market benchmarks (DAT, Greenscreens, Chainalytics). Set targets: cost reduction percentage, service level minimums, carrier diversity goals. +- **RFP design:** Include lane-level detail (origin/destination zip, volume range, required equipment, any special handling), current transit time expectations, accessorial requirements, payment terms, insurance minimums, and your evaluation criteria with weightings. Make carriers bid lane-by-lane — portfolio bids ("we'll give you 5% off everything") hide cross-subsidization. +- **Bid evaluation:** Don't award on price alone. Weight cost at 40-50%, service history at 25-30%, capacity commitment at 15-20%, and operational fit at 10-15%. A carrier 3% above the lowest bid but with 97% OTD and 95% tender acceptance is cheaper than the lowest bidder with 85% OTD and 70% tender acceptance — the service failures cost more than the rate difference. +- **Award and implementation:** Award in waves — primary carriers first, then secondary. Give carriers 2-3 weeks to operationalize new lanes before you start tendering. Run a 30-day parallel period where old and new routing guides overlap. Cut over cleanly. + +### Market Intelligence + +Rate cycles are predictable in direction, unpredictable in magnitude: + +- **DAT and Greenscreens:** DAT RateView provides lane-level spot and contract rate benchmarks based on broker-reported transactions. Greenscreens provides carrier-specific pricing intelligence and predictive analytics. Use both — DAT for market direction, Greenscreens for carrier-specific negotiation leverage. Neither is perfectly accurate, but both are better than negotiating blind. +- **Freight market cycles:** The truckload market oscillates between shipper-favorable (excess capacity, falling rates, high tender acceptance) and carrier-favorable (tight capacity, rising rates, tender rejections). Cycles last 18-36 months peak-to-peak. Key indicators: DAT load-to-truck ratio (>6:1 signals tight market), OTRI (Outbound Tender Rejection Index — >10% signals carrier leverage shifting), Class 8 truck orders (leading indicator of capacity addition 6-12 months out). +- **Seasonal patterns:** Produce season (April-July) tightens reefer capacity in the Southeast and West. Peak retail season (October-January) tightens dry van capacity nationally. The last week of each month and quarter sees volume spikes as shippers meet revenue targets. Budget RFP timing to avoid awarding contracts at the peak or trough of a cycle — award during the transition for more realistic rates. + +### FMCSA Compliance Vetting + +Every carrier in your portfolio must pass compliance screening before their first load and on a recurring quarterly basis: + +- **Operating authority:** Verify active MC (Motor Carrier) or FF (Freight Forwarder) authority via FMCSA SAFER. An "authorized" status that hasn't been updated in 12+ months may indicate a carrier that's technically authorized but operationally inactive. Check the "authorized for" field — a carrier authorized for "property" cannot legally carry household goods. +- **Insurance minimums:** $750K minimum for general freight (per FMCSA §387.9), $1M for hazmat, $5M for household goods. Require $1M minimum from all carriers regardless of commodity — the FMCSA minimum of $750K doesn't cover a serious accident. Verify insurance through the FMCSA Insurance tab, not just the certificate the carrier provides — certificates can be forged or outdated. +- **Safety rating:** FMCSA assigns Satisfactory, Conditional, or Unsatisfactory ratings based on compliance reviews. Never use a carrier with an Unsatisfactory rating. Conditional carriers require case-by-case evaluation — understand what the conditions are. Carriers with no rating ("unrated") make up the majority — use their CSA (Compliance, Safety, Accountability) scores instead. Focus on Unsafe Driving, Hours-of-Service, and Vehicle Maintenance BASICs. A carrier in the top 25% percentile (worst) on Unsafe Driving is a liability risk. +- **Broker bond verification:** If using brokers, verify their $75K surety bond or trust fund is active. A broker whose bond has been revoked or reduced is likely in financial distress. Check the FMCSA Bond/Trust tab. Also verify the broker has contingent cargo insurance — this protects you if the broker's underlying carrier causes a loss and the carrier's insurance is insufficient. + +## Decision Frameworks + +### Carrier Selection for New Lanes + +When adding a new lane to your network, evaluate candidates on this decision tree: + +1. **Do existing portfolio carriers cover this lane?** If yes, negotiate with incumbents first — adding a new carrier for one lane introduces onboarding cost ($500-$1,500) and relationship management overhead. Offer existing carriers the new lane as incremental volume in exchange for a rate concession on an existing lane. +2. **If no incumbent covers the lane:** Source 3-5 candidates. For lanes >500 miles, prioritize asset carriers with domicile within 100 miles of the origin. For lanes <300 miles, consider regional carriers and dedicated fleets. For infrequent lanes (<1 load/week), a broker with strong regional coverage may be the most practical option. +3. **Evaluate:** Run FMCSA compliance check. Request 12-month service history on the specific lane from each candidate (not just their network average). Check DAT lane rates for market benchmark. Compare total cost (linehaul + FSC + expected accessorials), not just linehaul. +4. **Trial period:** Award 30-day trial at contracted rates. Set clear KPIs: OTD ≥93%, tender acceptance ≥85%, invoice accuracy ≥95%. Review at 30 days — do not lock in a 12-month commitment without operational validation. + +### When to Consolidate vs. Diversify + +- **Consolidate (reduce carrier count) when:** You have more than 3 carriers on a lane with <5 loads/week (each carrier gets too little volume to care). Your carrier management resources are stretched. You need deeper pricing from a strategic partner (volume concentration = leverage). The market is loose and carriers are competing for your freight. +- **Diversify (add carriers) when:** A single carrier handles >40% of a critical lane. Tender rejections are rising above 15% on a lane. You're entering peak season and need surge capacity. A carrier shows financial distress indicators (late payments to drivers reported on Carrier411, FMCSA insurance lapses, sudden driver turnover visible via CDL postings). + +### Spot vs. Contract Decisions + +- **Stay on contract when:** The spread between contract and spot is <10%. You have consistent, predictable volume. Capacity is tightening (spot rates are rising). The lane is customer-critical with tight delivery windows. +- **Go to spot when:** Spot rates are >15% below your contract rate (market is soft). The lane is irregular (<1 load/week). You need one-time surge capacity beyond your routing guide. Your contract carrier is consistently rejecting tenders on this lane (they're effectively pricing you into spot anyway). +- **Renegotiate contract when:** The spread between your contract rate and DAT benchmark exceeds 15% for 60+ consecutive days. A carrier's tender acceptance drops below 75% for 30 days. You've had a significant volume change (up or down) that changes the lane economics. + +### Carrier Exit Criteria + +Remove a carrier from your active routing guide when any of these thresholds are met, after documented corrective action has failed: + +- OTD below 85% for 60 consecutive days +- Tender acceptance below 70% for 30 consecutive days with no communication +- Claims ratio exceeds 2% of spend for 90 days +- FMCSA authority revoked, insurance lapsed, or safety rating downgraded to Unsatisfactory +- Invoice accuracy below 88% for 90 days after corrective notice +- Discovery of double-brokering your freight +- Evidence of financial distress: bond revocation, driver complaints on CarrierOK or Carrier411, unexplained service collapse + +## Key Edge Cases + +These are situations where standard playbook decisions lead to poor outcomes. Brief summaries here — see [edge-cases.md](references/edge-cases.md) for full analysis. + +1. **Capacity squeeze during a hurricane:** Your top carrier evacuates drivers from the Gulf Coast. Spot rates triple. The temptation is to pay any rate to move freight. The expert move: activate pre-positioned regional carriers, reroute through unaffected corridors, and negotiate multi-load commitments with spot carriers to lock a rate ceiling. + +2. **Double-brokering discovery:** You're told the truck that arrived isn't from the carrier on your BOL. The insurance chain may be broken and your freight is at higher risk. Do not accept the load if it hasn't departed. If in transit, document everything and demand a written explanation within 24 hours. + +3. **Rate renegotiation after 40% volume loss:** Your company lost a major customer and your freight volume dropped. Your carriers' contract rates were predicated on volume commitments you can no longer meet. Proactive renegotiation preserves relationships; letting carriers discover the shortfall at invoice time destroys trust. + +4. **Carrier financial distress indicators:** The warning signs appear months before a carrier fails: delayed driver settlements, FMCSA insurance filings changing underwriters frequently, bond amount dropping, Carrier411 complaints spiking. Reduce exposure incrementally — don't wait for the failure. + +5. **Mega-carrier acquisition of your niche partner:** Your best regional carrier just got acquired by a national fleet. Expect service disruption during integration, rate renegotiation attempts, and potential loss of your dedicated account manager. Secure alternative capacity before the transition completes. + +6. **Fuel surcharge manipulation:** A carrier proposes an artificially low base rate with an aggressive FSC schedule that inflates the total cost above market. Always model total cost across a range of diesel prices ($3.50, $4.00, $4.50/gal) to expose this tactic. + +7. **Detention and accessorial disputes at scale:** When detention charges represent >5% of a carrier's total billing, the root cause is usually shipper facility operations, not carrier overcharging. Address the operational issue before disputing the charges — or lose the carrier. + +## Communication Patterns + +### Rate Negotiation Tone + +Rate negotiations are long-term relationship conversations, not one-time transactions. Calibrate tone: + +- **Opening position:** Lead with data, not demands. "DAT shows this lane averaging $2.15/mile over the last 90 days. Our current contract is $2.45. We'd like to discuss alignment." Never say "your rate is too high" — say "the market has shifted and we want to make sure we're in a competitive position together." +- **Counter-offers:** Acknowledge the carrier's perspective. "We understand driver pay increases are real. Let's find a number that keeps this lane attractive for your drivers while keeping us competitive." Meet in the middle on base rate, negotiate harder on accessorials and FSC table. +- **Annual reviews:** Frame as partnership check-ins, not cost-cutting exercises. Share your volume forecast, growth plans, and lane changes. Ask what you can do operationally to help the carrier (faster dock times, consistent scheduling, drop-trailer programs). Carriers give better rates to shippers who make their drivers' lives easier. + +### Performance Reviews + +- **Positive reviews:** Be specific. "Your 97% OTD on the Chicago–Dallas lane saved us approximately $45K in expedite costs this quarter. We're increasing your allocation from 60% to 75% on that lane." Carriers invest in relationships that reward performance. +- **Corrective reviews:** Lead with data, not accusations. Present the scorecard. Identify the specific metrics below threshold. Ask for a corrective action plan with a 30/60/90-day timeline. Set a clear consequence: "If OTD on this lane doesn't reach 92% by the 60-day mark, we'll need to shift 50% of volume to an alternate carrier." + +For full communication templates, see [communication-templates.md](references/communication-templates.md). + +## Escalation Protocols + +### Automatic Escalation Triggers + +| Trigger | Action | Timeline | +| ----------------------------------------------------------------- | ------------------------------------------------ | --------------- | +| Carrier tender acceptance drops below 70% for 2 consecutive weeks | Notify procurement, schedule carrier call | Within 48 hours | +| Spot spend exceeds 30% of lane budget for any lane | Review routing guide, initiate carrier sourcing | Within 1 week | +| Carrier FMCSA authority or insurance lapses | Immediately suspend tendering, notify operations | Within 1 hour | +| Single carrier controls >50% of a critical lane | Initiate secondary carrier qualification | Within 2 weeks | +| Claims ratio exceeds 1.5% for any carrier for 60+ days | Schedule formal performance review | Within 1 week | +| Rate variance >20% from DAT benchmark on 5+ lanes | Initiate contract renegotiation or mini-bid | Within 2 weeks | +| Carrier reports driver shortage or service disruption | Activate backup carriers, increase monitoring | Within 4 hours | +| Double-brokering confirmed on any load | Immediate carrier suspension, compliance review | Within 2 hours | + +### Escalation Chain + +Analyst → Transportation Manager (48 hours) → Director of Transportation (1 week) → VP Supply Chain (persistent issue or >$100K exposure) + +## Performance Indicators + +Track weekly, review monthly with carrier management team, share quarterly with carriers: + +| Metric | Target | Red Flag | +| ------------------------------------------------ | -------------- | ------------------------ | +| Contract rate vs. DAT benchmark | Within ±8% | >15% premium or discount | +| Routing guide compliance (% of freight on guide) | ≥85% | <70% | +| Primary tender acceptance | ≥90% | <80% | +| Weighted average OTD across portfolio | ≥95% | <90% | +| Carrier portfolio claims ratio | <0.5% of spend | >1.0% | +| Average carrier invoice accuracy | ≥97% | <93% | +| Spot freight percentage | <20% | >30% | +| RFP cycle time (launch to implementation) | ≤12 weeks | >16 weeks | + +## Additional Resources + +- For detailed decision frameworks on rate negotiation, portfolio optimization, and RFP execution, see [decision-frameworks.md](references/decision-frameworks.md) +- For the comprehensive edge case library with full analysis, see [edge-cases.md](references/edge-cases.md) +- For complete communication templates with variables and tone guidance, see [communication-templates.md](references/communication-templates.md) + +## When to Use + +Use this skill when you are **designing or tuning your carrier portfolio, routing guides, and freight procurement strategy**: + +- Running freight RFPs, renegotiating contract and fuel tables, or balancing spot vs. contract exposure. +- Building carrier scorecards, exit criteria, and escalation protocols to manage performance and risk. +- Deciding how to allocate lanes across asset carriers, brokers, and regional specialists to protect service while controlling logistics spend. diff --git a/web-app/public/skills/carrier-relationship-management/references/communication-templates.md b/web-app/public/skills/carrier-relationship-management/references/communication-templates.md new file mode 100644 index 00000000..053b981a --- /dev/null +++ b/web-app/public/skills/carrier-relationship-management/references/communication-templates.md @@ -0,0 +1,584 @@ +# Communication Templates — Carrier Relationship Management + +> **Reference Type:** Tier 3 — Load on demand when composing or reviewing carrier communications. +> +> **Usage:** Each template includes variable placeholders in `{{double_braces}}` for direct substitution. Templates are organized by communication type and business context. Select the template matching your scenario, substitute variables, review tone guidance, and send. + +--- + +## Table of Contents + +1. [RFP Invitation Letter](#1-rfp-invitation-letter) +2. [Rate Negotiation Opening](#2-rate-negotiation-opening) +3. [Rate Counter-Offer](#3-rate-counter-offer) +4. [Carrier Performance Review — Positive](#4-carrier-performance-review--positive) +5. [Carrier Performance Review — Corrective](#5-carrier-performance-review--corrective) +6. [Carrier Onboarding Welcome](#6-carrier-onboarding-welcome) +7. [Carrier Warning Letter](#7-carrier-warning-letter) +8. [Carrier Exit Notification](#8-carrier-exit-notification) +9. [Market Rate Discussion](#9-market-rate-discussion) +10. [Partnership Proposal](#10-partnership-proposal) +11. [Detention Dispute Communication](#11-detention-dispute-communication) +12. [Accessorial Challenge](#12-accessorial-challenge) + +--- + +## Variable Reference + +Common variables used across templates: + +| Variable | Description | Example | +|---|---|---| +| `{{carrier_name}}` | Carrier legal or DBA name | `Ridgeline Transport, Inc.` | +| `{{carrier_contact}}` | Carrier contact name | `Mike Patterson` | +| `{{carrier_contact_title}}` | Carrier contact title | `VP of Sales` | +| `{{carrier_mc}}` | Carrier MC number | `MC-498132` | +| `{{our_company}}` | Our company name | `Consolidated Manufacturing LLC` | +| `{{our_contact_name}}` | Our representative name | `Sarah Chen` | +| `{{our_contact_title}}` | Our representative title | `Director of Transportation` | +| `{{our_contact_email}}` | Our representative email | `schen@company.com` | +| `{{our_contact_phone}}` | Our representative phone | `(312) 555-0189` | +| `{{lane_origin}}` | Lane origin city/state | `Chicago, IL` | +| `{{lane_destination}}` | Lane destination city/state | `Dallas, TX` | +| `{{current_rate}}` | Current contract rate per mile | `$2.45/mile` | +| `{{proposed_rate}}` | Proposed new rate | `$2.28/mile` | +| `{{market_rate}}` | DAT/benchmark market rate | `$2.18/mile` | +| `{{volume_loads_week}}` | Weekly load volume | `8 loads/week` | +| `{{annual_spend}}` | Annual freight spend with carrier | `$2.4M` | +| `{{contract_start}}` | Contract effective date | `2026-04-01` | +| `{{contract_end}}` | Contract expiration date | `2027-03-31` | +| `{{rfp_deadline}}` | RFP response deadline | `2026-03-15` | +| `{{otd_percentage}}` | Carrier's on-time delivery rate | `96.2%` | +| `{{tender_acceptance}}` | Carrier's tender acceptance rate | `91.4%` | +| `{{claims_ratio}}` | Carrier's claims ratio | `0.3%` | +| `{{invoice_accuracy}}` | Carrier's invoice accuracy rate | `97.8%` | +| `{{review_period}}` | Performance review time period | `Q3 2025 (Jul-Sep)` | +| `{{detention_amount}}` | Disputed detention charge amount | `$4,275` | +| `{{accessorial_type}}` | Specific accessorial charge type | `liftgate delivery` | + +--- + +## 1. RFP Invitation Letter + +**Channel:** Email +**Audience:** Carrier sales / pricing leadership +**Tone:** Professional, opportunity-oriented. You're inviting them to compete for business, not demanding concessions. + +--- + +**Subject:** `Invitation to Bid — {{our_company}} Freight RFP — {{contract_start}} Award` + +{{carrier_contact}}, + +{{our_company}} is conducting our annual freight RFP process and we're inviting {{carrier_name}} to participate as a bidding carrier. Based on our analysis of market capabilities and your operational profile, we believe there may be strong alignment between your network and our shipping requirements. + +**RFP Overview:** +- **Scope:** {{lane_count}} lanes across TL, LTL, and intermodal modes +- **Total annual freight spend:** Approximately {{total_annual_spend}} +- **Contract period:** {{contract_start}} through {{contract_end}} +- **Bid deadline:** {{rfp_deadline}} at 5:00 PM CT + +**What We're Looking For:** +We evaluate bids on a weighted scorecard: rate competitiveness (40%), service history and reliability (25%), capacity commitment (20%), and operational fit including technology integration (15%). We value carriers who bring consistent service and a commitment to partnership over the lowest possible rate. + +**Enclosed with this letter:** +1. Lane-level bid package with volume ranges, equipment requirements, and transit expectations +2. Accessorial schedule with standard rates and negotiable items +3. Insurance and compliance requirements +4. Service-level expectations (OTD, tender acceptance, claims thresholds) +5. Contract terms summary + +**Next Steps:** +Please confirm your intent to bid by {{rfp_confirm_date}}. A Q&A webinar for all participating carriers is scheduled for {{qa_date}} at {{qa_time}} CT. All questions must be submitted in writing through the RFP portal; responses will be shared with all bidders. + +We look forward to your participation. + +Best regards, +{{our_contact_name}} +{{our_contact_title}} | {{our_company}} +{{our_contact_email}} | {{our_contact_phone}} + +--- + +## 2. Rate Negotiation Opening + +**Channel:** Email followed by phone call +**Audience:** Carrier account manager or VP of Sales +**Tone:** Data-driven, collaborative. Lead with market data, not demands. Frame as aligning rates with market reality, not squeezing the carrier. + +--- + +**Subject:** `Rate Review Discussion — {{lane_origin}} to {{lane_destination}} | {{our_company}}` + +{{carrier_contact}}, + +I'd like to schedule a call to discuss rate alignment on our {{lane_origin}} to {{lane_destination}} lane. As part of our quarterly rate benchmarking process, we've identified an opportunity to ensure our pricing on this lane reflects current market conditions. + +**Our Current Situation:** +- **Current contract rate:** {{current_rate}} (effective since {{contract_start}}) +- **DAT 90-day contract average for this lane:** {{market_rate}} +- **Your current volume on this lane:** {{volume_loads_week}} +- **Your performance:** {{otd_percentage}} OTD, {{tender_acceptance}} tender acceptance + +We recognize that {{carrier_name}} has delivered strong service on this lane, and our goal is to find a rate that keeps this lane attractive for both of us. We're not looking to drive rates to a level that compromises your service or driver compensation — we are looking for alignment with where the market has moved. + +Could you check availability for a 30-minute call this week? I'd like to walk through the data together and explore options. + +Best regards, +{{our_contact_name}} +{{our_contact_title}} | {{our_company}} +{{our_contact_email}} | {{our_contact_phone}} + +--- + +## 3. Rate Counter-Offer + +**Channel:** Email +**Audience:** Carrier account manager or pricing team +**Tone:** Firm but respectful. Acknowledge the carrier's position while advancing yours. Always justify with data. + +--- + +**Subject:** `Re: Rate Proposal — {{lane_origin}} to {{lane_destination}}` + +{{carrier_contact}}, + +Thank you for the rate proposal on our {{lane_origin}} to {{lane_destination}} lane. I appreciate the detail and the time your team invested. + +After reviewing your proposal against our market data and total cost model, I'd like to share our counter-position: + +**Your Proposal:** {{carrier_proposed_rate}} +**Our Counter:** {{our_counter_rate}} + +**Rationale:** +- DAT 90-day contract average for this lane is {{market_rate}}, which puts your proposal {{percentage_above_market}}% above the current market benchmark. +- We modeled total cost including your proposed fuel surcharge schedule at diesel prices of $3.25, $3.85, and $4.50/gal. At current diesel ({{current_diesel}}), your total cost per mile is {{total_cost_per_mile}}, which is {{total_cost_vs_market}}% above our benchmark total cost. +- Our counter rate of {{our_counter_rate}} reflects the market benchmark plus a {{premium_percentage}}% premium for your service quality — which we genuinely value. Your {{otd_percentage}} OTD is among the best in our portfolio. + +**What We're Offering in Return:** +- Volume commitment: {{volume_commitment}} loads/week guaranteed (vs. your current {{current_volume}} loads/week) +- Payment terms: Net {{payment_days}} (vs. our standard Net 30) +- Drop-trailer program at our {{facility_name}} facility (eliminating an average of {{detention_hours}} hours detention per load) + +I believe we can find alignment here. Would a call on {{proposed_call_date}} work to discuss? + +Best regards, +{{our_contact_name}} +{{our_contact_title}} | {{our_company}} +{{our_contact_email}} | {{our_contact_phone}} + +--- + +## 4. Carrier Performance Review — Positive + +**Channel:** Email + formal quarterly business review meeting +**Audience:** Carrier account manager, VP of Sales, and operations leadership +**Tone:** Celebratory and specific. Name the metrics, quantify the impact, and reward with tangible actions (more volume, longer contract, public recognition). Generic praise is worse than no praise. + +--- + +**Subject:** `Q{{quarter}} Performance Review — {{carrier_name}} | Outstanding Results` + +{{carrier_contact}}, + +I want to formally recognize {{carrier_name}}'s performance during {{review_period}}. Your team has been exceptional across every metric we track, and we want to make sure you know it — and that we're backing up that recognition with action. + +**Performance Summary — {{review_period}}:** + +| Metric | Target | Your Performance | Portfolio Average | +|--------|--------|-----------------|-------------------| +| On-Time Delivery | ≥95% | {{otd_percentage}} | {{portfolio_avg_otd}} | +| Tender Acceptance | ≥90% | {{tender_acceptance}} | {{portfolio_avg_tender}} | +| Claims Ratio | <0.5% | {{claims_ratio}} | {{portfolio_avg_claims}} | +| Invoice Accuracy | ≥97% | {{invoice_accuracy}} | {{portfolio_avg_invoice}} | + +**Specific Highlights:** +- Your team's performance on the {{highlight_lane}} lane was particularly strong — {{highlight_detail}}. +- Driver {{driver_name}} received compliments from our {{facility_name}} receiving team for consistent professionalism and efficient dock operations. +- Your operations team's proactive communication during {{event}} prevented what could have been a significant service disruption. + +**What This Means for Our Partnership:** +Based on this performance, we're making the following allocation changes effective {{effective_date}}: +- **{{lane_1}}:** Increasing your allocation from {{old_allocation_1}}% to {{new_allocation_1}}% +- **{{lane_2}}:** Adding you as primary carrier (new lane award — {{volume_2}} loads/week) +- **Contract extension:** We'd like to discuss extending our agreement through {{extended_end_date}} at current terms + +Thank you for making our operation better. We value this partnership and look forward to continuing to grow together. + +Best regards, +{{our_contact_name}} +{{our_contact_title}} | {{our_company}} +{{our_contact_email}} | {{our_contact_phone}} + +--- + +## 5. Carrier Performance Review — Corrective + +**Channel:** Email followed by in-person or video meeting +**Audience:** Carrier account manager and operations leadership +**Tone:** Professional, direct, data-driven. Not punitive — corrective. Present the data, state the impact, set clear expectations with a timeline, and define the consequence. Avoid emotional language. + +--- + +**Subject:** `Performance Review — {{carrier_name}} | Corrective Action Required` + +{{carrier_contact}}, + +I'm reaching out regarding {{carrier_name}}'s performance during {{review_period}} on lanes serviced for {{our_company}}. Several metrics have fallen below our minimum standards, and I want to address this directly so we can work together on a resolution. + +**Performance Summary — {{review_period}}:** + +| Metric | Our Standard | Your Performance | Gap | +|--------|-------------|-----------------|-----| +| On-Time Delivery | ≥95% | {{otd_percentage}} | {{otd_gap}} below standard | +| Tender Acceptance | ≥90% | {{tender_acceptance}} | {{tender_gap}} below standard | +| Claims Ratio | <0.5% | {{claims_ratio}} | {{claims_gap}} above standard | +| Invoice Accuracy | ≥97% | {{invoice_accuracy}} | {{invoice_gap}} below standard | + +**Business Impact:** +- Tender rejections on the {{problem_lane}} lane forced {{spot_loads}} loads to the spot market at an average premium of {{spot_premium}}%, costing us approximately ${{incremental_cost}} in incremental freight spend. +- Late deliveries resulted in {{penalty_count}} customer penalty events totaling ${{penalty_total}}. + +**What We Need:** +We value our relationship with {{carrier_name}} and want to find a path forward. We're requesting a Corrective Action Plan that addresses the following within the timelines indicated: + +| Metric | Target | 30-Day Checkpoint | 60-Day Checkpoint | +|--------|--------|-------------------|-------------------| +| OTD | ≥{{otd_target}}% | ≥{{otd_30day}}% | ≥{{otd_60day}}% | +| Tender Acceptance | ≥{{tender_target}}% | ≥{{tender_30day}}% | ≥{{tender_60day}}% | + +Please send your CAP document by {{cap_due_date}} outlining the root causes you've identified and the specific operational changes you're implementing. + +**If Targets Are Not Met:** +If the 60-day checkpoint targets are not achieved, we will need to reduce your allocation on affected lanes by 50% and reassign volume to alternate carriers. This is not our preferred outcome — we'd much rather see improvement and continue building this partnership. + +I'd like to schedule a call for {{proposed_call_date}} to discuss your initial assessment. Please let me know your availability. + +Regards, +{{our_contact_name}} +{{our_contact_title}} | {{our_company}} +{{our_contact_email}} | {{our_contact_phone}} + +--- + +## 6. Carrier Onboarding Welcome + +**Channel:** Email +**Audience:** Carrier's assigned account manager and operations contact +**Tone:** Welcoming, organized, and clear about expectations. First impressions set the relationship trajectory. + +--- + +**Subject:** `Welcome to {{our_company}}'s Carrier Network — Onboarding Information` + +{{carrier_contact}}, + +Welcome to {{our_company}}'s carrier network. We're pleased to have {{carrier_name}} as a transportation partner and look forward to a productive relationship. + +This email contains everything you need to get started. Please review carefully and let me know if you have questions. + +**Your Awarded Lanes:** + +| Lane | Volume | Equipment | Transit Requirement | +|------|--------|-----------|-------------------| +| {{lane_1_origin}} → {{lane_1_dest}} | {{lane_1_volume}}/week | {{lane_1_equip}} | {{lane_1_transit}} | +| {{lane_2_origin}} → {{lane_2_dest}} | {{lane_2_volume}}/week | {{lane_2_equip}} | {{lane_2_transit}} | + +**Onboarding Checklist (please complete by {{onboarding_deadline}}):** + +- [ ] Return signed Carrier Transportation Agreement (attached) +- [ ] Provide current Certificate of Insurance meeting our minimums ($1M auto liability, $100K cargo) +- [ ] Complete W-9 form (attached) +- [ ] Provide EDI/API contact for system integration setup (if applicable) +- [ ] Confirm operational contact for daily dispatching (name, phone, email) +- [ ] Confirm after-hours emergency contact (name, phone) + +**What to Expect:** +- **First 30 days:** We'll run trial loads on your awarded lanes. Our minimum standards during trial: ≥93% OTD, ≥85% tender acceptance, ≥95% invoice accuracy. +- **Day 30 review:** We'll review trial performance together. If targets are met, you'll move to full allocation. If not, we'll discuss what adjustments are needed. +- **Ongoing:** Quarterly performance reviews, annual rate review aligned with our RFP cycle. + +**Our Facilities — Key Operational Notes:** + +| Facility | Dock Hours | Appointment Required? | Avg Load/Unload Time | Detention Policy | +|----------|-----------|----------------------|---------------------|-----------------| +| {{facility_1}} | {{hours_1}} | {{appt_1}} | {{avg_time_1}} | {{detention_1}} | +| {{facility_2}} | {{hours_2}} | {{appt_2}} | {{avg_time_2}} | {{detention_2}} | + +**Your Primary Contacts at {{our_company}}:** +- **Relationship management:** {{our_contact_name}}, {{our_contact_title}} ({{our_contact_email}}, {{our_contact_phone}}) +- **Daily operations / tendering:** {{ops_contact_name}}, {{ops_contact_title}} ({{ops_contact_email}}, {{ops_contact_phone}}) +- **Accounts payable / invoicing:** {{ap_contact_name}} ({{ap_contact_email}}) + +Welcome aboard. We believe in rewarding performance — carriers who deliver consistent, high-quality service earn more volume, longer contracts, and priority consideration for new lanes. + +Best regards, +{{our_contact_name}} +{{our_contact_title}} | {{our_company}} + +--- + +## 7. Carrier Warning Letter + +**Channel:** Formal email with read receipt requested; copy to carrier's VP of Sales +**Audience:** Carrier account manager + carrier senior leadership +**Tone:** Formal and serious. This is a documentation event as much as a communication — it creates the paper trail for a potential exit decision. Factual, not emotional. Cite specific contract provisions. + +--- + +**Subject:** `FORMAL NOTICE: Performance Deficiency — {{carrier_name}} / {{our_company}} Account` + +{{carrier_contact}}, + +This letter serves as formal notice that {{carrier_name}}'s performance on {{our_company}}'s account has fallen below contractual standards for a sustained period, and continued non-compliance will result in volume reduction and potential removal from our routing guide. + +**Deficiency Summary:** +Per Section {{contract_section}} of our Transportation Agreement dated {{agreement_date}}, the following minimum standards apply: + +| Metric | Contractual Minimum | {{carrier_name}}'s Performance ({{deficiency_period}}) | +|--------|--------------------|----------------------------------------------------| +| {{metric_1}} | {{standard_1}} | {{actual_1}} | +| {{metric_2}} | {{standard_2}} | {{actual_2}} | + +**Prior Communication:** +- {{prior_comm_date_1}}: {{prior_comm_description_1}} +- {{prior_comm_date_2}}: {{prior_comm_description_2}} +- {{cap_date}}: Corrective Action Plan submitted, targeting improvement by {{cap_target_date}} +- As of {{current_date}}, targets have not been met. + +**Consequences:** +Effective {{consequence_date}}, we will reduce {{carrier_name}}'s allocation on the following lanes by {{reduction_percentage}}%: +{{affected_lanes_list}} + +If performance does not reach contractual minimums by {{final_deadline}}, {{carrier_name}} will be removed from our active routing guide on all affected lanes. + +**Path to Resolution:** +We would prefer to resolve this cooperatively. If {{carrier_name}} can provide an updated remediation plan addressing the specific root causes and committing to measurable improvement targets, we are willing to extend the review period by 30 days. + +Please respond in writing by {{response_deadline}}. + +Regards, +{{our_contact_name}} +{{our_contact_title}} | {{our_company}} +{{our_contact_email}} | {{our_contact_phone}} + +CC: {{carrier_vp_name}}, {{carrier_vp_title}}, {{carrier_name}} +CC: {{our_director_name}}, {{our_director_title}}, {{our_company}} + +--- + +## 8. Carrier Exit Notification + +**Channel:** Formal email followed by phone call +**Audience:** Carrier account manager and carrier senior leadership +**Tone:** Respectful and final. This is a business decision, not a punishment. Leave the door open for future consideration. Avoid burning bridges — the carrier community is smaller than you think. + +--- + +**Subject:** `Notice of Routing Guide Removal — {{carrier_name}} / {{our_company}}` + +{{carrier_contact}}, + +After careful consideration and review of {{carrier_name}}'s performance over the past {{review_months}} months, we have made the decision to remove {{carrier_name}} from {{our_company}}'s active routing guide effective {{exit_date}}. + +**Reason for Decision:** +{{exit_reason_summary}} + +**Transition Plan:** +- **{{exit_date}} through {{transition_end_date}}:** We will reduce tender volume by approximately {{reduction_percent}}% per week during this transition period to allow both organizations to adjust. +- **Open invoices:** All outstanding invoices will be processed per standard payment terms. Please ensure all invoices are submitted by {{invoice_deadline}}. +- **Open claims:** Any pending claims will continue through their normal resolution process. This decision does not affect the adjudication of open claims. + +**What This Means Going Forward:** +This is not necessarily a permanent decision. We review our carrier portfolio annually during our RFP process. If {{carrier_name}} addresses the issues noted above and would like to re-engage, we welcome your participation in future RFP cycles. + +I'm available to discuss this decision directly if you'd like to connect. I respect the work your team has done for our account and want to ensure this transition is handled professionally. + +Regards, +{{our_contact_name}} +{{our_contact_title}} | {{our_company}} +{{our_contact_email}} | {{our_contact_phone}} + +--- + +## 9. Market Rate Discussion + +**Channel:** Email or phone, depending on relationship depth +**Audience:** Carrier account manager +**Tone:** Collegial and transparent. This is a market discussion, not a negotiation — you're sharing data and inviting dialogue. Use when market conditions have shifted and you want to proactively discuss alignment before it becomes a formal renegotiation. + +--- + +**Subject:** `Market Check-In — {{lane_origin}} to {{lane_destination}} Corridor` + +{{carrier_contact}}, + +I wanted to reach out proactively about what we're seeing in the {{lane_origin}} to {{lane_destination}} market. As you know, we track lane-level benchmarks quarterly, and the latest data suggests some movement worth discussing. + +**What We're Seeing:** +- DAT contract average for this lane has moved from {{old_benchmark}} to {{new_benchmark}} over the last {{timeframe}} — a {{percentage_change}} {{direction}} shift. +- Our spot procurement on overflow loads in this corridor has averaged {{spot_average}} over the last 30 days. +- Load-to-truck ratios in the {{region}} region are currently {{ltt_ratio}}, compared to {{ltt_previous}} last quarter. + +**Our Perspective:** +We're not sending this as a formal rate request — it's a market conversation. We want to understand how you're seeing the same data and whether there's an opportunity to align proactively rather than waiting for contract renewal. + +If the market has moved in a way that affects our lane economics, I'd rather discuss it now and find a mutually workable solution than have it surface as a surprise during our annual review. + +Would you have 20 minutes this week to discuss? + +Best regards, +{{our_contact_name}} +{{our_contact_title}} | {{our_company}} +{{our_contact_email}} | {{our_contact_phone}} + +--- + +## 10. Partnership Proposal + +**Channel:** Formal letter or meeting presentation +**Audience:** Carrier CEO, President, or SVP of Sales +**Tone:** Strategic and forward-looking. This is a business partnership proposal, not a procurement transaction. Emphasize mutual benefit, growth potential, and commitment. + +--- + +**Subject:** `Strategic Partnership Proposal — {{our_company}} and {{carrier_name}}` + +{{carrier_contact}}, + +I'd like to propose elevating the relationship between {{our_company}} and {{carrier_name}} from a standard carrier-shipper arrangement to a strategic partnership. Our analysis suggests significant mutual benefit in a deeper, more integrated collaboration. + +**Why {{carrier_name}}:** +Over the past {{relationship_years}} years, {{carrier_name}} has consistently performed in the top tier of our carrier portfolio. Specifically: +- {{otd_percentage}} OTD (vs. portfolio average of {{portfolio_avg}}%) +- {{tender_acceptance}} tender acceptance (vs. {{portfolio_avg_tender}}% average) +- Exceptional communication and problem-resolution responsiveness + +**What We're Proposing:** +1. **Volume commitment:** Increase {{carrier_name}}'s share of our total freight from {{current_share}}% to {{proposed_share}}%, representing approximately {{proposed_spend}} in annual freight spend. +2. **Multi-year agreement:** 24-month contract with pre-agreed annual escalators tied to {{escalator_index}}, replacing the annual RFP cycle for your lanes. +3. **Operational integration:** Implement real-time tracking integration (API), shared KPI dashboard, and quarterly executive business reviews. +4. **Growth collaboration:** As {{our_company}} expands into {{growth_markets}}, {{carrier_name}} would be our first-call carrier for new lanes in your network. + +**What We'd Need in Return:** +1. Rate alignment: Competitive pricing reflecting the volume commitment and multi-year certainty (we're targeting rates within {{target_range}}% of DAT contract benchmark). +2. Service guarantee: {{otd_target}}% OTD and {{tender_target}}% tender acceptance with quarterly review. +3. Dedicated account management: A named contact who knows our operations, our customers, and our seasonal patterns. +4. Capacity priority: During peak season or disruption events, {{our_company}} freight receives priority dispatch from your operations team. + +I'd welcome the opportunity to discuss this in a meeting with your leadership team. Would {{proposed_meeting_date}} work for an in-person session at {{proposed_location}}? + +Best regards, +{{our_contact_name}} +{{our_contact_title}} | {{our_company}} +{{our_contact_email}} | {{our_contact_phone}} + +--- + +## 11. Detention Dispute Communication + +**Channel:** Email with supporting documentation attached +**Audience:** Carrier billing / accounts receivable team, cc carrier account manager +**Tone:** Factual and cooperative. Detention disputes get adversarial quickly — lead with data and a willingness to pay what's legitimate while disputing what's not. + +--- + +**Subject:** `Detention Invoice Dispute — PRO# {{pro_number}} / {{dispute_date}}` + +{{carrier_contact}}, + +We've reviewed the detention invoice for PRO# {{pro_number}} ({{lane_origin}} to {{lane_destination}}, delivered {{delivery_date}}) and have identified discrepancies between the invoiced detention and our facility records. + +**Your Invoice:** +- Driver arrival: {{carrier_arrival_time}} +- Departure: {{carrier_departure_time}} +- Total detention billed: {{billed_detention_hours}} hours at ${{detention_rate}}/hr = {{detention_amount}} + +**Our Records:** +- Driver check-in at guard shack: {{our_checkin_time}} +- Dock door assigned: {{dock_assign_time}} +- Loading/unloading complete (BOL signed): {{bol_sign_time}} +- Free time: {{free_time_hours}} hours per contract Section {{contract_section}} + +**Discrepancy Analysis:** +- The driver arrived {{early_minutes}} minutes before the scheduled appointment of {{appointment_time}}. Per our contract, detention begins at the later of appointment time or arrival time — not early arrival time. +- Our records show actual dock dwell time (from check-in to BOL signature) of {{actual_dwell}} hours, of which {{free_time_hours}} hours is free time. Billable detention per our records: {{adjusted_detention}} hours. + +**Our Proposed Resolution:** +We'll pay {{adjusted_amount}} ({{adjusted_detention}} hours × ${{detention_rate}}/hr) against this invoice. If you believe our records are inaccurate, please provide driver GPS or ELD data showing dock arrival and departure times, and we'll reconcile. + +We want to get this right for both of us. If detention on this lane is a recurring issue, I'd welcome a discussion about adjusting appointment scheduling or implementing a drop-trailer program to address the root cause. + +Best regards, +{{our_contact_name}} +{{our_contact_title}} | {{our_company}} +{{our_contact_email}} | {{our_contact_phone}} + +--- + +## 12. Accessorial Challenge + +**Channel:** Email +**Audience:** Carrier billing / pricing team, cc carrier account manager +**Tone:** Measured and evidence-based. Accessorial disputes are high-volume, low-dollar events that can poison a relationship if handled aggressively. Focus on accuracy, not accusation. + +--- + +**Subject:** `Accessorial Charge Review — {{accessorial_type}} | PRO# {{pro_number}}` + +{{carrier_contact}}, + +We're reviewing an accessorial charge on PRO# {{pro_number}} ({{lane_origin}} to {{lane_destination}}, {{delivery_date}}) and need clarification before processing payment. + +**Charge in Question:** +- Accessorial type: {{accessorial_type}} +- Amount: ${{accessorial_amount}} +- Invoice reference: {{invoice_number}} + +**Our Concern:** +{{concern_detail}} + +Per our Transportation Agreement (Section {{contract_section}}, Accessorial Schedule Item {{schedule_item}}), {{accessorial_type}} charges apply when {{contract_condition}}. Based on the BOL and delivery receipt for this shipment, {{evidence_detail}}. + +**Supporting Documentation (attached):** +- BOL showing {{bol_detail}} +- Delivery receipt showing {{pod_detail}} +- Rate confirmation with accessorial schedule reference + +**Requested Action:** +Please review the charge against the attached documentation and either (a) confirm the charge with additional supporting evidence we may not have, or (b) issue a credit memo for ${{accessorial_amount}} against invoice {{invoice_number}}. + +If this accessorial category is becoming a recurring issue on this lane, I'd like to discuss whether there's an operational adjustment (at either end) that could prevent these charges from accruing. + +Thank you for your prompt review. + +Best regards, +{{our_contact_name}} +{{our_contact_title}} | {{our_company}} +{{our_contact_email}} | {{our_contact_phone}} + +--- + +## Usage Guidelines + +### Tone Calibration by Relationship Status + +| Relationship Status | Appropriate Templates | Tone Adjustment | +|--------------------|----------------------|-----------------| +| New carrier (< 6 months) | Onboarding welcome, rate negotiation opening, market rate discussion | More formal, set clear expectations, be specific about standards | +| Established carrier (6-24 months) | All templates | Standard professional tone, data-driven, collaborative | +| Strategic partner (2+ years, top tier) | Performance review positive, partnership proposal, market rate discussion | More collegial, emphasize growth opportunity, share more operational context | +| Underperforming carrier | Performance review corrective, warning letter, exit notification | Strictly professional, document everything, focus on facts and data | +| Carrier in dispute | Detention dispute, accessorial challenge, warning letter | Factual and neutral, avoid emotional language, always propose a resolution path | + +### Communication Channel Selection + +| Situation | Primary Channel | When to Escalate Channel | +|-----------|----------------|------------------------| +| Rate discussion (routine) | Email → phone follow-up | If email exchange exceeds 3 rounds without resolution | +| Performance review (positive) | Email + QBR meeting | N/A — always share good news broadly | +| Performance review (corrective) | Email first (documentation), then phone/meeting | If carrier doesn't respond within 5 business days | +| Warning letter | Formal email with read receipt | If carrier doesn't respond within 3 business days, follow up via carrier VP phone call | +| Exit notification | Formal email + same-day phone call | N/A — always deliver exit decisions via both channels | +| Detention/accessorial dispute | Email with documentation | If not resolved in 15 business days, escalate to carrier account manager | +| Partnership proposal | Formal letter/email → in-person meeting | N/A — partnership proposals require in-person discussion | diff --git a/web-app/public/skills/carrier-relationship-management/references/decision-frameworks.md b/web-app/public/skills/carrier-relationship-management/references/decision-frameworks.md new file mode 100644 index 00000000..bf8a4ac8 --- /dev/null +++ b/web-app/public/skills/carrier-relationship-management/references/decision-frameworks.md @@ -0,0 +1,534 @@ +# Decision Frameworks — Carrier Relationship Management + +This reference provides detailed decision trees, scoring matrices, negotiation models, +and strategic frameworks for managing carrier portfolios, negotiating freight rates, +running RFPs, and making allocation decisions. It is loaded on demand when the agent +needs to make or recommend nuanced carrier relationship decisions. + +All thresholds, rate assumptions, and market benchmarks reflect US domestic freight +operations across TL, LTL, intermodal, and brokerage. Adjust for regional markets +and current cycle position. + +--- + +## 1. Rate Negotiation Strategy + +### 1.1 Pre-Negotiation Intelligence Gathering + +Before entering any rate negotiation, assemble a lane-level data package for each +lane under discussion. Negotiating without data is guessing; carriers always have +better data about their own costs than you do about market rates. + +#### Data Assembly Checklist + +| Data Point | Source | Purpose | +|-----------|--------|---------| +| Current contract rate (linehaul + FSC + avg accessorials) | TMS / rate management system | Establish baseline total cost | +| DAT 90-day lane average (spot and contract) | DAT RateView | Market benchmark for shipper leverage | +| Greenscreens carrier-specific rate intelligence | Greenscreens.ai | Carrier-specific pricing behavior and predicted pricing | +| Your volume on this lane (loads/week, annual loads) | TMS shipment history | Volume leverage — carriers price based on density | +| Carrier's current tender acceptance rate on this lane | TMS acceptance data | Indicator of whether current rate is below carrier's floor | +| Carrier's OTD and claims performance on this lane | Carrier scorecard | Service quality justification for rate position | +| Competitor carrier bids (from recent RFP or spot activity) | RFP results / spot tender logs | Alternative pricing to create competitive tension | +| Diesel price trend and DOE forecast | DOE Weekly Retail Diesel | FSC modeling across price scenarios | +| Seasonal volume forecast for the lane | Demand planning / sales forecast | Carrier values volume predictability — share forecasts to build trust | + +### 1.2 Total Cost Modeling + +Never negotiate linehaul in isolation. Model total cost per shipment across diesel +price scenarios to expose hidden costs and FSC manipulation. + +#### Total Cost Formula + +``` +Total Cost per Shipment = Linehaul Rate + + Fuel Surcharge (at given diesel price) + + Expected Detention (avg hours × rate × frequency) + + Expected Accessorials (liftgate, residential, etc. × frequency) + + Reweigh/Reclass Fees (LTL — frequency × cost) + + Payment Term Cost (if offering quick-pay discount) +``` + +#### Diesel Price Scenario Modeling + +For every carrier proposal, calculate total cost at three diesel price points: + +| Scenario | Diesel Price | Purpose | +|----------|-------------|---------| +| Low | $3.25/gallon | Tests carrier's FSC floor — does the FSC go to zero or maintain a minimum? | +| Current | Current DOE average | Apples-to-apples comparison with other carriers | +| High | $4.50/gallon | Exposes aggressive FSC schedules that inflate cost disproportionately | + +**Example — Comparing Two TL Carrier Proposals (Chicago to Dallas, ~920 miles):** + +``` +Carrier A: Linehaul $2.10/mi, FSC base $3.50, $0.01/mi per $0.05 diesel increase +Carrier B: Linehaul $1.95/mi, FSC base $3.00, $0.015/mi per $0.05 diesel increase + +At diesel $3.50: + Carrier A: ($2.10 × 920) + ($0.00 FSC) = $1,932 + Carrier B: ($1.95 × 920) + ($0.015 × 10 increments × 920) = $1,794 + $138 = $1,932 + +At diesel $4.50: + Carrier A: ($2.10 × 920) + ($0.01 × 20 × 920) = $1,932 + $184 = $2,116 + Carrier B: ($1.95 × 920) + ($0.015 × 30 × 920) = $1,794 + $414 = $2,208 + +Carrier B is $92 more expensive at high diesel despite a $0.15/mi lower linehaul. +The aggressive FSC base ($3.00 vs. $3.50) and steeper increment ($0.015 vs. $0.01) +make Carrier B the more expensive option when fuel prices rise. +``` + +### 1.3 Negotiation Positioning by Market Cycle + +The freight market cycle determines your leverage. Negotiate differently in each phase: + +#### Shipper-Favorable Market (Capacity Surplus) + +Indicators: DAT load-to-truck ratio <3:1, OTRI <5%, spot rates below contract by >10%. + +| Tactic | Detail | +|--------|--------| +| Push for rate reductions | Target 5-12% reduction on lanes where your rate exceeds DAT contract benchmark by >10% | +| Extend contract terms | Lock favorable rates for 18-24 months instead of the standard 12. Carriers will accept longer terms to secure volume during a downturn | +| Negotiate accessorial caps | Push for detention free time of 3 hours (instead of standard 2). Negotiate liftgate and residential fees down 15-20% | +| Add service commitments | Require 95% OTD and 92% tender acceptance as contract terms with remedy clauses (rate credits for non-performance) | +| Don't over-squeeze | A carrier losing money on your lanes will exit when the market turns. Leave enough margin for the carrier to cover their variable costs + a thin margin. A carrier hauling your freight at $0.05/mile below their cost will be the first to reject tenders when demand returns | + +#### Carrier-Favorable Market (Capacity Shortage) + +Indicators: DAT load-to-truck ratio >6:1, OTRI >12%, spot rates above contract by >15%. + +| Tactic | Detail | +|--------|--------| +| Protect volume commitments | Offer volume guarantees (minimum loads/week) in exchange for capacity commitments. Carriers in a tight market prioritize shippers who provide consistent, guaranteed volume | +| Accept moderate rate increases | A 5-8% increase is reasonable when the market has moved 15-20%. Refusing all increases pushes carriers to more profitable freight | +| Accelerate payment terms | Offer 15-day or quick-pay terms (vs. standard 30-day) as a non-rate incentive. Carriers are cash-constrained in tight markets — faster payment is worth 2-3% rate equivalent | +| Improve shipper operations | Reduce driver detention, offer drop-trailer programs, ensure consistent dock scheduling. Every operational improvement makes your freight more attractive relative to competitors | +| Negotiate multi-year with escalators | Lock base rates for 24 months with a pre-agreed annual escalator (3-5%) tied to a cost index. Protects against further rate spikes while giving the carrier predictability | + +#### Transitional Market + +Indicators: Mixed signals — OTRI between 5-12%, spot-contract spread narrowing. + +| Tactic | Detail | +|--------|--------| +| Benchmark aggressively | Transition markets are when benchmark data matters most. Carriers will argue the market is tighter than it is (if transitioning to carrier-favorable) or softer (if transitioning to shipper-favorable). Let the data decide | +| Run mini-bids | Instead of full RFPs, run targeted mini-bids on your bottom-performing 20% of lanes. This creates competitive pressure without disrupting your entire routing guide | +| Lock strategic lanes | Secure rates on your highest-volume, most critical lanes first. Leave secondary lanes flexible to benefit from continued market movement | + +### 1.4 Concession Strategy + +When a negotiation reaches an impasse, use structured concessions to find agreement +without giving away core economics: + +#### Concession Priority (Give These First — They Cost Less Than They're Worth) + +| Concession | Your Cost | Carrier Value | When to Offer | +|-----------|-----------|---------------|---------------| +| Volume commitment (guarantee minimum loads/week) | Low — you were shipping this volume anyway | High — predictable volume improves carrier utilization | When carrier won't budge on rate | +| Faster payment terms (Net 15 vs. Net 30) | Moderate — accelerates cash outflow by 15 days | High — carriers are always cash-constrained | When spread between positions is <5% | +| Drop-trailer program | Moderate — requires trailer parking space | Very High — eliminates driver detention, improves asset utilization | When carrier cites detention as cost driver | +| Consistent appointment scheduling | Low — operational discipline | High — drivers can plan routes and HOS around fixed appointments | When carrier cites unpredictable scheduling | +| Multi-year contract with escalators | Low — locks rate but adds predictability | High — long-term revenue certainty | When carrier values stability over short-term optimization | + +#### Concession Boundary (Never Give These Away) + +| Element | Why It's Non-Negotiable | +|---------|----------------------| +| FSC table transparency | Opaque FSC schedules are a carrier margin tool, not a cost recovery mechanism | +| Accessorial audit rights | You must be able to verify every accessorial charge against the BOL and contract | +| Service-level remedies | A contract without OTD and tender acceptance minimums is just a rate sheet with no accountability | +| Right to re-bid lanes annually | Market conditions change — you need the ability to benchmark and adjust | +| Carrier compliance requirements (FMCSA, insurance) | Safety and legal compliance are not negotiable under any market condition | + +--- + +## 2. Carrier Portfolio Optimization + +### 2.1 Portfolio Health Assessment + +Run this assessment quarterly to identify optimization opportunities: + +#### Step 1: Carrier Concentration Analysis + +For each lane in your top 50 by volume: + +| Metric | Target | Action If Out of Range | +|--------|--------|----------------------| +| Primary carrier volume share | 50-70% | If >70%: diversify. If <50%: routing guide isn't being followed — investigate ops compliance | +| Number of active carriers on lane | 2-4 | If <2: single point of failure risk. If >4: volume is too fragmented for carriers to care | +| Backup carrier last-used date | Within 90 days | If >90 days: the backup is stale. Run a test load to confirm the carrier can still service the lane | +| Spot freight % on lane | <15% | If >15%: routing guide is failing. Either rates are below market or tender acceptance is low | + +#### Step 2: Carrier Scorecard Triage + +Rank all active carriers by composite score (weighted: OTD 30%, tender acceptance 25%, +claims ratio 20%, invoice accuracy 15%, communication/responsiveness 10%). + +| Tier | Score Range | Action | +|------|------------|--------| +| A — Strategic Partners | ≥90% | Increase allocation, offer longer-term contracts, invest in integration (EDI, API), invite to annual business review | +| B — Reliable Performers | 75-89% | Maintain current allocation, monitor for improvement or decline, include in next RFP | +| C — Underperformers | 60-74% | Issue corrective action plan with 60-day timeline. Reduce allocation by 25%. If no improvement at 60 days, reduce by another 25% | +| D — Exit Candidates | <60% | Initiate carrier exit process (see §2.4). Stop new lane awards immediately. Allow existing commitments to run out | + +#### Step 3: Spend Optimization + +| Analysis | Method | Target | +|----------|--------|--------| +| Rate-vs-market alignment | Compare contract rates to DAT contract lane average for each active lane | Within ±8% of DAT. If >+15%, renegotiate. If <-10%, carrier may be underpriced and at exit risk | +| Accessorial spend ratio | Total accessorials / total linehaul spend | <8% of total spend. If >12%, audit accessorial billing and address root causes (detention, reclass) | +| Spot premium tracking | (Avg spot rate - avg contract rate) / avg contract rate | <15% premium. If >25%, routing guide coverage is insufficient | +| Small shipment consolidation | Identify LTL shipments to same destination within 48-hour windows | Consolidate into TL or multi-stop when LTL spend on a lane exceeds $5K/month | + +### 2.2 Routing Guide Design + +The routing guide is your operational expression of carrier strategy. A well-designed +guide executes itself; a poorly designed one requires constant manual intervention. + +#### Structure by Lane Volume + +| Lane Volume | Guide Depth | Primary % | Secondary % | Tertiary % | +|-------------|------------|-----------|-------------|------------| +| >10 loads/week | 3-4 carriers | 50-60% | 25-30% | 10-20% | +| 5-10 loads/week | 3 carriers | 55-65% | 25-30% | 10-15% | +| 2-5 loads/week | 2-3 carriers | 60-75% | 25-40% | — | +| <2 loads/week | 2 carriers (or 1 + broker) | 70-80% | 20-30% | — | + +#### Tender Waterfall Logic + +``` +1. Tender to Primary Carrier + → If accepted within 2 hours: assign + → If rejected or no response: + +2. Tender to Secondary Carrier + → If accepted within 1.5 hours: assign + → If rejected or no response: + +3. Tender to Tertiary Carrier + → If accepted within 1 hour: assign + → If rejected or no response: + +4. Move to Spot Procurement + → Post to carrier board or contact preferred spot carriers + → Set rate ceiling at tertiary contract rate + 15% + → If no coverage within 2 hours at ceiling: escalate to manager +``` + +#### Routing Guide Maintenance Cadence + +| Activity | Frequency | Owner | +|----------|-----------|-------| +| Review lane-level tender acceptance rates | Weekly | Transportation Analyst | +| Adjust carrier allocation based on performance trends | Monthly | Transportation Manager | +| Full routing guide audit (dead lanes, stale backups, rate alignment) | Quarterly | Director of Transportation | +| Complete routing guide rebuild (RFP) | Annually or after major volume/network change | VP Supply Chain + Procurement | + +### 2.3 Carrier Onboarding Process + +A standardized onboarding process protects against compliance risk and sets performance +expectations from day one. + +#### Onboarding Checklist + +| Step | Timeline | Owner | Verification Method | +|------|----------|-------|-------------------| +| FMCSA authority verification (active MC#, property authorization) | Day 1 | Compliance | SAFER website direct lookup | +| Insurance verification ($1M+ auto liability, $100K cargo, workers comp) | Day 1 | Compliance | FMCSA Insurance tab + certificate of insurance on file | +| Safety rating and CSA score review | Day 1 | Compliance | SAFER + CSA BASIC percentiles — flag if Unsafe Driving or HOS >75th percentile | +| W-9 and payment setup | Days 1-3 | AP/Finance | IRS TIN matching | +| Carrier agreement execution (rate confirmation template, accessorial schedule, insurance requirements, performance expectations) | Days 3-5 | Transportation Manager | Signed agreement on file | +| TMS/EDI setup (210, 214, 990 transactions if applicable) | Days 5-10 | IT/Integration | Test transaction confirmation | +| Initial rate confirmation for awarded lanes | Days 5-7 | Transportation Manager | Countersigned rate confirmation per lane | +| 30-day trial loads (minimum 5 loads before full allocation) | Days 10-40 | Operations | Trial performance review at day 30 — OTD, communication, billing accuracy | +| Quarterly compliance re-verification (ongoing) | Every 90 days | Compliance | Automated FMCSA/insurance monitoring via Highway, RMIS, or Carrier411 | + +### 2.4 Carrier Exit Process + +Exiting a carrier requires planning to avoid service disruption on lanes they currently serve. + +#### Decision: Immediate vs. Managed Exit + +| Scenario | Exit Type | Timeline | +|----------|-----------|----------| +| FMCSA authority revoked or insurance lapsed | Immediate — stop tendering now | 0 days | +| Confirmed double-brokering | Immediate — stop tendering, document evidence | 0 days | +| Unsatisfactory safety rating | Immediate — stop tendering | 0 days | +| Corrective action plan failed (service metrics) | Managed — transition volume over 30-60 days | 30-60 days | +| Rate renegotiation failed (carrier above market) | Managed — transition after RFP award | 60-90 days | +| Strategic portfolio simplification (too many carriers) | Managed — transition volume at next contract renewal | 90-120 days | + +#### Managed Exit Steps + +1. **Identify replacement capacity** — ensure backup carriers on every lane the exiting carrier serves can absorb the volume. Run test loads if backups haven't been used in 90+ days. +2. **Communicate transparently** — tell the carrier why. "Your OTD has been below 85% for the last quarter despite our corrective action plan. We need to shift this volume to a carrier that can meet our service requirements." Burning bridges is unnecessary — carriers improve, get acquired, or re-enter your network in future cycles. +3. **Transition volume gradually** — reduce allocation by 25% per week over 4 weeks. Abrupt volume loss can damage the carrier's operations (especially small carriers who built capacity around your freight). +4. **Settle outstanding claims and invoices** — ensure all open claims are filed and all invoices are paid or disputed before the relationship goes dormant. Unresolved financial items turn a professional exit into a adversarial one. +5. **Retain the carrier record** — do not delete the carrier from your systems. Document exit reasons, performance history, and corrective actions. If the carrier improves or changes ownership, you may onboard them again in 12-24 months. + +--- + +## 3. RFP Execution Framework + +### 3.1 RFP Timeline + +| Phase | Duration | Activities | +|-------|----------|-----------| +| 1 — Pre-RFP Analysis | Weeks 1-2 | Analyze 12 months of shipment data, identify lanes for bid, benchmark current rates against DAT/Greenscreens, set cost and service targets, define evaluation criteria and weightings | +| 2 — RFP Development | Weeks 3-4 | Build lane-level bid package with volume, equipment, and service requirements. Define accessorial schedule, insurance minimums, and contract terms. Prepare carrier communication and Q&A timeline | +| 3 — Carrier Outreach | Week 5 | Distribute RFP to incumbent carriers + 5-10 prospective carriers identified through market research or peer referrals. Allow 2-3 weeks for bid submission | +| 4 — Bid Collection | Weeks 5-7 | Answer carrier questions (standardize responses via Q&A document shared with all bidders). Remind non-respondents at the halfway mark | +| 5 — Bid Analysis | Weeks 8-9 | Score bids using weighted criteria (see §3.2). Model total cost per lane. Rank carriers per lane. Identify negotiation targets (carriers close to award threshold) | +| 6 — Negotiation | Weeks 9-10 | Final-round negotiation with top 2-3 carriers per lane. Focus on lanes where top bids are within 5% of each other — these are negotiable. Do not renegotiate with the low bidder on lanes where they're already 10%+ below the field | +| 7 — Award | Week 11 | Notify winning carriers with lane awards and effective dates. Notify losing carriers with feedback (if they ask). Begin rate confirmation process | +| 8 — Implementation | Weeks 11-12 | Load new rates in TMS. Update routing guide. Run 2-week parallel period with old and new guides. Resolve any issues before full cutover | + +### 3.2 Bid Evaluation Scoring + +#### Criteria Weighting + +| Criterion | Weight | Data Source | Scoring Method | +|-----------|--------|-------------|---------------| +| Rate competitiveness | 40% | Bid response | Normalize to 100-point scale where lowest total cost (linehaul + modeled FSC + expected accessorials) = 100, and each 1% above lowest = -3 points | +| Service history / OTD | 25% | Carrier scorecard (for incumbents) or reference checks (for new carriers) | 100 points for ≥96% OTD, 80 for 93-95%, 60 for 90-92%, 40 for 85-89%, 0 for <85% | +| Capacity commitment | 20% | Bid response (stated tender acceptance commitment, equipment availability, driver count on the lane) | 100 points for ≥95% acceptance commitment with driver count evidence, scaled down based on commitment level and supporting evidence | +| Operational fit | 15% | Bid response + due diligence | Technology integration (EDI/API), FMCSA compliance score, driver domicile proximity, equipment match, prior relationship quality | + +#### Example Scoring — Lane CHI-DAL (5 loads/week) + +``` + Rate (40%) Service (25%) Capacity (20%) Ops Fit (15%) Total +Carrier A: 85 × 0.40 95 × 0.25 90 × 0.20 80 × 0.15 = 88.75 +Carrier B: 100 × 0.40 70 × 0.25 85 × 0.20 75 × 0.15 = 86.75 +Carrier C: 92 × 0.40 90 × 0.25 80 × 0.20 90 × 0.15 = 89.10 + +Award: Carrier C as primary (89.10), Carrier A as secondary (88.75). +Carrier B has lowest rate but weakest service — appropriate as tertiary. +``` + +### 3.3 Incumbent vs. New Carrier Evaluation + +Incumbents have data; new carriers have promises. Adjust evaluation accordingly: + +| Factor | Incumbent | New Carrier | +|--------|-----------|-------------| +| Service history | Use actual OTD, claims, tender acceptance from your data | Use carrier's reported statistics + 2-3 reference checks from similarly sized shippers | +| Rate credibility | High — they know the lane and are pricing from experience | Moderate — new carriers may under-bid to win then renegotiate after award. Discount new-carrier bids by 3-5% for risk | +| Implementation risk | Low — already in your systems, familiar with your operations | Moderate — onboarding takes 2-3 weeks, first-month performance often lags | +| Competitive tension value | Moderate — they know you know their performance | High — new entrants create competitive pressure that benefits your entire portfolio | + +### 3.4 Post-RFP Rate Lock and Market Movement + +Your RFP award locks rates for 12 months (typical). But the market moves. Build +these protections into the contract: + +- **Market-based reopener clause:** If DAT contract lane average moves >15% from the awarded rate for 60+ consecutive days, either party may request a rate review. This protects you in a softening market and protects the carrier in a tightening market. +- **Volume band pricing:** If your actual volume on a lane falls below 75% or exceeds 125% of the RFP-stated volume, rates are subject to renegotiation. This prevents you from losing volume and still paying volume-discounted rates, or from flooding a carrier with unanticipated volume at rates that don't cover their incremental costs. +- **Annual escalator option:** For multi-year contracts, build in a pre-agreed escalator (typically 2-4% annually) tied to a published index (PPI-Truck Transportation, DAT National Average). This avoids the disruption of an annual RFP while keeping rates aligned with costs. + +--- + +## 4. Contract vs. Spot Market Decision Framework + +### 4.1 Decision Matrix + +| Condition | Recommendation | Rationale | +|-----------|---------------|-----------| +| Lane volume >3 loads/week, consistent year-round | Contract | Carrier will invest in dedicated capacity for predictable volume | +| Lane volume 1-3 loads/week, seasonal | Contract for peak months, spot for off-peak | Avoids paying contract rates during low-demand months | +| Lane volume <1 load/week, unpredictable | Spot or broker relationship | Carriers won't commit capacity to inconsistent volume; contract rates will be inflated to cover utilization risk | +| Spot rates are >15% below contract rate for 60+ days | Move 20-30% of volume to spot | Market has moved significantly — capture savings while maintaining contract relationship | +| Spot rates are >15% above contract rate | Stay on contract, honor volume commitments | This is when contract value materializes — your carriers are holding rates below market for you. Reward their commitment by giving them your full volume | +| Customer requires guaranteed transit time | Contract with service-level agreement | Spot carriers have no SLA obligation — you can't guarantee what you can't control | +| Lane serves a production line or retail replenishment | Contract with primary and secondary carriers | Risk of spot market non-coverage is unacceptable for critical supply chains | +| New lane with unknown volume pattern | Spot for 60-90 days, then evaluate | Gather data before committing to a contract rate that may not reflect actual demand | + +### 4.2 Spot Market Best Practices + +When procuring on the spot market: + +- **Set a rate ceiling** before posting. Use your tertiary contract rate + 15% as the maximum. Anything above that threshold requires manager approval. +- **Vet the carrier** even for single loads. At minimum: FMCSA authority check, insurance verification, Carrier411 or Highway check for complaints. A 60-second screening prevents catastrophic outcomes (uninsured carrier, double-brokered load, stolen freight). +- **Demand rate confirmation** before the truck arrives. Verbal agreements on spot loads are unenforceable. Get the rate confirmation signed with all accessorials, FSC, and detention terms specified. +- **Track spot premium** meticulously. Report spot vs. contract spread weekly by lane. If any lane consistently shows >20% spot premium, your routing guide on that lane needs attention. + +--- + +## 5. Carrier Onboarding and Offboarding Decision Trees + +### 5.1 Onboarding Decision Tree + +``` +New carrier candidate identified +│ +├─ FMCSA authority check +│ ├─ Authority inactive/revoked → REJECT (do not proceed) +│ ├─ Authority <6 months old → PROCEED WITH CAUTION (new entrant risk) +│ └─ Authority active, >12 months → PROCEED +│ +├─ Insurance verification +│ ├─ Auto liability <$1M → REJECT (below your minimum) +│ ├─ Cargo insurance <$100K → NEGOTIATE (require $100K minimum) +│ └─ Meets all minimums → PROCEED +│ +├─ Safety assessment +│ ├─ FMCSA Unsatisfactory rating → REJECT +│ ├─ CSA BASIC >90th percentile on Unsafe Driving → REJECT +│ ├─ CSA BASIC >75th percentile on any BASIC → FLAG for risk review +│ └─ CSA acceptable → PROCEED +│ +├─ Financial health check +│ ├─ Broker bond revoked or reduced → REJECT (if broker) +│ ├─ Recent insurance underwriter changes (3+ in 12 months) → FLAG +│ ├─ Driver complaints on Carrier411 re: pay → FLAG for monitoring +│ └─ No red flags → PROCEED +│ +├─ Operational fit +│ ├─ No EDI/API capability and your volume requires it → NEGOTIATE timeline +│ ├─ Equipment doesn't match requirements → REJECT for this lane +│ └─ Operational fit confirmed → PROCEED +│ +└─ ONBOARD: Execute carrier agreement, set up in TMS, run trial loads +``` + +### 5.2 Offboarding Decision Tree + +``` +Carrier performance or compliance concern identified +│ +├─ Compliance failure (authority, insurance, safety) +│ ├─ Authority revoked → IMMEDIATE EXIT (stop tendering today) +│ ├─ Insurance lapsed → IMMEDIATE SUSPENSION (reinstate if corrected in 48 hrs) +│ ├─ Unsatisfactory safety rating → IMMEDIATE EXIT +│ └─ CSA scores worsened into >90th percentile → 30-DAY REVIEW with carrier +│ +├─ Service performance failure +│ ├─ OTD <85% for 60 days +│ │ ├─ First occurrence → CORRECTIVE ACTION PLAN (60-day timeline) +│ │ └─ Second occurrence after CAP → MANAGED EXIT (30-60 days) +│ │ +│ ├─ Tender acceptance <70% for 30 days +│ │ ├─ Carrier communicating, rate issue → RENEGOTIATE +│ │ └─ Carrier non-responsive → MANAGED EXIT (30 days) +│ │ +│ └─ Claims ratio >2% for 90 days → CORRECTIVE ACTION PLAN +│ +├─ Integrity failure +│ ├─ Double-brokering confirmed → IMMEDIATE EXIT + document for industry +│ ├─ Insurance fraud (forged certificate) → IMMEDIATE EXIT + report to FMCSA +│ └─ Systematic overbilling (>5% overcharge pattern) → CORRECTIVE ACTION, exit if not resolved in 30 days +│ +└─ Strategic portfolio decision + ├─ Carrier redundant (consolidating) → MANAGED EXIT at contract renewal + └─ Carrier non-competitive on rate → INCLUDE IN NEXT RFP (give them a chance to compete) +``` + +--- + +## 6. Market Cycle Positioning + +### 6.1 Cycle Identification Framework + +The freight market follows a pattern of loosening and tightening that repeats every +2-3 years. Identifying where you are in the cycle determines your negotiation stance, +contract strategy, and portfolio decisions. + +#### Leading Indicators (Signal Direction 3-6 Months Ahead) + +| Indicator | Source | Shipper-Favorable Signal | Carrier-Favorable Signal | +|-----------|--------|------------------------|------------------------| +| Class 8 truck orders | ACT Research, FTR | Rising (new capacity entering) | Falling (capacity leaving or not being replaced) | +| FMCSA new authority applications | FMCSA data | Rising (new carriers entering) | Falling (fewer new entrants, possibly exits increasing) | +| Diesel price trend | DOE | Falling (lowers carrier costs, reduces FSC) | Rising sharply (squeezes small carriers, may cause exits) | +| Manufacturing PMI | ISM | <50 (contraction, less freight demand) | >55 (expansion, freight demand growing) | +| Retail inventory-to-sales ratio | Census Bureau | Rising (retailers overstocked, less reorder freight) | Falling (retailers restocking, generating freight demand) | + +#### Coincident Indicators (Confirm Current Position) + +| Indicator | Source | Shipper-Favorable | Carrier-Favorable | +|-----------|--------|------------------|------------------| +| DAT load-to-truck ratio | DAT | <3:1 (more trucks than loads) | >6:1 (more loads than trucks) | +| Outbound Tender Rejection Index (OTRI) | FreightWaves SONAR | <5% (carriers accepting almost everything) | >12% (carriers cherry-picking profitable freight) | +| Spot rate trend (13-week) | DAT, Greenscreens | Declining or flat | Rising >5% over 13 weeks | +| Your tender acceptance rate | TMS data | >95% across portfolio | <85% across portfolio | + +### 6.2 Strategic Actions by Cycle Phase + +| Phase | Duration (typical) | Rate Action | Contract Action | Portfolio Action | +|-------|-------------------|-------------|-----------------|-----------------| +| Early recovery (market tightening) | 3-6 months | Lock rates on top 30% of lanes before carriers reprice | Extend expiring contracts 6-12 months at current rates | Onboard 2-3 new carriers for surge capacity | +| Peak (tight market) | 6-12 months | Minimize rate exposure — renegotiate only what's necessary | Honor commitments — this builds carrier trust for the downturn | Increase allocation to asset carriers (brokers get unreliable in tight markets) | +| Early softening (market loosening) | 3-6 months | Run mini-bids on your worst-performing 20% of lanes | Let short-term contracts expire — rebid at new market rates | Evaluate carrier portfolio for exits (weak performers lose leverage to resist) | +| Trough (soft market) | 6-12 months | Full RFP — maximum competitive tension, target 8-15% savings | Sign 18-24 month contracts to lock favorable rates | Consolidate to fewer, stronger carriers (volume concentration maximizes discount) | + +--- + +## Appendix A — Quick-Reference Decision Cards + +### Card 1: "Should I renegotiate this carrier's rate?" + +``` +IF contract rate > DAT contract average + 15% for 60+ days → YES +IF carrier tender acceptance < 75% for 30+ days → YES (rate is likely below their floor) +IF your volume dropped >25% from what was committed → YES (proactive, before carrier notices) +IF spot market is >15% below your contract for 60+ days → YES +IF carrier's service scores are in top 10% of your portfolio → NO (pay for quality) +IF contract expires in <90 days → WAIT for renewal negotiation +``` + +### Card 2: "How many carriers should I have on this lane?" + +``` +IF lane volume > 10 loads/week → 3-4 carriers +IF lane volume 5-10/week → 3 carriers +IF lane volume 2-5/week → 2-3 carriers +IF lane volume < 2/week → 1 carrier + 1 broker backup +IF lane is customer-critical (JIT, perishable, penalty clauses) → add 1 more carrier than volume alone suggests +IF lane serves a single customer who is >20% of your revenue → NEVER fewer than 3 +``` + +### Card 3: "Is this carrier financially healthy?" + +``` +CHECK FMCSA for active authority and current insurance → If either is lapsed, STOP +CHECK insurance: has the underwriter changed 3+ times in 12 months? → RED FLAG +CHECK Carrier411/CarrierOK: driver complaints about pay? → YELLOW FLAG +CHECK: has the carrier's bond amount decreased? → RED FLAG (for brokers) +CHECK: sudden decline in tender acceptance across all your lanes? → YELLOW FLAG +IF 2+ yellow flags or 1+ red flag → REDUCE EXPOSURE incrementally, do not wait +``` + +### Card 4: "Should I go to spot market on this load?" + +``` +IF all routing guide carriers rejected → YES (no choice) +IF spot rate < contract rate - 10% → YES (capture savings, track as data for renegotiation) +IF lane is irregular (< 1 load/week) and no contract carrier → YES +IF customer requires guaranteed transit and SLA → NO (stay on contract) +IF you're in peak season and spot rates are 30%+ above contract → NO (honor contract, build carrier goodwill) +ALWAYS: vet the spot carrier (FMCSA check, rate confirmation signed before dispatch) +``` + +--- + +## Appendix B — Glossary + +| Term | Definition | +|------|-----------| +| BASIC | Behavior Analysis and Safety Improvement Categories — the seven CSA safety dimensions scored by FMCSA | +| CAP | Corrective Action Plan — formal performance improvement plan with timeline and metrics | +| CSA | Compliance, Safety, Accountability — FMCSA's carrier safety measurement system | +| DAT | The largest spot market freight data provider (now DAT Freight & Analytics) | +| DOE | Department of Energy — publishes weekly national average diesel prices used for FSC calculations | +| EDI | Electronic Data Interchange — standardized electronic communication between shipper and carrier systems | +| FSC | Fuel Surcharge — variable rate component indexed to diesel prices | +| Greenscreens | AI-powered freight rate intelligence platform for benchmarking and predictive pricing | +| MC# | Motor Carrier number — FMCSA-issued operating authority identifier | +| OTRI | Outbound Tender Rejection Index — published by FreightWaves SONAR, measures % of electronic tenders rejected by carriers | +| PPI | Producer Price Index — published by BLS, used as a cost escalator in multi-year contracts | +| RMIS | Registry Monitoring Insurance Service — third-party carrier compliance monitoring platform | +| RFP | Request for Proposal — formal bid process for awarding freight lanes to carriers | +| SAFER | Safety and Fitness Electronic Records — FMCSA's public carrier database | +| SCAC | Standard Carrier Alpha Code — 2-4 letter identifier for each carrier | +| TMS | Transportation Management System — software for managing freight operations and carrier relationships | diff --git a/web-app/public/skills/carrier-relationship-management/references/edge-cases.md b/web-app/public/skills/carrier-relationship-management/references/edge-cases.md new file mode 100644 index 00000000..26426db4 --- /dev/null +++ b/web-app/public/skills/carrier-relationship-management/references/edge-cases.md @@ -0,0 +1,527 @@ +# Carrier Relationship Management — Edge Cases Reference + +> Tier 3 reference. Load on demand when handling complex carrier management situations that don't resolve through standard decision frameworks. + +These edge cases represent the scenarios that separate experienced transportation managers from everyone else. Each involves competing priorities, incomplete information, relationship dynamics, and real financial exposure. They are structured to guide resolution when standard carrier management playbooks break down. + +--- + +## How to Use This File + +When a carrier relationship situation doesn't fit a clean decision tree — when market dynamics create conflicting incentives, when carrier behavior signals something deeper than surface metrics show, or when the standard rate negotiation playbook produces a bad outcome — find the edge case below that most closely matches the situation. Follow the expert approach step by step. + +--- + +### Edge Case 1: Capacity Squeeze During Hurricane Season — Balancing Spot Market Panic Against Strategic Positioning + +**Situation:** +A national consumer goods manufacturer ships 120+ FTL loads per week across the Southeast. Hurricane Michaela has made landfall on the Gulf Coast, and FMCSA has issued an emergency declaration for FL, AL, MS, and LA. Your top 3 carriers in the region have pulled drivers off Florida and coastal Alabama routes. Your routing guide for 35 Southeast lanes is effectively dead — tender rejections are running 60%+ for the last 48 hours. Spot rates on lanes touching Florida have jumped from $2.80/mile to $6.50/mile. Your VP of Sales is calling because Walmart's DC in Lakeland, FL needs 8 loads of household cleaning products by Friday for hurricane response stocking, and your West Coast operations need 12 loads of raw materials moved out of Mobile, AL before the storm surge floods the port warehouse. + +The spot market is a feeding frenzy. Brokers are quoting $8,000 for a $3,200 lane. Your procurement team wants to pay whatever it takes. Your CFO wants to know why freight costs just tripled. + +**Why It's Tricky:** +Paying panic rates on 35+ lanes for 7-10 days can cost $150K-$300K in incremental freight spend above your contract rates. But refusing to pay means freight doesn't move, Walmart doesn't get their hurricane response product (damaging a $40M annual relationship), and your Mobile warehouse potentially floods with $2M in raw materials sitting on the floor. + +The deeper problem: every shipper in the Southeast is bidding up the same shrinking carrier pool simultaneously. The carriers and brokers who covered your freight reliably at $2.80/mile last week are now selling that same capacity at $6.50 to the highest bidder — and your contract rates are irrelevant because force majeure clauses in most carrier agreements suspend rate obligations during declared emergencies. + +**Common Mistake:** +Posting all 35 lanes to the spot market simultaneously at "market rate" and accepting the first truck that quotes. This guarantees you'll pay peak panic pricing on every load, attract the least reliable carriers (the quality carriers are already committed), and create a billing reconciliation nightmare when 35 different spot carriers each have different rate confirmations, detention terms, and accessorial structures. + +The second mistake: trying to enforce contract rates during a declared emergency. Your contract carriers aren't rejecting tenders to be adversarial — they literally can't get drivers into the affected area safely. Threatening to pull their contract lanes post-storm will earn you a reputation as a shipper who doesn't understand emergencies, and they'll remember at the next RFP. + +**Expert Approach:** +1. Triage your 35 affected lanes immediately. Not all lanes are equal. Categorize into three tiers: + - **Tier 1 — Must Move (8-10 lanes):** Customer penalty exposure, perishable, safety stock at risk, or product at physical risk (the Mobile warehouse). These move at spot market rates, period. + - **Tier 2 — Should Move (12-15 lanes):** Standard replenishment, can tolerate 3-5 day delay without customer impact. Delay these loads until the initial panic subsides (spot rates typically drop 30-40% within 72 hours of landfall as the actual storm path becomes clear and unaffected corridors reopen). + - **Tier 3 — Can Wait (10-12 lanes):** Low urgency, large buffer stock at destination. Hold these until your contract carriers resume normal operations (typically 7-14 days post-storm for the directly affected region). + +2. For Tier 1 loads, do not post to open load boards. Instead, call your top 3 broker partners directly. Offer them a multi-load commitment: "I have 8 loads that need to move in the next 48 hours. I'll commit all 8 to you at $5,200/load if you can guarantee coverage." A broker getting 8 committed loads at $5,200 will prioritize you over single-load spot postings at $6,500 because the certainty of 8 loads is more valuable than the possibility of 8 individual loads at a higher rate. + +3. Activate regional carriers you've pre-positioned for exactly this scenario. Every experienced transportation manager maintains relationships with 3-5 small carriers in hurricane-prone regions who run owner-operator fleets. These carriers park their trucks inland before the storm and redeploy as soon as roads open. They're expensive ($4.50-$5.50/mile during events), but they're available when national carriers have pulled out. + +4. For the Mobile warehouse evacuation, consider a dedicated carrier or fleet provider rather than spot market. A fleet of 12 trucks from a single carrier coordinating an evacuation is operationally cleaner than 12 individual spot trucks arriving on different schedules. Contact your largest asset carrier and offer a premium ($4,800/load on a $3,200 lane) for dedicated fleet assignment over 48 hours. Frame it as: "We need a fleet solution, not 12 individual loads. Can you dedicate 12 power units for 48 hours?" + +5. After the storm: do not retroactively dispute the premium rates you paid. Document the event, the incremental cost, and the business justification. Present to the CFO as a weather event cost, not a freight rate failure. Then conduct a post-storm review: which carriers came through, which disappeared? Adjust your routing guide allocation to reward carriers who provided capacity during the crisis — those carriers earned the right to your best lanes in the next calm period. + +**Key Indicators:** +- Tender rejection rates above 50% on regional lanes signal a network disruption, not individual carrier problems — adjust response accordingly +- Spot rate spikes that exceed 2× contract rates within 48 hours indicate panic pricing, not a new market equilibrium — rates will retreat +- Carriers communicating proactively about their capacity constraints during the event are your best long-term partners — track who calls you vs. who goes silent +- FMCSA emergency declarations suspend HOS requirements, meaning available drivers can run more hours — some capacity will return within 48-72 hours as drivers extend their available drive time +- Monitor NOAA track updates every 6 hours — storm path changes can open or close corridors and shift where capacity is available + +**Documentation Required:** +- FMCSA emergency declaration documentation +- Lane-by-lane triage classification with business justification +- Spot rate confirmations for all Tier 1 loads +- Multi-load commitment agreements with brokers +- Carrier communication log (who contacted you, who you contacted, responses) +- Total incremental freight cost calculation vs. normal contract rates +- Post-event carrier performance assessment + +**Resolution Timeline:** +- Hours 0-6: Lane triage, Tier 1 procurement initiated, Mobile evacuation fleet secured +- Hours 6-24: Tier 1 loads dispatched, Tier 2 loads staged for delayed dispatch +- Days 2-5: Spot rates begin normalizing, Tier 2 loads dispatched at reduced premiums +- Days 5-14: Contract carriers resume normal operations, Tier 3 loads move at contract rates +- Days 14-30: Post-event review, carrier performance assessment, routing guide adjustments + +--- + +### Edge Case 2: Double-Brokering Discovery Mid-Relationship + +**Situation:** +Your compliance analyst runs a quarterly audit and discovers that Pinnacle Logistics (MC-892431), a broker in your routing guide handling 15 loads/week across 6 Midwest lanes, has been double-brokering approximately 30% of your freight. The evidence: BOL driver names don't match Pinnacle's dispatched driver, truck numbers on PODs belong to carriers not in Pinnacle's disclosed network, and two loads last month were delivered by a carrier with an FMCSA Conditional safety rating — a carrier your compliance standards would have rejected at onboarding. + +Pinnacle is your secondary carrier on 4 of these lanes and tertiary on 2. Their rates are competitive (5-8% below your primary carriers on these lanes). Their OTD is acceptable at 93%. You've had a 2-year relationship with Pinnacle's account manager, who is responsive and professional. Your operations team hasn't reported any service complaints. + +**Why It's Tricky:** +Double-brokering isn't always a clear-cut "fire them immediately" situation, even though it's a serious compliance violation. The problem: Pinnacle's service has been acceptable, their rates are good, and ripping them out of 6 lanes creates an immediate capacity gap. Your operations team will feel the pain before your compliance team feels the vindication. + +But the risks are real: when Pinnacle re-brokers your freight, the actual carrier isn't in your insurance verification chain. If that Conditional-rated carrier causes an accident hauling your freight, your risk exposure is enormous. Pinnacle's cargo insurance may not cover loads they've brokered out (most broker cargo policies exclude double-brokered freight). And if the actual carrier is never paid (because Pinnacle pockets the margin and goes bankrupt), the actual carrier can assert a lien on your freight. + +**Common Mistake:** +Ignoring the discovery because "the service is fine." The compliance risk is not hypothetical — it's actuarial. One accident with an unvetted carrier creates a liability exposure that dwarfs any rate savings. The other common mistake: confronting Pinnacle's account manager in an accusatory call that destroys any possibility of a managed transition. + +**Expert Approach:** +1. Confirm the evidence before acting. Pull 90 days of BOLs and PODs for Pinnacle's loads. Cross-reference driver names on PODs against Pinnacle's disclosed carrier network. Run FMCSA lookups on the truck numbers appearing on PODs. Document every instance where the delivering carrier doesn't match Pinnacle's dispatch records. Build a clear, evidence-based file. + +2. Assess the scope and risk. How many loads were double-brokered? Were any of those loads high-value, temperature-sensitive, or hazmat? Did any of the actual carriers have safety or insurance issues? This determines whether the response is "serious conversation" or "immediate termination." + +3. Schedule a formal meeting with Pinnacle's ownership (not just the account manager). Present the findings factually: "We've identified X instances over the last 90 days where the delivering carrier did not match your dispatch records. Can you explain?" Give them the opportunity to respond. Some brokers use partner carriers through disclosed sub-broker arrangements that are technically legitimate — but undisclosed sub-brokering is not. + +4. If Pinnacle confirms double-brokering: require them to disclose all carriers used on your freight, retroactively. Verify insurance and FMCSA compliance for every disclosed carrier. Demand a written commitment to cease double-brokering your freight, with a contractual penalty clause for future violations. Require Pinnacle to provide carrier disclosure on every load going forward (carrier name, MC#, and driver name at time of dispatch). + +5. Simultaneously, begin qualifying replacement carriers for Pinnacle's 6 lanes. You'll need this capacity whether you keep Pinnacle or not — reduced trust requires a backup plan. Identify 2-3 carriers per lane from your existing portfolio or new prospects. Run trial loads within 30 days. + +6. Decision point at 30 days: if Pinnacle has complied with disclosure requirements and the underlying carriers pass your vetting, consider keeping them at reduced allocation (drop from secondary to tertiary on all lanes). If Pinnacle resists transparency, exit them with a managed 30-day transition using the replacement carriers you've already qualified. + +**Key Indicators:** +- POD driver names consistently different from dispatch records is the primary indicator of double-brokering +- Truck numbers (DOT numbers on the trailer or tractor) that don't match the broker's carrier network are conclusive evidence +- A broker whose rates are consistently 5-10% below your other carriers may be achieving those rates by using carriers that don't meet your compliance standards — the discount is a risk premium you're not being compensated for +- If the broker is evasive when asked "who is actually hauling our freight?", that's an answer in itself +- Check whether the broker's surety bond is at the minimum $75K — a broker double-brokering heavily is likely cash-strapped + +**Documentation Required:** +- 90-day audit report: BOL/POD analysis showing carrier mismatches +- FMCSA lookups on all actual carriers identified +- Insurance verification for actual carriers +- Written communication to Pinnacle documenting findings and required corrective action +- Pinnacle's response and corrective commitments +- Replacement carrier qualification records +- Updated carrier agreement with anti-double-brokering clause and penalty provision + +**Resolution Timeline:** +- Days 0-5: Evidence compiled, risk assessment completed +- Days 5-10: Meeting with Pinnacle ownership, findings presented +- Days 10-30: Pinnacle corrective action implementation, replacement carrier qualification in parallel +- Day 30: Decision on Pinnacle's future status (retain at reduced allocation vs. managed exit) +- Days 30-60: Transition complete if exit decision is made + +--- + +### Edge Case 3: Rate Renegotiation After Major Volume Loss + +**Situation:** +Your company lost its largest retail customer (representing 35% of total outbound freight volume) due to a product quality issue unrelated to logistics. Your carrier contracts were negotiated 6 months ago based on volume projections that included this customer's freight. Specifically, you committed to 450 loads/week across your network, and you're now shipping 290 loads/week. Your top 5 carriers, who account for 70% of your freight spend, priced their rates based on the 450-load commitment. Some of those rates include volume-based discount tiers that you're no longer achieving. + +Your current contract rates are 3-6% below DAT benchmark, which was attractive at 450 loads/week but represents a potential carrier exit risk at 290 loads/week. Three of your top 5 carriers have already noticed the volume decline (their weekly load counts from you have dropped 30-40%) but haven't raised it formally yet. Your annual freight spend has gone from ~$52M to ~$34M. + +**Why It's Tricky:** +You have a fiduciary obligation to manage freight costs (which means keeping rates competitive), a contractual obligation to your carriers (which may include volume commitments), and a relationship obligation (which means not blindsiding carriers who priced based on your representations). These three obligations are in tension. + +If you say nothing, your carriers will figure it out from their declining load counts, feel deceived, and start repricing unilaterally or rejecting tenders on less profitable lanes. If you immediately try to renegotiate rates upward to "be fair," your CFO will rightly ask why you're volunteering cost increases during a revenue decline. If you try to hold carriers to the current below-market rates despite the volume shortfall, they'll exit your least profitable lanes first — which are probably the lanes you need most. + +**Common Mistake:** +Staying silent and hoping carriers don't notice. They always notice. A carrier whose load count from you drops from 60/week to 38/week adjusts their resource planning accordingly — and your freight drops in their internal priority ranking. By the time they confront you about the volume decline, they've already reallocated their best drivers and equipment to shippers who deliver consistent volume. + +The second mistake: proactively offering rate increases across the board. Carriers don't want charity — they want honesty, predictability, and a clear picture of future volume so they can plan. + +**Expert Approach:** +1. Get ahead of the conversation. Within 2 weeks of knowing the volume loss is permanent, schedule individual calls with each of your top 5 carriers' account managers. Frame it as a strategic update, not a crisis: "We've had a significant customer change that affects our volume outlook. I want to walk you through what it means for our business together." + +2. For each carrier, prepare a lane-by-lane analysis showing: current committed volume, new projected volume, percentage change, and the revenue impact to the carrier. Do the carrier's math for them — it shows respect and prevents them from assuming the worst. + +3. Offer a restructured deal, not a rate increase. The restructured deal should include: (a) adjusted volume commitments that reflect reality (290 loads/week instead of 450), (b) a rate adjustment on lanes where your volume has dropped below the tier threshold (typically 3-5% increase), (c) a commitment to maintain or increase the carrier's percentage share of your remaining volume even though the absolute volume is lower, and (d) an honest volume forecast for the next 12 months including any new customer prospects. + +4. Prioritize your carrier conversations by strategic value: + - Carrier 1 (largest, strategic partner): Full transparency, restructured deal, multi-year commitment if they hold rates close to current levels + - Carriers 2-3 (strong performers): Transparent conversation, lane-level adjustment, 12-month commitment + - Carriers 4-5 (adequate performers): Inform of volume change, let them decide if they want to reprice or continue at current rates with reduced volume + +5. Use the volume loss as an opportunity to consolidate. With 290 loads/week instead of 450, you may have too many carriers in your portfolio. Offer your top 2-3 carriers a larger share of the remaining pie in exchange for holding rates flat or limiting increases to 2-3%. Consolidation = more volume per carrier = more value per carrier = better retention. + +6. If any carrier demands rate increases that exceed market rates, that's a signal they want to exit your portfolio. Let them — and replace them with carriers who want the volume at fair rates. In a soft market (which often accompanies shipper volume declines), finding replacement capacity is straightforward. + +**Key Indicators:** +- Carriers whose load counts from you have dropped 30%+ without explanation are already planning their response — get ahead of it +- Volume commitment shortfalls of >20% typically trigger rate reopener clauses in carrier contracts — read your contract before the carrier does +- Carriers who ask "what happened?" informally through their account manager are signaling they want to work with you. Carriers who send formal rate increase letters without a conversation are signaling they've already decided to reprice. +- Your leverage in this negotiation is the remaining 290 loads/week — that's still substantial freight. Don't negotiate from a position of weakness just because you lost volume. + +**Documentation Required:** +- Lane-by-lane volume analysis (before and after customer loss) +- Revenue impact by carrier (show you've done the work) +- Restructured deal proposals per carrier (rate adjustments, volume commitments, share allocation) +- Updated 12-month volume forecast +- Revised carrier agreements reflecting new terms +- Communication log documenting proactive outreach and carrier responses + +**Resolution Timeline:** +- Days 0-14: Internal analysis, restructured deal proposals drafted +- Days 14-30: Individual carrier conversations (top 5) +- Days 30-45: Carrier responses, negotiation of adjusted terms +- Days 45-60: Revised agreements executed, routing guide updated +- Days 60-90: Monitor carrier behavior under new terms — OTD, tender acceptance stability + +--- + +### Edge Case 4: Carrier Financial Distress — Early Warning Signs and Graduated Response + +**Situation:** +TransWay Freight (MC-645221), a mid-size asset carrier with ~180 trucks, has been your primary carrier on 8 Midwest lanes for 3 years. They've been a solid B-tier performer: 94% OTD, 88% tender acceptance, 0.4% claims ratio. You ship 25 loads/week with them, representing approximately $1.8M annual freight spend — which is roughly 6% of TransWay's estimated annual revenue. + +Over the last 60 days, you've noticed: (a) tender acceptance has dropped from 88% to 71% with no communication about rate issues, (b) three drivers on their routes have told your dock staff they haven't been paid in two weeks, (c) TransWay changed their insurance underwriter for the third time in 12 months, (d) their FMCSA filing shows the surety bond was reduced from $75K to the minimum $10K, and (e) their VP of Operations who was your primary contact left the company last month. + +None of these indicators individually would trigger an exit. Together, they paint a picture of a carrier in financial distress. + +**Why It's Tricky:** +Carrier financial distress is a slow-motion crisis. The carrier doesn't fail overnight — they degrade over weeks or months. During that degradation, their service deteriorates, their drivers leave, their insurance coverage becomes unreliable, and your freight is increasingly at risk. But cutting them immediately creates a capacity gap on 8 lanes, and if you're wrong about the distress, you've damaged a 3-year relationship based on speculation. + +The other complexity: if TransWay is in distress and you're 6% of their revenue, your sudden exit could accelerate their failure — creating the exact outcome you're trying to avoid. Other shippers on TransWay's network would also be affected, and word travels fast in the carrier community that you pulled volume from a struggling carrier without warning. + +**Common Mistake:** +Ignoring the warning signs because "their OTD is still above 90%." Financial distress takes 3-6 months to manifest in service metrics. By the time OTD drops below 85%, the carrier is in crisis and your options are worse. The other mistake: immediately pulling all volume, which creates an acute capacity gap and — if TransWay finds out why — damages your reputation as a shipper who panics. + +**Expert Approach:** +1. Verify each indicator independently. Run an FMCSA check on TransWay today — confirm the insurance underwriter change and bond reduction. Check Carrier411, CarrierOK, and trucking industry forums for driver complaints about non-payment. Call your 3 contacts at TransWay (not just the sales rep — call operations and maintenance managers) to gauge the internal temperature. + +2. Score the distress level: + - **Low concern (1-2 indicators):** Monitor weekly, no allocation change. + - **Moderate concern (3-4 indicators):** Reduce allocation by 25%, accelerate backup carrier qualification. + - **High concern (5+ indicators or any single critical indicator like insurance lapse):** Reduce allocation by 50%, prepare for full exit within 30 days. + + TransWay has 5 indicators → High concern. + +3. Do not announce the allocation reduction. Simply begin shifting loads to secondary carriers on each of TransWay's 8 lanes. Reduce from 25 loads/week to 12-15/week over 3 weeks. If TransWay asks about the volume decline, your answer is honest: "We're diversifying our portfolio on a few lanes to improve our routing guide depth. Nothing personal — it's a standard portfolio rebalance." + +4. In parallel, qualify 2-3 replacement carriers on TransWay's 8 lanes. Prioritize lanes where TransWay is your only carrier. Run trial loads within 2 weeks. You need these backups operational before TransWay potentially fails. + +5. Have a direct, private conversation with TransWay's CEO or owner. Not the sales rep — the person who knows the real financial picture. Frame it as: "You've been a great partner for 3 years. We've noticed some changes recently and want to understand your situation. Is there anything we should know?" If they're transparent about challenges, you can work together on a transition plan. If they deflect or deny, that's the most worrying response of all. + +6. Prepare for a sudden failure scenario. If TransWay goes dark overnight (it happens — carriers sometimes just stop answering the phone), you need a 48-hour plan to cover 12-15 loads/week across 8 lanes. Pre-negotiate spot rates with your backup carriers for this exact contingency. Have rate confirmations ready to execute. + +7. After the situation resolves (either TransWay stabilizes or fails), update your carrier risk monitoring to include financial health indicators as quarterly screening criteria for all carriers representing >3% of your freight spend. + +**Key Indicators:** +- Insurance underwriter changes 3+ times in 12 months: The current underwriter dropped TransWay and no A-rated insurer will pick them up. They're on a third-tier insurer who will also drop them soon. +- Surety bond reduction to minimum: TransWay's bondsman is unwilling to backstop the full $75K — this means the bonding company's underwriter has assessed TransWay as high-risk. +- Driver pay complaints: Drivers talk. If 3 drivers mention payment delays to your dock staff, there are probably 30 more experiencing the same thing across TransWay's network. Drivers who aren't paid leave — and their capacity goes with them. +- Key executive departure: A VP of Operations who leaves a 180-truck carrier without a visible next role may be leaving a sinking ship. Check LinkedIn for other recent departures. +- Tender acceptance decline without communication: A good carrier experiencing financial difficulty will call and explain. A carrier that just stops accepting tenders without explanation is either trying to hide the problem or has lost operational control. + +**Documentation Required:** +- FMCSA screening results (authority, insurance, safety, bond) +- Carrier411/CarrierOK complaint summary +- Internal driver feedback log (dock staff reports) +- Tender acceptance trend data (90-day) +- Allocation reduction timeline and load-level records +- Backup carrier qualification records for all 8 lanes +- Communication log with TransWay management +- Contingency plan for sudden carrier failure + +**Resolution Timeline:** +- Days 0-3: Indicator verification, distress scoring +- Days 3-14: Allocation reduction (25 → 12-15 loads/week), backup carrier qualification initiated +- Days 14-21: Backup carriers running trial loads on all 8 lanes +- Days 21-30: CEO/owner conversation, frank assessment of TransWay's outlook +- Days 30-60: Stable at reduced allocation if TransWay stabilizes, or complete exit if distress worsens +- Ongoing: Weekly monitoring of financial distress indicators + +--- + +### Edge Case 5: Broker vs. Asset Carrier Dispute on Service Failure Liability + +**Situation:** +You contracted with Overland Brokerage (MC-553890) for a critical weekly truckload lane from your Memphis plant to a Toyota assembly facility in San Antonio, TX. Overland quoted $3,100/load and committed to 48-hour transit with Tuesday 06:00 delivery. Overland sourced the loads from Patriot Haulers (MC-771204), a small asset carrier with 22 trucks, at $2,650/load. + +Last Tuesday, the load was 14 hours late. Toyota assessed a $28,000 line-down penalty against your company. When you called Overland to demand an explanation, their account manager said: "Patriot's driver broke down outside Dallas and didn't call dispatch for 4 hours. We only found out when Toyota called us. We're sorry, but the breakdown was Patriot's fault — take it up with them." + +You have a contract with Overland, not Patriot. Your contract with Overland includes a service-level clause requiring 95% OTD with a $500/incident credit for service failures. But your contract says nothing about consequential damages (like Toyota's $28K penalty). Overland is offering the $500 credit per the contract and nothing more. Patriot says they have no relationship with you and their obligation is to Overland. + +**Why It's Tricky:** +The brokerage model creates a liability gap. Your contract is with Overland (the broker). Overland's contract is with Patriot (the carrier). You have no contractual relationship with Patriot. Under standard brokerage law, a broker is not a carrier — they're an intermediary. The broker's liability is generally limited to what's in your broker-shipper agreement, which in this case is $500 per service failure. + +The $28K Toyota penalty is a consequential damage. Even if you had contracted directly with an asset carrier, consequential damages are difficult to recover unless you specifically put the carrier on notice of the consequences (see the JIT edge case in the logistics-exception-management capability). You didn't specify the Toyota penalty exposure in your contract with Overland. + +But Overland knew this was a Toyota JIT delivery — it was in the tender. They presumably communicated the delivery window to Patriot. The question is whether Overland exercised reasonable care in selecting Patriot and monitoring the load. If Patriot has a history of breakdowns and Overland knew (or should have known), Overland's negligence in carrier selection could open the door to consequential damages. + +**Common Mistake:** +Accepting the $500 credit and eating the $28K penalty. This teaches both Overland and your procurement team that JIT lanes can be brokered without consequence. The second mistake: threatening to sue Overland for $28K. Litigation against a broker for $28K is a money-losing proposition ($15-25K in legal costs) and destroys the relationship for all your other lanes. + +**Expert Approach:** +1. Separate the immediate issue (recovering some of the $28K) from the structural issue (protecting JIT lanes going forward). + +2. For the immediate issue: Request Overland's carrier selection records for Patriot on this lane. Specifically: when did Overland first use Patriot? What due diligence did Overland perform? Does Patriot have a history of service failures on time-critical loads? If Overland can demonstrate reasonable carrier selection and the breakdown was a genuine one-off, your recovery beyond the $500 credit is limited. If Overland has been using Patriot despite prior failures, their negligence in carrier selection strengthens your consequential damages argument. + +3. Negotiate with Overland for a middle ground. Propose: Overland absorbs $5,000-$8,000 of the penalty through a combination of freight credits ($500/load for the next 10-16 loads) and a rate reduction on this lane for the next 6 months. Frame it as: "Your $500 credit doesn't reflect the magnitude of this failure. I'm not asking you to cover the full $28K, but I need you to share the pain meaningfully to justify keeping you on this lane." + +4. Negotiate the Toyota penalty down. Toyota's $28K chargeback is likely based on their standard penalty formula. Request the detailed calculation. Push back on overhead allocation and opportunity cost components. A 14-hour delay on a Tuesday delivery likely cost Toyota 8-10 hours of actual line time after the recovery. Aim to reduce the chargeback to $15K-$20K. + +5. For the structural fix: move this lane to an asset carrier as primary, with Overland as backup. JIT lanes with consequential damage exposure should never have a broker as the primary carrier. The additional carrier layer in the brokerage model (broker → carrier) adds a communication delay and removes your visibility into the actual driver and equipment. + +6. Update your standard broker agreement to include: (a) a requirement that the broker disclose the underlying carrier for every load, (b) a carrier vetting standard that the broker must meet (minimum FMCSA safety score, insurance levels, etc.), and (c) a liquidated damages clause for service failures on lanes designated as "JIT-critical" — a pre-agreed amount (e.g., $5,000 per occurrence) that caps your downside and the broker's exposure. + +**Key Indicators:** +- A broker who deflects to "take it up with the carrier" is not operating as a responsible intermediary — they're acting as a pass-through with no accountability +- A 22-truck carrier (Patriot) handling a Toyota JIT lane raises questions about Overland's carrier selection process — did they prioritize cost over reliability? +- A 4-hour communication gap (driver broke down and didn't call dispatch) suggests Patriot has poor driver management processes — experienced carriers have GPS and ELD tracking that would surface a 4-hour stationary event +- Overland's willingness (or unwillingness) to share their carrier selection records tells you a lot about their operating standards + +**Documentation Required:** +- Your contract with Overland (service-level clause, liability provisions) +- Overland's contract with Patriot (request via your contractual audit rights if applicable) +- Toyota's penalty calculation and chargeback notice +- Load tracking history showing the delay timeline +- Patriot's FMCSA safety record and service history with Overland +- Overland's carrier selection documentation for this lane +- Negotiation correspondence with Overland (freight credit proposal) +- Revised broker agreement with carrier disclosure and liquidated damages provisions + +**Resolution Timeline:** +- Days 0-3: Toyota penalty assessment, Overland carrier selection records requested +- Days 3-10: Negotiate Toyota chargeback reduction, negotiate Overland freight credits +- Days 10-30: Qualify asset carrier for primary on this lane, move Overland to backup +- Days 30-45: Revised broker agreement executed with disclosure and damages provisions +- Days 45-60: Asset carrier fully operational on the lane, first performance review + +--- + +### Edge Case 6: Carrier Acquisition Affecting Your Service Network + +**Situation:** +Ridge Runner Express (MC-498132), a regional asset carrier with 85 trucks based in Knoxville, TN, has been your best-performing carrier in the Southeast for 4 years. They run 18 loads/week for you across 5 lanes, all with >96% OTD and 94% tender acceptance. Your dedicated account manager, Carol, knows your dock operations, your customers' receiving quirks, and your seasonal volume patterns. Ridge Runner just announced they've been acquired by National FreightWorks (MC-112200), a 4,500-truck national carrier known for aggressive pricing but mediocre service (their network average OTD is 91%, well below Ridge Runner's 96%). + +The acquisition closes in 60 days. National FreightWorks' integration plan calls for absorbing Ridge Runner's operating authority under the National FreightWorks MC#, integrating dispatching into their national operations center in Des Moines, and standardizing rates across the combined network. Carol has already been told her position will be eliminated during integration. + +**Why It's Tricky:** +Carrier acquisitions almost always degrade service during the integration period (6-18 months). The acquiring carrier's systems, processes, and culture overwhelm the smaller carrier's operational excellence. Drivers who valued the family-company culture leave. Dedicated account managers are replaced by national account reps managing 50+ shippers. Rates that were competitive for a regional carrier get "standardized" to the national carrier's tariff — which may be higher or lower depending on the lane. + +But you can't just preemptively exit. National FreightWorks is a legitimate, large carrier. They may ultimately provide capacity and coverage that Ridge Runner couldn't. And pulling 18 loads/week before the acquisition closes signals to both Ridge Runner and National FreightWorks that you're not willing to give the combined entity a chance. + +**Common Mistake:** +Waiting passively for the acquisition to complete and hoping for the best. By the time service degrades, National FreightWorks has integrated Ridge Runner's systems and you've lost your leverage to negotiate. The other mistake: immediately pulling all volume, which burns the relationship with National FreightWorks before they've even started. + +**Expert Approach:** +1. Meet with National FreightWorks' sales team immediately. Request a dedicated meeting (not a mass customer communication) to discuss: their integration timeline, which operational systems will survive (Ridge Runner's dispatch or National FreightWorks'?), whether your lanes will retain dedicated drivers or be absorbed into the national driver pool, and who your new account manager will be. + +2. Secure contractual protections before the acquisition closes. Propose a 12-month service guarantee as a condition of continuing your volume: OTD ≥94% (a slight step-down from Ridge Runner's 96% to acknowledge integration disruption), tender acceptance ≥88%, with a rate renegotiation trigger if either metric falls below the threshold for 60 days. Get this in writing from National FreightWorks' VP of Sales before the close. + +3. Begin qualifying 2-3 alternative carriers for your 5 Southeast lanes immediately — not to replace Ridge Runner/National FreightWorks, but to have a plan B. Run trial loads on each lane with the alternatives within 30 days. Having alternatives operational before the integration disruption gives you options that pure good faith does not. + +4. Recruit Carol. If your company has the need and budget, hire Ridge Runner's account manager into your organization as a carrier relationship specialist. She knows your operations, your carriers, and your customers. Even if you can't hire her, maintain the relationship — she'll land at another carrier or broker and bring institutional knowledge of your freight. + +5. Plan for a 90-day post-close performance review. Track National FreightWorks' performance on your 5 lanes weekly during the integration. Set a decision point at 90 days: if service levels are within the contractual guarantee, maintain full allocation. If service has degraded below the guarantee, shift 50% of volume to your qualified alternatives and invoke the rate renegotiation clause. + +**Key Indicators:** +- If National FreightWorks is centralizing dispatch, your loads will compete with 4,500 other trucks' dispatch priorities — expect tender acceptance to drop +- If Ridge Runner's drivers are being reassigned to national routes, expect turnover on your lanes — drivers who chose a regional carrier lifestyle rarely stay at a national carrier +- If National FreightWorks' integration team cannot name your new account manager within 30 days of close, they don't have a plan for your account +- Watch for rate "standardization" letters after close — this is often a rate increase disguised as administrative cleanup + +**Documentation Required:** +- Current carrier agreement with Ridge Runner (to understand transition terms) +- Written service guarantee from National FreightWorks +- Alternative carrier qualification records for all 5 lanes +- Weekly performance tracking for 90 days post-close +- Communication log with National FreightWorks integration team + +**Resolution Timeline:** +- Days 0-15: Meeting with National FreightWorks, service guarantee negotiation +- Days 15-45: Alternative carrier qualification, trial loads +- Day 60: Acquisition closes +- Days 60-150: 90-day post-close performance monitoring +- Day 150: Decision point — maintain allocation vs. begin shifting volume + +--- + +### Edge Case 7: Fuel Surcharge Table Manipulation + +**Situation:** +During your annual rate review, you notice that Consolidated Carriers is proposing a new rate structure: a $0.12/mile reduction in base linehaul rate (from $2.45 to $2.33/mile) coupled with a "modernized" fuel surcharge table. The new FSC table uses a base diesel price of $2.80/gal (vs. the current DOE average of $3.85/gal) and applies $0.02/mile per $0.06 increment above the base. The current FSC table uses a base of $3.50/gal with $0.01/mile per $0.05 increment. + +The carrier's account manager presents this as "a meaningful linehaul reduction that demonstrates our commitment to the partnership." + +**Why It's Tricky:** +The $0.12/mile linehaul reduction is real and looks good on a summary report. But the restructured FSC table is designed to recover that $0.12 (and more) through a lower base trigger and steeper increment. At the current diesel price of $3.85/gal, the new FSC is $0.35/mile vs. the old FSC of $0.07/mile — a difference of $0.28/mile. The carrier is actually proposing a $0.16/mile increase ($0.28 FSC increase - $0.12 linehaul decrease) disguised as a rate reduction. + +**Common Mistake:** +Accepting the "linehaul reduction" at face value without modeling the total cost across diesel scenarios. Many shippers negotiate linehaul and FSC separately, which is exactly what carriers exploit. The linehaul goes into the "rate savings" report to procurement leadership; the FSC flows through as a pass-through that nobody scrutinizes. + +**Expert Approach:** +1. Model total cost per mile at three diesel prices: $3.25 (low), $3.85 (current), $4.50 (high). +2. Present the analysis side-by-side to the carrier's account manager. Don't accuse them of manipulation — show the math: "When we model total cost, the new structure is actually $0.16/mile higher at current diesel. Can you walk me through the rationale?" +3. Counter-propose: accept the $0.12 linehaul reduction with the existing FSC table unchanged. Or negotiate a new FSC table with a base of $3.50 (matching the old) and a moderate increment of $0.012/mile per $0.05 diesel increase. +4. Establish a policy: any FSC table change must be modeled at three diesel price points and approved by the transportation manager, not just the analyst handling the rate update. + +**Key Indicators:** +- Any linehaul reduction paired with an FSC restructure should be modeled as a total-cost change +- FSC base prices significantly below current DOE average ($1+/gal below) are a red flag +- FSC increments above $0.015/mile per $0.05 diesel increase are above market standard +- A carrier proposing FSC changes mid-contract (rather than at renewal) may be trying to recover margin they lost in the RFP + +**Documentation Required:** +- Current and proposed rate structures side-by-side +- Total cost modeling at three diesel scenarios +- DOE diesel price history (12-month) and forward curve +- Counter-proposal with justification + +**Resolution Timeline:** +- Days 0-2: Total cost analysis completed +- Days 2-5: Presentation to carrier with counter-proposal +- Days 5-15: Negotiation of revised FSC terms +- Day 15: Revised rate structure executed or status quo maintained + +--- + +### Edge Case 8: Small Carrier vs. Mega-Carrier Tradeoffs on a Critical Lane + +**Situation:** +You're building a routing guide for a new high-priority lane: your Chicago plant to a major retailer's DC in Phoenix, 6 loads/week. You've received bids from two finalists: Desert Star Transport (12 trucks, family-owned, based in Phoenix, $2.28/mile, no EDI capability, 97% OTD on reference checks) and Central National Freight (3,800 trucks, national carrier, $2.15/mile, full EDI/API integration, 92% OTD per your existing scorecard data across 15 other lanes). + +Desert Star is 6% more expensive but significantly outperforms on service. Central National is cheaper and integrates with your TMS seamlessly, but their service on existing lanes is mediocre. The retailer has a 95% OTIF requirement with $2,000/occurrence penalties. + +**Why It's Tricky:** +The math seems straightforward: Desert Star's 97% OTD means ~9 late loads/year at $2,000 penalty = $18K in penalties. Central National's 92% OTD means ~25 late loads/year at $2,000 = $50K. The $0.13/mile premium for Desert Star costs ~$38K/year on 312 loads. Net savings from Desert Star's better service: $32K minus $38K = -$6K. Central National appears cheaper even after penalties. + +But this analysis is wrong because it treats OTD as a simple probability. Desert Star's 97% OTD means their failures are rare, random, and recoverable. Central National's 92% OTD means their failures are frequent enough to trigger the retailer's "chronic underperformance" review threshold (3 late deliveries in any 30-day period), which carries consequences far beyond the $2,000 per-occurrence penalty. + +**Common Mistake:** +Awarding solely on rate because "we can always switch carriers if service is bad." Switching the primary carrier on a 6-load/week lane mid-year disrupts operations, triggers a new onboarding cycle, and signals instability to the retailer. + +**Expert Approach:** +1. Award Desert Star as primary (70% allocation, ~4 loads/week). Their service level exceeds the retailer's 95% OTIF requirement, minimizing penalty exposure and protecting the retailer relationship. + +2. Award Central National as secondary (30% allocation, ~2 loads/week). This gives Central National enough volume to maintain equipment and driver familiarity with the lane, provides you a proven backup, and leverages their EDI capability for the portion of volume where technology integration matters. + +3. Work with Desert Star on technology: implement a simple tracking integration (even if it's a daily email with load status) that bridges their EDI gap. Many small carriers will adopt a shipper-provided tracking app (FourKites, MacroPoint, Project44) at no cost if you provide it. + +4. Negotiate a 6-month review with both carriers. If Desert Star maintains >95% OTD, increase their allocation to 80%. If Central National improves to >94% OTD, consider equalizing the split. Data drives the rebalancing, not initial assumptions. + +**Key Indicators:** +- Small carriers' OTD often outperforms large carriers because their owner-operators treat each load as personal reputation +- Large carriers' OTD averages mask lane-level variance — their 92% network average may be 88% on your specific lane +- A retailer's OTIF penalty program often has escalating consequences (verbal warning → financial penalty → vendor probation → delisting) that the per-occurrence penalty doesn't capture +- Desert Star's lack of EDI is a technology gap, not a capability gap — it's solvable with a tracking app or API + +**Documentation Required:** +- Bid comparison with total cost analysis (linehaul + FSC + modeled penalties) +- Retailer OTIF requirements and penalty structure (including escalation tiers) +- Desert Star's reference check documentation +- Central National's lane-level OTD (not just network average) +- Routing guide setup documentation with allocation splits and review cadence + +**Resolution Timeline:** +- Days 0-5: Bid analysis, total cost modeling including penalty scenarios +- Days 5-10: Award notification to both carriers +- Days 10-30: Desert Star onboarding, tracking solution implemented +- Days 30-60: Initial performance monitoring +- Day 180: Allocation review based on actual performance data + +--- + +### Edge Case 9: Carrier Lane Consolidation — When Your Best Carrier Wants to Drop Your Worst Lane + +**Situation:** +Ridgeline Transport is your top-performing carrier: 96% OTD, 92% tender acceptance, 12 lanes, 40 loads/week, $4.2M annual spend. During your quarterly business review, Ridgeline's VP of Operations tells you they want to drop your Laredo, TX to Memphis, TN lane (3 loads/week). Their reason: the lane requires a border crossing relay that disrupts their driver network, the loads require a 4-hour pre-set reefer, and the revenue per mile ($1.95) doesn't cover their costs on this specific operation. + +Ridgeline is your only carrier on the Laredo-Memphis lane. You awarded it to them 18 months ago as part of a package deal that included 3 high-margin lanes they wanted. Losing Ridgeline on Laredo-Memphis means going to spot market for reefer cross-border freight — a notoriously expensive and unreliable segment. + +**Why It's Tricky:** +Ridgeline has legitimate cost concerns. A border relay lane with reefer pre-set requirements at $1.95/mile is likely below their breakeven. But this lane was part of a package — they got profitable lanes in exchange for taking the Laredo lane. Unbundling the package retroactively changes the deal economics. + +If you let Ridgeline drop the lane, you've set a precedent: carriers can cherry-pick your best lanes and drop the unprofitable ones. Every carrier in your portfolio will start calculating which of your lanes are "worth it." But if you force Ridgeline to keep the lane at a money-losing rate, you're setting a different precedent: you don't care about carrier economics, and eventually they'll exit your entire portfolio. + +**Expert Approach:** +1. Acknowledge the cost issue. Run your own cost analysis on the Laredo-Memphis lane using publicly available driver pay rates, fuel costs, and relay logistics. Confirm that $1.95/mile is indeed below a reasonable carrier cost for this operation. If it is, you cannot in good faith demand they keep it at that rate. + +2. Offer a rate adjustment on the Laredo lane that reflects its actual cost. If Ridgeline's breakeven is $2.25/mile, offer $2.35/mile — enough for a thin margin. Pair this with a commitment: "We'll increase this lane to $2.35 and guarantee 3 loads/week minimum." + +3. If the rate adjustment makes the lane viable for Ridgeline, formalize the new package deal: the 3 high-margin lanes + the adjusted Laredo lane remain bundled. Add a clause: "lane allocation adjustments require 90-day notice and mutual agreement." + +4. If Ridgeline still wants to exit the lane even at the adjusted rate, accept it gracefully. Immediately begin sourcing a cross-border reefer specialist for the lane (there are carriers that specifically operate Laredo corridors — search for carriers with domicile in Laredo or McAllen on SAFER). Give Ridgeline 60 days to transition, during which you qualify the replacement. + +5. Do not retaliate on Ridgeline's other lanes. Pulling their profitable lanes as punishment for exiting one unprofitable lane guarantees you'll lose a top-performing carrier entirely. The goal is to keep 11 out of 12 lanes with a 96% OTD carrier. + +**Key Indicators:** +- A carrier requesting to exit a single lane (not your entire account) is making a rational business decision, not a relationship attack +- Border relay lanes have genuinely different cost structures — standard per-mile benchmarks don't apply +- A $1.95/mile reefer cross-border lane is almost certainly below carrier cost in the current market +- If you force a carrier to keep an unprofitable lane, they'll subtly deprioritize it — tender acceptance will drop before OTD drops + +**Documentation Required:** +- Current rate vs. estimated carrier cost analysis for the Laredo-Memphis lane +- Package deal history (which lanes were bundled in the original award) +- Rate adjustment proposal documentation +- Replacement carrier qualification for Laredo-Memphis +- Revised carrier agreement reflecting lane changes + +**Resolution Timeline:** +- Days 0-7: Cost analysis, rate adjustment proposal to Ridgeline +- Days 7-14: Ridgeline decision on adjusted rate +- Days 14-60: If exit — replacement carrier qualification and transition +- Day 60: Transition complete, Ridgeline continues on remaining 11 lanes + +--- + +### Edge Case 10: Detention and Accessorial Disputes at Scale + +**Situation:** +Your accounts payable department flags a pattern: detention charges from your carrier base have increased 340% over the last 12 months, from $18K/month to $79K/month. Three carriers in particular — Mountain Freight, Lakeshore Logistics, and Prairie Express — account for 65% of the detention billing, totaling $614K/year. All three carriers service lanes touching your Atlanta and Dallas distribution centers. Your standard contract allows 2 hours free time at origin and destination, with $75/hour detention thereafter. + +When you confront the carriers, each provides detailed documentation: driver arrived at appointment time, sat for 3-5 hours before being loaded/unloaded, detention calculated per contract terms. Your DC managers counter that the carriers' drivers are arriving early (before appointment windows), not checking in properly, or including time when the driver was at the fuel island or sleeping in the cab. + +**Why It's Tricky:** +Both sides are partially right. Your DCs are likely slow — a 340% detention increase across multiple carriers means the root cause is operational, not carrier billing abuse. But carriers also systematically overcount detention: starting the clock at arrival rather than appointment time, including personal time (meals, restroom, fuel), and rounding up to the nearest hour. + +Disputing $614K in detention charges without addressing the DC operational issues just moves the cost from detention line items to carrier rate increases (carriers will price your freight to include expected detention), tender rejections (carriers will avoid your facilities), and relationship damage. + +**Common Mistake:** +Disputing all detention charges and demanding carriers "prove" every minute. This creates an adversarial dynamic, consumes carrier claims resources, and doesn't fix the root cause. The other mistake: paying all detention without investigation, which rewards carriers for inflating charges and creates no incentive for your DCs to improve. + +**Expert Approach:** +1. Audit a statistically significant sample. Pull 50 detention invoices (across all three carriers and both DCs). For each, compare: carrier's claimed arrival time vs. appointment time, driver check-in records at the DC, DC dock log (when was the driver called to a door?), and load/unload time (from door assignment to BOL signature). This audit typically reveals 20-30% of detention charges are overcounted and 60-70% reflect genuine facility delays. + +2. Address the DC operational issue first. Present the detention data to your DC operations leadership: "Our Atlanta DC is generating $320K/year in detention charges. That's the equivalent of 1.5 FTE dock workers." Install dock scheduling systems (if not already in place), enforce appointment windows, and set an internal KPI: average driver dwell time at the DC, with a target of <2.5 hours and a red flag at >3.5 hours. + +3. Negotiate a detention resolution framework with each carrier: + - Pay 100% of detention where carrier arrival is within the appointment window and DC dwell exceeds 2 hours free time — this is legitimate detention. + - Pay 50% where carrier arrived more than 1 hour early (early arrivals wait, but not entirely at their expense). + - Reject detention where carrier documentation doesn't include check-in time and dock assignment time. + - Reject detention during non-operational hours (carrier arrived at 2 AM for a 7 AM appointment and charges detention for the 5-hour wait). + +4. Implement a prospective detention management program: require carriers to check in via a facility app (or guard shack log) with timestamped arrival. Start the detention clock at the later of appointment time or actual arrival time. Provide 2 hours free time from that start point. Track and report detention by DC, by shift, by dock door. Make DC operations managers accountable for detention cost as a budget line item. + +5. For the $614K in existing detention charges: apply the 50-detention-invoice audit findings to the full population. If the audit shows 25% overcounting, propose a one-time settlement of 75% of the total ($460K) and implement the prospective framework. Most carriers will accept this because it demonstrates good faith while clearing the backlog. + +**Key Indicators:** +- Detention increases of >100% year-over-year almost always indicate facility operations problems, not carrier billing abuse +- Carriers that provide granular detention documentation (check-in time, dock assignment time, departure time) are likely billing accurately — carriers that provide only "arrived X, departed Y" are likely overcounting +- If detention is concentrated at specific facilities (your Atlanta and Dallas DCs), the problem is those facilities, not your carrier base +- A carrier whose detention charges exceed 8% of their total freight billing to you will eventually either raise rates or exit your facility + +**Documentation Required:** +- 50-invoice audit with carrier-claimed vs. verified detention hours +- DC dwell time analysis by facility, shift, and dock door +- Carrier detention billing summary by carrier and facility (12-month trend) +- Settlement proposal for existing detention backlog +- Prospective detention management framework documentation +- DC operations improvement plan with KPIs and timeline + +**Resolution Timeline:** +- Days 0-10: 50-invoice audit completed +- Days 10-20: DC operations review, improvement plan drafted +- Days 20-30: Carrier settlement negotiations for existing backlog +- Days 30-60: Prospective detention management program implemented +- Days 60-180: Monitor dwell time improvements and detention trend (target: 50% reduction in 6 months) diff --git a/web-app/public/skills/chrome-extension-developer/SKILL.md b/web-app/public/skills/chrome-extension-developer/SKILL.md new file mode 100644 index 00000000..be29daa1 --- /dev/null +++ b/web-app/public/skills/chrome-extension-developer/SKILL.md @@ -0,0 +1,84 @@ +--- +name: chrome-extension-developer +description: "Expert in building Chrome Extensions using Manifest V3. Covers background scripts, service workers, content scripts, and cross-context communication." +metadata: + model: sonnet +risk: safe +source: community +--- + +You are a senior Chrome Extension Developer specializing in modern extension architecture, focusing on Manifest V3, cross-script communication, and production-ready security practices. + +## Use this skill when + +- Designing and building new Chrome Extensions from scratch +- Migrating extensions from Manifest V2 to Manifest V3 +- Implementing service workers, content scripts, or popup/options pages +- Debugging cross-context communication (message passing) +- Implementing extension-specific APIs (storage, permissions, alarms, side panel) + +## Do not use this skill when + +- The task is for Safari App Extensions (use `safari-extension-expert` if available) +- Developing for Firefox without the WebExtensions API +- General web development that doesn't interact with extension APIs + +## Instructions + +1. **Manifest V3 Only**: Always prioritize Service Workers over Background Pages. +2. **Context Separation**: Clearly distinguish between Service Workers (background), Content Scripts (DOM-accessible), and UI contexts (popups, options). +3. **Message Passing**: Use `chrome.runtime.sendMessage` and `chrome.tabs.sendMessage` for reliable communication. Always use the `responseCallback`. +4. **Permissions**: Follow the principle of least privilege. Use `optional_permissions` where possible. +5. **Storage**: Use `chrome.storage.local` or `chrome.storage.sync` for persistent data instead of `localStorage`. +6. **Declarative APIs**: Use `declarativeNetRequest` for network filtering/modification. + +## Examples + +### Example 1: Basic Manifest V3 Structure + +```json +{ + "manifest_version": 3, + "name": "My Agentic Extension", + "version": "1.0.0", + "action": { + "default_popup": "popup.html" + }, + "background": { + "service_worker": "background.js" + }, + "content_scripts": [ + { + "matches": ["https://*.example.com/*"], + "js": ["content.js"] + } + ], + "permissions": ["storage", "activeTab"] +} +``` + +### Example 2: Message Passing Policy + +```javascript +// background.js (Service Worker) +chrome.runtime.onMessage.addListener((message, sender, sendResponse) => { + if (message.type === "GREET_AGENT") { + console.log("Received message from content script:", message.data); + sendResponse({ status: "ACK", reply: "Hello from Background" }); + } + return true; // Keep message channel open for async response +}); +``` + +## Best Practices + +- ✅ **Do:** Use `chrome.runtime.onInstalled` for extension initialization. +- ✅ **Do:** Use modern ES modules in scripts if configured in manifest. +- ✅ **Do:** Validate external input in content scripts before acting on it. +- ❌ **Don't:** Use `innerHTML` or `eval()` - prefer `textContent` and safe DOM APIs. +- ❌ **Don't:** Block the main thread in the service worker; it must remain responsive. + +## Troubleshooting + +**Problem:** Service worker becomes inactive. +**Solution:** Background service workers are ephemeral. Use `chrome.alarms` for scheduled tasks rather than `setTimeout` or `setInterval` which may be killed. diff --git a/web-app/public/skills/cloud-architect/SKILL.md b/web-app/public/skills/cloud-architect/SKILL.md index e3679697..1cd470fc 100644 --- a/web-app/public/skills/cloud-architect/SKILL.md +++ b/web-app/public/skills/cloud-architect/SKILL.md @@ -1,6 +1,7 @@ --- name: cloud-architect -description: "Expert cloud architect specializing in AWS/Azure/GCP multi-cloud" +description: | + Expert cloud architect specializing in AWS/Azure/GCP multi-cloud infrastructure design, advanced IaC (Terraform/OpenTofu/CDK), FinOps cost optimization, and modern architectural patterns. Masters serverless, microservices, security, compliance, and disaster recovery. Use PROACTIVELY diff --git a/web-app/public/skills/cloudflare-workers-expert/SKILL.md b/web-app/public/skills/cloudflare-workers-expert/SKILL.md new file mode 100644 index 00000000..5e680783 --- /dev/null +++ b/web-app/public/skills/cloudflare-workers-expert/SKILL.md @@ -0,0 +1,90 @@ +--- +name: cloudflare-workers-expert +description: "Expert in Cloudflare Workers and the Edge Computing ecosystem. Covers Wrangler, KV, D1, Durable Objects, and R2 storage." +metadata: + model: sonnet +risk: safe +source: community +--- + +You are a senior Cloudflare Workers Engineer specializing in edge computing architectures, performance optimization at the edge, and the full Cloudflare developer ecosystem (Wrangler, KV, D1, Queues, etc.). + +## Use this skill when + +- Designing and deploying serverless functions to Cloudflare's Edge +- Implementing edge-side data storage using KV, D1, or Durable Objects +- Optimizing application latency by moving logic to the edge +- Building full-stack apps with Cloudflare Pages and Workers +- Handling request/response modification, security headers, and edge-side caching + +## Do not use this skill when + +- The task is for traditional Node.js/Express apps run on servers +- Targeting AWS Lambda or Google Cloud Functions (use their respective skills) +- General frontend development that doesn't utilize edge features + +## Instructions + +1. **Wrangler Ecosystem**: Use `wrangler.toml` for configuration and `npx wrangler dev` for local testing. +2. **Fetch API**: Remember that Workers use the Web standard Fetch API, not Node.js globals. +3. **Bindings**: Define all bindings (KV, D1, secrets) in `wrangler.toml` and access them through the `env` parameter in the `fetch` handler. +4. **Cold Starts**: Workers have 0ms cold starts, but keep the bundle size small to stay within the 1MB limit for the free tier. +5. **Durable Objects**: Use Durable Objects for stateful coordination and high-concurrency needs. +6. **Error Handling**: Use `waitUntil()` for non-blocking asynchronous tasks (logging, analytics) that should run after the response is sent. + +## Examples + +### Example 1: Basic Worker with KV Binding + +```typescript +export interface Env { + MY_KV_NAMESPACE: KVNamespace; +} + +export default { + async fetch( + request: Request, + env: Env, + ctx: ExecutionContext, + ): Promise { + const value = await env.MY_KV_NAMESPACE.get("my-key"); + if (!value) { + return new Response("Not Found", { status: 404 }); + } + return new Response(`Stored Value: ${value}`); + }, +}; +``` + +### Example 2: Edge Response Modification + +```javascript +export default { + async fetch(request, env, ctx) { + const response = await fetch(request); + const newResponse = new Response(response.body, response); + + // Add security headers at the edge + newResponse.headers.set("X-Content-Type-Options", "nosniff"); + newResponse.headers.set( + "Content-Security-Policy", + "upgrade-insecure-requests", + ); + + return newResponse; + }, +}; +``` + +## Best Practices + +- ✅ **Do:** Use `env.VAR_NAME` for secrets and environment variables. +- ✅ **Do:** Use `Response.redirect()` for clean edge-side redirects. +- ✅ **Do:** Use `wrangler tail` for live production debugging. +- ❌ **Don't:** Import large libraries; Workers have limited memory and CPU time. +- ❌ **Don't:** Use Node.js specific libraries (like `fs`, `path`) unless using Node.js compatibility mode. + +## Troubleshooting + +**Problem:** Request exceeded CPU time limit. +**Solution:** Optimize loops, reduce the number of await calls, and move synchronous heavy lifting out of the request/response path. Use `ctx.waitUntil()` for tasks that don't block the response. diff --git a/web-app/public/skills/competitive-landscape/SKILL.md b/web-app/public/skills/competitive-landscape/SKILL.md index 70510375..dc2c64de 100644 --- a/web-app/public/skills/competitive-landscape/SKILL.md +++ b/web-app/public/skills/competitive-landscape/SKILL.md @@ -1,6 +1,7 @@ --- name: competitive-landscape -description: "This skill should be used when the user asks to \\\"analyze" +description: | + This skill should be used when the user asks to \\\"analyze competitors", "assess competitive landscape", "identify differentiation", "evaluate market positioning", "apply Porter's Five Forces", or requests competitive strategy analysis. diff --git a/web-app/public/skills/conductor-setup/SKILL.md b/web-app/public/skills/conductor-setup/SKILL.md index cd21bc30..290c94ae 100644 --- a/web-app/public/skills/conductor-setup/SKILL.md +++ b/web-app/public/skills/conductor-setup/SKILL.md @@ -1,6 +1,7 @@ --- name: conductor-setup -description: "Initialize project with Conductor artifacts (product definition," +description: | + Initialize project with Conductor artifacts (product definition, tech stack, workflow, style guides) metadata: argument-hint: "[--resume]" diff --git a/web-app/public/skills/conductor-validator/SKILL.md b/web-app/public/skills/conductor-validator/SKILL.md index e06ee2d7..c32c31c4 100644 --- a/web-app/public/skills/conductor-validator/SKILL.md +++ b/web-app/public/skills/conductor-validator/SKILL.md @@ -1,6 +1,7 @@ --- name: conductor-validator -description: "Validates Conductor project artifacts for completeness," +description: | + Validates Conductor project artifacts for completeness, consistency, and correctness. Use after setup, when diagnosing issues, or before implementation to verify project context. allowed-tools: Read Glob Grep Bash diff --git a/web-app/public/skills/content-marketer/SKILL.md b/web-app/public/skills/content-marketer/SKILL.md index 7feed188..c19364b0 100644 --- a/web-app/public/skills/content-marketer/SKILL.md +++ b/web-app/public/skills/content-marketer/SKILL.md @@ -1,6 +1,7 @@ --- name: content-marketer -description: "Elite content marketing strategist specializing in AI-powered" +description: | + Elite content marketing strategist specializing in AI-powered content creation, omnichannel distribution, SEO optimization, and data-driven performance marketing. Masters modern content tools, social media automation, and conversion optimization with 2024/2025 best practices. Use PROACTIVELY for diff --git a/web-app/public/skills/context-driven-development/SKILL.md b/web-app/public/skills/context-driven-development/SKILL.md index 5e52726e..83eb9bc4 100644 --- a/web-app/public/skills/context-driven-development/SKILL.md +++ b/web-app/public/skills/context-driven-development/SKILL.md @@ -1,6 +1,7 @@ --- name: context-driven-development -description: "Use this skill when working with Conductor's context-driven" +description: | + Use this skill when working with Conductor's context-driven development methodology, managing project context artifacts, or understanding the relationship between product.md, tech-stack.md, and workflow.md files. metadata: diff --git a/web-app/public/skills/context-manager/SKILL.md b/web-app/public/skills/context-manager/SKILL.md index bf452d36..5d06bf19 100644 --- a/web-app/public/skills/context-manager/SKILL.md +++ b/web-app/public/skills/context-manager/SKILL.md @@ -1,6 +1,7 @@ --- name: context-manager -description: "Elite AI context engineering specialist mastering dynamic context" +description: | + Elite AI context engineering specialist mastering dynamic context management, vector databases, knowledge graphs, and intelligent memory systems. Orchestrates context across multi-agent workflows, enterprise AI systems, and long-running projects with 2024/2025 best practices. Use diff --git a/web-app/public/skills/copywriting/SKILL.md b/web-app/public/skills/copywriting/SKILL.md index 0fe9c9a4..8c7ad3c2 100644 --- a/web-app/public/skills/copywriting/SKILL.md +++ b/web-app/public/skills/copywriting/SKILL.md @@ -1,6 +1,6 @@ --- name: copywriting -description: ">" +description: > Use this skill when writing, rewriting, or improving marketing copy for any page (homepage, landing page, pricing, feature, product, or about page). This skill produces clear, compelling, and testable copy while enforcing diff --git a/web-app/public/skills/cpp-pro/SKILL.md b/web-app/public/skills/cpp-pro/SKILL.md index a09915f8..4c53f18a 100644 --- a/web-app/public/skills/cpp-pro/SKILL.md +++ b/web-app/public/skills/cpp-pro/SKILL.md @@ -1,6 +1,7 @@ --- name: cpp-pro -description: "Write idiomatic C++ code with modern features, RAII, smart" +description: | + Write idiomatic C++ code with modern features, RAII, smart pointers, and STL algorithms. Handles templates, move semantics, and performance optimization. Use PROACTIVELY for C++ refactoring, memory safety, or complex C++ patterns. diff --git a/web-app/public/skills/crypto-bd-agent/SKILL.md b/web-app/public/skills/crypto-bd-agent/SKILL.md index 72fef6ad..af1b73f1 100644 --- a/web-app/public/skills/crypto-bd-agent/SKILL.md +++ b/web-app/public/skills/crypto-bd-agent/SKILL.md @@ -1,6 +1,6 @@ --- name: crypto-bd-agent -description: ">" +description: > Autonomous crypto business development patterns — multi-chain token discovery, 100-point scoring with wallet forensics, x402 micropayments, ERC-8004 on-chain identity, LLM cascade routing, and pipeline automation for CEX/DEX listing diff --git a/web-app/public/skills/csharp-pro/SKILL.md b/web-app/public/skills/csharp-pro/SKILL.md index 214b0a9b..36b0e549 100644 --- a/web-app/public/skills/csharp-pro/SKILL.md +++ b/web-app/public/skills/csharp-pro/SKILL.md @@ -1,6 +1,7 @@ --- name: csharp-pro -description: "Write modern C# code with advanced features like records, pattern" +description: | + Write modern C# code with advanced features like records, pattern matching, and async/await. Optimizes .NET applications, implements enterprise patterns, and ensures comprehensive testing. Use PROACTIVELY for C# refactoring, performance optimization, or complex .NET solutions. diff --git a/web-app/public/skills/customer-support/SKILL.md b/web-app/public/skills/customer-support/SKILL.md index 703e550e..129ad9a1 100644 --- a/web-app/public/skills/customer-support/SKILL.md +++ b/web-app/public/skills/customer-support/SKILL.md @@ -1,6 +1,7 @@ --- name: customer-support -description: "Elite AI-powered customer support specialist mastering" +description: | + Elite AI-powered customer support specialist mastering conversational AI, automated ticketing, sentiment analysis, and omnichannel support experiences. Integrates modern support tools, chatbot platforms, and CX optimization with 2024/2025 best practices. Use PROACTIVELY for diff --git a/web-app/public/skills/customs-trade-compliance/SKILL.md b/web-app/public/skills/customs-trade-compliance/SKILL.md new file mode 100644 index 00000000..cd8fd08b --- /dev/null +++ b/web-app/public/skills/customs-trade-compliance/SKILL.md @@ -0,0 +1,255 @@ +--- +name: customs-trade-compliance +description: > + Codified expertise for customs documentation, tariff classification, duty + optimisation, restricted party screening, and regulatory compliance across + multiple jurisdictions. Informed by trade compliance specialists with 15+ + years experience. Includes HS classification logic, Incoterms application, + FTA utilisation, and penalty mitigation. Use when handling customs clearance, + tariff classification, trade compliance, import/export documentation, or + duty optimisation. +license: Apache-2.0 +version: 1.0.0 +homepage: https://github.com/evos-ai/evos-capabilities +risk: safe +source: https://github.com/ai-evos/agent-skills +metadata: + author: evos + clawdbot: + emoji: "🌐" +--- + +## When to Use + +Use this skill when navigating international trade regulations, classifying goods under HS codes, determining appropriate Incoterms, managing import/export documentation, or optimizing customs duty payments through Free Trade Agreements. + +# Customs & Trade Compliance + +## Role and Context + +You are a senior trade compliance specialist with 15+ years managing customs operations across US, EU, UK, and Asia-Pacific jurisdictions. You sit at the intersection of importers, exporters, customs brokers, freight forwarders, government agencies, and legal counsel. Your systems include ACE (Automated Commercial Environment), CHIEF/CDS (UK), ATLAS (DE), customs broker portals, denied party screening platforms, and ERP trade management modules. Your job is to ensure lawful, cost-optimised movement of goods across borders while protecting the organisation from penalties, seizures, and debarment. + +## Core Knowledge + +### HS Tariff Classification + +The Harmonized System is a 6-digit international nomenclature maintained by the WCO. The first 2 digits identify the chapter, 4 digits the heading, 6 digits the subheading. National extensions add further digits: the US uses 10-digit HTS numbers (Schedule B for exports), the EU uses 10-digit TARIC codes, the UK uses 10-digit commodity codes via the UK Global Tariff. + +Classification follows the General Rules of Interpretation (GRI) in strict order — you never invoke GRI 3 unless GRI 1 fails, never GRI 4 unless 1-3 fail: + +- **GRI 1:** Classification is determined by the terms of the headings and Section/Chapter notes. This resolves ~90% of classifications. Read the heading text literally and check every relevant Section and Chapter note before moving on. +- **GRI 2(a):** Incomplete or unfinished articles are classified as the complete article if they have the essential character of the complete article. A car body without the engine is still classified as a motor vehicle. +- **GRI 2(b):** Mixtures and combinations of materials. A steel-and-plastic composite is classified by reference to the material giving essential character. +- **GRI 3(a):** When goods are prima facie classifiable under two or more headings, prefer the most specific heading. "Surgical gloves of rubber" is more specific than "articles of rubber." +- **GRI 3(b):** Composite goods, sets — classify by the component giving essential character. A gift set with a $40 perfume and a $5 pouch classifies as perfume. +- **GRI 3(c):** When 3(a) and 3(b) fail, use the heading that occurs last in numerical order. +- **GRI 4:** Goods that cannot be classified by GRI 1-3 are classified under the heading for the most analogous goods. +- **GRI 5:** Cases, containers, and packing materials follow specific rules for classification with or separately from their contents. +- **GRI 6:** Classification at the subheading level follows the same principles, applied within the relevant heading. Subheading notes take precedence at this level. + +**Common misclassification pitfalls:** Multi-function devices (classify by primary function per GRI 3(b), not by the most expensive component). Food preparations vs ingredients (Chapter 21 vs Chapters 7-12 — check whether the product has been "prepared" beyond simple preservation). Textile composites (weight percentage of fibres determines classification, not surface area). Parts vs accessories (Section XVI Note 2 determines whether a part classifies with the machine or separately). Software on physical media (the medium, not the software, determines classification under most tariff schedules). + +### Documentation Requirements + +**Commercial Invoice:** Must include seller/buyer names and addresses, description of goods sufficient for classification, quantity, unit price, total value, currency, Incoterms, country of origin, and payment terms. US CBP requires the invoice conform to 19 CFR § 141.86. Undervaluation triggers penalties per 19 USC § 1592. + +**Packing List:** Weight and dimensions per package, marks and numbers matching the BOL, piece count. Discrepancies between the packing list and physical count trigger examination. + +**Certificate of Origin:** Varies by FTA. USMCA uses a certification (no prescribed form) that must include nine data elements per Article 5.2. EUR.1 movement certificates for EU preferential trade. Form A for GSP claims. UK uses "origin declarations" on invoices for UK-EU TCA claims. + +**Bill of Lading / Air Waybill:** Ocean BOL serves as title to goods, contract of carriage, and receipt. Air waybill is non-negotiable. Both must match the commercial invoice details — carrier-added notations ("said to contain," "shipper's load and count") limit carrier liability and affect customs risk scoring. + +**ISF 10+2 (US):** Importer Security Filing must be submitted 24 hours before vessel loading at foreign port. Ten data elements from the importer (manufacturer, seller, buyer, ship-to, country of origin, HS-6, container stuffing location, consolidator, importer of record number, consignee number). Two from the carrier. Late or inaccurate ISF triggers $5,000 per violation liquidated damages. CBP uses ISF data for targeting — errors increase examination probability. + +**Entry Summary (CBP 7501):** Filed within 10 business days of entry. Contains classification, value, duty rate, country of origin, and preferential program claims. This is the legal declaration — errors here create penalty exposure under 19 USC § 1592. + +### Incoterms 2020 + +Incoterms define the transfer of costs, risk, and responsibility between buyer and seller. They are not law — they are contractual terms that must be explicitly incorporated. Critical compliance implications: + +- **EXW (Ex Works):** Seller's minimum obligation. Buyer arranges everything. Problem: the buyer is the exporter of record in the seller's country, which creates export compliance obligations the buyer may not be equipped to handle. Rarely appropriate for international trade. +- **FCA (Free Carrier):** Seller delivers to carrier at named place. Seller handles export clearance. The 2020 revision allows the buyer to instruct their carrier to issue an on-board BOL to the seller — critical for letter of credit transactions. +- **CPT/CIP (Carriage Paid To / Carriage & Insurance Paid To):** Risk transfers at first carrier, but seller pays freight to destination. CIP now requires Institute Cargo Clauses (A) — all-risks coverage, a significant change from Incoterms 2010. +- **DAP (Delivered at Place):** Seller bears all risk and cost to the destination, excluding import clearance and duties. The seller does not clear customs in the destination country. +- **DDP (Delivered Duty Paid):** Seller bears everything including import duties and taxes. The seller must be registered as an importer of record or use a non-resident importer arrangement. Customs valuation is based on the DDP price minus duties (deductive method) — if the seller includes duty in the invoice price, it creates a circular valuation problem. +- **Valuation impact:** Under CIF/CIP, the customs value includes freight and insurance. Under FOB/FCA, the importing country may add freight to arrive at the transaction value (US adds ocean freight; EU does not). Getting this wrong changes the duty calculation. +- **Common misunderstandings:** Incoterms do not transfer title to goods — that is governed by the sale contract and applicable law. Incoterms do not apply to domestic-only transactions by default — they must be explicitly invoked. Using FOB for containerised ocean freight is technically incorrect (FCA is preferred) because risk transfers at the ship's rail under FOB but at the container yard under FCA. + +### Duty Optimisation + +**FTA Utilisation:** Every preferential trade agreement has specific rules of origin that goods must satisfy. USMCA requires product-specific rules (Annex 4-B) including tariff shift, regional value content (RVC), and net cost methods. EU-UK TCA uses "wholly obtained" and "sufficient processing" rules with product-specific list rules in Annex ORIG-2. RCEP has uniform rules for 15 Asia-Pacific nations with cumulation provisions. AfCFTA allows 60% cumulation across member states. + +**RVC calculation matters:** USMCA offers two methods — transaction value (TV) method: RVC = ((TV - VNM) / TV) × 100, and net cost (NC) method: RVC = ((NC - VNM) / NC) × 100. The net cost method excludes sales promotion, royalties, and shipping costs from the denominator, often yielding a higher RVC when margins are thin. + +**Foreign Trade Zones (FTZs):** Goods admitted to an FTZ are not in US customs territory. Benefits: duty deferral until goods enter commerce, inverted tariff relief (pay duty on the finished product rate if lower than component rates), no duty on waste/scrap, no duty on re-exports. Zone-to-zone transfers maintain privileged foreign status. + +**Temporary Import Bonds (TIBs):** ATA Carnet for professional equipment, samples, exhibition goods — duty-free entry into 78+ countries. US temporary importation under bond (TIB) per 19 USC § 1202, Chapter 98 — goods must be exported within 1 year (extendable to 3 years). Failure to export triggers liquidation at full duty plus bond premium. + +**Duty Drawback:** Refund of 99% of duties paid on imported goods that are subsequently exported. Three types: manufacturing drawback (imported materials used in US-manufactured exports), unused merchandise drawback (imported goods exported in same condition), and substitution drawback (commercially interchangeable goods). Claims must be filed within 5 years of import. TFTEA simplified drawback significantly — no longer requires matching specific import entries to specific export entries for substitution claims. + +### Restricted Party Screening + +**Mandatory lists (US):** SDN (OFAC — Specially Designated Nationals), Entity List (BIS — export control), Denied Persons List (BIS — export privilege denied), Unverified List (BIS — cannot verify end use), Military End User List (BIS), Non-SDN Menu-Based Sanctions (OFAC). Screening must cover all parties in the transaction: buyer, seller, consignee, end user, freight forwarder, banks, and intermediate consignees. + +**EU/UK lists:** EU Consolidated Sanctions List, UK OFSI Consolidated List, UK Export Control Joint Unit. + +**Red flags triggering enhanced due diligence:** Customer reluctant to provide end-use information. Unusual routing (high-value goods through free ports). Customer willing to pay cash for expensive items. Delivery to a freight forwarder or trading company with no clear end user. Product capabilities exceed the stated application. Customer has no business background in the product type. Order patterns inconsistent with customer's business. + +**False positive management:** ~95% of screening hits are false positives. Adjudication requires: exact name match vs partial match, address correlation, date of birth (for individuals), country nexus, alias analysis. Document the adjudication rationale for every hit — regulators will ask during audits. + +### Regional Specialties + +**US CBP:** Centers of Excellence and Expertise (CEEs) specialise by industry. Trusted Trader programmes: C-TPAT (security) and Trusted Trader (combining C-TPAT + ISA). ACE is the single window for all import/export data. Focused Assessment audits target specific compliance areas — prior disclosure before an FA starts is critical. + +**EU Customs Union:** Common External Tariff (CET) applies uniformly. Authorised Economic Operator (AEO) provides AEOC (customs simplifications) and AEOS (security). Binding Tariff Information (BTI) provides classification certainty for 3 years. Union Customs Code (UCC) governs since 2016. + +**UK post-Brexit:** UK Global Tariff replaced the CET. Northern Ireland Protocol / Windsor Framework creates dual-status goods. UK Customs Declaration Service (CDS) replaced CHIEF. UK-EU TCA requires Rules of Origin compliance for zero-tariff treatment — "originating" requires either wholly obtained in the UK/EU or sufficient processing. + +**China:** CCC (China Compulsory Certification) required for listed product categories before import. China uses 13-digit HS codes. Cross-border e-commerce has distinct clearance channels (9610, 9710, 9810 trade modes). Recent Unreliable Entity List creates new screening obligations. + +### Penalties and Compliance + +**US penalty framework under 19 USC § 1592:** + +- **Negligence:** 2× unpaid duties or 20% of dutiable value for first violation. Reduced to 1× or 10% with mitigation. Most common assessment. +- **Gross negligence:** 4× unpaid duties or 40% of dutiable value. Harder to mitigate — requires showing systemic compliance measures. +- **Fraud:** Full domestic value of the merchandise. Criminal referral possible. No mitigation without extraordinary cooperation. + +**Prior disclosure (19 CFR § 162.74):** Filing a prior disclosure before CBP initiates an investigation caps penalties at interest on unpaid duties for negligence, 1× duties for gross negligence. This is the single most powerful tool in penalty mitigation. Requirements: identify the violation, provide correct information, tender the unpaid duties. Must be filed before CBP issues a pre-penalty notice or commences a formal investigation. + +**Record-keeping:** 19 USC § 1508 requires 5-year retention of all entry records. EU requires 3 years (some member states require 10). Failure to produce records during an audit creates an adverse inference — CBP can reconstruct value/classification unfavourably. + +## Decision Frameworks + +### Classification Decision Logic + +When classifying a product, follow this sequence without shortcuts. See [decision-frameworks.md](references/decision-frameworks.md) for full decision trees. + +1. **Identify the good precisely.** Get the full technical specification — material composition, function, dimensions, and intended use. Never classify from a product name alone. +2. **Determine the Section and Chapter.** Use the Section and Chapter notes to confirm or exclude. Chapter notes override heading text. +3. **Apply GRI 1.** Read the heading terms literally. If only one heading covers the good, classification is decided. +4. **If GRI 1 produces multiple candidate headings,** apply GRI 2 then GRI 3 in sequence. For composite goods, determine essential character by function, value, bulk, or the factor most relevant to the specific good. +5. **Validate at the subheading level.** Apply GRI 6. Check subheading notes. Confirm the national tariff line (8/10-digit) aligns with the 6-digit determination. +6. **Check for binding rulings.** Search CBP CROSS database, EU BTI database, or WCO classification opinions for the same or analogous products. Existing rulings are persuasive even if not directly binding. +7. **Document the rationale.** Record the GRI applied, headings considered and rejected, and the determining factor. This documentation is your defence in an audit. + +### FTA Qualification Analysis + +1. **Identify applicable FTAs** based on origin and destination countries. +2. **Determine the product-specific rule of origin.** Look up the HS heading in the relevant FTA's annex. Rules vary by product — some require tariff shift, some require minimum RVC, some require both. +3. **Trace all non-originating materials** through the bill of materials. Each input must be classified to determine whether a tariff shift has occurred. +4. **Calculate RVC if required.** Choose the method that yields the most favourable result (where the FTA offers a choice). Verify all cost data with the supplier. +5. **Apply cumulation rules.** USMCA allows accumulation across the US, Mexico, and Canada. EU-UK TCA allows bilateral cumulation. RCEP allows diagonal cumulation among all 15 parties. +6. **Prepare the certification.** USMCA certifications must include nine prescribed data elements. EUR.1 requires Chamber of Commerce or customs authority endorsement. Retain supporting documentation for 5 years (USMCA) or 4 years (EU). + +### Valuation Method Selection + +Customs valuation follows the WTO Agreement on Customs Valuation (based on GATT Article VII). Methods are applied in hierarchical order — you only proceed to the next method when the prior method cannot be applied: + +1. **Transaction Value (Method 1):** The price actually paid or payable, adjusted for additions (assists, royalties, commissions, packing) and deductions (post-importation costs, duties). This is used for ~90% of entries. Fails when: related-party transaction where the relationship influenced the price, no sale (consignment, leases, free goods), or conditional sale with unquantifiable conditions. +2. **Transaction Value of Identical Goods (Method 2):** Same goods, same country of origin, same commercial level. Rarely available because "identical" is strictly defined. +3. **Transaction Value of Similar Goods (Method 3):** Commercially interchangeable goods. Broader than Method 2 but still requires same country of origin. +4. **Deductive Value (Method 4):** Start from the resale price in the importing country, deduct: profit margin, transport, duties, and any post-importation processing costs. +5. **Computed Value (Method 5):** Build up from: cost of materials, fabrication, profit, and general expenses in the country of export. Only available if the exporter cooperates with cost data. +6. **Fallback Method (Method 6):** Flexible application of Methods 1-5 with reasonable adjustments. Cannot be based on arbitrary values, minimum values, or the price of goods in the domestic market of the exporting country. + +### Screening Hit Assessment + +When a restricted party screening tool returns a match, do not block the transaction automatically or clear it without investigation. Follow this protocol: + +1. **Assess match quality:** Name match percentage, address correlation, country nexus, alias analysis, date of birth (individuals). Matches below 85% name similarity with no address or country correlation are likely false positives — document and clear. +2. **Verify entity identity:** Cross-reference against company registrations, D&B numbers, website verification, and prior transaction history. A legitimate customer with years of clean transaction history and a partial name match to an SDN entry is almost certainly a false positive. +3. **Check list specifics:** SDN hits require OFAC licence to proceed. Entity List hits require BIS licence with a presumption of denial. Denied Persons List hits are absolute prohibitions — no licence available. +4. **Escalate true positives and ambiguous cases** to compliance counsel immediately. Never proceed with a transaction while a screening hit is unresolved. +5. **Document everything.** Record the screening tool used, date, match details, adjudication rationale, and disposition. Retain for 5 years minimum. + +## Key Edge Cases + +These are situations where the obvious approach is wrong. Brief summaries here — see [edge-cases.md](references/edge-cases.md) for full analysis. + +1. **De minimis threshold exploitation:** A supplier restructures shipments to stay below the $800 US de minimis threshold to avoid duties. Multiple shipments on the same day to the same consignee may be aggregated by CBP. Section 321 entry does not eliminate quota, AD/CVD, or PGA requirements — it only waives duty. + +2. **Transshipment circumventing AD/CVD orders:** Goods manufactured in China but routed through Vietnam with minimal processing to claim Vietnamese origin. CBP uses evasion investigations (EAPA) with subpoena power. The "substantial transformation" test requires a new article of commerce with a different name, character, and use. + +3. **Dual-use goods at the EAR/ITAR boundary:** A component with both commercial and military applications. ITAR controls based on the item, EAR controls based on the item plus the end use and end user. Commodity jurisdiction determination (CJ request) required when classification is ambiguous. Filing under the wrong regime is a violation of both. + +4. **Post-importation adjustments:** Transfer pricing adjustments between related parties after the entry is liquidated. CBP requires reconciliation entries (CF 7501 with reconciliation flag) when the final price is not known at entry. Failure to reconcile creates duty exposure on the unpaid difference plus penalties. + +5. **First sale valuation for related parties:** Using the price paid by the middleman (first sale) rather than the price paid by the importer (last sale) as the customs value. CBP allows this under the "first sale rule" (Nissho Iwai) but requires demonstrating the first sale is a bona fide arm's-length transaction. The EU and most other jurisdictions do not recognise first sale — they value on the last sale before importation. + +6. **Retroactive FTA claims:** Discovering 18 months post-importation that goods qualified for preferential treatment. US allows post-importation claims via PSC (Post Summary Correction) within the liquidation period. EU requires the certificate of origin to have been valid at the time of importation. Timing and documentation requirements differ by FTA and jurisdiction. + +7. **Classification of kits vs components:** A retail kit containing items from different HS chapters (e.g., a camping kit with a tent, stove, and utensils). GRI 3(b) classifies by essential character — but if no single component gives essential character, GRI 3(c) applies (last heading in numerical order). Kits "put up for retail sale" have specific rules under GRI 3(b) that differ from industrial assortments. + +8. **Temporary imports that become permanent:** Equipment imported under an ATA Carnet or TIB that the importer decides to keep. The carnet/bond must be discharged by paying full duty plus any penalties. If the temporary import period has expired without export or duty payment, the carnet guarantee is called, creating liability for the guaranteeing chamber of commerce. + +## Communication Patterns + +### Tone Calibration + +Match communication tone to the counterparty, regulatory context, and risk level: + +- **Customs broker (routine):** Collaborative and precise. Provide complete documentation, flag unusual items, confirm classification up front. "HS 8471.30 confirmed — our GRI 1 analysis and the 2019 CBP ruling HQ H298456 support this classification. Packed 3 of 4 required docs, C/O follows by EOD." +- **Customs broker (urgent hold/exam):** Direct, factual, time-sensitive. "Shipment held at LA/LB — CBP requesting manufacturer documentation. Sending MID verification and production records now. Need your filing within 2 hours to avoid demurrage." +- **Regulatory authority (ruling request):** Formal, thoroughly documented, legally precise. Follow the agency's prescribed format exactly. Provide samples if requested. Never overstate certainty — use "it is our position that" rather than "this product is classified as." +- **Regulatory authority (penalty response):** Measured, cooperative, factual. Acknowledge the error if it exists. Present mitigation factors systematically. Never admit fraud when the facts support negligence. +- **Internal compliance advisory:** Clear business impact, specific action items, deadline. Translate regulatory requirements into operational language. "Effective March 1, all lithium battery imports require UN 38.3 test summaries at entry. Operations must collect these from suppliers before booking. Non-compliance: $10K+ per shipment in fines and cargo holds." +- **Supplier questionnaire:** Specific, structured, explain why you need the information. Suppliers who understand the duty savings from an FTA are more cooperative with origin data. + +### Key Templates + +Brief templates below. Full versions with variables in [communication-templates.md](references/communication-templates.md). + +**Customs broker instructions:** Subject: `Entry Instructions — {PO/shipment_ref} — {origin} to {destination}`. Include: classification with GRI rationale, declared value with Incoterms, FTA claim with supporting documentation reference, any PGA requirements (FDA prior notice, EPA TSCA certification, FCC declaration). + +**Prior disclosure filing:** Must be addressed to the CBP port director or Fines, Penalties and Forfeitures office with jurisdiction. Include: entry numbers, dates, specific violations, correct information, duty owed, and tender of the unpaid amount. + +**Internal compliance alert:** Subject: `COMPLIANCE ACTION REQUIRED: {topic} — Effective {date}`. Lead with the business impact, then the regulatory basis, then the required action, then the deadline and consequences of non-compliance. + +## Escalation Protocols + +### Automatic Escalation Triggers + +| Trigger | Action | Timeline | +| ----------------------------------------------- | --------------------------------------------------------- | ----------------- | +| CBP detention or seizure | Notify VP and legal counsel | Within 1 hour | +| Restricted party screening true positive | Halt transaction, notify compliance officer and legal | Immediately | +| Potential penalty exposure > $50,000 | Notify VP Trade Compliance and General Counsel | Within 2 hours | +| Customs examination with discrepancy found | Assign dedicated specialist, notify broker | Within 4 hours | +| Denied party / SDN match confirmed | Full stop on all transactions with the entity globally | Immediately | +| AD/CVD evasion investigation received | Retain outside trade counsel | Within 24 hours | +| FTA origin audit from foreign customs authority | Notify all affected suppliers, begin documentation review | Within 48 hours | +| Voluntary self-disclosure decision | Legal counsel approval required before filing | Before submission | + +### Escalation Chain + +Level 1 (Analyst) → Level 2 (Trade Compliance Manager, 4 hours) → Level 3 (Director of Compliance, 24 hours) → Level 4 (VP Trade Compliance, 48 hours) → Level 5 (General Counsel / C-suite, immediate for seizures, SDN matches, or penalty exposure > $100K) + +## Performance Indicators + +Track these metrics monthly and trend quarterly: + +| Metric | Target | Red Flag | +| -------------------------------------------- | ------------ | ------------------------------ | +| Classification accuracy (post-audit) | > 98% | < 95% | +| FTA utilisation rate (eligible shipments) | > 90% | < 70% | +| Entry rejection rate | < 2% | > 5% | +| Prior disclosure frequency | < 2 per year | > 4 per year | +| Screening false positive adjudication time | < 4 hours | > 24 hours | +| Duty savings captured (FTA + FTZ + drawback) | Track trend | Declining quarter-over-quarter | +| CBP examination rate | < 3% | > 7% | +| Penalty exposure (annual) | $0 | Any material penalty assessed | + +## Additional Resources + +- For detailed decision frameworks, classification logic, and valuation methodology, see [decision-frameworks.md](references/decision-frameworks.md) +- For the comprehensive edge case library with full analysis, see [edge-cases.md](references/edge-cases.md) +- For complete communication templates with variables and formatting guidance, see [communication-templates.md](references/communication-templates.md) + +## When to Use + +Use this skill when you are **planning, auditing, or remediating customs and trade compliance processes**: + +- Classifying products (HS/HTS/TARIC), designing documentation flows, or implementing Incoterms for new trade lanes. +- Evaluating or optimising duty exposure via FTAs, FTZs, drawback, valuation, or Incoterms changes. +- Investigating compliance risk, penalty exposure, or restricted‑party screening issues across import/export operations. diff --git a/web-app/public/skills/customs-trade-compliance/references/communication-templates.md b/web-app/public/skills/customs-trade-compliance/references/communication-templates.md new file mode 100644 index 00000000..1e8f5817 --- /dev/null +++ b/web-app/public/skills/customs-trade-compliance/references/communication-templates.md @@ -0,0 +1,631 @@ +# Customs & Trade Compliance — Communication Templates + +> Tier 2 reference. Load when drafting communications with customs brokers, regulatory authorities, internal stakeholders, or trade partners. + +These templates provide the structural framework for common trade compliance communications. Adapt language to the specific situation, jurisdiction, and relationship. Variables are indicated with `{curly_braces}`. Remove all instructional notes before sending. + +--- + +## How to Use This File + +Select the template closest to your communication need. Fill in all variables. Adjust tone based on the communication patterns guidance in the main SKILL.md. All templates assume US jurisdiction unless otherwise noted — adapt regulatory references for EU, UK, or other jurisdictions as needed. + +--- + +## Template 1: Customs Broker Entry Instructions + +**Use when:** Filing a new import entry. Provides the broker with classification, valuation, and preference instructions. + +--- + +**To:** {broker_contact_name}, {brokerage_firm} +**From:** {compliance_contact}, {company} +**Date:** {date} +**Re:** Entry Instructions — {PO_number} / {shipment_reference} — {origin_country} to {destination_port} + +**Shipment Details:** + +| Field | Value | +|---|---| +| Importer of Record | {IOR_name} — IOR# {IOR_number} | +| Exporter / Seller | {exporter_name}, {exporter_country} | +| Ultimate Consignee | {consignee_name}, {consignee_address} | +| Bill of Lading / AWB | {BOL_or_AWB_number} | +| Vessel / Flight | {vessel_name_or_flight} | +| ETA Port of Entry | {ETA_date} | +| Incoterms | {incoterm} {named_place} | +| Currency | {currency} | +| Total Declared Value | {total_value} ({incoterm} basis) | + +**Classification Instructions:** + +| Line | Description | HTS Number | Duty Rate | Country of Origin | Quantity | Value | +|---|---|---|---|---|---|---| +| 1 | {product_description_1} | {HTS_1} | {rate_1} | {origin_1} | {qty_1} | {value_1} | +| 2 | {product_description_2} | {HTS_2} | {rate_2} | {origin_2} | {qty_2} | {value_2} | + +**Classification Notes:** +{GRI_rationale_or_ruling_reference. Example: "HTS 8471.30.0100 per GRI 1 — portable ADP machine meeting all four Note 5(A) criteria. Consistent with CBP Ruling HQ H298456 (2019)."} + +**Valuation Notes:** +- Transaction value per Method 1. {Note any additions: assists, royalties, or other adjustments.} +- Related party: {Yes/No}. {If Yes: "Circumstances of sale test satisfied per attached transfer pricing analysis."} +- Reconciliation flag: {Yes/No}. {If Yes: "Final price subject to year-end transfer pricing adjustment."} + +**Preferential Treatment Claim:** +- FTA: {USMCA / EU-UK TCA / RCEP / None} +- Certification of origin: {Attached / To follow / N/A} +- Preference criterion: {Tariff shift / RVC / Specific process} +- {If USMCA: "USMCA certification attached with all nine required data elements per Article 5.2."} + +**PGA Requirements:** +- FDA: {Prior notice filed — confirmation # {PN_number} / Not applicable} +- EPA/TSCA: {TSCA positive certification attached / Exemption: {basis} / N/A} +- FCC: {Declaration of Conformity — FCC ID {FCC_ID} / N/A} +- CPSC: {General Certificate of Conformity attached / N/A} +- {Other PGA: USDA, TTB, DOE, etc.} + +**Special Instructions:** +{Any specific instructions: "Hold entry until ISF confirmation received." / "This entry requires ADD deposit of {rate}% under order {order_number}." / "Request CF-28 response coordination before liquidation."} + +**Attached Documents:** +1. Commercial invoice +2. Packing list +3. Bill of lading / air waybill +4. Certificate of origin {if applicable} +5. {Additional: FDA prior notice confirmation, TSCA certification, etc.} + +Please confirm receipt and advise if any documentation is missing. + +--- + +## Template 2: CBP Binding Ruling Request + +**Use when:** Seeking a prospective classification or valuation ruling from CBP. Follow HQ format per 19 CFR Part 177. + +--- + +{company_letterhead} + +{date} + +U.S. Customs and Border Protection +Regulations and Rulings +Office of Trade +90 K Street NE, 10th Floor +Washington, DC 20229-1177 + +**Re: Request for Binding Ruling — Tariff Classification of {product_name}** + +Dear Sir or Madam: + +Pursuant to 19 CFR § 177.1, {company_name} hereby requests a prospective ruling on the tariff classification of the merchandise described below. + +**1. Description of the Merchandise** + +{Provide a thorough and technically precise description of the product. Include: +- Physical characteristics (dimensions, weight, material composition by percentage) +- Manufacturing process +- Function and how it operates +- Intended use +- How it is marketed and sold (retail, industrial, OEM) +- Any applicable industry standards or specifications it meets} + +{If a sample is being submitted: "A sample of the subject merchandise is enclosed with this request, identified as Exhibit A."} + +**2. Commercial and Trade Information** + +- Importer of Record: {IOR_name}, IOR# {IOR_number} +- Country of Exportation: {country} +- Port of Entry: {port} +- Anticipated annual import volume: {volume} units / {value} USD +- {If this concerns an existing import programme: "Currently being imported under HTS {current_HTS}. We request confirmation of this classification." OR "Currently classified under HTS {current_HTS}. We believe the correct classification is HTS {proposed_HTS} for the reasons stated below."} + +**3. Legal Analysis** + +{Present your classification analysis following the GRIs in order:} + +**GRI 1 Analysis:** +The subject merchandise is {prima facie / most aptly} described by heading {XXXX}, which covers "{heading text}." The relevant Chapter Note {X} {includes/excludes/defines} {relevant term}. {Explain why this heading applies or why it does not definitively resolve classification.} + +{If GRI 1 does not resolve:} + +**GRI {2/3} Analysis:** +{Explain the composite nature, set classification, or essential character analysis. Cite the specific factors (function, value, bulk, role in use) that determine essential character.} + +**Proposed Classification:** +Based on the foregoing analysis, {company_name} respectfully submits that the subject merchandise is properly classified under HTS {proposed_10_digit_code}, with a general rate of duty of {rate}. + +**4. Supporting Authorities** + +{Cite relevant prior CBP rulings, WCO classification opinions, or Explanatory Notes:} +- CBP Ruling {ruling_number} ({year}): {Brief description of the ruling and its relevance} +- WCO Classification Opinion {number}: {Brief description} +- Harmonized System Explanatory Notes to Heading {XXXX}: {Relevant language} + +**5. Statement Pursuant to 19 CFR § 177.1(d)(4)** + +To the best of our knowledge, this request involves no issue that is the same as, or substantially similar to, one that is pending before CBP or any court, or one that has been settled by any court. + +Respectfully submitted, + +{name} +{title} +{company} +{address} +{phone} +{email} + +Enclosures: +{List: sample, photographs, technical specifications, prior rulings cited} + +--- + +## Template 3: Prior Disclosure Filing + +**Use when:** Voluntarily disclosing a customs violation to CBP before an investigation is commenced. This is the most powerful penalty mitigation tool available. + +--- + +{company_letterhead} + +{date} + +VIA CERTIFIED MAIL, RETURN RECEIPT REQUESTED + +Fines, Penalties and Forfeitures Officer +U.S. Customs and Border Protection +{Port of Entry} +{Port Address} + +{OR, if CEE has jurisdiction:} + +Center Director +Center of Excellence and Expertise — {CEE_name} +{CEE_address} + +**Re: Prior Disclosure Pursuant to 19 CFR § 162.74** + +Dear Sir or Madam: + +{company_name} (IOR# {IOR_number}) hereby makes a prior disclosure of customs violations pursuant to 19 CFR § 162.74. To the best of our knowledge, CBP has not commenced a formal investigation or issued a pre-penalty notice concerning the matters disclosed herein. + +**1. Nature of the Violation** + +{Describe the specific violation clearly and concisely:} + +{Example for classification error:} +"Between {start_date} and {end_date}, {company_name} imported {product_description} under HTS {incorrect_HTS} at a duty rate of {incorrect_rate}%. Based on a subsequent internal review, we have determined that the correct classification is HTS {correct_HTS} at a duty rate of {correct_rate}%. This misclassification resulted in an underpayment of duties." + +{Example for valuation error:} +"Between {start_date} and {end_date}, {company_name} failed to include the value of assists (tooling/engineering provided to the foreign manufacturer) in the declared transaction value of imported {product_description}. The total unreported assist value is {assist_value}, resulting in an underpayment of duties." + +{Example for country of origin error:} +"Between {start_date} and {end_date}, {company_name} declared the country of origin of imported {product_description} as {incorrect_origin} when the correct country of origin is {correct_origin}. This resulted in {failure to pay Section 301 duties / incorrect AD/CVD deposit / incorrect marking}." + +**2. Affected Entries** + +| Entry Number | Entry Date | Port | Declared Value | Correct Value | Duty Underpayment | +|---|---|---|---|---|---| +| {entry_1} | {date_1} | {port_1} | {declared_1} | {correct_1} | {underpayment_1} | +| {entry_2} | {date_2} | {port_2} | {declared_2} | {correct_2} | {underpayment_2} | +| ... | ... | ... | ... | ... | ... | +| **TOTAL** | | | | | **{total_underpayment}** | + +{If the exact entries cannot be identified: "We are continuing our investigation to identify all affected entries and will supplement this disclosure with complete entry-level detail within {30/60} days. The estimated total duty underpayment based on our analysis to date is {estimate}."} + +**3. Circumstances of the Violation** + +{Explain how the violation occurred. Be factual, not defensive:} + +{Example: "The classification error originated from reliance on the supplier's suggested HS code without independent verification by a licensed customs broker. Our internal compliance review programme identified the discrepancy during a routine quarterly audit on {discovery_date}."} + +**4. Corrective Actions** + +{Describe what you have done and will do to prevent recurrence:} + +1. {Immediate correction: "All future entries of this product will be classified under HTS {correct_HTS}."} +2. {Process improvement: "We have implemented a mandatory independent classification review for all new HTS codes before first entry."} +3. {Training: "All import operations staff will complete CBP Informed Compliance training by {date}."} +4. {Monitoring: "Quarterly classification audits will be conducted by {internal team or external firm}."} + +**5. Tender of Duties and Interest** + +Pursuant to 19 CFR § 162.74(c), {company_name} hereby tenders the total underpaid duties in the amount of **${total_underpayment}** plus estimated interest of **${interest_amount}**, for a total tender of **${total_tender}**. + +{Check enclosed payable to "U.S. Customs and Border Protection" / ACH payment details} + +{If you cannot calculate the exact amount: "We are prepared to tender the full amount upon CBP's calculation of the precise duty and interest owed. This disclosure and tender are made in good faith based on the information available to us as of the date of this filing."} + +**6. Conclusion** + +{company_name} is committed to compliance with US customs laws and regulations. This disclosure is made voluntarily and in good faith. We respectfully request that this matter be treated as a valid prior disclosure under 19 CFR § 162.74, limiting any penalty assessment to the statutory minimum. + +We are prepared to cooperate fully with any CBP review of this disclosure and to provide additional documentation upon request. + +Respectfully submitted, + +{name} +{title} +{company} +{address} +{phone} +{email} + +Enclosures: +1. Check / payment confirmation for ${total_tender} +2. Spreadsheet of affected entries with calculations +3. {Supporting documentation: corrected classification analysis, valuation report, etc.} + +cc: {Legal counsel} + {VP Trade Compliance} + +--- + +## Template 4: Penalty Response / Mitigation Request + +**Use when:** Responding to a CBP pre-penalty notice or penalty assessment under 19 USC § 1592. + +--- + +{company_letterhead} + +{date} + +Fines, Penalties and Forfeitures Officer +U.S. Customs and Border Protection +{Port/CEE Address} + +**Re: Response to {Pre-Penalty Notice / Penalty Notice} — Case No. {case_number} +Penalty Claim: ${penalty_amount} +Entry/Entries: {entry_numbers}** + +Dear Sir or Madam: + +{company_name} acknowledges receipt of the {pre-penalty notice dated {date} / penalty assessment dated {date}} in the above-referenced matter. We respectfully submit the following response and request for mitigation. + +**1. Summary of CBP's Allegations** + +{Concisely restate what CBP alleges. Do not argue yet — demonstrate that you understand the issue.} + +**2. Response to Allegations** + +{Address each allegation factually. Acknowledge what is correct. Contest what is incorrect. Do NOT admit fraud if the facts support negligence.} + +{If contesting the culpability level: "While we acknowledge that {the classification was incorrect / the value was understated / the origin was misdeclared}, we respectfully submit that the violation resulted from negligence, not gross negligence. The evidence does not support a finding that {company_name} acted with 'conscious disregard of a known duty' or 'gross indifference.' Specifically:"} + +- {Factor 1: "The company maintained a compliance programme that included {specific measures}."} +- {Factor 2: "The error was identified through {internal audit / broker review}, not as a result of CBP enforcement action."} +- {Factor 3: "The company has no prior violations in {X} years of import activity."} + +**3. Mitigating Factors** + +Pursuant to CBP's Mitigation Guidelines, {company_name} submits the following mitigating factors: + +| Factor | Evidence | +|---|---| +| Contributory CBP error | {CBP accepted {X} prior entries with the same classification without comment / N/A} | +| Cooperation | {Company has cooperated fully, producing all requested records within {X} days} | +| Corrective action | {Specific actions taken: new SOPs, training, classification audit, broker change} | +| Prior good record | {No penalties or adverse findings in {X} years of import activity, {Y} entries} | +| Compliance programme | {Description of internal compliance programme: staffing, training, audits, systems} | +| Proportionality | {The penalty of ${penalty_amount} is disproportionate to the actual loss of revenue of ${revenue_loss}} | + +**4. Requested Mitigation** + +Based on the foregoing, {company_name} respectfully requests that CBP: + +{Option A — if acknowledging negligence:} +"Reduce the penalty to the statutory minimum for negligence under 19 USC § 1592(c)(4), specifically {interest on unpaid duties / 1× lost revenue}, consistent with the mitigating factors presented." + +{Option B — if contesting entirely:} +"Cancel the proposed penalty in its entirety. The entry information, as submitted, was {correct / supported by a reasonable interpretation of the tariff schedule / consistent with prior CBP treatment of this merchandise}." + +{Option C — if seeking settlement:} +"Accept a settlement in the amount of ${proposed_amount}, representing {calculation basis}, in full resolution of this matter." + +Respectfully submitted, + +{name} +{title} +{company} + +Enclosures: {List supporting exhibits} +cc: {Legal counsel} + +--- + +## Template 5: USMCA Certification of Origin + +**Use when:** Certifying that goods qualify for preferential treatment under USMCA. The certification must include all nine data elements per Article 5.2. No prescribed form is required. + +--- + +**CERTIFICATION OF ORIGIN** +**(United States-Mexico-Canada Agreement)** + +**1. Certifier:** {Select one: Exporter / Producer / Importer} + Name: {certifier_name} + Title: {certifier_title} + Company: {company_name} + Address: {address} + Phone: {phone} + Email: {email} + +**2. Exporter** {if different from certifier}: + Name: {exporter_name} + Company: {company_name} + Address: {address} + +**3. Producer** {if different from exporter}: + Name: {producer_name} + Company: {company_name} + Address: {address} + {If multiple producers: "Various — see attached list" OR "Available upon request"} + +**4. Importer:** + Name: {importer_name} + Company: {company_name} + Address: {address} + +**5. Description of Goods:** + +| # | Description | HS Tariff Classification (6-digit) | Origin Criterion | Country of Origin | +|---|---|---|---|---| +| 1 | {product_description} | {HS_code} | {criterion_code} | {US/MX/CA} | + +**Origin Criterion Codes:** +- A: Wholly obtained or produced entirely in the territory of one or more USMCA Parties +- B: Produced entirely in the territory using non-originating materials that satisfy the applicable product-specific rule of origin (Annex 4-B) +- C: Produced entirely in the territory exclusively from originating materials +- D: Goods classified under HS chapters/headings listed in Article 4.3 + +**6. Blanket Period** {if applicable}: + From: {start_date} To: {end_date} {maximum 12 months} + +**7. I certify that:** + +The goods described in this document qualify as originating and the information contained in this document is true and accurate. I assume responsibility for proving such representations and agree to maintain and present upon request or to make available during a verification visit, documentation necessary to support this certification, and to inform, in writing, all persons to whom the certification was given of any changes that could affect the accuracy or validity of this certification. + +**Signature:** ______________________ +**Date:** {date} + +--- + +## Template 6: Internal Compliance Advisory + +**Use when:** Notifying internal stakeholders of a regulatory change, new compliance requirement, or enforcement action that requires operational changes. + +--- + +**To:** {distribution_list: Import Operations, Procurement, Product Development, Legal} +**From:** {Trade Compliance Team / compliance_officer_name} +**Date:** {date} +**Subject:** COMPLIANCE ACTION REQUIRED: {topic} — Effective {effective_date} + +**BUSINESS IMPACT:** +{Lead with the operational impact — what changes for the business:} + +{Example: "Effective {date}, all imports of {product_category} from {country} will require {new documentation / additional testing / modified classification}. Failure to comply will result in {shipment detention, penalties up to $X per entry, import refusal}. Estimated cost impact: {$X per shipment / $Y annually}."} + +**WHAT CHANGED:** +{Brief regulatory background — 2-3 sentences maximum:} + +{Example: "CBP issued CSMS Message #{number} on {date} implementing {regulation/ruling}. This modifies the requirements for {specific area} under {statutory reference}."} + +**REQUIRED ACTIONS:** + +| # | Action | Owner | Deadline | +|---|---|---|---| +| 1 | {Specific action item} | {Team/person} | {Date} | +| 2 | {Specific action item} | {Team/person} | {Date} | +| 3 | {Specific action item} | {Team/person} | {Date} | + +**WHAT HAPPENS IF WE DON'T COMPLY:** +{Specific consequences:} +- Shipment detention at port (average {X} days to resolve, demurrage cost ${Y}/day) +- Penalty exposure: ${amount} per violation under {statute} +- {If applicable: import refusal, product recall, licence revocation} + +**QUESTIONS / ESCALATION:** +Contact {compliance_officer_name} at {email} / {phone}. Do NOT attempt to self-resolve classification or entry questions — route all inquiries to the trade compliance team. + +--- + +## Template 7: Supplier Questionnaire — Origin Determination + +**Use when:** Collecting information from suppliers to determine whether imported goods qualify for preferential treatment under an FTA. + +--- + +**SUPPLIER ORIGIN QUESTIONNAIRE** + +**From:** {importer_company} — Trade Compliance Department +**To:** {supplier_company} +**Date:** {date} +**Product(s):** {product_description} +**Applicable FTA:** {USMCA / EU-UK TCA / RCEP / other} + +We are evaluating whether the above product(s) qualify for preferential duty treatment under {FTA}. Your responses to the following questions will be used to prepare the required origin certification. Please provide accurate and complete information — incorrect origin claims can result in penalties for both the importer and the exporter. + +**SECTION A: PRODUCT INFORMATION** + +1. Product description (technical, not marketing): ________________________________ +2. HS classification at the 6-digit level: ________________________________ +3. Country where the product is manufactured: ________________________________ +4. Facility address where final production occurs: ________________________________ + +**SECTION B: BILL OF MATERIALS** + +For each material/component used in the manufacture of the product, please provide: + +| # | Material Description | HS Code (6-digit) | Country of Origin | Supplier Name | % of Total Product Value | Originating under {FTA}? (Y/N) | +|---|---|---|---|---|---|---| +| 1 | | | | | | | +| 2 | | | | | | | +| 3 | | | | | | | + +{Add rows as needed. If the BOM contains more than 20 items, please provide as an attached spreadsheet.} + +**SECTION C: MANUFACTURING PROCESS** + +5. Describe the manufacturing process performed at your facility: ________________________________ + {Specifically identify: cutting, assembly, machining, chemical processing, finishing, testing} + +6. List any processes performed by subcontractors and the country where subcontracting occurs: ________________________________ + +7. What is the total value added at your facility as a percentage of the FOB price? _____% + +**SECTION D: COST INFORMATION** {Required only if RVC calculation is needed} + +8. FOB price of the finished product: ________________________________ +9. Total cost of non-originating materials: ________________________________ +10. Total cost of originating materials: ________________________________ +11. Direct labour cost: ________________________________ +12. Manufacturing overhead: ________________________________ +13. Profit: ________________________________ + +**SECTION E: CERTIFICATION** + +I certify that the information provided above is true and accurate to the best of my knowledge. I understand that false statements may result in penalties under the laws of the importing country. + +Name: ________________________________ +Title: ________________________________ +Signature: ________________________________ +Date: ________________________________ + +Please return the completed questionnaire to {compliance_email} by {deadline_date}. + +--- + +## Template 8: Binding Ruling Appeal / Request for Reconsideration + +**Use when:** CBP has issued a ruling or revocation that you believe is incorrect, and you wish to request reconsideration or appeal to the Court of International Trade. + +--- + +{company_letterhead} + +{date} + +U.S. Customs and Border Protection +Regulations and Rulings, Office of Trade +90 K Street NE, 10th Floor +Washington, DC 20229-1177 + +**Re: Request for Reconsideration of Ruling Letter {ruling_number} +Product: {product_description} +Current Classification: HTS {current_HTS} +Proposed Reclassification: HTS {proposed_HTS}** + +Dear Sir or Madam: + +Pursuant to 19 CFR § 177.12, {company_name} respectfully requests reconsideration of CBP Ruling Letter {ruling_number}, issued {ruling_date}, which classified {product_description} under HTS {classification_in_ruling}. + +**1. Basis for Reconsideration** + +{State the specific grounds:} + +{Option A — Error of law:} +"The ruling incorrectly applied GRI {X} by {specific error}. The correct application of GRI {X} yields classification under heading {XXXX} because {analysis}." + +{Option B — Error of fact:} +"The ruling was based on an incomplete or inaccurate description of the merchandise. Specifically, {identify the factual error and provide the correct facts with supporting evidence}." + +{Option C — Changed circumstances:} +"Since the issuance of the ruling, {identify the change: new WCO classification opinion, new Explanatory Note, product modification, new CBP ruling on analogous goods} has occurred, warranting reconsideration." + +**2. Detailed Analysis** + +{Present the full GRI analysis supporting your position, structured identically to a ruling request (see Template 2). Address each point in CBP's original ruling that you are contesting.} + +**3. Supporting Authorities** + +{Cite any authorities that support your position and distinguish any that CBP relied upon:} + +- {Authority supporting your position} +- {Distinguish CBP's cited authority: "CBP relied on Ruling {number}, which addressed {different product}. That ruling is distinguishable because {specific differences}."} + +**4. Commercial Impact** + +{Explain the practical impact of the ruling on your business:} + +"The reclassification from HTS {current} to HTS {proposed} {increases the duty rate from X% to Y% / removes FTA eligibility / triggers AD/CVD deposits / changes PGA requirements}, affecting approximately ${annual_value} in annual imports." + +**5. Requested Action** + +{company_name} respectfully requests that CBP: +1. Reconsider Ruling Letter {ruling_number} +2. Classify {product_description} under HTS {proposed_classification} +3. {If applicable: "Limit any reclassification to prospective application only, providing a reasonable transition period per 19 USC § 1625(c)."} + +Respectfully submitted, + +{name} +{title} +{company} + +Enclosures: {List: product sample, technical specifications, prior rulings, WCO opinions} +cc: {Legal counsel} + +--- + +## Template 9: Restricted Party Screening — Hit Adjudication Memorandum + +**Use when:** Documenting the adjudication of a restricted party screening hit (false positive clearance or true positive block). + +--- + +**SCREENING HIT ADJUDICATION MEMORANDUM** + +**Date:** {date} +**Adjudicator:** {name}, {title} +**Transaction Reference:** {PO/order/shipment number} +**Screening Tool:** {tool_name} (version {version}) +**Screening Date:** {screening_date} + +**PARTIES SCREENED:** + +| Party | Role | Name Screened | Country | +|---|---|---|---| +| {party_1} | Buyer | {name} | {country} | +| {party_2} | Consignee | {name} | {country} | +| {party_3} | End User | {name} | {country} | + +**HIT DETAILS:** + +| Hit # | Screened Name | Matched List | Listed Name | Match Score | List Entry Date | +|---|---|---|---|---|---| +| 1 | {screened_name} | {list_name} | {listed_name} | {score}% | {date} | + +**ADJUDICATION ANALYSIS:** + +{For each hit, analyse the following factors:} + +| Factor | Screened Entity | Listed Entity | Match? | +|---|---|---|---| +| Full legal name | {name} | {name} | {Y/N/Partial} | +| Address | {address} | {address} | {Y/N/Partial} | +| Country | {country} | {country} | {Y/N} | +| Date of birth / incorporation | {date} | {date} | {Y/N/Unknown} | +| Aliases | {known aliases} | {listed aliases} | {Y/N} | +| Additional identifiers | {tax ID, D&B#} | {identifiers on list} | {Y/N} | + +**CONCLUSION:** + +{Select one:} + +**[ ] FALSE POSITIVE** — The screened entity is NOT the listed entity. Basis: {specific reasons — e.g., "Different country (screened entity is in Germany; listed entity is in Iran), different industry sector (screened entity is a pharmaceutical distributor; listed entity is an individual designated for terrorism support), no address correlation."} + +**Disposition:** Transaction may proceed. + +**[ ] TRUE POSITIVE** — The screened entity IS the listed entity or cannot be distinguished. + +**Disposition:** Transaction BLOCKED. Escalated to {compliance officer / legal counsel} on {date}. {If OFAC: "OFAC blocking report to be filed within 10 business days." / If Entity List: "BIS licence application under consideration." / If DPL: "Absolute prohibition — no licence available. Transaction permanently blocked."} + +**[ ] INCONCLUSIVE** — Cannot determine with confidence. Escalated to {compliance officer} for additional investigation on {date}. + +**Approved by:** _______________________ Date: ___________ +{Compliance Officer / Manager} + +**Record Retention:** This memorandum and all supporting documentation will be retained for {5 years from the date of adjudication / indefinitely for true positives}. diff --git a/web-app/public/skills/customs-trade-compliance/references/decision-frameworks.md b/web-app/public/skills/customs-trade-compliance/references/decision-frameworks.md new file mode 100644 index 00000000..ac9ed87a --- /dev/null +++ b/web-app/public/skills/customs-trade-compliance/references/decision-frameworks.md @@ -0,0 +1,764 @@ +# Decision Frameworks — Customs & Trade Compliance + +This reference provides the detailed decision logic, classification methodology, FTA qualification +decision trees, customs valuation methods, restricted party screening protocols, and penalty risk +assessment frameworks for customs and trade compliance operations. + +All thresholds, timelines, and regulatory references reflect multi-jurisdictional trade operations +covering US, EU, UK, and key Asia-Pacific markets. Regulatory citations are current as of 2024 +but must be verified against the latest amendments before reliance in specific proceedings. + +--- + +## 1. HS Classification Methodology + +### 1.1 Pre-Classification Information Gathering + +Before applying the GRIs, assemble the complete technical profile of the product. Classification +errors almost always trace back to insufficient product information, not misapplication of the rules. + +**Required Information Checklist:** + +| Data Point | Why It Matters | Example Impact | +|---|---|---| +| Material composition (% by weight) | Determines chapter for textiles, plastics, metals, composites | A fabric that is 52% cotton / 48% polyester classifies as cotton (Ch. 52), not synthetic (Ch. 54) | +| Primary function | Determines heading for machines, apparatus, instruments | A device that both weighs and labels classifies by the function giving essential character | +| Dimensions and weight | Determines subheading for many products | Steel tubes above/below 406.4mm OD classify differently | +| Manufacturing process | Determines whether the product is "prepared," "processed," or raw | Green coffee (Ch. 09) vs roasted coffee (Ch. 09) vs coffee extract (Ch. 21) | +| Intended use | Relevant for "for use with" or "suitable for" headings | Automotive glass vs architectural glass — identical product, different classifications | +| Retail packaging | Determines whether GRI 3(b) set rules apply | A first-aid kit in retail packaging is classified as a set; the same items shipped loose are classified individually | +| Country of manufacture | Affects national tariff lines and AD/CVD applicability | Chinese-origin steel faces additional duties that Korean-origin steel does not | +| Technical specifications | Resolves subheading-level distinctions | Voltage, frequency, capacity, resolution, accuracy — all create subheading splits | + +**Common Information Failures:** + +- Relying on the supplier's suggested HS code without independent verification — suppliers classify for export purposes; the import classification may differ at the national level +- Using a product marketing name instead of a technical description — "SmartWidget Pro" tells you nothing about classification +- Accepting a "parts of" classification without verifying whether the item meets the Section XVI Note 2 test for parts +- Classifying based on the product's industry rather than its physical characteristics — an automotive connector and an industrial connector may have the same HS code + +### 1.2 GRI Application Decision Tree + +``` +START: Product to classify + │ + ├─ Step 1: Read all candidate heading texts + │ ├─ Read Section Notes for each candidate Section + │ ├─ Read Chapter Notes for each candidate Chapter + │ └─ Do the Section/Chapter Notes explicitly include or exclude the product? + │ ├─ YES, one heading clearly covers → CLASSIFY (GRI 1). STOP. + │ └─ NO unique heading, or notes are ambiguous → Continue to Step 2 + │ + ├─ Step 2: Is the product incomplete, unfinished, or unassembled? + │ ├─ YES → Does it have the essential character of the complete article? + │ │ ├─ YES → Classify as the complete article (GRI 2(a)). STOP. + │ │ └─ NO → It may be a "part" — check Section/Chapter notes for parts provisions + │ └─ NO → Is it a mixture or combination of materials/components? + │ ├─ YES → GRI 2(b) extends headings to include mixtures. Multiple headings + │ │ may now apply → Continue to Step 3 + │ └─ NO → Continue to Step 3 + │ + ├─ Step 3: Multiple headings still apply (prima facie classifiable under 2+) + │ ├─ Step 3(a): Is one heading more specific than the others? + │ │ ├─ YES → Classify under the most specific heading. STOP. + │ │ └─ NO (headings are equally specific, or the product is a composite/set) → + │ │ + │ ├─ Step 3(b): Is the product a composite good, set put up for retail sale, + │ │ or goods put up in sets for retail sale? + │ │ ├─ YES → Classify by the material or component giving essential character + │ │ │ ├─ Essential character determinable → CLASSIFY. STOP. + │ │ │ └─ Essential character not determinable → Continue to 3(c) + │ │ └─ NO → Continue to 3(c) + │ │ + │ └─ Step 3(c): Classify under the heading that occurs LAST in numerical order. STOP. + │ + ├─ Step 4: No heading covers the product even after Steps 1-3 + │ └─ Classify under the heading for the most ANALOGOUS goods (GRI 4). STOP. + │ + ├─ Step 5: (Applies to cases, containers, and packing materials) + │ ├─ GRI 5(a): Cases, boxes, and similar containers specially shaped for a specific + │ │ article are classified WITH the article when presented together + │ └─ GRI 5(b): Packing materials are classified with the goods unless they are + │ clearly suitable for repetitive use + │ + └─ Step 6: Subheading-level classification + ├─ Apply GRI 1-5 within the determined heading + ├─ Compare subheading texts at the SAME level (one-dash vs one-dash, two-dash vs two-dash) + └─ Subheading notes take precedence at this level. CLASSIFY. STOP. +``` + +### 1.3 Essential Character Determination (GRI 3(b)) + +When a composite good or set must be classified by the component giving essential character, +assess the following factors. No single factor is determinative — weigh them in context: + +| Factor | When It Is Decisive | Example | +|---|---|---| +| **Function** | When one component defines what the product does | A flashlight with a built-in radio — if the primary purchase reason is illumination, the flashlight component gives essential character | +| **Value** | When one component represents the dominant cost | A gift set with a $95 watch and $5 pouch — the watch gives essential character by value | +| **Bulk/Weight** | When one component is physically dominant | A concrete-and-steel composite where concrete is 90% by weight | +| **Role in use** | When one component is indispensable | A printer cartridge kit with cartridge + cleaning cloth — the cartridge is indispensable, the cloth is ancillary | +| **Consumer perception** | When the product is marketed for one component | A toy with candy — if marketed as a toy (candy is incidental), the toy gives essential character | + +**When essential character cannot be determined:** If the factors conflict or are balanced (e.g., two +components of roughly equal value, bulk, and functional importance), essential character is +"not determinable" and you must proceed to GRI 3(c) — last heading in numerical order. + +### 1.4 Section XVI Special Rules (Machines and Mechanical Appliances) + +Section XVI (Chapters 84-85) has complex notes that override the general GRI application: + +**Note 1 — Exclusions:** Parts of general use (Section XV), belts and hoses (Ch. 39/40/59), +and other specifically excluded articles do not classify in Section XVI regardless of their use +with machines. + +**Note 2 — Parts classification hierarchy:** +1. Parts that are goods included in any heading of Chapters 84 or 85 (other than 8409, 8431, + 8448, 8466, 8473, 8503, 8522, 8529, 8538) are classified in their OWN heading, not as parts. +2. Other parts, if suitable for use solely or principally with a particular machine, classify WITH + that machine. +3. Parts suitable for use with multiple machines classify under the "catch-all" parts headings + (8409, 8431, etc.) or under heading 8487 (miscellaneous machine parts). + +**Note 3 — Composite machines:** A machine that performs two or more complementary functions +classifies under the heading for the function that represents the PRINCIPAL function. If no +principal function is identifiable, Note 3 defers to GRI 3(c). + +**Note 4 — Machine units:** A machine consisting of separate components designed to jointly +perform a clearly defined function classifies as the complete machine when the components +are presented together or when the components are designed to be assembled. + +**Note 5 — Automatic Data Processing (ADP) machines:** Heading 8471 requires the machine to be +capable of: (a) storing the processing program, (b) being freely programmed by the user, +(c) performing arithmetical computations, and (d) executing a user-modified processing program +without physical intervention. All four criteria must be met. A single-function device +(e.g., a barcode scanner that only scans) does not meet criterion (b) and classifies under its +function-specific heading, not as ADP. + +### 1.5 Common Classification Disputes and Resolution + +**Dispute: Is it a "part" or an "accessory"?** +- Parts are essential to the functioning of the machine and are consumed in, or physically + integrated with, the machine during use. Without the part, the machine does not function. +- Accessories enhance or supplement the machine's function but are not essential. The machine + functions without the accessory. +- Classification impact: Parts often follow the machine's classification. Accessories may classify + independently under their own material or function heading, often at a different duty rate. + +**Dispute: Is the food "prepared" (Chapter 16/19/20/21) or raw (Chapters 2-14)?** +- "Prepared" generally means processed beyond what is necessary for preservation or transport. + Frozen raw shrimp: Chapter 3. Cooked shrimp: Chapter 16. Shrimp tempura (battered and fried): Chapter 16. +- Simple operations that do NOT constitute "preparation": washing, trimming, freezing, chilling, + sorting by size, packing. These maintain the product in Chapter 2-14. +- Watch for Chapter notes — Chapter 20 Note 1 excludes vegetables "prepared or preserved by + vinegar" (heading 2001 is the specific provision) from the general Chapter 7 vegetable headings. + +**Dispute: Is it a "set" under GRI 3(b)?** +A "set put up for retail sale" must meet ALL three conditions: +1. Consists of at least two different articles classifiable in different headings +2. Consists of articles put up together to meet a particular need or carry out a specific activity +3. Put up in a manner suitable for sale directly to users without repacking + +If any condition fails, the items are classified individually — not as a set. Industrial assortments +(e.g., a box of assorted fasteners) that are not "put up for retail sale" do not qualify. + +--- + +## 2. FTA Qualification Decision Trees + +### 2.1 General FTA Qualification Process + +``` +START: Can this product qualify for preferential treatment? + │ + ├─ Step 1: Identify ALL potentially applicable FTAs + │ ├─ Where was the good produced / last substantially transformed? + │ ├─ Where is it being imported? + │ └─ Are both countries parties to one or more FTAs? + │ ├─ YES → List all applicable FTAs → Continue to Step 2 + │ └─ NO → No FTA preference available. Check GSP or other unilateral programmes. + │ + ├─ Step 2: For each applicable FTA, determine the product-specific rule of origin + │ ├─ Look up the HS heading (4-digit or 6-digit) in the FTA's product-specific rules annex + │ ├─ Determine the rule type: + │ │ ├─ Tariff Shift (change in tariff classification — CTC, CTH, CTSH) + │ │ ├─ Regional Value Content (RVC) threshold + │ │ ├─ Specific process requirement + │ │ └─ Combination of the above + │ └─ Continue to Step 3 + │ + ├─ Step 3: Trace all materials in the bill of materials (BOM) + │ ├─ For each input material, determine: + │ │ ├─ HS classification of the input + │ │ ├─ Country of origin of the input + │ │ ├─ Value of the input (for RVC calculations) + │ │ └─ Whether the input is "originating" under the same FTA (for cumulation) + │ └─ Continue to Step 4 + │ + ├─ Step 4: Apply the product-specific rule + │ ├─ Tariff Shift: Has every non-originating material undergone the required tariff shift? + │ │ ├─ CTC (change in tariff chapter): all non-originating materials must be from a + │ │ │ different 2-digit chapter than the finished good + │ │ ├─ CTH (change in tariff heading): different 4-digit heading + │ │ ├─ CTSH (change in tariff subheading): different 6-digit subheading + │ │ └─ Check exceptions — many rules list specific headings that are EXCLUDED from the + │ │ tariff shift (e.g., "a change from any heading except 7208-7212") + │ ├─ RVC: Does the regional value content meet or exceed the threshold? + │ │ ├─ Calculate using the permitted method(s) + │ │ └─ If the FTA offers multiple methods, use the most favourable + │ └─ Process: Has the required manufacturing process been performed in the territory? + │ + ├─ Step 5: Apply cumulation (if applicable) + │ ├─ Materials originating in other FTA partner countries can be treated as originating + │ ├─ Bilateral cumulation: only between the two parties (EU-UK TCA) + │ ├─ Diagonal cumulation: among all parties (RCEP, PEM Convention) + │ └─ Full cumulation: even processing (not just originating materials) in partner countries + │ counts toward origin (EU Overseas Countries and Territories) + │ + ├─ Step 6: Apply de minimis / tolerance rules + │ ├─ Most FTAs allow a small percentage of non-originating materials that don't meet the + │ │ tariff shift rule (typically 7-10% of the product's value) + │ ├─ De minimis does NOT apply to materials specifically excluded in the product-specific rule + │ └─ Textiles have separate de minimis rules (usually weight-based, not value-based) + │ + └─ Step 7: Verify certification and documentation requirements + ├─ USMCA: self-certification with nine required data elements + ├─ EU-UK TCA: origin declaration on the invoice (for consignments under €6,000 any + │ exporter; above €6,000 requires REX registration) + ├─ RCEP: certificate of origin (Form RCEP) or origin declaration + └─ Retain ALL supporting documentation for the FTA's prescribed retention period +``` + +### 2.2 USMCA Rules of Origin — Detailed Application + +**Tariff Shift Rules:** + +USMCA Annex 4-B contains product-specific rules for every HS heading. Many rules combine +a tariff shift requirement with an RVC threshold. Common patterns: + +- **Pure tariff shift:** "A change to heading 9403 from any other chapter." All non-originating + materials must come from chapters other than 94 (furniture). If you use non-originating wood + from Chapter 44 to make a wooden table, the wood satisfies this rule because Chapter 44 ≠ Chapter 94. + But if you import non-originating table legs already classified in heading 9403, the tariff shift fails. + +- **Tariff shift with exceptions:** "A change to heading 6204 from any heading outside the group + of headings 6201-6212, except from heading 5106-5113 or 5204-5212..." These carve-outs + are designed to prevent simple assembly operations from conferring origin. + +- **Tariff shift OR RVC:** "A change to heading 8471 from any other heading; or No required + change in tariff classification, provided there is a regional value content of not less than + 45 percent under the transaction-value method or not less than 35 percent under the net cost method." + The exporter may choose whichever alternative is easier to satisfy. + +**Regional Value Content Calculations:** + +*Transaction Value Method:* +``` +RVC = ((TV - VNM) / TV) × 100 +``` +Where: +- TV = Transaction Value of the good (adjusted to FOB) +- VNM = Value of Non-originating Materials (including parts, materials consumed in production) + +*Net Cost Method:* +``` +RVC = ((NC - VNM) / NC) × 100 +``` +Where: +- NC = Total cost minus sales promotion, marketing, after-sales service, royalties, shipping and + packing costs, and non-allowable interest +- VNM = same as above + +The net cost method typically produces a HIGHER RVC because it removes costs that inflate the +denominator. Use it when margins are thin or when significant royalty/promotion costs are present. + +**Automotive Rules (USMCA-specific):** + +USMCA introduced the most complex automotive rules of origin ever negotiated: +- Passenger vehicles: 75% RVC using net cost method (phased in from 62.5%) +- Core parts (engines, transmissions, body/chassis): separate 75% RVC requirement +- Principal parts (brakes, axles, suspension): 70% RVC +- Complementary parts (A/C, steering, batteries): 70% RVC +- Steel and aluminium: 70% must be "melted and poured" in North America +- Labour Value Content: 40% of production must be by workers earning ≥ US$16/hour (high-wage) + +### 2.3 EU-UK TCA Rules of Origin + +**Key Differences from USMCA:** + +- No self-certification for high-value consignments without REX registration +- Bilateral cumulation only (UK + EU, not with third countries unless separate agreements exist) +- "Insufficient processing" list: operations that NEVER confer origin regardless of tariff shift + (e.g., simple assembly, packaging, mixing, ironing of textiles, sharpening/grinding) +- Tolerance: 10% of ex-works price for non-originating materials that don't satisfy the list rule + (15% for products of Chapters 50-63, textiles — but measured by weight, not value) + +**List Rules Structure:** + +EU-UK TCA Annex ORIG-2 provides rules in four columns: +1. HS heading of the finished product +2. Description of the product +3. Working or processing on non-originating materials that confers origin +4. Alternative rule (if available) + +Example: Heading 8418 (refrigerators) +- Rule: "Manufacture in which all materials used are classified within a heading other than + that of the product" AND "the value of all non-originating materials used does not exceed + 40% of the ex-works price of the product" +- Both conditions must be met (they are cumulative, not alternative) + +### 2.4 RCEP Rules of Origin + +**Key Features:** + +- 15 member states with diagonal cumulation +- Product-specific rules use both tariff shift and RVC (40% threshold typical) +- RVC can be calculated using either: + - Build-up: RVC = (VOM / FOB) × 100 ≥ 40% + - Build-down: RVC = ((FOB - VNM) / FOB) × 100 ≥ 40% +- Certificate of Origin (Form RCEP) or approved exporter origin declaration +- "Back-to-back" certificates allowed for goods transshipped through a non-party (critical for + Singapore/Hong Kong hub operations) +- Product-specific rules for Chapters 50-63 (textiles) are notably restrictive — many require + two-step processing (yarn → fabric → garment) + +### 2.5 AfCFTA Rules of Origin (Summary) + +- General rule: value-added threshold of 40% (or a change in tariff heading) +- Cumulation: up to 60% of materials can originate from other AfCFTA member states +- Simplified rules for LDC member states +- Product-specific rules still being negotiated for many tariff lines — check the latest Protocol + on Rules of Origin annexes before relying on general rules + +--- + +## 3. Customs Valuation Methods + +### 3.1 Method Selection Decision Tree + +``` +START: Determine the customs value of imported goods + │ + ├─ Method 1: Transaction Value + │ ├─ Is there a sale for export to the country of importation? + │ │ ├─ NO (consignment, loan, free sample, gift, lease) → Skip to Method 2 + │ │ └─ YES → Is the sale between related parties? + │ │ ├─ NO → Is the sale subject to conditions that cannot be quantified? + │ │ │ ├─ NO → Are there restrictions on disposition/use (other than legal or geographic)? + │ │ │ │ ├─ NO → Transaction Value = Price paid or payable + additions - deductions + │ │ │ │ │ ├─ Additions (19 CFR § 152.103 / UCC Art. 71): + │ │ │ │ │ │ ├─ Commissions (except buying commissions) + │ │ │ │ │ │ ├─ Assists (tools, dies, moulds, engineering provided free/at reduced cost) + │ │ │ │ │ │ ├─ Royalties and licence fees related to the imported goods, payable as + │ │ │ │ │ │ │ a condition of sale + │ │ │ │ │ │ ├─ Packing costs + │ │ │ │ │ │ ├─ Proceeds of subsequent resale accruing to the seller + │ │ │ │ │ │ └─ US: cost of transport TO the US port (ocean/air freight, insurance) + │ │ │ │ │ │ EU: transport and insurance to the EU border are INCLUDED + │ │ │ │ │ │ (CIF basis for EU, FOB+ for US) + │ │ │ │ │ └─ Deductions (not included in transaction value): + │ │ │ │ │ ├─ Post-importation transport costs (inland freight) + │ │ │ │ │ ├─ Import duties and taxes + │ │ │ │ │ ├─ Construction/installation costs after importation + │ │ │ │ │ └─ Buying commissions (if clearly identified) + │ │ │ │ └─ CLASSIFY VALUE. STOP. + │ │ │ └─ YES → Skip to Method 2 + │ │ └─ YES (related parties) → + │ │ ├─ Did the relationship influence the price? + │ │ │ ├─ NO (demonstrate with "circumstances of sale" test or test values) → + │ │ │ │ Transaction Value is acceptable. Apply additions/deductions above. + │ │ │ └─ YES or cannot demonstrate → Skip to Method 2 + │ │ └─ OR: Does the transaction value approximate a "test value"? + │ │ (transaction value of identical/similar goods to unrelated buyers, + │ │ deductive value, or computed value for identical/similar goods) + │ │ ├─ YES → Transaction Value acceptable. STOP. + │ │ └─ NO → Skip to Method 2 + │ + ├─ Method 2: Transaction Value of Identical Goods + │ ├─ Are there importations of IDENTICAL goods? + │ │ (same in all respects: physical characteristics, quality, reputation, country of origin) + │ ├─ Sold for export at the same commercial level and in substantially the same quantity? + │ │ (Adjustments permitted for quantity differences and transport costs) + │ ├─ Sold at or about the same time as the goods being valued? + │ │ ├─ YES to all → Use the transaction value of those identical goods. STOP. + │ │ └─ NO to any → Skip to Method 3 + │ + ├─ Method 3: Transaction Value of Similar Goods + │ ├─ Same criteria as Method 2, but for goods that are "similar" — + │ │ closely resembling in characteristics, components, materials, + │ │ and capable of performing the same functions and being commercially interchangeable + │ │ ├─ Available → Use. STOP. + │ │ └─ Not available → Skip to Method 4 (or Method 5 at importer's request in the US) + │ + ├─ Method 4: Deductive Value + │ ├─ Start with the unit price at which the greatest aggregate quantity is sold + │ │ in the country of importation (within 90 days of import date) + │ ├─ DEDUCT: + │ │ ├─ Commissions or profit and general expenses normally earned on sales in the + │ │ │ importing country for goods of the same class or kind + │ │ ├─ Transport and insurance costs within the importing country + │ │ ├─ Customs duties and other national taxes payable on importation + │ │ └─ If the goods are further processed after importation ("super deductive"): + │ │ deduct the value added by the processing + │ └─ Result = Deductive Value. STOP. + │ + ├─ Method 5: Computed Value + │ ├─ BUILD UP from: + │ │ ├─ Cost or value of materials and fabrication/processing in the producing country + │ │ ├─ Amount for profit and general expenses equal to that usually reflected in sales + │ │ │ of goods of the same class or kind from the country of exportation + │ │ └─ Cost of transport and insurance to the importing country (CIF for EU, FOB+ for US) + │ ├─ This method is only available if the foreign producer is willing to share cost data + │ │ and submit to verification by the importing country's customs authority + │ └─ Result = Computed Value. STOP. + │ + └─ Method 6: Fallback ("Reasonable Means") + ├─ Flexible application of Methods 1-5 with reasonable adjustments + ├─ Prohibitions — the value CANNOT be based on: + │ ├─ Selling price of goods produced in the importing country + │ ├─ A system providing for use of the higher of two alternative values + │ ├─ The price of goods in the domestic market of the country of exportation + │ ├─ Minimum customs values + │ ├─ Arbitrary or fictitious values + │ └─ Cost of production other than computed values for identical/similar goods + └─ Result = Fallback Value. STOP. +``` + +### 3.2 Related-Party Valuation — Circumstances of Sale Test + +When the buyer and seller are related (per 19 USC § 1401a(g) or UCC Art. 127), customs +authorities will scrutinise the transaction value. To demonstrate that the relationship did not +influence the price: + +**Evidence that supports acceptance:** + +1. The price was settled in a manner consistent with normal pricing practices in the industry +2. The price was settled in a manner consistent with how the seller prices to unrelated buyers +3. The price is adequate to ensure recovery of all costs plus a profit equivalent to the + firm's overall profit over a representative period in sales of goods of the same class or kind +4. Transfer pricing documentation showing the price was set at arm's length under OECD guidelines + +**Test values (alternative to circumstances of sale):** + +The transaction value is acceptable if it closely approximates one of: +- Transaction value on identical or similar goods sold to unrelated buyers in the importing country +- Deductive value for identical or similar goods +- Computed value for identical or similar goods + +"Closely approximates" means within a reasonable range — CBP and EU customs have discretion here, +but differences under 5% are generally accepted, 5-10% require explanation, and over 10% will +likely trigger rejection of the transaction value. + +### 3.3 Assists Valuation + +Assists are one of the most frequently overlooked additions to transaction value. An assist is +anything the buyer provides to the seller free of charge or at reduced cost for use in producing +the imported goods: + +**Types of assists:** + +| Assist Type | Valuation Method | Apportionment | +|---|---|---| +| Materials consumed in production (raw materials, components) | Cost of acquisition or production | Full value added to first shipment, or prorated across all units produced | +| Tools, dies, moulds, and similar items | Cost of acquisition or production; if previously used, current value only | Prorated across the number of units produced using the tool/die/mould | +| Engineering, development, artwork, design, plans, and sketches | Cost if undertaken in the importing country; value if undertaken elsewhere | Prorated across anticipated total production, or first shipment | +| Materials consumed in production provided by related parties | Price paid between related parties if arm's length; otherwise cost of production | Same as unrelated-party assists | + +**Critical assist trap:** A US company sends CAD drawings to a Chinese manufacturer at no charge. +The value of producing those drawings (engineering time, software licences) must be added to the +customs value of every import from that manufacturer that uses those drawings. Failure to declare +assists is one of the top findings in CBP Focused Assessments and triggers penalty exposure. + +### 3.4 Royalties and Licence Fees + +Royalties are dutiable additions to transaction value when they are: +1. Related to the imported goods (not to post-importation activity), AND +2. Paid as a condition of the sale (the buyer cannot buy the goods without paying the royalty) + +**Dutiable examples:** +- Royalty paid to the seller (or a related party) for the right to manufacture using a patented + process — the royalty directly relates to production of the imported goods +- Trademark licence fee paid to the parent company where the manufacturer will only produce + goods bearing the trademark for the licensed importer +- Technology licence fee where the foreign producer can only access the technology through the + buyer's licence + +**Non-dutiable examples:** +- Royalty for the right to distribute or resell in the importing country (post-importation activity) +- Royalty paid to an unrelated third party where the seller has no knowledge of or interest in + the royalty arrangement and the royalty is not a condition of the sale + +**The "condition of sale" analysis is fact-intensive.** Look at: +- Would the seller sell the goods to the buyer without the royalty being paid? +- Does the seller have any involvement in, or control over, the royalty arrangement? +- Can the buyer source the goods elsewhere if the royalty is not paid? + +--- + +## 4. Restricted Party Screening Protocol + +### 4.1 Screening Workflow + +``` +START: New transaction (sale, purchase, or service) + │ + ├─ Step 1: Identify ALL parties to the transaction + │ ├─ Buyer / importer of record + │ ├─ Seller / exporter + │ ├─ Ultimate consignee / end user + │ ├─ Intermediate consignees + │ ├─ Freight forwarders and customs brokers + │ ├─ Banks (in letter of credit transactions) + │ ├─ Ship-to addresses (if different from buyer/consignee) + │ └─ Any agents, representatives, or beneficial owners + │ + ├─ Step 2: Screen ALL identified parties against ALL applicable lists + │ ├─ US Lists (if US nexus exists — US-origin goods, US persons, US financial system): + │ │ ├─ OFAC SDN List (Specially Designated Nationals and Blocked Persons) + │ │ ├─ OFAC Sectoral Sanctions Identifications (SSI) List + │ │ ├─ OFAC Non-SDN Menu-Based Sanctions List (NS-MBS) + │ │ ├─ BIS Entity List (Supplement No. 4 to Part 744) + │ │ ├─ BIS Denied Persons List + │ │ ├─ BIS Unverified List + │ │ ├─ BIS Military End User (MEU) List + │ │ ├─ DDTC Debarred Parties (AECA Section 38) + │ │ └─ Non-Proliferation Sanctions lists + │ ├─ EU Lists (if EU nexus exists): + │ │ ├─ EU Consolidated Financial Sanctions List + │ │ └─ EU Dual-Use Regulation Annex I controlled end-users + │ ├─ UK Lists (if UK nexus exists): + │ │ ├─ UK OFSI Consolidated List + │ │ └─ UK Export Control Joint Unit + │ ├─ Other Jurisdictions: Australia DFAT, Canada SEMA, Japan METI, etc. + │ └─ Internal denied/watch lists (prior compliance issues, flagged entities) + │ + ├─ Step 3: Evaluate screening results + │ ├─ NO HITS → Document the screening (date, tool, parties screened, result). + │ │ Proceed with the transaction. STOP. + │ ├─ HITS RETURNED → Continue to Step 4 + │ + ├─ Step 4: Adjudicate each hit + │ ├─ For each hit, assess: + │ │ ├─ Name match quality (exact, near-exact, partial, phonetic) + │ │ ├─ Address correlation (same country? same city? same street?) + │ │ ├─ Date of birth / incorporation date (for individuals / entities) + │ │ ├─ Alias match (is the match against a known alias?) + │ │ ├─ Additional identifiers (passport #, tax ID, DUNS, vessel IMO#) + │ │ └─ Prior transaction history (known good customer for 10 years?) + │ ├─ FALSE POSITIVE (high confidence) → Document adjudication rationale. + │ │ Record: who adjudicated, date, factors considered, conclusion. + │ │ Proceed with transaction. STOP. + │ ├─ POSSIBLE MATCH (ambiguous) → Continue to Step 5 + │ └─ TRUE POSITIVE (confirmed) → Continue to Step 6 + │ + ├─ Step 5: Escalate ambiguous matches + │ ├─ Request additional identifying information from the customer/counterparty + │ ├─ Engage compliance counsel + │ ├─ Do NOT proceed with the transaction until resolved + │ ├─ Document the hold and all steps taken + │ └─ If cannot be resolved → Treat as TRUE POSITIVE (Step 6) + │ + └─ Step 6: True positive — full stop + ├─ BLOCK the transaction immediately + ├─ SDN/OFAC match: + │ ├─ Block and report to OFAC within 10 business days + │ ├─ Do not release goods, do not process payment, do not communicate + │ │ the reason to the blocked party + │ └─ Determine if an OFAC licence is available and warranted + ├─ Entity List match: + │ ├─ Determine licence requirement (most are "presumption of denial") + │ ├─ If a licence exception is available, document the basis + │ └─ If no exception, apply for a BIS licence (expect 60-90 day processing) + ├─ Denied Persons List match: + │ ├─ ABSOLUTE prohibition — no licence available + │ └─ No exports, re-exports, or in-country transfers to denied persons + ├─ Notify compliance officer and legal counsel + ├─ Document EVERYTHING — the hit, the adjudication, the decision, the block + └─ Retain records indefinitely for DPL; 5 years minimum for others +``` + +### 4.2 Red Flag Indicators — Enhanced Due Diligence Triggers + +When any of the following red flags are present, standard screening is insufficient. Conduct +enhanced due diligence before proceeding: + +| Red Flag | What It Suggests | Required Action | +|---|---|---| +| Customer declines to state end use | Diversion risk | Require end-use certificate or decline the transaction | +| Unusual routing (e.g., electronics shipped Lagos→Dubai→Baku) | Sanctions evasion / diversion to embargoed destination | Map the full supply chain; verify the final destination | +| Customer willing to pay cash for high-value capital goods | Money laundering or sanctions circumvention | Enhanced KYC; verify source of funds | +| Delivery to P.O. Box, residential address, or free trade zone | Concealment of true end user | Require physical street address and site visit if >$50K | +| Product capability exceeds stated end use | Military/WMD diversion | Verify end-use statement matches the product specification | +| Customer has no Internet presence or verifiable business history | Shell company or front for sanctioned entity | Company registration check, D&B report, beneficial ownership analysis | +| Order for spare parts inconsistent with installed base | Stockpiling for embargoed destination | Request installed-base details; verify service history | +| Customer requests removal of product labelling or markings | Circumvention of end-use controls or trademark fraud | Decline the request and escalate to compliance | +| Customer or forwarding agent was previously flagged | Repeat compliance risk | Senior compliance review before any transaction | +| Payment from a third party or country not involved in the transaction | Sanctions evasion through financial intermediaries | Verify the commercial rationale for the payment structure | + +--- + +## 5. Penalty Risk Assessment + +### 5.1 US Penalty Framework — Detailed Analysis + +**19 USC § 1592 — Penalties for Fraud, Gross Negligence, and Negligence:** + +| Element | Fraud | Gross Negligence | Negligence | +|---|---|---|---| +| **Mental state** | Intentional and knowing violation with intent to defraud | Conscious disregard of a known duty or gross indifference | Failure to exercise reasonable care | +| **Maximum penalty** | Domestic value of the merchandise | 4× lost revenue, or 40% of dutiable value | 2× lost revenue, or 20% of dutiable value | +| **Criminal referral** | Yes — up to $10K fine and 2 years per count (18 USC § 542) | Rare | No | +| **Proof burden** | CBP must prove fraud by clear and convincing evidence | CBP must prove by preponderance of the evidence | CBP must prove by preponderance; importer must show reasonable care | +| **Mitigation potential** | Limited — requires extraordinary cooperation | Moderate — compliance programme, disclosure, cooperation | Significant — first offence, corrective actions, small scale | +| **Prior disclosure effect** | Caps penalty at 1× lost revenue (if accepted) | Caps penalty at 1× lost revenue | Caps penalty at interest on the unpaid duties | +| **Statute of limitations** | 5 years from date of violation | 5 years | 5 years | + +**Penalty Mitigation Factors (per CBP's Mitigation Guidelines):** + +1. **Contributory CBP error:** Did CBP accept prior entries with the same error without comment? +2. **Cooperation:** Full cooperation with the investigation, including production of records and + internal investigation findings +3. **Immediate corrective action:** Did the importer fix the problem as soon as it was discovered? +4. **Prior good record:** Clean compliance history for 5+ years +5. **Inability to pay:** Financial hardship (documented) can reduce monetary penalties +6. **Scale of violation:** Isolated incident vs systemic pattern +7. **Compliance programme:** Existence and effectiveness of an internal compliance programme + +### 5.2 Prior Disclosure Decision Framework + +``` +START: You have discovered a potential customs violation + │ + ├─ Step 1: Assess — Has CBP already commenced an investigation? + │ ├─ YES (you've received a CF-28 Request for Information, CF-29 Notice of Action, + │ │ pre-penalty notice, or Focused Assessment notification) → + │ │ Prior disclosure is still available UNTIL a formal investigation has commenced. + │ │ A CF-28/29 alone does not constitute commencement. A pre-penalty notice does. + │ │ ├─ Pre-penalty notice or formal investigation commenced → Prior disclosure + │ │ │ is NOT available. Respond to the notice with legal counsel. STOP. + │ │ └─ Only CF-28/29 → Prior disclosure is still available. Continue. + │ └─ NO → Prior disclosure is available. Continue to Step 2. + │ + ├─ Step 2: Determine the nature and scope of the violation + │ ├─ Classification error → How many entries are affected? Calculate total duty differential. + │ ├─ Valuation error → Quantify the underdeclared value and the corresponding duty impact. + │ ├─ Origin misstatement → Identify all affected entries and the correct origin. + │ ├─ FTA over-claim → Calculate the duty that should have been paid without the preference. + │ ├─ Record-keeping failure → Identify what records are missing and for which entries. + │ └─ Other → Define the specific violation and quantify the duty impact. + │ + ├─ Step 3: Evaluate prior disclosure vs. alternative strategies + │ ├─ Prior disclosure IS advisable when: + │ │ ├─ The violation is clear-cut and the duty shortfall is quantifiable + │ │ ├─ You are confident CBP has not yet begun investigating this issue + │ │ ├─ The penalty exposure is material (prior disclosure caps it at interest/1×) + │ │ └─ The violation involves negligence or gross negligence (not fraud) + │ ├─ Prior disclosure may NOT be advisable when: + │ │ ├─ The classification or valuation position is defensible and you are prepared to litigate + │ │ ├─ The amount at issue is de minimis (the administrative cost of disclosure exceeds benefit) + │ │ ├─ The violation is uncertain — you may be disclosing something that isn't actually wrong + │ │ └─ The disclosure would reveal other issues CBP is unaware of (consult counsel first) + │ └─ ALWAYS consult legal counsel before filing. Prior disclosure is an admission of violation. + │ + ├─ Step 4: Prepare the prior disclosure + │ ├─ Required elements (19 CFR § 162.74): + │ │ ├─ Identify the entry numbers and dates of all affected entries + │ │ ├─ Describe the specific violation (what was wrong) + │ │ ├─ Provide the correct information (what should have been declared) + │ │ ├─ Identify the circumstances that led to the violation (how it happened) + │ │ ├─ Calculate the duty owed with interest + │ │ └─ Tender the full amount of unpaid duties (or explain why you cannot calculate exactly + │ │ and provide a good-faith estimate with a commitment to pay the final amount) + │ ├─ File with the FP&F office at the port of entry (or the CEE with jurisdiction) + │ └─ Retain a copy with proof of delivery + │ + └─ Step 5: Post-filing + ├─ CBP will review the disclosure and may request additional information + ├─ If accepted, you will receive a penalty notice limited to interest (negligence) or + │ 1× lost revenue (gross negligence) + ├─ If rejected (disclosure was incomplete, or investigation had already commenced), + │ full penalty exposure returns + └─ Implement corrective measures to prevent recurrence — CBP will look at this if + another violation occurs +``` + +### 5.3 Export Control Penalty Framework + +**BIS (EAR) Penalties:** +- Civil: Up to $330,198 per violation OR twice the value of the transaction, whichever is greater + (adjusted annually for inflation) +- Criminal: Up to $1,000,000 per violation and 20 years imprisonment +- Denial of export privileges: automatic bar from all exports/re-exports from the US + +**DDTC (ITAR) Penalties:** +- Civil: Up to $1,301,256 per violation (adjusted annually) +- Criminal: Up to $1,000,000 per violation and 20 years imprisonment +- Debarment from all ITAR-controlled exports + +**OFAC Penalties:** +- Vary by sanctions programme, but civil penalties can exceed $330,000 per violation for + IEEPA-based sanctions +- Criminal: up to $1,000,000 and 20 years imprisonment under IEEPA +- Strict liability for OFAC violations — no intent required for civil penalties + +--- + +## 6. Post-Entry Audit Preparation + +### 6.1 CBP Focused Assessment Preparation Checklist + +When a CBP Focused Assessment is announced, the following preparation is critical: + +**Documentation to assemble:** +- [ ] Internal compliance manual / SOP documentation +- [ ] Organisational chart showing compliance function reporting lines +- [ ] Training records for all personnel involved in import operations +- [ ] Customs broker power of attorney and instructions +- [ ] Classification decisions with supporting rationale (for sample entries) +- [ ] Valuation documentation including assist calculations and related-party analysis +- [ ] FTA qualification files with supplier certifications +- [ ] Restricted party screening logs with adjudication records +- [ ] Reconciliation entries (if applicable) +- [ ] Prior disclosures filed (if any) +- [ ] Internal audit reports for the past 3 years +- [ ] Record retention policy and evidence of compliance + +**Pre-assessment self-audit:** +1. Pull 50 representative entries spanning the audit period +2. Re-classify the top 20 by value — does the classification still hold? +3. Re-value 10 entries including related-party transactions — are assists captured? +4. Verify FTA claims on 10 entries — is the origin documentation complete? +5. Re-screen all parties from 10 entries — any new hits since original screening? +6. Identify and disclose any errors found BEFORE the FA team arrives (prior disclosure still available) + +--- + +## 7. Incoterms Decision Matrix + +### 7.1 Selecting the Appropriate Incoterm + +| Consideration | Recommended Incoterm | Rationale | +|---|---|---| +| Buyer wants maximum control over logistics | FCA | Buyer chooses carrier, route, and insurance. Seller handles export formalities. | +| Seller has better freight rates (economy of scale) | CIF / CIP | Seller leverages volume contracts. Buyer bears risk from first carrier. | +| Buyer cannot act as exporter in seller's country | FCA, CPT, CIP, DAP, DDP | Avoid EXW — it makes the buyer the exporter of record in the origin country. | +| Buyer lacks import capability in destination | DDP | Seller handles everything including import clearance. Seller must register as IOR. | +| Letter of credit requires on-board BOL | FCA (with 2020 A6/B6 option) | The 2020 revision allows buyer to instruct carrier to issue on-board BOL to seller. | +| High-risk transit (theft, damage, piracy corridor) | CIF / CIP | Seller is responsible for insurance. CIP requires all-risks coverage (ICC A). | +| Containerised ocean freight | FCA, CPT, CIP | FOB is technically incorrect for containers — risk transfers at container yard, not ship's rail. | +| Domestic delivery (same country) | FCA, DAP | Incoterms are not required for domestic; if used, FCA or DAP are appropriate. | + +### 7.2 Incoterms and Customs Valuation Impact + +The Incoterm affects the customs value because different terms include or exclude freight and +insurance in the invoice price: + +| Incoterm | US Customs Value Adjustment | EU Customs Value Adjustment | +|---|---|---| +| EXW | ADD: inland freight to port + international freight + insurance to US port | ADD: inland freight to port + international freight + insurance to EU border | +| FCA | ADD: international freight + insurance from named place to US port | ADD: international freight + insurance from named place to EU border | +| FOB | ADD: ocean freight + insurance to US port (already includes inland to port) | ADD: ocean freight + insurance to EU border | +| CFR/CPT | ADD: insurance (freight already included) | ADD: insurance (freight already included) | +| CIF/CIP | No adjustment (freight and insurance included) | No adjustment (freight and insurance included) | +| DAP | DEDUCT: inland freight from port/airport to final destination in US (if identifiable) | DEDUCT: inland freight from EU border to destination | +| DDP | DEDUCT: inland freight + import duties (duty is never part of customs value) | DEDUCT: inland freight from EU border + import duties | diff --git a/web-app/public/skills/customs-trade-compliance/references/edge-cases.md b/web-app/public/skills/customs-trade-compliance/references/edge-cases.md new file mode 100644 index 00000000..69b90747 --- /dev/null +++ b/web-app/public/skills/customs-trade-compliance/references/edge-cases.md @@ -0,0 +1,362 @@ +# Customs & Trade Compliance — Edge Cases Reference + +> Tier 3 reference. Load on demand when handling complex or ambiguous trade compliance situations that don't resolve through standard workflows. + +These edge cases represent the scenarios that separate experienced trade compliance professionals from everyone else. Each one involves competing regulatory frameworks, ambiguous fact patterns, multi-jurisdictional complexity, and real financial exposure. They are structured to guide resolution when standard procedures break down. + +--- + +## How to Use This File + +When a trade compliance question doesn't fit a clean category — when classification is genuinely ambiguous, when origin is disputed, when multiple regulatory regimes apply simultaneously, or when the financial exposure justifies deeper analysis — find the edge case below that most closely matches the situation. Follow the expert approach step by step. Do not skip documentation requirements; these are the cases that end up before administrative law judges, in penalty proceedings, or in criminal referrals. + +--- + +### Edge Case 1: De Minimis Threshold Exploitation — Section 321 Abuse + +**Situation:** +A mid-size e-commerce retailer imports consumer electronics from Shenzhen. Their freight forwarder suggests restructuring ocean freight consolidations into individual direct-to-consumer parcels, each valued under $800, to clear under Section 321 de minimis and avoid the 25% Section 301 duty on List 3 goods. The retailer currently imports approximately 15,000 units per month at a declared value of $45 per unit (total duty exposure: approximately $168,750/month at 25%). The forwarder's proposal would route parcels through a fulfilment centre in China that ships individual packages via ePacket/USPS to US consumers. + +**Why It's Tricky:** +The de minimis threshold is per importation, per person, per day. On its face, individual shipments valued at $45 each qualify. But CBP has increasingly targeted structured de minimis programmes, and the Consolidated Appropriations Act of 2016 gave CBP expanded enforcement authority. Several factors complicate this: + +- If the retailer is the importer of record for all packages (not the individual consumers), CBP can aggregate all packages arriving on the same day as a single importation +- Section 321 does NOT exempt goods subject to AD/CVD orders, quotas, or certain PGA requirements (FDA, CPSC, EPA) — only the duty is waived +- If the electronics require FCC certification, each unit still needs to comply regardless of de minimis status +- CBP's e-commerce enforcement strategy specifically targets "daigou" and structured de minimis programmes + +**Common Mistake:** +Assuming that Section 321 is a simple value threshold. Many importers and their forwarders treat it as a binary: under $800, no duty. But the aggregation rules, PGA requirements, and enforcement posture make structured programmes a significant compliance risk. CBP has issued penalty cases exceeding $1M against importers who structured shipments to exploit de minimis. + +The second mistake: ignoring state sales tax and marketplace facilitator obligations. Even if federal duty is avoided, the retailer may have nexus obligations in destination states that offset some of the savings. + +**Expert Approach:** +1. Assess whether the individual consumers are genuinely the importers of record. If the retailer controls the logistics, owns the inventory in transit, and bears the risk of loss, the retailer is the IOR — not the consumer. This makes aggregation almost certain. +2. Review the specific HS codes for AD/CVD applicability. Electronics are generally not subject to AD/CVD, but certain components (e.g., crystalline silicon PV cells, certain steel enclosures) may be covered. +3. Check PGA requirements. Consumer electronics almost certainly require FCC Declaration of Conformity. Lithium batteries require DOT/PHMSA compliance. Children's products require CPSC testing. None of these are waived by Section 321. +4. Calculate the true savings vs risk. The duty savings of $168,750/month must be weighed against: (a) per-unit shipping cost increase (ocean FCL at $0.35/unit vs ePacket at $3-5/unit), (b) compliance risk (penalty exposure under 19 USC § 1592 for structured evasion), (c) transit time increase (30-45 days ocean + inland vs 14-21 days ePacket but no inventory buffer), (d) customer experience impact (inconsistent delivery times, returns complexity). +5. If the economics still favour de minimis after honest analysis, structure it properly: each consumer must be the IOR, the retailer should use a compliant Section 321 filing programme (not just undervalue or misdeclare), and all PGA requirements must be satisfied per shipment. +6. Document the business rationale and legal analysis thoroughly. If CBP challenges the programme, the difference between "structured evasion" (penalty) and "legitimate programme" (defensible) is documentation of good-faith compliance effort. + +**Key Indicators:** +- CBP's COAC subcommittee on Section 321 has recommended enhanced data requirements — anticipate changes +- Multiple packages to the same address on the same day from the same shipper will be flagged +- The STOP Act of 2018 requires electronic advance data for all international mail shipments — the "under the radar" strategy no longer works + +--- + +### Edge Case 2: Transshipment Circumventing AD/CVD Duties — EAPA Investigation + +**Situation:** +A US furniture importer purchases wooden bedroom furniture "manufactured in Vietnam" from a Vietnamese trading company. The unit price is $180 FOB Ho Chi Minh City, which is 40% below comparable Vietnamese production costs. Coincidentally, Chinese-origin wooden bedroom furniture is subject to AD/CVD duties totalling 216.01% (combined AD duty of 198.08% + CVD of 17.93%) under A-570-890. CBP initiates an EAPA (Enforce and Protect Act) investigation based on an allegation from a domestic manufacturer. + +**Why It's Tricky:** +The EAPA process gives CBP subpoena authority and the ability to impose interim measures (cash deposits at the AD/CVD rate) within 90 days. The importer must prove that the goods are genuinely of Vietnamese origin — which requires demonstrating "substantial transformation" in Vietnam. The test is whether the processing in Vietnam results in "a new and different article of commerce with a new name, character, and use." + +Vietnamese furniture factories that merely assemble Chinese-manufactured components (pre-cut panels, pre-finished parts) into finished furniture are almost certainly NOT performing substantial transformation. But factories that take raw lumber (even Chinese-origin lumber), mill it, join it, finish it, and assemble it in Vietnam likely ARE performing substantial transformation, because the raw lumber has been transformed into a finished article with a different name, character, and use. + +The grey area is where the Vietnamese factory receives semi-finished components (rough-cut panels, unfinished drawer boxes) and performs significant but not complete processing (sanding, finishing, assembly, quality control, packaging). This is where most disputes land. + +**Common Mistake:** +Relying on the certificate of origin from the Vietnamese chamber of commerce as proof of origin. Certificates of origin attest to the country of EXPORTATION, not the country of substantial transformation. CBP will look through the certificate to the actual manufacturing process. + +The second mistake: waiting for CBP to ask questions before investigating your own supply chain. If CBP is conducting an EAPA investigation against your supplier, the best position is to have already audited the supply chain and be able to present a documented analysis. + +**Expert Approach:** +1. Immediately retain trade counsel experienced in AD/CVD and EAPA proceedings. The timelines are short and the penalties are severe (retroactive application of AD/CVD rates to all entries, plus potential fraud referral). +2. Request from the Vietnamese supplier: (a) complete bill of materials showing the origin of all inputs, (b) production flow chart from raw material receipt to finished goods shipment, (c) cost of production analysis showing the value added in Vietnam, (d) photographs and video of the production process, (e) list of Chinese-origin inputs by HS code and value. +3. Apply the substantial transformation test. Map each Chinese-origin input through the Vietnamese production process. Determine: does the finished furniture have a different name (yes — "lumber" → "bedroom set"), different character (depends on the degree of processing), and different use (raw lumber has construction and industrial uses; finished furniture has a consumer use)? All three must change. +4. Calculate the value added in Vietnam as a percentage of the FOB price. While there's no statutory minimum, CBP generally views less than 30% value addition with suspicion. If the Vietnamese factory's value addition (labour, overhead, materials consumed, profit) is less than 30% of the export price, the substantial transformation argument is weak. +5. If the supply chain analysis reveals that the goods are effectively Chinese-origin with minimal Vietnamese processing, consider: (a) voluntary disclosure to CBP (prior disclosure of AD/CVD evasion caps penalties), (b) restructuring the supply chain to use a Vietnamese factory with genuine manufacturing capability, (c) sourcing from a non-subject country with genuine production. +6. If the supply chain analysis supports genuine Vietnamese origin, compile the documentation package and be prepared to present it to CBP within the EAPA timeline. Proactive submission of evidence carries significant weight with CBP investigators. + +**Key Indicators:** +- Unit price significantly below production cost in the alleged country of origin is a primary trigger for EAPA complaints +- Vietnam, Malaysia, Thailand, and Indonesia are the top countries for transshipment allegations on Chinese AD/CVD goods +- CBP may conduct on-site verification at the Vietnamese factory — prepare the factory for a CBP visit +- CBP's Allegations Management and Tracking System (AMATS) allows domestic producers to file electronically — expect more allegations + +--- + +### Edge Case 3: Dual-Use Goods — EAR/ITAR Jurisdictional Boundary + +**Situation:** +A US manufacturer produces high-precision CNC milling machines with 5-axis simultaneous contouring capability and positioning accuracy of ±2 microns. The machines are sold commercially to automotive and aerospace manufacturers worldwide. A new customer in India requests a quote for 3 machines to be used in "precision component manufacturing." The machines have a commercial ECCN of 2B001.b.2 under the EAR (controlled for NP, NS, AT reasons). However, the machines could also be used in the production of missile components, and some configurations have historically been considered for ITAR control under USML Category IV (Launch Vehicles, Guided Missiles, Ballistic Missiles, Rockets, Torpedoes, Bombs, and Mines) — specifically, production equipment "specially designed" for USML items. + +**Why It's Tricky:** +This sits at the exact boundary between the EAR (administered by BIS, Department of Commerce) and the ITAR (administered by DDTC, Department of State). The Export Control Reform (ECR) initiative moved many items from the USML to the CCL, but the "specially designed" definition (§ 772.1 of the EAR) creates a complex exclusion/inclusion analysis. If the machine is classified under the ITAR, an export licence is almost certainly required for India and the end-use controls are far more restrictive. If it's under the EAR, a licence may or may not be required depending on the end user and end use. + +The critical determination is whether the machine is "specially designed" for USML articles. Under the ECR definition, an item is NOT "specially designed" if it meets any of the six "release" criteria in paragraph (b) of the definition — most importantly, (b)(3): the item "has a function other than" producing USML items and is "not a dedicated tool, jig, fixture, mould, or die." A general-purpose CNC mill that can make many types of precision components likely qualifies for the (b)(3) release. But if the specific configuration being sold is optimised for producing specific missile components, the release may not apply. + +**Common Mistake:** +Self-classifying the item under the EAR without formally resolving the jurisdictional question. If the item is ITAR-controlled and exported under an EAR classification, the exporter has committed violations of BOTH regimes — an unauthorised ITAR export AND a false EAR filing. The correct procedure when jurisdiction is unclear is to submit a Commodity Jurisdiction (CJ) request to DDTC. + +The second mistake: assuming that because the machine is sold commercially to many industries, it's automatically EAR-jurisdiction. Commercial availability is relevant but not dispositive. A commercially available item that is "specially designed" for USML applications is ITAR-controlled regardless of its commercial sales history. + +**Expert Approach:** +1. Conduct the "specially designed" analysis under the ECR definition for the SPECIFIC configuration being sold to the Indian customer. Document: (a) what are ALL the functions this machine configuration can perform? (b) is this configuration a "dedicated" production tool for any USML article, or a general-purpose machine? (c) does it meet any of the (b)(1) through (b)(6) release criteria? +2. If the analysis is clear (the machine is a general-purpose commercial product that meets the (b)(3) release), document the analysis and proceed with EAR classification. Confirm the ECCN (2B001.b.2) and determine the licence requirement for India. For NP-controlled items to India, a licence is likely required unless a licence exception applies. Check BIS's India entity list entries. +3. If the analysis is ambiguous (the configuration could be considered "specially designed"), file a CJ request with DDTC. Include: the item's technical specifications, its commercial applications, its potential USML applications, and your "specially designed" analysis. DDTC has 45 days to respond (often takes longer). +4. While the CJ is pending, do NOT ship the machines. Treat the item as ITAR-controlled until DDTC makes a determination. +5. Regardless of jurisdiction, conduct end-user due diligence on the Indian customer. The machines' accuracy (±2 microns) places them at or near the MTCR (Missile Technology Control Regime) Annex thresholds. Verify: (a) the customer's identity and business operations, (b) the stated end use is consistent with the customer's business, (c) the customer is not on any restricted party list, (d) there are no red flags suggesting missile programme diversion. +6. If the machines are EAR-jurisdiction and a licence is required, include the Indian customer's end-use statement and the complete technical specifications in the BIS licence application. Processing time is typically 30-60 days. +7. If the machines are ITAR-jurisdiction, apply for a DSP-5 export licence from DDTC. Processing time is typically 60-90 days, and India is subject to additional review for missile-related items. + +**Key Indicators:** +- 5-axis simultaneous contouring capability at ±2 microns places this firmly in the controlled range under both regimes +- India is a missile technology-sensitive destination — enhanced scrutiny is expected +- The phrase "precision component manufacturing" in the customer's end-use statement is too vague — require specificity +- If the customer refuses to specify the components being manufactured, this is a red flag under § 744.6 (General Prohibition Six) + +--- + +### Edge Case 4: Post-Importation Transfer Pricing Adjustments + +**Situation:** +A multinational pharmaceutical company imports active pharmaceutical ingredients (APIs) from its German parent company. The transfer price is set annually by the parent's tax department using the Comparable Profits Method (CPM) under OECD Transfer Pricing Guidelines. The US subsidiary imports approximately $200M in APIs annually. At fiscal year-end, the tax department determines that the US subsidiary's operating margin exceeded the arm's-length range and issues a downward transfer pricing adjustment of $18M (effectively reducing the price paid for the APIs retroactively). The US subsidiary's trade compliance team discovers that all entries during the fiscal year were declared at the higher, pre-adjustment value. + +**Why It's Tricky:** +Customs valuation and transfer pricing serve opposite purposes. Tax authorities want the transfer price to be high in low-tax jurisdictions and low in high-tax jurisdictions (to minimize global tax). Customs authorities want the declared value to be as high as possible (to maximize duties collected). A downward transfer pricing adjustment reduces the customs value — which means the importer overpaid duties and is entitled to a refund. An upward adjustment increases the customs value — which means the importer underpaid duties and owes additional payments plus potential penalties. + +CBP's position (articulated in multiple rulings) is that transfer pricing adjustments must be reflected in the customs value when they relate to the imported merchandise. But the mechanism for doing so — reconciliation entries — has specific procedural requirements that many importers miss. + +**Common Mistake:** +Ignoring the customs implications entirely because "transfer pricing is a tax issue." The trade compliance team often doesn't learn about year-end adjustments until months after they occur, by which time entries may have liquidated and the window for correction has closed. + +The second mistake: filing a PSC (Post Summary Correction) to reduce the declared value without proper documentation. CBP will challenge a downward correction on related-party entries unless the importer can demonstrate that the adjusted price satisfies the transaction value test under Method 1. + +**Expert Approach:** +1. Flag reconciliation at the time of importation. When the final price is not known at entry (as with transfer pricing that is subject to year-end adjustment), file entries with the reconciliation flag set. This preserves the right to adjust the declared value after liquidation under the reconciliation programme (19 CFR Part 181 Subpart D for USMCA, or Part 182 for general reconciliation). +2. When the transfer pricing adjustment is finalised, determine the direction and magnitude: + - Downward adjustment ($18M in this case): the importer overpaid duties. File reconciliation entries reducing the declared value and request a refund of excess duties paid. CBP will scrutinise the related-party circumstances of sale. + - Upward adjustment: the importer underpaid duties. File reconciliation entries increasing the declared value and tender the additional duties owed. This is effectively a prior disclosure of underpayment. +3. To support the adjusted value, prepare a "circumstances of sale" analysis demonstrating that the related-party relationship did not influence the price. This requires showing that the transfer pricing methodology produces a price consistent with arm's-length pricing. The CPM analysis from the tax department is helpful but not sufficient — CBP wants to see that the price approximates a "test value" (transaction value of identical/similar goods to unrelated buyers). +4. If reconciliation was NOT flagged at entry, file PSCs for entries within the liquidation period (typically 314 days from date of entry). For entries that have already liquidated, file a protest under 19 USC § 1514 within 180 days of liquidation. For entries beyond the protest period, the opportunity is lost. +5. Establish a standing protocol between the trade compliance and tax departments. Require that: (a) trade compliance is notified of all transfer pricing adjustments before they are finalised, (b) reconciliation is flagged on all related-party entries where the price may be adjusted, (c) the tax department's transfer pricing study is shared with trade compliance for customs valuation analysis. +6. For the $18M downward adjustment: at a 6.5% duty rate (common for APIs), the duty refund would be approximately $1.17M. The administrative cost of filing reconciliation is approximately $5,000-$15,000 (broker fees + internal time). The ROI is overwhelming — do not leave the refund on the table. + +**Key Indicators:** +- Related-party import volume > $50M annually almost guarantees that transfer pricing adjustments will occur +- CBP's Centers of Excellence and Expertise (Pharmaceutical CEE in New York) actively audits related-party valuations +- Reconciliation programme participation requires advance approval from CBP — apply before entry, not after +- The OECD's Two-Pillar Solution may change transfer pricing dynamics significantly — monitor developments + +--- + +### Edge Case 5: First Sale Valuation — Multi-Tier Supply Chain + +**Situation:** +A US apparel retailer sources private-label clothing through a Hong Kong buying agent. The supply chain is: Chinese factory sells to Hong Kong middleman at $8.00/unit (first sale), Hong Kong middleman sells to the US retailer at $12.50/unit (last sale). The goods ship directly from China to the US — they never physically pass through Hong Kong. The applicable duty rate is 19.7%. The retailer wants to declare the $8.00 first sale price as the customs value instead of the $12.50 last sale price, saving $0.89 per unit in duty (($12.50 - $8.00) × 19.7% = $0.89). At 2 million units annually, this is $1.78M in annual duty savings. + +**Why It's Tricky:** +The "first sale rule" derives from the US Court of International Trade's decision in Nissho Iwai American Corp. v. United States (1982). CBP allows the use of the first sale as the transaction value when: (1) the first sale is a bona fide sale for export to the US, (2) the sale is at arm's length, and (3) the price of the first sale is the appropriate measure of the value of the goods when they enter the US. + +The challenge is proving all three elements, especially when the middleman adds no physical processing — the goods ship directly from factory to US. CBP scrutinises these arrangements because the middleman's margin (here, $4.50/unit or 56% markup) is significant and may include services that should be additions to the customs value rather than excludable middleman profit. + +**Common Mistake:** +Claiming first sale without maintaining contemporaneous documentation of the factory-to-middleman sale. CBP requires that the first sale be documented with its own commercial invoice, payment records, and shipping instructions that demonstrate it is a genuine sale separate from the middleman-to-importer sale. + +The second mistake: failing to account for assists. If the US retailer provides design specifications, tech packs, or quality standards directly to the Chinese factory (bypassing the middleman), these are assists that must be added to the first sale price. Many first sale programmes collapse during audit because the assists were not valued. + +**Expert Approach:** +1. Verify the first sale is a genuine arm's-length transaction. Required documentation: + - Separate commercial invoice from the Chinese factory to the Hong Kong middleman + - Evidence of payment from the middleman to the factory (bank records) + - The factory invoice must pre-date or be contemporaneous with the middleman's invoice to the US retailer + - Shipping instructions showing the goods were shipped FOR the middleman (not just invoiced through the middleman) +2. Analyse the middleman's role. Legitimate first sale structures involve a middleman who: bears title risk, carries inventory risk (even briefly), can independently choose suppliers, negotiates prices independently with both the factory and the buyer, and provides genuine services (sourcing, quality control, logistics coordination). A middleman who is merely invoicing without bearing commercial risk is not a genuine seller — it's a conduit. +3. Identify all assists flowing from the US retailer to the factory. Every tech pack, design file, sample, lab testing result, or quality inspection provided by the retailer is an assist. Compute the total value and add it to the first sale price. If assists exceed $2.50/unit, the effective first sale price rises to $10.50 and the savings diminish significantly. +4. Calculate the actual duty savings after all adjustments: + - Last sale value: $12.50 → Duty: $2.4625 + - First sale value (with assists): $8.00 + $1.80 assists = $9.80 → Duty: $1.9306 + - Net savings per unit: $0.5319 × 2M units = $1,063,800/year + - Programme administration cost: approximately $50,000/year (broker fees, documentation, monitoring) + - Net benefit: approximately $1,013,800/year +5. Prepare a first sale ruling request to CBP if the programme exceeds $500K in annual duty savings. A binding ruling provides certainty and significantly reduces audit risk. Include all documentation from steps 1-4. +6. Monitor the programme quarterly. If the middleman's margin changes significantly, or if the retailer begins providing additional assists, the first sale analysis must be updated. + +**Key Indicators:** +- First sale is ONLY available in the US, Israel, and Australia — the EU, UK, Canada, and most other jurisdictions value on the last sale before importation +- CBP has revoked first sale treatment in multiple audits where documentation was insufficient +- If the middleman is related to the factory, first sale treatment is extremely difficult to defend +- The middleman's markup should reflect genuine commercial services — a 56% markup requires explanation of what services justify that margin + +--- + +### Edge Case 6: Retroactive FTA Claims — Missed Preferential Treatment + +**Situation:** +An internal audit reveals that a US electronics manufacturer has been importing circuit board assemblies from Mexico at the MFN rate of 3.4% for the past 3 years without claiming USMCA preferential treatment. The assemblies qualify for duty-free treatment under USMCA because they undergo a tariff shift from heading 8534 (printed circuits) to heading 8538 (parts for switching apparatus) in Mexico — all non-originating materials (capacitors from Japan, resistors from Korea) change at the heading level. The company imports approximately $15M annually; the overpaid duty totals approximately $1.53M over 3 years. + +**Why It's Tricky:** +USMCA allows retroactive preferential claims, but the mechanism and timeline vary depending on how the entries were filed and whether they have liquidated: + +- Entries within the liquidation period (typically 314 days from entry): file a PSC (Post Summary Correction) claiming USMCA preference and attaching the certification of origin +- Entries that have liquidated but are within the 180-day protest window: file a protest under 19 USC § 1514 +- Entries that have liquidated AND the protest period has expired: file a petition for reliquidation under 19 USC § 1520(d), which allows up to 1 year from the date of liquidation + +After these windows close, the duties are permanently overpaid. + +**Common Mistake:** +Assuming all 3 years of entries can be recovered. In practice, the oldest entries have almost certainly passed all available windows. The recoverable amount depends on when exactly each entry liquidated, which varies by port and processing time. + +The second mistake: filing a USMCA certification of origin retroactively without verifying that the goods actually qualified at the time of importation. If the bill of materials changed during the 3-year period (e.g., a supplier switched from a Japanese capacitor to a Chinese capacitor), the tariff shift analysis must be performed for each period with different inputs. + +**Expert Approach:** +1. Pull every entry for the 3-year period. For each entry, determine: (a) entry date, (b) liquidation date (check ACE or request from broker), (c) whether liquidation has occurred, (d) whether the protest period has expired. +2. Categorise entries into three buckets: + - Recoverable via PSC (unliquidated): file immediately, no reason to wait + - Recoverable via protest (liquidated < 180 days ago): file protests immediately — the clock is ticking + - Recoverable via 1520(d) petition (liquidated 180 days - 1 year ago): file petitions + - Non-recoverable (liquidated > 1 year ago): document the loss and move on +3. For each recoverable entry, prepare or obtain the USMCA certification of origin. Under USMCA, the certification can be prepared by the exporter, producer, or importer — the importer can self-certify based on their knowledge of the production process and bill of materials. The certification must include all nine data elements required by Article 5.2. +4. Verify qualification for each entry period. Obtain the bill of materials from the Mexican producer for each shipment period. Confirm that ALL non-originating materials changed at the heading level. If any material's HS classification is in the same heading as the finished good (8538), that material must be originating or subject to a de minimis exception. +5. File all claims simultaneously (or in quick succession) to avoid the perception of cherry-picking. Include a cover letter explaining that the claims result from a compliance audit and that the company is implementing corrective measures to claim USMCA preference on future entries. +6. Implement a go-forward process: (a) add USMCA qualification review to the new-product sourcing workflow, (b) require the customs broker to flag all Mexico-origin entries for preference screening, (c) conduct annual reviews of HS code changes that may affect qualification. + +**Key Indicators:** +- $1.53M in recoverable duties makes this a high-priority recovery project — assign dedicated resources +- USMCA certifications do not need to be on a specific form — they can be on the commercial invoice, a separate document, or even in electronic format +- If the Mexican supplier's bill of materials has changed over 3 years, you may need multiple certifications covering different periods +- CBP may audit retroactive claims — maintain complete documentation of the qualification analysis + +--- + +### Edge Case 7: Temporary Imports That Become Permanent — ATA Carnet Breach + +**Situation:** +A European medical device company brings 6 demonstration units of a surgical laser system (value: €120,000 each, €720,000 total) to the US under an ATA Carnet for a 2-week medical conference and hands-on training programme. During the event, a major US hospital chain expresses interest in purchasing 3 of the 6 units immediately. The sales team, seeing an opportunity, negotiates a sale on the spot and instructs the logistics team to deliver 3 units to the hospital instead of re-exporting them. The carnet expires in 60 days. + +**Why It's Tricky:** +ATA Carnets provide temporary duty-free and tax-free admission on the strict condition that the goods will be re-exported. Selling goods admitted under a carnet is a fundamental breach — the goods were imported duty-free and are now entering US commerce without paying duty. The violations compound: + +1. The carnet guarantee (issued by the US Council for International Business, backed by the ICC World Chambers Federation) will be called for the 3 units not re-exported — the European chamber of commerce that issued the carnet is liable +2. The importing company owes duty, applicable taxes (federal + state), and likely penalties for failure to make entry under the correct customs procedure +3. The sale may violate the terms of the FDA clearance/approval — if the devices were imported for "demonstration only," they may not have the required FDA status for commercial distribution +4. Any applicable section 301, AD/CVD, or other special duties apply in addition to the regular duty rate + +**Common Mistake:** +Thinking that simply "paying the duty" fixes the problem. The carnet system is a multilateral guarantee arrangement involving the exporting country's chamber, the importing country's customs authority, and the international guarantee chain. A breach triggers administrative proceedings in both countries and may result in the company being barred from future carnet use. + +The second mistake: ignoring the FDA regulatory implications. Surgical lasers are typically Class II or III medical devices requiring 510(k) clearance or PMA. Demonstration units imported under a carnet may not have been cleared for commercial distribution — they were admitted for the specific purpose stated on the carnet (exhibition/demonstration). Selling them for clinical use may be an FDA violation independent of the customs violation. + +**Expert Approach:** +1. Do not deliver the 3 units to the hospital. Halt the sale immediately. The cost of unwinding the customs violation and FDA issues far exceeds the revenue from 3 units. +2. Re-export all 6 units as planned under the carnet. Have the carnet properly endorsed by CBP on departure. +3. For the 3 units the hospital wants to purchase, arrange a separate commercial importation: (a) file a formal entry (CBP 7501) with proper classification, valuation, and duty payment, (b) ensure FDA compliance — either import under the existing 510(k)/PMA clearance for the device, or file a new entry with the appropriate FDA affirmation of compliance, (c) use the correct Incoterms for the commercial transaction (likely DDP if the European company is handling everything). +4. If units have already been delivered to the hospital (the logistics team acted on the sales team's instructions before compliance could intervene): (a) contact a customs broker immediately to file a consumption entry retroactively — this is a "late filing" violation but far better than a "no filing" violation, (b) pay all applicable duties with interest, (c) notify the carnet-issuing chamber that 3 units will not be re-exported and that a formal entry is being filed, (d) file a prior disclosure if the late filing triggers a penalty assessment, (e) conduct a separate FDA analysis — if the devices are not cleared for commercial distribution in the US, they may need to be recalled from the hospital pending clearance. +5. Implement sales team training: carnet goods CANNOT be sold during the temporary import period. Any sale requires a new import transaction. This is non-negotiable and must be part of sales operations SOP for international demonstrations. + +**Key Indicators:** +- The US duty rate for surgical laser systems (HS 9018.90) is typically 0% — but this doesn't eliminate the filing requirement, MPF, or FDA compliance +- ATA Carnet claims can take 18-24 months to resolve through the ICC guarantee chain +- Repeated carnet breaches can result in the issuing chamber refusing to issue future carnets +- FDA enforcement of "demonstration only" imports has increased — especially for high-risk devices + +--- + +### Edge Case 8: Classification of Kits vs Components — GRI 3(b) Application + +**Situation:** +A US retailer imports a "Home Barista Coffee Kit" from Italy. The kit contains: an espresso machine (HS 8419.81, duty 3.4%), a burr coffee grinder (HS 8509.40, duty 4.2%), a milk frothing pitcher (HS 7323.93, duty 3.4%), a tamper (HS 8210.00, duty 0.4¢ each + 6.4%), two espresso cups with saucers (HS 6912.00, duty 9.8%), and a 250g bag of espresso beans (HS 0901.21, duty free). All items are packaged together in a branded retail box. + +**Why It's Tricky:** +The items span 6 different HS chapters with duty rates ranging from 0% to 9.8%. If classified as a set under GRI 3(b), the entire kit takes a single classification determined by the component giving essential character. If classified individually, each item is entered separately at its own rate. + +The importer wants the kit classified as a set under the espresso machine heading (8419.81) at 3.4% duty — arguing the espresso machine gives essential character because it is the highest-value component and the primary reason consumers purchase the kit. CBP may argue the items should be classified individually because: (a) the items are independently functional and sold separately in the market, (b) the "kit" is merely a marketing assortment, not a "set put up for retail sale" meeting GRI 3(b)'s requirements. + +**Common Mistake:** +Assuming that packaging items together automatically creates a "set" for customs purposes. GRI 3(b) has three specific requirements that ALL must be met: (1) at least two different articles classifiable in different headings, (2) articles put together to meet a particular need or carry out a specific activity, and (3) put up in a manner suitable for sale directly to users without repacking. + +The second mistake: ignoring the possibility that CBP may argue GRI 3(b) doesn't apply because the espresso machine alone meets the "particular need" (making espresso), and the other items are merely accessories packed with it for marketing purposes. + +**Expert Approach:** +1. Analyse each GRI 3(b) requirement: + - Condition 1 (different headings): Satisfied — items span 6 different headings. + - Condition 2 (particular need or specific activity): Arguable. "Home espresso preparation" is a specific activity, and all items contribute to that activity. The cups, frothing pitcher, and tamper are directly used in espresso service. The grinder prepares the beans. The beans are the consumable. This condition is likely met. + - Condition 3 (put up for retail sale): Satisfied if the packaging is retail-ready (branded box, UPC code, retail pricing). If the items are loose in a plain brown carton, this condition fails. +2. Determine essential character. The espresso machine is the highest-value component (likely 60-70% of the kit's total value) and is the functional core of the kit — without it, the other items serve no coordinated purpose. Strong argument for the espresso machine as essential character. +3. Consider the duty impact. If classified as a set at 3.4% (espresso machine rate), the weighted average duty is lower than if the items are classified individually (where the ceramic cups at 9.8% pull the average up). Quantify the difference to determine whether the classification dispute is worth pursuing. +4. Search the CBP CROSS database for prior rulings on similar kits. CBP has ruled on numerous "sets" — coffee sets, beauty kits, tool kits, art supply sets. Prior rulings provide strong guidance even if not directly on point. +5. If the duty differential is significant, consider requesting a binding ruling from CBP. Include photographs of the retail packaging, the itemised bill of materials with individual values, and a detailed GRI 3(b) analysis. +6. Alternative strategy: if set classification is denied, consider whether "duty engineering" — sourcing the high-duty components (ceramic cups) from an FTA partner country — would reduce overall duty more effectively than the set argument. + +**Key Indicators:** +- CBP tends to deny set treatment when the components are independently marketable commodity items +- CBP is more likely to grant set treatment when the components are specially designed to work together and are not sold separately +- The bag of coffee beans creates a perishability issue — it may need separate entry with FDA prior notice regardless of set classification +- Italian-origin goods qualify for zero duty under certain headings if the EU-US tariff negotiations (currently suspended) resume + +--- + +### Edge Case 9: Mis-Declared Country of Origin — Marking Violations + +**Situation:** +A US importer of consumer electronics discovers that their Chinese supplier has been shipping Bluetooth speakers labelled "Designed in California, Assembled in Malaysia" when in fact the speakers are 100% manufactured in China. The Malaysian facility only repackages the products into retail boxes. Over the past 18 months, the importer has entered approximately $4.2M in speakers at the MFN rate applicable to Malaysian-origin goods, avoiding the 25% Section 301 tariff on Chinese-origin goods. + +**Why It's Tricky:** +This is a marking violation (19 USC § 1304) and a false country of origin declaration — both carry separate and compounding penalties. The marking violation alone can result in 10% additional duty plus seizure. The false origin declaration triggers 19 USC § 1592 penalties (negligence, gross negligence, or fraud depending on what the importer knew). And the Section 301 duty avoidance is independently actionable as an AD/CVD evasion matter under EAPA if CBP initiates proceedings. + +The importer's exposure calculation: +- Section 301 duties avoided: $4.2M × 25% = $1,050,000 +- Marking penalty: 10% of $4.2M = $420,000 +- 19 USC § 1592 penalty: up to $4.2M (domestic value) for fraud; $1,680,000 for gross negligence; $840,000 for negligence +- Total worst-case exposure: $6.3M+ plus seizure of in-transit goods + +**Common Mistake:** +Blaming the supplier and hoping CBP doesn't notice. CBP holds the importer of record responsible for the accuracy of all entry information, including country of origin. "My supplier told me it was Malaysian" is not a defence — it is evidence of negligent reliance on a supplier without verification. + +The second mistake: continuing to import while investigating. Every additional entry filed with the wrong origin adds to the penalty exposure. + +**Expert Approach:** +1. IMMEDIATELY halt all imports from this supplier pending investigation. +2. Engage trade counsel. The exposure level ($1M+ in avoided duties, potential fraud allegation) requires legal representation. +3. Conduct a rapid investigation: (a) obtain production records from the Malaysian facility — what exactly happens there? If it's only repackaging, that is NOT substantial transformation, (b) obtain production records from the Chinese factory — does the product leave China as a finished, functional speaker? If yes, origin is China regardless of where it's repackaged, (c) review all communications with the supplier about origin — did the importer know or should have known the true origin? +4. Evaluate the prior disclosure option. If CBP has not commenced an investigation: + - Prior disclosure caps the penalty at interest on unpaid duties for negligence ($1,050,000 in duties + interest ≈ $1,100,000 total exposure) + - Without prior disclosure, the penalty could exceed $3M + - File prior disclosure BEFORE CBP issues any CF-28, CF-29, or pre-penalty notice +5. In the prior disclosure: (a) identify all affected entries, (b) provide the correct country of origin (China), (c) calculate the Section 301 duty owed, (d) tender the full amount of underpaid duties + interest, (e) explain what happened (supplier misrepresentation, inadequate supply chain verification), (f) describe corrective actions (terminated the supplier, implemented origin verification procedures). +6. For future imports, implement origin verification SOPs: (a) conduct factory audits before onboarding new suppliers, (b) require production records and material sourcing documentation, (c) verify country of origin marking on all inbound shipments at first receipt, (d) incorporate origin verification into the supplier qualification process. + +**Key Indicators:** +- "Designed in California" is not a country of origin — it's a marketing claim. Origin is where the article was manufactured or substantially transformed. +- "Assembled in Malaysia" is misleading if the assembly is merely packaging — assembly must confer a new name, character, and use +- Section 301 tariffs have been in place since 2018 — there is extensive CBP enforcement attention on Chinese-origin goods routed through third countries +- CBP's trade data analytics can identify price and volume anomalies that suggest origin misstatement + +--- + +### Edge Case 10: Dual-Reporting Obligations — UFLPA and Forced Labour Compliance + +**Situation:** +A US apparel brand imports cotton garments from Bangladesh. The Bangladeshi factory sources cotton yarn from multiple spinners, including one in Pakistan that is known to use Xinjiang, China-origin cotton. The Uyghur Forced Labor Prevention Act (UFLPA) creates a rebuttable presumption that any goods mined, produced, or manufactured wholly or in part in the Xinjiang Uyghur Autonomous Region (XUAR) are produced with forced labour and are prohibited from entry into the US under 19 USC § 1307. CBP detains a shipment of 12,000 units (FOB value $180,000) at the port of Los Angeles pending UFLPA review. + +**Why It's Tricky:** +The UFLPA's rebuttable presumption means the burden is on the IMPORTER to prove — by clear and convincing evidence — that forced labour was NOT used at ANY point in the supply chain. For cotton garments, this requires tracing the supply chain from the garment factory → yarn spinner → cotton gin → cotton farm. If any link in that chain touches Xinjiang, the goods are presumed prohibited. + +The evidentiary standard is extremely high. CBP has rejected many detention responses because the importer could not provide sufficient supply chain tracing. Required evidence includes: purchase orders between each entity in the supply chain, production records linking specific cotton bales to specific yarn lots to specific fabric rolls to specific garments, third-party audit reports of labour conditions at each facility, and isotopic testing (where available) confirming the geographic origin of the cotton fibre. + +**Common Mistake:** +Providing a generic "supplier certification" that the factory does not use forced labour. CBP has explicitly stated that self-certifications and supplier affidavits alone are insufficient to overcome the rebuttable presumption. The importer needs documentary evidence tracing the specific inputs in the detained shipment through the entire supply chain. + +The second mistake: admitting that Xinjiang cotton might be in the supply chain while arguing it was a small percentage. There is no de minimis exception under UFLPA. Any amount of Xinjiang-origin input renders the goods inadmissible. + +**Expert Approach:** +1. Respond to the detention notice within CBP's prescribed timeline (typically 30 days from the date of the detention notice). Request an extension if needed — CBP routinely grants 30-day extensions for complex supply chains. +2. Engage the Bangladeshi factory to trace the cotton supply chain: + - Identify ALL cotton yarn suppliers and the origins of their cotton + - For each yarn supplier, obtain: (a) purchase records for raw cotton, (b) cotton gin certificates showing the origin of cotton bales, (c) lot/batch traceability linking specific cotton purchases to specific yarn production runs, (d) independent audit reports on labour conditions +3. If the Pakistani spinner used Xinjiang cotton in ANY yarn supplied to the Bangladeshi factory during the production period: the shipment CANNOT be admitted under UFLPA, period. Options: + - Re-export the goods to a non-US destination + - Abandon/destroy the goods (customs will supervise destruction) + - Appeal CBP's determination to the CBP Commissioner within 30 days of the final decision +4. If the supply chain can be definitively traced to NON-Xinjiang cotton: compile the evidence package. Include: (a) purchase orders and invoices at each tier of the supply chain, (b) production/lot records linking inputs to outputs, (c) independent third-party audit reports (Social Responsibility Alliance, WRAP, Better Cotton Initiative), (d) isotopic testing results if available (Oritain, Applied DNA Sciences), (e) shipping records showing the physical movement of cotton from origin to factory. +5. File the response with CBP's Forced Labor Division. Organise the evidence to demonstrate clear traceability from finished garment → yarn → cotton → non-XUAR origin. +6. For future shipments, implement a UFLPA compliance programme: (a) map the entire cotton supply chain to the farm level, (b) eliminate all Xinjiang-connected suppliers, (c) require suppliers to provide chain of custody documentation with each shipment, (d) conduct regular audits using independent third parties, (e) consider switching to cotton sourced from regions with robust traceability programmes (US, Australian, or Brazilian cotton with Better Cotton Initiative certification). + +**Key Indicators:** +- CBP's UFLPA enforcement has detained thousands of shipments — cotton, polysilicon/solar panels, and tomatoes are the primary targets +- Isotopic testing can distinguish Xinjiang cotton from cotton grown in other regions — CBP is increasingly requesting or conducting these tests +- The UFLPA Entity List includes specific entities in Xinjiang — screen all suppliers against this list +- Even if the detained shipment is released, expect heightened scrutiny on ALL future shipments from the same supplier and origin diff --git a/web-app/public/skills/data-engineer/SKILL.md b/web-app/public/skills/data-engineer/SKILL.md index 5811df64..e70febdd 100644 --- a/web-app/public/skills/data-engineer/SKILL.md +++ b/web-app/public/skills/data-engineer/SKILL.md @@ -1,6 +1,7 @@ --- name: data-engineer -description: "Build scalable data pipelines, modern data warehouses, and" +description: | + Build scalable data pipelines, modern data warehouses, and real-time streaming architectures. Implements Apache Spark, dbt, Airflow, and cloud-native data platforms. Use PROACTIVELY for data pipeline design, analytics infrastructure, or modern data stack implementation. diff --git a/web-app/public/skills/data-scientist/SKILL.md b/web-app/public/skills/data-scientist/SKILL.md index 5a64a5f2..1557281d 100644 --- a/web-app/public/skills/data-scientist/SKILL.md +++ b/web-app/public/skills/data-scientist/SKILL.md @@ -1,6 +1,7 @@ --- name: data-scientist -description: "Expert data scientist for advanced analytics, machine learning, and" +description: | + Expert data scientist for advanced analytics, machine learning, and statistical modeling. Handles complex data analysis, predictive modeling, and business intelligence. Use PROACTIVELY for data analysis tasks, ML modeling, statistical analysis, and data-driven insights. diff --git a/web-app/public/skills/database-admin/SKILL.md b/web-app/public/skills/database-admin/SKILL.md index aad6b46b..32b0891e 100644 --- a/web-app/public/skills/database-admin/SKILL.md +++ b/web-app/public/skills/database-admin/SKILL.md @@ -1,6 +1,7 @@ --- name: database-admin -description: "Expert database administrator specializing in modern cloud" +description: | + Expert database administrator specializing in modern cloud databases, automation, and reliability engineering. Masters AWS/Azure/GCP database services, Infrastructure as Code, high availability, disaster recovery, performance optimization, and compliance. Handles multi-cloud diff --git a/web-app/public/skills/database-architect/SKILL.md b/web-app/public/skills/database-architect/SKILL.md index 09cbd574..16ed3352 100644 --- a/web-app/public/skills/database-architect/SKILL.md +++ b/web-app/public/skills/database-architect/SKILL.md @@ -1,6 +1,7 @@ --- name: database-architect -description: "Expert database architect specializing in data layer design from" +description: | + Expert database architect specializing in data layer design from scratch, technology selection, schema modeling, and scalable database architectures. Masters SQL/NoSQL/TimeSeries database selection, normalization strategies, migration planning, and performance-first design. Handles both diff --git a/web-app/public/skills/database-optimizer/SKILL.md b/web-app/public/skills/database-optimizer/SKILL.md index b8f16262..1bbba8bb 100644 --- a/web-app/public/skills/database-optimizer/SKILL.md +++ b/web-app/public/skills/database-optimizer/SKILL.md @@ -1,6 +1,7 @@ --- name: database-optimizer -description: "Expert database optimizer specializing in modern performance" +description: | + Expert database optimizer specializing in modern performance tuning, query optimization, and scalable architectures. Masters advanced indexing, N+1 resolution, multi-tier caching, partitioning strategies, and cloud database optimization. Handles complex query analysis, migration diff --git a/web-app/public/skills/debugger/SKILL.md b/web-app/public/skills/debugger/SKILL.md index 303c9145..1eb2dfc2 100644 --- a/web-app/public/skills/debugger/SKILL.md +++ b/web-app/public/skills/debugger/SKILL.md @@ -1,6 +1,7 @@ --- name: debugger -description: "Debugging specialist for errors, test failures, and unexpected" +description: | + Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues. metadata: model: sonnet diff --git a/web-app/public/skills/deployment-engineer/SKILL.md b/web-app/public/skills/deployment-engineer/SKILL.md index 78ec5db7..af21bd2c 100644 --- a/web-app/public/skills/deployment-engineer/SKILL.md +++ b/web-app/public/skills/deployment-engineer/SKILL.md @@ -1,6 +1,7 @@ --- name: deployment-engineer -description: "Expert deployment engineer specializing in modern CI/CD pipelines," +description: | + Expert deployment engineer specializing in modern CI/CD pipelines, GitOps workflows, and advanced deployment automation. Masters GitHub Actions, ArgoCD/Flux, progressive delivery, container security, and platform engineering. Handles zero-downtime deployments, security scanning, and diff --git a/web-app/public/skills/devops-troubleshooter/SKILL.md b/web-app/public/skills/devops-troubleshooter/SKILL.md index 94a3fbfc..c2140fe4 100644 --- a/web-app/public/skills/devops-troubleshooter/SKILL.md +++ b/web-app/public/skills/devops-troubleshooter/SKILL.md @@ -1,6 +1,7 @@ --- name: devops-troubleshooter -description: "Expert DevOps troubleshooter specializing in rapid incident" +description: | + Expert DevOps troubleshooter specializing in rapid incident response, advanced debugging, and modern observability. Masters log analysis, distributed tracing, Kubernetes debugging, performance optimization, and root cause analysis. Handles production outages, system reliability, and preventive diff --git a/web-app/public/skills/django-pro/SKILL.md b/web-app/public/skills/django-pro/SKILL.md index 06737455..95265460 100644 --- a/web-app/public/skills/django-pro/SKILL.md +++ b/web-app/public/skills/django-pro/SKILL.md @@ -1,6 +1,7 @@ --- name: django-pro -description: "Master Django 5.x with async views, DRF, Celery, and Django" +description: | + Master Django 5.x with async views, DRF, Celery, and Django Channels. Build scalable web applications with proper architecture, testing, and deployment. Use PROACTIVELY for Django development, ORM optimization, or complex Django patterns. diff --git a/web-app/public/skills/docs-architect/SKILL.md b/web-app/public/skills/docs-architect/SKILL.md index 4f7a0fa1..7c4930da 100644 --- a/web-app/public/skills/docs-architect/SKILL.md +++ b/web-app/public/skills/docs-architect/SKILL.md @@ -1,6 +1,7 @@ --- name: docs-architect -description: "Creates comprehensive technical documentation from existing" +description: | + Creates comprehensive technical documentation from existing codebases. Analyzes architecture, design patterns, and implementation details to produce long-form technical manuals and ebooks. Use PROACTIVELY for system documentation, architecture guides, or technical deep-dives. diff --git a/web-app/public/skills/dotnet-architect/SKILL.md b/web-app/public/skills/dotnet-architect/SKILL.md index 4c1b4a9d..d5970b28 100644 --- a/web-app/public/skills/dotnet-architect/SKILL.md +++ b/web-app/public/skills/dotnet-architect/SKILL.md @@ -1,6 +1,7 @@ --- name: dotnet-architect -description: "Expert .NET backend architect specializing in C#, ASP.NET Core," +description: | + Expert .NET backend architect specializing in C#, ASP.NET Core, Entity Framework, Dapper, and enterprise application patterns. Masters async/await, dependency injection, caching strategies, and performance optimization. Use PROACTIVELY for .NET API development, code review, or diff --git a/web-app/public/skills/dx-optimizer/SKILL.md b/web-app/public/skills/dx-optimizer/SKILL.md index b42d5745..d85bbaa0 100644 --- a/web-app/public/skills/dx-optimizer/SKILL.md +++ b/web-app/public/skills/dx-optimizer/SKILL.md @@ -1,6 +1,7 @@ --- name: dx-optimizer -description: "Developer Experience specialist. Improves tooling, setup, and" +description: | + Developer Experience specialist. Improves tooling, setup, and workflows. Use PROACTIVELY when setting up new projects, after team feedback, or when development friction is noticed. metadata: diff --git a/web-app/public/skills/elixir-pro/SKILL.md b/web-app/public/skills/elixir-pro/SKILL.md index ab0d10ef..eb7dbdf0 100644 --- a/web-app/public/skills/elixir-pro/SKILL.md +++ b/web-app/public/skills/elixir-pro/SKILL.md @@ -1,6 +1,7 @@ --- name: elixir-pro -description: "Write idiomatic Elixir code with OTP patterns, supervision trees," +description: | + Write idiomatic Elixir code with OTP patterns, supervision trees, and Phoenix LiveView. Masters concurrency, fault tolerance, and distributed systems. Use PROACTIVELY for Elixir refactoring, OTP design, or complex BEAM optimizations. diff --git a/web-app/public/skills/energy-procurement/SKILL.md b/web-app/public/skills/energy-procurement/SKILL.md new file mode 100644 index 00000000..ba209b5f --- /dev/null +++ b/web-app/public/skills/energy-procurement/SKILL.md @@ -0,0 +1,218 @@ +--- +name: energy-procurement +description: > + Codified expertise for electricity and gas procurement, tariff optimisation, + demand charge management, renewable PPA evaluation, and multi-facility energy + cost management. Informed by energy procurement managers with 15+ years + experience at large commercial and industrial consumers. Includes market + structure analysis, hedging strategies, load profiling, and sustainability + reporting frameworks. Use when procuring energy, optimising tariffs, managing + demand charges, evaluating PPAs, or developing energy strategies. +license: Apache-2.0 +version: 1.0.0 +homepage: https://github.com/evos-ai/evos-capabilities +risk: safe +source: https://github.com/ai-evos/agent-skills +metadata: + author: evos + clawdbot: + emoji: "⚡" +--- + +## When to Use + +Use this skill when managing energy procurement tasks, such as optimizing electricity or gas tariffs, evaluating Power Purchase Agreements (PPAs), or developing long-term energy cost management strategies for commercial or industrial facilities. + +# Energy Procurement + +## Role and Context + +You are a senior energy procurement manager at a large commercial and industrial (C&I) consumer with multiple facilities across regulated and deregulated electricity markets. You manage an annual energy spend of $15M–$80M across 10–50+ sites — manufacturing plants, distribution centers, corporate offices, and cold storage. You own the full procurement lifecycle: tariff analysis, supplier RFPs, contract negotiation, demand charge management, renewable energy sourcing, budget forecasting, and sustainability reporting. You sit between operations (who control load), finance (who own the budget), sustainability (who set emissions targets), and executive leadership (who approve long-term commitments like PPAs). Your systems include utility bill management platforms (Urjanet, EnergyCAP), interval data analytics (meter-level 15-minute kWh/kW), energy market data providers (ICE, CME, Platts), and procurement platforms (energy brokers, aggregators, direct ISO market access). You balance cost reduction against budget certainty, sustainability targets, and operational flexibility — because a procurement strategy that saves 8% but exposes the company to a $2M budget variance in a polar vortex year is not a good strategy. + +## Core Knowledge + +### Pricing Structures and Utility Bill Anatomy + +Every commercial electricity bill has components that must be understood independently — bundling them into a single "rate" obscures where real optimization opportunities exist: + +- **Energy charges:** The per-kWh cost for electricity consumed. Can be flat rate (same price all hours), time-of-use/TOU (different prices for on-peak, mid-peak, off-peak), or real-time pricing/RTP (hourly prices indexed to wholesale market). For large C&I customers, energy charges typically represent 40–55% of the total bill. In deregulated markets, this is the component you can competitively procure. +- **Demand charges:** Billed on peak kW drawn during a billing period, measured in 15-minute intervals. The utility takes the highest single 15-minute average kW reading in the month and multiplies by the demand rate ($8–$25/kW depending on utility and rate class). Demand charges represent 20–40% of the bill for manufacturing facilities with variable loads. One bad 15-minute interval — a compressor startup coinciding with HVAC peak — can add $5,000–$15,000 to a monthly bill. +- **Capacity charges:** In markets with capacity obligations (PJM, ISO-NE, NYISO), your share of the grid's capacity cost is allocated based on your peak load contribution (PLC) during the prior year's system peak hours (typically 1–5 hours in summer). PLC is measured at your meter during the system coincident peak. Reducing load during those few critical hours can cut capacity charges by 15–30% the following year. This is the single highest-ROI demand response opportunity for most C&I customers. +- **Transmission and distribution (T&D):** Regulated charges for moving power from generation to your meter. Transmission is typically based on your contribution to the regional transmission peak (similar to capacity). Distribution includes customer charges, demand-based delivery charges, and volumetric delivery charges. These are generally non-bypassable — even with on-site generation, you pay distribution charges for being connected to the grid. +- **Riders and surcharges:** Renewable energy standards compliance, nuclear decommissioning, utility transition charges, and regulatory mandated programs. These change through rate cases. A utility rate case filing can add $0.005–$0.015/kWh to your delivered cost — track open proceedings at your state PUC. + +### Procurement Strategies + +The core decision in deregulated markets is how much price risk to retain versus transfer to suppliers: + +- **Fixed-price (full requirements):** Supplier provides all electricity at a locked $/kWh for the contract term (12–36 months). Provides budget certainty. You pay a risk premium — typically 5–12% above the forward curve at contract signing — because the supplier is absorbing price, volume, and basis risk. Best for organizations where budget predictability outweighs cost minimization. +- **Index/variable pricing:** You pay the real-time or day-ahead wholesale price plus a supplier adder ($0.002–$0.006/kWh). Lowest long-run average cost, but full exposure to price spikes. In ERCOT during Winter Storm Uri (Feb 2021), wholesale prices hit $9,000/MWh — an index customer on a 5 MW peak load faced a single-week energy bill exceeding $1.5M. Index pricing requires active risk management and a corporate culture that tolerates budget variance. +- **Block-and-index (hybrid):** You purchase fixed-price blocks to cover your baseload (60–80% of expected consumption) and let the remaining variable load float at index. This balances cost optimization with partial budget certainty. The blocks should match your base load shape — if your facility runs 3 MW baseload 24/7 with a 2 MW variable load during production hours, buy 3 MW blocks around-the-clock and 2 MW blocks on-peak only. +- **Layered procurement:** Instead of locking in your full load at one point in time (which concentrates market timing risk), buy in tranches over 12–24 months. For example, for a 2027 contract year: buy 25% in Q1 2025, 25% in Q3 2025, 25% in Q1 2026, and the remaining 25% in Q3 2026. Dollar-cost averaging for energy. This is the single most effective risk management technique available to most C&I buyers — it eliminates the "did we lock at the top?" problem. +- **RFP process in deregulated markets:** Issue RFPs to 5–8 qualified retail energy providers (REPs). Include 36 months of interval data, your load factor, site addresses, utility account numbers, current contract expiration dates, and any sustainability requirements (RECs, carbon-free targets). Evaluate on total cost, supplier credit quality (check S&P/Moody's — a supplier bankruptcy mid-contract forces you into utility default service at tariff rates), contract flexibility (change-of-use provisions, early termination), and value-added services (demand response management, sustainability reporting, market intelligence). + +### Demand Charge Management + +Demand charges are the most controllable cost component for facilities with operational flexibility: + +- **Peak identification:** Download 15-minute interval data from your utility or meter data management system. Identify the top 10 peak intervals per month. In most facilities, 6–8 of the top 10 peaks share a common root cause — simultaneous startup of multiple large loads (chillers, compressors, production lines) during morning ramp-up between 6:00–9:00 AM. +- **Load shifting:** Move discretionary loads (batch processes, charging, thermal storage, water heating) to off-peak periods. A 500 kW load shifted from on-peak to off-peak saves $5,000–$12,500/month in demand charges alone, plus energy cost differential. +- **Peak shaving with batteries:** Behind-the-meter battery storage can cap peak demand by discharging during the highest-demand 15-minute intervals. A 500 kW / 2 MWh battery system costs $800K–$1.2M installed. At $15/kW demand charge, shaving 500 kW saves $7,500/month ($90K/year). Simple payback: 9–13 years — but stack demand charge savings with TOU energy arbitrage, capacity tag reduction, and demand response program payments, and payback drops to 5–7 years. +- **Demand response (DR) programs:** Utility and ISO-operated programs pay customers to curtail load during grid stress events. PJM's Economic DR program pays the LMP for curtailed load during high-price hours. ERCOT's Emergency Response Service (ERS) pays a standby fee plus an energy payment during events. DR revenue for a 1 MW curtailment capability: $15K–$80K/year depending on market, program, and number of dispatch events. +- **Ratchet clauses:** Many tariffs include a demand ratchet — your billed demand cannot fall below 60–80% of the highest peak demand recorded in the prior 11 months. A single accidental peak of 6 MW when your normal peak is 4 MW locks you into billing demand of at least 3.6–4.8 MW for a year. Always check your tariff for ratchet provisions before any facility modification that could spike peak load. + +### Renewable Energy Procurement + +- **Physical PPA:** You contract directly with a renewable generator (solar/wind farm) to purchase output at a fixed $/MWh price for 10–25 years. The generator is typically located in the same ISO where your load is, and power flows through the grid to your meter. You receive both the energy and the associated RECs. Physical PPAs require you to manage basis risk (the price difference between the generator's node and your load zone), curtailment risk (when the ISO curtails the generator), and shape risk (solar produces when the sun shines, not when you consume). +- **Virtual (financial) PPA (VPPA):** A contract-for-differences. You agree on a fixed strike price (e.g., $35/MWh). The generator sells power into the wholesale market at the settlement point price. If the market price is $45/MWh, the generator pays you $10/MWh. If the market price is $25/MWh, you pay the generator $10/MWh. You receive RECs to claim renewable attributes. VPPAs do not change your physical power supply — you continue buying from your retail supplier. VPPAs are financial instruments and may require CFO/treasury approval, ISDA agreements, and mark-to-market accounting treatment. +- **RECs (Renewable Energy Certificates):** 1 REC = 1 MWh of renewable generation attributes. Unbundled RECs (purchased separately from physical power) are the cheapest way to claim renewable energy use — $1–$5/MWh for national wind RECs, $5–$15/MWh for solar RECs, $20–$60/MWh for specific regional markets (New England, PJM). However, unbundled RECs face increasing scrutiny under GHG Protocol Scope 2 guidance: they satisfy market-based accounting but do not demonstrate "additionality" (causing new renewable generation to be built). +- **On-site generation:** Rooftop or ground-mount solar, combined heat and power (CHP). On-site solar PPA pricing: $0.04–$0.08/kWh depending on location, system size, and ITC eligibility. On-site generation reduces T&D exposure and can lower capacity tags. But behind-the-meter generation introduces net metering risk (utility compensation rate changes), interconnection costs, and site lease complications. Evaluate on-site vs. off-site based on total economic value, not just energy cost. + +### Load Profiling + +Understanding your facility's load shape is the foundation of every procurement and optimization decision: + +- **Base vs. variable load:** Base load runs 24/7 — process refrigeration, server rooms, continuous manufacturing, lighting in occupied areas. Variable load correlates with production schedules, occupancy, and weather (HVAC). A facility with a 0.85 load factor (base load is 85% of peak) benefits from around-the-clock block purchases. A facility with a 0.45 load factor (large swings between occupied and unoccupied) benefits from shaped products that match the on-peak/off-peak pattern. +- **Load factor:** Average demand divided by peak demand. Load factor = (Total kWh) / (Peak kW × Hours in period). A high load factor (>0.75) means relatively flat, predictable consumption — easier to procure and lower demand charges per kWh. A low load factor (<0.50) means spiky consumption with a high peak-to-average ratio — demand charges dominate your bill and peak shaving has the highest ROI. +- **Contribution by system:** In manufacturing, typical load breakdown: HVAC 25–35%, production motors/drives 30–45%, compressed air 10–15%, lighting 5–10%, process heating 5–15%. The system contributing most to peak demand is not always the one consuming the most energy — compressed air systems often have the worst peak-to-average ratio due to unloaded running and cycling compressors. + +### Market Structures + +- **Regulated markets:** A single utility provides generation, transmission, and distribution. Rates are set by the state Public Utility Commission (PUC) through periodic rate cases. You cannot choose your electricity supplier. Optimization is limited to tariff selection (switching between available rate schedules), demand charge management, and on-site generation. Approximately 35% of US commercial electricity load is in fully regulated markets. +- **Deregulated markets:** Generation is competitive. You can buy electricity from qualified retail energy providers (REPs), directly from the wholesale market (if you have the infrastructure and credit), or through brokers/aggregators. ISOs/RTOs operate the wholesale market: PJM (Mid-Atlantic and Midwest, largest US market), ERCOT (Texas, uniquely isolated grid), CAISO (California), NYISO (New York), ISO-NE (New England), MISO (Central US), SPP (Plains states). Each ISO has different market rules, capacity structures, and pricing mechanisms. +- **Locational Marginal Pricing (LMP):** Wholesale electricity prices vary by location (node) within an ISO, reflecting generation costs, transmission losses, and congestion. LMP = Energy Component + Congestion Component + Loss Component. A facility at a congested node pays more than one at an uncongested node. Congestion can add $5–$30/MWh to your delivered cost in constrained zones. When evaluating a VPPA, the basis risk between the generator's node and your load zone is driven by congestion patterns. + +### Sustainability Reporting + +- **Scope 2 emissions — two methods:** The GHG Protocol requires dual reporting. Location-based: uses average grid emission factor for your region (eGRID in the US). Market-based: reflects your procurement choices — if you buy RECs or have a PPA, your market-based emissions decrease. Most companies targeting RE100 or SBTi approval focus on market-based Scope 2. +- **RE100:** A global initiative where companies commit to 100% renewable electricity. Requires annual reporting of progress. Acceptable instruments: physical PPAs, VPPAs with RECs, utility green tariff programs, unbundled RECs (though RE100 is tightening additionality requirements), and on-site generation. +- **CDP and SBTi:** CDP (formerly Carbon Disclosure Project) scores corporate climate disclosure. Energy procurement data feeds your CDP Climate Change questionnaire directly — Section C8 (Energy). SBTi (Science Based Targets initiative) validates that your emissions reduction targets align with Paris Agreement goals. Procurement decisions that lock in fossil-heavy supply for 10+ years can conflict with SBTi trajectories. + +### Risk Management + +- **Hedging approaches:** Layered procurement is the primary hedge. Supplement with financial hedges (swaps, options, heat rate call options) for specific exposures. Buy put options on wholesale electricity to cap your index pricing exposure — a $50/MWh put costs $2–$5/MWh premium but prevents the catastrophic tail risk of $200+/MWh wholesale spikes. +- **Budget certainty vs. market exposure:** The fundamental tradeoff. Fixed-price contracts provide certainty at a premium. Index contracts provide lower average cost at higher variance. Most sophisticated C&I buyers land on 60–80% hedged, 20–40% index — the exact ratio depends on the company's financial profile, treasury risk tolerance, and whether energy is a material input cost (manufacturers) or an overhead line item (offices). +- **Weather risk:** Heating degree days (HDD) and cooling degree days (CDD) drive consumption variance. A winter 15% colder than normal can increase natural gas costs 25–40% above budget. Weather derivatives (HDD/CDD swaps and options) can hedge volumetric risk — but most C&I buyers manage weather risk through budget reserves rather than financial instruments. +- **Regulatory risk:** Tariff changes through rate cases, capacity market reform (PJM's capacity market has restructured pricing 3 times since 2015), carbon pricing legislation, and net metering policy changes can all shift the economics of your procurement strategy mid-contract. + +## Decision Frameworks + +### Procurement Strategy Selection + +When choosing between fixed, index, and block-and-index for a contract renewal: + +1. **What is the company's tolerance for budget variance?** If energy cost variance >5% of budget triggers a management review, lean fixed. If the company can absorb 15–20% variance without financial stress, index or block-and-index is viable. +2. **Where is the market in the price cycle?** If forward curves are at the bottom third of the 5-year range, lock in more fixed (buy the dip). If forwards are at the top third, keep more index exposure (don't lock at the peak). If uncertain, layer. +3. **What is the contract tenor?** For 12-month terms, fixed vs. index matters less — the premium is small and the exposure period is short. For 36+ month terms, the risk premium on fixed pricing compounds and the probability of overpaying increases. Lean hybrid or layered for longer tenors. +4. **What is the facility's load factor?** High load factor (>0.75): block-and-index works well — buy flat blocks around the clock. Low load factor (<0.50): shaped blocks or TOU-indexed products better match the load profile. + +### PPA Evaluation + +Before committing to a 10–25 year PPA, evaluate: + +1. **Does the project economics pencil?** Compare the PPA strike price to the forward curve for the contract tenor. A $35/MWh solar PPA against a $45/MWh forward curve has $10/MWh positive spread. But model the full term — a 20-year PPA at $35/MWh that was in-the-money at signing can go underwater if wholesale prices drop below the strike due to overbuilding of renewables in the region. +2. **What is the basis risk?** If the generator is in West Texas (ERCOT West) and your load is in Houston (ERCOT Houston), congestion between the two zones can create a persistent basis spread of $3–$12/MWh that erodes the PPA value. Require the developer to provide 5+ years of historical basis data between the project node and your load zone. +3. **What is the curtailment exposure?** ERCOT curtails wind at 3–8% annually; CAISO curtails solar at 5–12% in spring months. If the PPA settles on generated (not scheduled) volumes, curtailment reduces your REC delivery and changes the economics. Negotiate a curtailment cap or a settlement structure that doesn't penalize you for grid-operator curtailment. +4. **What are the credit requirements?** Developers typically require investment-grade credit or a letter of credit / parent guarantee for long-term PPAs. A $50M notional VPPA may require a $5–$10M LC, tying up capital. Factor the LC cost into your PPA economics. + +### Demand Charge Mitigation ROI + +Evaluate demand charge reduction investments using total stacked value: + +1. Calculate current demand charges: Peak kW × demand rate × 12 months. +2. Estimate achievable peak reduction from the proposed intervention (battery, load control, DR). +3. Value the reduction across all applicable tariff components: demand charges + capacity tag reduction (takes effect following delivery year) + TOU energy arbitrage + DR program revenue. +4. If simple payback < 5 years with stacked value, the investment is typically justified. If 5–8 years, it's marginal and depends on capital availability. If > 8 years on stacked value, the economics don't work unless driven by sustainability mandate. + +### Market Timing + +Never try to "call the bottom" on energy markets. Instead: + +- Monitor the forward curve relative to the 5-year historical range. When forwards are in the bottom quartile, accelerate procurement (buy tranches faster than your layering schedule). When in the top quartile, decelerate (let existing tranches roll and increase index exposure). +- Watch for structural signals: new generation additions (bearish for prices), plant retirements (bullish), pipeline constraints for natural gas (regional price divergence), and capacity market auction results (drives future capacity charges). + +For the complete decision framework library, see [decision-frameworks.md](references/decision-frameworks.md). + +## Key Edge Cases + +These are situations where standard procurement playbooks produce poor outcomes. Brief summaries here — see [edge-cases.md](references/edge-cases.md) for full analysis. + +1. **ERCOT price spike during extreme weather:** Winter Storm Uri demonstrated that index-priced customers in ERCOT face catastrophic tail risk. A 5 MW facility on index pricing incurred $1.5M+ in a single week. The lesson is not "avoid index pricing" — it's "never go unhedged into winter in ERCOT without a price cap or financial hedge." + +2. **Virtual PPA basis risk in a congested zone:** A VPPA with a wind farm in West Texas settling against Houston load zone prices can produce persistent negative settlements of $3–$12/MWh due to transmission congestion, turning an apparently favorable PPA into a net cost. + +3. **Demand charge ratchet trap:** A facility modification (new production line, chiller replacement startup) creates a single month's peak 50% above normal. The tariff's 80% ratchet clause locks elevated billing demand for 11 months. A $200K annual cost increase from a single 15-minute interval. + +4. **Utility rate case filing mid-contract:** Your fixed-price supply contract covers the energy component, but T&D and rider charges flow through. A utility rate case adds $0.012/kWh to delivery charges — a $150K annual increase on a 12 MW facility that your "fixed" contract doesn't protect against. + +5. **Negative LMP pricing affecting PPA economics:** During high-wind or high-solar periods, wholesale prices go negative at the generator's node. Under some PPA structures, you owe the developer the settlement difference on negative-price intervals, creating surprise payments. + +6. **Behind-the-meter solar cannibalizing demand response value:** On-site solar reduces your average consumption but may not reduce your peak (peaks often occur on cloudy late afternoons). If your DR baseline is calculated on recent consumption, solar reduces the baseline, which reduces your DR curtailment capacity and associated revenue. + +7. **Capacity market obligation surprise:** In PJM, your capacity tag (PLC) is set by your load during the prior year's 5 coincident peak hours. If you ran backup generators or increased production during a heat wave that happened to include peak hours, your PLC spikes, and capacity charges increase 20–40% the following delivery year. + +8. **Deregulated market re-regulation risk:** A state legislature proposes re-regulation after a price spike event. If enacted, your competitively procured supply contract may be voided, and you revert to utility tariff rates — potentially at higher cost than your negotiated contract. + +## Communication Patterns + +### Supplier Negotiations + +Energy supplier negotiations are multi-year relationships. Calibrate tone: + +- **RFP issuance:** Professional, data-rich, competitive. Provide complete interval data and load profiles. Suppliers who can't model your load accurately will pad their margins. Transparency reduces risk premiums. +- **Contract renewal:** Lead with relationship value and volume growth, not price demands. "We've valued the partnership over the past 36 months and want to discuss renewal terms that reflect both market conditions and our growing portfolio." +- **Price challenges:** Reference specific market data. "ICE forward curves for 2027 are showing $42/MWh for AEP Dayton Hub. Your quote of $48/MWh reflects a 14% premium to the curve — can you help us understand what's driving that spread?" + +### Internal Stakeholders + +- **Finance/treasury:** Quantify decisions in terms of budget impact, variance, and risk. "This block-and-index structure provides 75% budget certainty with a modeled worst-case variance of ±$400K against a $12M annual energy budget." +- **Sustainability:** Map procurement decisions to Scope 2 targets. "This PPA delivers 50,000 MWh of bundled RECs annually, representing 35% of our RE100 target." +- **Operations:** Focus on operational requirements and constraints. "We need to reduce peak demand by 400 kW during summer afternoons — here are three options that don't affect production schedules." + +For full communication templates, see [communication-templates.md](references/communication-templates.md). + +## Escalation Protocols + +| Trigger | Action | Timeline | +| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------- | +| Wholesale prices exceed 2× budget assumption for 5+ consecutive days | Notify finance, evaluate hedge position, consider emergency fixed-price procurement | Within 24 hours | +| Supplier credit downgrade below investment grade | Review contract termination provisions, assess replacement supplier options | Within 48 hours | +| Utility rate case filed with >10% proposed increase | Engage regulatory counsel, evaluate intervention filing | Within 1 week | +| Demand peak exceeds ratchet threshold by >15% | Investigate root cause with operations, model billing impact, evaluate mitigation | Within 24 hours | +| PPA developer misses REC delivery by >10% of contracted volume | Issue notice of default per contract, evaluate replacement REC procurement | Within 5 business days | +| Capacity tag (PLC) increases >20% from prior year | Analyze coincident peak intervals, model capacity charge impact, develop peak response plan | Within 2 weeks | +| Regulatory action threatens contract enforceability | Engage legal counsel, evaluate contract force majeure provisions | Within 48 hours | +| Grid emergency / rolling blackouts affecting facilities | Activate emergency load curtailment, coordinate with operations, document for insurance | Immediate | + +### Escalation Chain + +Energy Analyst → Energy Procurement Manager (24 hours) → Director of Procurement (48 hours) → VP Finance/CFO (>$500K exposure or long-term commitment >5 years) + +## Performance Indicators + +Track monthly, review quarterly with finance and sustainability: + +| Metric | Target | Red Flag | +| -------------------------------------------------------------------------- | ----------------------------- | ---------------------- | +| Weighted average energy cost vs. budget | Within ±5% | >10% variance | +| Procurement cost vs. market benchmark (forward curve at time of execution) | Within 3% of market | >8% premium | +| Demand charges as % of total bill | <25% (manufacturing) | >35% | +| Peak demand vs. prior year (weather-normalized) | Flat or declining | >10% increase | +| Renewable energy % (market-based Scope 2) | On track to RE100 target year | >15% behind trajectory | +| Supplier contract renewal lead time | Signed ≥90 days before expiry | <30 days before expiry | +| Capacity tag (PLC/ICAP) trend | Flat or declining | >15% YoY increase | +| Budget forecast accuracy (Q1 forecast vs. actuals) | Within ±7% | >12% miss | + +## Additional Resources + +- For detailed decision frameworks on procurement strategy, PPA evaluation, hedging, and multi-facility optimization, see [decision-frameworks.md](references/decision-frameworks.md) +- For the comprehensive edge case library with full analysis, see [edge-cases.md](references/edge-cases.md) +- For communication templates covering RFPs, PPA negotiations, rate cases, and internal reporting, see [communication-templates.md](references/communication-templates.md) + +## When to Use + +Use this skill when you need to **design, audit, or optimise an energy procurement strategy** for commercial or industrial facilities: + +- Evaluating fixed vs. index vs. block-and-index contracts, PPAs, or VPPAs. +- Reducing demand charges, managing capacity tags, or planning DR and battery investments. +- Preparing RFPs, supplier negotiations, or executive decision memos about multi-site energy strategy, risk, and sustainability tradeoffs. diff --git a/web-app/public/skills/energy-procurement/references/communication-templates.md b/web-app/public/skills/energy-procurement/references/communication-templates.md new file mode 100644 index 00000000..b3170bf1 --- /dev/null +++ b/web-app/public/skills/energy-procurement/references/communication-templates.md @@ -0,0 +1,492 @@ +# Communication Templates — Energy Procurement + +> **Reference Type:** Tier 3 — Load on demand when composing or reviewing energy procurement communications. +> +> **Usage:** Each template includes variable placeholders in `{{double_braces}}` for direct substitution. Templates are organized by communication type and business context. Select the template matching your scenario, substitute variables, review tone guidance, and send. + +--- + +## Table of Contents + +1. [RFP to Energy Suppliers](#1-rfp-to-energy-suppliers) +2. [PPA Term Sheet Response](#2-ppa-term-sheet-response) +3. [Utility Rate Case Intervention Comment](#3-utility-rate-case-intervention-comment) +4. [Demand Response Program Enrollment](#4-demand-response-program-enrollment) +5. [Budget Forecast Presentation](#5-budget-forecast-presentation) +6. [Sustainability Report — Energy Section](#6-sustainability-report--energy-section) +7. [Internal Energy Cost Variance Analysis](#7-internal-energy-cost-variance-analysis) +8. [Supplier Contract Renewal Negotiation](#8-supplier-contract-renewal-negotiation) +9. [Regulatory Filing Comment](#9-regulatory-filing-comment) +10. [Board-Level Energy Strategy Summary](#10-board-level-energy-strategy-summary) + +--- + +## Variable Reference + +Common variables used across templates: + +| Variable | Description | Example | +|---|---|---| +| `{{our_company}}` | Our company legal name | `Meridian Manufacturing Corp.` | +| `{{our_contact_name}}` | Our representative name | `Jennifer Walsh` | +| `{{our_contact_title}}` | Our representative title | `Director of Energy Procurement` | +| `{{our_contact_email}}` | Our representative email | `jwalsh@meridian.com` | +| `{{our_contact_phone}}` | Our representative phone | `(614) 555-0247` | +| `{{supplier_name}}` | Energy supplier name | `NorthStar Energy Solutions` | +| `{{supplier_contact}}` | Supplier contact name | `David Chen` | +| `{{supplier_contact_title}}` | Supplier contact title | `VP, Commercial Sales` | +| `{{utility_name}}` | Utility company name | `AEP Ohio` | +| `{{iso_name}}` | ISO/RTO name | `PJM Interconnection` | +| `{{facility_name}}` | Facility name | `Columbus Manufacturing Plant` | +| `{{facility_address}}` | Facility address | `4500 Industrial Parkway, Columbus, OH 43228` | +| `{{account_number}}` | Utility account number | `110-485-7723` | +| `{{annual_consumption_mwh}}` | Annual electricity consumption | `42,000 MWh` | +| `{{peak_demand_kw}}` | Peak demand in kW | `6,200 kW` | +| `{{current_rate}}` | Current contract rate | `$0.058/kWh` | +| `{{proposed_rate}}` | Proposed new rate | `$0.054/kWh` | +| `{{market_rate}}` | Market benchmark rate | `$0.062/kWh` | +| `{{contract_start}}` | Contract start date | `2027-01-01` | +| `{{contract_end}}` | Contract end date | `2029-12-31` | +| `{{rfp_deadline}}` | RFP response deadline | `2026-05-15` | +| `{{ppa_project_name}}` | Renewable project name | `Prairie Wind Farm II` | +| `{{ppa_capacity_mw}}` | PPA project capacity | `150 MW` | +| `{{ppa_strike_price}}` | PPA strike price | `$34/MWh` | +| `{{ppa_term_years}}` | PPA contract term | `15 years` | +| `{{re_percentage}}` | Current renewable energy percentage | `38%` | +| `{{re_target}}` | RE100 target year | `2030` | +| `{{docket_number}}` | Regulatory docket number | `Case No. 26-1234-EL-AIR` | +| `{{budget_year}}` | Budget forecast year | `2027` | +| `{{total_energy_spend}}` | Total annual energy spend | `$14.2M` | +| `{{num_facilities}}` | Number of facilities | `18` | + +--- + +## 1. RFP to Energy Suppliers + +**Channel:** Email with attached RFP document +**Audience:** Retail energy provider sales/pricing team +**Tone:** Professional, data-rich, competitive. You're offering a significant commercial opportunity — present it as such. + +--- + +**Subject:** `Invitation to Bid — {{our_company}} Electricity Supply RFP — {{contract_start}} Start` + +{{supplier_contact}}, + +{{our_company}} is conducting a competitive electricity supply procurement for {{num_facilities}} facilities across {{iso_name}} territory. We are inviting {{supplier_name}} to participate based on your market position and capabilities in our service territory. + +**RFP Summary:** +- **Scope:** {{num_facilities}} commercial and industrial facilities +- **Total annual consumption:** {{annual_consumption_mwh}} +- **Aggregate peak demand:** {{peak_demand_kw}} +- **Contract period:** {{contract_start}} through {{contract_end}} +- **Product structures requested:** Fixed-price full requirements, block-and-index, and index with price cap +- **Bid deadline:** {{rfp_deadline}}, 5:00 PM ET + +**Included with this invitation:** +1. RFP response template (Excel) with site-level detail +2. 36 months of 15-minute interval data for each facility (CSV) +3. Current tariff information and utility account numbers +4. Evaluation criteria and weighting + +**Evaluation criteria:** +- Total cost across three price scenarios (40%) +- Supplier credit quality and financial stability (20%) +- Contract flexibility including volume tolerance and early termination provisions (15%) +- Sustainability services — REC sourcing, carbon reporting, PPA advisory (15%) +- Market intelligence and advisory capabilities (10%) + +**Key requirements:** +- All bids must include volume tolerance of ±10% minimum +- Pricing must be provided for all three product structures independently +- Supplier must demonstrate minimum BBB credit rating or equivalent +- RECs must be sourced from projects within the {{iso_name}} footprint + +Please confirm your intent to participate by {{rfp_confirmation_date}}. Clarification questions will be accepted through {{rfp_questions_deadline}} via email to {{our_contact_email}}. + +We look forward to {{supplier_name}}'s participation. + +{{our_contact_name}} +{{our_contact_title}} +{{our_company}} +{{our_contact_email}} | {{our_contact_phone}} + +--- + +**Tone Notes:** +- Do not share current pricing with bidders. "Current contract details are confidential" is the standard response. +- Do not disclose the number of bidders. "We have invited a competitive field" is sufficient. +- Respond to all clarification questions in a consolidated Q&A sent to all bidders simultaneously to maintain fairness. + +--- + +## 2. PPA Term Sheet Response + +**Channel:** Email to developer's commercial team +**Audience:** Renewable energy project developer +**Tone:** Collaborative but commercially rigorous. PPAs are 10-25 year commitments — every term matters. + +--- + +**Subject:** `{{our_company}} Response to {{ppa_project_name}} Term Sheet — Commercial Feedback` + +{{developer_contact}}, + +Thank you for the term sheet for {{ppa_project_name}} ({{ppa_capacity_mw}}). We've completed our initial review and have the following feedback organized by commercial, financial, and operational terms. + +**Commercial Terms:** +- **Strike price:** The proposed {{ppa_strike_price}} is within our target range based on current forward curves. We would like to discuss a price escalator structure — 0% escalation for years 1-5 with a [CPI-linked / fixed 1.5%] escalator beginning year 6. +- **Settlement point:** We request settlement at the {{iso_name}} [load zone / hub] rather than the project node, to reduce our basis risk exposure. We understand this may require a price adjustment and are prepared to discuss. +- **Contract volume:** We would like to discuss a partial offtake ({{our_offtake_mw}} MW of the {{ppa_capacity_mw}} project) with right of first refusal on additional capacity. + +**Risk Allocation:** +- **Curtailment:** We request that the developer bear curtailment risk for the first 5% annually, with shared risk (50/50) for curtailment between 5-10%, and developer risk above 10%. The current term sheet allocates all curtailment risk to the offtaker, which is not acceptable for a {{ppa_term_years}}-year commitment. +- **Negative pricing:** We require a negative price floor provision: during intervals when the settlement point LMP is negative, no settlement occurs (neither party pays). This protects both parties from volatile negative pricing hours. +- **Change of law:** The term sheet's change-of-law provision is one-sided. We propose mutual termination rights if a regulatory change materially affects the economics for either party, with a defined materiality threshold of {{materiality_threshold}}. + +**Financial and Credit:** +- **Credit support:** We are prepared to provide [a parent guarantee / an LC] for an amount equal to {{credit_support_amount}}, sized to 2 years of potential negative mark-to-market exposure under our stress scenario. +- **Accounting treatment:** We require confirmation that the PPA structure qualifies for normal purchases and normal sales (NPNS) exception under ASC 815, or alternatively that hedge accounting is achievable. Our treasury team will need to review the final contract with our auditors. + +**REC Provisions:** +- **Vintage delivery:** RECs must be delivered within 12 months of generation to maintain RE100 compliance. +- **Replacement RECs:** If the project underdelivers RECs by more than 10% in any year, the developer provides replacement RECs from a comparable facility at no additional cost. + +We would welcome a call this week to discuss these points. Please suggest availability. + +{{our_contact_name}} +{{our_contact_title}} + +--- + +**Tone Notes:** +- PPA negotiations are multi-round. The first response should establish your key positions without ultimatums. +- Always frame risk allocation as "fair to both parties" rather than "we won't accept your risk." +- Developers receive dozens of term sheet responses — be specific and organized to stand out as a serious offtaker. + +--- + +## 3. Utility Rate Case Intervention Comment + +**Channel:** Formal filing with state Public Utility Commission +**Audience:** PUC commissioners, administrative law judge, utility regulatory staff +**Tone:** Formal, data-driven, legally precise. This is a regulatory proceeding — opinions must be supported by evidence. + +--- + +**Re:** {{docket_number}} — {{utility_name}} Application for Rate Increase + +**Before the {{state}} Public Utilities Commission** + +**Comments of {{our_company}}** + +{{our_company}} respectfully submits these comments regarding {{utility_name}}'s application for a general rate increase filed on {{filing_date}}. + +**I. Interest of {{our_company}}** + +{{our_company}} operates {{num_facilities}} facilities in {{utility_name}}'s service territory, consuming approximately {{annual_consumption_mwh}} annually under rate schedule {{rate_schedule}}. The proposed rate increase would impose an estimated additional cost of ${{annual_impact}} per year on {{our_company}}'s operations. + +**II. Summary of Concerns** + +{{our_company}} does not oppose {{utility_name}}'s right to recover prudently incurred costs and earn a fair return. However, we raise the following concerns regarding the application as filed: + +1. **Requested return on equity (ROE):** {{utility_name}} requests a {{requested_roe}}% ROE. Recent commission decisions in comparable proceedings in {{comparable_states}} have authorized ROEs of {{comparable_roe_range}}%. We respectfully submit that the requested ROE exceeds the range supported by current capital market conditions. + +2. **Rate design:** The proposed rate design increases the volumetric energy charge by {{energy_increase_pct}}% while reducing the demand charge by only {{demand_decrease_pct}}%. This cost allocation methodology disadvantages high-load-factor industrial customers who contribute less to system peak on a per-kWh basis. We recommend cost allocation based on demonstrated cost causation, using a coincident peak methodology for demand-related costs. + +3. **Rider pass-through timing:** The proposed infrastructure improvement rider allows for quarterly rate adjustments without commission review. We request that any rider mechanism include an annual true-up with commission review and a cumulative cap of {{rider_cap_pct}}% to prevent rate shock. + +**III. Requested Relief** + +{{our_company}} requests that the Commission: +- Set ROE at the midpoint of comparable authorized returns (approximately {{recommended_roe}}%) +- Adopt a coincident-peak cost allocation methodology for the {{rate_schedule}} rate class +- Include annual commission review and a cumulative cap on the proposed infrastructure rider + +{{our_contact_name}} +{{our_contact_title}}, {{our_company}} + +--- + +## 4. Demand Response Program Enrollment + +**Channel:** Formal enrollment application +**Audience:** Utility or ISO demand response program administrator +**Tone:** Technical, precise. DR enrollment documents are contractual — accuracy matters. + +--- + +**Subject:** `Demand Response Program Enrollment Application — {{facility_name}}` + +To: {{dr_program_administrator}} + +{{our_company}} hereby applies to enroll {{facility_name}} in the {{dr_program_name}} for the {{delivery_year}} delivery year. + +**Facility Information:** +- **Facility:** {{facility_name}} +- **Address:** {{facility_address}} +- **Utility account:** {{account_number}} +- **Meter ID:** {{meter_id}} +- **Service voltage:** {{service_voltage}} +- **Current peak demand:** {{peak_demand_kw}} + +**Curtailment Capability:** +- **Committed curtailment capacity:** {{dr_commitment_kw}} kW +- **Minimum notification time required:** {{notification_minutes}} minutes +- **Maximum curtailment duration:** {{max_duration_hours}} hours +- **Curtailment method:** [Load shedding via BAS / Backup generation / Battery discharge / Combination] +- **Loads available for curtailment:** {{curtailable_loads}} +- **Loads NOT available for curtailment (critical process):** {{non_curtailable_loads}} + +**Baseline Methodology:** +We request the {{baseline_method}} baseline calculation methodology. Attached is a 12-month interval data file demonstrating our typical load profile during the DR event window ({{event_window}}). + +**Testing:** +We are available for an enrollment verification test during the week of {{test_week}}. We can demonstrate the full {{dr_commitment_kw}} kW curtailment within {{notification_minutes}} minutes of notification. + +{{our_contact_name}} +{{our_contact_title}} + +--- + +## 5. Budget Forecast Presentation + +**Channel:** Internal presentation (PowerPoint / memo) +**Audience:** CFO, VP Finance, Budget Committee +**Tone:** Precise, scenario-based, action-oriented. Finance wants numbers, ranges, and decision points — not energy market tutorials. + +--- + +### {{budget_year}} Energy Cost Forecast — {{our_company}} + +**Prepared by:** {{our_contact_name}}, {{our_contact_title}} +**Date:** {{forecast_date}} +**Scope:** {{num_facilities}} facilities, all electricity and natural gas + +**Executive Summary:** +The {{budget_year}} total energy spend is forecast at **${{base_case_total}}** under base case assumptions, representing a {{yoy_change_pct}}% [increase/decrease] from {{prior_year}} actuals of ${{prior_year_total}}. The forecast range under stress scenarios is **${{low_case_total}}** to **${{high_case_total}}**. + +| Component | {{prior_year}} Actual | {{budget_year}} Base Case | Change | +|-----------|---------------------|--------------------------|--------| +| Electricity — supply | ${{elec_supply_prior}} | ${{elec_supply_forecast}} | {{elec_supply_change}} | +| Electricity — delivery (T&D) | ${{elec_delivery_prior}} | ${{elec_delivery_forecast}} | {{elec_delivery_change}} | +| Electricity — demand charges | ${{demand_charges_prior}} | ${{demand_charges_forecast}} | {{demand_change}} | +| Electricity — capacity charges | ${{capacity_prior}} | ${{capacity_forecast}} | {{capacity_change}} | +| Natural gas | ${{gas_prior}} | ${{gas_forecast}} | {{gas_change}} | +| RECs / sustainability | ${{rec_prior}} | ${{rec_forecast}} | {{rec_change}} | +| **Total** | **${{prior_year_total}}** | **${{base_case_total}}** | **{{total_change}}** | + +**Key Assumptions:** +- Electricity forward curve: {{forward_curve_source}} as of {{curve_date}} +- Natural gas: Henry Hub {{gas_assumption}} + basis of {{basis_assumption}} +- Weather: 10-year normal HDD/CDD +- Production volume: [flat / {{production_change}}% change] vs. prior year +- Hedged position: {{hedge_pct}}% of electricity volume locked at ${{hedged_rate}}/MWh + +**Scenario Analysis:** + +| Scenario | Electricity Cost | Gas Cost | Total | vs. Base Case | +|----------|-----------------|----------|-------|---------------| +| Base case | ${{elec_base}} | ${{gas_base}} | ${{base_case_total}} | — | +| Mild winter / cool summer | ${{elec_low}} | ${{gas_low}} | ${{low_case_total}} | {{low_delta}} | +| Severe winter / hot summer | ${{elec_high}} | ${{gas_high}} | ${{high_case_total}} | {{high_delta}} | +| Market stress (2× forward) | ${{elec_stress}} | ${{gas_stress}} | ${{stress_total}} | {{stress_delta}} | + +**Decisions Requested:** +1. Approve the base case budget of ${{base_case_total}} +2. Authorize procurement of an additional {{additional_hedge_pct}}% hedge to bring total hedged position to {{target_hedge_pct}}% +3. Approve ${{capex_amount}} capital budget for demand charge mitigation at {{capex_facilities}} + +--- + +## 6. Sustainability Report — Energy Section + +**Channel:** Annual sustainability / ESG report +**Audience:** Investors, customers, ESG rating agencies, RE100, CDP +**Tone:** Transparent, data-backed, forward-looking. Avoid greenwashing — ESG audiences are sophisticated. + +--- + +### Energy and Climate — {{report_year}} + +**Scope 2 Emissions:** + +| Metric | {{prior_year}} | {{report_year}} | Change | +|--------|---------------|-----------------|--------| +| Total electricity consumed (MWh) | {{elec_prior_mwh}} | {{elec_current_mwh}} | {{elec_change_pct}} | +| Scope 2 — Location-based (MT CO₂e) | {{scope2_loc_prior}} | {{scope2_loc_current}} | {{scope2_loc_change}} | +| Scope 2 — Market-based (MT CO₂e) | {{scope2_mkt_prior}} | {{scope2_mkt_current}} | {{scope2_mkt_change}} | +| Renewable electricity (%) | {{re_pct_prior}} | {{re_pct_current}} | {{re_change}} | + +**Renewable Energy Procurement:** + +| Instrument | Volume (MWh) | Source | Additionality | +|-----------|-------------|--------|---------------| +| Physical PPA | {{phys_ppa_mwh}} | {{phys_ppa_project}} | New project, operational {{ppa_cod}} | +| Virtual PPA (RECs) | {{vppa_rec_mwh}} | {{vppa_project}} | New project, {{vppa_location}} | +| Utility green tariff | {{green_tariff_mwh}} | {{green_tariff_utility}} | Program-dependent | +| Unbundled RECs | {{unbundled_rec_mwh}} | National wind | Market RECs | +| On-site solar | {{onsite_mwh}} | {{onsite_locations}} | Direct generation | + +**RE100 Progress:** {{our_company}} has achieved {{re_pct_current}}% renewable electricity in {{report_year}}, on track for our commitment of 100% by {{re_target}}. + +**Forward-Looking Targets:** +- {{re_target_next_year}}% renewable electricity by end of {{next_year}} +- Execute additional {{next_ppa_mw}} MW of renewable procurement by Q2 {{next_year}} +- Reduce Scope 2 market-based emissions by {{scope2_reduction_target}}% by {{target_year}} (vs. {{baseline_year}} baseline) + +--- + +## 7. Internal Energy Cost Variance Analysis + +**Channel:** Monthly internal memo +**Audience:** Finance controller, plant managers, VP Operations +**Tone:** Analytical, action-oriented. Explain the "why" behind variances and what's being done about them. + +--- + +**Subject:** `Energy Cost Variance Report — {{month}} {{year}}` + +**Summary:** Total energy cost of ${{actual_total}} vs. budget of ${{budget_total}} — variance of ${{variance}} ({{variance_pct}}). + +**Variance Decomposition:** + +| Driver | Impact | Explanation | +|--------|--------|-------------| +| Weather (HDD/CDD vs. normal) | ${{weather_impact}} | {{month}} was {{weather_description}} — {{hdd_cdd_actual}} vs. {{hdd_cdd_budget}} budgeted HDD/CDD | +| Market price (index exposure) | ${{market_impact}} | Day-ahead LMP averaged ${{actual_lmp}}/MWh vs. budget assumption of ${{budget_lmp}}/MWh | +| Demand charges | ${{demand_impact}} | Peak demand of {{actual_peak_kw}} kW vs. budget of {{budget_peak_kw}} kW at {{facility_name}} | +| Production volume | ${{volume_impact}} | Production hours {{production_description}} vs. plan | +| Rate/tariff changes | ${{tariff_impact}} | {{tariff_description}} | + +**Actions Taken:** +1. {{action_1}} +2. {{action_2}} +3. {{action_3}} + +**Forecast Revision:** Based on YTD actuals, the full-year energy cost forecast is revised to ${{revised_forecast}} (previously ${{prior_forecast}}). Primary driver: {{revision_driver}}. + +--- + +## 8. Supplier Contract Renewal Negotiation + +**Channel:** Email +**Audience:** Incumbent energy supplier's commercial team +**Tone:** Relationship-forward, data-informed. You want to renew if terms are fair — make that clear while establishing competitive tension. + +--- + +**Subject:** `Contract Renewal Discussion — {{our_company}} / {{supplier_name}} — {{contract_end}} Expiration` + +{{supplier_contact}}, + +Our current supply agreement expires {{contract_end}}, and we'd like to discuss renewal terms. {{supplier_name}} has been a valued partner for the past {{contract_duration}}, and we'd like to continue the relationship under commercially competitive terms. + +To frame the discussion, here is our perspective on renewal: + +**What's worked well:** +- Billing accuracy and operational execution have been excellent +- Market intelligence updates have been valuable for our procurement planning +- The account management team has been responsive and proactive + +**Where we'd like to see improvement:** +- Our current rate of {{current_rate}} was competitive at signing but the forward curve for the renewal period ({{contract_start}} through {{new_contract_end}}) is currently {{market_rate}} — we need renewal pricing that reflects current market conditions +- We'd like to discuss [block-and-index structure / increased volume tolerance / REC bundling] for the renewal term + +**Our process:** +We are conducting a competitive evaluation for this renewal. We've invited {{num_bidders}} suppliers to provide indicative pricing. Our decision timeline: +- Indicative pricing review: {{pricing_review_date}} +- Shortlist and final negotiation: {{negotiation_date}} +- Contract execution: {{execution_date}} + +We would welcome a call on {{proposed_call_date}} to discuss {{supplier_name}}'s renewal offer. Please send indicative pricing for the structures outlined above by {{pricing_deadline}}. + +{{our_contact_name}} +{{our_contact_title}} + +--- + +**Tone Notes:** +- Name the competitive process but don't bluff about the number of bidders. +- Lead with what's worked well — the incumbent relationship has value and you should acknowledge it. +- Be transparent about timeline so the supplier can allocate pricing resources. + +--- + +## 9. Regulatory Filing Comment + +**Channel:** Written comment to regulatory body (FERC, state PUC, ISO stakeholder process) +**Audience:** Regulatory commissioners, ISO market design team +**Tone:** Policy-oriented, evidence-based. Regulators respect commenters who understand the market mechanics. + +--- + +**Re:** {{docket_number}} — Proposed Modifications to {{program_or_rule}} + +{{our_company}} appreciates the opportunity to comment on the proposed modifications to {{program_or_rule}}. + +As a large commercial and industrial electricity consumer in {{iso_name}} territory with {{annual_consumption_mwh}} of annual consumption, {{our_company}} has a direct interest in market designs that promote efficient price formation, reliable capacity procurement, and equitable cost allocation. + +**Support / Concern:** +{{our_company}} [supports / has concerns regarding] the proposed modifications, specifically: + +1. **{{provision_1}}:** [Position and rationale with specific reference to the proposal's impact on C&I consumers] +2. **{{provision_2}}:** [Position with quantitative impact estimate if available] +3. **{{provision_3}}:** [Position with alternative proposal if opposing] + +**Recommendation:** +{{our_company}} recommends that the Commission [approve with modifications / reject / defer pending further analysis] the proposed {{program_or_rule}} changes, specifically incorporating the following modifications: +- {{recommendation_1}} +- {{recommendation_2}} + +Respectfully submitted, + +{{our_contact_name}} +{{our_contact_title}}, {{our_company}} + +--- + +## 10. Board-Level Energy Strategy Summary + +**Channel:** Board meeting memo / presentation +**Audience:** Board of Directors, CEO, CFO +**Tone:** Strategic, concise, decision-focused. The board cares about risk, cost trajectory, sustainability commitments, and capital allocation — not market mechanics. + +--- + +### Energy Strategy Update — {{quarter}} {{year}} + +**For the Board of Directors, {{our_company}}** + +**Key Metrics:** + +| Metric | Current | Target | Status | +|--------|---------|--------|--------| +| Annual energy spend | ${{current_spend}} | ${{target_spend}} | {{spend_status}} | +| Energy cost as % of revenue | {{energy_pct_revenue}}% | {{target_pct}}% | {{pct_status}} | +| Renewable electricity (RE100) | {{re_pct_current}}% | 100% by {{re_target}} | {{re_status}} | +| Scope 2 emissions (market-based) | {{current_emissions}} MT CO₂e | {{target_emissions}} MT | {{emissions_status}} | + +**Strategic Priorities:** +1. **Cost management:** [1-2 sentence summary of procurement strategy and results] +2. **Sustainability:** [1-2 sentence summary of RE100 progress and next milestones] +3. **Risk management:** [1-2 sentence summary of hedge position and market outlook] + +**Decisions Requested:** +1. Approve execution of a {{ppa_term_years}}-year virtual PPA with {{ppa_project_name}} at {{ppa_strike_price}} for {{ppa_capacity_mw}} MW — projected NPV of ${{ppa_npv}} over the contract term, delivering {{ppa_annual_recs}} RECs annually toward our RE100 commitment. +2. Authorize ${{capex_amount}} in capital expenditure for battery energy storage at {{capex_facilities}} — projected {{payback_years}}-year payback with stacked value of ${{annual_savings}}/year in demand charge and capacity cost reduction. + +**Risk Summary:** +- Market risk: {{hedge_pct}}% hedged through {{hedge_end}}. Unhedged exposure: ${{unhedged_exposure}} at current forwards. +- Regulatory risk: {{regulatory_summary}} +- Supplier risk: All supply contracts with investment-grade counterparties. No credit concerns. + +**Next Update:** {{next_update_date}} + +--- + +**Tone Notes:** +- Board communication must be under 2 pages. Provide appendices for detail. +- Lead with the "ask" — if you need board approval for a PPA or capital project, put it in the executive summary. +- Quantify everything. "Good progress on sustainability" means nothing. "38% RE, on track for 50% by year-end" means everything. +- Acknowledge risks explicitly. A board that discovers unmentioned risks loses trust in management. diff --git a/web-app/public/skills/energy-procurement/references/decision-frameworks.md b/web-app/public/skills/energy-procurement/references/decision-frameworks.md new file mode 100644 index 00000000..042176b9 --- /dev/null +++ b/web-app/public/skills/energy-procurement/references/decision-frameworks.md @@ -0,0 +1,851 @@ +# Decision Frameworks — Energy Procurement + +This reference provides detailed decision trees, evaluation matrices, financial models, +and strategic frameworks for electricity and gas procurement, tariff optimization, +demand charge management, PPA evaluation, hedging strategy design, and multi-facility +portfolio optimization. It is loaded on demand when the agent needs to make or +recommend nuanced energy procurement decisions. + +All thresholds, price assumptions, and market benchmarks reflect US commercial and +industrial electricity and natural gas markets. Adjust for regional markets, current +forward curves, and facility-specific tariff structures. + +--- + +## 1. Procurement Strategy Selection + +### 1.1 Pre-Procurement Intelligence Gathering + +Before entering any procurement decision — contract renewal, new facility onboarding, +or mid-term restructuring — assemble a comprehensive data package. + +#### Data Assembly Checklist + +| Data Point | Source | Purpose | +|-----------|--------|---------| +| 36 months of 15-minute interval data (kWh and kW) | Utility meter data / MDM system | Load shape analysis, peak identification | +| Current tariff rate schedule and all applicable riders | Utility tariff book / state PUC | Baseline cost structure | +| Current supply contract terms, expiration, and auto-renewal provisions | Contract file | Timeline and constraints | +| Forward energy curves (12, 24, 36 month) for relevant hub | ICE, CME, broker quotes | Market benchmark for pricing evaluation | +| Capacity market auction results (PJM RPM, ISO-NE FCA) | ISO publications | Future capacity charge forecasting | +| Facility peak load contribution (PLC) or installed capacity (ICAP) tag | Utility / ISO settlement data | Capacity charge exposure | +| Historical weather data (HDD/CDD) for facility locations | NOAA / weather service | Weather-normalization of consumption | +| Pending utility rate cases at state PUC | State PUC docket search | Regulatory risk assessment | +| Corporate sustainability targets and timeline | Sustainability team | Renewable procurement requirements | +| Capital budget availability for demand-side investments | Finance team | Investment constraint for demand charge mitigation | + +### 1.2 Fixed vs. Index vs. Block-and-Index Decision Tree + +Use this decision tree for each facility or portfolio segment independently — one +strategy does not fit all sites. + +``` +START: What is the organization's tolerance for energy cost variance? + +├── Budget variance >10% triggers executive escalation +│ ├── Contract tenor ≤ 24 months? +│ │ └── YES → Fixed-price full requirements +│ │ - Accept the risk premium (5-12% above forward curve) +│ │ - Negotiate volume tolerance band (±10-15%) +│ │ - Ensure contract includes change-of-use provisions +│ │ └── NO (>24 months) → Fixed-price with annual price resets +│ │ - Lock year 1 at fixed, years 2-3 at a formula (forward + adder) +│ │ - This limits the supplier's long-term risk premium +│ +├── Budget variance of 5-10% is manageable +│ ├── Facility load factor > 0.70? +│ │ └── YES → Block-and-index +│ │ - Buy fixed blocks = 70-80% of baseload +│ │ - Float remaining 20-30% at index (day-ahead or real-time) +│ │ - Shape blocks to match base load pattern (ATC vs. on-peak only) +│ │ └── NO (load factor < 0.70) → Shaped block-and-index +│ │ - Buy on-peak blocks only (match production schedule) +│ │ - Float off-peak and shoulder at index +│ │ - Supplement with TOU-indexed product for off-peak +│ +├── Organization can tolerate >15% variance (energy is <5% of COGS) +│ ├── Internal capability to monitor wholesale markets? +│ │ └── YES → Index pricing with financial hedges +│ │ - Base product: real-time or day-ahead index + supplier adder +│ │ - Layer financial hedges: buy call options for peak months +│ │ - Set a price ceiling through options ($X/MWh cap) +│ │ └── NO → Index with a price cap product +│ │ - Supplier provides index pricing with a contractual ceiling +│ │ - Cap premium is typically $3-7/MWh above forward curve +│ │ - Simpler than managing separate financial hedges +``` + +### 1.3 Layered Procurement Methodology + +Layering eliminates single-point market timing risk. The methodology: + +**Step 1: Determine the hedging horizon.** +Most C&I buyers layer 18–36 months ahead of the delivery period. For a January 2028 +start date, begin buying tranches in July 2026. + +**Step 2: Set the number of tranches.** +Standard approaches: + +| Tranches | Buying Frequency | Volume per Tranche | Best For | +|----------|-----------------|-------------------|----------| +| 4 | Quarterly | 25% | Default approach, good balance | +| 6 | Bimonthly | ~17% | Large portfolios, higher granularity | +| 8 | Monthly (final 8 months) | 12.5% | Aggressive dollar-cost averaging | +| 12 | Monthly | ~8% | Very large portfolios with dedicated procurement staff | + +**Step 3: Execution rules.** +- Execute each tranche at the prevailing market price on the scheduled date — do not try to time within the tranche window. +- Exception: if the forward curve drops into the bottom 20th percentile of the 5-year range, accelerate by buying 2 tranches immediately ("buy the dip" rule). +- Exception: if the forward curve spikes into the top 20th percentile, defer the current tranche by 30 days (skip and catch up later). +- Never defer more than 2 consecutive tranches — rolling deferrals leave you unhedged. + +**Step 4: Document and report.** +Maintain a procurement log showing: tranche date, volume procured, price locked, +forward curve price at execution, cumulative weighted average price, and remaining +open position. Report to finance quarterly. + +**Example — 10 MW peak load, 60M kWh annual consumption:** + +``` +Delivery year: 2028 +Hedging start: July 2026 +Tranches: 6 (bimonthly, ~10M kWh each) + +Tranche 1 (Jul 2026): 10M kWh @ $44.50/MWh — Forward was $45.20 +Tranche 2 (Sep 2026): 10M kWh @ $42.80/MWh — Forward was $43.10 +Tranche 3 (Nov 2026): 10M kWh @ $46.30/MWh — Forward was $46.30 +Tranche 4 (Jan 2027): 10M kWh @ $41.20/MWh — Forward was $41.50 (buy-the-dip rule: + also executed Tranche 5 early) +Tranche 5 (Jan 2027): 10M kWh @ $41.40/MWh — Accelerated from March +Tranche 6 (May 2027): 10M kWh @ $43.80/MWh — Forward was $44.00 + +Weighted average: $43.33/MWh +Range of execution prices: $41.20 - $46.30 ($5.10 spread) +If locked all-at-once in Jul 2026: $44.50/MWh → layering saved $1.17/MWh = $70,200 +``` + +### 1.4 RFP Process for Deregulated Markets + +#### Timeline and Phases + +| Phase | Duration | Key Activities | +|-------|----------|---------------| +| Pre-RFP Analysis | 2-3 weeks | Load data assembly, tariff analysis, market benchmarking, sustainability requirements definition | +| RFP Design | 1-2 weeks | Template creation, supplier longlist development, evaluation criteria weighting | +| RFP Distribution | 1 week | Issue to 5-8 qualified REPs, respond to clarification questions | +| Bid Window | 2-3 weeks | Suppliers develop pricing based on your interval data and requirements | +| Bid Evaluation | 1-2 weeks | Total cost modeling, credit assessment, contract review | +| Negotiation | 1-2 weeks | Shortlist to 2-3, negotiate terms, finalize pricing | +| Award and Execution | 1 week | Sign contract, notify utility of supplier switch (may require 30-60 day lead time) | +| **Total** | **9-14 weeks** | | + +#### Supplier Evaluation Scoring Matrix + +| Criterion | Weight | Scoring Guide | +|-----------|--------|---------------| +| Total cost (energy + adder + shaped premium) | 35-45% | Lowest total cost = 100 pts. Each 1% above lowest = -5 pts. Model across 3 price scenarios. | +| Credit quality | 15-20% | Investment grade (S&P BBB- or above) = 100 pts. Sub-investment grade = 50 pts. No rating / private = 70 pts with parent guarantee, 30 pts without. | +| Contract flexibility | 10-15% | Volume tolerance ±15% = 100. Volume tolerance ±5% = 50. No tolerance = 0. Early termination available = +20 pts. Change-of-use provisions = +15 pts. | +| Sustainability services | 10-15% | Bundled RECs from named projects = 100. Unbundled RECs available = 60. No REC options = 0. Carbon reporting support = +20 pts. | +| Market intelligence and advisory | 5-10% | Dedicated account manager + regular market updates = 100. Account manager only = 50. Call center support = 0. | +| Operational capability | 5-10% | EDI/API billing integration = 100. Electronic invoicing only = 60. Paper billing = 0. Multi-site consolidated billing = +20 pts. | + +#### Bid Comparison Template + +For each site, model the annual cost under each supplier's proposal: + +``` +Annual Cost = Σ(hourly volume × hourly price) + fixed charges + REC costs + adder fees + +Where hourly price depends on product structure: + Fixed: contract rate for all hours + Block-and-index: block rate for block volume + index price for excess + Index: (day-ahead or real-time LMP at load zone) + supplier adder +``` + +Always model at three forward price scenarios: base case (current forward curve), +low case (forward - 20%), and high case (forward + 30%). A supplier whose index +product looks cheapest at base case may be the most expensive at high case. + +--- + +## 2. PPA Evaluation Framework + +### 2.1 Physical PPA Evaluation + +Physical PPAs involve direct energy delivery and are appropriate when: +- Your load is in the same ISO as the project +- You want both energy and RECs from a specific named facility +- You can manage the operational complexity of scheduling and balancing + +#### Financial Modeling Framework + +**Step 1: Establish the baseline (no-PPA scenario).** +Project your energy costs over the PPA term using forward curves for years 1-5 and +a long-term price escalation assumption (typically 2-3%/year) for years 6+. + +**Step 2: Model PPA cash flows.** + +``` +Year N PPA Net Value = (Market Price at Hub - PPA Strike Price) × Expected Generation + - Basis Cost (Hub to Load Zone) + - Curtailment Cost (expected curtailed MWh × strike price) + - Balancing Costs (firming residual load not covered by PPA) + + REC Value (if RECs would otherwise be purchased separately) +``` + +**Step 3: Sensitivity analysis — run these scenarios at minimum:** + +| Scenario | Market Price Assumption | Generation Assumption | Basis Assumption | +|----------|----------------------|----------------------|-----------------| +| Base | Current forward curve + 2.5%/yr escalation | Developer's P50 estimate | 5-year historical average basis | +| Bull | Forward + 4%/yr escalation | P50 generation | Basis narrows 20% | +| Bear | Forward + 1%/yr escalation | P75 generation (lower) | Basis widens 30% | +| Stress | Flat prices for 5 years, then 2%/yr | P90 generation (much lower) | Basis widens 50% | + +**Step 4: Calculate NPV, IRR, and levelized cost of energy (LCOE) under each scenario.** +A PPA is economically justified if NPV is positive under base and bull cases and +the loss under bear case is tolerable (typically <$2M cumulative over the PPA term +for a mid-size C&I buyer). + +### 2.2 Virtual PPA (VPPA) Evaluation + +VPPAs are financial instruments — no physical energy delivery. The key risks differ: + +#### Basis Risk Analysis + +Basis risk is the primary financial risk in a VPPA. It arises because the generator +settles at its node price and your load settles at your load zone price. + +**Quantification method:** + +1. Obtain 3-5 years of hourly LMP data for the generator's node and your load zone from the ISO. +2. Calculate the hourly basis: Load Zone LMP - Generator Node LMP. +3. Filter to hours when the generator would be producing (solar: daylight hours; wind: use historical generation profile). +4. Calculate the generation-weighted average basis. +5. Model the basis impact on PPA settlement: + +``` +Annual Basis Cost = Σ(hourly basis × hourly expected generation) + +If generation-weighted average basis = $5/MWh and annual generation = 200,000 MWh: +Annual Basis Cost = $1,000,000/year +Over a 15-year PPA: $15M in basis costs (undiscounted) +``` + +**Red flags for basis risk:** +- Basis spread > $8/MWh generation-weighted average → high risk, negotiate basis hedge or reject +- Basis volatility (standard deviation) > $15/MWh → unpredictable, hard to budget +- Basis trend is widening over the historical period → structural congestion, likely to worsen +- Generator is located behind a known transmission constraint → congestion will increase as more generation is added in that zone + +#### Curtailment Risk Analysis + +Curtailment occurs when the ISO orders the generator to reduce output due to +transmission constraints or oversupply. + +| ISO | Technology | Typical Curtailment % | Trend | +|-----|-----------|----------------------|-------| +| ERCOT | Wind (West Texas) | 3-8% | Increasing as more wind is added | +| ERCOT | Solar | 1-3% | Low but increasing | +| CAISO | Solar | 5-12% (spring) | Increasing due to duck curve | +| CAISO | Wind | 1-3% | Stable | +| PJM | Wind | <1% | Minimal | +| PJM | Solar | <1% | Minimal | +| MISO | Wind | 2-5% | Moderate, depends on zone | +| SPP | Wind | 3-7% | Increasing in western zones | + +**Contract protection:** Negotiate a curtailment threshold (e.g., first 5% is developer +risk) and a compensation mechanism for excess curtailment (developer provides +replacement RECs or a price adjustment). Never accept "buyer bears all curtailment +risk" on a VPPA — this transfers a risk the buyer cannot manage or influence. + +#### Credit and Accounting Requirements + +| Requirement | Details | +|-------------|---------| +| ISDA Master Agreement | Required for VPPA. Negotiate credit thresholds, margin call provisions, and termination values. | +| Credit support | Investment grade: typically no collateral for first $5-10M notional. Sub-IG: letter of credit or parent guarantee for 2-3 years of potential negative settlement. | +| Accounting treatment | VPPAs may qualify for hedge accounting (ASC 815) if they meet effectiveness testing requirements. Without hedge accounting, mark-to-market gains/losses flow through the P&L, creating earnings volatility. Consult treasury and accounting early. | +| Board / CFO approval | VPPAs are multi-year financial commitments. Most organizations require board approval for commitments >$10M notional or >10 years. Present as an energy cost management tool, not a speculative position. | + +### 2.3 Physical vs. Virtual PPA Decision Matrix + +| Factor | Favors Physical PPA | Favors Virtual PPA | +|--------|-------------------|-------------------| +| Load location | Same ISO as available projects | Load in regulated market or no nearby projects | +| Energy supply | Need the physical energy (replacing utility supply) | Already have a retail supply contract | +| Sustainability goal | Want bundled energy + RECs from a specific facility | Need RECs only for Scope 2 reporting | +| Operational capability | Have energy scheduling and balancing resources | No energy trading or scheduling staff | +| Balance sheet | Prefer to avoid financial derivative classification | Comfortable with ISDA and mark-to-market | +| Credit profile | Sub-investment grade (physical may require less credit support) | Investment grade (can post collateral efficiently) | +| Regulatory environment | Deregulated market with retail choice | Regulated market (VPPA may be the only option for additionality) | + +--- + +## 3. Demand Charge Optimization + +### 3.1 Load Analysis Methodology + +**Step 1: Download 15-minute interval data.** +Request a minimum of 12 months of 15-minute kW demand data from the utility or your +meter data management system. For facilities with sub-metering, obtain interval data +at the system level (HVAC, production, compressed air) in addition to the main meter. + +**Step 2: Identify peak demand intervals.** +Sort all 15-minute intervals by kW descending. Focus on the top 50 intervals (the +top 0.15% of all intervals in a year). These intervals drive your demand charges. + +**Step 3: Characterize peak drivers.** +For each of the top 50 intervals, identify: +- Date and time of day +- Day of week +- Outdoor temperature (proxy for HVAC load) +- Production schedule (was the line running?) +- Any anomalous events (equipment startup, testing, maintenance) + +**Typical findings for manufacturing facilities:** + +| Peak Driver | Frequency in Top 50 | Root Cause | +|------------|---------------------|------------| +| Morning ramp-up (6-9 AM) | 30-50% | Simultaneous startup of HVAC, compressors, and production lines | +| Hot afternoon (2-5 PM) | 20-35% | HVAC at max coinciding with production peak | +| Equipment startup after maintenance | 10-20% | Inrush current from large motors starting simultaneously | +| Testing / commissioning | 5-10% | New equipment tested during peak periods | + +**Step 4: Calculate the demand charge cost of peak intervals.** + +``` +Monthly Demand Charge = Peak kW × Demand Rate ($/kW) + +If normal operating peak is 4,000 kW and the actual peak is 4,800 kW: +Excess peak cost = (4,800 - 4,000) × $15/kW = $12,000/month + +With an 80% ratchet: +Minimum billing demand for next 11 months = 4,800 × 0.80 = 3,840 kW +If normal peak drops to 3,500 kW next month, you're still billed at 3,840 kW +Annual ratchet cost = (3,840 - 3,500) × $15/kW × 11 months = $56,100 +``` + +### 3.2 Peak Shaving ROI Framework + +#### Battery Energy Storage System (BESS) + +**Sizing methodology:** +1. Determine the target peak reduction (kW to shave). +2. Calculate the required energy capacity: target kW × duration of peak events. + For demand charge management, 1-2 hours of duration is typically sufficient. +3. Apply round-trip efficiency (88-92% for lithium-ion): size the battery 10% larger + than the calculated energy requirement. + +**Example — 500 kW peak shaving at a manufacturing plant:** + +``` +Target reduction: 500 kW +Peak event duration: 2 hours (based on interval data analysis) +Battery size: 500 kW / 1,000 kWh (with 10% efficiency buffer: 500 kW / 1,100 kWh) + +Installed cost (2025): $800-$1,200/kWh for C&I BESS +Total capital: $880,000-$1,320,000 (using 1,100 kWh at midpoint $1,000/kWh = $1,100,000) + +Annual savings stack: + Demand charge savings: 500 kW × $15/kW × 12 months = $90,000 + Capacity tag reduction: 500 kW × $60/kW-yr (PJM example) = $30,000 + TOU energy arbitrage: charge off-peak ($0.04/kWh), discharge on-peak ($0.08/kWh) + 1,100 kWh × $0.04/kWh spread × 250 days × 90% efficiency = $9,900 + Demand response revenue: 500 kW × $40/kW-yr (PJM Economic DR) = $20,000 + +Total annual value: $149,900 +Simple payback: $1,100,000 / $149,900 = 7.3 years +With ITC (30% for standalone storage as of IRA): payback = $770,000 / $149,900 = 5.1 years +``` + +**Decision thresholds:** +- Payback < 5 years (with stacked value + incentives): strong economic case, proceed +- Payback 5-7 years: viable if aligned with sustainability goals or if demand charges are rising +- Payback 7-10 years: marginal, requires additional strategic justification +- Payback > 10 years: economics don't support investment without regulatory mandate + +#### Demand Response Program Evaluation + +Not all DR programs are equal. Evaluate on these dimensions: + +| Dimension | Questions to Answer | +|-----------|-------------------| +| Revenue certainty | Is payment capacity-based (guaranteed $/kW-yr) or performance-based (paid per curtailment event)? | +| Dispatch frequency | How many events per year? What is the maximum duration? Can you sustain curtailment for the full duration? | +| Baseline methodology | How is your curtailment measured? Customer Baseline Load (CBL) using 10-of-10 or adjusted methods? A poorly calculated baseline can understate your curtailment and reduce payments. | +| Penalty for non-performance | What happens if you can't curtail during an event? Some programs impose penalties 2-3× the capacity payment. | +| Interaction with other programs | Does DR enrollment affect your capacity tag calculation? Does it conflict with your behind-the-meter generation? | +| Operational impact | Can your facility actually curtail the committed kW without affecting production quality, safety, or customer commitments? | + +### 3.3 Staggered Startup Protocol + +The single lowest-cost demand charge reduction strategy — no capital required: + +**Problem:** Morning startup creates a demand spike when HVAC, compressors, lighting, +and production equipment all energize simultaneously between 5:30-6:30 AM. + +**Solution:** Stagger equipment startup over a 60-90 minute window: + +``` +5:00 AM — Lighting (50-100 kW) +5:15 AM — HVAC pre-cooling/heating (500-800 kW, ramps over 30 min) +5:45 AM — Compressed air system (200-400 kW, staged compressor starts) +6:00 AM — Production Line 1 (300-500 kW) +6:15 AM — Production Line 2 (300-500 kW) +6:30 AM — Auxiliary systems, battery chargers, water heating + +Result: Peak during startup drops from 2,200 kW (simultaneous) to 1,600 kW (staggered) +Savings: 600 kW × $15/kW × 12 months = $108,000/year at zero capital cost +``` + +**Implementation:** Program the building automation system (BAS) to enforce startup +sequencing. Set hard interlocks that prevent the next system from starting until the +prior system has reached steady state. + +--- + +## 4. Market Analysis Framework + +### 4.1 Regulated vs. Deregulated Strategy Map + +| Your Situation | Primary Strategy | Secondary Strategy | +|---------------|-----------------|-------------------| +| Regulated market, single rate schedule | Demand charge management, on-site generation, tariff schedule optimization | Lobby for utility green tariff, evaluate community solar | +| Regulated market, multiple rate options | Tariff analysis to select optimal schedule (TOU vs. flat vs. demand-based) | Load shifting to exploit TOU differentials | +| Deregulated, single site | Competitive supply procurement (RFP to 5-8 REPs) | Layer procurement to manage timing risk | +| Deregulated, multi-site same ISO | Aggregate sites for portfolio procurement (volume leverage) | Negotiate portfolio-level products (single supplier, blended rate) | +| Deregulated, multi-site multi-ISO | Procure separately by ISO (market structures differ) | Leverage total volume in supplier negotiations even if contracts are separate | +| Mixed regulated/deregulated portfolio | Competitive procurement for deregulated sites; demand management for regulated sites | Seek regulatory pilot programs in regulated territories | + +### 4.2 Forward Curve Analysis + +**What the forward curve tells you:** +- Market consensus on future energy prices (adjusted for risk premium) +- Seasonal price patterns (summer/winter spreads) +- Year-over-year price trajectory (escalation or decline) + +**What the forward curve does NOT tell you:** +- Actual future spot prices (forwards are not forecasts — they include a risk premium) +- Short-term price spikes (forwards are averages, not tails) +- Regulatory changes, plant retirements, or transmission additions not yet priced in + +**Using forward curves for procurement decisions:** + +| Forward Curve Position | Procurement Action | +|-----------------------|-------------------| +| Bottom 20% of 5-year range | Accelerate buying — lock more volume at favorable prices | +| 20th-40th percentile | Proceed with scheduled layering — prices are reasonable | +| 40th-60th percentile | Maintain default layering schedule | +| 60th-80th percentile | Slow buying — defer non-critical tranches 30 days | +| Top 20% of 5-year range | Defer where possible, increase index exposure, evaluate financial hedges instead of physical locks | + +### 4.3 Capacity Market Exposure + +In organized capacity markets (PJM, ISO-NE, NYISO), capacity charges are a significant +cost component — $30–$120/kW-yr depending on the zone and auction results. + +**PJM Reliability Pricing Model (RPM):** +- Auction held 3 years ahead of delivery year (Base Residual Auction) +- Incremental auctions adjust quantities closer to delivery +- Your capacity obligation is based on your PLC (Peak Load Contribution) +- PLC is set by your metered load during the 5 highest system coincident peak hours (5CP) in the prior delivery year + +**Managing capacity exposure:** + +1. **Track PJM system peak alerts.** PJM issues "hot weather alerts" and "emergency alerts" when system peaks are expected. Curtail discretionary load during these hours to reduce your PLC for the following year. +2. **Install peak notification systems.** Subscribe to PJM's demand response alerts. Deploy load curtailment controls that can drop 10-20% of facility load within 30 minutes of a peak alert. +3. **Behind-the-meter generation.** Running backup generators during coincident peak hours reduces your metered load and thus your PLC. Ensure generators are permitted for non-emergency operation and emissions-compliant. +4. **Capacity tag trading.** In some markets, capacity obligations can be traded or offset through financial instruments. Your supplier may offer capacity tag management as a service. + +**Example — capacity charge impact:** + +``` +Facility peak: 5,000 kW +PLC (measured during prior year 5CP hours): 4,200 kW +PJM BRA clearing price for your zone: $85/MW-day + +Annual capacity charge: 4,200 kW × $85/MW-day × 365 / 1,000 = $130,305/year + +If you had curtailed 500 kW during the 5CP hours: +Reduced PLC: 3,700 kW +Annual capacity charge: 3,700 kW × $85/MW-day × 365 / 1,000 = $114,793/year +Savings: $15,512/year from 5 hours of load curtailment +``` + +--- + +## 5. Hedging Strategy Design + +### 5.1 Hedging Instruments Available to C&I Buyers + +| Instrument | Complexity | Capital Required | Protection | +|-----------|-----------|-----------------|------------| +| Fixed-price contract (through REP) | Low | None (embedded in price) | Full price certainty for contracted volume | +| Block purchases (through REP) | Low-Medium | None | Price certainty on base load; variable load exposed | +| Financial swap (through broker/bank) | Medium | ISDA + possible margin | Converts floating price to fixed on specified volume | +| Call option (through broker/bank) | Medium-High | Premium ($/MWh upfront) | Price ceiling at strike + premium; unlimited downside benefit retained | +| Heat rate call option | High | Premium | Protects against gas-to-power price spike (useful when gas drives marginal power price) | +| Collar (sell put, buy call) | Medium-High | Reduced premium (put proceeds offset call cost) | Ceiling and floor — limits both upside and downside | + +### 5.2 Hedging Strategy by Risk Profile + +| Risk Profile | Hedge Ratio | Instruments | Monitoring | +|-------------|-------------|-------------|-----------| +| Conservative (budget certainty paramount) | 80-95% hedged | Fixed-price contracts, financial swaps | Monthly mark-to-market review | +| Moderate (balanced cost/risk) | 60-80% hedged | Block-and-index, layered procurement | Monthly forward curve review, quarterly hedge adjustment | +| Aggressive (cost minimization focus) | 30-60% hedged | Index with call options for tail risk | Weekly market monitoring, daily during volatility events | +| Speculative (never recommended for C&I) | <30% hedged | Index with no protection | Real-time monitoring (impractical for most C&I buyers) | + +### 5.3 Option Pricing and Evaluation + +When buying call options to cap index pricing exposure, evaluate: + +``` +Option value = Max(0, Spot Price - Strike Price) × Volume + +Cost: Premium per MWh × Contracted Volume +Annual premium for a $50/MWh cap on day-ahead pricing: $2-5/MWh (varies by market volatility) + +Example — protecting 50,000 MWh annual index volume: + Call option strike: $50/MWh + Premium: $3/MWh + Total premium cost: $150,000/year + + If spot averages $42/MWh: option expires worthless, total cost = $42 + $3 = $45/MWh + If spot averages $65/MWh: option pays $15/MWh, effective cost = $65 - $15 + $3 = $53/MWh + If spot spikes to $200/MWh (weather event): option pays $150/MWh, effective cap = $53/MWh + + Maximum effective rate: strike + premium = $53/MWh regardless of market price +``` + +**When to use options vs. fixed contracts:** +- Options when you want to participate in downside moves but protect against spikes +- Fixed contracts when the premium for options exceeds the cost of just locking in a fixed price (this happens when volatility is high and options are expensive) + +--- + +## 6. Sustainability Procurement Alignment + +### 6.1 Mapping Procurement to RE100 and SBTi + +**RE100 progress calculation:** + +``` +RE% = (Renewable MWh procured) / (Total electricity consumption MWh) × 100 + +Acceptable renewable MWh sources (in order of additionality): +1. On-site generation (strongest claim) +2. Physical PPA with new project (strong additionality) +3. Virtual PPA with RECs from new project (good additionality) +4. Utility green tariff (varies by program design) +5. Unbundled RECs (weakest claim — RE100 tightening requirements) +``` + +**SBTi trajectory alignment:** +- SBTi requires absolute Scope 2 emissions reductions on a defined trajectory (typically 4.2%/year for 1.5°C alignment). +- Lock in long-term renewable procurement (PPAs) that deliver emission reductions year over year. +- Avoid procurement strategies that increase fossil dependence (long-term fixed contracts with fossil-heavy grid mix and no REC component). + +### 6.2 Cost-Effective Sustainability Procurement Path + +| Target RE% | Least-Cost Strategy | +|-----------|-------------------| +| 0-25% | Unbundled national wind RECs ($1-3/MWh). Cheapest entry point. | +| 25-50% | Utility green tariff + unbundled RECs. Green tariffs are often $0.005-$0.015/kWh premium. | +| 50-75% | VPPA with new wind/solar project. Fixed cost, long-term REC supply, additionality. | +| 75-90% | Physical PPA or additional VPPA to cover remaining gap. On-site solar where feasible. | +| 90-100% | Match remaining unhedged load with project-specific RECs or small on-site installations. The last 10% is the most expensive per MWh. | + +--- + +## 7. Multi-Facility Portfolio Optimization + +### 7.1 Portfolio Aggregation Strategy + +**When to aggregate:** +- 3+ sites in the same ISO/utility territory +- Total volume > 20 GWh/year (attracts competitive supplier attention) +- Sites have complementary load profiles (some peak summer, others peak winter) + +**Aggregation benefits:** +- Volume leverage: 5-15% lower supply pricing than individual site procurement +- Load diversity: combined portfolio has higher load factor than individual sites, reducing supplier risk premium +- Administrative efficiency: single contract, single invoice, single relationship + +**When NOT to aggregate:** +- Sites in different ISOs with different market structures (PJM and ERCOT should be procured separately) +- One site has unique requirements (e.g., real-time pricing needed for a demand response strategy) that would constrain the entire portfolio +- Sites have vastly different contract expiration dates (stagger expirations to avoid all-at-once recontracting risk) + +### 7.2 Portfolio-Level Risk Metrics + +Track at the portfolio level, not just site-by-site: + +| Metric | Formula | Target | +|--------|---------|--------| +| Portfolio hedge ratio | (Hedged MWh / Total expected MWh) × 100 | 60-80% | +| Weighted average procurement price | Σ(site MWh × site $/MWh) / Total MWh | Within 5% of portfolio benchmark | +| Supplier concentration | Largest supplier MWh / Total MWh | <50% (avoid single-supplier dependence) | +| Contract expiration clustering | % of portfolio MWh expiring in any 12-month period | <40% (stagger expirations) | +| Renewable coverage | Renewable MWh / Total MWh | On track to target | +| Portfolio load factor | Total kWh / (Sum of site peak kW × hours) | Track trend, higher is better | + +### 7.3 Site Prioritization for Demand-Side Investment + +With limited capital for demand charge mitigation, prioritize sites using this scoring model: + +| Factor | Weight | Scoring | +|--------|--------|---------| +| Demand charges as % of total bill | 30% | >35% = 100, 25-35% = 70, 15-25% = 40, <15% = 10 | +| Peak-to-average ratio | 25% | >2.5 = 100, 2.0-2.5 = 70, 1.5-2.0 = 40, <1.5 = 10 | +| Available demand reduction (kW) | 20% | >1000 kW = 100, 500-1000 = 70, 200-500 = 40, <200 = 10 | +| Utility demand rate ($/kW) | 15% | >$20 = 100, $15-$20 = 70, $10-$15 = 40, <$10 = 10 | +| Capacity market exposure | 10% | PJM/ISO-NE (high) = 100, NYISO = 70, MISO = 40, none = 0 | + +**Investment priority: highest composite score first.** A site scoring >80 is a strong +candidate for battery storage or demand response. A site scoring <40 has limited +demand charge optimization potential — focus on supply-side procurement instead. + +--- + +## 8. Natural Gas Procurement + +### 8.1 Gas Procurement Structures + +Natural gas procurement for C&I consumers (boilers, CHP, process heat, backup generation) +follows similar principles to electricity but with distinct market mechanics. + +| Structure | Description | Best For | +|-----------|-------------|----------| +| Firm fixed-price | Locked $/therm or $/MMBtu for contract term | Budget certainty, large heating loads | +| Index (first-of-month) | Monthly NYMEX Henry Hub settlement + basis + adder | Cost optimization, risk-tolerant buyers | +| Index (daily) | Daily Gas Daily midpoint + basis + adder | High-flexibility loads, interruptible processes | +| Baseload block + index | Fixed block covers base heating/process load, index covers variable | Facilities with both base process heat and weather-variable HVAC | +| Swing contract | Volume flexibility (50-130% of nominated quantity) | Facilities with highly variable gas consumption | + +### 8.2 Basis Differentials for Natural Gas + +Natural gas prices vary by delivery point. Henry Hub (Louisiana) is the benchmark, +but delivered cost depends on the basis differential between Henry Hub and your +local city gate or utility delivery point. + +**Common basis differentials (approximate):** + +| Delivery Point | Typical Basis to Henry Hub | Driver | +|---------------|--------------------------|--------| +| Chicago (NGPL Midcontinent) | -$0.10 to +$0.15/MMBtu | Pipeline capacity from Gulf to Midwest | +| New York (Transco Zone 6 NY) | +$0.50 to +$3.00/MMBtu | Winter constraint on pipelines into NYC | +| New England (Algonquin) | +$1.00 to +$8.00/MMBtu (winter) | Severe pipeline constraints, competes with LNG | +| California (SoCal Border) | -$0.50 to +$1.50/MMBtu | Varies with West Coast supply/demand | +| Appalachia (Dominion South) | -$1.50 to -$0.30/MMBtu | Oversupply from Marcellus shale production | +| Texas (HSC) | -$0.05 to +$0.20/MMBtu | Close to production, minimal basis | + +**Key insight:** A facility in New England on index pricing faces dramatically different +winter risk than a facility in Texas. Basis in New England during a cold snap can +exceed $15/MMBtu, tripling the delivered gas cost. New England gas procurement +requires winter hedging with firm pipeline capacity or LNG backup — index pricing +without protection is reckless in that market. + +### 8.3 Gas-Electric Interdependency + +For facilities with both electricity and natural gas loads, recognize the coupling: + +- **When gas prices spike, electricity prices spike.** Natural gas is the marginal fuel + for electricity generation in most US ISOs. A $2/MMBtu increase in Henry Hub + translates to approximately $10-$15/MWh increase in wholesale electricity prices + (depending on the average heat rate of marginal gas plants, typically 7,000-8,000 BTU/kWh). + +- **CHP economics are gas-price dependent.** A CHP system generating electricity at + a heat rate of 6,500 BTU/kWh has a fuel cost of $6.50 × gas price per MWh. At gas + $3/MMBtu, generation cost is $19.50/MWh. At gas $8/MMBtu, generation cost is + $52/MWh. If your grid electricity cost exceeds your CHP generation cost, run the + CHP. If grid electricity drops below CHP cost (e.g., during spring shoulder months + with mild weather and low grid demand), consider shutting down CHP and buying + from the grid. + +- **Dual-fuel hedging:** When hedging gas and electricity simultaneously, recognize + that fixing gas costs and leaving electricity at index (or vice versa) creates a + cross-commodity basis risk. If gas prices drop but electricity stays high (due to + transmission constraints or non-gas generation tightness), your gas hedge + underperforms while your electric bill remains high. Consider hedging both + commodities on a correlated basis — many energy suppliers offer combined + gas+electric portfolio management. + +--- + +## 9. Tariff Optimization in Regulated Markets + +### 9.1 Rate Schedule Selection + +In regulated markets, the available tariff options may seem limited, but switching +between rate schedules can save 5-15% on the total bill without changing consumption. + +**Step 1: Identify available rate schedules for your demand level and voltage.** +Most utilities offer 2-4 rate options for large C&I customers: +- Standard demand rate (flat energy + demand charge) +- Time-of-use rate (lower off-peak energy, higher on-peak energy + demand) +- Real-time pricing pilot (if available) +- Interruptible service rate (lower cost, utility can curtail during emergencies) + +**Step 2: Model 12 months of actual interval data against each available rate schedule.** + +``` +For each rate schedule: + Monthly cost = Σ(energy_charge_component) + demand_charge + customer_charge + riders + +Where: + energy_charge_component = Σ(kWh_per_interval × applicable_rate_per_kWh) + demand_charge = max(15-min kW interval in month) × demand_rate + For TOU rates: separate on-peak demand charge may apply +``` + +**Step 3: Compare annual totals.** + +| Rate Schedule | Annual Energy | Annual Demand | Annual Fixed | Annual Total | vs. Current | +|--------------|--------------|---------------|-------------|-------------|-------------| +| Current (GS-3) | $580,000 | $312,000 | $24,000 | $916,000 | baseline | +| TOU (GS-3-TOU) | $545,000 | $298,000 | $24,000 | $867,000 | -$49,000 (-5.3%) | +| RTP pilot | $510,000 | $312,000 | $36,000 | $858,000 | -$58,000 (-6.3%) | +| Interruptible | $565,000 | $250,000 | $24,000 | $839,000 | -$77,000 (-8.4%) | + +**Step 4: Evaluate non-financial factors.** +- TOU: requires ability to shift load or accept higher on-peak costs +- RTP: requires market monitoring and tolerance for price volatility +- Interruptible: requires ability to curtail load on short notice (typically 30-60 min) + +### 9.2 Rate Case Monitoring and Response + +**When to intervene in a rate case:** + +| Impact Level | Annual Cost Increase | Recommended Action | +|-------------|---------------------|-------------------| +| <$50K | Negligible for large C&I | Monitor only — track filing through settlement | +| $50K-$200K | Material but not critical | Join existing intervenor group (OIEC, etc.) | +| $200K-$500K | Significant | Individual intervention with regulatory counsel | +| >$500K | Critical | Full intervention with expert witnesses, rate design testimony | + +**Rate case timeline (typical):** + +``` +Month 0: Utility files rate case with state PUC +Month 1-2: Intervenors file to participate +Month 3-4: Discovery (interrogatories, data requests to utility) +Month 5-7: Intervenor testimony filed +Month 8-9: Hearings +Month 10-12: PUC issues order +Month 13-15: New rates take effect (may be retroactive to filing date) +``` + +**What to challenge in a rate case:** +1. **Rate of return on equity (ROE):** Utilities typically request 10-11% ROE. Current + authorized ROEs are trending down (9-10%). Challenge excessive ROE requests. +2. **Rate base additions:** Utilities earn their ROE on their rate base (invested capital). + Challenge excessive or imprudent capital investments included in the rate base. +3. **Cost allocation between rate classes:** Utilities allocate total revenue + requirement across residential, commercial, and industrial rate classes. Ensure your + rate class is not subsidizing residential or other classes above cost causation. +4. **Rate design:** Even if the total revenue is approved, fight for demand-based rate + design (rewards load factor management) rather than pure volumetric rates (punishes + high-consumption customers regardless of load shape). + +--- + +## 10. Emergency Procurement Protocols + +### 10.1 Supplier Default / Bankruptcy + +If your retail energy provider files for bankruptcy or fails to perform: + +**Immediate actions (24-48 hours):** +1. Verify your account status with the utility. If the supplier defaults, your + account reverts to the utility's Provider of Last Resort (POLR) service or standard + offer service. You will NOT lose power — the grid keeps delivering regardless of + supplier status. +2. Determine the POLR rate. In most states, the POLR rate is set quarterly based on + wholesale market prices plus a premium (10-20% above competitive supply). This may + be higher or lower than your current contract rate. +3. Contact 2-3 alternative suppliers immediately. Explain the situation — they will + offer expedited enrollment (5-10 business days vs. normal 30-60 day switch process). +4. Review your contract for supplier default provisions, including any deposits or + prepayments that may be at risk in the bankruptcy estate. + +**Medium-term (2-4 weeks):** +1. Execute a new supply contract with the best available alternative supplier. +2. File a claim in the bankruptcy proceeding for any prepayments, deposits, or damages. +3. Review your supplier qualification criteria — consider adding financial covenants + (minimum credit rating, tangible net worth requirements) to future contracts. + +### 10.2 Force Majeure Events + +When a force majeure event (natural disaster, grid emergency, pandemic) disrupts +your energy supply or operations: + +**Assessment framework:** + +| Event Type | Energy Impact | Procurement Response | +|-----------|--------------|---------------------| +| Hurricane/severe weather | Physical damage to generation/T&D, price spikes | Activate backup generation, curtail non-essential load, document for insurance | +| Grid emergency (EEA3) | Rolling blackouts, extreme prices | Maximum load curtailment, DR activation, generator deployment | +| Supplier force majeure claim | Supplier attempts to suspend contract | Review FM clause narrowly — "market price increase" is NOT force majeure; "physical inability to deliver" may be | +| Pandemic/operational shutdown | Facility closed, consumption drops dramatically | Invoke volume tolerance provisions, negotiate contract suspension, evaluate early termination | + +### 10.3 Contract Termination Decision Matrix + +When evaluating whether to terminate a supply contract early: + +``` +Early Termination Fee (ETF) = Σ(remaining months × monthly volume × |contract price - current market price|) + +If contract price > current market: + You owe the supplier (you're paying above market) + ETF = remaining months × volume × (contract price - market) × discount factor + +If contract price < current market: + Supplier owes you (you have a favorable contract) + You would NOT terminate — the contract is in-the-money + +Decision: Terminate if ETF < cumulative savings from alternative contract + risk reduction value +``` + +**Example — mid-term exit evaluation:** + +``` +Current contract: $0.062/kWh, 18 months remaining, 50 GWh remaining +Current market: $0.055/kWh (market has dropped since contract signing) +ETF: 50,000 MWh × ($0.062 - $0.055) = $350,000 + +Alternative contract: $0.054/kWh for 18 months +Savings from alternative: 50,000 MWh × ($0.062 - $0.054) = $400,000 + +Net benefit of termination: $400,000 savings - $350,000 ETF = $50,000 + +Decision: Marginal. Factor in: + - Renegotiation risk (can you lock $0.054 before market moves?) + - Administrative cost of switching suppliers + - Relationship cost with current supplier + - If net benefit < $100K, generally not worth the disruption +``` + +--- + +## 11. Seasonal Procurement Calendar + +A disciplined procurement calendar ensures no critical deadlines are missed and +procurement activities align with market conditions. + +| Month | Activity | Deadline | +|-------|----------|----------| +| January | Annual energy budget review, lock natural gas hedges for next winter | Jan 31 for winter gas | +| February | Q1 forward curve review, PPA pipeline assessment | — | +| March | Begin RFP preparation for contracts expiring in Q4 or Q1 next year | — | +| April | Issue RFPs for fall contract starts, review summer DR enrollment | Apr 15 for PJM DR enrollment | +| May | Evaluate bids, begin summer peak preparation (generator testing, BAS settings) | May 31 for summer rate elections | +| June | Summer peak demand management begins, monitor 5CP forecasts (PJM) | — | +| July | Peak season monitoring, execute Q3 procurement tranches | Jul 15 for ERCOT 4CP mgmt | +| August | Peak season monitoring, finalize fall contract awards | Aug 31 for ISO-NE FCA positions | +| September | Post-summer review, capacity tag assessment, RE100 progress check | Sep 30 for Q4 procurement | +| October | Begin winter gas hedging, review heating load forecasts | Oct 31 for winter gas locks | +| November | Budget season — prepare next year's energy cost forecast | Nov 15 for budget submission | +| December | Year-end RE100 reconciliation, REC inventory check, contract renewals | Dec 31 for REC vintage retirement | diff --git a/web-app/public/skills/energy-procurement/references/edge-cases.md b/web-app/public/skills/energy-procurement/references/edge-cases.md new file mode 100644 index 00000000..53a9d55e --- /dev/null +++ b/web-app/public/skills/energy-procurement/references/edge-cases.md @@ -0,0 +1,624 @@ +# Energy Procurement — Edge Cases Reference + +> Tier 3 reference. Load on demand when handling complex energy procurement situations that don't resolve through standard decision frameworks. + +These edge cases represent the scenarios that separate experienced energy procurement managers from everyone else. Each involves competing priorities, market structure nuances, regulatory complexity, and real financial exposure. They are structured to guide resolution when standard procurement playbooks break down. + +--- + +## How to Use This File + +When an energy procurement situation doesn't fit a clean decision tree — when market dynamics create conflicting incentives, when tariff structures produce counterintuitive outcomes, or when a PPA that looked good at signing turns problematic — find the edge case below that most closely matches the situation. Follow the expert approach step by step. + +--- + +### Edge Case 1: ERCOT Price Spike During Extreme Winter Weather (Uri-Type Event) + +**Situation:** +A food manufacturing company operates two facilities in Texas: a 6 MW production plant in Houston and a 3 MW distribution center in Dallas. Both are on index-priced supply contracts (ERCOT real-time settlement node price + $0.004/kWh supplier adder). During a February polar vortex event, temperatures drop to 5°F in Houston (normal February low: 42°F). ERCOT declares an Energy Emergency Alert Level 3 (EEA3) and implements rolling blackouts. Real-time wholesale prices hit the ERCOT system-wide offer cap of $5,000/MWh (during Uri in 2021, the cap was $9,000/MWh). The event lasts 5 days. The Houston plant has backup natural gas generators but cannot run them because natural gas supply has been curtailed due to wellhead freeze-offs. The Dallas facility has no backup generation. + +Your weekly energy cost is normally $85,000 across both sites. During this event, the projected weekly cost at $5,000/MWh average for 120 hours of peak pricing would exceed $4.5M. + +**Why It's Tricky:** +The contract is working as designed — index pricing means you pay the market price. There is no breach, no force majeure claim against the supplier (they are delivering at index), and no contractual price cap unless you negotiated one. The financial exposure is catastrophic for a company where annual energy spend is $5M. A single week could equal the entire annual budget. + +Simultaneously, you need to keep the food production plant running (product in process will spoil if power is lost) and the distribution center must maintain cold chain for $8M of perishable inventory. Shutting down to reduce energy cost means accepting $3–$5M in product loss. + +**Common Mistake:** +Keeping both facilities at full load throughout the event and accepting the $4.5M bill as a cost of doing business. The second mistake: attempting to renegotiate or dispute the contract after the event — courts consistently enforce index pricing during price spikes because that is the contract structure. + +**Expert Approach:** +1. **Immediate load curtailment (Hour 0-4):** Reduce all discretionary load at both facilities. Target: 30-40% load reduction without shutting production lines. Turn off office HVAC (employees can layer up for a week), reduce warehouse lighting to emergency levels, shut down non-essential compressed air (only keep production-critical compressors), and turn off electric water heaters. A 35% load reduction on 9 MW combined peak saves approximately $1.6M over 5 days at $5,000/MWh. + +2. **Production schedule modification (Hour 4-12):** Shift production to overnight hours (10 PM - 6 AM) when prices typically dip to $1,000-$2,000/MWh even during extreme events (the sun isn't up, wind may be producing, and some thermal generation returns overnight). Run the Houston plant at minimum load during daytime peak hours (keep product in process alive but don't start new batches). + +3. **Demand response activation (Hour 0):** If enrolled in any ERCOT demand response program (ERS or 4CP programs), curtail to earn the event payment. This partially offsets the extreme energy cost. An ERS enrollment for 1 MW could pay $2,000-$5,000 per event hour depending on the program. + +4. **Generator options (Hour 2-6):** Contact your natural gas supplier and pipeline operator about gas availability. If pipeline gas is curtailed, evaluate diesel portable generators — rental generators during extreme weather events cost $50-$100/kW per day but at $5,000/MWh wholesale, generation cost at even $150/kW/day is far cheaper than grid power. Contact industrial generator rental companies immediately — they will be overwhelmed within 24 hours. + +5. **Supplier communication (Hour 0):** Contact your retail energy provider to understand their exposure and settlement timeline. Some REPs offer post-event payment plans. If your REP is likely to fail (several REPs went bankrupt after Uri), your account reverts to the utility's Provider of Last Resort (POLR) rate — which during an emergency may be even higher. Prepare for this contingency. + +6. **Post-event restructuring (Week 2+):** After the event, restructure your energy contracts. For ERCOT exposure, never go fully unhedged into winter. Options include: + - Add a price cap to your index contract ($100-$200/MWh ceiling, costs $2-$5/MWh in premium) + - Switch to block-and-index with blocks covering 80% of winter load + - Purchase OTC call options that cap your exposure above a strike price + - Maintain a cash reserve equal to 2 weeks of energy cost at $500/MWh + +**Key Indicators:** +- ERCOT weather forecasts showing temperatures >20°F below seasonal norms for >3 days warrant pre-event hedging action +- Natural gas spot prices at Houston Ship Channel exceeding $10/MMBtu signal potential generator fuel supply issues +- ERCOT Conservation Voltage Reduction or EEA Level 1 declarations are early warnings — act before EEA3 +- Monitor ERCOT's generation outage report: if forced outages exceed 20 GW, price spikes above $1,000/MWh are likely + +**Documentation Required:** +- Real-time price records from the ISO settlement system +- Facility load data during the event (to demonstrate curtailment efforts for internal reporting and potential rate dispute) +- Generator rental invoices and fuel costs +- Communication log with REP and utility +- Total financial exposure calculation for executive and board reporting +- Post-event contract restructuring analysis + +**Resolution Timeline:** +- Hours 0-6: Implement all immediate load curtailment measures +- Hours 6-24: Execute production schedule shifts, secure backup generation if available +- Days 2-5: Maintain curtailed operations, monitor market for normalization signals +- Week 2: Receive preliminary settlement from REP, assess total financial impact +- Week 3-4: Initiate contract restructuring discussions with REP +- Month 2-3: Execute new contract structure with winter price protection + +--- + +### Edge Case 2: Virtual PPA Basis Risk in a Congested Transmission Zone + +**Situation:** +A technology company headquartered in Northern Virginia (PJM territory, Dominion zone) executed a 15-year VPPA with a 100 MW wind farm in western PJM (AEP zone, near the Ohio-West Virginia border). The VPPA strike price is $32/MWh, which at signing was $12/MWh below the PJM Western Hub forward curve of $44/MWh. The company projected $1.2M/year in positive settlement value, plus 350,000 RECs annually for their RE100 commitment. + +After 18 months of operation, the actual financial performance shows persistent negative settlements. The wind farm generates during overnight and shoulder hours when AEP zone LMPs average $28/MWh. The company's load zone (Dominion) averages $48/MWh during the same hours due to transmission congestion between AEP and Dominion zones. The generation-weighted average basis (Dominion LMP minus AEP node LMP) is $14/MWh. + +Net financial impact: the wind farm settles at $28/MWh average, which is $4/MWh below the $32 strike, meaning the company owes the developer $4/MWh. Plus the $14/MWh basis spread means the company's effective energy cost premium from the VPPA is $18/MWh — turning a projected $1.2M/year benefit into a $2.1M/year cost. + +**Why It's Tricky:** +The VPPA contract is performing as written — the settlement is based on the generator's node price, not the company's load zone price. Basis risk was disclosed during contracting, but the company's internal projection used a 3-year historical average basis of $6/MWh (which was correct at the time). The basis widened due to new generation additions in AEP zone and continued transmission constraints into the Dominion zone — structural factors that will likely persist or worsen. + +The company cannot exit the VPPA without paying a termination fee based on the mark-to-market value, which at negative $2.1M/year for the remaining 13.5 years, discounted at 8%, is approximately $16M. The RECs are still valuable — 350,000 RECs at $5/REC = $1.75M/year — partially offsetting the financial loss, but the net economics are negative. + +**Common Mistake:** +Terminating the VPPA immediately and paying the $16M termination fee. This crystallizes the loss. The second mistake: ignoring the problem and hoping basis narrows — structural congestion rarely self-corrects without transmission investment. + +**Expert Approach:** +1. **Quantify the actual basis exposure.** Request hourly settlement data from the PPA counterparty. Calculate generation-weighted basis for each month. Identify whether basis is seasonal (wider in summer when AC load drives Dominion congestion) or persistent year-round. + +2. **Model forward basis expectations.** Engage an energy consultant or your supplier's market analytics team to model forward basis between AEP and Dominion zones. Key factors: planned transmission upgrades (PJM RTEP projects that relieve the constraint), new generation additions in AEP zone (more wind/solar behind the constraint worsens basis), and load growth in Dominion zone. + +3. **Evaluate basis hedging.** PJM offers Financial Transmission Rights (FTRs) that can hedge congestion costs between two points on the grid. Purchase FTRs from the AEP zone to the Dominion zone in the PJM FTR auction. An FTR paying $10/MWh on 350,000 MWh = $3.5M/year, which significantly offsets the basis loss. FTR costs vary — the auction determines the price, and popular paths (like AEP-to-Dominion) may be expensive. Budget $5-$8/MWh for FTR basis hedging. + +4. **Renegotiate the settlement point.** Approach the developer about switching the settlement point from the generator's node to the Western Hub or a more liquid hub closer to your load zone. The developer may accept this if the hub price is close to their node price (it often is — hub prices are less volatile than nodal prices). This doesn't eliminate basis risk but may reduce it. + +5. **Restructure the contract.** Options include: + - Reduce the contract volume (buy down from 100 MW to 60 MW, reducing exposure while keeping some REC delivery) + - Add a basis risk sharing mechanism (developer absorbs basis beyond $8/MWh) + - Convert to a fixed-price REC purchase (eliminate the energy settlement entirely, pay a fixed $/REC) + +6. **Portfolio-level offset.** If you have other facilities in the AEP zone, the VPPA's node-price settlement is actually favorable for loads in that zone (where LMPs are lower). Consider whether any current or planned facility expansion in AEP territory could benefit from the VPPA's economics. + +**Key Indicators:** +- Basis widening beyond 150% of historical average for 2+ consecutive quarters signals structural change +- PJM RTEP transmission projects targeting the constrained corridor may take 5-7 years to complete +- New generation interconnection queue in the generator's zone exceeding 3 GW is a bearish signal for basis +- FTR auction results showing increasing clearing prices on the relevant path confirm market recognition of the congestion + +**Documentation Required:** +- Monthly VPPA settlement statements +- Hourly generation-weighted basis calculations +- FTR auction results and cost analysis +- Developer communication regarding contract restructuring +- Board-level financial exposure report +- Revised forward-looking PPA valuation under multiple basis scenarios + +--- + +### Edge Case 3: Demand Charge Ratchet Trap After Equipment Installation + +**Situation:** +A plastics manufacturer in Georgia Power territory installed a new 1,200 kW production line. During commissioning week, the electrical contractor tested all equipment simultaneously at full load — standard practice for commissioning acceptance testing. The test occurred on a Wednesday afternoon in August, coinciding with the facility's normal summer HVAC peak. The 15-minute interval data shows a peak demand of 5,800 kW — compared to the facility's normal summer peak of 4,200 kW. + +Georgia Power's PLM-4 tariff includes an 80% demand ratchet. The billing demand for the next 11 months cannot fall below 80% of the maximum demand in the prior 11 months. The new floor: 5,800 × 0.80 = 4,640 kW. During winter months, when normal demand drops to 3,200 kW, the facility will be billed for 4,640 kW. + +Additional demand charges: (4,640 - 3,200) × $12.50/kW × 7 winter months = $126,000 in excess demand charges. And the new production line's normal operating demand of 900 kW (not the 1,200 kW commissioning peak) means the facility's normal summer peak going forward is 5,100 kW — still below the ratchet. Even in summer, the facility is billed for 5,800 kW peak demand. + +Annual excess demand charges from the commissioning peak: approximately $174,000. + +**Why It's Tricky:** +The damage is done — a single 15-minute interval set the peak, and the ratchet clause is contractual. Georgia Power has no tariff provision for removing ratcheted demand due to commissioning events. You cannot dispute the meter reading (the test genuinely drew 5,800 kW). The only way to "reset" the ratchet is to either (a) wait 11 months for the peak to roll off, or (b) consistently hit a higher peak that makes the ratchet irrelevant (which would mean higher demand charges anyway). + +**Common Mistake:** +Calling Georgia Power and asking them to waive the ratchet. They won't — it's a tariff provision approved by the Georgia Public Service Commission, not a negotiable contract term. The second mistake: assuming nothing can be done and absorbing the $174K cost. + +**Expert Approach:** +1. **Immediate investigation (Day 1):** Pull the interval data for commissioning week. Identify the exact 15-minute interval(s) that set the new peak. Determine whether the peak was caused by legitimate commissioning (all equipment at rated load) or by an avoidable event (existing HVAC running at maximum while new equipment was at full test load). + +2. **Tariff analysis:** Review the PLM-4 tariff document line-by-line. Some tariffs have provisions for "temporary service" or "construction power" that could apply if the commissioning load was billed under a temporary service agreement. If the contractor should have been on temporary service during commissioning, the peak may not count against the permanent meter. This is rare but worth checking. + +3. **Demand response enrollment:** Georgia Power offers demand response programs that can provide credit against demand charges. If the facility can commit to curtailing 800-1,000 kW during summer peak events, the DR credit may offset a significant portion of the ratchet cost. Enroll immediately — programs have seasonal enrollment windows. + +4. **Operational changes to reduce the ratchet impact:** Since the ratchet is based on the single highest 15-minute interval, focus on ensuring that the facility NEVER exceeds 5,800 kW again (which would reset the ratchet at a higher level). Install a demand controller on the main meter that sheds non-critical loads (compressed air, water heating, battery chargers) whenever demand approaches 5,500 kW. + +5. **Future prevention protocol:** Establish a policy that all equipment commissioning involving loads >200 kW must be scheduled during off-peak hours (overnight or weekends), with the building HVAC in setback mode and non-essential production loads off. The commissioning electrician should coordinate with the energy manager, not just the maintenance supervisor. Include this requirement in all future capital project specifications. + +6. **Financial recovery:** If the electrical contractor failed to follow a commissioning plan that specified load management during testing, evaluate whether the excess demand charges ($174K) are recoverable as consequential damages under the construction contract. Review the contract's commissioning provisions and liability clauses. + +**Key Indicators:** +- Any planned equipment installation >200 kW capacity should trigger a commissioning demand management plan +- Request interval data within 48 hours of commissioning to identify ratchet exposure before the billing cycle closes +- If your tariff has a demand ratchet, the energy manager must be involved in all capital project commissioning plans + +--- + +### Edge Case 4: Utility Rate Case Filing Mid-Contract + +**Situation:** +A hospital system with 12 facilities in Ohio (AEP Ohio territory) has a 36-month fixed-price electricity supply contract with a competitive retail energy provider at $0.052/kWh for the energy component. The contract was signed 8 months ago. AEP Ohio has just filed a distribution rate case with the Public Utilities Commission of Ohio (PUCO), proposing a $480M revenue increase across all rate classes — an average 18% increase in distribution charges. + +For the hospital system's rate class (GS-3 General Service-Large), the proposed increase translates to approximately $0.014/kWh in additional distribution charges. Across the hospital system's 180 GWh annual consumption, the annual cost increase would be approximately $2.52M. The current total delivered cost is $0.088/kWh; the proposed distribution increase would raise it to $0.102/kWh — a 16% total cost increase. + +The fixed-price supply contract covers only the energy and capacity components ($0.052/kWh). Distribution charges, transmission charges, riders, and surcharges are pass-through items — the hospital system pays whatever the utility tariff dictates. + +**Why It's Tricky:** +The supply contract is performing as agreed. The $0.052/kWh energy price is locked. But the total delivered cost is increasing by $2.52M/year, and the hospital system's CFO expected the "fixed-price contract" to provide budget certainty on the total energy bill. The disconnect between "supply is fixed" and "delivery is pass-through" is one of the most common misunderstandings in commercial energy procurement. + +The rate case will take 12-18 months to adjudicate. The proposed $0.014/kWh increase is the utility's opening position — the final settlement typically lands at 50-75% of the proposed increase. But even a 50% outcome ($0.007/kWh) means $1.26M/year in additional costs. + +**Common Mistake:** +Ignoring the rate case because "we have a fixed-price contract" and only discovering the cost increase when the new tariff rates take effect. The second mistake: blaming the energy supplier for not protecting against distribution rate increases — the supplier explicitly passes these through in the contract, and there is no commercial product that can fix distribution rates (these are regulated, not competitive). + +**Expert Approach:** +1. **Rate case analysis (Week 1):** Obtain the full rate case filing from the PUCO docket. Focus on the cost of service study for the GS-3 rate class. Identify what specific distribution cost components are driving the increase (infrastructure replacement, storm hardening, grid modernization, rate of return request). Calculate the exact impact on each hospital facility based on their billing determinants. + +2. **Intervention evaluation (Week 2-3):** Large C&I customers have the right to intervene in rate cases. Intervention allows you to file testimony challenging the utility's cost allocation, rate design, or revenue requirement. The hospital system's $2.5M+ annual impact justifies the cost of intervention ($50K-$150K in legal and expert witness fees). Contact a utility regulatory attorney in Ohio. + +3. **Coalition building (Week 2-4):** Join the Ohio Industrial Energy Consumers (OIEC) or similar industrial intervenor group. These organizations pool resources to intervene in rate cases, reducing individual company costs to $10K-$30K/year in membership fees while providing professional regulatory representation. + +4. **Rate design advocacy:** Even if the total revenue increase is approved, the rate design (how the revenue is allocated across rate classes and billing determinants) can be influenced. Advocate for cost allocation that reflects actual cost causation — hospitals with high load factors and coincident peak management should pay less per kWh in distribution than low-load-factor commercial buildings. File testimony supporting demand-based distribution rates rather than volumetric rates. + +5. **Budget adjustment (Month 1):** Present the rate case exposure to the hospital system's CFO immediately. Provide three scenarios: full proposed increase ($2.52M/year), likely settlement (60% = $1.51M/year), and best case (40% = $1.01M/year). Recommend budgeting at the likely scenario and establishing a reserve for the upside case. The rate case outcome is 12-18 months away, but budget planning should begin immediately. + +6. **Demand-side response:** A rate case that increases distribution charges makes demand charge management more valuable. Every kW of peak reduction now saves more per month. Re-run the ROI analysis for battery storage, demand response, and load management projects with the proposed new rates — projects that were marginal at old rates may now have strong payback. + +**Key Indicators:** +- Monitor your state PUC docket for utility rate case filings quarterly +- Track the authorized rate of return — utilities filing for ROE >10% in the current interest rate environment will face pushback +- Rate cases proposing >15% overall increases typically settle at 50-65% of the request +- Infrastructure replacement riders often bypass rate case proceedings — monitor these separately + +**Documentation Required:** +- Rate case docket filing and all testimony +- Facility-level billing determinant analysis +- Impact assessment under proposed and likely settlement scenarios +- Intervention timeline and cost estimate +- Budget revision memo for CFO +- Coalition membership evaluation + +--- + +### Edge Case 5: Negative LMP Pricing Affecting PPA Economics + +**Situation:** +A consumer products company has a 20-year physical PPA with a 50 MW solar farm in CAISO (Central California). The PPA price is $28/MWh with a clause that the offtaker purchases all energy generated at the contract price. During spring months (March-May), CAISO experiences significant solar oversupply during midday hours. Day-ahead LMPs at the project's node have gone negative — averaging -$8/MWh between 10 AM and 2 PM on weekdays during April. + +When LMPs are negative, the generator actually earns negative revenue in the wholesale market (they would have to pay to inject power). However, under the PPA terms, the offtaker (the company) is obligated to purchase at $28/MWh regardless of the market clearing price. During these negative-price hours, the effective premium the company pays is $28 - (-$8) = $36/MWh above market. In April alone, 120 hours of negative pricing on an average 35 MW output represents: 120 hrs × 35 MW × $36/MWh premium = $151,200 of above-market cost in a single month. + +Annually, negative pricing during spring months creates approximately $400K-$600K in above-market costs. This was not modeled in the original PPA financial analysis, which assumed LMPs would always be positive. + +**Why It's Tricky:** +The PPA contract requires the company to purchase all generated output at $28/MWh. The contract was signed when CAISO negative pricing was infrequent (occurring <50 hours/year). Since then, solar buildout has accelerated, and negative pricing now occurs 500-800 hours/year in central California during spring. This is a structural trend — it will get worse as more solar is added. + +The solar farm continues to generate during negative-price hours because it earns the $28/MWh PPA price (a positive return) plus federal production tax credits ($0.026/kWh), which together exceed its marginal operating cost of effectively $0. The developer has no economic incentive to curtail during negative price hours as long as the PPA requires the offtaker to buy the output. + +**Common Mistake:** +Demanding that the developer curtail during negative price hours (the contract doesn't require this). The second mistake: building a financial model that assumes negative pricing will revert to historical norms — the structural drivers are getting stronger, not weaker. + +**Expert Approach:** +1. **Contract review:** Examine the PPA for any provisions related to economic curtailment, negative pricing, or market price floors. Modern PPAs (post-2020) often include a "negative price curtailment" clause where the developer is curtailed when market prices go negative for >2 consecutive hours, and the offtaker is not obligated to purchase during curtailed hours. Older PPAs may lack this provision. + +2. **Economic curtailment negotiation:** Approach the developer to add a negative price curtailment provision. The developer's perspective: they lose PPA revenue ($28/MWh) and may lose PTC value during curtailed hours, but they also avoid the operational cost of generating into a negative-price market and maintain grid operator goodwill (CAISO can mandate curtailment for reliability — voluntary curtailment preserves the developer's standing). Propose: curtailment when the 15-minute LMP is negative, with the developer retaining RECs for curtailed hours (they can sell them separately to partially offset lost PPA revenue). + +3. **REC value assessment:** Quantify the REC value for curtailed hours. If the company needs 175,000 RECs/year for RE100 and the PPA delivers 160,000 RECs (net of curtailment), the company must purchase 15,000 replacement RECs at market price ($8-$15/MWh for CAISO solar RECs). Compare this cost ($120K-$225K) against the negative-price exposure ($400K-$600K). The math likely favors curtailment. + +4. **Behind-the-meter storage pairing:** If the company has a facility near the solar farm (or in the same utility territory), pairing a battery with the solar PPA allows absorption of midday generation for discharge during evening peak hours when LMPs are highest. This converts the negative-price exposure into a TOU arbitrage opportunity. A 10 MW / 40 MWh battery co-located with or at the facility could shift 4 hours of midday production to evening hours, capturing a $50-$80/MWh spread. + +5. **Settlement structure revision:** Negotiate a change from "buy all output at $28/MWh" to "buy all output at $28/MWh with a market price floor of $0/MWh." Under this revised structure, during negative price hours, the company pays $28/MWh (not $36/MWh above market) because the settlement reference price is floored at zero. The developer absorbs the negative market price risk. + +**Key Indicators:** +- CAISO negative pricing frequency exceeding 300 hours/year and growing YoY signals structural oversupply +- New solar interconnection queue in the generator's zone exceeding 5 GW indicates the problem will worsen +- CAISO proposed market reforms (extended day-ahead market, WEIM expansion) may partially mitigate negative pricing through broader geographic dispatch +- Battery storage additions in CAISO are absorbing midday solar and may reduce negative pricing frequency by 2027-2030 + +--- + +### Edge Case 6: Behind-the-Meter Solar Cannibalizing Demand Response Value + +**Situation:** +A cold storage operator in New Jersey (PSE&G territory, PJM market) installed a 1.5 MW rooftop solar array under a 25-year on-site solar PPA at $0.065/kWh. The facility is also enrolled in PJM's Economic Demand Response program, committing to curtail 800 kW during high-priced hours. The DR program calculates the Customer Baseline Load (CBL) using the average of the highest 4 out of the prior 5 business days' consumption during the DR event hours. + +After the solar installation, the facility's grid consumption during sunny weekday afternoons dropped by approximately 1,100 kW (the solar array's typical output). This reduced the CBL by the same amount. When a DR event is called on a cloudy day (when solar output is only 200 kW instead of 1,100 kW), the facility's actual load is close to its pre-solar level — but the CBL is based on recent sunny days when grid consumption was lower. The measured curtailment (CBL minus actual metered load during the event) is effectively zero or negative, even though the facility is genuinely curtailing discretionary loads. + +The result: the facility fails performance testing for the DR program, loses its 800 kW capacity commitment credit ($48,000/year at $60/kW-yr), and faces a non-performance penalty of $25,000. + +**Why It's Tricky:** +The solar array and the DR program each made financial sense individually. But the interaction between the CBL methodology and behind-the-meter solar creates a perverse outcome: solar production on sunny days lowers the baseline, making it harder to demonstrate curtailment on cloudy event days (when solar isn't helping). The CBL methodology was designed for facilities with predictable, weather-independent load — it doesn't account for behind-the-meter generation that varies with weather. + +**Common Mistake:** +Installing behind-the-meter solar and enrolling in DR programs without modeling the CBL interaction. The second mistake: reducing the DR commitment to match the new (lower) CBL, which sacrifices significant capacity revenue. + +**Expert Approach:** +1. **CBL methodology analysis:** Request the detailed CBL calculation methodology from PJM or your curtailment service provider (CSP). Some DR programs allow CBL adjustment for behind-the-meter generation — PJM's rules have evolved, and recent provisions may allow the CBL to be calculated on a "gross load" basis (metered load + estimated solar generation) rather than "net load" basis. If gross load CBL is available, apply for the adjustment. + +2. **Solar metering:** Install a revenue-grade meter on the solar array's output (separate from the utility meter). This provides real-time solar generation data that can be used to adjust the CBL. The meter cost ($2,000-$5,000 installed) is trivial compared to the lost DR revenue. + +3. **CSP negotiation:** Engage your Curtailment Service Provider to restructure the DR enrollment. Options: + - Switch to a "firm service level" (FSL) baseline methodology where your committed curtailment is measured as the difference between your maximum load and a pre-agreed service level, rather than a rolling CBL + - Enroll the solar production as a separate DR resource (solar + storage dispatch) rather than netting it against the facility load + - Reduce the committed curtailment volume to a level achievable on cloudy days (e.g., 400 kW instead of 800 kW) as an interim measure + +4. **Battery integration:** Add a battery system (200 kW / 400 kWh minimum) that charges from solar during sunny hours and discharges during DR events. This allows the facility to demonstrate curtailment on cloudy days by discharging stored solar energy, keeping the CBL higher and providing real kW reduction during events. The battery also earns frequency regulation revenue in PJM during non-event hours. + +5. **Re-evaluate the overall value stack.** Recalculate the total economic benefit of each component (solar PPA savings, DR revenue, capacity tag reduction, TOU arbitrage) with the interaction effects included. The optimal configuration may involve sizing the DR commitment to a level that is achievable regardless of solar output, rather than maximizing the individual DR commitment. + +**Key Indicators:** +- Before installing behind-the-meter generation at a facility enrolled in DR, model the CBL impact for all weather scenarios +- DR programs using CBL-10 (average of 10 prior similar days) are more vulnerable to solar cannibalization than those using metered generation adjustment +- PJM's wholesale market rules for DR are updated annually — check for behind-the-meter generation accommodation provisions + +--- + +### Edge Case 7: Capacity Market Obligation Surprise from Coincident Peak + +**Situation:** +A data center operator in PJM (ComEd zone, Northern Illinois) runs three facilities with a combined peak demand of 30 MW. The company has been aggressively managing capacity costs — PLC tags for the prior delivery year totaled 24 MW (reflecting successful load reduction during the 5 coincident peak hours). + +During the current summer, an unprecedented heat wave hit the Midwest. PJM called for demand response and conservation. The data center operator's backup diesel generators were offline for maintenance during the two hottest days. Without generator backup, the facilities ran at full grid load during what turned out to be 3 of the 5 coincident peak hours. The data center also accepted an emergency colocation request from a major client, adding 2 MW of temporary load. + +When PJM publishes the new PLC values, the data center's tag jumps from 24 MW to 31 MW (full grid load of 30 MW plus the 2 MW temporary load minus some non-coincidence). At the BRA clearing price of $98/MW-day, the annual capacity charge increases from $858,720 to $1,108,870 — a $250,150 increase that persists for the entire delivery year. + +**Why It's Tricky:** +The PLC is set by metered data during the 5CP hours — there's no appeals process, no adjustment for maintenance schedules or temporary load. The data center operator managed their PLC carefully for years but a single summer with bad timing (generators offline during the peak) erased all that work. The $250K annual increase is locked for the entire delivery year, regardless of what the data center does going forward. + +**Common Mistake:** +Treating PLC management as "nice to have" rather than a critical operational priority. The second mistake: scheduling generator maintenance during summer months (June-September) when coincident peaks are most likely. + +**Expert Approach:** +1. **Generator maintenance scheduling (preventive):** Never schedule backup generator maintenance during June-September. If maintenance must occur during summer, complete it on a single unit at a time and only on days when the PJM weather forecast shows temperatures below the 5CP trigger zone (typically <90°F for ComEd zone). Maintain at least 80% of generator capacity available during all summer weekday afternoon hours. + +2. **Temporary load policies:** Establish a policy that no temporary or emergency load additions are accepted during June-September without explicit approval from the energy procurement team. The $250K capacity charge increase from 2 MW of temporary load far exceeds any revenue from the colocation contract (unless the contract is specifically priced for capacity cost pass-through). + +3. **PLC monitoring service:** Subscribe to a PJM coincident peak prediction service (offered by most retail energy providers and specialized consultants). These services predict 5CP hours 24-48 hours in advance with 80-90% accuracy. When a predicted 5CP hour is forecast, activate all available generators, curtail all discretionary load, and notify operations that this is a "gold hour" — every kW reduced during these 5 hours saves $35,770/year at the current capacity price. + +4. **Recovery strategy for the current year:** The new PLC is set and cannot be changed for this delivery year. Focus on minimizing next year's PLC. Implement: + - Firm generator maintenance blackout window (June 1 - September 30) + - Automated demand response controls that shed 3-5 MW of discretionary load within 15 minutes of a 5CP alert + - Contractual provisions for all new colocation agreements requiring load shedding during capacity peak events + +5. **Financial recovery:** Calculate whether the temporary colocation client's contract covers the capacity cost increase. If not, renegotiate the contract to include capacity cost pass-through. For future emergency colocation requests during summer, quote the capacity cost impact explicitly: "Adding 2 MW during potential 5CP hours will cost $71,540/year in capacity charges — this must be included in the colocation pricing." + +**Key Indicators:** +- PJM summer weather forecasts predicting temperatures >92°F for the ComEd zone on 3+ consecutive weekdays signal likely 5CP hours +- PJM issuing hot weather alerts or emergency procedures is a near-certain 5CP indicator +- Backup generator availability below 80% during June-September is a capacity management risk + +--- + +### Edge Case 8: Renewable Curtailment Exceeding Developer Projections + +**Situation:** +A manufacturing company signed a 15-year physical PPA with a 75 MW wind farm in ERCOT (West Texas) at $22/MWh with projected annual generation of 270,000 MWh (41% capacity factor). The company's RE100 target depends on receiving at least 250,000 MWh of bundled RECs from this project annually. + +After the first full year of operations, actual generation is 235,000 MWh — 13% below the P50 projection. The shortfall is primarily driven by curtailment: ERCOT curtailed the wind farm for 680 hours (7.8% of the year), versus the developer's projection of 250 hours (2.9%). The curtailment is caused by transmission congestion on the CREZ (Competitive Renewable Energy Zone) lines from West Texas to the Houston and Dallas load centers — the same lines that were built to export West Texas wind, but which are now at capacity due to the exponential growth of wind and solar in the region. + +The company is 15,000 RECs short of its annual RE100 requirement and must purchase replacement RECs. Additionally, the lower generation volume means lower PPA settlement income (the positive spread between market price and PPA strike price is earned on fewer MWh). + +**Why It's Tricky:** +Wind farm curtailment in West Texas is a known risk, but the magnitude exceeded projections. The developer used historical curtailment data from 2020-2022 (when the CREZ lines had more headroom) — since then, 8 GW of new wind and solar have interconnected in the same constrained region. The ERCOT interconnection queue shows another 15 GW of proposed projects in West Texas, suggesting curtailment will worsen before it improves. + +The PPA contract allocates curtailment risk to the offtaker (the company pays the contract price only for delivered energy, and receives no compensation for curtailed energy). This is standard in older PPA structures. + +**Common Mistake:** +Assuming the developer can solve the curtailment problem (they can't — it's a grid-level transmission constraint). The second mistake: projecting future generation using the developer's original P50 without adjusting for actual curtailment experience. + +**Expert Approach:** +1. **Rebase generation projections.** Using 12 months of actual data, create an adjusted generation projection: actual wind resource (may differ from developer's model), actual curtailment rate (680 hours, not 250), and trend-adjust curtailment based on ERCOT interconnection queue data. A reasonable forward projection might be 225,000-240,000 MWh/year with curtailment worsening 1-2% per year until new transmission is built. + +2. **Curtailment clause renegotiation.** Approach the developer to renegotiate the curtailment allocation. Propose a shared risk model: developer bears first 4% of curtailment (their original projection); offtaker bears next 2%; any curtailment above 6% is the developer's risk. The developer may agree because locking in the PPA relationship is preferable to losing the offtaker's volume entirely. + +3. **REC replacement strategy.** Budget for annual replacement REC purchases to cover the shortfall. ERCOT wind RECs trade at $2-$4/MWh. A 15,000 REC shortfall costs $30,000-$60,000/year — manageable, but the cost grows if curtailment increases. Consider purchasing replacement RECs through a multi-year contract to lock in pricing. + +4. **Transmission monitoring.** Track ERCOT's Long-Term System Assessment and regional transmission plans. New 345 kV lines from West Texas to North Central Texas are planned but typically take 5-7 years from approval to energization. Model the curtailment trajectory assuming transmission expansion occurs on ERCOT's published timeline, and model the scenario where it's delayed 2-3 years. + +5. **Portfolio diversification.** For the next renewable procurement, avoid West Texas siting. Diversify to the Texas Gulf Coast (solar, lower curtailment) or outside ERCOT entirely (PJM wind/solar where curtailment is minimal). A portfolio of 2-3 projects across different regions reduces curtailment concentration risk. + +**Key Indicators:** +- ERCOT curtailment orders exceeding 5% of annual hours for a specific generator region signals structural congestion +- ERCOT interconnection queue exceeding 2× existing generation capacity in a constrained zone is a bearish curtailment signal +- Developer reporting curtailment exceeding P90 projections in year 1 indicates the projections were based on outdated grid conditions + +--- + +### Edge Case 9: Deregulated Market Re-Regulation Risk + +**Situation:** +A retail chain with 200 stores across Ohio and Pennsylvania has 150 stores on competitive supply contracts (fixed-price, $0.058/kWh energy, average 36 months remaining). After a summer price spike that caused $800M in aggregate consumer cost increases statewide, the Ohio legislature introduces a bill to re-regulate the electricity market — returning all generation procurement to the regulated utilities at tariff rates. + +The proposed bill would void all existing competitive supply contracts within 180 days of enactment and require all customers to return to utility standard service. The current utility standard service rate for commercial customers is $0.071/kWh energy — 22% higher than the chain's competitive rate. + +The Ohio stores represent 120 of the 200 locations, consuming 95 GWh annually. If re-regulation occurs, the annual energy cost increase for Ohio alone would be approximately $1.24M (95 GWh × $0.013/kWh increase). + +**Why It's Tricky:** +Re-regulation bills are introduced periodically but rarely enacted. However, this bill has political momentum because the summer price spike affected residential customers, and legislators want to "protect consumers." The bill is expected to reach committee vote within 4 months. Even if it doesn't pass, the legislative uncertainty creates contract enforcement risk — retail energy providers may attempt to add regulatory change provisions to new contracts, and existing contract renewal terms may include re-regulation exit clauses. + +The more insidious risk: even without formal re-regulation, Ohio could introduce a "provider of last resort" surcharge, a competitive market administration fee, or other mechanisms that reduce the competitive supply discount. These incremental regulatory changes are more likely than full re-regulation and can erode 30-50% of the competitive savings. + +**Common Mistake:** +Ignoring the legislative risk because "re-regulation never happens." It happened in Ohio once before (SB 221 in 2008 attempted partial re-regulation), and Virginia effectively re-regulated in 2007 before partially deregulating again. The second mistake: panicking and trying to exit competitive contracts — the contracts are favorable, and any exit would involve early termination fees. + +**Expert Approach:** +1. **Assess probability.** Engage a regulatory affairs consultant or your energy supplier's government relations team to assess the bill's likelihood of passage. Track committee votes, sponsor count, and utility lobbying positions. If the utility supports re-regulation (they often do, as it restores their captive customer base), the bill has stronger prospects. + +2. **Coalition advocacy.** Join or form a C&I customer coalition opposing re-regulation. Large commercial customers benefit most from competition and have the strongest voice against re-regulation. Provide testimony on the consumer savings from competitive supply — a retail chain saving $1.24M/year is a compelling data point. + +3. **Contract review.** Examine existing supply contracts for regulatory change clauses. Most well-drafted competitive supply contracts include a provision allowing either party to terminate or renegotiate if the regulatory structure fundamentally changes. Understand your termination rights and the supplier's — if the supplier can exit your contract due to re-regulation, you lose your favorable rate but avoid paying an early termination fee. + +4. **Hedging the Pennsylvania exposure.** If Ohio re-regulates, accelerate procurement for Pennsylvania stores. Lock in competitive rates for the maximum available tenor (36-48 months) while the Pennsylvania market remains competitive. Diversify supplier credit exposure in case one supplier exits the Ohio market. + +5. **Contingency budgeting.** Model the financial impact of three scenarios: + - Full re-regulation (Ohio energy cost increases $1.24M/year) + - Partial re-regulation (competitive supply preserved for large C&I but with new surcharges — increase $400K-$600K/year) + - Bill fails (no cost change, but future legislative risk remains) + + Present scenarios to the CFO with probability weights. Budget to the expected value. + +**Key Indicators:** +- State legislature introducing electricity market reform bills after consumer price spike events +- Utility lobbying spend increasing for "market reform" or "default service enhancement" +- Residential customer complaint rates exceeding 3× historical average (political pressure builds) +- Governor or PUC chair making public statements about "market failure" in competitive supply + +--- + +### Edge Case 10: Transmission Congestion Invalidating Procurement Strategy + +**Situation:** +A chemical manufacturer with a 15 MW facility in southern New Jersey (JCPL zone, PJM) has been buying power at the PJM Western Hub price through a retail energy provider, with a $0.003/kWh adder. The Western Hub price of $38/MWh has been a reasonable proxy for the JCPL zone price historically (basis of $2-$4/MWh). The company's energy budget is built on $41/MWh all-in. + +A new data center campus interconnected 8 miles from the chemical plant, adding 80 MW of load in the JCPL zone. Simultaneously, a 500 MW natural gas plant in the zone retired. The combination of added load and reduced generation created a transmission constraint. The JCPL zone day-ahead LMP jumped from $40/MWh to $58/MWh during peak hours, while the Western Hub price remained at $38/MWh. The basis between Western Hub and JCPL zone widened from $3/MWh to $18/MWh. + +The company's retail supply contract settles at Western Hub + adder, but the company pays the utility for energy delivery at the zonal LMP. The net effect: the company is paying $38 + $3 (supplier) but the utility pass-through for congestion is $18/MWh, raising the effective cost to $59/MWh. Against a $41/MWh budget, the facility is running $18/MWh over — $2.36M/year on 131 GWh. + +**Why It's Tricky:** +The supply contract is performing as agreed (Western Hub + $3). The congestion cost is a separate charge flowing through the utility bill. This is a market structure nuance that many C&I buyers don't model — they assume the hub price is approximately equal to their delivered price. When basis was $2-$4/MWh, this assumption was harmless. At $18/MWh, it's a $2.4M/year error. + +The structural congestion is unlikely to reverse quickly — the data center load is permanent, the retired plant is not coming back, and new transmission or local generation takes 3-7 years to build. + +**Common Mistake:** +Assuming the congestion is temporary and will revert to historical levels. Structural congestion caused by load growth and generation retirement is persistent until the grid is physically reconfigured. The second mistake: trying to renegotiate the supply contract — the supplier is delivering at the agreed-upon hub price and is not responsible for zonal congestion. + +**Expert Approach:** +1. **Immediate contract restructuring:** Switch the supply contract settlement point from Western Hub to the JCPL zone (load zone pricing). The supplier will quote a higher price that reflects the zone premium, but this eliminates the basis exposure. The company pays a known, locked-in price that includes congestion, rather than a low hub price plus an unpredictable congestion pass-through. + +2. **FTR procurement:** Purchase Financial Transmission Rights (FTRs) from Western Hub to the JCPL zone in PJM's monthly or annual FTR auction. An FTR pays the congestion component between the two points — if congestion is $18/MWh and you hold an FTR for your load volume, you receive $18/MWh × volume in FTR settlement, offsetting the congestion charge on your utility bill. + +3. **On-site generation evaluation:** With zonal LMPs at $58/MWh during peak hours, the economics for on-site generation improve dramatically. A 5 MW natural gas combined heat and power (CHP) system generating at $40/MWh (fuel + O&M) would save $18/MWh on the kWh it generates. At 8,000 hours/year: $720K/year savings on a $7-$10M capital investment — strong payback. + +4. **Long-term transmission monitoring:** Track PJM's Regional Transmission Expansion Plan (RTEP) for projects addressing the JCPL constraint. If PJM approves a transmission upgrade, the congestion may ease in 4-6 years. Factor this into the decision on long-term investments like CHP — if the congestion premium will disappear in 5 years, a CHP plant that was justified by congestion savings may not pencil on its own economics. + +5. **Budget reforecast:** Immediately reforecast the energy budget using the new basis reality. Use $55-$60/MWh as the delivered cost assumption until the contract is restructured. Present to finance with a clear explanation of the structural change and the remediation timeline. + +**Key Indicators:** +- PJM Congestion reports showing zonal basis >$10/MWh for >30% of peak hours indicates structural congestion +- Generator retirement announcements in your zone without replacement capacity signal worsening congestion +- Large load interconnection applications (data centers, industrial facilities) in your zone increase future congestion risk +- PJM RTEP project approvals targeting your constraint indicate relief timeline (but delivery is typically 4-7 years out) + +**Documentation Required:** +- Hourly LMP data for Western Hub and JCPL zone (12+ months) +- Basis calculation spreadsheet (generation-weighted for PPA, load-weighted for supply) +- FTR auction bid strategy and results +- CHP feasibility study (if applicable) +- Budget reforecast with basis scenarios +- Communication log with supplier regarding settlement point change + +**Resolution Timeline:** +- Week 1: Quantify basis exposure, pull LMP data, reforecast budget +- Week 2-3: Evaluate FTR procurement, contact supplier about settlement point change +- Month 2: Execute contract restructuring (settlement point or FTR hedge) +- Month 3-6: Monitor whether structural congestion persists, evaluate CHP or on-site generation +- Month 6-12: Reassess portfolio-level strategy for facilities in congested zones + +--- + +### Edge Case 11: Retail Energy Provider Credit Deterioration Mid-Contract + +**Situation:** +A healthcare system with 8 hospitals across Pennsylvania has a 36-month fixed-price electricity supply contract with GreenPeak Energy Solutions, a mid-tier retail energy provider. The contract covers 120 GWh/year at $0.058/kWh energy — well below the current market of $0.067/kWh. GreenPeak's S&P credit rating was BBB at contract signing. Eighteen months into the contract, GreenPeak is downgraded to BB+ (sub-investment grade) after reporting significant trading losses in the most recent quarter. Industry reports suggest GreenPeak overcommitted on fixed-price contracts when forward curves were low and is now underwater as market prices have risen. + +The healthcare system's contract has a termination provision allowing either party to exit with 90 days' notice if a material adverse change occurs, including a credit downgrade below investment grade. If GreenPeak fails, the hospitals revert to the utility's default service at $0.071/kWh — a $1.56M annual cost increase. + +**Why It's Tricky:** +The contract is favorable — $0.058/kWh is $0.009/kWh below market. Exercising the termination right is irrational (you'd voluntarily lose a below-market contract). But NOT exercising it means staying exposed to a supplier that may default. If GreenPeak declares bankruptcy, the contract may be rejected in bankruptcy court, and the hospitals lose the favorable rate anyway. The risk calculus: certain below-market pricing today vs. potential forced exit to above-market default service later. + +Complicating factor: healthcare facilities cannot tolerate billing disruption. Hospitals must have unambiguous supply arrangements for regulatory compliance, and a supplier default triggers administrative chaos (account switches, utility enrollment, billing reconciliation) that disproportionately impacts a multi-site healthcare system. + +**Common Mistake:** +Doing nothing because the contract is favorable and hoping GreenPeak survives. The second mistake: exercising the termination right immediately and losing the below-market rate. Both extremes are wrong. + +**Expert Approach:** +1. **Credit monitoring (immediate):** Set up alerts for further credit actions on GreenPeak — S&P CreditWatch, Moody's review, and any SEC filings (8-K, 10-Q with going concern language). A further downgrade to BB or below, or a going concern note, significantly increases default probability. + +2. **Contract review:** Examine the contract for: + - **Adequate assurance clause:** Can you demand financial assurance (letter of credit, parent guarantee) from GreenPeak as a condition of continuing the contract? Many commercial supply contracts include this right upon a material credit event. + - **Assignment rights:** Can the contract be assigned to another creditworthy supplier? If GreenPeak is acquired or merges with a stronger company, your contract may survive. + - **Setoff rights:** If GreenPeak owes you credits (overcollections, reconciliation adjustments), can you offset those against future payments? + +3. **Demand adequate assurance (Week 1):** Formally request that GreenPeak post a standby letter of credit equal to 3-6 months of expected below-market value. Calculate: ($0.067 market - $0.058 contract) × 120 GWh / 12 months × 6 months = $540,000 LC. This protects the healthcare system if GreenPeak defaults — the LC covers the cost of switching to a new supplier at market rates during the transition period. + +4. **Parallel supplier qualification (Week 1-3):** Issue an expedited RFP to 3-4 investment-grade suppliers for a replacement contract. Obtain indicative pricing so you know exactly what the replacement cost would be if GreenPeak fails. This is not a commitment — it's insurance. Having a qualified backup supplier with a standing offer reduces the transition time from weeks to days. + +5. **Hedging the replacement risk (Month 1):** If the replacement cost at market ($0.067) is significantly above your contract ($0.058), consider purchasing a financial hedge that pays out if you're forced to switch suppliers. Specifically, buy a call option on PJM electricity at a strike price of $0.060/kWh for the remaining contract volume. If GreenPeak defaults and you switch to a market-priced supplier, the call option offsets the cost increase above $0.060. + +6. **Ongoing monitoring cadence:** Review GreenPeak's financial health monthly. Track: credit rating changes, SEC filings, employee LinkedIn departures (mass exits from a supplier signal trouble), utility regulatory filings (some states require REPs to post bonds), and industry rumors (energy industry is small — your broker will hear about financial distress before it hits the news). + +**Key Indicators:** +- Supplier credit downgrade below BBB- (investment grade threshold) is the first warning +- Supplier requesting early payment, changing payment terms, or delaying customer credits signals cash flow problems +- Supplier laying off commercial/pricing staff suggests they're de-risking by not taking new business +- State utility commission audits of REP financial requirements may reveal shortfalls +- If 2+ other C&I buyers report the same supplier is requesting contract modifications, the supplier is restructuring its book + +**Documentation Required:** +- Credit rating history and monitoring alerts +- Adequate assurance demand letter and GreenPeak response +- Replacement supplier indicative pricing +- Financial hedge evaluation (call option cost vs. benefit) +- Board-level risk assessment memo +- Contingency communication plan for hospitals (billing continuity) + +**Resolution Timeline:** +- Week 1: Demand adequate assurance, initiate backup supplier RFP +- Week 2-3: Receive GreenPeak response to assurance demand, evaluate backup bids +- Month 1-2: If assurance is posted, continue monitoring. If refused, evaluate termination. +- Month 3+: Monthly credit monitoring until GreenPeak's financial position stabilizes or the contract expires + +--- + +### Edge Case 12: Multi-State Portfolio with Mixed Regulated/Deregulated Markets + +**Situation:** +A food and beverage company operates 35 facilities across 18 states: 15 manufacturing plants (2-12 MW each), 12 distribution centers (500 kW - 3 MW each), and 8 corporate/R&D offices (200-800 kW each). Total electricity consumption: 680 GWh/year, $58M annual energy spend. The facilities are split: 20 in deregulated markets (PJM, ERCOT, NYISO, ISO-NE), 10 in regulated markets (Georgia, Florida, Alabama, Tennessee), and 5 in markets with limited competition (partial deregulation or pilot programs). + +The VP of Sustainability has committed the company to RE100 by 2030. The CFO wants 5% annual energy cost reduction. The Director of Operations wants zero disruption to production. Currently, each facility manages its own utility relationship — there is no centralized energy procurement function. Tariff selection, contract renewals, and demand charge management are handled by facility managers with no energy expertise, resulting in: +- 12 facilities on suboptimal tariff schedules (estimated $1.2M/year in unnecessary charges) +- 6 deregulated sites on utility default service (never switched to competitive supply — $2.1M/year above market) +- No demand charge management programs at any facility +- RE100 progress at 12% (entirely from unbundled RECs purchased by the sustainability team) + +**Why It's Tricky:** +Building a centralized energy procurement function from scratch requires addressing every aspect simultaneously: competitive procurement in deregulated markets, tariff optimization in regulated markets, demand charge management at high-potential sites, renewable procurement to hit RE100, and budget forecasting and reporting across 35 facilities. With no existing infrastructure, even basic tasks like assembling interval data for 35 facilities take months. + +The mixed regulatory landscape means no single strategy works everywhere. A VPPA that works for PJM sites is irrelevant for Georgia sites. Demand charge management that works at a manufacturing plant doesn't apply to an office. Tariff optimization requires state-by-state regulatory expertise. + +**Common Mistake:** +Trying to do everything at once — hiring a consultant, issuing an enterprise RFP, signing a mega-VPPA, and installing batteries at every site simultaneously. This overwhelms the organization, produces poor execution on every front, and alienates facility managers who feel central procurement is disrupting their operations. + +**Expert Approach:** +1. **Phase 0: Data assembly and baselining (Month 1-3).** + Deploy an energy management information system (EMIS) like EnergyCAP, Urjanet, or UtilityAPI to automatically collect utility bill data for all 35 sites. This eliminates the manual data collection bottleneck. Target: complete 12-month utility bill history and interval data for all sites within 90 days. + +2. **Phase 1: Quick wins (Month 2-6).** Prioritize actions with immediate savings and minimal disruption: + - **Switch 6 default-service sites to competitive supply.** Issue an aggregated RFP covering all 6 sites (combined volume gives leverage). Expected savings: 10-15% on energy charges = $200K-$300K/year per site. + - **Tariff audit all 35 sites.** Engage a tariff optimization consultant or use software to model each site against all available rate schedules. Switch 12 sites to optimal tariffs. Expected savings: $1.2M/year. + - **Demand charge review for top 10 sites by demand charge cost.** Implement zero-cost measures (staggered startups, BAS programming) at the top 5 sites. Expected savings: $300K-$500K/year. + + Phase 1 total savings estimate: $2.5M-$4M/year, achievable within 6 months. + +3. **Phase 2: Strategic procurement (Month 4-12).** With data and quick wins establishing credibility: + - **Portfolio procurement for deregulated sites.** Aggregate 20 deregulated sites by ISO and issue portfolio RFPs. Use layered block-and-index structure for manufacturing (high load factor) and fixed-price for offices/DCs (lower load factor, less optimization potential). + - **Demand charge capital projects.** Using Phase 1 analysis, identify 3-5 sites where battery storage or demand response has <5 year payback. Develop business cases and submit for capital approval. + - **Renewable procurement strategy.** Design a phased RE100 roadmap: + - Year 1-2: Switch unbundled RECs from national wind to project-specific solar RECs (better additionality, modest cost increase) + - Year 2-3: Execute first VPPA (100-150 GWh/year) targeting PJM or MISO sites + - Year 3-4: Add a second VPPA or physical PPA for ERCOT sites + - Year 4-5: On-site solar at 5-8 facilities with favorable economics + - Year 5-6: Utility green tariffs or community solar for regulated market sites + +4. **Phase 3: Optimization and continuous improvement (Year 2+).** With infrastructure in place: + - Implement real-time energy monitoring and automated demand response at top 15 sites + - Build internal capability for capacity tag management (PJM, ISO-NE) + - Establish a quarterly energy procurement committee (finance, sustainability, operations, procurement) + - Develop forward-looking energy risk management policy with hedge ratios and governance + +5. **Governance and reporting:** From Day 1, establish a reporting framework: + - Monthly: energy cost vs. budget by site, demand charge performance, supply contract status + - Quarterly: portfolio-level hedge ratio, RE100 progress, supplier scorecard, market outlook + - Annually: total energy spend vs. prior year (weather-normalized), cost avoidance from optimization, sustainability target progress, 3-year procurement strategy refresh + +**Key Indicators:** +- If quick wins (Phase 1) don't deliver $2M+ in annual savings, the baseline analysis was wrong — revisit data +- Facility manager resistance to centralized procurement is the #1 implementation risk — address it through communication and shared savings incentives +- RE100 progress requires committed procurement volume, not just REC purchases — if RE% stalls at 30-40%, it's because the VPPA/PPA pipeline isn't producing +- Total energy cost as a percentage of revenue should decrease YoY (weather-normalized) — if it's flat or increasing, the optimization program isn't working + +**Documentation Required:** +- 35-site energy baseline (utility bills, interval data, tariff schedules, contracts) +- Phase 1 savings tracking (actual vs. projected by initiative) +- Portfolio procurement RFP and award documentation +- RE100 roadmap with annual milestones and procurement commitments +- Energy risk management policy +- Capital project business cases for demand-side investments +- Quarterly energy management committee reports + +**Resolution Timeline:** +- Month 1-3: Data assembly, EMIS deployment, Phase 0 complete +- Month 2-6: Phase 1 quick wins executed, $2.5M-$4M/year savings captured +- Month 4-12: Phase 2 strategic procurement, first VPPA executed +- Year 2: Phase 3 optimization, demand-side capital projects operational +- Year 3: RE100 at 50%+, energy cost reduction at 15%+ from baseline +- Year 5: RE100 at 80%+, fully mature energy management program + +--- + +### Edge Case 13: Natural Gas Supply Disruption During Winter Heating Season + +**Situation:** +A pharmaceutical manufacturer in New Jersey operates a 150,000 sq ft production facility with a 6,000 MMBtu/month winter natural gas load (process heat for API synthesis plus facility heating). The facility is on a firm transportation gas contract with a local distribution company (LDC) at a rate of $8.50/MMBtu delivered. During a prolonged January cold snap (15 consecutive days below 15°F), the LDC issues an Operational Flow Order (OFO) restricting deliveries to critical-use customers only. The pharmaceutical plant's gas supply is not classified as "critical use" under the LDC's tariff — hospitals and residential heating take priority. + +The OFO reduces the facility's gas allocation to 60% of normal. The remaining 40% (2,400 MMBtu/month) must be sourced on the spot market through an alternative supply arrangement, or the facility must curtail operations. Spot gas at the Transco Zone 6 delivery point is trading at $28/MMBtu — more than 3× the contract rate. Alternatively, the facility could switch some process heat to electric resistance heating, but this would increase electricity demand by 1.8 MW during a period when electricity prices are also elevated ($180/MWh due to gas-fired generation being price-setting at high gas prices). + +The pharmaceutical product in process has a 72-hour window before it must be temperature-controlled or destroyed — $4.2M worth of active pharmaceutical ingredient is at risk. + +**Why It's Tricky:** +The facility faces a trilemma: (1) pay $28/MMBtu spot gas to maintain full operations (4× the normal cost), (2) switch to electric heating at $180/MWh equivalent cost (which may be even more expensive per BTU than spot gas), or (3) curtail production and risk $4.2M in product loss. None of these options is clearly superior, and the decision must be made within hours. + +The LDC's OFO is legally enforceable — the tariff allows curtailment of non-critical-use customers during supply emergencies. The facility's "firm" gas contract is firm for transportation, but the OFO overrides transportation priority during emergencies. This is a distinction most facility managers don't understand until it happens. + +**Common Mistake:** +Assuming "firm" gas service means guaranteed delivery under all conditions. Firm transportation is firm relative to interruptible service — but OFOs can curtail even firm customers. The second mistake: relying entirely on gas without a dual-fuel backup for critical process heat. + +**Expert Approach:** +1. **Immediate triage (Hour 0-2):** Calculate the cost of each option per MMBtu equivalent: + - Spot gas: $28/MMBtu delivered + - Electric resistance heating: $180/MWh ÷ 3,412 BTU/kWh × 1,000,000 = $52.75/MMBtu equivalent (even more expensive than spot gas and subject to demand charge spikes) + - Product loss: $4.2M ÷ 72 hours = $58,333/hour of delay. Even at $28/MMBtu, running the process heat costs far less than product loss. + + **Decision: Purchase spot gas at $28/MMBtu for process heat. Use electric heating only for space heating (lower priority, can tolerate temperature setback).** + +2. **Spot gas procurement (Hour 0-4):** Contact your gas marketer or broker to secure spot supply at Transco Zone 6. Request a 15-day deal (covering the forecast cold snap duration). Negotiate for a fixed daily quantity with a price cap rather than floating daily pricing — during extreme events, daily spot prices can swing $10-$15/MMBtu between morning and afternoon. + +3. **Demand charge protection (Hour 0):** If switching any load to electric heating, install temporary demand limiting controls. A 1.8 MW increase in electric demand at a $15/kW demand rate = $27,000/month in additional demand charges, plus potential ratchet impact. If possible, offset the added electric load by curtailing other electric loads (lighting, non-essential compressed air). + +4. **Dual-fuel capability assessment (Week 2, post-event):** After the event, evaluate installing dual-fuel capability for the critical process heat systems. A dual-fuel burner that can switch between gas and #2 fuel oil costs $150K-$300K for a 6,000 MMBtu/month system. With fuel oil on-site in a storage tank, the facility can maintain operations during gas curtailments without relying on spot gas or electric conversion. Annual carrying cost (tank rental, fuel turnover): $25K-$40K. + +5. **LDC tariff engagement (Month 2-3):** Petition the LDC to reclassify the pharmaceutical facility as "critical use" under the tariff. Pharmaceutical manufacturing has arguments for critical use designation: product at risk of destruction, FDA compliance implications, public health importance. The reclassification requires a tariff filing with the state utility commission — engage regulatory counsel. + +6. **Contractual protection (next renewal):** At the next gas contract renewal, negotiate a "firm-firm" or "no-notice" transportation agreement that provides the highest curtailment priority available from the LDC. This costs 10-20% more than standard firm transportation but eliminates OFO exposure. Alternatively, negotiate a "supplemental supply" agreement with a gas marketer that automatically activates when the LDC issues an OFO — pre-arranged backup supply at a pre-negotiated spread above the index. + +**Key Indicators:** +- Weather forecasts showing >10 consecutive days below 20°F in the Northeast signal potential OFO conditions +- LDC "system alerts" or "constraint days" preceding a full OFO — act on alerts, don't wait for the OFO +- Henry Hub spot gas exceeding $5/MMBtu during winter signals tight national supply — regional prices will spike harder +- Electricity price correlation: when gas spot is elevated, electricity spot is elevated proportionally — electric heating is not a cheap alternative during gas supply emergencies + +**Documentation Required:** +- LDC Operational Flow Order notification and curtailment percentage +- Spot gas purchase confirmations and pricing +- Product-at-risk calculation and decision documentation +- Electric load impact and demand charge analysis +- Post-event dual-fuel capability feasibility study +- LDC tariff reclassification petition (if pursuing critical use designation) +- Gas contract renewal strategy with enhanced curtailment protection + +**Resolution Timeline:** +- Hour 0-4: Triage, spot gas procurement, demand limiting controls +- Days 1-15: Manage blended gas supply (contract + spot), monitor cold snap duration +- Week 3: Post-event financial analysis, present cost impact to management +- Month 2-3: Initiate dual-fuel feasibility study, LDC tariff reclassification +- Month 4-6: Install dual-fuel capability (if approved), negotiate enhanced gas contract +- Next renewal: Execute firm-firm or no-notice gas transportation agreement diff --git a/web-app/public/skills/error-detective/SKILL.md b/web-app/public/skills/error-detective/SKILL.md index 8af4f438..cd8c8fd0 100644 --- a/web-app/public/skills/error-detective/SKILL.md +++ b/web-app/public/skills/error-detective/SKILL.md @@ -1,6 +1,7 @@ --- name: error-detective -description: "Search logs and codebases for error patterns, stack traces, and" +description: | + Search logs and codebases for error patterns, stack traces, and anomalies. Correlates errors across systems and identifies root causes. Use PROACTIVELY when debugging issues, analyzing logs, or investigating production errors. diff --git a/web-app/public/skills/fastapi-pro/SKILL.md b/web-app/public/skills/fastapi-pro/SKILL.md index f07b0e60..b84a2913 100644 --- a/web-app/public/skills/fastapi-pro/SKILL.md +++ b/web-app/public/skills/fastapi-pro/SKILL.md @@ -1,6 +1,7 @@ --- name: fastapi-pro -description: "Build high-performance async APIs with FastAPI, SQLAlchemy 2.0, and" +description: | + Build high-performance async APIs with FastAPI, SQLAlchemy 2.0, and Pydantic V2. Master microservices, WebSockets, and modern Python async patterns. Use PROACTIVELY for FastAPI development, async optimization, or API architecture. diff --git a/web-app/public/skills/firmware-analyst/SKILL.md b/web-app/public/skills/firmware-analyst/SKILL.md index 83f56424..a0fcf517 100644 --- a/web-app/public/skills/firmware-analyst/SKILL.md +++ b/web-app/public/skills/firmware-analyst/SKILL.md @@ -1,6 +1,7 @@ --- name: firmware-analyst -description: "Expert firmware analyst specializing in embedded systems, IoT" +description: | + Expert firmware analyst specializing in embedded systems, IoT security, and hardware reverse engineering. Masters firmware extraction, analysis, and vulnerability research for routers, IoT devices, automotive systems, and industrial controllers. Use PROACTIVELY for firmware security diff --git a/web-app/public/skills/flutter-expert/SKILL.md b/web-app/public/skills/flutter-expert/SKILL.md index 7b8ee06a..f5d6d848 100644 --- a/web-app/public/skills/flutter-expert/SKILL.md +++ b/web-app/public/skills/flutter-expert/SKILL.md @@ -1,6 +1,7 @@ --- name: flutter-expert -description: "Master Flutter development with Dart 3, advanced widgets, and" +description: | + Master Flutter development with Dart 3, advanced widgets, and multi-platform deployment. Handles state management, animations, testing, and performance optimization for mobile, web, desktop, and embedded platforms. Use PROACTIVELY for Flutter architecture, UI implementation, or cross-platform diff --git a/web-app/public/skills/form-cro/SKILL.md b/web-app/public/skills/form-cro/SKILL.md index d6ec718a..42691609 100644 --- a/web-app/public/skills/form-cro/SKILL.md +++ b/web-app/public/skills/form-cro/SKILL.md @@ -1,6 +1,6 @@ --- name: form-cro -description: ">" +description: > Optimize any form that is NOT signup or account registration — including lead capture, contact, demo request, application, survey, quote, and checkout forms. Use when the goal is to increase form completion rate, reduce friction, or diff --git a/web-app/public/skills/frontend-developer/SKILL.md b/web-app/public/skills/frontend-developer/SKILL.md index 9076ec20..0f065ebb 100644 --- a/web-app/public/skills/frontend-developer/SKILL.md +++ b/web-app/public/skills/frontend-developer/SKILL.md @@ -1,6 +1,7 @@ --- name: frontend-developer -description: "Build React components, implement responsive layouts, and handle" +description: | + Build React components, implement responsive layouts, and handle client-side state management. Masters React 19, Next.js 15, and modern frontend architecture. Optimizes performance and ensures accessibility. Use PROACTIVELY when creating UI components or fixing frontend issues. diff --git a/web-app/public/skills/frontend-security-coder/SKILL.md b/web-app/public/skills/frontend-security-coder/SKILL.md index fd8d22dc..1edc8ade 100644 --- a/web-app/public/skills/frontend-security-coder/SKILL.md +++ b/web-app/public/skills/frontend-security-coder/SKILL.md @@ -1,6 +1,7 @@ --- name: frontend-security-coder -description: "Expert in secure frontend coding practices specializing in XSS" +description: | + Expert in secure frontend coding practices specializing in XSS prevention, output sanitization, and client-side security patterns. Use PROACTIVELY for frontend security implementations or client-side security code reviews. diff --git a/web-app/public/skills/golang-pro/SKILL.md b/web-app/public/skills/golang-pro/SKILL.md index 807a3552..5393bc58 100644 --- a/web-app/public/skills/golang-pro/SKILL.md +++ b/web-app/public/skills/golang-pro/SKILL.md @@ -1,6 +1,7 @@ --- name: golang-pro -description: "Master Go 1.21+ with modern patterns, advanced concurrency," +description: | + Master Go 1.21+ with modern patterns, advanced concurrency, performance optimization, and production-ready microservices. Expert in the latest Go ecosystem including generics, workspaces, and cutting-edge frameworks. Use PROACTIVELY for Go development, architecture design, or diff --git a/web-app/public/skills/graphql-architect/SKILL.md b/web-app/public/skills/graphql-architect/SKILL.md index b6f5fb25..211e873e 100644 --- a/web-app/public/skills/graphql-architect/SKILL.md +++ b/web-app/public/skills/graphql-architect/SKILL.md @@ -1,6 +1,7 @@ --- name: graphql-architect -description: "Master modern GraphQL with federation, performance optimization," +description: | + Master modern GraphQL with federation, performance optimization, and enterprise security. Build scalable schemas, implement advanced caching, and design real-time systems. Use PROACTIVELY for GraphQL architecture or performance optimization. diff --git a/web-app/public/skills/grpc-golang/SKILL.md b/web-app/public/skills/grpc-golang/SKILL.md new file mode 100644 index 00000000..66d17712 --- /dev/null +++ b/web-app/public/skills/grpc-golang/SKILL.md @@ -0,0 +1,103 @@ +--- +name: grpc-golang +description: "Build production-ready gRPC services in Go with mTLS, streaming, and observability. Use when designing Protobuf contracts with Buf or implementing secure service-to-service transport." +risk: safe +source: self +--- + +# gRPC Golang (gRPC-Go) + +## Overview + +Comprehensive guide for designing and implementing production-grade gRPC services in Go. Covers contract standardization with Buf, transport layer security via mTLS, and deep observability with OpenTelemetry interceptors. + +## Use this skill when + +- Designing microservices communication with gRPC in Go. +- Building high-performance internal APIs using Protobuf. +- Implementing streaming workloads (unidirectional or bidirectional). +- Standardizing API contracts using Protobuf and Buf. +- Configuring mTLS for service-to-service authentication. + +## Do not use this skill when + +- Building pure REST/HTTP public APIs without gRPC requirements. +- Modifying legacy `.proto` files without the ability to introduce a new API version (e.g., `api.v2`) or ensure backward compatibility. +- Managing service mesh traffic routing (e.g., Istio/Linkerd), which is outside the application code scope. + +## Step-by-Step Guide + +1. **Confirm Technical Context**: Identify Go version, gRPC-Go version, and whether the project uses Buf or raw protoc. +2. **Confirm Requirements**: Identify mTLS needs, load patterns (unary/streaming), SLOs, and message size limits. +3. **Plan Schema**: Define package versioning (e.g., `api.v1`), resource types, and error mapping. +4. **Security Design**: Implement mTLS for service-to-service authentication. +5. **Observability**: Configure interceptors for tracing, metrics, and structured logging. +6. **Verification**: Always run `buf lint` and breaking change checks before finalizing code generation. + +Refer to `resources/implementation-playbook.md` for detailed patterns, code examples, and anti-patterns. + +## Examples + +### Example 1: Defining a Service & Message (v1 API) + +```proto +syntax = "proto3"; +package api.v1; +option go_package = "github.com/org/repo/gen/api/v1;apiv1"; + +service UserService { + rpc GetUser(GetUserRequest) returns (GetUserResponse); +} + +message User { + string id = 1; + string name = 2; +} + +message GetUserRequest { + string id = 1; +} + +message GetUserResponse { + User user = 1; +} +``` + +## Best Practices + +- ✅ **Do:** Use Buf to standardize your toolchain and linting with `buf.yaml` and `buf.gen.yaml`. +- ✅ **Do:** Always use semantic versioning in package paths (e.g., `package api.v1`). +- ✅ **Do:** Enforce mTLS for all internal service-to-service communication. +- ✅ **Do:** Handle `ctx.Done()` in all streaming handlers to prevent resource leaks. +- ✅ **Do:** Map domain errors to standard gRPC status codes (e.g., `codes.NotFound`). +- ❌ **Don't:** Return raw internal error strings or stack traces to gRPC clients. +- ❌ **Don't:** Create a new `grpc.ClientConn` per request; always reuse connections. + +## Troubleshooting + +- **Error: Inconsistent Gen**: If the generated code does not match the schema, run `buf generate` and verify the `go_package` option. +- **Error: Context Deadline**: Check client timeouts and ensure the server is not blocking infinitely in streaming handlers. +- **Error: mTLS Handshake**: Ensure the CA certificate is correctly added to the `x509.CertPool` on both client and server sides. + +## Limitations + +- Does not cover service mesh traffic routing (Istio/Linkerd configuration). +- Does not cover gRPC-Web or browser-based gRPC integration. +- Assumes Go 1.21+ and gRPC-Go v1.60+; older versions may have different APIs (e.g., `grpc.Dial` vs `grpc.NewClient`). +- Does not cover L7 gRPC-aware load balancer configuration (e.g., Envoy, NGINX). +- Does not address Protobuf schema registry or large-scale schema governance beyond Buf lint. + +## Resources + +- `resources/implementation-playbook.md` for detailed patterns, code examples, and anti-patterns. +- [Google API Design Guide](https://cloud.google.com/apis/design) +- [Buf Docs](https://buf.build/docs) +- [gRPC-Go Docs](https://grpc.io/docs/languages/go/) +- [OpenTelemetry Go Instrumentation](https://opentelemetry.io/docs/instrumentation/go/) + +## Related Skills + +- @golang-pro - General Go patterns and performance optimization outside the gRPC layer. +- @go-concurrency-patterns - Advanced goroutine lifecycle management for streaming handlers. +- @api-design-principles - Resource naming and versioning strategy before writing `.proto` files. +- @docker-expert - Containerizing gRPC services and configuring TLS cert injection via Docker secrets. diff --git a/web-app/public/skills/grpc-golang/resources/implementation-playbook.md b/web-app/public/skills/grpc-golang/resources/implementation-playbook.md new file mode 100644 index 00000000..e6eece49 --- /dev/null +++ b/web-app/public/skills/grpc-golang/resources/implementation-playbook.md @@ -0,0 +1,548 @@ +# gRPC Golang Implementation Playbook + +This file contains detailed patterns, checklists, and code samples referenced by the skill. + +## Schema Design Standards + +### Protobuf Definition + +- **Syntax**: Use proto3 only. +- **Versioning**: Use package versioning (e.g., `api.v1`). +- **Pagination**: Use `page_token` and `page_size` for list operations. +- **Timezone**: Always use `google.protobuf.Timestamp` with UTC values at the server level. +- **Idempotency**: Use idempotency keys or design side-effect-free methods to allow safe retries. +- **Validation**: Adopt a schema-level validation approach (e.g., Buf validation rules or `protoc-gen-validate`) and ensure generated code is enforced server-side. + +```proto +syntax = "proto3"; +package api.v1; +option go_package = "github.com/org/repo/gen/api/v1;apiv1"; + +import "google/protobuf/timestamp.proto"; + +service UserService { + rpc GetUser(GetUserRequest) returns (GetUserResponse); + rpc ListUsers(ListUsersRequest) returns (ListUsersResponse); + rpc WatchUsers(WatchUsersRequest) returns (stream UserEvent); +} + +message User { + string id = 1; + string name = 2; + string email = 3; + google.protobuf.Timestamp created_at = 4; +} + +message GetUserRequest { + string id = 1; +} + +message GetUserResponse { + User user = 1; +} + +message ListUsersRequest { + int32 page_size = 1; + string page_token = 2; +} + +message ListUsersResponse { + repeated User users = 1; + string next_page_token = 2; +} + +message WatchUsersRequest { + // Empty; streams all user events from the current point. +} + +message UserEvent { + enum EventType { + EVENT_TYPE_UNSPECIFIED = 0; + EVENT_TYPE_CREATED = 1; + EVENT_TYPE_UPDATED = 2; + EVENT_TYPE_DELETED = 3; + } + EventType type = 1; + User user = 2; + google.protobuf.Timestamp occurred_at = 3; +} +``` + +## Code Generation + +- **Toolchain**: Use `google.golang.org/protobuf/cmd/protoc-gen-go` and `protoc-gen-go-grpc`. +- **Management**: Use `buf.gen.yaml` to manage plugin versions and generation parameters. +- **Compatibility**: Ensure plugins use Protobuf Go v2 API (`google.golang.org/protobuf`). Do not mix with the deprecated v1 API (`github.com/golang/protobuf`). + +### buf.gen.yaml Example + +```yaml +version: v2 +plugins: + - remote: buf.build/protocolbuffers/go + out: gen + opt: paths=source_relative + - remote: buf.build/grpc/go + out: gen + opt: paths=source_relative +``` + +## Server Implementation + +### Full Server Setup with Graceful Shutdown + +```go +package main + +import ( + "context" + "log" + "net" + "os" + "os/signal" + "syscall" + "time" + + "google.golang.org/grpc" + "google.golang.org/grpc/health" + healthpb "google.golang.org/grpc/health/grpc_health_v1" + "google.golang.org/grpc/keepalive" + + apiv1 "github.com/org/repo/gen/api/v1" +) + +func main() { + srv := grpc.NewServer( + grpc.ChainUnaryInterceptor( + recoveryInterceptor, + loggingInterceptor, + otelUnaryInterceptor, + ), + grpc.KeepaliveParams(keepalive.ServerParameters{ + MaxConnectionIdle: 5 * time.Minute, + Time: 1 * time.Minute, + Timeout: 20 * time.Second, + }), + grpc.MaxRecvMsgSize(4<<20), // 4 MB + grpc.MaxSendMsgSize(4<<20), // 4 MB + ) + + // Register application services. + apiv1.RegisterUserServiceServer(srv, newUserService()) + + // Register health check with fully-qualified service name. + healthSrv := health.NewServer() + healthpb.RegisterHealthServer(srv, healthSrv) + healthSrv.SetServingStatus( + "api.v1.UserService", + healthpb.HealthCheckResponse_SERVING, + ) + + lis, err := net.Listen("tcp", ":50051") + if err != nil { + log.Fatalf("listen: %v", err) + } + + // Graceful shutdown: GracefulStop with a fallback timeout to Stop. + go func() { + sigCh := make(chan os.Signal, 1) + signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM) + <-sigCh + + log.Println("shutting down gRPC server...") + healthSrv.SetServingStatus( + "api.v1.UserService", + healthpb.HealthCheckResponse_NOT_SERVING, + ) + + ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second) + defer cancel() + + stopped := make(chan struct{}) + go func() { + srv.GracefulStop() + close(stopped) + }() + + select { + case <-stopped: + log.Println("server stopped gracefully") + case <-ctx.Done(): + log.Println("graceful stop timed out, forcing stop") + srv.Stop() + } + }() + + log.Printf("gRPC server listening on %s", lis.Addr()) + if err := srv.Serve(lis); err != nil { + log.Fatalf("serve: %v", err) + } +} +``` + +## mTLS Setup + +```go +package main + +import ( + "crypto/tls" + "crypto/x509" + "fmt" + "log" + "os" + + "google.golang.org/grpc" + "google.golang.org/grpc/credentials" +) + +// loadServerTLS configures mTLS for the server side. +func loadServerTLS() grpc.ServerOption { + tlsCert, err := tls.LoadX509KeyPair("server.crt", "server.key") + if err != nil { + log.Fatalf("load server cert: %v", err) + } + + caCert, err := os.ReadFile("ca.crt") + if err != nil { + log.Fatalf("read CA cert: %v", err) + } + + caPool := x509.NewCertPool() + if !caPool.AppendCertsFromPEM(caCert) { + log.Fatal("failed to append CA cert") + } + + tlsCfg := &tls.Config{ + Certificates: []tls.Certificate{tlsCert}, + ClientCAs: caPool, + ClientAuth: tls.RequireAndVerifyClientCert, + MinVersion: tls.VersionTLS13, + } + return grpc.Creds(credentials.NewTLS(tlsCfg)) +} + +// dialWithMTLS creates a client connection using mTLS. +func dialWithMTLS(target string) (*grpc.ClientConn, error) { + clientCert, err := tls.LoadX509KeyPair("client.crt", "client.key") + if err != nil { + return nil, fmt.Errorf("load client cert: %w", err) + } + + caCert, err := os.ReadFile("ca.crt") + if err != nil { + return nil, fmt.Errorf("read CA cert: %w", err) + } + + caPool := x509.NewCertPool() + if !caPool.AppendCertsFromPEM(caCert) { + return nil, fmt.Errorf("failed to append CA cert") + } + + creds := credentials.NewTLS(&tls.Config{ + Certificates: []tls.Certificate{clientCert}, + RootCAs: caPool, + MinVersion: tls.VersionTLS13, + }) + + // Note: for gRPC-Go v1.63+, grpc.NewClient is the recommended replacement. + conn, err := grpc.Dial(target, grpc.WithTransportCredentials(creds)) + if err != nil { + return nil, fmt.Errorf("dial %s: %w", target, err) + } + return conn, nil +} +``` + +## Client Best Practices + +### Connection Reuse + +```go +package main + +import ( + "context" + "fmt" + "log" + "os" + "time" + + "google.golang.org/grpc" + "google.golang.org/grpc/credentials" + + apiv1 "github.com/org/repo/gen/api/v1" +) + +// Initialize once at startup; reuse across the application lifetime. +var userConn *grpc.ClientConn + +func initClients(creds credentials.TransportCredentials) { + var err error + // Note: for gRPC-Go v1.63+, use grpc.NewClient instead. + userConn, err = grpc.Dial( + os.Getenv("USER_SVC_ADDR"), + grpc.WithTransportCredentials(creds), + ) + if err != nil { + log.Fatalf("dial user-svc: %v", err) + } +} + +func callListUsers(ctx context.Context) (*apiv1.ListUsersResponse, error) { + // Always set a deadline per call, not per connection. + ctx, cancel := context.WithTimeout(ctx, 5*time.Second) + defer cancel() + + client := apiv1.NewUserServiceClient(userConn) + resp, err := client.ListUsers(ctx, &apiv1.ListUsersRequest{PageSize: 20}) + if err != nil { + return nil, fmt.Errorf("list users: %w", err) + } + return resp, nil +} +``` + +### Retry Policy + +Only enable retries for idempotent calls. Use exponential backoff. + +```go +import "google.golang.org/grpc" + +// Service config with retry policy for idempotent methods. +const retryPolicy = `{ + "methodConfig": [{ + "name": [{"service": "api.v1.UserService", "method": "GetUser"}], + "retryPolicy": { + "maxAttempts": 3, + "initialBackoff": "0.1s", + "maxBackoff": "1s", + "backoffMultiplier": 2, + "retryableStatusCodes": ["UNAVAILABLE", "DEADLINE_EXCEEDED"] + } + }] +}` + +// Note: for gRPC-Go v1.63+, use grpc.NewClient instead of grpc.Dial. +conn, err := grpc.Dial( + target, + grpc.WithTransportCredentials(creds), + grpc.WithDefaultServiceConfig(retryPolicy), +) +``` + +## Observability + +### Interceptor Labels + +- **Logging**: Include `grpc.method`, `grpc.service`, `grpc.code`, `latency_ms`, and `trace_id`. +- **Metrics**: Export request count, latency histogram, and in-flight stream count. + +### OpenTelemetry Integration + +```go +import ( + "go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc" + "google.golang.org/grpc" +) + +srv := grpc.NewServer( + grpc.StatsHandler(otelgrpc.NewServerHandler()), +) + +// Note: for gRPC-Go v1.63+, use grpc.NewClient instead of grpc.Dial. +conn, err := grpc.Dial( + target, + grpc.WithStatsHandler(otelgrpc.NewClientHandler()), +) +``` + +## Testing + +### bufconn In-Process Test + +```go +package service_test + +import ( + "context" + "net" + "testing" + "time" + + "google.golang.org/grpc" + "google.golang.org/grpc/credentials/insecure" + "google.golang.org/grpc/status" + "google.golang.org/grpc/codes" + "google.golang.org/grpc/test/bufconn" + + apiv1 "github.com/org/repo/gen/api/v1" +) + +func TestListUsers(t *testing.T) { + lis := bufconn.Listen(1 << 20) + srv := grpc.NewServer() + apiv1.RegisterUserServiceServer(srv, &fakeUserSvc{}) + go func() { + if err := srv.Serve(lis); err != nil { + t.Logf("server exited: %v", err) + } + }() + t.Cleanup(srv.GracefulStop) + + // Note: for gRPC-Go v1.63+, use grpc.NewClient instead of grpc.DialContext. + conn, err := grpc.DialContext(context.Background(), + "bufnet", + grpc.WithContextDialer(func(ctx context.Context, _ string) (net.Conn, error) { + return lis.DialContext(ctx) + }), + grpc.WithTransportCredentials(insecure.NewCredentials()), + ) + if err != nil { + t.Fatalf("dial bufnet: %v", err) + } + t.Cleanup(func() { conn.Close() }) + + client := apiv1.NewUserServiceClient(conn) + ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second) + defer cancel() + + resp, err := client.ListUsers(ctx, &apiv1.ListUsersRequest{PageSize: 10}) + if code := status.Code(err); code != codes.OK { + t.Fatalf("expected OK, got %v: %v", code, err) + } + if resp == nil { + t.Fatal("expected non-nil response") + } +} +``` + +## Streaming Handler Pattern + +Always check `ctx.Done()` in streaming loops. Never expose raw internal errors to clients. + +```go +func (s *userService) WatchUsers( + req *apiv1.WatchUsersRequest, + stream apiv1.UserService_WatchUsersServer, +) error { + ctx := stream.Context() + + events := s.subscribeUserEvents() + defer s.unsubscribe(events) + + for { + select { + case <-ctx.Done(): + // Client disconnected or deadline exceeded; exit cleanly. + return status.Error(codes.Canceled, "client disconnected") + + case event, ok := <-events: + if !ok { + // Channel closed; server is shutting down. + return status.Error(codes.Unavailable, "service shutting down") + } + + if err := stream.Send(event); err != nil { + // Log the raw error server-side for diagnostics. + log.Printf("stream send failed: %v", err) + // Return a generic message to the client; never leak raw err. + return status.Error(codes.Internal, "failed to send event") + } + } + } +} +``` + +## Error Mapping + +Map domain errors to gRPC status codes consistently: + +Only return `err.Error()` to clients when it is a safe, user-facing domain message (not an internal error string). + +```go +package service + +import ( + "errors" + + "google.golang.org/grpc/codes" + "google.golang.org/grpc/status" +) + +var ( + ErrNotFound = errors.New("resource not found") + ErrAlreadyExists = errors.New("resource already exists") + ErrInvalidInput = errors.New("invalid input") + ErrPermission = errors.New("permission denied") +) + +// toGRPCError maps a domain error to a gRPC status error. +func toGRPCError(err error) error { + if err == nil { + return nil + } + switch { + case errors.Is(err, ErrNotFound): + return status.Error(codes.NotFound, err.Error()) + case errors.Is(err, ErrAlreadyExists): + return status.Error(codes.AlreadyExists, err.Error()) + case errors.Is(err, ErrInvalidInput): + return status.Error(codes.InvalidArgument, err.Error()) + case errors.Is(err, ErrPermission): + return status.Error(codes.PermissionDenied, err.Error()) + default: + return status.Error(codes.Internal, "internal error") + } +} +``` + +## Project Layout + +``` +project/ + buf.gen.yaml + buf.yaml + proto/ + api/ + v1/ + user_service.proto + gen/ # Generated code (committed or gitignored) + api/ + v1/ + user_service.pb.go + user_service_grpc.pb.go + internal/ + service/ + user.go # Service implementation + user_test.go # bufconn tests + domain/ + errors.go # Domain error definitions + cmd/ + server/ + main.go # Server entrypoint with graceful shutdown + config/ + config.go # Env-based config (timeouts, TLS paths, limits) +``` + +## Safety Checklist + +- Default to TLS/mTLS for all production traffic. +- Enforce limits (`MaxRecvMsgSize`, `MaxSendMsgSize`, metadata size) to reduce resource exhaustion. +- Treat client-sent metadata as untrusted; validate and allowlist keys used for auth or tenant routing. +- Disable gRPC reflection in production to avoid exposing internal service schemas. +- Check `context.Done()` in every iteration of a streaming handler to prevent goroutine leaks. + +## Anti-Patterns + +| Anti-Pattern | Why It Hurts | Fix | +| --------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | +| Create new `grpc.ClientConn` per request | Exhausts OS sockets and disables HTTP/2 multiplexing, causing high latency and resource leaks | Initialize once, reuse globally | +| Mix Protobuf v1 and v2 libraries | Causes silent marshaling bugs; `proto.Marshal` from v1 and v2 are NOT interchangeable | Pin to `google.golang.org/protobuf` (v2) throughout | +| Expose raw internal error strings to clients | Leaks stack traces and internal service names; a security and UX risk | Map errors with `status.Errorf` using appropriate gRPC codes | +| Ignore `context.Done()` in streaming handlers | Goroutine and connection leak when client disconnects | Check `ctx.Err()` in every iteration of a streaming loop | +| Skip error handling with `_ =` | Hides failures silently; production outages become undiagnosable | Always check and handle errors explicitly | +| Use `grpc.Dial` without health checks | Connection failures are deferred and may surface as runtime errors | Use health checks and monitor connection state | + +> **Migration note**: For gRPC-Go v1.63+ (Jan 2024), `grpc.NewClient` is the newer API recommended by the gRPC-Go project for new code. For older versions (or when following existing codebases and official grpc.io examples), using `grpc.Dial` / `grpc.DialContext` is still common. diff --git a/web-app/public/skills/hig-components-content/SKILL.md b/web-app/public/skills/hig-components-content/SKILL.md index 5e6e86d9..e5083edf 100644 --- a/web-app/public/skills/hig-components-content/SKILL.md +++ b/web-app/public/skills/hig-components-content/SKILL.md @@ -1,7 +1,7 @@ --- name: hig-components-content version: 1.0.0 -description: ">" +description: > Apple Human Interface Guidelines for content display components. Use this skill when the user asks about "charts component", "collection view", "image view", "web view", "color well", "image well", "activity view", "lockup", "data visualization", "content display", displaying images, rendering diff --git a/web-app/public/skills/hig-components-controls/SKILL.md b/web-app/public/skills/hig-components-controls/SKILL.md index 3bfe5397..ae7fdb11 100644 --- a/web-app/public/skills/hig-components-controls/SKILL.md +++ b/web-app/public/skills/hig-components-controls/SKILL.md @@ -1,7 +1,7 @@ --- name: hig-components-controls version: 1.0.0 -description: ">-" +description: >- Apple HIG guidance for selection and input controls including pickers, toggles, sliders, steppers, segmented controls, combo boxes, text fields, text views, labels, token fields, virtual keyboards, rating indicators, and gauges. Use diff --git a/web-app/public/skills/hig-components-dialogs/SKILL.md b/web-app/public/skills/hig-components-dialogs/SKILL.md index 1242ca6c..ce2ea3ea 100644 --- a/web-app/public/skills/hig-components-dialogs/SKILL.md +++ b/web-app/public/skills/hig-components-dialogs/SKILL.md @@ -1,7 +1,7 @@ --- name: hig-components-dialogs version: 1.0.0 -description: ">-" +description: >- Apple HIG guidance for presentation components including alerts, action sheets, popovers, sheets, and digit entry views. Use this skill when the user says "should I use an alert or a sheet," "how do I show a confirmation dialog," diff --git a/web-app/public/skills/hig-components-layout/SKILL.md b/web-app/public/skills/hig-components-layout/SKILL.md index fd26bda2..f4c44de8 100644 --- a/web-app/public/skills/hig-components-layout/SKILL.md +++ b/web-app/public/skills/hig-components-layout/SKILL.md @@ -1,7 +1,7 @@ --- name: hig-components-layout version: 1.0.0 -description: ">" +description: > Apple Human Interface Guidelines for layout and navigation components. Use this skill when the user asks about "sidebar", "split view", "tab bar", "tab view", "scroll view", "window design", "panel", "list view", "table view", "column view", "outline view", "navigation structure", "app layout", diff --git a/web-app/public/skills/hig-components-menus/SKILL.md b/web-app/public/skills/hig-components-menus/SKILL.md index b75247a5..6a3b2892 100644 --- a/web-app/public/skills/hig-components-menus/SKILL.md +++ b/web-app/public/skills/hig-components-menus/SKILL.md @@ -1,7 +1,7 @@ --- name: hig-components-menus version: 1.0.0 -description: ">-" +description: >- Apple HIG guidance for menu and button components including menus, context menus, dock menus, edit menus, the menu bar, toolbars, action buttons, pop-up buttons, pull-down buttons, disclosure controls, and standard buttons. Use this skill diff --git a/web-app/public/skills/hig-components-search/SKILL.md b/web-app/public/skills/hig-components-search/SKILL.md index af722b5d..71f35232 100644 --- a/web-app/public/skills/hig-components-search/SKILL.md +++ b/web-app/public/skills/hig-components-search/SKILL.md @@ -1,7 +1,7 @@ --- name: hig-components-search version: 1.0.0 -description: ">-" +description: >- Apple HIG guidance for navigation-related components including search fields, page controls, and path controls. Use this skill when the user says "how should search work in my app," "I need a breadcrumb," "how do I paginate content," or diff --git a/web-app/public/skills/hig-components-status/SKILL.md b/web-app/public/skills/hig-components-status/SKILL.md index de026f09..20586287 100644 --- a/web-app/public/skills/hig-components-status/SKILL.md +++ b/web-app/public/skills/hig-components-status/SKILL.md @@ -1,7 +1,7 @@ --- name: hig-components-status version: 1.0.0 -description: ">" +description: > Apple HIG guidance for status and progress UI components including progress indicators, status bars, and activity rings. Use this skill when asked about: "progress indicator", "progress bar", "loading spinner", "status bar", "activity ring", "progress display", diff --git a/web-app/public/skills/hig-components-system/SKILL.md b/web-app/public/skills/hig-components-system/SKILL.md index ccf7ed22..cf87dc15 100644 --- a/web-app/public/skills/hig-components-system/SKILL.md +++ b/web-app/public/skills/hig-components-system/SKILL.md @@ -1,7 +1,7 @@ --- name: hig-components-system version: 1.0.0 -description: ">" +description: > Apple HIG guidance for system experience components: widgets, live activities, notifications, complications, home screen quick actions, top shelf, watch faces, app clips, and app shortcuts. Use when asked about: "widget design", "live activity", diff --git a/web-app/public/skills/hig-foundations/SKILL.md b/web-app/public/skills/hig-foundations/SKILL.md index 294e1baa..821c237b 100644 --- a/web-app/public/skills/hig-foundations/SKILL.md +++ b/web-app/public/skills/hig-foundations/SKILL.md @@ -1,7 +1,7 @@ --- name: hig-foundations version: 1.0.0 -description: ">" +description: > Apple Human Interface Guidelines design foundations. Use this skill when the user asks about "HIG color", "Apple typography", "SF Symbols", "dark mode guidelines", "accessible design", "Apple design foundations", "app icon", "layout guidelines", "materials", "motion", "privacy", diff --git a/web-app/public/skills/hig-inputs/SKILL.md b/web-app/public/skills/hig-inputs/SKILL.md index 199f52a5..dc00c8a6 100644 --- a/web-app/public/skills/hig-inputs/SKILL.md +++ b/web-app/public/skills/hig-inputs/SKILL.md @@ -1,7 +1,7 @@ --- name: hig-inputs version: 1.0.0 -description: ">" +description: > Apple HIG guidance for input methods and interaction patterns: gestures, Apple Pencil, keyboards, game controllers, pointers, Digital Crown, eye tracking, focus system, remotes, spatial interactions, gyroscope, accelerometer, and nearby interactions. diff --git a/web-app/public/skills/hig-patterns/SKILL.md b/web-app/public/skills/hig-patterns/SKILL.md index 2114dd74..33deb5c4 100644 --- a/web-app/public/skills/hig-patterns/SKILL.md +++ b/web-app/public/skills/hig-patterns/SKILL.md @@ -1,7 +1,7 @@ --- name: hig-patterns version: 1.0.0 -description: ">" +description: > Apple Human Interface Guidelines interaction and UX patterns. Use this skill when the user asks about "onboarding flow", "user onboarding", "app launch", "loading state", "drag and drop", "search pattern", "settings design", "notifications", "modality", "multitasking", "feedback pattern", "haptics", diff --git a/web-app/public/skills/hig-platforms/SKILL.md b/web-app/public/skills/hig-platforms/SKILL.md index 85eacd9e..df3a5fce 100644 --- a/web-app/public/skills/hig-platforms/SKILL.md +++ b/web-app/public/skills/hig-platforms/SKILL.md @@ -1,7 +1,7 @@ --- name: hig-platforms version: 1.0.0 -description: ">" +description: > Apple Human Interface Guidelines for platform-specific design. Use this skill when the user asks about "designing for iOS", "iPad app design", "macOS design", "tvOS", "visionOS", "watchOS", "Apple platform", "which platform", platform differences, platform-specific conventions, or multi-platform app design. diff --git a/web-app/public/skills/hig-project-context/SKILL.md b/web-app/public/skills/hig-project-context/SKILL.md index 1a49d8d1..95037430 100644 --- a/web-app/public/skills/hig-project-context/SKILL.md +++ b/web-app/public/skills/hig-project-context/SKILL.md @@ -1,7 +1,7 @@ --- name: hig-project-context version: 1.0.0 -description: ">-" +description: >- Create or update a shared Apple design context document that other HIG skills use to tailor guidance. Use when the user says "set up my project context," "what platforms am I targeting," "configure HIG settings," or when starting a diff --git a/web-app/public/skills/hig-technologies/SKILL.md b/web-app/public/skills/hig-technologies/SKILL.md index abb66f63..556cc949 100644 --- a/web-app/public/skills/hig-technologies/SKILL.md +++ b/web-app/public/skills/hig-technologies/SKILL.md @@ -1,7 +1,7 @@ --- name: hig-technologies version: 1.0.0 -description: ">" +description: > Apple HIG guidance for Apple technology integrations: Siri, Apple Pay, HealthKit, HomeKit, ARKit, machine learning, generative AI, iCloud, Sign in with Apple, SharePlay, CarPlay, Game Center, in-app purchase, NFC, Wallet, VoiceOver, Maps, diff --git a/web-app/public/skills/hr-pro/SKILL.md b/web-app/public/skills/hr-pro/SKILL.md index b9607f97..c3d81cd4 100644 --- a/web-app/public/skills/hr-pro/SKILL.md +++ b/web-app/public/skills/hr-pro/SKILL.md @@ -1,6 +1,7 @@ --- name: hr-pro -description: "Professional, ethical HR partner for hiring," +description: | + Professional, ethical HR partner for hiring, onboarding/offboarding, PTO and leave, performance, compliant policies, and employee relations. Ask for jurisdiction and company context before advising; produce structured, bias-mitigated, lawful templates. diff --git a/web-app/public/skills/hybrid-cloud-architect/SKILL.md b/web-app/public/skills/hybrid-cloud-architect/SKILL.md index cb7eaf2d..bf3b6bbe 100644 --- a/web-app/public/skills/hybrid-cloud-architect/SKILL.md +++ b/web-app/public/skills/hybrid-cloud-architect/SKILL.md @@ -1,6 +1,7 @@ --- name: hybrid-cloud-architect -description: "Expert hybrid cloud architect specializing in complex multi-cloud" +description: | + Expert hybrid cloud architect specializing in complex multi-cloud solutions across AWS/Azure/GCP and private clouds (OpenStack/VMware). Masters hybrid connectivity, workload placement optimization, edge computing, and cross-cloud automation. Handles compliance, cost optimization, disaster diff --git a/web-app/public/skills/imagen/SKILL.md b/web-app/public/skills/imagen/SKILL.md index 1497cc89..92b0bb50 100644 --- a/web-app/public/skills/imagen/SKILL.md +++ b/web-app/public/skills/imagen/SKILL.md @@ -1,6 +1,6 @@ --- name: imagen -description: "|" +description: | source: "https://github.com/sanjay3290/ai-skills/tree/main/skills/imagen" risk: safe --- diff --git a/web-app/public/skills/incident-responder/SKILL.md b/web-app/public/skills/incident-responder/SKILL.md index f78f9519..0ec76b66 100644 --- a/web-app/public/skills/incident-responder/SKILL.md +++ b/web-app/public/skills/incident-responder/SKILL.md @@ -1,6 +1,7 @@ --- name: incident-responder -description: "Expert SRE incident responder specializing in rapid problem" +description: | + Expert SRE incident responder specializing in rapid problem resolution, modern observability, and comprehensive incident management. Masters incident command, blameless post-mortems, error budget management, and system reliability patterns. Handles critical outages, communication diff --git a/web-app/public/skills/inventory-demand-planning/SKILL.md b/web-app/public/skills/inventory-demand-planning/SKILL.md new file mode 100644 index 00000000..933d7e1d --- /dev/null +++ b/web-app/public/skills/inventory-demand-planning/SKILL.md @@ -0,0 +1,239 @@ +--- +name: inventory-demand-planning +description: > + Codified expertise for demand forecasting, safety stock optimisation, + replenishment planning, and promotional lift estimation at multi-location + retailers. Informed by demand planners with 15+ years experience managing + hundreds of SKUs. Includes forecasting method selection, ABC/XYZ analysis, + seasonal transition management, and vendor negotiation frameworks. + Use when forecasting demand, setting safety stock, planning replenishment, + managing promotions, or optimising inventory levels. +license: Apache-2.0 +version: 1.0.0 +homepage: https://github.com/evos-ai/evos-capabilities +risk: safe +source: https://github.com/ai-evos/agent-skills +metadata: + author: evos + clawdbot: + emoji: "📊" +--- + +## When to Use + +Use this skill when forecasting product demand, calculating optimal safety stock levels, planning inventory replenishment cycles, estimating the impact of retail promotions, or conducting ABC/XYZ inventory segmentation. + +# Inventory Demand Planning + +## Role and Context + +You are a senior demand planner at a multi-location retailer operating 40–200 stores with regional distribution centers. You manage 300–800 active SKUs across categories including grocery, general merchandise, seasonal, and promotional assortments. Your systems include a demand planning suite (Blue Yonder, Oracle Demantra, or Kinaxis), an ERP (SAP, Oracle), a WMS for DC-level inventory, POS data feeds at the store level, and vendor portals for purchase order management. You sit between merchandising (which decides what to sell and at what price), supply chain (which manages warehouse capacity and transportation), and finance (which sets inventory investment budgets and GMROI targets). Your job is to translate commercial intent into executable purchase orders while minimizing both stockouts and excess inventory. + +## Core Knowledge + +### Forecasting Methods and When to Use Each + +**Moving Averages (simple, weighted, trailing):** Use for stable-demand, low-variability items where recent history is a reliable predictor. A 4-week simple moving average works for commodity staples. Weighted moving averages (heavier on recent weeks) work better when demand is stable but shows slight drift. Never use moving averages on seasonal items — they lag trend changes by half the window length. + +**Exponential Smoothing (single, double, triple):** Single exponential smoothing (SES, alpha 0.1–0.3) suits stationary demand with noise. Double exponential smoothing (Holt's) adds trend tracking — use for items with consistent growth or decline. Triple exponential smoothing (Holt-Winters) adds seasonal indices — this is the workhorse for seasonal items with 52-week or 12-month cycles. The alpha/beta/gamma parameters are critical: high alpha (>0.3) chases noise in volatile items; low alpha (<0.1) responds too slowly to regime changes. Optimize on holdout data, never on the same data used for fitting. + +**Seasonal Decomposition (STL, classical, X-13ARIMA-SEATS):** When you need to isolate trend, seasonal, and residual components separately. STL (Seasonal and Trend decomposition using Loess) is robust to outliers. Use seasonal decomposition when seasonal patterns are shifting year over year, when you need to remove seasonality before applying a different model to the de-seasonalized data, or when building promotional lift estimates on top of a clean baseline. + +**Causal/Regression Models:** When external factors drive demand beyond the item's own history — price elasticity, promotional flags, weather, competitor actions, local events. The practical challenge is feature engineering: promotional flags should encode depth (% off), display type, circular feature, and cross-category promo presence. Overfitting on sparse promo history is the single biggest pitfall. Regularize aggressively (Lasso/Ridge) and validate on out-of-time, not out-of-sample. + +**Machine Learning (gradient boosting, neural nets):** Justified when you have large data (1,000+ SKUs × 2+ years of weekly history), multiple external regressors, and an ML engineering team. LightGBM/XGBoost with proper feature engineering outperforms simpler methods by 10–20% WAPE on promotional and intermittent items. But they require continuous monitoring — model drift in retail is real and quarterly retraining is the minimum. + +### Forecast Accuracy Metrics + +- **MAPE (Mean Absolute Percentage Error):** Standard metric but breaks on low-volume items (division by near-zero actuals produces inflated percentages). Use only for items averaging 50+ units/week. +- **Weighted MAPE (WMAPE):** Sum of absolute errors divided by sum of actuals. Prevents low-volume items from dominating the metric. This is the metric finance cares about because it reflects dollars. +- **Bias:** Average signed error. Positive bias = forecast systematically too high (overstock risk). Negative bias = systematically too low (stockout risk). Bias < ±5% is healthy. Bias > 10% in either direction means a structural problem in the model, not noise. +- **Tracking Signal:** Cumulative error divided by MAD (mean absolute deviation). When tracking signal exceeds ±4, the model has drifted and needs intervention — either re-parameterize or switch methods. + +### Safety Stock Calculation + +The textbook formula is `SS = Z × σ_d × √(LT + RP)` where Z is the service level z-score, σ_d is the standard deviation of demand per period, LT is lead time in periods, and RP is review period in periods. In practice, this formula works only for normally distributed, stationary demand. + +**Service Level Targets:** 95% service level (Z=1.65) is standard for A-items. 99% (Z=2.33) for critical/A+ items where stockout cost dwarfs holding cost. 90% (Z=1.28) is acceptable for C-items. Moving from 95% to 99% nearly doubles safety stock — always quantify the inventory investment cost of the incremental service level before committing. + +**Lead Time Variability:** When vendor lead times are uncertain, use `SS = Z × √(LT_avg × σ_d² + d_avg² × σ_LT²)` — this captures both demand variability and lead time variability. Vendors with coefficient of variation (CV) on lead time > 0.3 need safety stock adjustments that can be 40–60% higher than demand-only formulas suggest. + +**Lumpy/Intermittent Demand:** Normal-distribution safety stock fails for items with many zero-demand periods. Use Croston's method for forecasting intermittent demand (separate forecasts for demand interval and demand size), and compute safety stock using a bootstrapped demand distribution rather than analytical formulas. + +**New Products:** No demand history means no σ_d. Use analogous item profiling — find the 3–5 most similar items at the same lifecycle stage and use their demand variability as a proxy. Add a 20–30% buffer for the first 8 weeks, then taper as own history accumulates. + +### Reorder Logic + +**Inventory Position:** `IP = On-Hand + On-Order − Backorders − Committed (allocated to open customer orders)`. Never reorder based on on-hand alone — you will double-order when POs are in transit. + +**Min/Max:** Simple, suitable for stable-demand items with consistent lead times. Min = average demand during lead time + safety stock. Max = Min + EOQ. When IP drops to Min, order up to Max. The weakness: it doesn't adapt to changing demand patterns without manual adjustment. + +**Reorder Point / EOQ:** ROP = average demand during lead time + safety stock. EOQ = √(2DS/H) where D = annual demand, S = ordering cost, H = holding cost per unit per year. EOQ is theoretically optimal for constant demand, but in practice you round to vendor case packs, layer quantities, or pallet tiers. A "perfect" EOQ of 847 units means nothing if the vendor ships in cases of 24. + +**Periodic Review (R,S):** Review inventory every R periods, order up to target level S. Better when you consolidate orders to a vendor on fixed days (e.g., Tuesday orders for Thursday pickup). R is set by vendor delivery schedule; S = average demand during (R + LT) + safety stock for that combined period. + +**Vendor Tier-Based Frequencies:** A-vendors (top 10 by spend) get weekly review cycles. B-vendors (next 20) get bi-weekly. C-vendors (remaining) get monthly. This aligns review effort with financial impact and allows consolidation discounts. + +### Promotional Planning + +**Demand Signal Distortion:** Promotions create artificial demand peaks that contaminate baseline forecasting. Strip promotional volume from history before fitting baseline models. Keep a separate "promotional lift" layer that applies multiplicatively on top of the baseline during promo weeks. + +**Lift Estimation Methods:** (1) Year-over-year comparison of promoted vs. non-promoted periods for the same item. (2) Cross-elasticity model using historical promo depth, display type, and media support as inputs. (3) Analogous item lift — new items borrow lift profiles from similar items in the same category that have been promoted before. Typical lifts: 15–40% for TPR (temporary price reduction) only, 80–200% for TPR + display + circular feature, 300–500%+ for doorbuster/loss-leader events. + +**Cannibalization:** When SKU A is promoted, SKU B (same category, similar price point) loses volume. Estimate cannibalization at 10–30% of lifted volume for close substitutes. Ignore cannibalization across categories unless the promo is a traffic driver that shifts basket composition. + +**Forward-Buy Calculation:** Customers stock up during deep promotions, creating a post-promo dip. The dip duration correlates with product shelf life and promotional depth. A 30% off promotion on a pantry item with 12-month shelf life creates a 2–4 week dip as households consume stockpiled units. A 15% off promotion on a perishable produces almost no dip. + +**Post-Promo Dip:** Expect 1–3 weeks of below-baseline demand after a major promotion. The dip magnitude is typically 30–50% of the incremental lift, concentrated in the first week post-promo. Failing to forecast the dip leads to excess inventory and markdowns. + +### ABC/XYZ Classification + +**ABC (Value):** A = top 20% of SKUs driving 80% of revenue/margin. B = next 30% driving 15%. C = bottom 50% driving 5%. Classify on margin contribution, not revenue, to avoid overinvesting in high-revenue low-margin items. + +**XYZ (Predictability):** X = CV of demand < 0.5 (highly predictable). Y = CV 0.5–1.0 (moderately predictable). Z = CV > 1.0 (erratic/lumpy). Compute on de-seasonalized, de-promoted demand to avoid penalizing seasonal items that are actually predictable within their pattern. + +**Policy Matrix:** AX items get automated replenishment with tight safety stock. AZ items need human review every cycle — they're high-value but erratic. CX items get automated replenishment with generous review periods. CZ items are candidates for discontinuation or make-to-order conversion. + +### Seasonal Transition Management + +**Buy Timing:** Seasonal buys (e.g., holiday, summer, back-to-school) are committed 12–20 weeks before selling season. Allocate 60–70% of expected season demand in the initial buy, reserving 30–40% for reorder based on early-season sell-through. This "open-to-buy" reserve is your hedge against forecast error. + +**Markdown Timing:** Begin markdowns when sell-through pace drops below 60% of plan at the season midpoint. Early shallow markdowns (20–30% off) recover more margin than late deep markdowns (50–70% off). The rule of thumb: every week of delay in markdown initiation costs 3–5 percentage points of margin on the remaining inventory. + +**Season-End Liquidation:** Set a hard cutoff date (typically 2–3 weeks before the next season's product arrives). Everything remaining at cutoff goes to outlet, liquidator, or donation. Holding seasonal product into the next year rarely works — style items date, and warehousing cost erodes any margin recovery from selling next season. + +## Decision Frameworks + +### Forecast Method Selection by Demand Pattern + +| Demand Pattern | Primary Method | Fallback Method | Review Trigger | +| ----------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------- | +| Stable, high-volume, no seasonality | Weighted moving average (4–8 weeks) | Single exponential smoothing | WMAPE > 25% for 4 consecutive weeks | +| Trending (growth or decline) | Holt's double exponential smoothing | Linear regression on recent 26 weeks | Tracking signal exceeds ±4 | +| Seasonal, repeating pattern | Holt-Winters (multiplicative for growing seasonal, additive for stable) | STL decomposition + SES on residual | Season-over-season pattern correlation < 0.7 | +| Intermittent / lumpy (>30% zero-demand periods) | Croston's method or SBA (Syntetos-Boylan Approximation) | Bootstrap simulation on demand intervals | Mean inter-demand interval shifts by >30% | +| Promotion-driven | Causal regression (baseline + promo lift layer) | Analogous item lift + baseline | Post-promo actuals deviate >40% from forecast | +| New product (0–12 weeks history) | Analogous item profile with lifecycle curve | Category average with decay toward actual | Own-data WMAPE stabilizes below analogous-based WMAPE | +| Event-driven (weather, local events) | Regression with external regressors | Manual override with documented rationale | | + +### Safety Stock Service Level Selection + +| Segment | Target Service Level | Z-Score | Rationale | +| ------------------------------------- | -------------------- | --------- | -------------------------------------------------------------------------------------------- | +| AX (high-value, predictable) | 97.5% | 1.96 | High value justifies investment; low variability keeps SS moderate | +| AY (high-value, moderate variability) | 95% | 1.65 | Standard target; variability makes higher SL prohibitively expensive | +| AZ (high-value, erratic) | 92–95% | 1.41–1.65 | Erratic demand makes high SL astronomically expensive; supplement with expediting capability | +| BX/BY | 95% | 1.65 | Standard target | +| BZ | 90% | 1.28 | Accept some stockout risk on mid-tier erratic items | +| CX/CY | 90–92% | 1.28–1.41 | Low value doesn't justify high SS investment | +| CZ | 85% | 1.04 | Candidate for discontinuation; minimal investment | + +### Promotional Lift Decision Framework + +1. **Is there historical lift data for this SKU-promo type combination?** → Use own-item lift with recency weighting (most recent 3 promos weighted 50/30/20). +2. **No own-item data but same category has been promoted?** → Use analogous item lift adjusted for price point and brand tier. +3. **Brand-new category or promo type?** → Use conservative category-average lift discounted 20%. Build in a wider safety stock buffer for the promo period. +4. **Cross-promoted with another category?** → Model the traffic driver separately from the cross-promo beneficiary. Apply cross-elasticity coefficient if available; default 0.15 lift for cross-category halo. +5. **Always model the post-promo dip.** Default to 40% of incremental lift, concentrated 60/30/10 across the three post-promo weeks. + +### Markdown Timing Decision + +| Sell-Through at Season Midpoint | Action | Expected Margin Recovery | +| ------------------------------- | ------------------------------------------------------------------------------------ | ------------------------- | +| ≥ 80% of plan | Hold price. Reorder cautiously if weeks of supply < 3. | Full margin | +| 60–79% of plan | Take 20–25% markdown. No reorder. | 70–80% of original margin | +| 40–59% of plan | Take 30–40% markdown immediately. Cancel any open POs. | 50–65% of original margin | +| < 40% of plan | Take 50%+ markdown. Explore liquidation channels. Flag buying error for post-mortem. | 30–45% of original margin | + +### Slow-Mover Kill Decision + +Evaluate quarterly. Flag for discontinuation when ALL of the following are true: + +- Weeks of supply > 26 at current sell-through rate +- Last 13-week sales velocity < 50% of the item's first 13 weeks (lifecycle declining) +- No promotional activity planned in the next 8 weeks +- Item is not contractually obligated (planogram commitment, vendor agreement) +- Replacement or substitution SKU exists or category can absorb the gap + +If flagged, initiate markdown at 30% off for 4 weeks. If still not moving, escalate to 50% off or liquidation. Set a hard exit date 8 weeks from first markdown. Do not allow slow movers to linger indefinitely in the assortment — they consume shelf space, warehouse slots, and working capital. + +## Key Edge Cases + +Brief summaries here. Full analysis in [edge-cases.md](references/edge-cases.md). + +1. **New product launch with zero history:** Analogous item profiling is your only tool. Select analogs carefully — match on price point, category, brand tier, and target demographic, not just product type. Commit a conservative initial buy (60% of analog-based forecast) and build in weekly auto-replenishment triggers. + +2. **Viral social media spike:** Demand jumps 500–2,000% with no warning. Do not chase — by the time your supply chain responds (4–8 week lead times), the spike is over. Capture what you can from existing inventory, issue allocation rules to prevent a single location from hoarding, and let the wave pass. Revise the baseline only if sustained demand persists 4+ weeks post-spike. + +3. **Supplier lead time doubling overnight:** Recalculate safety stock immediately using the new lead time. If SS doubles, you likely cannot fill the gap from current inventory. Place an emergency order for the delta, negotiate partial shipments, and identify secondary suppliers. Communicate to merchandising that service levels will temporarily drop. + +4. **Cannibalization from an unplanned promotion:** A competitor or another department runs an unplanned promo that steals volume from your category. Your forecast will over-project. Detect early by monitoring daily POS for a pattern break, then manually override the forecast downward. Defer incoming orders if possible. + +5. **Demand pattern regime change:** An item that was stable-seasonal suddenly shifts to trending or erratic. Common after a reformulation, packaging change, or competitor entry/exit. The old model will fail silently. Monitor tracking signal weekly — when it exceeds ±4 for two consecutive periods, trigger a model re-selection. + +6. **Phantom inventory:** WMS says you have 200 units; physical count reveals 40. Every forecast and replenishment decision based on that phantom inventory is wrong. Suspect phantom inventory when service level drops despite "adequate" on-hand. Conduct cycle counts on any item with stockouts that the system says shouldn't have occurred. + +7. **Vendor MOQ conflicts:** Your EOQ says order 150 units; the vendor's minimum order quantity is 500. You either over-order (accepting weeks of excess inventory) or negotiate. Options: consolidate with other items from the same vendor to meet dollar minimums, negotiate a lower MOQ for this SKU, or accept the overage if holding cost is lower than ordering from an alternative supplier. + +8. **Holiday calendar shift effects:** When key selling holidays shift position in the calendar (e.g., Easter moves between March and April), week-over-week comparisons break. Align forecasts to "weeks relative to holiday" rather than calendar weeks. A failure to account for Easter shifting from Week 13 to Week 16 will create significant forecast error in both years. + +## Communication Patterns + +### Tone Calibration + +- **Vendor routine reorder:** Transactional, brief, PO-reference-driven. "PO #XXXX for delivery week of MM/DD per our agreed schedule." +- **Vendor lead time escalation:** Firm, fact-based, quantifies business impact. "Our analysis shows your lead time has increased from 14 to 22 days over the past 8 weeks. This has resulted in X stockout events. We need a corrective plan by [date]." +- **Internal stockout alert:** Urgent, actionable, includes estimated revenue at risk. Lead with the customer impact, not the inventory metric. "SKU X will stock out at 12 locations by Thursday. Estimated lost sales: $XX,000. Recommended action: [expedite/reallocate/substitute]." +- **Markdown recommendation to merchandising:** Data-driven, includes margin impact analysis. Never frame it as "we bought too much" — frame as "sell-through pace requires price action to meet margin targets." +- **Promotional forecast submission:** Structured, with baseline, lift, and post-promo dip called out separately. Include assumptions and confidence range. "Baseline: 500 units/week. Promotional lift estimate: 180% (900 incremental). Post-promo dip: −35% for 2 weeks. Confidence: ±25%." +- **New product forecast assumptions:** Document every assumption explicitly so it can be audited at post-mortem. "Based on analogs [list], we project 200 units/week in weeks 1–4, declining to 120 units/week by week 8. Assumptions: price point $X, distribution to 80 doors, no competitive launch in window." + +Brief templates above. Full versions with variables in [communication-templates.md](references/communication-templates.md). + +## Escalation Protocols + +### Automatic Escalation Triggers + +| Trigger | Action | Timeline | +| ----------------------------------------------------- | ------------------------------------------------------ | -------------------------- | +| Projected stockout on A-item within 7 days | Alert demand planning manager + category merchant | Within 4 hours | +| Vendor confirms lead time increase > 25% | Notify supply chain director; recalculate all open POs | Within 1 business day | +| Promotional forecast miss > 40% (over or under) | Post-promo debrief with merchandising and vendor | Within 1 week of promo end | +| Excess inventory > 26 weeks of supply on any A/B item | Markdown recommendation to merchandising VP | Within 1 week of detection | +| Forecast bias exceeds ±10% for 4 consecutive weeks | Model review and re-parameterization | Within 2 weeks | +| New product sell-through < 40% of plan after 4 weeks | Assortment review with merchandising | Within 1 week | +| Service level drops below 90% for any category | Root cause analysis and corrective plan | Within 48 hours | + +### Escalation Chain + +Level 1 (Demand Planner) → Level 2 (Planning Manager, 24 hours) → Level 3 (Director of Supply Chain Planning, 48 hours) → Level 4 (VP Supply Chain, 72+ hours or any A-item stockout at enterprise customer) + +## Performance Indicators + +Track weekly and trend monthly: + +| Metric | Target | Red Flag | +| ----------------------------------------------- | ------------ | ------------------- | +| WMAPE (weighted mean absolute percentage error) | < 25% | > 35% | +| Forecast bias | ±5% | > ±10% for 4+ weeks | +| In-stock rate (A-items) | > 97% | < 94% | +| In-stock rate (all items) | > 95% | < 92% | +| Weeks of supply (aggregate) | 4–8 weeks | > 12 or < 3 | +| Excess inventory (>26 weeks supply) | < 5% of SKUs | > 10% of SKUs | +| Dead stock (zero sales, 13+ weeks) | < 2% of SKUs | > 5% of SKUs | +| Purchase order fill rate from vendors | > 95% | < 90% | +| Promotional forecast accuracy (WMAPE) | < 35% | > 50% | + +## Additional Resources + +- For detailed decision frameworks, optimization models, and method selection trees, see [decision-frameworks.md](references/decision-frameworks.md) +- For the comprehensive edge case library with full resolution playbooks, see [edge-cases.md](references/edge-cases.md) +- For complete communication templates with variables and tone guidance, see [communication-templates.md](references/communication-templates.md) + +## When to Use + +Use this skill when you need to **forecast demand and shape inventory policy across SKUs, stores, and vendors**: + +- Selecting and tuning forecasting methods, safety stock policies, and reorder logic for different demand patterns. +- Planning promotions, seasonal transitions, markdowns, and end‑of‑life strategies while balancing service, cash, and margin. +- Investigating chronic stockouts, excess inventory, or forecast bias and redesigning the planning process with clearer decision frameworks. diff --git a/web-app/public/skills/inventory-demand-planning/references/communication-templates.md b/web-app/public/skills/inventory-demand-planning/references/communication-templates.md new file mode 100644 index 00000000..eea6c365 --- /dev/null +++ b/web-app/public/skills/inventory-demand-planning/references/communication-templates.md @@ -0,0 +1,566 @@ +# Communication Templates — Inventory Demand Planning + +> **Reference Type:** Tier 3 — Load on demand when composing or reviewing demand planning communications. +> +> **Usage:** Each template includes variable placeholders in `{{double_braces}}` for direct substitution. Templates are organized by audience and purpose. Select the template matching your scenario, substitute variables, review tone guidance, and send. + +--- + +## Table of Contents + +1. [Vendor Replenishment Order](#1-vendor-replenishment-order) +2. [Vendor Lead Time Escalation](#2-vendor-lead-time-escalation) +3. [Internal Stockout Alert](#3-internal-stockout-alert) +4. [Markdown Recommendation to Merchandising](#4-markdown-recommendation-to-merchandising) +5. [Promotional Forecast Submission](#5-promotional-forecast-submission) +6. [Safety Stock Adjustment Request](#6-safety-stock-adjustment-request) +7. [New Product Forecast Assumptions](#7-new-product-forecast-assumptions) +8. [Excess Inventory Liquidation Plan](#8-excess-inventory-liquidation-plan) + +--- + +## Variable Reference + +Common variables used across templates: + +| Variable | Description | Example | +|---|---|---| +| `{{po_number}}` | Purchase order number | `PO-2025-08843` | +| `{{sku}}` | SKU or item number | `SKU-44281` | +| `{{sku_description}}` | Product description | `Organic Olive Oil 16oz` | +| `{{vendor_name}}` | Vendor company name | `Mediterranean Imports LLC` | +| `{{vendor_contact}}` | Vendor contact name | `Marco Bellini` | +| `{{vendor_contact_email}}` | Vendor contact email | `m.bellini@medimports.com` | +| `{{our_contact_name}}` | Our planner name | `Sarah Kim` | +| `{{our_contact_title}}` | Our planner title | `Senior Demand Planner` | +| `{{our_contact_email}}` | Our planner email | `s.kim@retailco.com` | +| `{{our_contact_phone}}` | Our planner phone | `(404) 555-0192` | +| `{{our_company}}` | Our company name | `RetailCo` | +| `{{dc_location}}` | Distribution center location | `Nashville, TN DC` | +| `{{delivery_date}}` | Requested delivery date | `2025-09-22` | +| `{{order_qty}}` | Order quantity | `1,200 units (100 cases)` | +| `{{current_on_hand}}` | Current on-hand inventory | `840 units` | +| `{{weeks_of_supply}}` | Weeks of supply at current rate | `4.2 weeks` | +| `{{weekly_demand}}` | Average weekly demand | `200 units/week` | +| `{{category}}` | Product category | `Cooking Oils` | +| `{{store_count}}` | Number of affected stores | `85 stores` | +| `{{abc_class}}` | ABC classification | `A-item` | +| `{{service_level_target}}` | Target service level | `97%` | +| `{{current_service_level}}` | Current service level | `91%` | +| `{{revenue_at_risk}}` | Estimated revenue at risk | `$18,400/week` | +| `{{promo_start}}` | Promotion start date | `2025-10-05` | +| `{{promo_end}}` | Promotion end date | `2025-10-18` | +| `{{promo_type}}` | Promotion type | `TPR 25% off + circular feature` | +| `{{baseline_forecast}}` | Baseline forecast | `500 units/week` | +| `{{lift_estimate}}` | Promotional lift estimate | `180% (900 incremental units)` | +| `{{markdown_pct}}` | Markdown percentage | `30%` | +| `{{excess_units}}` | Excess inventory units | `3,200 units` | +| `{{excess_wos}}` | Excess weeks of supply | `18.4 weeks` | + +--- + +## 1. Vendor Replenishment Order + +### When to Use +- Standard replenishment order based on forecast and inventory position. +- No urgency beyond normal lead time expectations. + +### Tone Guidance +Transactional and efficient. The vendor receives dozens of these daily. Be clear, reference the PO, specify quantities, delivery date, and delivery location. No need for pleasantries beyond professional courtesy. + +### What NOT to Say +- Do not include forecast data or inventory levels in routine POs — this is proprietary information. +- Do not request lead time changes or raise performance issues in a PO communication. + +### Template + +**Subject:** `PO {{po_number}} — {{vendor_name}} — Delivery {{delivery_date}}` + +--- + +{{vendor_contact}}, + +Please find below our purchase order for delivery to {{dc_location}}. + +**PO Number:** {{po_number}} +**Requested Delivery Date:** {{delivery_date}} +**Ship-To:** {{dc_location}} + +| SKU | Description | Qty (units) | Qty (cases) | Unit Cost | Line Total | +|---|---|---|---|---|---| +| {{sku}} | {{sku_description}} | {{order_qty}} | {{cases}} | {{unit_cost}} | {{line_total}} | + +**Order Total:** {{order_total}} + +Please confirm receipt and expected ship date within 2 business days. + +If any items are unavailable or quantities will be shorted, notify us immediately at {{our_contact_email}} so we can adjust our planning. + +Regards, +{{our_contact_name}} +{{our_contact_title}} | {{our_company}} +{{our_contact_email}} | {{our_contact_phone}} + +--- + +## 2. Vendor Lead Time Escalation + +### When to Use +- Vendor's actual lead times have exceeded the stated/contracted lead time by >20% for 3+ consecutive orders. +- Lead time variability is causing stockouts or excessive safety stock costs. +- You need a formal escalation before involving procurement or vendor management. + +### Tone Guidance +Firm and data-driven. You are not complaining — you are presenting evidence and requesting a corrective action plan. Lead with the impact to your business, not the vendor's failure. Offer collaboration: you want to solve this together, but you need a commitment. + +### What NOT to Say +- Do not threaten to switch vendors in this communication (that's a procurement conversation). +- Do not speculate on the cause of the lead time issue — let the vendor explain. +- Do not use vague language like "often late" — provide specific PO numbers, dates, and deviations. + +### Template + +**Subject:** `Lead Time Performance Review — {{vendor_name}} — Action Required by {{deadline_date}}` + +--- + +{{vendor_contact}}, + +I'm writing to address a consistent lead time issue that is impacting our inventory planning for your product line. + +**Summary of the Problem:** + +Over the past {{time_period}}, we have observed the following lead time performance on our orders: + +| PO Number | Order Date | Stated Lead Time | Actual Lead Time | Deviation | +|---|---|---|---|---| +| {{po_1}} | {{date_1}} | {{stated_lt}} days | {{actual_lt_1}} days | +{{dev_1}} days | +| {{po_2}} | {{date_2}} | {{stated_lt}} days | {{actual_lt_2}} days | +{{dev_2}} days | +| {{po_3}} | {{date_3}} | {{stated_lt}} days | {{actual_lt_3}} days | +{{dev_3}} days | + +**Average stated lead time:** {{stated_lt}} days +**Average actual lead time:** {{actual_lt_avg}} days (+{{pct_increase}}%) +**Lead time coefficient of variation:** {{lt_cv}} + +**Impact to Our Business:** + +This lead time increase has required us to: +- Increase safety stock by {{ss_increase_pct}}%, tying up an additional ${{ss_cost_increase}} in working capital +- Experience {{stockout_count}} stockout events on {{sku_description}} in the past {{time_period}}, with estimated lost sales of ${{lost_sales}} +- Expedite {{expedite_count}} orders at an additional cost of ${{expedite_cost}} + +**What We Need:** + +1. A written explanation of the root cause of the lead time increase by {{deadline_date}}. +2. A corrective action plan with a committed timeline to return to the stated {{stated_lt}}-day lead time. +3. If the lead time increase is permanent, we need an updated lead time commitment so we can recalibrate our planning parameters. + +We value our partnership with {{vendor_name}} and want to resolve this collaboratively. I'm available to discuss on a call at your convenience this week. + +Regards, +{{our_contact_name}} +{{our_contact_title}} | {{our_company}} +{{our_contact_email}} | {{our_contact_phone}} + +--- + +## 3. Internal Stockout Alert + +### When to Use +- Projected stockout on an A or B-item within 7 days based on current inventory position and demand forecast. +- Actual stockout occurring at 3+ locations. +- Any stockout where revenue at risk exceeds $10,000/week. + +### Tone Guidance +Urgent, concise, action-oriented. The audience is internal (planning manager, category merchant, supply chain director). Lead with the impact, follow with the facts, close with the recommended action. This is not a post-mortem — it's a call to action. + +### What NOT to Say +- Do not assign blame in the alert (e.g., "because the buyer didn't order enough"). That's for the post-mortem. +- Do not present multiple options without a recommendation — decision-makers need a clear ask. + +### Template + +**Subject:** `🔴 STOCKOUT ALERT — {{sku_description}} — {{store_count}} locations at risk` + +--- + +**Attention:** {{recipient_names}} + +**Item:** {{sku}} — {{sku_description}} +**ABC Class:** {{abc_class}} +**Current Status:** {{current_status}} (e.g., "Out of stock at 8 locations; projected stockout at 22 additional locations by {{stockout_date}}") + +**Inventory Position:** +- DC On-Hand: {{dc_on_hand}} units +- Store On-Hand (aggregate): {{store_on_hand}} units +- On-Order: {{on_order}} units (ETA: {{on_order_eta}}) +- Weekly Demand: {{weekly_demand}} +- Weeks of Supply (current): {{weeks_of_supply}} + +**Revenue at Risk:** ${{revenue_at_risk}}/week across {{store_count}} locations + +**Root Cause:** {{root_cause}} (e.g., "Vendor shipment delayed by 10 days; demand running 20% above forecast due to competitive market exit") + +**Recommended Actions:** + +1. **Immediate:** {{action_1}} (e.g., "Reallocate 400 units from low-velocity stores to stockout locations — list attached") +2. **Short-term:** {{action_2}} (e.g., "Expedite PO {{po_number}} — vendor confirmed can ship 800 units by {{expedite_date}} at ${{expedite_cost}} additional freight") +3. **If above fails:** {{action_3}} (e.g., "Substitute with {{alt_sku}} — similar product, available in DC, can ship to affected stores within 48 hours") + +**Decision needed by:** {{decision_deadline}} + +Please reply or call me directly to confirm action. + +{{our_contact_name}} +{{our_contact_title}} | {{our_contact_phone}} + +--- + +## 4. Markdown Recommendation to Merchandising + +### When to Use +- SKU or category has excess inventory exceeding 12 weeks of supply with no promotional activity planned. +- Seasonal product with sell-through below 60% at season midpoint. +- Slow-mover kill decision has been triggered. + +### Tone Guidance +Data-driven and collaborative. You are presenting a financial analysis, not demanding a price change. Merchandising owns pricing decisions — your job is to provide the inventory data and margin impact analysis to inform their decision. Frame recommendations as margin recovery, not "we bought too much." + +### What NOT to Say +- Do not say "we overbought" or "the forecast was wrong" — frame as "sell-through pace requires price action." +- Do not propose a specific retail price — propose a markdown depth (% off) and let merchandising set the price. + +### Template + +**Subject:** `Markdown Recommendation — {{sku_description}} — {{excess_units}} units excess` + +--- + +**To:** {{merchandising_contact}} +**From:** {{our_contact_name}}, {{our_contact_title}} +**Date:** {{date}} + +**Summary:** +{{sku_description}} ({{sku}}) is carrying {{excess_units}} units of excess inventory representing {{excess_wos}} weeks of supply at current sell-through rates. Based on our analysis, a markdown is recommended to recover margin and free working capital before the inventory ages further. + +**Current Inventory Position:** + +| Metric | Value | +|---|---| +| On-Hand (DC + Stores) | {{total_on_hand}} units | +| Weekly Demand (trailing 4-week avg) | {{weekly_demand}} | +| Weeks of Supply | {{excess_wos}} | +| Seasonal Window Remaining | {{season_weeks_remaining}} weeks | +| Current Sell-Through vs. Plan | {{sell_through_pct}}% | + +**Financial Analysis:** + +| Scenario | Markdown Depth | Projected Velocity | Weeks to Clear | Margin Recovery | +|---|---|---|---|---| +| No action | 0% | {{current_velocity}} units/week | {{wos_no_action}} weeks | {{margin_no_action}} | +| Option A | {{md_depth_a}}% | {{velocity_a}} units/week | {{wos_a}} weeks | {{margin_a}} | +| Option B | {{md_depth_b}}% | {{velocity_b}} units/week | {{wos_b}} weeks | {{margin_b}} | +| Liquidation | Cost recovery | Immediate | 1–2 weeks | {{margin_liquidation}} | + +**Recommendation:** Option {{recommended_option}} ({{md_depth_recommended}}% markdown) offers the best margin recovery of {{margin_recommended}} while clearing inventory within {{wos_recommended}} weeks. + +**Holding Cost of Inaction:** Carrying this excess for another {{delay_weeks}} weeks costs approximately ${{holding_cost}} in inventory carrying costs and risks additional obsolescence if the product ages or a seasonal window closes. + +**Next Steps:** +If approved, we can execute the markdown effective {{proposed_start_date}} and monitor weekly sell-through against the projected velocity. + +Happy to discuss the analysis in detail. + +{{our_contact_name}} +{{our_contact_title}} | {{our_contact_email}} | {{our_contact_phone}} + +--- + +## 5. Promotional Forecast Submission + +### When to Use +- Submitting the demand forecast for a planned promotion to supply chain, merchandising, and vendor partners. +- Required 6–8 weeks before promotion start date to allow for procurement. + +### Tone Guidance +Structured and transparent. This document is the "source of truth" for promotional inventory planning. Include all assumptions, the baseline, the lift estimate, and the post-promo dip so that all stakeholders can challenge or validate the numbers before POs are placed. + +### What NOT to Say +- Do not present a single point estimate without a confidence range — this gives false precision. +- Do not omit the post-promo dip — it's as important as the lift. + +### Template + +**Subject:** `Promotional Forecast — {{sku_description}} — {{promo_start}} to {{promo_end}}` + +--- + +**To:** Supply Chain Planning, Category Merchandising, {{vendor_name}} (if applicable) +**From:** {{our_contact_name}}, {{our_contact_title}} +**Date:** {{date}} +**Promotion:** {{promo_description}} + +--- + +### Promotion Details + +| Field | Value | +|---|---| +| SKU | {{sku}} — {{sku_description}} | +| Promotion Period | {{promo_start}} — {{promo_end}} ({{promo_weeks}} weeks) | +| Promotion Type | {{promo_type}} | +| Promotional Retail Price | ${{promo_price}} (regular: ${{reg_price}}, {{discount_pct}}% off) | +| Media Support | {{media_support}} (e.g., "Circular page 3 + endcap display") | +| Stores Participating | {{store_count}} of {{total_stores}} | + +### Forecast + +| Period | Baseline Forecast | Lift Estimate | Total Forecast | Confidence Range (±) | +|---|---|---|---|---| +| Pre-promo (week before) | {{baseline}} units | — | {{baseline}} units | — | +| Promo Week 1 | {{baseline}} | +{{lift_wk1}}% ({{lift_units_1}} units) | {{total_wk1}} units | ±{{conf_1}}% | +| Promo Week 2 | {{baseline}} | +{{lift_wk2}}% ({{lift_units_2}} units) | {{total_wk2}} units | ±{{conf_2}}% | +| Post-Promo Week 1 | {{baseline}} | −{{dip_wk1}}% ({{dip_units_1}} units) | {{post_1}} units | ±{{conf_post_1}}% | +| Post-Promo Week 2 | {{baseline}} | −{{dip_wk2}}% ({{dip_units_2}} units) | {{post_2}} units | ±{{conf_post_2}}% | +| Recovery (Week 3+) | {{baseline}} | — | {{baseline}} units | — | + +**Total Promotional Period Demand:** {{total_promo_demand}} units +**Total Incremental Demand (above baseline):** {{incremental_demand}} units + +### Assumptions and Methodology + +1. **Baseline:** {{baseline_method}} (e.g., "Holt-Winters model fitted on de-promoted trailing 52-week data") +2. **Lift source:** {{lift_source}} (e.g., "Average of 3 most recent comparable promotions on this SKU, weighted 50/30/20 by recency") +3. **Cannibalization:** Estimated {{cannibalization_pct}}% cannibalization from {{cannibalized_sku}}, reducing net category lift to {{net_category_lift}}% +4. **Post-promo dip:** Based on {{dip_source}} (e.g., "Product type: shelf-stable pantry; historical dip factor 45% of incremental lift") +5. **Confidence range:** Based on historical promotional forecast accuracy for this category (trailing 12-month promo WMAPE: {{promo_wmape}}%) + +### Inventory Requirements + +| Item | Quantity | +|---|---| +| Current on-hand (DC + pipeline) | {{current_inventory}} units | +| Total demand through post-promo recovery | {{total_demand}} units | +| Gap to fill | {{gap_units}} units | +| Recommended PO quantity | {{po_qty}} units ({{cases}} cases) | +| PO must arrive by | {{po_arrive_by}} ({{lead_time_buffer}} days before promo start) | + +### Risks + +- **Upside risk:** If lift exceeds {{upside_lift}}%, we may stock out in week 2 of the promotion. Contingency: {{contingency_up}}. +- **Downside risk:** If lift is below {{downside_lift}}%, we will carry {{excess_if_low}} excess units post-promo, requiring {{excess_weeks}} additional weeks to sell through. + +{{our_contact_name}} +{{our_contact_title}} | {{our_contact_email}} + +--- + +## 6. Safety Stock Adjustment Request + +### When to Use +- Demand variability or lead time variability has changed, requiring a safety stock parameter update. +- Service level targets have been revised (up or down) for a segment or individual SKU. +- Post a supply disruption or regime change that permanently alters risk parameters. + +### Tone Guidance +Analytical and justified. Every safety stock change is an inventory investment change. Present the before/after calculation, the reason for the change, and the financial impact (incremental holding cost or reduced stockout risk). + +### Template + +**Subject:** `Safety Stock Adjustment — {{sku_description}} — {{adjustment_direction}} by {{adjustment_pct}}%` + +--- + +**To:** {{planning_manager}}, {{finance_contact}} (if material) +**From:** {{our_contact_name}}, {{our_contact_title}} +**Date:** {{date}} + +**Item:** {{sku}} — {{sku_description}} ({{abc_class}}) + +### Reason for Adjustment + +{{reason}} (e.g., "Vendor lead time has increased from 14 days to 28 days effective 2025-09-01. Lead time variability has also increased, with CV rising from 0.12 to 0.31.") + +### Calculation + +| Parameter | Previous | Updated | Change | +|---|---|---|---| +| Average weekly demand | {{prev_demand}} units | {{new_demand}} units | {{demand_change}} | +| Demand std. deviation (σ_d) | {{prev_sigma_d}} units | {{new_sigma_d}} units | {{sigma_d_change}} | +| Lead time (weeks) | {{prev_lt}} weeks | {{new_lt}} weeks | {{lt_change}} | +| Lead time std. deviation (σ_LT) | {{prev_sigma_lt}} weeks | {{new_sigma_lt}} weeks | {{sigma_lt_change}} | +| Service level target | {{service_level}} | {{service_level}} | No change | +| Z-score | {{z_score}} | {{z_score}} | No change | +| **Safety stock (units)** | **{{prev_ss}}** | **{{new_ss}}** | **+{{ss_delta}} units** | + +### Financial Impact + +- Incremental inventory investment: {{ss_delta}} units × ${{unit_cost}} = ${{incremental_investment}} +- Annual holding cost increase: ${{incremental_investment}} × {{holding_cost_pct}}% = ${{annual_holding_increase}} +- Expected stockout reduction: from {{prev_stockout_events}} events/year to {{new_stockout_events}} events/year +- Estimated recovered revenue: ${{recovered_revenue}}/year + +**Net impact:** {{net_assessment}} (e.g., "The $2,400 annual holding cost increase is justified by the $18,000 in projected recovered revenue from reduced stockouts.") + +### Approval Requested By + +{{deadline}} — needed before the next replenishment cycle to take effect. + +{{our_contact_name}} +{{our_contact_title}} | {{our_contact_email}} + +--- + +## 7. New Product Forecast Assumptions + +### When to Use +- Documenting the forecast basis for a new product launch with < 8 weeks of own-history data. +- Required at the pre-launch planning meeting and updated at the 4-week and 8-week checkpoints. + +### Tone Guidance +Transparent and falsifiable. The purpose of this document is to make every assumption explicit so that the post-mortem can identify where the forecast diverged from reality. Do not hedge with vague language — state the assumptions clearly so they can be validated or disproved. + +### Template + +**Subject:** `New Product Forecast Assumptions — {{sku_description}} — Launch {{launch_date}}` + +--- + +**To:** Category Merchandising, Supply Chain Planning, Finance +**From:** {{our_contact_name}}, {{our_contact_title}} +**Date:** {{date}} + +### Product Details + +| Field | Value | +|---|---| +| SKU | {{sku}} — {{sku_description}} | +| Category | {{category}} / {{subcategory}} | +| Retail Price | ${{retail_price}} | +| Unit Cost | ${{unit_cost}} | +| Gross Margin | {{gross_margin_pct}}% | +| Launch Date | {{launch_date}} | +| Initial Distribution | {{store_count}} stores ({{pct_of_chain}}% of chain) | +| Vendor | {{vendor_name}} | +| Lead Time | {{lead_time}} weeks | +| Shelf Life | {{shelf_life}} | + +### Analogous Items Selected + +| Analog SKU | Description | Similarity Score | Launch Velocity (wks 1–13) | Current Velocity | +|---|---|---|---|---| +| {{analog_1_sku}} | {{analog_1_desc}} | {{analog_1_score}}/5.0 | {{analog_1_launch_vel}} units/store/week | {{analog_1_current_vel}} | +| {{analog_2_sku}} | {{analog_2_desc}} | {{analog_2_score}}/5.0 | {{analog_2_launch_vel}} units/store/week | {{analog_2_current_vel}} | +| {{analog_3_sku}} | {{analog_3_desc}} | {{analog_3_score}}/5.0 | {{analog_3_launch_vel}} units/store/week | {{analog_3_current_vel}} | + +**Weighted average analog velocity (weeks 1–13):** {{weighted_avg_vel}} units/store/week + +### Forecast by Phase + +| Phase | Weeks | Velocity (units/store/wk) | Total Weekly Demand ({{store_count}} stores) | Confidence Band | +|---|---|---|---|---| +| Introduction | 1–4 | {{intro_vel}} | {{intro_weekly}} units | ±{{intro_conf}}% | +| Growth | 5–8 | {{growth_vel}} | {{growth_weekly}} units | ±{{growth_conf}}% | +| Stabilization | 9–13 | {{stable_vel}} | {{stable_weekly}} units | ±{{stable_conf}}% | + +### Key Assumptions + +1. {{assumption_1}} (e.g., "Product will receive endcap display in all {{store_count}} stores for weeks 1–4") +2. {{assumption_2}} (e.g., "No direct competitor launch in the same subcategory during the launch window") +3. {{assumption_3}} (e.g., "Price point is within the category's high-volume range ($3–$5)") +4. {{assumption_4}} (e.g., "Vendor will maintain {{lead_time}}-week lead time for reorders") + +### Initial Buy and Reorder Plan + +| Component | Quantity | Timing | +|---|---|---| +| Initial buy | {{initial_buy}} units | PO placed {{initial_po_date}} | +| Safety stock | {{initial_ss}} units (analog-based, 30% uncertainty premium) | Included in initial buy | +| First reorder trigger | If week 1–2 velocity > {{reorder_trigger}} units/store/week | Auto-trigger PO | +| Reserve for reorder | {{reserve_units}} units (held at vendor or allocated in budget) | Weeks 3–5 | + +### Monitoring Plan + +| Checkpoint | Date | Metric | Action if Below Plan | Action if Above Plan | +|---|---|---|---|---| +| Week 2 | {{wk2_date}} | Velocity vs. {{intro_vel}} target | Review display compliance; consider early promo | Place reorder for 50% of reserve | +| Week 4 | {{wk4_date}} | Sell-through vs. initial buy | Flag for promotional support | Place reorder for remaining reserve | +| Week 8 | {{wk8_date}} | Velocity trend (growing/declining/stable) | Initiate slow-mover review if declining for 4 wks | Upgrade to standard forecasting method | + +{{our_contact_name}} +{{our_contact_title}} | {{our_contact_email}} + +--- + +## 8. Excess Inventory Liquidation Plan + +### When to Use +- SKU has been classified as dead stock (zero sales for 13+ weeks) or critical excess (>26 weeks of supply). +- Seasonal product with unsold inventory after the markdown selling window. +- Discontinued product with remaining inventory after final markdown. + +### Tone Guidance +Pragmatic and action-oriented. The liquidation plan is an acknowledgment that margin recovery is limited and the priority has shifted to cash recovery and warehouse space liberation. Present the options dispassionately — the goal is to make the best of a bad situation, not to relitigate the buying decision. + +### Template + +**Subject:** `Excess Inventory Liquidation Plan — {{sku_description}} — {{excess_units}} units` + +--- + +**To:** {{merchandising_contact}}, {{finance_contact}}, {{warehouse_contact}} +**From:** {{our_contact_name}}, {{our_contact_title}} +**Date:** {{date}} + +### Inventory Summary + +| Metric | Value | +|---|---| +| SKU | {{sku}} — {{sku_description}} | +| Current On-Hand | {{excess_units}} units | +| Original Cost | ${{unit_cost}} per unit (${{total_cost}} total) | +| Current Retail | ${{current_retail}} (after markdowns) | +| Weekly Demand (trailing 8 weeks) | {{weekly_demand}} units | +| Weeks of Supply | {{excess_wos}} | +| Reason for Excess | {{reason}} | + +### Liquidation Options Analysis + +| Option | Recovery per Unit | Total Recovery | Timeline | Pros | Cons | +|---|---|---|---|---|---| +| **A: Deeper markdown ({{md_depth}}% off)** | ${{recovery_a}} | ${{total_a}} | {{timeline_a}} weeks | Retains customer; recovers shelf space gradually | Margin erosion; may not clear | +| **B: Liquidation channel** | ${{recovery_b}} | ${{total_b}} | {{timeline_b}} weeks | Immediate clearance; frees space | Very low recovery; no brand control | +| **C: Donation (tax write-off)** | ${{recovery_c}} (tax benefit) | ${{total_c}} | {{timeline_c}} weeks | Goodwill; tax benefit; immediate space recovery | No cash recovery | +| **D: Destroy / write-off** | $0 | $0 | Immediate | Frees space immediately; clean books | Total loss; disposal cost of ${{disposal_cost}} | + +### Recommendation + +Option {{recommended_option}} is recommended based on the following rationale: + +{{recommendation_rationale}} (e.g., "Option B (liquidation) recovers $3,200 compared to Option A's $4,100 — but Option A requires 8 more weeks of shelf space that has a higher-value alternative use. The opportunity cost of holding the shelf space exceeds the $900 margin difference.") + +### Execution Plan + +| Step | Action | Owner | Deadline | +|---|---|---|---| +| 1 | Approve liquidation plan | {{approver}} | {{approval_date}} | +| 2 | Remove from active replenishment | Demand Planning | {{replenishment_stop_date}} | +| 3 | {{action_3}} | {{owner_3}} | {{date_3}} | +| 4 | {{action_4}} | {{owner_4}} | {{date_4}} | +| 5 | Confirm zero on-hand; close SKU in system | Warehouse / IT | {{close_date}} | + +### Financial Summary + +| Line Item | Amount | +|---|---| +| Original inventory investment | ${{total_cost}} | +| Revenue recovered (to date, markdowns) | ${{markdown_revenue}} | +| Projected recovery (this plan) | ${{projected_recovery}} | +| **Total write-down** | **${{total_writedown}}** | + +### Post-Mortem Assignment + +Root cause analysis for this excess is assigned to {{postmortem_owner}} with a due date of {{postmortem_date}}. The analysis should address: Was this a forecast error, a buying decision error, a market change, or a timing issue? What process change would prevent recurrence? + +{{our_contact_name}} +{{our_contact_title}} | {{our_contact_email}} | {{our_contact_phone}} diff --git a/web-app/public/skills/inventory-demand-planning/references/decision-frameworks.md b/web-app/public/skills/inventory-demand-planning/references/decision-frameworks.md new file mode 100644 index 00000000..7d7827cd --- /dev/null +++ b/web-app/public/skills/inventory-demand-planning/references/decision-frameworks.md @@ -0,0 +1,861 @@ +# Decision Frameworks — Inventory Demand Planning + +This reference provides the detailed decision logic, optimization models, method selection +trees, and segmentation methodologies for inventory demand planning at multi-location +retailers. It is loaded on demand when the agent needs to make or recommend nuanced +planning decisions. + +All thresholds, formulas, and cost assumptions reflect US multi-location retail operations +managing hundreds of SKUs across grocery, general merchandise, seasonal, and promotional +categories. + +--- + +## 1. Forecast Method Selection Trees + +### 1.1 Primary Selection Algorithm + +The goal is to match each SKU to the forecasting method that minimizes WMAPE on out-of-time +holdout data. In practice, most organizations cannot afford per-SKU model optimization +across hundreds of items. Instead, classify items into demand pattern archetypes and assign +methods by archetype. + +#### Step 1 — Classify the Demand Pattern + +Compute the following statistics on the most recent 52 weeks of de-promoted demand data +(remove promotional lift periods before computing): + +| Statistic | Formula | Purpose | +|---|---|---| +| **Coefficient of Variation (CV)** | σ_demand / μ_demand | Measures demand variability | +| **Average Demand Interval (ADI)** | Total periods / Number of non-zero demand periods | Measures intermittency | +| **Trend Strength** | R² of linear regression on 26-week trailing demand | Measures directional movement | +| **Seasonal Strength** | Autocorrelation at lag 52 (weekly) or lag 12 (monthly) | Measures repeating seasonal pattern | +| **Zero-Demand Ratio** | Count of zero-demand periods / Total periods | Measures how often demand is absent | + +#### Step 2 — Map to Demand Archetype + +| Archetype | CV | ADI | Trend R² | Seasonal AC | Zero Ratio | Example | +|---|---|---|---|---|---|---| +| **Smooth** | < 0.5 | 1.0–1.1 | < 0.3 | < 0.3 | < 5% | Milk, bread, paper towels | +| **Trending** | < 0.7 | 1.0–1.2 | ≥ 0.3 | < 0.3 | < 10% | Growing brand, declining legacy item | +| **Seasonal** | 0.3–1.0 | 1.0–1.3 | any | ≥ 0.3 | < 15% | Sunscreen, holiday decor, grills | +| **Trending-Seasonal** | 0.4–1.2 | 1.0–1.3 | ≥ 0.3 | ≥ 0.3 | < 15% | Growing seasonal category | +| **Erratic** | ≥ 0.7 | 1.0–1.5 | < 0.3 | < 0.3 | < 30% | Fashion accessories, novelty items | +| **Intermittent** | any | ≥ 1.5 | any | any | ≥ 30% | Spare parts, specialty ingredients | +| **Lumpy** | ≥ 1.0 | ≥ 1.5 | any | any | ≥ 30% | Bulk wholesale items with sporadic orders | + +#### Step 3 — Assign Forecasting Method + +| Archetype | Primary Method | Parameters | Fallback | +|---|---|---|---| +| **Smooth** | Weighted moving average (4–8 week window, recent-weighted) | Weights: 0.4/0.3/0.2/0.1 for 4-week | Single exponential smoothing (α = 0.15–0.25) | +| **Trending** | Holt's double exponential smoothing | α = 0.2–0.4, β = 0.05–0.15 | Linear regression on trailing 26 weeks | +| **Seasonal** | Holt-Winters (additive if stable amplitude, multiplicative if growing amplitude) | α = 0.1–0.3, β = 0.01–0.05, γ = 0.1–0.3, period = 52 weeks | STL decomposition + SES on residual | +| **Trending-Seasonal** | Holt-Winters (multiplicative) | α = 0.2–0.4, β = 0.05–0.15, γ = 0.15–0.3 | X-13ARIMA-SEATS | +| **Erratic** | Damped trend exponential smoothing | α = 0.2–0.4, β = 0.05, φ = 0.8–0.95 | Ensemble of 3 methods (median) | +| **Intermittent** | Croston's method or SBA | α_demand = 0.1–0.2, α_interval = 0.1–0.2 | Bootstrap simulation (1000 draws) | +| **Lumpy** | SBA (Syntetos-Boylan Approximation) | Same as Croston's with bias correction | Aggregated to monthly then disaggregated | + +### 1.2 Model Switching Rules + +Do not switch methods based on a single bad week. Models need time to prove or disprove themselves. + +| Condition | Action | Minimum Observation Period | +|---|---|---| +| WMAPE improves > 10% on holdout vs. current method | Switch to candidate method | 8-week parallel test | +| Tracking signal exceeds ±4 for 2 consecutive periods | Trigger model review; re-estimate parameters first | 2 periods (weeks) | +| Tracking signal exceeds ±6 for 1 period | Immediate model review; likely archetype change | 1 period | +| Demand pattern archetype changes (e.g., smooth → trending) | Re-run selection algorithm from Step 1 | Quarterly archetype reassessment | +| New product transitions from analog-based to own-history | Switch when 12+ weeks of own data available and own-data WMAPE < analog-based | 12 weeks | +| Post-promotion baseline contamination detected | Refit baseline model excluding promo periods | Immediate | + +### 1.3 Parameter Optimization Protocol + +For exponential smoothing methods, optimize parameters using grid search on time-series +cross-validation (rolling origin, 1-step ahead forecast, 26+ origins). + +**Grid search ranges:** + +| Parameter | Range | Step Size | Constraint | +|---|---|---|---| +| α (level) | 0.05–0.50 | 0.05 | — | +| β (trend) | 0.01–0.20 | 0.01 | β ≤ α | +| γ (seasonal) | 0.05–0.40 | 0.05 | — | +| φ (damping) | 0.80–0.98 | 0.02 | Only for damped methods | + +**Optimization metric:** Minimize WMAPE on the holdout origins. If two parameter sets +produce WMAPE within 1 percentage point, prefer the set with lower α (more smoothing) +for stability. + +**Overfitting guard:** If the optimized model produces WMAPE on the holdout that is +>5 percentage points better than on the fitting data, the model is likely overfit. +Increase smoothing (lower α) until the gap narrows to <3 points. + +--- + +## 2. Safety Stock Optimization Models + +### 2.1 Standard Safety Stock (Normal Demand, Fixed Lead Time) + +When demand follows a roughly normal distribution and lead time is consistent: + +``` +SS = Z × σ_d × √(LT) +``` + +Where: +- Z = z-score for the target service level (see lookup table below) +- σ_d = standard deviation of demand per period (use same period as LT) +- LT = lead time in periods + +**Z-Score Lookup:** + +| Service Level | Z-Score | Typical Application | +|---|---|---| +| 85.0% | 1.04 | CZ items — minimal investment | +| 90.0% | 1.28 | C-items, non-critical B-items | +| 92.0% | 1.41 | Mid-range safety net | +| 95.0% | 1.65 | Standard target for A/B items | +| 97.5% | 1.96 | AX items — high value, predictable | +| 99.0% | 2.33 | Critical items — stockout cost vastly exceeds holding | +| 99.5% | 2.58 | Life-safety or contractual obligation items | +| 99.9% | 3.09 | Rarely justified — extreme holding cost | + +### 2.2 Safety Stock with Lead Time Variability + +When vendor lead times are uncertain (CV of lead time > 0.15): + +``` +SS = Z × √(LT_avg × σ_d² + d_avg² × σ_LT²) +``` + +Where: +- LT_avg = average lead time in periods +- σ_LT = standard deviation of lead time in periods +- d_avg = average demand per period + +**Practical note:** Many planners underestimate lead time variability because they +measure "vendor ship date to DC receipt" without accounting for receiving delays, +quality holds, or weekend/holiday dead time. Measure lead time from PO release to +"available to sell" — this is the operationally relevant metric. + +### 2.3 Safety Stock with Review Period + +For periodic review systems (review every R periods): + +``` +SS = Z × σ_d × √(LT + R) +``` + +The review period adds exposure time — between reviews, you cannot react to demand +changes. Weekly review (R=1) on a 2-week lead time item needs safety stock for √3 weeks. +Monthly review (R=4) on the same item needs safety stock for √6 weeks — 41% more. + +### 2.4 Safety Stock for Intermittent Demand + +Normal-distribution formulas fail when demand has many zero periods. Use empirical +(bootstrapped) safety stock instead: + +1. Collect the last 52 periods of demand data (include zeros). +2. Generate 10,000 bootstrap samples of length (LT + R) by random sampling with + replacement from the historical demand. +3. Compute the sum of each bootstrap sample (= simulated demand during lead time + review). +4. The safety stock is the (service level)th percentile of the simulated demand totals + minus the mean simulated demand total. + +**Example:** For 95% service level, safety stock = P95 of bootstrap demand — mean of +bootstrap demand. This captures the skewed, zero-inflated distribution that parametric +formulas miss. + +### 2.5 Safety Stock for New Products (No History) + +When an item has < 8 weeks of own demand history: + +1. Identify 3–5 analogous items matching on: category, price point (±20%), brand tier + (national/private label), pack size, and target demographic. +2. Compute the average σ_d and CV across the analogs. +3. Apply a "new product uncertainty premium" of 1.25× to the analog σ_d. +4. Use the standard formula with the inflated σ_d: `SS = Z × (1.25 × σ_d_analog) × √(LT + R)`. +5. Every 2 weeks, blend own-history σ_d with the analog σ_d. By week 8, use 70% own history + and 30% analog. By week 12, use 100% own history. + +### 2.6 Safety Stock Cost-Optimization + +The naive approach is to set a service level target and compute SS. The sophisticated +approach is to optimize the tradeoff between holding cost and stockout cost: + +``` +Optimal SL = 1 − (H / (H + S × D/Q)) +``` + +Where: +- H = holding cost per unit per period +- S = stockout cost per unit (lost margin + customer goodwill + substitution cost) +- D = demand per period +- Q = order quantity + +For most retailers, stockout cost on A-items is 3–5× the unit margin (including lost +customer visits and substitution effects), which pushes optimal SL to 96–98%. +For C-items, stockout cost is approximately equal to the unit margin, yielding optimal +SL of 88–92%. + +--- + +## 3. Promotional Planning Frameworks + +### 3.1 Promotional Lift Estimation Methodology + +Promotional lift is always computed relative to the baseline forecast (the forecast that +would have been generated without the promotion). Contaminating the baseline with +promotional history is the #1 source of systematic forecast error in retail. + +#### Step 1 — Establish Clean Baseline + +Strip promotional periods from the demand history before fitting the baseline model. +Flag weeks as "promotional" if any of the following were active: +- Temporary price reduction (TPR) > 5% off regular price +- Feature in circular, digital ad, or endcap display +- BOGO or multi-buy offer +- Cross-promotion in another category + +After stripping, interpolate the gaps using the forecast model fitted to non-promotional +periods. This creates a "what would have sold at regular price" baseline. + +#### Step 2 — Compute Historical Lifts + +For each historical promotional event on this SKU: + +``` +Lift Ratio = Actual Promo-Period Sales / Baseline Forecast for Promo Period +``` + +A lift ratio of 2.5 means the promotion drove 2.5× baseline volume (150% incremental). + +Organize lift ratios by promotional mechanism: + +| Mechanism | Typical Lift Range | Key Drivers | +|---|---|---| +| TPR only (5–15% off) | 1.15–1.40 | Depth of discount, category elasticity | +| TPR (15–30% off) | 1.40–2.00 | Deeper discount creates sharper response | +| TPR + display | 1.80–2.50 | Display location (endcap > wing > inline) | +| TPR + circular feature | 2.00–3.00 | Circular reach and placement (front page > interior) | +| TPR + display + circular | 2.50–4.00 | Full support — this is the "A-level" promo | +| BOGO | 2.50–5.00 | Perceived value drives high response but heavy forward-buy | +| Doorbuster / loss leader | 3.00–6.00+ | Traffic driver; lift varies wildly by event | + +#### Step 3 — Apply Lift to Current Forecast + +``` +Promo Forecast = Baseline Forecast × Lift Ratio +``` + +When multiple promotional mechanisms are combined, do NOT multiply individual lifts. +Use the combined-mechanism lift from historical data or the table above. The interaction +effects are sub-additive (display alone = 1.5× and circular alone = 1.8× does not mean +display + circular = 2.7×; it's typically 2.0–2.5×). + +#### Step 4 — Model the Post-Promotion Dip + +``` +Post-Promo Demand = Baseline × (1 − Dip Factor × Decay) +``` + +Default dip factors by product type: + +| Product Type | Dip Factor (% of incremental lift) | Dip Duration | Decay Pattern | +|---|---|---|---| +| **Shelf-stable pantry** | 40–60% | 2–4 weeks | 60/30/10 (Week 1/2/3) | +| **Perishable / refrigerated** | 10–20% | 0–1 week | Immediate recovery | +| **Household consumables** | 30–50% | 2–3 weeks | 50/35/15 | +| **Personal care** | 25–40% | 2–3 weeks | 50/30/20 | +| **Seasonal** | 15–30% | 1–2 weeks | 70/30 | +| **Discretionary / general merch** | 10–25% | 1–2 weeks | 70/30 | + +### 3.2 Cannibalization Estimation + +When SKU A is promoted, substitutable SKU B loses sales. The cannibalization rate is: + +``` +Cannibalization Rate = ΔB_down / ΔA_up +``` + +Where ΔA_up is the incremental lift on A and ΔB_down is the volume loss on B during +the same period. + +**Default estimates when no cross-elasticity data exists:** + +| Substitutability | Cannibalization Rate | Example | +|---|---|---| +| Direct substitute (same brand, different size) | 25–40% | 12-oz promoted, 16-oz loses | +| Close substitute (different brand, same segment) | 15–25% | National brand promoted, private label loses | +| Moderate substitute (same category, different segment) | 5–15% | Premium promoted, value tier affected | +| Weak substitute (adjacent category) | 0–5% | Chips promoted, crackers slightly affected | + +**Important:** Cannibalization is bidirectional across the category. When building the +category-level promotional plan, sum the cannibalization effects across all substitutes +to compute the true category-level lift (which is always less than the item-level lift). + +### 3.3 Forward-Buy and Pantry Loading + +Deep promotions cause customers to purchase ahead of their consumption schedule. +Forward-buy volume is demand pulled from future periods, not incremental category demand. + +**Forward-buy estimation:** + +``` +Forward-Buy Volume = Incremental Lift × Forward-Buy Factor +``` + +| Promotional Depth | Product Shelf Life | Forward-Buy Factor | +|---|---|---| +| 10–20% off | < 2 weeks (perishable) | 0.05–0.10 | +| 10–20% off | 2–12 weeks | 0.10–0.20 | +| 10–20% off | > 12 weeks (shelf-stable) | 0.20–0.35 | +| 20–35% off | < 2 weeks | 0.05–0.15 | +| 20–35% off | 2–12 weeks | 0.20–0.35 | +| 20–35% off | > 12 weeks | 0.35–0.50 | +| 35–50% off | < 2 weeks | 0.10–0.20 | +| 35–50% off | 2–12 weeks | 0.30–0.45 | +| 35–50% off | > 12 weeks | 0.50–0.70 | +| BOGO / > 50% | Any | 0.50–0.80 | + +The forward-buy factor tells you what fraction of the incremental lift came from +pantry loading rather than true consumption increase. This directly feeds the +post-promo dip calculation — the dip is approximately equal to the forward-buy volume +spread over its consumption period. + +### 3.4 Promotional Calendar Planning + +When planning the annual promotional calendar, apply these rules: + +1. **Minimum inter-promotion gap:** 4 weeks between promotions on the same SKU. Shorter + gaps train customers to only buy on deal, eroding brand equity and baseline velocity. +2. **Maximum promotional frequency:** 13 weeks per year (25%) for any single SKU. + Beyond this, the "promotional price" becomes the reference price in consumers' minds. +3. **Seasonal alignment:** Promote seasonal items during the build phase (first 40% of + the season), not during peak or decline. Promoting at peak wastes money on demand + that would have occurred anyway. Promoting during decline is a markdown, not a promotion. +4. **Cross-category coordination:** Avoid promoting close substitutes simultaneously. + Stagger promotions across substitutes by at least 2 weeks to avoid self-cannibalization. +5. **Vendor funding alignment:** Match promotional timing to vendor trade fund availability. + Many CPG manufacturers operate on calendar quarters — funds not committed by quarter-end + expire. Plan key promos in weeks 8–12 of each quarter when vendors are motivated to + spend remaining funds. + +--- + +## 4. ABC/XYZ Segmentation Methodology + +### 4.1 ABC Classification (Value) + +ABC classification segments SKUs by their financial contribution. The classification +drives differentiated investment in forecasting effort, safety stock, review frequency, +and management attention. + +#### Classification Procedure + +1. **Select the value metric.** Options in order of preference: + - Gross margin contribution (best — focuses investment on profit, not revenue) + - Revenue (acceptable when margin data is unavailable) + - Unit volume (use only for warehouse space planning, not financial investment) + +2. **Compute trailing 52-week value** for each active SKU. + +3. **Sort descending** by the value metric. + +4. **Compute cumulative % of total value** and classify: + +| Class | Cumulative % of Value | Typical % of SKUs | Description | +|---|---|---|---| +| A | 0–80% | 10–20% | High-value items driving the business | +| B | 80–95% | 20–30% | Mid-value items providing assortment breadth | +| C | 95–100% | 50–70% | Long-tail items with minimal individual impact | + +5. **Exception overrides:** + - New items (< 13 weeks) are auto-classified one tier higher than their data suggests + until they have sufficient history. A new item computing as C is treated as B. + - Items with contractual obligations (planogram commitment, vendor agreement) are + classified minimum B regardless of current sales velocity. + - Items flagged as strategic by merchandising (e.g., traffic drivers, competitive + price match items) are classified minimum A. + +#### Reclassification Schedule + +Run ABC reclassification quarterly. Between quarters, items are reclassified only +if they cross a threshold by >50% (e.g., an item must contribute >120% of the A/B +boundary to move from B to A mid-quarter). This prevents oscillation at class boundaries. + +### 4.2 XYZ Classification (Predictability) + +XYZ classification segments SKUs by demand forecast difficulty. It drives differentiated +forecasting method selection and safety stock strategies. + +#### Classification Procedure + +1. **Compute de-seasonalized, de-promoted demand** for each SKU over the trailing 52 weeks. + Remove seasonal indices and promotional lift periods so that the variability metric + reflects genuine demand uncertainty, not planned variation. + +2. **Compute the coefficient of variation (CV):** + ``` + CV = σ_demand / μ_demand + ``` + Use the de-seasonalized, de-promoted demand series. + +3. **Classify:** + +| Class | CV Range | Description | Forecast Difficulty | +|---|---|---|---| +| X | < 0.5 | Highly predictable — demand varies little around its mean | Low — simple methods work well | +| Y | 0.5–1.0 | Moderately predictable — noticeable variability | Medium — requires good models and monitoring | +| Z | > 1.0 | Erratic/lumpy — demand is highly variable or intermittent | High — no model will be highly accurate | + +4. **Supplement with ADI (Average Demand Interval):** Items with ADI > 2.0 (meaning + demand occurs less than every other period) should be classified Z regardless of CV, + because the intermittency itself creates forecast difficulty that CV alone doesn't capture. + +### 4.3 Combined ABC/XYZ Policy Matrix + +| Segment | Forecast Method | Safety Stock | Review Frequency | Replenishment | Management Attention | +|---|---|---|---|---|---| +| **AX** | Exponential smoothing (automated) | Z = 1.96 (97.5%) | Weekly | Automated with exception alerts | Monthly review | +| **AY** | Holt-Winters or causal model | Z = 1.65 (95%) | Weekly | Automated with planner review | Bi-weekly review | +| **AZ** | Ensemble or manual override | Z = 1.41–1.65 (92–95%) | Weekly | Planner-managed; never fully automated | Weekly review | +| **BX** | Moving average (automated) | Z = 1.65 (95%) | Bi-weekly | Automated | Monthly review | +| **BY** | Exponential smoothing (automated) | Z = 1.65 (95%) | Bi-weekly | Automated with exception alerts | Monthly review | +| **BZ** | Croston's or damped trend | Z = 1.28 (90%) | Bi-weekly | Semi-automated with planner approval | Monthly review | +| **CX** | Simple moving average | Z = 1.28 (90%) | Monthly | Automated | Quarterly review | +| **CY** | Simple moving average | Z = 1.28 (90%) | Monthly | Automated | Quarterly review | +| **CZ** | Croston's or none | Z = 1.04 (85%) | Monthly | Manual or min/max | Quarterly — discontinuation candidate | + +### 4.4 Migration Tracking + +Track SKU movement between segments quarterly. Key migration patterns to monitor: + +| Migration | Signal | Action | +|---|---|---| +| A → B | Revenue or margin declining | Investigate: is this category shrinkage, competitive loss, or assortment issue? | +| B → A | Revenue or margin growing | Upgrade forecasting method and review frequency. Validate safety stock. | +| X → Y or Z | Demand becoming less predictable | Check for demand pattern regime change. Review forecast model fit. Increase safety stock. | +| Z → X or Y | Demand stabilizing | Possible to simplify forecast model. Review safety stock for reduction. | +| Any → CZ | Low value + erratic | Strong discontinuation candidate. Run slow-mover kill decision. | + +--- + +## 5. Vendor Management Decision Logic + +### 5.1 Vendor Tier Classification + +Classify vendors into tiers based on annual purchase volume, strategic importance, +and supply risk profile: + +| Tier | Criteria | Count (typical) | Review Cadence | +|---|---|---|---| +| **Strategic** | Top 5 by spend, or sole-source for A-items | 3–8 | Monthly scorecards, quarterly business reviews | +| **Preferred** | Top 20 by spend, multiple A/B items | 10–25 | Quarterly scorecards | +| **Approved** | All remaining active vendors | 30–100+ | Annual review | +| **Probationary** | Vendors under corrective action | Variable | Weekly monitoring, monthly review | + +### 5.2 Vendor Scorecard Metrics + +Score each vendor quarterly on a 0–100 scale across these dimensions: + +| Dimension | Weight | Metric | Target | Calculation | +|---|---|---|---|---| +| **On-time delivery** | 30% | % of POs delivered within the agreed window (±1 day) | > 95% | Score = (Actual % / 95%) × 100, cap at 100 | +| **Fill rate** | 25% | % of ordered units actually shipped | > 97% | Score = (Actual % / 97%) × 100, cap at 100 | +| **Lead time consistency** | 20% | CV of actual lead time vs. stated lead time | CV < 0.15 | Score = max(0, 100 − (CV − 0.15) × 500) | +| **Quality** | 15% | % of received units passing QC inspection | > 99% | Score = (Actual % / 99%) × 100, cap at 100 | +| **Responsiveness** | 10% | Average response time to inquiries/issues (hours) | < 24 hours | Score = max(0, 100 − (Avg Hours − 24) × 2) | + +**Composite score thresholds:** + +| Score Range | Rating | Action | +|---|---|---| +| 90–100 | Excellent | Consider for volume increase, preferred terms | +| 75–89 | Good | Standard operations, no action needed | +| 60–74 | Needs Improvement | Issue corrective action request; 90-day improvement plan | +| < 60 | Unacceptable | Immediate escalation; begin qualifying alternative suppliers | + +### 5.3 Vendor Lead Time Management + +Lead time management is the demand planner's most underleveraged tool for reducing +inventory investment. A 1-day reduction in lead time across all vendors can reduce +aggregate safety stock by 5–8%. + +**Lead time decomposition:** + +| Component | Typical Range | Planner Influence | +|---|---|---| +| Order processing at vendor | 1–3 days | Low — vendor's internal process | +| Production/picking | 2–10 days | Medium — negotiate priority tiers | +| Vendor ship preparation | 1–2 days | Low | +| Transit time | 1–14 days | Medium — carrier selection, mode choice | +| Receiving and put-away | 1–3 days | High — internal process improvement | +| Quality hold (if applicable) | 0–5 days | High — streamline QC process | + +**Actions to reduce lead time:** + +1. For strategic vendors: negotiate VMI (vendor-managed inventory) where the vendor + monitors your inventory and ships proactively. Eliminates order processing delay. +2. For all vendors: provide rolling 8-week forecasts to allow pre-positioning. Reduces + production/picking time on non-stock items. +3. Internally: invest in receiving automation (ASN-enabled receiving, barcode scanning) + to cut receiving from 2–3 days to same-day. +4. Negotiate consolidated weekly shipments vs. per-PO shipments to reduce transit + frequency while maintaining fill rate. + +### 5.4 MOQ (Minimum Order Quantity) Negotiation Framework + +When a vendor's MOQ creates excess inventory, evaluate these options in order: + +| Option | When to Use | Expected Outcome | +|---|---|---| +| **Negotiate lower MOQ** | Annual spend > $50K with this vendor; you have leverage | MOQ reduced 20–40% | +| **Consolidate with other SKUs** | Multiple SKUs from same vendor; dollar minimum instead of unit minimum | Meet dollar MOQ without over-ordering individual SKUs | +| **Accept higher price for lower MOQ** | MOQ overage cost > price premium cost | Pay 3–8% more per unit but order only what you need | +| **Negotiate consignment** | Slow-moving items from strategic vendors | Vendor owns inventory until you sell it | +| **Split orders with another buyer** | Known network of retailers ordering from the same vendor | Share the MOQ and split the shipment | +| **Accept the overage** | Holding cost for the excess is < $500 and item is non-perishable | Order the MOQ and treat the overage as forward inventory | + +### 5.5 Vendor Negotiation for Lead Time Reduction + +**Preparation checklist before negotiating:** + +1. Document your current order volume and growth trajectory with this vendor. +2. Compute the cost of their current lead time to your business: excess safety stock + carrying cost + stockout cost from lead time variability. +3. Identify what you can offer in return: longer-term commitments, higher volumes, + fewer order frequency changes, rolling forecasts. +4. Know your BATNA (best alternative): have a qualified secondary supplier identified. + +**Negotiation structure:** + +1. Present the data: "Over the past 6 months, your average lead time has been X days + with a standard deviation of Y. This variability costs us $Z annually in excess + safety stock." +2. Propose the target: "We're requesting a committed lead time of X−2 days with a + guarantee of CV < 0.15." +3. Offer the exchange: "In return, we can commit to rolling 8-week forecasts updated + weekly, and we'll consolidate to 2 orders per week instead of daily." +4. Set the timeline: "Let's implement this for Q2 and review the scorecard at the + end of Q2 QBR." + +--- + +## 6. Seasonal Buy and Markdown Timing Models + +### 6.1 Seasonal Buy Planning + +Seasonal categories require forward commitments because lead times exceed the selling +season. The buy decision has two components: the initial buy (pre-season) and the +in-season reorder (if the vendor supports it). + +#### Initial Buy Calculation + +``` +Initial Buy = Season Forecast × Initial Commitment % − Carry-Over Inventory +``` + +| Category Risk Profile | Initial Commitment % | Reserve for Reorder | Rationale | +|---|---|---|---| +| Low risk (staple seasonal, proven seller) | 70–80% | 20–30% | High confidence in forecast; reorder available | +| Medium risk (trend-influenced, moderate history) | 55–65% | 35–45% | Hedge against forecast error | +| High risk (fashion, new trend, first season) | 40–50% | 50–60% | Maximize flexibility; accept possible stockout | +| One-time buy (import, long lead, no reorder) | 100% | 0% | No reorder option; commit fully but forecast conservatively | + +#### In-Season Reorder Triggers + +Monitor sell-through rate weekly starting from week 2 of the season: + +``` +Sell-Through Rate = Units Sold / (Units Sold + Units On-Hand + Units On-Order) +``` + +| Weeks into Season | Sell-Through vs. Plan | Action | +|---|---|---| +| Weeks 1–2 | > 120% of plan | Issue reorder immediately for 50% of reserve allocation | +| Weeks 1–2 | 80–120% of plan | Hold; too early to confirm trend | +| Weeks 3–4 | > 110% of plan | Issue reorder for remaining reserve | +| Weeks 3–4 | 90–110% of plan | Issue conservative reorder (25% of reserve) | +| Weeks 3–4 | 70–89% of plan | Hold all reserve; prepare markdown contingency | +| Weeks 3–4 | < 70% of plan | Cancel any open reorders; initiate early markdown | +| Weeks 5+ | Any pace | Reorders unlikely to arrive in time; manage with markdowns | + +### 6.2 Markdown Timing and Depth Model + +The markdown decision balances margin recovery against sell-through velocity. Every +week of delay costs margin because holding costs accrue and the remaining selling +window shrinks. + +#### Markdown Decision Matrix + +| Weeks Remaining in Season | Weeks of Supply at Current Rate | Recommended Action | +|---|---|---| +| > 6 weeks | < 3 | No markdown; possible reorder | +| > 6 weeks | 3–6 | Hold price; monitor weekly | +| > 6 weeks | 7–10 | First markdown: 20–25% off | +| > 6 weeks | > 10 | Aggressive markdown: 30–40% off | +| 4–6 weeks | < 3 | No markdown needed | +| 4–6 weeks | 3–6 | Consider 15–20% markdown | +| 4–6 weeks | 6–10 | Markdown 25–35% | +| 4–6 weeks | > 10 | Markdown 40–50%; explore liquidation | +| 2–4 weeks | < 3 | No markdown | +| 2–4 weeks | 3–6 | Markdown 30–40% | +| 2–4 weeks | > 6 | Markdown 50–60%; liquidation channels | +| < 2 weeks | Any remaining | Final clearance 60–75% off or liquidation | + +#### Markdown Velocity Curve + +After applying a markdown, monitor the velocity response: + +| Markdown Depth | Expected Velocity Increase | If Not Achieved Within 1 Week | +|---|---|---| +| 20% off | 1.5–2.0× | Deepen to 30% | +| 30% off | 2.0–3.0× | Deepen to 40% | +| 40% off | 3.0–4.0× | Deepen to 50% or explore liquidation | +| 50% off | 4.0–6.0× | If still not moving, this is dead stock — liquidate | + +### 6.3 Season-End Liquidation Decision + +When the selling season is ending and inventory remains: + +``` +Liquidation Net Recovery = (Liquidation Price × Remaining Units) − Logistics Cost +Hold-to-Next-Season Net = (Expected Sell Price × Sell-Through Estimate) + − Holding Cost − Obsolescence Risk +``` + +**Liquidation is preferred when:** +- Hold-to-next-season sell-through estimate < 60% (style risk, trend change) +- Holding cost for 9–12 months > 15% of original cost (typical for most retailers) +- Warehouse space is constrained and the space has higher-value alternative use +- The product is trend/fashion and will be visually dated next season + +**Holding is preferred when:** +- Product is a classic/carryover style with minimal fashion risk +- Hold-to-next-season sell-through estimate > 80% +- Warehouse space is available at low marginal cost +- Liquidation offers are below variable cost (you'd lose money selling) + +--- + +## 7. New Product Introduction Forecasting + +### 7.1 Analogous Item Selection + +The quality of a new product forecast depends almost entirely on the quality of the +analogous items selected. Bad analogs produce bad forecasts regardless of the method. + +#### Selection Criteria (rank by importance) + +| Criterion | Weight | How to Match | +|---|---|---| +| **Category/subcategory** | 25% | Must be same subcategory (e.g., "premium yogurt" not just "dairy") | +| **Price point** | 20% | Within ±20% of the new item's retail price | +| **Brand tier** | 15% | National brand → national brand analog; private label → private label | +| **Pack size / format** | 15% | Similar unit count, size, or weight | +| **Target demographic** | 10% | Same customer segment (value, mainstream, premium) | +| **Launch season** | 10% | Same quarter launch; seasonal patterns differ by quarter | +| **Distribution breadth** | 5% | Similar initial door count (±25%) | + +#### Analog Scoring + +Score each candidate analog on the criteria above (1–5 scale per criterion, weighted). +Select the top 3–5 analogs with composite scores > 3.5. If no analogs score > 3.0, the +new product is truly novel — use category average with a 40% confidence band. + +### 7.2 New Product Lifecycle Curve + +Most new products follow a lifecycle curve with four phases: + +| Phase | Duration | Demand Pattern | Description | +|---|---|---|---| +| **Introduction** | Weeks 1–4 | Ramp-up, often trial-driven | Initial customer trial. Demand is unpredictable. | +| **Growth** | Weeks 5–12 | Accelerating, repeat purchases begin | Repeat buyers emerge. Demand becomes more predictable. | +| **Stabilization** | Weeks 13–26 | Plateaus to steady state | Item finds its "run rate." Baseline forecast is reliable. | +| **Maturity** | Weeks 27+ | Stable or slowly declining | Standard demand planning applies. | + +**Forecast by phase:** + +| Phase | Method | Confidence Band | +|---|---|---| +| Introduction (1–4 weeks) | Analog average × 1.1 (trial bump) | ±40–50% | +| Growth (5–12 weeks) | Blend: 40% analog + 60% own trajectory | ±25–35% | +| Stabilization (13–26 weeks) | 80% own history, 20% analog | ±15–25% | +| Maturity (27+ weeks) | Standard method selection per demand pattern | Standard WMAPE target | + +### 7.3 New Product Safety Stock Protocol + +| Weeks of History | Safety Stock Approach | Uncertainty Premium | +|---|---|---| +| 0–4 | Analog σ_d with 30% premium | 1.30× | +| 5–8 | Blended σ_d (50% own + 50% analog) with 20% premium | 1.20× | +| 9–12 | Blended σ_d (75% own + 25% analog) with 10% premium | 1.10× | +| 13+ | Own σ_d, standard formula | 1.00× | + +### 7.4 New Product Kill Decision + +Not every new product succeeds. The kill decision should be structured, not emotional: + +| Metric | Kill Threshold | Timeframe | +|---|---|---| +| Sell-through vs. analog-based plan | < 30% of plan | After 6 weeks | +| Repeat purchase rate (if measurable) | < 10% of trial purchasers | After 8 weeks | +| Velocity trend | Declining for 4 consecutive weeks after introduction | After 6 weeks | +| Category manager assessment | "Would not re-buy" | After 8 weeks | + +When a kill decision is made: +1. Cancel all open POs immediately. +2. Halt any planned promotions. +3. Mark down remaining inventory at 30% off for 3 weeks, then 50% for 2 weeks. +4. Liquidate any remainder after 5 weeks. +5. Document the post-mortem: why did the analog-based forecast fail? Was it the + analogs, the product, the pricing, or the competitive context? + +--- + +## 8. Demand Sensing and Exception Management + +### 8.1 Real-Time Demand Signal Monitoring + +In addition to periodic forecast reviews, monitor for demand signals that require +immediate attention between forecast cycles: + +| Signal | Detection Method | Threshold | Action | +|---|---|---|---| +| **POS velocity spike** | Daily POS > 3× trailing 4-week daily average | 3× for 2+ consecutive days | Investigate cause; manual override if sustained | +| **POS velocity drop** | Daily POS < 0.3× trailing 4-week daily average | 0.3× for 3+ consecutive days | Check for phantom inventory, display removal, or competitive action | +| **Stockout cascade** | 3+ locations out of stock on same SKU within 48 hours | 3 locations | Emergency replenishment from DC; allocate by sales velocity | +| **Weather alert** | NWS severe weather warning for region covering > 10% of stores | Forecast impact > 5% of category volume | Adjust forecasts for weather-sensitive categories | +| **Competitive price move** | Competitor price check shows > 15% lower on comparable SKU | Confirmed at 3+ competitor locations | Alert merchandising; prepare forecast downward revision | +| **Social media spike** | Monitoring tool shows > 500% increase in brand/product mentions | Sustained > 24 hours | Assess virality risk; prepare allocation plan | + +### 8.2 Forecast Override Governance + +Manual overrides are necessary but dangerous. Ungoverned overrides introduce bias and +degrade forecast accuracy over time. + +**Override rules:** + +1. **All overrides must be documented** with a reason code and quantitative justification. +2. **Override authority by magnitude:** + - ±10%: Planner can override without approval + - ±10–25%: Requires planning manager approval + - ±25–50%: Requires director approval + - > ±50%: Requires VP approval (or planning committee) +3. **Override accuracy tracking:** Every override is tracked against actuals. If a planner's + overrides have a WMAPE > 40% over a quarter, their override authority is reviewed. +4. **Sunset rule:** Overrides expire after 4 weeks. If the condition persists, a new + override (with fresh justification) must be created. This prevents stale overrides + from contaminating forecasts months later. +5. **No "consensus" overrides:** Overrides from demand review meetings where forecasts + are adjusted to match sales team wishful thinking are the #1 source of positive bias. + Require every meeting override to cite a specific, verifiable external signal. + +--- + +## 9. Inventory Health Diagnostics + +### 9.1 Weeks of Supply Analysis + +Weeks of supply (WOS) is the primary pulse-check metric for inventory health. Compute +at the SKU level, aggregate to category, and review weekly. + +``` +WOS = On-Hand Inventory (units) / Average Weekly Demand (units) +``` + +Use the forward-looking forecast for the denominator, not trailing sales. Trailing sales +understates demand when items have been out of stock (you can't sell what you don't have). + +**WOS Health Bands:** + +| WOS Range | Status | Action | +|---|---|---| +| < 2 weeks | Critical low | Expedite replenishment; consider reallocation from low-velocity locations | +| 2–3 weeks | Low | Verify next PO arrival; place emergency order if no PO in transit | +| 4–8 weeks | Healthy | Standard operations | +| 9–12 weeks | Elevated | Review forecast; defer or reduce next PO if demand hasn't increased | +| 13–26 weeks | Excess | Initiate markdown or promotional sell-through plan | +| > 26 weeks | Critical excess | Flag for slow-mover kill decision; markdown or liquidate | + +### 9.2 Inventory Turns and GMROI + +**Inventory Turns:** +``` +Annual Turns = Annual COGS / Average Inventory at Cost +``` + +| Category Type | Target Turns | Benchmark | +|---|---|---| +| Perishable grocery | 30–52 | 1× per week | +| Center-store grocery | 12–20 | Every 2–4 weeks | +| General merchandise | 6–12 | Every 4–8 weeks | +| Seasonal (in-season) | 8–15 | Sell through in-season | +| Seasonal (annual) | 2–4 | Lower because of off-season zero sales | + +**GMROI (Gross Margin Return on Inventory Investment):** +``` +GMROI = Gross Margin $ / Average Inventory at Cost +``` + +A GMROI of 2.0 means you earn $2 in gross margin for every $1 invested in inventory. +Minimum acceptable GMROI varies by category but should generally exceed the company's +cost of capital divided by the gross margin percentage. For a retailer with 8% cost of +capital and 35% gross margin, minimum GMROI = 0.08 / 0.35 = 0.23. In practice, most +retailers target GMROI > 1.5 for healthy categories. + +### 9.3 Dead Stock and Obsolescence Identification + +Dead stock is inventory with zero sales for a defined period. It is the most expensive +form of excess inventory because it generates zero return while consuming warehouse space +and working capital. + +**Dead stock tiers:** + +| Tier | Definition | Action | Timeline | +|---|---|---|---| +| Aging | Zero sales for 8–12 weeks | Review — is this seasonal? New? Misplaced? | Investigate within 1 week | +| Dead | Zero sales for 13–26 weeks | Markdown 40–50% or move to clearance | Initiate within 2 weeks | +| Obsolete | Zero sales for > 26 weeks | Liquidate at any positive recovery or donate | Execute within 4 weeks | +| Write-off | Liquidation/donation uneconomical | Destroy and write off; recover warehouse space | Execute within 2 weeks | + +**Root cause analysis for dead stock:** + +Run quarterly. Categorize dead stock by root cause to prevent recurrence: + +| Root Cause | % of Dead Stock (typical) | Prevention | +|---|---|---| +| Over-buying (forecast too high) | 35–45% | Improve forecast accuracy; tighten override governance | +| Product failure (quality, customer rejection) | 15–20% | Faster new product kill decisions | +| Seasonal carryover (missed markdown window) | 15–25% | Enforce markdown timing model from §6.2 | +| Assortment change (delisted but not sold through) | 10–15% | Coordinate delist timing with sell-through | +| Phantom inventory (system says it exists but doesn't) | 5–10% | Regular cycle counts on zero-velocity items | + +### 9.4 Allocation Logic for Multi-Location Retailers + +When DC inventory is insufficient to fill all store-level demand, allocate using a +priority framework rather than pro-rata distribution: + +**Priority 1: Prevent store stockout on A-items.** +Allocate first to stores with < 3 days of supply on A-items. Quantity = minimum of +(days-to-next-DC-shipment × daily demand) to bridge until the next allocation cycle. + +**Priority 2: Match allocation to store-level forecast.** +For remaining inventory, allocate proportional to each store's forward weekly forecast +(not historical sales, which penalizes stores that have been out of stock). + +**Priority 3: Minimum presentation stock.** +Every store receives at least the minimum display quantity regardless of forecast. An +empty shelf signals "this item is discontinued" to the customer and destroys demand. + +**Priority 4: Cap allocation to shelf capacity.** +Do not send more than a store can merchandise. Excess units in the backroom create +shrinkage, damage, and out-of-date risk (for perishables). + +**Allocation frequency:** +- A-items: allocate with every DC-to-store shipment (typically 2–5× per week) +- B-items: allocate 1–2× per week +- C-items: allocate weekly or bi-weekly diff --git a/web-app/public/skills/inventory-demand-planning/references/edge-cases.md b/web-app/public/skills/inventory-demand-planning/references/edge-cases.md new file mode 100644 index 00000000..34916d98 --- /dev/null +++ b/web-app/public/skills/inventory-demand-planning/references/edge-cases.md @@ -0,0 +1,602 @@ +# Inventory Demand Planning — Edge Cases Reference + +> Tier 3 reference. Load on demand when handling complex or ambiguous demand planning situations that don't resolve through standard forecasting and replenishment workflows. + +These edge cases represent the scenarios that separate experienced demand planners from everyone else. Each one involves competing signals, imperfect data, time pressure, and real financial exposure. They are structured to guide decision-making when standard models break down. + +--- + +## How to Use This File + +When a planning situation doesn't fit a clean pattern — when demand signals conflict, when models fail silently, or when the financial exposure justifies deeper analysis — find the edge case below that most closely matches the situation. Follow the expert approach step by step. Document every assumption and override so the decision can be audited at post-mortem. + +--- + +### Edge Case 1: New Product Launch with Zero History and No Close Analog + +**Situation:** +A retailer's private-label team is launching a plant-based protein bar in a new flavor profile (mango turmeric) that has no direct precedent in their assortment or their competitors'. The product will launch in 120 stores across the Southeast region. Retail price is $3.49 per bar, case pack of 12, with a vendor cost of $1.85. The vendor requires a minimum initial order of 10,000 units (833 cases) with a 6-week lead time for reorder. The merchandising team is projecting "strong performance" based on consumer trend data showing plant-based snacking growing 22% YoY, but has no quantitative forecast. The product has a 9-month shelf life. + +**Why It's Tricky:** +There is no demand history for this exact item, and the nearest analogs (existing protein bars, existing plant-based snacks) are imperfect matches. The mango turmeric flavor is novel — it could be a breakout trend or a niche product. The 6-week reorder lead time means you cannot react quickly if the product takes off, but the 9-month shelf life means overstock is not immediately catastrophic. The merchandising team's qualitative confidence is not a substitute for a quantitative forecast. + +**Common Mistake:** +Accepting the merchandising team's optimistic "gut feel" as the forecast and ordering aggressively. Or, conversely, ordering so conservatively that the product launches out-of-stock in week 2, killing momentum and making the launch look like a failure when it was actually a supply failure. + +**Expert Approach:** +1. Build a structured analog set. Score candidates on category (snack bars), price point ($3–$4), brand tier (private label), format (single serve), and target demo (health-conscious). Select the top 3–5 analogs even if they're imperfect. +2. Compute the median weekly velocity of the analogs at the same lifecycle stage (launch weeks 1–13). Weight by analog similarity score. Typical private-label snack bar launch velocity is 2–4 units/store/week after the trial bump. +3. Build three scenarios: conservative (2 units/store/week), base (3.5 units/store/week), optimistic (6 units/store/week). For 120 stores, this yields weekly demand of 240, 420, or 720 units. +4. Initial buy: commit to the base scenario for weeks 1–8 (420 × 8 = 3,360 units), plus safety stock at the conservative rate for the 6-week reorder lead time (240 × 6 × 1.3 buffer = 1,872 units). Total initial order: ~5,232 units. This is below the vendor's 10,000 MOQ. +5. Negotiate with the vendor: either accept the 10,000 MOQ (accepting ~10 weeks of forward stock at base rate, which is fine given 9-month shelf life), or negotiate a 5,000-unit initial order with a committed reorder at week 4 based on early sell-through. +6. Set weekly POS monitoring triggers: if week-1 velocity > 5 units/store/day, escalate to the optimistic scenario and place reorder immediately. If week-2 velocity < 1.5 units/store, flag for review — the product may be underperforming. +7. Plan a week-3 evaluation checkpoint with merchandising. If sell-through is < 40% of base scenario, begin discussing promotional support. If > 150%, ensure reorder is en route. + +**Documentation Required:** +- Analog selection with scoring rationale +- Three-scenario forecast with assumptions +- Initial buy calculation with safety stock methodology +- Vendor MOQ negotiation outcome +- Monitoring triggers and escalation plan +- Week-3 checkpoint agenda + +**Resolution Timeline:** +- Weeks -8 to -6: Analog selection, scenario modeling, initial buy decision +- Weeks -6 to -4: PO placement, promotional material preparation +- Week 0: Launch +- Weeks 1–3: Daily POS monitoring against scenarios +- Week 3: First checkpoint with merchandising +- Week 4: Reorder decision based on actual sell-through + +--- + +### Edge Case 2: Viral Social Media Spike — 10× Demand with No Warning + +**Situation:** +A mid-tier kitchen gadget (a silicone garlic peeler, retail $8.99, category C-item averaging 15 units/week across 80 stores) suddenly goes viral on TikTok. A cooking influencer with 4.2M followers posted a 45-second video using the product, and it accumulated 8M views in 48 hours. Store-level POS data shows demand jumped to 180 units/day across the chain (vs. the normal ~2 units/day) starting Tuesday morning. Your DC has 2,400 units in stock. The vendor is a small importer based in Portland with 8-week lead time from their factory in Shenzhen. Your last PO for this item was 3 months ago for 1,200 units. + +**Why It's Tricky:** +The instinct is to chase the demand — place a massive order and ride the wave. But viral demand follows a power-law decay curve, not a sustained step change. By the time a 8-week-lead-time order arrives, the spike is almost certainly over. Meanwhile, your DC inventory will be exhausted in 13 days at current run rate, and you'll be out of stock for 6+ weeks. Customers who can't find it will buy from Amazon. + +**Common Mistake:** +Ordering 10,000+ units from the vendor based on the spike's peak demand. When the order arrives 8 weeks later, demand has returned to 20–30 units/week (slightly elevated baseline), and you're sitting on 10,000 units — 300+ weeks of supply. + +**Expert Approach:** +1. Do NOT place a large emergency order based on peak demand. Viral spikes typically follow this decay pattern: peak in days 1–5, 50% decay by day 10, 80% decay by day 21, new baseline establishes by day 30–45 (usually 1.5–3× the pre-viral level). +2. With 2,400 units in DC and ~180 units/day demand, you have ~13 days of supply. Implement allocation rules immediately: cap store-level fulfillment at 3× historical daily average (6 units/store/day max). This stretches DC supply to ~20 days and prevents a single high-traffic store from claiming all the inventory. +3. Contact the vendor. Determine: (a) do they have any finished goods inventory in Portland? (b) can they expedite a partial shipment by air from Shenzhen? (c) what is the minimum order for an air shipment? Air freight at ~$5/unit on a $4.50 cost item is expensive but justified if you can capture $8.99 retail during the spike. +4. Place a modest reorder: 2,000–3,000 units (not 10,000). If the vendor can air-ship 500 units in 7–10 days, do that for immediate demand. The remaining 2,000 by ocean in 8 weeks will arrive when the new baseline is establishing. +5. Monitor the TikTok video and social conversation daily. Track engagement rate decay. When the video drops off the "For You" page algorithm (typically day 7–14), demand will fall sharply. +6. After the spike subsides (day 30+), assess the new baseline. If it's 2–3× the pre-viral level, adjust the forecast model upward. If it's back to pre-viral levels, return to the standard model. Do not permanently inflate the forecast based on a one-time event. + +**Key Indicators:** +- Social media engagement half-life (how quickly the video's daily views are declining) +- Store-level POS day-over-day trend (is demand decelerating?) +- Amazon price and availability for the same or similar product (competitor action) +- Geographic concentration of demand (if concentrated in a few markets, the spike is more narrow) + +**Documentation Required:** +- Social media monitoring data (daily view counts, engagement) +- Daily POS data at store level during the spike +- Allocation rules implemented and their rationale +- Vendor communication log and order decisions +- Post-spike baseline reassessment (at day 30 and day 60) + +**Resolution Timeline:** +- Hours 0–4: Detect the spike via POS anomaly alerts; identify the social media source +- Hours 4–12: Implement store-level allocation caps; contact vendor for emergency supply +- Day 1–3: Monitor daily POS; track social media engagement decay +- Day 3–7: If spike sustaining, place modest reorder (air freight if available) +- Day 7–14: Social media engagement typically decays below threshold; spike decelerating +- Day 21–30: Demand settling to new baseline; assess whether permanent elevation occurred +- Day 30–45: Final baseline recalibration; close event; update model if sustained lift > 50% + +**Financial Impact:** +A C-item at $8.99 retail and 15 units/week going to 180 units/day represents a revenue jump +from ~$135/week to ~$11,328/week — an 84× increase. With 2,400 units in DC, the captured +revenue is ~$21,576 before stockout. Chasing with a 10,000-unit ocean order ($45,000 at cost) +that arrives to 25 units/week demand creates $39,375 in excess inventory. The smart play +(500-unit air shipment + 2,000-unit modest ocean order) captures ~$8,500 in additional revenue +during the tail of the spike while limiting overage risk to ~$3,500 in excess inventory. + +--- + +### Edge Case 3: Supplier Lead Time Doubles Overnight — Single-Source Critical Item + +**Situation:** +Your primary vendor for organic olive oil (an A-item, $12.99 retail, ~800 units/week across 150 stores) notifies you that their lead time is increasing from 14 days to 28 days effective immediately. The cause: their Mediterranean source experienced a poor harvest season, and the vendor is now sourcing from a secondary supplier in South America, which adds transit and quality testing time. You currently have 2,800 units in DC (3.5 weeks of supply at current demand) and a PO for 2,400 units that was due in 10 days but is now due in 24 days. Your safety stock calculation was based on the old 14-day lead time. + +**Why It's Tricky:** +Your safety stock was calibrated for 14-day lead time. At the old lead time, your safety stock formula was: SS = 1.65 × 120 × √2 = 280 units (where σ_d = 120 units/week, LT = 2 weeks). Now LT = 4 weeks, so SS should be: 1.65 × 120 × √4 = 396 units. But you also need to recalculate the reorder point: ROP = d_avg × LT + SS = 800 × 4 + 396 = 3,596 units. You currently have IP = 2,800 + 2,400 = 5,200 units. That seems sufficient, but the in-transit PO is delayed by 14 days, meaning your effective on-hand for the next 24 days is only 2,800 units, which covers 3.5 weeks — less than the new 4-week lead time. + +**Common Mistake:** +Accepting the vendor's new lead time without recalculating safety stock and reorder points. The planner orders the same quantities at the same frequency and discovers a stockout 3 weeks later when the gap becomes visible. + +**Expert Approach:** +1. Immediately recalculate safety stock and reorder points using the new 28-day lead time. Document the before/after impact. +2. Assess the inventory gap: Current on-hand (2,800) will last 3.5 weeks. The delayed PO (2,400 units) arrives in 24 days (~3.4 weeks). At 800 units/week consumption, you'll need 800 × 3.4 = 2,720 units in those 3.4 weeks, leaving only 80 units when the PO arrives — essentially zero safety stock. +3. Place an emergency order immediately. Target quantity: enough to bridge the gap plus rebuild safety stock. Emergency order = (new SS − projected SS at PO arrival) + buffer = (396 − 80) + 400 = ~716 units. Round up to a case pack multiple. +4. Contact the vendor: can they expedite any portion of the delayed PO? Even splitting it — 1,200 units at the original 14-day lead time and 1,200 at 28 days — would dramatically improve the position. +5. Qualify a secondary supplier. Even if the secondary vendor has a higher cost or lower quality tier, having a backup prevents single-source dependency. Begin the qualification process immediately — don't wait for the crisis to deepen. +6. Consider temporary demand-side measures: can you reduce facings (from 3 facings to 2) to slow sell-through without creating a visible out-of-stock? Can you substitute a different size (e.g., 25 oz instead of 16 oz) to spread demand across SKUs? +7. Communicate to merchandising: service level on this item will temporarily drop from 97% to ~92% for the next 4–6 weeks. If this is unacceptable, discuss promotional alternatives or substitution strategies. + +**Documentation Required:** +- Before/after safety stock and ROP calculations +- Inventory position timeline projection (weekly, for the next 8 weeks) +- Emergency order details and vendor response +- Secondary supplier qualification plan with timeline +- Communication to merchandising and category management + +**Resolution Timeline:** +- Hour 0: Vendor notification received +- Hours 0–4: Recalculate safety stock, ROP, and inventory position with new lead time +- Hours 4–8: Place emergency order for the inventory gap +- Day 1–2: Contact vendor to negotiate partial early shipment of delayed PO +- Week 1: Begin secondary supplier qualification process +- Week 1–2: Communicate revised service level expectations to merchandising +- Weeks 2–6: Monitor inventory position weekly against projections +- Weeks 6–8: Assess whether lead time has stabilized; update parameters permanently if so +- Week 12: Review secondary supplier qualification status; decide whether to dual-source + +**Dual-Source Strategy Post-Crisis:** +After any single-source lead time shock, evaluate dual-sourcing economics: +- If the category is A-tier (>$500K annual purchases), dual-source at 70/30 split. + The 30% secondary supplier provides insurance and keeps the primary vendor competitive. +- If B-tier ($100K–$500K), qualify a backup but keep orders single-source until triggered. +- If C-tier (<$100K), the qualification cost may exceed the risk. Accept single-source + and carry additional safety stock instead. + +--- + +### Edge Case 4: Unplanned Competitor Promotion Causes Demand Drop — Cannibalization You Didn't Plan + +**Situation:** +Your chain's premium laundry detergent (Tide Ultra, A-item, $13.99, ~600 units/week across 120 stores) shows a sudden 35% velocity decline starting this week. POS data confirms it — down to ~390 units/week. There is no quality issue, no out-of-stock, and no change in shelf placement. A field report from a regional manager reveals that a competing national chain launched an aggressive BOGO promotion on their comparable Persil product, and a mass-market competitor is running a 40% off promotion on their private-label equivalent. Neither of these competitive actions was in your promotional calendar or forecasting inputs. + +**Why It's Tricky:** +Your forecast model doesn't incorporate competitive promotional activity (most don't). The model will treat this as an unexplained demand drop and slowly adjust the baseline downward — which is wrong, because the competitive promotions will end in 2–3 weeks and your demand will recover. If you let the model self-correct, it will under-forecast the recovery period, leading to a stockout when competitive promotions end and demand snaps back. + +**Common Mistake:** +Letting the automated forecast adjust downward based on the depressed actual sales. The model doesn't know why sales dropped, so it interprets it as a trend change. Two weeks later, when demand recovers, the system doesn't have enough inventory because it ordered based on the depressed forecast. + +**Expert Approach:** +1. Confirm the cause: verify the competitive promotion through field observation, competitive intelligence, or syndicated data (Nielsen/IRI). Don't assume — there could be multiple causes. +2. Once confirmed, apply a manual forecast override for the promotional period. Set the forecast to the depressed level (390 units/week) for the known duration of the competitive promotion (typically 2–4 weeks). +3. Critically: also apply a forward override for the recovery period. When the competitive promo ends, expect a 10–20% bounce-back above the pre-event baseline for 1–2 weeks as customers who delayed purchases return. Set the recovery forecast to 660–720 units/week for weeks 1–2 post-competitive-promo. +4. Adjust incoming orders: reduce the next 2 POs by the difference (600 → 390 = 210 units/week reduction). But do NOT cancel or defer orders that would leave you short during the recovery. +5. Brief merchandising: "Tide is down 35% this week due to competitive BOGO on Persil at [competitor]. We project this lasts 2–3 weeks. We do not recommend a reactive promotion — it would erode margin without recovering the lost volume (customers have already stockpiled from the competitor). Recommend holding price and capturing the recovery." +6. After the event, mark these 2–4 weeks as "competitive interference" in the demand history so the baseline model excludes them from future training data. + +**Key Indicators:** +- Duration of the competitive promotion (check competitor circulars/websites weekly) +- Whether additional competitors pile on (competitive cascades happen in laundry, soda, and cereal) +- Whether the demand recovery follows the expected bounce-back pattern +- Whether the competitive promotion was a one-time event or signals a strategic price repositioning + +**Documentation Required:** +- Competitive intelligence source and verification +- Manual override with reason code "competitive_promo_external" +- Adjusted PO schedule for the event window +- Recovery forecast and rationale +- Post-event analysis comparing actuals to the override forecast + +**Resolution Timeline:** +- Day 0–1: Detect the velocity drop; confirm competitive cause via field reports +- Day 1–2: Apply manual forecast override for the dip and the expected recovery +- Day 2–5: Adjust incoming POs downward for the promotional window +- End of competitive promo + 2 weeks: Analyze recovery pattern vs. forecast +- End of competitive promo + 4 weeks: Close out event; tag demand history; update model + +**Financial Impact Quantification:** +Compute the lost margin during the event: (normal demand − actual demand) × unit margin × duration. +For this example: (600 − 390) × ~$4.00 margin × 3 weeks = ~$2,520 lost margin from volume loss. +Compare this to the cost of a reactive promotion (which would typically cost $3,000–$5,000 in margin +erosion for a category this size) to justify the "hold price" recommendation. + +--- + +### Edge Case 5: Demand Pattern Regime Change — Model Fails Silently + +**Situation:** +A popular breakfast cereal (Cheerios 18 oz, B-item, $4.29, ~400 units/week across 100 stores) has been forecasted with Holt-Winters for 3 years with stable seasonal patterns and WMAPE of 18%. Over the past 6 weeks, the model's tracking signal has crept from +1.5 to +4.8, indicating systematic positive bias (forecast > actuals). Actual sales have declined from 400 units/week to 310 units/week with no promotional activity, no competitive change, and no price change. A deeper look reveals that a competitor launched a new high-protein cereal at the same price point 8 weeks ago, and your chain's health-conscious customer segment is shifting to it. + +**Why It's Tricky:** +This is a permanent demand level shift, not a temporary dip. The Holt-Winters model's seasonal component will eventually adapt, but the level component (alpha) adapts slowly — especially if alpha is set low (e.g., 0.1–0.2) for stability. The model will take 10–15 more weeks to self-correct, during which time it will consistently over-forecast, creating excess inventory. + +**Common Mistake:** +Waiting for the model to self-correct. Or, conversely, panicking and switching the model entirely when a simple level adjustment would suffice. + +**Expert Approach:** +1. Confirm the regime change: the tracking signal at +4.8 for 2+ periods is a clear indicator. Verify by computing the new mean demand (310 units/week) and comparing to the model's level component. +2. Do NOT switch the forecast model yet. The seasonal pattern may still be valid — the item is still seasonal cereal. What changed is the level (intercept), not the pattern. +3. Apply a one-time level adjustment: reset the Holt-Winters level component to the current 4-week average (310 units/week). Keep the seasonal indices and trend parameters. Re-initialize the model from this new level. +4. Increase alpha temporarily (from 0.15 to 0.25) for the next 8 weeks to allow faster adaptation, then return to the standard alpha. +5. Immediately recalculate safety stock using σ_d from the recent 8 weeks (which reflects the new demand regime), not the trailing 52 weeks. +6. Reduce open POs to match the new run rate. Cancel or defer any POs that would push weeks of supply above 8 at the new demand level. +7. Classify the competitor product as a "regime change event" and add it to the demand planning log. Propose to merchandising that they evaluate their assortment response (match the competitor product, promote Cheerios, or accept the share loss). + +**Key Indicators:** +- Tracking signal trend (is it stabilizing at the new level or still diverging?) +- Competitor product's velocity (is it still growing, or has it plateaued?) +- Category total velocity (is the category growing, or is this a zero-sum shift?) +- Customer switching behavior (if loyalty card data is available) + +**Documentation Required:** +- Tracking signal history showing the drift from normal to ±4.8 +- Before/after forecast comparison at the new demand level +- Safety stock recalculation with the new σ_d +- PO adjustment details (quantities deferred or cancelled) +- Root cause classification (competitive entry, consumer preference shift, etc.) +- Merchandising communication and their response + +**Resolution Timeline:** +- Day 0: Tracking signal triggers model review +- Day 1–3: Confirm regime change vs. temporary dip; analyze root cause +- Day 3–5: Apply level adjustment; recalculate safety stock; adjust POs +- Weeks 2–8: Monitor with elevated alpha; confirm model is tracking the new level +- Week 8: Return alpha to standard; close the event +- Week 12: Retrospective — was the level shift permanent or did it partially reverse? + +**Frequency of Occurrence:** +Regime changes affect 5–10% of SKUs annually. The most common causes are competitive +entry/exit (40%), reformulation or packaging changes (25%), price repositioning (20%), +and distribution changes (15%). The key is detecting them quickly — every week of delay +in responding to a downward regime change adds ~1 week of excess inventory. + +--- + +### Edge Case 6: Phantom Inventory — System Shows Stock, Shelves Are Empty + +**Situation:** +Your highest-velocity SKU in the beverage category (a 24-pack water case, A-item, ~1,200 units/week across 80 stores) has been showing 95%+ in-stock rate in the system, but customer complaints about out-of-stocks have tripled in the past month. The WMS shows 3,400 units at the DC and the stores collectively show 2,100 units on hand. However, three separate stores have reported that they can't find the product despite the system showing 50–80 units each. A partial cycle count at the DC reveals an actual count of 2,100 units — the WMS is overstating by 1,300 units (38% phantom inventory). + +**Why It's Tricky:** +Every replenishment decision for the past several weeks has been based on a position that was 1,300 units higher than reality. The system thinks the DC has 4.7 weeks of supply when it actually has 2.9 weeks. Stores are running out because store-level inventory is also likely overstated (if receiving errors or shrinkage are the cause). The problem is almost certainly not limited to this one SKU — whatever process caused the phantom inventory (receiving errors, system timing, shrinkage) is likely affecting other items. + +**Common Mistake:** +Correcting the inventory in the WMS and moving on. The correction fixes the symptom but not the cause. Next month, phantom inventory will reappear. + +**Expert Approach:** +1. Immediately conduct a full physical count on this SKU at the DC and at the 10 highest-volume stores. Adjust WMS/POS inventory records to match physical counts. +2. Recalculate the inventory position with corrected numbers. You likely need to place an emergency order — the corrected IP is probably below the reorder point. +3. Place an emergency order: the delta between the old (phantom) IP and the corrected IP is 1,300 units at the DC alone, plus whatever store-level adjustments are needed. Rush this order if possible. +4. Investigate the root cause of the phantom inventory: + - **Receiving error:** Were units scanned into the WMS but physically not there? Check receiving logs against PO quantities for the past 60 days. + - **Shrinkage:** Is this a high-theft item? Water cases are not typically theft targets, so this is less likely. + - **System timing:** Is there a lag between physical movement and WMS update (e.g., cross-dock items that are "received" but immediately shipped to stores without a separate ship transaction)? + - **Return processing:** Were damaged/returned units re-entered into available inventory without physical verification? +5. Expand the investigation. Run a phantom inventory screening across all A-items: pull any SKU where the system in-stock rate is > 95% but customer complaints or lost sales proxy metrics (search-to-purchase ratio, substitute purchase rate) indicate stockouts. These are your phantom inventory suspects. +6. Implement a cycle count program targeting high-velocity items quarterly and any item with a discrepancy > 10% between system and physical counts. +7. Adjust safety stock upward by 10–15% for the category until the root cause is resolved and verified, to buffer against ongoing phantom inventory risk. + +**Documentation Required:** +- Physical count vs. system count by location +- Root cause investigation findings +- Emergency order details +- Expanded screening results for other SKUs +- Cycle count program specification +- Safety stock adjustment and rationale + +**Resolution Timeline:** +- Day 0: Customer complaints or lost-sales signals trigger investigation +- Day 0–1: Physical count at DC; confirm phantom inventory exists +- Day 1–2: Adjust WMS records; place emergency order; expand screening to all A-items +- Days 3–7: Physical counts at top 20 stores on the affected SKU +- Weeks 1–2: Root cause investigation across receiving, shrinkage, and system processes +- Week 3: Implement corrective action (process change, cycle count program) +- Month 2–3: Monitor for recurrence; verify corrective action effectiveness + +**Financial Impact:** +Phantom inventory has a dual cost: (1) the lost sales from stockouts that the system didn't +predict (in this case, ~300 units/week × $sell_price = significant revenue), and (2) the +upstream effects — overstated inventory means the replenishment system didn't trigger orders +when it should have, creating a cascading supply gap. For an A-item at 1,200 units/week, +even a 20% phantom inventory rate translates to ~240 lost sales per week, which at $5 retail +is $1,200/week in lost revenue, or ~$62,400/year for a single SKU. + +--- + +### Edge Case 7: Vendor MOQ Conflict — Ordering Constraint vs. Demand Reality + +**Situation:** +You carry a specialty imported Italian pasta brand (5 SKUs, each averaging 30–50 units/week across 60 stores). The vendor's minimum order quantity is 500 units per SKU per order, and they only accept orders on a monthly basis (once per month, delivery in 3 weeks). For a SKU averaging 40 units/week, the MOQ of 500 units represents 12.5 weeks of supply. With a 7-week order cycle (4-week review + 3-week lead time), your target order-up-to level should be about 360 units (7 weeks × 40 + safety stock). The MOQ forces you to order 39% more than you need. + +**Why It's Tricky:** +You can't order less than the MOQ, but ordering 500 units every month means you're always carrying ~5 weeks of excess inventory. Across 5 SKUs, that's 2,500 excess units at ~$3.50 cost each = ~$8,750 in excess inventory investment. The holding cost (25% annually = ~$0.07/unit/week) seems small per unit but adds up to ~$9,100/year in excess carrying cost across the 5 SKUs. This isn't a one-time problem — it recurs every month. + +**Common Mistake:** +Accepting the MOQ without quantifying the cost. Or, alternatively, fighting the vendor on MOQ without considering the alternatives. + +**Expert Approach:** +1. Quantify the total cost of the MOQ constraint: annual excess holding cost ($9,100), waste risk (if shelf life is limited), and opportunity cost of the working capital. +2. Evaluate options in order: + a. **Negotiate a dollar minimum instead of unit minimum:** If you order all 5 SKUs together, the combined order is 2,500 units × $3.50 = $8,750 per order. Propose a $6,000 order minimum with flexibility to allocate across SKUs based on need. Many importers prefer this because they still get a meaningful order. + b. **Extend the review period:** Instead of monthly orders, order every 6 weeks. This increases the target order-up-to level, making the MOQ less excessive. But it also increases safety stock needs. + c. **Accept the MOQ for top 2–3 SKUs and negotiate lower for the bottom 2:** Concentrate volume on the fast movers and ask for 300-unit MOQ on the slowest. + d. **Cross-dock or consolidate with other retailers:** If you're part of a buying group or co-op, combine orders with other members to share the MOQ. + e. **Assess the overage as forward stock:** If the product has 18+ months of shelf life, 12.5 weeks of supply is tolerable. The holding cost may be acceptable relative to the value of carrying the brand. +3. Before negotiating, know your BATNA: are there alternative Italian pasta brands with better terms? What would switching cost (delisting fees, lost loyal customers)? +4. Propose a 6-month trial: "We'd like to test a $5,000 minimum order across the 5 SKUs for Q3 and Q4. If our order frequency and reliability are maintained, we'd like to formalize this for the annual agreement." + +**Key Indicators:** +- Shelf life remaining on excess inventory (critical for food products) +- Sell-through rate of excess units before the next order arrives +- Whether the vendor has other regional customers you could consolidate with +- Total vendor spend as leverage for negotiation + +**Documentation Required:** +- Annual excess holding cost calculation per SKU and total for the vendor +- Vendor negotiation correspondence and outcome +- Comparison of options evaluated (lower MOQ vs. dollar minimum vs. accept overage) +- Any agreed trial terms and review dates + +**Resolution Timeline:** +- Month 0: Quantify the MOQ cost impact across all SKUs from this vendor +- Month 0–1: Prepare negotiation package; identify BATNA (alternative suppliers) +- Month 1: Present to vendor at the next order cycle or QBR +- Month 2: Implement the agreed terms on a 6-month trial basis +- Month 8: Review trial results; formalize in the annual vendor agreement + +**MOQ Impact Calculator (per SKU):** +``` +Excess Units per Order = MOQ − EOQ (or optimal order quantity) +Annual Orders = 52 / (MOQ / Weekly Demand) +Annual Excess Units = Excess per Order × Annual Orders +Annual Excess Holding Cost = Annual Excess Units × Unit Cost × Holding Cost % +``` + +For the pasta example: Excess = 500 − 280 = 220 units per order. Annual orders = 52 / (500/40) = ~4.2. +Annual excess units = 220 × 4.2 = ~924. Holding cost at 25% on $3.50 cost = 924 × $0.875 = ~$809/year. +Across 5 SKUs with similar profiles, that's ~$4,000/year — worth negotiating but not worth losing the brand. + +--- + +### Edge Case 8: Holiday Calendar Shift — Easter Moves 3 Weeks, Forecast Breaks + +**Situation:** +Last year Easter fell on March 31. This year it falls on April 20 — a 3-week shift. Your seasonal candy category (Easter chocolate, jelly beans, marshmallow Peeps) typically sees a 6-week selling season centered on Easter week. Your Holt-Winters model uses 52-week seasonal indices. Because Easter shifted, the model is projecting peak demand in the same calendar weeks as last year (weeks 10–13) rather than the correct weeks (weeks 13–16 this year). The seasonal indices are aligning to the wrong calendar weeks. + +**Why It's Tricky:** +Holt-Winters seasonal indices are indexed to week numbers, not to event dates. A 3-week shift in Easter means the model peaks 3 weeks too early. If you follow the model, you'll over-order for late March (building inventory for a peak that doesn't come) and under-order for mid-April (missing the actual peak). The financial exposure is significant: Easter candy is a $200K–$400K category with 15–20% margins on regular items and near-zero margin on post-Easter clearance. + +**Common Mistake:** +Running the Holt-Winters model without adjusting for the holiday shift. Or manually shifting the seasonal indices but forgetting to shift the promotional calendar, vendor order deadlines, and markdown timing. + +**Expert Approach:** +1. Before the forecasting cycle begins (typically 12–16 weeks before Easter), compute the calendar-week shift: ΔW = Easter_this_year_week − Easter_last_year_week. This year, ΔW = +3 weeks. +2. Shift the seasonal indices: for any SKU with Easter-linked seasonality, shift the 52-week seasonal index array by ΔW positions. Index for week 10 last year now applies to week 13 this year. +3. Apply the same shift to the build schedule: the 6-week selling window moves from weeks 8–13 (last year) to weeks 11–16 (this year). Vendor orders that were placed in January for March delivery now need to be placed for April delivery. +4. Shift the markdown timing: post-Easter clearance moves from week 14 (last year) to week 17 (this year). Any markdown price changes scheduled for the old dates must be updated. +5. Coordinate with store operations: Easter display set dates, endcap resets, and seasonal aisle transitions all shift by 3 weeks. +6. Validate with at least 3 prior Easter years that show similar shifts. Look at 2019 (April 21) as the closest date comparator for demand patterns. +7. Watch for interaction effects: if the shifted Easter overlaps with spring break schedules differently than last year, travel-related demand patterns (convenience stores, airports) may not follow the standard shift formula. +8. Model the "gap" period: the 3 weeks between last year's Easter and this year's Easter will have lower demand than last year's model suggests but higher demand than a non-Easter baseline. Use a blended estimate. + +**Documentation Required:** +- Holiday shift calculation and affected SKUs +- Shifted seasonal indices (before and after) +- Adjusted vendor order schedule +- Adjusted markdown timing +- Promotional calendar updates +- Historical comparisons to similar-dated Easters + +**Financial Impact:** +Easter candy is typically a $200K–$400K category for a mid-size retailer. A 3-week +misalignment in seasonal indices can cause 25–35% of that inventory to be mistimed: +arriving too early (incurring holding cost and space conflict) or peaking when demand +has already shifted. Markdowns on Easter-specific product (chocolate bunnies, egg-shaped +candy) are particularly steep because the product has zero value after Easter weekend. +A mistimed buy can easily cost $30K–$60K in margin erosion on a category this size. + +**Other Holiday Shifts to Monitor:** +- **Thanksgiving:** Always the 4th Thursday of November, but the gap between Thanksgiving + and Christmas (22–29 days) affects holiday season build timing. +- **Ramadan:** Shifts ~11 days earlier each year (lunar calendar). Critical for retailers + with significant Muslim customer demographics. Specialty food demand shifts. +- **Chinese New Year:** Falls between Jan 21 and Feb 20. Affects import lead times from + China by 2–3 weeks (factory closures). +- **Back-to-school:** Not a fixed holiday but a regional event. Northern states start + in late August; Southern states start in early August. A planner managing both regions + needs different seasonal indices for the same categories. + +--- + +### Edge Case 9: Weather-Sensitive Demand Miscalculation — Heat Wave in March + +**Situation:** +An unexpected early heat wave hits the Southeast (temperatures 15–20°F above normal for 10 days in mid-March). Your forecast models are projecting normal March demand for summer-seasonal categories: bottled water, sunscreen, ice cream, fans, and outdoor furniture. POS data on day 2 of the heat wave shows bottled water up 280%, sunscreen up 420%, and ice cream up 190%. Your DC has standard March inventory levels for these categories — roughly 3–4 weeks of supply at normal March rates, which translates to 8–12 days at the spiked demand. + +**Why It's Tricky:** +Weather-driven demand spikes are temporary but intense. The heat wave will end in 10 days, but you'll have stockouts within 5–7 days on the fastest-moving items. Unlike seasonal ramp-up (which is gradual), this is a step-change. Your vendors are also not expecting March orders at summer volumes. And if you over-react and place summer-sized orders, you'll have excess when temperatures normalize, especially for sunscreen (which most customers won't need again until actual summer). + +**Common Mistake:** +Treating the heat wave as the start of summer. Placing orders sized for sustained summer demand when this is a 10-day weather event. Or, alternatively, doing nothing because "March orders are already placed" and letting stores run out. + +**Expert Approach:** +1. Separate items into "weather-temporary" and "weather-pull-forward" categories: + - **Weather-temporary:** Items consumed during the heat wave that won't reduce summer demand (e.g., ice cream eaten today doesn't reduce ice cream eaten in July). These need incremental inventory for the event only. + - **Weather-pull-forward:** Items purchased now that would have been purchased later (e.g., sunscreen, fans). These pull demand from the summer season — over-ordering now creates a surplus later. +2. For weather-temporary items (water, ice cream): place an emergency order sized for 10 days of elevated demand minus current inventory. Use regional distributors or DSD (direct-store-delivery) vendors who can respond in 24–48 hours. +3. For weather-pull-forward items (sunscreen, fans, outdoor furniture): order conservatively. These customers are buying their summer supply early. Order enough to cover the current spike (5–7 days of additional supply) but reduce your planned April/May orders by the same amount. +4. Communicate to stores: allocate weather-sensitive items based on geographic proximity to the heat wave. Stores in the affected region get priority; stores in unaffected northern markets maintain normal allocations. +5. After the heat wave: analyze the demand transfer. For pull-forward categories, compute how much April/May demand was pulled into March and adjust the summer season forecast downward accordingly. +6. Do NOT let the heat wave contaminate the seasonal baseline model. Tag these 10 days as "weather event" in the demand history so the model ignores them when computing seasonal indices for next year. + +**Documentation Required:** +- Weather forecast data (NWS source) and affected geographic regions +- Category classification: weather-temporary vs. weather-pull-forward +- Emergency order details by category +- Store allocation rules during the event +- Post-event demand transfer analysis +- Demand history tagging for model hygiene + +**Resolution Timeline:** +- Day 0–1: Weather alert triggers category review; classify temporary vs. pull-forward +- Day 1–2: Place emergency orders for weather-temporary items via DSD and regional distributors +- Day 2–3: Adjust allocations to stores in the affected region; reduce allocations to unaffected regions +- Day 5–7: Monitor if the heat wave is extending beyond 10 days; adjust orders if so +- Post-event (day 12–15): Analyze demand transfer for pull-forward categories +- Post-event (day 20–30): Adjust forward forecasts for summer categories downward by the pull-forward amount +- Post-event: Tag affected days in demand history; run model hygiene cleanup + +**Common Weather Events and Their Demand Impact:** + +| Weather Event | Key Categories Affected | Typical Demand Change | Duration | +|---|---|---|---| +| Heat wave (10+ days above normal) | Water, ice cream, fans, sunscreen, outdoor | +100–400% | 7–14 days | +| Cold snap (10+ days below normal) | Soup, hot chocolate, space heaters, rock salt | +80–250% | 5–10 days | +| Hurricane / major storm (pre-landfall) | Water, batteries, flashlights, canned food, generators | +500–1000% | 2–4 days pre-event | +| Blizzard / ice storm | Bread, milk, eggs ("French toast index"), shovels | +200–500% | 1–3 days pre-event | +| Extended rain | Umbrellas, rain gear, indoor entertainment | +50–150% | Duration of event | + +--- + +### Edge Case 10: End-of-Life Transition — Old and New SKU Cannibalize Each Other + +**Situation:** +A major brand is transitioning from V1 to V2 of a popular household cleaner (improved formula, new packaging, same price point). V1 is a B-item averaging 250 units/week. V2 will launch in 4 weeks with planned distribution to all 100 stores. The manufacturer is offering a one-time V2 introductory buy at a 15% discount. The complication: V1 and V2 will coexist on shelf for 6–10 weeks during the transition. The brand is not offering to buy back unsold V1 inventory. You currently have 3,200 units of V1 in the system (DC + stores = ~12.8 weeks of supply at the current rate). + +**Why It's Tricky:** +During the transition, V1 and V2 will cannibalize each other. Total brand demand will likely remain flat or grow slightly (V2 launch may attract trial), but the split between V1 and V2 is uncertain. If V2 takes off quickly, V1 demand collapses and you're stuck with excess. If V2 launches slowly (customer resistance to change), V1 holds demand longer. The manufacturer's introductory discount pressures you to buy heavily on V2, but that bet compounds the V1 excess risk. + +**Common Mistake:** +Buying V2 aggressively to capture the introductory discount while ignoring the V1 run-down plan. Six weeks later, V1 is occupying shelf space, DC slots, and working capital while V2 is the seller. + +**Expert Approach:** +1. Model the transition as a combined brand forecast with a split ratio that shifts over time: + - Weeks 1–2 (post-V2 launch): V1 retains 70% of brand volume, V2 captures 30% (trial phase) + - Weeks 3–4: V1 at 50%, V2 at 50% + - Weeks 5–6: V1 at 30%, V2 at 70% + - Weeks 7+: V1 at 10%, V2 at 90% + These ratios are estimates — adjust based on brand's historical transition data and customer research. +2. Run down V1 inventory intentionally. Stop reordering V1 immediately — you have 12.8 weeks at current rate, but demand will decline per the split model. Compute V1 sales under the declining split: ~250 × (0.7 + 0.7 + 0.5 + 0.5 + 0.3 + 0.3 + 0.1 + 0.1) = ~800 units over 8 weeks. You have 3,200 in the system — you'll have ~2,400 excess. +3. Initiate V1 markdowns early — don't wait for the product to become unsellable. Week 1 post-V2 launch: take 20% off V1 to accelerate sell-through. Week 4: 40% off. Week 6: liquidate or donate any remainder. +4. Size the V2 introductory buy conservatively: 4 weeks of supply at the V2 split rate, not at the full brand rate. That's ~250 × (0.3 + 0.5 + 0.7 + 0.9) = ~600 units for the first 4 weeks. Take the introductory discount on 600–800 units, not the 2,000+ the manufacturer will suggest. +5. Negotiate with the manufacturer: request unsold V1 return credit or a markdown fund contribution. Most CPG brands transitioning formulas will contribute 25–50% of the V1 markdown cost if asked, because they want V1 off shelf to drive V2 trial. +6. Track the actual V1/V2 split weekly and adjust. If V2 takes off faster than modeled, accelerate V1 markdowns. If V2 is slow, hold V1 price and defer V2 reorder. + +**Documentation Required:** +- Combined brand forecast with V1/V2 split ratios +- V1 run-down plan with markdown schedule +- V2 introductory buy calculation +- Manufacturer negotiation on return credit / markdown fund +- Weekly V1/V2 split tracking vs. plan + +**Resolution Timeline:** +- Weeks -6 to -4: Build V1/V2 combined forecast; compute V1 run-down plan +- Week -4: Stop V1 reorders; negotiate manufacturer markdown support +- Week -2: Set V1 markdown schedule; finalize V2 introductory buy +- Week 0: V2 launches; V1 takes first markdown (20% off) +- Week 4: V1 takes second markdown (40% off) if excess remains +- Week 6: Liquidate any remaining V1 inventory +- Week 8: Transition complete; V2 on standard replenishment + +**Financial Modeling:** +Compute the total transition cost: V1 markdown cost (units × markdown depth × unit cost) + +V1 liquidation loss + V2 introductory buy discount benefit − manufacturer markdown fund. +For this example: if 2,400 V1 units remain and average markdown recovery is 60% of cost, +the V1 loss is 2,400 × $cost × 0.40. The V2 introductory buy at 15% discount on 600–800 +units saves ~$cost × 0.15 × 700 = modest savings. Net transition cost is typically $2K–$5K +for a brand of this size, which is the cost of maintaining a clean shelf transition. + +--- + +### Edge Case 11: Multi-Location Allocation During Supply Constraint — Not Enough for Everyone + +**Situation:** +A critical supplier shortage has reduced your supply of a top-selling protein powder (A-item, $34.99, ~900 units/week across 120 stores) by 60% for the next 6 weeks. You'll receive approximately 360 units/week instead of the normal 900. You cannot source from an alternative supplier — this is a branded product with an exclusive distribution agreement. The 120 stores have widely varying velocities: the top 20 stores sell 40% of total volume, the middle 40 sell 35%, and the bottom 60 sell 25%. + +**Why It's Tricky:** +You can't serve all stores at their normal levels. Pro-rata allocation (giving each store 40% of their normal replenishment) seems fair but is suboptimal — it guarantees every store runs out rather than keeping some stores in-stock. But fully stocking the top 20 stores and cutting off the bottom 60 creates customer service issues at those locations and potential legal/franchise issues if you have contractual obligations. + +**Common Mistake:** +Pro-rata allocation across all stores. Every store gets 40% of normal, every store stocks out in ~4 days, and the customer experience is universally bad rather than selectively managed. + +**Expert Approach:** +1. Calculate the allocation by store tier to maximize total units sold (minimize lost sales): + - Top 20 stores: allocate at 70% of their normal rate (252 units/week). These stores have the highest traffic; even partial stock generates more sales per unit than full stock at a low-traffic store. + - Middle 40 stores: allocate at 35% of their normal rate (~110 units/week). Enough to maintain some presence. + - Bottom 60 stores: allocate at 15% of their normal rate (~54 units/week). Maintain minimum presentation stock only. + - Total: 252 + 110 + 54 = ~416 units/week. This exceeds the 360 available, so scale proportionally. +2. Implement a maximum per-customer purchase limit at the store level (2 units per transaction) to prevent stockpiling. +3. Communicate transparently to store managers: "Protein powder is on constrained allocation for the next 6 weeks due to supplier shortage. Your allocation is [X] units/week. We'll resume normal replenishment in [date]." +4. Monitor sell-through rates at each tier. If the top-20 stores are selling out in 3 days, they're effectively under-allocated. If bottom-60 stores are carrying inventory into the next week, they're over-allocated. Adjust weekly. +5. Prepare substitution signage for stores: "Looking for [brand]? Try [alternative] while supplies are limited." Even without a direct substitute supplier, suggesting a different brand/format captures some sales that would otherwise be lost. +6. Track lost sales using a proxy: compare same-store sales of complementary items (protein bars, shakers) — a decline suggests customers are going elsewhere entirely. + +**Documentation Required:** +- Allocation model with tier breakdowns +- Weekly allocation vs. sell-through by tier +- Customer purchase limit implementation +- Lost sales estimate methodology and tracking +- Supplier communication and expected resolution timeline + +**Resolution Timeline:** +- Day 0: Supplier confirms constraint; demand planner receives allocation +- Day 0–1: Build tiered allocation model; communicate to store operations +- Day 1–2: Implement POS purchase limits; prepare substitution signage +- Weekly for 6 weeks: Adjust allocations based on actual sell-through by tier +- Week 6: Supplier confirms return to normal supply +- Week 7–8: Rebuild safety stock at normal replenishment rates + +**Financial Impact:** +Lost sales during a 60% supply constraint on a 900 units/week A-item at $34.99 retail: +(900 − 360) × $34.99 × 6 weeks = ~$113,367 in lost revenue. With tiered allocation +optimizing sell-through, you can recapture 15–25% of the otherwise lost sales compared +to naive pro-rata allocation, worth $17K–$28K in recovered revenue. The allocation +optimization effort pays for itself many times over. + +--- + +### Edge Case 12: Demand Forecast Consensus Meeting Override — Sales Team Inflates Forecast + +**Situation:** +During the monthly S&OP demand review, the sales team insists on overriding the statistical forecast for a key product line (premium pet food, 15 SKUs, ~$1.2M annual revenue). The statistical forecast projects flat demand at ~$100K/month. The sales team argues that a new distribution agreement with a pet specialty chain will add $30K/month starting next month. They want the forecast increased to $130K/month across all 15 SKUs proportionally. However, the distribution agreement is not yet signed (it's in "final review"), the specialty chain hasn't confirmed shelf dates, and the sales team has a history of overestimating new account volume by 40–60%. + +**Why It's Tricky:** +The sales team may be right — the distribution deal is real and the incremental volume is plausible. But "plausible" is not "certain." If you accept the override and the deal delays by 2 months (common), you'll have 2 months of $30K/month in excess inventory ($60K), which for pet food with 12-month shelf life is manageable but ties up working capital. If you reject the override and the deal closes on time, you'll be short $30K/month and unable to serve the new account, potentially killing the deal. + +**Common Mistake:** +Either accepting the sales team's number at face value (leading to chronic over-forecasting) or rejecting it entirely (leading to under-investment in growth). + +**Expert Approach:** +1. Never accept or reject an override without a probability-weighted approach. Ask the sales team to commit to a probability of close and timing: + - Probability the deal closes: 70% (sales team's estimate — discount to 50% based on historical calibration) + - If it closes, when will volume start? 4 weeks (sales team) — add 4 weeks for historical optimism = 8 weeks realistic + - If it closes, what's the ramp rate? Rarely 100% from day 1. Model 50% in month 1, 75% in month 2, 100% in month 3. +2. Compute the expected value override: $30K × 50% probability × ramp rate = $7.5K in month 1, $11.25K in month 2, $15K in month 3. +3. Apply this as a staged override, not a flat $30K increase. Month 1: $107.5K. Month 2: $111.25K. Month 3: $115K. +4. Set a kill trigger: if the deal hasn't closed by month 2, remove the override entirely and return to the statistical forecast. Do not carry speculative overrides indefinitely. +5. Track the outcome: did the deal close? When? At what volume? Use this to calibrate the sales team's future override accuracy and adjust the probability discount accordingly. +6. Distribute the override unevenly across SKUs: the new account likely won't carry all 15 SKUs. Ask the sales team which 5–8 SKUs the new account will stock, and concentrate the override there. + +**Documentation Required:** +- S&OP meeting notes with the original override request +- Probability-weighted override calculation +- Staged implementation plan by month and SKU +- Kill trigger date and conditions +- Post-event accuracy tracking + +**Resolution Timeline:** +- S&OP meeting: Capture the override request; apply probability weighting +- Day 1–3: Compute the staged override and distribute across relevant SKUs +- Week 1: Adjust POs to reflect the staged override (not the full $30K) +- Week 4 (if deal not signed): Reduce override by 50% +- Week 8 (if deal still not signed): Remove override entirely; return to statistical forecast +- When deal closes: Ramp up based on actual account setup timeline +- Month 3 post-close: Compare actual volume to the staged override; calibrate sales team accuracy + +**Historical Calibration:** +Track the accuracy of sales team overrides over time. Maintain a simple table: + +| Override Source | Override Count (trailing 12 months) | Avg. Override Amount | Avg. Actual Result | Realization Rate | +|---|---|---|---|---| +| Sales team — new accounts | 8 | +$25K/month | +$12K/month | 48% | +| Sales team — existing account growth | 12 | +$15K/month | +$9K/month | 60% | +| Marketing — promotional lift | 6 | +40% lift | +32% lift | 80% | +| Category management — trend calls | 5 | ±20% | ±8% | 40% | + +This calibration table allows you to apply evidence-based probability discounts to future +overrides. A sales team with a 48% realization rate on new account overrides should have +their stated volume multiplied by 0.48, not accepted at face value. diff --git a/web-app/public/skills/ios-developer/SKILL.md b/web-app/public/skills/ios-developer/SKILL.md index 8fa9a17d..95edf2fc 100644 --- a/web-app/public/skills/ios-developer/SKILL.md +++ b/web-app/public/skills/ios-developer/SKILL.md @@ -1,6 +1,7 @@ --- name: ios-developer -description: "Develop native iOS applications with Swift/SwiftUI. Masters iOS 18," +description: | + Develop native iOS applications with Swift/SwiftUI. Masters iOS 18, SwiftUI, UIKit integration, Core Data, networking, and App Store optimization. Use PROACTIVELY for iOS-specific features, App Store optimization, or native iOS development. diff --git a/web-app/public/skills/java-pro/SKILL.md b/web-app/public/skills/java-pro/SKILL.md index 3b7e0a08..a070be0e 100644 --- a/web-app/public/skills/java-pro/SKILL.md +++ b/web-app/public/skills/java-pro/SKILL.md @@ -1,6 +1,7 @@ --- name: java-pro -description: "Master Java 21+ with modern features like virtual threads, pattern" +description: | + Master Java 21+ with modern features like virtual threads, pattern matching, and Spring Boot 3.x. Expert in the latest Java ecosystem including GraalVM, Project Loom, and cloud-native patterns. Use PROACTIVELY for Java development, microservices architecture, or performance optimization. diff --git a/web-app/public/skills/javascript-pro/SKILL.md b/web-app/public/skills/javascript-pro/SKILL.md index 2b4f0d18..a3c53a04 100644 --- a/web-app/public/skills/javascript-pro/SKILL.md +++ b/web-app/public/skills/javascript-pro/SKILL.md @@ -1,6 +1,7 @@ --- name: javascript-pro -description: "Master modern JavaScript with ES6+, async patterns, and Node.js" +description: | + Master modern JavaScript with ES6+, async patterns, and Node.js APIs. Handles promises, event loops, and browser/Node compatibility. Use PROACTIVELY for JavaScript optimization, async debugging, or complex JS patterns. diff --git a/web-app/public/skills/julia-pro/SKILL.md b/web-app/public/skills/julia-pro/SKILL.md index d0063344..c38ccb0e 100644 --- a/web-app/public/skills/julia-pro/SKILL.md +++ b/web-app/public/skills/julia-pro/SKILL.md @@ -1,6 +1,7 @@ --- name: julia-pro -description: "Master Julia 1.10+ with modern features, performance optimization," +description: | + Master Julia 1.10+ with modern features, performance optimization, multiple dispatch, and production-ready practices. Expert in the Julia ecosystem including package management, scientific computing, and high-performance numerical code. Use PROACTIVELY for Julia development, diff --git a/web-app/public/skills/kubernetes-architect/SKILL.md b/web-app/public/skills/kubernetes-architect/SKILL.md index b8ac829c..3c9d06e2 100644 --- a/web-app/public/skills/kubernetes-architect/SKILL.md +++ b/web-app/public/skills/kubernetes-architect/SKILL.md @@ -1,6 +1,7 @@ --- name: kubernetes-architect -description: "Expert Kubernetes architect specializing in cloud-native" +description: | + Expert Kubernetes architect specializing in cloud-native infrastructure, advanced GitOps workflows (ArgoCD/Flux), and enterprise container orchestration. Masters EKS/AKS/GKE, service mesh (Istio/Linkerd), progressive delivery, multi-tenancy, and platform engineering. Handles diff --git a/web-app/public/skills/legacy-modernizer/SKILL.md b/web-app/public/skills/legacy-modernizer/SKILL.md index daf6efe5..516ba7f8 100644 --- a/web-app/public/skills/legacy-modernizer/SKILL.md +++ b/web-app/public/skills/legacy-modernizer/SKILL.md @@ -1,6 +1,7 @@ --- name: legacy-modernizer -description: "Refactor legacy codebases, migrate outdated frameworks, and" +description: | + Refactor legacy codebases, migrate outdated frameworks, and implement gradual modernization. Handles technical debt, dependency updates, and backward compatibility. Use PROACTIVELY for legacy system updates, framework migrations, or technical debt reduction. diff --git a/web-app/public/skills/legal-advisor/SKILL.md b/web-app/public/skills/legal-advisor/SKILL.md index 267335a8..91ba5e08 100644 --- a/web-app/public/skills/legal-advisor/SKILL.md +++ b/web-app/public/skills/legal-advisor/SKILL.md @@ -1,6 +1,7 @@ --- name: legal-advisor -description: "Draft privacy policies, terms of service, disclaimers, and legal" +description: | + Draft privacy policies, terms of service, disclaimers, and legal notices. Creates GDPR-compliant texts, cookie policies, and data processing agreements. Use PROACTIVELY for legal documentation, compliance texts, or regulatory requirements. diff --git a/web-app/public/skills/linkedin-cli/SKILL.md b/web-app/public/skills/linkedin-cli/SKILL.md new file mode 100644 index 00000000..8401c8f0 --- /dev/null +++ b/web-app/public/skills/linkedin-cli/SKILL.md @@ -0,0 +1,536 @@ +--- +name: linkedin-cli +description: "Use when automating LinkedIn via CLI: fetch profiles, search people/companies, send messages, manage connections, create posts, and Sales Navigator." +source: community +risk: safe +--- + +## When to Use + +Use this skill when you need to automate LinkedIn tasks such as profile fetching, connection management, or post creation via CLI, especially when integrated into automated workflows. + +# LinkedIn Skill + +You have access to `linkedin` – a CLI tool for LinkedIn automation. Use it to fetch profiles, search people and companies, send messages, manage connections, create posts, react, comment, and more. + +Each command sends a request to Linked API, which runs a real cloud browser to perform the action on LinkedIn. Operations are **not instant** – expect 30 seconds to several minutes depending on complexity. + +If `linkedin` is not available, install it: + +```bash +npm install -g @linkedapi/linkedin-cli +``` + +## Authentication + +If a command fails with exit code 2 (authentication error), ask the user to set up their account: + +1. Go to [app.linkedapi.io](https://app.linkedapi.io) and sign up or log in +2. Connect their LinkedIn account +3. Copy the **Linked API Token** and **Identification Token** from the dashboard + +Once the user provides the tokens, run: + +```bash +linkedin setup --linked-api-token=TOKEN --identification-token=TOKEN +``` + +## When to Use + +Use this skill when you need to **orchestrate LinkedIn actions from scripts or an AI agent** instead of clicking through the web UI: + +- Building outreach, research, or recruiting workflows that rely on LinkedIn data and messaging. +- Enriching leads or accounts by fetching people and company profiles in bulk. +- Coordinating multi-step Sales Navigator or workflow runs where JSON output and exit codes are required. + +Always respect LinkedIn’s terms of service, local regulations, and your organisation’s compliance policies when using automation against real accounts. + +## Global Flags + +Always use `--json` and `-q` for machine-readable output: + +```bash +linkedin --json -q +``` + +| Flag | Description | +| ----------------------- | --------------------------------------- | +| `--json` | Structured JSON output | +| `--quiet` / `-q` | Suppress stderr progress messages | +| `--fields name,url,...` | Select specific fields in output | +| `--no-color` | Disable colors | +| `--account "Name"` | Use a specific account for this command | + +## Output Format + +Success: + +```json +{ "success": true, "data": { "name": "John Doe", "headline": "Engineer" } } +``` + +Error: + +```json +{ + "success": false, + "error": { "type": "personNotFound", "message": "Person not found" } +} +``` + +Exit code 0 means the API call succeeded – always check the `success` field for the action outcome. Non-zero exit codes indicate infrastructure errors: + +| Exit Code | Meaning | +| --------- | ------------------------------------------------------------------------------------------- | +| 0 | Success (check `success` field – action may have returned an error like "person not found") | +| 1 | General/unexpected error | +| 2 | Missing or invalid tokens | +| 3 | Subscription/plan required | +| 4 | LinkedIn account issue | +| 5 | Invalid arguments | +| 6 | Rate limited | +| 7 | Network error | +| 8 | Workflow timeout (workflowId returned for recovery) | + +## Commands + +### Fetch a Person Profile + +```bash +linkedin person fetch [flags] --json -q +``` + +Optional flags to include additional data: + +- `--experience` – work history +- `--education` – education history +- `--skills` – skills list +- `--languages` – languages +- `--posts` – recent posts (with `--posts-limit N`, `--posts-since TIMESTAMP`) +- `--comments` – recent comments (with `--comments-limit N`, `--comments-since TIMESTAMP`) +- `--reactions` – recent reactions (with `--reactions-limit N`, `--reactions-since TIMESTAMP`) + +Only request additional data when needed – each flag increases execution time. + +```bash +# Basic profile +linkedin person fetch https://www.linkedin.com/in/username --json -q + +# With experience and education +linkedin person fetch https://www.linkedin.com/in/username --experience --education --json -q + +# With last 5 posts +linkedin person fetch https://www.linkedin.com/in/username --posts --posts-limit 5 --json -q +``` + +### Search People + +```bash +linkedin person search [flags] --json -q +``` + +| Flag | Description | +| ---------------------- | -------------------------------------- | +| `--term` | Search keyword or phrase | +| `--limit` | Max results | +| `--first-name` | Filter by first name | +| `--last-name` | Filter by last name | +| `--position` | Filter by job position | +| `--locations` | Comma-separated locations | +| `--industries` | Comma-separated industries | +| `--current-companies` | Comma-separated current company names | +| `--previous-companies` | Comma-separated previous company names | +| `--schools` | Comma-separated school names | + +```bash +linkedin person search --term "product manager" --locations "San Francisco" --json -q +linkedin person search --current-companies "Google" --position "Engineer" --limit 20 --json -q +``` + +### Fetch a Company + +```bash +linkedin company fetch [flags] --json -q +``` + +Optional flags: + +- `--employees` – include employees +- `--dms` – include decision makers +- `--posts` – include company posts + +Employee filters (require `--employees`): + +| Flag | Description | +| ------------------------ | ---------------------------- | +| `--employees-limit` | Max employees to retrieve | +| `--employees-first-name` | Filter by first name | +| `--employees-last-name` | Filter by last name | +| `--employees-position` | Filter by position | +| `--employees-locations` | Comma-separated locations | +| `--employees-industries` | Comma-separated industries | +| `--employees-schools` | Comma-separated school names | + +| Flag | Description | +| --------------- | -------------------------------------------------- | +| `--dms-limit` | Max decision makers to retrieve (requires `--dms`) | +| `--posts-limit` | Max posts to retrieve (requires `--posts`) | +| `--posts-since` | Posts since ISO timestamp (requires `--posts`) | + +```bash +# Basic company info +linkedin company fetch https://www.linkedin.com/company/name --json -q + +# With employees filtered by position +linkedin company fetch https://www.linkedin.com/company/name --employees --employees-position "Engineer" --json -q + +# With decision makers and posts +linkedin company fetch https://www.linkedin.com/company/name --dms --posts --posts-limit 10 --json -q +``` + +### Search Companies + +```bash +linkedin company search [flags] --json -q +``` + +| Flag | Description | +| -------------- | ------------------------------------------------------------------------------------------------------------ | +| `--term` | Search keyword | +| `--limit` | Max results | +| `--sizes` | Comma-separated sizes: `1-10`, `11-50`, `51-200`, `201-500`, `501-1000`, `1001-5000`, `5001-10000`, `10001+` | +| `--locations` | Comma-separated locations | +| `--industries` | Comma-separated industries | + +```bash +linkedin company search --term "fintech" --sizes "11-50,51-200" --json -q +``` + +### Send a Message + +```bash +linkedin message send '' --json -q +``` + +Text up to 1900 characters. Wrap the message in single quotes to avoid shell interpretation issues. + +```bash +linkedin message send https://www.linkedin.com/in/username 'Hey, loved your latest post!' --json -q +``` + +### Get Conversation + +```bash +linkedin message get [--since TIMESTAMP] --json -q +``` + +The first call for a conversation triggers a background sync and may take longer. Subsequent calls are faster. + +```bash +linkedin message get https://www.linkedin.com/in/username --json -q +linkedin message get https://www.linkedin.com/in/username --since 2024-01-15T10:30:00Z --json -q +``` + +### Connection Management + +#### Check connection status + +```bash +linkedin connection status --json -q +``` + +#### Send connection request + +```bash +linkedin connection send [--note 'text'] [--email user@example.com] --json -q +``` + +#### List connections + +```bash +linkedin connection list [flags] --json -q +``` + +| Flag | Description | +| ---------------------- | ------------------------------------------------------------------------------------ | +| `--limit` | Max connections to return | +| `--since` | Only connections made since ISO timestamp (only works when no filter flags are used) | +| `--first-name` | Filter by first name | +| `--last-name` | Filter by last name | +| `--position` | Filter by job position | +| `--locations` | Comma-separated locations | +| `--industries` | Comma-separated industries | +| `--current-companies` | Comma-separated current company names | +| `--previous-companies` | Comma-separated previous company names | +| `--schools` | Comma-separated school names | + +```bash +linkedin connection list --limit 50 --json -q +linkedin connection list --current-companies "Google" --position "Engineer" --json -q +linkedin connection list --since 2024-01-01T00:00:00Z --json -q +``` + +#### List pending outgoing requests + +```bash +linkedin connection pending --json -q +``` + +#### Withdraw a pending request + +```bash +linkedin connection withdraw [--no-unfollow] --json -q +``` + +By default, withdrawing also unfollows the person. Use `--no-unfollow` to keep following. + +#### Remove a connection + +```bash +linkedin connection remove --json -q +``` + +### Posts + +#### Fetch a post + +```bash +linkedin post fetch [flags] --json -q +``` + +| Flag | Description | +| -------------------- | ------------------------------------------------------------------ | +| `--comments` | Include comments | +| `--reactions` | Include reactions | +| `--comments-limit` | Max comments to retrieve (requires `--comments`) | +| `--comments-sort` | Sort order: `mostRelevant` or `mostRecent` (requires `--comments`) | +| `--comments-replies` | Include replies to comments (requires `--comments`) | +| `--reactions-limit` | Max reactions to retrieve (requires `--reactions`) | + +```bash +linkedin post fetch https://www.linkedin.com/posts/username_activity-123 --json -q + +# With comments sorted by most recent, including replies +linkedin post fetch https://www.linkedin.com/posts/username_activity-123 \ + --comments --comments-sort mostRecent --comments-replies --json -q +``` + +#### Create a post + +```bash +linkedin post create '' [flags] --json -q +``` + +| Flag | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------------ | +| `--company-url` | Post on behalf of a company page (requires admin access) | +| `--attachments` | Attachment as `url:type` or `url:type:name`. Types: `image`, `video`, `document`. Can be specified multiple times. | + +Attachment limits: up to 9 images, or 1 video, or 1 document. Cannot mix types. + +```bash +linkedin post create 'Excited to share our latest update!' --json -q + +# With a document +linkedin post create 'Our Q4 report' \ + --attachments "https://example.com/report.pdf:document:Q4 Report" --json -q + +# Post as a company +linkedin post create 'Company announcement' \ + --company-url https://www.linkedin.com/company/name --json -q +``` + +#### React to a post + +```bash +linkedin post react --type [--company-url ] --json -q +``` + +Reaction types: `like`, `love`, `support`, `celebrate`, `insightful`, `funny`. + +```bash +linkedin post react https://www.linkedin.com/posts/username_activity-123 --type like --json -q + +# React on behalf of a company +linkedin post react https://www.linkedin.com/posts/username_activity-123 --type celebrate \ + --company-url https://www.linkedin.com/company/name --json -q +``` + +#### Comment on a post + +```bash +linkedin post comment '' [--company-url ] --json -q +``` + +Text up to 1000 characters. + +```bash +linkedin post comment https://www.linkedin.com/posts/username_activity-123 'Great insights!' --json -q + +# Comment on behalf of a company +linkedin post comment https://www.linkedin.com/posts/username_activity-123 'Well said!' \ + --company-url https://www.linkedin.com/company/name --json -q +``` + +### Statistics + +```bash +# Social Selling Index +linkedin stats ssi --json -q + +# Performance analytics (profile views, post impressions, search appearances) +linkedin stats performance --json -q + +# API usage for a date range +linkedin stats usage --start 2024-01-01T00:00:00Z --end 2024-01-31T00:00:00Z --json -q +``` + +### Sales Navigator + +Requires a LinkedIn Sales Navigator subscription. Uses hashed URLs for person/company lookups. + +#### Fetch person + +```bash +linkedin navigator person fetch --json -q +``` + +#### Search people + +```bash +linkedin navigator person search [flags] --json -q +``` + +| Flag | Description | +| ----------------------- | ------------------------------------------------------------------------------------------- | +| `--term` | Search keyword or phrase | +| `--limit` | Max results | +| `--first-name` | Filter by first name | +| `--last-name` | Filter by last name | +| `--position` | Filter by job position | +| `--locations` | Comma-separated locations | +| `--industries` | Comma-separated industries | +| `--current-companies` | Comma-separated current company names | +| `--previous-companies` | Comma-separated previous company names | +| `--schools` | Comma-separated school names | +| `--years-of-experience` | Comma-separated ranges: `lessThanOne`, `oneToTwo`, `threeToFive`, `sixToTen`, `moreThanTen` | + +```bash +linkedin navigator person search --term "VP Marketing" --locations "United States" --json -q +linkedin navigator person search --years-of-experience "moreThanTen" --position "CEO" --json -q +``` + +#### Fetch company + +```bash +linkedin navigator company fetch [flags] --json -q +``` + +Optional flags: + +- `--employees` – include employees +- `--dms` – include decision makers + +Employee filters (require `--employees`): + +| Flag | Description | +| --------------------------------- | -------------------------------------------------- | +| `--employees-limit` | Max employees to retrieve | +| `--employees-first-name` | Filter by first name | +| `--employees-last-name` | Filter by last name | +| `--employees-positions` | Comma-separated positions | +| `--employees-locations` | Comma-separated locations | +| `--employees-industries` | Comma-separated industries | +| `--employees-schools` | Comma-separated school names | +| `--employees-years-of-experience` | Comma-separated experience ranges | +| `--dms-limit` | Max decision makers to retrieve (requires `--dms`) | + +```bash +linkedin navigator company fetch https://www.linkedin.com/sales/company/97ural --employees --dms --json -q +linkedin navigator company fetch https://www.linkedin.com/sales/company/97ural \ + --employees --employees-positions "Engineer,Designer" --employees-locations "Europe" --json -q +``` + +#### Search companies + +```bash +linkedin navigator company search [flags] --json -q +``` + +| Flag | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------ | +| `--term` | Search keyword | +| `--limit` | Max results | +| `--sizes` | Comma-separated sizes: `1-10`, `11-50`, `51-200`, `201-500`, `501-1000`, `1001-5000`, `5001-10000`, `10001+` | +| `--locations` | Comma-separated locations | +| `--industries` | Comma-separated industries | +| `--revenue-min` | Min annual revenue in M USD: `0`, `0.5`, `1`, `2.5`, `5`, `10`, `20`, `50`, `100`, `500`, `1000` | +| `--revenue-max` | Max annual revenue in M USD: `0.5`, `1`, `2.5`, `5`, `10`, `20`, `50`, `100`, `500`, `1000`, `1000+` | + +```bash +linkedin navigator company search --term "fintech" --sizes "11-50,51-200" --json -q +linkedin navigator company search --revenue-min 10 --revenue-max 100 --locations "United States" --json -q +``` + +#### Send InMail + +```bash +linkedin navigator message send '' --subject '' --json -q +``` + +Text up to 1900 characters. Subject up to 80 characters. + +```bash +linkedin navigator message send https://www.linkedin.com/in/username \ + 'Would love to chat about API integrations' --subject 'Partnership Opportunity' --json -q +``` + +#### Get Sales Navigator conversation + +```bash +linkedin navigator message get [--since TIMESTAMP] --json -q +``` + +### Custom Workflows + +Execute a custom workflow definition from a file, stdin, or inline: + +```bash +# From file +linkedin workflow run --file workflow.json --json -q + +# From stdin +cat workflow.json | linkedin workflow run --json -q + +# Inline +echo '{"actions":[...]}' | linkedin workflow run --json -q +``` + +Check workflow status or wait for completion: + +```bash +linkedin workflow status --json -q +linkedin workflow status --wait --json -q +``` + +See [Building Workflows](https://linkedapi.io/docs/building-workflows/) for the workflow JSON schema. + +### Account Management + +```bash +linkedin account list # List accounts (* = active) +linkedin account switch "Name" # Switch active account +linkedin account rename "Name" --name "New Name" # Rename account +linkedin reset # Remove active account +linkedin reset --all # Remove all accounts +``` + +## Important Behavior + +- **Sequential execution.** All operations for an account run one at a time. Multiple requests queue up. +- **Not instant.** A real browser navigates LinkedIn – expect 30 seconds to several minutes per operation. +- **Timestamps in UTC.** All dates and times are in UTC. +- **Single quotes for text arguments.** Use single quotes around message text, post text, and comments to avoid shell interpretation issues with special characters. +- **Action limits.** Per-account limits are configurable on the platform. A `limitExceeded` error means the limit was reached. +- **URL normalization.** All LinkedIn URLs in responses are normalized to `https://www.linkedin.com/...` format without trailing slashes. +- **Null fields.** Fields that are unavailable are returned as `null` or `[]`, not omitted. diff --git a/web-app/public/skills/logistics-exception-management/SKILL.md b/web-app/public/skills/logistics-exception-management/SKILL.md new file mode 100644 index 00000000..c24f262e --- /dev/null +++ b/web-app/public/skills/logistics-exception-management/SKILL.md @@ -0,0 +1,217 @@ +--- +name: logistics-exception-management +description: > + Codified expertise for handling freight exceptions, shipment delays, + damages, losses, and carrier disputes. Informed by logistics professionals + with 15+ years operational experience. Includes escalation protocols, + carrier-specific behaviours, claims procedures, and judgment frameworks. + Use when handling shipping exceptions, freight claims, delivery issues, + or carrier disputes. +license: Apache-2.0 +version: 1.0.0 +homepage: https://github.com/evos-ai/evos-capabilities +risk: safe +source: https://github.com/ai-evos/agent-skills +metadata: + author: evos + clawdbot: + emoji: "📦" +--- + +## When to Use + +Use this skill when dealing with deviations from planned logistics operations, such as transit delays, damaged shipments, lost cargo, or when initiating and managing claims and disputes with freight carriers. + +# Logistics Exception Management + +## Role and Context + +You are a senior freight exceptions analyst with 15+ years managing shipment exceptions across all modes — LTL, FTL, parcel, intermodal, ocean, and air. You sit at the intersection of shippers, carriers, consignees, insurance providers, and internal stakeholders. Your systems include TMS (transportation management), WMS (warehouse management), carrier portals, claims management platforms, and ERP order management. Your job is to resolve exceptions quickly while protecting financial interests, preserving carrier relationships, and maintaining customer satisfaction. + +## Core Knowledge + +### Exception Taxonomy + +Every exception falls into a classification that determines the resolution workflow, documentation requirements, and urgency: + +- **Delay (transit):** Shipment not delivered by promised date. Subtypes: weather, mechanical, capacity (no driver), customs hold, consignee reschedule. Most common exception type (~40% of all exceptions). Resolution hinges on whether delay is carrier-fault or force majeure. +- **Damage (visible):** Noted on POD at delivery. Carrier liability is strong when consignee documents on the delivery receipt. Photograph immediately. Never accept "driver left before we could inspect." +- **Damage (concealed):** Discovered after delivery, not noted on POD. Must file concealed damage claim within 5 days of delivery (industry standard, not law). Burden of proof shifts to shipper. Carrier will challenge — you need packaging integrity evidence. +- **Damage (temperature):** Reefer/temperature-controlled failure. Requires continuous temp recorder data (Sensitech, Emerson). Pre-trip inspection records are critical. Carriers will claim "product was loaded warm." +- **Shortage:** Piece count discrepancy at delivery. Count at the tailgate — never sign clean BOL if count is off. Distinguish driver count vs warehouse count conflicts. OS&D (Over, Short & Damage) report required. +- **Overage:** More product delivered than on BOL. Often indicates cross-shipment from another consignee. Trace the extra freight — somebody is short. +- **Refused delivery:** Consignee rejects. Reasons: damaged, late (perishable window), incorrect product, no PO match, dock scheduling conflict. Carrier is entitled to storage charges and return freight if refusal is not carrier-fault. +- **Misdelivered:** Delivered to wrong address or wrong consignee. Full carrier liability. Time-critical to recover — product deteriorates or gets consumed. +- **Lost (full shipment):** No delivery, no scan activity. Trigger trace at 24 hours past ETA for FTL, 48 hours for LTL. File formal tracer with carrier OS&D department. +- **Lost (partial):** Some items missing from shipment. Often happens at LTL terminals during cross-dock handling. Serial number tracking critical for high-value. +- **Contaminated:** Product exposed to chemicals, odors, or incompatible freight (common in LTL). Regulatory implications for food and pharma. + +### Carrier Behaviour by Mode + +Understanding how different carrier types operate changes your resolution strategy: + +- **LTL carriers** (FedEx Freight, XPO, Estes): Shipments touch 2-4 terminals. Each touch = damage risk. Claims departments are large and process-driven. Expect 30-60 day claim resolution. Terminal managers have authority up to ~$2,500. +- **FTL/truckload** (asset carriers + brokers): Single-driver, dock-to-dock. Damage is usually loading/unloading. Brokers add a layer — the broker's carrier may go dark. Always get the actual carrier's MC number. +- **Parcel** (UPS, FedEx, USPS): Automated claims portals. Strict documentation requirements. Declared value matters — default liability is very low ($100 for UPS). Must purchase additional coverage at shipping. +- **Intermodal** (rail + drayage): Multiple handoffs. Damage often occurs during rail transit (impact events) or chassis swap. Bill of lading chain determines liability allocation between rail and dray. +- **Ocean** (container shipping): Governed by Hague-Visby or COGSA (US). Carrier liability is per-package ($500 per package under COGSA unless declared). Container seal integrity is everything. Surveyor inspection at destination port. +- **Air freight:** Governed by Montreal Convention. Strict 14-day notice for damage, 21 days for delay. Weight-based liability limits unless value declared. Fastest claims resolution of all modes. + +### Claims Process Fundamentals + +- **Carmack Amendment (US domestic surface):** Carrier is liable for actual loss or damage with limited exceptions (act of God, act of public enemy, act of shipper, public authority, inherent vice). Shipper must prove: goods were in good condition when tendered, goods arrived damaged/short, and the amount of damages. +- **Filing deadline:** 9 months from delivery date for US domestic (49 USC § 14706). Miss this and the claim is time-barred regardless of merit. +- **Documentation required:** Original BOL (showing clean tender), delivery receipt (showing exception), commercial invoice (proving value), inspection report, photographs, repair estimates or replacement quotes, packaging specifications. +- **Carrier response:** Carrier has 30 days to acknowledge, 120 days to pay or decline. If they decline, you have 2 years from the decline date to file suit. + +### Seasonal and Cyclical Patterns + +- **Peak season (Oct-Jan):** Exception rates increase 30-50%. Carrier networks are strained. Transit times extend. Claims departments slow down. Build buffer into commitments. +- **Produce season (Apr-Sep):** Temperature exceptions spike. Reefer availability tightens. Pre-cooling compliance becomes critical. +- **Hurricane season (Jun-Nov):** Gulf and East Coast disruptions. Force majeure claims increase. Rerouting decisions needed within 4-6 hours of storm track updates. +- **Month/quarter end:** Shippers rush volume. Carrier tender rejections spike. Double-brokering increases. Quality suffers across the board. +- **Driver shortage cycles:** Worst in Q4 and after new regulation implementation (ELD mandate, FMCSA drug clearinghouse). Spot rates spike, service drops. + +### Fraud and Red Flags + +- **Staged damages:** Damage patterns inconsistent with transit mode. Multiple claims from same consignee location. +- **Address manipulation:** Redirect requests post-pickup to different addresses. Common in high-value electronics. +- **Systematic shortages:** Consistent 1-2 unit shortages across multiple shipments — indicates pilferage at a terminal or during transit. +- **Double-brokering indicators:** Carrier on BOL doesn't match truck that shows up. Driver can't name their dispatcher. Insurance certificate is from a different entity. + +## Decision Frameworks + +### Severity Classification + +Assess every exception on three axes and take the highest severity: + +**Financial Impact:** + +- Level 1 (Low): < $1,000 product value, no expedite needed +- Level 2 (Moderate): $1,000 - $5,000 or minor expedite costs +- Level 3 (Significant): $5,000 - $25,000 or customer penalty risk +- Level 4 (Major): $25,000 - $100,000 or contract compliance risk +- Level 5 (Critical): > $100,000 or regulatory/safety implications + +**Customer Impact:** + +- Standard customer, no SLA at risk → does not elevate +- Key account with SLA at risk → elevate by 1 level +- Enterprise customer with penalty clauses → elevate by 2 levels +- Customer's production line or retail launch at risk → automatic Level 4+ + +**Time Sensitivity:** + +- Standard transit with buffer → does not elevate +- Delivery needed within 48 hours, no alternative sourced → elevate by 1 +- Same-day or next-day critical (production shutdown, event deadline) → automatic Level 4+ + +### Eat-the-Cost vs Fight-the-Claim + +This is the most common judgment call. Thresholds: + +- **< $500 and carrier relationship is strong:** Absorb. The admin cost of claims processing ($150-250 internal) makes it negative-ROI. Log for carrier scorecard. +- **$500 - $2,500:** File claim but don't escalate aggressively. This is the "standard process" zone. Accept partial settlements above 70% of value. +- **$2,500 - $10,000:** Full claims process. Escalate at 30-day mark if no resolution. Involve carrier account manager. Reject settlements below 80%. +- **> $10,000:** VP-level awareness. Dedicated claims handler. Independent inspection if damage. Reject settlements below 90%. Legal review if denied. +- **Any amount + pattern:** If this is the 3rd+ exception from the same carrier in 30 days, treat it as a carrier performance issue regardless of individual dollar amounts. + +### Priority Sequencing + +When multiple exceptions are active simultaneously (common during peak season or weather events), prioritize: + +1. Safety/regulatory (temperature-controlled pharma, hazmat) — always first +2. Customer production shutdown risk — financial multiplier is 10-50x product value +3. Perishable with remaining shelf life < 48 hours +4. Highest financial impact adjusted for customer tier +5. Oldest unresolved exception (prevent aging beyond SLA) + +## Key Edge Cases + +These are situations where the obvious approach is wrong. Brief summaries here — see [edge-cases.md](references/edge-cases.md) for full analysis. + +1. **Pharma reefer failure with disputed temps:** Carrier shows correct set-point; your Sensitech data shows excursion. The dispute is about sensor placement and pre-cooling. Never accept carrier's single-point reading — demand continuous data logger download. + +2. **Consignee claims damage but caused it during unloading:** POD is signed clean, but consignee calls 2 hours later claiming damage. If your driver witnessed their forklift drop the pallet, the driver's contemporaneous notes are your best defense. Without that, concealed damage claim against you is likely. + +3. **72-hour scan gap on high-value shipment:** No tracking updates doesn't always mean lost. LTL scan gaps happen at busy terminals. Before triggering a loss protocol, call the origin and destination terminals directly. Ask for physical trailer/bay location. + +4. **Cross-border customs hold:** When a shipment is held at customs, determine quickly if the hold is for documentation (fixable) or compliance (potentially unfixable). Carrier documentation errors (wrong harmonized codes on the carrier's portion) vs shipper errors (incorrect commercial invoice values) require different resolution paths. + +5. **Partial deliveries against single BOL:** Multiple delivery attempts where quantities don't match. Maintain a running tally. Don't file shortage claim until all partials are reconciled — carriers will use premature claims as evidence of shipper error. + +6. **Broker insolvency mid-shipment:** Your freight is on a truck, the broker who arranged it goes bankrupt. The actual carrier has a lien right. Determine quickly: is the carrier paid? If not, negotiate directly with the carrier for release. + +7. **Concealed damage discovered at final customer:** You delivered to distributor, distributor delivered to end customer, end customer finds damage. The chain-of-custody documentation determines who bears the loss. + +8. **Peak surcharge dispute during weather event:** Carrier applies emergency surcharge retroactively. Contract may or may not allow this — check force majeure and fuel surcharge clauses specifically. + +## Communication Patterns + +### Tone Calibration + +Match communication tone to situation severity and relationship: + +- **Routine exception, good carrier relationship:** Collaborative. "We've got a delay on PRO# X — can you get me an updated ETA? Customer is asking." +- **Significant exception, neutral relationship:** Professional and documented. State facts, reference BOL/PRO, specify what you need and by when. +- **Major exception or pattern, strained relationship:** Formal. CC management. Reference contract terms. Set response deadlines. "Per Section 4.2 of our transportation agreement dated..." +- **Customer-facing (delay):** Proactive, honest, solution-oriented. Never blame the carrier by name. "Your shipment has experienced a transit delay. Here's what we're doing and your updated timeline." +- **Customer-facing (damage/loss):** Empathetic, action-oriented. Lead with the resolution, not the problem. "We've identified an issue with your shipment and have already initiated [replacement/credit]." + +### Key Templates + +Brief templates below. Full versions with variables in [communication-templates.md](references/communication-templates.md). + +**Initial carrier inquiry:** Subject: `Exception Notice — PRO# {pro} / BOL# {bol}`. State: what happened, what you need (ETA update, inspection, OS&D report), and by when. + +**Customer proactive update:** Lead with: what you know, what you're doing about it, what the customer's revised timeline is, and your direct contact for questions. + +**Escalation to carrier management:** Subject: `ESCALATION: Unresolved Exception — {shipment_ref} — {days} Days`. Include timeline of previous communications, financial impact, and what resolution you expect. + +## Escalation Protocols + +### Automatic Escalation Triggers + +| Trigger | Action | Timeline | +| ------------------------------------------ | ---------------------------------------------- | ----------------- | +| Exception value > $25,000 | Notify VP Supply Chain immediately | Within 1 hour | +| Enterprise customer affected | Assign dedicated handler, notify account team | Within 2 hours | +| Carrier non-response | Escalate to carrier account manager | After 4 hours | +| Repeated carrier (3+ in 30 days) | Carrier performance review with procurement | Within 1 week | +| Potential fraud indicators | Notify compliance and halt standard processing | Immediately | +| Temperature excursion on regulated product | Notify quality/regulatory team | Within 30 minutes | +| No scan update on high-value (> $50K) | Initiate trace protocol and notify security | After 24 hours | +| Claims denied > $10,000 | Legal review of denial basis | Within 48 hours | + +### Escalation Chain + +Level 1 (Analyst) → Level 2 (Team Lead, 4 hours) → Level 3 (Manager, 24 hours) → Level 4 (Director, 48 hours) → Level 5 (VP, 72+ hours or any Level 5 severity) + +## Performance Indicators + +Track these metrics weekly and trend monthly: + +| Metric | Target | Red Flag | +| -------------------------------------- | ------------------- | ------------- | +| Mean resolution time | < 72 hours | > 120 hours | +| First-contact resolution rate | > 40% | < 25% | +| Financial recovery rate (claims) | > 75% | < 50% | +| Customer satisfaction (post-exception) | > 4.0/5.0 | < 3.5/5.0 | +| Exception rate (per 1,000 shipments) | < 25 | > 40 | +| Claims filing timeliness | 100% within 30 days | Any > 60 days | +| Repeat exceptions (same carrier/lane) | < 10% | > 20% | +| Aged exceptions (> 30 days open) | < 5% of total | > 15% | + +## Additional Resources + +- For detailed decision frameworks, escalation matrices, and mode-specific workflows, see [decision-frameworks.md](references/decision-frameworks.md) +- For the comprehensive edge case library with full analysis, see [edge-cases.md](references/edge-cases.md) +- For complete communication templates with variables and tone guidance, see [communication-templates.md](references/communication-templates.md) + +## When to Use + +Use this skill when you need to **triage and resolve logistics exceptions or design exception-handling playbooks**: + +- Handling delays, damages, shortages, misdeliveries, and claims across LTL, FTL, parcel, intermodal, ocean, or air. +- Defining escalation rules, severity classification, and “eat‑the‑cost vs fight‑the‑claim” thresholds for your network. +- Building SOPs, dashboards, or automation for OS&D, claims workflows, and customer communications during freight disruptions. diff --git a/web-app/public/skills/logistics-exception-management/references/communication-templates.md b/web-app/public/skills/logistics-exception-management/references/communication-templates.md new file mode 100644 index 00000000..99726782 --- /dev/null +++ b/web-app/public/skills/logistics-exception-management/references/communication-templates.md @@ -0,0 +1,1170 @@ +# Communication Templates — Logistics Exception Management + +> **Reference Type:** Tier 3 — Load on demand when composing or reviewing exception communications. +> +> **Usage:** Each template includes variable placeholders in `{{double_braces}}` for direct substitution. Templates are organized by audience and escalation stage. Select the template matching your scenario, substitute variables, review tone guidance, and send. + +--- + +## Table of Contents + +1. [Initial Exception Notification to Carrier (Standard)](#1-initial-exception-notification-to-carrier-standard) +2. [Initial Exception Notification to Carrier (Urgent)](#2-initial-exception-notification-to-carrier-urgent) +3. [Customer Proactive Update — Delay](#3-customer-proactive-update--delay) +4. [Customer Proactive Update — Damage](#4-customer-proactive-update--damage) +5. [Customer Proactive Update — Loss](#5-customer-proactive-update--loss) +6. [Escalation to Carrier Account Manager](#6-escalation-to-carrier-account-manager) +7. [Escalation to Carrier VP/Director](#7-escalation-to-carrier-vpdirector) +8. [Internal Escalation to VP Supply Chain](#8-internal-escalation-to-vp-supply-chain) +9. [Claims Filing Cover Letter](#9-claims-filing-cover-letter) +10. [Settlement Negotiation Response (Accepting)](#10-settlement-negotiation-response-accepting) +11. [Settlement Negotiation Response (Rejecting)](#11-settlement-negotiation-response-rejecting) +12. [Post-Resolution Summary](#12-post-resolution-summary) +13. [Carrier Performance Warning](#13-carrier-performance-warning) +14. [Customer Apology with Resolution](#14-customer-apology-with-resolution) + +--- + +## Variable Reference + +Common variables used across templates: + +| Variable | Description | Example | +|---|---|---| +| `{{pro_number}}` | Carrier PRO / tracking number | `PRO 1234-5678-90` | +| `{{bol_number}}` | Bill of Lading number | `BOL-2025-04872` | +| `{{po_number}}` | Customer purchase order number | `PO-88431` | +| `{{shipment_id}}` | Internal shipment reference | `SHP-2025-11049` | +| `{{carrier_name}}` | Carrier legal or DBA name | `Acme Freight, Inc.` | +| `{{carrier_mc}}` | Carrier MC/DOT number | `MC-345678` | +| `{{carrier_scac}}` | Carrier SCAC code | `ACMF` | +| `{{origin_city_state}}` | Origin city and state | `Dallas, TX` | +| `{{dest_city_state}}` | Destination city and state | `Columbus, OH` | +| `{{ship_date}}` | Original ship date | `2025-09-14` | +| `{{original_eta}}` | Original estimated delivery | `2025-09-17` | +| `{{revised_eta}}` | Revised estimated delivery | `2025-09-19` | +| `{{customer_name}}` | Customer company name | `Midwest Distribution Co.` | +| `{{customer_contact}}` | Customer contact name | `Sarah Chen` | +| `{{our_contact_name}}` | Our representative name | `James Petrovic` | +| `{{our_contact_title}}` | Our representative title | `Transportation Manager` | +| `{{our_contact_email}}` | Our representative email | `jpetrovic@company.com` | +| `{{our_contact_phone}}` | Our representative phone | `(312) 555-0147` | +| `{{our_company}}` | Our company name | `Consolidated Shippers LLC` | +| `{{exception_date}}` | Date exception was identified | `2025-09-16` | +| `{{commodity}}` | Freight commodity description | `Automotive brake assemblies` | +| `{{weight}}` | Shipment weight | `12,400 lbs` | +| `{{piece_count}}` | Piece/pallet count | `14 pallets` | +| `{{freight_charge}}` | Freight charge amount | `$3,840.00` | +| `{{cargo_value}}` | Declared cargo value | `$47,200.00` | +| `{{claim_amount}}` | Claim dollar amount | `$47,200.00` | +| `{{claim_number}}` | Carrier-assigned claim number | `CLM-2025-0398` | +| `{{our_claim_ref}}` | Internal claim reference | `EXC-2025-1104` | +| `{{deadline_date}}` | Response or action deadline | `2025-09-18 by 14:00 CT` | +| `{{days_in_transit}}` | Days shipment has been moving | `5` | +| `{{last_known_location}}` | Last scan or check-call location | `Indianapolis, IN terminal` | + +--- + +## 1. Initial Exception Notification to Carrier (Standard) + +### When to Use +- Exception identified through tracking, check-call miss, or OS&D report. +- Severity is moderate — the shipment is delayed or has a discrepancy but is not in immediate jeopardy. +- First outreach to carrier operations or dispatch regarding this specific issue. + +### Tone Guidance +Keep this factual and collaborative. You are a professional notifying a partner of a discrepancy, not accusing anyone of failure. Assume good intent — the goal is to get information and a corrective plan, not to assign blame at this stage. + +### What NOT to Say +- Do not threaten claims or contract consequences in the first contact. +- Do not speculate on what caused the exception. +- Do not use language like "you failed to" or "your driver caused" — you do not yet have confirmed root cause. +- Do not copy the customer on carrier operational communications. + +### Subject Line + +``` +Exception Notice — PRO {{pro_number}} | {{origin_city_state}} to {{dest_city_state}} | BOL {{bol_number}} +``` + +### Body + +``` +Team, + +We are writing regarding a shipment exception on the following load: + + PRO: {{pro_number}} + BOL: {{bol_number}} + PO: {{po_number}} + Origin: {{origin_city_state}} + Destination: {{dest_city_state}} + Ship Date: {{ship_date}} + Original ETA: {{original_eta}} + Commodity: {{commodity}} + Weight/Count: {{weight}} / {{piece_count}} + +EXCEPTION DETAILS: +{{exception_description}} + +We identified this exception on {{exception_date}} at approximately {{exception_time}}. +The last confirmed status was {{last_known_status}} at {{last_known_location}} on +{{last_scan_date}}. + +We need the following from your team: + + 1. Current physical location of the freight + 2. Updated ETA to the consignee + 3. Root cause of the delay or discrepancy + 4. Corrective action being taken + +Please respond by {{deadline_date}} so we can update our customer accordingly. + +If you have questions or need additional shipment details, contact me directly at +{{our_contact_phone}} or {{our_contact_email}}. + +Regards, +{{our_contact_name}} +{{our_contact_title}} +{{our_company}} +{{our_contact_phone}} +``` + +--- + +## 2. Initial Exception Notification to Carrier (Urgent) + +### When to Use +- Shipment is critical: production-down, store-opening, perishable, or high-value. +- Exception creates immediate financial exposure (e.g., production line stoppage, contract penalty window). +- Customer has already escalated or SLA breach is imminent (within 24 hours). + +### Tone Guidance +Direct and time-bound. This is not hostile, but it communicates that the situation requires immediate action, not a callback tomorrow. Every sentence should drive toward a concrete next step. Use specific deadlines, not "as soon as possible." + +### What NOT to Say +- Do not soften the urgency — "when you get a chance" undermines the entire message. +- Do not issue ultimatums you cannot enforce at this stage. +- Do not reference other shipments or unrelated performance issues — stay on this load. +- Do not leave out the financial exposure figure; it justifies the urgency. + +### Subject Line + +``` +URGENT — Immediate Response Required | PRO {{pro_number}} | {{dest_city_state}} | ETA Miss +``` + +### Body + +``` +URGENT — IMMEDIATE RESPONSE REQUIRED + +This shipment requires your immediate attention. We need a substantive response +by {{deadline_date}} — not an acknowledgment, but confirmed status and a recovery plan. + +SHIPMENT DETAILS: + PRO: {{pro_number}} + BOL: {{bol_number}} + PO: {{po_number}} + Origin: {{origin_city_state}} + Destination: {{dest_city_state}} + Ship Date: {{ship_date}} + Original ETA: {{original_eta}} + Commodity: {{commodity}} + Weight/Count: {{weight}} / {{piece_count}} + Declared Value: {{cargo_value}} + +EXCEPTION: +{{exception_description}} + +BUSINESS IMPACT: +{{business_impact_description}} + +Estimated financial exposure if not resolved by {{resolution_deadline}}: {{financial_exposure}}. + +REQUIRED BY {{deadline_date}}: + 1. Confirmed physical location of the freight — verified, not last-scan + 2. Firm revised delivery date and time + 3. Name and direct phone number of the person managing recovery + 4. Written recovery plan + +If I do not have a response by the deadline above, I will escalate to your account +management team and begin contingency planning, which may include diversion or +re-tender. + +Contact me directly: +{{our_contact_name}} | {{our_contact_phone}} | {{our_contact_email}} + +Regards, +{{our_contact_name}} +{{our_contact_title}} +{{our_company}} +``` + +--- + +## 3. Customer Proactive Update — Delay + +### When to Use +- Transit delay confirmed or highly probable (revised ETA is beyond the committed window). +- Send this before the customer discovers the delay on their own. Proactive communication preserves trust; reactive communication erodes it. +- You have a revised ETA — even if approximate. If you have no ETA at all, say so and commit to a follow-up time. + +### Tone Guidance +Honest and solution-forward. Acknowledge the delay plainly — do not bury it in qualifiers. Lead with the revised timeline, then explain briefly. The customer wants to know "when will I get my freight" before they want to know "what happened." Do not name the carrier or assign blame to any specific party. + +### What NOT to Say +- Do not blame the carrier by name — say "our carrier partner," not "XYZ Trucking messed up." +- Do not say "unforeseen circumstances" — be specific about the cause category (weather, equipment, routing). +- Do not promise a revised ETA you cannot support. If uncertain, give a range. +- Do not use "we apologize for any inconvenience" — it reads as form language. Be specific about the impact you understand. + +### Subject Line + +``` +Shipment Update — PO {{po_number}} | Revised ETA {{revised_eta}} +``` + +### Body + +``` +{{customer_contact}}, + +I want to update you on PO {{po_number}} (our reference {{shipment_id}}) shipping +from {{origin_city_state}} to {{dest_city_state}}. + +This shipment is experiencing a transit delay. The original estimated delivery was +{{original_eta}}. Based on current status, the revised delivery estimate is +{{revised_eta}}. + +CAUSE: {{delay_cause_customer_facing}} + +HERE IS WHAT WE ARE DOING: + - {{action_item_1}} + - {{action_item_2}} + - {{action_item_3}} + +I will send you another update by {{next_update_time}} with confirmed delivery +details. If the timeline shifts further in either direction, you will hear from me +immediately. + +If this delay impacts your operations and you need us to evaluate expedited +alternatives, please let me know and I will have options to you within +{{expedite_response_window}}. + +Regards, +{{our_contact_name}} +{{our_contact_title}} +{{our_company}} +{{our_contact_phone}} | {{our_contact_email}} +``` + +### Variant — Delay with No ETA Yet + +When you cannot provide a revised ETA, replace the ETA section: + +``` +This shipment is experiencing a transit delay. The original estimated delivery was +{{original_eta}}. We do not yet have a confirmed revised delivery time, but I am +working to get one and will update you by {{next_update_time}} today. +``` + +--- + +## 4. Customer Proactive Update — Damage + +### When to Use +- Carrier or consignee has reported visible damage at delivery or in transit. +- Damage is confirmed or strongly suspected (e.g., photos from driver, consignee notation on POD). +- Send before the customer calls you. If they are the consignee, send before they have to chase you for next steps. + +### Tone Guidance +Lead with the resolution, not the problem. The customer's first question is "what are you going to do about it" — answer that before describing the damage. Be specific about the remediation path (replacement, credit, re-ship) and timeline. Express genuine concern for the business impact without being dramatic. + +### What NOT to Say +- Do not lead with the damage description. The opening paragraph should be about the resolution path. +- Do not say "these things happen in transit" — it minimizes the customer's loss. +- Do not speculate on cause (packaging, handling, weather) until investigation is complete. +- Do not ask the customer to file a claim — that is your job. + +### Subject Line + +``` +PO {{po_number}} — Delivery Update and Resolution Plan +``` + +### Body + +``` +{{customer_contact}}, + +I am reaching out regarding PO {{po_number}} (our reference {{shipment_id}}) +delivered to {{dest_city_state}} on {{delivery_date}}. + +We have identified damage to a portion of this shipment and I want to walk you +through the resolution we are putting in place. + +RESOLUTION: + {{resolution_description}} + + Timeline: {{resolution_timeline}} + +DAMAGE DETAILS: + Items Affected: {{damaged_items_description}} + Extent: {{damage_extent}} + Pieces Affected: {{damaged_piece_count}} of {{piece_count}} total + +We are handling the carrier claim and investigation on our end — no action is +needed from your team on that front. + +What we do need from you: + - Confirmation of the affected quantities once your receiving team completes + inspection + - Direction on whether you want us to {{resolution_option_a}} or + {{resolution_option_b}} + +I understand this impacts your {{customer_impact_area}} and I take that seriously. +I will stay on this personally until it is fully resolved. + +Next update from me: {{next_update_time}}. + +Regards, +{{our_contact_name}} +{{our_contact_title}} +{{our_company}} +{{our_contact_phone}} | {{our_contact_email}} +``` + +--- + +## 5. Customer Proactive Update — Loss + +### When to Use +- Shipment is confirmed lost — not just delayed or unlocated. A shipment is "lost" when the carrier has confirmed they cannot locate the freight after a thorough trace, OR when {{days_without_scan}} days have passed with no carrier response to trace requests. +- This is the most sensitive exception communication. The customer is learning that their goods are gone. Do not send this template for a shipment that is merely late or temporarily unlocated. + +### Tone Guidance +Empathetic, direct, and action-oriented. Do not hedge or use passive constructions — "your shipment has been lost" is clearer than "there appears to be a situation involving the non-delivery of your order." Immediately establish the action plan. The customer needs to know three things: (1) what happened, (2) what you are doing right now, and (3) when they will have resolution. Convey that you understand the severity. + +### What NOT to Say +- Do not say "misplaced" or "misrouted" if the shipment is confirmed lost — it sounds like you are minimizing. +- Do not say "we are still looking into it" without a concrete next step and deadline. +- Do not blame the carrier by name. +- Do not lead with the claims process — lead with the replacement or remediation plan. The customer needs their goods, not a claims education. +- Do not use "unfortunately" more than once. + +### Subject Line + +``` +PO {{po_number}} — Shipment Status and Immediate Action Plan +``` + +### Body + +``` +{{customer_contact}}, + +I need to share a difficult update on PO {{po_number}} (our reference +{{shipment_id}}), originally shipping {{origin_city_state}} to +{{dest_city_state}} on {{ship_date}}. + +After an extensive trace with our carrier partner, we have confirmed that this +shipment — {{piece_count}} of {{commodity}}, valued at {{cargo_value}} — has +been lost in transit. I know this creates a real problem for your team and I want +to lay out exactly what we are doing about it. + +IMMEDIATE ACTION PLAN: + + 1. REPLACEMENT / RE-SHIP: + {{replacement_plan}} + Expected availability: {{replacement_date}} + + 2. FINANCIAL REMEDIATION: + {{financial_remediation_plan}} + Timeline: {{financial_remediation_timeline}} + + 3. CARRIER CLAIM: + We have filed a formal cargo claim against the carrier. This is our + responsibility to manage — you do not need to take any action on the + claim. + Claim reference: {{our_claim_ref}} + + 4. PREVENTION: + {{prevention_steps}} + +I will call you at {{follow_up_call_time}} to discuss this directly and answer +any questions. If you need to reach me before then, my cell is +{{our_contact_phone}}. + +I take full ownership of making this right. + +Regards, +{{our_contact_name}} +{{our_contact_title}} +{{our_company}} +{{our_contact_phone}} | {{our_contact_email}} +``` + +--- + +## 6. Escalation to Carrier Account Manager + +### When to Use +- Initial contact to carrier dispatch or operations has gone unanswered for 4+ hours on a standard exception, or 2+ hours on an urgent exception. +- You have documented at least two prior outreach attempts (email, phone, or both) to the frontline contact. +- The account manager is the next level of the carrier's organization who can apply internal pressure. + +### Tone Guidance +Professional but firm. You are not angry — you are a business partner whose reasonable requests have been ignored, and you need the account manager to intervene. State the timeline of your attempts factually. Make the ask concrete. The account manager needs to know exactly what you need and by when so they can push their operations team. + +### What NOT to Say +- Do not trash the frontline contact by name — say "your operations team" or "your dispatch." +- Do not threaten to pull freight at this stage unless you mean it and have authority. +- Do not pile on unrelated issues — stay on this shipment. + +### Subject Line + +``` +Escalation — No Response on PRO {{pro_number}} | Requires Your Intervention +``` + +### Body + +``` +{{carrier_account_manager_name}}, + +I am escalating to you because I have been unable to get a substantive response +from your operations team on a shipment exception that requires immediate +attention. + +SHIPMENT: + PRO: {{pro_number}} + BOL: {{bol_number}} + PO: {{po_number}} + Route: {{origin_city_state}} → {{dest_city_state}} + Ship Date: {{ship_date}} + Original ETA: {{original_eta}} + +EXCEPTION: +{{exception_description}} + +OUTREACH TIMELINE: + {{attempt_1_date_time}} — {{attempt_1_method}}: {{attempt_1_summary}} + {{attempt_2_date_time}} — {{attempt_2_method}}: {{attempt_2_summary}} + {{attempt_3_date_time}} — {{attempt_3_method}}: {{attempt_3_summary}} + +It has been {{hours_since_first_contact}} hours since our first outreach with no +confirmed status or recovery plan. + +I need the following by {{deadline_date}}: + 1. Confirmed current location of the freight + 2. Firm revised ETA + 3. A direct contact managing the recovery who I can reach by phone + +My customer is waiting on this update and I cannot continue to respond with "we +are working on it" without specifics. + +Please call me at {{our_contact_phone}} or reply to this email by the deadline +above. + +Regards, +{{our_contact_name}} +{{our_contact_title}} +{{our_company}} +{{our_contact_phone}} | {{our_contact_email}} +``` + +--- + +## 7. Escalation to Carrier VP/Director + +### When to Use +- Account manager has failed to resolve or respond within a reasonable window (typically 12–24 hours after account manager escalation). +- The exception has significant financial exposure, or a pattern of similar failures exists. +- You are prepared to reference contract terms, volume commitments, or documented performance history. +- This is a formal escalation — send it knowing it may be shared with carrier executive leadership. + +### Tone Guidance +Formal and data-driven. This is a business communication between senior professionals. No emotion, no sarcasm, no threats — but clear consequences stated as business realities. Reference specific contract provisions, dollar figures, and incident history. The VP needs to understand that this is not a one-off complaint; it is a business risk they need to manage. + +### What NOT to Say +- Do not be sarcastic or condescending — "I'm sure you're very busy" undermines your credibility. +- Do not make threats you cannot follow through on (e.g., "we will never use you again" when they are your only option for a lane). +- Do not reference verbal promises or informal agreements — stick to what is documented. +- Do not CC your customer. This is a carrier management conversation. + +### Subject Line + +``` +Executive Escalation — Unresolved Exception PRO {{pro_number}} | {{our_company}} Account +``` + +### Body + +``` +{{carrier_vp_name}}, +{{carrier_vp_title}} +{{carrier_name}} + +I am writing to escalate a shipment exception that has not been resolved despite +repeated engagement with your operations and account management teams. + +SHIPMENT DETAILS: + PRO: {{pro_number}} + BOL: {{bol_number}} + Route: {{origin_city_state}} → {{dest_city_state}} + Ship Date: {{ship_date}} + Commodity: {{commodity}} + Shipment Value: {{cargo_value}} + +EXCEPTION SUMMARY: +{{exception_description}} + +ESCALATION HISTORY: + {{escalation_timeline_summary}} + + Total time without resolution: {{total_hours_unresolved}} hours. + +FINANCIAL EXPOSURE: + Direct cargo exposure: {{cargo_value}} + Customer penalty risk: {{customer_penalty_amount}} + Expedite/recovery costs: {{recovery_cost_estimate}} + Total potential exposure: {{total_financial_exposure}} + +CONTRACT REFERENCE: +Per Section {{contract_section}} of our transportation agreement dated +{{contract_date}}, {{relevant_contract_provision}}. + +{{#if pattern_exists}} +PERFORMANCE PATTERN: +This is not an isolated incident. Over the past {{pattern_period}}, we have +logged {{incident_count}} exceptions on your loads, resulting in +{{total_pattern_cost}} in direct costs. Specific incidents: + {{pattern_incident_list}} +{{/if}} + +I need the following from your team by {{deadline_date}}: + 1. Full resolution of this specific shipment + 2. Written root cause analysis + 3. Corrective action plan to prevent recurrence + +I value the partnership between {{our_company}} and {{carrier_name}}, and I want +to resolve this collaboratively. However, continued non-responsiveness will +require us to reassess our routing and volume commitments on the +{{origin_city_state}}–{{dest_city_state}} lane. + +I am available to discuss at {{our_contact_phone}}. + +Regards, +{{our_contact_name}} +{{our_contact_title}} +{{our_company}} +{{our_contact_phone}} | {{our_contact_email}} +``` + +--- + +## 8. Internal Escalation to VP Supply Chain + +### When to Use +- Financial exposure exceeds your authority threshold (typically $25,000+ or customer-specific triggers). +- Customer relationship is at risk and executive-to-executive communication may be required. +- A decision is needed that is above your pay grade: re-tender, expedite at premium cost, authorize production-down recovery, or waive contractual terms. +- You need VP awareness even if you do not need VP action — significant exceptions should not be surprises. + +### Tone Guidance +Brief and structured. Your VP does not need the narrative — they need the numbers, the exposure, what you have already done, and what you need from them. Lead with the decision or awareness item. Use bullet points. This is an internal operational brief, not a customer communication. + +### What NOT to Say +- Do not editorialize — "the carrier is terrible" adds nothing. State the facts. +- Do not bury the financial number. It should be in the first three lines. +- Do not present problems without proposed solutions. +- Do not send this without having already exhausted the escalation steps within your authority. + +### Subject Line + +``` +[ACTION REQUIRED] Exception — {{customer_name}} PO {{po_number}} | ${{financial_exposure}} Exposure +``` + +### Body + +``` +{{vp_name}}, + +Flagging an active exception that requires {{your_awareness / your_decision}}. + +BOTTOM LINE: + Customer: {{customer_name}} + Shipment: PO {{po_number}} / PRO {{pro_number}} + Exception Type: {{exception_type}} + Financial Exposure: ${{financial_exposure}} + Customer Risk: {{customer_risk_level}} — {{customer_risk_description}} + +SITUATION: + {{two_to_three_sentence_summary}} + +WHAT I HAVE DONE: + - {{action_taken_1}} + - {{action_taken_2}} + - {{action_taken_3}} + +WHAT I NEED FROM YOU: + {{decision_or_action_needed}} + + Options: + A. {{option_a}} — Cost: ${{option_a_cost}} | Timeline: {{option_a_timeline}} + B. {{option_b}} — Cost: ${{option_b_cost}} | Timeline: {{option_b_timeline}} + + My recommendation: Option {{recommended_option}} because {{rationale}}. + +I need a decision by {{decision_deadline}} to execute the recovery plan. + +—{{our_contact_name}} +``` + +--- + +## 9. Claims Filing Cover Letter + +### When to Use +- Decision has been made to file a formal freight claim against the carrier. +- All supporting documentation has been gathered (BOL, POD, inspection reports, photos, invoice, packing list). +- Claim is being sent within the filing window (9 months under Carmack Amendment for interstate; check state law or contract for intrastate or brokered freight). + +### Tone Guidance +Formal and precise. This is a legal document. No emotion, no narrative, no relationship language. State the facts, cite the applicable law, list the enclosed documents, and demand payment. Every statement should be supportable with evidence. Use the carrier's legal name and MC number, not their DBA or sales contact's name. + +### What NOT to Say +- Do not editorialize about the carrier's service or your frustration. +- Do not include demands beyond the provable loss amount — consequential damages require separate analysis and legal review. +- Do not omit the filing date or claim amount — these are jurisdictional requirements. +- Do not reference settlement discussions or verbal admissions of fault. + +### Subject Line + +``` +Formal Freight Claim — PRO {{pro_number}} | Claim Amount: ${{claim_amount}} +``` + +### Body + +``` + {{current_date}} + +VIA EMAIL AND CERTIFIED MAIL + +{{carrier_legal_name}} +{{carrier_claims_address}} +MC-{{carrier_mc}} / DOT-{{carrier_dot}} + +Attn: Claims Department + +RE: Formal Freight Claim + PRO Number: {{pro_number}} + BOL Number: {{bol_number}} + Ship Date: {{ship_date}} + Origin: {{origin_city_state}} + Destination: {{dest_city_state}} + Our Reference: {{our_claim_ref}} + Claim Amount: ${{claim_amount}} + +Dear Claims Department: + +{{our_company}} hereby files this formal claim for {{claim_type}} against +{{carrier_legal_name}} pursuant to the Carmack Amendment, 49 U.S.C. § 14706, +and applicable regulations at 49 C.F.R. Part 370. + +FACTS: + +On {{ship_date}}, {{our_company}} tendered {{piece_count}} of {{commodity}}, +weighing {{weight}}, to {{carrier_legal_name}} at {{origin_facility}}, +{{origin_city_state}}, for transportation to {{dest_facility}}, +{{dest_city_state}}, under BOL {{bol_number}}. + +{{claim_facts_paragraph}} + +CLAIMED AMOUNT: + +The total claimed amount is ${{claim_amount}}, computed as follows: + + {{claim_calculation_line_items}} + + Total: ${{claim_amount}} + +This amount represents the {{value_basis}} of the goods at the time and place +of shipment, supported by the enclosed invoice documentation. + +ENCLOSED DOCUMENTATION: + + 1. Bill of Lading (BOL {{bol_number}}) + 2. Delivery receipt / Proof of Delivery with consignee notations + 3. {{inspection_report_description}} + 4. Photographs of {{photo_description}} + 5. Commercial invoice(s) — Invoice No. {{invoice_numbers}} + 6. Packing list + 7. Shipper's certificate of value / weight + {{#if additional_documents}} + 8. {{additional_documents}} + {{/if}} + +DEMAND: + +{{our_company}} demands payment of ${{claim_amount}} within thirty (30) days +of receipt of this claim, per 49 C.F.R. § 370.9. In the alternative, we +request written acknowledgment within thirty (30) days and final disposition +within one hundred twenty (120) days, as required by regulation. + +Please direct all claim correspondence to: + + {{our_contact_name}} + {{our_contact_title}} + {{our_company}} + {{our_claims_address}} + {{our_contact_email}} + {{our_contact_phone}} + + Claim Reference: {{our_claim_ref}} + +{{our_company}} reserves all rights and remedies available under applicable +law, including the right to pursue this claim in a court of competent +jurisdiction if not resolved within the regulatory timeframe. + +Respectfully, + + +{{our_contact_name}} +{{our_contact_title}} +{{our_company}} +``` + +--- + +## 10. Settlement Negotiation Response (Accepting) + +### When to Use +- Carrier has offered a settlement amount and you have decided to accept it. +- The settlement amount has been approved internally (check your authority level — partial settlements often require management sign-off). +- You are ready to close the claim and release the carrier from further liability on this shipment. + +### Tone Guidance +Professional and conclusive. You are closing a business matter, not doing the carrier a favor. Confirm the exact terms clearly — amount, payment method, timeline, and scope of release. Do not express gratitude for the settlement or suggest the amount was generous. It is a business resolution. + +### What NOT to Say +- Do not say "thank you for your generous offer" — you are accepting fair compensation, not a gift. +- Do not leave any ambiguity about what is being released — specify the PRO, BOL, and claim reference. +- Do not agree to confidentiality clauses or broad releases without legal review. +- Do not accept verbally — always confirm in writing. + +### Subject Line + +``` +Claim Settlement Acceptance — PRO {{pro_number}} | Claim {{our_claim_ref}} +``` + +### Body + +``` +{{carrier_claims_contact}}, + +This letter confirms {{our_company}}'s acceptance of the settlement offer +received on {{offer_date}} regarding the following claim: + + PRO Number: {{pro_number}} + BOL Number: {{bol_number}} + Our Reference: {{our_claim_ref}} + Your Reference: {{claim_number}} + +SETTLEMENT TERMS: + + Settlement Amount: ${{settlement_amount}} + Payment Method: {{payment_method}} + Payment Due: Within {{payment_days}} business days of this acceptance + Scope of Release: Full and final settlement of all claims arising from PRO + {{pro_number}} / BOL {{bol_number}} for the shipment of + {{commodity}} from {{origin_city_state}} to + {{dest_city_state}} on {{ship_date}} + +Upon receipt of ${{settlement_amount}}, {{our_company}} releases +{{carrier_legal_name}} (MC-{{carrier_mc}}) from any further liability related +to the above-referenced shipment. + +This release does not extend to any other shipments, claims, or obligations +between the parties. + +Please remit payment to: + + {{our_company}} + {{our_remittance_address}} + {{our_payment_details}} + + Reference: {{our_claim_ref}} + +Please confirm receipt of this acceptance and expected payment date. + +Regards, +{{our_contact_name}} +{{our_contact_title}} +{{our_company}} +{{our_contact_phone}} | {{our_contact_email}} +``` + +--- + +## 11. Settlement Negotiation Response (Rejecting) + +### When to Use +- Carrier's settlement offer is below your documented loss amount and you have evidence to support a higher claim. +- You are prepared to counter-offer with a specific amount backed by documentation. +- You have reviewed the carrier's stated basis for the reduced offer and can address their objections. + +### Tone Guidance +Firm and evidence-based. You are not offended by a low offer — you are correcting an inaccurate valuation. Walk through their reasoning, point out where it is wrong, and anchor your counter to specific evidence. Keep the door open for resolution but make clear that the documented loss supports your position. + +### What NOT to Say +- Do not say "this is insulting" or express emotion about the offer amount. +- Do not threaten litigation in the same sentence as a counter-offer — it contradicts the settlement posture. +- Do not accept their framing if it is incorrect (e.g., if they depreciated new goods or excluded documented items). +- Do not counter without supporting documentation — attach the evidence. + +### Subject Line + +``` +Claim {{our_claim_ref}} — Settlement Offer Declined | Counter-Offer Enclosed +``` + +### Body + +``` +{{carrier_claims_contact}}, + +We have reviewed your settlement offer of ${{offered_amount}} dated +{{offer_date}} for the following claim: + + PRO Number: {{pro_number}} + BOL Number: {{bol_number}} + Our Reference: {{our_claim_ref}} + Your Reference: {{claim_number}} + Original Claim: ${{claim_amount}} + +We are unable to accept this offer. Our original claim of ${{claim_amount}} is +supported by documented evidence, and the offered amount does not adequately +compensate for the loss. + +RESPONSE TO YOUR STATED BASIS FOR REDUCTION: + +{{carrier_reduction_reason_1}}: + Our response: {{our_response_1}} + Supporting documentation: {{supporting_doc_1}} + +{{carrier_reduction_reason_2}}: + Our response: {{our_response_2}} + Supporting documentation: {{supporting_doc_2}} + +{{#if carrier_reduction_reason_3}} +{{carrier_reduction_reason_3}}: + Our response: {{our_response_3}} + Supporting documentation: {{supporting_doc_3}} +{{/if}} + +COUNTER-OFFER: + +{{our_company}} is willing to settle this claim for ${{counter_offer_amount}}, +which reflects {{counter_offer_basis}}. + +This counter-offer is supported by the following enclosed documentation: + {{counter_offer_documentation_list}} + +We request your response within {{response_days}} business days. We remain open +to resolving this matter directly and would welcome a call to discuss if that +would be productive. + +If we are unable to reach a fair resolution, we will need to evaluate our +options under 49 U.S.C. § 14706, which provides a two-year statute of +limitations from the date of claim denial. + +Regards, +{{our_contact_name}} +{{our_contact_title}} +{{our_company}} +{{our_contact_phone}} | {{our_contact_email}} +``` + +--- + +## 12. Post-Resolution Summary + +### When to Use +- Exception has been fully resolved — freight delivered, claim settled, or loss remediated. +- Distribute to internal stakeholders: operations, account management, finance, and carrier procurement. +- This becomes the permanent record of the exception and feeds carrier scorecard reviews. + +### Tone Guidance +Neutral and analytical. This is a post-mortem, not a complaint. State what happened, what it cost, what was done, and what should change. Be specific about lessons learned — vague statements like "we need to communicate better" are worthless. Recommend concrete process changes. + +### What NOT to Say +- Do not assign personal blame to individuals — focus on process and system failures. +- Do not omit the financial impact even if the claim was settled favorably — the true cost includes staff time, expedite charges, and customer goodwill. +- Do not skip the "prevention" section. If you cannot recommend a prevention step, say so and explain why. + +### Subject Line + +``` +[CLOSED] Exception Summary — {{customer_name}} / PRO {{pro_number}} | {{exception_type}} +``` + +### Body + +``` +EXCEPTION POST-RESOLUTION SUMMARY +==================================== + +Exception Reference: {{our_claim_ref}} +Status: CLOSED — {{closure_date}} +Prepared by: {{our_contact_name}} +Distribution: {{distribution_list}} + +1. SHIPMENT DETAILS + Customer: {{customer_name}} + PO: {{po_number}} + PRO: {{pro_number}} + BOL: {{bol_number}} + Carrier: {{carrier_name}} (MC-{{carrier_mc}} / SCAC: {{carrier_scac}}) + Route: {{origin_city_state}} → {{dest_city_state}} + Ship Date: {{ship_date}} + Commodity: {{commodity}} + Weight/Pieces: {{weight}} / {{piece_count}} + +2. EXCEPTION SUMMARY + Type: {{exception_type}} + Discovered: {{exception_date}} + Root Cause: {{confirmed_root_cause}} + Description: {{exception_narrative}} + +3. TIMELINE + {{exception_timeline}} + +4. FINANCIAL IMPACT + Cargo Loss/Damage: ${{cargo_loss_amount}} + Freight Charges (original): ${{freight_charge}} + Expedite / Recovery Costs: ${{recovery_costs}} + Customer Penalties / Credits: ${{customer_penalties}} + Internal Labor (est.): ${{internal_labor_cost}} + ───────────────────────────────── + Total Cost of Exception: ${{total_exception_cost}} + + Claim Filed: ${{claim_amount}} + Settlement Received: ${{settlement_amount}} + Net Unrecovered Loss: ${{net_loss}} + +5. CUSTOMER IMPACT + {{customer_impact_summary}} + Customer Satisfaction Status: {{csat_status}} + Relationship Risk: {{relationship_risk_level}} + +6. CARRIER SCORECARD IMPACT + Carrier: {{carrier_name}} + Incidents (trailing 12 months): {{trailing_12_incident_count}} + On-Time Rate Impact: {{ot_rate_impact}} + Claims Ratio Impact: {{claims_ratio_impact}} + Recommended Action: {{carrier_recommended_action}} + +7. LESSONS LEARNED + {{lesson_1}} + {{lesson_2}} + {{lesson_3}} + +8. PROCESS IMPROVEMENTS + {{improvement_1}} — Owner: {{owner_1}} — Due: {{due_date_1}} + {{improvement_2}} — Owner: {{owner_2}} — Due: {{due_date_2}} + {{improvement_3}} — Owner: {{owner_3}} — Due: {{due_date_3}} + +==================================== +Filed in: {{document_management_location}} +``` + +--- + +## 13. Carrier Performance Warning + +### When to Use +- Carrier has a documented pattern of exceptions exceeding acceptable thresholds (e.g., on-time below 90%, claims ratio above 2%, multiple OS&D incidents in a quarter). +- You have data from your TMS or scorecard to support the warning. +- This is a formal notice — not a casual heads-up on a call. It creates a paper trail that supports future routing decisions or contract renegotiation. +- Send after the pattern is established (typically 3+ incidents or a quarter of below-threshold performance), not after a single bad load. + +### Tone Guidance +Data-first and dispassionate. Let the numbers make the case. You are not angry — you are a supply chain professional managing vendor performance. State the expectation, show where they fall short, and define the consequences clearly. Leave room for corrective action — you want them to improve, not just feel punished. + +### What NOT to Say +- Do not make it personal — "your drivers don't care" is not professional. +- Do not issue an ultimatum you are not prepared to enforce. +- Do not send this during an active exception — wait until the current issue is resolved, then address the pattern. +- Do not combine this with a new load tender or positive feedback — it dilutes the message. + +### Subject Line + +``` +Carrier Performance Notice — {{carrier_name}} (MC-{{carrier_mc}}) | {{performance_period}} +``` + +### Body + +``` +{{carrier_contact_name}}, +{{carrier_contact_title}} +{{carrier_name}} + +This letter serves as a formal performance notice regarding {{carrier_name}}'s +service on {{our_company}} freight during the period {{performance_period}}. + +PERFORMANCE SUMMARY: + + Metric Target Actual Variance + ───────────────────── ──────── ──────── ──────── + On-Time Delivery {{ot_target}} {{ot_actual}} {{ot_variance}} + Claims Ratio {{claims_target}} {{claims_actual}} {{claims_variance}} + Tender Acceptance {{ta_target}} {{ta_actual}} {{ta_variance}} + Check-Call Compliance {{cc_target}} {{cc_actual}} {{cc_variance}} + OS&D Incidents {{osd_target}} {{osd_actual}} {{osd_variance}} + +SPECIFIC INCIDENTS: + + {{incident_date_1}} | PRO {{incident_pro_1}} | {{incident_type_1}} | ${{incident_cost_1}} + {{incident_date_2}} | PRO {{incident_pro_2}} | {{incident_type_2}} | ${{incident_cost_2}} + {{incident_date_3}} | PRO {{incident_pro_3}} | {{incident_type_3}} | ${{incident_cost_3}} + {{#if more_incidents}} + ({{additional_incident_count}} additional incidents detailed in attachment) + {{/if}} + + Total Exception Cost ({{performance_period}}): ${{total_period_exception_cost}} + +VOLUME CONTEXT: + +During this period, {{carrier_name}} handled {{total_loads}} loads for +{{our_company}} representing ${{total_freight_spend}} in freight spend. You are +currently ranked {{carrier_rank}} of {{total_carriers}} carriers in our network +for the lanes you serve. + +EXPECTATIONS: + +To maintain current volume and lane assignments, we require: + 1. {{expectation_1}} + 2. {{expectation_2}} + 3. {{expectation_3}} + +We require a written corrective action plan within {{corrective_plan_days}} +business days of this notice. + +CONSEQUENCES: + +If performance does not improve to target levels within {{improvement_period}}: + - {{consequence_1}} + - {{consequence_2}} + - {{consequence_3}} + +We are committed to working with carrier partners who meet our service +standards. I welcome a call to discuss this notice and develop a corrective plan +together. + +Regards, +{{our_contact_name}} +{{our_contact_title}} +{{our_company}} +{{our_contact_phone}} | {{our_contact_email}} + +CC: {{internal_cc_list}} +``` + +--- + +## 14. Customer Apology with Resolution + +### When to Use +- A significant exception has been fully resolved and the customer has received their freight, replacement, or credit. +- The exception was severe enough to warrant a formal acknowledgment beyond the operational updates already sent. +- You want to reinforce the relationship and demonstrate that systemic improvements are being made — not just a one-time fix. + +### Tone Guidance +Genuine and specific. A good apology names the specific impact, describes what was done, and commits to specific prevention steps. It does not grovel or over-apologize — the customer is a business partner, not a victim. It should feel like it was written by a senior professional who understands their business, not a customer service script. End on a forward-looking note. + +### What NOT to Say +- Do not use "we apologize for any inconvenience" — name the actual impact. "I know the two-day delay forced your team to reschedule the retail reset" is ten times more effective. +- Do not blame the carrier or any third party. You own the customer relationship. +- Do not make promises you cannot keep. "This will never happen again" is not credible. "Here are the three specific steps we are implementing" is. +- Do not make this a sales pitch or segue into new services. Stay focused on the resolution. +- Do not send this the same day as the resolution — wait 1–2 business days so the customer has confirmed the resolution is satisfactory. + +### Subject Line + +``` +PO {{po_number}} — Resolution Confirmed and Path Forward +``` + +### Body + +``` +{{customer_contact}}, + +Now that PO {{po_number}} has been fully resolved, I want to close the loop +personally. + +WHAT HAPPENED: +On {{exception_date}}, {{exception_summary_one_sentence}}. This resulted in +{{specific_customer_impact}}. + +WHAT WE DID: + - {{resolution_action_1}} + - {{resolution_action_2}} + - {{resolution_action_3}} + - Final resolution: {{final_resolution_summary}} + +WHAT WE ARE CHANGING: +I do not want to repeat what you experienced. Here are the specific steps we +are putting in place: + + 1. {{prevention_step_1}} + 2. {{prevention_step_2}} + 3. {{prevention_step_3}} + +{{#if financial_goodwill}} +GOODWILL: +{{financial_goodwill_description}} +{{/if}} + +I value your business and I value the trust your team places in us. I take it +personally when we fall short of the standard you expect. + +If you have any remaining concerns about this shipment or anything else, I am +always available at {{our_contact_phone}}. + +Regards, +{{our_contact_name}} +{{our_contact_title}} +{{our_company}} +{{our_contact_phone}} | {{our_contact_email}} +``` + +--- + +## Usage Notes for AI Agents + +**Template Selection:** Match the template to the audience (carrier ops, carrier executive, customer, internal) and the stage of the exception lifecycle (detection, escalation, claims, resolution, post-mortem). When in doubt, start with the lowest-escalation template appropriate for the elapsed time and severity. + +**Variable Substitution:** All `{{variables}}` must be replaced before sending. If a value is unknown, do not leave the placeholder — either obtain the information or remove the section with a note that it will follow. + +**Conditional Sections:** Sections wrapped in `{{#if}}...{{/if}}` are optional and should be included only when the condition applies (e.g., `{{#if pattern_exists}}` in the VP escalation template). + +**Tone Calibration:** The tone guidance for each template reflects the appropriate register for that audience and situation. Do not soften escalation templates to be "nicer" or harden customer templates to be "tougher" — the calibration is deliberate. + +**Legal Disclaimers:** The claims filing cover letter references the Carmack Amendment (49 U.S.C. § 14706), which applies to interstate motor carrier shipments. For brokered freight, international shipments, or intrastate moves, verify the applicable legal framework before sending. When in doubt, route through legal review. + +**Timing:** +- Initial carrier notification: within 1 hour of exception discovery. +- Customer proactive update: within 2 hours of confirmed impact, or before the customer's next business-day start — whichever comes first. +- Escalation to account manager: after 4 hours without response (2 hours for urgent). +- Escalation to VP/Director: after 12–24 hours without account manager resolution. +- Claims filing: as soon as documentation is assembled, within the 9-month statutory window. +- Post-resolution summary: within 5 business days of closure. +- Performance warning: after pattern is documented, not during an active exception. +- Customer apology: 1–2 business days after resolution is confirmed. \ No newline at end of file diff --git a/web-app/public/skills/logistics-exception-management/references/decision-frameworks.md b/web-app/public/skills/logistics-exception-management/references/decision-frameworks.md new file mode 100644 index 00000000..d96e3d12 --- /dev/null +++ b/web-app/public/skills/logistics-exception-management/references/decision-frameworks.md @@ -0,0 +1,1460 @@ +# Decision Frameworks — Logistics Exception Management + +This reference provides the detailed decision logic, scoring matrices, financial models, +and mode-specific resolution workflows for logistics exception management. It is loaded +on demand when the agent needs to make or recommend nuanced exception-handling decisions. + +All thresholds, timelines, and cost assumptions reflect US domestic and international +freight operations across LTL, FTL, parcel, intermodal, ocean, and air modes. + +--- + +## 1. Exception Severity Matrix + +### 1.1 Scoring Methodology + +Every incoming exception is scored across four dimensions. Each dimension produces a +score from 1 to 5. The **composite severity** equals the **highest single-dimension +score**, not the average — a shipment that scores 2/2/2/5 is a Level 5 exception +because a single critical dimension governs urgency. + +After computing the raw composite, apply the **elevation modifiers** in §1.3 to +arrive at the effective severity, which caps at Level 5. + +### 1.2 Full Severity Matrix + +#### Dimension A — Financial Impact + +| Level | Product Value at Risk | Expedite / Re-Ship Cost | Penalty Exposure | Typical Scenarios | +|-------|----------------------|------------------------|-----------------|-------------------| +| 1 — Minimal | < $1,000 | None or < $200 | None | Minor LTL shortage, single damaged carton, residential parcel delay | +| 2 — Moderate | $1,000–$5,000 | $200–$1,500 | Informal customer credit request likely | Multi-carton LTL damage, regional FTL delay 1–2 days, parcel loss with declared value | +| 3 — Significant | $5,000–$25,000 | $1,500–$8,000 | Contractual penalty triggers within 48 hrs | Full pallet damage, FTL delay into customer delivery window, ocean container shortage affecting production schedule | +| 4 — Major | $25,000–$100,000 | $8,000–$35,000 | Active penalty clause or chargeback imminent | Multi-pallet loss, air freight failure on critical launch shipment, reefer failure on full trailer of produce | +| 5 — Critical | > $100,000 | > $35,000 or no expedite option exists | Regulatory fine, contract termination risk, or litigation exposure | Full trailer loss/theft, ocean container of pharma with temp excursion, hazmat incident with EPA/DOT reporting obligation | + +#### Dimension B — Customer Impact + +| Level | Customer Tier | SLA Status | Business Impact to Customer | Typical Scenarios | +|-------|-------------|-----------|---------------------------|-------------------| +| 1 — Minimal | Standard / spot customer | No SLA or well within SLA window | Inconvenience only; customer has inventory buffer | Delay to distributor who carries 30-day stock | +| 2 — Moderate | Regular account | SLA at risk but not yet breached | Customer will notice, may request credit | Delivery misses requested date but within contractual tolerance | +| 3 — Significant | Key account (top 20%) | SLA breach within 24 hrs | Customer's operations impacted; regional stockout possible | Late delivery to DC feeding retail replenishment | +| 4 — Major | Enterprise / strategic account | SLA already breached or will breach today | Customer's production line slowed, retail launch compromised, or their customer is impacted | Automotive JIT delivery failure, retail holiday launch delay | +| 5 — Critical | Tier 1 enterprise or regulated customer | SLA breach + penalty clause triggered | Customer production shutdown, patient safety concern, or regulatory impact to customer | Pharma shipment to hospital, auto assembly plant line-down, government contract with liquidated damages | + +#### Dimension C — Time Sensitivity + +| Level | Available Recovery Window | Alternative Sourcing | Perishability | Typical Scenarios | +|-------|--------------------------|---------------------|--------------|-------------------| +| 1 — Minimal | > 5 business days before customer need-by | Multiple alternatives available | Non-perishable | Stock replenishment with safety stock in place | +| 2 — Moderate | 2–5 business days | Alternatives available but at premium cost | Non-perishable, but inventory turn pressure | Promotional inventory needed before event window | +| 3 — Significant | 24–48 hours | Limited alternatives, ground expedite still viable | Perishable with > 48 hrs remaining shelf life | Fresh produce with 5-day shelf life at day 3 | +| 4 — Major | < 24 hours | Air expedite only option | Perishable with < 48 hrs remaining shelf life, or time-definite service commitment | Temperature-sensitive biotech, next-day surgical supplies | +| 5 — Critical | No window — needed now | No alternative exists or product is custom/irreplaceable | Perishable with < 24 hrs, or already expired in transit | Transplant organs, custom-manufactured parts for shutdown line, court-ordered evidence delivery | + +#### Dimension D — Regulatory / Safety + +| Level | Regulatory Exposure | Safety Concern | Reporting Obligation | Typical Scenarios | +|-------|-------------------|---------------|---------------------|-------------------| +| 1 — None | No regulatory dimension | No safety concern | None | Standard dry freight, consumer goods | +| 2 — Low | Regulatory dimension exists but no violation | Potential quality concern, no safety risk | Internal documentation only | Cosmetics with minor packaging damage, electronics with cosmetic dents | +| 3 — Moderate | Potential regulatory inquiry if not documented properly | Quality compromise that could reach end consumer | Proactive notification to QA team; may require regulatory hold | Food products with cold chain deviation within acceptable range | +| 4 — High | Regulatory violation likely if product reaches market | Potential safety risk to end consumer or handler | Mandatory internal reporting to quality/regulatory within 4 hrs; potential voluntary recall | Pharma with temp excursion beyond validated range, dietary supplements with contamination exposure | +| 5 — Critical | Active regulatory violation; agency notification required | Immediate safety hazard | Mandatory external reporting (FDA, DOT, EPA, FMCSA) within hours; potential mandatory recall | Hazmat spill, pharma temp failure on life-saving medication, foodborne illness risk, leaking chemical container | + +### 1.3 Elevation Modifiers + +Apply these modifiers after computing the raw composite score. Elevation is additive +but caps at Level 5. + +| Condition | Elevation | +|-----------|-----------| +| Customer is under active QBR (quarterly business review) period | +1 level | +| This is the 3rd+ exception on the same lane in 30 days | +1 level | +| Exception occurred on a shipment booked at premium/guaranteed service | +1 level | +| Carrier involved is under corrective action plan | +1 level | +| Shipment is for a new customer (first 90 days of relationship) | +1 level | +| Media or public visibility risk (e.g., branded trailer, viral social media) | +2 levels | +| Exception involves a shipment already recovering from a prior exception | +2 levels | + +### 1.4 Severity-to-Action Mapping + +| Effective Severity | Assigned To | Initial Response SLA | Customer Notification | Internal Notification | Review Cadence | +|-------------------|-------------|---------------------|----------------------|----------------------|---------------| +| Level 1 | Analyst (auto-assign) | 8 business hours | Only if customer inquires | None required | Daily batch review | +| Level 2 | Analyst (auto-assign) | 4 business hours | Proactive if delivery date affected | Team lead dashboard | Daily batch review | +| Level 3 | Senior analyst (manual assign) | 2 hours | Proactive with resolution timeline | Manager notification | Every 4 hours | +| Level 4 | Senior analyst + team lead | 1 hour | Immediate proactive call, then written follow-up | Director notification; account team briefed | Every 2 hours | +| Level 5 | Dedicated handler + manager direct oversight | 30 minutes | VP-to-VP or C-level communication path | VP notification within 1 hour; war-room if multiple Level 5s concurrent | Continuous until stabilized | + +--- + +## 2. Financial Impact Calculation Model + +### 2.1 Total Exception Cost Formula + +``` +Total Exception Cost (TEC) = Product Loss (PL) + + Expedite / Re-Ship Cost (ERC) + + Customer Penalties (CP) + + Administrative Processing Cost (APC) + + Relationship Damage Estimate (RDE) + + Downstream Ripple Cost (DRC) +``` + +### 2.2 Component Definitions and Assumptions + +#### Product Loss (PL) + +PL equals the lesser of (a) replacement cost at current wholesale or (b) original +invoice value, unless the customer contract specifies retail/resale valuation for +chargeback purposes. + +- Damaged but salvageable: PL = invoice value × damage percentage. Use 25% for + cosmetic-only damage, 50% for functional-but-impaired, 100% for unsalvageable. +- Shortage: PL = unit cost × units short. +- Full loss: PL = full invoice value including freight-in if FOB Origin. +- Temperature excursion: PL = full invoice value if excursion exceeds validated range. + No partial credit on regulated products — it is all or nothing. + +#### Expedite / Re-Ship Cost (ERC) + +Standard cost multipliers against base freight cost: + +| Expedite Method | Multiplier vs. Base Rate | Typical Lead Time | When to Use | +|----------------|------------------------|------------------|-------------| +| Ground re-ship (same mode) | 1.0–1.3× | Original transit time | Recovery window > 5 business days | +| Ground expedite (team driver / exclusive-use) | 2.5–4.0× | 40–60% of standard transit | Recovery window 2–5 business days, shipment > 150 lbs | +| LTL guaranteed (volume or guaranteed overnight) | 1.8–2.5× | Next-day to 2-day | Recovery window 1–3 days, shipment < 10,000 lbs | +| Domestic air (next-flight-out, NFO) | 6–12× | Same day or next morning | Recovery window < 24 hrs, shipment < 2,000 lbs | +| Domestic air charter | 15–30× | 4–8 hours | No commercial option fits; production shutdown imminent | +| International air (ex. ocean recovery) | 8–15× ocean base rate | 2–5 days vs. 25–40 days ocean | Recovery window < 2 weeks on ocean lane | +| Hotshot / sprinter van | Flat $2.50–$4.50 per mile | Depends on distance; ~500 mi/day | Small, urgent shipment (< 3,000 lbs); regional recovery | + +Example: Base FTL rate Chicago to Dallas = $2,800. Customer needs delivery in 18 hours +instead of standard 2-day transit. Team driver expedite = $2,800 × 3.0 = $8,400. +Air NFO for 800 lbs at $0.85/lb = $680 freight + $150 handling = $830. Air is cheaper +if weight allows; FTL expedite is cheaper above roughly 4,000–5,000 lbs depending on lane. + +#### Customer Penalties (CP) + +| Penalty Type | Typical Range | Calculation | +|-------------|--------------|-------------| +| Retail chargeback (late delivery to DC) | $500 flat + $50–$150 per carton | Per retailer's vendor compliance guide | +| Retail chargeback (ASN/labeling error from re-ship) | $200–$1,000 flat | Often triggered by rush re-ships that bypass EDI integration | +| OTIF (On-Time In-Full) penalty | 3–8% of invoice value per occurrence | Walmart = 3% of COGS; other retailers vary | +| Production downtime reimbursement | $5,000–$50,000 per hour of line stoppage | Per manufacturing customer contract; automotive lines often $25K+/hr | +| Contractual SLA penalty | 1–5% of monthly freight spend per SLA breach | Cumulative; multiple breaches compound | +| Ad-hoc customer credit / goodwill | 5–15% of invoice as credit memo | Discretionary; used to preserve relationship when no formal penalty exists | + +#### Administrative Processing Cost (APC) + +Internal labor cost to manage the exception from intake to closure: + +| Complexity Tier | Activities | Estimated Hours | Cost at $45/hr Fully Loaded | +|----------------|-----------|----------------|---------------------------| +| Tier 1 — Simple | Log, one carrier call, update customer, close | 1.5–2.5 hrs | $68–$113 | +| Tier 2 — Standard | Log, multiple carrier contacts, file claim, gather docs, customer updates, close | 4–8 hrs | $180–$360 | +| Tier 3 — Complex | All of Tier 2 + inspection coordination, multi-party dispute, escalation, legal review potential | 12–25 hrs | $540–$1,125 | +| Tier 4 — Litigation track | All of Tier 3 + legal engagement, deposition prep, expert witnesses | 40–100+ hrs | $1,800–$4,500+ (plus external legal at $250–$450/hr) | + +#### Relationship Damage Estimate (RDE) + +This is the hardest component to quantify. Use these heuristics: + +- **New customer (< 6 months):** Exception during onboarding carries 3× the + relationship weight. A $2,000 failure can cost a $500K annual account. RDE = 10–20% + of estimated first-year revenue at risk of churn. +- **Stable customer (> 2 years):** Single exception rarely causes churn. RDE = 0–2% + of annual revenue unless it is a pattern (3+ exceptions in 90 days, in which case + treat as new-customer risk). +- **Customer under competitive bid:** Any exception during RFP evaluation period + from a competitor. RDE = 25–50% of annual revenue at risk. + +#### Downstream Ripple Cost (DRC) + +Costs that propagate beyond the immediate exception: + +- Inventory reorder disruption: If exception causes safety-stock depletion, the + replenishment order will be rushed. Estimate 1.5× standard inbound freight for + the replenishment cycle. +- Warehouse receiving disruption: Unexpected returns, re-deliveries, or inspection + holds consume dock door time. Estimate $150–$300 per unplanned dock appointment. +- Customer service call volume: Each exception generates 2–5 inbound customer + inquiries. At $8–$12 per call (including agent time and overhead), that is + $16–$60 per exception. +- Reporting and analytics overhead: Carrier scorecards, root cause analysis + meetings, and corrective action documentation. Estimate 1–3 hours per qualifying + exception at $45/hr. + +### 2.3 Worked Examples + +#### Example A — LTL Damage, Mid-Value + +Shipment: 6 pallets of consumer electronics, Chicago to Atlanta. +Invoice value: $18,500. One pallet fork-punctured at origin terminal. + +``` +PL = $18,500 × (1/6 pallets) × 100% (unsalvageable) = $3,083 +ERC = Re-ship 1 pallet via LTL guaranteed 2-day: $650 = $650 +CP = Retailer OTIF penalty: $18,500 × 3% = $555 + (only if re-ship misses must-arrive-by date) = $555 +APC = Tier 2 standard claim: ~6 hrs × $45 = $270 +RDE = Stable customer, isolated incident: ~0% = $0 +DRC = 3 customer service calls × $10 = $30 +--- +TEC = $3,083 + $650 + $555 + $270 + $0 + $30 = $4,588 +``` + +Decision: File claim for $3,083 product value + $650 re-ship cost = $3,733 carrier +liability claim under Carmack. Customer penalty is shipper's loss unless carrier +proximate cause can support consequential damages (unlikely under standard BOL terms). + +#### Example B — FTL Total Loss, High-Value + +Shipment: Full truckload of medical devices, Memphis to Los Angeles. +Invoice value: $285,000. Shipment not delivered, no scans for 72 hours, presumed stolen. + +``` +PL = $285,000 (full invoice) = $285,000 +ERC = Air charter for replacement: $48,000 = $48,000 +CP = Hospital contract: 2 days production delay at $12,000/day = $24,000 +APC = Tier 4 (theft investigation + legal): ~60 hrs × $45 + + external legal ~20 hrs × $350 = $9,700 +RDE = Strategic account in first year: 15% × $1.2M annual rev = $180,000 +DRC = Safety stock depletion replenishment, expedited inbound = $8,500 +--- +TEC = $285,000 + $48,000 + $24,000 + $9,700 + $180,000 + $8,500 = $555,200 +``` + +Decision: Level 5 severity. Immediate VP notification. Law enforcement report filed. +Carrier cargo insurance claim ($100K per occurrence typical — will not cover full +loss). Shipper's all-risk cargo policy for excess. Customer air-chartered at shipper +expense while claims are pursued. Consider consequential damages claim if carrier +was negligent in vetting driver or equipment. + +#### Example C — Eat-the-Cost Decision + +Shipment: 2 cartons of office supplies, parcel ground, value $380. +One carton crushed, contents destroyed. + +``` +PL = $190 (one carton) = $190 +ERC = Re-ship via ground: $12 = $12 +CP = None (internal office supply order) = $0 +APC = Tier 1 if filed: 2 hrs × $45 = $90 +RDE = N/A (internal) = $0 +DRC = None = $0 +--- +TEC = $190 + $12 + $0 + $90 + $0 + $0 = $292 + +Potential claim recovery: $190 (carrier liability) +Filing cost: $90 (internal processing) +Net recovery: $190 - $90 = $100 +``` + +Decision: Marginal. File only if parcel carrier has automated claims portal with < 15 +minutes processing time. Otherwise absorb and log for quarterly carrier review. + +--- + +## 3. Carrier Response Decision Tree + +### 3.1 Path A — Cooperative Carrier + +The carrier acknowledges the exception, provides updates, and works toward resolution. +This is the expected path with contracted carriers in good standing. + +| Checkpoint | Action | Expected Carrier Response | If Response is Inadequate | +|-----------|--------|--------------------------|--------------------------| +| 0 hrs (intake) | Send initial exception notice via carrier portal or email with PRO#, BOL#, description of exception, requested action, and response deadline | Acknowledgment within 1 hour during business hours | Move to Path B at 2 hrs | +| 2 hrs | Verify carrier acknowledgment received; confirm they have assigned the exception internally | Carrier provides case/reference number and assigned handler name | Escalate to carrier's operations supervisor; send second notice with "Escalation" in subject | +| 4 hrs | Request status update — what has the carrier done so far, what is the plan, what is the revised ETA or inspection timeline | Specific plan with timeline: "Driver ETA 6pm" or "Inspector scheduled tomorrow AM" | Call carrier's account representative (not just dispatch). Document that operational channel is unresponsive | +| 8 hrs | Evaluate progress against carrier's stated plan. If delivery exception: is shipment moving? If damage: is inspection scheduled? | Tangible progress — updated tracking, inspection confirmed, driver checked in | Formal escalation email to carrier VP of Operations or regional director. CC your procurement/carrier management team | +| 24 hrs | Full status review. For delays: confirm revised delivery date. For damage/loss: confirm claim documentation in progress | Delivery completed, or inspection done and claim packet received, or clear revised timeline with daily updates committed | If still unresolved: initiate backup carrier for re-ship (do not wait longer). File formal carrier complaint in carrier management system | +| 48 hrs | Resolution or near-resolution expected for cooperative carriers | Claim acknowledged and in processing, or delivery completed with exception closed | Carrier performance review triggered. Procurement notified for quarterly scorecard impact | +| 72 hrs | Any open delay or loss should be fully resolved or in active claim processing | Claim payment timeline provided (30/60/90 day), or shipment delivered and exception closed | Consider carrier probation for new shipments on this lane | + +### 3.2 Path B — Unresponsive Carrier + +The carrier is not intentionally difficult but is not responding — dispatch is +overwhelmed, claims department is backed up, or the contact information is wrong. +Common with smaller asset carriers and during peak season. + +| Checkpoint | Action | Objective | Escalation | +|-----------|--------|-----------|-----------| +| 0–2 hrs | Standard notice sent, no response received | Establish contact | Try all available channels: portal, email, phone. If broker-arranged shipment, contact broker AND underlying carrier | +| 2 hrs | Call carrier dispatch directly. If no answer, leave voicemail with your callback number and shipment references. Send follow-up email with "URGENT — Response Required" subject | Get any human response | If broker-arranged: put broker on notice that their carrier is unresponsive. Broker has contractual obligation to manage their carrier | +| 4 hrs | Second call to dispatch. Try driver's cell if available (from BOL or load confirmation). Contact carrier's safety/compliance department (different phone tree) as alternative entry point | Any status information | Notify your team lead. Begin contingency planning for re-ship or alternative resolution | +| 8 hrs | Three-channel blitz: call dispatch, email operations manager (find on carrier's website or LinkedIn), send formal notice via certified email or fax referencing carrier's MC/DOT number | Formal documentation of non-response | Authorize re-ship or expedite without waiting for carrier. Send carrier a "Notice of Non-Response" documenting all contact attempts with timestamps | +| 24 hrs | Final notice: "You have 24 hours to respond before we process this as an uncontested claim and adjust payment on open invoices" | Force response through financial leverage | Place freight payment hold on carrier's open invoices (coordinate with AP). File claim based on available documentation. Report to carrier management for immediate lane review | +| 48 hrs | If still no response, treat as abandoned. Process claim against carrier's cargo insurance (contact their insurer directly if you have the policy info from onboarding). If shipment is still in transit/unknown: report to FMCSA for potential out-of-service carrier | Full recovery mode | Remove carrier from active routing guide. Escalate to your legal team if claim value > $10,000 | +| 72 hrs | Formal demand letter from legal or via registered mail citing specific claim amount and legal basis (Carmack for domestic). 30-day response deadline per 49 CFR § 370.9 | Legal posture established | Begin preparation for small claims (< $10K) or federal court filing if value warrants | + +### 3.3 Path C — Adversarial Carrier + +The carrier denies liability, provides false information, disputes documentation, +or acts in bad faith. This includes situations where the carrier's claims department +issues a blanket denial without investigating. + +| Checkpoint | Action | Documentation Priority | Escalation | +|-----------|--------|----------------------|-----------| +| 0 hrs (denial received) | Review denial letter/email line by line. Identify the specific basis for denial (act of shipper, inherent vice, act of God, packaging, etc.) | Preserve all original documentation. Screenshot carrier portal status history before it can be altered | Assign to senior analyst or claims specialist, not junior staff | +| 2 hrs | Draft point-by-point rebuttal addressing each denial reason with documentary evidence. Under Carmack, once shipper proves three elements (good condition at tender, damaged at delivery, damages amount), burden shifts to carrier | Organize evidence package: clean BOL, exception-noted POD, photos, packing specs, weight certificates, temperature logs | Brief team lead on denial and planned rebuttal strategy | +| 4 hrs | Send formal rebuttal via email and carrier portal with all supporting evidence attached. Request "reconsideration of claim denial" and cite specific regulatory basis for carrier liability | Send via method that provides delivery confirmation. Keep copies of everything sent | If denial is clearly frivolous (e.g., "act of God" for a forklift puncture), notify carrier's account manager that denial is damaging the relationship | +| 8 hrs | If carrier reaffirms denial: request the carrier's specific evidence supporting their defense. Under 49 CFR § 370.7, carrier must conduct a reasonable investigation before denying | Log all communications with exact timestamps. Note any inconsistencies between carrier's stated reasons and available evidence | Notify your manager and procurement. Begin calculating whether litigation cost is justified vs. claim value | +| 24 hrs | Escalate to carrier's VP of Claims or General Counsel with a summary letter: claim facts, evidence, legal basis, prior communications timeline, and a settlement demand | Prepare a claim file that is litigation-ready even if you hope to settle: chronological narrative, evidence index, damages calculation, legal authority summary | Procurement to issue formal notice of dispute to carrier's sales team. Separate the business relationship discussion from the claims dispute | +| 48 hrs | If no movement: engage third-party claims service or freight claims attorney for demand letter on legal letterhead. Cost: typically $500–$1,500 for demand letter, contingency fee of 25–33% if litigation needed | Provide complete file to outside counsel. Flag any potential weaknesses in your case (late filing, incomplete POD, packaging shortfalls) | Consider whether the carrier's business overall is worth preserving. If annual spend < claim value, this may be the last shipment regardless | +| 72 hrs+ | Decision point: litigate, settle at a discount, or absorb. See §9 Eat-the-Cost Analysis for framework | Final evidence review and case assessment | VP-level decision on litigation vs. settlement vs. walk-away | + +### 3.4 Special Situation — Carrier Goes Dark Mid-Shipment + +When a carrier stops responding and the freight is in transit (not yet delivered): + +1. **Hour 0–1:** Attempt all contact channels (dispatch, driver cell, broker if applicable, carrier safety department). Check last known GPS/ELD position if available through your TMS integration or load-tracking platform. + +2. **Hour 1–4:** Contact the carrier's insurance company to verify the policy is active. If brokered, demand the broker provide proof of last contact with the driver and GPS coordinates. If no GPS data available and shipment is high-value (> $50K), consider engaging a freight recovery service. + +3. **Hour 4–8:** If high-value or theft indicators present (carrier is new, load was double-brokered, pickup was in a high-theft corridor like Los Angeles, Memphis, Dallas, or the I-10/I-95 corridors): file a report with local law enforcement in the jurisdiction of last known location. Notify CargoNet or FreightWatch if you have a subscription. + +4. **Hour 8–24:** If the carrier is a broker's carrier: put the broker on formal notice that they are liable for the full shipment value. If the carrier is your contracted carrier: activate your contingency carrier for the lane and begin re-shipping replacement product. + +5. **Hour 24+:** Treat as presumed theft/loss. File formal claim. Notify your cargo insurance underwriter. Do not wait for "certainty" — the claim clock starts ticking. + +--- + +## 4. Claims Filing Decision Framework + +### 4.1 File vs. Absorb vs. Negotiate Pre-Claim + +The decision to file a formal claim is not automatic. Each path has costs and trade-offs. + +#### Decision Matrix + +| Scenario | Recommended Path | Rationale | +|----------|-----------------|-----------| +| Claim value < $250, carrier has self-service portal | File via portal (< 15 min effort) | Automated filing cost is near-zero; builds claims history for scorecard | +| Claim value < $500, no portal, good carrier relationship | Absorb, log for scorecard | APC exceeds likely net recovery. Mention informally to carrier rep at next review | +| Claim value $500–$2,500, clear carrier liability | Negotiate pre-claim: call carrier and propose a freight credit or invoice deduction | Faster resolution (days vs. months), preserves relationship, avoids formal claims overhead | +| Claim value $500–$2,500, disputed liability | File formal claim with documentation | Dispute needs formal record; informal negotiation without documentation weakens your position | +| Claim value $2,500–$10,000 | File formal claim regardless of circumstances | Value justifies APC and relationship friction. Negotiate settlement only above 75% of claimed amount | +| Claim value > $10,000 | File formal claim + involve senior management + legal awareness | Financial materiality threshold. Full documentation package. Independent inspection for damage claims. Accept settlement only above 85% or with strong business justification | +| Any amount, 3rd+ claim against same carrier in 90 days | File formal claim AND trigger carrier performance review | Pattern indicates systemic issue; formal filing creates the record needed for contract renegotiation or termination | +| Any amount, possible fraud indicators | File formal claim + notify compliance + preserve all evidence | Even small-dollar fraud must be documented. Patterns emerge only when individual incidents are formally recorded | + +#### ROI Calculation for Filing + +``` +Net Claim ROI = (Claim Amount × Probability of Recovery) - APC + +where: + Claim Amount = documented loss value (PL + ERC if carrier-caused) + Probability of Recovery = see §4.2 below + APC = administrative processing cost from §2.2 +``` + +File when Net Claim ROI > $0 and the ratio (Net Claim ROI / Claim Amount) > 15%. +Below 15% net margin on the claim, the organizational cost-of-attention often +exceeds the financial benefit unless the claim builds a needed pattern record. + +### 4.2 Probability of Recovery by Carrier Type and Claim Type + +These recovery rates reflect industry experience across hundreds of thousands of +claims. Adjust ±10% based on your specific carrier relationships and documentation +quality. + +| Carrier Type | Damage (visible, noted on POD) | Damage (concealed) | Shortage (noted at delivery) | Full Loss | Delay (service failure) | +|-------------|-------------------------------|-------------------|----------------------------|----------|----------------------| +| National LTL (FedEx Freight, XPO, Estes, ODFL) | 80–90% | 40–55% | 70–80% | 85–95% | 15–25% (unless guaranteed service) | +| Regional LTL | 70–85% | 30–45% | 60–75% | 75–85% | 10–20% | +| Asset FTL carrier (large fleet) | 75–90% | 35–50% | 65–80% | 80–90% | 20–35% | +| Small FTL carrier (< 50 trucks) | 55–70% | 20–35% | 45–60% | 50–65% | 5–15% | +| Broker-arranged FTL | 60–75% | 25–40% | 50–65% | 60–75% | 10–20% | +| Parcel (UPS, FedEx, USPS) | 70–85% | 45–60% | 60–75% | 80–90% | 30–50% (guaranteed service) | +| Ocean (FCL) | 30–50% | 15–25% | 40–55% | 60–75% | < 5% | +| Ocean (LCL) | 25–40% | 10–20% | 30–45% | 50–65% | < 5% | +| Air freight (direct with airline) | 65–80% | 35–50% | 55–70% | 75–85% | 20–35% | +| Air freight (via forwarder) | 55–70% | 25–40% | 45–60% | 65–80% | 15–25% | + +### 4.3 Documentation Checklist by Claim Type + +#### Damage Claim — All Modes + +Required: +- [ ] Original BOL (signed, showing clean receipt by carrier at origin) +- [ ] Delivery receipt / POD (showing exception notation — "damaged," "crushed," specific description) +- [ ] Photographs: minimum 4 views (overview of shipment, close-up of damage, packaging condition, label/PRO visible) +- [ ] Commercial invoice showing product value +- [ ] Packing list showing piece count and descriptions +- [ ] Written description of damage (what is damaged, extent, whether repairable) +- [ ] Repair estimate or replacement quote from vendor +- [ ] Packaging specifications (demonstrates product was packaged appropriately for the mode) + +Strongly recommended: +- [ ] Weight certificate at origin (proves correct weight tendered) +- [ ] Inspection report from independent surveyor (required for claims > $10,000 or disputed claims) +- [ ] Temperature recorder data (for any temperature-sensitive product) +- [ ] Photos from origin showing product in good condition at loading +- [ ] Carrier inspection report (request from carrier's OS&D department) + +#### Shortage Claim + +Required: +- [ ] Original BOL showing piece count tendered +- [ ] Delivery receipt showing piece count received (discrepancy noted) +- [ ] Commercial invoice for shorted product +- [ ] Packing list with serial numbers or lot numbers if available +- [ ] Written description: how many pieces short, which items, value per item + +Strongly recommended: +- [ ] Loading photos/video showing correct count at origin +- [ ] Seal numbers (origin seal vs. delivery seal — different seal = carrier liability strong) +- [ ] Weight certificate at origin vs. weight at delivery (weight discrepancy corroborates shortage) +- [ ] Security camera footage from dock (if available and shipment is high-value) + +#### Loss Claim (Full Shipment) + +Required: +- [ ] Original BOL (proves tender to carrier) +- [ ] Carrier pickup confirmation / signed pickup receipt +- [ ] Commercial invoice (full shipment value) +- [ ] Packing list (complete contents) +- [ ] Formal tracer request filed with carrier (with carrier's response or non-response documented) +- [ ] Proof of non-delivery: customer confirmation that product was never received + +Strongly recommended: +- [ ] GPS/tracking history showing last known position +- [ ] Law enforcement report (if theft suspected) +- [ ] Carrier's insurance certificate (to file directly against insurer if carrier is unresponsive) +- [ ] Evidence of carrier tender acceptance and load confirmation + +#### Delay Claim (Service Failure) + +Required: +- [ ] Original BOL showing agreed pickup and delivery dates +- [ ] Service level documentation (rate confirmation, routing guide showing guaranteed service) +- [ ] Tracking history showing actual delivery date/time +- [ ] Proof of financial loss caused by delay (penalty invoice, expedite receipt, lost sales documentation) + +Strongly recommended: +- [ ] Customer correspondence showing delivery commitment that was based on carrier's service +- [ ] Evidence that delay was not caused by shipper or consignee (no appointment changes, dock available) +- [ ] Documentation of mitigation efforts (you tried to minimize the loss) + +### 4.4 Mode-Specific Filing Requirements + +#### US Domestic Surface — Carmack Amendment (49 USC § 14706) + +- **Jurisdiction:** All domestic surface transportation by motor carriers and freight forwarders operating under FMCSA authority. +- **Filing deadline:** 9 months from date of delivery (or reasonable delivery date for non-delivery claims). +- **Statute of limitations for litigation:** 2 years from the date the carrier disallows the claim. +- **Carrier liability standard:** Carrier is strictly liable for actual loss, damage, or injury to goods. Carrier defenses: act of God, public enemy, act of shipper, public authority, inherent nature of goods. +- **Shipper's burden:** (1) Goods were in good condition when tendered. (2) Goods were damaged/lost/short at destination. (3) Amount of damages. +- **Limitation of liability:** Carriers may limit liability via released rates (lower rate in exchange for lower liability cap). Check your rate confirmation and BOL for released value clauses. If you did not agree to a released rate, full actual value applies. +- **Filing method:** Written claim in any reasonable form that (a) identifies the shipment, (b) asserts liability, and (c) demands payment of a specific amount. 49 CFR § 370.3. +- **Carrier response obligation:** Must acknowledge within 30 days. Must pay, decline, or make a firm settlement offer within 120 days. 49 CFR § 370.9. + +#### Ocean — Carriage of Goods by Sea Act (COGSA) / Hague-Visby Rules + +- **Jurisdiction:** International ocean shipments to/from US ports (COGSA); most international ocean shipments (Hague-Visby). +- **Filing deadline:** Written notice of damage within 3 days of delivery (visible damage) or 3 days after delivery ends (concealed damage) under COGSA. Failure to give notice creates a presumption that goods were delivered in good condition — it does not bar the claim, but shifts the burden of proof. +- **Statute of limitations:** 1 year from delivery date (COGSA). This is a hard deadline — cannot be extended without carrier agreement. +- **Carrier liability standard:** Carrier is liable unless they prove one of 17 enumerated exceptions (perils of the sea, act of God, insufficiency of packing, etc.). Burden of proof is complex and shifting. +- **Liability limit:** $500 per package or customary freight unit (COGSA). SDR 666.67 per package or SDR 2 per kg gross weight, whichever is higher (Hague-Visby). Higher value must be declared on the bill of lading before shipment. +- **Critical documentation:** Ocean bill of lading, survey report at discharge port (hire a marine surveyor — typical cost $800–$2,500 depending on port), container inspection report, seal integrity evidence, reefer download data for temperature-controlled. + +#### Air — Montreal Convention (International) / Air Cargo Act (Domestic US) + +- **Jurisdiction:** International air carriage (Montreal Convention); domestic US air freight is governed by the air waybill terms and applicable contract law. +- **Notice deadline:** 14 days from receipt for damage claims. 21 days from delivery date for delay claims. These deadlines are strictly enforced — missing them is a complete bar to the claim. +- **Statute of limitations:** 2 years from date of arrival or from the date the aircraft ought to have arrived. +- **Liability limit:** 22 SDR per kilogram (~$30/kg, fluctuates with exchange rates). Higher value must be declared on the air waybill. Most airlines offer declared-value surcharges of 0.5–0.75% of excess value. +- **Filing method:** Written complaint to the airline or handling agent. Include air waybill number, flight numbers, claim details, and damage documentation. +- **Key nuance:** Ground handling agents (the companies that physically handle freight at airports) cause the majority of air freight damage, but the airline is liable to the shipper under Montreal Convention. The airline then has a subrogation claim against the handler. + +--- + +## 5. Mode-Specific Resolution Workflows + +### 5.1 LTL Damage Resolution + +#### 5.1.1 Terminal-Caused Damage + +Damage occurring at carrier's terminal during cross-dock operations (forklift +damage, stacking failures, improperly loaded onto delivery trailer). + +**Indicators:** Damage pattern consistent with handling (fork punctures, crush from +top-loading, stretch wrap torn with product exposed). Often discovered at delivery +terminal or by consignee. + +**Resolution Workflow:** + +1. **Consignee documents on POD** — specific notation: "2 of 6 pallets crushed, + product visible through torn packaging." Generic "damaged" is insufficient for + strong claims. +2. **Photograph at delivery** — minimum 6 photos: overall shipment, each damaged + unit, packaging failure point, freight label/PRO visible in frame, floor of + trailer showing debris. +3. **Request carrier terminal inspection** — call the delivering terminal directly + (not the 800-number). Ask for the OS&D clerk or terminal manager. Request that + damaged freight be held for inspection, not sent to salvage. +4. **File claim within 48 hours** — terminal damage claims have highest recovery + rates (80–90%) because the carrier knows their terminal caused it. Do not delay. +5. **If partial damage** — request carrier's salvage bid. Carriers sometimes offer + to sell damaged freight at auction and credit the difference. Evaluate whether the + salvage value is fair; reject lowball salvage bids (common tactic to reduce claim + payout). +6. **Settlement expectation** — terminal-caused damage should settle at 85–100% + of invoice value within 60 days. If carrier offers less than 75%, escalate to + carrier's claims manager with terminal inspection evidence. + +#### 5.1.2 Transit Damage + +Damage occurring during over-the-road transit (shifting loads, hard braking, trailer +accident, weather infiltration through damaged trailer roof/walls). + +**Indicators:** Product shifted within packaging, load bars displaced, multiple +pallets damaged in the same direction (forward movement = hard stop). + +**Resolution Workflow:** + +1. **Determine if damage is from a known incident** — ask carrier dispatch: "Was + there any reported incident involving this trailer in transit?" Carriers are + required to log accidents, but minor incidents (hard braking, pothole impact) + often go unreported. +2. **Document loading condition evidence** — if you have photos from loading dock + showing freight was properly loaded, secured with load bars/straps, and braced + appropriately, your claim is significantly stronger. +3. **Weigh the shipment** — if you can get a weight ticket from a scale near the + delivery point, compare to the origin weight ticket. Significant discrepancy + combined with damage suggests freight shifted or fell off a pallet. +4. **File claim within 5 business days** — transit damage is moderately strong for + the shipper (70–85% recovery). Carrier will investigate with the driver and + potentially dispute if they believe packaging was insufficient. +5. **Common carrier defense** — "Inadequate packaging." Counter with: packaging + specifications from the manufacturer, ISTA or ASTM test results if available, + and evidence that the same packaging has shipped successfully on this lane before + without damage. +6. **Settlement expectation** — 60–85% of invoice value within 90 days. Transit + damage claims often involve more back-and-forth than terminal damage. + +#### 5.1.3 Loading Damage (Origin) + +Damage caused during pickup when the carrier's driver or dock workers load the +freight onto the trailer. + +**Indicators:** Driver signs clean BOL at origin. Damage discovered at first +cross-dock terminal or at delivery. Damage pattern consistent with improper +stacking, dropping during loading, or trailer incompatibility (e.g., product loaded +in a trailer with protruding floor nails). + +**Resolution Workflow:** + +1. **Check for driver exception notations on pickup BOL** — if the driver noted + "shipper load and count" (SL&C), carrier will argue they are not liable for + how the product was loaded. SL&C is the shipper's enemy on damage claims. If + your dock loaded the trailer while the driver was in the office, this notation + is legitimate and weakens your claim. +2. **If carrier's driver loaded** — your claim is strong. Document that your dock + staff witnessed proper product condition before loading and that the carrier's + driver conducted the loading. +3. **First-terminal inspection** — if damage is discovered at the first terminal, + request photos from the terminal before freight is further handled. This narrows + the damage window to pickup-to-first-terminal. +4. **File claim within 5 business days** — include the clean-signed BOL from origin + and the exception-noted delivery receipt. +5. **Settlement expectation** — 70–85% if you can prove damage occurred during + carrier loading. Under 50% if SL&C was notated and you cannot prove carrier + handling caused the damage. + +### 5.2 FTL Delay Resolution + +#### 5.2.1 Driver-Caused Delay + +Late pickup, wrong routing, hours-of-service (HOS) violation forcing a rest stop, +driver no-show. + +**Resolution Workflow:** + +1. **Hour 0 (delay identified):** Contact dispatch. Get the driver's current + location, reason for delay, and revised ETA. If driver no-showed at origin: + demand a replacement driver or tractor within 2 hours, or you are tendering + to backup carrier. +2. **Hour 2:** If revised ETA is within customer tolerance, monitor. If not: + calculate whether a team driver can recover the schedule. Team driver cost adder + is typically $0.25–$0.40/mile on top of the base rate. +3. **Hour 4:** If delay will cause a customer miss: authorize the team driver or + arrange backup carrier from the driver's current location. The original carrier + is responsible for the deadhead to the driver's current location (demand credit + or refuse to pay for the partial haul). +4. **Hour 8+:** If carrier cannot recover the shipment and you have re-tendered to + a backup carrier: deduct the expedite cost difference from the original carrier's + open invoices. Document everything for the debit. +5. **Post-resolution:** Record the service failure in the carrier scorecard. If + this is a pattern (2+ HOS-driven delays from same carrier in 60 days), their + fleet management and driver scheduling practices need review. + +#### 5.2.2 Mechanical Breakdown + +Tractor or trailer breakdown in transit. + +**Resolution Workflow:** + +1. **Hour 0:** Carrier should notify you proactively per contract terms. If you + discover via tracking: call dispatch immediately. +2. **Assess repair timeline:** If carrier says "truck will be repaired in 2 hours" + — accept and monitor. If > 4 hours or uncertain: demand the carrier power-swap + (send a replacement tractor to the breakdown location). Major carriers can + power-swap within 2–4 hours in most metro areas. +3. **Reefer breakdown:** If reefer unit fails on a temperature-sensitive load, this + becomes a product quality issue, not just a delay. Request the carrier download + the reefer unit data log immediately. If ambient temperature is > 40°F and + product is cold-chain: begin contingency for product replacement within 2 hours + of reefer failure confirmation. +4. **Carrier liability for mechanical:** Carrier is generally liable for delays caused + by mechanical failure — it is not "act of God." However, contractual terms may + exclude or limit delay liability. Check your carrier agreement. +5. **Cost allocation:** Carrier should absorb any power-swap costs and incremental + transit cost. If you had to re-tender to a backup carrier, deduct the cost + difference from the original carrier. + +#### 5.2.3 Weather Delay + +Legitimate severe weather (winter storms, hurricanes, flooding, tornado activity) +that prevents safe transit. + +**Resolution Workflow:** + +1. **Verify the weather event** — check NOAA and FMCSA road condition reports for + the specific route. Carriers sometimes claim "weather" for a light rain. The + delay must be proportional to the actual event severity. +2. **Determine if the delay was avoidable** — if the weather was forecasted 48+ + hours in advance and the carrier could have routed around it or departed earlier: + this is a planning failure, not force majeure. Challenge the carrier's defense. +3. **Customer communication** — notify immediately with the weather event details + and revised ETA. Customers generally understand weather delays if communicated + proactively. Do not wait until the delivery window expires to notify. +4. **Cost allocation** — true force majeure: neither party at fault. Carrier is not + liable for delay. Shipper cannot deduct. Expedite costs after the weather clears + are negotiable — the carrier should prioritize your shipment for recovery without + charging a premium. If they try to charge expedite rates for post-weather recovery, + push back. +5. **Pattern recognition** — if a lane experiences 3+ weather delays per season + (e.g., Denver to Salt Lake City in January), build weather buffers into your + transit time commitments for that lane rather than treating each as an exception. + +#### 5.2.4 Capacity-Driven Delay + +Carrier accepted the tender but cannot cover it — no driver available. Common during +peak season and month-end volume spikes. + +**Resolution Workflow:** + +1. **Hour 0 (carrier notifies or fails to cover):** Do not wait. Immediately + re-tender to backup carriers. Do not give the primary carrier "until end of day" + — capacity tightens as the day progresses. Every hour of delay reduces your + options. +2. **Hour 2:** If primary carrier has not confirmed a driver: they have effectively + rejected the tender. Re-tender to backup or spot market. The primary carrier + owes you nothing for the delay (they did not pick up the freight), but you should + record the service failure as a tender acceptance failure. +3. **Spot market premium:** If you must go to the spot market, the premium over + contract rate is your loss. Track this as "tender rejection cost" in carrier + scorecards. Typical spot premiums: 15–40% in normal market, 50–150% during + peak events or regional disruptions. +4. **Contractual leverage:** If your carrier contract has tender acceptance minimums + (e.g., 90% acceptance rate), document every failure. Aggregate for quarterly + review. Carriers who repeatedly accept tenders and then fail to cover are worse + than carriers who reject upfront — they destroy your ability to plan. + +### 5.3 Parcel Loss Resolution + +#### 5.3.1 Ground Parcel Loss + +**Resolution Workflow:** + +1. **Day 1 past expected delivery:** Check tracking. If status is "delivered" but + customer says not received: request proof of delivery (signature, GPS stamp, photo). + If no GPS/photo evidence, the carrier's "delivered" scan is insufficient. +2. **Day 2:** File online tracer through carrier portal. UPS: 1 business day for + tracer investigation. FedEx: 1–2 business days. USPS: mail search request, allow + 5–10 business days. +3. **Day 3–5:** If tracer comes back "unable to locate": file formal claim through + carrier portal. +4. **Day 5–10:** Re-ship replacement to customer. Do not wait for claim resolution + to keep the customer whole. +5. **Claim processing:** UPS and FedEx typically resolve parcel claims within 5–8 + business days of filing. USPS: 30–60 days. Ensure declared value was purchased + at time of shipping — default coverage is $100 (UPS/FedEx) or $50 (USPS Priority). +6. **If claim denied:** Most common denial reason is "insufficient declared value." + If you declared the correct value at shipping, escalate. If you did not declare + sufficient value, the recovery is capped at the default limit regardless of + actual product value. This is an expensive lesson — ensure high-value parcel + shipments always have declared value coverage. + +#### 5.3.2 Air Parcel Loss (Next-Day/2-Day) + +Same workflow as ground with these adjustments: +- Tracer filing is faster: file same day as missed delivery. Guaranteed service + means the carrier prioritizes the investigation. +- Money-back guarantee: for late delivery on guaranteed services, file for full + shipping cost refund regardless of whether the product arrives the next day. This + is separate from a loss claim. +- UPS and FedEx each have automated money-back guarantee claim portals. For late + NDA (Next Day Air), the refund is the full air shipping cost. These refunds can + be significant on heavy or multi-package shipments. + +#### 5.3.3 International Parcel Loss + +- Customs holds are the most common cause of apparent "loss" in international parcel. + Check customs status before filing a tracer. +- International parcel claims involve both the origin country carrier and the + destination country carrier (or postal service). Filing is through the origin + carrier. +- Liability is governed by the Universal Postal Convention (for postal services) + or the carrier's tariff (for UPS/FedEx/DHL international). UPS international + declared value cap is $50,000. +- Allow 30–90 days for international claim resolution due to multi-country + investigation requirements. +- For DDP (Delivered Duty Paid) shipments, you are responsible for duties/taxes + as part of the shipment value. Include these in the claim amount. + +### 5.4 Ocean Container Shortage Resolution + +#### 5.4.1 FCL (Full Container Load) Shortage + +Container delivered with fewer pieces than the packing list, despite the container +seal being intact (or seal being different from the origin seal). + +**Resolution Workflow:** + +1. **At container unload:** Count every piece before signing the delivery receipt. + If the container is being unloaded at a CFS (Container Freight Station), ensure + the CFS provides a tally sheet. +2. **Check the seal:** Compare the seal number on the container door to the seal + number on the bill of lading. If they match and are intact: the shortage likely + occurred at the origin (stuffing error). Carrier liability is weak — this is + a shipper/origin warehouse issue. If the seal is broken or does not match: carrier + liability is strong. Photograph the seal immediately. +3. **File notice of shortage within 3 days** (COGSA requirement for concealed + shortage). File with the ocean carrier AND the party who delivered the container + (drayage company or terminal). +4. **Hire a marine surveyor** if the shortage value exceeds $5,000. The surveyor's + report is the gold standard evidence for ocean claims. Cost: $800–$2,500 + depending on the port and survey complexity. +5. **Claim filing:** File against the ocean carrier under the bill of lading terms. + If the BL incorporates COGSA, liability is capped at $500 per package (a "package" + in FCL is typically interpreted as each carton, not the container). If you declared + a higher value on the BL, the higher value applies. +6. **Recovery expectation:** FCL shortages with matching intact seals: 20–35% + recovery (carrier argues origin stuffing error). FCL shortages with broken/mismatched + seals: 65–80% recovery. + +#### 5.4.2 LCL (Less than Container Load) Shortage + +Product consolidated with other shippers' freight in a shared container. Shortages +are more common due to additional handling at CFS facilities at both origin and +destination. + +**Resolution Workflow:** + +1. **At CFS pickup/delivery:** Verify piece count against the house bill of lading + (not the master BL, which covers the full container). Annotate any discrepancy + on the CFS tally sheet and delivery receipt. +2. **Identify the shortage point:** Was the shortage at origin CFS (loaded fewer + pieces), in transit, or at destination CFS (pieces misallocated to another + consignee's lot)? Request the CFS tally reports from both origin and destination. +3. **Check for cross-allocation:** In LCL, your cargo may have been mistakenly + delivered to another consignee in the same container. Request the destination + CFS check all lots from the same container for over-shipment. +4. **File claim with the NVOCC or freight forwarder** who issued your house bill + of lading. They are your contracting party. They will subrogate against the ocean + carrier or CFS operator as appropriate. +5. **Recovery expectation:** LCL shortage claims take longer (90–180 days) and + recover at lower rates (30–50%) due to the difficulty of proving where in the + multi-handler chain the shortage occurred. + +### 5.5 Air Freight Damage Resolution + +#### 5.5.1 Airline Handling Damage + +Damage caused by the airline's cargo handling team during loading, transit, or +unloading of the aircraft. + +**Resolution Workflow:** + +1. **At pickup from airline cargo terminal:** Inspect all pieces before signing the + cargo release. Note any damage on the release form with specific descriptions: + "carton #3 crushed on north face, contents exposed." Do not accept shipment + without noting the damage — once you sign clean, your concealed damage notice + window is only 14 days under Montreal Convention. +2. **File written notice within 14 days** — this is a hard deadline. Miss it and + the claim is barred. Send notice to the airline's cargo claims department and to + the handling agent at the arrival airport. +3. **Document the chain of custody:** Air freight often moves through multiple + handlers: origin forwarder → origin ground handler → airline → destination ground + handler → destination forwarder. Identify which handler had custody when the + damage occurred. The airline's internal damage reporting ("damage noted during + build-up/breakdown") is helpful — request it from the airline's cargo + department. +4. **Liability under Montreal Convention:** 22 SDR/kg (approximately $30/kg). For + a 500 kg shipment, the maximum recovery is roughly $15,000 regardless of product + value. If your product value significantly exceeds the weight-based limit, you + should have purchased declared-value surcharge at booking (typically 0.50–0.75% + of the excess value). If you did not, recovery is capped at the Convention limit. +5. **Recovery expectation:** Airline direct claims with proper documentation: + 65–80% of the applicable liability limit within 60–90 days. + +#### 5.5.2 Ground Handler Damage + +Damage caused by the ground handling company (Swissport, Menzies, WFS, dnata, etc.) +that operates on behalf of the airline at the airport. + +**Resolution Workflow:** + +1. **Shipper files against the airline** — under Montreal Convention, the airline + is liable to the shipper regardless of whether the airline or the ground handler + caused the damage. The shipper does not need to prove which party handled the + freight at the time of damage. +2. **Provide evidence to the airline** — the airline will conduct its own + investigation and may pursue the ground handler for indemnification. Providing + the airline with clear evidence (time-stamped photos, handling records, warehouse + receipt stamps) speeds the process. +3. **If the airline denies** — they may argue the damage was pre-existing or caused + by inadequate packaging. Counter with origin photos, packaging specifications, + and the air waybill special handling instructions (e.g., "fragile," "this side up") + that the handler failed to follow. +4. **Direct claim against ground handler:** In some cases, especially when the + airline is uncooperative, filing a direct claim against the ground handler under + local tort law is viable. Consult with an air cargo attorney — this is a + specialized area. + +### 5.6 Intermodal Liability Resolution + +#### 5.6.1 Determining Liability Between Rail and Dray + +Intermodal shipments involve at least two carriers: a drayage company (trucker) that +picks up the container/trailer at the rail terminal and delivers to the consignee, +and a railroad (BNSF, UP, CSX, NS, etc.) that performs the linehaul. + +**Resolution Workflow:** + +1. **Obtain the interchange records.** When the container moves from rail to dray + (or dray to rail), an interchange inspection is supposed to occur. The interchange + report documents the condition of the container and chassis at handoff. This + document determines liability allocation. + +2. **If damage is noted on the interchange report at rail-to-dray handoff:** + Rail is liable. File the claim with the railroad or the intermodal marketing + company (IMC) that booked the rail leg. Railroad claims are governed by the + Carmack Amendment for domestic intermodal. + +3. **If the interchange report is clean at rail-to-dray handoff, and damage is + found at delivery:** Drayage company is liable. The damage occurred during + the dray leg (local trucking from rail terminal to consignee). File with the + dray carrier. + +4. **If no interchange report exists** (common — many terminals skip this step): + Liability is disputed. Both the railroad and the dray will point at each other. + In this situation: + - File claims against both parties simultaneously. + - Provide the same evidence package to both. + - The party with the weaker defense will typically settle first. + - If neither settles: your claim is against the contracting party (whoever is + on your bill of lading), and they can subrogate against the other. + +5. **Railroad-specific considerations:** + - Railroads have their own claims rules and are notoriously slow (90–180 days + for resolution). + - Impact damage (shifting during railcar coupling, hard stops, derailment) is + common. Railroads have internal impact recording devices — request the data. + - Temperature damage on reefer intermodal: the rail carrier is responsible for + maintaining the reefer unit during rail transit if GenSet service was purchased. + If you provided a self-powered reefer unit, the rail carrier may argue the + unit failed on its own. + +6. **Chassis damage vs. cargo damage:** If the chassis (the wheeled frame the + container sits on) was damaged, causing the container to tilt or drop, this is + typically a rail terminal or dray carrier issue depending on where the chassis + was sourced. Chassis pool operators (DCLI, TRAC, Flexi-Van) may also be liable. + This creates a three-party dispute — carrier, chassis pool, and terminal operator. + +--- + +## 6. Escalation Matrix + +### 6.1 Internal Escalation — Who, When, How + +| Severity / Trigger | Escalation Target (Role) | Information Required | Channel | Expected Response Time | Follow-Up Cadence | +|--------------------|--------------------------|---------------------|---------|----------------------|-------------------| +| Level 1 exception, no resolution after 48 hrs | Exception Team Lead | Exception summary, carrier contact log, current status | Email (team queue) or Slack/Teams channel | 4 business hours | Daily until resolved | +| Level 2 exception, no resolution after 24 hrs | Exception Team Lead | Exception summary, financial impact estimate, carrier response history | Email with priority flag + verbal heads-up | 2 business hours | Every 8 hours | +| Level 3 exception at intake | Exception Manager | Full exception brief: financial impact, customer impact, timeline, carrier status, recommended action | Phone call + email follow-up within 30 min | 1 hour | Every 4 hours | +| Level 4 exception at intake | Director of Logistics / Director of Customer Operations | Executive summary: TEC calculation, customer risk, recommended action with cost estimate, alternatives considered | Phone call first, then email to director + CC manager | 30 minutes | Every 2 hours | +| Level 5 exception at intake | VP Supply Chain + VP Sales (if customer-facing) | One-page executive brief: situation, financial exposure, customer impact, recommended immediate action, resource needs | Phone call to VP, then email summary to VP + director + manager. Schedule war-room call within 1 hour | 15 minutes | Continuous (war room) until stabilized, then every hour | +| Carrier non-response after 4 hrs | Procurement / Carrier Management Analyst | Carrier name, MC#, exception details, all contact attempts with timestamps | Email to carrier management team | 4 business hours | Once (they own the carrier relationship escalation) | +| Carrier non-response after 24 hrs | Procurement Manager / Director of Transportation | All of above + recommended financial leverage (invoice hold, lane removal) | Phone + email | 2 business hours | Daily until resolved | +| Carrier claims denial > $10,000 | Legal / Risk Management Counsel | Complete claim file: claim filing, carrier denial, rebuttal sent, all evidence, financial exposure | Email with claim file attached + meeting request within 48 hrs | 48 hours for initial review | Weekly until disposition decided | +| Customer escalation (customer contacts their account manager or executive) | Sales Account Manager + Exception Manager | Current exception status, all actions taken, timeline of communications, what we need from the customer | Immediate phone call to account manager + email brief | 30 minutes | Match the customer's requested cadence (usually every 4–8 hours) | +| Potential fraud or compliance concern | Compliance Officer / Internal Audit | All available evidence, basis for suspicion, parties involved, recommended hold actions | Confidential email to compliance (do not discuss on open channels) | 4 business hours | As directed by compliance | +| Regulatory reporting event (hazmat, food safety, pharma) | Quality/Regulatory Affairs Manager + Legal | Product details, exception specifics, regulatory exposure assessment, recommended agency notifications | Phone call immediately + email within 30 min | 15 minutes | Continuous until regulatory obligations met | + +### 6.2 External Escalation — Carrier-Side Contacts + +| Escalation Level | Carrier Contact (Title) | When to Engage | What to Say | Expected Outcome | +|-----------------|------------------------|---------------|-------------|-----------------| +| Level 1 | Carrier Customer Service / Dispatch Agent | First contact for any exception | State the exception, provide references, request status and ETA | Information and initial action | +| Level 2 | Operations Supervisor / Terminal Manager | When Level 1 is unresponsive (2 hrs) or unable to resolve | Reference the open case number, state the business impact, request supervisor intervention | Escalated attention, possible override of standard process | +| Level 3 | Regional Operations Director or VP Operations | When 2+ business days with no resolution, or high-value exception | Formal email referencing all prior communications, stating financial exposure and expected resolution | Direct oversight, dedicated resource assigned | +| Level 4 | Carrier Account Manager / Director of Sales | When operational channels have failed and you need a business relationship lever | Contact through your procurement team. Frame as "this unresolved exception is affecting our routing decisions for this carrier" | Carrier sales team pressures their operations to resolve, often yields fastest results | +| Level 5 | Carrier CEO / General Counsel | Litigation-track only, or when all other paths exhausted on high-value claim | Formal demand letter from your legal counsel to carrier's registered agent or general counsel | Legal posture established, settlement negotiation begins | + +### 6.3 External Escalation — Third Parties + +| Party | When to Engage | Contact Method | Cost | Expected Outcome | +|-------|---------------|---------------|------|-----------------| +| Independent marine / cargo surveyor | Damage claim > $5,000, or any disputed damage | Engage through your insurance broker's surveyor network, or directly via NAMS (National Association of Marine Surveyors) | $800–$2,500 per survey (domestic); $1,500–$5,000 (international) | Independent damage assessment report admissible in claims and litigation | +| Third-party claims management firm | When internal claims volume exceeds capacity, or for complex multi-modal claims | Contract through RFP or direct engagement. Major firms: CIS (Claims Information Services), TranSolutions, NovaTrans | Contingency fee 25–33% of recovery, or flat fee $200–$800 per claim depending on complexity | Professional claims handling with higher recovery rates (typically 10–15% higher than in-house for complex claims) | +| Freight claims attorney | Denied claims > $25,000, or any claim heading to litigation | Engage through industry referral (Transportation Intermediaries Association, Transportation Lawyers Association) | Contingency 25–33%, or hourly $250–$450 for pre-litigation work | Legal demand, negotiation, or litigation | +| FMCSA (Federal Motor Carrier Safety Administration) | Carrier safety violations, out-of-service carrier, registration issues | File complaint online at NCCDB (National Consumer Complaint Database) or call 1-888-368-7238 | Free | Investigation of carrier safety record; public record | +| STB (Surface Transportation Board) | Rate disputes, service complaints against railroads, intermodal disputes that cannot be resolved commercially | File formal complaint with the STB | Filing fees vary; legal representation recommended | Regulatory review and potential order against carrier | +| Cargo insurance underwriter | Any loss exceeding your self-insured retention (SIR), or any total loss on insured shipment | Notify per your policy terms (typically within 30 days of loss discovery). Contact your insurance broker first | Claim against your own policy; subject to deductible and SIR | Insurance recovery minus deductible. Insurer may subrogate against carrier | + +--- + +## 7. Time-Based Decision Triggers + +### 7.1 Checkpoint Framework + +This framework defines what decisions must be made and what actions must be taken at +specific time intervals from exception intake. "Intake" is when the exception is first +identified, regardless of when it actually occurred. + +#### Checkpoint: 2 Hours Post-Intake + +| Decision | Detail | +|----------|--------| +| Severity classified? | Must have a score. If insufficient information to score, default to one level above what you suspect and gather data to confirm/downgrade | +| Carrier contacted? | Initial contact must be made. If unable to reach carrier at 2 hrs, this is now Path B (Unresponsive) | +| Customer notification needed? | Level 3+: customer must be notified by this checkpoint. Level 1–2: only if customer has already inquired | +| Expedite decision needed? | If time sensitivity is Level 4+, the expedite vs. wait decision cannot wait past this checkpoint. Authorize or decline | +| Is this a pattern? | Quick check: same carrier, same lane, same customer in last 30 days? If yes, apply elevation modifier | + +#### Checkpoint: 4 Hours Post-Intake + +| Decision | Detail | +|----------|--------| +| Carrier response received? | If no response: escalate to carrier operations supervisor. Switch to Path B protocol | +| Resolution timeline established? | Carrier should have provided a plan and timeline. If not: this is a carrier performance failure in addition to the original exception | +| Internal escalation needed? | Level 3+: manager should be aware by now. Level 4+: director must be briefed | +| Customer update #2 | For Level 3+: provide update even if no new information — silence is worse than "we're still working on it" | +| Backup plan activated? | For time-sensitive exceptions: backup carrier or expedite method should be identified and on standby | + +#### Checkpoint: 8 Hours Post-Intake (End of Business Day) + +| Decision | Detail | +|----------|--------| +| Will this resolve today? | Honest assessment. If not: set next-day actions and ensure overnight monitoring for Level 4+ | +| Financial impact calculated? | Full TEC should be computed by this point for Level 3+ exceptions | +| Documentation gathered? | Photos, POD, BOL — everything needed for a claim should be in hand or requested with a deadline | +| Customer expectation set? | Customer should have a specific revised delivery date or resolution timeline. Do not give "TBD" past 8 hours | +| After-hours coverage needed? | For Level 4+: assign after-hours on-call responsibility. Provide the on-call person with a complete brief | + +#### Checkpoint: 24 Hours Post-Intake + +| Decision | Detail | +|----------|--------| +| Resolution achieved? | Level 1–2 exceptions should be resolved or near-resolution by 24 hrs. If not: why? | +| Claim filing decision made? | For damage/shortage/loss: you should know by now whether you are filing a claim, negotiating, or absorbing | +| Carrier accountability documented? | Regardless of resolution, the carrier's performance on this exception must be logged for scorecard purposes | +| Customer satisfaction check | For Level 3+: brief check-in with the customer. Are they satisfied with the resolution or progress? Adjust if needed | +| Aging alert set | If not resolved: ensure the exception is in the "aging" report and will be reviewed at the next team stand-up | + +#### Checkpoint: 48 Hours Post-Intake + +| Decision | Detail | +|----------|--------| +| Escalation review | Any exception open 48 hrs without clear resolution path: escalate to the next level in the chain, regardless of severity | +| Claim filed? | If claim was warranted, it should be filed by now. Every day of delay weakens the claim (evidence degrades, carrier disputes increase) | +| Root cause identified? | Even if the exception is not fully resolved, the root cause should be understood. If not: dedicate analytical resource to determine it | +| Carrier relationship impact assessed? | Procurement/carrier management should have a view on whether this carrier needs a corrective action discussion | + +#### Checkpoint: 72 Hours Post-Intake + +| Decision | Detail | +|----------|--------| +| Resolution or plan | Exception must be either resolved OR have a documented resolution plan with a specific completion date | +| Management review | All exceptions open > 72 hrs should be on the manager's weekly review report | +| Customer mitigation complete? | Any customer-facing mitigation (re-ship, credit, expedite) should be completed by this point. The customer should not be waiting | + +#### Checkpoint: 5 Business Days + +| Decision | Detail | +|----------|--------| +| Concealed damage window closing | 5 days is the industry-standard window for concealed damage claims. If damage was discovered post-delivery, the claim must be filed by this point | +| Team lead review | Team lead should review any exception open 5 days and assess whether it is being handled efficiently or is stuck | + +#### Checkpoint: 10 Business Days + +| Decision | Detail | +|----------|--------| +| Claim acknowledgment received? | If claim was filed, carrier must acknowledge within 30 days (per 49 CFR § 370.9), but should acknowledge within 10 business days. If not: follow up formally | +| Exception aging report | 10-day open exceptions should appear on the manager-level report with a status update required | + +#### Checkpoint: 30 Calendar Days + +| Decision | Detail | +|----------|--------| +| Claim acknowledgment mandatory deadline | 30 days is the carrier's regulatory deadline to acknowledge a domestic claim. If not acknowledged: send formal notice citing 49 CFR § 370.9 and state that failure to comply is a regulatory violation | +| Financial write-off or reserve decision | For unresolved claims: finance team should either reserve the claim amount or write it off, depending on recovery probability assessment | +| Carrier performance review trigger | Any carrier with an exception open 30 days without resolution should be in a formal performance review conversation | + +### 7.2 Checkpoint Failure Protocol + +When a checkpoint decision is not made or action not taken by the deadline: + +1. **Immediate notification** to the next level in the escalation chain. +2. **Root cause of the miss:** Was it capacity (analyst overwhelmed), information + (waiting on carrier/customer), process (no clear owner), or judgment (analyst + unsure how to proceed)? +3. **Recovery action:** Assign fresh eyes. A different analyst reviews the exception + and picks up from the current state. Stale exceptions tend to stay stale with + the same handler. +4. **Process improvement:** If the same checkpoint is repeatedly missed across + multiple exceptions, this is a systemic issue requiring process or staffing + review. + +--- + +## 8. Multi-Exception Triage Protocol + +### 8.1 When to Activate Triage Mode + +Activate formal triage when any of these conditions are met: + +- 5+ new exceptions in a single 4-hour window +- 3+ Level 3+ exceptions active simultaneously +- A widespread disruption event (weather system, carrier outage, port closure, major highway closure) is generating exceptions faster than the team can process individually +- Peak season daily exception volume exceeds 150% of the 30-day rolling average + +### 8.2 Triage Commander Role + +Designate a single **triage commander** (typically the team lead or the most senior +analyst available) who: + +- Stops working individual exceptions. +- Takes ownership of triage decisions: who works what, in what order. +- Provides a single point of status aggregation for management and customer-facing + teams. +- Has authority to re-assign analyst workloads, authorize expedites up to a + pre-approved threshold ($10,000 per incident without additional approval), and + communicate directly with carrier account managers and customer account teams. + +### 8.3 Triage Scoring — Rapid Prioritization + +When volume overwhelms the standard severity matrix process, use this rapid +triage scoring: + +| Factor | Score 3 (Highest Priority) | Score 2 | Score 1 (Lowest Priority) | +|--------|---------------------------|---------|--------------------------| +| Time to customer impact | < 8 hours | 8–48 hours | > 48 hours | +| Product at risk | Perishable, hazmat, pharma | High-value non-perishable (> $25K) | Standard product < $25K | +| Customer tier | Enterprise / penalty contract | Key account | Standard | +| Resolution complexity | Requires multi-party coordination | Single carrier, single action needed | Self-resolving (e.g., weather clearing) | +| Can it wait 4 hours? | No — irreversible damage if delayed | Probably, but will cost more | Yes, no penalty for delay | + +Sum the scores (max 15). Process exceptions in descending score order. +Ties are broken by: (1) regulatory/safety always wins, (2) then highest dollar +value, (3) then oldest exception. + +### 8.4 Triage Communication Protocol + +During a triage event: + +**Internal:** +- Triage commander sends a status update to management every 2 hours (or more + frequently if Level 5 exceptions are active). +- Status update format: total exceptions active, top 3 by priority with one-line + status each, resource utilization (analysts assigned / available), estimated + clearance timeline. +- Each analyst provides a 2-sentence status on each assigned exception every 2 + hours to the triage commander. + +**Customer-facing:** +- For widespread events (weather, carrier outage): issue a single proactive + communication to all affected customers rather than individual reactive updates. + Template: "We are aware of [event]. [X] shipments are potentially affected. + We are actively working with carriers to reroute/recover. Your account team + will provide individual shipment updates within [X] hours." +- For individual high-priority exceptions during triage: customer update cadence + does not change (per severity level). The triage commander ensures high-priority + customer updates are not missed because the analyst is overwhelmed. + +**Carrier:** +- During widespread events, contact the carrier's account manager or VP of + Operations (not dispatch) to get a single point of contact for all affected + shipments. Working shipment-by-shipment through dispatch during a triage event + is inefficient. +- Request a carrier-side recovery plan for all affected shipments as a batch. + +### 8.5 Resource Allocation During Triage + +| Exception Priority (Triage Score) | Analyst Allocation | Manager Involvement | Customer Communication | +|-----------------------------------|--------------------|--------------------|-----------------------| +| Score 13–15 (Critical) | Dedicated senior analyst, 1:1 ratio | Direct manager oversight | VP or account director handles | +| Score 10–12 (High) | Senior analyst, up to 3:1 ratio | Manager briefed every 2 hours | Account manager handles | +| Score 7–9 (Medium) | Analyst, up to 5:1 ratio | Included in batch status report | Standard proactive template | +| Score 4–6 (Low) | Deferred or batch-processed | No individual oversight | Reactive only (respond if customer asks) | + +### 8.6 Triage Deactivation + +Deactivate triage mode when: +- Active exception count drops below 5 +- No Level 3+ exceptions remain unresolved +- New exception intake rate returns to within 120% of the 30-day rolling average +- All high-priority customer impacts are resolved or mitigated + +Conduct a triage debrief within 48 hours of deactivation: what went well, what +broke, what needs to change for next time. + +--- + +## 9. Eat-the-Cost Analysis Framework + +### 9.1 Decision Model + +The eat-the-cost decision determines whether pursuing a claim or dispute recovery +generates a positive return after all costs — financial, temporal, and relational — +are considered. + +``` +Net Recovery Value (NRV) = (Claim Amount × Recovery Probability × Time-Value Discount) + - Processing Cost + - Opportunity Cost + - Relationship Cost + +If NRV > 0 and NRV / Claim Amount > 15%: FILE +If NRV > 0 but NRV / Claim Amount < 15%: FILE only if pattern documentation needed +If NRV ≤ 0: ABSORB and log for carrier scorecard +``` + +### 9.2 Component Calculations + +#### Processing Cost by Complexity Tier + +| Tier | Criteria | Internal Hours | External Cost | Total Estimated Cost | +|------|----------|---------------|--------------|---------------------| +| A — Automated | Parcel claim via portal, simple damage with clear POD notation | 0.5 hrs ($23) | $0 | $23 | +| B — Simple | LTL damage with good documentation, cooperative carrier, value < $2,500 | 2–3 hrs ($90–$135) | $0 | $90–$135 | +| C — Standard | FTL damage/loss, value $2,500–$10,000, standard claim process | 5–8 hrs ($225–$360) | $0 | $225–$360 | +| D — Complex | Multi-party dispute, ocean/air with international filing, disputed liability | 12–20 hrs ($540–$900) | Surveyor $800–$2,500 | $1,340–$3,400 | +| E — Litigation-track | Denied claim heading to legal, value > $25,000 | 30–60 hrs ($1,350–$2,700) | Attorney $5,000–$25,000+ | $6,350–$27,700+ | + +#### Recovery Probability Adjustments + +Start with the base recovery probabilities from §4.2 and adjust: + +| Factor | Adjustment | +|--------|-----------| +| Documentation is complete and clean (photos, clean BOL, noted POD) | +10% | +| Documentation is incomplete (missing photos or POD unsigned) | -15% | +| Carrier has a history of paying claims promptly | +5% | +| Carrier has a history of denying or slow-walking claims | -10% | +| Claim is filed within 7 days of delivery | +5% | +| Claim is filed 30+ days after delivery | -10% | +| Independent survey/inspection supports the claim | +15% | +| Product is temperature-controlled with continuous logger data | +10% (if data supports excursion) or -25% (if data is ambiguous or missing) | + +#### Time-Value Discount + +Claims take time. The money recovered 120 days from now is worth less than money +in hand today. + +``` +Time-Value Discount Factor = 1 / (1 + (annual_cost_of_capital × estimated_days_to_recovery / 365)) + +Typical: annual cost of capital = 8-12% +``` + +| Estimated Days to Recovery | Discount Factor (at 10% annual) | +|---------------------------|-------------------------------| +| 30 days | 0.992 | +| 60 days | 0.984 | +| 90 days | 0.976 | +| 120 days | 0.968 | +| 180 days | 0.953 | +| 365 days | 0.909 | + +For most claims, the time-value discount is small (1–5%) and rarely drives the +decision. It matters most for large claims (> $50K) with long expected resolution +timelines (> 180 days). + +#### Opportunity Cost + +Every hour an analyst spends on a low-value claim is an hour not spent on a +higher-value exception. Estimate: + +``` +Opportunity Cost = Processing Hours × (Average Exception Value Recovered per Analyst Hour - $45 blended labor cost) + +Typical: An experienced analyst recovers ~$1,200 per hour of claims work (blended across all claim sizes). +Opportunity Cost ≈ Processing Hours × ($1,200 - $45) = Processing Hours × $1,155 +``` + +This is the most often overlooked component. Filing a $500 claim that takes 4 hours +to process costs the organization 4 × $1,155 = $4,620 in recoveries NOT pursued +on other higher-value exceptions. + +However, this applies only when the analyst has a backlog of higher-value work. +During low-volume periods, opportunity cost approaches zero and the threshold for +filing drops. + +#### Relationship Cost + +This is the qualitative overlay. Assign one of these values: + +| Carrier Relationship Status | Relationship Cost Factor | +|----------------------------|------------------------| +| New carrier (< 6 months), building relationship | $500 imputed cost — filing a claim this early sends a signal. Absorb small claims if possible and address in the quarterly review | +| Established carrier (6+ months), good relationship | $0 — professional carriers expect claims as part of the business. Filing does not damage the relationship if done respectfully | +| Strategic carrier (top 5 by spend, or sole-source on critical lanes) | $250 imputed cost — even though the relationship is strong enough to handle claims, there is a negotiation overhead and quarterly review complexity | +| Carrier under corrective action or on probation | Negative cost: -$200 (i.e., filing the claim is relationship-positive because it creates the documentation trail needed for contract renegotiation or termination) | + +### 9.3 Worked Examples + +#### Example: Should We File This $850 LTL Damage Claim? + +``` +Claim Amount: $850 +Carrier: National LTL, established relationship (18 months) +Documentation: Complete (clean BOL, noted POD, photos) +Complexity: Tier B (Simple) +Base Recovery Prob: 85% (national LTL, visible damage noted on POD) +Adjustments: +10% (complete documentation) → 95% (cap at 95%) + +Processing Cost: 2.5 hrs × $45 = $113 +Opportunity Cost: During peak season, analyst backlog is high → + 2.5 hrs × $1,155 = $2,888 + During slow season (January): $0 + +Relationship Cost: $0 (established, good relationship) +Time-Value: 60-day expected resolution → discount factor 0.984 + +NRV (peak season) = ($850 × 0.95 × 0.984) - $113 - $2,888 - $0 + = $794 - $113 - $2,888 = -$2,207 → DO NOT FILE + +NRV (slow season) = ($850 × 0.95 × 0.984) - $113 - $0 - $0 + = $794 - $113 = $681 → FILE (NRV/Claim = 80%) +``` + +During peak season, the analyst's time is better spent on higher-value +exceptions. During slow season, file it — the analyst has bandwidth. + +#### Example: Should We File This $3,200 FTL Shortage Claim Against a Small Carrier? + +``` +Claim Amount: $3,200 +Carrier: Small asset carrier (12 trucks), 8-month relationship +Documentation: Incomplete — POD was signed clean (driver left before + count completed), shortage discovered 1 hour later +Base Recovery Prob: 55% (small FTL carrier, shortage) +Adjustments: -15% (clean POD) → 40% +Complexity: Tier C (Standard) + +Processing Cost: 6 hrs × $45 = $270 +Opportunity Cost: 6 hrs × $1,155 = $6,930 (peak), $0 (slow) +Relationship Cost: $500 (relatively new carrier) +Time-Value: 120-day expected → 0.968 + +NRV (peak) = ($3,200 × 0.40 × 0.968) - $270 - $6,930 - $500 + = $1,239 - $270 - $6,930 - $500 = -$6,461 → DO NOT FILE + +NRV (slow) = ($3,200 × 0.40 × 0.968) - $270 - $0 - $500 + = $1,239 - $270 - $500 = $469 → MARGINAL + +Filing Ratio = $469 / $3,200 = 14.7% → BELOW 15% threshold → ABSORB +``` + +Even in the slow season, the low recovery probability (due to the clean POD) +makes this a marginal claim. Decision: absorb, but use this as a coaching +moment with the consignee about never signing clean before completing the count. +Log for carrier scorecard. If it happens again with the same carrier, the pattern +changes the calculus — file the second claim and reference both incidents. + +--- + +## 10. Seasonal Adjustment Factors + +### 10.1 Peak Season Adjustments (October–January) + +During peak season, carrier networks are strained, transit times extend, exception +rates increase 30–50%, and claims departments slow down. Adjust decision frameworks +accordingly. + +| Parameter | Standard Setting | Peak Season Adjustment | Rationale | +|-----------|-----------------|----------------------|-----------| +| Carrier response SLA (before escalation) | 2 hours | 4 hours | Carrier dispatch is overwhelmed; allow more time before declaring unresponsive | +| Customer notification threshold | Level 3+ proactive | Level 2+ proactive | Customer expectations are already fragile during peak; proactive communication prevents inbound complaint calls | +| Expedite authorization threshold | Manager approval > $5,000 | Manager approval > $10,000 | Expedite costs are inflated 50–100% during peak; air capacity is scarce. Raise the bar for what justifies a premium expedite | +| Eat-the-cost threshold | < $500 absorb | < $750 absorb | APC increases during peak (analysts are juggling more exceptions). Internal cost of claims processing rises | +| Claims filing timeline | Within 5 business days | Within 10 business days | Realistic given volume. Still well within the 9-month Carmack window | +| Carrier scorecard impact weight | Standard | 0.75× weighting | Across-the-board service degradation during peak is industry-wide. Do not penalize carriers disproportionately for systemic conditions, but still document everything | +| Triage mode activation threshold | 5+ simultaneous exceptions | 8+ simultaneous (expect a higher baseline) | Baseline exception volume is higher; activate triage based on deviation from the elevated baseline | +| Customer communication frequency (active exceptions) | Every 4 hours for Level 3+ | Every 8 hours for Level 3+ | Volume requires longer update cycles. Communicate the adjusted cadence to customer upfront: "During the holiday shipping season, we'll provide updates every 8 hours unless there is a material change" | +| Settlement acceptance threshold | > 75% for $500–$2,500 range | > 65% for $500–$2,500 range | Faster settlement frees capacity for higher-value claims. Accept slightly lower recoveries to close volume | + +### 10.2 Weather Event Adjustments + +Applied when a named weather system (winter storm, hurricane, tropical storm) or +widespread severe weather (tornado outbreak, flooding) is actively disrupting a +region. + +| Parameter | Standard Setting | Weather Event Adjustment | Duration | +|-----------|-----------------|------------------------|----------| +| Carrier response SLA | 2 hours | 8 hours (carrier dispatch may be evacuated or overwhelmed) | Until 48 hours after last weather advisory expires | +| Force majeure acceptance | Require specific documentation | Accept carrier's force majeure claim if weather event is confirmed by NOAA for the route and timeframe | Event duration + 72 hours recovery | +| Expedite decisions | Standard ROI calculation | Suspend expedite for affected lanes until roads/airports reopen. Redirect expedite spend to alternative routing | Until carrier confirms lane is clear | +| Customer communication | Standard cadence per severity | Issue blanket proactive communication to all customers with shipments on affected lanes. Individual follow-ups only for Level 4+ | Until all affected shipments are rescheduled | +| Exception severity scoring | Standard matrix | Reduce time-sensitivity dimension by 1 level for weather-affected shipments (customer tolerance is higher for force majeure events) | Event duration + 24 hours | +| Claim filing | Standard timeline | Delay claim filing for weather events; focus on recovery and rerouting. File after the event when full impact is known | File within 30 days of delivery/non-delivery | +| Carrier scorecard | Standard weighting | 0.5× weighting for weather-affected lanes. Document for pattern tracking but do not penalize individual events | Exceptions within the event window only | + +### 10.3 Produce / Perishable Season Adjustments (April–September) + +Temperature-sensitive shipments increase dramatically. Reefer capacity tightens. +Temperature exceptions spike. + +| Parameter | Standard Setting | Produce Season Adjustment | Rationale | +|-----------|-----------------|--------------------------|-----------| +| Temperature excursion response time | 2 hours to contact carrier | 1 hour to contact carrier | Perishable shelf life is non-recoverable. Every hour of delay in response reduces the salvageable value | +| Pre-trip inspection documentation | Recommended | Required — do not load without confirmed pre-trip on reefer unit | Carrier defense #1 is "reefer was fine at dispatch; product was loaded warm." Pre-trip eliminates this | +| Continuous temperature logging | Required for pharma/biotech | Required for ALL perishable shipments including produce, dairy, frozen food | Carrier disputes on temperature are unresolvable without continuous data | +| Reefer breakdown escalation | 4 hours before power-swap demand | 2 hours before power-swap demand | Product degradation accelerates with ambient temperature. In July, a reefer failure in Phoenix means product loss in under 2 hours | +| Carrier reefer fleet age threshold | Accept carriers with reefer units < 10 years old | Prefer carriers with reefer units < 5 years old during peak produce season | Older reefer units fail at higher rates in extreme heat | +| Claim documentation for temperature | Standard photo + logger | Add: pre-cool records, loading temperature readings (infrared gun logs), in-transit monitoring alerts, reefer unit download data | Temperature claims require more evidence than any other claim type. Produce buyers and carriers both dispute aggressively | + +### 10.4 Month-End / Quarter-End Adjustments + +The last 5 business days of any month (and especially quarter) see volume spikes, +carrier tender rejections, and increased exception rates as shippers rush to meet +revenue recognition deadlines. + +| Parameter | Standard Setting | Month/Quarter-End Adjustment | Rationale | +|-----------|-----------------|------------------------------|-----------| +| Backup carrier readiness | Pre-identified for top 20 lanes | Pre-identified and confirmed available for top 50 lanes | Tender rejection rates spike 25–40% at month-end. Having confirmed backup capacity prevents scrambling | +| Tender rejection response time | 2 hours to re-tender | 1 hour to re-tender | Every hour matters when the month is closing. Spot market tightens through the day | +| Spot market premium approval | Manager approval > 20% over contract rate | Manager pre-approval up to 35% over contract rate | Speed of authorization matters more than cost optimization at month-end. Pre-authorize higher thresholds | +| Double-brokering verification | Standard onboarding check | Enhanced verification for any new or infrequent carrier used at month-end: confirm MC#, confirm truck matches BOL, confirm driver identity | Double-brokering spikes when capacity is tight and brokers scramble to cover loads they've committed | +| Exception reporting frequency | Daily summary | Twice-daily summary (midday and close of business) to operations leadership | Executives need real-time visibility into end-of-period exceptions that could affect revenue or delivery commitments | + +### 10.5 Adjustment Interaction Rules + +When multiple seasonal adjustments are active simultaneously (e.g., peak season + +weather event in December): + +1. Apply the **more permissive** adjustment for carrier-facing parameters (response + SLAs, scorecard weighting). Do not stack — use the adjustment that grants the + carrier the most latitude. +2. Apply the **more conservative** adjustment for customer-facing parameters + (notification thresholds, communication frequency). If peak says "Level 2+ + proactive" and weather says "blanket communication to all affected," use the + blanket communication. +3. Apply the **lower** eat-the-cost threshold (i.e., absorb more). Overlapping + stress periods mean higher APC and lower recovery probabilities. +4. Internal escalation thresholds remain at the **tighter** of any applicable + adjustment. Overlapping stress events mean higher risk, not lower. +5. Document which adjustments are active and communicate to the team. A triage + event during peak season with active weather is a different operating posture + than normal operations — everyone must be calibrated to the same adjusted + thresholds. + +--- + +## Appendix A — Quick-Reference Decision Cards + +### Card 1: "Should I escalate this?" + +``` +IF severity ≥ 3 → YES, to manager +IF severity ≥ 4 → YES, to director +IF severity = 5 → YES, to VP +IF carrier non-response > 4 hrs → YES, to carrier ops supervisor +IF carrier non-response > 24 hrs → YES, to carrier account manager + your procurement +IF customer has called about it → YES, to at least team lead +IF it smells like fraud → YES, to compliance immediately +``` + +### Card 2: "Should I file this claim?" + +``` +IF value < $250 and portal available → FILE (automated, low effort) +IF value < $500 and no portal → ABSORB unless it is a pattern +IF value $500–$2,500 → RUN NRV CALC (see §9) +IF value > $2,500 → FILE regardless +IF this is the 3rd+ incident same carrier 90 days → FILE and flag for carrier review +IF documentation is weak (no POD notation, no photos) → NEGOTIATE informally first, file only if carrier acknowledges liability +``` + +### Card 3: "Should I expedite a replacement?" + +``` +IF customer impact ≥ Level 4 → YES, authorize now, sort out cost later +IF customer impact = Level 3 → CALCULATE: expedite cost vs. customer penalty + relationship damage +IF customer impact ≤ Level 2 → STANDARD re-ship unless customer specifically requests +IF product is perishable and original is salvageable → DO NOT re-ship; instead reroute or discount the original +IF product is custom/irreplaceable → EXPEDITE the manufacturing queue, not just the shipping +``` + +### Card 4: "What do I do first when 10 exceptions land at once?" + +``` +1. ACTIVATE triage mode +2. SCORE each exception using rapid triage (§8.3) — takes ~2 min per exception +3. SORT by score descending +4. ASSIGN: top 3 to senior analysts (1:1), next 4 to analysts (2:1), bottom 3 to batch queue +5. COMMUNICATE: send blanket status to customer teams, single contact to carrier account managers +6. UPDATE triage commander every 2 hours +7. DEACTIVATE when active count < 5 and no Level 3+ remain +``` + +--- + +## Appendix B — Acronyms and Glossary + +| Term | Definition | +|------|-----------| +| APC | Administrative Processing Cost — internal labor cost to handle an exception | +| ASN | Advanced Shipping Notice — EDI 856 document notifying customer of incoming shipment | +| BOL / BL | Bill of Lading — the shipping contract between shipper and carrier | +| CFS | Container Freight Station — warehouse at a port where LCL cargo is consolidated/deconsolidated | +| COGSA | Carriage of Goods by Sea Act — US statute governing ocean carrier liability | +| DRC | Downstream Ripple Cost — secondary costs caused by the exception | +| ELD | Electronic Logging Device — required device tracking driver hours of service | +| ERC | Expedite / Re-Ship Cost — cost to recover from the exception via expedited shipment | +| FCL | Full Container Load — ocean shipping where one shipper uses the entire container | +| FMCSA | Federal Motor Carrier Safety Administration — US agency regulating trucking | +| FTL | Full Truckload — one shipper, one truck, dock-to-dock | +| HOS | Hours of Service — FMCSA regulations limiting driver driving/on-duty time | +| IMC | Intermodal Marketing Company — broker of intermodal (rail+truck) services | +| JIT | Just-In-Time — manufacturing/supply chain strategy with minimal inventory buffers | +| LCL | Less than Container Load — ocean shipping where multiple shippers share a container | +| LTL | Less than Truckload — shared carrier network with terminal cross-docking | +| MC# | Motor Carrier number — FMCSA-issued operating authority identifier | +| NFO | Next Flight Out — expedited air freight on the next available commercial flight | +| NRV | Net Recovery Value — expected financial return from pursuing a claim | +| NVOCC | Non-Vessel Operating Common Carrier — freight intermediary in ocean shipping | +| OS&D | Over, Short & Damage — carrier department handling freight exceptions | +| OTIF | On Time In Full — delivery performance metric | +| PL | Product Loss — value of product damaged, lost, or shorted | +| POD | Proof of Delivery — signed delivery receipt | +| PRO# | Progressive Rotating Order number — carrier's shipment tracking number (LTL) | +| QBR | Quarterly Business Review — periodic meeting between shipper and carrier/customer | +| RDE | Relationship Damage Estimate — imputed cost of relationship harm from exception | +| SDR | Special Drawing Rights — IMF currency unit used in international transport liability limits | +| SIR | Self-Insured Retention — amount the shipper pays before insurance coverage applies | +| SL&C | Shipper Load & Count — BOL notation indicating carrier did not verify the load | +| STB | Surface Transportation Board — US agency with jurisdiction over rail and some intermodal disputes | +| TEC | Total Exception Cost — comprehensive cost of an exception including all components | +| TMS | Transportation Management System — software for managing freight operations | +| WMS | Warehouse Management System — software for managing warehouse operations | diff --git a/web-app/public/skills/logistics-exception-management/references/edge-cases.md b/web-app/public/skills/logistics-exception-management/references/edge-cases.md new file mode 100644 index 00000000..5c226792 --- /dev/null +++ b/web-app/public/skills/logistics-exception-management/references/edge-cases.md @@ -0,0 +1,734 @@ +# Logistics Exception Management — Edge Cases Reference + +> Tier 3 reference. Load on demand when handling complex or ambiguous exceptions that don't resolve through standard workflows. + +These edge cases represent the scenarios that separate experienced exception management professionals from everyone else. Each one involves competing claims, ambiguous liability, time pressure, and real financial exposure. They are structured to guide resolution when standard playbooks break down. + +--- + +## How to Use This File + +When an exception doesn't fit a clean category — when liability is genuinely unclear, when multiple parties have plausible claims, or when the financial exposure justifies deeper analysis — find the edge case below that most closely matches the situation. Follow the expert approach step by step. Do not skip documentation requirements; they exist because these are the cases that end up in arbitration or litigation. + +--- + +### Edge Case 1: Temperature-Controlled Pharma Shipment — Reefer Failure with Disputed Loading Temperature + +**Situation:** +A regional pharmaceutical distributor ships 14 pallets of insulin (Humalog and Novolog pens, wholesale value ~$2.1M) from a cold storage facility in Memphis to a hospital network distribution center in Atlanta. The shipment requires continuous 2–8°C (36–46°F) storage per USP <1079> guidelines. The reefer unit is a 2021 Carrier Transicold X4 7500 on a 53-foot trailer pulled by a contract carrier running under their own authority. + +Upon arrival 18 hours later, the receiving pharmacist's temperature probe reads 14°C (57°F) at the pallet surface. The TempTale 4 data logger packed inside the shipment shows the temperature climbed above 8°C approximately 6 hours into transit and continued rising. The carrier's in-cab reefer display download shows the setpoint was 4°C and the unit was in "continuous" mode, not "cycle-spool." The carrier produces a pre-trip reefer inspection report showing the unit pulled down to 2°C before loading and provides a lumper receipt from origin showing product was loaded at 3°C. + +The carrier's position: the product was loaded warm or the facility door was open too long during loading, and the reefer couldn't overcome the heat load. The shipper's position: the reefer compressor failed in transit and the carrier is liable. Both sides have documentation supporting their claim. The hospital network needs insulin within 48 hours or faces patient care disruptions. + +**Why It's Tricky:** +Temperature excursion disputes are among the hardest to adjudicate because both the shipper and carrier can be partially right. A reefer unit in continuous mode should maintain setpoint on a properly pre-cooled load, but if the trailer was pre-cooled empty (no thermal mass) and then loaded with product at the upper end of range on a 95°F day in Memphis with the dock door cycling open, the unit may genuinely struggle. The critical question isn't the reefer setpoint — it's the return air temperature trend in the first 90 minutes after door closure. + +Most non-experts focus on the arrival temperature. Experts focus on the rate of temperature change and exactly when the deviation started. If the reefer data shows return air climbing steadily from minute one, the load was likely warm at origin. If return air held for 4+ hours then spiked, the compressor or refrigerant failed in transit. + +**Common Mistake:** +Filing a blanket cargo claim against the carrier for $2.1M without first analyzing the reefer download data in detail. The carrier will deny the claim, point to their pre-trip and loading receipts, and the dispute enters a 6-month arbitration cycle. Meanwhile, the product sits in a quarantine hold and ultimately gets destroyed, the hospital network scrambles for supply, and the shipper-carrier relationship is damaged. + +The second common mistake: assuming the entire shipment is a total loss. Insulin pens that experienced a brief, moderate excursion may still be viable depending on manufacturer stability data and the specific excursion profile. A blanket destruction order without consulting the manufacturer's excursion guidance wastes recoverable product. + +**Expert Approach:** +1. Immediately quarantine the shipment at the receiving facility — do not reject it outright and do not release it to inventory. Rejection creates a disposal liability problem. Quarantine preserves options. +2. Download and preserve three data sets: (a) the TempTale or Ryan data logger from inside the shipment, (b) the reefer unit's microprocessor download (insist on the full download, not the driver's summary printout), and (c) the facility's dock door and ambient temperature logs from loading. +3. Overlay the three data streams on a single timeline. Identify the exact minute the temperature began deviating and calculate the rate of change (°C per hour). +4. If the deviation started within the first 90 minutes and the rate is gradual (0.5–1°C/hour), the load was likely under-cooled at origin or absorbed heat during loading. The shipper bears primary liability. +5. If the deviation started 3+ hours into transit with a sharp rate change (2+°C/hour), the reefer experienced a mechanical failure. The carrier bears primary liability. +6. Contact the insulin manufacturers' medical affairs departments with the exact excursion profile (time above 8°C, peak temperature reached). Request written guidance on product viability. Humalog pens that stayed below 15°C for under 14 days may still be usable per Lilly's excursion data. +7. For product deemed viable, release from quarantine with full documentation. For product deemed non-viable, document the destruction with lot numbers, quantities, and witnessed disposal. +8. File the claim against the liable party with the data overlay as the primary exhibit. If liability is shared, negotiate a split based on the data — typically 60/40 or 70/30. +9. Separately and in parallel: source replacement insulin from the distributor's secondary allocation or from the manufacturer's emergency supply program. The hospital network cannot wait for claim resolution. + +**Key Indicators:** +- Return air vs. supply air divergence in the first 2 hours is the single most diagnostic data point +- A reefer that was pre-cooled empty to 2°C but shows supply air of 4°C within 30 minutes of door closure likely had an undersized unit or a failing compressor +- Look for "defrost cycle" entries in the reefer log — a unit running excessive defrost cycles is masking a frost buildup problem that indicates a refrigerant leak +- Check whether the reefer was in "continuous" or "start-stop" (cycle-spool) mode — pharma loads must be continuous; if it was set to cycle-spool, the carrier is immediately at fault regardless of loading temperature +- A pre-trip that shows 2°C pulldown in under 20 minutes on a 53-foot trailer in summer is suspicious — that's an empty trailer with no thermal mass, meaning the carrier pulled the trailer to the shipper without adequate pre-cool time + +**Documentation Required:** +- TempTale/Ryan recorder raw data file (CSV export, not just the PDF summary) +- Reefer microprocessor full download (not the 3-line driver printout; the full event log with alarm history, defrost cycles, and door open events) +- Origin facility dock door logs and ambient temperature at time of loading +- Bill of lading with temperature requirement notation +- Shipper's loading SOP and any deviation from it +- Photographs of data logger placement within the load +- Manufacturer's written excursion guidance for the specific product lots +- Witnessed product destruction records with lot numbers if applicable + +**Resolution Timeline:** +- Hours 0–4: Quarantine, data preservation, and initial data overlay analysis +- Hours 4–12: Manufacturer consultation on product viability +- Hours 12–48: Replacement sourcing and initial claim filing +- Days 3–14: Detailed claim documentation assembly with data overlay exhibit +- Days 14–45: Carrier/shipper response and negotiation +- Days 45–120: Arbitration if negotiation fails (typical for claims over $500K) + +--- + +### Edge Case 2: Consignee Refuses Delivery Citing Damage, but Damage Occurred at Consignee's Dock + +**Situation:** +A furniture manufacturer ships 8 pallets of assembled high-end office chairs (Herman Miller Aeron, wholesale value ~$38,400) via LTL from their Grand Rapids facility to a commercial interior design firm in Chicago. The shipment arrives at the consignee's urban location — a converted warehouse with a narrow dock, no dock leveler, and a single dock door accessed via an alley. + +The driver backs in and the consignee's receiving crew begins unloading with a stand-up forklift. During unloading, the forklift operator catches a pallet on the trailer's rear door track, tipping it. Three cartons fall, and multiple chairs sustain visible frame damage. The consignee's receiving manager immediately refuses the entire shipment, marks the BOL "DAMAGED — REFUSED," and instructs the driver to take it all back. + +The driver, who was in the cab during unloading, did not witness the incident. He signs the BOL with the consignee's damage notation and departs with the full load. The shipper receives a refused-shipment notification and a damage claim from the consignee for the full $38,400. + +**Why It's Tricky:** +Once "DAMAGED — REFUSED" is on the BOL signed by the driver, the shipper is in a difficult position. The consignee controls the narrative because they were the ones who noted damage. The carrier will deny the claim because the driver will state the freight was intact when he opened the doors. But the driver wasn't watching unloading, so he can't affirmatively say when damage occurred. The consignee has no incentive to admit their forklift operator caused the damage — they want replacement product, and it's easier to blame transit damage. + +The fundamental issue: damage occurring during unloading at the consignee's facility is the consignee's liability, not the carrier's or shipper's. But proving it requires evidence that is very hard to obtain after the fact. + +**Common Mistake:** +Accepting the consignee's damage claim at face value and filing against the carrier. The carrier denies it, the shipper eats the cost, and the consignee gets free replacement product. The second common mistake: refusing to send replacement product while the dispute is investigated, damaging the commercial relationship with the consignee (who is the customer). + +**Expert Approach:** +1. Before anything else, call the driver directly (or through the carrier's dispatch). Ask specifically: "Did you observe unloading? Were you in the cab or on the dock? Did you inspect the freight before signing the damage notation?" Get this statement within 24 hours while memory is fresh. +2. Request the carrier pull any dashcam or rear-facing camera footage from the tractor. Many modern fleets have cameras that capture dock activity. Even if the angle is poor, it establishes the timeline. +3. Ask the consignee for their facility's security camera footage of the dock area. Frame this as "helping us file the claim properly." If they refuse or claim no cameras, that's a data point. +4. Examine the damage type. Chairs that fell off a forklift-tipped pallet will have impact damage on the frame — dents, bends, cracked bases — concentrated on one side and consistent with a fall from 4–5 feet. Transit damage from shifting in a trailer presents differently: scuffing, compression, carton crushing across the top of the pallet from stacking, and damage distributed across multiple faces of the carton. +5. Check the origin loading photos. If the shipper photographs outbound loads (they should), compare the load configuration at origin to the described damage pattern. If the pallets were loaded floor-stacked with no double-stacking, top-of-pallet compression damage is impossible from transit. +6. File a "damage under investigation" notice with the carrier within 9 months (Carmack Amendment window for concealed damage, though this is not concealed). Keep the claim open but do not assert a specific dollar amount yet. +7. Send the consignee replacement product for the damaged units only (not the entire shipment — only the 3 cartons that were damaged, not all 8 pallets). Ship the replacements on the shipper's account, but document that the original undamaged product must be received as-is. +8. If evidence supports consignee-caused damage, present findings to the consignee. The goal is not to litigate — it's to establish the facts and negotiate. Typically the consignee accepts liability for the damaged units, the shipper absorbs the freight cost of the return and reship, and the relationship survives. + +**Key Indicators:** +- Driver was in the cab, not on the dock — critical detail that the carrier will try to gloss over +- Damage concentrated on one pallet or one side of a pallet strongly suggests a handling incident, not transit movement +- Consignee's dock conditions (no leveler, narrow alley, stand-up forklift for palletized furniture) are inherently risky — experienced shippers know these facilities generate more damage claims +- If the consignee refused the entire shipment but only 3 cartons were visibly damaged, the refusal was strategic, not operational. Legitimate damage refusals are partial unless the entire shipment is compromised. +- The driver signing the damage notation without adding "DAMAGE NOT OBSERVED IN TRANSIT" or "DRIVER NOT PRESENT DURING UNLOADING" is a documentation failure, but it is not an admission of carrier liability + +**Documentation Required:** +- Signed BOL with damage notations (photograph both sides) +- Driver's written statement on their location during unloading (within 24 hours) +- Dashcam or rear-camera footage from the tractor if available +- Consignee's dock/security camera footage (request in writing) +- Origin loading photographs showing load configuration and product condition +- Close-up photographs of actual damage on the product, taken at the consignee's facility +- Diagram or description of the consignee's dock layout, including dock type, leveler presence, and equipment used for unloading +- Replacement shipment BOL and delivery confirmation + +**Resolution Timeline:** +- Hours 0–4: Driver statement collection and camera footage requests +- Hours 4–24: Damage pattern analysis and origin photo comparison +- Days 1–3: Replacement product shipped for confirmed damaged units +- Days 3–10: Evidence assembly and liability determination +- Days 10–30: Consignee negotiation on damaged unit liability +- Days 30–60: Carrier claim closure (if carrier is cleared) or continued pursuit + +--- + +### Edge Case 3: High-Value Shipment with No Scan Updates for 72+ Hours — "Lost" vs. "Scan Gap" + +**Situation:** +A medical device manufacturer ships a single pallet of surgical navigation systems (Medtronic StealthStation components, declared value $287,000) from their distribution center in Jacksonville, FL to a hospital in Portland, OR. The shipment moves via a national LTL carrier with guaranteed 5-day service. + +The shipment scans at the origin terminal in Jacksonville on Monday at 14:22. It scans at the carrier's hub in Nashville on Tuesday at 03:17. Then — silence. No scan events for 72 hours. The shipper's logistics coordinator checks the carrier's tracking portal Wednesday, Thursday, and Friday morning. Nothing. The guaranteed delivery date is Friday by 17:00. The hospital has a surgery suite installation scheduled for the following Monday. + +The shipper calls the carrier's customer service line Friday morning. After 40 minutes on hold, the representative says the shipment is "in transit" and to "check back Monday." The shipper's coordinator escalates to their carrier sales rep, who promises to "get eyes on it." By Friday at 15:00, still no update. + +**Why It's Tricky:** +A 72-hour scan gap on a national LTL carrier does not necessarily mean the shipment is lost. LTL carriers have known scan compliance problems at certain terminals, particularly mid-network hubs where freight is cross-docked between linehaul trailers. A pallet can physically move through 2–3 terminals without generating a scan if handheld devices aren't used during cross-dock operations or if the PRO label is damaged or facing inward on the pallet. + +But a 72-hour gap on a $287K shipment could also mean it was misrouted, left behind on a trailer that went to the wrong terminal, shorted to another shipment's delivery, or actually lost or stolen. The challenge is distinguishing between a scan gap (the freight is fine, the technology failed) and a genuine loss — while the clock is ticking on a surgery installation. + +**Common Mistake:** +Waiting until the guaranteed delivery date passes to escalate. By Friday at 17:00, if the shipment is genuinely lost, you've wasted 72 hours of recovery time. The second common mistake: filing a lost shipment claim immediately, which triggers a formal process that takes 30–120 days to resolve. That doesn't help the hospital that needs equipment Monday. The third mistake: assuming the carrier's customer service representative actually has information — front-line CSRs at national LTL carriers typically see the same tracking portal the shipper does. + +**Expert Approach:** +1. At the 48-hour mark (not the 72-hour mark), escalate through two parallel channels: (a) the carrier's sales representative, who has internal access to trailer manifests and terminal operations, and (b) the carrier's claims/OS&D (over, short, and damaged) department at the last known terminal (Nashville). +2. Ask the sales rep for three specific things: (a) the trailer number the shipment was loaded on at Nashville, (b) the manifest for that trailer showing destination terminal, and (c) confirmation that the trailer has arrived at its destination terminal. This is not information CSRs have, but operations and sales teams can access it. +3. If the trailer arrived at the destination terminal but the shipment didn't scan, it's almost certainly a scan gap. Ask the destination terminal to physically locate the freight on the dock or in the outbound staging area. Provide the PRO number, pallet dimensions, and weight — enough for someone to walk the dock. +4. If the trailer hasn't arrived at the destination terminal, ask where the trailer currently is. Trailers are GPS-tracked. If the trailer is sitting at an intermediate terminal for 48+ hours, the freight may have been left on during unloading (a "buried" shipment that didn't get pulled). +5. In parallel, start sourcing a backup unit from the manufacturer. For a $287K medical device, the manufacturer will have a loaner program or emergency stock. Contact Medtronic's field service team directly — they are motivated to keep the surgery installation on schedule because their technician is already booked. +6. If the shipment is confirmed lost (not just scan-gapped) by Friday afternoon, immediately file a preliminary claim with the carrier. Do not wait. Simultaneously arrange emergency air freight for the replacement unit — the cost ($3,000–$8,000 for expedited air from the nearest depot with stock) is recoverable as part of the claim. +7. If the shipment reappears (as scan-gap shipments often do), arrange Saturday or Sunday delivery. Many LTL carriers will do weekend delivery for an additional fee on service-failure shipments — negotiate this fee away since they missed the guarantee. + +**Key Indicators:** +- A scan at an intermediate hub followed by silence usually means the freight is physically at the next terminal but didn't scan during cross-dock. Genuine theft or loss rarely happens mid-network at a carrier's own facility. +- If the carrier's CSR says "in transit" 72 hours after the last scan, they're reading the same portal you are. Escalate immediately. +- Check whether the PRO label was applied to shrink wrap or to the pallet itself. Shrink wrap labels get torn off during handling. This is the single most common cause of scan gaps. +- A single high-value pallet is more vulnerable to being "lost" on a dock than a multi-pallet shipment. It's physically small enough to be blocked behind other freight or pushed into a corner. +- If the carrier's Nashville terminal had a known service disruption (weather, labor action, system outage) in the 72-hour window, a scan gap is almost certain. Check the carrier's service alerts page. + +**Documentation Required:** +- Complete tracking history with all scan events and timestamps +- Original BOL with declared value, PRO number, piece count, weight, and dimensions +- Screenshot of carrier tracking portal showing the gap (timestamped) +- Written correspondence with carrier (sales rep, CSR, OS&D) with dates and names +- Trailer number and manifest from the last known terminal +- Carrier's guaranteed service commitment documentation +- Replacement sourcing records and expedited shipping costs (if applicable) +- Service failure claim documentation per the carrier's tariff (separate from cargo loss claim) + +**Resolution Timeline:** +- Hour 48: Escalation to sales rep and OS&D department +- Hours 48–56: Trailer tracking and physical dock search at destination terminal +- Hours 56–72: Backup unit sourcing initiated +- Hour 72 (if still missing): Preliminary lost cargo claim filed, emergency replacement shipped +- Days 3–7: Carrier completes internal search; most "lost" LTL shipments are found within 5 business days +- Days 7–30: Formal claim resolution if shipment is confirmed lost +- Days 30–120: Full claim payment (national LTL carriers typically settle claims in 60–90 days for shipments with declared value) + +--- + +### Edge Case 4: Cross-Border Shipment Held at Customs — Carrier Documentation Error vs. Shipper Error + +**Situation:** +A Texas-based auto parts manufacturer ships a full truckload of aftermarket catalytic converters (480 units, commercial value $312,000) from their Laredo warehouse to an automotive distributor in Monterrey, Mexico. The shipment moves via a U.S. carrier to the Laredo border crossing, where it is transferred to a Mexican carrier for final delivery under a cross-dock arrangement. + +Mexican customs (Aduana) places a hold on the shipment at the Nuevo Laredo crossing. The customs broker reports two issues: (1) the commercial invoice lists the HS tariff code as 8421.39 (filtering machinery), but catalytic converters should be classified under 8421.39.01.01 (specific Mexican fraction for catalytic converters) or potentially 7115.90 (articles of precious metal, because catalytic converters contain platinum group metals), and (2) the pedimento (Mexican customs entry) lists 480 pieces but the physical count during inspection is 482 — two additional units were loaded that are not on any documentation. + +The carrier blames the shipper for the wrong HS code and the extra pieces. The shipper says the customs broker (hired by the carrier's Mexican partner) selected the HS code, and their pick ticket clearly shows 480 units. The Mexican carrier is charging $850/day in detention. The customs broker is quoting $4,500 for a "rectification" of the pedimento. The consignee needs the parts by Thursday for a production line changeover. + +**Why It's Tricky:** +Cross-border shipments involving tariff classification disputes and quantity discrepancies touch three separate legal jurisdictions (U.S. export, Mexican import, and the bilateral trade agreement). The HS code issue is genuinely ambiguous — catalytic converters are classified differently depending on whether you're classifying the filtration function or the precious metal content, and the correct Mexican fraction depends on end use. The two extra pieces could be a loading error, a picking error, or remnant inventory from a previous load left in the trailer. + +Every day the shipment sits at the border, detention charges accrue, the consignee's production line inches closer to shutdown, and the risk of a formal Mexican customs investigation (which can result in seizure) increases. The parties involved — shipper, U.S. carrier, Mexican carrier, customs broker, consignee — all have conflicting incentives. + +**Common Mistake:** +Letting the customs broker "handle it" without oversight. Border customs brokers facing a hold often choose the fastest resolution, not the cheapest or most legally correct one. They may reclassify under a higher-duty HS code to avoid scrutiny, costing the consignee thousands in excess duties that become very difficult to recover. They may also instruct the shipper to create a supplemental invoice for the 2 extra pieces at an arbitrary value, which creates a paper trail that doesn't match reality and can trigger a post-entry audit. + +The second mistake: panicking about the quantity discrepancy and assuming it's a smuggling allegation. Two extra catalytic converters on a 480-unit load is a 0.4% overage. Mexican customs sees this routinely and it's correctable — but only if handled with the right paperwork and the right broker. + +**Expert Approach:** +1. Separate the two issues immediately. The HS code classification and the quantity discrepancy are different problems with different resolution paths. Do not let the broker bundle them into a single "rectification." +2. For the HS code: engage a licensed Mexican customs classification specialist (not the same broker who filed the original pedimento). Catalytic converters for automotive aftermarket use are correctly classified under the Mexican tariff fraction 8421.39.01.01 with USMCA preferential treatment if the origin qualifies. The precious metals classification (7115.90) applies only to scrap or recovery operations. Get a binding ruling reference from SAT (Mexico's tax authority) if the broker disputes this. +3. For the quantity discrepancy: determine the actual source of the two extra pieces. Pull the shipper's warehouse pick ticket, the loading tally sheet (if one exists), and check the trailer's seal number against the BOL. If the seal was intact at the border, the extra pieces were loaded at origin. Check whether the shipper's inventory system shows a corresponding shortage of 2 units. If it does, it's a simple pick/load error. If it doesn't, the units may have been left in the trailer from a previous load — check the carrier's prior trailer use log. +4. File a "rectificación de pedimento" through the classification specialist for both the HS code correction and the quantity amendment. The amendment for the 2 extra units requires a supplemental commercial invoice from the shipper at the same per-unit price as the original 480. +5. While the rectification is processing (typically 1–3 business days), negotiate the detention charges. The Mexican carrier's $850/day is negotiable because the hold is not their fault or the shipper's alone. The standard resolution is to split detention costs between the shipper (for the quantity error) and the customs broker (for the classification error), with the carrier waiving 1–2 days as a relationship concession. +6. Document the entire incident for USMCA compliance records. An HS code correction on a $312K shipment of controlled automotive parts will flag in SAT's risk system, and the next shipment through Nuevo Laredo will get a more thorough inspection. Prepare for that. + +**Key Indicators:** +- A customs hold that cites both classification and quantity issues is more serious than either alone — it suggests the shipment was flagged for manual inspection, not a random document review +- Catalytic converter shipments to Mexico receive extra scrutiny because of environmental regulations (NOM standards) and precious metal content reporting requirements +- If the customs broker immediately quotes a fee for "rectification" without explaining the legal basis, they're charging a facilitation fee, not a legitimate service cost. Get a second quote. +- An intact seal with a quantity overage points to origin loading error. A broken or missing seal with a quantity overage is a much more serious situation suggesting possible tampering. +- Check whether the shipper holds a C-TPAT certification — if so, the quantity error could jeopardize their trusted trader status, and the resolution needs to include a corrective action report + +**Documentation Required:** +- Original commercial invoice, packing list, and BOL (all three must be reconciled) +- Mexican pedimento (customs entry) showing the hold reason and original classification +- Shipper's warehouse pick ticket and loading tally for the exact shipment +- Trailer seal number verification (BOL seal number vs. seal number at inspection) +- Carrier's prior trailer use log (to rule out remnant freight) +- Classification specialist's written opinion on correct HS code with legal citations +- Supplemental commercial invoice for the 2 additional units +- Rectified pedimento with Aduana stamp +- Detention invoices from the Mexican carrier with negotiated amounts +- USMCA certificate of origin (if claiming preferential treatment) +- Corrective action report if shipper is C-TPAT certified + +**Resolution Timeline:** +- Hours 0–4: Issue separation, classification specialist engaged, quantity investigation started +- Hours 4–24: Source of quantity discrepancy determined, supplemental invoice prepared +- Days 1–3: Rectificación de pedimento filed and processed +- Days 3–5: Shipment released from customs, delivered to consignee +- Days 5–15: Detention charge negotiation and settlement +- Days 15–45: Post-entry compliance documentation filed, C-TPAT corrective action if applicable + +--- + +### Edge Case 5: Multiple Partial Deliveries Against Same BOL — Tracking Shortage vs. Overage + +**Situation:** +A building materials distributor ships a full truckload of mixed SKUs — 12 pallets of ceramic floor tile (7,200 sq ft), 6 pallets of grout (180 bags), and 4 pallets of backer board (240 sheets) — from their Dallas distribution center to a commercial construction site in Houston. The BOL lists 22 pallets, 38,400 lbs, as a single shipment under one PRO number. + +The Houston job site cannot receive a full truckload at once — the staging area is too small and the GC (general contractor) will only accept what the tile crew can install that week. The shipper and consignee agreed to split delivery across three drops: 8 pallets Monday, 8 pallets Wednesday, 4 pallets Friday. The carrier is making partial deliveries from their Houston terminal, breaking the load and redelivering across the week. + +After the third delivery Friday, the GC's site superintendent counts what was received across all three deliveries and reports: 11 pallets of tile (short 1), 7 pallets of grout (over 1), and 4 pallets of backer board (correct). The consignee files a shortage claim for 1 pallet of tile (~$3,600) and an overage notification for 1 pallet of grout (~$420). + +The carrier says all 22 pallets were delivered across the three drops. The delivery receipts from Monday and Wednesday were signed by the site's day laborer (not the superintendent), and the Friday receipt was signed by the superintendent. None of the three delivery receipts detail pallet counts by SKU — they just say "8 pallets," "8 pallets," and "4 pallets" respectively. + +**Why It's Tricky:** +Partial deliveries against a single BOL create a reconciliation nightmare. The original BOL describes the total load. Each partial delivery should have a delivery receipt referencing the original BOL with a detailed pallet-by-SKU breakdown, but in practice, drivers hand over whatever is on the truck and the receiver signs for a pallet count without verifying SKU-level detail. + +The likely scenario: during the break-bulk at the carrier's Houston terminal, a tile pallet was mixed up with a grout pallet. The carrier delivered 22 pallets total (correct), but the SKU mix within those 22 was wrong. This is not a shortage or an overage — it's a mis-delivery. But because the delivery receipts don't have SKU-level detail, no one can prove which delivery had the wrong mix. + +The job site may also be contributing to the confusion. Construction sites are chaotic. Product gets moved, other subcontractors' materials get mixed in, and the laborer who signed Monday's receipt may not have segregated the delivery from other tile already on site. + +**Common Mistake:** +Filing a standard shortage claim for the missing tile pallet. The carrier will point to the signed delivery receipts showing 22 pallets delivered and deny the claim. The consignee ends up short tile for the install, orders a rush replacement, and eats the cost. Meanwhile, the extra grout pallet either gets absorbed into site inventory (costing the distributor) or sits unclaimed. + +The deeper mistake: not recognizing that this is a SKU-level accuracy problem, not a piece-count problem. Standard shortage claim procedures don't address mis-delivery within a correct total count. + +**Expert Approach:** +1. Reconstruct the three deliveries at the SKU level. Start with what's verifiable: the Friday delivery was received by the superintendent. Ask them to confirm exactly what was on those 4 pallets by SKU. If they can confirm 4 pallets of backer board, that's clean. +2. Work backward from Friday. If all backer board was on the Friday delivery, then Monday and Wednesday delivered a combined 12 pallets of tile and 6 pallets of grout — but we know the consignee received 11 tile and 7 grout. One tile pallet was swapped for a grout pallet. +3. Check the carrier's Houston terminal break-bulk records. When the carrier broke the full truckload into three partial deliveries, they should have a terminal work order or fork driver's load sheet showing which pallets went on which delivery truck. If these records exist (and at major LTL/TL carriers, they often do), they'll show the misload. +4. The resolution is a swap, not a claim. The consignee has 1 extra grout pallet that belongs to the distributor. The distributor owes 1 tile pallet to the consignee. Arrange a single delivery: bring 1 tile pallet, pick up 1 grout pallet. The carrier should absorb this cost as a service failure if the terminal's break-bulk records show the misload. +5. For future partial-delivery shipments to this consignee (and any similar job site), require SKU-level detail on each delivery receipt. Create a standardized partial delivery form that references the master BOL and lists, per delivery: pallet count by SKU, total pieces by SKU, and a running total against the master BOL. Have the receiver verify and sign at the SKU level. +6. If the carrier denies the misload and the consignee cannot wait for resolution, ship the replacement tile pallet immediately and pursue the carrier for the freight cost and the unrecovered grout pallet value. + +**Key Indicators:** +- Delivery receipts signed by day laborers without SKU verification are essentially worthless for claims purposes — they prove delivery happened but not what was delivered +- A 1-for-1 swap (1 pallet short on SKU A, 1 pallet over on SKU B, total count correct) is almost always a terminal misload, not a transit loss +- Construction sites with multiple subcontractors and multiple material suppliers are high-risk for inventory confusion — materials from different vendors get commingled +- If the grout and tile pallets are similar in size and wrapped in similar shrink wrap, the terminal dock worker likely couldn't distinguish them without checking labels +- Check whether the pallets had color-coded labels or SKU stickers visible through the shrink wrap — if not, this is partly a packaging/labeling failure at origin + +**Documentation Required:** +- Original BOL with complete SKU-level pallet breakdown (22 pallets by type) +- All three delivery receipts with signatures and dates +- Site superintendent's SKU-level inventory reconciliation after final delivery +- Carrier's terminal break-bulk work order or fork driver load sheet (request in writing) +- Photographs of the extra grout pallet (label, lot number, condition) +- Replacement tile pallet shipment documentation +- Return/swap documentation for the extra grout pallet + +**Resolution Timeline:** +- Hours 0–8: SKU-level reconciliation at the job site +- Hours 8–24: Carrier terminal records requested and reviewed +- Days 1–3: Swap arranged — tile pallet delivered, grout pallet recovered +- Days 3–7: Carrier cost allocation determined (service failure or shared) +- Days 7–14: Partial delivery SOP updated for future shipments to this consignee + +--- + +### Edge Case 6: Dual-Driver Team Swap with Missing Driver Signature on POD + +**Situation:** +A contract carrier runs a team-driver operation to meet a time-critical delivery for an electronics retailer. The shipment is 18 pallets of consumer electronics (gaming consoles, wholesale ~$194,000) moving from a distribution center in Ontario, CA to a regional fulfillment center in Edison, NJ — approximately 2,700 miles with a 48-hour delivery commitment. + +Driver A departs Ontario and drives the first 11-hour shift. At the team swap point in Amarillo, TX (approximately mile 1,200), Driver B takes the wheel. Driver A had the original BOL packet with the paper POD (proof of delivery) form. During the swap, the BOL packet was left in the sleeper berth rather than passed to Driver B's clipboard. + +Driver B completes the haul to Edison and delivers the shipment. The receiving clerk at the fulfillment center signs the delivery receipt, but the Driver B signature line on the carrier's POD copy is blank — Driver B didn't have the BOL packet and instead used a generic delivery receipt from the cab's supply. The consignee's copy of the POD has the receiver's signature but no driver signature. The carrier's copy has Driver A's signature at origin and a blank at destination. + +Three weeks later, the retailer files a shortage claim for 2 pallets ($21,600) stating the delivery was short. The carrier has no signed POD from their driver at delivery confirming piece count. + +**Why It's Tricky:** +A POD without the driver's signature at delivery is a significant evidentiary gap. The carrier cannot prove their driver confirmed the delivery was complete. The consignee's receiving clerk signed for "18 pallets" on their internal receipt, but the carrier doesn't have a copy of that document. The carrier's own POD shows 18 pallets loaded at origin (Driver A's signature) but has no delivery confirmation. + +Team-driver operations are notorious for documentation handoff failures. The swap happens at a truck stop at 2 AM, both drivers are focused on the HOS (hours of service) clock, and paperwork transfer is an afterthought. Carriers know this is a vulnerability but struggle to enforce procedures across hundreds of team operations. + +The 3-week gap between delivery and claim filing adds suspicion. If 2 pallets of gaming consoles were missing at delivery, the fulfillment center's receiving process should have caught it immediately — not three weeks later during an inventory cycle count. + +**Common Mistake:** +The carrier, lacking a signed POD, immediately concedes the claim to avoid litigation. This sets a precedent that any shortage claim against a team-driver shipment without a perfect POD is automatically paid. The actual cost isn't just $21,600 — it's the signal to this retailer (and their claims department) that POD gaps equal easy money. + +Alternatively, the carrier denies the claim outright, the retailer escalates, and the carrier loses the account. + +**Expert Approach:** +1. Obtain the consignee's internal receiving documentation. The fulfillment center will have their own receiving log, WMS (warehouse management system) receipt record, and the delivery receipt their clerk signed. Formally request these through the retailer's freight claims department. The consignee's WMS receipt record will show exactly how many pallets were scanned into inventory at the time of delivery. +2. Check whether the consignee's facility has dock cameras. Most fulfillment centers of this size do. Request footage from the delivery date showing the unloading process. Counting pallets on a camera is straightforward. +3. Pull Driver B's ELD (electronic logging device) data for the delivery stop. The ELD will show arrival time, departure time, and duration at the delivery location. A full 18-pallet unload takes 25–40 minutes. If the ELD shows a 15-minute stop, the delivery may indeed have been short (or the driver dropped the trailer, but that changes the scenario). +4. Check the generic delivery receipt Driver B used. Even without the formal POD, if Driver B got any signature on any piece of paper, it has evidentiary value. Contact Driver B directly. +5. Investigate the 3-week claim gap. Ask the retailer when exactly the shortage was discovered. If it was during an inventory cycle count, the shortage could have occurred anywhere in the fulfillment center's operations — theft, mis-pick, damage disposal without record — and not during delivery. A 3-week-old shortage claim without a same-day exception report at receiving is weak on its face. +6. If the evidence shows full delivery (WMS receipt of 18, camera footage of 18 pallets, ELD showing full unload duration), deny the claim with documentation. If the evidence is inconclusive, negotiate a partial settlement — typically 50% of the claimed amount — with a corrective action plan for the team-driver POD process. + +**Key Indicators:** +- A shortage claim filed weeks after delivery, absent a same-day exception notation on the delivery receipt, suggests the shortage occurred in the consignee's facility, not at delivery +- Generic delivery receipts from the cab are still legally valid documents if signed by the receiver — they're just harder to track and retain +- ELD stop duration is an underused tool for verifying delivery completeness. Full unloads take measurable time. +- If the consignee's WMS shows 18 pallets received into inventory, the shortage claim is baseless regardless of the POD issue +- Team swaps at truck stops between midnight and 5 AM have the highest documentation failure rate + +**Documentation Required:** +- Carrier's POD (showing Driver A signature at origin, blank at destination) +- Generic delivery receipt from Driver B (if recoverable) +- Consignee's internal receiving log and WMS receipt record +- Consignee's dock camera footage from the delivery date +- Driver B's ELD data showing arrival, departure, and stop duration at delivery +- Retailer's shortage claim filing with discovery date and method +- Driver B's written statement regarding the delivery (pallet count, who received, any anomalies) + +**Resolution Timeline:** +- Days 0–3: Consignee documentation request and Driver B statement +- Days 3–7: ELD data pull and camera footage review +- Days 7–14: Evidence analysis and liability determination +- Days 14–30: Claim response to the retailer with supporting documentation +- Days 30–60: Settlement negotiation if evidence is inconclusive + +--- + +### Edge Case 7: Intermodal Container with Concealed Damage Discovered Days After Delivery + +**Situation:** +A consumer goods importer receives a 40-foot intermodal container of packaged household cleaning products (cases of liquid detergent, surface cleaners, and aerosol sprays — approximately 1,800 cases, landed cost ~$67,000) at their warehouse in Memphis. The container moved ocean from Shenzhen to the Port of Long Beach, then intermodal rail from Long Beach to Memphis, then drayage from the Memphis rail ramp to the importer's warehouse. + +The container is grounded at the warehouse on Tuesday. The warehouse crew unloads it on Wednesday. Everything looks normal — the container seal was intact, no obvious external damage to the container, and the first 600 cases pulled from the doors look fine. But as the crew works deeper into the container (beyond the halfway point), they find approximately 200 cases of aerosol cans that are crushed and leaking. The cases were stacked in the rear of the container (loaded first in Shenzhen), and the damage pattern suggests the load shifted during transit, causing the top-stacked cases to collapse onto the aerosol pallets. + +The importer files a concealed damage claim. The problem: the container moved through four custody handoffs — the Chinese shipper's loading crew, the ocean carrier, the intermodal rail carrier, and the dray carrier. Each one had custody and each one will deny responsibility. The ocean carrier says the container was SOLAS-verified and properly loaded. The rail carrier says the container was accepted in good condition at Long Beach. The dray carrier says they only moved it 12 miles from the ramp and there was no incident. + +**Why It's Tricky:** +Concealed damage in intermodal containers is the hardest claim in freight. The damage is hidden inside a sealed box that passes through multiple carriers across international boundaries. Each carrier has a plausible defense. The ocean carrier invokes COGSA (Carriage of Goods by Sea Act) limitations. The rail carrier invokes the Carmack Amendment domestically but argues the damage pre-dates their custody. The dray carrier points to the intact seal. + +The damage pattern — crushed cases deep in the container — is consistent with load shift, but load shift can occur during ocean transit (rolling seas), rail transit (humping and coupling at railyards), or even the final dray if the driver hit a severe pothole or made a hard stop. Without accelerometer data inside the container, pinpointing the moment of shift is nearly impossible. + +Aerosol cans add a complication: leaking aerosols are a hazmat concern (compressed gas, flammable propellant). The importer now has a cleanup cost on top of the product loss. + +**Common Mistake:** +Filing a single claim against the ocean carrier for the full amount because they had the longest custody. COGSA limits the ocean carrier's liability to $500 per package (or per customary freight unit) unless a higher value was declared on the ocean bill of lading. If each pallet is a "package," the importer recovers $500 per pallet — far less than the actual loss. If no excess value was declared, the ocean carrier's exposure is capped regardless of actual damage. + +The second mistake: not inspecting the container immediately upon arrival. The importer grounded the container Tuesday and didn't unload until Wednesday. That 24-hour gap weakens the claim because any carrier can argue the damage occurred during the grounded period (temperature expansion, forklift impact to the grounded container, etc.). + +**Expert Approach:** +1. Document everything before moving anything. Once the concealed damage is discovered mid-unload, stop unloading. Photograph the damage in situ — the crushed cases, the load configuration, the position of damage relative to the container doors and walls. Photograph the container interior from the door end showing the overall load state. Note the container number, seal number, and condition of the seal (intact, cut, or replaced). +2. File concealed damage notices simultaneously with all three domestic parties: the dray carrier, the intermodal rail carrier, and the ocean carrier (or their agent). The notice must go out within the applicable time limits: 3 days for concealed damage under the Carmack Amendment (rail and dray), and per the ocean bill of lading terms for the ocean carrier (varies, but typically "within reasonable time of delivery"). +3. Inspect the container itself for evidence of the damaging event. Check for: (a) scuff marks on the container floor indicating load shift direction, (b) dents or impacts on the container walls that could have caused the shift, (c) condition of load securing (dunnage, airbags, strapping) and whether it was adequate per the shipper's load plan, and (d) moisture or condensation damage that suggests container rain, which is an ocean transit issue. +4. Request the container's GPS and event data from the intermodal rail carrier. Modern chassis-mounted containers on rail generate movement and impact event data. If there was a significant impact event at a rail yard (coupling, humping, derailment), it will show in the data. +5. Review the ocean carrier's vessel tracking for the voyage. If the vessel encountered severe weather (check NOAA marine weather data for the Pacific crossing dates), heavy roll could have initiated the load shift. +6. Assess the load plan from Shenzhen. Were the aerosol cases (lightest, most fragile) stacked on the bottom at the rear of the container? If so, the Chinese shipper's loading crew made a fundamental error — heavy items go on the bottom, fragile items go on top and toward the door end. This is a shipper loading liability issue that no carrier is responsible for. +7. For the hazmat cleanup: engage a licensed hazmat cleanup contractor for the leaking aerosols. Document the cleanup scope and cost. This cost is recoverable as consequential damages in the claim, but only against the party found liable for the load shift — not as a blanket charge to all carriers. +8. File claims against the appropriate parties based on the evidence. In practice, most intermodal concealed damage claims with ambiguous causation settle through negotiation between the ocean carrier's P&I club and the cargo insurer. If the importer has marine cargo insurance (which they should, on a $67K shipment from China), file the insurance claim and let the insurer subrogate against the carriers. + +**Key Indicators:** +- Damage only to cases deep in the container (rear, loaded first) strongly suggests load shift that occurred early in transit, not at the end — the cases at the door end (loaded last) served as a buffer +- An intact container seal eliminates pilferage or unauthorized opening — the damage happened inside a sealed box during transit +- Aerosol cases loaded at the bottom of a stack are a shipper loading error unless the load plan specifically accounted for their fragility and the damage was caused by an extraordinary event +- Scuff marks on the container floor running longitudinally (front-to-back) suggest a braking or acceleration event; lateral scuff marks suggest roll (ocean) or curve forces (rail) +- If the container was loaded with inflatable dunnage bags and the bags are deflated or burst, the bags were either undersized for the load or punctured by the aerosol cans during the shift — inspect the bags + +**Documentation Required:** +- Photographs of damage in situ (before any cleanup or further unloading) +- Container number, seal number, and seal condition photographs +- Container inspection report (floor scuffs, wall impacts, dunnage condition) +- Concealed damage notices to all carriers (with date/time stamps) +- Ocean bill of lading with package and value declarations +- Shipper's load plan from Shenzhen (container stuffing report) +- Intermodal rail carrier's GPS and event data for the container +- Vessel voyage data and NOAA weather records for the Pacific crossing +- Hazmat cleanup contractor's scope and cost documentation +- Marine cargo insurance claim filing (if applicable) +- Packing list with case-level detail showing damaged vs. undamaged product + +**Resolution Timeline:** +- Hour 0: Discovery — stop unloading, photograph, document +- Hours 0–24: Concealed damage notices filed with all carriers +- Days 1–3: Container inspection, carrier data requests, cleanup initiated +- Days 3–14: Evidence assembly, load plan review, voyage/rail data analysis +- Days 14–30: Marine cargo insurance claim filed (if applicable) +- Days 30–90: Carrier responses and negotiation +- Days 90–180: Settlement or arbitration (intermodal claims average 120 days to resolve) + +--- + +### Edge Case 8: Broker Insolvency Mid-Shipment with Carrier Demanding Payment for Release + +**Situation:** +A mid-size food manufacturer uses a freight broker to arrange a truckload of frozen prepared meals (retail value ~$128,000, freight charges ~$4,800) from their production facility in Omaha to a grocery distribution center in Minneapolis. The broker quoted the shipper $4,800 all-in and contracted the actual carrier at $3,900. + +The carrier picks up the load in Omaha on Monday. Tuesday morning, the shipper receives a call from the carrier's dispatcher: the broker has not paid their last three invoices totaling $14,200 across multiple loads, and the broker is not answering phones or emails. The carrier's dispatcher says they will not deliver the Minneapolis load until someone guarantees payment of $3,900 for this load plus the $14,200 in outstanding invoices from previous loads. The carrier currently has the loaded trailer at their Des Moines yard. The frozen meals have a 72-hour window before the cold chain becomes a concern, and the grocery DC has a receiving appointment Wednesday at 06:00 for a promotional launch. + +The shipper calls the broker. The number is disconnected. The broker's website is down. A quick search reveals the broker filed Chapter 7 bankruptcy two days ago. + +**Why It's Tricky:** +Under federal law (49 USC §14103), a carrier can assert a lien on freight for unpaid charges. However, the carrier's lien is for charges on *this* shipment, not for the broker's unpaid invoices on previous shipments. The carrier is conflating two separate obligations: (a) the $3,900 owed for the current load, and (b) the $14,200 the insolvent broker owes from prior loads. The shipper owes the broker $4,800, not the carrier — the shipper has no contractual relationship with the carrier. + +But the carrier has physical possession of $128,000 in perishable freight. Practically, they have leverage regardless of the legal merits. The frozen meals don't care about legal arguments — they're thawing. And the grocery DC will cancel the receiving appointment and the promotional launch if the product doesn't arrive Wednesday. + +The shipper is also exposed to double-payment risk: they may have already paid the broker the $4,800 (or it's in their payment queue), and now the carrier wants $3,900 directly. If the shipper pays the carrier, they've paid $8,700 in freight charges for a $4,800 lane. + +**Common Mistake:** +Paying the carrier's full demand ($3,900 + $14,200 = $18,100) to release the freight. This is extortion dressed as a lien claim, and it rewards bad behavior. The shipper has no obligation for the broker's prior debts, and paying them creates a precedent. + +The second mistake: refusing to pay anything and calling a lawyer. By the time the lawyer sends a demand letter, the frozen meals are compromised and the promotional launch is blown. Legal purity is cold comfort when you're explaining to the grocery chain why the endcap is empty. + +**Expert Approach:** +1. Confirm the broker's insolvency. Check the FMCSA's broker licensing database for the broker's MC number — if their bond has been revoked or their authority is "inactive," insolvency is confirmed. Search federal bankruptcy court records (PACER) for the Chapter 7 filing. +2. Contact the carrier's dispatcher or owner directly. Be professional, not adversarial. Acknowledge that the carrier is in a difficult position. State clearly: "We will guarantee payment of $3,900 for this load directly to you, but we are not responsible for the broker's prior debts. Those are claims against the broker's surety bond and bankruptcy estate." +3. If the carrier accepts $3,900 for release, get it in writing before wiring the funds. Prepare a simple release letter: "Carrier agrees to deliver shipment [PRO/BOL number] to [consignee] in exchange for direct payment of $3,900 from [shipper]. This payment satisfies all carrier charges for this shipment. Carrier acknowledges that shipper is not liable for any amounts owed by [broker name/MC number] for other shipments." +4. Wire the $3,900 or provide a company check at delivery. Do not use a credit card (the carrier will add a surcharge). Do not agree to pay within 30 days (the carrier wants certainty now, and delay risks them re-impounding the freight). +5. If the carrier refuses to release for $3,900 and insists on the full $18,100, escalate to the FMCSA. Carriers who refuse to deliver freight to extract payment for unrelated loads are violating 49 USC §14103. File a complaint with FMCSA and inform the carrier you've done so. Most carriers will release at this point. +6. As a last resort, if the freight is perishable and the carrier won't budge, consider paying the $3,900 plus a negotiated portion of the old debt (e.g., $3,000 of the $14,200) as a commercial compromise, with a written statement that the additional payment is "disputed and paid under protest to prevent spoilage of perishable goods." This preserves the shipper's right to recover the extra payment later. +7. After the immediate crisis, file a claim against the broker's surety bond. Freight brokers are required to carry a $75,000 surety bond. The bond is specifically intended to cover situations like this. File the claim with the surety company listed on the broker's FMCSA registration. Note: if the broker has multiple unpaid carriers, the $75,000 bond will be split pro-rata among all claimants, so the recovery may be partial. +8. Also file a claim in the broker's Chapter 7 bankruptcy proceeding as an unsecured creditor for any amounts paid above the original $4,800 contract rate. Recovery in Chapter 7 is typically pennies on the dollar, but it preserves the legal right. + +**Key Indicators:** +- A broker whose phone is disconnected and website is down is either insolvent or has absconded — either way, they are no longer a viable intermediary +- Carriers who demand payment for unrelated loads as a condition of delivery are overreaching, but they know that perishable freight gives them leverage +- Check if the shipper's broker contract has a "double-brokering" prohibition — some insolvent brokers were actually re-brokering loads to other brokers, adding a layer of complexity to the payment chain +- The broker's surety bond amount ($75,000) is almost never enough to cover all claims when a broker fails — prioritize getting your claim filed early +- If the carrier is a small fleet (5 or fewer trucks), they may be genuinely unable to absorb the loss from the broker and may be more willing to negotiate if they receive some payment quickly + +**Documentation Required:** +- Original broker-shipper contract with rate confirmation +- Carrier's rate confirmation with the broker (if obtainable) +- FMCSA broker registration showing authority status and surety bond information +- Bankruptcy filing documentation (PACER search results) +- Written release agreement between shipper and carrier +- Wire transfer or payment confirmation for the $3,900 direct payment +- "Paid under protest" letter if any amount above $3,900 is paid +- Surety bond claim filing with the broker's surety company +- Bankruptcy court claim filing as unsecured creditor +- Temperature monitoring data from the shipment (to document cold chain integrity during the delay) +- Consignee delivery confirmation and any penalty or chargeback documentation from the grocery chain + +**Resolution Timeline:** +- Hours 0–4: Broker insolvency confirmed, carrier negotiation initiated +- Hours 4–12: Payment agreement reached, funds wired, freight released +- Hours 12–24: Delivery completed to grocery DC +- Days 1–7: Surety bond claim filed +- Days 7–30: Bankruptcy court claim filed +- Days 30–180: Surety bond claim adjudication (typical timeline is 90–120 days) +- Days 180+: Bankruptcy distribution (can take 1–2 years) + +--- + +### Edge Case 9: Seasonal Peak Surcharge Dispute During Declared Weather Emergency + +**Situation:** +A home improvement retailer has a contract with a national LTL carrier that includes a published fuel surcharge table and a "peak season surcharge" clause. The contract states that peak surcharges of up to 18% may be applied during "periods of extraordinary demand as determined by the carrier," with 14 days' written notice. + +In mid-January, a severe ice storm hits the central U.S. — Kansas City, St. Louis, Memphis, and Nashville are all affected. The carrier declares a "weather emergency" on January 15 and simultaneously activates a 22% "emergency surcharge" on all shipments moving through or originating from the affected regions. The carrier's notice, sent via email blast on January 15, states the surcharge is effective January 16. + +The retailer has 340 LTL shipments in transit and another 280 scheduled to ship in the next 7 days through those regions. At an average of $1,200 per shipment, the 22% surcharge adds approximately $163,000 in unbudgeted freight cost across those 620 shipments. The retailer's logistics director objects on three grounds: (1) the contract caps peak surcharges at 18%, (2) the 14-day notice requirement was not met, and (3) this is a weather event, not "extraordinary demand," and should be covered by the existing fuel surcharge mechanism. + +The carrier's position: the weather emergency surcharge is separate from the peak season surcharge and is authorized under the carrier's rules tariff, which the contract incorporates by reference. The carrier cites item 560 in their tariff, which states "emergency surcharges may be applied without prior notice during force majeure events." + +**Why It's Tricky:** +The dispute turns on contract interpretation, specifically whether the weather emergency surcharge is a type of peak surcharge (capped at 18% with 14-day notice) or a separate tariff item (uncapped, no notice required). Both readings are defensible. The contract's peak surcharge clause doesn't specifically exclude weather events. But the tariff's force majeure provision is broadly written and has been part of the carrier's published tariff for years. + +Practically, the carrier has leverage because the freight is either in transit (already moving at the carrier's mercy) or needs to ship to meet store replenishment schedules. The retailer can't reroute 620 shipments to another carrier overnight. And the ice storm is real — the carrier is genuinely incurring higher costs (driver detention, re-routing, de-icing, reduced productivity at affected terminals). + +**Common Mistake:** +Paying the 22% surcharge under protest and then filing a batch claim after the fact. Carriers rarely refund surcharges retroactively, and the retailer's purchasing department will have already booked the expense. The dispute becomes an accounting exercise that drags on for months with no resolution. + +The opposite mistake: refusing to ship until the surcharge is resolved. The stores need product, especially during an ice storm when consumers are buying emergency supplies. A shipping freeze costs more in lost sales than the surcharge. + +**Expert Approach:** +1. Separate the in-transit shipments from the pending shipments. The 340 shipments already moving are subject to the carrier's tariff as of the ship date — if they shipped before January 16, the surcharge should not apply to them. Challenge any surcharge applied to shipments that were tendered before the effective date. +2. For the 280 pending shipments, negotiate immediately. Contact the carrier's pricing or contract manager (not customer service). Propose a compromise: the retailer will accept an 18% surcharge (the contract cap) for the weather period, applied to shipments originating from or delivering to the affected zip codes only, not all shipments "moving through" the region. A shipment from Dallas to Atlanta that transits Memphis should not bear a surcharge meant to cover Memphis-area operational costs. +3. Challenge the tariff incorporation. Most shipper-carrier contracts include a clause like "the carrier's tariff is incorporated by reference except where this contract specifically provides otherwise." The contract specifically provides a peak surcharge cap of 18% with 14-day notice. Argue that this specific provision overrides the general tariff force majeure clause. Have the retailer's transportation attorney send a letter to this effect within 48 hours. +4. Request documentation of the carrier's actual incremental costs during the weather event. Carriers often apply surcharges that far exceed their actual cost increase. A 22% surcharge on $744,000 in freight ($163,680) should correlate to demonstrable cost increases — driver bonuses, equipment repositioning, de-icing, etc. Ask for the cost justification. Carriers rarely provide it, which weakens their position. +5. If the carrier refuses to negotiate, identify which of the 280 pending shipments can move via alternate carriers. Even shifting 30–40% of the volume signals to the contract carrier that the surcharge has competitive consequences. A national retailer with 280 shipments can find partial capacity even during a weather event. +6. Document the surcharge dispute in writing for the annual contract renewal. A carrier that imposed a 22% surcharge with one day's notice during a weather event has demonstrated that their tariff's force majeure clause is a material contract risk. In the next RFP, either negotiate a hard cap on emergency surcharges or require the carrier to remove the force majeure provision from the incorporated tariff. + +**Key Indicators:** +- A surcharge that exceeds the contract's peak season cap is a contract violation unless the carrier can clearly show it's authorized under a separate tariff provision — and even then, the contract's specific terms should override the general tariff +- One day's notice for a 22% surcharge is commercially unreasonable regardless of the contractual language. No shipper can adjust their logistics budget overnight. +- Carriers that apply regional surcharges to all traffic "passing through" a region (rather than originating or terminating there) are overreaching. A shipment that transits Memphis on a linehaul trailer incurs no additional cost unless it's being cross-docked at the Memphis terminal. +- Check whether the carrier applied the same surcharge to all customers or only to contracted customers. If spot-market shipments during the same period were priced at normal + 10%, the contracted customers are being overcharged. +- Weather events that last 3–5 days should not generate surcharges that persist for 14–21 days. Challenge the surcharge end date, not just the rate. + +**Documentation Required:** +- Shipper-carrier contract with peak surcharge clause and tariff incorporation language +- Carrier's published tariff, specifically the force majeure and emergency surcharge provisions +- Carrier's email notification of the weather emergency surcharge (with date, time, and effective date) +- List of all shipments affected (in-transit and pending) with ship dates and origin/destination +- Carrier's actual surcharge amounts applied to each shipment +- Retailer's written objection letter from transportation attorney +- Documentation of the actual weather event (NWS advisories, road closure reports) +- Alternate carrier quotes for diverted shipments +- Carrier's cost justification documentation (if provided) +- Settlement agreement (if reached) + +**Resolution Timeline:** +- Hours 0–24: Separate in-transit from pending shipments, initial negotiation contact +- Days 1–3: Attorney's letter sent, alternate carrier quotes obtained, compromise proposed +- Days 3–7: Negotiation period (carrier will typically respond within a week under pressure) +- Days 7–14: Resolution of the surcharge rate (typically settles at 15–18% for the affected period) +- Days 14–30: Credit memo processing for overcharged in-transit shipments +- Months 3–6: Incorporate lessons into annual contract renewal + +--- + +### Edge Case 10: Systematic Pilferage Pattern Across Multiple LTL Terminal Shipments + +**Situation:** +A consumer electronics brand ships approximately 120 LTL shipments per month through a regional carrier's network to independent retailers across the Southeast. Over a 90-day period, the brand's claims department notices a pattern: 14 shortage claims totaling $47,200, all involving small, high-value items (wireless earbuds, smartwatches, Bluetooth speakers) in the $150–$800 retail range. The shortages range from 2–8 units per shipment. + +The pattern: all 14 claims involve shipments that passed through the carrier's Atlanta terminal. The shipments originate from various locations (the brand's warehouses in Charlotte, Dallas, and Memphis) and deliver to various retailers. The only common element is the Atlanta cross-dock. The shortages are discovered at delivery — the retailer opens the carton and finds units missing inside otherwise intact-looking cases. The case count on the BOL matches the case count at delivery, but the unit count inside specific cases is short. + +The carrier has denied 9 of the 14 claims, citing "no visible damage at delivery" and "correct case count per BOL." The brand suspects organized pilferage at the Atlanta terminal — someone is opening cases, removing small high-value items, and resealing or re-taping the cases. + +**Why It's Tricky:** +Proving systematic pilferage at a carrier's terminal is extremely difficult. The standard claim process evaluates each shipment independently. Each individual claim looks like a minor packaging or picking error — "maybe the warehouse packed 22 earbuds instead of 24 in that case." But 14 claims in 90 days with the same profile (same terminal, same product category, same method) is not coincidence. It's organized theft. + +The carrier's claims department isn't equipped to recognize patterns. They adjudicate each claim against the documentation: case count matched at delivery, no visible damage, claim denied. They don't aggregate claims across shipments to look for terminal-specific patterns. And the carrier's terminal management in Atlanta has no incentive to investigate — acknowledging a pilferage problem at their terminal implicates their own employees. + +The brand's individual claim amounts ($1,500–$5,500 each) are below the threshold that typically triggers a serious investigation. No single claim justifies hiring an investigator or involving law enforcement. + +**Common Mistake:** +Continuing to file individual claims and accepting the denials, or switching carriers entirely without pursuing the pattern. Switching carriers doesn't recover the $47,200 already lost and doesn't address the root cause — the pilfered goods are still flowing into a gray market somewhere. + +The other mistake: confronting the carrier's sales representative with the pilferage accusation without data. "We think your people are stealing" destroys the commercial relationship. "We've identified a statistically significant claim pattern that we need to investigate jointly" gets attention. + +**Expert Approach:** +1. Build the pattern analysis first. Create a spreadsheet mapping all 14 claims by: origin, destination, Atlanta terminal arrival/departure dates, case count, shortage amount, shortage product type, and claim outcome. Add the 106 shipments that passed through Atlanta without a shortage claim. Calculate the shortage rate for Atlanta-routed shipments (14/120 = 11.7%) vs. the brand's overall shortage rate across all carriers and terminals (industry average for consumer electronics is 1–2%). +2. Identify the shift pattern. Atlanta terminal operates multiple shifts. Cross-reference the 14 shortage shipments' arrival and departure scan times against the terminal's shift schedule. If all 14 shipments were on the dock during the same shift window, the pilferage is likely associated with specific workers on that shift. +3. Present the pattern analysis to the carrier's Director of Claims or VP of Operations — not the sales rep, not the local terminal manager. This is a corporate-level conversation. Frame it as: "We have data suggesting a pattern that requires a joint investigation. Here's our analysis. We want to work with your security team." +4. Request that the carrier's loss prevention or security department conduct a covert investigation at the Atlanta terminal. Major LTL carriers have internal security teams specifically for this. Provide them with the shift-pattern analysis and the product profiles that are being targeted. +5. In parallel, introduce covert tracking. Ship 5–10 "bait" packages through the Atlanta terminal containing AirTag-type trackers concealed inside the product boxes alongside real product. If units are pilfered, the trackers will provide location data on where the stolen goods end up, which helps law enforcement build a case. +6. Implement tamper-evident packaging for all high-value shipments moving through the Atlanta terminal. Use serialized security tape that changes color if peeled and replaced. This doesn't prevent pilferage but makes it detectable at delivery — if the security tape is broken, the shortage is documented immediately. +7. File a comprehensive claim covering all 14 shortages as a single pattern claim, totaling $47,200, supported by the statistical analysis. Individual claims of $2,000 get denied by a claims adjuster following a script. A $47,200 pattern claim with statistical evidence gets escalated to claims management. +8. If the carrier refuses to investigate or settle, consider filing a report with the local FBI field office. Organized cargo theft from carrier terminals is a federal crime (18 USC §659, theft from interstate or foreign shipments). The FBI's cargo theft unit handles exactly this type of pattern. + +**Key Indicators:** +- Shortages of small, high-value consumer electronics from inside otherwise intact cases is the hallmark of organized terminal pilferage, not random loss +- A single terminal appearing in all claims is the strongest pattern indicator — it eliminates origin and destination as variables +- Shortage claims that the carrier denies because "case count matched" are actually consistent with pilferage — the thief reseals the case to avoid detection at the piece-count level +- If the shortages are concentrated on specific days of the week, there may be a shift or crew pattern +- Check if the carrier's Atlanta terminal has had employee theft incidents reported in the past — local court records or news reports may reveal prior issues + +**Documentation Required:** +- Detailed claim log for all 14 shortage claims with full shipment data +- Statistical pattern analysis (spreadsheet) showing Atlanta terminal as common factor +- Shift-pattern analysis correlating shortage shipments to terminal operating hours +- Rate comparison: shortage rate for Atlanta-routed vs. non-Atlanta-routed shipments +- Photographs of opened cases showing missing units and condition of tape/seal +- Bait package tracking data (if deployed) +- Tamper-evident packaging results (if implemented) +- Carrier correspondence — all claim filings, denials, and escalation communications +- Formal pattern claim filing with the carrier ($47,200 aggregate) +- Law enforcement report (if filed) + +**Resolution Timeline:** +- Days 0–7: Pattern analysis completed and presented to carrier leadership +- Days 7–14: Carrier security team briefed and investigation initiated +- Days 14–30: Bait packages shipped, tamper-evident packaging deployed +- Days 30–60: Investigation results (carrier internal) and pattern claim response +- Days 60–90: Settlement negotiation on the aggregate claim +- Days 90–180: If pilferage is confirmed, potential criminal prosecution and full recovery + +--- + +### Edge Case 11: Hazmat Shipment Damaged in Transit with Environmental Contamination Risk + +**Situation:** +A specialty chemical manufacturer ships a truckload of sodium hypochlorite solution (industrial bleach, 12.5% concentration) — 20 IBC totes (275 gallons each, 5,500 gallons total), classified as UN1791, Corrosive Liquid, Class 8, PG II — from their plant in Baton Rouge, LA to a water treatment facility in Birmingham, AL. + +At approximately mile 180 on I-59 near Hattiesburg, MS, the driver encounters a sudden lane closure for road construction. He brakes hard. Three IBC totes in the rear of the trailer shift forward, two of them toppling. One tote's valve assembly shears off and sodium hypochlorite begins leaking onto the trailer floor and out the rear door gaps. The driver smells chlorine, pulls over, and calls his dispatcher. He estimates 50–75 gallons have leaked onto the highway shoulder before he could stop. + +The situation now involves: (a) a hazmat spill on a state highway requiring notification and cleanup, (b) a damaged shipment where 3 of 20 totes may be compromised, (c) a driver who has been exposed to chlorine vapor and may need medical attention, (d) a consignee water treatment plant that needs the chemical for drinking water treatment, and (e) potential EPA, Mississippi DEQ, and DOT enforcement actions. + +**Why It's Tricky:** +A hazmat in-transit incident is not just a freight claim — it's a multi-agency regulatory event. The spill triggers mandatory reporting obligations under 49 CFR §171.15 (immediate phone report to the National Response Center if the spill meets reportable quantity thresholds) and 49 CFR §171.16 (written hazmat incident report within 30 days). Sodium hypochlorite at 50+ gallons on a highway triggers the reportable quantity threshold. + +The environmental cleanup cost will likely dwarf the product value. The 5,500 gallons of chemical is worth about $8,250. The highway shoulder cleanup, soil remediation, and storm drain protection for a 50-gallon bleach spill on a Mississippi highway will cost $15,000–$40,000 depending on proximity to waterways. + +Liability is layered: the shipper is the "offeror" under hazmat regulations and is responsible for proper packaging and loading. The carrier is responsible for safe transportation and proper load securement. If the IBC totes shifted because they weren't properly secured (blocked and braced per the carrier's securement obligations under 49 CFR §393), the carrier bears liability. If the totes shifted because the valve assemblies were improperly rated for transport vibration, the shipper/manufacturer bears liability. + +**Common Mistake:** +Treating this as a freight claim first and a hazmat incident second. It's the opposite. The first priority is life safety and environmental containment, followed by regulatory compliance, and then — distantly — commercial recovery. + +The second mistake: the driver attempting to clean up the spill himself. Sodium hypochlorite at 12.5% concentration is a corrosive that generates toxic chlorine gas, especially if it contacts organic matter or acid (which could be in the road debris). The driver should evacuate the area, not grab a mop. + +**Expert Approach:** +1. Immediate response (minute 0): the driver must move upwind and uphill from the spill, call 911, and report a hazardous materials spill. The driver must not attempt to stop the leak, upright the totes, or clean the spill unless they are hazmat-trained and have appropriate PPE (which over-the-road drivers typically do not carry for Class 8 corrosives). +2. Regulatory notifications (within 15 minutes): the carrier's dispatch must call the National Response Center (NRC) at 800-424-8802. This is a mandatory immediate notification for any hazmat spill meeting the reportable quantity. For sodium hypochlorite, the reportable quantity is 100 lbs — 50 gallons at approximately 10 lbs/gallon is 500 lbs, well over the threshold. +3. The carrier must also notify Mississippi's Department of Environmental Quality (MDEQ) emergency spill line. State notification is required in addition to federal NRC notification. +4. Driver medical: if the driver is experiencing respiratory distress, burning eyes, or coughing from chlorine exposure, 911 will dispatch EMS. The carrier must ensure the driver receives medical attention before worrying about the freight. +5. Once emergency services arrive and control the scene, the carrier must arrange for a licensed hazmat cleanup contractor. The Mississippi State Highway Patrol will not allow the carrier to move the trailer until the spill is contained and the remaining totes are assessed for stability. This can take 4–12 hours. +6. Assessment of the remaining product: the 17 undamaged totes and the 2 toppled (but possibly intact) totes need to be inspected by a hazmat technician before they can continue transport. If the toppled totes have compromised valve assemblies or cracked walls, they must be overpacked (placed inside larger containment) for transport to a transload facility — they cannot continue to the consignee in damaged condition. +7. Load securement investigation: before moving any freight, document the securement setup. Were the IBC totes blocked and braced? Were load bars or cargo straps used? IBC totes on flatbed or dry van trailers must be secured per 49 CFR §393.116 (securement of intermodal containers) or the general cargo securement provisions. Photograph the securement setup as-is. This is the key liability evidence. +8. Contact the consignee water treatment plant immediately. They need to source replacement chemical from a backup supplier to maintain drinking water treatment operations. A water treatment plant running low on disinfection chemical is a public health emergency. Provide the plant with the timeline for delivery of the undamaged product (likely 24–48 hours after scene clearance) and help them source the 825-gallon shortfall (3 damaged totes worth) from a regional supplier. +9. File the written hazmat incident report (DOT Form F 5800.1) within 30 days. This report goes to PHMSA (Pipeline and Hazardous Materials Safety Administration) and becomes a public record. Accuracy is critical — this document can be used in enforcement proceedings. +10. Pursue the cargo and environmental cleanup costs based on liability determination. If the carrier failed to properly secure the load, they bear liability for the product loss, cleanup costs, driver medical costs, and any regulatory fines. If the shipper's IBC totes had a manufacturing defect (e.g., the valve assembly sheared at normal braking force, indicating a design flaw), the tote manufacturer bears product liability. + +**Key Indicators:** +- A valve assembly that shears off during normal hard braking (not a collision) suggests either an improperly rated valve or a tote that was overfilled — check the fill level against the tote's maximum capacity and the 80% fill rule for IBCs containing corrosives +- If the load was unsecured (no straps, no load bars, no blocking), the carrier's liability is clear regardless of the braking situation +- Three totes shifting suggests a systemic securement failure, not an isolated strap break. One tote falling could be a strap failure; three totes means the entire load was inadequately secured. +- Check the driver's CDL for hazmat endorsement. Driving a placarded load without the endorsement is a separate violation that compounds the carrier's liability. +- If the sodium hypochlorite reached a storm drain or waterway, the cleanup cost escalates dramatically and may trigger Superfund reporting requirements + +**Documentation Required:** +- NRC notification confirmation number and timestamp +- MDEQ spill notification confirmation +- 911 call record and emergency response documentation +- Photographs of the spill scene, damaged totes, and load securement setup (taken before cleanup) +- Driver's medical treatment records (if applicable) +- Hazmat cleanup contractor's containment and remediation report with cost +- 49 CFR §393 load securement inspection report +- DOT Form F 5800.1 hazmat incident report (filed within 30 days) +- Driver's CDL and hazmat endorsement verification +- IBC tote manufacturer specifications and valve assembly ratings +- BOL, shipping papers, and emergency response information (ERG guide page) +- Consignee notification and replacement sourcing documentation +- Environmental monitoring results (soil, water testing at the spill site) + +**Resolution Timeline:** +- Minutes 0–15: Emergency notifications (911, NRC, MDEQ) +- Hours 0–4: Scene control, spill containment, driver medical attention +- Hours 4–12: Hazmat cleanup, remaining totes inspected, trailer released +- Hours 12–48: Undamaged totes delivered to consignee, replacement chemical sourced for shortfall +- Days 1–7: Load securement investigation, liability assessment, carrier/shipper negotiation +- Days 7–30: DOT Form F 5800.1 filed, environmental monitoring results received +- Days 30–90: Cleanup cost and cargo claim settlement +- Days 90–365: Potential PHMSA enforcement action (civil penalties for securement violations can reach $500,000+ per violation) + +--- + +### Edge Case 12: Customer Rejects Shipment for Late Delivery on JIT Production Line, but Carrier Met the BOL Delivery Window + +**Situation:** +An automotive Tier 1 supplier ships a truckload of stamped metal brackets (43,000 pieces, value $186,000) from their Youngstown, OH plant to a GM assembly plant in Spring Hill, TN. The parts feed directly into the truck assembly line under a JIT (just-in-time) delivery program. The JIT window, per GM's scheduling system, is Tuesday 04:00–06:00 — parts must arrive within that 2-hour window or the line shuts down. + +The BOL, however, lists the delivery date as "Tuesday" with no specific time window. The carrier's rate confirmation lists delivery as "by end of day Tuesday." The carrier delivers at 11:42 on Tuesday. The GM receiving dock rejects the shipment because the JIT window closed at 06:00. GM's production line halted at 06:47 when the bracket buffer stock ran out, and the line was down for 4.5 hours until the carrier's truck was finally unloaded at 11:42 under emergency protocols. + +GM issues a line-down chargeback to the Tier 1 supplier for $215,000 (the calculated cost of 4.5 hours of assembly line downtime at ~$47,800/hour). The Tier 1 supplier demands the carrier pay the chargeback plus the freight charges. The carrier says they delivered on Tuesday — within the BOL's delivery date — and they have no knowledge of, or obligation to meet, a JIT delivery window that was never communicated to them. + +**Why It's Tricky:** +The carrier has a strong defense. The BOL says "Tuesday" and the carrier delivered Tuesday. The rate confirmation says "by end of day Tuesday" and the carrier delivered by end of day. The JIT window of 04:00–06:00 appears nowhere in the carrier's documentation. The Tier 1 supplier's logistics team communicated the JIT window to their own scheduling system and to GM, but never put it on the BOL or the carrier's rate confirmation. + +The $215,000 chargeback is a consequential damage claim — the carrier is responsible for the freight charges and possibly the value of the goods if damaged, but consequential damages (like production line downtime) require that the carrier had "actual or constructive notice" of the specific consequences of late delivery. Under the Carmack Amendment, consequential damages are recoverable only if the carrier knew or should have known about the specific time-sensitivity. + +A carrier delivering at 11:42 for a "Tuesday" delivery did nothing wrong by the terms they agreed to. The Tier 1 supplier's failure to communicate the JIT window to the carrier is the root cause, but GM doesn't care about the supplier's internal logistics — they want their $215,000. + +**Common Mistake:** +The Tier 1 supplier's traffic manager tries to recover the full $215,000 from the carrier by arguing "you knew this was an automotive JIT delivery." But knowing a consignee is an auto assembly plant is not the same as knowing the specific delivery window. Many deliveries to assembly plants go to a warehouse dock, not the JIT receiving dock. Without specific written notice of the 04:00–06:00 window and the consequences of missing it, the carrier's liability for consequential damages is virtually zero. + +The second mistake: the supplier accepting the full $215,000 chargeback from GM without negotiation. GM's chargeback calculations are often inflated — the $47,800/hour figure includes overhead allocation, labor costs for idled workers, and opportunity cost. The actual incremental cost of 4.5 hours of downtime may be significantly lower. Chargebacks are negotiable. + +**Expert Approach:** +1. Accept responsibility for the communication failure — the Tier 1 supplier's logistics team did not convey the JIT window to the carrier. This is not the carrier's fault. Attempting to blame the carrier poisons a relationship for a claim they'll ultimately lose. +2. Negotiate the GM chargeback. Request GM's detailed calculation supporting the $47,800/hour figure. Standard OEM downtime calculations include direct costs (line labor, utility, scrap from partial builds) and indirect costs (overhead allocation, management time, schedule recovery). Push back on the indirect costs. A 4.5-hour stoppage with a full recovery by end of shift typically warrants a 40–60% reduction in the chargeback amount. Aim for $90,000–$130,000. +3. File an internal corrective action. The failure was in the supplier's logistics process: the JIT window was known internally but not transmitted to the carrier. Implement a standard procedure requiring all JIT delivery windows to appear on the BOL in the "special instructions" field and on the carrier's rate confirmation. The rate confirmation should state: "DELIVERY WINDOW: 04:00–06:00 TUESDAY. LATE DELIVERY WILL RESULT IN PRODUCTION LINE DOWNTIME AT APPROXIMATELY $X/HOUR." +4. For the carrier relationship: share the situation transparently. Explain the JIT delivery program and acknowledge the communication gap. Offer to add the delivery window to future rate confirmations along with an appropriate accessorial charge for time-definite delivery. Carriers will quote a premium for guaranteed delivery windows — typically $200–$500 for a 2-hour window on a 500-mile haul — but that premium is trivial compared to a $215,000 chargeback. +5. Implement a buffer strategy with GM. The underlying vulnerability is a single truckload feeding a production line with minimal buffer stock. Work with GM's materials planning team to increase the bracket buffer from 47 minutes (which is what the 06:47 line-down time implies) to 4 hours. This costs additional warehouse space and carrying cost at the assembly plant, but it converts a missed 2-hour delivery window from a $215,000 disaster to a minor scheduling inconvenience. +6. Consider a carrier-of-last-resort arrangement for this lane. Identify a dedicated carrier or small fleet within 2 hours of Spring Hill that can run an emergency load if the primary carrier is delayed. Pre-stage one truckload of brackets at a cross-dock near Spring Hill as rolling safety stock. The carrying cost of $186,000 in brackets sitting at a cross-dock ($400–$600/month in storage) is insurance against $215,000 chargebacks. + +**Key Indicators:** +- A BOL without a specific delivery time window provides the carrier zero legal exposure for consequential damages from late delivery — the entire consequential damages claim depends on documented, communicated time-sensitivity +- GM and other major OEMs chargeback calculations are formulaic and include significant overhead allocation — they are always negotiable, though the negotiation requires understanding the OEM's cost model +- A 47-minute buffer stock at an assembly plant is dangerously thin for a JIT delivery program — anything less than 2 hours of buffer for a 500+ mile lane is an organizational risk management failure +- If the carrier has a history of on-time delivery for this lane (check their scorecard), this is an anomaly, not a pattern — that context helps in both the carrier conversation and the GM chargeback negotiation +- Check whether the carrier experienced any en-route delays (weather, traffic, mechanical) that explain the 11:42 arrival. A documented en-route delay is a mitigating factor even though the carrier isn't technically liable. + +**Documentation Required:** +- BOL showing delivery date without time window +- Carrier rate confirmation showing "by end of day Tuesday" +- GM's JIT scheduling system printout showing the 04:00–06:00 delivery window +- GM's line-down notification and production stoppage report +- GM's chargeback notice with detailed cost calculation +- Carrier's delivery receipt showing 11:42 arrival and unloading +- Carrier's ELD data showing en-route trip timeline +- Internal corrective action report documenting the communication gap +- Updated BOL and rate confirmation templates with JIT delivery window fields +- Negotiated chargeback settlement agreement with GM +- Carrier on-time performance scorecard for the lane (prior 12 months) + +**Resolution Timeline:** +- Hours 0–4: Immediate crisis management — emergency unloading at GM, line restarted +- Days 1–3: Root cause analysis, carrier conversation, GM chargeback received +- Days 3–14: GM chargeback negotiation, internal corrective action drafted +- Days 14–30: Corrective action implemented (BOL/rate confirmation process updates) +- Days 30–45: GM chargeback settlement +- Days 30–60: Buffer strategy and carrier-of-last-resort arrangement implemented +- Ongoing: Monthly review of JIT delivery performance for all assembly plant lanes + +--- + +## Cross-Cutting Lessons + +The edge cases above share several themes that experienced exception managers internalize: + +1. **Documentation at the moment of discovery is irreplaceable.** Photos, data downloads, witness statements, and physical evidence degrade or disappear within hours. The first responder's instinct should be to document, not to fix. + +2. **Separate the immediate crisis from the claim.** Getting the customer their product, containing the spill, or keeping the production line running is always the first priority. The claim can be filed for months afterward; the commercial or safety crisis cannot wait. + +3. **Liability is rarely 100% on one party.** Most complex exceptions involve shared fault — a shipper who didn't communicate, a carrier who didn't secure, a broker who didn't pay, a consignee who didn't inspect. Expert resolution is about finding the right allocation, not proving absolute fault. + +4. **Escalate through data, not emotion.** "Your driver broke our product" gets denied. "We have a pattern of 14 shortage claims correlating to your Atlanta terminal's second shift" gets investigated. + +5. **The carrier's front-line customer service sees the same portal you do.** For any exception involving real money or real urgency, go directly to the carrier's operations team, sales representative, or claims director. The 800-number is for routine inquiries, not for $200K exposures. + +6. **Contracts and tariffs are the battlefield.** Every surcharge dispute, every consequential damages claim, and every liability allocation ultimately comes down to what was written, what was communicated, and what was incorporated by reference. Read the tariff. Read the contract. Know what your counterparty actually agreed to. + +7. **Time is the most expensive variable.** Every day a perishable shipment sits at a carrier's yard, every hour an assembly line is down, every week a customs hold persists — these accrue costs that dwarf the underlying product value. Speed of resolution is not just a service metric; it's a financial imperative. diff --git a/web-app/public/skills/m365-agents-dotnet/SKILL.md b/web-app/public/skills/m365-agents-dotnet/SKILL.md index eb93c7eb..01b1885f 100644 --- a/web-app/public/skills/m365-agents-dotnet/SKILL.md +++ b/web-app/public/skills/m365-agents-dotnet/SKILL.md @@ -1,6 +1,6 @@ --- name: m365-agents-dotnet -description: "|" +description: | Microsoft 365 Agents SDK for .NET. Build multichannel agents for Teams/M365/Copilot Studio with ASP.NET Core hosting, AgentApplication routing, and MSAL-based auth. Triggers: "Microsoft 365 Agents SDK", "Microsoft.Agents", "AddAgentApplicationOptions", "AgentApplication", "AddAgentAspNetAuthentication", "Copilot Studio client", "IAgentHttpAdapter". package: Microsoft.Agents.Hosting.AspNetCore, Microsoft.Agents.Authentication.Msal, Microsoft.Agents.CopilotStudio.Client risk: unknown diff --git a/web-app/public/skills/m365-agents-py/SKILL.md b/web-app/public/skills/m365-agents-py/SKILL.md index 0583cd23..3ec3bbdf 100644 --- a/web-app/public/skills/m365-agents-py/SKILL.md +++ b/web-app/public/skills/m365-agents-py/SKILL.md @@ -1,6 +1,6 @@ --- name: m365-agents-py -description: "|" +description: | Microsoft 365 Agents SDK for Python. Build multichannel agents for Teams/M365/Copilot Studio with aiohttp hosting, AgentApplication routing, streaming responses, and MSAL-based auth. Triggers: "Microsoft 365 Agents SDK", "microsoft_agents", "AgentApplication", "start_agent_process", "TurnContext", "Copilot Studio client", "CloudAdapter". package: microsoft-agents-hosting-core, microsoft-agents-hosting-aiohttp, microsoft-agents-activity, microsoft-agents-authentication-msal, microsoft-agents-copilotstudio-client risk: unknown diff --git a/web-app/public/skills/m365-agents-ts/SKILL.md b/web-app/public/skills/m365-agents-ts/SKILL.md index f62cadf7..b6ec66fe 100644 --- a/web-app/public/skills/m365-agents-ts/SKILL.md +++ b/web-app/public/skills/m365-agents-ts/SKILL.md @@ -1,6 +1,6 @@ --- name: m365-agents-ts -description: "|" +description: | Microsoft 365 Agents SDK for TypeScript/Node.js. Build multichannel agents for Teams/M365/Copilot Studio with AgentApplication routing, Express hosting, streaming responses, and Copilot Studio client integration. Triggers: "Microsoft 365 Agents SDK", "@microsoft/agents-hosting", "AgentApplication", "startServer", "streamingResponse", "Copilot Studio client", "@microsoft/agents-copilotstudio-client". package: "@microsoft/agents-hosting, @microsoft/agents-hosting-express, @microsoft/agents-activity, @microsoft/agents-copilotstudio-client" risk: unknown diff --git a/web-app/public/skills/malware-analyst/SKILL.md b/web-app/public/skills/malware-analyst/SKILL.md index d6737995..4b447911 100644 --- a/web-app/public/skills/malware-analyst/SKILL.md +++ b/web-app/public/skills/malware-analyst/SKILL.md @@ -1,6 +1,7 @@ --- name: malware-analyst -description: "Expert malware analyst specializing in defensive malware research," +description: | + Expert malware analyst specializing in defensive malware research, threat intelligence, and incident response. Masters sandbox analysis, behavioral analysis, and malware family identification. Handles static/dynamic analysis, unpacking, and IOC extraction. Use PROACTIVELY for malware triage, diff --git a/web-app/public/skills/market-sizing-analysis/SKILL.md b/web-app/public/skills/market-sizing-analysis/SKILL.md index 0768dcd3..3ddc7dd0 100644 --- a/web-app/public/skills/market-sizing-analysis/SKILL.md +++ b/web-app/public/skills/market-sizing-analysis/SKILL.md @@ -1,6 +1,7 @@ --- name: market-sizing-analysis -description: "This skill should be used when the user asks to \\\"calculate TAM\\\"," +description: | + This skill should be used when the user asks to \\\"calculate TAM\\\", "determine SAM", "estimate SOM", "size the market", "calculate market opportunity", "what's the total addressable market", or requests market sizing analysis for a startup or business opportunity. diff --git a/web-app/public/skills/mermaid-expert/SKILL.md b/web-app/public/skills/mermaid-expert/SKILL.md index 424f298c..6e328913 100644 --- a/web-app/public/skills/mermaid-expert/SKILL.md +++ b/web-app/public/skills/mermaid-expert/SKILL.md @@ -1,6 +1,7 @@ --- name: mermaid-expert -description: "Create Mermaid diagrams for flowcharts, sequences, ERDs, and" +description: | + Create Mermaid diagrams for flowcharts, sequences, ERDs, and architectures. Masters syntax for all diagram types and styling. Use PROACTIVELY for visual documentation, system diagrams, or process flows. metadata: diff --git a/web-app/public/skills/microsoft-azure-webjobs-extensions-authentication-events-dotnet/SKILL.md b/web-app/public/skills/microsoft-azure-webjobs-extensions-authentication-events-dotnet/SKILL.md index e79459a7..d49dcee2 100644 --- a/web-app/public/skills/microsoft-azure-webjobs-extensions-authentication-events-dotnet/SKILL.md +++ b/web-app/public/skills/microsoft-azure-webjobs-extensions-authentication-events-dotnet/SKILL.md @@ -1,6 +1,6 @@ --- name: microsoft-azure-webjobs-extensions-authentication-events-dotnet -description: "|" +description: | Microsoft Entra Authentication Events SDK for .NET. Azure Functions triggers for custom authentication extensions. Use for token enrichment, custom claims, attribute collection, and OTP customization in Entra ID. Triggers: "Authentication Events", "WebJobsAuthenticationEventsTrigger", "OnTokenIssuanceStart", "OnAttributeCollectionStart", "custom claims", "token enrichment", "Entra custom extension", "authentication extension". risk: unknown source: community diff --git a/web-app/public/skills/minecraft-bukkit-pro/SKILL.md b/web-app/public/skills/minecraft-bukkit-pro/SKILL.md index e52acd91..f89b7668 100644 --- a/web-app/public/skills/minecraft-bukkit-pro/SKILL.md +++ b/web-app/public/skills/minecraft-bukkit-pro/SKILL.md @@ -1,6 +1,7 @@ --- name: minecraft-bukkit-pro -description: "Master Minecraft server plugin development with Bukkit, Spigot, and" +description: | + Master Minecraft server plugin development with Bukkit, Spigot, and Paper APIs. Specializes in event-driven architecture, command systems, world manipulation, player management, and performance optimization. Use PROACTIVELY for plugin architecture, gameplay mechanics, server-side features, or diff --git a/web-app/public/skills/ml-engineer/SKILL.md b/web-app/public/skills/ml-engineer/SKILL.md index f34b1020..4a816dc6 100644 --- a/web-app/public/skills/ml-engineer/SKILL.md +++ b/web-app/public/skills/ml-engineer/SKILL.md @@ -1,6 +1,7 @@ --- name: ml-engineer -description: "Build production ML systems with PyTorch 2.x, TensorFlow, and" +description: | + Build production ML systems with PyTorch 2.x, TensorFlow, and modern ML frameworks. Implements model serving, feature engineering, A/B testing, and monitoring. Use PROACTIVELY for ML model deployment, inference optimization, or production ML infrastructure. diff --git a/web-app/public/skills/mlops-engineer/SKILL.md b/web-app/public/skills/mlops-engineer/SKILL.md index 97a59c63..511743e8 100644 --- a/web-app/public/skills/mlops-engineer/SKILL.md +++ b/web-app/public/skills/mlops-engineer/SKILL.md @@ -1,6 +1,7 @@ --- name: mlops-engineer -description: "Build comprehensive ML pipelines, experiment tracking, and model" +description: | + Build comprehensive ML pipelines, experiment tracking, and model registries with MLflow, Kubeflow, and modern MLOps tools. Implements automated training, deployment, and monitoring across cloud platforms. Use PROACTIVELY for ML infrastructure, experiment management, or pipeline automation. diff --git a/web-app/public/skills/mobile-developer/SKILL.md b/web-app/public/skills/mobile-developer/SKILL.md index a347fb69..7c9de867 100644 --- a/web-app/public/skills/mobile-developer/SKILL.md +++ b/web-app/public/skills/mobile-developer/SKILL.md @@ -1,6 +1,7 @@ --- name: mobile-developer -description: "Develop React Native, Flutter, or native mobile apps with modern" +description: | + Develop React Native, Flutter, or native mobile apps with modern architecture patterns. Masters cross-platform development, native integrations, offline sync, and app store optimization. Use PROACTIVELY for mobile features, cross-platform code, or app optimization. diff --git a/web-app/public/skills/mobile-security-coder/SKILL.md b/web-app/public/skills/mobile-security-coder/SKILL.md index 77e20219..d6756980 100644 --- a/web-app/public/skills/mobile-security-coder/SKILL.md +++ b/web-app/public/skills/mobile-security-coder/SKILL.md @@ -1,6 +1,7 @@ --- name: mobile-security-coder -description: "Expert in secure mobile coding practices specializing in input" +description: | + Expert in secure mobile coding practices specializing in input validation, WebView security, and mobile-specific security patterns. Use PROACTIVELY for mobile security implementations or mobile security code reviews. diff --git a/web-app/public/skills/network-engineer/SKILL.md b/web-app/public/skills/network-engineer/SKILL.md index 3fc439d3..26cf7f66 100644 --- a/web-app/public/skills/network-engineer/SKILL.md +++ b/web-app/public/skills/network-engineer/SKILL.md @@ -1,6 +1,7 @@ --- name: network-engineer -description: "Expert network engineer specializing in modern cloud networking," +description: | + Expert network engineer specializing in modern cloud networking, security architectures, and performance optimization. Masters multi-cloud connectivity, service mesh, zero-trust networking, SSL/TLS, global load balancing, and advanced troubleshooting. Handles CDN optimization, network diff --git a/web-app/public/skills/observability-engineer/SKILL.md b/web-app/public/skills/observability-engineer/SKILL.md index 6246773f..ac320312 100644 --- a/web-app/public/skills/observability-engineer/SKILL.md +++ b/web-app/public/skills/observability-engineer/SKILL.md @@ -1,6 +1,7 @@ --- name: observability-engineer -description: "Build production-ready monitoring, logging, and tracing systems." +description: | + Build production-ready monitoring, logging, and tracing systems. Implements comprehensive observability strategies, SLI/SLO management, and incident response workflows. Use PROACTIVELY for monitoring infrastructure, performance optimization, or production reliability. diff --git a/web-app/public/skills/page-cro/SKILL.md b/web-app/public/skills/page-cro/SKILL.md index cf1c1d80..bdb40688 100644 --- a/web-app/public/skills/page-cro/SKILL.md +++ b/web-app/public/skills/page-cro/SKILL.md @@ -1,6 +1,6 @@ --- name: page-cro -description: ">" +description: > Analyze and optimize individual pages for conversion performance. Use when the user wants to improve conversion rates, diagnose why a page is underperforming, or increase the effectiveness of marketing pages diff --git a/web-app/public/skills/payment-integration/SKILL.md b/web-app/public/skills/payment-integration/SKILL.md index 5620721d..378ae43d 100644 --- a/web-app/public/skills/payment-integration/SKILL.md +++ b/web-app/public/skills/payment-integration/SKILL.md @@ -1,6 +1,7 @@ --- name: payment-integration -description: "Integrate Stripe, PayPal, and payment processors. Handles checkout" +description: | + Integrate Stripe, PayPal, and payment processors. Handles checkout flows, subscriptions, webhooks, and PCI compliance. Use PROACTIVELY when implementing payments, billing, or subscription features. metadata: diff --git a/web-app/public/skills/php-pro/SKILL.md b/web-app/public/skills/php-pro/SKILL.md index 1bd59417..99fa90e7 100644 --- a/web-app/public/skills/php-pro/SKILL.md +++ b/web-app/public/skills/php-pro/SKILL.md @@ -1,6 +1,7 @@ --- name: php-pro -description: "Write idiomatic PHP code with generators, iterators, SPL data" +description: | + Write idiomatic PHP code with generators, iterators, SPL data structures, and modern OOP features. Use PROACTIVELY for high-performance PHP applications. metadata: diff --git a/web-app/public/skills/posix-shell-pro/SKILL.md b/web-app/public/skills/posix-shell-pro/SKILL.md index 6e248286..b6c7824a 100644 --- a/web-app/public/skills/posix-shell-pro/SKILL.md +++ b/web-app/public/skills/posix-shell-pro/SKILL.md @@ -1,6 +1,7 @@ --- name: posix-shell-pro -description: "Expert in strict POSIX sh scripting for maximum portability across" +description: | + Expert in strict POSIX sh scripting for maximum portability across Unix-like systems. Specializes in shell scripts that run on any POSIX-compliant shell (dash, ash, sh, bash --posix). metadata: diff --git a/web-app/public/skills/production-scheduling/SKILL.md b/web-app/public/skills/production-scheduling/SKILL.md new file mode 100644 index 00000000..02cd702d --- /dev/null +++ b/web-app/public/skills/production-scheduling/SKILL.md @@ -0,0 +1,229 @@ +--- +name: production-scheduling +description: > + Codified expertise for production scheduling, job sequencing, line balancing, + changeover optimisation, and bottleneck resolution in discrete and batch + manufacturing. Informed by production schedulers with 15+ years experience. + Includes TOC/drum-buffer-rope, SMED, OEE analysis, disruption response + frameworks, and ERP/MES interaction patterns. Use when scheduling production, + resolving bottlenecks, optimising changeovers, responding to disruptions, + or balancing manufacturing lines. +license: Apache-2.0 +version: 1.0.0 +homepage: https://github.com/evos-ai/evos-capabilities +risk: safe +source: https://github.com/ai-evos/agent-skills +metadata: + author: evos + clawdbot: + emoji: "🏭" +--- + +## When to Use + +Use this skill when planning manufacturing operations, sequencing jobs to minimize changeover times, balancing production lines, resolving factory bottlenecks, or responding to unexpected equipment downtime and supply disruptions. + +# Production Scheduling + +## Role and Context + +You are a senior production scheduler at a discrete and batch manufacturing facility operating 3–8 production lines with 50–300 direct-labour headcount per shift. You manage job sequencing, line balancing, changeover optimization, and disruption response across work centres that include machining, assembly, finishing, and packaging. Your systems include an ERP (SAP PP, Oracle Manufacturing, or Epicor), a finite-capacity scheduling tool (Preactor, PlanetTogether, or Opcenter APS), an MES for shop floor execution and real-time reporting, and a CMMS for maintenance coordination. You sit between production management (which owns output targets and headcount), planning (which releases work orders from MRP), quality (which gates product release), and maintenance (which owns equipment availability). Your job is to translate a set of work orders with due dates, routings, and BOMs into a minute-by-minute execution sequence that maximises throughput at the constraint while meeting customer delivery commitments, labour rules, and quality requirements. + +## Core Knowledge + +### Scheduling Fundamentals + +**Forward vs. backward scheduling:** Forward scheduling starts from material availability date and schedules operations sequentially to find the earliest completion date. Backward scheduling starts from the customer due date and works backward to find the latest permissible start date. In practice, use backward scheduling as the default to preserve flexibility and minimise WIP, then switch to forward scheduling when the backward pass reveals that the latest start date is already in the past — that work order is already late-starting and needs to be expedited from today forward. + +**Finite vs. infinite capacity:** MRP runs infinite-capacity planning — it assumes every work centre has unlimited capacity and flags overloads for the scheduler to resolve manually. Finite-capacity scheduling (FCS) respects actual resource availability: machine count, shift patterns, maintenance windows, and tooling constraints. Never trust an MRP-generated schedule as executable without running it through finite-capacity logic. MRP tells you _what_ needs to be made; FCS tells you _when_ it can actually be made. + +**Drum-Buffer-Rope (DBR) and Theory of Constraints:** The drum is the constraint resource — the work centre with the least excess capacity relative to demand. The buffer is a time buffer (not inventory buffer) protecting the constraint from upstream starvation. The rope is the release mechanism that limits new work into the system to the constraint's processing rate. Identify the constraint by comparing load hours to available hours per work centre; the one with the highest utilisation ratio (>85%) is your drum. Subordinate every other scheduling decision to keeping the drum fed and running. A minute lost at the constraint is a minute lost for the entire plant; a minute lost at a non-constraint costs nothing if buffer time absorbs it. + +**JIT sequencing:** In mixed-model assembly environments, level the production sequence to minimise variation in component consumption rates. Use heijunka logic: if you produce models A, B, and C in a 3:2:1 ratio per shift, the ideal sequence is A-B-A-C-A-B, not AAA-BB-C. Levelled sequencing smooths upstream demand, reduces component safety stock, and prevents the "end-of-shift crunch" where the hardest jobs get pushed to the last hour. + +**Where MRP breaks down:** MRP assumes fixed lead times, infinite capacity, and perfect BOM accuracy. It fails when (a) lead times are queue-dependent and compress under light load or expand under heavy load, (b) multiple work orders compete for the same constrained resource, (c) setup times are sequence-dependent, or (d) yield losses create variable output from fixed input. Schedulers must compensate for all four. + +### Changeover Optimisation + +**SMED methodology (Single-Minute Exchange of Die):** Shigeo Shingo's framework divides setup activities into external (can be done while the machine is still running the previous job) and internal (must be done with the machine stopped). Phase 1: document the current setup and classify every element as internal or external. Phase 2: convert internal elements to external wherever possible (pre-staging tools, pre-heating moulds, pre-mixing materials). Phase 3: streamline remaining internal elements (quick-release clamps, standardised die heights, colour-coded connections). Phase 4: eliminate adjustments through poka-yoke and first-piece verification jigs. Typical results: 40–60% setup time reduction from Phase 1–2 alone. + +**Colour/size sequencing:** In painting, coating, printing, and textile operations, sequence jobs from light to dark, small to large, or simple to complex to minimise cleaning between runs. A light-to-dark paint sequence might need only a 5-minute flush; dark-to-light requires a 30-minute full-purge. Capture these sequence-dependent setup times in a setup matrix and feed it to the scheduling algorithm. + +**Campaign vs. mixed-model scheduling:** Campaign scheduling groups all jobs of the same product family into a single run, minimising total changeovers but increasing WIP and lead times. Mixed-model scheduling interleaves products to reduce lead times and WIP but incurs more changeovers. The right balance depends on the changeover-cost-to-carrying-cost ratio. When changeovers are long and expensive (>60 minutes, >$500 in scrap and lost output), lean toward campaigns. When changeovers are fast (<15 minutes) or when customer order profiles demand short lead times, lean toward mixed-model. + +**Changeover cost vs. inventory carrying cost vs. delivery tradeoff:** Every scheduling decision involves this three-way tension. Longer campaigns reduce changeover cost but increase cycle stock and risk missing due dates for non-campaign products. Shorter campaigns improve delivery responsiveness but increase changeover frequency. The economic crossover point is where marginal changeover cost equals marginal carrying cost per unit of additional cycle stock. Compute it; don't guess. + +### Bottleneck Management + +**Identifying the true constraint vs. where WIP piles up:** WIP accumulation in front of a work centre does not necessarily mean that work centre is the constraint. WIP can pile up because the upstream work centre is batch-dumping, because a shared resource (crane, forklift, inspector) creates an artificial queue, or because a scheduling rule creates starvation downstream. The true constraint is the resource with the highest ratio of required hours to available hours. Verify by checking: if you added one hour of capacity at this work centre, would plant output increase? If yes, it is the constraint. + +**Buffer management:** In DBR, the time buffer is typically 50% of the production lead time for the constraint operation. Monitor buffer penetration: green zone (buffer consumed < 33%) means the constraint is well-protected; yellow zone (33–67%) triggers expediting of late-arriving upstream work; red zone (>67%) triggers immediate management attention and possible overtime at upstream operations. Buffer penetration trends over weeks reveal chronic problems: persistent yellow means upstream reliability is degrading. + +**Subordination principle:** Non-constraint resources should be scheduled to serve the constraint, not to maximise their own utilisation. Running a non-constraint at 100% utilisation when the constraint operates at 85% creates excess WIP with no throughput gain. Deliberately schedule idle time at non-constraints to match the constraint's consumption rate. + +**Detecting shifting bottlenecks:** The constraint can move between work centres as product mix changes, as equipment degrades, or as staffing shifts. A work centre that is the bottleneck on day shift (running high-setup products) may not be the bottleneck on night shift (running long-run products). Monitor utilisation ratios weekly by product mix. When the constraint shifts, the entire scheduling logic must shift with it — the new drum dictates the tempo. + +### Disruption Response + +**Machine breakdowns:** Immediate actions: (1) assess repair time estimate with maintenance, (2) determine if the broken machine is the constraint, (3) if constraint, calculate throughput loss per hour and activate the contingency plan — overtime on alternate equipment, subcontracting, or re-sequencing to prioritise highest-margin jobs. If not the constraint, assess buffer penetration — if buffer is green, do nothing to the schedule; if yellow or red, expedite upstream work to alternate routings. + +**Material shortages:** Check substitute materials, alternate BOMs, and partial-build options. If a component is short, can you build sub-assemblies to the point of the missing component and complete later (kitting strategy)? Escalate to purchasing for expedited delivery. Re-sequence the schedule to pull forward jobs that do not require the short material, keeping the constraint running. + +**Quality holds:** When a batch is placed on quality hold, it is invisible to the schedule — it cannot ship and it cannot be consumed downstream. Immediately re-run the schedule excluding held inventory. If the held batch was feeding a customer commitment, assess alternative sources: safety stock, in-process inventory from another work order, or expedited production of a replacement batch. + +**Absenteeism:** With certified operator requirements, one absent operator can disable an entire line. Maintain a cross-training matrix showing which operators are certified on which equipment. When absenteeism occurs, first check whether the missing operator runs the constraint — if so, reassign the best-qualified backup. If the missing operator runs a non-constraint, assess whether buffer time absorbs the delay before pulling a backup from another area. + +**Re-sequencing framework:** When disruption hits, apply this priority logic: (1) protect constraint uptime above all else, (2) protect customer commitments in order of customer tier and penalty exposure, (3) minimise total changeover cost of the new sequence, (4) level labour load across remaining available operators. Re-sequence, communicate the new schedule within 30 minutes, and lock it for at least 4 hours before allowing further changes. + +### Labour Management + +**Shift patterns:** Common patterns include 3×8 (three 8-hour shifts, 24/5 or 24/7), 2×12 (two 12-hour shifts, often with rotating days), and 4×10 (four 10-hour days for day-shift-only operations). Each pattern has different implications for overtime rules, handover quality, and fatigue-related error rates. 12-hour shifts reduce handovers but increase error rates in hours 10–12. Factor this into scheduling: do not put critical first-piece inspections or complex changeovers in the last 2 hours of a 12-hour shift. + +**Skill matrices:** Maintain a matrix of operator × work centre × certification level (trainee, qualified, expert). Scheduling feasibility depends on this matrix — a work order routed to a CNC lathe is infeasible if no qualified operator is on shift. The scheduling tool should carry labour as a constraint alongside machines. + +**Cross-training ROI:** Each additional operator certified on the constraint work centre reduces the probability of constraint starvation due to absenteeism. Quantify: if the constraint generates $5,000/hour in throughput and average absenteeism is 8%, having only 2 qualified operators vs. 4 qualified operators changes the expected throughput loss by $200K+/year. + +**Union rules and overtime:** Many manufacturing environments have contractual constraints on overtime assignment (by seniority), mandatory rest periods between shifts (typically 8–10 hours), and restrictions on temporary reassignment across departments. These are hard constraints that the scheduling algorithm must respect. Violating a union rule can trigger a grievance that costs far more than the production it was meant to save. + +### OEE — Overall Equipment Effectiveness + +**Calculation:** OEE = Availability × Performance × Quality. Availability = (Planned Production Time − Downtime) / Planned Production Time. Performance = (Ideal Cycle Time × Total Pieces) / Operating Time. Quality = Good Pieces / Total Pieces. World-class OEE is 85%+; typical discrete manufacturing runs 55–65%. + +**Planned vs. unplanned downtime:** Planned downtime (scheduled maintenance, changeovers, breaks) is excluded from the Availability denominator in some OEE standards and included in others. Use TEEP (Total Effective Equipment Performance) when you need to compare across plants or justify capital expansion — TEEP includes all calendar time. + +**Availability losses:** Breakdowns and unplanned stops. Address with preventive maintenance, predictive maintenance (vibration analysis, thermal imaging), and TPM operator-level daily checks. Target: unplanned downtime < 5% of scheduled time. + +**Performance losses:** Speed losses and micro-stops. A machine rated at 100 parts/hour running at 85 parts/hour has a 15% performance loss. Common causes: material feed inconsistencies, worn tooling, sensor false-triggers, and operator hesitation. Track actual cycle time vs. standard cycle time per job. + +**Quality losses:** Scrap and rework. First-pass yield below 95% on a constraint operation directly reduces effective capacity. Prioritise quality improvement at the constraint — a 2% yield improvement at the constraint delivers the same throughput gain as a 2% capacity expansion. + +### ERP/MES Interaction Patterns + +**SAP PP / Oracle Manufacturing production planning flow:** Demand enters as sales orders or forecast consumption, drives MPS (Master Production Schedule), which explodes through MRP into planned orders by work centre with material requirements. The scheduler converts planned orders into production orders, sequences them, and releases to the shop floor via MES. Feedback flows from MES (operation confirmations, scrap reporting, labour booking) back to ERP to update order status and inventory. + +**Work order management:** A work order carries the routing (sequence of operations with work centres, setup times, and run times), the BOM (components required), and the due date. The scheduler's job is to assign each operation to a specific time slot on a specific resource, respecting resource capacity, material availability, and dependency constraints (operation 20 cannot start until operation 10 is complete). + +**Shop floor reporting and plan-vs-reality gap:** MES captures actual start/end times, actual quantities produced, scrap counts, and downtime reasons. The gap between the schedule and MES actuals is the "plan adherence" metric. Healthy plan adherence is > 90% of jobs starting within ±1 hour of scheduled start. Persistent gaps indicate that either the scheduling parameters (setup times, run rates, yield factors) are wrong or that the shop floor is not following the sequence. + +**Closing the loop:** Every shift, compare scheduled vs. actual at the operation level. Update the schedule with actuals, re-sequence the remaining horizon, and publish the updated schedule. This "rolling re-plan" cadence keeps the schedule realistic rather than aspirational. The worst failure mode is a schedule that diverges from reality and becomes ignored by the shop floor — once operators stop trusting the schedule, it ceases to function. + +## Decision Frameworks + +### Job Priority Sequencing + +When multiple jobs compete for the same resource, apply this decision tree: + +1. **Is any job past-due or will miss its due date without immediate processing?** → Schedule past-due jobs first, ordered by customer penalty exposure (contractual penalties > reputational damage > internal KPI impact). +2. **Are any jobs feeding the constraint and the constraint buffer is in yellow or red zone?** → Schedule constraint-feeding jobs next to prevent constraint starvation. +3. **Among remaining jobs, apply the dispatching rule appropriate to the product mix:** + - High-variety, short-run: use **Earliest Due Date (EDD)** to minimise maximum lateness. + - Long-run, few products: use **Shortest Processing Time (SPT)** to minimise average flow time and WIP. + - Mixed, with sequence-dependent setups: use **setup-aware EDD** — EDD with a setup-time lookahead that swaps adjacent jobs when a swap saves >30 minutes of setup without causing a due date miss. +4. **Tie-breaker:** Higher customer tier wins. If same tier, higher margin job wins. + +### Changeover Sequence Optimisation + +1. **Build the setup matrix:** For each pair of products (A→B, B→A, A→C, etc.), record the changeover time in minutes and the changeover cost (labour + scrap + lost output). +2. **Identify mandatory sequence constraints:** Some transitions are prohibited (allergen cross-contamination in food, hazardous material sequencing in chemical). These are hard constraints, not optimisable. +3. **Apply nearest-neighbour heuristic as baseline:** From the current product, select the next product with the smallest changeover time. This gives a feasible starting sequence. +4. **Improve with 2-opt swaps:** Swap pairs of adjacent jobs; keep the swap if total changeover time decreases without violating due dates. +5. **Validate against due dates:** Run the optimised sequence through the schedule. If any job misses its due date, insert it earlier even if it increases total changeover time. Due date compliance trumps changeover optimisation. + +### Disruption Re-Sequencing + +When a disruption invalidates the current schedule: + +1. **Assess impact window:** How many hours/shifts is the disrupted resource unavailable? Is it the constraint? +2. **Freeze committed work:** Jobs already in process or within 2 hours of start should not be moved unless physically impossible. +3. **Re-sequence remaining jobs:** Apply the job priority framework above to all unfrozen jobs, using updated resource availability. +4. **Communicate within 30 minutes:** Publish the revised schedule to all affected work centres, supervisors, and material handlers. +5. **Set a stability lock:** No further schedule changes for at least 4 hours (or until next shift start) unless a new disruption occurs. Constant re-sequencing creates more chaos than the original disruption. + +### Bottleneck Identification + +1. **Pull utilisation reports** for all work centres over the trailing 2 weeks (by shift, not averaged). +2. **Rank by utilisation ratio** (load hours / available hours). The top work centre is the suspected constraint. +3. **Verify causally:** Would adding one hour of capacity at this work centre increase total plant output? If the work centre downstream of it is always starved when this one is down, the answer is yes. +4. **Check for shifting patterns:** If the top-ranked work centre changes between shifts or between weeks, you have a shifting bottleneck driven by product mix. In this case, schedule the constraint _for each shift_ based on that shift's product mix, not on a weekly average. +5. **Distinguish from artificial constraints:** A work centre that appears overloaded because upstream batch-dumps WIP into it is not a true constraint — it is a victim of poor upstream scheduling. Fix the upstream release rate before adding capacity to the victim. + +## Key Edge Cases + +Brief summaries here. Full analysis in [edge-cases.md](references/edge-cases.md). + +1. **Shifting bottleneck mid-shift:** Product mix change moves the constraint from machining to assembly during the shift. The schedule that was optimal at 6:00 AM is wrong by 10:00 AM. Requires real-time utilisation monitoring and intra-shift re-sequencing authority. + +2. **Certified operator absent for regulated process:** An FDA-regulated coating operation requires a specific operator certification. The only certified night-shift operator calls in sick. The line cannot legally run. Activate the cross-training matrix, call in a certified day-shift operator on overtime if permitted, or shut down the regulated operation and re-route non-regulated work. + +3. **Competing rush orders from tier-1 customers:** Two top-tier automotive OEM customers both demand expedited delivery. Satisfying one delays the other. Requires commercial decision input — which customer relationship carries higher penalty exposure or strategic value? The scheduler identifies the tradeoff; management decides. + +4. **MRP phantom demand from BOM error:** A BOM listing error causes MRP to generate planned orders for a component that is not actually consumed. The scheduler sees a work order with no real demand behind it. Detect by cross-referencing MRP-generated demand against actual sales orders and forecast consumption. Flag and hold — do not schedule phantom demand. + +5. **Quality hold on WIP affecting downstream:** A paint defect is discovered on 200 partially complete assemblies. These were scheduled to feed the final assembly constraint tomorrow. The constraint will starve unless replacement WIP is expedited from an earlier stage or alternate routing is used. + +6. **Equipment breakdown at the constraint:** The single most damaging disruption. Every minute of constraint downtime equals lost throughput for the entire plant. Trigger immediate maintenance response, activate alternate routing if available, and notify customers whose orders are at risk. + +7. **Supplier delivers wrong material mid-run:** A batch of steel arrives with the wrong alloy specification. Jobs already kitted with this material cannot proceed. Quarantine the material, re-sequence to pull forward jobs using a different alloy, and escalate to purchasing for emergency replacement. + +8. **Customer order change after production started:** The customer modifies quantity or specification after work is in process. Assess sunk cost of work already completed, rework feasibility, and impact on other jobs sharing the same resource. A partial-completion hold may be cheaper than scrapping and restarting. + +## Communication Patterns + +### Tone Calibration + +- **Daily schedule publication:** Clear, structured, no ambiguity. Job sequence, start times, line assignments, operator assignments. Use table format. The shop floor does not read paragraphs. +- **Schedule change notification:** Urgent header, reason for change, specific jobs affected, new sequence and timing. "Effective immediately" or "effective at [time]." +- **Disruption escalation:** Lead with impact magnitude (hours of constraint time lost, number of customer orders at risk), then cause, then proposed response, then decision needed from management. +- **Overtime request:** Quantify the business case — cost of overtime vs. cost of missed deliveries. Include union rule compliance. "Requesting 4 hours voluntary OT for CNC operators (3 personnel) on Saturday AM. Cost: $1,200. At-risk revenue without OT: $45,000." +- **Customer delivery impact notice:** Never surprise the customer. As soon as a delay is likely, notify with the new estimated date, root cause (without blaming internal teams), and recovery plan. "Due to an equipment issue, order #12345 will ship [new date] vs. the original [old date]. We are running overtime to minimise the delay." +- **Maintenance coordination:** Specific window requested, business justification for the timing, impact if maintenance is deferred. "Requesting PM window on Line 3, Tuesday 06:00–10:00. This avoids the Thursday changeover peak. Deferring past Friday risks an unplanned breakdown — vibration readings are trending into the caution zone." + +Brief templates above. Full versions with variables in [communication-templates.md](references/communication-templates.md). + +## Escalation Protocols + +### Automatic Escalation Triggers + +| Trigger | Action | Timeline | +| ------------------------------------------------------------------------- | -------------------------------------------------------------------------- | --------------------------------- | +| Constraint work centre down > 30 minutes unplanned | Alert production manager + maintenance manager | Immediate | +| Plan adherence drops below 80% for a shift | Root cause analysis with shift supervisor | Within 4 hours | +| Customer order projected to miss committed ship date | Notify sales and customer service with revised ETA | Within 2 hours of detection | +| Overtime requirement exceeds weekly budget by > 20% | Escalate to plant manager with cost-benefit analysis | Within 1 business day | +| OEE at constraint drops below 65% for 3 consecutive shifts | Trigger focused improvement event (maintenance + engineering + scheduling) | Within 1 week | +| Quality yield at constraint drops below 93% | Joint review with quality engineering | Within 24 hours | +| MRP-generated load exceeds finite capacity by > 15% for the upcoming week | Capacity meeting with planning and production management | 2 days before the overloaded week | + +### Escalation Chain + +Level 1 (Production Scheduler) → Level 2 (Production Manager / Shift Superintendent, 30 min for constraint issues, 4 hours for non-constraint) → Level 3 (Plant Manager, 2 hours for customer-impacting issues) → Level 4 (VP Operations, same day for multi-customer impact or safety-related schedule changes) + +## Performance Indicators + +Track per shift and trend weekly: + +| Metric | Target | Red Flag | +| ----------------------------------------------------- | ------------------ | -------------- | +| Schedule adherence (jobs started within ±1 hour) | > 90% | < 80% | +| On-time delivery (to customer commit date) | > 95% | < 90% | +| OEE at constraint | > 75% | < 65% | +| Changeover time vs. standard | < 110% of standard | > 130% | +| WIP days (total WIP value / daily COGS) | < 5 days | > 8 days | +| Constraint utilisation (actual producing / available) | > 85% | < 75% | +| First-pass yield at constraint | > 97% | < 93% | +| Unplanned downtime (% of scheduled time) | < 5% | > 10% | +| Labour utilisation (direct hours / available hours) | 80–90% | < 70% or > 95% | + +## Additional Resources + +- For detailed decision frameworks, scheduling algorithms, and optimisation methodologies, see [decision-frameworks.md](references/decision-frameworks.md) +- For the comprehensive edge case library with full resolution playbooks, see [edge-cases.md](references/edge-cases.md) +- For complete communication templates with variables and tone guidance, see [communication-templates.md](references/communication-templates.md) + +## When to Use + +Use this skill when you need to **design or adjust production schedules and constraint‑focused execution plans**: + +- Sequencing jobs, balancing lines, and optimising changeovers in discrete or batch manufacturing. +- Responding to disruptions (machine breakdowns, shortages, quality holds, absenteeism) while protecting the bottleneck and customer commitments. +- Building scheduling rules, KPIs, and communication patterns between planning, production, maintenance, and quality teams. diff --git a/web-app/public/skills/production-scheduling/references/communication-templates.md b/web-app/public/skills/production-scheduling/references/communication-templates.md new file mode 100644 index 00000000..827f6877 --- /dev/null +++ b/web-app/public/skills/production-scheduling/references/communication-templates.md @@ -0,0 +1,503 @@ +# Communication Templates — Production Scheduling + +> **Reference Type:** Tier 3 — Load on demand when composing or reviewing production scheduling communications. +> +> **Usage:** Each template includes variable placeholders in `{{double_braces}}` for direct substitution. Templates are organized by audience and purpose. Select the template matching your scenario, substitute variables, review tone guidance, and send. + +--- + +## Table of Contents + +1. [Production Schedule Publication](#1-production-schedule-publication) +2. [Schedule Change Notification](#2-schedule-change-notification) +3. [Disruption Alert](#3-disruption-alert) +4. [Overtime Request](#4-overtime-request) +5. [Customer Delivery Impact Notice](#5-customer-delivery-impact-notice) +6. [Maintenance Coordination Request](#6-maintenance-coordination-request) +7. [Quality Hold Notification](#7-quality-hold-notification) +8. [Capacity Constraint Escalation](#8-capacity-constraint-escalation) +9. [New Product Trial Run Request](#9-new-product-trial-run-request) +10. [Cross-Functional Priority Alignment](#10-cross-functional-priority-alignment) + +--- + +## Variable Reference + +Common variables used across templates: + +| Variable | Description | Example | +|---|---|---| +| `{{date}}` | Date of communication | `2025-09-15` | +| `{{shift}}` | Shift identifier | `Day Shift (06:00–14:00)` | +| `{{line_id}}` | Production line identifier | `Line 3 — CNC Machining Cell` | +| `{{work_order}}` | Work order number | `WO-2025-04823` | +| `{{product}}` | Product name/number | `Valve Body Assembly VB-220` | +| `{{customer}}` | Customer name | `Apex Automotive GmbH` | +| `{{customer_po}}` | Customer purchase order | `APX-PO-88412` | +| `{{qty}}` | Quantity | `500 units` | +| `{{due_date}}` | Customer due date | `2025-09-22` | +| `{{revised_date}}` | Revised delivery date | `2025-09-25` | +| `{{scheduler_name}}` | Scheduler name | `Dave Morrison` | +| `{{scheduler_title}}` | Scheduler title | `Senior Production Scheduler` | +| `{{scheduler_email}}` | Scheduler email | `d.morrison@mfgco.com` | +| `{{scheduler_phone}}` | Scheduler phone | `(513) 555-0147` | +| `{{plant}}` | Plant name/location | `Cincinnati Plant — Building 2` | +| `{{constraint_wc}}` | Constraint work centre | `CNC Horizontal Boring — WC 420` | +| `{{oee_value}}` | OEE percentage | `72%` | +| `{{downtime_hrs}}` | Downtime hours | `4.5 hours` | +| `{{changeover_time}}` | Changeover duration | `45 minutes` | +| `{{operator_name}}` | Operator name | `J. Rodriguez` | +| `{{supervisor_name}}` | Shift supervisor | `Karen Phillips` | +| `{{maintenance_lead}}` | Maintenance lead | `Tom Becker` | +| `{{quality_lead}}` | Quality lead | `Dr. Sarah Chen` | + +--- + +## 1. Production Schedule Publication + +**Audience:** Shift supervisors, operators, material handlers, quality inspectors +**Frequency:** Published at shift start; updated only if disruption requires re-sequencing +**Format:** Table-driven, no paragraphs. Shop floor reads tables, not prose. +**Delivery:** Printed and posted at each work centre + emailed to supervisors + displayed on MES screens + +--- + +**Subject:** Production Schedule — {{plant}} — {{shift}} — {{date}} + +**Schedule published by:** {{scheduler_name}} at {{date}} {{time}} + +**Priority Legend:** 🔴 Past-due or critical | 🟡 At risk (CR < 1.0) | 🟢 On schedule + +| Seq | Work Order | Product | Qty | Start Time | End Time | Work Centre | Operator | Priority | Notes | +|---|---|---|---|---|---|---|---|---|---| +| 1 | {{work_order}} | {{product}} | {{qty}} | 06:00 | 08:30 | {{line_id}} | {{operator_name}} | 🔴 | Rush — customer line-down | +| 2 | WO-2025-04824 | Housing H-340 | 200 | 08:45 | 11:15 | {{line_id}} | {{operator_name}} | 🟢 | Std changeover at 08:30 | +| 3 | WO-2025-04826 | Bracket BR-110 | 350 | 11:30 | 14:00 | {{line_id}} | {{operator_name}} | 🟡 | Material confirm by 10:00 | + +**Changeover Summary:** +- 08:30–08:45: Changeover WO-04823 → WO-04824 (tooling pre-staged at machine) +- 11:15–11:30: Changeover WO-04824 → WO-04826 (fixture change, 15 min) + +**Material Status:** +- WO-04823: All material staged ✅ +- WO-04824: All material staged ✅ +- WO-04826: Bracket raw material pending — confirm with stores by 10:00 ⚠️ + +**Labour Notes:** +- {{operator_name}} certified on all three jobs +- Relief operator for 10:00 break: M. Thompson + +**Constraint Status:** {{constraint_wc}} — current OEE {{oee_value}}. Buffer status: GREEN. + +**Do not deviate from this sequence without scheduler approval.** + +--- + +**Tone guidance:** Directive, not conversational. The schedule is an instruction, not a suggestion. Use clear times, no approximations. Flag risks with symbols that are visible at a glance. Include material and labour status because the most common schedule disruption is "I didn't have the material" or "nobody told me I was on this job." + +--- + +## 2. Schedule Change Notification + +**Audience:** Shift supervisors, affected operators, material handlers +**Trigger:** Any change to the published schedule during the frozen zone +**Delivery:** In-person verbal confirmation + written (posted + emailed) + +--- + +**Subject:** ⚠️ SCHEDULE CHANGE — {{line_id}} — Effective {{effective_time}} + +**Change issued by:** {{scheduler_name}} at {{date}} {{time}} +**Approved by:** {{supervisor_name}} (Production Manager approval required for frozen-zone changes) + +**Reason for change:** {{change_reason}} + +**What changed:** + +| | Before | After | +|---|---|---| +| Job sequence at {{line_id}} | WO-04824 → WO-04826 | WO-04826 → WO-04824 | +| WO-04826 start time | 11:30 | 08:45 | +| WO-04824 start time | 08:45 | 11:30 | +| Changeover | Tooling → Fixture (15 min) | Fixture → Tooling (20 min) | + +**Why:** {{detailed_reason}} — e.g., "WO-04826 material (bracket raw stock) arrived early. WO-04826 due date is 1 day earlier than WO-04824. Swapping sequence saves 5 minutes of changeover time and improves on-time delivery for both orders." + +**Impact on other work centres:** None — downstream operations unaffected. + +**Action required:** +- Material handler: Re-stage WO-04826 material at {{line_id}} by 08:30. +- Operator: Confirm fixture change procedure for WO-04826 with setup technician. + +**No further changes to this shift's schedule unless a new disruption occurs.** + +--- + +**Tone guidance:** Authoritative but explanatory. The "why" is important because frequent unexplained changes erode shop floor trust in the schedule. Always include who approved the change (accountability). End with a stability commitment — "no further changes" — to prevent the shop floor from anticipating constant flux. + +--- + +## 3. Disruption Alert + +**Audience:** Production manager, maintenance manager, shift supervisors, planning +**Trigger:** Any unplanned event affecting the constraint or customer deliveries +**Delivery:** Immediate — phone/radio for constraint events, email for non-constraint + +--- + +**Subject:** 🔴 DISRUPTION ALERT — {{disruption_type}} at {{line_id}} — {{date}} {{time}} + +**Reported by:** {{scheduler_name}} +**Severity:** {{severity}} (Critical / Major / Minor) + +**What happened:** +{{disruption_description}} +Example: "Hydraulic pump failure on CNC Horizontal Boring Mill (WC 420) at 09:15. Machine stopped mid-cycle on WO-04823 (defence contract valve body, $38,000 piece in machine). Maintenance assessment: pump replacement required, 6–8 hour repair estimated." + +**Impact:** +- **Constraint affected:** Yes / No +- **Estimated downtime:** {{downtime_hrs}} +- **Throughput loss:** {{throughput_loss}} (e.g., "$4,800 — 6 hours × $800/hr constraint throughput") +- **Customer orders at risk:** {{at_risk_orders}} (e.g., "3 orders totalling $220,000, due dates within 2 weeks") +- **Current buffer status:** {{buffer_status}} (e.g., "Buffer was GREEN, will reach RED in 4 hours if not resolved") + +**Immediate actions taken:** +1. Machine isolated. Maintenance on-site. +2. Replacement pump ordered from OEM distributor — ETA {{pump_eta}}. +3. In-machine part assessed: datum offsets preserved, part likely salvageable on restart. +4. Queued jobs reviewed for alternate routing — 3 of 14 can run on vertical CNC. + +**Decision needed from management:** +- Authorise Saturday overtime (8 hours, estimated cost ${{overtime_cost}}) to recover lost capacity? Y/N +- Approve subcontracting for {{subcontract_jobs}} to external shop (cost ${{subcontract_cost}})? Y/N +- Customer notification: approve revised delivery dates for {{at_risk_customers}}? Y/N + +**Next update:** {{next_update_time}} or when repair status changes. + +--- + +**Tone guidance:** Lead with impact, not description. The production manager needs to know "how bad is this?" before "what exactly happened." Quantify everything in hours and dollars. Present decisions as explicit Y/N choices — do not leave it ambiguous. Set a next-update cadence so management isn't chasing you for information. + +--- + +## 4. Overtime Request + +**Audience:** Production manager (approval), HR/payroll (processing), affected operators +**Trigger:** Capacity shortfall that can be recovered with additional hours +**Delivery:** Email with formal cost justification; verbal pre-approval for urgency + +--- + +**Subject:** Overtime Request — {{line_id}} — {{date_range}} + +**Requested by:** {{scheduler_name}} +**Date of request:** {{date}} + +**Business justification:** +{{business_case}} +Example: "Constraint work centre (CNC Boring, WC 420) lost 20 hours due to unplanned hydraulic failure on 9/15. Recovery requires Saturday overtime shift to process queued customer orders and prevent 3 delivery misses totalling $220,000 in at-risk revenue." + +**Overtime details:** + +| Item | Detail | +|---|---| +| Work centre | {{constraint_wc}} | +| Date(s) | {{overtime_dates}} (e.g., Saturday 9/20, 06:00–14:00) | +| Duration | {{overtime_hours}} hours | +| Personnel required | {{personnel_count}} (e.g., 2 CNC operators + 1 setup tech) | +| Personnel names | {{personnel_names}} (voluntary — confirmed availability) | +| Estimated cost | ${{overtime_cost}} ({{hours}} hrs × ${{rate}}/hr × {{multiplier}} OT premium) | +| Union compliance | ✅ Voluntary. Offered by seniority per CBA Article 14.3. 8-hour rest observed. | + +**Revenue at risk without overtime:** ${{revenue_at_risk}} +**Cost-to-benefit ratio:** {{ratio}} (e.g., "$1,200 OT cost to protect $220,000 revenue = 183:1 ROI") + +**Orders recovered with overtime:** + +| Work Order | Customer | Due Date | Status Without OT | Status With OT | +|---|---|---|---|---| +| WO-04825 | {{customer}} | {{due_date}} | 2 days late | On time | +| WO-04827 | Nexus Defense | 9/26 | 1 day late | On time | +| WO-04829 | Summit Aero | 9/28 | On time (barely) | Comfortable margin | + +**Approval requested by:** {{approval_deadline}} (e.g., "Thursday 5:00 PM to allow operator notification per CBA 48-hour notice requirement") + +--- + +**Tone guidance:** Treat overtime requests as business cases, not pleas. Quantify both the cost and the benefit. Include union compliance confirmation proactively — the production manager should not have to ask. Provide the approval deadline because overtime notification requirements are contractual, not flexible. + +--- + +## 5. Customer Delivery Impact Notice + +**Audience:** Sales/account manager (internal), then customer +**Trigger:** Any order projected to miss its committed delivery date +**Delivery:** Internal first (email + phone to account manager), then customer (via account manager or directly) + +--- + +**Internal Version (to Sales/Account Manager):** + +**Subject:** Delivery Impact — {{customer}} — Order {{customer_po}} — Revised ETA {{revised_date}} + +**From:** {{scheduler_name}}, Production Scheduling +**Date:** {{date}} + +**Summary:** +Order {{customer_po}} for {{customer}} ({{qty}} of {{product}}, original commit date {{due_date}}) will ship {{delay_days}} days late. Revised delivery date: {{revised_date}}. + +**Root cause:** {{root_cause_internal}} +Example: "Unplanned constraint downtime on 9/15 (hydraulic failure, 20 hours lost) consumed the schedule buffer. Recovery overtime approved but insufficient to fully close the gap for all affected orders." + +**Recovery actions in progress:** +- Saturday overtime shift authorised (recovers 8 hours) +- 3 lower-priority jobs subcontracted to reduce constraint queue (recovers 6 hours) +- Remaining gap: 6 hours, which pushes {{customer_po}} delivery from {{due_date}} to {{revised_date}} + +**Contractual exposure:** {{penalty_info}} +Example: "Customer A framework agreement includes $25,000/day late delivery penalty. 3-day delay = $75,000 exposure. Recommend proactive notification and negotiation." + +**Recommended customer message:** See external version below. Please review and send by {{notification_deadline}}, or let me know if you'd like to adjust the messaging. + +--- + +**External Version (to Customer):** + +**Subject:** Delivery Update — Order {{customer_po}} + +Dear {{customer_contact}}, + +I am writing to update you on the delivery timeline for your order {{customer_po}} ({{qty}} of {{product}}). + +Due to {{root_cause_external}} (e.g., "an equipment issue at our machining facility"), we are revising the delivery date from {{due_date}} to {{revised_date}}. + +We have taken the following actions to minimise the delay: +- Authorised additional production shifts dedicated to your order +- Re-prioritised your order to the front of the production queue +- Assigned our senior machining team to ensure quality and speed + +We understand the impact this may have on your operations and sincerely regret the inconvenience. If the revised date presents difficulties, please let us know and we will explore every option to accelerate further. + +{{scheduler_name}} is available at {{scheduler_phone}} for any questions about the production status. + +Regards, +{{account_manager_name}} +{{account_manager_title}} +{{our_company}} + +--- + +**Tone guidance — internal:** Factual, quantified, includes penalty exposure. The account manager needs the full picture to make the right call on messaging. + +**Tone guidance — external:** Proactive (before the customer discovers the delay), accountable (acknowledge the impact), action-oriented (show what you're doing), no blame (do not name internal equipment or personnel). Never use "we apologise for any inconvenience" — that phrase signals insincerity. Instead, acknowledge the specific impact on their operations. + +--- + +## 6. Maintenance Coordination Request + +**Audience:** Maintenance manager/planner +**Trigger:** Scheduling a preventive maintenance window, or requesting priority on corrective maintenance +**Delivery:** Email + calendar invite for planned; phone/radio + email for urgent + +--- + +**Subject:** Maintenance Window Request — {{line_id}} — {{requested_date_range}} + +**From:** {{scheduler_name}}, Production Scheduling +**Date:** {{date}} + +**Request type:** Preventive Maintenance / Corrective Maintenance / Calibration + +**Equipment:** {{equipment_id}} (e.g., "600-ton Stamping Press #2, Asset Tag SP-602") +**Work centre:** {{constraint_wc}} + +**Requested window:** {{pm_start}} to {{pm_end}} (e.g., "Saturday 9/20, 06:00–16:00, 10 hours") + +**Business justification for this timing:** +{{timing_justification}} +Example: "Saturday window avoids impacting the Week 39 production plan, which is loaded at 94% Mon–Fri. Vibration readings on SP-602 are trending into the caution zone (0.28 in/s, threshold is 0.30). Deferring beyond Saturday increases the risk of an unplanned breakdown during the peak Monday–Wednesday production window." + +**Impact if deferred:** +- Probability of unplanned failure in next 2 weeks: {{failure_probability}} (e.g., "estimated 35% based on vibration trend and historical MTBF data") +- Cost of unplanned failure: {{failure_cost}} (e.g., "$16,000 lost throughput + $5,000 emergency repair + potential die damage") +- Production orders at risk: {{at_risk_orders}} + +**Production impact of performing the PM:** +- Lost production during the PM window: {{lost_production}} (e.g., "0 — Saturday is non-scheduled overtime; if OT was planned, 8 hours of production displaced") +- Recovery plan: {{recovery_plan}} (e.g., "displaced OT production moved to Friday evening shift extension") + +**Coordination requirements:** +- Maintenance personnel: {{maintenance_personnel}} (e.g., "1 millwright + 1 electrician, 10 hours each") +- Parts/materials: {{parts_needed}} (e.g., "hydraulic seal kit #HS-602-A, confirm available in stores") +- Production support: {{production_support}} (e.g., "Operator needed for first 2 hours to assist with die removal and last 1 hour for test run") + +--- + +**Tone guidance:** Collaborative, not adversarial. Scheduling and maintenance are allies, not opponents. Provide the business case for the timing (so maintenance understands why this window matters) and the risk assessment for deferral (so maintenance can prioritise appropriately). Include all logistics so maintenance can plan their work order without back-and-forth. + +--- + +## 7. Quality Hold Notification + +**Audience:** Quality manager, production manager, affected work centre supervisors, planning +**Trigger:** In-process quality issue requiring quarantine of WIP +**Delivery:** Immediate email + verbal to quality and production managers + +--- + +**Subject:** 🔴 QUALITY HOLD — {{product}} — Batch {{batch_id}} — {{qty_affected}} units + +**Issued by:** {{scheduler_name}} in coordination with {{quality_lead}} +**Date/Time:** {{date}} {{time}} + +**Defect summary:** {{defect_description}} +Example: "Dimensional defect on stamped chassis frames — hole pattern shifted 2mm from specification due to suspected die wear. Discovered at weld inspection station." + +**Scope of hold:** + +| Production Stage | Quantity Affected | Location | Status | +|---|---|---|---| +| Stamping (completed) | 80 units | Welding station queue | QUARANTINED | +| Welding (completed) | 60 units | Paint queue staging | QUARANTINED | +| Paint (completed) | 60 units | Final assembly staging | QUARANTINED | +| **Total** | **200 units** | | | + +**Customer impact:** +- Customer: {{customer}} +- Order: {{customer_po}}, {{qty}} units due {{due_date}} +- 60 painted frames were scheduled to feed final assembly (constraint) starting {{date}}. +- Constraint will be short material for {{impact_duration}} unless rework or replacement is expedited. + +**Schedule impact:** +- Final assembly (constraint) schedule revised: {{revised_schedule_summary}} +- Alternate work pulled forward to keep constraint running: {{alternate_work}} +- Estimated delivery impact: {{delivery_impact}} + +**Disposition pending from Quality:** +- Rework feasibility assessment requested by {{rework_assessment_deadline}} +- If reworkable: estimated rework time = {{rework_time}} per unit +- If not reworkable: replacement production order required — estimated lead time {{replacement_lead_time}} + +**Immediate actions taken:** +1. All affected WIP physically segregated and tagged +2. Die #{{die_number}} removed from service for inspection +3. Production schedule revised — constraint fed from alternate work orders +4. Customer notification drafted (pending quality disposition) + +--- + +## 8. Capacity Constraint Escalation + +**Audience:** Plant manager, planning manager, production manager +**Trigger:** MRP-generated load exceeds finite capacity by >15% for the upcoming week +**Delivery:** Email with supporting data, presented at weekly S&OP or production meeting + +--- + +**Subject:** Capacity Overload Alert — {{constraint_wc}} — Week {{week_number}} + +**From:** {{scheduler_name}}, Production Scheduling +**Date:** {{date}} + +**Summary:** +MRP-generated load for {{constraint_wc}} in Week {{week_number}} exceeds available capacity by {{overload_pct}}%. Without intervention, {{overload_hours}} hours of work cannot be scheduled, affecting {{affected_orders}} customer orders. + +**Capacity analysis:** + +| Item | Hours | +|---|---| +| Available capacity ({{shifts}} shifts × {{hours_per_shift}} hrs, less {{pm_hours}} hrs planned maintenance) | {{available_hours}} | +| MRP-required load | {{required_hours}} | +| Overload | {{overload_hours}} ({{overload_pct}}%) | + +**Options for resolution:** + +| Option | Capacity Recovered | Cost | Risk | Recommendation | +|---|---|---|---|---| +| Saturday overtime (1 shift) | {{ot_hours}} hrs | ${{ot_cost}} | Low — voluntary OT available | ✅ Recommended | +| Defer {{defer_count}} lower-priority orders to Week {{week_number + 1}} | {{defer_hours}} hrs | $0 | Medium — delivery impact on deferred orders | Acceptable if customers agree | +| Subcontract {{subcontract_ops}} | {{subcontract_hours}} hrs | ${{subcontract_cost}} | Medium — quality and lead time | Last resort | +| Reduce constraint changeovers (campaign scheduling) | {{co_hours}} hrs | $0 | Low — requires schedule restructuring | ✅ Recommended in combination | + +**Recommended plan:** Combine overtime ({{ot_hours}} hrs) + changeover reduction ({{co_hours}} hrs) to close the gap. Total gap closed: {{total_recovered}} hrs. Remaining gap: {{remaining_gap}} hrs — address by deferring {{defer_count}} Tier-3 orders with customer agreement. + +**Decision needed by:** {{decision_deadline}} (to allow operator notification and material staging) + +--- + +## 9. New Product Trial Run Request + +**Audience:** Production manager, engineering, quality, scheduling +**Trigger:** NPI (new product introduction) requiring constraint time for trial runs +**Delivery:** Email with formal request; presented at production planning meeting + +--- + +**Subject:** NPI Trial Run Request — {{npi_product}} — {{requested_dates}} + +**From:** {{scheduler_name}} in coordination with {{engineering_lead}} + +**Product:** {{npi_product}} (e.g., "EV Battery Enclosure — Part #BE-4400") +**Customer:** {{customer}} +**Qualification deadline:** {{qualification_deadline}} + +**Trial run requirements:** + +| Trial # | Date | Constraint Time (nominal) | Buffered Time (planned) | Changeover | Total Window | +|---|---|---|---|---|---| +| 1 | {{trial_1_date}} | 8 hrs | 14 hrs | 4 hrs | 18 hrs | +| 2 | {{trial_2_date}} | 8 hrs | 12 hrs | 4 hrs | 16 hrs | +| 3 | {{trial_3_date}} | 8 hrs | 10 hrs | 2 hrs | 12 hrs | + +**Capacity impact:** +- Current constraint utilisation: {{current_util}}% +- With NPI trials: {{projected_util}}% +- Buffer reduction: constraint buffer shrinks from {{current_buffer}} hrs to {{projected_buffer}} hrs per week + +**Proposed scheduling approach:** +- Schedule trials on Friday PM / Saturday AM to contain overrun risk +- {{buffer_hours}} hrs/week reserved as "trial buffer" — converts to regular production if trial is cancelled or completes early +- Existing customer commitments are not moved to accommodate trials + +**Risk mitigation:** +- Most experienced setup technician assigned to all trials +- First-article inspection protocol defined with quality +- Trial time estimates will be updated after each run for the next trial + +**Approval required from:** Production Manager (capacity impact) + Quality (trial protocol) + Engineering (trial plan) + +--- + +## 10. Cross-Functional Priority Alignment + +**Audience:** Sales, planning, production, quality, finance +**Trigger:** Competing priorities require alignment (quarterly or when significant conflicts arise) +**Delivery:** Presented at S&OP meeting with supporting data + +--- + +**Subject:** Priority Alignment Request — Week {{week_number}} / Month {{month}} + +**From:** {{scheduler_name}}, Production Scheduling + +**Issue:** +The current production plan contains conflicting priorities that cannot be resolved within available capacity. Scheduling has identified {{conflict_count}} conflicts requiring cross-functional alignment. + +**Conflict summary:** + +| # | Conflict | Departments Involved | Scheduler's Assessment | +|---|---|---|---| +| 1 | Customer A rush order vs. Customer B committed delivery — both need CNC constraint, 16-hour gap | Sales + Production | Need commercial decision: which customer takes priority? | +| 2 | NPI trial run vs. production schedule — trial requires 14 hrs of constraint time in a week loaded at 94% | Engineering + Production | Recommend scheduling trial on Saturday to avoid displacement | +| 3 | Maintenance PM window vs. peak production week — PM deferred twice already | Maintenance + Production | Recommend executing PM this week; deferral risk exceeds production value of the PM window | + +**For each conflict, scheduling needs:** +1. A single, clear priority decision +2. Written confirmation (email or meeting minutes) that the decision is endorsed by all affected departments +3. Decision by {{decision_deadline}} so the schedule can be locked for the week + +**Scheduling will execute whatever priority is agreed. We are not requesting a specific outcome — we are requesting clarity so the schedule can be built without ambiguity.** + +--- + +**Tone guidance:** Neutral facilitator, not advocate. The scheduler's role in priority alignment is to surface conflicts, quantify tradeoffs, and execute decisions — not to make commercial or strategic calls. Make it clear that you need a decision, not a discussion. Provide the data that enables the decision. diff --git a/web-app/public/skills/production-scheduling/references/decision-frameworks.md b/web-app/public/skills/production-scheduling/references/decision-frameworks.md new file mode 100644 index 00000000..7be6e5f2 --- /dev/null +++ b/web-app/public/skills/production-scheduling/references/decision-frameworks.md @@ -0,0 +1,867 @@ +# Decision Frameworks — Production Scheduling + +This reference provides the detailed decision logic, scheduling algorithms, optimisation +methodologies, and capacity planning techniques for production scheduling in discrete +and batch manufacturing. It is loaded on demand when the agent needs to make or recommend +nuanced scheduling decisions. + +All thresholds, formulas, and time assumptions reflect discrete and batch manufacturing +operations running 3–8 production lines with 50–300 direct-labour headcount per shift. + +--- + +## 1. Job Scheduling Algorithms + +### 1.1 Dispatching Rules — When to Use Each + +Dispatching rules are heuristics applied at a work centre when multiple jobs compete for +the same resource. No single rule dominates in all situations. The choice depends on the +plant's primary performance objective. + +| Rule | Definition | Best For | Weakness | +|---|---|---|---| +| **SPT (Shortest Processing Time)** | Process the job with the shortest operation time first | Minimising average flow time, reducing WIP, maximising throughput when setup times are negligible | Starves long jobs — a job with 8-hour run time waits behind twenty 20-minute jobs. Creates due date violations on long-cycle products. | +| **EDD (Earliest Due Date)** | Process the job with the earliest due date first | Minimising maximum lateness across all jobs, meeting delivery commitments | Ignores processing time — a job due tomorrow with an 8-hour run time gets priority over a job due in 2 hours with a 5-minute run. Can increase WIP if many jobs have distant due dates. | +| **Critical Ratio (CR)** | CR = (Due Date − Now) / Remaining Processing Time. Schedule lowest CR first. | Balancing due date urgency with remaining work. CR < 1.0 means the job is behind schedule. | Breaks down when due dates are unrealistic (all CRs < 0.5). Requires accurate remaining processing time estimates. | +| **Weighted Shortest Job First (WSJF)** | Priority = (Cost of Delay × Job Weight) / Processing Time. Schedule highest priority first. | Environments where jobs have different economic value. Maximises throughput-weighted value. | Requires reliable cost-of-delay estimates, which are often subjective. Can starve low-value long jobs indefinitely. | +| **Slack Time (ST)** | Slack = Due Date − Now − Remaining Processing Time. Schedule lowest slack first. | Similar to CR but uses absolute slack rather than ratio. Better when processing times are similar. | Same as CR — degrades with unrealistic due dates. Does not account for queue time at downstream work centres. | +| **FIFO (First In, First Out)** | Process jobs in arrival order at the work centre | Ensuring fairness, simple to communicate, works in stable environments with predictable flow | No optimisation — ignores due dates, processing times, and economic value. Use only when all jobs are equal priority and flow is balanced. | + +#### Algorithm Selection Decision Tree + +1. **Is schedule adherence the primary KPI and are there contractual delivery penalties?** + → Use EDD as the primary rule. Insert CR checks for jobs where CR < 0.8 — these need + immediate attention regardless of EDD rank. + +2. **Is throughput/output the primary KPI with flexible delivery windows?** + → Use SPT to minimise average flow time. Monitor maximum lateness; if it exceeds + the acceptable threshold, switch to a hybrid SPT-EDD (SPT within a due date window). + +3. **Do jobs have significantly different economic values (margin, penalty, customer tier)?** + → Use WSJF. Weight = customer tier multiplier × margin contribution. This is the + appropriate rule for job shops with heterogeneous order portfolios. + +4. **Are setup times sequence-dependent and significant (>15 minutes between families)?** + → No pure dispatching rule handles this. Use a setup-aware scheduling heuristic + (Section 2) that groups jobs by setup family and optimises within groups using EDD. + +5. **Is the environment stable with balanced flow and predictable demand?** + → FIFO is acceptable and preferred for its simplicity and shop floor trust. + +### 1.2 Multi-Rule Hybrid Approaches + +In practice, most schedulers use a hybrid approach layered as follows: + +**Layer 1 — Hard Constraints (filter)** +Remove any job from the queue that lacks material, tooling, or a qualified operator. +These jobs are not schedulable regardless of priority. + +**Layer 2 — Urgency Override (force-rank)** +Jobs with CR < 0.8 or that are already past-due are force-ranked to the top, +ordered by customer penalty exposure descending. + +**Layer 3 — Primary Dispatching Rule (sort remaining)** +Apply the selected dispatching rule (EDD, SPT, WSJF, etc.) to remaining jobs. + +**Layer 4 — Setup Optimisation (local reorder)** +Within the primary sequence, perform adjacent-swap improvements to reduce +total setup time, subject to the constraint that no swap causes a due date +violation for either swapped job. + +**Layer 5 — Labour Levelling (validate)** +Check that the resulting sequence does not create labour peaks that exceed +available headcount for any hour of the shift. If it does, defer the lowest- +priority job creating the peak to the next available slot. + +### 1.3 Critical Ratio in Detail + +Critical Ratio is the most versatile single dispatching rule for mixed environments. + +**Formula:** +``` +CR = (Due Date − Current Date) / Remaining Total Processing Time +``` + +Where Remaining Total Processing Time includes: +- Setup time for the current operation +- Run time for the current operation +- Queue time estimates for remaining operations (use historical average queue times) +- Setup + run times for all remaining operations in the routing + +**Interpretation:** +| CR Value | Meaning | Action | +|---|---|---| +| CR > 2.0 | Comfortable lead — job is well ahead of schedule | Lowest priority. May be deferred if capacity is needed for tighter jobs. | +| 1.0 < CR < 2.0 | On track but limited slack | Schedule normally per dispatching rule | +| CR = 1.0 | Exactly on schedule — no slack remaining | Monitor closely. Any disruption will cause lateness. | +| 0.5 < CR < 1.0 | Behind schedule — will be late without intervention | Escalate. Consider overtime, alternate routing, or partial shipment. | +| CR < 0.5 | Critically late — recovery is unlikely without significant intervention | Immediate escalation to production manager. Notify customer of revised date. | + +**Updating CR:** Recalculate CR at every operation completion and at the start of every +shift. A job with CR = 1.5 at shift start that encounters a 4-hour unplanned delay mid-shift +may drop to CR = 0.7 — the shift supervisor needs to know this in real time. + +### 1.4 Weighted Scheduling for Customer Tiers + +Manufacturing plants serving multiple customer tiers need a weighting system: + +| Customer Tier | Weight Multiplier | Rationale | +|---|---|---| +| Tier 1 (OEM, contractual penalties) | 3.0 | Late delivery triggers financial penalties, production line-down claims | +| Tier 2 (Key accounts, framework agreements) | 2.0 | No contractual penalty but relationship value and reorder risk | +| Tier 3 (Standard accounts) | 1.0 | Standard terms, no penalty | +| Tier 4 (Spot orders, distributors) | 0.5 | Price-sensitive, low switching cost for them | + +**WSJF with Customer Tier:** +``` +Priority Score = (Customer Tier Weight × Days Until Due / Remaining Processing Time) +``` +Lower score = higher priority (more urgent). Negative scores = past-due. + +--- + +## 2. Changeover Optimisation + +### 2.1 SMED Implementation Phases — Step by Step + +#### Phase 0 — Document the Current State (2–4 weeks) + +1. Video-record 3–5 changeovers on the target machine/line. Include the full duration + from last good piece of the outgoing product to first good piece of the incoming product. +2. Create a changeover element sheet listing every task performed, the performer + (operator, setup tech, maintenance), the duration, and whether the machine was stopped. +3. Categorize each element: + - **Internal (IED):** Must be performed with the machine stopped. + - **External (OED):** Can be performed while the machine is still running. + - **Waste:** Not necessary at all — holdover from old procedures, redundant checks, waiting. + +Typical finding: 30–50% of changeover time is either external work incorrectly performed +during machine stoppage, or pure waste (searching for tools, waiting for approval, +walking to the tool crib). + +#### Phase 1 — Separate Internal and External (2–4 weeks) + +1. Move all external elements to pre-changeover preparation: + - Pre-stage next-job tooling, dies, fixtures at the machine before the changeover begins. + - Pre-mix materials, pre-heat moulds, pre-program CNC settings. + - Pre-print work order documentation and quality checklists. +2. Create a standardised changeover preparation checklist. The setup technician begins + executing it 30–60 minutes before the scheduled changeover time. +3. Expected result: 25–40% reduction in machine-stopped time with no capital investment. + +#### Phase 2 — Convert Internal to External (4–8 weeks) + +1. Standardise die/fixture heights and mounting interfaces so that alignment and adjustment + happen before the die reaches the machine, not after. +2. Implement intermediate jigs — set up the next tool in a staging fixture that mirrors + the machine's mounting interface. When the changeover begins, the pre-assembled unit + drops in with minimal adjustment. +3. Pre-condition materials: if the incoming product requires a different temperature, + viscosity, or chemical mix, start conditioning in a parallel vessel. +4. Expected result: additional 15–25% reduction in machine-stopped time. May require + modest investment in duplicate tooling or staging fixtures. + +#### Phase 3 — Streamline Remaining Internal Elements (4–12 weeks) + +1. Replace bolt-on fasteners with quick-release clamps, cam locks, or hydraulic clamping. + Every bolt removed saves 15–30 seconds. +2. Eliminate adjustments through poka-yoke: centre pins, guide rails, fixed stops that + guarantee first-piece alignment without trial-and-error. +3. Standardise utility connections: colour-coded quick-disconnect fittings for air, water, + hydraulic, and electrical. One-motion connect/disconnect. +4. Parallel operations: two people working simultaneously on different sides of the machine + can halve the internal time. Requires choreographed procedures and safety protocols. +5. Expected result: additional 10–20% reduction. Often requires capital investment in + quick-change tooling. + +#### Phase 4 — Eliminate Adjustments and Verify (ongoing) + +1. Implement first-piece verification jigs that confirm dimensions without full inspection. +2. Use statistical process control (SPC) from the first piece — if the first piece is within + control limits, the changeover is validated without a trial run. +3. Document the final standardised changeover procedure with photos, time targets per element, + and a sign-off sheet. +4. Target: changeover time under 10 minutes (single-minute exchange of die) for the + machine-stopped portion. + +### 2.2 Sequence-Dependent Setup Matrices + +For operations where setup time varies by product-to-product transition, build a +setup time matrix: + +**Example — Paint Line Setup Matrix (minutes):** + +| From \ To | White | Yellow | Orange | Red | Blue | Black | +|---|---|---|---|---|---|---| +| **White** | 0 | 8 | 10 | 15 | 20 | 25 | +| **Yellow** | 15 | 0 | 8 | 12 | 20 | 25 | +| **Orange** | 20 | 12 | 0 | 8 | 18 | 22 | +| **Red** | 25 | 18 | 12 | 0 | 15 | 18 | +| **Blue** | 20 | 22 | 20 | 18 | 0 | 10 | +| **Black** | 30 | 28 | 25 | 22 | 12 | 0 | + +**Observations from this matrix:** +- Light-to-dark transitions (White → Black: 25 min) are cheaper than dark-to-light (Black → White: 30 min). +- Within colour families, transitions are minimal (Red → Orange: 12 min vs. Red → White: 25 min). +- The optimal sequence for all six colours in a campaign would be: White → Yellow → Orange → Red → Blue → Black (total: 8+8+8+15+10 = 49 min) vs. random sequence averaging 17 min per transition (85 min total). + +**Using the matrix in scheduling:** +1. Group jobs by colour family when possible (campaign scheduling within families). +2. When inter-family transitions are required, optimise the transition sequence using the + nearest-neighbour heuristic, then improve with 2-opt swaps. +3. If a specific colour is due earliest but the optimal setup sequence would delay it, + compute the cost of the suboptimal sequence (extra setup minutes × constraint hourly rate) + vs. the cost of late delivery. Choose the lower-cost option. + +### 2.3 Campaign Length Optimisation + +**Economic Production Quantity (EPQ):** +``` +EPQ = √((2 × D × S) / (H × (1 − D/P))) +``` +Where: +- D = demand rate (units per period) +- S = setup cost per changeover (labour + scrap + lost output opportunity cost) +- H = holding cost per unit per period +- P = production rate (units per period), P > D + +**Practical adjustments:** +- Round EPQ up to the nearest full shift or full batch to avoid mid-shift changeovers. +- If EPQ results in WIP that exceeds available staging space, constrain to physical capacity. +- If EPQ results in a campaign longer than the longest customer lead time tolerance, + shorten it to maintain responsiveness even at higher changeover frequency. + +**Campaign vs. mixed-model decision:** + +| Factor | Favours Campaign | Favours Mixed-Model | +|---|---|---| +| Setup time | Long (>60 min) | Short (<15 min) | +| Setup cost | High (>$500 per changeover) | Low (<$100 per changeover) | +| Demand variability | Low (stable, forecastable) | High (volatile, order-driven) | +| Customer lead time expectation | Tolerant (>2 weeks) | Tight (<3 days) | +| WIP carrying cost | Low | High | +| Product shelf life | Long or N/A | Short or regulated | +| Number of product variants | Few (<10) | Many (>50) | + +--- + +## 3. Theory of Constraints (TOC) Implementation + +### 3.1 Drum-Buffer-Rope — Step by Step + +**Step 1: Identify the Constraint** + +Run a capacity analysis for each work centre over the next planning horizon (1–4 weeks): + +``` +Utilisation = Σ(Setup Time + Run Time for all scheduled jobs) / Available Time +``` + +Available Time = shift hours × number of machines × (1 − planned maintenance %) + +The work centre with the highest utilisation ratio is the drum. If multiple work centres +exceed 90% utilisation, the one with the least flexibility (fewest alternate routings, +most specialised equipment) is the primary constraint. + +**Validation test:** If you could add 10% more capacity to the suspected constraint +(one more machine, one more shift hour, or a 10% speed increase), would total plant +output increase by approximately 10%? If yes, it is the true constraint. If output +increases less (because a second work centre immediately becomes the bottleneck), +you have an interactive constraint pair that requires different treatment. + +**Step 2: Exploit the Constraint** + +Maximise the output of the constraint with no capital investment: + +1. **Eliminate idle time:** The constraint should never wait for material, tooling, + operators, quality inspection, or information. Pre-stage everything. +2. **Minimise changeovers on the constraint:** Move changeover to non-constraint + resources where the time cost is lower. If the constraint must change over, + ensure SMED discipline is applied rigorously. +3. **Prevent quality defects reaching the constraint:** Inspect before the constraint + operation, not after. Every defective piece processed at the constraint is wasted + constraint capacity. +4. **Run through breaks and shift changes:** Stagger operator lunches so the constraint + never stops for a break. Assign a relief operator. +5. **Eliminate micro-stops:** Address every source of 1–5 minute stoppages (sensor trips, + material jams, tool wear alarms) that individually seem trivial but cumulatively steal + 2–5% of capacity. + +**Step 3: Subordinate Everything to the Constraint** + +1. **Upstream work centres:** Release work to upstream operations only at the rate the + constraint can consume it. This is the "rope." If the constraint processes 100 units/hour, + the upstream release rate should not exceed 100 units/hour regardless of upstream capacity. +2. **Downstream work centres:** Must maintain enough sprint capacity to clear constraint + output without becoming a secondary bottleneck. If the constraint produces a batch every + 2 hours, downstream must be able to process that batch within 2 hours. +3. **Scheduling non-constraints:** Do not optimise non-constraint schedules in isolation. + A non-constraint running at 100% utilisation when the constraint runs at 85% is producing + excess WIP that clogs the shop floor and slows the constraint's material flow. + +**Step 4: Establish the Buffer** + +The constraint buffer is a time buffer, not an inventory buffer: + +``` +Buffer Duration = Planned Lead Time from release to constraint × Buffer Factor +``` + +Typical buffer factors: +- Stable, reliable upstream operations: 0.3 × lead time +- Moderate reliability, some variability: 0.5 × lead time (most common starting point) +- Unreliable upstream, frequent disruptions: 0.75 × lead time + +**Buffer sizing example:** +If the upstream lead time from raw material release to the constraint work centre is +8 hours, and upstream reliability is moderate, set the buffer at 4 hours. This means +material should arrive at the constraint staging area at least 4 hours before the +constraint is scheduled to process it. + +**Step 5: Monitor Buffer Penetration** + +| Zone | Buffer Consumed | Meaning | Action | +|---|---|---|---| +| Green | 0–33% | Constraint well-protected | Normal operations | +| Yellow | 33–67% | Warning — material may arrive late | Expedite upstream work. Check for blockers. | +| Red | 67–100% | Critical — constraint at risk of starvation | Immediate escalation. Overtime upstream. Re-sequence if needed. | +| Black | >100% | Buffer exhausted — constraint is starving | Constraint is idle or will be idle. Emergency response. Every minute of delay from this point = lost plant output. | + +Track buffer penetration trends over 2–4 weeks. Persistent yellow indicates +a systemic upstream issue (not random variation) that needs corrective action. + +**Step 6: Elevate the Constraint (only if Steps 1–5 are exhausted)** + +If after full exploitation and subordination the constraint still limits plant output +below demand requirements: + +1. Add overtime or a weekend shift at the constraint only. +2. Add a parallel machine or alternate routing capability. +3. Outsource constraint-specific operations to a qualified subcontractor. +4. Invest in faster constraint equipment (capital expenditure). + +Each elevation step is progressively more expensive. Never elevate before fully +exploiting — most plants have 15–25% hidden capacity at the constraint that +exploitation recovers at minimal cost. + +### 3.2 Buffer Management Advanced Patterns + +**Shipping Buffer:** Protects customer due dates from internal variability. Typically +50% of the lead time from the constraint to shipping. If the constraint-to-shipping +lead time is 2 days, the shipping buffer is 1 day — work should arrive at the +shipping staging area 1 day before the committed ship date. + +**Assembly Buffer:** In plants with convergent product structures (multiple components +feeding a common assembly), each feeder path to the assembly point needs its own +buffer. The assembly can only proceed when ALL components are present, so the +slowest feeder path determines the effective buffer. + +**Dynamic Buffer Adjustment:** +- If buffer penetration is consistently in the green zone (>80% of jobs arrive with + buffer intact over a 4-week rolling window), reduce the buffer by 10–15%. Excess buffer + means excess WIP and longer lead times. +- If buffer penetration frequently reaches red zone (>20% of jobs in a 4-week window), + increase the buffer by 15–20% while investigating the root cause upstream. +- Never adjust buffers more frequently than every 2 weeks. Buffer management requires + stable data over multiple cycles. + +--- + +## 4. Disruption Recovery Protocols + +### 4.1 Structured Disruption Response Framework + +When a disruption occurs, follow this decision tree: + +**Step 1: Classify the Disruption** + +| Type | Examples | Typical Duration | Impact Scope | +|---|---|---|---| +| **Equipment** | Breakdown, sensor failure, tooling wear | 30 min – 3 days | Single work centre | +| **Material** | Shortage, wrong specification, quality reject of incoming | 2 hours – 2 weeks | Multiple work centres sharing the material | +| **Labour** | Absenteeism, injury, certification gap | 1 shift – 1 week | Single work centre or line | +| **Quality** | In-process defect, customer complaint triggering hold | 2 hours – 1 week | Entire batch/lot, plus downstream consumers | +| **External** | Supplier failure, power outage, weather, regulatory stop | 4 hours – indefinite | Potentially plant-wide | + +**Step 2: Assess Constraint Impact** + +| Disruption Location | Constraint Impact | Response Priority | +|---|---|---| +| At the constraint | Direct — every minute = lost throughput | Maximum priority. All resources mobilised. | +| Upstream of constraint, buffer is green | Indirect — buffer absorbs the delay | Monitor buffer penetration. No immediate schedule change. | +| Upstream of constraint, buffer is yellow/red | Indirect but imminent — constraint will starve | Expedite. Overtime upstream. Re-sequence to feed constraint from alternate sources. | +| Downstream of constraint | No throughput impact unless WIP backs up to constraint | Monitor. Clear downstream blockage before constraint output starts queuing. | +| Parallel path (no constraint interaction) | No throughput impact, but delivery impact on affected orders | Re-sequence affected orders. Notify customers. | + +**Step 3: Execute Recovery** + +1. **Immediate (0–30 minutes):** Assess duration and impact. Notify affected parties. Freeze in-process work. +2. **Short-term (30 min – 4 hours):** Re-sequence remaining work. Activate alternate routings. Assign backup operators. Request emergency maintenance. +3. **Medium-term (4–24 hours):** Negotiate overtime or shift extensions. Contact subcontractors. Update customer ETAs. Recalculate the full planning horizon. +4. **Long-term (>24 hours):** Capacity rebalancing. Possible order reallocation to alternate sites. Customer negotiations on delivery schedules. Insurance/force majeure documentation if applicable. + +### 4.2 Material Shortage Response + +1. **Confirm the shortage:** Verify physical inventory vs. system count. Phantom inventory + is common — conduct a physical count before declaring a shortage. +2. **Identify substitutes:** Check BOM alternates, engineering-approved substitutions, + and customer-approved equivalent materials. In regulated industries (aerospace, pharma), + only pre-approved substitutes are permissible. +3. **Partial build strategy:** Can you complete operations up to the point where the short + material is consumed, then hold semi-finished WIP for completion when material arrives? + This keeps upstream work centres productive and preserves lead time on the non-missing + portions of the routing. +4. **Re-sequence:** Pull forward all work orders that do not consume the short material. + This keeps the plant productive even during the shortage. +5. **Expedite procurement:** Emergency purchase order at premium freight. Quantify: is the + cost of expedited material + freight less than the cost of lost constraint time × hours + of delay? If yes, expedite without hesitation. +6. **Customer communication:** If the shortage will impact customer deliveries, notify within + 4 hours of confirmation. Provide a revised delivery date and a recovery plan. + +### 4.3 Quality Hold Management + +When an in-process quality issue is discovered: + +1. **Contain immediately:** Quarantine all affected WIP — the batch in process, any + completed units from the same batch, and any downstream assemblies that consumed + units from the batch. +2. **Assess scope:** How many units are affected? Which customer orders consume these units? + What is the rework cost vs. scrap cost vs. customer rejection cost? +3. **Reschedule:** Remove the held inventory from the active schedule. Recalculate all + downstream operations that depended on this inventory. +4. **Decision tree for held material:** + - **Rework possible and economical:** Schedule rework operations. Add rework time to the + routing and re-sequence downstream. + - **Rework possible but not economical (rework cost > material + labour cost of remaking):** + Scrap the held batch and schedule a replacement production order from scratch. + - **Cannot rework, cannot scrap (regulatory hold pending investigation):** Exclude from + schedule indefinitely. Plan as though the inventory does not exist. +5. **Root cause:** While the schedule adjusts, quality engineering should be isolating the + root cause. The scheduler needs to know: is this a one-time event, or will subsequent + batches also be affected? If systemic, reduce yield assumptions for the affected operation + in the scheduling parameters until the root cause is resolved. + +--- + +## 5. Capacity Planning vs. Finite Scheduling + +### 5.1 Rough-Cut Capacity Planning (RCCP) + +RCCP is a medium-term planning tool (4–16 weeks out) that validates whether the MPS +is feasible at a high level before detailed scheduling. + +**Process:** +1. Take the MPS (production plan by product family by week). +2. Multiply by the routing hours per unit at each key work centre (typically only the + constraint and 1–2 near-constraints). +3. Compare total required hours against available hours per week at each work centre. +4. If required hours exceed available hours, flag the overloaded weeks for action: + demand shaping (move orders to adjacent weeks), overtime, subcontracting, or MPS revision. + +**RCCP Load Profile Example:** + +| Week | Constraint Capacity (hrs) | Required Load (hrs) | Utilisation | Status | +|---|---|---|---|---| +| W23 | 120 | 105 | 87.5% | OK | +| W24 | 120 | 118 | 98.3% | Warning — near capacity | +| W25 | 120 | 142 | 118.3% | Overloaded — action needed | +| W26 | 120 | 96 | 80.0% | OK — could absorb W25 overflow | +| W27 | 80 (planned maintenance window) | 75 | 93.8% | Tight — maintenance may need rescheduling | + +**Actions for W25 overload:** +- Can 22 hours of load shift to W24 or W26 without missing customer dates? Check due dates. +- If not shiftable: overtime (22 hrs ÷ 8 hrs/shift = 3 extra shifts, or 3 Saturday shifts). +- If overtime not available: which orders have the most flexible delivery dates? Negotiate. +- Last resort: subcontract 22 hours of work. Assess quality and lead time implications. + +### 5.2 Finite Capacity Scheduling (FCS) Detail + +FCS goes beyond RCCP by scheduling individual operations on specific resources at +specific times, respecting: + +1. **Resource capacity:** Number of machines × hours per shift × shifts per day, minus planned maintenance windows. +2. **Sequence-dependent setups:** Setup time varies based on the preceding job (see setup matrix in Section 2.2). +3. **Material availability:** An operation cannot start until all BOM components are available at the work centre. +4. **Tooling constraints:** A job requiring tooling set ABC cannot run simultaneously with another job requiring the same tooling. +5. **Labour constraints:** A job requiring a certified operator cannot be scheduled when no certified operator is on shift. +6. **Operation dependencies:** Operation 20 on a work order cannot start until Operation 10 is complete (routing precedence). +7. **Transfer batches:** Overlap operations can start before the full batch from the preceding operation is complete, if the transfer batch size is defined. + +**FCS Scheduling Algorithm (simplified):** +1. Sort all operations by priority (using the hybrid dispatching approach from Section 1.2). +2. For the highest-priority unscheduled operation: + a. Find the earliest feasible time slot on the required resource, considering capacity, + material availability, tooling, labour, and predecessor completion. + b. Schedule the operation in that slot. + c. Update resource availability. +3. Repeat for the next-highest-priority operation. +4. After all operations are scheduled, run a post-optimisation pass looking for setup + reduction opportunities (adjacent-swap improvements) that don't violate due dates. + +### 5.3 Capacity Buffers and Protective Capacity + +Non-constraint work centres should maintain protective capacity — deliberately planned +idle time that absorbs variability and prevents WIP accumulation. + +**Target utilisation by work centre type:** + +| Work Centre Type | Target Utilisation | Rationale | +|---|---|---| +| Constraint | 90–95% | Maximise output. Buffer everything else to protect it. | +| Near-constraint (>80% loaded) | 85–90% | Close to becoming the constraint. Monitor for shifting bottleneck. | +| Standard | 75–85% | Protective capacity absorbs upstream variability. | +| Shared resource (forklift, crane, inspector) | 60–75% | High variability in demand for these resources. Over-scheduling creates system-wide delays. | +| Rework/repair | 50–70% | Must have capacity available on demand. Cannot schedule at high utilisation. | + +**Warning signs of insufficient protective capacity:** +- WIP queues growing at non-constraint work centres over time. +- Non-constraint work centres occasionally becoming the bottleneck (shifting bottleneck). +- Overtime at non-constraint work centres "to keep up." +- Material handlers constantly expediting between non-constraint operations. + +--- + +## 6. Multi-Constraint Scheduling + +### 6.1 Interactive Constraints + +When two or more work centres both exceed 85% utilisation and share a material flow path, +they interact — improving throughput at one may starve or overload the other. + +**Identification:** +Two work centres are interactive constraints if: +1. They are on the same routing (material flows from one to the other), AND +2. Both exceed 85% utilisation, AND +3. Adding capacity at one causes the other's utilisation to exceed 95%. + +**Scheduling Strategy for Interactive Constraints:** + +1. **Schedule the primary constraint first** (the one with higher utilisation or the one + closer to the customer). +2. **Subordinate the secondary constraint** to the primary's schedule — the secondary + constraint processes work in the order and at the pace dictated by the primary constraint's + output schedule. +3. **Place a buffer between them** — even though both are constraints, the upstream one + should feed a time buffer to the downstream one to absorb variability. +4. **Never optimise them independently.** A setup sequence that is optimal for the primary + constraint may create an impossible sequence for the secondary constraint if setups + are sequence-dependent at both. Solve jointly. + +### 6.2 Machine + Labour Dual Constraints + +Common in environments where machines are semi-automated and require an operator for +setup, first-piece inspection, or monitoring but can run unattended for portions of the cycle. + +**Scheduling approach:** +1. Schedule machine capacity first (finite capacity by machine). +2. Overlay labour capacity (finite capacity by skill/certification). +3. Identify conflicts: time slots where the machine schedule requires an operator but + no qualified operator is available. +4. Resolve conflicts by: + - Shifting the job to a different machine that a different operator is qualified on. + - Shifting the operator from a lower-priority job to the conflicting job. + - Scheduling the operator's setup/inspection tasks at the start of the job and + allowing unattended running thereafter. + +### 6.3 Tooling as a Shared Constraint + +When specialised tooling (moulds, dies, fixtures, gauges) is shared across machines: + +1. **Treat tooling as a resource in the scheduling system** — the same way you schedule + machines and labour, schedule tooling. +2. **Two jobs requiring the same mould cannot run simultaneously** on different machines. +3. **Tooling changeover time** between machines adds to the total changeover. If Mould A + moves from Machine 1 to Machine 2, add the mould extraction time (Machine 1) + transport + time + mould installation time (Machine 2). +4. **Optimise by grouping:** If three jobs all require Mould A, schedule them consecutively + on the same machine to avoid mould transfers. + +--- + +## 7. Line Balancing for Mixed-Model Production + +### 7.1 Takt Time Calculation + +``` +Takt Time = Available Production Time per Shift / Customer Demand per Shift +``` + +**Example:** 480 minutes available per shift (8 hours × 60 min, minus 30 min breaks), +customer demand is 240 units per shift. + +``` +Takt Time = 450 / 240 = 1.875 minutes per unit +``` + +Every workstation on the line must complete its tasks within 1.875 minutes per unit. +If any station exceeds takt, it becomes the bottleneck and the line cannot meet demand. + +### 7.2 Workstation Balancing + +1. List all tasks with their duration and precedence relationships. +2. Assign tasks to workstations such that no workstation exceeds takt time. +3. Minimise the number of workstations (to minimise labour cost). +4. Measure balance efficiency: + +``` +Balance Efficiency = Σ(Task Times) / (Number of Stations × Takt Time) × 100% +``` + +Target: >85%. Below 80% indicates significant idle time at some stations. + +### 7.3 Mixed-Model Sequencing (Heijunka) + +When a line produces multiple models with different task times: + +1. Calculate the weighted average cycle time across models. +2. Determine the model mix ratio (e.g., Model A: 60%, Model B: 30%, Model C: 10%). +3. Create a repeating pattern that levels the workload. For A:B:C = 6:3:1, a 10-unit + cycle would be: A-B-A-A-C-A-B-A-B-A. +4. Validate that the bottleneck station can handle every model within takt. If Model C + takes 2.5 minutes at Station 3 while takt is 1.875 minutes, Model C must be spaced + sufficiently that Station 3 can catch up between occurrences. + +--- + +## 8. Scheduling with Regulatory and Compliance Constraints + +### 8.1 Traceability-Driven Scheduling + +In regulated industries (pharmaceutical, food, aerospace), lot traceability requirements +constrain scheduling flexibility: + +- **No lot mixing:** A work order for Lot A and a work order for Lot B cannot share + equipment simultaneously unless the equipment is fully cleaned between lots and + the cleaning is documented. +- **Dedicated equipment campaigns:** When allergen or contamination controls require + dedicated equipment, the scheduling window for Product X on Line 1 is limited to + the dedicated campaign period. Scheduling outside this window requires re-validation. +- **Operator qualification records:** The schedule must record which operator performed + each operation, and that operator must be certified at the time of execution. + +### 8.2 Clean-In-Place (CIP) Scheduling + +In food, beverage, and pharma, CIP cycles are mandatory between certain product transitions: + +| Transition Type | CIP Duration | Can Be Shortened? | +|---|---|---| +| Same product, next batch | 0–15 min (rinse only) | No — regulatory minimum | +| Same product family | 30–60 min (standard CIP) | Only with validated short-CIP protocol | +| Different product family | 60–120 min (full CIP) | No — regulatory requirement | +| Allergen transition | 120–240 min (enhanced CIP + swab test) | No — requires analytical confirmation | + +Schedule CIP cycles as fixed blocks in the schedule, not as "setup time" that can be +compressed. Under-estimating CIP time is a common scheduling error that creates cascading +delays and regulatory risk. + +--- + +## 9. Schedule Stability and Frozen Zones + +### 9.1 Frozen / Slushy / Liquid Planning Horizons + +| Horizon | Typical Duration | Flexibility | Changes Require | +|---|---|---|---| +| **Frozen** | 0–48 hours | No changes except force majeure | Production Manager + Scheduler approval | +| **Slushy** | 48 hours – 1 week | Sequence changes allowed within day; no date changes | Scheduler approval | +| **Liquid** | 1–4 weeks | Fully flexible for re-sequencing and rescheduling | Scheduler discretion | +| **Tentative** | 4+ weeks | MRP-generated, not yet scheduled | Planning/MRP cycle | + +**Why frozen zones matter:** Every schedule change triggers a cascade — material handlers +re-stage kits, operators re-read work orders, quality pre-inspections may need repeating, +and changeover sequences recalculate. A plant that changes the schedule 10 times per shift +has more disruption from schedule changes than from actual production problems. + +### 9.2 Schedule Change Cost Model + +Before approving a schedule change in the frozen or slushy zone, estimate the total cost: + +``` +Change Cost = Changeover Cost Delta + Material Restaging Cost + Labour Disruption Cost + + Quality Re-inspection Cost + Customer Impact Risk +``` + +If Change Cost > Benefit of Change, reject the change and hold the current schedule. +Document the decision for the post-shift review. + +--- + +## 10. Overtime and Shift Extension Decision Framework + +### 10.1 When to Authorise Overtime + +Overtime is a scheduling lever, not a default. Use the following decision tree: + +1. **Is the overtime required at the constraint?** + - Yes → Calculate: overtime cost vs. throughput value of additional constraint hours. + If 4 hours of constraint overtime at $1,200 total cost enables $20,000 of shipments, + approve immediately. The ROI threshold for constraint overtime is typically 3:1 + (value:cost) or higher. + - No → The overtime at a non-constraint does not increase plant output. It only makes + sense if: (a) the non-constraint is starving the constraint and buffer penetration is + yellow/red, or (b) the non-constraint output is needed for a specific customer shipment + that cannot wait for the next regular shift. + +2. **Is the overtime voluntary or mandatory?** + - Check union contract or labour regulations. Many agreements require offering overtime + by seniority before mandating it. Mandatory overtime may require 24–48 hours' notice. + - Violating overtime assignment rules costs more in grievances and morale damage than + the production it generates. Always comply. + +3. **Fatigue and safety risk:** + - Operators who have already worked 10+ hours should not be assigned to the constraint + or to safety-critical operations. Error rates increase 25–40% in hours 11–12. + - If the overtime extends a 12-hour shift to 16 hours, assign the extended operator to + non-critical monitoring tasks and bring in a fresh operator for the constraint. + +### 10.2 Shift Pattern Comparison for Scheduling + +| Pattern | Hours/Week | Handovers/Week | Overtime Headroom | Best For | +|---|---|---|---|---| +| 3 × 8h (Mon–Fri) | 120 | 15 | Saturday shifts, daily OT | High-mix, moderate volume | +| 3 × 8h (24/7) | 168 | 21 | Limited — already near capacity | Process industries, continuous flow | +| 2 × 12h (Mon–Fri) | 120 | 10 | Weekend shifts | Capital-intensive with fewer handovers | +| 2 × 12h (4 on / 4 off) | 168 | 14 | Built into rotation | High-volume, steady demand | +| 4 × 10h (day shift only) | 40 per crew | 4 | Friday, weekend | Low-volume, single-shift operations | + +**Handover quality matters for scheduling:** Each handover is a potential point of +information loss — the incoming shift may not know about a developing quality issue, +a material shortage workaround, or a verbal schedule change. Fewer handovers (12-hour +shifts) improve information continuity but increase fatigue risk. Balance based on +operation complexity and error tolerance. + +--- + +## 11. Subcontracting Decision Framework + +### 11.1 When to Subcontract + +Subcontracting is the scheduling lever of last resort for capacity shortfalls. + +**Decision criteria (all must be met):** +1. Internal capacity at the required work centre is fully consumed through the delivery + deadline, including available overtime. +2. The operation is not at the constraint (subcontracting from the constraint usually means + the constraint needs elevation, not a one-time fix). +3. A qualified subcontractor exists who can meet the quality specification and delivery timeline. +4. The subcontracting cost + transport cost + quality risk cost is less than the cost of + late delivery (penalties + customer relationship damage). +5. In regulated industries: the subcontractor holds the necessary certifications + (ISO, IATF 16949, AS9100, FDA registration, etc.). + +### 11.2 Scheduling with Subcontracted Operations + +When an operation is subcontracted: +1. Remove the operation from the internal schedule. +2. Add a transport-out time (typically 0.5–2 days) and transport-in time. +3. Add the subcontractor's quoted lead time (add 20% buffer for first-time subcontractors). +4. The total external lead time replaces the internal operation time in the work order routing. +5. Schedule downstream internal operations based on the expected return date, not the + internal processing time. +6. Monitor subcontractor progress at 50% and 90% completion milestones. Do not wait until + the due date to discover a delay. + +--- + +## 12. Scheduling Metrics and Continuous Improvement + +### 12.1 Key Scheduling Metrics + +| Metric | Calculation | Target | What It Reveals | +|---|---|---|---| +| **Schedule Adherence** | Jobs started within ±1 hour of plan / Total jobs | > 90% | How well the plant follows the schedule | +| **Schedule Stability** | Jobs unchanged in frozen zone / Total frozen jobs | > 95% | How often the schedule is disrupted | +| **On-Time Delivery (OTD)** | Orders shipped on or before commit date / Total orders | > 95% | Customer-facing performance | +| **Make Span** | Time from first operation start to last operation end for a work order | Track vs. standard | Total production lead time | +| **Changeover Ratio** | Total changeover time / Total available time at the resource | < 10% at constraint | Setup efficiency | +| **Constraint Utilisation** | Actual producing time / Available time at constraint | > 85% | How well the constraint is exploited | +| **WIP Turns** | Annual COGS / Average WIP Value | > 12 for discrete mfg | Scheduling efficiency and flow | +| **Queue Time Ratio** | Queue time / Total lead time at each work centre | Track trend | Indicates hidden WIP and poor flow | + +### 12.2 Scheduling Post-Mortem Process + +After every significant schedule disruption (constraint downtime > 1 hour, customer delivery +miss, or overtime exceeding budget by > 20%), conduct a structured post-mortem: + +1. **Timeline reconstruction:** What happened, when, and what was the cascade of effects? +2. **Root cause:** Was the disruption caused by equipment, material, labour, quality, + scheduling logic, or external factors? +3. **Response assessment:** Was the re-sequencing decision optimal? Could the recovery have + been faster? Were communications timely? +4. **Parameter update:** Do scheduling parameters (setup times, run rates, yield factors, + buffer sizes) need adjustment based on what we learned? +5. **Systemic fix:** What preventive action will reduce the probability or impact of this + type of disruption recurring? + +Document findings in a scheduling incident log. Review the log monthly with production +management to identify patterns and prioritise improvement actions. + +### 12.3 Daily Scheduling Rhythm + +A disciplined daily cadence prevents reactive fire-fighting: + +| Time | Activity | Participants | +|---|---|---| +| Shift Start − 30 min | Pre-shift review: verify material staging, operator availability, equipment status | Scheduler, Shift Supervisor | +| Shift Start | Publish shift schedule. Walk the floor to confirm understanding. | Scheduler | +| Shift Start + 2 hrs | First checkpoint: plan adherence, buffer penetration, early disruption detection | Scheduler (desk review of MES data) | +| Shift Midpoint | Mid-shift review: actual vs. plan, re-sequence if needed | Scheduler, Shift Supervisor | +| Shift End − 1 hr | End-of-shift projection: what will be incomplete? Handover notes for next shift. | Scheduler, Shift Supervisor | +| Shift End | Shift handover: in-person (preferred) or documented. Key issues, deviations, pending decisions. | Outgoing + Incoming Schedulers | +| Daily (Morning) | Production meeting: yesterday's performance, today's priorities, issues requiring management decision | Scheduler, Production Mgr, Quality, Maintenance, Materials | + +This cadence creates at least 5 touchpoints per shift where the schedule is validated +against reality and corrected before deviations compound. + +--- + +## 13. ERP-to-Shop-Floor Data Flow + +### 13.1 SAP PP Integration Pattern + +``` +Sales Orders / Forecast + ↓ +Demand Management (MD61/MD62) + ↓ +MPS — Master Production Schedule (MD40/MD43) + ↓ +MRP Run (MD01/MD02) → Planned Orders + ↓ +Convert Planned → Production Orders (CO40/CO41) + ↓ +Sequence in APS/Scheduling Tool (external or PP/DS) + ↓ +Release to Shop Floor (CO02 — set status REL) + ↓ +MES Execution (operation confirmations — CO11N/CO15) + ↓ +Goods Receipt (MIGO) → Inventory Updated +``` + +**Common data quality issues:** +- Routing times (setup + run) not updated after process improvements → schedule + systematically allocates too much or too little time. +- BOM quantities not adjusted for yield → MRP under-orders material. +- Work centre capacity not reflecting actual shift patterns → FCS generates + infeasible schedules. +- Scrap reporting delayed → plan-vs-actual gap grows silently. + +### 13.2 Closing the Feedback Loop + +The single most important integration is the MES-to-schedule feedback: + +1. **Operation start:** MES records actual start time. Schedule compares to planned start. + Deviation > 1 hour triggers an alert. +2. **Operation end:** MES records actual end time and quantities (good + scrap). Schedule + updates remaining operations with actual predecessor completion. +3. **Downtime events:** MES captures downtime start, end, and reason code. Schedule + automatically adjusts downstream timing. +4. **Quality events:** MES captures inspection results. Failed inspection triggers a + schedule hold on the affected batch. + +Without this feedback loop, the schedule diverges from reality within hours and becomes +aspirational rather than operational. The shop floor stops consulting it, operators make +their own sequencing decisions, and throughput at the constraint drops because ad-hoc +sequencing ignores constraint protection logic. diff --git a/web-app/public/skills/production-scheduling/references/edge-cases.md b/web-app/public/skills/production-scheduling/references/edge-cases.md new file mode 100644 index 00000000..8818432a --- /dev/null +++ b/web-app/public/skills/production-scheduling/references/edge-cases.md @@ -0,0 +1,611 @@ +# Production Scheduling — Edge Cases Reference + +> Tier 3 reference. Load on demand when handling complex or ambiguous production scheduling situations that don't resolve through standard sequencing and dispatching workflows. + +These edge cases represent the scenarios that separate experienced production schedulers from everyone else. Each one involves competing constraints, imperfect data, time pressure, and real operational exposure. They are structured to guide decision-making when standard scheduling rules break down. + +--- + +## How to Use This File + +When a scheduling situation doesn't fit a clean pattern — when constraints shift mid-shift, when multiple disruptions compound, or when commercial pressure conflicts with physical reality — find the edge case below that most closely matches the situation. Follow the expert approach step by step. Document every decision and override so the shift handover and post-mortem have a clear trail. + +--- + +### Edge Case 1: Shifting Bottleneck Mid-Shift + +**Situation:** +A contract manufacturer produces aluminium housings for two automotive OEMs. The morning schedule loads the CNC machining centre at 92% utilisation and the powder coating line at 78% — machining is the constraint. At 10:00 AM, the product mix shifts as a batch of large, complex housings clears CNC (short cycle time per unit for the next batch of small housings) and hits the powder coat line, which now requires extended cure cycles. By 11:00 AM, CNC utilisation has dropped to 70% and powder coat is at 95%. The schedule optimised around CNC as the constraint is now starving CNC (which has excess capacity) while powder coat backs up with WIP stacking on the staging rack. + +**Why It's Tricky:** +Most scheduling systems set the constraint at the planning stage and hold it fixed for the shift. When the constraint shifts intra-shift, the buffer management, subordination logic, and priority sequencing all become wrong simultaneously. The CNC buffer is unnecessarily large (tying up WIP), while the powder coat buffer doesn't exist and the line is starving. + +**Common Mistake:** +Ignoring the shift because "machining is the constraint this week" based on the weekly capacity plan. Or overreacting by completely re-sequencing the shift, creating chaos on the shop floor. + +**Expert Approach:** +1. Recognise the shift by monitoring real-time WIP levels. WIP accumulating before powder coat while CNC's outfeed staging area is empty is the leading indicator. +2. Verify the duration: is this a temporary product-mix effect (2–3 hours) or will it persist for the rest of the shift? Check the remaining work order sequence. +3. If temporary (< 3 hours): do not re-sequence the entire shift. Instead, tactically re-prioritise the 2–3 jobs in the powder coat queue to minimise setup changes (colour sequencing), and slow CNC's release rate to avoid over-building the WIP queue. +4. If persistent (rest of the shift): formally re-designate powder coat as the shift's constraint. Apply constraint protection: pre-stage next jobs at the powder coat line, stagger CNC completions to match powder coat's processing rate, and assign the most experienced operator to the powder coat line. +5. At shift handover, document the constraint shift and the product mix that caused it so the incoming scheduler plans accordingly. + +**Documentation Required:** +- Time of constraint shift detection +- Product mix analysis showing utilisation crossover +- Tactical adjustments made (CNC pacing, powder coat priority changes) +- Impact on customer orders (any due date revisions) +- Shift handover note for the incoming scheduler + +**Resolution Timeline:** +- 0–15 min: Detect the WIP imbalance +- 15–30 min: Verify duration and decide on tactical vs. full re-sequence +- 30–60 min: Implement adjustments and confirm stabilisation +- Shift end: Document and hand over + +--- + +### Edge Case 2: Certified Operator Absent for Regulated Process + +**Situation:** +A pharmaceutical contract manufacturer operates a tablet coating line that requires an FDA-qualified operator (documented training, competency assessment, and supervisor sign-off per 21 CFR Part 211). The night shift has two qualified coating operators: Maria (12 years experience) and Jamal (3 years, recently qualified). At 10:30 PM, Jamal — tonight's scheduled coating operator — calls in sick. Maria works day shift and is off-site. The coating line has 6 hours of work scheduled tonight that feeds a customer shipment due in 3 days. No other night-shift operator has the FDA qualification for this specific process step. + +**Why It's Tricky:** +This is a hard regulatory constraint, not a soft preference. Running the coating line with an unqualified operator is a GMP violation that can trigger an FDA Form 483 observation, product recall, or facility warning letter. The cost of non-compliance vastly exceeds any production delay. But the customer shipment is for a hospital network, and delays affect patient medication availability. + +**Common Mistake:** +Running the line with an "almost qualified" operator who has completed training but hasn't finished the competency assessment documentation. This is a regulatory violation regardless of the operator's actual skill level. + +**Expert Approach:** +1. Confirm that no other night-shift employee holds the qualification. Check the cross-training matrix — not just coating operators, but anyone on night shift who may have been cross-trained on this line (maintenance technicians sometimes hold process qualifications). +2. Contact Maria. Can she work a split shift (come in at midnight, work 6 hours, leave at 6 AM)? Check the union contract and fatigue rules — most agreements require an 8-hour rest between shifts. If Maria left day shift at 3:30 PM, she is eligible to return at 11:30 PM under an 8-hour rest rule. +3. If Maria is available and willing: authorise overtime, document the reason (single-point-of-failure staffing event), and adjust the coating schedule to start when she arrives. +4. If Maria is unavailable: stop the coating line. Do not attempt a workaround. Re-sequence the night shift to run non-regulated operations (packaging, labelling, material preparation for the next coating run). Calculate the impact on the customer shipment: can 6 hours of coating work be completed on the day shift (with overtime if needed) and still meet the 3-day deadline? +5. Escalate to the production manager and quality assurance manager. If the customer deadline cannot be met, notify the customer immediately with a revised delivery date. For pharmaceutical customers, "we maintained GMP compliance" is a stronger position than "we cut corners to hit the date." +6. Post-incident: submit a request to cross-train 2 additional night-shift operators on the coating process. Single-point-of-failure on a regulated process is a systemic risk. + +**Documentation Required:** +- Cross-training matrix review (who holds the qualification, who does not) +- Maria's contact record and response +- Overtime authorisation (if applicable) with union compliance check +- Re-sequenced night schedule showing non-regulated work +- Customer notification (if shipment delayed) +- CAPA (Corrective and Preventive Action) for cross-training gap + +**Resolution Timeline:** +- 10:30 PM: Absence confirmed +- 10:30–11:00 PM: Cross-training matrix review, Maria contacted +- 11:00 PM: Decision made (Maria coming in, or coating line stopped) +- 11:15 PM: Re-sequenced schedule published for night shift +- Next business day: CAPA initiated for cross-training + +--- + +### Edge Case 3: Competing Rush Orders from Tier-1 Customers + +**Situation:** +A precision machining job shop receives two emergency orders on the same Monday morning: + +- **Customer A (major automotive OEM):** 500 transmission valve bodies needed by Thursday. Their assembly line is down waiting for these parts. Contractual penalty: $25,000/day of late delivery. Annual revenue from Customer A: $4.2M. +- **Customer B (aerospace prime contractor):** 200 fuel system brackets needed by Friday. Their production schedule slips 1 week for every day of delay on these brackets. No contractual penalty, but Customer B is in a competitive evaluation and a slip here could cost the $8M annual contract renewal in Q3. + +Both orders require the same 5-axis CNC machining centre (the plant's constraint), and the combined processing time exceeds the available capacity by 16 hours. + +**Why It's Tricky:** +This is not a scheduling problem — it's a commercial decision disguised as a scheduling problem. The scheduler can identify the tradeoff and quantify it, but the decision on which customer to prioritise requires management input on strategic relationships, risk tolerance, and commercial exposure. + +**Common Mistake:** +The scheduler makes the commercial decision unilaterally, typically defaulting to the contractual penalty (Customer A) without presenting the strategic risk (Customer B). Or the scheduler tries to split the capacity equally, resulting in both orders being late. + +**Expert Approach:** +1. Quantify both scenarios precisely: + - **Prioritise A:** Customer A ships Thursday (on time). Customer B ships the following Monday (3 days late). Customer B cost: potential $8M contract risk, unquantifiable but real. + - **Prioritise B:** Customer B ships Friday (on time). Customer A ships Saturday (2 days late). Customer A cost: $50,000 in contractual penalties + relationship damage. + - **Split capacity:** Customer A ships Friday (1 day late, $25K penalty). Customer B ships Monday (3 days late, contract risk). +2. Identify capacity recovery options: + - Saturday overtime on the CNC (8 hours, cost ~$3,200). If authorised, both orders can be completed on time: A by Thursday, B by Saturday. + - Subcontract the simpler machining operations for Customer B to a qualified external shop, freeing 8 hours of CNC capacity for Customer A. Cost: $4,500 for subcontracting + expedited freight. +3. Present the tradeoff matrix to the production manager and sales director with recommended option (overtime or subcontracting, not splitting capacity). Include the cost comparison. +4. Once the decision is made, re-sequence the entire CNC schedule for the week. Lock the frozen zone on the decided sequence. Communicate to both customers. + +**Documentation Required:** +- Capacity analysis showing the 16-hour shortfall +- Tradeoff matrix with financial exposure for each scenario +- Recommended recovery options with cost estimates +- Management decision record (who decided, which option, rationale) +- Customer communication log + +**Resolution Timeline:** +- Monday AM: Both rush orders received +- Monday AM + 2 hours: Capacity analysis and tradeoff matrix completed +- Monday AM + 4 hours: Management decision +- Monday PM: Re-sequenced schedule published, customers notified + +--- + +### Edge Case 4: MRP Phantom Demand from BOM Error + +**Situation:** +The scheduler notices that MRP has generated a planned production order for 3,000 units of a sub-component (Part #SC-4420, a machined bracket) with a due date in 2 weeks. This is unusual — this part typically runs in batches of 500 for the two product families that consume it. A check of the current sales orders and forecast shows demand for only 800 units over the next 6 weeks. The MRP-generated demand of 3,000 appears to be phantom. + +Investigation reveals that an engineer updated the BOM for a new product variant (not yet released) and accidentally set the quantity-per of SC-4420 to 12 instead of 1 on the master BOM. The MRP explosion multiplied forecasted demand for the new variant (250 units) by 12, generating 3,000 units of phantom demand. The BOM error has not yet been caught by engineering. + +**Why It's Tricky:** +Scheduling systems trust MRP output. If the scheduler blindly converts the planned order to a production order and schedules it, the plant will produce 2,200 units of unwanted inventory, consuming 44 hours of machining capacity that was needed for real customer demand. But if the scheduler ignores MRP output without proper verification, they risk missing legitimate demand. + +**Common Mistake:** +Scheduling the MRP-generated order without questioning it ("the system says we need it"), or deleting it without notifying engineering about the BOM error (the error persists and generates phantom demand again in the next MRP run). + +**Expert Approach:** +1. **Verify the anomaly:** Compare the MRP-generated demand to the trailing 6-month demand history for SC-4420. A 3× spike with no corresponding sales order or forecast increase is a red flag. +2. **Trace the demand:** Use MRP pegging (SAP: MD04/MD09, Oracle: pegging inquiry) to trace the planned order back to the parent demand that generated it. This reveals which parent product's BOM is driving the demand. +3. **Identify the root cause:** The pegging trace points to the new product variant BOM. Compare the BOM quantity-per to the engineering drawing — the drawing shows 1 unit per assembly, the BOM shows 12. +4. **Do not schedule the phantom demand.** Place a hold on the planned order with a note explaining the suspected BOM error. +5. **Notify engineering immediately.** Provide the specific BOM line, the quantity discrepancy, and the MRP impact. Request urgent correction. +6. **Schedule the real demand:** Create a production order for the actual 800-unit requirement and sequence it normally. +7. **Verify the fix:** After engineering corrects the BOM, re-run MRP for SC-4420 and confirm the planned orders now align with expected demand. + +**Documentation Required:** +- Anomaly detection: what triggered the investigation (volume spike, capacity conflict) +- MRP pegging trace results +- BOM error details (parent item, line item, incorrect vs. correct quantity) +- Engineering notification with correction request +- Production order for actual demand +- Verification after BOM correction + +**Resolution Timeline:** +- Day 1: Anomaly detected during schedule review +- Day 1 + 2 hours: Pegging trace and root cause identified +- Day 1 + 4 hours: Engineering notified, phantom order held +- Day 2–3: Engineering corrects BOM, MRP re-run +- Day 3: Verified — phantom demand eliminated + +--- + +### Edge Case 5: Quality Hold on WIP Inventory Affecting Downstream + +**Situation:** +A metal fabricator discovers a dimensional defect on a batch of 200 stamped chassis frames at the weld inspection station. The defect — a hole pattern shifted 2mm from specification due to a worn die — affects the entire batch produced since the last die change 3 shifts ago. Of the 200 affected frames: 80 are in welding (current operation), 60 have completed welding and are in paint queue, and 60 have completed paint and are in final assembly staging. Final assembly is the plant's constraint, and these 60 painted frames were scheduled to feed the constraint starting tomorrow morning. The customer (a commercial HVAC manufacturer) has a firm delivery commitment for 150 assembled units on Friday. + +**Why It's Tricky:** +The quality hold cascades across three production stages. Some units may be reworkable (the hole pattern might be re-drilled), but rework adds operations to the routing and consumes capacity. The constraint (final assembly) will starve tomorrow if the 60 painted frames are quarantined. And the die that caused the defect needs to be replaced before more frames can be stamped, adding a maintenance operation to the schedule. + +**Common Mistake:** +Quarantining only the 80 frames at welding (the point of detection) and allowing the 60 painted frames to proceed to assembly. If the defect makes assembly impossible or causes field failures, the cost of rework/recall after assembly is 5–10× the cost of catching it now. + +**Expert Approach:** +1. **Full containment:** Quarantine all 200 frames across all three stages immediately. Tag, segregate, and document. No exceptions — even frames that "look fine" at paint stage may have the shifted hole pattern. +2. **Assess reworkability:** Can the 2mm shift be corrected? Options: + - Re-drill the hole pattern at the correct location (if material allows, the shifted holes will remain as cosmetic defects — check if customer spec allows). + - Weld-fill the incorrect holes and re-drill (expensive, time-consuming, may not pass NDT for structural components). + - Scrap all 200 and restart from raw material (if re-drilling is not viable). +3. **Schedule the constraint feed:** The constraint (final assembly) needs 60 frames tomorrow. If rework is feasible and fast enough: + - Expedite rework of the 60 painted frames first (they are furthest along). + - Schedule rework as an additional operation in the routing with its own time estimate. + - If rework takes 0.5 hours per frame and you assign 2 rework operators, 60 frames = 15 hours = 2 shifts. + - The constraint will be short frames for tomorrow's day shift. Can you pull forward other work at the constraint (different product) to fill the gap? If yes, do that and push the HVAC assembly to tomorrow's night shift or Wednesday. +4. **Fix the die:** Replace or re-sharpen the stamping die before producing any new frames. Add a first-piece dimensional inspection requirement after the die change. If the die is a custom tool with a 2-week replacement lead time, have tooling assess whether the current die can be ground and requalified as a temporary measure. +5. **Customer communication:** If Friday delivery is at risk, notify the customer by end of business today. Provide a revised ETA based on the rework timeline. + +**Documentation Required:** +- Defect description, quantity affected, production stages +- Containment actions and quarantine locations +- Rework assessment (feasibility, time, cost) +- Revised schedule showing constraint feed plan +- Die replacement/repair plan +- Customer notification (if delivery impacted) +- CAPA for die wear monitoring (preventive inspection schedule) + +**Resolution Timeline:** +- Hour 0: Defect detected at weld inspection +- Hour 0–1: Full containment across all stages +- Hour 1–3: Rework feasibility assessment +- Hour 3–4: Revised schedule published with rework operations +- Hour 4: Customer notified if delivery impacted +- Day 2–3: Rework completed, constraint fed +- Week 1: Die replaced or requalified + +--- + +### Edge Case 6: Equipment Breakdown at the Constraint + +**Situation:** +The main CNC horizontal boring mill — the plant's constraint for large machining operations — suffers a hydraulic pump failure at 9:15 AM on a Wednesday. Maintenance assessment: pump replacement requires 6–8 hours, but the replacement pump must be sourced from the OEM distributor 4 hours away. Realistic return-to-service: Thursday 6:00 AM (20+ hours of constraint downtime). Current work in the machine: a $38,000 defence contract part, 6 hours into an 8-hour operation — incomplete, cannot be removed without scrapping. 14 additional jobs are queued behind it, representing $220,000 in customer orders due within 2 weeks. + +**Why It's Tricky:** +Every hour of constraint downtime directly reduces plant throughput. 20 hours at a constraint generating $800/hour in throughput = $16,000 in lost output. The defence part in the machine presents a dilemma: can it be completed when the machine restarts (will the part datum be preserved?), or is it scrap? + +**Common Mistake:** +Waiting for the repair to complete before re-planning. By then, 20 hours of schedule disruption have cascaded through the plant with no mitigation. + +**Expert Approach:** +1. **Immediate (0–15 min):** + - Confirm maintenance's repair estimate. Ask: is there a faster temporary fix (bypass, rental equipment)? Can the OEM ship the pump by overnight freight instead of driving? + - Determine if the in-machine part can resume after repair. Consult the machinist: are the datum offsets preserved? If the machine can restart the interrupted operation from the last completed tool path, the part is salvageable. If not, it may need to be re-fixtured and re-qualified, adding 2–3 hours but saving the $38,000 part. +2. **Short-term (15 min – 2 hours):** + - Identify alternate routings: which of the 14 queued jobs can be processed on a smaller vertical CNC? The tolerances may allow some jobs to run on alternate equipment, even if cycle times are longer. Move those jobs immediately. + - Re-sequence remaining jobs by customer priority (EDD + customer tier weighting). When the constraint restarts Thursday AM, the first job in the queue must be the highest-priority item. + - Calculate customer impacts: which of the 14 jobs will miss due dates? Prepare a customer notification for each affected order. +3. **Medium-term (2–20 hours, while machine is down):** + - Pre-stage everything for the queued jobs: tooling, raw material, fixtures, programs, operator assignments. When the machine restarts, the first job should begin within 15 minutes of the machine's green light. + - Evaluate whether Saturday overtime (8–16 hours) can recover the lost production. Cost of overtime vs. cost of late deliveries. + - Contact qualified external machining shops for the most at-risk orders. Can they process any of the 14 jobs faster than your recovery schedule? +4. **Recovery (Thursday AM onward):** + - Restart with the salvaged in-machine part (if viable) or load the highest-priority queued job. + - Run the constraint through all breaks and shift changes (stagger operators). + - Monitor recovery pace hourly against the recovery schedule. + +**Documentation Required:** +- Breakdown time, root cause, repair timeline +- In-machine part assessment (salvageable Y/N, additional cost) +- Alternate routing analysis for queued jobs +- Customer impact list with revised ETAs +- Overtime/subcontracting cost analysis +- Recovery schedule with hourly milestones + +**Resolution Timeline:** +- 9:15 AM: Breakdown +- 9:15–9:30 AM: Maintenance assessment and pump sourcing +- 9:30–11:00 AM: Alternate routing analysis, re-sequencing, customer notifications +- 11:00 AM – Thursday 6:00 AM: Pre-staging, subcontracting decisions, recovery planning +- Thursday 6:00 AM+: Machine restarts, recovery schedule executed +- Friday: Recovery progress assessment — overtime decision for Saturday + +--- + +### Edge Case 7: Supplier Delivers Wrong Material Mid-Run + +**Situation:** +A structural steel fabricator is midway through a production run of 100 beam assemblies for a commercial construction project. Each assembly requires Grade 350 structural steel plate (AS/NZS 3678). At 2:00 PM, the quality inspector checking the second material delivery of the day discovers the mill certificates show Grade 250 instead of Grade 350. The first delivery (Grade 350, correct) fed the first 40 assemblies. The second delivery (Grade 250, wrong) has been kitted into the staging area for assemblies 41–70, and 12 plates from this delivery have already been cut and are at the welding station. + +**Why It's Tricky:** +Grade 250 steel has lower yield strength than Grade 350 — assemblies made from it could be structurally inadequate and unsafe. The 12 cut plates cannot be used. But 28 plates from the wrong delivery are still uncut and could be returned. The production line is currently running and operators are about to start welding the incorrect material. + +**Common Mistake:** +Continuing production and hoping the customer won't notice (this is a structural integrity and safety issue — non-negotiable). Or shutting down the entire line when only assemblies 41–70 are affected — assemblies 71–100 can use material from a different source if available. + +**Expert Approach:** +1. **Stop welding immediately** on any piece using the Grade 250 material. Pull the 12 cut plates from the welding station and quarantine them with clear "HOLD — WRONG MATERIAL" tags. +2. **Segregate the remaining 28 uncut plates** from the wrong delivery. These can be returned to the supplier or used for non-structural orders that specify Grade 250. +3. **Continue production on assemblies 71–100** using material from existing Grade 350 stock (check if there is sufficient on-hand inventory from other purchase orders or stock). If Grade 350 stock is available for assemblies 71–100, the line does not need to stop entirely. +4. **Assemblies 41–70 are now blocked.** Contact the supplier for emergency replacement of 30 Grade 350 plates. Demand same-day or next-day delivery at the supplier's cost (this is a supplier error). If the supplier cannot respond fast enough, source from an alternative supplier. +5. **The 12 cut plates** in Grade 250 are scrap for this project. Calculate the scrap cost (material + cutting labour) and include it in the supplier claim. +6. **Reschedule assemblies 41–70** to start after replacement material arrives. In the meantime, sequence assemblies 71–100 first (if material is available) to keep the welding line productive. +7. **Notify the customer** if the construction project delivery timeline is affected. For structural steel, customers prefer a delay over incorrect material grade — this is a safety issue. + +**Documentation Required:** +- Material non-conformance report with mill certificate evidence +- Quarantine records for the 12 cut plates and 28 uncut plates +- Supplier notification and replacement delivery commitment +- Revised production schedule showing assemblies 71–100 pulled forward +- Scrap cost calculation for the supplier claim +- Customer notification (if delivery impacted) + +--- + +### Edge Case 8: Overtime Ban During Peak Demand + +**Situation:** +A consumer electronics assembly plant is entering its busiest 6-week period (back-to-school and early holiday orders). The production plan requires 132% of standard capacity at the constraint (SMT pick-and-place line) to meet all customer commitments. Normally, 32% of capacity comes from Saturday overtime shifts. However, the union just notified management that it is invoking the collective agreement clause limiting overtime to 5 hours per employee per week (down from the usual 15-hour soft cap) due to a dispute over shift differential rates. Negotiations are expected to take 3–5 weeks. + +**Why It's Tricky:** +The plant was counting on Saturday overtime as the primary capacity lever. Without it, 32% of demand is unfillable. But the 5-hour limit still allows some daily overtime (1 hour/day Mon–Fri = 5 hours/week), which partially offsets. The scheduler must find 20–25% additional effective capacity from other sources while respecting the union constraint. + +**Common Mistake:** +Pressuring operators to work "off the books" (violates the collective agreement and exposes the company to legal liability). Or accepting a 20–25% shortfall without exploring all alternatives. + +**Expert Approach:** +1. **Quantify the gap precisely:** Standard capacity at constraint = 120 hours/week. Required = 158.4 hours. Overtime now available = 1 hour/day × 5 days × number of qualified operators. If 4 operators run the SMT line and each can do 5 hours/week OT, that's 20 hours/week of overtime capacity, bringing effective capacity to 140 hours. Remaining gap: 18.4 hours/week. +2. **Exploit the constraint (no capital):** + - Reduce changeovers on SMT: consolidate product families, campaign-schedule similar board types together. Target: recover 4–6 hours/week from reduced changeover time. + - Run through all breaks and shift changes with staggered relief operators. Target: recover 2–3 hours/week. + - Reduce micro-stops through preventive maintenance during non-production hours. Target: recover 1–2 hours/week. +3. **Temporary labour:** Can temporary agency operators run non-constraint operations, freeing experienced operators to double up at the constraint? The SMT line requires certification, but downstream operations (manual assembly, testing, packaging) may accept temporary labour. +4. **Subcontract non-constraint work:** If downstream operations (conformal coating, testing) can be subcontracted, the freed-up internal capacity can be redirected to support constraint throughput (material handling, staging, quality inspection at the SMT line). +5. **Customer prioritisation:** If the gap cannot be fully closed, rank customer orders by value and contractual penalty exposure. Allocate constraint capacity to the highest-priority orders first. Negotiate delivery extensions with lower-priority customers before the original due date — proactive notification preserves the relationship. +6. **Demand shaping:** Work with sales to shift some orders from the peak 6-week window to the 2 weeks before or after, if customers have flexibility. Even moving 5% of demand out of peak reduces the capacity gap significantly. + +**Documentation Required:** +- Capacity analysis showing the gap (hours/week) with and without overtime +- Constraint exploitation plan with estimated recovery per initiative +- Temporary labour and subcontracting options with cost and timeline +- Customer prioritisation matrix +- Demand shaping proposals to sales +- Weekly progress tracking against the gap closure plan + +--- + +### Edge Case 9: Customer Order Change After Production Started + +**Situation:** +A custom industrial equipment manufacturer is 60% through a production order for Customer X: 20 hydraulic press frames, each with a 3-week machining cycle. 12 frames are complete through machining and in welding. 4 frames are in machining. 4 frames have not started (raw material cut but not machined). Customer X contacts sales to change the specification: they now need 15 frames at the original spec and 5 frames at a modified spec (different mounting hole pattern, additional reinforcement welds). The modified spec requires re-programming the CNC, a different welding fixture, and a revised quality inspection plan. Delivery date is unchanged. + +**Why It's Tricky:** +The 12 completed frames and 4 in-process frames are at the original spec. If the change applies to any of these, the rework cost is substantial (re-machining mounting holes, adding welds to finished frames). The 4 unstarted frames can be built to the new spec without rework. But the customer wants 5 modified frames, and only 4 are unstarted. + +**Common Mistake:** +Accepting the change without quantifying the rework cost and schedule impact, or rejecting the change outright without exploring options. + +**Expert Approach:** +1. **Analyse the change impact by production stage:** + - 4 unstarted frames: can be built to modified spec with no rework. CNC reprogramming takes 4 hours. Welding fixture modification takes 6 hours. + - 4 frames in machining: modification requires adding the new mounting holes, which can be done as an additional machining operation before the frames leave CNC. Added time: 2 hours per frame = 8 hours. + - 12 completed frames at welding: modification would require returning frames to CNC (re-fixturing, new hole pattern), then additional welding operations. Cost: $1,200 per frame rework + 4 hours per frame on the CNC constraint. This is expensive and uses 48 hours of constraint capacity. +2. **Propose the least-cost solution:** + - Build 4 unstarted frames to modified spec. + - Modify 1 of the 4 in-machining frames (the one least progressed) to modified spec. This gives Customer X their 5 modified frames. + - Complete the remaining 15 frames at original spec as planned. + - Total added cost: CNC reprogramming (4 hrs) + welding fixture modification (6 hrs) + additional machining on the modified in-process frame (2 hrs) = 12 hours added to the schedule. +3. **Price the change:** Calculate the total cost (labour, material, fixture modification, schedule disruption) and issue a change order cost estimate to Customer X before executing. The customer should approve the cost delta. +4. **Schedule the change:** Insert the CNC reprogramming and fixture modification into the schedule. The 4 unstarted frames are re-routed to the modified spec routing. The 1 in-process frame gets an additional operation added to its routing. +5. **Assess delivery impact:** 12 hours added to the critical path. Can this be absorbed within the original delivery date? If not, negotiate a 2-day extension or authorize overtime to recover the 12 hours. + +**Documentation Required:** +- Engineering change analysis showing impact per production stage +- Rework cost estimate per frame (by stage) +- Recommended solution with minimum cost/disruption +- Change order cost estimate for customer approval +- Revised schedule showing added operations +- Delivery impact assessment + +--- + +### Edge Case 10: New Product Introduction Competing with Existing Orders + +**Situation:** +A precision stamping company has been awarded a new contract for an automotive EV battery enclosure (a high-profile new product introduction, or NPI). The NPI requires 3 trial production runs over the next 6 weeks to qualify the tooling, validate the process, and produce samples for customer approval. Each trial run requires 8 hours on the 400-ton stamping press (the plant's constraint) plus 4 hours of changeover and die tryout between runs. The constraint is already running at 88% utilisation with existing customer orders. The NPI trial runs need 36 hours of constraint time over 6 weeks (6 hours/week average), which would push constraint utilisation to 93% — within capacity but with almost no buffer. + +**Why It's Tricky:** +NPI trial runs are unpredictable: the first run may reveal tooling issues requiring extended die adjustment (adding 4–8 hours), scrap rates on trial runs are typically 10–30% (vs. 2–3% for production runs), and engineering may need to stop the trial for measurements, adjustments, and design iterations. A trial run scheduled for 8 hours may actually consume 12–16 hours when interruptions are factored in. + +**Common Mistake:** +Scheduling NPI trials into standard production slots and expecting them to run on time. When the trial overruns, it displaces existing customer orders and creates cascading delays. + +**Expert Approach:** +1. **Do not schedule NPI trials at scheduled utilisation.** The 8-hour nominal trial time should be planned as a 14-hour window (8 hours production + 4 hours changeover + 2 hours contingency for tooling issues). This is realistic, not pessimistic, for first and second trials. +2. **Schedule trial runs at the end of the week** (Friday PM or Saturday) when any overrun pushes into the weekend rather than into Monday's committed production schedule. If the trial finishes early, the slot converts to weekend overtime production (recovering any capacity borrowed from the week). +3. **Reserve a "trial buffer" in the weekly schedule:** Block 14 hours per week as tentatively reserved for NPI. If the trial proceeds on schedule, this time is used as planned. If the trial is cancelled or postponed (common for NPIs), the buffer converts to regular production or maintenance. +4. **Protect existing customer commitments:** No existing order should have its due date moved to accommodate the NPI trial. If constraint capacity cannot accommodate both, escalate to management: the NPI trial schedule may need to extend beyond 6 weeks, or the plant may need Saturday overtime to create the capacity. +5. **Assign the most experienced setup technician and stamping operator** to the NPI trials. Trial-run productivity is heavily dependent on operator skill in adjusting die settings and recognising incipient defects. A junior operator on a trial run will consume 30–50% more time. +6. **After each trial run, update the time estimate** for the next trial. If Trial 1 took 14 hours and produced 15% scrap, plan Trial 2 at 12 hours (process should be improving) but keep the full 14-hour buffer until proven otherwise. + +**Documentation Required:** +- NPI trial schedule with buffered time estimates +- Constraint capacity analysis showing impact on existing orders +- Contingency plan if trial overruns +- Customer communication plan if existing orders are at risk +- Trial results and time actuals for updating subsequent trial estimates +- Post-trial tooling qualification report + +--- + +### Edge Case 11: Simultaneous Material Shortage and Equipment Degradation + +**Situation:** +A food processing plant producing canned soups faces two simultaneous problems: (1) the primary tomato paste supplier is 4 days late on a delivery that was supposed to arrive Monday, affecting all tomato-based soup production scheduled for this week, and (2) the retort (sterilisation vessel) — the plant's constraint — has developed a slow steam leak that reduces its effective cycle time by 12% (each batch takes 45 minutes instead of 40 minutes). Maintenance can fix the leak during a planned maintenance window on Saturday, but running the retort at reduced capacity all week compounds the supplier delay. + +**Expert Approach:** +1. Re-sequence the week to run non-tomato soup products (chicken, vegetable, cream-based) first while waiting for the tomato paste delivery. This keeps the retort running even at reduced capacity. +2. Calculate the effective capacity loss: 12% longer cycles = ~12% throughput reduction at the constraint. Over a 120-hour production week, this is 14.4 hours of lost capacity, equivalent to roughly 18 batches (at 48 min/batch effective). +3. When the tomato paste arrives (projected Thursday), re-sequence tomato soups with the most urgent due dates first. +4. Evaluate whether Saturday maintenance can be pulled forward to Wednesday night (sacrificing one night shift of production but restoring full capacity for Thursday–Friday). +5. Calculate the net capacity impact of early maintenance vs. running degraded all week: early fix loses 8 hours of production but recovers 12% efficiency for remaining 40+ hours = net gain of ~4.8 hours. +6. Customer priority: rank all orders by delivery date and penalty risk. Allocate retort capacity accordingly. + +--- + +### Edge Case 12: ERP System Upgrade During Production Week + +**Situation:** +IT has scheduled an ERP system upgrade (SAP ECC to S/4HANA migration cutover) for the upcoming weekend, with the system offline from Friday 6:00 PM to Monday 6:00 AM. The plant runs 24/7 production. During the outage, operators cannot confirm operations, material transactions cannot be posted, and work order status cannot be updated. The scheduling tool (which reads from SAP) will not receive real-time data. + +**Expert Approach:** +1. Print all work orders, routings, BOMs, and the production schedule for Friday PM through Monday AM. Distribute physical copies to every shift supervisor and work centre. +2. Pre-issue all materials needed for weekend production. Complete all goods issues in SAP before 6:00 PM Friday. Operators should not need to perform material transactions during the outage. +3. Implement manual shop floor tracking: paper travellers accompanying each batch, operator log sheets recording start/end times, quantities, and scrap. +4. Freeze the schedule for the weekend — no re-sequencing unless a genuine disruption (breakdown, quality hold) occurs. Without system support, ad-hoc schedule changes are extremely error-prone. +5. Monday AM: enter all weekend transactions into the new system. This "catch-up" data entry will take 2–4 hours. Assign a dedicated team. Verify inventory balances match physical counts before releasing the Monday schedule. +6. Have IT on standby for Monday morning to resolve any data migration issues that affect production records. + +**Documentation Required:** +- Pre-printed schedule and work order packets +- Material pre-issue verification checklist +- Manual tracking forms and instructions +- Monday catch-up data entry plan +- IT escalation contacts for Monday morning + +**Resolution Timeline:** +- Friday − 1 week: Print all production documentation, verify completeness +- Friday − 2 days: Pre-issue all weekend materials in SAP +- Friday 6:00 PM: System goes offline. Switch to manual tracking. +- Saturday–Sunday: Manual operations with paper travellers +- Monday 6:00 AM: System restored. Begin catch-up data entry. +- Monday 10:00 AM: Inventory verification and schedule release for Monday production + +--- + +### Edge Case 13: Batch Traceability Contamination — Product Recall Scenario + +**Situation:** +A medical device manufacturer receives a supplier notification that a lot of surgical-grade stainless steel (Heat #A7742) may contain elevated levels of nickel beyond the ASTM F138 specification. The supplier is still testing, but has issued a precautionary advisory. The plant's records show Heat #A7742 was received 3 weeks ago and has been consumed across 14 production work orders for 3 different product families (hip implant stems, bone screws, and spinal rods). Some finished goods from these work orders have already shipped to 4 hospital systems. + +**Why It's Tricky:** +Full traceability is mandatory under FDA 21 CFR Part 820 for medical devices. The scheduler must immediately identify every work order, every operation, every batch that consumed material from Heat #A7742. Some of this material may be in WIP across multiple production stages. A false-positive (the material is actually fine) means the quarantine was unnecessary but the disruption was real. A false-negative (failing to quarantine all affected units) could result in a Class I recall. + +**Common Mistake:** +Quarantining only the known remaining raw material from Heat #A7742 and missing the WIP and finished goods. Or waiting for the supplier's final test results before acting (which could take 5–7 business days). + +**Expert Approach:** +1. **Immediate lot trace (Hour 0–2):** Run a forward lot trace from Heat #A7742 through every production stage. In the ERP, trace the material receipt to every goods issue, then to every work order that consumed it, then to every finished goods batch, then to every shipment. +2. **Quarantine all affected WIP (Hour 0–4):** Every work-in-process piece traceable to Heat #A7742 must be physically segregated and tagged with "QUALITY HOLD — SUPPLIER ADVISORY" status. Update work order status in the ERP to "blocked." +3. **Identify shipped finished goods:** For units already shipped, prepare a device history record (DHR) extract for the quality team. They will assess whether a customer notification or field action is required. +4. **Re-schedule all affected work orders:** These are now blocked. Remove them from the active schedule. Calculate the impact on customer deliveries. The 14 work orders represent significant production volume — their removal creates a capacity surplus at some work centres and a delivery shortfall. +5. **Fill the capacity gap:** Pull forward work orders for unaffected product families. Keep the constraint running on unaffected work. The quarantine should not idle the constraint if other schedulable work exists. +6. **Monitor the supplier investigation:** Request daily updates. If the material passes testing (false alarm), the quarantined WIP can be released and re-inserted into the schedule. If the material fails, transition from quarantine to scrap/rework disposition. +7. **Schedule replacement production:** If the quarantined material is confirmed non-conforming, replacement raw material must be ordered and new work orders created. Calculate the lead time for replacement material + production to meet customer delivery obligations. + +**Documentation Required:** +- Full forward lot trace from Heat #A7742 +- Quarantine records for all WIP and finished goods +- Shipped goods report for quality team +- Revised schedule excluding quarantined work orders +- Replacement material purchase order +- Customer notification drafts (for quality team review) +- Daily supplier investigation status updates + +**Resolution Timeline:** +- Hour 0: Supplier advisory received +- Hour 0–2: Lot trace completed, scope of exposure quantified +- Hour 2–4: All affected WIP quarantined, schedule revised +- Hour 4–8: Customer delivery impact assessed, replacement material ordered +- Day 2–7: Awaiting supplier test results, running unaffected production +- Day 7+: Disposition decision (release or scrap), recovery schedule published + +--- + +### Edge Case 14: Power Curtailment Order During Peak Production + +**Situation:** +During a summer heat wave, the regional utility issues a mandatory curtailment order requiring the plant to reduce electrical consumption by 30% during peak hours (1:00 PM – 7:00 PM) for the next 5 business days. The plant's major electrical loads are: arc welding stations (35% of load), CNC machining (25%), HVAC/lighting (20%), and electric furnaces (20%). The constraint work centre is a CNC machining cell. Shutting down any production equipment during peak hours will reduce output. Non-compliance with the curtailment order carries fines of $50,000/day. + +**Expert Approach:** +1. **Load analysis:** Identify which equipment can be shut down during peak hours with the least production impact. HVAC cannot be fully shut down (heat stress safety risk for operators), but setpoint can be raised by 3–4°F to reduce load by ~30% of HVAC consumption. +2. **Shift heavy loads to off-peak:** Move arc welding operations to the early morning (5:00 AM – 1:00 PM) and evening (7:00 PM – 1:00 AM) shifts. Welding is labour-intensive but electrically heavy — shifting it avoids most of the curtailment window. +3. **Protect the constraint:** CNC machining is the constraint. Calculate whether CNC can run during the curtailment window if welding and furnaces are offline. If CNC alone is within the 70% power allowance, keep CNC running and idle the other major loads. +4. **Electric furnace scheduling:** Pre-heat and pre-melt in the morning. Hold molten metal in insulated vessels during the curtailment window (thermal mass carries 4–6 hours). Resume furnace operations at 7:00 PM. +5. **Reschedule the week:** Create two sub-schedules: + - Off-peak (5:00 AM – 1:00 PM and 7:00 PM – 5:00 AM): Full production, all work centres operational. + - Peak curtailment (1:00 PM – 7:00 PM): Constraint (CNC) running, welding and furnaces offline, non-electrical operations (manual assembly, inspection, packaging, material prep) active. +6. **Labour adjustment:** Operators who normally work day shift welding are reassigned to manual operations during curtailment hours, then brought back to welding on an adjusted schedule. Check overtime implications — some operators may need split shifts. +7. **Customer impact:** Calculate the throughput reduction from 5 days of restricted production. If the constraint runs during curtailment but non-constraints do not, the throughput impact may be small (constraint is the bottleneck). Quantify and notify affected customers if any delivery dates slip. + +**Documentation Required:** +- Load analysis by equipment and time window +- Curtailment compliance plan (submitted to utility if required) +- Revised daily schedules for the 5-day curtailment period +- Labour reassignment plan +- Customer delivery impact assessment +- Cost analysis: compliance plan cost vs. $50K/day non-compliance fine + +--- + +### Edge Case 15: Concurrent Preventive Maintenance and Rush Order + +**Situation:** +A stamping plant's quarterly preventive maintenance (PM) on the 600-ton press (the constraint) is scheduled for this Saturday, requiring a full 10-hour shutdown for die inspection, hydraulic system service, and electrical control calibration. On Thursday afternoon, the plant receives a rush order from its largest customer: 5,000 brackets due Wednesday of next week. The 600-ton press is the only machine that can stamp these brackets. The job requires 18 hours of press time. Without the Saturday PM, the bracket run can start Friday evening and finish Sunday afternoon, meeting the Wednesday deadline easily. With the PM, the bracket run cannot start until Sunday afternoon and will finish Tuesday, cutting it dangerously close to the Wednesday ship deadline. + +**Why It's Tricky:** +Skipping or deferring PM on the constraint is a high-risk gamble. The PM schedule exists because the 600-ton press has a history of hydraulic seal failures when PM intervals stretch beyond the quarterly cycle. A hydraulic failure during the bracket run would be catastrophic — potentially damaging the die (a $45,000 asset), scrapping in-process work, and causing multiple days of unplanned downtime. + +**Expert Approach:** +1. **Do not skip the PM.** The expected cost of a hydraulic failure (die damage + scrap + 3–5 days unplanned downtime + customer penalties) far exceeds the cost of any workaround. +2. **Can the PM be compressed?** Consult maintenance: can the 10-hour PM be reduced to 6 hours by parallelising activities (two maintenance crews working simultaneously on hydraulics and electrical)? If so, the press is available Saturday evening instead of Sunday morning, giving an extra 8+ hours for the bracket run. +3. **Can the PM be moved earlier?** If PM starts Friday night instead of Saturday morning, the press is available by Saturday morning. Friday night PM means cancelling Friday night production — calculate the lost production (probably 1 shift of lower-priority work) vs. the benefit of earlier bracket availability. +4. **Can the bracket run be accelerated?** Check if the die can be modified for a 2-out configuration (stamping 2 brackets per stroke instead of 1). If tooling supports this and first-piece quality validates, the 18-hour job drops to 10 hours. This is a production engineering question, not just a scheduling question. +5. **Recommended plan:** Move PM to Friday 10:00 PM – Saturday 8:00 AM (compressed to 10 hours or less). Start bracket run Saturday 8:00 AM. At 18 hours, the run finishes Sunday 2:00 AM. Ship Monday for Wednesday delivery — comfortable margin. +6. **Backup plan:** If PM cannot be compressed or moved earlier, start the bracket run Sunday afternoon, run through Sunday night and Monday day shift (18 hours completion by Monday evening), and ship Tuesday for Wednesday delivery. This is tight but feasible. Add an overtime shift Monday evening as insurance. + +**Documentation Required:** +- PM schedule analysis showing compression/shift options +- Bracket run time calculation and earliest-start-time scenarios +- Risk assessment of PM deferral (not recommended, but documented to explain the decision) +- Customer delivery confirmation with the chosen plan +- Maintenance crew availability for compressed PM schedule + +**Resolution Timeline:** +- Thursday PM: Rush order received +- Thursday PM + 2 hours: PM compression/shift analysis completed +- Thursday end-of-day: Decision made, revised schedule published +- Friday night or Saturday AM: PM begins +- Saturday AM or PM: Bracket run begins +- Sunday or Monday: Bracket run complete +- Monday–Tuesday: Ship for Wednesday delivery + +--- + +### Edge Case 16: Multi-Site Load Balancing Under Capacity Crunch + +**Situation:** +A packaging company operates two plants 90 miles apart. Plant A specialises in rigid plastic containers (thermoforming + printing) and Plant B specialises in flexible pouches (form-fill-seal). Both plants have secondary capability in the other's specialty, but at 30–40% lower throughput rates. Plant A's thermoforming constraint is at 97% utilisation for the next 3 weeks. Plant B's form-fill-seal line is at 72%. A key customer (national retailer) has just increased their Q4 order for rigid containers by 25%, pushing Plant A's projected utilisation to 122%. + +**Why It's Tricky:** +Moving rigid container production to Plant B is technically possible but operationally complex: different tooling must be transferred, operator cross-training is limited, Plant B's rigid container quality history is weaker, and the customer has approved Plant A as the manufacturing site (switching sites may require customer re-qualification, especially for food-contact packaging). + +**Common Mistake:** +Accepting all incremental volume at Plant A and planning to "make it work" with overtime. At 122% utilisation, even maximum overtime only reaches ~108%, creating an inevitable 14% shortfall. Or refusing the incremental order without exploring Plant B as an option. + +**Expert Approach:** +1. **Quantify the overflow precisely:** Plant A needs 22% more capacity = 26.4 hours/week over 3 weeks = 79.2 total overflow hours. +2. **Assess Plant A's maximum realistic capacity:** Standard (120 hrs/week) + Saturday OT (16 hrs) + reduced changeovers (estimated 4 hrs recovery through better sequencing) = 140 hrs/week max. At 122% requirement = 146.4 hrs needed. Plant A can deliver 140 hrs, shortfall = 6.4 hrs/week = 19.2 hours over 3 weeks. +3. **Assess Plant B's absorption capacity:** Plant B's rigid container capability runs at 70% of Plant A's throughput. 19.2 hours of Plant A work = 27.4 hours at Plant B's rate. Plant B has 33.6 hours of available capacity (120 × 28% headroom) — it can absorb the overflow. +4. **Customer qualification:** Contact the customer's quality team to determine whether a temporary site switch requires re-qualification. For food-contact packaging, the answer is usually yes for a new site, but may be waived if both plants hold the same certifications (SQF, BRC, FDA registration) and use identical raw materials. +5. **Tooling transfer plan:** Which moulds and print plates need to move to Plant B? What is the transfer time (transport + setup + qualification runs at Plant B)? Plan for 2–3 days of transfer activity before Plant B can begin producing. +6. **Quality safeguard:** Assign Plant A's quality supervisor to Plant B for the first 2 days of the overflow production run. First-article inspection with full dimensional check before releasing production quantities. +7. **Logistics:** Coordinate shipping from Plant B to the customer's DC. If the customer expects a single point of shipment, Plant B's output may need to be consolidated at Plant A before shipping. + +**Documentation Required:** +- Capacity analysis for both plants over the 3-week horizon +- Overflow volume calculation and Plant B absorption plan +- Customer qualification requirement assessment +- Tooling transfer schedule +- Quality plan for Plant B overflow production +- Logistics coordination plan +- Cost comparison: overtime at Plant A vs. transfer + production at Plant B + +--- + +### Edge Case 17: Seasonal Product Transition with Shared Tooling + +**Situation:** +A consumer goods manufacturer produces both summer products (portable fans, outdoor lighting) and winter products (space heaters, humidifiers) on shared injection moulding and assembly lines. The seasonal transition begins in August: summer products wind down while winter products ramp up. Both product families share 6 of the plant's 10 injection moulding machines, requiring complete mould changes (4–6 hours per machine). The transition must happen while simultaneously filling the last summer orders (end-of-season clearance orders from retailers, due by August 31) and beginning the winter build-up (first winter shipments due September 15). + +**Why It's Tricky:** +During the transition period, the plant needs to produce both summer and winter products on the same machines. Every mould change consumes 4–6 hours of production capacity. If you transition all 6 machines at once, you lose 24–36 hours of capacity in a single week — during the highest-demand period. If you transition one machine at a time, you maintain more capacity but stretch the transition over 3+ weeks, during which the schedule is constantly in flux with different machines running different product families. + +**Expert Approach:** +1. **Phase the transition by machine and demand priority:** + - Weeks 1–2 (Aug 1–14): Keep all 6 machines on summer products. Fill all remaining summer orders. + - Week 3 (Aug 15–21): Transition 2 machines to winter moulds. These begin producing the highest-priority winter products. + - Week 4 (Aug 22–28): Transition 2 more machines. Now 4 winter, 2 summer. + - Week 5 (Aug 29 – Sep 4): Transition final 2 machines. All 6 on winter products. +2. **Priority sequencing during transition:** + - Summer machines in Weeks 3–4 focus exclusively on committed retailer orders with firm due dates. No speculative production. + - Winter machines in Weeks 3–4 focus on long-lead-time components that downstream assembly needs by September 15. +3. **Mould change scheduling:** Schedule all mould changes for Friday PM or Saturday AM, when the changeover downtime has the least impact on committed production (assuming the plant runs Mon–Fri with Saturday overtime available). +4. **Buffer management:** Build 1 week of safety stock on critical summer components before Week 3 begins. This buffers downstream assembly from any transition-related disruptions on the moulding machines. +5. **Labour coordination:** Mould changes require skilled tooling technicians. Ensure technician availability matches the changeover schedule — do not schedule 4 mould changes on the same day with only 2 technicians. + +**Documentation Required:** +- Phased transition schedule showing machine-by-product assignment per week +- Summer order backlog with due dates and machine requirements +- Winter build-up schedule with component lead times +- Mould change schedule with technician assignments +- Safety stock build plan for transition buffer +- Post-transition capacity verification (all winter moulds qualified and running at standard rates) + +**Resolution Timeline:** +- Aug 1: Transition plan published to all departments +- Aug 1–14: Summer production, safety stock build +- Aug 15: First 2 machines transition — winter production begins +- Aug 22: Second pair transitions +- Aug 29: Final pair transitions — full winter production +- Sep 5: Post-transition review — all machines at standard winter rates +- Sep 15: First winter shipments + +--- + +## Summary: Edge Case Pattern Recognition + +Experienced production schedulers recognise recurring patterns across these edge cases: + +| Pattern | Key Indicator | First Response | +|---|---|---| +| **Constraint shift** | WIP moving from one queue to another unexpectedly | Re-identify the constraint. Don't re-sequence unless shift persists. | +| **Single-point-of-failure** | One operator, one machine, one supplier | Cross-train, qualify alternates, dual-source before the failure occurs. | +| **Commercial vs. physical conflict** | Multiple customers need the same scarce resource | Quantify the tradeoff. Present options. Let management decide. | +| **Data integrity failure** | MRP generating implausible demand, phantom inventory | Verify at the source. Trace the data. Fix the root before acting on bad data. | +| **Cascading quality issue** | Defect detected late, affecting multiple production stages | Full containment first, rework assessment second, schedule recovery third. | +| **External constraint imposed** | Utility curtailment, regulatory stop, weather | Protect the constraint. Shift flexible operations around the restriction. | +| **Transition complexity** | Product mix changing, seasonal changeover, NPI | Phase the transition. Buffer between old and new. Don't try to flip everything at once. | + +The common thread: **never sacrifice the constraint's output for a non-constraint problem.** Every decision should be evaluated through the lens of: "Does this protect or harm throughput at the constraint?" If a disruption does not affect the constraint (directly or through buffer penetration), it is lower priority regardless of how visible or noisy it is on the shop floor. diff --git a/web-app/public/skills/programmatic-seo/SKILL.md b/web-app/public/skills/programmatic-seo/SKILL.md index 28a2b0c1..dd0cf288 100644 --- a/web-app/public/skills/programmatic-seo/SKILL.md +++ b/web-app/public/skills/programmatic-seo/SKILL.md @@ -1,6 +1,6 @@ --- name: programmatic-seo -description: ">" +description: > Design and evaluate programmatic SEO strategies for creating SEO-driven pages at scale using templates and structured data. Use when the user mentions programmatic SEO, pages at scale, template pages, directory pages, location pages, diff --git a/web-app/public/skills/python-pro/SKILL.md b/web-app/public/skills/python-pro/SKILL.md index 97430766..d4c64386 100644 --- a/web-app/public/skills/python-pro/SKILL.md +++ b/web-app/public/skills/python-pro/SKILL.md @@ -1,6 +1,7 @@ --- name: python-pro -description: "Master Python 3.12+ with modern features, async programming," +description: | + Master Python 3.12+ with modern features, async programming, performance optimization, and production-ready practices. Expert in the latest Python ecosystem including uv, ruff, pydantic, and FastAPI. Use PROACTIVELY for Python development, optimization, or advanced Python patterns. diff --git a/web-app/public/skills/quality-nonconformance/SKILL.md b/web-app/public/skills/quality-nonconformance/SKILL.md new file mode 100644 index 00000000..e0a2f8ef --- /dev/null +++ b/web-app/public/skills/quality-nonconformance/SKILL.md @@ -0,0 +1,250 @@ +--- +name: quality-nonconformance +description: > + Codified expertise for quality control, non-conformance investigation, root + cause analysis, corrective action, and supplier quality management in + regulated manufacturing. Informed by quality engineers with 15+ years + experience across FDA, IATF 16949, and AS9100 environments. Includes NCR + lifecycle management, CAPA systems, SPC interpretation, and audit methodology. + Use when investigating non-conformances, performing root cause analysis, + managing CAPAs, interpreting SPC data, or handling supplier quality issues. +license: Apache-2.0 +version: 1.0.0 +homepage: https://github.com/evos-ai/evos-capabilities +risk: safe +source: https://github.com/ai-evos/agent-skills +metadata: + author: evos + clawdbot: + emoji: "🔍" +--- + +## When to Use + +Use this skill when investigating product defects or process deviations, performing root cause analysis (RCA), managing Corrective and Preventive Actions (CAPA), interpreting Statistical Process Control (SPC) data, or auditing supplier quality. + +# Quality & Non-Conformance Management + +## Role and Context + +You are a senior quality engineer with 15+ years in regulated manufacturing environments — FDA 21 CFR 820 (medical devices), IATF 16949 (automotive), AS9100 (aerospace), and ISO 13485 (medical devices). You manage the full non-conformance lifecycle from incoming inspection through final disposition. Your systems include QMS (eQMS platforms like MasterControl, ETQ, Veeva), SPC software (Minitab, InfinityQS), ERP (SAP QM, Oracle Quality), CMM and metrology equipment, and supplier portals. You sit at the intersection of manufacturing, engineering, procurement, regulatory, and customer quality. Your judgment calls directly affect product safety, regulatory standing, production throughput, and supplier relationships. + +## Core Knowledge + +### NCR Lifecycle + +Every non-conformance follows a controlled lifecycle. Skipping steps creates audit findings and regulatory risk: + +- **Identification:** Anyone can initiate. Record: who found it, where (incoming, in-process, final, field), what standard/spec was violated, quantity affected, lot/batch traceability. Tag or quarantine nonconforming material immediately — no exceptions. Physical segregation with red-tag or hold-tag in a designated MRB area. Electronic hold in ERP to prevent inadvertent shipment. +- **Documentation:** NCR number assigned per your QMS numbering scheme. Link to part number, revision, PO/work order, specification clause violated, measurement data (actuals vs. tolerances), photographs, and inspector ID. For FDA-regulated products, records must satisfy 21 CFR 820.90; for automotive, IATF 16949 §8.7. +- **Investigation:** Determine scope — is this an isolated piece or a systemic lot issue? Check upstream and downstream: other lots from the same supplier shipment, other units from the same production run, WIP and finished goods inventory from the same period. Containment actions must happen before root cause analysis begins. +- **Disposition via MRB (Material Review Board):** The MRB typically includes quality, engineering, and manufacturing representatives. For aerospace (AS9100), the customer may need to participate. Disposition options: + - **Use-as-is:** Part does not meet drawing but is functionally acceptable. Requires engineering justification (concession/deviation). In aerospace, requires customer approval per AS9100 §8.7.1. In automotive, customer notification is typically required. Document the rationale — "because we need the parts" is not a justification. + - **Rework:** Bring the part into conformance using an approved rework procedure. The rework instruction must be documented, and the reworked part must be re-inspected to the original specification. Track rework costs. + - **Repair:** Part will not fully meet the original specification but will be made functional. Requires engineering disposition and often customer concession. Different from rework — repair accepts a permanent deviation. + - **Return to Vendor (RTV):** Issue a Supplier Corrective Action Request (SCAR) or CAR. Debit memo or replacement PO. Track supplier response within agreed timelines. Update supplier scorecard. + - **Scrap:** Document scrap with quantity, cost, lot traceability, and authorized scrap approval (often requires management sign-off above a dollar threshold). For serialized or safety-critical parts, witness destruction. + +### Root Cause Analysis + +Stopping at symptoms is the most common failure mode in quality investigations: + +- **5 Whys:** Simple, effective for straightforward process failures. Limitation: assumes a single linear causal chain. Fails on complex, multi-factor problems. Each "why" must be verified with data, not opinion — "Why did the dimension drift?" → "Because the tool wore" is only valid if you measured tool wear. +- **Ishikawa (Fishbone) Diagram:** Use the 6M framework (Man, Machine, Material, Method, Measurement, Mother Nature/Environment). Forces consideration of all potential cause categories. Most useful as a brainstorming framework to prevent premature convergence on a single cause. Not a root cause tool by itself — it generates hypotheses that need verification. +- **Fault Tree Analysis (FTA):** Top-down, deductive. Start with the failure event and decompose into contributing causes using AND/OR logic gates. Quantitative when failure rate data is available. Required or expected in aerospace (AS9100) and medical device (ISO 14971 risk analysis) contexts. Most rigorous method but resource-intensive. +- **8D Methodology:** Team-based, structured problem-solving. D0: Symptom recognition and emergency response. D1: Team formation. D2: Problem definition (IS/IS-NOT). D3: Interim containment. D4: Root cause identification (use fishbone + 5 Whys within 8D). D5: Corrective action selection. D6: Implementation. D7: Prevention of recurrence. D8: Team recognition. Automotive OEMs (GM, Ford, Stellantis) expect 8D reports for significant supplier quality issues. +- **Red flags that you stopped at symptoms:** Your "root cause" contains the word "error" (human error is never a root cause — why did the system allow the error?), your corrective action is "retrain the operator" (training alone is the weakest corrective action), or your root cause matches the problem statement reworded. + +### CAPA System + +CAPA is the regulatory backbone. FDA cites CAPA deficiencies more than any other subsystem: + +- **Initiation:** Not every NCR requires a CAPA. Triggers: repeat non-conformances (same failure mode 3+ times), customer complaints, audit findings, field failures, trend analysis (SPC signals), regulatory observations. Over-initiating CAPAs dilutes resources and creates closure backlogs. Under-initiating creates audit findings. +- **Corrective Action vs. Preventive Action:** Corrective addresses an existing non-conformance and prevents its recurrence. Preventive addresses a potential non-conformance that hasn't occurred yet — typically identified through trend analysis, risk assessment, or near-miss events. FDA expects both; don't conflate them. +- **Writing Effective CAPAs:** The action must be specific, measurable, and address the verified root cause. Bad: "Improve inspection procedures." Good: "Add torque verification step at Station 12 with calibrated torque wrench (±2%), documented on traveler checklist WI-4401 Rev C, effective by 2025-04-15." Every CAPA must have an owner, a target date, and defined evidence of completion. +- **Verification vs. Validation of Effectiveness:** Verification confirms the action was implemented as planned (did we install the poka-yoke fixture?). Validation confirms the action actually prevented recurrence (did the defect rate drop to zero over 90 days of production data?). FDA expects both. Closing a CAPA at verification without validation is a common audit finding. +- **Closure Criteria:** Objective evidence that the corrective action was implemented AND effective. Minimum effectiveness monitoring period: 90 days for process changes, 3 production lots for material changes, or the next audit cycle for system changes. Document the effectiveness data — charts, rejection rates, audit results. +- **Regulatory Expectations:** FDA 21 CFR 820.198 (complaint handling) and 820.90 (nonconforming product) feed into 820.100 (CAPA). IATF 16949 §10.2.3-10.2.6. AS9100 §10.2. ISO 13485 §8.5.2-8.5.3. Each standard has specific documentation and timing expectations. + +### Statistical Process Control (SPC) + +SPC separates signal from noise. Misinterpreting charts causes more problems than not charting at all: + +- **Chart Selection:** X-bar/R for continuous data with subgroups (n=2-10). X-bar/S for subgroups n>10. Individual/Moving Range (I-MR) for continuous data with subgroup n=1 (batch processes, destructive testing). p-chart for proportion defective (variable sample size). np-chart for count of defectives (fixed sample size). c-chart for count of defects per unit (fixed opportunity area). u-chart for defects per unit (variable opportunity area). +- **Capability Indices:** Cp measures process spread vs. specification width (potential capability). Cpk adjusts for centering (actual capability). Pp/Ppk use overall variation (long-term) vs. Cp/Cpk which use within-subgroup variation (short-term). A process with Cp=2.0 but Cpk=0.8 is capable but not centered — fix the mean, not the variation. Automotive (IATF 16949) typically requires Cpk ≥ 1.33 for established processes, Ppk ≥ 1.67 for new processes. +- **Western Electric Rules (signals beyond control limits):** Rule 1: One point beyond 3σ. Rule 2: Nine consecutive points on one side of the center line. Rule 3: Six consecutive points steadily increasing or decreasing. Rule 4: Fourteen consecutive points alternating up and down. Rule 1 demands immediate action. Rules 2-4 indicate systematic causes requiring investigation before the process goes out of spec. +- **The Over-Adjustment Problem:** Reacting to common cause variation by tweaking the process increases variation — this is tampering. If the chart shows a stable process within control limits but individual points "look high," do not adjust. Only adjust for special cause signals confirmed by the Western Electric rules. +- **Common vs. Special Cause:** Common cause variation is inherent to the process — reducing it requires fundamental process changes (better equipment, different material, environmental controls). Special cause variation is assignable to a specific event — a worn tool, a new raw material lot, an untrained operator on second shift. SPC's primary function is detecting special causes quickly. + +### Incoming Inspection + +- **AQL Sampling Plans (ANSI/ASQ Z1.4 / ISO 2859-1):** Determine inspection level (I, II, III — Level II is standard), lot size, AQL value, and sample size code letter. Tightened inspection: switch after 2 of 5 consecutive lots rejected. Normal: default. Reduced: switch after 10 consecutive lots accepted AND production stable. Critical defects: AQL = 0 with appropriate sample size. Major defects: typically AQL 1.0-2.5. Minor defects: typically AQL 2.5-6.5. +- **LTPD (Lot Tolerance Percent Defective):** The defect level the plan is designed to reject. AQL protects the producer (low risk of rejecting good lots). LTPD protects the consumer (low risk of accepting bad lots). Understanding both sides is critical for communicating inspection risk to management. +- **Skip-Lot Qualification:** After a supplier demonstrates consistent quality (typically 10+ consecutive lots accepted at normal inspection), reduce frequency to inspecting every 2nd, 3rd, or 5th lot. Revert immediately upon any rejection. Requires formal qualification criteria and documented decision. +- **Certificate of Conformance (CoC) Reliance:** When to trust supplier CoCs vs. performing incoming inspection: new supplier = always inspect; qualified supplier with history = CoC + reduced verification; critical/safety dimensions = always inspect regardless of history. CoC reliance requires a documented agreement and periodic audit verification (audit the supplier's final inspection process, not just the paperwork). + +### Supplier Quality Management + +- **Audit Methodology:** Process audits assess how work is done (observe, interview, sample). System audits assess QMS compliance (document review, record sampling). Product audits verify specific product characteristics. Use a risk-based audit schedule — high-risk suppliers annually, medium biennially, low every 3 years plus cause-based. Announce audits for system assessments; unannounced audits for process verification when performance concerns exist. +- **Supplier Scorecards:** Measure PPM (parts per million defective), on-time delivery, SCAR response time, SCAR effectiveness (recurrence rate), and lot acceptance rate. Weight the metrics by business impact. Share scorecards quarterly. Scores drive inspection level adjustments, business allocation, and ASL status. +- **Corrective Action Requests (CARs/SCARs):** Issue for each significant non-conformance or repeated minor non-conformances. Expect 8D or equivalent root cause analysis. Set response deadline (typically 10 business days for initial response, 30 days for full corrective action plan). Follow up on effectiveness verification. +- **Approved Supplier List (ASL):** Entry requires qualification (first article, capability study, system audit). Maintenance requires ongoing performance meeting scorecard thresholds. Removal is a significant business decision requiring procurement, engineering, and quality agreement plus a transition plan. Provisional status (approved with conditions) is useful for suppliers under improvement plans. +- **Develop vs. Switch Decisions:** Supplier development (investment in training, process improvement, tooling) makes sense when: the supplier has unique capability, switching costs are high, the relationship is otherwise strong, and the quality gaps are addressable. Switching makes sense when: the supplier is unwilling to invest, the quality trend is deteriorating despite CARs, or alternative qualified sources exist with lower total cost of quality. + +### Regulatory Frameworks + +- **FDA 21 CFR 820 (QSR):** Covers medical device quality systems. Key sections: 820.90 (nonconforming product), 820.100 (CAPA), 820.198 (complaint handling), 820.250 (statistical techniques). FDA auditors specifically look at CAPA system effectiveness, complaint trending, and whether root cause analysis is rigorous. +- **IATF 16949 (Automotive):** Adds customer-specific requirements on top of ISO 9001. Control plans, PPAP (Production Part Approval Process), MSA (Measurement Systems Analysis), 8D reporting, special characteristics management. Customer notification required for process changes and non-conformance disposition. +- **AS9100 (Aerospace):** Adds requirements for product safety, counterfeit part prevention, configuration management, first article inspection (FAI per AS9102), and key characteristic management. Customer approval required for use-as-is dispositions. OASIS database for supplier management. +- **ISO 13485 (Medical Devices):** Harmonized with FDA QSR but with European regulatory alignment. Emphasis on risk management (ISO 14971), traceability, and design controls. Clinical investigation requirements feed into non-conformance management. +- **Control Plans:** Define inspection characteristics, methods, frequencies, sample sizes, reaction plans, and responsible parties for each process step. Required by IATF 16949 and good practice universally. Must be a living document updated when processes change. + +### Cost of Quality + +Build the business case for quality investment using Juran's COQ model: + +- **Prevention costs:** Training, process validation, design reviews, supplier qualification, SPC implementation, poka-yoke fixtures. Typically 5-10% of total COQ. Every dollar invested here returns $10-$100 in failure cost avoidance. +- **Appraisal costs:** Incoming inspection, in-process inspection, final inspection, testing, calibration, audit costs. Typically 20-25% of total COQ. +- **Internal failure costs:** Scrap, rework, re-inspection, MRB processing, production delays due to non-conformances, root cause investigation labor. Typically 25-40% of total COQ. +- **External failure costs:** Customer returns, warranty claims, field service, recalls, regulatory actions, liability exposure, reputation damage. Typically 25-40% of total COQ but most volatile and highest per-incident cost. + +## Decision Frameworks + +### NCR Disposition Decision Logic + +Evaluate in this sequence — the first path that applies governs the disposition: + +1. **Safety/regulatory critical:** If the non-conformance affects a safety-critical characteristic or regulatory requirement → do not use-as-is. Rework if possible to full conformance, otherwise scrap. No exceptions without formal engineering risk assessment and, where required, regulatory notification. +2. **Customer-specific requirements:** If the customer specification is tighter than the design spec and the part meets design but not customer requirements → contact customer for concession before disposing. Automotive and aerospace customers have explicit concession processes. +3. **Functional impact:** Engineering evaluates whether the non-conformance affects form, fit, or function. If no functional impact and within material review authority → use-as-is with documented engineering justification. If functional impact exists → rework or scrap. +4. **Reworkability:** If the part can be brought into full conformance through an approved rework process → rework. Verify rework cost vs. replacement cost. If rework cost exceeds 60% of replacement cost, scrap is usually more economical. +5. **Supplier accountability:** If the non-conformance is supplier-caused → RTV with SCAR. Exception: if production cannot wait for replacement parts, use-as-is or rework may be needed with cost recovery from the supplier. + +### RCA Method Selection + +- **Single-event, simple causal chain:** 5 Whys. Budget: 1-2 hours. +- **Single-event, multiple potential cause categories:** Ishikawa + 5 Whys on the most likely branches. Budget: 4-8 hours. +- **Recurring issue, process-related:** 8D with full team. Budget: 20-40 hours across D0-D8. +- **Safety-critical or high-severity event:** Fault Tree Analysis with quantitative risk assessment. Budget: 40-80 hours. Required for aerospace product safety events and medical device post-market analysis. +- **Customer-mandated format:** Use whatever the customer requires (most automotive OEMs mandate 8D). + +### CAPA Effectiveness Verification + +Before closing any CAPA, verify: + +1. **Implementation evidence:** Documented proof the action was completed (updated work instruction with revision, installed fixture with validation, modified inspection plan with effective date). +2. **Monitoring period data:** Minimum 90 days of production data, 3 consecutive production lots, or one full audit cycle — whichever provides the most meaningful evidence. +3. **Recurrence check:** Zero recurrences of the specific failure mode during the monitoring period. If recurrence occurs, the CAPA is not effective — reopen and re-investigate. Do not close and open a new CAPA for the same issue. +4. **Leading indicator review:** Beyond the specific failure, have related metrics improved? (e.g., overall PPM for that process, customer complaint rate for that product family). + +### Inspection Level Adjustment + +| Condition | Action | +| ---------------------------------------------- | ----------------------------------------------- | +| New supplier, first 5 lots | Tightened inspection (Level III or 100%) | +| 10+ consecutive lots accepted at normal | Qualify for reduced or skip-lot | +| 1 lot rejected under reduced inspection | Revert to normal immediately | +| 2 of 5 consecutive lots rejected under normal | Switch to tightened | +| 5 consecutive lots accepted under tightened | Revert to normal | +| 10 consecutive lots rejected under tightened | Suspend supplier; escalate to procurement | +| Customer complaint traced to incoming material | Revert to tightened regardless of current level | + +### Supplier Corrective Action Escalation + +| Stage | Trigger | Action | Timeline | +| --------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | +| Level 1: SCAR issued | Single significant NC or 3+ minor NCs in 90 days | Formal SCAR requiring 8D response | 10 days for response, 30 for implementation | +| Level 2: Supplier on watch | SCAR not responded to in time, or corrective action not effective | Increased inspection, supplier on probation, procurement notified | 60 days to demonstrate improvement | +| Level 3: Controlled shipping | Continued quality failures during watch period | Supplier must submit inspection data with each shipment; or third-party sort at supplier's expense | 90 days to demonstrate sustained improvement | +| Level 4: New source qualification | No improvement under controlled shipping | Initiate alternate supplier qualification; reduce business allocation | Qualification timeline (3-12 months depending on industry) | +| Level 5: ASL removal | Failure to improve or unwillingness to invest | Formal removal from Approved Supplier List; transition all parts | Complete transition before final PO | + +## Key Edge Cases + +These are situations where the obvious approach is wrong. Brief summaries here — see [edge-cases.md](references/edge-cases.md) for full analysis. + +1. **Customer-reported field failure with no internal detection:** Your inspection and testing passed this lot, but customer field data shows failures. The instinct is to question the customer's data — resist it. Check whether your inspection plan covers the actual failure mode. Often, field failures expose gaps in test coverage rather than test execution errors. + +2. **Supplier audit reveals falsified Certificates of Conformance:** The supplier has been submitting CoCs with fabricated test data. Quarantine all material from that supplier immediately, including WIP and finished goods. This is a regulatory reportable event in aerospace (counterfeit prevention per AS9100) and potentially in medical devices. The scale of the containment drives the response, not the individual NCR. + +3. **SPC shows process in-control but customer complaints are rising:** The chart is stable within control limits, but the customer's assembly process is sensitive to variation within your spec. Your process is "capable" by the numbers but not capable enough. This requires customer collaboration to understand the true functional requirement, not just a spec review. + +4. **Non-conformance discovered on already-shipped product:** Containment must extend to the customer's incoming stock, WIP, and potentially their customers. The speed of notification depends on safety risk — safety-critical issues require immediate customer notification, others can follow the standard process with urgency. + +5. **CAPA that addresses a symptom, not the root cause:** The defect recurs after CAPA closure. Before reopening, verify the original root cause analysis — if the root cause was "operator error" and the corrective action was "retrain," neither the root cause nor the action was adequate. Start the RCA over with the assumption the first investigation was insufficient. + +6. **Multiple root causes for a single non-conformance:** A single defect results from the interaction of machine wear, material lot variation, and a measurement system limitation. The 5 Whys forces a single chain — use Ishikawa or FTA to capture the interaction. Corrective actions must address all contributing causes; fixing only one may reduce frequency but won't eliminate the failure mode. + +7. **Intermittent defect that cannot be reproduced on demand:** Cannot reproduce ≠ does not exist. Increase sample size and monitoring frequency. Check for environmental correlations (shift, ambient temperature, humidity, vibration from adjacent equipment). Component of Variation studies (Gauge R&R with nested factors) can reveal intermittent measurement system contributions. + +8. **Non-conformance discovered during a regulatory audit:** Do not attempt to minimize or explain away. Acknowledge the finding, document it in the audit response, and treat it as you would any NCR — with a formal investigation, root cause analysis, and CAPA. Auditors specifically test whether your system catches what they find; demonstrating a robust response is more valuable than pretending it's an anomaly. + +## Communication Patterns + +### Tone Calibration + +Match communication tone to situation severity and audience: + +- **Routine NCR, internal team:** Direct and factual. "NCR-2025-0412: Incoming lot 4471 of part 7832-A has OD measurements at 12.52mm against a 12.45±0.05mm specification. 18 of 50 sample pieces out of spec. Material quarantined in MRB cage, Bay 3." +- **Significant NCR, management reporting:** Summarize impact first — production impact, customer risk, financial exposure — then the details. Managers need to know what it means before they need to know what happened. +- **Supplier notification (SCAR):** Professional, specific, and documented. State the nonconformance, the specification violated, the impact, and the expected response format and timeline. Never accusatory; the data speaks. +- **Customer notification (non-conformance on shipped product):** Lead with what you know, what you've done (containment), what the customer needs to do, and the timeline for full resolution. Transparency builds trust; delay destroys it. +- **Regulatory response (audit finding):** Factual, accountable, and structured per the regulatory expectation (e.g., FDA Form 483 response format). Acknowledge the observation, describe the investigation, state the corrective action, provide evidence of implementation and effectiveness. + +### Key Templates + +Brief templates below. Full versions with variables in [communication-templates.md](references/communication-templates.md). + +**NCR Notification (internal):** Subject: `NCR-{number}: {part_number} — {defect_summary}`. State: what was found, specification violated, quantity affected, current containment status, and initial assessment of scope. + +**SCAR to Supplier:** Subject: `SCAR-{number}: Non-Conformance on PO# {po_number} — Response Required by {date}`. Include: part number, lot, specification, measurement data, quantity affected, impact statement, expected response format. + +**Customer Quality Notification:** Lead with: containment actions taken, product traceability (lot/serial numbers), recommended customer actions, timeline for corrective action, and direct contact for quality engineering. + +## Escalation Protocols + +### Automatic Escalation Triggers + +| Trigger | Action | Timeline | +| ---------------------------------------------- | ------------------------------------------------------------- | --------------- | +| Safety-critical non-conformance | Notify VP Quality and Regulatory immediately | Within 1 hour | +| Field failure or customer complaint | Assign dedicated investigator, notify account team | Within 4 hours | +| Repeat NCR (same failure mode, 3+ occurrences) | Mandatory CAPA initiation, management review | Within 24 hours | +| Supplier falsified documentation | Quarantine all supplier material, notify regulatory and legal | Immediately | +| Non-conformance on shipped product | Initiate customer notification protocol, containment | Within 4 hours | +| Audit finding (external) | Management review, response plan development | Within 48 hours | +| CAPA overdue > 30 days past target | Escalate to Quality Director for resource allocation | Within 1 week | +| NCR backlog exceeds 50 open items | Process review, resource allocation, management briefing | Within 1 week | + +### Escalation Chain + +Level 1 (Quality Engineer) → Level 2 (Quality Supervisor, 4 hours) → Level 3 (Quality Manager, 24 hours) → Level 4 (Quality Director, 48 hours) → Level 5 (VP Quality, 72+ hours or any safety-critical event) + +## Performance Indicators + +Track these metrics weekly and trend monthly: + +| Metric | Target | Red Flag | +| --------------------------------------- | ------------------ | ------------------ | +| NCR closure time (median) | < 15 business days | > 30 business days | +| CAPA on-time closure rate | > 90% | < 75% | +| CAPA effectiveness rate (no recurrence) | > 85% | < 70% | +| Supplier PPM (incoming) | < 500 PPM | > 2,000 PPM | +| Cost of quality (% of revenue) | < 3% | > 5% | +| Internal defect rate (in-process) | < 1,000 PPM | > 5,000 PPM | +| Customer complaint rate (per 1M units) | < 50 | > 200 | +| Aged NCRs (> 30 days open) | < 10% of total | > 25% | + +## Additional Resources + +- For detailed decision frameworks, MRB processes, and SPC decision logic, see [decision-frameworks.md](references/decision-frameworks.md) +- For the comprehensive edge case library with full analysis, see [edge-cases.md](references/edge-cases.md) +- For complete communication templates with variables and tone guidance, see [communication-templates.md](references/communication-templates.md) + +## When to Use + +Use this skill when you need to **run or improve non‑conformance and CAPA processes in regulated manufacturing**: + +- Investigating NCRs, selecting root‑cause methods, and defining MRB dispositions and CAPA actions. +- Designing or auditing CAPA systems, SPC programmes, incoming inspection plans, and supplier quality governance. +- Preparing for, or responding to, customer and regulatory audits (FDA, IATF, AS9100, ISO 13485) that focus on non‑conformance handling and CAPA effectiveness. diff --git a/web-app/public/skills/quality-nonconformance/references/communication-templates.md b/web-app/public/skills/quality-nonconformance/references/communication-templates.md new file mode 100644 index 00000000..b733f4ab --- /dev/null +++ b/web-app/public/skills/quality-nonconformance/references/communication-templates.md @@ -0,0 +1,711 @@ +# Communication Templates — Quality & Non-Conformance Management + +> **Reference Type:** Tier 3 — Load on demand when composing or reviewing quality communications. +> +> **Usage:** Each template includes variable placeholders in `{{double_braces}}` for direct substitution. Templates are organized by audience and situation. Select the template matching your scenario, substitute variables, review tone guidance, and send. + +--- + +## Table of Contents + +1. [NCR Notification (Internal)](#1-ncr-notification-internal) +2. [MRB Disposition Record](#2-mrb-disposition-record) +3. [Corrective Action Request (CAR) to Supplier](#3-corrective-action-request-car-to-supplier) +4. [CAPA Initiation Record](#4-capa-initiation-record) +5. [CAPA Effectiveness Review](#5-capa-effectiveness-review) +6. [Audit Finding Response](#6-audit-finding-response) +7. [Customer Quality Notification](#7-customer-quality-notification) +8. [Supplier Audit Report Summary](#8-supplier-audit-report-summary) +9. [Quality Alert (Internal)](#9-quality-alert-internal) +10. [Management Review Quality Summary](#10-management-review-quality-summary) +11. [Regulatory Agency Response (FDA Form 483)](#11-regulatory-agency-response-fda-form-483) + +--- + +## Variable Reference + +Common variables used across templates: + +| Variable | Description | Example | +|---|---|---| +| `{{ncr_number}}` | Non-conformance report number | `NCR-2025-0412` | +| `{{capa_number}}` | CAPA record number | `CAPA-2025-0023` | +| `{{scar_number}}` | Supplier corrective action request number | `SCAR-2025-0089` | +| `{{part_number}}` | Part number and revision | `7832-A Rev D` | +| `{{part_description}}` | Part description | `Shaft, Output — Titanium` | +| `{{lot_number}}` | Lot or batch number | `LOT-2025-4471` | +| `{{po_number}}` | Purchase order number | `PO-2025-08832` | +| `{{wo_number}}` | Work order number | `WO-2025-1104` | +| `{{serial_numbers}}` | Affected serial numbers (if applicable) | `SN-10042 through SN-10089` | +| `{{supplier_name}}` | Supplier company name | `Precision Castings Corp.` | +| `{{supplier_contact}}` | Supplier quality contact name | `Maria Gonzalez, Quality Manager` | +| `{{customer_name}}` | Customer company name | `MedTech Instruments Inc.` | +| `{{customer_contact}}` | Customer quality contact name | `David Chen, Supplier Quality Engineer` | +| `{{spec_requirement}}` | Specification and requirement violated | `Drawing 7832-A Rev D, Dim A: 12.45 ±0.05mm` | +| `{{actual_values}}` | Measured values of nonconforming product | `12.52mm, 12.54mm, 12.51mm (3 of 50 sample)` | +| `{{quantity_affected}}` | Number of parts affected | `18 of 500 pieces inspected` | +| `{{quantity_total}}` | Total lot quantity | `2,000 pieces` | +| `{{defect_description}}` | Description of the non-conformance | `OD exceeds USL by 0.02-0.04mm` | +| `{{containment_status}}` | Current containment actions | `Material quarantined in MRB cage, Bay 3` | +| `{{our_quality_contact}}` | Internal quality contact | `Sarah Thompson, Quality Engineer` | +| `{{our_quality_email}}` | Internal quality email | `sthompson@company.com` | +| `{{our_quality_phone}}` | Internal quality phone | `(555) 234-5678` | +| `{{our_company}}` | Our company name | `Advanced Manufacturing Solutions` | +| `{{date_discovered}}` | Date non-conformance was discovered | `2025-03-15` | +| `{{response_deadline}}` | Deadline for response | `2025-03-25 (10 business days)` | +| `{{severity_level}}` | NCR severity classification | `Major — Dimensional non-conformance on key characteristic` | + +--- + +## 1. NCR Notification (Internal) + +### When to Use +- Non-conformance identified at incoming inspection, in-process, or final inspection +- Initial notification to affected departments (manufacturing, engineering, procurement, planning) +- Material has been quarantined; disposition pending + +### Tone Guidance +Factual and direct. Internal teams need to know what happened, what the scope is, and what the immediate impact is. No blame, no speculation — data only. Include enough detail for engineering to begin their assessment and for planning to evaluate the production impact. + +### Template + +**Subject:** `{{ncr_number}}: {{part_number}} — {{defect_description}}` + +**To:** Manufacturing Engineering, Production Planning, Procurement (if supplier-related), Quality Manager +**Cc:** Quality file + +--- + +**Non-Conformance Report: {{ncr_number}}** + +**Date Discovered:** {{date_discovered}} +**Discovered By:** {{inspector_name}}, {{inspection_stage}} (incoming / in-process / final) +**Part Number:** {{part_number}} — {{part_description}} +**Lot/Batch:** {{lot_number}} | Work Order: {{wo_number}} | PO: {{po_number}} (if incoming) + +**Non-Conformance Description:** +{{defect_description}} + +**Specification Requirement:** {{spec_requirement}} +**Actual Values:** {{actual_values}} +**Quantity Affected:** {{quantity_affected}} of {{quantity_total}} total lot + +**Containment Status:** +{{containment_status}} + +**Initial Scope Assessment:** +- [ ] Other lots from same supplier/production run checked: {{scope_check_result}} +- [ ] WIP containing this material identified: {{wip_status}} +- [ ] Finished goods containing this material identified: {{fg_status}} +- [ ] Downstream customer shipments containing this material: {{shipped_status}} + +**Production Impact:** +{{production_impact_summary}} (e.g., "Line 3 is waiting on this material for WO-2025-1104; 2-day impact if not dispositioned by Thursday") + +**Requested Action:** +Engineering review of functional impact requested by {{disposition_deadline}}. +MRB meeting scheduled: {{mrb_date_time}}. + +**Quality Contact:** {{our_quality_contact}} | {{our_quality_email}} | {{our_quality_phone}} + +--- + +## 2. MRB Disposition Record + +### When to Use +- Documenting the Material Review Board's disposition decision +- Required for all NCR dispositions that are not straightforward scrap +- Audit-trail document; this is what auditors review + +### Tone Guidance +Formal, precise, and complete. This is a controlled document. Every field must be populated. Engineering justification must be technically sound and specific — not "acceptable per engineering review" but a detailed rationale citing functional requirements. + +### Template + +**MRB DISPOSITION RECORD** + +| Field | Value | +|---|---| +| NCR Number | {{ncr_number}} | +| MRB Date | {{mrb_date}} | +| Part Number / Rev | {{part_number}} | +| Part Description | {{part_description}} | +| Lot/Batch | {{lot_number}} | +| Quantity Affected | {{quantity_affected}} | +| Nonconformance | {{defect_description}} | +| Specification Violated | {{spec_requirement}} | +| Actual Values | {{actual_values}} | + +**Disposition Decision:** ☐ Use-As-Is ☐ Rework ☐ Repair ☐ Return to Vendor ☐ Scrap + +**Engineering Justification (required for Use-As-Is and Repair):** +{{engineering_justification}} + +Example: "The OD measurement of 12.52mm (USL 12.50mm) exceeds the drawing tolerance by 0.02mm. Per engineering analysis EA-2025-0034, this dimension interfaces with bore ID 12.60 +0.05/-0.00mm on mating part 7833-B. Minimum clearance at worst-case stack-up (shaft 12.52mm, bore 12.60mm) is 0.08mm. Assembly requirement per DWG 100-ASSY-Rev C specifies minimum 0.05mm clearance. The 0.08mm clearance meets the functional requirement. No impact to form, fit, or function." + +**Risk Assessment (required for safety-critical parts):** +{{risk_assessment_reference}} (e.g., "Per ISO 14971 risk assessment RA-2025-0012, risk level is acceptable — severity [minor], probability [remote]") + +**Customer Approval (required for aerospace Use-As-Is/Repair):** +☐ Not required (standard/non-regulated) ☐ Requested — Reference: {{customer_approval_ref}} ☐ Approved — Date: {{approval_date}} ☐ Denied + +**Cost Impact:** +| Item | Amount | +|---|---| +| Scrap cost | {{scrap_cost}} | +| Rework labor | {{rework_cost}} | +| Re-inspection | {{reinspect_cost}} | +| Expedite / replacement | {{expedite_cost}} | +| **Total NCR cost** | **{{total_cost}}** | + +**CAPA Required:** ☐ Yes — {{capa_number}} ☐ No — Rationale: {{no_capa_rationale}} + +**MRB Attendees and Signatures:** + +| Name | Department | Signature | Date | +|---|---|---|---| +| {{quality_rep}} | Quality Engineering | | {{date}} | +| {{engineering_rep}} | Design/Product Engineering | | {{date}} | +| {{manufacturing_rep}} | Manufacturing Engineering | | {{date}} | +| {{other_rep}} | {{other_dept}} | | {{date}} | + +--- + +## 3. Corrective Action Request (CAR) to Supplier + +### When to Use +- Significant non-conformance on incoming material traceable to a supplier +- Repeated minor non-conformances from the same supplier (3+ in 90 days) +- Supplier escalation Level 1 (SCAR issuance) + +### Tone Guidance +Professional, specific, and structured. Provide all data the supplier needs to investigate. Set clear expectations for the response format and timeline. Do not be accusatory — present the facts and ask for investigation. The supplier's willingness and quality of response will tell you whether this is a fixable issue or a systemic problem. + +### What NOT to Say +- Do not threaten ASL removal in a first-time CAR (save escalation language for Level 2+) +- Do not speculate on the root cause — that's the supplier's job +- Do not include internal financial impact numbers (the supplier doesn't need to know your downstream costs at this stage) + +### Template + +**Subject:** `SCAR-{{scar_number}}: Non-Conformance on PO# {{po_number}} — Response Required by {{response_deadline}}` + +**To:** {{supplier_contact}}, {{supplier_name}} +**Cc:** {{our_quality_contact}}, Procurement buyer + +--- + +**SUPPLIER CORRECTIVE ACTION REQUEST** + +**SCAR Number:** {{scar_number}} +**Date Issued:** {{date_issued}} +**Response Due:** {{response_deadline}} (initial response with containment + preliminary root cause) +**Full Corrective Action Plan Due:** {{full_response_deadline}} (30 calendar days) + +**Supplier Information:** +- Supplier: {{supplier_name}} +- Supplier Code: {{supplier_code}} +- Contact: {{supplier_contact}} + +**Non-Conformance Details:** +- Part Number: {{part_number}} — {{part_description}} +- PO Number: {{po_number}} +- Lot/Batch: {{lot_number}} +- Quantity Received: {{quantity_total}} +- Quantity Nonconforming: {{quantity_affected}} +- Date Received: {{date_received}} +- Date Non-Conformance Identified: {{date_discovered}} + +**Specification Requirement:** +{{spec_requirement}} + +**Actual Results:** +{{actual_values}} + +**Supporting Documentation Attached:** +- [ ] Inspection report with measurement data +- [ ] Photographs of nonconforming material +- [ ] Drawing excerpt highlighting affected dimension/requirement +- [ ] Copy of your Certificate of Conformance for this lot + +**Impact to Our Operations:** +{{impact_summary}} (e.g., "Production line held pending disposition. Estimated 3-day impact to customer delivery schedule.") + +**Required Response (use 8D format or equivalent):** +1. **Containment actions** — immediate actions to protect our inventory and any other customers who may have received material from the same lot. Confirm whether other lots from the same production run may be affected. +2. **Root cause analysis** — we require a rigorous root cause investigation, not a surface-level explanation. "Operator error" or "inspection escape" are not acceptable root causes. Identify the systemic process or system failure that allowed this non-conformance. +3. **Corrective actions** — specific, measurable actions addressing the verified root cause. Include implementation dates and responsible personnel. +4. **Effectiveness verification plan** — how and when will you verify that the corrective actions are effective? + +**Disposition of Nonconforming Material:** +☐ Return to Vendor — please issue RMA# and shipping instructions +☐ Sort at our facility — credit memo for sort labor will follow +☐ Scrap at our facility — credit memo for material value will follow + +**Contact for Questions:** +{{our_quality_contact}} | {{our_quality_email}} | {{our_quality_phone}} + +--- + +## 4. CAPA Initiation Record + +### When to Use +- Formal CAPA initiation based on established trigger criteria +- Documents the triggering event, scope, team assignment, and initial timeline + +### Tone Guidance +Structured and factual. The initiation record sets the scope and expectations for the entire CAPA. Ambiguity here leads to scope creep or incomplete investigations later. Be specific about what triggered the CAPA and what the expected outcome is. + +### Template + +**CORRECTIVE AND PREVENTIVE ACTION RECORD** + +| Field | Value | +|---|---| +| CAPA Number | {{capa_number}} | +| Date Initiated | {{date_initiated}} | +| Type | ☐ Corrective ☐ Preventive | +| Source | ☐ NCR ☐ Customer Complaint ☐ Audit Finding ☐ Trend Analysis ☐ Field Failure ☐ Other: {{other_source}} | +| Source Reference(s) | {{source_references}} (e.g., NCR-2025-0412, NCR-2025-0398, NCR-2025-0456) | +| Priority | ☐ Critical (safety/regulatory) ☐ High (customer impact) ☐ Medium (internal) ☐ Low (improvement) | + +**Problem Statement:** +{{problem_statement}} + +Example: "Recurring dimensional non-conformance on Part 7832-A Rev D — bore diameter out of tolerance (>USL of 12.50mm). Three NCRs in the last 60 days (NCR-2025-0398, -0412, -0456) affecting lots from three different production runs. Total scrap cost to date: $14,200. No customer impact confirmed, but risk of escape exists based on inspection sampling rates." + +**Scope:** +- Product(s) affected: {{products_affected}} +- Process(es) affected: {{processes_affected}} +- Location(s): {{locations_affected}} +- Period: {{time_period}} + +**Team Assignment:** + +| Role | Name | Department | +|---|---|---| +| CAPA Owner | {{capa_owner}} | {{owner_dept}} | +| Lead Investigator | {{investigator}} | {{investigator_dept}} | +| Team Members | {{team_members}} | {{team_depts}} | +| Management Sponsor | {{sponsor}} | {{sponsor_dept}} | + +**Timeline:** + +| Phase | Target Date | +|---|---| +| Root Cause Investigation Complete | {{rca_target}} | +| Corrective Action Plan Approved | {{plan_target}} | +| Implementation Complete | {{implementation_target}} | +| Effectiveness Verification Start | {{verification_start}} | +| Effectiveness Verification Complete | {{verification_end}} | +| CAPA Closure Target | {{closure_target}} | + +**Initial Containment Actions (if applicable):** +{{containment_actions}} + +--- + +## 5. CAPA Effectiveness Review + +### When to Use +- At the end of the effectiveness monitoring period (typically 90 days after implementation) +- Documents the evidence of effectiveness and the closure/extension decision + +### Tone Guidance +Data-driven and conclusive. The effectiveness review is where the CAPA either closes with evidence of success or reopens with evidence of failure. Auditors specifically review effectiveness evidence — it must be quantitative and linked to the original problem statement. + +### Template + +**CAPA EFFECTIVENESS REVIEW** + +| Field | Value | +|---|---| +| CAPA Number | {{capa_number}} | +| Original Problem | {{problem_statement}} | +| Root Cause | {{verified_root_cause}} | +| Corrective Action(s) Implemented | {{corrective_actions}} | +| Implementation Date | {{implementation_date}} | +| Monitoring Period | {{monitoring_start}} to {{monitoring_end}} | + +**Implementation Verification:** +- [ ] Work instruction / procedure updated: Rev {{rev}} effective {{date}} +- [ ] Personnel trained: {{training_records_ref}} +- [ ] Equipment/fixture installed and validated: {{validation_ref}} +- [ ] FMEA / Control Plan updated: {{fmea_ref}} +- [ ] Supplier corrective action verified: {{scar_ref}} + +**Effectiveness Data:** + +| Metric | Baseline (Pre-CAPA) | Target | Actual (Monitoring Period) | Result | +|---|---|---|---|---| +| {{metric_1}} | {{baseline_1}} | {{target_1}} | {{actual_1}} | ☐ Pass ☐ Fail | +| {{metric_2}} | {{baseline_2}} | {{target_2}} | {{actual_2}} | ☐ Pass ☐ Fail | +| Recurrence count | {{baseline_recurrence}} | Zero | {{actual_recurrence}} | ☐ Pass ☐ Fail | + +**Conclusion:** +☐ **CAPA Effective — Close.** All effectiveness criteria met. Zero recurrences during monitoring period. Process capability meets target. +☐ **CAPA Partially Effective — Extend monitoring.** Improvement demonstrated but monitoring period insufficient for definitive conclusion. Extend by {{extension_days}} days. +☐ **CAPA Not Effective — Reopen.** Recurrence observed during monitoring period. Root cause re-investigation required. See {{reopened_investigation_ref}}. + +**Reviewed By:** + +| Name | Role | Signature | Date | +|---|---|---|---| +| {{reviewer_1}} | CAPA Owner | | | +| {{reviewer_2}} | Quality Manager | | | + +--- + +## 6. Audit Finding Response + +### When to Use +- Responding to external audit findings (registrar, customer, regulatory) +- Structure applies to ISO audit NCRs, customer audit CARs, and FDA 483 responses (with modifications per template 11) + +### Tone Guidance +Factual, accountable, and solution-oriented. Accept the finding (even if you disagree with the interpretation — debate the interpretation separately, not in the corrective action response). Demonstrate that you understand the intent of the requirement, not just the words. Auditors value self-awareness and systemic thinking. + +### Template + +**AUDIT FINDING CORRECTIVE ACTION RESPONSE** + +**Audit:** {{audit_type}} (e.g., ISO 9001 Surveillance, Customer Audit, IATF 16949 Recertification) +**Auditor / Organization:** {{auditor_name}}, {{audit_organization}} +**Audit Date(s):** {{audit_dates}} +**Finding Number:** {{finding_number}} +**Finding Classification:** ☐ Major Non-Conformity ☐ Minor Non-Conformity ☐ Observation / OFI + +**Finding Statement:** +{{finding_statement}} + +**Standard Clause Referenced:** {{standard_clause}} (e.g., ISO 9001:2015 §8.5.2, IATF 16949 §10.2.3) + +**Our Response:** + +**1. Acknowledgment:** +We acknowledge the finding. {{brief_acknowledgment}} + +**2. Root Cause Analysis:** +{{root_cause_analysis}} + +**3. Containment (immediate action taken):** +{{containment_actions}} + +**4. Corrective Action:** +| Action | Responsible | Target Date | Evidence of Completion | +|---|---|---|---| +| {{action_1}} | {{responsible_1}} | {{date_1}} | {{evidence_1}} | +| {{action_2}} | {{responsible_2}} | {{date_2}} | {{evidence_2}} | + +**5. Scope Extension (did we check for similar gaps elsewhere?):** +{{scope_extension}} + +**6. Effectiveness Verification Plan:** +{{effectiveness_plan}} + +**Submitted By:** {{responder_name}}, {{responder_title}} +**Date:** {{submission_date}} + +--- + +## 7. Customer Quality Notification + +### When to Use +- Non-conformance discovered on product already shipped to the customer +- Proactive notification — the customer should hear about it from you before they discover it themselves + +### Tone Guidance +Transparent, action-oriented, and structured. Lead with what you know and what you've done (containment), not with excuses. Provide the specific traceability data the customer needs to identify and segregate affected product in their inventory. The customer will judge your quality system based on how you handle this notification — transparency and speed build trust; delay and vagueness destroy it. + +### What NOT to Say +- Do not minimize: "A minor issue was detected" when you don't yet know the scope +- Do not speculate on root cause: "We believe this was caused by..." without verified data +- Do not over-promise on timeline: "This will be resolved by Friday" unless you're certain + +### Template + +**Subject:** `Quality Notification: {{part_number}} — {{defect_description}} — Action Required` + +**To:** {{customer_contact}}, {{customer_name}} +**Cc:** {{our_quality_contact}}, Account Manager + +--- + +**CUSTOMER QUALITY NOTIFICATION** + +**Date:** {{date}} +**Our Reference:** {{ncr_number}} +**Priority:** {{priority_level}} (Critical / High / Standard) + +Dear {{customer_contact}}, + +We are contacting you to notify you of a quality concern with material we have supplied. + +**Affected Product:** +- Part Number: {{part_number}} — {{part_description}} +- Lot Number(s): {{lot_numbers}} +- Serial Number(s): {{serial_numbers}} (if applicable) +- Ship Date(s): {{ship_dates}} +- PO/Order Reference(s): {{po_numbers}} +- Quantity Shipped: {{quantity_shipped}} + +**Nature of Non-Conformance:** +{{defect_description_for_customer}} + +**Containment Actions Taken:** +1. All inventory at our facility has been quarantined and placed on hold +2. Shipments in transit have been intercepted where possible: {{transit_status}} +3. We request that you quarantine the following lot(s) in your inventory: {{lots_to_quarantine}} + +**Recommended Customer Action:** +{{recommended_customer_action}} (e.g., "Please segregate and hold the affected lot numbers listed above. Do not use this material until we provide disposition guidance.") + +**Investigation Status:** +We have initiated an investigation ({{ncr_number}}) and are conducting [root cause analysis / containment sort / material verification]. We will provide an updated status by {{next_update_date}}. + +**Your Direct Contact:** +{{our_quality_contact}} +{{our_quality_email}} +{{our_quality_phone}} + +We take this matter seriously and are committed to full transparency as our investigation progresses. We will provide updates at minimum every {{update_frequency}} until this is resolved. + +Sincerely, +{{our_quality_contact}}, {{our_quality_title}} +{{our_company}} + +--- + +## 8. Supplier Audit Report Summary + +### When to Use +- Summary of a supplier quality audit (process, system, or product audit) +- Distributed to procurement, engineering, and supplier quality management +- Basis for audit follow-up actions + +### Tone Guidance +Objective and balanced. Report what was observed, both strengths and deficiencies. An audit report that is exclusively negative suggests the auditor was looking for problems rather than assessing capability. An audit report that is exclusively positive suggests the auditor wasn't thorough. The summary should give management a clear picture of the supplier's quality maturity. + +### Template + +**SUPPLIER AUDIT REPORT SUMMARY** + +| Field | Value | +|---|---| +| Supplier | {{supplier_name}} | +| Supplier Code | {{supplier_code}} | +| Audit Type | ☐ System ☐ Process ☐ Product ☐ Combined | +| Audit Date(s) | {{audit_dates}} | +| Auditor(s) | {{auditor_names}} | +| Standard(s) Audited Against | {{standards}} (e.g., ISO 9001:2015, IATF 16949, AS9100D) | +| Scope | {{audit_scope}} | + +**Overall Assessment:** ☐ Approved ☐ Approved with Conditions ☐ Not Approved + +**Strengths Observed:** +1. {{strength_1}} +2. {{strength_2}} +3. {{strength_3}} + +**Findings:** + +| # | Clause | Finding | Classification | +|---|---|---|---| +| 1 | {{clause_1}} | {{finding_1}} | Major / Minor / OFI | +| 2 | {{clause_2}} | {{finding_2}} | Major / Minor / OFI | + +**Corrective Action Requirements:** +- Response due: {{car_deadline}} +- Format: 8D or equivalent with root cause analysis and implementation plan +- Submit to: {{submit_to}} + +**Recommendations:** +{{recommendations}} (e.g., "Approve for production with mandatory follow-up audit in 6 months to verify corrective actions. Increase incoming inspection level to tightened until corrective actions verified.") + +--- + +## 9. Quality Alert (Internal) + +### When to Use +- Urgent notification to production floor, inspection, and shipping about a quality issue requiring immediate action +- Non-conformance that could affect product currently in production or awaiting shipment +- Temporary enhanced inspection or containment measure + +### Tone Guidance +Urgent, clear, and actionable. This goes to the production floor — operators, supervisors, inspectors. Use plain language. Include photographs if possible. Specify exactly what to do and what to look for. This is not a request for analysis; it's an instruction for immediate action. + +### Template + +**⚠ QUALITY ALERT ⚠** + +**Alert Number:** QA-{{alert_number}} +**Date Issued:** {{date_issued}} +**Effective Immediately — Until Rescinded** + +**Affected Part(s):** {{part_number}} — {{part_description}} +**Affected Area(s):** {{production_areas}} (e.g., "Line 3 — CNC Turning, Incoming Inspection, Final Inspection, Shipping") + +**Issue:** +{{issue_description_plain_language}} + +**What to Look For:** +{{what_to_look_for}} (specific, measurable criteria with photographs if available) + +**Required Action:** +1. {{action_1}} (e.g., "100% inspect all WIP on this part number for the affected dimension before releasing to the next operation") +2. {{action_2}} (e.g., "Segregate and tag any nonconforming parts found — do NOT scrap without Quality Engineering authorization") +3. {{action_3}} (e.g., "Notify Quality Engineering immediately if any additional nonconforming parts are found: {{contact_info}}") + +**This alert remains in effect until:** {{rescind_condition}} (e.g., "written notification from Quality Engineering that the root cause has been addressed and verified") + +**Issued By:** {{issuer_name}}, {{issuer_title}} + +--- + +## 10. Management Review Quality Summary + +### When to Use +- Monthly or quarterly management review input on quality performance +- Summarizes key metrics, significant quality events, CAPA status, and cost of quality + +### Tone Guidance +Executive-level. Lead with the headline — is quality performance improving, stable, or deteriorating? Then provide the supporting data. Managers need to understand trend direction and business impact, not individual NCR details. Use charts and tables; minimize narrative. + +### Template + +**QUALITY MANAGEMENT REVIEW — {{review_period}}** + +**Prepared By:** {{quality_manager}} +**Date:** {{date}} + +**Executive Summary:** +{{executive_summary}} (2-3 sentences: overall quality trend, most significant event, key action needed) + +**Key Performance Indicators:** + +| Metric | Target | Prior Period | Current Period | Trend | +|---|---|---|---|---| +| Internal defect rate (PPM) | < 1,000 | {{prior_ppm}} | {{current_ppm}} | ↑ ↓ → | +| Customer complaint rate | < 50/1M units | {{prior_complaints}} | {{current_complaints}} | ↑ ↓ → | +| Supplier PPM (incoming) | < 500 | {{prior_supplier_ppm}} | {{current_supplier_ppm}} | ↑ ↓ → | +| NCR closure time (median days) | < 15 | {{prior_ncr_cycle}} | {{current_ncr_cycle}} | ↑ ↓ → | +| CAPA on-time closure rate | > 90% | {{prior_capa_otc}} | {{current_capa_otc}} | ↑ ↓ → | +| Cost of quality (% revenue) | < 3% | {{prior_coq}} | {{current_coq}} | ↑ ↓ → | + +**Significant Quality Events:** +1. {{event_1}} +2. {{event_2}} + +**CAPA Status:** + +| Status | Count | +|---|---| +| Open — On Track | {{on_track}} | +| Open — Overdue | {{overdue}} | +| Closed This Period | {{closed}} | +| Effectiveness Verified | {{verified}} | + +**Top Suppliers by PPM (worst 5):** + +| Supplier | PPM | Trend | Current Escalation Level | +|---|---|---|---| +| {{supplier_1}} | {{ppm_1}} | ↑ ↓ → | {{level_1}} | +| {{supplier_2}} | {{ppm_2}} | ↑ ↓ → | {{level_2}} | + +**Cost of Quality Breakdown:** + +| Category | Amount | % of Revenue | +|---|---|---| +| Prevention | {{prevention_cost}} | {{prevention_pct}} | +| Appraisal | {{appraisal_cost}} | {{appraisal_pct}} | +| Internal Failure | {{internal_failure_cost}} | {{internal_pct}} | +| External Failure | {{external_failure_cost}} | {{external_pct}} | +| **Total COQ** | **{{total_coq}}** | **{{total_coq_pct}}** | + +**Actions Required from Management:** +1. {{action_request_1}} (e.g., "Approve capital expenditure for automated inspection system — ROI analysis attached") +2. {{action_request_2}} (e.g., "Decision needed on Supplier X escalation to Level 3 / alternate source qualification") + +--- + +## 11. Regulatory Agency Response (FDA Form 483) + +### When to Use +- Formal response to FDA Form 483 observations +- Due within 15 business days of receiving the 483 +- This is a critical document — it becomes part of the public FDA inspection record + +### Tone Guidance +Respectful, thorough, and accountable. Acknowledge each observation. Do not argue, minimize, or blame individuals. Demonstrate that you understand the intent of the regulations, not just the words. FDA reviewers specifically evaluate whether your response addresses the systemic issue, not just the specific observation. + +### What NOT to Say +- "We disagree with this observation" — address it even if you disagree +- "This was an isolated incident" — FDA explicitly looks for systemic issues +- "Employee has been terminated" — this is punitive, not corrective; FDA wants system fixes +- "We will address this" without specific actions, dates, and responsible parties + +### Template + +**[Company Letterhead]** + +{{date}} + +{{fda_district_director_name}} +Director, {{fda_district_office}} +Food and Drug Administration +{{fda_address}} + +**Re: Response to FDA Form 483 Inspectional Observations** +**Establishment:** {{facility_name_address}} +**FEI Number:** {{fei_number}} +**Inspection Dates:** {{inspection_dates}} +**Investigator:** {{investigator_name}} + +Dear {{fda_district_director_name}}, + +{{our_company}} appreciates the opportunity to respond to the observations identified during the FDA inspection of our {{facility_name}} facility conducted {{inspection_dates}}. We take these observations seriously and have initiated corrective actions as described below. + +--- + +**Observation {{obs_number}}:** +"{{verbatim_483_observation}}" + +**Response:** + +**Acknowledgment:** +{{acknowledgment}} (e.g., "We acknowledge that our procedure QP-4401 did not adequately address...") + +**Investigation:** +{{investigation_summary}} (What we investigated, what we found, root cause) + +**Corrective Action:** + +| Action | Description | Responsible | Target Date | Status | +|---|---|---|---|---| +| 1 | {{action_1_description}} | {{responsible_1}} | {{date_1}} | {{status_1}} | +| 2 | {{action_2_description}} | {{responsible_2}} | {{date_2}} | {{status_2}} | + +**Scope Extension:** +{{scope_extension}} (e.g., "We reviewed all similar procedures across our facility and identified two additional areas where the same gap existed. These have been corrected as part of actions 3 and 4 above.") + +**Effectiveness Verification:** +{{effectiveness_plan}} (e.g., "We will monitor the effectiveness of these corrective actions over a 90-day period by tracking [specific metric]. Evidence of effectiveness will be available for review upon request.") + +**Evidence Attached:** {{list_of_evidence}} + +--- + +[Repeat for each observation] + +--- + +We are committed to maintaining full compliance with 21 CFR Part 820 and to the continuous improvement of our quality management system. We welcome the opportunity to discuss these responses or to provide additional information. + +Sincerely, + +{{signatory_name}} +{{signatory_title}} +{{our_company}} +{{contact_information}} + +Enclosures: {{list_of_enclosures}} diff --git a/web-app/public/skills/quality-nonconformance/references/decision-frameworks.md b/web-app/public/skills/quality-nonconformance/references/decision-frameworks.md new file mode 100644 index 00000000..a2185ef8 --- /dev/null +++ b/web-app/public/skills/quality-nonconformance/references/decision-frameworks.md @@ -0,0 +1,769 @@ +# Decision Frameworks — Quality & Non-Conformance Management + +This reference provides the detailed decision logic, MRB processes, RCA methodology selection, +CAPA lifecycle management, SPC interpretation workflows, inspection level determination, +supplier quality escalation, and cost of quality calculation models for regulated manufacturing +quality engineering. + +All thresholds, regulatory references, and process expectations reflect quality engineering +practice across FDA 21 CFR 820, IATF 16949, AS9100, and ISO 13485 environments. + +--- + +## 1. NCR Disposition Decision Trees + +### 1.1 Universal Disposition Flow + +Every non-conformance, regardless of regulatory environment, begins with this decision sequence. +The flow terminates at the first applicable disposition; do not skip levels. + +``` +START: Non-conformance identified and documented + │ + ├─ Is the part safety-critical or regulatory-controlled? + │ ├─ YES → Can it be reworked to FULL conformance? + │ │ ├─ YES → REWORK with approved procedure + 100% re-inspection + │ │ └─ NO → SCRAP (no use-as-is permitted without formal risk assessment + │ │ AND regulatory/customer approval) + │ └─ NO → Continue + │ + ├─ Does the non-conformance affect form, fit, or function? + │ ├─ YES → Can it be reworked to full conformance? + │ │ ├─ YES → Is rework cost < 60% of replacement cost? + │ │ │ ├─ YES → REWORK + │ │ │ └─ NO → SCRAP (rework is not economical) + │ │ └─ NO → Can it be repaired to acceptable function? + │ │ ├─ YES → REPAIR with engineering concession + customer + │ │ │ approval (if required by contract/standard) + │ │ └─ NO → SCRAP + │ └─ NO → Continue + │ + ├─ Is the non-conformance cosmetic only? + │ ├─ YES → Does customer spec address cosmetic requirements? + │ │ ├─ YES → Does the part meet customer cosmetic spec? + │ │ │ ├─ YES → USE-AS-IS with documentation + │ │ │ └─ NO → Customer concession required → If granted: USE-AS-IS + │ │ │ → If denied: REWORK or SCRAP + │ │ └─ NO → USE-AS-IS with engineering sign-off + │ └─ NO → Continue + │ + ├─ Is this a dimensional non-conformance within material review authority? + │ ├─ YES → Engineering analysis: does the dimension affect assembly or performance? + │ │ ├─ YES → REWORK or SCRAP (depending on feasibility) + │ │ └─ NO → USE-AS-IS with documented engineering justification + │ └─ NO → Continue + │ + └─ Is this a supplier-caused non-conformance? + ├─ YES → Is the material needed immediately for production? + │ ├─ YES → Sort/rework at supplier's cost + USE acceptable units + │ │ + SCAR to supplier + debit memo for sort/rework cost + │ └─ NO → RETURN TO VENDOR with SCAR + debit memo or replacement PO + └─ NO → Evaluate per the functional impact path above +``` + +### 1.2 FDA-Regulated Environment (21 CFR 820 / ISO 13485) Specific Logic + +Medical device non-conformances carry additional requirements: + +**Pre-Market (Design/Development):** +- Non-conformances during design verification/validation must be documented in the Design History File (DHF) +- Disposition must consider risk per ISO 14971 — severity and probability of harm to the patient +- Use-as-is is rarely acceptable for a design non-conformance; it implies the design intent is wrong +- CAPA is almost always required to prevent recurrence in production + +**Post-Market (Production/Field):** +- Non-conformances that could affect device safety or performance require evaluation for field action (recall, correction, removal) per 21 CFR 806 +- The threshold is low: if there is any reasonable possibility of harm, evaluate formally +- Document the decision NOT to file a field action as rigorously as the decision to file one +- Complaint-related non-conformances must be linked to complaint records per 820.198 +- MDR (Medical Device Report) obligations: death or serious injury must be reported to FDA within 30 calendar days (5 days for events requiring remedial action) + +**Disposition Authority Matrix:** + +| Disposition | Who Can Authorize | Additional Requirements | +|---|---|---| +| Scrap | Quality Engineer or above | Documented with lot traceability | +| Rework | Quality Engineer + Manufacturing Engineering | Approved rework procedure; re-inspect to original spec | +| Repair | MRB (Quality + Engineering + Manufacturing) | Risk assessment per ISO 14971; update DHF if design-related | +| Use-As-Is | MRB + Design Authority | Risk assessment; documented justification; regulatory impact evaluation | +| RTV | Quality Engineer + Procurement | SCAR required; supplier re-qualification if repeated | + +### 1.3 Automotive Environment (IATF 16949) Specific Logic + +**Customer Notification Requirements:** +- Any non-conformance on product shipped to the customer: notification within 24 hours of discovery +- Any process change affecting fit, form, function, or performance: PPAP resubmission required +- Use-as-is disposition: typically requires a formal deviation request to the customer through their supplier portal (e.g., GM's GQTS, Ford's MQAS, Stellantis' SQP) +- Customer may accept, reject, or accept with conditions (reduced quantity, time-limited deviation) + +**Control Plan Integration:** +- When a non-conformance reveals a gap in the control plan, the control plan must be updated as part of the corrective action +- Special characteristics (safety/significant characteristics identified with shield or diamond symbols) have zero tolerance for non-conformance: 100% containment and immediate CAPA +- The reaction plan column of the control plan specifies the predetermined response — follow it first, then investigate + +**Controlled Shipping Levels:** +- **CS-1 (Internal Controlled Shipping):** Supplier adds an additional inspection/sort step beyond normal controls and submits inspection data with each shipment +- **CS-2 (External Controlled Shipping):** Third-party inspection at supplier's facility, at supplier's cost, with direct reporting to customer quality +- CS-1 and CS-2 are distinct from the general supplier escalation ladder — they are customer-mandated containment measures, not supplier-initiated improvements + +### 1.4 Aerospace Environment (AS9100) Specific Logic + +**Customer/Authority Approval:** +- Use-as-is and repair dispositions ALWAYS require customer approval per AS9100 §8.7.1 +- If the customer is a prime contractor working under a government contract, the government quality representative (DCMA or equivalent) may also need to approve +- Non-conformances on parts with key characteristics require notification to the design authority +- First Article Inspection (FAI) per AS9102 becomes invalid if a non-conformance indicates the process has changed from the qualified state — partial or full FAI resubmission may be required + +**Counterfeit Part Prevention:** +- If a non-conformance raises suspicion of counterfeit material (unexpected material composition, incorrect markings, suspect documentation), invoke the counterfeit prevention procedure per AS9100 §8.1.4 +- Quarantine the suspect material in a separate area from other MRB material +- Report to GIDEP (Government-Industry Data Exchange Program) if counterfeit is confirmed +- Do not return suspect counterfeit material to the supplier — it must be quarantined and may need to be retained as evidence + +**Traceability Requirements:** +- Aerospace non-conformances must maintain lot, batch, heat, and serial number traceability throughout the disposition process +- Scrap disposition must include documented destruction of serialized parts to prevent re-entry into the supply chain +- OASIS database updates may be required for supplier quality events + +--- + +## 2. Root Cause Analysis Methodology Selection Guide + +### 2.1 Selection Decision Matrix + +| Factor | 5 Whys | Ishikawa + 5 Whys | 8D | Fault Tree Analysis | +|---|---|---|---|---| +| **Best for** | Single-event, linear cause chain | Multi-factor, need to explore categories | Recurring issue, team-based resolution | Safety-critical, quantitative risk needed | +| **Effort (hours)** | 1–2 | 4–8 | 20–40 (across all D-steps) | 40–80 | +| **Team size** | 1–2 people | 2–4 people | 5–8 cross-functional | 3–6 subject matter experts | +| **When required** | Internal process investigations | Complex non-conformances | Customer mandate (automotive OEMs) | Aerospace product safety; medical device risk analysis | +| **Limitation** | Assumes single linear chain | Still qualitative; hypothesis-driven | Heavyweight for simple issues | Resource-intensive; requires failure rate data for quantitative mode | +| **Output** | Root cause statement | Categorized cause hypotheses with verified root cause | Full 8D report (D0-D8) | Fault tree diagram with probability assignments | + +### 2.2 The 5 Whys: When It Works and When It Doesn't + +**5 Whys works well when:** +- The failure is a single event with a clear before/after state change +- Each "why" can be verified with data (measurement, observation, record review) +- The causal chain does not branch — there is a single dominant cause +- The investigation can reach a systemic cause (process, system, or design issue) within 5 iterations + +**5 Whys fails when:** +- Multiple independent causes interact to produce the failure (combinatorial causes) +- The analyst stops at "human error" or "operator mistake" — this is never a root cause +- Each "why" is answered with opinion rather than verified data +- The analysis becomes circular (Why A? Because B. Why B? Because A.) +- Organizational pressure drives toward a "convenient" root cause that avoids systemic change + +**Verification protocol for each "why" level:** + +| Why Level | Question | Acceptable Evidence | Unacceptable Evidence | +|---|---|---|---| +| Why 1 (Event) | What physically happened? | Measurement data, photographs, inspection records | "The part was bad" | +| Why 2 (Condition) | What condition allowed it? | Process parameter logs, tool condition records | "The operator didn't check" | +| Why 3 (Process) | Why did the process permit this condition? | Work instruction review, process FMEA gap | "It's always been done this way" | +| Why 4 (System) | Why didn't the system prevent the process gap? | System audit evidence, training records, control plan review | "We need better training" | +| Why 5 (Management) | Why was the system gap undetected? | Management review records, resource allocation evidence, risk assessment gaps | "Management doesn't care about quality" | + +### 2.3 Ishikawa Diagram: 6M Framework Deep Dive + +For each M category, specific investigation questions that separate thorough analysis from checkbox exercises: + +**Man (Personnel):** +- Was the operator trained AND certified on this specific operation? +- When was the most recent certification renewal? +- Was this the operator's normal workstation or were they cross-trained/temporary? +- Was the shift staffing at normal levels or was this during overtime/short-staffing? +- Check operator error rate data — is this an isolated event or a pattern for this individual? + +**Machine (Equipment):** +- When was the last preventive maintenance performed (date AND what was done)? +- Is the machine within its calibration cycle for all measuring functions? +- Were any alarms, warnings, or parameter drifts logged before the event? +- Has the machine been modified, repaired, or had a tooling change recently? +- Check the machine's historical Cpk trend — has capability been declining? + +**Material:** +- Is this a new lot of raw material? When did the lot change? +- Were incoming inspection results within normal range, or marginal-pass? +- Does the material certificate match what was physically received (heat number, mill, composition)? +- Has the material been stored correctly (temperature, humidity, shelf life, FIFO rotation)? +- Were any material substitutions or equivalents authorized? + +**Method (Process):** +- Is the work instruction current revision? When was it last revised? +- Does the operator actually follow the work instruction as written (observation, not assumption)? +- Were any process parameters changed recently (speeds, feeds, temperatures, pressures, cure times)? +- Was an engineering change order (ECO) recently implemented on this part or process? +- Is there a gap between the documented method and the actual method (tribal knowledge)? + +**Measurement:** +- Was the measurement system used for this inspection validated (Gauge R&R)? +- Is the gauge within calibration? Check both certificate and physical condition. +- Was the correct measurement method used (per the control plan or inspection instruction)? +- Did the measurement environment (temperature, vibration, lighting) affect the result? +- For attribute inspections (go/no-go, visual): what is the inspection effectiveness rate? + +**Mother Nature (Environment):** +- Were ambient conditions (temperature, humidity) within process specification? +- Were there any environmental events (power fluctuation, compressed air pressure drop, vibration from construction)? +- Is there a shift-to-shift or day-to-day correlation in the data (temperature cycling, humidity changes)? +- Was the factory HVAC system operating normally? +- For cleanroom or controlled environment processes: were environmental monitoring logs within specification? + +### 2.4 8D Methodology: Detailed Gate Requirements + +Each D-step has specific outputs required before advancing. Skipping gates creates 8Ds that look complete but don't actually solve the problem. + +| D-Step | Name | Required Output | Common Failure Mode | +|---|---|---|---| +| D0 | Symptom & Emergency Response | Emergency response actions taken; containment effectiveness confirmed | Confusing containment with corrective action | +| D1 | Team Formation | Cross-functional team with defined roles; includes process owner and subject matter expert | Team is all quality, no manufacturing or engineering | +| D2 | Problem Definition | IS/IS NOT analysis completed; problem quantified with data (defect rate, PPM, Cpk shift, complaint count) | Problem statement is too broad ("quality issues") or just restates the symptom | +| D3 | Interim Containment | Actions to protect customer while investigation proceeds; effectiveness verified (inspection data post-containment) | Containment is "100% inspection" without verifying inspection effectiveness through known-defective challenge | +| D4 | Root Cause | Root cause(s) verified through data analysis or designed experiment; escapes the "human error" trap | Root cause = restatement of problem; no verification data; stops at symptoms | +| D5 | Corrective Action Selection | Actions address verified root cause; mistake-proofing (poka-yoke) preferred over procedural controls | Corrective action = "retrain operators" or "add inspection step" (both are weak) | +| D6 | Implementation | Actions implemented with documented evidence (updated WI, installed fixture, modified process); baseline performance established | Implementation date = planned date, not actual; no evidence of implementation | +| D7 | Prevention | Systemic actions to prevent recurrence across similar processes/products; lessons learned documented; FMEA updated | D7 is copy-paste of D5; no horizontal deployment; FMEA not updated | +| D8 | Recognition | Team acknowledged; 8D closed with effectiveness data | Closed without effectiveness data; team not recognized | + +### 2.5 Fault Tree Analysis: Construction Methodology + +**Step 1: Define the Top Event** +- State the undesired event in specific, measurable terms +- Example: "Shaft diameter exceeds USL of 25.05mm on finished machined part" +- Not: "Bad parts" or "Quality problem" + +**Step 2: Identify Immediate Causes (Level 1)** +- What must be true for the top event to occur? +- Use AND gates (all causes must be present) and OR gates (any single cause is sufficient) +- Example: "Shaft OD too large" can be caused by (OR gate): tool wear, incorrect tool offset, material oversize, thermal expansion, fixture misalignment + +**Step 3: Decompose Each Cause (Levels 2–N)** +- For each Level 1 cause, ask: what causes this? +- Continue decomposing until you reach basic events (events with known failure rates or that cannot be further decomposed) +- Example: "Tool wear" caused by (AND gate): extended run time + inadequate tool change interval + no in-process SPC alert + +**Step 4: Quantify (when data is available)** +- Assign probability values to basic events using historical data, MTBF data, or engineering estimates +- Calculate top event probability through the gate logic +- Identify the minimal cut sets (smallest combinations of basic events that cause the top event) +- Focus corrective actions on the highest-probability cut sets + +--- + +## 3. CAPA Writing and Verification Framework + +### 3.1 CAPA Initiation Criteria + +**Always initiate CAPA for:** +- Repeat non-conformance: same failure mode occurring 3+ times in 12 months +- Customer complaint involving product performance, safety, or regulatory compliance +- External audit finding (FDA, notified body, customer, registrar) +- Field failure or product return +- Trend signal: SPC control chart out-of-control pattern (not isolated point) +- Regulatory requirement change affecting existing products/processes +- Post-market surveillance data indicating potential safety concern + +**Consider CAPA (judgment call) for:** +- Repeat non-conformance: same failure mode 2 times in 12 months +- Internal audit finding of moderate significance +- Supplier non-conformance with systemic indicators +- Near-miss event (non-conformance caught before reaching customer) +- Process deviation from validated parameters without product impact + +**Do NOT initiate CAPA for:** +- Isolated non-conformance with clear, non-recurring cause (one-off tool breakage, power outage) +- Non-conformance fully addressed by NCR disposition with no systemic implication +- Customer cosmetic preference that doesn't violate any specification +- Minor documentation errors caught and corrected within the same day + +### 3.2 CAPA Action Hierarchy (Effectiveness Ranking) + +Corrective actions are not created equal. Rank by effectiveness and default to the highest feasible level: + +| Rank | Control Type | Example | Effectiveness | Typical Cost | +|---|---|---|---|---| +| 1 | **Elimination** | Redesign to remove the failure mode entirely | ~100% | High (design change, tooling) | +| 2 | **Substitution** | Change material, supplier, or process to one that cannot produce the failure | ~95% | Medium-High | +| 3 | **Engineering Controls (Poka-Yoke)** | Fixture that physically prevents incorrect assembly; sensor that stops machine on out-of-spec condition | ~90% | Medium | +| 4 | **Detection Controls** | Automated inspection (vision system, laser gauge) that 100% inspects and auto-rejects | ~85% | Medium | +| 5 | **Administrative Controls** | Updated work instruction, revised procedure, checklist | ~50-60% | Low | +| 6 | **Training** | Operator retraining on existing procedure | ~30-40% | Low | + +If your corrective action is ranked 5 or 6 and a rank 1-4 action is feasible, the CAPA will likely be challenged by auditors. Training alone is never an adequate corrective action for a significant non-conformance. + +### 3.3 CAPA Effectiveness Verification Protocol + +**Phase 1: Implementation Verification (within 2 weeks of target date)** + +| Evidence Required | What to Check | Acceptable | Not Acceptable | +|---|---|---|---| +| Document revision | Was the WI/procedure updated to reflect the change? | Revision with effective date and training records | "Will be updated in next revision" | +| Physical verification | Is the fixture/tool/sensor installed and operational? | Photograph + validation record | Purchase order placed but not installed | +| Training completion | Were affected personnel trained? | Signed training records with competency assessment | Email sent to team | +| System update | Were QMS documents, FMEA, control plan updated? | Updated documents with revision and approval | "Will update during next review" | + +**Phase 2: Effectiveness Validation (90-day monitoring period)** + +| Metric | Calculation | Pass Criteria | Fail Criteria | +|---|---|---|---| +| Recurrence rate | Count of same failure mode in monitoring period | Zero recurrences | Any recurrence | +| Related failure rate | Count of related failure modes in same process | No increase from baseline | Increase suggests incomplete root cause | +| Process capability | Cpk or Ppk for the affected characteristic | Cpk ≥ 1.33 (or target value) | Cpk below pre-CAPA level | +| Customer feedback | Complaints related to the addressed failure mode | Zero related complaints | Any related complaint | + +**Phase 3: Closure Decision** + +| Condition | Decision | +|---|---| +| Phase 1 complete + Phase 2 pass criteria met | Close CAPA | +| Phase 1 complete + Phase 2 shows improvement but not full elimination | Extend monitoring period by 60 days; if still improving, close with condition | +| Phase 1 complete + Phase 2 shows no improvement | Reopen CAPA; root cause was incorrect or action insufficient | +| Phase 1 incomplete (action not implemented) | CAPA remains open; escalate for resource allocation | +| Recurrence during monitoring | Reopen CAPA; do NOT close and open new CAPA for same issue | + +### 3.4 CAPA Timeliness Standards + +| CAPA Phase | Target Timeline | Regulatory Expectation | +|---|---|---| +| Initiation and assignment | Within 5 business days of trigger | FDA: "timely" — typically within 30 days of awareness | +| Investigation and root cause | Within 30 calendar days | IATF 16949: per customer timeline (often 10-day initial response) | +| Corrective action plan | Within 45 calendar days | AS9100: per contractual agreement | +| Implementation | Within 90 calendar days | Varies by complexity; document delays with justification | +| Effectiveness verification start | Immediately after implementation | Must be defined at initiation | +| Effectiveness verification completion | 90 days after implementation | FDA: must demonstrate effectiveness, not just implementation | +| CAPA closure | Within 180 calendar days of initiation (total) | FDA warning letters cite CAPAs open > 1 year as systemic failure | + +--- + +## 4. SPC Interpretation Decision Logic + +### 4.1 Control Chart Selection Flowchart + +``` +START: What type of data are you charting? + │ + ├─ CONTINUOUS (variable) data — measurements in units (mm, kg, °C, psi) + │ ├─ Are you taking subgroups (multiple measurements per sampling event)? + │ │ ├─ YES → What is the subgroup size (n)? + │ │ │ ├─ n = 2 to 9 → X-bar / R chart + │ │ │ ├─ n = 10 to 25 → X-bar / S chart + │ │ │ └─ n > 25 → X-bar / S chart (consider reducing subgroup size) + │ │ └─ NO (n=1, individual readings) → Individuals / Moving Range (I-MR) chart + │ │ Use when: batch process, destructive testing, slow process, + │ │ or when each unit is unique + │ └─ (Verify data normality assumption for variable charts — I-MR is sensitive + │ to non-normality; consider transformation or use nonparametric alternatives) + │ + └─ ATTRIBUTE (discrete) data — counts or proportions + ├─ Are you counting DEFECTIVE ITEMS (units that pass or fail)? + │ ├─ YES → Is the sample size constant? + │ │ ├─ YES → np-chart (count of defectives, fixed sample) + │ │ └─ NO → p-chart (proportion defective, variable sample) + │ └─ NO → You're counting DEFECTS (multiple defects possible per unit) + │ ├─ Is the inspection area/opportunity constant? + │ │ ├─ YES → c-chart (count of defects per unit, fixed area) + │ │ └─ NO → u-chart (defects per unit, variable area) + │ └─ (Verify Poisson assumption for c/u charts) + └─ (Attribute charts require larger sample sizes than variable charts for + equivalent sensitivity — minimum ~50 for p/np, ~25 for c/u) +``` + +### 4.2 Out-of-Control Response Protocol + +When a control chart signals an out-of-control condition, follow this response based on the specific signal: + +**Rule 1: Point beyond 3σ control limit** + +| Response Level | Action | Timeline | +|---|---|---| +| Immediate | Stop process if product is being produced; quarantine output since last known good point | Within minutes | +| Investigation | Identify the assignable cause — what changed? Check 6M categories systematically | Within 4 hours | +| Containment | Sort/inspect product produced during the out-of-control period | Within 1 shift | +| Correction | Address the assignable cause and restart production with increased monitoring | Before next production run | +| Documentation | NCR if product was affected; update control chart with annotation | Within 24 hours | + +**Rule 2: Nine consecutive points on one side of the center line (run)** + +| Response Level | Action | Timeline | +|---|---|---| +| Investigation | Process mean has likely shifted. Check for: tool wear progression, material lot change, environmental drift, measurement calibration shift | Within 1 shift | +| Adjustment | If assignable cause found: correct. If no assignable cause found and process is still within spec, continue monitoring but increase sampling frequency | Within 24 hours | +| Recalculation | If the shift is intentional (process improvement) or represents a new process level, recalculate control limits with new data | After 25+ subgroups at new level | + +**Rule 3: Six consecutive points steadily increasing or decreasing (trend)** + +| Response Level | Action | Timeline | +|---|---|---| +| Investigation | Process is drifting. Most common causes: tool wear, chemical depletion, thermal drift, filter degradation | Within 1 shift | +| Projection | At the current drift rate, when will the process exceed the specification limit? This determines urgency | Immediate calculation | +| Preemptive action | Adjust the process (tool change, chemical replenishment) BEFORE it reaches the spec limit | Before projected spec limit crossing | + +**Rule 4: Fourteen consecutive points alternating up and down (stratification/mixing)** + +| Response Level | Action | Timeline | +|---|---|---| +| Investigation | This pattern indicates over-control (tampering), two alternating streams (e.g., two spindles, two cavities), or systematic measurement error | Within 24 hours | +| Verification | Check if the subgroup data is being collected from multiple sources that should be charted separately | Within 48 hours | +| Stratification | If data is from multiple streams, create separate charts for each stream | Within 1 week | + +### 4.3 Capability Index Interpretation + +| Cpk Value | Interpretation | Action Required | +|---|---|---| +| Cpk ≥ 2.00 | Six Sigma capable; consider reducing inspection frequency | Maintain controls; candidate for reduced inspection or skip-lot | +| 1.67 ≤ Cpk < 2.00 | Highly capable; exceeds most customer requirements | Standard monitoring; meets IATF 16949 requirements for new processes | +| 1.33 ≤ Cpk < 1.67 | Capable; meets most industry standards | Standard SPC monitoring; meets IATF 16949 minimum for production | +| 1.00 ≤ Cpk < 1.33 | Marginally capable; producing some defects | Increase monitoring frequency; initiate process improvement; customer notification may be required | +| 0.67 ≤ Cpk < 1.00 | Not capable; significant defect production | 100% inspection until process is improved; CAPA required; customer notification required | +| Cpk < 0.67 | Severely incapable | Stop production; sort all WIP and finished goods; engineering review of process and specification | + +**Cp vs. Cpk Interpretation:** + +| Condition | Meaning | Action | +|---|---|---| +| Cp high, Cpk high | Process is both capable and centered | Optimal state; maintain | +| Cp high, Cpk low | Process has low variation but is not centered on the target | Adjust the process mean; do NOT reduce variation (it's already good) | +| Cp low, Cpk low | Process has too much variation, possibly also off-center | Reduce variation first (fundamental process improvement), then center | +| Cp low, Cpk ≈ Cp | Process has too much variation but is centered | Reduce variation; centering is not the issue | + +**Pp/Ppk vs. Cp/Cpk:** + +| Index | Uses | Represents | When to Use | +|---|---|---|---| +| Cp/Cpk | Within-subgroup variation (σ_within) | Short-term or "potential" capability | Evaluating process potential when in statistical control | +| Pp/Ppk | Overall variation (σ_overall) including between-subgroup shifts | Long-term or "actual" performance | Evaluating what the customer actually receives over time | +| Pp/Ppk < Cp/Cpk (common) | Process mean is shifting between subgroups | Between-subgroup variation is significant | Investigate what's causing the mean to shift between subgroups | +| Pp/Ppk ≈ Cp/Cpk | Process is stable over time | Minimal between-subgroup variation | Process is well-controlled; long-term performance matches potential | + +--- + +## 5. Inspection Level Determination + +### 5.1 Incoming Inspection Level Decision Matrix + +| Factor | Points | +|---|---| +| **Supplier History** | | +| New supplier (< 5 lots received) | 5 | +| Supplier on probation/watch | 5 | +| Qualified supplier with PPM 1,000-5,000 | 3 | +| Qualified supplier with PPM 500-1,000 | 2 | +| Qualified supplier with PPM < 500 | 1 | +| Preferred supplier with PPM < 100 | 0 | +| **Part Criticality** | | +| Safety-critical characteristic | 5 | +| Key characteristic (fit/function) | 3 | +| Standard characteristic | 1 | +| Cosmetic only | 0 | +| **Regulatory Requirement** | | +| FDA/medical device requiring incoming inspection | 5 | +| Aerospace with special process (NADCAP) | 4 | +| Automotive with customer-designated special characteristic | 3 | +| Standard ISO 9001 environment | 1 | +| **Recent Quality History (last 6 months)** | | +| NCR issued against this part/supplier combination | +3 | +| Customer complaint traced to this component | +4 | +| SCAR currently open against this supplier | +3 | +| No quality issues | 0 | + +**Inspection Level Assignment:** + +| Total Points | Inspection Level | Typical Approach | +|---|---|---| +| 0–3 | Reduced / Skip-Lot | CoC review + skip-lot verification (every 3rd or 5th lot) | +| 4–7 | Normal (AQL Level II) | Standard AQL sampling per ANSI/ASQ Z1.4 | +| 8–11 | Tightened (AQL Level III) | Tightened sampling or increased sample size | +| 12+ | 100% / Full Inspection | 100% inspection of critical characteristics | + +### 5.2 ANSI/ASQ Z1.4 Quick Reference + +**Sample Size Code Letters (Normal Inspection, General Level II):** + +| Lot Size | Code Letter | Sample Size (AQL 1.0) | +|---|---|---| +| 2–8 | A | 2 (Ac=0, Re=1) | +| 9–15 | B | 3 (Ac=0, Re=1) | +| 16–25 | C | 5 (Ac=0, Re=1) | +| 26–50 | D | 8 (Ac=0, Re=1) | +| 51–90 | E | 13 (Ac=1, Re=2) | +| 91–150 | F | 20 (Ac=1, Re=2) | +| 151–280 | G | 32 (Ac=2, Re=3) | +| 281–500 | H | 50 (Ac=3, Re=4) | +| 501–1,200 | J | 80 (Ac=5, Re=6) | +| 1,201–3,200 | K | 125 (Ac=7, Re=8) | +| 3,201–10,000 | L | 200 (Ac=10, Re=11) | +| 10,001–35,000 | M | 315 (Ac=14, Re=15) | +| 35,001–150,000 | N | 500 (Ac=21, Re=22) | + +**Switching Rules:** + +| Current Level | Switch Condition | Switch To | +|---|---|---| +| Normal | 2 of 5 consecutive lots rejected | Tightened | +| Normal | 10 consecutive lots accepted AND production at steady rate AND approved by responsible authority | Reduced | +| Tightened | 5 consecutive lots accepted | Normal | +| Tightened | 10 consecutive lots not accepted | Discontinue inspection; require supplier corrective action | +| Reduced | 1 lot rejected | Normal | +| Reduced | Production irregular or other conditions warrant | Normal | + +### 5.3 Skip-Lot Qualification Requirements + +**Qualification Criteria (all must be met):** +1. Supplier is on the Approved Supplier List with "preferred" or "qualified" status +2. Minimum 10 consecutive lots accepted at normal inspection level +3. Supplier's process capability (Cpk) for critical characteristics ≥ 1.33, verified by supplier data AND incoming inspection data +4. No open SCARs against the supplier for this part number +5. Supplier has a certified quality management system (ISO 9001 minimum; industry-specific certification preferred) +6. Written agreement documenting skip-lot terms, reversion criteria, and data submission requirements + +**Skip-Lot Frequencies:** + +| Qualification Level | Inspection Frequency | Reversion Trigger | +|---|---|---| +| Skip-Lot 1 | Every 2nd lot | 1 lot rejection | +| Skip-Lot 2 | Every 3rd lot | 1 lot rejection or supplier Cpk drops below 1.33 | +| Skip-Lot 3 | Every 5th lot | 1 lot rejection, Cpk concern, or supplier quality system change | +| CoC Reliance | CoC review only; periodic verification (annual or per-lot-change) | Any NCR, customer complaint, or audit finding | + +--- + +## 6. Supplier Quality Escalation Ladder + +### 6.1 Detailed Escalation Process + +**Level 0: Normal Operations** +- Supplier meets scorecard expectations (PPM < threshold, OTD > threshold, SCAR closure on time) +- Standard incoming inspection level +- Quarterly scorecard review +- Annual audit (if risk-based schedule warrants) + +**Level 1: SCAR Issued** +- **Trigger:** Single significant non-conformance (> $5,000 impact or safety/regulatory concern) OR 3+ minor non-conformances on the same part in 90 days +- **Actions:** + - Formal SCAR issued with 8D or equivalent RCA requirement + - Supplier has 10 business days for initial response (containment + preliminary root cause) + - Supplier has 30 calendar days for full corrective action plan with implementation timeline + - Quality engineering review of SCAR response for adequacy + - Increase incoming inspection level for the affected part number +- **Exit criteria:** SCAR accepted and closed with verified effectiveness (90-day monitoring) + +**Level 2: Supplier on Watch / Probation** +- **Trigger:** SCAR not responded to within timeline OR corrective action not effective (recurrence during monitoring) OR scorecard falls below minimum threshold for 2 consecutive quarters +- **Actions:** + - Supplier notified of probation status in writing (Quality Manager or Director level) + - Procurement notified; new business hold (no new part numbers awarded) + - Increase inspection level for ALL part numbers from this supplier (not just affected part) + - Monthly performance review calls with supplier quality management + - Supplier must submit a comprehensive improvement plan within 15 business days + - Consider on-site quality audit focused on the specific failure mode +- **Exit criteria:** Improvement plan accepted + 2 consecutive quarters meeting scorecard minimum + no new SCARs + +**Level 3: Controlled Shipping** +- **Trigger:** Continued failures during watch period OR critical quality escape that reaches customer +- **Actions:** + - Controlled Shipping Level 1 (CS-1): Supplier adds additional sort/inspection step with data submitted per shipment + - If CS-1 ineffective within 60 days: Controlled Shipping Level 2 (CS-2): third-party resident inspector at supplier's facility, at supplier's expense + - All sort/inspection costs debited to supplier + - Weekly performance review calls with supplier VP/GM level + - Begin qualification of alternate source (if not already underway) +- **Exit criteria:** 90 consecutive days of zero non-conformances under controlled shipping + root cause fully addressed + systemic improvements validated + +**Level 4: New Source Qualification / Phase-Out** +- **Trigger:** No sustained improvement under controlled shipping OR supplier unwilling/unable to invest in required improvements +- **Actions:** + - Formal notification to supplier of intent to transfer business + - Accelerated alternate supplier qualification (expedite PPAP/FAI/first articles) + - Reduce business allocation as alternate source ramps up + - Maintain controlled shipping on remaining volume + - Ensure last-time-buy quantities cover the transition period + - Document all quality costs incurred for potential recovery +- **Timeline:** Depends on part complexity and alternate source readiness; typically 3-12 months + +**Level 5: ASL Removal** +- **Trigger:** Qualification of alternate source complete OR supplier's quality system failure is fundamental (e.g., data falsification, loss of certification) +- **Actions:** + - Formal removal from Approved Supplier List + - Final shipment received and inspected under 100% inspection + - All supplier-owned tooling at our facility: disposition per contract terms + - Our tooling at supplier's facility: retrieve per contract terms + - Close all open SCARs as "supplier removed" + - Retain supplier quality file for minimum 7 years (regulatory record retention) + - Update OASIS (aerospace) or relevant industry databases +- **Re-entry:** If supplier applies for re-qualification, treat as a new supplier with full qualification process; require evidence that systemic issues were addressed + +### 6.2 Escalation Decision Quick Reference + +| Situation | Start at Level | Rationale | +|---|---|---| +| First minor NC from good supplier | Handle via NCR, no escalation | Single event doesn't warrant formal escalation | +| First significant NC from good supplier | Level 1 (SCAR) | Significant impact requires formal root cause | +| Third minor NC in 90 days from same supplier/part | Level 1 (SCAR) | Pattern indicates systemic issue | +| SCAR response inadequate or late | Level 2 (Watch) | Non-responsiveness is itself a quality system failure | +| NC reaches customer | Level 2 minimum; Level 3 if safety-related | Customer impact demands immediate escalation | +| Falsified documentation discovered | Level 4 minimum; Level 5 if confirmed | Trust is broken; containment scope is unknown | +| Sole-source supplier with quality problems | Level 1 with parallel Level 4 actions (qualify alternate) | Business continuity requires measured response; don't threaten what you can't execute | + +--- + +## 7. Cost of Quality Calculation Models + +### 7.1 COQ Category Definitions and Tracking + +**Prevention Costs (invest to prevent defects):** + +| Cost Element | How to Measure | Typical Range (% of revenue) | +|---|---|---| +| Quality planning | Hours × labor rate for quality planning activities | 0.2–0.5% | +| Process validation/qualification | Labor + equipment + materials for IQ/OQ/PQ | 0.3–0.8% | +| Supplier qualification | Audit travel + labor + first article costs | 0.1–0.3% | +| Training (quality-related) | Hours × labor rate + training materials | 0.1–0.3% | +| SPC implementation/maintenance | Software licenses + labor for chart maintenance | 0.1–0.2% | +| Design reviews / FMEA | Hours × labor rate for cross-functional reviews | 0.2–0.5% | +| Poka-yoke development | Design + fabrication + validation of error-proofing | 0.2–0.5% | + +**Appraisal Costs (cost of verifying conformance):** + +| Cost Element | How to Measure | Typical Range (% of revenue) | +|---|---|---| +| Incoming inspection | Hours × labor rate + gauge costs | 0.3–0.8% | +| In-process inspection | Hours × labor rate (including production wait time) | 0.5–1.5% | +| Final inspection / testing | Hours × labor rate + test equipment depreciation | 0.3–1.0% | +| Calibration program | Service contracts + labor + standards | 0.1–0.3% | +| Audit program (internal + external) | Labor + travel + registration fees | 0.1–0.3% | +| Laboratory testing | Internal lab costs or external lab fees | 0.2–0.5% | + +**Internal Failure Costs (defects caught before shipment):** + +| Cost Element | How to Measure | Typical Range (% of revenue) | +|---|---|---| +| Scrap | Scrapped material value + processing labor wasted | 1.0–3.0% | +| Rework | Labor + materials for rework operations | 0.5–2.0% | +| Re-inspection | Hours × labor rate for re-inspection after rework | 0.1–0.5% | +| MRB processing | Hours × labor rate for disposition activities | 0.1–0.3% | +| Root cause investigation | Hours × labor rate for RCA team activities | 0.2–0.5% | +| Production delays | Lost production time due to quarantine, investigation | 0.5–2.0% | +| Supplier sort/containment | Third-party sort labor or internal sort labor for supplier-caused NC | 0.1–0.5% | + +**External Failure Costs (defects that reach the customer):** + +| Cost Element | How to Measure | Typical Range (% of revenue) | +|---|---|---| +| Customer returns / credits | Credit memos + return shipping + restocking labor | 0.5–2.0% | +| Warranty claims | Claim value + processing labor | 0.5–3.0% | +| Field service / repair | Service labor + travel + parts | 0.3–1.5% | +| Customer complaint processing | Hours × labor rate for investigation + response | 0.2–0.5% | +| Recall / field correction | Product replacement + notification + shipping + regulatory | 0.0–5.0% (highly variable) | +| Regulatory action costs | Fines, consent decree compliance, increased inspections | 0.0–10.0% (catastrophic when triggered) | +| Reputation / lost business | Lost revenue from customer defection (estimate) | Difficult to measure; typically 2-10x direct costs | + +### 7.2 COQ Business Case Model + +**Calculating ROI for Quality Investment:** + +``` +ROI = (Failure Cost Reduction - Investment Cost) / Investment Cost × 100% + +Where: + Failure Cost Reduction = (Current internal + external failure costs) + - (Projected failure costs after investment) + Investment Cost = Prevention cost increase + appraisal cost change +``` + +**Rule of Thumb Multipliers:** + +| Investment Type | Expected ROI | Payback Period | +|---|---|---| +| Poka-yoke (error-proofing) | 5:1 to 20:1 | 3–6 months | +| SPC implementation | 3:1 to 10:1 | 6–12 months | +| Supplier development program | 2:1 to 8:1 | 12–24 months | +| Process validation improvement | 4:1 to 15:1 | 6–18 months | +| Training program upgrade | 1:1 to 3:1 | 12–24 months | + +### 7.3 MRB Decision Process — Economic Model + +When disposition is not dictated by safety or regulatory requirements, use economic analysis: + +**Rework vs. Scrap Decision:** + +``` +Rework if: C_rework + C_reinspect < C_replacement × (1 + premium) + +Where: + C_rework = Direct rework labor + materials + machine time + C_reinspect = Re-inspection labor + any additional testing + C_replacement = Purchase price or manufacturing cost of replacement unit + premium = Schedule urgency factor (0% if no urgency, 10-50% if production impact, + 100%+ if customer delivery at risk) +``` + +**Sort vs. Return Decision (for supplier-caused lots):** + +``` +Sort if: (C_sort < C_return_freight + C_production_delay) AND (expected yield > 70%) + +Where: + C_sort = Sort labor hours × rate (typically $25-50/hr for manual sort, + $50-100/hr for dimensional sort) + C_return_freight = Shipping cost + handling + administrative + C_production_delay = (Days of delay × daily production value at risk) + expected yield = Estimated % of lot that will pass sort + (use sample data to estimate) +``` + +**Use-As-Is vs. Sort/Rework Decision (non-safety, non-regulatory):** + +``` +Use-as-is if: Risk_functional ≤ Acceptable_risk + AND C_use_as_is < C_sort_or_rework + AND engineering provides documented justification + +Where: + Risk_functional = P(failure in use) × Impact(failure) + C_use_as_is = Warranty risk increase (estimated) + documentation cost + C_sort_or_rework = Direct sort/rework costs + production delay costs +``` + +--- + +## 8. MRB Decision Process — Detailed Workflow + +### 8.1 MRB Meeting Structure + +**Frequency:** Scheduled weekly; ad hoc for urgent dispositions (safety-critical, production-blocking) + +**Required Attendees:** +- Quality Engineering (chair, facilitates and documents) +- Design/Product Engineering (functional impact assessment) +- Manufacturing Engineering (reworkability assessment) +- Production/Operations (schedule impact) +- Procurement (supplier-related dispositions, commercial impact) +- Optional: Regulatory Affairs (if regulatory implications), Customer Quality (if customer notification required) + +**Standard Agenda:** +1. Review of new NCRs pending disposition (by priority: safety first, then production-blocking, then age) +2. Presentation of data package per NCR (measurements, photographs, process data) +3. Engineering assessment of functional impact +4. Disposition decision with documented rationale +5. Review of aging NCRs (> 15 days without disposition) +6. Review of MRB metrics (volume, cycle time, cost) + +### 8.2 MRB Documentation Requirements + +Each MRB disposition must include: + +| Element | Purpose | Who Provides | +|---|---|---| +| NCR number and description | Identification and traceability | Quality Engineering | +| Part number, revision, quantity | Scope of disposition | Quality Engineering | +| Specification violated (clause, dimension, requirement) | Clarity on what's nonconforming | Quality Engineering | +| Measurement data (actuals vs. tolerances) | Evidence base for disposition | Quality Engineering / Inspection | +| Photographs (if applicable) | Visual evidence | Quality Engineering / Inspection | +| Engineering justification (for use-as-is or repair) | Technical rationale for accepting deviation | Design/Product Engineering | +| Risk assessment (for safety-related items) | Formal risk evaluation | Design/Product Engineering + Quality | +| Customer approval reference (if required) | Compliance with contract/standard | Quality Engineering | +| Disposition decision | The decision itself | MRB consensus | +| Signatures of all MRB members | Accountability and traceability | All attendees | +| Cost impact | Financial tracking for COQ | Quality Engineering + Finance | +| CAPA reference (if initiated) | Link to systemic corrective action | Quality Engineering | diff --git a/web-app/public/skills/quality-nonconformance/references/edge-cases.md b/web-app/public/skills/quality-nonconformance/references/edge-cases.md new file mode 100644 index 00000000..c98d9458 --- /dev/null +++ b/web-app/public/skills/quality-nonconformance/references/edge-cases.md @@ -0,0 +1,588 @@ +# Quality & Non-Conformance Management — Edge Cases Reference + +> Tier 3 reference. Load on demand when handling complex or ambiguous quality situations that don't resolve through standard NCR/CAPA workflows. + +These edge cases represent the scenarios that separate experienced quality engineers from everyone else. Each one involves competing priorities, ambiguous data, regulatory pressure, and real business impact. They are structured to guide resolution when standard playbooks break down. + +--- + +## How to Use This File + +When a quality situation doesn't fit a clean NCR category — when the data is ambiguous, when multiple stakeholders have legitimate competing claims, or when the regulatory and business implications justify deeper analysis — find the edge case below that most closely matches the situation. Follow the expert approach step by step. Do not skip documentation requirements; these are the situations that end up in audit findings, regulatory actions, or legal proceedings. + +--- + +### Edge Case 1: Customer-Reported Field Failure with No Internal Detection + +**Situation:** +Your medical device company ships Class II endoscopic accessories to a hospital network. Your internal quality data is clean — incoming inspection acceptance rate is 99.7%, in-process defect rate is below 200 PPM, and final inspection has not flagged any issues for the last 6 months. Then a customer complaint comes in: three units from different lots failed during clinical use. The failure mode is a fractured distal tip during retraction, which was not part of your inspection plan because design verification showed the material exceeds the fatigue limit by 4x. The hospital has paused use of your product pending investigation. + +**Why It's Tricky:** +The instinct is to defend your data. "Our inspection shows everything is within specification. The customer must be using the product incorrectly." This is wrong and dangerous for three reasons: (1) field failures can expose failure modes your test plan doesn't cover, (2) clinical use conditions differ from bench testing, and (3) in FDA-regulated environments, dismissing customer complaints without investigation is itself a regulatory violation per 21 CFR 820.198. + +The deeper problem is that your inspection plan was designed around the design verification data, which tested fatigue under controlled, uniaxial loading. Clinical use involves multiaxial loading with torsion, and the fatigue characteristics under combined loading may be significantly different. Your process is "in control" but your control plan has a coverage gap. + +**Common Mistake:** +Treating this as a customer-use issue. Sending a "letter of clarification" on proper use without investigating the failure mode. This delays discovery, may worsen patient safety risk, and creates an adverse audit trail if FDA reviews your complaint handling. + +The second common mistake: initiating a CAPA that focuses on inspection. "Add fatigue testing to final inspection" solves nothing if the inspection uses the same uniaxial loading condition as the original design verification. + +**Expert Approach:** +1. **Immediate containment:** Place a quality hold on all units of the affected part numbers in your finished goods, distribution, and at the hospital's inventory. Contact the hospital's biomedical engineering department to coordinate the hold — they need serial/lot numbers to identify affected inventory. +2. **Complaint investigation per 820.198:** Open a formal complaint record. Classify for MDR determination — fractured device during clinical use meets the "malfunction that could cause or contribute to death or serious injury" threshold, requiring MDR filing within 30 days. +3. **Failure analysis:** Request the failed units from the hospital for physical failure analysis. Conduct fractographic analysis (SEM if needed) to determine the fracture mode — was it fatigue (progressive crack growth), overload (single-event), stress corrosion, or manufacturing defect (inclusion, porosity)? +4. **Gap analysis on test coverage:** Map the clinical loading conditions against your design verification test protocol. If the failure mode is combined loading fatigue, your uniaxial test would not have detected it. This is a design control gap per 820.30, not a manufacturing control gap. +5. **Design verification update:** Develop a multiaxial fatigue test that simulates clinical conditions. Test retained samples from the affected lots AND from current production. If retained samples fail the updated test, the scope of the problem is potentially every unit shipped. +6. **Risk assessment per ISO 14971:** Update the risk file with the newly identified hazard. Calculate the risk priority based on the severity (clinical failure) and probability (based on complaint rate vs. units in service). Determine whether the risk is acceptable per your risk acceptance criteria. +7. **Field action determination:** Based on the risk assessment, determine whether a voluntary recall, field correction, or enhanced monitoring is appropriate. Document the decision with the risk data supporting it. +8. **CAPA:** Root cause is a gap in design verification testing — the failure mode was not characterized under clinical loading conditions. Corrective action addresses the test protocol, not the manufacturing process. + +**Key Indicators:** +- Complaint rate vs. units in service determines population risk (e.g., 3 failures in 10,000 units = 300 PPM field failure rate) +- Fracture surface morphology distinguishes fatigue, overload, and material defects +- Time-to-failure pattern (all early-life vs. random vs. wear-out) indicates failure mechanism +- If multiple lots are affected, the root cause is likely design or process-related, not material-lot-specific + +**Documentation Required:** +- Formal complaint records per 820.198 +- MDR filing documentation +- Failure analysis report with photographs and fractography +- Updated risk file per ISO 14971 +- Revised design verification test protocol +- Field action decision documentation (including decision NOT to recall, if applicable) +- CAPA record linking complaint → investigation → root cause → corrective action + +--- + +### Edge Case 2: Supplier Audit Reveals Falsified Certificates of Conformance + +**Situation:** +During a routine audit of a casting supplier (Tier 2 supplier to your automotive Tier 1 operation), your auditor discovers that the material certificates for A356 aluminum castings do not match the spectrometer results. The supplier has been submitting CoCs showing material composition within specification, but the auditor's portable XRF readings on randomly selected parts show silicon content at 8.2% against a specification of 6.5-7.5%. The supplier's quality manager initially claims the XRF is inaccurate, but when pressed, admits that their spectrometer has been out of calibration for 4 months, and they've been using historical test results on the CoCs rather than actual lot-by-lot test data. + +**Why It's Tricky:** +This is not a simple non-conformance — it's a quality system integrity failure. The supplier did not simply ship nonconforming parts; they submitted fraudulent documentation. The distinction matters because: (1) every shipment received during the 4-month period is now suspect, (2) you cannot trust ANY data from this supplier without independent verification, (3) in automotive, this may constitute a failure to maintain IATF 16949 requirements, and (4) parts from this supplier may already be in customer vehicles. + +The containment scope is potentially enormous. A356 aluminum with elevated silicon has different mechanical properties — it may be more brittle. If these castings are structural or safety-critical, the implications extend to end-of-line testing, vehicle recalls, and NHTSA notification. + +**Common Mistake:** +Treating this like a normal NCR. Writing a SCAR and asking the supplier to "improve their testing process." This underestimates the severity — the issue is not process improvement but fundamental integrity. A supplier that falsifies data will not be fixed by a corrective action request. + +The second common mistake: immediately terminating the supplier without securing containment. If you have weeks of WIP and finished goods containing these castings, cutting off the supplier before you've contained and sorted the affected inventory creates a dual crisis — quality AND supply. + +**Expert Approach:** +1. **Preserve evidence immediately.** Photograph the audit findings, retain the XRF readings, request copies of the CoCs for the last 4 months, and document the supplier quality manager's admission in the audit notes with date, time, and witnesses. This evidence may be needed for legal proceedings or regulatory reporting. +2. **Scope the containment.** Identify every lot received from this supplier in the last 4+ months (add buffer — the calibration may have drifted before formal "out of calibration" date). Trace those lots through your operation: incoming stock, WIP, finished goods, shipped to customer, in customer's inventory or vehicles. +3. **Independent verification.** Send representative samples from each suspect lot to an accredited independent testing laboratory for full material composition analysis. Do not rely on the supplier's belated retesting — their data has zero credibility. +4. **Risk assessment on affected product.** If material composition is out of spec, have design engineering evaluate the functional impact. A356 with 8.2% Si instead of max 7.5% may still be functional depending on the application, or it may be critically weakened for a structural casting. The answer depends on the specific part function and loading conditions. +5. **Customer notification.** In IATF 16949 environments, customer notification is mandatory when suspect product may have been shipped. Contact your customer quality representative within 24 hours. Provide lot/date range, the nature of the issue, and your containment actions. +6. **Automotive-specific reporting.** If the parts are safety-critical and the composition affects structural integrity, evaluate NHTSA reporting obligations per 49 CFR Part 573 (defect notification). Consult legal counsel — the bar for vehicle safety defect reporting is "poses an unreasonable risk to motor vehicle safety." +7. **Supplier disposition.** This is an immediate escalation to Level 4-5 on the supplier ladder. Begin alternate source qualification in parallel. Maintain the supplier on controlled shipping (CS-2, third-party inspection) only for the duration needed to transition. Do not invest in "developing" a supplier that falsified data — the trust foundation is broken. +8. **Systemic review.** Audit all other CoC-reliant incoming inspection processes. If this supplier falsified data, what is the probability that others are as well? Increase verification sampling on other CoC-reliance suppliers, especially those with single-source positions. + +**Key Indicators:** +- Duration of falsification determines containment scope (months × volume = total suspect population) +- The specific spec exceedance determines functional risk (minor chemistry drift vs. major composition deviation) +- Traceability of material lots through your production determines the search space +- Whether the supplier proactively disclosed vs. you discovered impacts the trust assessment + +**Documentation Required:** +- Audit report with all findings, evidence, and admissions +- XRF readings and independent lab results +- Complete lot traceability from supplier through your process to customer +- Risk assessment on functional impact of material deviation +- Customer notification records with acknowledgment +- Legal review documentation (privilege-protected as applicable) +- Supplier escalation and phase-out plan + +--- + +### Edge Case 3: SPC Shows Process In-Control But Customer Complaints Are Rising + +**Situation:** +Your CNC turning operation produces shafts for a precision instrument manufacturer. Your SPC charts on the critical OD dimension (12.00 ±0.02mm) have been stable for 18 months — X-bar/R chart shows a process running at 12.002mm mean with Cpk of 1.45. No control chart signals. Your internal quality metrics are green across the board. But the customer's complaint rate on your shafts has tripled in the last quarter. Their failure mode: intermittent binding in the mating bore assembly. Your parts meet print, their parts meet print, but the assembly doesn't work consistently. + +**Why It's Tricky:** +The conventional quality response is "our parts meet specification." And technically, that's true. But the customer's assembly process is sensitive to variation WITHIN your specification. Their bore is also within specification, but when your shaft is at the high end of tolerance (+0.02) and their bore is at the low end, the assembly binds. Both parts individually meet print, but the tolerance stack-up creates interference in the worst-case combination. + +The SPC chart is not lying — your process is in statistical control and capable by every standard metric. The problem is that capability indices measure your process against YOUR specification, not against the functional requirement of the assembly. A Cpk of 1.45 means you're producing virtually no parts outside ±0.02mm, but if the actual functional window is ±0.01mm centered on the nominal, your process is sending significant variation into a critical zone. + +**Common Mistake:** +Dismissing the complaint because the data says you're in spec. Sending a letter citing your Cpk and stating that the parts conform. This is technically correct and operationally wrong — it destroys the customer relationship and ignores the actual problem. + +The second mistake: reacting by tightening your internal specification without understanding the functional requirement. If you arbitrarily cut your tolerance to ±0.01mm, you increase your scrap rate (and cost) without certainty that it solves the assembly issue. + +**Expert Approach:** +1. **Acknowledge the complaint and avoid the "we meet spec" defense.** The customer is experiencing real failures. Whether they're caused by your variation, their variation, or the interaction of both is what needs to be determined — not assumed. +2. **Request the customer's mating component data.** Ask for their bore SPC data — mean, variation, Cpk, distribution shape. You need to understand both sides of the assembly equation. +3. **Conduct a tolerance stack-up analysis.** Using both your shaft data and their bore data, calculate the assembly clearance distribution. Identify what percentage of assemblies fall into the interference zone. This analysis converts "your parts meet spec" into "X% of assemblies will have interference problems." +4. **Evaluate centering vs. variation.** If the problem is that your process runs at 12.002mm (slightly above nominal) and their bore is centered low, the fix may be as simple as re-centering your process to 11.998mm — shifting the mean away from the interference zone without changing the variation. +5. **Consider bilateral specification refinement.** Propose a joint engineering review to establish a tighter bilateral tolerance that accounts for both process capabilities. If your Cpk for ±0.01mm around a recentered mean is still > 1.33, the tighter spec is achievable. +6. **Update your control plan.** If the assembly-level functional requirement is tighter than the print tolerance, your control plan should reflect the actual functional target, not just the nominal ± tolerance from the drawing. +7. **This is NOT a CAPA.** This is a specification adequacy issue, not a non-conformance. The correct vehicle is an engineering change process to update the specification, not a CAPA to "fix" a process that is operating correctly per its current requirements. + +**Key Indicators:** +- Your process Cpk relative to the FUNCTIONAL tolerance (not drawing tolerance) is the key metric +- Assembly clearance distribution reveals the actual failure probability +- Shift in customer complaint timing may correlate with a process change on the customer's side (did they tighten their bore process?) +- Temperature effects on both parts at assembly (thermal expansion can change clearances) + +--- + +### Edge Case 4: Non-Conformance Discovered on Already-Shipped Product + +**Situation:** +During a routine review of calibration records, your metrology technician discovers that a CMM probe used for final inspection of surgical instrument components had a qualification failure that was not flagged. The probe was used to inspect and release 14 lots over the past 6 weeks. The qualification failure indicates the probe may have been reading 0.015mm off on Z-axis measurements. The affected dimension is a critical depth on an implantable device component with a tolerance of ±0.025mm. Of the 14 lots (approximately 8,400 units), 9 lots have already been shipped to three different customers (medical device OEMs). Five lots are still in your finished goods inventory. + +**Why It's Tricky:** +The measurement uncertainty introduced by the probe error doesn't mean the parts are nonconforming — it means you can't be certain they're conforming. A 0.015mm bias on a ±0.025mm tolerance doesn't automatically reject all parts, but it may have caused you to accept parts that were actually near or beyond the lower specification limit. + +For FDA-regulated medical device components, measurement system integrity is not optional — it's a core requirement of 21 CFR 820.72 (inspection, measuring, and test equipment). A calibration failure that went undetected means your quality records for 14 lots cannot be relied upon. This is a measurement system failure, not necessarily a product failure, but you must treat it as a potential product failure until proven otherwise. + +**Common Mistake:** +Recalling all 14 lots immediately without first analyzing the data. A blind recall of 8,400 implantable device components creates massive supply chain disruption for your customers (who may be OEMs that incorporate your component into a finished device in their own supply chain). If the actual parts are conforming (just the measurement was uncertain), the recall causes more harm than it prevents. + +The other common mistake: doing nothing because you believe the parts are "probably fine." Failure to investigate and document constitutes a quality system failure, regardless of whether the parts are actually good. + +**Expert Approach:** +1. **Immediate hold on the 5 lots still in inventory.** Quarantine in MRB area. These can be re-inspected. +2. **Quantify the measurement uncertainty.** Re-qualify the CMM probe and determine the actual bias. Then overlay the bias on the original measurement data for all 14 lots. For each part, recalculate: measured value + bias = potential actual value. Identify how many parts' recalculated values fall outside specification. +3. **Risk stratification of shipped lots.** Group the 9 shipped lots into three categories: + - Parts where recalculated values are well within specification (> 50% of tolerance margin remaining): low risk. Document the analysis but no customer notification needed for these specific lots. + - Parts where recalculated values are marginal (within specification but < 25% margin): medium risk. Engineering assessment needed on functional impact. + - Parts where recalculated values potentially exceed specification: high risk. Customer notification required; recall or sort at customer. +4. **Customer notification protocol.** For medium and high-risk lots, notify the customer quality contacts within 24 hours. Provide: lot numbers, the nature of the measurement uncertainty, your risk assessment, and your recommended action (e.g., replace at-risk units, sort at customer site with your quality engineer present, or engineering disposition if parts are functionally acceptable). +5. **Re-inspect the 5 held lots.** Use a verified, qualified CMM probe. Release lots that pass. Scrap or rework lots that fail. +6. **Root cause and CAPA.** Root cause: probe qualification failure was not flagged by the CMM operator or the calibration review process. Investigate why: was the qualification check skipped, was the acceptance criteria not clear, was the operator not trained on the significance of qualification failure? CAPA must address the system gap — likely a combination of calibration software alerting, operator procedure, and management review of calibration status. +7. **Evaluate MDR obligation.** If any shipped parts are potentially outside specification and the component is in an implantable device, evaluate whether this constitutes a reportable event. Consult with Regulatory Affairs — the threshold is whether the situation "could cause or contribute to death or serious injury." The measurement uncertainty may or may not meet this threshold depending on the functional significance of the affected dimension. + +**Key Indicators:** +- The ratio of measurement bias to tolerance width determines the severity (0.015mm bias on ±0.025mm tolerance = 30% of tolerance, which is significant) +- The distribution of original measurements near the specification limit determines how many parts are truly at risk +- Whether the bias was consistent or variable determines whether the risk analysis is conservative or optimistic +- Customer's use of the component (implantable vs. non-patient-contact) determines the regulatory urgency + +--- + +### Edge Case 5: CAPA That Addresses Symptom, Not Root Cause + +**Situation:** +Six months ago, your company closed CAPA-2024-0087 for a recurring dimensional non-conformance on a machined housing. The root cause was documented as "operator measurement technique variation" and the corrective action was "retrain all operators on use of bore micrometer per WI-3302 and implement annual re-certification." Training records show all operators were retrained. The CAPA effectiveness check at 90 days showed zero recurrences. The CAPA was closed. + +Now, the same defect is back. Three NCRs in the last 30 days — all the same failure mode (bore diameter out of tolerance on the same feature). The operators are certified. The work instruction has not changed. The micrometer is in calibration. + +**Why It's Tricky:** +This CAPA failure is embarrassing and common. It reveals two problems: (1) the original root cause analysis was insufficient — "operator technique variation" is a symptom, not a root cause, and (2) the 90-day effectiveness monitoring happened to coincide with a period when the actual root cause was quiescent. + +The deeper issue is organizational: the company's CAPA process accepted a "retrain the operator" corrective action for a recurring dimensional non-conformance. An experienced quality engineer would flag training-only CAPAs for manufacturing non-conformances as inherently weak. + +**Common Mistake:** +Opening a new CAPA with a new number and starting fresh. This creates the illusion of a new problem when it's the same unresolved problem. The audit trail now shows a closed CAPA (false closure) and a new CAPA — which is exactly what an FDA auditor looks for when evaluating CAPA system effectiveness. + +The second mistake: doubling down on training — "more training, more frequently, with a competency test." If the first round of training didn't fix the problem, a second round won't either. + +**Expert Approach:** +1. **Reopen CAPA-2024-0087, do not create a new CAPA.** The original CAPA was ineffective. Document the recurrence as evidence that the CAPA effectiveness verification was premature or based on insufficient data. The CAPA system must track this as a single unresolved issue, not two separate issues. +2. **Discard the original root cause.** "Operator technique variation" must be explicitly rejected as a root cause. Document why: training was implemented and verified, operators are certified, yet the defect recurred. Therefore, the root cause was not operator technique. +3. **Restart root cause analysis with fresh eyes.** Form a new team that includes people who were NOT on the original team (fresh perspective). Use Ishikawa/6M to systematically investigate all cause categories — the original team likely converged too quickly on the Man category. +4. **Investigate the actual root cause candidates:** + - Machine: Is the CNC spindle developing runout or thermal drift? Check spindle vibration data and thermal compensation logs. + - Material: Has the raw material lot changed? Different material hardness affects cutting dynamics and can shift dimensions. + - Method: Did the tool path or cutting parameters change? Check the CNC program revision history. + - Measurement: Is the bore micrometer the right gauge for this measurement? What's the Gauge R&R? If the gauge is marginal, operators may get variable results even with correct technique. + - Environment: Did ambient temperature change with the season? A 5°C temperature swing in a non-climate-controlled shop can shift dimensions by 5-10μm on aluminum parts. +5. **Design the corrective action at a higher effectiveness rank.** If root cause is machine-related: implement predictive maintenance or in-process gauging (detection control, rank 4). If material-related: adjust process parameters by material lot or source from a more consistent supplier (substitution, rank 2). If measurement-related: install a hard-gauging fixture (engineering control, rank 3). Training is only acceptable as a SUPPLEMENTARY action, never the primary action. +6. **Extend the effectiveness monitoring period.** The original 90-day monitoring was insufficient. For a recurring issue, monitor for 6 months or 2 full cycles of the suspected environmental/seasonal factor, whichever is longer. Define quantitative pass criteria (e.g., zero recurrences of the specific failure mode AND Cpk on the affected dimension ≥ 1.33 for the full monitoring period). + +**Key Indicators:** +- The fact that 90-day monitoring showed zero recurrence but the defect returned suggests the root cause is intermittent or cyclic (seasonal temperature, tool wear cycle, material lot cycle) +- Operator-related root causes are almost never the actual root cause for dimensional non-conformances in CNC machining — the machine is controlling the dimension, not the operator +- Gauge R&R data is critical — if the measurement system contribution is > 30% of the tolerance, the measurement itself may be the root cause of apparent non-conformances + +--- + +### Edge Case 6: Audit Finding That Challenges Existing Practice + +**Situation:** +During a customer audit of your aerospace machining facility, the auditor cites a finding against your first article inspection (FAI) process. Your company performs FAI per AS9102 and has a long track record of conforming FAIs. The auditor's finding: you do not perform a full FAI resubmission when you change from one qualified tool supplier to another for the same cutting tool specification. Your position is that the tool meets the same specification (material, geometry, coating) and the cutting parameters are identical, so no FAI is required. The auditor contends that a different tool supplier — even for the same specification — constitutes a "change in manufacturing source for special processes or materials" under AS9102, requiring at minimum a partial FAI. + +**Why It's Tricky:** +Both positions have merit. AS9102 requires FAI when there is a change in "manufacturing source" for the part. A cutting tool is not the part — it's a consumable used to make the part. But the auditor's argument is that a different tool supplier may have different cutting performance characteristics (tool life, surface finish, dimensional consistency) that could affect the part even though the tool itself meets the same specification. + +The practical reality is that your machinists know different tool brands cut differently. A Sandvik insert and a Kennametal insert with the same ISO designation will produce slightly different surface finishes and may wear at different rates. In aerospace, "slightly different" can matter. + +**Common Mistake:** +Arguing with the auditor during the audit. Debating the interpretation of AS9102 in real time is unproductive and creates an adversarial audit relationship. Accept the finding, respond formally, and use the response to present your interpretation with supporting evidence. + +The second mistake: over-correcting by requiring a full FAI for every consumable change. This would make your FAI process unworkable — you change tool inserts multiple times per shift. The corrective action must be proportionate to the actual risk. + +**Expert Approach:** +1. **Accept the audit finding formally.** Do not concede that your interpretation is wrong — accept that the auditor has identified an area where your process does not explicitly address the scenario. Write the response as: "We acknowledge the finding and will evaluate our FAI triggering criteria for manufacturing consumable source changes." +2. **Research industry guidance.** AS9102 Rev C, IAQG FAQ documents, and your registrar's interpretation guides may provide clarity. Contact your certification body's technical manager for their interpretation. +3. **Risk-based approach.** Categorize tool supplier changes by risk: + - Same specification, same brand/series, different batch: No FAI required (normal tool replacement) + - Same specification, different brand: Evaluate with a tool qualification run — measure first articles from the new tool brand against the FAI characteristics. If all characteristics are within specification, document the qualification and don't require formal FAI. + - Different specification or geometry: Full or partial FAI per AS9102 +4. **Process change.** Update your FAI trigger procedure to explicitly address consumable source changes. Create a "tool qualification" process that is lighter than FAI but provides documented evidence that the new tool source produces conforming parts. +5. **Corrective action response.** Your formal response to the auditor should describe the risk-based approach, the tool qualification procedure, and the updated FAI trigger criteria. Demonstrate that you've addressed the gap with a proportionate control, not with a blanket rule that will be unworkable. + +**Key Indicators:** +- The auditor's interpretation may or may not be upheld at the next certification body review — but arguing the point at the audit is always unproductive +- Your machinist's tribal knowledge about tool brand differences is actually valid evidence — document it +- The risk-based approach is defensible because AS9100 itself is built on risk-based thinking + +--- + +### Edge Case 7: Multiple Root Causes for Single Non-Conformance + +**Situation:** +Your injection molding operation is producing connectors with intermittent short shots (incomplete fill) and flash simultaneously on the same tool. SPC on shot weight shows variation has doubled over the last month. The standard 5 Whys analysis by the floor quality technician concluded "injection pressure too low" and recommended increasing pressure by 10%. The problem did not improve — in fact, flash increased while short shots continued. + +**Why It's Tricky:** +Short shots and flash are opposing defects. Short shot = insufficient material reaching the cavity. Flash = material escaping the parting line. Having both simultaneously on the same tool is pathological and indicates that the 5 Whys answer ("pressure too low") was oversimplified. Increasing pressure addresses the short shot but worsens the flash. This is a classic case where 5 Whys fails because the failure has multiple interacting causes, not a single linear chain. + +**Common Mistake:** +Continuing to adjust a single parameter (pressure) up and down looking for a "sweet spot." This is tampering — chasing the process around the operating window without understanding what's driving the variation. + +**Expert Approach:** +1. **Stop adjusting.** Return the process to the validated parameters. Document that the attempted pressure increase did not resolve the issue and created additional flash defects. +2. **Use Ishikawa, not 5 Whys.** Map the potential causes across all 6M categories. For this type of combined defect, the most likely interacting causes are: + - **Machine:** Worn platens or tie bars allowing non-uniform clamp pressure across the mold face. This allows flash where clamp force is low while restricting fill where the parting line is tight. + - **Material:** Material viscosity variation (lot-to-lot MFI variation, or moisture content). High viscosity in one shot → short shot. Low viscosity in next shot → flash. + - **Mold (Method):** Worn parting line surfaces creating uneven shut-off. Vent clogging restricting gas escape in some cavities (causing short shots) while flash at the parting line. +3. **Data collection before root cause conclusion.** Run a short diagnostic study: + - Measure clamp tonnage distribution across the mold face (platen deflection check with pressure-indicating film between the parting surfaces) + - Check material MFI on the current lot and the last 3 lots + - Inspect the mold parting line for wear, verify vent depths +4. **Address ALL contributing causes.** The corrective actions will likely be multiple: + - Mold maintenance (clean vents, re-stone parting line surfaces) — addresses the flash pathway + - Material incoming inspection for MFI with tighter acceptance criteria — addresses viscosity variation + - Platen deflection correction or mold design modification — addresses the non-uniform clamp force +5. **The CAPA must capture all three causes.** Document that the single defect (short shot + flash) has three interacting root causes. Each cause has its own corrective action. Effectiveness monitoring must track the combined defect rate, not each cause independently. + +**Key Indicators:** +- Combined opposing defects always indicate multiple interacting causes — never a single parameter +- Shot-to-shot weight variation (SPC) distinguishes material variation (random pattern) from machine variation (trending or cyclic pattern) +- Pressure-indicating film between mold halves reveals clamp force distribution problems that are invisible otherwise +- Vent depth measurements should be part of routine mold PM but are commonly skipped + +--- + +### Edge Case 8: Intermittent Defect That Cannot Be Reproduced on Demand + +**Situation:** +Your electronics assembly line has a 0.3% field return rate on a PCB assembly due to intermittent solder joint failures on a specific BGA (Ball Grid Array) component. The defect has been reported 47 times across approximately 15,000 units shipped over 6 months. X-ray inspection of returned units shows voiding in BGA solder joints exceeding 25% (your internal standard is <20% voiding). However, your in-process X-ray inspection of production units consistently shows voiding below 15%. The defect is real (47 customer failures is not noise), but your inspection process cannot detect or reproduce it. + +**Why It's Tricky:** +The customer failures are real — 47 returns with consistent failure mode across multiple lots rules out customer misuse. But your production inspection shows conforming product. This means either: (1) your inspection is sampling the wrong things, (2) the voiding develops or worsens after initial inspection (during subsequent thermal cycling in reflow for other components, or during customer thermal cycling in use), or (3) the void distribution varies within the BGA footprint and your X-ray angle doesn't capture the worst-case joints. + +BGA solder joint voiding is particularly insidious because voids that are acceptable at room temperature can cause failure under thermal cycling — the void acts as a stress concentrator and crack initiation site. The failure mechanism is thermomechanical fatigue accelerated by voiding, which means the defect is present at the time of manufacture but only manifests after enough thermal cycles in the field. + +**Common Mistake:** +Increasing the X-ray inspection frequency or adding 100% X-ray inspection. If your current X-ray protocol can't distinguish the failing population from the good population, doing more of the same inspection won't help — you're looking for the defect in the wrong way. + +**Expert Approach:** +1. **Failure analysis on returned units.** Cross-section the BGA solder joints on failed returns. Map the void location, size, and the crack propagation path. Determine if the cracks initiate at voids (they almost always do in BGA thermomechanical fatigue). +2. **X-ray protocol review.** Compare the X-ray imaging parameters (angle, magnification, algorithm) between production inspection and failure analysis inspection. Often, the production X-ray uses a top-down view that averages voiding across the entire joint, while the critical voiding is concentrated at the component-side interface where thermal stress is highest. +3. **Process investigation using DOE.** Solder paste voiding is influenced by: stencil aperture design, paste-to-pad ratio, reflow profile (soak zone temperature and time), pad finish (ENIG vs. OSP vs. HASL), and BGA component pad finish. Run a designed experiment varying the controllable factors against voiding as the response. Use the optimized parameters to reduce the baseline voiding level below the failure threshold. +4. **Reliability testing.** Subject production samples to accelerated thermal cycling (ATC) testing per IPC-9701 (-40°C to +125°C for SnPb, -40°C to +100°C for SAC305). Monitor for failure at intervals. This replicates the field failure mechanism in a controlled environment and allows you to validate that process improvements actually reduce the failure rate. +5. **SPC on voiding.** Implement BGA voiding measurement as an SPC characteristic with limits set based on the reliability test data (not just the IPC-7095 generic guideline). The control limits should be set at the voiding level below which reliability testing shows acceptable life. + +**Key Indicators:** +- 0.3% field return rate in electronics is unusually high for a solder defect — this is a systemic process issue, not random +- Void location within the joint matters more than total void percentage — a 15% void concentrated at the interface is worse than 25% distributed throughout the joint body +- Correlation between void levels and reflow profile parameters (especially time above liquidus and peak temperature) is typically the strongest process lever + +--- + +### Edge Case 9: Supplier Sole-Source with Quality Problems + +**Situation:** +Your sole-source supplier for a custom titanium forging (Ti-6Al-4V, closed-die forging with proprietary tooling) has been on SCAR for the third time in 12 months. The recurring issue is grain flow non-conformance — the microstructural grain flow does not follow the specified contour, which affects fatigue life. The forgings are for a landing gear component (aerospace, AS9100). The forgings cost $12,000 each, with 6-month lead time for tooling and 4-month lead time for production. You need 80 forgings per year. There is no other qualified supplier, and qualifying a new forging source would take 18-24 months including tooling, first articles, and customer qualification. + +**Why It's Tricky:** +This is the sole-source quality trap. Your supplier quality escalation ladder says you should move to controlled shipping and begin alternate source qualification. But controlled shipping at a sole-source supplier is a paper exercise — you'll inspect the forgings, but if they fail, you have no alternative. And beginning alternate source qualification gives you 18-24 months of continued dependence on a problematic supplier. + +The business can't tolerate a supply disruption. Each forging is a $12,000 part with 6+ months of lead time, and you need 80 per year for an active production program. Shutting off the supplier shuts off your production. + +**Common Mistake:** +Treating this like a normal supplier quality issue. Following the escalation ladder to the letter (controlled shipping → alternate source qualification → phase-out) without considering that the escalation ladder was designed for commodity parts with alternatives. For a sole-source strategic supplier, aggressive escalation can backfire — the supplier may deprioritize your business or increase prices. + +The opposite mistake: accepting the recurring non-conformance because you have no alternative. "Use-as-is because we're sole-sourced" is not an acceptable disposition for a safety-critical aerospace forging, regardless of supply constraints. + +**Expert Approach:** +1. **Invest in the supplier, don't just punish them.** Propose a joint development program. Your metallurgical engineer works with their forging process engineer to optimize die design, forging temperature, and press force profile for the grain flow requirement. This is supplier development, not just supplier corrective action. +2. **Root cause the grain flow issue properly.** Grain flow non-conformance in closed-die forging is typically caused by: incorrect billet pre-form shape (material doesn't flow where the die expects it), insufficient forging reduction ratio, incorrect forging temperature (too cold = surface cracking, too hot = grain growth), or die wear allowing material to flow outside the intended path. Which of these is it? Each has a different solution. +3. **Begin alternate source qualification quietly.** Start the 18-24 month qualification process immediately, but do not use it as a threat. Frame it as "supply chain risk mitigation" — even if the supplier improves, having a second source is sound supply chain management for a safety-critical part. +4. **Negotiate a quality improvement agreement.** Work with procurement to structure a commercial agreement: the supplier invests in process improvements (die refurbishment, process parameter optimization, enhanced in-process metallographic inspection), and you commit to volume or price stability over the investment payback period. +5. **Increase your incoming inspection on these forgings.** Regardless of supplier performance, a safety-critical aerospace forging should have metallographic inspection at incoming — don't rely solely on the supplier's certification. The cost of a destructive test sample (one forging per lot) is small relative to the consequence of a grain flow non-conformance reaching the machined part. +6. **MRB each non-conformance individually.** Just because the supplier is sole-sourced does not mean every non-conformance gets a use-as-is disposition. Each forging must be evaluated on its specific grain flow pattern against the design intent. Some deviations may be acceptable with engineering and customer concession; others are scrapped regardless of supply impact. Document the disposition rationale with metallographic evidence and engineering analysis. + +**Key Indicators:** +- Grain flow pattern should be evaluated against the finished machined geometry, not just the forging geometry — material removal during machining can expose grain flow that was within the forging specification but becomes non-conforming in the machined part +- A 3-sigma supply buffer (keep 6+ months of safety stock) is essential while working the quality improvement with a sole source +- Die life tracking correlates with grain flow quality — quality typically degrades as the die wears + +--- + +### Edge Case 10: Non-Conformance Discovered During Regulatory Audit + +**Situation:** +During an FDA inspection of your medical device manufacturing facility, the investigator pulls a traveler for a recently completed production lot of surgical staplers. Reviewing the dimensional inspection data, the investigator notes that two of ten measured dimensions are recorded as "within tolerance" but the actual values are not recorded — only pass/fail. The investigator asks to see the actual measurement values. Your inspector explains that these two dimensions are measured with go/no-go gauges and the pass/fail result is all that's recorded. The investigator issues a Form 483 observation: "There is no procedure to ensure that manufacturing specifications have been met for two critical dimensions on [part number]. Actual measurement data is not recorded." + +The investigator's position: go/no-go gauging on a critical dimension of a Class II surgical device is insufficient because it doesn't provide trend data to detect process drift before the process goes out of specification. Your position: go/no-go gauges are an industry-accepted measurement method, the gauges are calibrated, and the control plan specified this method. + +**Why It's Tricky:** +Both positions are defensible. Go/no-go gauging is a valid measurement method recognized by ASME and used across all manufacturing industries. For many applications, it's actually preferred because it eliminates measurement error — the gauge is either go or no-go, there's no subjective reading. However, the FDA investigator has a point: attribute data (pass/fail) from go/no-go gauges does not support trend analysis or SPC, which means you cannot detect a process drifting toward the specification limit until it actually exceeds the limit and the gauge rejects the part. + +For a critical dimension on a surgical device, the argument for variable data (actual measurements) that supports trend analysis has real merit. This is the tension between measurement practicality and quality system rigor. + +**Common Mistake:** +Arguing with the investigator that go/no-go gauging is adequate. Even if you're technically right, arguing with an FDA investigator during an inspection almost never helps. The observation is written; your opportunity to respond is in the formal 483 response, not in the moment. + +The opposite mistake: immediately committing to variable gauging for every dimension. This may be impractical, expensive, and unnecessary for non-critical dimensions. Over-correcting in response to a 483 creates an unsustainable system. + +**Expert Approach:** +1. **Accept the observation gracefully.** During the inspection: "Thank you. We'll evaluate our measurement methodology for these critical dimensions and respond in our 483 response." Do not argue, do not minimize, do not promise a specific corrective action on the spot. +2. **483 response (due within 15 business days):** Structure the response in four parts: + - **Acknowledgment:** "We acknowledge the observation regarding [specific dimensions, specific part number]." + - **Investigation:** "We have reviewed the measurement methodology for critical dimensions on this part number. We concur that while go/no-go gauging provides conformance verification, it does not support the trend analysis needed to proactively detect process drift on critical dimensions." + - **Corrective action:** "We will implement variable measurement (calibrated digital calipers/micrometers with data recording) for all critical dimensions on Class II and Class III devices, effective [date]. Measurement data will be charted using SPC (X-bar/R) to enable trend detection. Go/no-go gauging will be retained as a secondary verification method." + - **Scope extension:** "We are reviewing all inspection plans for Class II and Class III devices to identify any other critical dimensions using attribute-only gauging and will convert to variable gauging as appropriate." +3. **Implementation.** Actually implement the change before the FDA follow-up (which may be in 6-12 months). Have SPC charts running and demonstrating trend capability by the time of re-inspection. This is what FDA means by "evidence of effectiveness." +4. **Don't over-correct.** Convert critical dimensions to variable gauging. Non-critical dimensions where go/no-go is practical and appropriate can remain as attribute gauging. Document the risk-based rationale for which dimensions require variable data and which do not. + +**Key Indicators:** +- The investigator's observation is about system capability, not about a specific defective product +- A strong 483 response demonstrates that you understand the intent of the observation, not just the letter +- The FDA evaluates your CAPA system partly by how you respond to observations — a proportionate, well-reasoned response is valued over a panicked over-correction +- Scope extension (looking beyond the specific finding to the systemic issue) is explicitly what FDA wants to see in a 483 response + +**Documentation Required:** +- Copy of Form 483 observation +- Formal 483 response with all four sections +- Updated inspection plans showing conversion from attribute to variable gauging +- SPC implementation records (chart setup, control limits, operator training) +- Risk-based rationale document for gauging method selection by characteristic criticality +- Evidence of scope extension review (list of all inspection plans reviewed, findings, and actions) + +--- + +### Edge Case 11: Customer Rejects Lot That Passed Your Final Inspection + +**Situation:** +Your automotive tier 2 plant ships stamped steel brackets to a tier 1 seat frame assembler. Your final inspection per the control plan checks 12 dimensions per AQL sampling (Level II, AQL 1.0). Lot 2025-0892 passed your inspection with zero rejects in the sample. The tier 1 customer's incoming inspection rejects the lot — their 100% automated vision system flagged 4.2% of pieces for a burr height exceeding 0.3mm on edge B. Your control plan does not include burr height on edge B as an inspection characteristic because the customer print specifies "deburr per shop practice" with no quantitative requirement. + +**Why It's Tricky:** +The customer's rejection appears to add a requirement that isn't on the drawing. "Deburr per shop practice" is a qualitative, subjective call — there's no measurable specification. However, the customer has an automated system that quantifies what "shop practice" means operationally. From the customer's perspective, 4.2% of parts have burrs that interfere with their automated assembly process. From your perspective, you met all dimensioned requirements and the subjective "deburr" note cannot be objectively measured. + +This is a specification gap, not a quality failure — but you still have a rejected lot, a customer demanding corrective action, and a control plan that doesn't cover the issue. + +**Common Mistake:** +Refusing the rejection because the requirement isn't quantified on the drawing. This is technically correct and commercially disastrous — the customer doesn't care about specification semantics; their assembly line is down. + +**Expert Approach:** +1. **Accept the return or sort on-site.** Business continuity first. Offer to send a sort team to the customer's facility to 100% inspect and remove the nonconforming parts, or accept the return and sort at your facility. This gets the customer's line running while you address the systemic issue. +2. **Request the quantitative requirement.** Contact the customer's quality engineering team and ask them to provide a measurable specification for burr height on edge B. "We need a quantified requirement to add this to our control plan and SPC program. Can you issue a drawing change or specification supplement with a maximum burr height?" +3. **Interim control.** While the drawing change is in process, add burr height inspection to your control plan as a customer-specific requirement with the threshold from their vision system (0.3mm max). +4. **Process investigation.** Why is burr height variable? Investigate stamping die condition — progressive die wear on the cutting edge increases burr height over the production run. Establish a die maintenance interval based on burr height progression, not just parts count. +5. **PPAP update.** Once the customer issues a formal specification for burr height, submit a PPAP update (at minimum a control plan revision and MSA for the new characteristic). + +**Key Indicators:** +- Burr height typically increases with die wear — plot burr height vs. parts since last die sharpen to establish the maintenance interval +- "Deburr per shop practice" without quantification is a common specification deficiency — the corrective action is a drawing change, not a process change +- The customer's 4.2% reject rate suggests your process is close to the threshold — a small process improvement (die maintenance interval) may reduce the rate below detection + +--- + +### Edge Case 12: Cross-Contamination in Multi-Product Manufacturing + +**Situation:** +Your pharmaceutical contract manufacturer runs tablet compression on Line 3 for both Product A (a controlled substance, Schedule III) and Product B (an over-the-counter supplement). Changeover between products follows your validated cleaning procedure (cleaning validation study CV-2023-011). During a routine post-cleaning swab analysis before starting Product B, the QC lab reports trace levels of Product A's active ingredient at 0.8 ppm — your validated cleaning limit is 1.0 ppm based on MACO (Maximum Allowable Carryover) calculation. The result is within specification, so the line is released for production. + +Two weeks later, the FDA requests your cleaning validation data during an inspection. The investigator points out that your MACO calculation used the maximum daily dose of Product B (the "contaminated" product) as 10 grams, but the actual maximum daily dose on the current label is 15 grams (the label was updated 6 months ago, but the MACO calculation was not revised). Recalculating with the correct maximum daily dose, the cleaning limit should be 0.67 ppm — and the 0.8 ppm result now exceeds the corrected limit. + +**Why It's Tricky:** +The cleaning validation was "validated" but the underlying calculation is now incorrect. This means: (1) every batch of Product B produced since the label change may have been exposed to unacceptable levels of Product A (a controlled substance, adding regulatory severity), (2) your cleaning validation program has a gap — it doesn't trigger recalculation when the inputs change, and (3) the FDA investigator has identified a systemic quality system failure, not just an isolated event. + +**Common Mistake:** +Arguing that 0.8 ppm is toxicologically insignificant. The FDA doesn't operate on "it's probably fine" — they operate on validated limits derived from documented calculations. If the calculation is wrong, the limit is wrong, and the validation is invalid. + +**Expert Approach:** +1. **Acknowledge the finding.** Do not debate the arithmetic with the FDA investigator. The calculation error is factual. +2. **Immediate containment.** Place a hold on all in-process and unreleased Product B lots manufactured since the label change. Review the cleaning verification results for every changeover in that period. For lots where the cleaning result exceeded the corrected 0.67 ppm limit, conduct a risk assessment on the actual patient exposure. +3. **Toxicological risk assessment.** Engage your toxicologist or a qualified consultant to assess the actual risk. At 0.8 ppm of Product A in Product B with a maximum daily dose of 15g, the maximum daily exposure to Product A is 12 µg. Is this below the ADI (Acceptable Daily Intake) for Product A's active ingredient? If yes, document this as a secondary justification — but it doesn't fix the process gap. +4. **Recalculate and revalidate.** Update the MACO calculation with the correct inputs. If the new limit (0.67 ppm) requires a different cleaning procedure, validate the new procedure. If the existing cleaning procedure can meet the new limit (review all historical data), document the cleaning verification with the new limit. +5. **Systemic corrective action.** The root cause is not the arithmetic error — it's the absence of a change control linkage between product labeling changes and cleaning validation inputs. The CAPA must establish a formal review trigger: any change to maximum daily dose, therapeutic dose, or product formulation triggers a review of all affected MACO calculations. +6. **Batch disposition.** For lots where Product B was produced with cleaning results between 0.67 and 1.0 ppm: if the toxicological assessment shows the exposure is within ADI, the lots may be dispositioned as acceptable with documentation. If exposure exceeds ADI, the lots must be rejected. + +**Key Indicators:** +- The MACO calculation inputs (maximum daily dose, minimum daily dose of contaminating product, safety factor) must be traceable to current product documentation +- A cleaning validation that hasn't been reviewed after a product change is not validated — it's out of date +- Controlled substance cross-contamination adds DEA regulatory obligations on top of FDA obligations +- The systemic fix (change control linkage) is more important than the specific calculation correction + +--- + +### Edge Case 13: Supplier Ships Correct Part but Wrong Material Certification + +**Situation:** +Your aerospace receiving inspection accepts a lot of 200 titanium fasteners (Ti-6Al-4V per AMS 4928) from a qualified supplier. The CoC shows the correct material specification. Your incoming dimensional inspection on a sample of 13 pieces passes. The parts are released into production. During assembly, one of your technicians notices the fasteners seem to machine differently during a modification step — they're cutting "easier" than expected for Ti-6Al-4V. You pull a part and send it for material verification via handheld XRF. The result shows the parts are commercially pure (CP) titanium (Grade 2), not Ti-6Al-4V. The CoC is for the correct material, but the actual parts are wrong. + +**Why It's Tricky:** +CP titanium Grade 2 and Ti-6Al-4V are both titanium, and visually indistinguishable. The CoC was correct for the material the supplier intended to ship, but a lot mix-up at the supplier's warehouse resulted in the wrong material being shipped. Your incoming inspection checked dimensions (which happen to be identical between the two materials) but did not perform material verification testing. + +In aerospace, this is a potential counterfeit/suspect part situation per AS9100 §8.1.4, even if it was an innocent mix-up. CP Grade 2 has significantly lower yield and tensile strength than Ti-6Al-4V (345 MPa vs. 880 MPa yield) — a safety-critical difference on a structural fastener. + +**Common Mistake:** +Assuming the parts can be sorted by XRF and the wrong material returned. While that's eventually the disposition, the immediate priority is containment: how many of the 200 fasteners have already been installed in assemblies? Those assemblies may need to be torn down and the fasteners replaced. + +**Expert Approach:** +1. **Immediate quarantine of all remaining fasteners.** Mark as suspect; do not use for any purpose until material verification is complete. +2. **Containment — trace forward.** How many of the 200 fasteners have been consumed in production? Which assemblies? Are any of those assemblies already shipped to the customer? Each installed CP titanium fastener in a structure designed for Ti-6Al-4V is a potential structural failure in service. +3. **100% material verification on remaining stock.** XRF every remaining fastener. Separate confirmed Ti-6Al-4V (if any) from confirmed CP Grade 2. +4. **Engineering assessment on installed fasteners.** For each assembly containing suspect fasteners, engineering must evaluate: (a) the specific loading condition on each fastener location, (b) whether CP Grade 2 meets the structural requirement at that location (it may for lightly loaded positions), and (c) whether the assembly can be reworked (remove and replace the fastener) without damaging the structure. +5. **Customer notification.** For shipped assemblies, notify the customer immediately with traceability data. The customer must evaluate their own installation context and downstream assemblies. +6. **Supplier investigation.** This is a material traceability failure at the supplier. Issue a SCAR demanding: (a) root cause of the lot mix-up, (b) containment of other orders that may have been affected by the same mix-up, (c) implementation of positive material identification (PMI) as a pre-shipment verification step. This is a Level 2 or Level 3 escalation depending on whether the supplier has had material-related non-conformances before. +7. **GIDEP reporting.** If the investigation suggests the material substitution was anything other than an innocent warehouse mix-up, report to GIDEP per AS9100 counterfeit prevention requirements. +8. **Incoming inspection update.** Add PMI (XRF or OES) to the incoming inspection plan for all structural material lots, regardless of supplier qualification level. CoC reliance without material verification is a known vulnerability for material mix-ups. + +**Key Indicators:** +- The machinability difference noticed by the technician is a real and reliable indicator — CP titanium machines significantly differently from Ti-6Al-4V (lower cutting forces, different chip formation) +- XRF can distinguish Grade 2 from Ti-6Al-4V quickly by the absence of aluminum and vanadium peaks +- The safety risk depends entirely on the application — a CP Grade 2 fastener in a lightly loaded panel is probably fine; the same fastener in a primary structure fitting is a safety-of-flight concern +- Lot traceability from the supplier's heat/melt lot number through their inventory system to your PO is the critical investigation path + +--- + +### Edge Case 14: CAPA System Backlog Creating Systemic Risk + +**Situation:** +Your quality management system currently has 147 open CAPAs. Of these, 62 are past their target closure date, with 23 overdue by more than 6 months. The quality team of 4 engineers is overwhelmed. Management's response has been to hire a temporary contractor to "clear the backlog." Your registrar audit is in 8 weeks, and the auditor will evaluate CAPA system effectiveness. FDA conducted an inspection 18 months ago and noted a 483 observation about CAPA timeliness; you committed to improvement in your response. + +**Why It's Tricky:** +The backlog itself is a symptom, and the proposed solution (hire a contractor to "close" CAPAs) is likely to create a bigger problem than it solves. A contractor who doesn't understand your processes, products, and quality history will either (a) close CAPAs with superficial effectiveness evidence, or (b) take months to ramp up and not clear the backlog in time. + +The deeper issue: 147 open CAPAs in a 4-person quality team means the system is initiating too many CAPAs, not that the team is closing too few. If every NCR and every minor audit finding generates a CAPA, the system is undifferentiated — everything is treated the same, so nothing gets adequate attention. + +**Common Mistake:** +Mass-closing CAPAs to reduce the count. Closing CAPAs without verified effectiveness is worse than having them open — it's a systemic falsification of the quality record. An auditor who sees 60 CAPAs closed in the last 2 weeks before an audit will investigate the closure quality, and finding superficial closures is a major finding. + +**Expert Approach:** +1. **Triage the 147 open CAPAs.** Categorize each into one of four buckets: + - **Active and valid:** Root cause is systemic, corrective action is in progress or effective. These stay open and get prioritized. + - **Should not have been CAPAs:** Isolated non-conformances that were over-escalated to CAPA. These should be downgraded to NCR dispositions with documented rationale for why CAPA was not required. This is not "closing for convenience" — it's applying correct CAPA initiation criteria retroactively. + - **Duplicate or overlapping:** Multiple CAPAs addressing the same root cause from different trigger events. Consolidate into a single CAPA with all triggers linked. + - **Stale and no longer applicable:** Process or product has changed since the CAPA was initiated, making the original issue moot. Close with documented rationale that the original condition no longer exists. +2. **Right-size the CAPA pipeline.** After triage, the active CAPA count should drop to 40-60 (manageable for a 4-person team at ~10-15 CAPAs per engineer). Prioritize by risk: safety and regulatory CAPAs first, customer-facing CAPAs second, internal improvement CAPAs third. +3. **Fix the initiation criteria.** Update the CAPA initiation procedure with clear, documented criteria for what warrants a CAPA vs. what is handled at the NCR level. Train the quality team on the updated criteria. This is the actual corrective action for the backlog — preventing future over-initiation. +4. **Demonstrate systemic improvement at audit.** Present the triage analysis, the updated initiation criteria, the prioritization methodology, and the current CAPA metrics (average closure time, effectiveness rate for closed CAPAs). An auditor who sees a thoughtful, risk-based approach to CAPA management will view this far more favorably than a frantic mass-closure. +5. **Address the FDA commitment.** Your 483 response committed to improvement in CAPA timeliness. The triage and process change demonstrate systemic improvement, which is what FDA expects. Simply clearing the backlog without fixing the systemic cause would be repeating the same failure. + +**Key Indicators:** +- CAPA count per engineer is the capacity metric — more than 15 active CAPAs per engineer indicates either over-initiation or under-resourcing +- The ratio of CAPAs initiated to CAPAs closed per month shows whether the pipeline is growing or shrinking +- Effectiveness rate (CAPAs closed with verified effectiveness, no recurrence) is more important than closure rate +- Auditors assess CAPA system maturity, not CAPA count — a mature system has few, well-managed CAPAs + +**Documentation Required:** +- CAPA triage register with categorization and rationale for each CAPA +- Updated CAPA initiation procedure (before and after revision) +- Management review presentation showing backlog analysis and improvement plan +- Metrics dashboard showing CAPA pipeline health (open count, aging, closure rate, effectiveness rate) +- Training records for quality team on updated initiation criteria +- Communication to management on the root cause of the backlog (over-initiation, not under-performance) + +--- + +### Edge Case 15: Process Validation Deviation During FDA-Regulated Production + +**Situation:** +Your medical device manufacturing facility completed process validation (IQ/OQ/PQ) for an ultrasonic welding process 18 months ago. The validated parameters include a weld force of 800N ±50N, amplitude of 40µm, and weld time of 0.6 seconds. During routine production monitoring, the quality engineer notices that the weld force has been running at 760N for the last 3 production lots — technically within the validated range (750-850N), but at the very bottom. The process has not been formally changed. Upon investigation, the force transducer was recalibrated 4 weeks ago, and the calibration adjustment shifted the reading by approximately 40N. The actual physical weld force has likely been consistent — it's the measurement that shifted. + +But there's a catch: the process validation was performed with the old calibration. If the transducer was reading 40N high during validation, the actual weld force during PQ was 760-810N, not the documented 800-850N. This means the validation data may not represent what was actually validated. + +**Why It's Tricky:** +This is not a simple calibration adjustment — it's a retroactive question about the validity of the process validation itself. If the force transducer was reading high during validation, the documented validated range (750-850N indicated) actually corresponded to 710-810N actual force. The question becomes: was the process validated at the range you thought it was validated at? + +For FDA 21 CFR 820.75, process validation must demonstrate that the process produces results consistently meeting predetermined specifications. If the validation data was collected with a biased instrument, the validation conclusion may be unsound. + +**Common Mistake:** +Ignoring the implication because "the process hasn't changed." The process may not have changed, but your understanding of what was validated has changed. This matters for FDA because the validation must be scientifically sound, and a 40N measurement bias on an 800N nominal process (5% bias) is not trivial. + +The second mistake: invalidating the process and halting production for a full revalidation. This may be an overreaction if the product quality data (test results, field performance) supports that the process has been producing conforming product throughout. + +**Expert Approach:** +1. **Quantify the calibration shift.** Review the calibration records — what was the as-found reading vs. the as-left reading during the last calibration? If the as-found was 40N high and the as-left is now correct, the shift is documented. +2. **Retrospective data analysis.** Collect all product quality data (weld pull-test results, leak test results, or whatever the product-level test is that verifies weld integrity) from the entire period between calibrations. If the product quality data shows consistent, conforming results throughout, this is strong evidence that the process, regardless of the measurement bias, was producing acceptable product. +3. **Impact assessment on validation.** Recalculate the process capability from the PQ study using the corrected force values (subtract the 40N bias from all documented force readings). If the corrected data still demonstrates capability (Cpk ≥ 1.33) within the specification range, the validation conclusion remains sound even with the adjusted values. +4. **Protocol for validated range.** If the corrected data shifts the validated range, determine whether the current operating point (760N indicated = 760N actual with corrected calibration) falls within the corrected validated range. If yes, no action needed beyond documentation. If no, a bridging validation study may be required to extend the validated range. +5. **Calibration program improvement.** The root cause is that the calibration program did not evaluate the impact of calibration adjustments on process validation status. The CAPA should establish a change control trigger: any calibration adjustment exceeding a defined threshold (e.g., > 2% of nominal) triggers a review of the impact on process validation. +6. **Documentation.** File this as a deviation to the process validation protocol. Document the impact assessment, the retrospective data analysis, the conclusion on validation status, and the corrective action. This creates the audit trail that demonstrates you identified, evaluated, and resolved the issue — which is what FDA expects. + +**Key Indicators:** +- The ratio of calibration shift to process tolerance determines severity (40N shift on a ±50N tolerance = 80% of tolerance, which is significant) +- Product-level test data is the ultimate evidence of process acceptability — it measures the output, not the input +- Calibration as-found/as-left data should always be evaluated for process validation impact, not just instrument accuracy + +**Documentation Required:** +- Calibration certificate showing as-found and as-left values +- Retrospective product quality data analysis with statistical summary +- Impact assessment on process validation (corrected PQ data analysis) +- Deviation report to process validation protocol +- Updated calibration program procedure requiring validation impact assessment + +--- + +## Quick Reference: Edge Case Pattern Recognition + +The edge cases above share common patterns. When you encounter a quality situation that feels complex, check which pattern(s) apply: + +### Pattern A: Specification Gap +**Signature:** Parts meet the documented specification but fail in application. +**Edge cases:** 3 (SPC in-control but complaints rising), 6 (audit finding challenging practice), 11 (customer rejects lot that passed inspection) +**Key question:** Is the specification adequate for the functional requirement? +**Default action:** Collaborate with the customer/user to quantify the real requirement. + +### Pattern B: Measurement System Integrity +**Signature:** The quality data says everything is fine, but reality disagrees. +**Edge cases:** 1 (field failure with no internal detection), 4 (shipped product with calibration issue), 8 (intermittent defect can't reproduce), 10 (go/no-go vs. variable gauging), 15 (calibration shift affects validation) +**Key question:** Is the measurement system capable of detecting the actual failure mode? +**Default action:** Evaluate measurement system against the failure mode, not just the specification. + +### Pattern C: Trust Breakdown +**Signature:** Data or documentation cannot be relied upon. +**Edge cases:** 2 (falsified CoCs), 13 (wrong material with correct cert) +**Key question:** What is the full scope of potentially affected product? +**Default action:** Independent verification; do not rely on the compromised data source. + +### Pattern D: Systemic Process Failure +**Signature:** The corrective action treats a symptom; the problem recurs. +**Edge cases:** 5 (CAPA addresses symptom not root cause), 7 (multiple root causes), 14 (CAPA backlog) +**Key question:** Is the root cause analysis rigorous enough? +**Default action:** Restart RCA with fresh team and more rigorous methodology. + +### Pattern E: Competing Priorities +**Signature:** Quality requirements conflict with supply or business constraints. +**Edge cases:** 9 (sole-source with quality problems), 12 (cross-contamination with supply implications) +**Key question:** What is the minimum acceptable quality action that maintains regulatory compliance? +**Default action:** Risk-based approach with parallel paths (fix the problem AND develop alternatives). + +### Cross-Referencing Edge Cases with Decision Frameworks + +| Edge Case | Primary Decision Framework | Secondary Framework | +|---|---|---| +| 1. Field failure no internal detection | CAPA initiation criteria | FDA reporting obligations | +| 2. Falsified CoCs | Supplier escalation ladder (Level 4-5) | NCR disposition (containment scope) | +| 3. SPC in-control, complaints rising | Cp/Cpk interpretation | Specification adequacy review | +| 4. NC on shipped product | NCR disposition (containment) | Customer notification protocol | +| 5. CAPA addresses symptom | RCA method selection (upgrade methodology) | CAPA effectiveness verification | +| 6. Audit finding challenges practice | Audit response protocol | Risk-based process change | +| 7. Multiple root causes | RCA method selection (Ishikawa/FTA) | CAPA action hierarchy | +| 8. Intermittent defect | Measurement system evaluation | SPC chart selection | +| 9. Sole-source quality problems | Supplier develop vs. switch | MRB economic model | +| 10. NC during regulatory audit | Regulatory response protocol | CAPA timeliness standards | +| 11. Customer rejects despite passing | Specification gap analysis | Control plan update | +| 12. Cross-contamination | Cleaning validation | FDA field action determination | +| 13. Wrong material, correct cert | Counterfeit prevention (AS9100) | Incoming inspection update | +| 14. CAPA backlog | CAPA initiation criteria triage | Management review | +| 15. Validation deviation | Process validation impact assessment | Calibration program improvement | diff --git a/web-app/public/skills/quant-analyst/SKILL.md b/web-app/public/skills/quant-analyst/SKILL.md index 9ce77053..c84d4b6f 100644 --- a/web-app/public/skills/quant-analyst/SKILL.md +++ b/web-app/public/skills/quant-analyst/SKILL.md @@ -1,6 +1,7 @@ --- name: quant-analyst -description: "Build financial models, backtest trading strategies, and analyze" +description: | + Build financial models, backtest trading strategies, and analyze market data. Implements risk metrics, portfolio optimization, and statistical arbitrage. Use PROACTIVELY for quantitative finance, trading algorithms, or risk analysis. diff --git a/web-app/public/skills/reference-builder/SKILL.md b/web-app/public/skills/reference-builder/SKILL.md index 83611fa8..d66d4b65 100644 --- a/web-app/public/skills/reference-builder/SKILL.md +++ b/web-app/public/skills/reference-builder/SKILL.md @@ -1,6 +1,7 @@ --- name: reference-builder -description: "Creates exhaustive technical references and API documentation." +description: | + Creates exhaustive technical references and API documentation. Generates comprehensive parameter listings, configuration guides, and searchable reference materials. Use PROACTIVELY for API docs, configuration references, or complete technical specifications. diff --git a/web-app/public/skills/returns-reverse-logistics/SKILL.md b/web-app/public/skills/returns-reverse-logistics/SKILL.md new file mode 100644 index 00000000..fde9d64d --- /dev/null +++ b/web-app/public/skills/returns-reverse-logistics/SKILL.md @@ -0,0 +1,231 @@ +--- +name: returns-reverse-logistics +description: > + Codified expertise for returns authorisation, receipt and inspection, + disposition decisions, refund processing, fraud detection, and warranty + claims management. Informed by returns operations managers with 15+ years + experience. Includes grading frameworks, disposition economics, fraud + pattern recognition, and vendor recovery processes. Use when handling + product returns, reverse logistics, refund decisions, return fraud + detection, or warranty claims. +license: Apache-2.0 +version: 1.0.0 +homepage: https://github.com/evos-ai/evos-capabilities +risk: safe +source: https://github.com/ai-evos/agent-skills +metadata: + author: evos + clawdbot: + emoji: "🔄" +--- + +## When to Use + +Use this skill when managing the product return lifecycle, including authorization, physical inspection, making disposition decisions (e.g., restock vs. liquidator), detecting return fraud, or processing warranty claims. + +# Returns & Reverse Logistics + +## Role and Context + +You are a senior returns operations manager with 15+ years handling the full returns lifecycle across retail, e-commerce, and omnichannel environments. Your responsibilities span return merchandise authorisation (RMA), receiving and inspection, condition grading, disposition routing, refund and credit processing, fraud detection, vendor recovery (RTV), and warranty claims management. Your systems include OMS (order management), WMS (warehouse management), RMS (returns management), CRM, fraud detection platforms, and vendor portals. You balance customer satisfaction against margin protection, processing speed against inspection accuracy, and fraud prevention against false-positive customer friction. + +## Core Knowledge + +### Returns Policy Logic + +Every return starts with policy evaluation. The policy engine must account for overlapping and sometimes conflicting rules: + +- **Standard return window:** Typically 30 days from delivery for most general merchandise. Electronics often 15 days. Perishables non-returnable. Furniture/mattresses 30-90 days with specific condition requirements. Extended holiday windows (purchases Nov 1 – Dec 31 returnable through Jan 31) create a surge that peaks mid-January. +- **Condition requirements:** Most policies require original packaging, all accessories, and no signs of use beyond reasonable inspection. "Reasonable inspection" is where disputes live — a customer who removed laptop screen protector film has technically altered the product but this is normal unboxing behaviour. +- **Receipt and proof of purchase:** POS transaction lookup by credit card, loyalty number, or phone number has largely replaced paper receipts. Gift receipts entitle the bearer to exchange or store credit at the purchase price, never cash refund. No-receipt returns are capped (typically $50-75 per transaction, 3 per rolling 12 months) and refunded at lowest recent selling price. +- **Restocking fees:** Applied to opened electronics (15%), special-order items (20-25%), and large/bulky items requiring return shipping coordination. Waived for defective products or fulfilment errors. The decision to waive for customer goodwill requires margin awareness — waiving a $45 restocking fee on a $300 item with 28% margin costs more than it appears. +- **Cross-channel returns:** Buy-online-return-in-store (BORIS) is expected by customers and operationally complex. Online prices may differ from store prices. The refund should match the original purchase price, not the current store shelf price. Inventory system must accept the unit back into store inventory or flag for return-to-DC. +- **International returns:** Duty drawback eligibility requires proof of re-export within the statutory window (typically 3-5 years depending on country). Return shipping costs often exceed product value for low-cost items — offer "returnless refund" when shipping exceeds 40% of product value. Customs declarations for returned goods differ from original export documentation. +- **Exceptions:** Price-match returns (customer found it cheaper), buyer's remorse beyond window with compelling circumstances, defective products outside warranty, and loyalty tier overrides (top-tier customers get extended windows and waived fees) all require judgment frameworks rather than rigid rules. + +### Inspection and Grading + +Returned products require consistent grading that drives disposition decisions. Speed and accuracy are in tension — a 30-second visual inspection moves volume but misses cosmetic defects; a 5-minute functional test catches everything but creates bottleneck at scale: + +- **Grade A (Like New):** Original packaging intact, all accessories present, no signs of use, passes functional test. Restockable as new or "open box" with full margin recovery (85-100% of original retail). Target inspection time: 45-90 seconds. +- **Grade B (Good):** Minor cosmetic wear, original packaging may be damaged or missing outer sleeve, all accessories present, fully functional. Restockable as "open box" or "renewed" at 60-80% of retail. May need repackaging ($2-5 per unit). Target inspection time: 90-180 seconds. +- **Grade C (Fair):** Visible wear, scratches, or minor damage. Missing accessories that cost <10% of unit value. Functional but cosmetically impaired. Sells through secondary channels (outlet, marketplace, liquidation) at 30-50% of retail. Refurbishment possible if cost < 20% of recovered value. +- **Grade D (Salvage/Parts):** Non-functional, heavily damaged, or missing critical components. Salvageable for parts or materials recovery at 5-15% of retail. If parts recovery isn't viable, route to recycling or destruction. + +Grading standards vary by category. Consumer electronics require functional testing (power on, screen check, connectivity) adding 2-4 minutes per unit. Apparel inspection focuses on stains, odour, stretched fabric, and missing tags — experienced inspectors use the "arm's length sniff test" and UV light for stain detection. Cosmetics and personal care items are almost never restockable once opened due to health regulations. + +### Disposition Decision Trees + +Disposition is where returns either recover value or destroy margin. The routing decision is economics-driven: + +- **Restock as new:** Only Grade A with complete packaging. Product must pass any required functional/safety testing. Relabelling or resealing may trigger regulatory issues (FTC "used as new" enforcement). Best for high-margin items where the restocking cost ($3-8 per unit) is trivial relative to recovered value. +- **Repackage and sell as "open box":** Grade A with damaged packaging or Grade B items. Repackaging cost ($5-15 depending on complexity) must be justified by the margin difference between open-box and next-lower channel. Electronics and small appliances are the sweet spot. +- **Refurbish:** Economically viable when refurbishment cost < 40% of the refurbished selling price, and a refurbished sales channel exists (certified refurbished program, manufacturer's outlet). Common for premium electronics, power tools, and small appliances. Requires dedicated refurb station, spare parts inventory, and re-testing capacity. +- **Liquidate:** Grade C and some Grade B items where repackaging/refurb isn't justified. Liquidation channels include pallet auctions (B-Stock, DirectLiquidation, Bulq), wholesale liquidators (per-pound pricing for apparel, per-unit for electronics), and regional liquidators. Recovery rates: 5-20% of retail. Critical insight: mixing categories in a pallet destroys value — electronics/apparel/home goods pallets sell at the lowest-category rate. +- **Donate:** Tax-deductible at fair market value (FMV). More valuable than liquidation when FMV > liquidation recovery AND the company has sufficient tax liability to utilise the deduction. Brand protection: restrict donations of branded products that could end up in discount channels undermining brand positioning. +- **Destroy:** Required for recalled products, counterfeit items found in the return stream, products with regulatory disposal requirements (batteries, electronics with WEEE compliance, hazmat), and branded goods where any secondary market presence is unacceptable. Certificate of destruction required for compliance and tax documentation. + +### Fraud Detection + +Return fraud costs US retailers $24B+ annually. The challenge is detection without creating friction for legitimate customers: + +- **Wardrobing (wear and return):** Customer buys apparel or accessories, wears them for an event, returns them. Indicators: returns clustered around holidays/events, deodorant residue, makeup on collars, creased/stretched fabric inconsistent with "tried on." Countermeasure: black-light inspection for cosmetic traces, RFID security tags that customers aren't instructed to remove (if the tag is missing, the item was worn). +- **Receipt fraud:** Using found, stolen, or fabricated receipts to return shoplifted merchandise for cash. Declining as digital receipt lookup replaces paper, but still occurs. Countermeasure: require ID for all cash refunds, match return to original payment method, limit no-receipt returns per ID. +- **Swap fraud (return switching):** Returning a counterfeit, cheaper, or broken item in the packaging of a purchased item. Common in electronics (returning a used phone in a new phone box) and cosmetics (refilling a container with a cheaper product). Countermeasure: serial number verification at return, weight check against expected product weight, detailed inspection of high-value items before processing refund. +- **Serial returners:** Customers with return rates > 30% of purchases or > $5,000 in annual returns. Not all are fraudulent — some are genuinely indecisive or bracket-shopping (buying multiple sizes to try). Segment by: return reason consistency, product condition at return, net lifetime value after returns. A customer with $50K in purchases and $18K in returns (36% rate) but $32K net revenue is worth more than a customer with $15K in purchases and zero returns. +- **Bracketing:** Intentionally ordering multiple sizes/colours with the plan to return most. Legitimate shopping behaviour that becomes costly at scale. Address through fit technology (size recommendation tools, AR try-on), generous exchange policies (free exchange, restocking fee on return), and education rather than punishment. +- **Price arbitrage:** Purchasing during promotions/discounts, then returning at a different location or time for full-price credit. Policy must tie refund to actual purchase price regardless of current selling price. Cross-channel returns are the primary vector. +- **Organised retail crime (ORC):** Coordinated theft-and-return operations across multiple stores/identities. Indicators: high-value returns from multiple IDs at the same address, returns of commonly shoplifted categories (electronics, cosmetics, health), geographic clustering. Report to LP (loss prevention) team — this is beyond standard returns operations. + +### Vendor Recovery + +Not all returns are the customer's fault. Defective products, fulfilment errors, and quality issues have a cost recovery path back to the vendor: + +- **Return-to-vendor (RTV):** Defective products returned within the vendor's warranty or defect claim window. Process: accumulate defective units (minimum RTV shipment thresholds vary by vendor, typically $200-500), obtain RTV authorisation number, ship to vendor's designated return facility, track credit issuance. Common failure: letting RTV-eligible product sit in the returns warehouse past the vendor's claim window (often 90 days from receipt). +- **Defect claims:** When defect rate exceeds the vendor agreement threshold (typically 2-5%), file a formal defect claim for the excess. Requires defect documentation (photos, inspection notes, customer complaint data aggregated by SKU). Vendors will challenge — your data quality determines your recovery. +- **Vendor chargebacks:** For vendor-caused issues (wrong item shipped from vendor DC, mislabelled products, packaging failures) charge back the full cost including return shipping and processing labour. Requires a vendor compliance program with published standards and penalty schedules. +- **Credit vs replacement vs write-off:** If the vendor is solvent and responsive, pursue credit. If the vendor is overseas with difficult collections, negotiate replacement product. If the claim is small (< $200) and the vendor is a critical supplier, consider writing it off and noting it in the next contract negotiation. + +### Warranty Management + +Warranty claims are distinct from returns and follow a different workflow: + +- **Warranty vs return:** A return is a customer exercising their right to reverse a purchase (typically within 30 days, any reason). A warranty claim is a customer reporting a product defect within the warranty coverage period (90 days to lifetime). Different systems, different policies, different financial treatment. +- **Manufacturer vs retailer obligation:** The retailer is typically responsible for the return window. The manufacturer is responsible for the warranty period. Grey area: the "lemon" product that keeps failing within warranty — the customer wants a refund, the manufacturer offers repair, and the retailer is caught in the middle. +- **Extended warranties/protection plans:** Sold at point of sale with 30-60% margins. Claims against extended warranties are handled by the warranty provider (often a third party). Retailer's role is facilitating the claim, not processing it. Common complaint: customers don't distinguish between retailer return policy, manufacturer warranty, and extended warranty coverage. + +## Decision Frameworks + +### Disposition Routing by Category and Condition + +| Category | Grade A | Grade B | Grade C | Grade D | +| -------------------- | -------------------- | ---------------------- | ----------------------------------- | ---------------------------- | +| Consumer Electronics | Restock (test first) | Open box / Renewed | Refurb if ROI > 40%, else liquidate | Parts harvest or e-waste | +| Apparel | Restock if tags on | Repackage / outlet | Liquidate by weight | Textile recycling | +| Home & Furniture | Restock | Open box with discount | Liquidate (local, avoid shipping) | Donate or destroy | +| Health & Beauty | Restock if sealed | Destroy (regulation) | Destroy | Destroy | +| Books & Media | Restock | Restock (discount) | Liquidate | Recycle | +| Sporting Goods | Restock | Open box | Refurb if cost < 25% value | Parts or donate | +| Toys & Games | Restock if sealed | Open box | Liquidate | Donate (if safety-compliant) | + +### Fraud Scoring Model + +Score each return 0-100. Flag for review at 65+, hold refund at 80+: + +| Signal | Points | Notes | +| ---------------------------------------------------- | ------ | ---------------------------------------- | +| Return rate > 30% (rolling 12 mo) | +15 | Adjusted for category norms | +| Item returned within 48 hours of delivery | +5 | Could be legitimate bracket shopping | +| High-value electronics, serial number mismatch | +40 | Near-certain swap fraud | +| Return reason changed between initiation and receipt | +10 | Inconsistency flag | +| Multiple returns same week | +10 | Cumulative with rate signal | +| Return from address different than shipping address | +10 | Gift returns excluded | +| Product weight differs > 5% from expected | +25 | Swap or missing components | +| Customer account < 30 days old | +10 | New account risk | +| No-receipt return | +15 | Higher risk of receipt fraud | +| Item in category with high shrink rate | +5 | Electronics, cosmetics, designer apparel | + +### Vendor Recovery ROI + +Pursue vendor recovery when: `(Expected credit × probability of collection) > (Labour cost + shipping cost + relationship cost)`. Rules of thumb: + +- Claims > $500: Always pursue. The math works even at 50% collection probability. +- Claims $200-500: Pursue if the vendor has a functional RTV programme and you can batch shipments. +- Claims < $200: Batch until threshold is met, or offset against next PO. Do not ship individual units. +- Overseas vendors: Increase minimum threshold to $1,000. Add 30% to expected processing time. + +### Return Policy Exception Logic + +When a return falls outside standard policy, evaluate in this order: + +1. **Is the product defective?** If yes, accept regardless of window or condition. Defective products are the company's problem, not the customer's. +2. **Is this a high-value customer?** (Top 10% by LTV) If yes, accept with standard refund. The retention math almost always favours the exception. +3. **Is the request reasonable to a neutral observer?** A customer returning a winter coat in March that they bought in November (4 months, outside 30-day window) is understandable. A customer returning a swimsuit in December that they bought in June is less so. +4. **What is the disposition outcome?** If the product is restockable (Grade A), the cost of the exception is minimal — grant it. If it's Grade C or worse, the exception costs real margin. +5. **Does granting create a precedent risk?** One-time exceptions for documented circumstances rarely create precedent. Publicised exceptions (social media complaints) always do. + +## Key Edge Cases + +These are situations where standard workflows fail. Brief summaries — see [edge-cases.md](references/edge-cases.md) for full analysis. + +1. **High-value electronics with firmware wiped:** Customer returns a laptop claiming defect, but the unit has been factory-reset and shows 6 months of battery cycle count. The device was used extensively and is now being returned as "defective" — grading must look beyond the clean software state. + +2. **Hazmat return with improper packaging:** Customer returns a product containing lithium batteries or chemicals without the required DOT packaging. Accepting creates regulatory liability; refusing creates a customer service problem. The product cannot go back through standard parcel return shipping. + +3. **Cross-border return with duty implications:** An international customer returns a product that was exported with duty paid. The duty drawback claim requires specific documentation that the customer doesn't have. The return shipping cost may exceed the product value. + +4. **Influencer bulk return post-content-creation:** A social media influencer purchases 20+ items, creates content, returns all but one. Technically within policy, but the brand value was extracted. Restocking challenges compound because unboxing videos show the exact items. + +5. **Warranty claim on product modified by customer:** Customer replaced a component in a product (e.g., upgraded RAM in a laptop), then claims a warranty defect in an unrelated component (e.g., screen failure). The modification may or may not void the warranty for the claimed defect. + +6. **Serial returner who is also a high-value customer:** Customer with $80K annual spend and a 42% return rate. Banning them from returns loses a profitable customer; accepting the behaviour encourages continuation. Requires nuanced segmentation beyond simple return rate. + +7. **Return of a recalled product:** Customer returns a product that is subject to an active safety recall. The standard return process is wrong — recalled products follow the recall programme, not the returns programme. Mixing them creates liability and reporting errors. + +8. **Gift receipt return where current price exceeds purchase price:** The gift recipient brings a gift receipt. The item is now selling for $30 more than the gift-giver paid. Policy says refund at purchase price, but the customer sees the shelf price and expects that amount. + +## Communication Patterns + +### Tone Calibration + +- **Standard refund confirmation:** Warm, efficient. Lead with the resolution amount and timeline, not the process. +- **Denial of return:** Empathetic but clear. Explain the specific policy, offer alternatives (exchange, store credit, warranty claim), provide escalation path. Never leave the customer with no options. +- **Fraud investigation hold:** Neutral, factual. "We need additional time to process your return" — never say "fraud" or "investigation" to the customer. Provide a timeline. Internal communications are where you document the fraud indicators. +- **Restocking fee explanation:** Transparent. Explain what the fee covers (inspection, repackaging, value loss) and confirm the net refund amount before processing so there are no surprises. +- **Vendor RTV claim:** Professional, evidence-based. Include defect data, photos, return volumes by SKU, and reference the vendor agreement section that covers defect claims. + +### Key Templates + +Brief templates below. Full versions with variables in [communication-templates.md](references/communication-templates.md). + +**RMA approval:** Subject: `Return Approved — Order #{order_id}`. Provide: RMA number, return shipping instructions, expected refund timeline, condition requirements. + +**Refund confirmation:** Lead with the number: "Your refund of ${amount} has been processed to your [payment method]. Please allow [X] business days." + +**Fraud hold notice:** "Your return is being reviewed by our processing team. We expect to have an update within [X] business days. We appreciate your patience." + +## Escalation Protocols + +### Automatic Escalation Triggers + +| Trigger | Action | Timeline | +| ------------------------------------------------------------------ | ---------------------------------------------------------------- | ----------------- | +| Return value > $5,000 (single item) | Supervisor approval required before refund | Before processing | +| Fraud score ≥ 80 | Hold refund, route to fraud review team | Immediately | +| Customer has filed chargeback simultaneously | Halt return processing, coordinate with payments team | Within 1 hour | +| Product identified as recalled | Route to recall coordinator, do not process as standard return | Immediately | +| Vendor defect rate exceeds 5% for SKU | Notify merchandise and vendor management | Within 24 hours | +| Third policy exception request from same customer in 12 months | Manager review before granting | Before processing | +| Suspected counterfeit in return stream | Pull from processing, photograph, notify LP and brand protection | Immediately | +| Return involves regulated product (pharma, hazmat, medical device) | Route to compliance team | Immediately | + +### Escalation Chain + +Level 1 (Returns Associate) → Level 2 (Team Lead, 2 hours) → Level 3 (Returns Manager, 8 hours) → Level 4 (Director of Operations, 24 hours) → Level 5 (VP, 48+ hours or any single-item return > $25K) + +## Performance Indicators + +| Metric | Target | Red Flag | +| ----------------------------------------------------- | ---------- | ---------- | +| Return processing time (receipt to refund) | < 48 hours | > 96 hours | +| Inspection accuracy (grade agreement on audit) | > 95% | < 88% | +| Restock rate (% of returns restocked as new/open box) | > 45% | < 30% | +| Fraud detection rate (confirmed fraud caught) | > 80% | < 60% | +| False positive rate (legitimate returns flagged) | < 3% | > 8% | +| Vendor recovery rate ($ recovered / $ eligible) | > 70% | < 45% | +| Customer satisfaction (post-return CSAT) | > 4.2/5.0 | < 3.5/5.0 | +| Cost per return processed | < $8.00 | > $15.00 | + +## Additional Resources + +- For detailed disposition trees, fraud scoring, vendor recovery frameworks, and grading standards, see [decision-frameworks.md](references/decision-frameworks.md) +- For the comprehensive edge case library with full analysis, see [edge-cases.md](references/edge-cases.md) +- For complete communication templates with variables and tone guidance, see [communication-templates.md](references/communication-templates.md) + +## When to Use + +Use this skill when you need to **design, improve, or troubleshoot returns and reverse logistics operations**: + +- Defining or revising returns policies, grading standards, and disposition routes across channels. +- Investigating high return rates, fraud patterns, or margin leakage in refunds and write‑offs. +- Building SOPs, scorecards, or automation flows for RMAs, inspections, RTV, and warranty workflows in retail or e‑commerce environments. diff --git a/web-app/public/skills/returns-reverse-logistics/references/communication-templates.md b/web-app/public/skills/returns-reverse-logistics/references/communication-templates.md new file mode 100644 index 00000000..d769c3bf --- /dev/null +++ b/web-app/public/skills/returns-reverse-logistics/references/communication-templates.md @@ -0,0 +1,532 @@ +# Communication Templates — Returns & Reverse Logistics + +> **Reference Type:** Tier 3 — Load on demand when composing or reviewing returns-related communications. +> +> **Usage:** Each template includes variable placeholders in `{{double_braces}}` for direct substitution. Templates are organized by audience and stage. Select the template matching your scenario, substitute variables, review tone guidance, and send. + +--- + +## Table of Contents + +1. [RMA Approval Notification](#1-rma-approval-notification) +2. [RMA Denial Notification](#2-rma-denial-notification) +3. [Fraud Investigation Hold Notice](#3-fraud-investigation-hold-notice) +4. [Vendor RTV Claim Submission](#4-vendor-rtv-claim-submission) +5. [Customer Refund Confirmation](#5-customer-refund-confirmation) +6. [Restocking Fee Explanation](#6-restocking-fee-explanation) +7. [Warranty Claim Filing to Manufacturer](#7-warranty-claim-filing-to-manufacturer) +8. [Disposition Report (Internal)](#8-disposition-report-internal) +9. [Return Policy Exception Approval](#9-return-policy-exception-approval) + +--- + +## Variable Reference + +Common variables used across templates: + +| Variable | Description | Example | +|---|---|---| +| `{{customer_name}}` | Customer's full name | `Sarah Chen` | +| `{{customer_email}}` | Customer's email | `schen@email.com` | +| `{{order_number}}` | Original order number | `ORD-2025-88431` | +| `{{rma_number}}` | Return merchandise authorisation number | `RMA-2025-04872` | +| `{{product_name}}` | Product name/description | `Sony WH-1000XM5 Wireless Headphones` | +| `{{product_sku}}` | Product SKU | `SNY-WH1000XM5-BLK` | +| `{{serial_number}}` | Product serial number | `SN-8834201` | +| `{{purchase_date}}` | Original purchase date | `2025-09-14` | +| `{{purchase_price}}` | Original purchase price | `$349.99` | +| `{{refund_amount}}` | Refund amount to be issued | `$349.99` | +| `{{restocking_fee}}` | Restocking fee amount | `$52.50` | +| `{{payment_method}}` | Original payment method (masked) | `Visa ending in 4821` | +| `{{return_reason}}` | Customer-stated return reason | `Product not as described` | +| `{{return_window_end}}` | Last day for standard return | `2025-10-14` | +| `{{rma_expiry}}` | RMA label/authorisation expiry date | `2025-10-28` | +| `{{our_company}}` | Our company name | `Apex Commerce Inc.` | +| `{{our_contact_name}}` | Returns team contact name | `Maria Gonzalez` | +| `{{our_contact_title}}` | Contact's title | `Returns Operations Supervisor` | +| `{{our_contact_email}}` | Contact email | `returns@apexcommerce.com` | +| `{{our_contact_phone}}` | Contact phone | `(800) 555-0199` | +| `{{vendor_name}}` | Vendor / manufacturer name | `Bose Corporation` | +| `{{vendor_contact}}` | Vendor returns contact | `James Park, RTV Coordinator` | +| `{{vendor_account}}` | Vendor account number | `APEX-VND-00342` | +| `{{defect_description}}` | Description of the defect | `Left ear cup intermittent audio dropout` | +| `{{inspection_grade}}` | Assigned condition grade | `Grade B` | +| `{{disposition_route}}` | Disposition decision | `Open box resale` | +| `{{business_days}}` | Processing time in business days | `5-7` | +| `{{carrier_name}}` | Return shipping carrier | `UPS Ground` | +| `{{tracking_number}}` | Return shipment tracking | `1Z999AA10123456784` | +| `{{warranty_end_date}}` | Warranty expiration date | `2027-09-14` | +| `{{claim_number}}` | Warranty or vendor claim reference | `WC-2025-11294` | + +--- + +## 1. RMA Approval Notification + +### When to Use +- Customer has initiated a return request and it has been approved under standard policy or an authorised exception. +- Send immediately upon RMA approval to minimise the time the customer holds the product. + +### Tone Guidance +Warm and efficient. The customer made a decision to return — make it easy. Lead with the actionable information (RMA number, shipping instructions), not the policy. + +### What NOT to Say +- Do not ask "are you sure?" or attempt to dissuade the return at this stage. +- Do not include language that implies the customer did something wrong. +- Do not bury the shipping instructions below marketing content. + +### Template + +**Subject:** Your Return Has Been Approved — RMA# {{rma_number}} + +--- + +Hi {{customer_name}}, + +Your return for **{{product_name}}** (Order {{order_number}}) has been approved. + +**Your RMA Number:** {{rma_number}} + +**How to Return Your Item:** + +1. Pack the product in its original packaging with all accessories included. +2. Print the prepaid return label attached to this email. +3. Attach the label to the outside of the package. +4. Drop off the package at any {{carrier_name}} location. + +**Important Details:** +- Please ship your return by **{{rma_expiry}}** — the RMA expires after this date. +- Once we receive and inspect your return, your refund of **{{refund_amount}}** will be processed to your {{payment_method}} within {{business_days}} business days. + +If you have any questions, reply to this email or call us at {{our_contact_phone}}. + +Best regards, +{{our_company}} Returns Team + +--- + +## 2. RMA Denial Notification + +### When to Use +- The return request does not meet policy requirements (outside window, excluded category, condition not met). +- Always provide specific reasons and alternative options. + +### Tone Guidance +Empathetic but clear. The customer will be disappointed. Acknowledge their situation, explain the specific reason (not generic "per our policy"), and always offer at least one alternative path forward. + +### What NOT to Say +- Do not use "unfortunately" more than once. +- Do not cite policy section numbers or legalistic language. +- Do not close the door completely — always provide an alternative or escalation path. +- Never say "there's nothing we can do." + +### Template + +**Subject:** Regarding Your Return Request — Order {{order_number}} + +--- + +Hi {{customer_name}}, + +Thank you for contacting us about returning your **{{product_name}}** (Order {{order_number}}, purchased {{purchase_date}}). + +After reviewing your request, we're unable to process a standard return because **{{denial_reason}}**. + +**We understand this is frustrating, and we want to help. Here are your options:** + +{{#if warranty_eligible}} +- **Warranty claim:** Your product is still covered under the manufacturer's warranty through {{warranty_end_date}}. We can help you file a warranty claim for repair or replacement. Just reply to this email and we'll get that started. +{{/if}} + +{{#if exchange_eligible}} +- **Exchange:** While we can't offer a refund, we can arrange an exchange for the same product or a similar item. A {{restocking_fee_pct}}% restocking fee would apply. +{{/if}} + +- **Store credit:** We may be able to offer store credit on a case-by-case basis. If you'd like us to review this option, please reply with any additional details about your situation. + +- **Speak with a supervisor:** If you feel your situation warrants an exception, we're happy to have a supervisor review your case. Call us at {{our_contact_phone}} and ask for a returns supervisor. + +We value your business and want to find a solution that works for you. + +Sincerely, +{{our_contact_name}} +{{our_company}} Returns Team +{{our_contact_email}} | {{our_contact_phone}} + +--- + +## 3. Fraud Investigation Hold Notice + +### When to Use +- A return has been flagged by the fraud scoring system (score ≥ 65) and requires review before the refund is processed. +- The customer must be informed of the delay without revealing the fraud investigation. + +### Tone Guidance +Neutral and professional. This is a "processing delay" notification. NEVER use the words "fraud," "suspicious," "investigation," or "flagged." The customer may be entirely legitimate — the hold is precautionary. + +### What NOT to Say +- Never say "your return has been flagged." +- Never reference fraud, theft, or abuse. +- Never imply the customer has done something wrong. +- Do not give an indefinite timeline — always commit to a specific review window. + +### Template + +**Subject:** Your Return is Being Processed — Order {{order_number}} + +--- + +Hi {{customer_name}}, + +Thank you for your return of **{{product_name}}** (RMA# {{rma_number}}). + +We've received your returned item and it is currently undergoing our quality review process. This review ensures we accurately assess the product's condition and process your refund correctly. + +**We expect to complete this review within {{review_days}} business days.** + +You don't need to do anything at this time. We'll send you a confirmation email once your refund has been processed. + +If you have questions in the meantime, you can reach us at {{our_contact_phone}} or reply to this email. + +Thank you for your patience, +{{our_company}} Returns Team + +--- + +### Internal Companion Note (Not Sent to Customer) + +**Fraud Review — RMA# {{rma_number}}** + +| Field | Detail | +|---|---| +| Customer | {{customer_name}} ({{customer_email}}) | +| Fraud Score | {{fraud_score}} | +| Primary Signals | {{fraud_signals}} | +| Product | {{product_name}} ({{product_sku}}) | +| Return Value | {{purchase_price}} | +| Customer LTV | {{customer_ltv}} | +| Action Required | {{review_action}} | +| Review Deadline | {{review_deadline}} | +| Assigned To | {{reviewer_name}} | + +**Review Instructions:** Complete inspection with photo documentation. Verify serial number against order record. Check product weight against expected weight. Compare physical product against product listing. Document findings in the fraud case management system. Recommend: process refund / partial refund / deny with escalation. + +--- + +## 4. Vendor RTV Claim Submission + +### When to Use +- Submitting a return-to-vendor claim for defective products, vendor-caused quality issues, or vendor compliance violations. +- Attach all supporting documentation (photos, inspection reports, customer complaint data). + +### Tone Guidance +Professional and evidence-based. Vendors respond to data, not complaints. Lead with the facts: SKU, quantity, defect description, return rate data. Reference the vendor agreement section that covers defect claims. + +### Template + +**Subject:** RTV Claim — {{vendor_account}} — {{claim_number}} + +--- + +{{vendor_contact}}, + +Please find below our return-to-vendor claim for defective merchandise received under account {{vendor_account}}. + +**Claim Reference:** {{claim_number}} +**Date Submitted:** {{claim_date}} +**RTV Authorisation #:** {{rtv_auth_number}} (if applicable) + +**Claim Details:** + +| SKU | Product Name | Qty Defective | Defect Description | Unit Cost | Extended | +|---|---|---|---|---|---| +| {{sku_1}} | {{product_1}} | {{qty_1}} | {{defect_1}} | {{cost_1}} | {{ext_1}} | +| {{sku_2}} | {{product_2}} | {{qty_2}} | {{defect_2}} | {{cost_2}} | {{ext_2}} | + +**Total Claim Amount:** {{total_claim_amount}} + +**Supporting Documentation (attached):** +- Defect photographs ({{photo_count}} images) +- Inspection reports for each SKU +- Customer return data by SKU (return rate, complaint summary) +- Original purchase order(s): {{po_numbers}} + +**Defect Rate Analysis:** +- SKU {{sku_1}}: {{defect_rate_1}}% return rate ({{period}}), versus category baseline of {{baseline_rate}}% +- Excess returns above baseline: {{excess_units}} units + +Per Section {{agreement_section}} of our Vendor Agreement dated {{agreement_date}}, defective merchandise exceeding the {{defect_threshold}}% defect rate threshold is eligible for full credit including inbound freight and return processing costs. + +**Requested Resolution:** Full merchandise credit of {{total_claim_amount}} plus return processing costs of {{processing_costs}} and inbound freight of {{freight_costs}}, for a total claim of {{grand_total}}. + +Please confirm receipt and provide expected credit timeline. Per our agreement, vendor credits are due within {{credit_days}} days of claim submission. + +Regards, +{{our_contact_name}} +{{our_contact_title}} +{{our_company}} +{{our_contact_email}} | {{our_contact_phone}} + +--- + +## 5. Customer Refund Confirmation + +### When to Use +- Refund has been processed. This is the final communication for a standard return. +- Send immediately when the refund is initiated (not when it clears the customer's bank). + +### Tone Guidance +Warm and concise. Lead with the refund amount and timeline. The customer wants to know: how much and when. + +### Template + +**Subject:** Your Refund Has Been Processed — {{refund_amount}} + +--- + +Hi {{customer_name}}, + +Your refund for **{{product_name}}** (Order {{order_number}}) has been processed. + +**Refund Details:** +- **Amount:** {{refund_amount}} +- **Refunded to:** {{payment_method}} +- **Expected arrival:** {{refund_timeline}} + +{{#if restocking_fee_applied}} +A restocking fee of {{restocking_fee}} was applied per our return policy for opened {{product_category}} items. Your original purchase price was {{purchase_price}}. +{{/if}} + +{{#if store_credit}} +Your store credit of {{store_credit_amount}} has been added to your account and is available immediately. +{{/if}} + +Thank you for shopping with us. If there's anything else we can help with, we're here. + +Best, +{{our_company}} Customer Care + +--- + +## 6. Restocking Fee Explanation + +### When to Use +- When a restocking fee is applied and the customer questions it (either proactively at the time of return or in response to a complaint). + +### Tone Guidance +Transparent and factual. Explain what the fee covers. Do not be apologetic about the policy, but do be clear about the specific dollar amounts. + +### Template + +**Subject:** Re: Your Return — Restocking Fee Details + +--- + +Hi {{customer_name}}, + +I understand you have a question about the restocking fee on your return of **{{product_name}}**. + +Here's a breakdown: + +| Item | Amount | +|---|---| +| Original purchase price | {{purchase_price}} | +| Restocking fee ({{restocking_fee_pct}}%) | -{{restocking_fee}} | +| **Your refund** | **{{refund_amount}}** | + +**Why a restocking fee is applied:** + +Our return policy includes a {{restocking_fee_pct}}% restocking fee for opened {{product_category}} products. This fee covers the cost of inspecting, testing, and repackaging the product so it can be offered to the next customer at a reduced "open box" price. Once an item has been opened and used, it can no longer be sold as new, and the restocking fee helps offset this value difference. + +**Please note:** Restocking fees are waived for defective products and fulfilment errors. If you believe your product was defective, please let us know and we'll review — if a defect is confirmed, we'll refund the restocking fee. + +If you'd like to discuss further, please call us at {{our_contact_phone}} or reply to this email. + +Regards, +{{our_contact_name}} +{{our_company}} Returns Team + +--- + +## 7. Warranty Claim Filing to Manufacturer + +### When to Use +- Filing a warranty claim with the manufacturer on behalf of the customer or for retailer-held defective inventory. + +### Tone Guidance +Formal and thorough. Manufacturers process warranty claims based on documentation quality. Include everything upfront to avoid back-and-forth. + +### Template + +**Subject:** Warranty Claim — {{claim_number}} — {{product_name}} + +--- + +To: {{manufacturer_warranty_dept}} + +**Warranty Claim Submission** + +| Field | Detail | +|---|---| +| Claim Reference | {{claim_number}} | +| Retailer Account | {{retailer_account_number}} | +| Product | {{product_name}} ({{product_sku}}) | +| Serial Number | {{serial_number}} | +| Purchase Date | {{purchase_date}} | +| Warranty Expiration | {{warranty_end_date}} | +| Defect Description | {{defect_description}} | +| Date Defect Reported | {{defect_report_date}} | + +**Customer Information:** +- Name: {{customer_name}} +- Original Order: {{order_number}} +- Customer has been provided interim resolution: {{interim_resolution}} + +**Defect Documentation:** +- Photographs of defect: attached ({{photo_count}} images) +- Functional test results: {{test_results}} +- Customer description of defect: "{{customer_defect_statement}}" + +**Product Condition:** +- Physical condition: {{physical_condition}} +- Modifications: {{modifications_noted}} +- Accessories present: {{accessories_status}} + +**Requested Resolution:** {{requested_resolution}} (repair / replacement / credit) + +Please confirm receipt and provide claim processing timeline. The customer is awaiting resolution. + +Regards, +{{our_contact_name}} +{{our_contact_title}} +{{our_company}} +{{our_contact_email}} | {{our_contact_phone}} + +--- + +## 8. Disposition Report (Internal) + +### When to Use +- Weekly or monthly summary of returns disposition outcomes for management review. +- Used to track recovery rates, identify disposition efficiency opportunities, and monitor fraud trends. + +### Tone Guidance +Data-first, concise. Management reads these for trends and exceptions, not prose. + +### Template + +**Subject:** Returns Disposition Report — {{report_period}} + +--- + +## Summary + +| Metric | This Period | Prior Period | Trend | +|---|---|---|---| +| Total returns received | {{total_returns}} | {{prior_total}} | {{trend_total}} | +| Total return value | {{total_value}} | {{prior_value}} | {{trend_value}} | +| Average return value | {{avg_value}} | {{prior_avg}} | {{trend_avg}} | +| Restock rate (Grade A) | {{restock_pct}}% | {{prior_restock}}% | {{trend_restock}} | +| Open box / renewed rate (Grade B) | {{open_box_pct}}% | {{prior_open_box}}% | {{trend_ob}} | +| Liquidation rate (Grade C) | {{liquidation_pct}}% | {{prior_liq}}% | {{trend_liq}} | +| Destroy / recycle rate (Grade D) | {{destroy_pct}}% | {{prior_destroy}}% | {{trend_destroy}} | +| Net recovery rate | {{recovery_pct}}% | {{prior_recovery}}% | {{trend_recovery}} | +| Fraud flags triggered | {{fraud_flags}} | {{prior_fraud}} | {{trend_fraud}} | +| Confirmed fraud cases | {{confirmed_fraud}} | {{prior_confirmed}} | {{trend_confirmed}} | +| Vendor RTV claims filed | {{rtv_count}} ({{rtv_value}}) | {{prior_rtv}} | {{trend_rtv}} | + +## Top Return Reasons + +| Reason | Count | % of Total | Avg Value | +|---|---|---|---| +| {{reason_1}} | {{count_1}} | {{pct_1}}% | {{avg_1}} | +| {{reason_2}} | {{count_2}} | {{pct_2}}% | {{avg_2}} | +| {{reason_3}} | {{count_3}} | {{pct_3}}% | {{avg_3}} | +| {{reason_4}} | {{count_4}} | {{pct_4}}% | {{avg_4}} | +| {{reason_5}} | {{count_5}} | {{pct_5}}% | {{avg_5}} | + +## Top SKUs by Return Volume + +| SKU | Product | Returns | Return Rate | Primary Reason | Action | +|---|---|---|---|---|---| +| {{sku_1}} | {{prod_1}} | {{ret_1}} | {{rate_1}}% | {{reason_sku_1}} | {{action_1}} | +| {{sku_2}} | {{prod_2}} | {{ret_2}} | {{rate_2}}% | {{reason_sku_2}} | {{action_2}} | +| {{sku_3}} | {{prod_3}} | {{ret_3}} | {{rate_3}}% | {{reason_sku_3}} | {{action_3}} | + +## Exceptions and Escalations + +- {{exception_summary_1}} +- {{exception_summary_2}} +- {{exception_summary_3}} + +## Recommendations + +- {{recommendation_1}} +- {{recommendation_2}} +- {{recommendation_3}} + +--- + +Prepared by: {{our_contact_name}}, {{our_contact_title}} +Distribution: {{distribution_list}} + +--- + +## 9. Return Policy Exception Approval + +### When to Use +- When an exception to standard return policy has been approved (outside window, missing receipt, condition outside standard acceptance criteria). +- Documents the exception for audit trail and communicates the decision to the customer. + +### Tone Guidance +Customer-facing version: warm, conveys that you went above and beyond. Internal version: factual, documents the business justification. + +### Customer-Facing Template + +**Subject:** Good News — Your Return Has Been Approved + +--- + +Hi {{customer_name}}, + +We've reviewed your return request for **{{product_name}}** (Order {{order_number}}) and we're happy to let you know that we've approved it as a one-time exception. + +**Here's what you need to know:** + +- **Refund amount:** {{refund_amount}} as {{refund_type}} +- **How to return:** {{return_instructions}} +- **RMA Number:** {{rma_number}} (valid through {{rma_expiry}}) + +{{#if conditions}} +**Please note:** {{exception_conditions}} +{{/if}} + +We appreciate your loyalty and hope this helps. If you need anything else, we're here. + +Best, +{{our_contact_name}} +{{our_company}} Customer Care + +--- + +### Internal Approval Record + +**Policy Exception Approval** + +| Field | Detail | +|---|---| +| RMA | {{rma_number}} | +| Customer | {{customer_name}} ({{customer_email}}) | +| Order | {{order_number}} | +| Product | {{product_name}} ({{product_sku}}) | +| Purchase Price | {{purchase_price}} | +| Refund Amount | {{refund_amount}} | +| Refund Type | {{refund_type}} | +| Standard Policy Violation | {{policy_violation}} | +| Exception Score | {{exception_score}} (per Exception Matrix) | +| Customer LTV | {{customer_ltv}} | +| Customer Return Rate | {{customer_return_rate}}% | +| Business Justification | {{business_justification}} | +| Approved By | {{approver_name}} ({{approver_title}}) | +| Approval Date | {{approval_date}} | +| Precedent Risk | {{precedent_risk}} | +| Notes | {{approval_notes}} | diff --git a/web-app/public/skills/returns-reverse-logistics/references/decision-frameworks.md b/web-app/public/skills/returns-reverse-logistics/references/decision-frameworks.md new file mode 100644 index 00000000..6b84367f --- /dev/null +++ b/web-app/public/skills/returns-reverse-logistics/references/decision-frameworks.md @@ -0,0 +1,823 @@ +# Decision Frameworks — Returns & Reverse Logistics + +This reference provides the detailed decision logic, scoring matrices, financial models, +grading standards, and disposition workflows for returns and reverse logistics operations. +It is loaded on demand when the agent needs to make or recommend nuanced return-handling +decisions. + +All thresholds, timelines, and cost assumptions reflect US retail and e-commerce operations +with applicability to omnichannel, pure-play e-commerce, and brick-and-mortar environments. + +--- + +## 1. Disposition Decision Trees by Product Category + +### 1.1 Decision Methodology + +Every returned item follows a decision tree that routes to the highest-value disposition +channel. The routing decision is made after grading (see §5) and considers: + +1. **Recovered value** at each disposition tier (restock, open box, refurbish, liquidate, donate, destroy) +2. **Processing cost** for each tier (inspection, repackaging, refurbishment, shipping) +3. **Time-to-recovery** — cash tied up in returns inventory has a carrying cost +4. **Regulatory constraints** — some dispositions are prohibited for certain categories +5. **Brand protection** — premium brands may restrict secondary-market sales + +The **net recovery** for any disposition = `(Sale price at channel) - (Processing cost) - (Shipping cost) - (Channel fees)`. + +Always route to the disposition with the highest net recovery, subject to regulatory and +brand constraints. + +### 1.2 Consumer Electronics + +Consumer electronics are the highest-value and most complex returns category. Serial numbers, +firmware states, activation locks, and functional testing requirements add cost and time. + +``` +RECEIVE → Verify serial number matches RMA + ├── Mismatch → Flag for fraud review (swap fraud), HALT processing + └── Match → Visual inspection + ├── Grade A (no cosmetic defects, all accessories, original packaging) + │ └── Functional test (power on, screen, connectivity, battery health) + │ ├── Pass → Check activation lock / factory reset status + │ │ ├── Locked → Contact customer for unlock, hold 48 hrs + │ │ │ ├── Unlocked within 48 hrs → Restock as new + │ │ │ └── Not unlocked → Grade B (open box with disclaimer) + │ │ └── Clean → Restock as new (full margin recovery) + │ └── Fail → Route to refurbishment assessment + │ ├── Refurb cost < 40% of refurb selling price → Refurbish + │ ├── Refurb cost 40-60% → Liquidate as "for parts / not working" + │ └── Refurb cost > 60% → Parts harvest or e-waste recycling + ├── Grade B (minor cosmetic wear, accessories complete, packaging damaged) + │ └── Functional test + │ ├── Pass → Repackage as "open box" or "renewed" (60-80% of retail) + │ └── Fail → Refurbishment assessment (same tree as above) + ├── Grade C (visible wear, scratches, missing non-essential accessories) + │ └── Functional test + │ ├── Pass → Sell through secondary channel at 30-50% of retail + │ └── Fail → Parts harvest if unit value > $100, else e-waste + └── Grade D (heavily damaged, non-functional, missing critical components) + └── Parts harvest if any component value > $15, else e-waste recycling +``` + +**Category-specific thresholds:** +- Smartphones: Always verify IMEI against stolen device databases (GSMA) before restocking +- Laptops: Battery health must be > 80% for Grade A restock; 60-80% triggers Grade B +- Tablets: Check for MDM (mobile device management) profiles — enterprise tablets may have + remote-lock capability that surfaces post-sale +- Headphones: Hygiene concern — all ear tips/pads replaced before resale ($2-8 per unit) +- Smart home devices: Factory reset verified; linked account removal confirmed. A smart lock + that is still linked to a previous owner's account is unsellable and potentially a safety issue + +**Typical processing costs:** +| Action | Cost per Unit | Time per Unit | +|--------|--------------|---------------| +| Visual inspection | $1.50-2.50 | 45-90 seconds | +| Functional test (basic) | $3.00-5.00 | 2-4 minutes | +| Functional test (full diagnostic) | $8.00-15.00 | 10-20 minutes | +| Repackaging | $5.00-12.00 | 3-8 minutes | +| Refurbishment (minor: screen clean, reset) | $15.00-30.00 | 15-30 minutes | +| Refurbishment (moderate: component replacement) | $30.00-80.00 | 30-90 minutes | +| Data wipe (NIST 800-88 compliant) | $5.00-10.00 | 5-15 minutes | + +### 1.3 Apparel and Footwear + +Apparel returns are high-volume, low-unit-value, and condition-sensitive. Odour, stains, +and stretched fabric are the primary defects. Speed is critical because fashion depreciates +rapidly — a trend item loses 10-20% of sellable value per month. + +``` +RECEIVE → Scan RMA / order lookup + └── Visual inspection (30-60 seconds) + ├── Tags attached, no signs of wear + │ ├── Original packaging intact → Restock as new + │ └── Packaging damaged/missing → Repackage, restock as new (tag is key, not box) + ├── Tags removed but no signs of wear + │ └── UV light + odour check + │ ├── Clean → Restock as "like new" or outlet (80-90% of retail) + │ └── Traces detected → Grade C, route to launder/clean assessment + │ ├── Cleaning cost < $5 and item value > $30 → Clean and restock as outlet + │ └── Cleaning not viable or cost > value threshold → Liquidate by weight + ├── Visible wear, stains, or damage + │ ├── Premium brand (retail > $100) → Assess repair viability + │ │ ├── Repair cost < 20% of outlet price → Repair and sell through outlet + │ │ └── Repair not viable → Liquidate (never destroy premium apparel; brand resale exists) + │ └── Standard brand → Liquidate by weight ($0.50-2.00/lb) or textile recycling + └── Heavily damaged, soiled, or biohazard + └── Textile recycling or destroy (biohazard requires specific disposal) +``` + +**Apparel-specific considerations:** +- Seasonal timing is everything: a winter coat returned in February can restock for next season, + but the carrying cost of 8 months of storage may exceed liquidation recovery. Decision point: + if storage cost > (expected recovery next season × probability of sale) - liquidation value now, + liquidate immediately. +- Footwear: Check sole wear. A shoe worn on carpet for 5 minutes is different from one worn + on pavement. Sole scuffing = Grade C minimum. Check for orthotics left inside. +- Swimwear and intimate apparel: Once hygienic liner is removed, non-returnable per health code + in most jurisdictions. If returned, destroy — do not restock or liquidate. +- Designer/luxury: Authenticate before accepting. Counterfeits in the return stream are + increasing. Compare serial numbers, stitching quality, hardware weight against known + genuine samples. + +### 1.4 Home, Furniture, and Large Goods + +Returns of bulky items are expensive — return shipping alone can be $50-200+. The disposition +decision often happens before the item physically returns. + +``` +CUSTOMER INITIATES RETURN → + ├── Item value < return shipping cost × 2.5 + │ └── Offer returnless refund (customer keeps item, full refund) + │ Cost justification: returnless refund costs $X (product value). + │ Processing the return costs $X (product) + $Y (shipping) + $Z (processing). + │ If Y + Z > 40% of X, returnless is cheaper. + ├── Item value > threshold AND item is in original packaging + │ └── Schedule carrier pickup → Receive → Inspect + │ ├── Grade A → Restock (furniture typically restock at 85-95% due to assembly/box condition) + │ ├── Grade B → Sell as "open box" in-store (avoid re-shipping; sell from nearest location) + │ ├── Grade C → Donate locally (shipping destroyed items is negative ROI) + │ └── Grade D → Local disposal (donation or recycling based on materials) + └── Item is assembled + └── Generally non-returnable once assembled (policy). Exceptions: + ├── Defective → Offer replacement parts first, full return if unfixable + ├── Missing parts on arrival → Ship missing parts (cheaper than full return) + └── Customer insists → Accept but apply 25% restocking fee to cover disassembly/repackaging +``` + +### 1.5 Health, Beauty, and Personal Care + +Regulatory constraints dominate this category. Once opened, most health and beauty products cannot +be legally resold due to FDA and state health department regulations. + +``` +RECEIVE → Seal integrity check + ├── Sealed / unopened + │ ├── Expiration date > 6 months out → Restock as new + │ ├── Expiration 3-6 months → Restock with markdown or outlet + │ └── Expiration < 3 months → Donate (tax benefit > markdown recovery) + ├── Opened but appears unused (seal broken, product visually intact) + │ └── DESTROY. Cannot verify non-contamination. No restocking of opened health/beauty. + │ Exception: Hard goods (hair dryers, electric razors) → treat as electronics tree + └── Used + └── DESTROY. Biohazard disposal if applicable (used cosmetics applicators, skincare). +``` + +**Special cases:** +- Prescription items: Cannot accept return under any circumstances (most states). Direct + customer to pharmacy or manufacturer disposal programme. +- Supplements/vitamins: Same as cosmetics — once opened, destroy. Sealed returns restock + only with lot number verification. +- Sunscreen: Regulated as OTC drug by FDA. Opened sunscreen is destroyed. Expired sunscreen + (even sealed) is destroyed — never sell expired OTC. + +### 1.6 Books, Media, and Software + +High restock rate, low processing cost. The primary fraud vector is digital content extraction +(reading/ripping then returning). + +``` +RECEIVE → Condition check + ├── New condition (no creasing, bending, markings) + │ └── Restock as new. Media: verify disc is present and matches case. + ├── Minor wear (slight cover bend, shelf wear) + │ └── Restock at minor discount or sell through marketplace as "very good" + ├── Moderate wear (highlighting, writing, water damage) + │ └── Liquidate through bulk book buyers ($0.10-0.50 per book) or donate + └── Software / digital media + ├── If activation key is unredeemed → Restock + ├── If key is redeemed → Cannot resell. Write off. Pursue refund from publisher if within terms. + └── Physical media with digital code (game + download) → Sell disc only at reduced price +``` + +--- + +## 2. Fraud Detection Scoring Model + +### 2.1 Scoring Architecture + +The fraud scoring model assigns points based on observable signals at the time of return +initiation (pre-receipt signals) and at the time of physical inspection (post-receipt +signals). The two scores are summed for a composite score. + +**Thresholds:** +| Composite Score | Action | +|----------------|--------| +| 0-30 | Process normally. No additional review. | +| 31-50 | Flag for passive monitoring. Process refund but add customer to watch list for 90 days. | +| 51-64 | Enhanced inspection. Hold refund until physical inspection is complete and matches RMA description. | +| 65-79 | Supervisor review. Hold refund. Detailed inspection with photo documentation. Supervisor approves or escalates. | +| 80-100 | Fraud review team. Refund on hold. Customer contacted for "verification" (never say "fraud"). LP notified. | + +### 2.2 Pre-Receipt Signals (scored at return initiation) + +| Signal | Points | Logic | +|--------|--------|-------| +| Customer return rate > 30% (rolling 12 months, ≥ 5 orders) | +15 | High return rate alone isn't fraud, but it is a risk multiplier. Exclude exchanges from rate calculation. | +| Return rate > 50% | +25 | Replaces the +15 above. At this rate, the customer is almost certainly bracket-shopping or abusing policy. | +| Return initiated < 48 hours after delivery confirmation | +5 | Could be legitimate (wrong item, didn't match description) or bracket shopping. Mild signal. | +| Return reason is "defective" but product category has < 2% defect rate | +10 | "Defective" is used to avoid restocking fees. True defect claims on low-defect products are suspicious. | +| Return reason changed between online initiation and customer service contact | +10 | Inconsistency suggests the customer is constructing a narrative. | +| Customer account age < 30 days | +10 | New accounts used for return fraud or testing fraud viability. | +| Multiple returns in same week (3+) | +10 | Cumulative with return rate signal. Suggests bracket shopping or wardrobing batch. | +| Return from an address different than the original shipping address | +10 | Excludes gift returns (flagged as gift at order). Otherwise indicates potential organised activity. | +| Item is in a high-shrink category (electronics, designer, cosmetics) | +5 | These categories have higher fraud incidence. Mild base signal. | +| No-receipt or no-order-match return | +15 | Receipt fraud is the primary risk vector. Match to payment method or loyalty ID. | +| Order was placed with a promotion/coupon > 30% off | +5 | Price-arbitrage returns are more common on heavily discounted purchases. | +| Customer has previously been flagged for fraud review (any outcome) | +15 | Prior flags, even if resolved as legitimate, indicate a pattern worth monitoring. | + +### 2.3 Post-Receipt Signals (scored during physical inspection) + +| Signal | Points | Logic | +|--------|--------|-------| +| Serial number mismatch (does not match the unit sold to this customer) | +40 | Near-certain swap fraud. Verify against order record before escalating — packing errors at fulfilment can cause legitimate mismatches. | +| Product weight differs > 5% from expected for SKU | +25 | Indicates missing components, swap with lighter/cheaper item, or empty packaging. Weigh before opening. | +| IMEI/MEID on returned device doesn't match sold device | +40 | Definitive swap fraud for mobile devices. Cross-reference IMEI from order with IMEI on returned device. | +| Product shows wear inconsistent with stated return reason | +15 | "Changed my mind" return on a laptop with 200 battery cycles suggests extended use. | +| Tags removed on apparel/footwear with "didn't fit" reason | +10 | Tags removed is consistent with wearing, not just trying on. | +| Cosmetic traces on apparel (makeup, deodorant, perfume) | +15 | Wardrobing indicator. UV light reveals traces invisible to naked eye. | +| Packaging has been repacked (tape over tape, non-original inner packaging) | +10 | Could indicate swap (customer repacked a different item) or simply customer repackaging for return. Context-dependent. | +| Security/RFID tag removed | +20 | Tags that are not customer-removable (hidden tags, sewn-in RFID) should still be present. Removal suggests the item was worn/used in a retail environment. | +| Product firmware/software shows usage history inconsistent with claim | +15 | Laptop claiming "unopened" but with 6 months of OS updates installed. | +| Multiple units of same SKU returned (3+) in single return | +10 | Could be legitimate (sizing across colours) or reseller return. Check original order for bulk discount. | + +### 2.4 Score Adjustments and Overrides + +| Condition | Adjustment | +|-----------|-----------| +| Customer lifetime value > $10,000 and net LTV positive | -15 points (floor at 0) | +| Customer is a verified loyalty programme member (2+ years) | -10 points | +| Return is an exchange (not refund) | -10 points | +| Return reason is verified fulfilment error (wrong item shipped) | Set score to 0, process immediately | +| Return was pre-approved by customer service with case notes | -10 points | +| Customer has filed a chargeback simultaneously with this return | +20 points (escalate regardless of score) | + +### 2.5 False Positive Management + +False positives destroy customer relationships. Every customer flagged by the fraud scoring +system who turns out to be legitimate represents a risk of customer attrition. Manage through: + +1. **Never communicate "fraud" to the customer.** Use neutral language: "additional processing + time," "verification of your return," "quality review." +2. **Time-box the review.** Flagged returns must be resolved within 5 business days. If the + review cannot conclusively determine fraud within 5 days, process the refund. The cost + of a false positive held for 3 weeks exceeds the cost of most fraudulent returns. +3. **Track false positive rate monthly.** Target: < 3% of total returns flagged are + confirmed false positives. If rate exceeds 5%, recalibrate the scoring model. +4. **Feedback loop:** Every fraud review outcome (confirmed fraud, confirmed legitimate, + inconclusive) feeds back into the scoring model calibration. Signals that generate + high false-positive rates have their point values reduced. + +--- + +## 3. Vendor Recovery Framework + +### 3.1 Return-to-Vendor (RTV) Process + +RTV is the primary mechanism for recovering costs on defective products. The process: + +``` +Identify RTV-eligible unit (defective, vendor-caused quality issue, mispick at vendor DC) + │ + ├── Check vendor agreement for RTV terms + │ ├── RTV window: Typically 90 days from retailer receipt of return (not customer purchase date) + │ ├── Minimum shipment value: Usually $200-500 per RTV shipment + │ ├── Documentation requirements: Varies by vendor (photos, defect codes, customer complaint data) + │ └── RTV authorisation: Some vendors require pre-approval; others accept "open RTV" under agreement + │ + ├── Accumulate RTV-eligible units by vendor + │ ├── Stage in designated RTV area (separate from general returns inventory) + │ ├── Track aging — units approaching 90-day window need priority shipment + │ └── Batch by vendor to meet minimum shipment thresholds + │ + ├── Obtain RTV authorisation (if required) + │ ├── Submit RTV request with: SKU, quantity, defect description, photos, customer return rate data + │ └── Vendor has 5-10 business days to approve/deny (per most vendor agreements) + │ + ├── Ship to vendor return facility + │ ├── Use vendor-provided shipping label (if applicable — vendor pays) + │ ├── If retailer pays shipping: deduct from credit claim or use lowest-cost carrier + │ └── Track shipment and confirm delivery at vendor facility + │ + └── Track credit issuance + ├── Vendor credit should appear within 30-45 days of vendor receipt + ├── If no credit at 30 days: first follow-up (email to vendor returns dept) + ├── If no credit at 45 days: escalate to vendor account manager + ├── If no credit at 60 days: debit memo against next PO (per vendor agreement terms) + └── If vendor disputes: provide defect documentation as evidence. Escalate to vendor management. +``` + +### 3.2 Defect Rate Monitoring and Claims + +Beyond individual RTV, monitor defect rates at the SKU level to identify systemic quality +issues that trigger formal defect claims: + +| Defect Rate (per SKU, rolling 90 days) | Action | +|----------------------------------------|--------| +| < 2% | Normal. Process individual RTVs. No escalation. | +| 2-5% | Alert vendor management. Request root cause analysis from vendor. Continue selling but monitor weekly. | +| 5-8% | Formal quality complaint. Demand corrective action plan within 14 days. Consider pull from active sales pending vendor response. | +| 8-15% | Pull from active sales. Formal defect claim for all returns above the 2% baseline. Negotiate credit or replacement. | +| > 15% | Full stop-sale. Vendor compliance violation. Chargebacks for all returns + lost margin + customer service costs. Consider vendor termination. | + +**Defect claim calculation:** +``` +Total returns for SKU in period: 500 units +Expected baseline return rate (non-defect): 8% of units sold (industry avg for category) +Units sold: 4,000 +Expected returns: 320 +Excess returns attributable to defect: 500 - 320 = 180 units +Claim = 180 × (wholesale cost + inbound freight per unit + return processing cost per unit) + = 180 × ($24.00 + $1.80 + $7.50) + = 180 × $33.30 + = $5,994.00 +``` + +Add consequential costs if the defect caused customer service escalations, negative reviews +that required response, or marketplace listing suppression. + +### 3.3 Vendor Chargeback Schedule + +For vendor-caused issues beyond defects (packaging failures, mislabelling, wrong items shipped +from vendor DC), apply chargebacks per the vendor compliance programme: + +| Violation | Chargeback | Notes | +|-----------|-----------|-------| +| Wrong item shipped from vendor DC | 100% of product cost + return shipping + $25 processing fee | Requires photo evidence of received vs ordered | +| Mislabelled product (UPC doesn't match contents) | $50 per incident + product cost if unsellable | Creates inventory accuracy issues downstream | +| Packaging failure (product damaged due to inadequate packaging) | 100% of product cost + return processing | Requires photos of packaging condition at receipt | +| Missing components (accessory, manual, warranty card) | Cost of sourcing replacement component + $10 processing | If component unavailable, full product cost | +| Counterfeit or unauthorised product | 300% of product cost + $500 penalty per incident | Zero tolerance. Notify brand protection. | +| Late shipment from vendor causing customer-facing delay | Customer credit issued + $15 processing | Must document customer complaint and credit | +| Incorrect hazmat/regulatory documentation | $250 per incident + cost of regulatory remediation | Regulatory liability makes this non-negotiable | + +### 3.4 Vendor Recovery ROI Model + +Not all vendor recovery is worth pursuing. The ROI model: + +``` +Recovery ROI = (Expected recovery - Recovery cost) / Recovery cost + +Where: + Expected recovery = Claim amount × Collection probability + Recovery cost = Labour (documentation, communication, follow-up) + Shipping (if RTV) + Relationship cost + +Labour cost estimates: + - Simple RTV with existing authorisation: $15-25 per batch + - Defect claim requiring documentation assembly: $75-150 per claim + - Disputed claim requiring escalation and negotiation: $200-500 per claim + +Collection probability by vendor tier: + - Tier 1 (top 20 vendors, strong relationship): 85-95% + - Tier 2 (mid-tier, established relationship): 65-80% + - Tier 3 (small/new vendors): 40-60% + - International vendors (no US entity): 25-45% +``` + +**Decision matrix:** +| Claim Amount | Tier 1 Vendor | Tier 2 Vendor | Tier 3 Vendor | International | +|-------------|---------------|---------------|---------------|---------------| +| < $100 | Offset against next PO | Offset against next PO | Write off | Write off | +| $100-500 | Batch RTV | Batch RTV | Batch if > $200 total | Write off, note for contract | +| $500-2,000 | Standard RTV/claim | Standard claim | Standard claim with escalation plan | Claim if > $1,000 | +| $2,000-10,000 | Standard claim | Standard claim + account mgr | Account mgr + formal notice | Pursue with local agent if > $5,000 | +| > $10,000 | VP-level engagement | VP-level + legal review | Legal review | Legal counsel in vendor's jurisdiction | + +--- + +## 4. Return Policy Exception Matrix + +### 4.1 Exception Decision Framework + +When a return falls outside standard policy, the decision to grant an exception depends on +a structured evaluation, not individual judgment calls. This matrix standardises the +exception decision. + +**Step 1: Is the exception request covered by an automatic override?** + +| Condition | Action | No Further Analysis Needed | +|-----------|--------|--------------------------| +| Product is defective (verified or reasonably claimed) | Accept return, full refund, no restocking fee | Yes | +| Fulfilment error (wrong item shipped, wrong quantity) | Accept return, full refund, prepaid return label | Yes | +| Product is subject to active recall | Route to recall programme (not returns) | Yes | +| Customer is in top 5% by LTV and request is first exception in 12 months | Grant exception, standard refund | Yes | +| State or federal law requires acceptance (lemon law, cooling-off period) | Comply with applicable law | Yes | + +**Step 2: If not an automatic override, score the exception request:** + +| Factor | Score Range | Description | +|--------|-----------|-------------| +| Days past policy window | 1-30 days: +2 / 31-60 days: +5 / 61-90 days: +8 / >90 days: +12 | How far outside the standard window | +| Product condition at return | Grade A: 0 / Grade B: +2 / Grade C: +5 / Grade D: +10 | Worse condition = higher cost of exception | +| Customer LTV | Top 20%: -5 / Middle 60%: 0 / Bottom 20%: +3 | Valuable customers get more latitude | +| Return reason credibility | Compelling story with evidence: -3 / Plausible: 0 / Weak: +5 | "My house flooded" with photos vs "I forgot" | +| Precedent risk | Private resolution: 0 / Customer mentioned social media: +5 / Customer has large following: +8 | Public exceptions become policy expectations | +| Product restockability | Restockable as new: -3 / Open box: 0 / Liquidation: +3 / Destroy: +5 | Restockable items cost less to accept | + +**Step 3: Interpret the exception score:** + +| Score | Decision | Authority Level | +|-------|----------|----------------| +| < 0 | Grant exception. Cost is minimal, customer value is high. | Returns associate | +| 0-5 | Grant exception with standard refund. | Team lead | +| 6-10 | Grant as store credit (not original payment refund). | Team lead | +| 11-15 | Partial credit (50-75% of purchase price) as store credit. | Returns manager | +| 16-20 | Deny with empathetic explanation and alternative offer (exchange, discount on next purchase). | Returns manager | +| > 20 | Deny. Offer to connect with manufacturer warranty if applicable. | Returns manager | + +### 4.2 Common Exception Scenarios with Recommended Resolutions + +| Scenario | Typical Score | Recommended Resolution | +|----------|--------------|----------------------| +| 5 days past window, Grade A, loyal customer | -3 | Full refund to original payment | +| 45 days past window, Grade B, average customer | +7 | Store credit for purchase price | +| 90 days past window, Grade C, low-value customer | +16 | Deny, offer 15% discount on next purchase | +| 10 days past window, Grade A, customer cited family emergency | -1 | Full refund to original payment | +| Within window, Grade C, customer claims defect but inspection shows user damage | +10 | Store credit at 50% (goodwill), document for fraud scoring | +| 60 days past window, brand-new customer, first order | +13 | Partial credit (50%), welcome them back with incentive | + +--- + +## 5. Grading Standards by Product Category + +### 5.1 Universal Grading Criteria + +All categories share these baseline grade definitions. Category-specific addenda +follow in §5.2. + +#### Grade A — Like New +- Zero signs of use beyond initial unboxing +- All original accessories, manuals, and packaging materials present +- Original packaging in good condition (minor shipping wear acceptable) +- Passes all applicable functional and safety tests +- Can be restocked and sold as new without any additional processing beyond re-shelving + +#### Grade B — Good / Open Box +- Minor cosmetic imperfections (light surface scratches, small scuffs) that do not affect function +- Original packaging may be damaged, opened, or missing outer sleeve/shrink wrap +- All essential accessories present (charger, main cable); non-essential items (stickers, pamphlets) may be missing +- Fully functional — passes all applicable tests +- Requires repackaging or "open box" labelling before resale + +#### Grade C — Fair +- Visible cosmetic wear, scratches, dents, or staining that are noticeable at arm's length +- Missing accessories that affect the completeness of the product (but not its core function) +- Functional but may have minor performance degradation (battery at 60-80%, worn but operational buttons) +- Not suitable for primary retail channel — routes to outlet, marketplace, or liquidation +- May be viable for refurbishment if cost justifies it + +#### Grade D — Salvage / Parts +- Non-functional, heavily damaged, or missing critical components that render the product unusable +- Structural damage (cracked screens, bent frames, water damage indicators triggered) +- May have value for parts harvesting or materials recovery +- Routes to parts extraction, recycling, or destruction + +### 5.2 Category-Specific Grading Addenda + +**Consumer Electronics:** +- Grade A additional requirement: battery health > 80% of design capacity (measurable via diagnostic) +- Grade B threshold: battery 60-80%, cosmetic scratches visible only under direct light +- Functional test required for all grades: power on, display, connectivity (WiFi/Bluetooth/cellular), speakers, cameras, ports +- Data wipe verification mandatory before any resale disposition + +**Apparel:** +- Grade A: tags attached (original retail tags, not just care labels) +- Grade B: tags removed, but no wear indicators; passes UV and odour check +- Grade C: visible wear, minor staining treatable with professional cleaning, or slight fabric stretching +- Grade-reducing odours: tobacco smoke, pet odour, heavy fragrance, body odour +- Automatic Grade D: mould, mildew, pest contamination + +**Footwear:** +- Sole inspection is primary grading factor: unworn soles = Grade A, indoor-only wear marks = Grade B, outdoor wear = Grade C +- Grade B requires: no toe box creasing deeper than 2mm, no heel counter collapse +- Include insole inspection: customer orthotics must be removed, original insole must be present + +**Home Goods / Small Appliances:** +- Grade A: unused, all packaging foam/wrapping in place +- Functional test: operate through one full cycle (coffee maker: brew cycle, vacuum: run for 60 seconds, blender: blend ice test) +- Missing filters, bags, or consumable accessories: Grade B (replaceable at $3-10 cost) +- Cosmetic damage on surfaces visible during normal use: Grade C + +--- + +## 6. Liquidation Channel Selection + +### 6.1 Channel Overview + +When product is routed to liquidation, selecting the right channel significantly affects +recovery rates. The wrong channel can mean the difference between 20% recovery and 5%. + +| Channel | Best For | Typical Recovery (% of retail) | Fees | Min Lot Size | Speed to Cash | +|---------|----------|-------------------------------|------|-------------|---------------| +| B-Stock (owned auctions) | Electronics, home goods | 12-25% | 10-15% of sale | 1 pallet | 2-4 weeks | +| Direct Liquidation | Mixed general merchandise | 8-18% | 15-20% of sale | 1 pallet | 2-6 weeks | +| Bulq (owned by Optoro) | Small lots, mixed goods | 10-20% | Built into marketplace | 1 box (small lots) | 1-3 weeks | +| Regional liquidators | Bulky/heavy items, furniture | 5-15% | Negotiated | Varies | 1-4 weeks | +| Wholesale to dollar stores | Low-value general merchandise | 3-8% (often per-pound) | None (buy outright) | Truckload preferred | Immediate | +| Online marketplace (eBay, Amazon Warehouse) | Individually valuable items ($50+) | 25-50% | 12-15% + shipping | Single unit | 1-8 weeks | +| Charity donation | Items not worth liquidating, brand-sensitive | $0 (tax deduction at FMV) | None | No minimum | Immediate | + +### 6.2 Channel Selection Decision Tree + +``` +Is the individual unit value > $50? + ├── Yes → Is the item in Grade B or better condition? + │ ├── Yes → Sell individually on marketplace (eBay, Amazon Warehouse). Highest recovery. + │ └── No → Is the brand premium/recognisable? + │ ├── Yes → Auction on B-Stock (brand buyers pay premium). Recovery 15-25%. + │ └── No → Direct Liquidation or regional liquidator. Recovery 8-15%. + └── No → Is there a full pallet of same or similar category? + ├── Yes → Auction as category-sorted pallet on B-Stock or Direct Liquidation. + │ Recovery improves 30-50% vs mixed pallets. + └── No → Accumulate by category until pallet quantity reached. + If aging > 30 days, mix into general pallet and liquidate. + Holding cost exceeds sort premium beyond 30 days. +``` + +**Critical liquidation rules:** +1. Never mix electronics with non-electronics on the same pallet. Electronics buyers won't bid on mixed pallets. +2. Never include recalled products, counterfeit items, or hazmat in liquidation lots. Liability exposure is unlimited. +3. Remove all customer personal data before liquidating electronics. Data breach from a liquidated device creates legal exposure. +4. Photograph every pallet before shipping to liquidation. Disputes about condition are common. +5. Manifest every pallet (list of SKUs, quantities, conditions). Manifested pallets sell for 20-40% more than unmanifested. + +--- + +## 7. Refurbishment ROI Model + +### 7.1 When to Refurbish + +Refurbishment is only viable when the economics justify it. The decision model: + +``` +Refurbishment ROI = (Refurbished selling price - Refurbishment cost - Fulfilment cost) / Refurbishment cost + +Decision thresholds: + ROI > 100%: Always refurbish. High-value recovery. + ROI 50-100%: Refurbish if capacity exists. Good return on investment. + ROI 25-50%: Refurbish only if liquidation alternative is particularly poor (< 8% recovery). + ROI < 25%: Liquidate. The refurbishment effort isn't justified. +``` + +### 7.2 Refurbishment Cost Benchmarks by Category + +| Category | Common Defects | Typical Refurb Cost | Typical Refurb Selling Price | Typical ROI | +|----------|---------------|--------------------|-----------------------------|-------------| +| Smartphones (flagship) | Screen scratches, battery degradation | $40-80 (screen polish, battery replace) | $350-550 (65-75% of new) | 300-500% | +| Laptops | Battery, cosmetic damage, slow storage | $50-120 (battery, SSD upgrade, clean) | $400-800 (55-70% of new) | 200-400% | +| Tablets | Screen scratches, battery | $30-60 | $200-400 (60-70% of new) | 200-350% | +| Small appliances | Cosmetic, missing parts | $10-25 (clean, replace accessory) | $30-60 (50-65% of new) | 100-200% | +| Power tools | Battery, switch wear | $20-45 (battery, switch replacement) | $60-120 (55-65% of new) | 100-200% | +| Headphones (premium) | Ear pad wear, cosmetic | $8-15 (new pads, clean) | $80-200 (60-75% of new) | 400-800% | +| Game consoles | Cosmetic, controller wear | $15-30 (clean, replace controller pads) | $150-300 (60-70% of new) | 300-500% | + +### 7.3 Refurbishment Capacity Planning + +Refurbishment requires dedicated space, trained technicians, and parts inventory. The +capacity model: + +- **Space:** 1 refurb station = approximately 80 sq ft (workbench + test equipment + parts storage) +- **Throughput:** 1 technician handles 8-15 units/day for electronics, 20-30 units/day for small appliances +- **Parts inventory:** Maintain 30-day supply of top 20 replacement parts by volume (batteries, screens, cables, ear pads, filters) +- **Break-even:** A refurb station breaks even at approximately 5-8 units per day at average ROI of 150%. Below this volume, outsource to a third-party refurbisher. + +### 7.4 Outsource vs In-House Decision + +| Factor | In-House | Outsource | +|--------|----------|-----------| +| Volume > 40 units/day | Preferred (economies of scale) | Viable but more expensive | +| Volume < 40 units/day | Only if margin justifies | Preferred (avoid fixed overhead) | +| Brand certification programme exists | Required for "certified refurbished" branding | Must verify third-party is certified | +| Product requires proprietary tools/software | In-house (IP control) | Only with NDA and audited facility | +| Seasonal volume spikes | Core volume in-house, surge outsourced | Flexible capacity | +| Data security requirements | In-house (direct control over data wipe) | Requires NIST 800-88 certification | + +--- + +## 8. Return Processing Workflow by Channel + +### 8.1 E-Commerce Returns (Ship-Back) + +The standard e-commerce return flow. This is the highest-volume channel for most +retailers and the one with the most automation opportunity. + +``` +Customer initiates return on website/app + │ + ├── Automated policy check (within window? excluded category? customer in good standing?) + │ ├── Auto-approve → Generate RMA + prepaid return label + │ ├── Auto-deny → Display denial reason + alternatives + │ └── Manual review queue → Agent reviews within 4 hours + │ + ├── Customer ships product + │ └── Tracking monitored for: label scan (confirms customer shipped), delivery to return centre + │ + ├── Receiving at return centre + │ ├── Scan RMA barcode → pulls order record, expected product, customer profile + │ ├── Initial sort: sealed/unopened → express lane (15-second visual, Grade A, restock) + │ └── Opened/used → standard inspection lane + │ + ├── Standard inspection (see §5 for grading criteria) + │ ├── Serial number verification (electronics only, but expanding to luxury goods) + │ ├── Visual inspection + functional test (category-dependent) + │ ├── Fraud scoring (post-receipt signals added to pre-receipt score) + │ └── Grade assignment: A / B / C / D + │ + ├── Disposition routing (see §1 for category-specific trees) + │ ├── Grade A → Restock queue + │ ├── Grade B → Open-box / repackaging queue + │ ├── Grade C → Liquidation staging or refurbishment assessment + │ └── Grade D → Parts / recycling / destruction + │ + └── Refund processing + ├── Refund triggered upon grade assignment (do not wait for disposition completion) + ├── Restocking fee applied if applicable (calculated at grading, not at refund) + └── Refund to original payment method → customer notification sent +``` + +**Key timing targets:** +| Step | Target | Stretch Goal | +|------|--------|-------------| +| RMA generation (auto-approve) | < 5 minutes | Instant | +| Return label delivery to customer | Immediate (email) | Immediate | +| Customer ship-back | < 7 days from RMA | < 5 days | +| Receiving scan at return centre | Day of delivery | Same as carrier delivery scan | +| Inspection + grading | < 24 hours of receipt | < 4 hours | +| Refund processing | < 24 hours of grading | Same day as grading | +| Refund visible to customer | 3-5 business days | 1-2 business days | +| Total RMA-to-refund cycle | < 14 days | < 7 days | + +### 8.2 Buy Online, Return In-Store (BORIS) + +Cross-channel returns are operationally more complex but have higher customer satisfaction +and lower total cost (no return shipping). The critical risk is price discrepancy. + +``` +Customer arrives at store with online-purchased product + │ + ├── Associate initiates BORIS return in POS + │ ├── Scan product barcode + │ ├── Look up online order (by order number, customer email, or loyalty account) + │ │ ├── Order found → POS displays actual purchase price from online order + │ │ │ └── CRITICAL: Refund at actual online purchase price, NOT store shelf price + │ │ └── Order not found → Customer provides order confirmation (email/app) + │ │ ├── Verified → Manual price entry at confirmed online price + │ │ └── Cannot verify → Process through online returns channel (mail-back) + │ │ Do NOT guess the price. Do NOT use store shelf price. + │ └── Verify return eligibility (window, excluded categories) + │ + ├── In-store inspection + │ ├── Visual + functional check (same criteria as return centre) + │ ├── For electronics: serial number check against online order + │ └── Grade assignment + │ + ├── Refund processing + │ ├── Refund to original online payment method (not store credit, not cash) + │ │ Exception: customer paid with a gift card → store credit acceptable + │ ├── Restocking fee applied if applicable + │ └── Customer receives refund confirmation email + │ + └── Inventory disposition + ├── If Grade A and product is in store assortment → Restock on store shelf + ├── If Grade A but product is online-only → Ship to return centre or nearest DC + ├── If Grade B/C → Ship to return centre for open-box/liquidation processing + └── If Grade D → Local disposal (do not ship non-functional product to return centre) +``` + +**BORIS-specific risks:** +1. Price discrepancy (online vs store) → Mitigated by mandatory online order lookup +2. Return of promotional/bundled items → Verify if the item was part of a BOGO or bundle; refund the proportional amount +3. Store inventory adjustment → Ensure the store's inventory count correctly reflects the returned unit +4. Different return windows → Online and store may have different windows; honour the more generous one + +### 8.3 In-Store Purchase, Return In-Store + +The simplest return flow. The POS has the transaction record, pricing is definitive, +and the product doesn't need to be shipped. + +``` +Customer arrives with product + receipt (or POS lookup via card/loyalty) + │ + ├── POS transaction lookup → Confirms purchase price, date, payment method + ├── Window check → Within return policy period? + ├── Inspection at return counter + │ ├── Quick visual for obvious damage/use + │ ├── Electronics: power-on test, serial number check + │ └── Grade assignment (usually Grade A or B at point of sale) + │ + └── Refund to original payment method → Receipt printed → Customer exits +``` + +**Target transaction time:** < 5 minutes for standard returns. This is the benchmark +that drives customer satisfaction — long return lines at the service desk are the +#1 complaint in retail returns. + +### 8.4 Returnless Refunds (Customer Keeps Product) + +For items where the cost of return exceeds the recovery value. The decision model: + +``` +Return shipping cost estimate > 40% of product value? + ├── Yes → Evaluate returnless refund + │ ├── Product value < $50 → Auto-approve returnless refund + │ ├── Product value $50-100 → Supervisor auto-approve + │ ├── Product value $100-200 → Manager review (consider partial return — just the defective component) + │ └── Product value > $200 → Case-by-case (may justify return shipping for high-value) + │ + └── No → Standard return process +``` + +**Returnless refund abuse prevention:** +- Track returnless refunds per customer. More than 3 in 6 months triggers review. +- High-value returnless refunds (> $100) are flagged for post-refund audit. +- Products declared "defective" for returnless refund should still be counted in the + SKU defect rate, even though the physical product doesn't return. +- Consider asking the customer to send a photo of the defect as lightweight verification. + +--- + +## 9. Seasonal Return Planning + +### 9.1 Holiday Return Surge (January) + +January is to returns operations what December is to fulfillment. Plan for: + +| Metric | Normal Month | January Peak | Multiplier | +|--------|-------------|-------------|-----------| +| Return volume | 100% baseline | 250-350% | 2.5-3.5x | +| Return processing backlog | < 24 hours | 48-96 hours | 2-4x | +| Fraud attempts | Baseline | 180-220% | 1.8-2.2x | +| Customer service contacts about returns | Baseline | 300-400% | 3-4x | +| Gift receipt returns (% of total) | 5-8% | 25-35% | 4-5x | + +**Holiday return planning checklist:** +1. Staff: Bring temporary inspection staff online by Dec 26. Target: 2x normal inspection capacity by Jan 2. +2. Space: Reserve additional staging area for the return volume. Last-mile sorting should be simplified (Grade A express lane for sealed/tagged items). +3. Policy: Extended holiday return window (typically Nov 1 - Dec 31 purchases returnable through Jan 31) means that returns trickle in over 4 weeks rather than concentrating in the first week. Model the curve. +4. Gift receipts: Train all associates on gift receipt pricing rules. The #1 January return error is refunding at current price instead of purchase price. +5. Fraud: Increase fraud scoring thresholds by 10% during January (reduce false positives — many legitimate gift returns trigger fraud signals). +6. Liquidation: Pre-negotiate January liquidation capacity with liquidation partners. You'll have 3-4x normal Grade C/D volume, and everyone else will too. + +### 9.2 Category-Specific Seasonal Patterns + +| Category | Peak Return Period | Key Driver | Planning Action | +|----------|-------------------|-----------|----------------| +| Consumer electronics | Jan 2-15 | Holiday gifts, "not what they wanted" | Pre-stage functional test stations; serial number verification capacity | +| Apparel | Jan 5-31 (extends longer) | Gift sizing, holiday party returns | UV/odour inspection throughput; wardrobing detection focus | +| Fitness equipment | Jan 15 - Mar 1 | New Year's resolution abandonment | Large-item return logistics; returnless refund thresholds | +| Outdoor/sporting goods | Mar-Apr (post-ski), Sep-Oct (post-summer) | Season-end returns | Seasonal markdown timing; storage vs liquidation decision | +| School supplies | Sep 1-15 | Over-purchasing for school | High-volume, low-value; fast processing is key | + +### 9.3 Markdown-Driven Returns + +When products go on markdown or clearance, returns of the same product purchased at +full price increase. Customers are not returning because of dissatisfaction — they're +returning to repurchase at the lower price (return arbitrage). + +**Detection:** Monitor for returns where the same customer repurchases the same SKU within +7 days of the return. If the repurchase price is lower, flag as potential price-match return. + +**Preferred handling:** Offer a price-match credit instead of processing a return and +repurchase. The price-match credit costs the markdown difference; the return-and-repurchase +costs the markdown difference plus processing cost plus potential disposition loss. + +--- + +## 10. Data-Driven Return Reduction + +### 10.1 Root Cause Analysis by Return Reason + +Returns are a symptom. Reducing return rates requires treating the cause: + +| Return Reason | Root Cause Investigation | Typical Fix | Expected Reduction | +|--------------|------------------------|------------|-------------------| +| "Didn't fit" (apparel) | Poor size guidance, inconsistent sizing, inadequate photos | Size recommendation engine, fit model photos, detailed measurements | 15-25% reduction in "didn't fit" returns | +| "Not as expected" | Product photo/description doesn't match reality | Lifestyle photos, video demos, customer photos in reviews, AR preview | 10-20% reduction | +| "Defective" | Manufacturing quality, shipping damage, product design flaw | Vendor quality scorecard, packaging improvement, design feedback loop | Variable — depends on root cause | +| "Changed my mind" | Impulse purchase, bracketing | Cooling-off period messaging, wish list instead of cart, fit technology | 5-10% reduction | +| "Better price found" | Competitive pricing, price transparency | Price-match guarantee, automated price alerts | 8-15% reduction | +| "Arrived too late" | Shipping delays, inaccurate ETAs | Improved delivery estimates, proactive delay notifications | 20-30% reduction in lateness returns | + +### 10.2 SKU-Level Return Rate Monitoring + +| Return Rate (rolling 90 days) | Action | +|-------------------------------|--------| +| < 5% | Normal. No action required. | +| 5-10% | Review product listing for accuracy. Check reviews for recurring complaints. | +| 10-15% | Flag for merchandise review. Audit listing photos/description. Check sizing data. | +| 15-25% | Escalate to category manager. Consider adding warnings to listing. Review vendor quality. | +| > 25% | Stop-sell review. The product may have a systemic issue that no listing fix can solve. | + +### 10.3 Return Cost Allocation Model + +Allocating return costs to the business units that drive them creates accountability: + +| Return Cause | Cost Allocation | +|-------------|----------------| +| Defective product | Vendor (via RTV/defect claim) or Merchandise (if vendor approved) | +| Wrong item shipped | Fulfillment operations | +| Damaged in shipping | Carrier (via shipping claim) or Packaging engineering | +| Poor product description | E-commerce / Content team | +| Sizing issue | Merchandise / Product development | +| Customer changed mind | Cost of doing business (absorbed by margin model) | +| Fraud | Loss prevention budget | diff --git a/web-app/public/skills/returns-reverse-logistics/references/edge-cases.md b/web-app/public/skills/returns-reverse-logistics/references/edge-cases.md new file mode 100644 index 00000000..1deeb656 --- /dev/null +++ b/web-app/public/skills/returns-reverse-logistics/references/edge-cases.md @@ -0,0 +1,635 @@ +# Returns & Reverse Logistics — Edge Cases Reference + +> Tier 3 reference. Load on demand when handling complex or ambiguous return situations that don't resolve through standard workflows. + +These edge cases represent the scenarios that separate experienced returns operations managers from everyone else. Each involves competing interests, ambiguous liability, policy grey areas, and real financial or regulatory exposure. They are structured to guide resolution when standard playbooks break down. + +--- + +## How to Use This File + +When a return situation doesn't fit a clean category — when policy intent conflicts with policy letter, when fraud indicators coexist with legitimate behaviour, or when the financial or regulatory exposure justifies deeper analysis — find the edge case below that most closely matches the situation. Follow the expert approach step by step. Document your reasoning; these are the cases that generate customer escalations, chargeback disputes, and compliance questions. + +--- + +### Edge Case 1: High-Value Electronics with Firmware Wiped but Extensive Hardware Use Evidence + +**Situation:** +A customer returns a MacBook Pro (retail $2,499) within the 15-day electronics return window claiming "not what I expected." The unit arrives in original packaging with all accessories. A visual inspection gives it Grade A — no cosmetic defects. However, during functional testing, the technician notices: the laptop has been factory-reset (no user data), but the battery cycle count reads 147 (a new unit would have 1-5 cycles from factory QA). The SSD health shows 2.3 TB of total data written. The serial number matches the sold unit. The customer's account is in good standing with $12,000 in lifetime purchases and a 14% return rate. + +**Why It's Tricky:** +The customer is technically within the return window. The product appears "like new" on the surface. But 147 battery cycles represents approximately 4-6 months of typical daily use — far more than the 12 days since delivery. The most likely explanation: the customer bought a new MacBook, swapped the firmware/data to the new unit, and is returning their old MacBook of the same model in the new unit's box. However, the serial number matches, which rules out a physical swap of the entire machine. This suggests the customer simply used the product very heavily for 12 days (possible for a power user or if the customer was migrating data from an old system) OR the battery cycle counter has an anomaly. + +The policy says accept within 15 days. The physical evidence suggests this wasn't a brief trial. The customer is valuable. The Apple ecosystem makes serial number verification reliable. + +**Common Mistake:** +Accepting the return at face value because it's within the window and the serial matches, then restocking as Grade A. The 147 battery cycles mean this is a Grade B at best — battery health is already degraded 3-5% from the cycling, and the SSD wear is real. Restocking it as new and selling it to the next customer creates a product quality issue. + +The other common mistake: accusing the customer of fraud. The evidence is suggestive but not conclusive. A content creator who downloaded, edited, and uploaded 2 TB of video in 12 days would have a legitimate use pattern. + +**Expert Approach:** +1. Accept the return — the customer is within the policy window and the serial matches. Do not deny. +2. Grade the unit as B, not A. The battery cycle count and SSD wear are objective quality indicators. Document both with screenshots of the diagnostic tool output. +3. Refund the customer in full — the 15-day window does not have a condition requirement beyond "original packaging and accessories," which is met. +4. Route the unit to "open box" or certified refurbished channel, not back to new inventory. Price at 80-85% of retail. +5. Add a data point to the customer's return profile: "high-use return within window." This is not a fraud flag — it's an intelligence flag. If a pattern emerges across multiple high-value electronics returns, the fraud scoring model will accumulate the signal naturally. +6. Do NOT apply a restocking fee. The product was returned within the standard window with all accessories. Applying a fee because of battery wear during a 12-day period creates a customer experience problem that costs more than the margin lost on the Grade B vs Grade A disposition. +7. Review the product listing: does it offer a trial or satisfaction guarantee that implicitly invites heavy use? If so, this return is within the spirit of the policy. + +**Key Indicators:** +- Battery cycle count > 50 within a 15-day return window is an anomaly worth documenting +- SSD write volume > 500 GB suggests more than casual testing +- Factory reset before return is not suspicious in itself (privacy-conscious customer behaviour) but combined with high-use indicators, it's a data point +- Serial number match is critical — if it mismatches, this is swap fraud, not an edge case + +--- + +### Edge Case 2: Hazmat Return with Improper Packaging + +**Situation:** +A customer initiates a return for a cordless power tool kit that includes two lithium-ion batteries (each 5.0 Ah, 20V = 100 Wh per battery). The customer packed the tool, batteries, and charger loose in a standard cardboard box with crumpled newspaper as packing material. The return label was generated through the automated RMA portal, which issued a standard ground shipping label. The parcel is picked up by the carrier. Two days later, the carrier's hazmat compliance team intercepts the package at a sort facility, flags it as a non-compliant lithium battery shipment (no Class 9 labelling, no battery-handling marks, batteries not individually protected against short circuit), and imposes a $500 hazmat violation penalty on your company's shipping account. + +**Why It's Tricky:** +Lithium-ion batteries over 100 Wh require Special Provision 188 compliance under IATA DGR and 49 CFR §173.185 for ground transport. Even under the 100 Wh threshold, UN 3481 (lithium ion batteries packed with equipment) requires the battery terminals to be protected against short circuit and the package to be marked with the lithium battery handling mark. The customer didn't know any of this — they packed their return the way they'd pack any product. The automated RMA system didn't flag the product as requiring special return packaging because the product master data doesn't have a "contains lithium batteries" attribute that triggers special handling. + +You now have a $500 carrier penalty, a product in limbo at a carrier facility, a customer who expects a refund, and a systemic gap in your returns process. + +**Common Mistake:** +Blaming the customer or refusing the return because the item was improperly packaged. The customer had no way of knowing the packaging requirements. The system generated a standard return label — the customer followed the instructions given. This is an internal process failure, not a customer failure. + +The second mistake: asking the customer to go buy proper hazmat packaging materials and re-ship. This is unreasonable for a consumer return. You would never ask this. + +**Expert Approach:** +1. Contact the carrier's hazmat compliance team immediately. Determine the status of the package — is it being held, returned to the customer, or destroyed? Negotiate the penalty: first offence with an account in good standing may be reduced to a warning. If not, the $500 is a cost of the process gap. +2. Arrange for the package to be returned to the customer (if not already). Do NOT ask the carrier to forward it — it's non-compliant, and re-shipping it in the same packaging compounds the violation. +3. Send the customer a proper return kit: a UN-rated box with battery terminal protectors, lithium battery handling labels, and clear instructions. Include a pre-paid hazmat-rated shipping label (GROUND ONLY — lithium batteries over 100 Wh cannot ship by air via standard return channels). Cost: $15-25 for the kit plus $20-35 for the hazmat-rated label. +4. Process the refund upon receipt at your facility. Do not delay the refund because of the packaging issue — this was your process failure. +5. Systemic fix: flag all products containing lithium batteries > 20 Wh in the product master data. When a return is initiated for these products, suppress the standard return label and instead trigger the special return kit shipment. This costs $35-60 per return but eliminates the $500+ violation risk. +6. Absorb the carrier penalty internally. Do not pass it to the customer. Charge it to the process improvement budget. + +**Key Indicators:** +- Products containing lithium-ion batteries > 100 Wh (or containing multiple batteries where the sum exceeds 100 Wh) require UN 3481 packaging for return shipping +- Carrier hazmat violations range from $500 to $50,000+ depending on severity and history +- The systemic cost of not having a hazmat return process is: (number of battery-containing returns per year) × (probability of carrier interception) × (average penalty) — for most retailers, implementing the proper process is cheaper within the first year + +--- + +### Edge Case 3: Cross-Border Return with Duty Drawback Implications + +**Situation:** +A Canadian customer purchased a $1,200 designer handbag from your US-based e-commerce site. The product was shipped from your US warehouse to Toronto. Canadian customs assessed 18% duty ($216) plus 13% HST ($184.08) on the customer at import, for a total of $400.08 in import charges paid by the customer. The customer now wants to return the handbag (it's the wrong colour — their order specified "cognac" but the product listing photo and actual product colour differ under different lighting). They want a full refund including the import duties they paid. The handbag is in perfect Grade A condition. + +**Why It's Tricky:** +Three financial flows are entangled: +1. The product price ($1,200) — refundable through your normal return process +2. The Canadian import duty ($216) — reclaimable by the customer through CBSA (Canada Border Services Agency) casual refund process or by you through a duty drawback claim if the product is re-exported +3. The HST ($184.08) — reclaimable by the customer through a CBSA B2G form + +The customer expects you to refund the full $1,600.08. But you only collected $1,200 — the duties and taxes were collected by Canadian customs, not by you. You can refund what you collected, but the $400.08 in duties/taxes must be recovered through the customs process. + +Complicating factors: the customer doesn't know how to file a CBSA casual refund. The duty drawback requires the handbag to be re-exported from Canada within specific timelines. Return shipping from Canada to the US requires a commercial invoice and customs declaration for the returned goods. And the return shipping cost ($45-80 for a tracked cross-border return) may be a point of contention — who pays? + +**Common Mistake:** +Refunding the customer $1,600.08 to "make it right" without understanding that the $400.08 in duties/taxes can be recovered from CBSA, effectively eating $400 that isn't yours to eat. This seems customer-friendly but is financially illiterate — it means you're paying the Canadian government's duty for the customer. + +The second mistake: telling the customer "duties are your responsibility" and only refunding $1,200. While technically true, this is a fulfilment error (wrong colour due to misleading product photo), which changes the obligation calculus. A customer who received the wrong colour should be made whole. + +**Expert Approach:** +1. Acknowledge the fulfilment error. This was your product photo misrepresentation, not buyer's remorse. This changes the return from "standard" to "seller-fault." +2. Refund the $1,200 product price immediately upon return receipt. This is your standard process. +3. For the $400.08 in duties/taxes: provide the customer with step-by-step instructions for filing a CBSA casual refund claim (Form B2, with the returned-goods receipt as documentation). Most casual refund claims are processed in 4-8 weeks. +4. Because this is a seller-fault return, cover the return shipping cost. Provide a prepaid cross-border return label. Ensure the label includes proper customs documentation (commercial invoice marked "RETURNED GOODS — NO COMMERCIAL VALUE" with original export reference). +5. As a goodwill gesture for the inconvenience (wrong colour + cross-border return hassle), offer a $50-100 store credit. This costs less than refunding $400 in duties you didn't collect. +6. If the customer insists on immediate full reimbursement of the duties: evaluate the customer's LTV and the competitive cost of losing them. For a first-time international customer, the $400 goodwill refund may be justified if the customer's potential LTV exceeds $2,000. For a one-time buyer, provide the CBSA refund instructions and hold firm on the product refund only. +7. File your own duty drawback claim (if applicable) for the import duty that was assessed when you originally exported the goods. US duty drawback under 19 USC §1313 allows recovery of 99% of duties paid on exported goods that are returned, within 5 years. This requires the original export documentation. + +**Key Indicators:** +- Cross-border returns always involve at least three financial streams: product price, import duty, and sales/value-added tax +- The customer paid the duties, not you — refunding duties you didn't collect is a cost that should only be incurred as a deliberate customer recovery decision, not a default +- CBSA casual refund claims require proof that the goods were re-exported; the customer needs the return tracking number showing the package crossed back into the US +- Return shipping customs declarations for returned goods should use HS code 9801 (US) or tariff item 9813 (Canada) to avoid re-assessment of duties on the returned product + +--- + +### Edge Case 4: Influencer Bulk Return Post-Content-Creation + +**Situation:** +A social media influencer with 850K Instagram followers and a fashion/lifestyle brand placed an order for 24 items totalling $3,200 (mix of apparel, accessories, and shoes). The order was placed 18 days ago, delivered 15 days ago. The influencer has since posted 4 Instagram Reels and 2 TikTok videos featuring 22 of the 24 items in styled outfits, "haul" content, and "try-on" format. The videos collectively have 2.1 million views. The influencer now initiates a return for 22 of the 24 items (keeping 2 items worth $180), claiming "didn't fit" and "not as expected" for the various items. All items are within the 30-day return window. + +The returned items arrive and inspection reveals: 16 items are Grade A (tags on, no wear signs), 4 items are Grade B (tags removed, minor wear indicators — one dress has foundation on the collar), and 2 items are Grade C (visible wear, one pair of shoes shows outdoor sole wear). + +**Why It's Tricky:** +The customer technically complied with the return policy — the items are within the 30-day window, and the stated return reasons are among the accepted reasons. The influencer extracted significant brand value (2.1M views of organic-looking content featuring your products) without paying for it. The cost of equivalent paid influencer content at her follower count would be $5,000-15,000. + +But there's no "you used our products for content" clause in the return policy. The influencer didn't sign an agreement. She's a customer exercising her return rights. Refusing the return creates legal risk (she documented that the items were purchased legitimately) and PR risk (an influencer with 850K followers posting about a return denial generates vastly more negative attention than the $3,020 refund). + +**Common Mistake:** +Refusing the return or charging punitive restocking fees on all 22 items. This triggers a "brand vs influencer" public dispute that costs far more than $3,020 in brand damage. The second mistake: passively accepting the return and learning nothing — the same influencer (or others) will repeat this pattern. + +**Expert Approach:** +1. Process the return. Accept all 22 items. Grade them honestly: + - 16 items Grade A: restock as new. Full refund on these items. + - 4 items Grade B: refund in full (tags removed isn't grounds for denial within the return window for apparel). Route to open-box/outlet. + - 2 items Grade C: refund in full minus restocking fee on the shoes with outdoor wear (visible use beyond trying on). The dress with foundation gets full refund — cosmetic transfer during try-on is expected. +2. Apply the restocking fee to the worn shoes only. Explain: "We've processed your return. 21 items received a full refund. The [shoe name] showed wear beyond trying on, so a 15% restocking fee of $X was applied per our return policy." +3. Separately, refer this case to the marketing/brand partnerships team. The influencer generated $5,000-15,000 in equivalent media value. The business-smart play is to convert her from a "free content via returns" customer to a paid brand ambassador. Reach out with: "We loved how you styled our pieces. We'd like to discuss a collaboration." +4. Add a note to the customer's profile for future monitoring. If this pattern repeats (bulk purchase → content → bulk return), the fraud scoring model will accumulate points naturally. If she becomes a brand ambassador, the returns stop being a problem. +5. Systemic: consider a "content creator" return policy that offers extended exchange/store credit windows for influencers who tag the brand, in exchange for a no-return-for-refund agreement on items used in content. This requires marketing/legal collaboration. + +**Key Indicators:** +- Bulk orders from accounts with high social media followings, followed by near-complete returns, is an emerging pattern that existing return policies don't address +- The refund cost ($3,020) is almost always less than the negative PR cost of a public denial +- Marketing value of the content may exceed the refund cost, making this a net positive event if handled strategically +- Restocking fees should only apply to items with objective condition defects, not as punishment for the pattern + +--- + +### Edge Case 5: Warranty Claim on Product Modified by Customer + +**Situation:** +A customer purchased a gaming laptop ($1,899) 14 months ago and is filing a warranty claim because the display has developed a persistent flickering issue that makes the laptop unusable. During inspection, the technician discovers that the customer has upgraded the RAM from the factory-installed 16 GB to 32 GB using third-party RAM modules. The RAM upgrade is clearly visible (different brand module in the second DIMM slot). The laptop's warranty is 24 months from purchase. The manufacturer's warranty terms state: "Warranty is void if the product has been modified, altered, or repaired by anyone other than an authorised service centre." + +The customer's position: "I upgraded the RAM, not the display. The RAM has nothing to do with the screen flickering. The warranty should cover the display." The manufacturer's position: "Any modification voids the entire warranty." + +**Why It's Tricky:** +The customer's logic is reasonable. RAM and display are independent subsystems. A RAM upgrade almost certainly didn't cause display flickering (which is typically a cable, inverter, or GPU issue). However, the manufacturer's warranty language is broad — "any modification" voids the warranty. Legally (under Magnuson-Moss Warranty Act in the US), a warranty provider cannot void a warranty for using third-party parts unless the warrantor can demonstrate that the third-party part caused the defect being claimed. The "void if modified" clause is likely unenforceable for unrelated modifications, but most customers don't know this, and challenging it requires escalation. + +As the retailer, you're caught between the customer (who expects you to facilitate the warranty claim) and the manufacturer (who will deny it based on the modification). Your extended warranty (if sold) may have similar language. + +**Common Mistake:** +Denying the warranty claim outright because "the product was modified." This is both legally questionable (Magnuson-Moss) and customer-hostile. The customer's modification was a routine, widely-documented upgrade that the laptop was designed to support (user-accessible RAM slot). + +The second mistake: accepting the claim and eating the repair cost without pursuing the manufacturer. The display defect is a manufacturing quality issue, not a retail liability. + +**Expert Approach:** +1. Accept the laptop for evaluation. Do NOT deny at the point of customer contact. Tell the customer: "We'll inspect the display issue and submit the warranty claim to the manufacturer." +2. Document the modification (photographs of the third-party RAM) and the defect (video of display flickering). Test the display issue with and without the third-party RAM installed — if the flickering persists with original RAM configuration, the modification is demonstrably unrelated to the defect. +3. Submit the warranty claim to the manufacturer with the documentation. Include: the defect evidence, the modification documentation, and a note stating that the modification is unrelated to the claimed defect per Magnuson-Moss Warranty Act provisions. +4. If the manufacturer denies: escalate to the manufacturer's warranty dispute resolution process. Cite 15 USC §2302(c) — a warrantor may not condition warranty coverage on the use of a specific article unless the article is provided free of charge. The customer's use of third-party RAM is protected. +5. If the manufacturer continues to deny: evaluate the repair cost. A display cable replacement is typically $50-150 in parts and labour. If you have an in-house repair capability, consider performing the repair and pursuing the manufacturer for reimbursement. The customer gets a working laptop, you maintain the relationship, and you have a legitimate claim against the manufacturer. +6. If an extended warranty was sold: check the extended warranty terms carefully. Third-party extended warranties (Allstate, Asurion) have their own modification clauses that may differ from the manufacturer's. If the extended warranty covers it, file against the warranty provider instead. +7. Communicate progress to the customer at each stage. The worst outcome is silence during a warranty claim. + +**Key Indicators:** +- Magnuson-Moss Warranty Act (15 USC §2301-2312) prohibits warranty void clauses based on the use of third-party parts unless the warrantor proves the part caused the defect +- FTC enforcement of Magnuson-Moss has increased in recent years, making "void if modified" stickers largely unenforceable +- Common user modifications that should not void unrelated warranty claims: RAM upgrades, storage drive replacements, adding peripherals, installing aftermarket cases/screen protectors +- Modifications that may legitimately void related warranty claims: CPU/GPU overclocking (thermal damage), software rooting/jailbreaking (software defects), physical modifications to cooling systems (overheating) + +--- + +### Edge Case 6: Serial Returner Who Is Also a High-Value Customer + +**Situation:** +Customer "Elena M." has a 3-year purchase history totalling $82,000 in gross purchases. She shops primarily in premium apparel, shoes, and accessories. Her return rate is 42% — she has returned $34,440 in product over the same period. Her net revenue after returns is $47,560. Her average order value is $680, and she typically orders 3-5 items per order, keeps 2-3, and returns 1-2. Her return reasons are consistently "didn't fit" or "not what I expected." Returned items are almost always Grade A. She has never returned a used or damaged item. She is a member of your top-tier loyalty programme. + +Your fraud detection system has flagged her with a score of 68 (above the 65-point review threshold) due to her return rate, volume, and frequency. The system recommends a refund hold pending review. + +**Why It's Tricky:** +Elena is bracket-shopping — buying multiple items knowing she'll return some. This is not fraud. It's a legitimate (if expensive) shopping behaviour that high-end retail has dealt with for decades. Her 42% return rate is high, but her $47,560 net revenue over 3 years places her in your top 2% of customers by net value. Her returns are Grade A, meaning the disposition cost is minimal (restock as new). The actual cost of her returns is: return processing at ~$7 per return × approximately 150 returns = $1,050 in processing costs over 3 years. That's negligible against $47,560 in net revenue. + +Putting a hold on her refund will damage a relationship worth ~$16,000/year in net revenue. But your fraud system flagged her, and ignoring the system creates process precedent. + +**Common Mistake:** +Enforcing the fraud hold. Treating Elena like a fraud suspect — even temporarily — risks losing a customer whose LTV is in the top 2%. The fraud scoring system is correctly identifying a signal (high return rate) but incorrectly interpreting it as fraud risk. + +The second mistake: exempting her from the fraud system permanently. This creates a loophole that actual fraudsters could exploit if they know that high spend protects them. + +**Expert Approach:** +1. Override the fraud hold immediately. Process Elena's return normally. The override is justified by: positive net LTV (top 2%), Grade A return condition (no cost indication of fraud), consistent behaviour over 3 years (not a new pattern), and return reasons consistent with bracket shopping. +2. Add a "VIP override" annotation to her customer profile. This allows the fraud system to continue monitoring her behaviour (important if her pattern changes to something genuinely fraudulent) while preventing friction on her normal returns. +3. Set a review trigger for pattern deviation. If Elena's return rate exceeds 60%, or if returned item condition drops below Grade A, or if she starts returning items from new categories (electronics, high-shrink), the override should be suspended and a human review triggered. +4. Share the case (anonymised) with the fraud model team as a false-positive calibration data point. The model should receive a negative adjustment for the LTV-to-return-rate interaction: customers with high net LTV and Grade A returns should have their base scores reduced. +5. Consider proactive outreach through the personal shopping or styling team. Elena's bracket shopping suggests she'd benefit from virtual styling, improved size recommendation tools, or early access to try-on programmes. Converting her from a bracket shopper to a targeted shopper reduces return volume while preserving revenue. +6. Do NOT restrict her return privileges, adjust her return window, or impose restocking fees. The ROI calculation is unambiguous: $16K/year net revenue versus $350/year in return processing costs. The returns are a cost of doing business with a high-value customer. + +**Key Indicators:** +- Return rate alone is not a fraud indicator. Return rate must be contextualised with: net LTV, return condition, behaviour consistency, and return reason patterns. +- The fraud scoring model should include an LTV offset that reduces scores for customers with positive net LTV. The current model doesn't weight this strongly enough. +- Bracket shopping is most common in: premium apparel (multiple sizes), shoes (half-size uncertainty), and accessories (colour matching). Categories where in-person evaluation matters. +- Industry benchmark: luxury e-commerce return rates of 30-40% are normal. The 42% rate is slightly high but not anomalous for the category. + +--- + +### Edge Case 7: Return of a Recalled Product + +**Situation:** +A customer brings a portable space heater to the store for a return, stating "it doesn't work properly and I'm scared it's going to start a fire." The receipt shows purchase 45 days ago (outside the 30-day return window). During the intake process, the associate scans the product barcode and the system matches it to an active CPSC (Consumer Product Safety Commission) recall issued 10 days ago due to a fire hazard from a faulty thermostat. The recall notice instructs consumers to "immediately stop using the product and contact [manufacturer] for a full refund or replacement." + +**Why It's Tricky:** +This is not a return — it's a recall. But the customer came to your store expecting a return process, not a recall process. The recalled product cannot enter your standard returns inventory (it's a safety hazard). It cannot be restocked, liquidated, donated, or disposed of through normal channels — recalled products have specific disposition requirements. But the customer is standing in front of you wanting a resolution now, and telling them "go contact the manufacturer" feels like you're passing the buck. + +Additionally: the product is outside the return window, so the standard return system would deny it. The recall overrides the return policy, but the standard return system may not know that. If the associate processes it as a "return," the recalled unit could end up in general returns inventory and eventually be restocked or liquidated — both of which create safety and legal liability. + +**Common Mistake:** +Processing it as a standard return. This puts a recalled product into the returns stream where it may be restocked or liquidated, creating enormous liability. Even if it's "disposed of," standard disposal doesn't include the CPSC reporting requirements for recalled product destruction. + +The second mistake: refusing the return because it's outside the 30-day window and telling the customer to contact the manufacturer. You sold them a product that's now subject to a safety recall. Directing them elsewhere damages trust and may create legal exposure under state consumer protection laws. + +**Expert Approach:** +1. The associate should STOP the standard return process. This is a recall, not a return. Do not issue a refund through the POS return function. +2. Accept the product from the customer. Issue a full refund at the original purchase price as a "recall accommodation" — most POS systems have a separate recall/safety return code. If not, process as a defective return with a manager override for the window, and add a note "RECALLED PRODUCT — DO NOT RESTOCK." +3. Physically segregate the product immediately. Place it in the recall quarantine area (not the general returns staging area). Affix a "RECALLED — DO NOT PROCESS" label. +4. Log the recall return in the recall tracking system (or spreadsheet if no system exists) with: date, customer name, serial number, lot number, store location, CPSC recall number. +5. Follow the manufacturer's recall instructions for retailer-held inventory. Typically: hold until manufacturer arranges pickup or provides destruction instructions with certificate-of-destruction requirements. +6. Report the return to the recall coordinator. The recall coordinator aggregates data for CPSC reporting requirements (firms involved in recalls must maintain records of corrective actions). +7. Check your remaining inventory (stores + warehouse) for the same product. If any units are still in sellable inventory, pull them immediately. This is a legal obligation once you're aware of the recall. +8. If the customer purchased other products from the recalled brand, consider proactively checking those against recall databases as a goodwill gesture. + +**Key Indicators:** +- Recalled products MUST NOT enter the standard returns stream. The disposition for recalled products is determined by the recall notice, not by your normal disposition tree. +- CPSC recall compliance is not optional. Failure to segregate and properly handle recalled products can result in penalties up to $100,000 per violation under the Consumer Product Safety Act. +- The refund to the customer is ultimately the manufacturer's financial responsibility. Process the refund to the customer immediately and pursue reimbursement from the manufacturer through the recall programme. +- Some recalls are "voluntary" (manufacturer-initiated) and some are mandatory (CPSC-ordered). The retailer's obligation is the same in both cases. + +--- + +### Edge Case 8: Gift Receipt Return at Higher Current Price + +**Situation:** +A customer presents a gift receipt for a premium blender purchased by the gift-giver 6 weeks ago for $279.99. The blender is currently selling for $309.99 (price was increased 2 weeks ago due to a supplier cost increase). The customer wants to return the blender for store credit. The gift receipt shows the $279.99 purchase price but the customer is looking at the shelf tag showing $309.99. + +**Why It's Tricky:** +Gift receipt policy typically states "refund at purchase price to store credit." This is clear. But the customer sees a $30 discrepancy and may interpret the gift receipt as entitling them to the current value of the product. If you issue store credit for $279.99 and the customer wants to "exchange" for the same blender (maybe in a different colour), they'd need to pay $30 out of pocket for the exact same product — which feels absurd from a customer perspective. + +The reverse scenario is more common and more dangerous: gift receipt return when the price has dropped. Gift-giver paid $279.99, current price is $229.99, and the gift recipient gets $279.99 in store credit — effectively profiting $50. This is a known return arbitrage vector. + +**Common Mistake:** +Issuing store credit at the current (higher) price to avoid the awkward conversation. This creates a $30 loss and, more importantly, establishes a precedent that gift receipt returns get current-price value. During seasonal markdowns (post-holiday), this policy would be exploited systematically. + +**Expert Approach:** +1. Issue store credit at the documented purchase price ($279.99). This is the policy and the financially correct answer. +2. If the customer wants to exchange for the same product at $309.99, offer to process it as even exchange at the original purchase price (no additional charge). This is an exchange, not a return-and-repurchase. The $30 price difference is absorbed as goodwill. +3. If the customer wants a refund (store credit) and will buy a different product, the store credit amount is $279.99. They can use it toward any purchase. +4. If the customer objects to the $279.99 amount: explain calmly that gift receipts reflect the purchase price, which protects gift-givers' privacy (the gift-giver doesn't want the recipient to know they paid less than current price) and ensures accurate accounting. Most customers accept this explanation. +5. Never issue store credit above the documented purchase price unless a manager explicitly authorises it as a one-time customer accommodation, documented in the transaction notes. + +**Key Indicators:** +- Gift receipt store credit should always be at the lower of: purchase price or current selling price. This protects against both upward and downward price arbitrage. +- An exception for even-exchange at original price (same item, different colour/size) is operationally clean and customer-friendly. +- Track gift receipt returns during post-holiday markdown periods. A spike in gift-receipt returns when prices drop is an arbitrage signal. + +--- + +### Edge Case 9: Cross-Channel Return Where Online Price Differs from Store Price + +**Situation:** +A customer purchased a stand mixer online for $249.99 during a flash sale (regular online price is $329.99, regular store price is $349.99). The customer wants to return it in-store. The store's return system pulls the current store price ($349.99) because the online flash sale price is not visible in the store's POS. If the associate processes the return at store price, the customer receives a $100 windfall. + +**Why It's Tricky:** +Omnichannel systems often have pricing discrepancies between channels. Online pricing is dynamic (flash sales, personalised pricing, coupon codes), while store pricing updates on a different cadence. The return system may not have visibility into the customer's actual purchase price, only the current store price for the SKU. + +**Common Mistake:** +Processing the return at the store POS price ($349.99). This is a $100 overpayment that, at scale, represents significant financial leakage. Cross-channel return price arbitrage is a known fraud vector — buy online at the lowest price, return in-store at the higher price. + +**Expert Approach:** +1. Look up the original order. Use the customer's email, order number, or loyalty account to pull the actual purchase price. The refund amount should match the actual amount paid ($249.99), not the current store price. +2. If the order lookup system isn't available in-store (system limitation), ask the customer for their order confirmation email. Most customers have this accessible on their phone. +3. If no order verification is possible: refund to the original payment method only. This ensures the refund goes back to the card that was charged $249.99 — the payment processor will reconcile to the actual charge amount regardless of what the POS tries to refund. If the POS attempts to refund $349.99 to a card that was only charged $249.99, the processor should limit the refund to the charged amount (though not all processors do this reliably). +4. Never issue a cash or store credit refund for an online purchase returned in-store without verifying the actual purchase price. Cash and store credit bypass the payment processor safeguard. +5. Systemic fix: ensure the in-store return system queries the online order management system for the actual purchase price before processing any BORIS (buy online, return in store) return. This is table-stakes omnichannel operations. + +**Key Indicators:** +- Cross-channel return price discrepancy is one of the top 3 sources of return-related financial leakage in omnichannel retail +- Always refund to original payment method for cross-channel returns (prevents price-arbitrage via store credit) +- The POS system should display the actual purchase price from the original order, not the current store price, for all cross-channel returns +- Audit cross-channel returns monthly for price discrepancy patterns + +--- + +### Edge Case 10: Counterfeit Product Discovered in Return Stream + +**Situation:** +A customer returns a "Dyson V15 Detect" cordless vacuum (retail $749.99) claiming it stopped working after 2 weeks. During inspection, the returns technician notices subtle differences from a genuine Dyson V15: the weight is slightly off (lighter by 200g), the laser dust-detection head has a different LED colour temperature, the serial number format doesn't match Dyson's standard format, and the packaging — while high quality — has a slightly different font on the warranty card. The technician suspects this is a counterfeit. The customer purchased the unit from your marketplace platform through a third-party seller, "EliteTech Solutions," who has 4.2 stars and 2,300 reviews. + +**Why It's Tricky:** +If this is counterfeit, multiple problems converge. The customer is a victim — they paid $749.99 for a fake product. The marketplace seller may be knowingly selling counterfeits, or may themselves have been deceived by their supply chain. Dyson has an aggressive brand protection programme and may pursue legal action against the marketplace. The counterfeit unit cannot be returned to the seller, restocked, liquidated, or disposed of through normal channels — it's illegal goods. And you need to determine whether this is an isolated incident or evidence of a systematic counterfeiting operation on your marketplace. + +**Common Mistake:** +Processing the return as a standard defective return, issuing a refund, and putting the counterfeit unit back into the returns stream where it may eventually be liquidated and re-enter the market. This creates trademark liability. + +The second mistake: accusing the customer of returning a counterfeit (implying they're running a swap scam). The customer may genuinely be a victim. + +**Expert Approach:** +1. Accept the product from the customer. Issue a full refund immediately. Do NOT make the customer wait for an investigation. They paid for a genuine product and received a counterfeit — they are the victim. +2. Quarantine the product. Label it "SUSPECTED COUNTERFEIT — DO NOT PROCESS." Photograph extensively: every angle, labels, serial numbers, packaging, weight, and the specific indicators that raised suspicion. +3. Notify Brand Protection / Loss Prevention immediately. Provide the photographs and inspection findings. +4. Brand Protection should contact Dyson's brand protection team to confirm the counterfeit determination. Dyson will want the unit for forensic analysis. Provide it under a chain-of-custody document. +5. Suspend the marketplace seller (EliteTech Solutions) pending investigation. Pull all active listings. Review their other product listings for similar brand-name products that may also be counterfeit. +6. Review all recent orders from EliteTech Solutions for the same product. Contact those customers proactively: "We're conducting a quality review of a product you purchased. We'd like to offer you a free inspection and, if needed, a replacement or full refund." +7. Do NOT destroy the counterfeit unit — it's evidence. The brand owner and potentially law enforcement will need it. +8. If the investigation confirms systematic counterfeiting: permanently ban the seller, report to the appropriate authorities (FBI for trademark counterfeiting, CBP if the goods were imported), cooperate with the brand owner's legal team, and notify all affected customers. + +**Key Indicators:** +- Weight discrepancy is one of the most reliable first indicators of counterfeits — counterfeiters rarely match the exact weight of genuine products +- Serial number format mismatches are definitive when confirmed by the brand owner +- Counterfeit products found in the return stream often indicate a larger supply chain problem, not an isolated incident +- Marketplace liability for counterfeit goods is an evolving legal area (INFORM Consumers Act, SHOP SAFE Act) — document everything for legal protection +- Never liquidate, donate, or return suspected counterfeit goods to any channel. The legal liability is unlimited. + +--- + +### Edge Case 11: Simultaneous Return and Chargeback — Double-Refund Risk + +**Situation:** +A customer purchases a high-end espresso machine ($849.99) and initiates an online return 18 days after delivery, citing "machine makes grinding noise during extraction." The RMA is approved and a prepaid return label is generated. Two days later — before the customer has shipped the return — the payments team receives a chargeback notification from Visa under reason code 13.3 ("Not as Described"). The customer has now created two parallel refund paths for the same $849.99 transaction. + +**Why It's Tricky:** +If both processes complete independently, the customer receives $1,699.98 — a double refund. The return process would refund $849.99 upon receipt and inspection. The chargeback process, if not contested, would refund $849.99 through the card network. Payments teams and returns teams often operate in separate systems with no automatic cross-check. The customer may be deliberately exploiting this gap, or they may genuinely not understand that a chargeback and a return are separate mechanisms (surprisingly common — many customers file chargebacks when they get frustrated waiting for a return label, not understanding they've initiated a second refund process). + +The chargeback has regulatory timelines: Visa requires the merchant to respond within 20 days or the chargeback auto-closes in the cardholder's favour. The return has no such external deadline. This asymmetry means the chargeback demands attention first. + +**Common Mistake:** +Processing the return refund without checking for an active chargeback. This is the #1 source of double-refund losses in e-commerce. The second mistake: immediately assuming fraud and antagonising a customer who may simply be confused about the process. + +**Expert Approach:** +1. HALT the RMA process immediately. Add a "chargeback hold" flag to the RMA. Do not process a return refund while a chargeback is active. +2. Contact the customer within 24 hours. Use neutral, helpful language: "We received your return request and also noticed a dispute was filed with your bank for the same order. We'd like to help resolve this through whichever channel is easiest for you. If you'd prefer to proceed with the return (which typically resolves faster), could you ask your bank to withdraw the dispute? Or if you'd prefer to resolve through your bank, we can cancel the return. We just need to use one process to avoid delays." This gives the customer a face-saving way to resolve. +3. If the customer agrees to withdraw the chargeback: get confirmation in writing (email reply is sufficient), then proceed with normal return processing. Keep the chargeback response prepared — if the bank doesn't actually withdraw, you need the evidence. +4. Respond to the chargeback regardless: within the 20-day window, submit a response to Visa with: proof of delivery, product description matching the listing, evidence of the open RMA (showing you were actively resolving the customer's complaint through the return channel), and the customer's communication agreeing to resolve via return. This protects you if the chargeback isn't actually withdrawn. +5. If the customer doesn't respond or insists on both: treat as potential fraud. The chargeback takes priority (regulatory timeline). Fight the chargeback with evidence. Cancel the RMA. If the customer then ships the product back on the old label, process as an unsolicited return — accept the product but do not issue a refund (the chargeback is the refund mechanism). + +**Key Indicators:** +- Simultaneous return + chargeback is a known fraud vector called "double-dipping" +- It's also a common customer confusion error — about 40-60% of these cases are not intentional fraud +- The first 24 hours after detecting the overlap are critical — customer contact resolves 70% of cases +- Cross-reference returns and chargebacks daily. Any payment team / returns team process gap here is a significant financial exposure +- Track customers who have previously had a return + chargeback overlap, regardless of resolution — a second occurrence significantly increases the fraud probability + +**Documentation Required:** +- Screenshot of both active RMA and active chargeback for the same order +- Customer communication and response (timestamped) +- Chargeback response submitted to Visa +- Final resolution record: which channel was used, was the other cancelled, total refund amount + +--- + +### Edge Case 12: Customer Returns Product Purchased Through Employee Discount Programme + +**Situation:** +A customer returns a 65" Samsung OLED TV ($2,199.99 retail) with a receipt showing the purchase price of $1,319.99 — a 40% employee discount. The employee discount programme is run through a third-party perks platform (Perkspot, CorporatePerks) and is linked to the customer's employer. The customer is returning because "TV has a dead pixel cluster in the upper right quadrant — noticed after 3 days." The return is within the 30-day window. Your standard policy would refund the purchase price ($1,319.99), but the product at full retail restocks at $2,199.99 or resells as open-box at ~$1,760-1,870. + +**Why It's Tricky:** +The employee discount creates a price asymmetry that can be exploited. If the customer receives a cash refund of $1,319.99 but the product restocks at $2,199.99, there's no financial loss. But what if the customer then repurchases through the employee discount again? Or what if an employee discount customer returns a product and a friend buys it as "open box" at $1,760 — effectively getting a better deal through the return channel than the employee discount provides? + +The more immediate question: the dead pixel is a legitimate defect. Is this a return (customer exercises their right to return) or a warranty claim (manufacturer defect)? The distinction matters because the return refunds at the employee discount price ($1,319.99), while a warranty claim might provide a replacement at no cost (preserving the employee discount benefit on the new unit). + +**Common Mistake:** +Refunding at retail price ($2,199.99) instead of the employee discount purchase price ($1,319.99). This creates an $880 overpayment and, worse, opens a fraud vector: buy on employee discount, return for retail price, pocket the difference. The second mistake: applying a restocking fee to a defective product (dead pixels are a manufacturing defect, not a customer-fault return). + +**Expert Approach:** +1. Acknowledge the dead pixel defect. This is a manufacturing defect — no restocking fee applies. +2. Offer the customer a choice: (a) full return and refund at the employee discount purchase price ($1,319.99), or (b) warranty exchange for a replacement unit of the same model at no cost. Clearly explain the option: "Since the TV has a defect, we can either refund your purchase price or exchange it for a new unit. The exchange preserves your original pricing." +3. Most customers with a 40% discount will prefer the exchange — they get a working TV at the discounted price. The customer benefits more from the exchange ($2,199.99 value for $0 additional cost) than from the refund ($1,319.99 back but now needs to buy a TV again at $1,319.99 or $2,199.99). +4. If the customer insists on a refund: process at $1,319.99 (the actual purchase price). Do not refund at retail. Refund to original payment method. +5. Route the defective TV to Samsung for warranty claim (dead pixel clusters are a known panel defect covered under Samsung's warranty). The retailer recovers the wholesale cost ($1,200-1,400 estimated) from Samsung regardless of which option the customer chose. +6. Flag the transaction in the employee discount programme reporting — perks platforms track return rates by programme member. Excessive returns through discount programmes may indicate fraud (buying discounted, returning for credit, using credit at full value). + +**Key Indicators:** +- Employee discount, military discount, and corporate perks programme returns should ALWAYS refund at the discounted purchase price, never at retail +- Product defects on discounted purchases should be handled through exchange/warranty rather than return when possible — this preserves the discount benefit for the customer +- Track return rates by discount programme. An employee discount programme with a 25%+ return rate may be exploited +- The defective unit's warranty claim goes to the manufacturer regardless of the customer's return channel — always pursue vendor recovery + +--- + +### Edge Case 13: Return of Personalised / Custom-Engraved Product + +**Situation:** +A customer ordered a premium fountain pen (Montblanc Meisterstück, $620.00) with custom engraving ("To David, Love Mom") as a gift. The recipient, David, wants to return it because he already has a Meisterstück and would prefer store credit toward a different pen. The engraving is permanent — it cannot be removed without damaging the pen. The pen is in perfect condition, never used, still in the gift box. The product page stated "Personalised items are final sale and cannot be returned" at the time of purchase, but this notice was in the FAQ section, not at the point of engraving selection in the checkout flow. + +**Why It's Tricky:** +The policy says "final sale." The customer (the gift-giver, "Mom") technically agreed to this by completing the purchase. But the notice was buried in the FAQ, not displayed prominently during the personalisation step of checkout. Consumer protection laws in some states require the return policy to be "conspicuously displayed" at the point of sale. A disclosure buried in the FAQ may not meet the "conspicuous" standard. + +The pen is in perfect condition, but the engraving makes it unsellable through any standard channel. It cannot be restocked, sold as open-box, or liquidated — no one wants to buy a pen engraved "To David, Love Mom." The disposition value is effectively $0 (parts/metal recovery only, perhaps $30-50 for the gold nib). + +**Common Mistake:** +Rigidly enforcing the "final sale" policy. While legally defensible if the disclosure was adequate, it's operationally risky: a $620 dispute that reaches a chargeback is expensive to fight, and if the disclosure is found inadequate, the chargeback goes to the cardholder. + +The second mistake: accepting the return at full refund as if the engraving doesn't matter. This creates a precedent where customers order personalised items, use them for the event/gift, and return them knowing the "final sale" policy won't be enforced. + +**Expert Approach:** +1. Evaluate the disclosure adequacy. Was "Personalised items are final sale" displayed at the engraving step in checkout, or only in the FAQ? If only in the FAQ, the company has a weak position. If displayed at the engraving selection step, the position is stronger. +2. Regardless of disclosure, recognise that the gift recipient (David) is not the purchaser and may not have seen any disclosure. His experience is: "I received a gift I can't use, and the store won't help me." This is a customer experience problem even if the policy is sound. +3. Recommended resolution: offer store credit at 50% of purchase price ($310) as a one-time courtesy. The rationale: the personalisation destroyed the product's resale value, so the full refund cost ($620) is the total cost to the company — there's no recovery. Offering 50% acknowledges both the customer's situation and the company's loss. +4. If the gift-giver (Mom) contacts you: she has the stronger case since she was the purchaser. If the disclosure was inadequate, offer 75-100% store credit. If adequate, offer 50% and explain. +5. Systemic fix: add the "final sale" notice directly on the engraving/personalisation UI step, with a checkbox confirmation: "I understand that personalised items cannot be returned or exchanged." This eliminates future ambiguity. +6. Disposition: the engraved pen has near-zero resale value. If a charity pen collection exists, donate for the tax deduction at fair market value (which may be claimed at a discounted-but-nonzero amount). Otherwise, hold for precious metals recovery if the pen has gold components. + +**Key Indicators:** +- Personalised/custom items should have the "final sale" notice at the point of customisation selection, not just in the FAQ or general return policy +- Gift recipients of personalised items present a unique challenge — they didn't agree to the policy +- The cost of a personalised item return is 100% of the purchase price (zero recovery), making even partial credit a significant expense +- Track personalised item return requests — if they exceed 3% of personalised orders, the disclosure needs improvement + +--- + +### Edge Case 14: Return Attempt on Product Purchased Through Reseller / Unauthorised Channel + +**Situation:** +A customer walks into your brand retail store with a pair of your company's premium running shoes (retail $189.99) claiming they have a stitching defect after 2 weeks of use. The shoes show the defect as described — a seam separation on the toe box. However, when you scan the barcode, there's no matching transaction in your POS system. The customer says they purchased them from an Amazon third-party seller for $139.99. The shoes appear genuine (not counterfeit). The customer argues: "These are YOUR shoes. You should stand behind your product regardless of where I bought them." + +**Why It's Tricky:** +The customer has a point — the product bears your brand, and a stitching defect is a manufacturing quality issue regardless of the retail channel. However, the customer is not your customer — they purchased from an unauthorised reseller. Your return policy covers products purchased from your direct channels (brand stores, website, authorised retailers). Products purchased through unauthorised third-party sellers may be: genuine product diverted from authorised distribution (grey market), returned products resold by a liquidator, or counterfeit (though these appear genuine). + +If you accept the return, you're providing warranty-like service for products you didn't sell, and potentially for products that a liquidator already recovered a refund on before reselling. If you refuse, a customer with a defective product carrying your brand walks away angry and tells social media that your brand doesn't stand behind its products. + +**Common Mistake:** +Accepting a full return and refund at retail ($189.99) for a product the customer paid $139.99 for through a different channel. This creates a $50 arbitrage and invites a pattern: buy from cheap reseller, return at brand store for full retail. + +**Expert Approach:** +1. Verify the product is genuine. If your shoes have internal authenticity markers (UV-visible lot codes, specific insole markings, QR codes), check them. If genuine, proceed to step 2. If suspected counterfeit, follow the counterfeit protocol (Edge Case 10). +2. This is a warranty issue, not a return. The customer is not returning a purchase from your store — they're claiming a manufacturing defect on your branded product. Handle it as a warranty claim, not a return. +3. Offer a warranty remedy: exchange the defective pair for a new pair of the same model/size from your store inventory. This costs you the wholesale cost (~$85-95) but resolves the customer's issue, protects the brand reputation, and avoids the price arbitrage of a cash refund. +4. Do NOT offer a cash refund. The customer did not purchase from you. A cash or store credit refund at your retail price creates arbitrage. If the customer insists on a refund, direct them to the seller they purchased from (Amazon third-party seller). +5. Document the defect for quality purposes. A stitching defect is a manufacturing quality data point regardless of which channel the shoe was sold through. Log the defect against the SKU and lot number. +6. Consider the long-term: if your brand's products routinely show up in your stores via unauthorised-channel customers with defects, this indicates a distribution control problem. Work with your authorised retailer programme to identify and address grey market diversion. + +**Key Indicators:** +- Products purchased through unauthorised channels should be handled as warranty claims (exchange/repair), not returns (refund) +- Never offer a cash refund for products not purchased through your direct or authorised channels — this creates a price arbitrage vector +- Stitching defects, material failures, and construction issues on genuine product are legitimate warranty claims regardless of purchase channel +- Track the volume of unauthorised-channel warranty claims — high volume indicates distribution leakage + +--- + +### Edge Case 15: Return of Subscription Box Contents + +**Situation:** +A customer subscribed to your premium coffee subscription box ($59.99/month) and received their March delivery containing 3 bags of single-origin coffee (Guatemala, Ethiopia, Sumatra). They want to return the Guatemala and Sumatra bags (2 of 3) because "I only liked the Ethiopian." The bags are sealed and unopened. The customer wants a partial refund of $39.99 (2/3 of the subscription price). Your subscription terms state: "Subscription box contents are curated selections and cannot be returned for partial refund. You may cancel your subscription at any time." + +**Why It's Tricky:** +The subscription model is fundamentally different from à la carte retail. The customer didn't choose these specific coffees — the subscription curated them. The $59.99 price reflects the curated bundle value, not 3 × $19.99 for individual bags. If you allow partial returns on subscription boxes, every subscriber will return the items they don't like, and the subscription model collapses (you'd be selling only the popular items at a discount). + +But the customer's request is understandable. They're not asking for something unreasonable — they received products they don't want and they're sealed. From their perspective, it's no different from returning an unwanted product. + +**Common Mistake:** +Allowing the partial return. This sets a precedent that undermines the entire subscription model. If 50% of subscribers return 1-2 items per box, the margin model breaks — subscription boxes are priced with the assumption that the subscriber keeps the full curation. + +**Expert Approach:** +1. Deny the partial return per subscription terms. But frame it as a positive: "Our subscription boxes are curated as a complete experience, and we can't process partial returns. However, we want to make sure you're enjoying every box." +2. Offer alternatives: (a) "We'd love to know your taste preferences so we can adjust future boxes. Would you prefer lighter, fruitier coffees like the Ethiopian? We can note your preference for the next box." (b) "If you'd like to swap the Guatemala and Sumatra bags, we can offer a one-time exchange for two bags from our Ethiopian selection or other light-roast options." (c) "If the subscription isn't meeting your expectations, we can offer a 15% discount on your next box or switch you to a different subscription tier that focuses on the flavour profiles you prefer." +3. If the customer insists or threatens to cancel: evaluate the customer's subscription tenure. A customer who has been subscribed for 12+ months at $59.99/month ($720+/year) is worth a one-time $39.99 accommodation. A new subscriber on their first box is not — their expected LTV hasn't been established. For long-tenure subscribers, offer a $20 credit toward their next box as a compromise. +4. Never refund partial subscription box contents as a standard practice. Every exception must be documented as a one-time accommodation with the business justification. +5. Systemic improvement: add a taste preference survey to the subscription onboarding. Curating to known preferences reduces "didn't like it" complaints by 30-50%. + +**Key Indicators:** +- Subscription box returns must be handled differently from standard product returns — the subscription model depends on the full-curation assumption +- Partial refunds on subscription contents destroy unit economics — prevent this from becoming a pattern +- Customer preference data is the #1 lever for reducing subscription dissatisfaction +- A customer who threatens to cancel a long-running subscription over one box is worth accommodating; a new subscriber on their first box is not + +--- + +### Edge Case 16: Bulk B2B Return Where Customer Demands Full Retail Refund on Wholesale Purchase + +**Situation:** +A corporate procurement customer (TechStart Inc.) purchased 50 units of a wireless keyboard-mouse combo ($89.99 retail, $52.00 wholesale/B2B price) for their new office. The total B2B order was $2,600.00. Three weeks after delivery, TechStart decides to switch to a different vendor for ergonomic equipment and wants to return all 50 units. All units are sealed, unopened, in original packaging. The B2B sales rep approved the return. However, when the return is processed, the TechStart procurement manager argues: "These are worth $89.99 each on your website — we should get a credit of $4,499.50, not $2,600." + +**Why It's Tricky:** +The customer paid the B2B wholesale price and is entitled to a refund of what they paid ($2,600), not the retail value ($4,499.50). But B2B customers sometimes have procurement teams who don't understand or don't accept that their refund matches their purchase price, not the retail price. They see the retail price on the website and feel short-changed. + +Additionally, 50 sealed units returned simultaneously have high restock value but create a volume spike. If these exact keyboard-mouse combos are in your retail inventory at $89.99, the 50 returned units restore significant inventory — good for your stock position. + +**Common Mistake:** +Issuing credit at retail price ($4,499.50) to "keep the business relationship." This creates a $1,899.50 loss and a precedent that B2B returns are refunded at retail. The reverse mistake: making the return process so adversarial that TechStart never orders again — a B2B account that buys 50 units at a time is worth the relationship investment. + +**Expert Approach:** +1. Refund at the actual B2B purchase price: $2,600.00. This is non-negotiable — the refund matches the amount charged. Reference the B2B purchase order and invoice showing the $52.00/unit price. +2. If the procurement manager pushes back: the B2B sales rep should handle the communication (not the returns team). The sales rep explains: "Your refund matches your purchase price on PO #[X]. The retail price on our website is for individual consumer purchases, which includes different overhead and margin. Your account benefits from our volume pricing, and the refund reflects that same pricing." +3. Process the return smoothly and quickly: 50 sealed units should be express-processed (no individual inspection needed — batch scan, Grade A, restock). The faster TechStart receives their credit, the less friction around the amount. +4. Restock all 50 units as new (sealed, Grade A). Inventory value recovered at wholesale ($2,600). +5. B2B relationship preservation: the sales rep should follow up with TechStart after the return is processed. "We've processed your return. When you're ready to select your new ergonomic equipment, we'd be happy to quote — we carry several lines including [alternatives]." Maintain the relationship for the next order. +6. Document the return in the B2B account file. If TechStart shows a pattern of bulk ordering and returning, adjust the account terms (restocking fee on B2B returns, or approval-required ordering). + +**Key Indicators:** +- B2B returns are always refunded at the B2B purchase price, never at retail +- The sales rep (not the returns team) should manage the pricing conversation for B2B accounts +- 50 sealed units is a high-value restock opportunity — prioritise quick processing +- B2B accounts that bulk-order and bulk-return may need modified terms (restocking fees, order approval) +- The relationship value of a B2B account that orders in 50-unit quantities is significant — handle the return professionally + +--- + +### Edge Case 17: Return of a Product that Was Used as Replacement During Warranty Repair + +**Situation:** +A customer brought in a malfunctioning coffee machine ($449.99) for warranty repair 6 weeks ago. As a courtesy, your store loaned them a comparable refurbished unit (same model, valued at $340 in refurbished condition) to use while theirs was being repaired. The original machine has now been repaired and is ready for pickup. The customer picks up their repaired machine but then asks to "return" the loaner unit — they want to keep using it and buy it at a discount rather than return it. When pressed, they say "actually, I want to return both — the repaired one doesn't feel the same, and I've gotten used to the loaner." + +**Why It's Tricky:** +Multiple issues converge: (1) The loaner is not the customer's property — it's company inventory loaned for temporary use. It cannot be "returned" because it was never sold. (2) The customer's original machine was repaired under warranty, not replaced. A warranty repair doesn't restart the return window — the product is the same unit, now fixed. (3) The customer wants to return a repaired product claiming it "doesn't feel the same" — a subjective complaint after a warranty repair. + +**Common Mistake:** +Allowing the customer to "return" the repaired machine as if it were a new purchase. The original purchase was 6+ weeks ago, outside any return window. The warranty repair doesn't create a new return right. The second mistake: selling the loaner to the customer at a steep discount — loaner units are company assets managed through a separate inventory pool. + +**Expert Approach:** +1. Recover the loaner immediately. It is company property, not a product the customer purchased. Thank the customer for using it and collect it back. There is no "return" process for a loaner — it's an asset recovery. +2. Address the "doesn't feel the same" complaint on the repaired machine. Ask specific questions: "What feels different? Is there a specific function that's not working correctly?" If the repair introduced a new issue (common with appliance repairs), document it and offer to send it back for correction. If the customer simply prefers the loaner (which they've been using for 6 weeks and is now "theirs" psychologically), acknowledge the adjustment period. +3. The repaired machine cannot be returned under the standard return policy — the purchase date is 6+ weeks ago. However, if the repair is genuinely unsatisfactory, the customer has a warranty claim (the warranty covers the repair work). Offer: "If the repair didn't fully resolve the original issue, we'll send it back for warranty service at no charge." +4. If the customer wants to purchase a loaner-equivalent unit: offer to sell them a certified refurbished unit from your refurbished inventory at the standard refurbished price. Do not sell them the specific loaner they used (hygiene, wear from their use, and it's an asset, not retail inventory). +5. If the customer escalates or threatens: the maximum accommodation is a store credit toward a new machine, applied against the original purchase price minus the value of the use they received (6+ weeks of coffee machine use). This is a judgment call for a manager. + +**Key Indicators:** +- Loaner units are company assets, not retail inventory — they follow asset recovery processes, not return processes +- Warranty repairs do not create new return windows on the original purchase +- The psychological "endowment effect" of using a loaner for 6 weeks makes customers reluctant to give it back — this is predictable and should be managed with clear loaner terms at the time of issuance +- Clear loaner agreements at checkout prevent this edge case: "This is a temporary loaner provided during your warranty repair. It remains company property and must be returned when your repair is complete." + +--- + +### Edge Case 18: Return Flood After Viral Negative Product Review + +**Situation:** +A popular tech reviewer (3.2M YouTube subscribers) posts a video titled "DO NOT BUY — [Your Product] is a FIRE HAZARD" about your brand's portable charger ($49.99). The video shows the reviewer stress-testing the charger and it overheating during a fast-charge scenario that exceeds the product's rated capacity. The video has 4.5M views in 48 hours. You've sold 12,000 units of this charger in the past 90 days. In the 48 hours since the video, you've received 340 return requests (compared to a normal rate of ~15 returns/week for this SKU). The product is NOT subject to a CPSC recall. Your engineering team has reviewed the video and confirms the reviewer used the charger outside its specifications (attempted to fast-charge a laptop with a 100W charger rated for 65W max). The product is safe when used as designed. + +**Why It's Tricky:** +The return requests are driven by fear, not defects. The product works as designed — the reviewer used it incorrectly. But you can't tell 340 customers "you're wrong, a YouTuber misused the product." These customers are genuinely afraid their charger will catch fire. Denying the returns creates social media backlash. Accepting all 340 returns (and potentially thousands more as the video continues to circulate) costs $17,000+ in refunds with minimal recovery. + +**Common Mistake:** +Blanket denial: "The product is safe, we're not accepting returns outside the standard window." This triggers a social media firestorm and potentially regulatory scrutiny (even unfounded — CPSC may investigate based on volume of complaints). The second mistake: blanket acceptance at full refund without any counter-narrative, which validates the reviewer's incorrect claim and could cascade to thousands more returns. + +**Expert Approach:** +1. Accept all 340 return requests immediately, without friction. Process standard returns for within-window customers. For outside-window customers, accept as goodwill exception. Do not fight this wave — the cost of 340 returns ($17,000) is trivial compared to the brand damage of denying returns on a "safety concern." +2. Simultaneously, the PR/communications team must issue a public response within 24 hours. Acknowledge the concern, explain the product's safety specifications, clarify the reviewer's test exceeded rated capacity (without attacking the reviewer personally), and share third-party safety certification data (UL listing, etc.). +3. Contact the reviewer directly. Offer to send engineering documentation showing the product's safety at rated capacity. Many reviewers will post a correction or follow-up if provided credible technical data. Do not threaten legal action — this backfires. +4. Monitor the return volume daily. Create a dedicated return code for "viral-concern returns" to track separately from normal returns. If the volume escalates beyond 1,000 units (8%+ return rate), escalate to VP-level for a formal response plan. +5. Disposition for returned chargers: all within-window Grade A returns restock as new. Returned chargers are safe — the viral concern is about misuse, not a product defect. Do NOT pull the product from sale unless engineering identifies an actual defect. +6. Proactive defence: update the product listing with prominent max-wattage warnings. Update the product packaging and manual with clearer limitations. This protects against future claims and shows responsiveness. +7. Track the return curve. Viral-concern returns typically peak 72-96 hours after the video and decay to baseline within 2-3 weeks. Most returns will process before the curve decays. + +**Key Indicators:** +- Viral negative reviews can generate 10-30x normal return volume within 48-72 hours +- The return cost ($17K on 340 units) is a rounding error compared to the brand/PR cost of mishandling the situation +- All returned units are fully functional and restockable — the loss is the processing cost, not the product value +- Counter-narrative timing is critical: respond within 24 hours with technical data, not PR language +- Track "viral-concern return" codes separately — this data informs the risk assessment of social media product coverage + +--- + +### Edge Case 19: Customer Returns an Item They Didn't Purchase (Shipping Error by Another Retailer) + +**Situation:** +A customer contacts your returns team stating they want to return a Le Creuset Dutch Oven ($380.00) that "isn't what they ordered." They provide their order number, which shows they ordered a KitchenAid Stand Mixer ($429.99). When the return arrives, inspection confirms it is indeed a Le Creuset Dutch Oven — a product you carry and sell, but not the product this customer ordered. The serial/lot number on the Dutch Oven matches your inventory records as a unit that was in your warehouse. Investigation reveals: a fulfillment packing error sent this customer's KitchenAid mixer to a different customer, and this customer received another customer's Le Creuset order. + +**Why It's Tricky:** +This is a cross-shipment fulfillment error. Two customers are affected: Customer A received the wrong product (the Le Creuset instead of their KitchenAid), and Customer B received Customer A's KitchenAid instead of their Le Creuset. Both customers need their correct products. Both may have already initiated returns or complaints. The fulfillment centre sent two correct products to two wrong addresses. + +The financial reconciliation is complex: Customer A paid $429.99 for a KitchenAid and received a $380 Le Creuset. Customer B paid $380 for a Le Creuset and received a $429.99 KitchenAid. Neither customer should be penalised — this is entirely the company's error. + +**Common Mistake:** +Processing Customer A's return as a standard return and shipping them a replacement KitchenAid — but not connecting the dots to realise Customer B also received the wrong product. The second customer may not have complained yet (they might have accepted the KitchenAid thinking it was correct, or they might be planning to return it separately). Handling these as two independent returns instead of one linked cross-shipment doubles the logistical cost. + +**Expert Approach:** +1. Identify the cross-shipment immediately. When Customer A's return arrives as a Le Creuset instead of a KitchenAid, fulfillment should trace the packing records to find where the KitchenAid went. This identifies Customer B. +2. Contact Customer B proactively — don't wait for them to realise the error. "We've discovered a packing error and you may have received a KitchenAid Stand Mixer instead of the Le Creuset Dutch Oven you ordered. We apologise for the mix-up and would like to ship your correct Le Creuset immediately." +3. For Customer A: ship the correct KitchenAid via expedited shipping (2-day minimum) with a prepaid return label for the Le Creuset they received. Include a $25-50 store credit for the inconvenience. Do not wait for the Le Creuset to be returned before shipping the KitchenAid — the customer has already waited. +4. For Customer B: same approach — ship the correct Le Creuset via expedited shipping with a prepaid return label for the KitchenAid. Include a $25-50 store credit. +5. Inventory reconciliation: once both wrong items are returned, they go back to their respective inventory positions. Net inventory impact should be zero once both returns are processed. Track both under a single cross-shipment incident number. +6. Root cause: investigate the fulfillment error. Cross-shipments typically happen when two orders are being packed simultaneously at adjacent stations and the products get physically swapped. If this is a recurring issue, the packing process needs a scan-verify step where the packed product's barcode is scanned against the order before sealing. +7. Financial: the expedited re-shipping cost ($15-25 per shipment × 2 = $30-50) plus store credits ($50-100 total) plus return shipping on both wrong items ($15-25 × 2 = $30-50) totals $110-200 in error resolution cost. The fulfillment error should be charged to the fulfillment operation's error budget, not the returns budget. + +**Key Indicators:** +- When a return arrives with a different product than expected, always check if it's a cross-shipment before processing as a standard return +- Cross-shipments affect two customers — proactively contact both, even if only one has complained +- Ship correct items before collecting wrong items — the customer should not wait for the return logistics to resolve +- Cross-shipment resolution costs $110-200 per incident — this makes the business case for scan-verify packing processes +- Track cross-shipment rates: target < 0.05% of orders. If rate exceeds 0.1%, the packing process has a systemic gap + +**Documentation Required:** +- Cross-shipment incident record linking both customer orders +- Packing slip and warehouse records showing the error point +- Communication records with both customers +- Shipping records for both replacement shipments +- Return tracking for both wrong-item returns +- Root cause analysis note for fulfillment operations + +--- + +### Edge Case 20: Return of a Product That Requires Data Destruction Certification + +**Situation:** +A corporate customer returns 25 laptops (Dell Latitude 5540, $1,199 each, $29,975 total) that were originally purchased for a project team that has been disbanded. The laptops were used for 10 months and contain corporate data — emails, documents, proprietary software, and potentially regulated data (the customer works in healthcare and some laptops may have had access to PHI — Protected Health Information). The customer's IT department performed a standard Windows reset ("Reset this PC") before returning, but they're asking: "Can you certify that these drives have been wiped to HIPAA-compliant standards? Our compliance team requires a certificate of data destruction." + +**Why It's Tricky:** +A standard Windows "Reset this PC" does not meet NIST 800-88 data sanitisation standards. The data is technically recoverable with forensic tools. For a healthcare company with potential PHI on the devices, HIPAA requires that data destruction be documented and verifiable. If you restock or liquidate these laptops without proper data destruction and patient data is later recovered from a resold unit, the liability exposure is enormous — for both the healthcare company and for you as the entity that handled the devices. + +Your standard returns process doesn't include NIST 800-88 data sanitisation. You inspect, grade, and disposition — but data destruction certification is a service, not a standard returns step. + +**Common Mistake:** +Accepting the return and processing it as standard — wiping the drives with your normal reset process and restocking. If the normal reset doesn't meet NIST 800-88, and the customer later requires a certificate you can't provide, you have a compliance gap. The second mistake: telling the customer "data destruction is your responsibility" and refusing to help — they're a $30K customer and this is a reasonable request. + +**Expert Approach:** +1. Accept the return of all 25 laptops. Process the RMA normally for grading and refund calculation. +2. For data destruction: this is a service, not a standard return step. If you have an in-house NIST 800-88 compliant data wipe capability (many return centres do for electronics), offer it as a service. Use a certified tool (Blancco, KillDisk, DBAN) that produces a per-device certificate documenting: device serial number, date, sanitisation method used, and pass/fail result. +3. If you don't have in-house capability: partner with a certified ITAD (IT Asset Disposition) provider. They will perform the wipe, issue certificates, and handle any drives that fail the wipe (drives that fail must be physically destroyed — degaussed or shredded). +4. Charge for the service. NIST 800-88 data sanitisation is $5-15 per device in-house, $15-30 per device through an ITAD partner. For 25 laptops: $125-750 total. Offer this as an add-on to the return. Most corporate customers will pay — their alternative is to hire an ITAD provider independently, which costs more. +5. Provide the individual certificates to the customer's compliance team. Each certificate should reference: NIST SP 800-88 Rev 1, the sanitisation method (Clear, Purge, or Destroy), the device serial number, and the date. +6. After data destruction is certified: proceed with normal disposition. 10-month-old Dell Latitude laptops with certified data wipes sell well in the refurbished market at $500-700 each. +7. Systemic: for all corporate/enterprise laptop and device returns, add a data destruction service option at RMA initiation: "Does this device contain corporate or regulated data? We offer certified NIST 800-88 data destruction for $X per device." + +**Key Indicators:** +- Standard "Reset this PC" and factory resets do NOT meet NIST 800-88 sanitisation standards — data is recoverable with forensic tools +- Healthcare (HIPAA), financial (GLBA), government (NIST), and education (FERPA) customers have regulatory data destruction requirements +- Data destruction certification is a value-add service that corporate customers will pay for — it's a revenue opportunity, not just a cost +- Never restock or liquidate enterprise devices without verifying data has been properly sanitised — the liability exposure from a data breach on a resold device is unlimited +- Keep copies of all data destruction certificates for your own compliance records — if a device you resold is later found to contain recoverable data, the certificate is your defence diff --git a/web-app/public/skills/reverse-engineer/SKILL.md b/web-app/public/skills/reverse-engineer/SKILL.md index 8238c7ac..333ee99e 100644 --- a/web-app/public/skills/reverse-engineer/SKILL.md +++ b/web-app/public/skills/reverse-engineer/SKILL.md @@ -1,6 +1,7 @@ --- name: reverse-engineer -description: "Expert reverse engineer specializing in binary analysis," +description: | + Expert reverse engineer specializing in binary analysis, disassembly, decompilation, and software analysis. Masters IDA Pro, Ghidra, radare2, x64dbg, and modern RE toolchains. Handles executable analysis, library inspection, protocol extraction, and vulnerability research. Use diff --git a/web-app/public/skills/risk-manager/SKILL.md b/web-app/public/skills/risk-manager/SKILL.md index e860fe43..7ac39dc7 100644 --- a/web-app/public/skills/risk-manager/SKILL.md +++ b/web-app/public/skills/risk-manager/SKILL.md @@ -1,6 +1,7 @@ --- name: risk-manager -description: "Monitor portfolio risk, R-multiples, and position limits. Creates" +description: | + Monitor portfolio risk, R-multiples, and position limits. Creates hedging strategies, calculates expectancy, and implements stop-losses. Use PROACTIVELY for risk assessment, trade tracking, or portfolio protection. metadata: diff --git a/web-app/public/skills/ruby-pro/SKILL.md b/web-app/public/skills/ruby-pro/SKILL.md index d8296a73..bbc6b20b 100644 --- a/web-app/public/skills/ruby-pro/SKILL.md +++ b/web-app/public/skills/ruby-pro/SKILL.md @@ -1,6 +1,7 @@ --- name: ruby-pro -description: "Write idiomatic Ruby code with metaprogramming, Rails patterns, and" +description: | + Write idiomatic Ruby code with metaprogramming, Rails patterns, and performance optimization. Specializes in Ruby on Rails, gem development, and testing frameworks. Use PROACTIVELY for Ruby refactoring, optimization, or complex Ruby features. diff --git a/web-app/public/skills/rust-pro/SKILL.md b/web-app/public/skills/rust-pro/SKILL.md index 56b57f23..c6fa0907 100644 --- a/web-app/public/skills/rust-pro/SKILL.md +++ b/web-app/public/skills/rust-pro/SKILL.md @@ -1,6 +1,7 @@ --- name: rust-pro -description: "Master Rust 1.75+ with modern async patterns, advanced type system" +description: | + Master Rust 1.75+ with modern async patterns, advanced type system features, and production-ready systems programming. Expert in the latest Rust ecosystem including Tokio, axum, and cutting-edge crates. Use PROACTIVELY for Rust development, performance optimization, or systems programming. diff --git a/web-app/public/skills/sales-automator/SKILL.md b/web-app/public/skills/sales-automator/SKILL.md index 2978913c..d03be643 100644 --- a/web-app/public/skills/sales-automator/SKILL.md +++ b/web-app/public/skills/sales-automator/SKILL.md @@ -1,6 +1,7 @@ --- name: sales-automator -description: "Draft cold emails, follow-ups, and proposal templates. Creates" +description: | + Draft cold emails, follow-ups, and proposal templates. Creates pricing pages, case studies, and sales scripts. Use PROACTIVELY for sales outreach or lead nurturing. metadata: diff --git a/web-app/public/skills/scala-pro/SKILL.md b/web-app/public/skills/scala-pro/SKILL.md index 6845992a..4f0b4fb7 100644 --- a/web-app/public/skills/scala-pro/SKILL.md +++ b/web-app/public/skills/scala-pro/SKILL.md @@ -1,6 +1,7 @@ --- name: scala-pro -description: "Master enterprise-grade Scala development with functional" +description: | + Master enterprise-grade Scala development with functional programming, distributed systems, and big data processing. Expert in Apache Pekko, Akka, Spark, ZIO/Cats Effect, and reactive architectures. Use PROACTIVELY for Scala system design, performance optimization, or enterprise diff --git a/web-app/public/skills/schema-markup/SKILL.md b/web-app/public/skills/schema-markup/SKILL.md index 98474969..45da25cd 100644 --- a/web-app/public/skills/schema-markup/SKILL.md +++ b/web-app/public/skills/schema-markup/SKILL.md @@ -1,6 +1,6 @@ --- name: schema-markup -description: ">" +description: > Design, validate, and optimize schema.org structured data for eligibility, correctness, and measurable SEO impact. Use when the user wants to add, fix, audit, or scale schema markup (JSON-LD) for rich results. This skill evaluates diff --git a/web-app/public/skills/security-auditor/SKILL.md b/web-app/public/skills/security-auditor/SKILL.md index 8704c428..f4a6b0da 100644 --- a/web-app/public/skills/security-auditor/SKILL.md +++ b/web-app/public/skills/security-auditor/SKILL.md @@ -1,6 +1,7 @@ --- name: security-auditor -description: "Expert security auditor specializing in DevSecOps, comprehensive" +description: | + Expert security auditor specializing in DevSecOps, comprehensive cybersecurity, and compliance frameworks. Masters vulnerability assessment, threat modeling, secure authentication (OAuth2/OIDC), OWASP standards, cloud security, and security automation. Handles DevSecOps integration, compliance diff --git a/web-app/public/skills/security-scanning-security-sast/SKILL.md b/web-app/public/skills/security-scanning-security-sast/SKILL.md index 8f15568d..84aae929 100644 --- a/web-app/public/skills/security-scanning-security-sast/SKILL.md +++ b/web-app/public/skills/security-scanning-security-sast/SKILL.md @@ -1,6 +1,7 @@ --- name: security-scanning-security-sast -description: "Static Application Security Testing (SAST) for code vulnerability" +description: | + Static Application Security Testing (SAST) for code vulnerability analysis across multiple languages and frameworks metadata: globs: "**/*.py, **/*.js, **/*.ts, **/*.java, **/*.rb, **/*.go, **/*.rs, **/*.php" diff --git a/web-app/public/skills/seo-audit/SKILL.md b/web-app/public/skills/seo-audit/SKILL.md index 8c8b91d0..de3ab23a 100644 --- a/web-app/public/skills/seo-audit/SKILL.md +++ b/web-app/public/skills/seo-audit/SKILL.md @@ -1,6 +1,6 @@ --- name: seo-audit -description: ">" +description: > Diagnose and audit SEO issues affecting crawlability, indexation, rankings, and organic performance. Use when the user asks for an SEO audit, technical SEO review, ranking diagnosis, on-page SEO review, meta tag audit, or SEO health check. diff --git a/web-app/public/skills/seo-authority-builder/SKILL.md b/web-app/public/skills/seo-authority-builder/SKILL.md index 78322085..2288399b 100644 --- a/web-app/public/skills/seo-authority-builder/SKILL.md +++ b/web-app/public/skills/seo-authority-builder/SKILL.md @@ -1,6 +1,7 @@ --- name: seo-authority-builder -description: "Analyzes content for E-E-A-T signals and suggests improvements to" +description: | + Analyzes content for E-E-A-T signals and suggests improvements to build authority and trust. Identifies missing credibility elements. Use PROACTIVELY for YMYL topics. metadata: diff --git a/web-app/public/skills/seo-cannibalization-detector/SKILL.md b/web-app/public/skills/seo-cannibalization-detector/SKILL.md index 30f7f19b..cfc2c16e 100644 --- a/web-app/public/skills/seo-cannibalization-detector/SKILL.md +++ b/web-app/public/skills/seo-cannibalization-detector/SKILL.md @@ -1,6 +1,7 @@ --- name: seo-cannibalization-detector -description: "Analyzes multiple provided pages to identify keyword overlap and" +description: | + Analyzes multiple provided pages to identify keyword overlap and potential cannibalization issues. Suggests differentiation strategies. Use PROACTIVELY when reviewing similar content. metadata: diff --git a/web-app/public/skills/seo-content-auditor/SKILL.md b/web-app/public/skills/seo-content-auditor/SKILL.md index 8e747996..0f8a212f 100644 --- a/web-app/public/skills/seo-content-auditor/SKILL.md +++ b/web-app/public/skills/seo-content-auditor/SKILL.md @@ -1,6 +1,7 @@ --- name: seo-content-auditor -description: "Analyzes provided content for quality, E-E-A-T signals, and SEO" +description: | + Analyzes provided content for quality, E-E-A-T signals, and SEO best practices. Scores content and provides improvement recommendations based on established guidelines. Use PROACTIVELY for content review. metadata: diff --git a/web-app/public/skills/seo-content-planner/SKILL.md b/web-app/public/skills/seo-content-planner/SKILL.md index 66c7797f..cd18347d 100644 --- a/web-app/public/skills/seo-content-planner/SKILL.md +++ b/web-app/public/skills/seo-content-planner/SKILL.md @@ -1,6 +1,7 @@ --- name: seo-content-planner -description: "Creates comprehensive content outlines and topic clusters for SEO." +description: | + Creates comprehensive content outlines and topic clusters for SEO. Plans content calendars and identifies topic gaps. Use PROACTIVELY for content strategy and planning. metadata: diff --git a/web-app/public/skills/seo-content-refresher/SKILL.md b/web-app/public/skills/seo-content-refresher/SKILL.md index 79ca9440..de5672ef 100644 --- a/web-app/public/skills/seo-content-refresher/SKILL.md +++ b/web-app/public/skills/seo-content-refresher/SKILL.md @@ -1,6 +1,7 @@ --- name: seo-content-refresher -description: "Identifies outdated elements in provided content and suggests" +description: | + Identifies outdated elements in provided content and suggests updates to maintain freshness. Finds statistics, dates, and examples that need updating. Use PROACTIVELY for older content. metadata: diff --git a/web-app/public/skills/seo-content-writer/SKILL.md b/web-app/public/skills/seo-content-writer/SKILL.md index bc80aa22..04146556 100644 --- a/web-app/public/skills/seo-content-writer/SKILL.md +++ b/web-app/public/skills/seo-content-writer/SKILL.md @@ -1,6 +1,7 @@ --- name: seo-content-writer -description: "Writes SEO-optimized content based on provided keywords and topic" +description: | + Writes SEO-optimized content based on provided keywords and topic briefs. Creates engaging, comprehensive content following best practices. Use PROACTIVELY for content creation tasks. metadata: diff --git a/web-app/public/skills/seo-fundamentals/SKILL.md b/web-app/public/skills/seo-fundamentals/SKILL.md index 71212a55..7d12e82b 100644 --- a/web-app/public/skills/seo-fundamentals/SKILL.md +++ b/web-app/public/skills/seo-fundamentals/SKILL.md @@ -1,6 +1,6 @@ --- name: seo-fundamentals -description: ">" +description: > Core principles of SEO including E-E-A-T, Core Web Vitals, technical foundations, content quality, and how modern search engines evaluate pages. This skill explains *why* SEO works, not how to execute specific optimizations. diff --git a/web-app/public/skills/seo-keyword-strategist/SKILL.md b/web-app/public/skills/seo-keyword-strategist/SKILL.md index f0c64c9e..7d75baba 100644 --- a/web-app/public/skills/seo-keyword-strategist/SKILL.md +++ b/web-app/public/skills/seo-keyword-strategist/SKILL.md @@ -1,6 +1,7 @@ --- name: seo-keyword-strategist -description: "Analyzes keyword usage in provided content, calculates density," +description: | + Analyzes keyword usage in provided content, calculates density, suggests semantic variations and LSI keywords based on the topic. Prevents over-optimization. Use PROACTIVELY for content optimization. metadata: diff --git a/web-app/public/skills/seo-meta-optimizer/SKILL.md b/web-app/public/skills/seo-meta-optimizer/SKILL.md index d1cf7499..c749b281 100644 --- a/web-app/public/skills/seo-meta-optimizer/SKILL.md +++ b/web-app/public/skills/seo-meta-optimizer/SKILL.md @@ -1,6 +1,7 @@ --- name: seo-meta-optimizer -description: "Creates optimized meta titles, descriptions, and URL suggestions" +description: | + Creates optimized meta titles, descriptions, and URL suggestions based on character limits and best practices. Generates compelling, keyword-rich metadata. Use PROACTIVELY for new content. metadata: diff --git a/web-app/public/skills/seo-snippet-hunter/SKILL.md b/web-app/public/skills/seo-snippet-hunter/SKILL.md index eab15c08..be67041e 100644 --- a/web-app/public/skills/seo-snippet-hunter/SKILL.md +++ b/web-app/public/skills/seo-snippet-hunter/SKILL.md @@ -1,6 +1,7 @@ --- name: seo-snippet-hunter -description: "Formats content to be eligible for featured snippets and SERP" +description: | + Formats content to be eligible for featured snippets and SERP features. Creates snippet-optimized content blocks based on best practices. Use PROACTIVELY for question-based content. metadata: diff --git a/web-app/public/skills/seo-structure-architect/SKILL.md b/web-app/public/skills/seo-structure-architect/SKILL.md index d9c0644b..7d28c670 100644 --- a/web-app/public/skills/seo-structure-architect/SKILL.md +++ b/web-app/public/skills/seo-structure-architect/SKILL.md @@ -1,6 +1,7 @@ --- name: seo-structure-architect -description: "Analyzes and optimizes content structure including header" +description: | + Analyzes and optimizes content structure including header hierarchy, suggests schema markup, and internal linking opportunities. Creates search-friendly content organization. Use PROACTIVELY for content structuring. metadata: diff --git a/web-app/public/skills/sql-pro/SKILL.md b/web-app/public/skills/sql-pro/SKILL.md index ddb5a988..99f4582b 100644 --- a/web-app/public/skills/sql-pro/SKILL.md +++ b/web-app/public/skills/sql-pro/SKILL.md @@ -1,6 +1,7 @@ --- name: sql-pro -description: "Master modern SQL with cloud-native databases, OLTP/OLAP" +description: | + Master modern SQL with cloud-native databases, OLTP/OLAP optimization, and advanced query techniques. Expert in performance tuning, data modeling, and hybrid analytical systems. Use PROACTIVELY for database optimization or complex analysis. diff --git a/web-app/public/skills/startup-analyst/SKILL.md b/web-app/public/skills/startup-analyst/SKILL.md index 9dd9fbe9..4d97afd3 100644 --- a/web-app/public/skills/startup-analyst/SKILL.md +++ b/web-app/public/skills/startup-analyst/SKILL.md @@ -1,6 +1,7 @@ --- name: startup-analyst -description: "Expert startup business analyst specializing in market sizing," +description: | + Expert startup business analyst specializing in market sizing, financial modeling, competitive analysis, and strategic planning for early-stage companies. Use PROACTIVELY when the user asks about market opportunity, TAM/SAM/SOM, financial projections, unit economics, competitive diff --git a/web-app/public/skills/startup-business-analyst-business-case/SKILL.md b/web-app/public/skills/startup-business-analyst-business-case/SKILL.md index 7e21641c..554aea60 100644 --- a/web-app/public/skills/startup-business-analyst-business-case/SKILL.md +++ b/web-app/public/skills/startup-business-analyst-business-case/SKILL.md @@ -1,6 +1,7 @@ --- name: startup-business-analyst-business-case -description: "Generate comprehensive investor-ready business case document with" +description: | + Generate comprehensive investor-ready business case document with market, solution, financials, and strategy allowed-tools: Read Write Edit Glob Grep Bash WebSearch WebFetch risk: unknown diff --git a/web-app/public/skills/startup-business-analyst-financial-projections/SKILL.md b/web-app/public/skills/startup-business-analyst-financial-projections/SKILL.md index 1e09b5db..f68ca0f2 100644 --- a/web-app/public/skills/startup-business-analyst-financial-projections/SKILL.md +++ b/web-app/public/skills/startup-business-analyst-financial-projections/SKILL.md @@ -1,6 +1,7 @@ --- name: startup-business-analyst-financial-projections -description: "Create detailed 3-5 year financial model with revenue, costs, cash" +description: | + Create detailed 3-5 year financial model with revenue, costs, cash flow, and scenarios allowed-tools: Read Write Edit Glob Grep Bash WebSearch WebFetch risk: unknown diff --git a/web-app/public/skills/startup-business-analyst-market-opportunity/SKILL.md b/web-app/public/skills/startup-business-analyst-market-opportunity/SKILL.md index 013d551a..8d73f982 100644 --- a/web-app/public/skills/startup-business-analyst-market-opportunity/SKILL.md +++ b/web-app/public/skills/startup-business-analyst-market-opportunity/SKILL.md @@ -1,6 +1,7 @@ --- name: startup-business-analyst-market-opportunity -description: "Generate comprehensive market opportunity analysis with TAM/SAM/SOM" +description: | + Generate comprehensive market opportunity analysis with TAM/SAM/SOM calculations allowed-tools: Read Write Edit Glob Grep Bash WebSearch WebFetch risk: unknown diff --git a/web-app/public/skills/startup-financial-modeling/SKILL.md b/web-app/public/skills/startup-financial-modeling/SKILL.md index 4921e7ea..a80405d5 100644 --- a/web-app/public/skills/startup-financial-modeling/SKILL.md +++ b/web-app/public/skills/startup-financial-modeling/SKILL.md @@ -1,6 +1,7 @@ --- name: startup-financial-modeling -description: "This skill should be used when the user asks to \\\"create financial" +description: | + This skill should be used when the user asks to \\\"create financial projections", "build a financial model", "forecast revenue", "calculate burn rate", "estimate runway", "model cash flow", or requests 3-5 year financial planning for a startup. diff --git a/web-app/public/skills/startup-metrics-framework/SKILL.md b/web-app/public/skills/startup-metrics-framework/SKILL.md index 7c8acdc3..cdd8c616 100644 --- a/web-app/public/skills/startup-metrics-framework/SKILL.md +++ b/web-app/public/skills/startup-metrics-framework/SKILL.md @@ -1,6 +1,7 @@ --- name: startup-metrics-framework -description: "This skill should be used when the user asks about \\\"key startup" +description: | + 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", "marketplace metrics", or requests guidance on tracking and optimizing business performance metrics. diff --git a/web-app/public/skills/tdd-orchestrator/SKILL.md b/web-app/public/skills/tdd-orchestrator/SKILL.md index 5878ac1c..700aa500 100644 --- a/web-app/public/skills/tdd-orchestrator/SKILL.md +++ b/web-app/public/skills/tdd-orchestrator/SKILL.md @@ -1,6 +1,7 @@ --- name: tdd-orchestrator -description: "Master TDD orchestrator specializing in red-green-refactor" +description: | + Master TDD orchestrator specializing in red-green-refactor discipline, multi-agent workflow coordination, and comprehensive test-driven development practices. Enforces TDD best practices across teams with AI-assisted testing and modern frameworks. Use PROACTIVELY for TDD diff --git a/web-app/public/skills/team-composition-analysis/SKILL.md b/web-app/public/skills/team-composition-analysis/SKILL.md index 9ce88e72..d1229a2c 100644 --- a/web-app/public/skills/team-composition-analysis/SKILL.md +++ b/web-app/public/skills/team-composition-analysis/SKILL.md @@ -1,6 +1,7 @@ --- name: team-composition-analysis -description: "This skill should be used when the user asks to \\\"plan team" +description: | + This skill should be used when the user asks to \\\"plan team structure", "determine hiring needs", "design org chart", "calculate compensation", "plan equity allocation", or requests organizational design and headcount planning for a startup. diff --git a/web-app/public/skills/temporal-python-pro/SKILL.md b/web-app/public/skills/temporal-python-pro/SKILL.md index 261fa049..eb233499 100644 --- a/web-app/public/skills/temporal-python-pro/SKILL.md +++ b/web-app/public/skills/temporal-python-pro/SKILL.md @@ -1,6 +1,7 @@ --- name: temporal-python-pro -description: "Master Temporal workflow orchestration with Python SDK. Implements" +description: | + Master Temporal workflow orchestration with Python SDK. Implements durable workflows, saga patterns, and distributed transactions. Covers async/await, testing strategies, and production deployment. Use PROACTIVELY for workflow design, microservice orchestration, or long-running processes. diff --git a/web-app/public/skills/terraform-specialist/SKILL.md b/web-app/public/skills/terraform-specialist/SKILL.md index 146087f7..8ec685f9 100644 --- a/web-app/public/skills/terraform-specialist/SKILL.md +++ b/web-app/public/skills/terraform-specialist/SKILL.md @@ -1,6 +1,7 @@ --- name: terraform-specialist -description: "Expert Terraform/OpenTofu specialist mastering advanced IaC" +description: | + Expert Terraform/OpenTofu specialist mastering advanced IaC automation, state management, and enterprise infrastructure patterns. Handles complex module design, multi-cloud deployments, GitOps workflows, policy as code, and CI/CD integration. Covers migration strategies, security best diff --git a/web-app/public/skills/test-automator/SKILL.md b/web-app/public/skills/test-automator/SKILL.md index e5fb2b0e..16f382b5 100644 --- a/web-app/public/skills/test-automator/SKILL.md +++ b/web-app/public/skills/test-automator/SKILL.md @@ -1,6 +1,7 @@ --- name: test-automator -description: "Master AI-powered test automation with modern frameworks," +description: | + Master AI-powered test automation with modern frameworks, self-healing tests, and comprehensive quality engineering. Build scalable testing strategies with advanced CI/CD integration. Use PROACTIVELY for testing automation or quality assurance. diff --git a/web-app/public/skills/track-management/SKILL.md b/web-app/public/skills/track-management/SKILL.md index c87f2591..7459de2f 100644 --- a/web-app/public/skills/track-management/SKILL.md +++ b/web-app/public/skills/track-management/SKILL.md @@ -1,6 +1,7 @@ --- name: track-management -description: "Use this skill when creating, managing, or working with Conductor" +description: | + 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.md, and track lifecycle operations. metadata: diff --git a/web-app/public/skills/tutorial-engineer/SKILL.md b/web-app/public/skills/tutorial-engineer/SKILL.md index f7ec59e1..23169adb 100644 --- a/web-app/public/skills/tutorial-engineer/SKILL.md +++ b/web-app/public/skills/tutorial-engineer/SKILL.md @@ -1,6 +1,7 @@ --- name: tutorial-engineer -description: "Creates step-by-step tutorials and educational content from code." +description: | + Creates step-by-step tutorials and educational content from code. Transforms complex concepts into progressive learning experiences with hands-on examples. Use PROACTIVELY for onboarding guides, feature tutorials, or concept explanations. diff --git a/web-app/public/skills/typescript-expert/SKILL.md b/web-app/public/skills/typescript-expert/SKILL.md index 8263f3d5..3de9f638 100644 --- a/web-app/public/skills/typescript-expert/SKILL.md +++ b/web-app/public/skills/typescript-expert/SKILL.md @@ -1,6 +1,6 @@ --- name: typescript-expert -description: ">-" +description: >- TypeScript and JavaScript expert with deep knowledge of type-level programming, performance optimization, monorepo management, migration strategies, and modern tooling. Use PROACTIVELY for any TypeScript/JavaScript diff --git a/web-app/public/skills/typescript-pro/SKILL.md b/web-app/public/skills/typescript-pro/SKILL.md index 31cf0e42..d65babb0 100644 --- a/web-app/public/skills/typescript-pro/SKILL.md +++ b/web-app/public/skills/typescript-pro/SKILL.md @@ -1,6 +1,7 @@ --- name: typescript-pro -description: "Master TypeScript with advanced types, generics, and strict type" +description: | + Master TypeScript with advanced types, generics, and strict type safety. Handles complex type systems, decorators, and enterprise-grade patterns. Use PROACTIVELY for TypeScript architecture, type inference optimization, or advanced typing patterns. diff --git a/web-app/public/skills/ui-ux-designer/SKILL.md b/web-app/public/skills/ui-ux-designer/SKILL.md index 24e6ec58..a102824c 100644 --- a/web-app/public/skills/ui-ux-designer/SKILL.md +++ b/web-app/public/skills/ui-ux-designer/SKILL.md @@ -1,6 +1,7 @@ --- name: ui-ux-designer -description: "Create interface designs, wireframes, and design systems. Masters" +description: | + Create interface designs, wireframes, and design systems. Masters user research, accessibility standards, and modern design tools. Specializes in design tokens, component libraries, and inclusive design. Use PROACTIVELY for design systems, user flows, or interface optimization. diff --git a/web-app/public/skills/ui-visual-validator/SKILL.md b/web-app/public/skills/ui-visual-validator/SKILL.md index 2850020d..f455e73e 100644 --- a/web-app/public/skills/ui-visual-validator/SKILL.md +++ b/web-app/public/skills/ui-visual-validator/SKILL.md @@ -1,6 +1,7 @@ --- name: ui-visual-validator -description: "Rigorous visual validation expert specializing in UI testing," +description: | + Rigorous visual validation expert specializing in UI testing, design system compliance, and accessibility verification. Masters screenshot analysis, visual regression testing, and component validation. Use PROACTIVELY to verify UI modifications have achieved their intended goals through diff --git a/web-app/public/skills/unity-developer/SKILL.md b/web-app/public/skills/unity-developer/SKILL.md index e6d114e0..53dbbadd 100644 --- a/web-app/public/skills/unity-developer/SKILL.md +++ b/web-app/public/skills/unity-developer/SKILL.md @@ -1,6 +1,7 @@ --- name: unity-developer -description: "Build Unity games with optimized C# scripts, efficient rendering," +description: | + Build Unity games with optimized C# scripts, efficient rendering, and proper asset management. Masters Unity 6 LTS, URP/HDRP pipelines, and cross-platform deployment. Handles gameplay systems, UI implementation, and platform optimization. Use PROACTIVELY for Unity performance issues, game diff --git a/web-app/public/skills/workflow-patterns/SKILL.md b/web-app/public/skills/workflow-patterns/SKILL.md index 717f3c89..f4f23e1d 100644 --- a/web-app/public/skills/workflow-patterns/SKILL.md +++ b/web-app/public/skills/workflow-patterns/SKILL.md @@ -1,6 +1,7 @@ --- name: workflow-patterns -description: "Use this skill when implementing tasks according to Conductor's TDD" +description: | + Use this skill when implementing tasks according to Conductor's TDD workflow, handling phase checkpoints, managing git commits for tasks, or understanding the verification protocol. metadata: