perf-skills 1.0.0

package/LICENSE.md

@@ -0,0 +1,8 @@
+Copyright 2026 NaveenKumar Namachivayam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

package/README.md

@@ -0,0 +1,227 @@
+# perf-skills
+
+> *"The more you sweat in training, the less you bleed in battle."* — Richard Marcinko
+>
+> The more relevant skills your AI loads during development, the fewer fires you fight in production.
+
+## What Is This?
+
+`perf-skills` is a structured knowledge base that gives AI coding assistants deep, opinionated expertise in performance testing. It works with any AI tool that supports custom instructions, rules, or skill files — helping you plan, script, execute, and analyze load tests using any major tool.
+
+### Supported Tools
+
+| Open Source | Commercial |
+|---|---|
+| Apache JMeter | NeoLoad (Tricentis) |
+| k6 (Grafana Labs) | LoadRunner (OpenText) |
+| Gatling | OctoPerf (SaaS) |
+| Locust | |
+
+### Topics Covered
+
+- **Workload design** — concurrency models, Little's Law, transaction mix, SLA targets
+- **Test data** — parameterization, CSV feeds, synthetic data, data isolation
+- **Script generation** — correlation, assertions, error handling, session management
+- **Test execution** — local, distributed, CI/CD pipelines, cloud execution
+- **Results analysis** — percentiles, bottleneck identification, trend comparison, reporting
+- **Observability** — APM integration, Prometheus/Grafana, distributed tracing, log correlation
+- **Production testing** — canary, shadow traffic, chaos engineering, safety controls
+- **Protocol testing** — gRPC, GraphQL, WebSocket/SSE, Kafka/message queues
+- **Database testing** — JDBC load testing, connection pools, query concurrency, replication lag
+- **Modern architectures** — microservices, Kubernetes (HPA, service mesh), serverless (cold starts), frontend (Core Web Vitals)
+
+## Compatible AI Coding Assistants
+
+| Tool | Integration Method | Setup |
+|---|---|---|
+| **Windsurf (Cascade)** | Skills | Copy to skills directory — auto-triggers on perf questions |
+| **Cursor** | Rules / Docs | Add as project rules or index via `@Docs` |
+| **Claude Code** | CLAUDE.md / Custom instructions | Reference files in `CLAUDE.md` or feed as context |
+| **Cline** | Custom instructions / `.clinerules` | Add to `.clinerules` or workspace instructions |
+| **Roo Code** | Custom instructions / Rules | Add as workspace rules or custom instructions |
+| **Aider** | Conventions / Chat context | Add to `.aider.conf.yml` conventions or `/read` files |
+| **OpenCode** | Custom instructions | Add to project-level instructions |
+| **Antigravity** | Context files | Add as context / knowledge files |
+| **Pochi** | Custom instructions | Reference files in project instructions |
+| **GitHub Copilot** | Custom instructions / `.github/copilot-instructions.md` | Reference in repo-level instructions |
+
+## Installation
+
+### Claude Code Plugin (Recommended)
+
+**Add the marketplace and install:**
+```bash
+/plugin marketplace add QAInsights/perf-skills
+/plugin install perf-skills@perf-skills
+```
+
+After install, the `/perf-skills` skill is available and auto-activates on performance testing questions.
+
+**Update to latest version:**
+```bash
+/plugin marketplace update
+```
+
+### Install as Skills (npx)
+
+```bash
+npx skills add QAInsights/perf-skills
+```
+
+### Install as Skills (Manual)
+
+```bash
+# Clone and copy to Claude skills directory
+git clone https://github.com/QAInsights/perf-skills.git
+cd perf-skills
+cp -r perf-skills/ ~/.claude/skills/
+```
+
+### Windsurf (Skills)
+
+1. Copy the `perf-skills/` directory into your Windsurf skills location.
+2. The skill auto-triggers when you ask about performance testing, load testing, or any supported tool.
+
+### Cursor (Rules / Docs)
+
+**Option A — Project Rules:**
+1. Create `.cursor/rules/perf-skills.mdc` in your project root.
+2. Add the content of `SKILL.md` as the rule, with file references pointing to the `references/` directory.
+
+**Option B — @Docs indexing:**
+1. Open Cursor Settings → Features → Docs.
+2. Add the `perf-skills/` directory as a doc source.
+3. Reference with `@Docs perf-skills` in chat.
+
+### Claude Code (CLAUDE.md)
+
+1. Copy the `perf-skills/` directory into your project.
+2. In your `CLAUDE.md`, add:
+```markdown
+For performance testing questions, read `perf-skills/SKILL.md` for routing,
+then load the relevant reference file(s) from `perf-skills/references/`.
+```
+
+### Cline / Roo Code
+
+1. Copy the `perf-skills/` directory into your project.
+2. Add to your custom instructions or `.clinerules`:
+```
+For performance testing guidance, consult the perf-skills knowledge base.
+Start with perf-skills/SKILL.md for routing to the correct reference file.
+```
+
+### Aider
+
+1. Copy the `perf-skills/` directory into your project.
+2. Use `/read perf-skills/SKILL.md` to load the routing file.
+3. Then `/read` the specific reference file(s) relevant to your question.
+
+### GitHub Copilot
+
+1. Copy the `perf-skills/` directory into your project.
+2. In `.github/copilot-instructions.md`, add:
+```markdown
+For performance testing questions, reference the perf-skills knowledge base.
+Start with perf-skills/SKILL.md, then load relevant files from perf-skills/references/.
+```
+
+### OpenCode / Antigravity / Pochi
+
+1. Copy the `perf-skills/` directory into your project.
+2. Add to your project-level custom instructions or context files:
+```
+For performance testing guidance, consult the perf-skills knowledge base.
+Start with perf-skills/SKILL.md for routing to the correct reference file.
+```
+
+### Any Other AI Tool
+
+The skill is plain markdown files. Any AI tool that can read files or accept custom instructions can use it:
+1. Point the tool to `SKILL.md` as the entry point.
+2. Let the Reference Map in `SKILL.md` guide which file(s) to load.
+
+### As a Standalone Knowledge Base
+
+Browse the markdown files directly — they're self-contained references useful even without an AI assistant.
+
+## File Structure
+
+```
+perf-skills/                              # Repository root
+├── .claude-plugin/
+│   └── marketplace.json                  # Claude Code marketplace catalog
+├── README.md
+├── LICENSE.md
+└── perf-skills/                          # Plugin / Skill directory
+    ├── .claude-plugin/
+    │   └── plugin.json                   # Claude Code plugin manifest
+    ├── SKILL.md                          # Entry point — tool selection, lifecycle, key principles
+    └── references/
+        ├── tools/                        # Tool-specific syntax and configuration
+        │   ├── jmeter.md                 # JMeter 5.6+ — samplers, extractors, plugins, Groovy
+        │   ├── k6.md                     # k6 v0.50+ — executors, checks, thresholds, modules
+        │   ├── gatling.md                # Gatling 3.10+ — Scala/Java DSL, feeders, injection
+        │   ├── locust.md                 # Locust 2.20+ — Python scripts, events, FastHttpUser
+        │   ├── neoload.md                # NeoLoad — GUI workflow, CLI, API execution
+        │   ├── loadrunner.md             # LoadRunner — VuGen, protocols, Controller scenarios
+        │   └── octoperf.md              # OctoPerf — JMeter-based SaaS, HAR import, cloud
+        └── topics/                       # Cross-cutting concepts (tool-agnostic)
+            ├── workload-design.md        # Concurrency models, load profiles, Little's Law
+            ├── test-data.md              # CSV, DB seeding, Faker, data isolation patterns
+            ├── script-generation.md      # Correlation, assertions, error handling, naming
+            ├── test-execution.md         # Distributed, CI/CD (GitHub Actions, GitLab, Jenkins)
+            ├── results-analysis.md       # Percentiles, bottleneck framework, reporting
+            ├── observability.md          # APM, Prometheus, Grafana, tracing, JVM metrics
+            ├── production-testing.md     # Canary, shadow traffic, chaos, safety controls
+            ├── protocol-testing.md       # gRPC, GraphQL, WebSocket, Kafka/message queues
+            ├── database-testing.md       # JDBC, connection pools, slow queries, deadlocks
+            └── modern-architectures.md   # Microservices, K8s, serverless, browser/Web Vitals
+```
+
+## How the Skill Works
+
+### Routing Logic
+
+`SKILL.md` acts as the entry point and router. It contains:
+
+1. **Loading Priority Rules** — tells the AI which file(s) to load based on the user's question (never all at once).
+2. **Reference Map** — maps user intent to the right file.
+3. **Protocol Routing Table** — maps protocols (gRPC, GraphQL, etc.) to recommended tools and reference files.
+4. **Tool Selection Matrix** — helps recommend a tool when the user hasn't chosen one.
+5. **Key Principles** — the single source of truth for cross-cutting best practices (assertions, think time, parameterization, correlation).
+
+### Design Principles
+
+- **Token-efficient**: Tool files contain only tool-specific syntax. Cross-cutting concepts live in topic files. No duplication.
+- **Selective loading**: The AI loads 1–2 files per question, not the entire knowledge base.
+- **Single source of truth**: Each concept is defined in exactly one place. Tool files cross-reference topic files for shared concepts.
+- **Opinionated**: The skill prescribes best practices, not just documentation. It tells you what to do, not just what's possible.
+
+## Example Questions This Skill Handles
+
+| Question | Files Loaded |
+|---|---|
+| "Help me write a k6 load test for our REST API" | `k6.md` |
+| "How should I design the workload for our e-commerce app?" | `workload-design.md` |
+| "Set up JMeter in our GitHub Actions pipeline" | `test-execution.md` + `jmeter.md` |
+| "Our p95 latency is spiking at 500 VUs — how do I debug?" | `results-analysis.md` + `observability.md` |
+| "How do I load test a gRPC service?" | `protocol-testing.md` + `k6.md` |
+| "What tool should I use? We're a Python team." | `SKILL.md` (Tool Selection Matrix) |
+| "Test our Kafka consumer throughput" | `protocol-testing.md` |
+| "Validate our K8s HPA scales correctly under load" | `modern-architectures.md` |
+| "Load test our PostgreSQL connection pool" | `database-testing.md` + `jmeter.md` |
+
+## Contributing
+
+To add or update content:
+
+1. **Tool-specific content** goes in `references/tools/<tool>.md` — syntax, config, tool-unique tips only.
+2. **Cross-cutting concepts** go in `references/topics/<topic>.md` — patterns that apply across tools.
+3. **Never duplicate** — if a concept exists in a topic file, tool files should cross-reference it, not restate it.
+4. **Update SKILL.md** if you add a new file — add it to the Reference Map and Protocol Routing Table if applicable.
+5. **Add a version indicator** (`> Targets: ...`) to new tool files.
+
+## License
+
+See repository license.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "perf-skills",
+  "version": "1.0.0",
+  "description": "Expert AI skill for performance testing — covers JMeter, k6, Gatling, Locust, NeoLoad, LoadRunner, OctoPerf across the full lifecycle",
+  "main": "perf-skills/SKILL.md",
+  "files": [
+    "perf-skills/"
+  ],
+  "keywords": [
+    "performance-testing",
+    "load-testing",
+    "jmeter",
+    "k6",
+    "gatling",
+    "locust",
+    "neoload",
+    "loadrunner",
+    "octoperf",
+    "stress-testing",
+    "soak-testing",
+    "grpc",
+    "graphql",
+    "websocket",
+    "observability",
+    "ci-cd",
+    "claude-skills",
+    "ai-assistant"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/QAInsights/perf-skills.git"
+  },
+  "author": {
+    "name": "NaveenKumar Namachivayam",
+    "email": "info@qainsights.com"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/QAInsights/perf-skills#readme",
+  "engines": {
+    "node": ">=14"
+  }
+}

package/perf-skills/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "perf-skills",
+  "description": "Expert guidance for performance testing: planning, scripting, executing, and analyzing load/stress/soak/spike tests using JMeter, k6, Gatling, Locust, NeoLoad, LoadRunner, OctoPerf.",
+  "version": "1.0.0"
+}

package/perf-skills/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: perf-skills
+description: >
+  Expert guidance for performance testing: planning, scripting, executing, and analyzing
+  load/stress/soak/spike tests using JMeter, k6, Gatling, Locust, NeoLoad, LoadRunner,
+  OctoPerf. Covers workload design, test data, correlation, CI/CD integration,
+  distributed testing, observability, production testing, and protocol-specific guidance
+  for HTTP, gRPC, GraphQL, WebSocket, JDBC, and message queues.
+---
+
+# Performance Testing Skill (perf-skills)
+
+This skill provides expert, opinionated guidance across the full performance testing lifecycle — from workload design through production observation. It covers both commercial tools (LoadRunner, NeoLoad, OctoPerf) and open-source tools (JMeter, k6, Gatling, Locust).
+
+---
+
+## How to Use This Skill
+
+Read the relevant reference files based on what the user needs. Multiple files may apply.
+
+### Loading Priority Rules
+
+1. **Tool-specific syntax/config** → load the tool file only.
+2. **Strategy/concepts** (workload design, test data, analysis) → load the topic file only.
+3. **Both apply** (e.g., "JMeter CI/CD") → load the topic file first for patterns, then the tool file for syntax.
+4. **Never load all files at once** — select the 1–2 most relevant.
+5. **Cross-cutting principles** (assertions, think time, parameterization) → this file's Key Principles section is the single source of truth.
+
+### Reference Map
+
+| User needs help with... | Read this file |
+|---|---|
+| Choosing the right tool | This file — see Tool Selection Matrix below |
+| JMeter scripts, plugins, config | `references/tools/jmeter.md` |
+| k6 scripting, extensions, cloud | `references/tools/k6.md` |
+| Gatling simulations, Scala/Java DSL | `references/tools/gatling.md` |
+| Locust Python tests, distributed | `references/tools/locust.md` |
+| NeoLoad projects, GUI, APIs | `references/tools/neoload.md` |
+| LoadRunner scripts, protocols, VuGen | `references/tools/loadrunner.md` |
+| OctoPerf cloud test management | `references/tools/octoperf.md` |
+| Designing workloads, concurrency, pacing | `references/topics/workload-design.md` |
+| Test data, parameterization, CSV feeds | `references/topics/test-data.md` |
+| Script patterns, correlation, best practices | `references/topics/script-generation.md` |
+| CI/CD, distributed execution, cloud runners | `references/topics/test-execution.md` |
+| Analyzing results, percentiles, SLAs | `references/topics/results-analysis.md` |
+| APM, metrics, tracing, dashboards | `references/topics/observability.md` |
+| Staging vs production testing strategies | `references/topics/production-testing.md` |
+| gRPC, GraphQL, WebSocket, messaging protocols | `references/topics/protocol-testing.md` |
+| Database load testing (JDBC, connection pools) | `references/topics/database-testing.md` |
+| Microservices, K8s, serverless performance | `references/topics/modern-architectures.md` |
+
+### Protocol Routing Table
+
+When the user's question is protocol-specific, use this to select the right tool and reference:
+
+| Protocol | Recommended Tools | Reference |
+|---|---|---|
+| HTTP / REST | k6, Gatling, JMeter | Tool file |
+| gRPC | k6, Gatling, JMeter (plugin) | `references/topics/protocol-testing.md` + tool file |
+| GraphQL | k6, Gatling | `references/topics/protocol-testing.md` + tool file |
+| WebSocket / SSE | Gatling, k6 | `references/topics/protocol-testing.md` + tool file |
+| JDBC / Database | JMeter | `references/topics/database-testing.md` + `jmeter.md` |
+| Kafka / Message Queues | k6 (xk6-kafka), JMeter | `references/topics/protocol-testing.md` |
+| SOAP / WSDL | LoadRunner, JMeter | Tool file |
+| SAP / Citrix | LoadRunner, NeoLoad | Tool file |
+
+---
+
+## Tool Selection Matrix
+
+Use this to recommend the right tool when the user hasn't decided yet.
+
+| Criteria | JMeter | k6 | Gatling | Locust | NeoLoad | LoadRunner | OctoPerf |
+|---|---|---|---|---|---|---|---|
+| **Language** | GUI/XML + Groovy | JavaScript/TypeScript | Scala/Java | Python | GUI + NeoLoad DSL | VuGen C-like | Web UI (JMeter-based) |
+| **Open source** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ (SaaS) |
+| **Protocol support** | HTTP, JDBC, JMS, MQTT, FTP, gRPC | HTTP, gRPC, WS | HTTP, JMS, gRPC | HTTP, gRPC | HTTP, gRPC, WS, SAP | HTTP, Citrix, SAP, Flex | HTTP (JMeter-backed) |
+| **Developer-friendly** | Medium | High | High | High | Low | Low | Medium |
+| **Enterprise support** | Community + BlazeMeter | Grafana Cloud | Gatling Enterprise | Limited | ✅ | ✅ | ✅ |
+| **CI/CD integration** | Good (Maven/Gradle) | Excellent | Excellent | Good | Good | Moderate | Good |
+| **Cloud execution** | BlazeMeter, OctoPerf | Grafana Cloud | Gatling Enterprise | Self-managed | NeoLoad Cloud | AWS/on-prem | OctoPerf Cloud |
+| **Best for** | Legacy systems, JDBC, protocols | Modern APIs, TypeScript devs | High-throughput HTTP | Python teams, flexible | SAP/Citrix enterprise | Mainframe, legacy enterprise | JMeter teams needing cloud UI |
+
+### Quick decision rules
+- **Team writes code** → k6 or Gatling
+- **Team uses GUI** → JMeter or NeoLoad
+- **Python shop** → Locust
+- **SAP / mainframe / Citrix** → LoadRunner or NeoLoad
+- **Need cloud SaaS with minimal setup** → OctoPerf (JMeter) or Grafana Cloud (k6)
+- **Free + protocol variety** → JMeter
+- **Correlation needed for session-heavy flows** → JMeter (with Correlation Recorder) or LoadRunner
+- **gRPC or GraphQL APIs** → k6 or Gatling
+- **Message queues (Kafka, RabbitMQ)** → k6 (xk6-kafka) or JMeter
+
+---
+
+## Performance Testing Lifecycle Overview
+
+Always think through these phases when helping a user — they often ask about one phase but need context from others.
+
+```
+1. PLAN
+   └─ Workload design → concurrency model → SLA targets → test type selection
+       → references/topics/workload-design.md
+
+2. DATA
+   └─ Identify variables → parameterization strategy → test data generation
+       → references/topics/test-data.md
+
+3. SCRIPT
+   └─ Record or code → correlation → parameterization → assertions → script review
+       → references/topics/script-generation.md + tool-specific file
+
+4. EXECUTE
+   └─ Local → distributed → CI/CD → cloud burst → monitoring hooks
+       → references/topics/test-execution.md
+
+5. OBSERVE
+   └─ APM → metrics → logs → traces → dashboards
+       → references/topics/observability.md
+
+6. ANALYZE
+   └─ Throughput, latency percentiles, errors → bottleneck ID → report
+       → references/topics/results-analysis.md
+
+7. PRODUCTION
+   └─ Canary testing → shadow load → chaos → synthetic monitoring
+       → references/topics/production-testing.md
+```
+
+---
+
+## Common Performance Test Types
+
+| Test Type | Goal | Key Metric |
+|---|---|---|
+| **Load** | Validate system at expected load | Response time, throughput, error rate |
+| **Stress** | Find the breaking point | Max VUs before degradation, error onset |
+| **Soak/Endurance** | Detect memory leaks, slow degradation | Resource trend over time (hours) |
+| **Spike** | Behavior under sudden traffic burst | Recovery time, error spike |
+| **Capacity** | Find max sustainable load | Throughput ceiling at SLA thresholds |
+| **Smoke** | Quick sanity check | Single VU — no errors |
+| **Breakpoint** | Incremental ramp until failure | Failure threshold VU count |
+
+---
+
+## Key Principles to Always Apply
+
+1. **Never test against production blindly** — always have a rollback plan and alerting in place.
+2. **Baseline first** — always establish a baseline before stress or soak runs.
+3. **Think time and pacing matter** — unrealistic zero-think-time tests produce misleading results.
+4. **Parameterize everything** — hardcoded credentials, tokens, and IDs will fail at scale.
+5. **Assertions are not optional** — tests without assertions are just generating traffic, not validating behavior.
+6. **Isolate the system under test** — shared environments invalidate results.
+7. **Correlate dynamic values** — session tokens, CSRF, ViewState, etc. must be extracted and reused.
+
+---
+
+## Asking the Right Questions
+
+When a user brings a performance problem, ask (or infer) these before prescribing a solution:
+
+- What is the **target concurrency** (VUs or RPS)?
+- What is the **SLA** (e.g., p95 < 500ms, error rate < 1%)?
+- What is the **protocol** (HTTP/REST, gRPC, JDBC, WebSocket)?
+- Is the app **stateful** (session-based) or **stateless** (token-based)?
+- Where will tests **run from** (local, CI, cloud)?
+- What **environment** is being tested (dev, staging, prod)?
+- Is there an **APM tool** in place (Datadog, Dynatrace, Grafana, New Relic)?