@skill-graph/cli 0.5.6

package/marketplace/skills/prompt-injection-defense/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: prompt-injection-defense
+description: "Use when reasoning about systems that pass untrusted content to a language model: the data-vs-instruction collapse that makes this attack class a structural property of LLMs rather than a fixable bug, the direct/indirect/exfiltration/action-trigger taxonomy, the role of every untrusted surface (RAG retrievals, tool results, attachments, web content, document parsing, user-provided text), why content filters and improved system prompts do not solve it, and the defense-in-depth measures that do (capability constraint, content origin tracking, separate planning and execution stages, human-in-the-loop gates, principle-of-least-authority for tools). Do NOT use for jailbreaking and policy circumvention (use model-safety), for general API security (use api-security), for runtime input validation patterns (use type-safety + api-design), or for the protocol cycle of tool calls (use tool-call-flow)."
+license: MIT
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"quality\",\"domain\":\"quality/security\",\"scope\":\"reference\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-16\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-16\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"comprehension_state\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"prompt injection\\\\\\\",\\\\\\\"indirect prompt injection\\\\\\\",\\\\\\\"LLM01\\\\\\\",\\\\\\\"OWASP LLM\\\\\\\",\\\\\\\"data exfiltration\\\\\\\",\\\\\\\"tool abuse\\\\\\\",\\\\\\\"untrusted content\\\\\\\",\\\\\\\"RAG injection\\\\\\\",\\\\\\\"markdown image exfiltration\\\\\\\",\\\\\\\"jailbreak\\\\\\\",\\\\\\\"instruction confusion\\\\\\\",\\\\\\\"principle of least authority\\\\\\\",\\\\\\\"dual LLM pattern\\\\\\\",\\\\\\\"prompt injection attack\\\\\\\",\\\\\\\"inject instructions into context\\\\\\\"]\",\"triggers\":\"[\\\\\\\"is this an injection vector\\\\\\\",\\\\\\\"how do we stop the model from following commands in user input\\\\\\\",\\\\\\\"the model is treating retrieved content as commands\\\\\\\",\\\\\\\"is RAG safe\\\\\\\",\\\\\\\"can the model exfiltrate data via a tool call\\\\\\\"]\",\"examples\":\"[\\\\\\\"review whether retrieved documents in a RAG pipeline can override the system prompt\\\\\\\",\\\\\\\"design the boundary between a planning agent and an execution agent so injected commands cannot trigger destructive tool calls\\\\\\\",\\\\\\\"explain why a content filter that blocks one canonical attack phrase does not stop the broader class\\\\\\\",\\\\\\\"decide what tools an agent reading email attachments may invoke without human confirmation\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"design the JSON shape of a tool's parameters (use tool-call-flow)\\\\\\\",\\\\\\\"harden an HTTP API against SQL injection or XSS (use api-security)\\\\\\\",\\\\\\\"audit a model's refusal behavior on disallowed content (use model-safety)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"tool-call-flow\\\\\\\",\\\\\\\"http-semantics\\\\\\\",\\\\\\\"type-safety\\\\\\\",\\\\\\\"api-design\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"tool-call-flow\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"tool-call-flow owns the protocol cycle by which a model invokes a tool; this skill owns the security property the cycle must preserve when any message carries untrusted content.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"type-safety\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"type-safety owns preventing type errors at compile time; this skill owns preventing command-execution errors at the data-vs-instruction boundary. Both are validate-at-the-boundary problems with different threat models.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"api-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"api-design owns the request/response surface contract; this skill owns the constraint that no field carrying user content may be treated as commands by a downstream model.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"http-semantics\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"http-semantics owns transport meaning (cache, idempotency, content type); this skill owns the threat that arrives over correct HTTP and is still harmful because the model interprets it as a command.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"api-design\\\\\\\",\\\\\\\"tool-call-flow\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"Prompt injection defense is to LLM-integrated systems what blast walls are to fuel depots — you cannot prevent the fuel from being flammable (the structural property), so you do not try; you build the walls so that an ignition contains itself, the radius is bounded, and the rest of the depot survives. The walls are the architectural defense; the model's susceptibility is the fuel's flammability — a property of its physics, not a bug to fix.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"This attack class describes systems where untrusted content placed within a language model's input causes the model to follow attacker-controlled directives instead of, or in addition to, the application's legitimate ones. It is a structural property of how transformer-based language models consume their input — every token in the context window contributes to the next-token prediction, and the model has no reliable mechanism to distinguish 'directives from the application developer' from 'directives in a document the application happens to have loaded.' Defense, therefore, is not elimination of the vulnerability but architectural containment of its blast radius.\\\\\\\",\\\\\\\"mental_model\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"purpose\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"boundary\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"taxonomy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"analogy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"misconception\\\\\\\":\\\\\\\"|\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/prompt-injection-defense/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/prompt-injection-defense/SKILL.md
+---
+
+# Prompt-Injection Defense
+
+## Coverage
+
+The architectural discipline of defending language-model-integrated systems against the attack class in which untrusted content causes the model to follow attacker-controlled directives. Covers the data-vs-directive collapse that makes this attack structural rather than incidental, the direct/indirect/action-trigger/exfiltration taxonomy, the injection surfaces (user input, RAG retrieval, tool result, attached document, multimodal image content, subagent output), why content filters and improved system prompts do not solve the class, and the defense-in-depth measures that do (capability constraint, origin tracking, dual-LLM pattern, planning/execution separation, human-in-the-loop confirmation, principle of least authority).
+
+## Philosophy
+
+This attack class is not a bug. It is a property of how transformer-based language models consume their context. Every token in the context window contributes to the next-token prediction, and the model has no reliable mechanism to distinguish "directives from the application developer" from "directives written by an attacker in a document the application happens to have loaded." Treating it as a bug to fix — by patching the model or improving the system prompt — buys partial reductions in attack success rate but never reaches zero.
+
+The discipline of defense, therefore, is not to eliminate the vulnerability. It is to ensure that successful compromise does not translate to consequential action. The model can be tricked; the runtime must not be. The defenses that work are architectural: limit what tools the model exposed to untrusted content can call, separate the agent that reads untrusted content from the agent (or code) that takes action, require human confirmation for high-impact operations regardless of model intent, and track the provenance of every byte in the context window so that low-trust content cannot route to high-authority execution paths.
+
+The wrong mental model is "build a smart fence around the model." The right mental model is "engineer the system so the model's mistakes don't matter."
+
+## The Threat Model
+
+| Element | Direct case | Indirect case |
+|---|---|---|
+| Who is the attacker | The user typing into the input | A third party who controls content the system reads |
+| Who is the victim | The application (or the user's interest in the app's correct behavior) | The user on whose behalf the model is acting |
+| Where the directive lives | The user-input field | A document, webpage, tool result, email, RAG entry, subagent output |
+| Why the user wouldn't notice | The user is the attacker | The user may never even see the injected content |
+| First demonstrated | Riley Goodside popularized in September 2022 | Greshake et al., "Not what you've signed up for," February 2023 |
+
+Both threat cases have the same root cause (data-vs-directive collapse in transformers) and require the same architectural defenses, but the indirect case is the harder threat — the user is not a participant in their own compromise.
+
+## The Defense Stack
+
+Defenses compose. None alone is sufficient; the stack as a whole determines the system's security posture.
+
+| Layer | What it does | Bypass class | Strength |
+|---|---|---|---|
+| Input filtering / blocklist | Pattern-match for known attack strings | Paraphrase, encoding, indirect content | Weak |
+| System-prompt warning | Tell the model not to follow injected directives | Sufficiently persuasive text in the same context | Weak-to-medium |
+| Output sanitization | Strip dangerous markdown / outbound URLs / scripts from model output | Same-origin exfiltration, encoded data | Medium for exfiltration |
+| Structured output enforcement | Force JSON/function-call schema | Semantic compromise within valid structure | Medium for shape, weak for content |
+| Tool authority constraint | The tools available to a low-trust agent are themselves low-impact | Compose multiple safe tools into harmful effect | Strong |
+| Origin tracking / dual-LLM pattern | A privileged LLM never sees untrusted content; a quarantined LLM produces typed outputs the privileged one consumes | Quarantined LLM persuades the privileged one via the typed channel — needs schema rigor | Strong |
+| Planning/execution separation | The planning model proposes; a separate execution layer enforces what is actually allowed | Bypassed only if execution policy is itself derived from model output | Strong |
+| Human-in-the-loop confirmation | Every irreversible action requires explicit user approval | User clicks through; UX matters | Strong if UX is honest |
+| Principle of least authority | The agent has only the credentials and scopes needed for the immediate task | Insider threat from the agent itself is the residual risk | Strong |
+
+The OWASP Top 10 for LLM Applications (LLM01: Prompt Injection) recommends combining several of these in any deployed system.
+
+## Injection Surfaces — Every One Is A Vector
+
+| Surface | Risk | Mitigation |
+|---|---|---|
+| User-input field | Direct case | Treat as untrusted; constrain tools accordingly |
+| RAG retrieval | Indirect via poisoned/attacker-authored documents in the corpus | Origin-tag retrieved chunks; low-trust score; never let RAG content escalate authority |
+| Tool result | Indirect via a tool that fetches third-party content (web, email body, low-trust DB rows) | Treat tool results as untrusted; constrain follow-up tool calls; do not let a tool result trigger an action the user did not authorize |
+| Attached document (PDF, DOCX, spreadsheet) | Indirect via attachment uploaded by anyone (the user, but also a forwarded email) | Same as above; consider whether the agent reading attachments needs any tool authority |
+| Image / multimodal | Directives encoded as text in image pixels, OCR'd by the model | Same as above; vision models susceptible to text-in-image directives |
+| Subagent output | A compromised subagent propagates the compromise to its parent | Subagent outputs are tool results; treat as untrusted |
+| The system prompt position | If user content gets prepended above the system prompt due to bug | Validate the message-list construction; system prompt must always be first |
+
+The defensive question for any new feature: **what untrusted content will enter the model's context, and what tools will the model have authority to call in that turn?** If the answer to the second is anything destructive, the design needs revision.
+
+## The Markdown-Image Exfiltration Pattern
+
+A signature exfiltration technique against assistant-style LLMs:
+
+1. Untrusted content the model is reading contains a directive to include, at the end of its response, a markdown image whose URL points at an attacker-controlled server with the query string containing some sensitive value from the conversation.
+2. The model, attending to the directive, constructs the markdown image element with the sensitive value embedded in the URL.
+3. The chat UI renders the markdown, causing the user's browser to fetch the image URL.
+4. The attacker's server logs the URL, capturing the sensitive value.
+
+The user did not click anything. They saw the assistant's reply, the image silently loaded, and the data was exfiltrated.
+
+Mitigations:
+- Strip markdown image links pointing to non-allowed origins before rendering.
+- Apply Content-Security-Policy to the chat UI restricting `img-src`.
+- Sanitize URLs in model output as part of the rendering pipeline, not the model output.
+
+This pattern generalizes: any rendered output that can produce an outbound network request based on attacker-controlled content is an exfiltration channel.
+
+## The Dual-LLM Pattern
+
+Proposed by Simon Willison (2023). Two LLMs split the work:
+
+- **Privileged LLM** — has access to tools, secrets, and authority. Never sees untrusted content directly. Receives only typed, structured summaries from the quarantined LLM (a schema like `{ documents_summary: string, action_options: Action[], recommended: Action }`).
+- **Quarantined LLM** — reads untrusted content. Has no tool authority. Its only output is into a typed schema that the privileged LLM consumes.
+
+Even if the quarantined LLM is fully compromised (every retrieved document successfully attacks it), it can only output values into the typed schema; the harm is bounded by what an attacker can express through that schema. If the schema is small and well-designed, the bound is tight.
+
+This is structurally analogous to a sandboxed process producing a parsed protobuf for a privileged orchestrator — the security boundary is the data shape between them, enforced by code on both sides.
+
+## Verification
+
+After applying this skill, verify:
+- [ ] Every place untrusted content enters the model's context is named explicitly. "User input" is not the only one — RAG retrievals, tool results, attached documents, multimodal image content, and subagent outputs all qualify.
+- [ ] The agent exposed to any untrusted content has tool authority limited to operations that cannot cause harm if maliciously invoked. Destructive tools require human-in-the-loop confirmation regardless of model intent.
+- [ ] No defense rests solely on prompting. System-prompt warnings are present as one layer but are not the load-bearing layer.
+- [ ] If output is rendered as HTML or Markdown, image-source and link-target origins are restricted by an allowlist or Content-Security-Policy, not by trust in the model output.
+- [ ] If the system uses RAG, retrieved chunks are origin-tagged; the rendering or downstream-tool layer treats retrieved content as low-trust regardless of corpus provenance.
+- [ ] If the system uses subagents, subagent outputs are treated as tool results — i.e., as untrusted content — when they re-enter the parent's context.
+- [ ] No single tool call can both ingest untrusted content and perform a high-impact action in the same turn. The planning/execution boundary is enforced architecturally, not by prompt.
+- [ ] An adversarial test has been run: at least one red-team pass against the system using public attack-prompt corpora (e.g., the OWASP LLM01 examples, the SPML benchmark) and a hand-written set targeting the system's specific tools and surfaces.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Hardening a model against producing disallowed content (jailbreaking) | `model-safety` | jailbreaking targets the model's policy boundary on behalf of one user; this attack class targets the application's correct behavior on behalf of a victim user |
+| Designing the JSON shape or parameter schema of a tool | `tool-call-flow` + `api-design` | tool-call-flow owns the model-runtime cycle; api-design owns parameter shape; this skill owns the security property they must preserve |
+| Defending an HTTP API against SQL injection or XSS | `api-security` | those have hard data-vs-directive boundaries that can be fixed at the encoding layer; this skill is for the boundary-less LLM case |
+| Auditing the model's accuracy or hallucination behavior | `eval-driven-development` | eval owns measurement; this skill owns the security property |
+| General authn/authz for API endpoints | `api-security` | authz governs what callers may do; this skill governs what an authenticated agent may be tricked into doing |
+
+## Key Sources
+
+- OWASP. [LLM01: Prompt Injection — OWASP Top 10 for Large Language Model Applications (2025)](https://genai.owasp.org/llmrisk/llm01-prompt-injection/). The canonical industry-aligned threat-classification and mitigation framework.
+- Greshake, K., Abdelnabi, S., Mishra, S., Endres, C., Holz, T., & Fritz, M. (2023). ["Not what you've signed up for: Compromising Real-World LLM-Integrated Applications with Indirect Prompt Injection"](https://arxiv.org/abs/2302.12173). The foundational academic paper on the indirect case; defines the threat model.
+- Perez, F., & Ribeiro, I. (2022). ["Ignore Previous Prompt: Attack Techniques For Language Models"](https://arxiv.org/abs/2211.09527). Early systematic study of direct attack techniques.
+- Willison, S. [Prompt injection: What's the worst that can happen?](https://simonwillison.net/2023/Apr/14/worst-that-can-happen/) and [The Dual LLM pattern for building AI assistants that can resist prompt injection](https://simonwillison.net/2023/Apr/25/dual-llm-pattern/). Canonical practitioner taxonomy and the dual-LLM architectural pattern.
+- NIST. [AI Risk Management Framework (AI RMF 1.0)](https://nvlpubs.nist.gov/nistpubs/ai/NIST.AI.100-1.pdf). Section on adversarial input and the broader AI risk taxonomy; useful framing for what this attack class sits inside.
+- Anthropic. [Mitigating jailbreaks and prompt injections](https://docs.anthropic.com/en/docs/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks). Vendor-side guidance on defense in depth for Anthropic-hosted models — useful as one practitioner perspective, not as a complete defense.
+- OWASP. [LLM02: Sensitive Information Disclosure](https://genai.owasp.org/llmrisk/llm02-sensitive-information-disclosure/) and [LLM06: Excessive Agency](https://genai.owasp.org/llmrisk/llm06-excessive-agency/). Adjacent OWASP categories that compose with this one — exfiltration consequences and over-broad tool authority are the consequence side of the threat.
+- Schulhoff, S., Pinto, J., Khan, A., et al. (2024). ["The Prompt Report: A Systematic Survey of Prompting Techniques"](https://arxiv.org/abs/2406.06608). Cross-references defensive prompting techniques within the broader prompting literature.

package/marketplace/skills/property-based-testing/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: property-based-testing
+description: "Use when reasoning about tests that specify universal properties of code rather than specific input-output pairs: the forall(input) → property quantification, the generator/shrinker primitives that produce inputs and minimize failing cases, the four-rules-of-simple-design analog (commutativity, associativity, idempotence, round-trip, oracle, invariant), the difference between example-based tests (one input, one assertion) and property-based tests (many generated inputs, one universal claim), why property tests find bugs example tests don't, the shrinking discipline that produces minimal failing cases, and the trade-off between generator complexity and bug-finding capacity. Do NOT use for specifying one concrete behavior with one input (use example-based tests under testing-strategy), for fuzz-testing focused on crashes (use fuzz-testing), for mutation testing as a test-suite quality signal (use mutation-testing), or for model-based testing of state machines (use state-machine-modeling)."
+license: MIT
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"quality\",\"domain\":\"quality/testing\",\"scope\":\"reference\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-16\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-16\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"comprehension_state\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"property-based testing\\\\\\\",\\\\\\\"PBT\\\\\\\",\\\\\\\"QuickCheck\\\\\\\",\\\\\\\"Hypothesis\\\\\\\",\\\\\\\"fast-check\\\\\\\",\\\\\\\"generator\\\\\\\",\\\\\\\"shrinker\\\\\\\",\\\\\\\"forall\\\\\\\",\\\\\\\"invariant\\\\\\\",\\\\\\\"round-trip property\\\\\\\",\\\\\\\"oracle property\\\\\\\",\\\\\\\"random testing\\\\\\\",\\\\\\\"generative testing\\\\\\\"]\",\"triggers\":\"[\\\\\\\"should this be a property test\\\\\\\",\\\\\\\"what's an invariant for this function\\\\\\\",\\\\\\\"the bug only happens on weird inputs\\\\\\\",\\\\\\\"QuickCheck or fast-check\\\\\\\",\\\\\\\"how do we test all possible cases\\\\\\\"]\",\"examples\":\"[\\\\\\\"design property-based tests for a sorting function that exercise the universal contract\\\\\\\",\\\\\\\"decide which functions in a parser deserve property tests vs example tests\\\\\\\",\\\\\\\"diagnose a property test that finds a real bug but the shrunk input is large — likely a poorly-shrinkable generator\\\\\\\",\\\\\\\"explain the round-trip property for an encode/decode pair\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"specify one concrete input-output case (use example-based tests; see testing-strategy)\\\\\\\",\\\\\\\"fuzz for crashes and memory safety (use fuzz-testing)\\\\\\\",\\\\\\\"measure whether tests would catch a defect (use mutation-testing)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"test-driven-development\\\\\\\",\\\\\\\"type-safety\\\\\\\",\\\\\\\"mutation-testing\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"testing-strategy owns the strategic question of what test levels to invest in; this skill owns one tactical technique (generative tests with universal properties) within that strategy. Property-based testing is a complement to example-based tests, not a replacement.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"mutation-testing\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"mutation-testing measures whether the test suite catches code-level defects; property-based testing is one source of high-mutation-killing tests because universal properties tend to be specific about behavior across many inputs. They compose: PBT writes the tests; mutation testing measures their effectiveness.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"type-safety\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"type-safety constrains the input space at compile time; property-based testing samples the runtime input space within the type-constraint envelope. Stronger types reduce the property-test surface needed; PBT is most valuable where types alone cannot encode the invariants (algorithmic correctness, business rules, round-trips).\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"mutation-testing\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"A property-based test is to an example test what an actuarial table is to a single insurance claim — the example tells you what happened in one case, the property tells you what must hold across the entire population; you do not learn that fire insurance is sound by inspecting one policy, you learn it from a contract that quantifies over every house ever insured.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"Property-based testing is a tactical technique in which a test specifies a universal property — a claim that must hold for all inputs in a domain — and a test framework generates many random inputs in the domain and checks the property holds. When the property fails on some input, the framework shrinks the input to the smallest failing case to make the bug legible. The unit of specification is a forall-quantified claim, not a single example. Properties typically take three shapes: invariants (a property the output must always have, independent of the input), oracles (the output must equal what an alternative implementation computes), and round-trips (encoding then decoding produces the original value). Property-based testing supplements example-based testing rather than replacing it: examples specify particular behaviors; properties specify the universal contract.\\\\\\\",\\\\\\\"mental_model\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"purpose\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"boundary\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"taxonomy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"analogy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"misconception\\\\\\\":\\\\\\\"|\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/property-based-testing/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/property-based-testing/SKILL.md
+---
+
+# Property-Based Testing
+
+## Coverage
+
+The tactical testing technique in which a test specifies a universal property — a claim that must hold for all inputs in a domain — and a framework generates many random inputs to challenge the claim, shrinking any failing input to its minimal form. Covers the four primitives (property, generator, shrinker, trial budget), the three classical property shapes (invariant, oracle, round-trip) plus algebraic and metamorphic patterns, the QuickCheck heritage and the modern tool ecosystem (Hypothesis, fast-check, ScalaCheck, proptest, jqwik), the generator/shrinker discipline for domain types, and the integration of property tests with example tests in a test suite.
+
+## Philosophy
+
+Property-based testing changes the unit of specification from the example to the contract. An example test says "for this input, the output should be this." A property test says "for any input matching this generator, this universal claim holds." When the contract is articulable, a property test verifies far more of the behavior than a hand-written set of examples could; when the contract is not articulable, property tests are made up after the fact and verify whatever happens to be in the generator's reach, which is not useful.
+
+The discipline is in three places: the property (is the claim universal, falsifiable, and meaningful?), the generator (does it produce inputs that cover the space, including the edges?), and the shrinker (when a property fails, can the framework reduce the failing input to something a developer can read?). All three must be well-designed for property-based testing to deliver its promise.
+
+Property tests are complements to example tests, not replacements. The mature pattern is properties for the universal contract and examples for the specific cases that document particular behaviors or bug fixes.
+
+## The Three Classical Property Shapes
+
+| Shape | Pattern | Example |
+|---|---|---|
+| Invariant | The output has a structural property regardless of input | `forall L. isSorted(sort(L))` |
+| Oracle | The output equals an alternative implementation's output | `forall L. fastSort(L) == referenceSort(L)` |
+| Round-trip | A transformation and its inverse compose to identity | `forall x. decode(encode(x)) == x` |
+
+Plus algebraic patterns (commutativity, associativity, identity, idempotence) and metamorphic patterns (relations between related inputs). Most useful property tests use one or two of these shapes.
+
+## The Generator and Shrinker
+
+A property test has two halves: the property and the generator. A well-designed generator produces inputs that exercise the input space — including edge cases (empty, single-element, boundary values), valid cases, and invalid cases as appropriate. A poorly-designed generator misses bug-triggering inputs and the property "passes" by not having been challenged.
+
+The shrinker reduces a failing input to its minimal form. Without shrinking, a failing input is random noise. With shrinking, a failing input is the smallest demonstration of the bug — usually small enough that the bug is visible at a glance.
+
+| Domain | Library-provided generator | Library-provided shrinker | Custom shrinker need |
+|---|---|---|---|
+| Primitive types (int, float, string, bool) | Yes | Yes | No |
+| Collections (list, map, set) | Yes | Yes | No |
+| Optional, Either, Result | Yes | Yes | No |
+| Tuples and products | Yes | Yes | No |
+| Custom domain types | Compose from primitives | Shrinks to component primitives | Sometimes — when domain has invariants |
+| Grammar-based (valid JSON, SQL, email) | Some libraries provide | May need custom | Often yes |
+| Stateful (sequences of operations) | Yes (PBT state-machine modes) | Yes | Custom for domain operations |
+
+## Property vs Example — Where Each Fits
+
+| Code character | Property test | Example test |
+|---|---|---|
+| Sorting, searching, data structure operations | Strong fit | For regression of specific bugs |
+| Parsing / unparsing, encoding / decoding | Strong fit (round-trip) | For known-input regression |
+| Pure mathematical functions | Strong fit | Rarely needed |
+| Business rules with combinatorial input | Strong fit | For specific edge cases |
+| API request/response round-trips | Strong fit | For known good/bad cases |
+| Functions defined by a small list of cases | Weak fit — property unclear | Strong fit |
+| Bug regression for a specific known input | Weak fit | Strong fit |
+| Code with side effects / I/O | Adaptable via stateful PBT | Often easier |
+
+A test suite typically mixes both; the right ratio depends on how much of the code has articulable universal contracts.
+
+## Verification
+
+After applying this skill, verify:
+- [ ] Every property test asserts a *universal* claim, not a specific input-output. A test that runs `forall input in [single_value]` is an example test in property-test clothing.
+- [ ] Each property fits one of the recognized shapes (invariant, oracle, round-trip, algebraic, metamorphic) or has a clearly-stated rationale for being a different shape.
+- [ ] Generators for domain types are composed from library primitives; custom generators ship with custom shrinkers when default shrinking produces unintuitive minimal cases.
+- [ ] Generator design produces both common and edge-case inputs. Generators that produce only "typical" inputs miss bug-triggering edge cases by construction.
+- [ ] When a property fails, the reported failing input is the shrunk minimum — not a 500-element random list. If the shrunk input is large, the generator/shrinker pair needs work.
+- [ ] Property tests are complemented by example tests for specific cases (bug regressions, documented behaviors). The suite is not property-only.
+- [ ] Trial budgets are appropriate to the property: 100 inputs for cheap properties; 1000+ for properties on slow code or with rare-bug input spaces; nightly long-running campaigns for production-critical properties.
+- [ ] PBT is applied where the contract is articulable. Functions that are genuinely defined by a list of cases are not force-fit to property tests.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Specifying one concrete input-output behavior | example tests (see `testing-strategy`) | examples specify particular behaviors; this skill specifies universal contracts |
+| Generating random inputs to find crashes or memory-safety bugs | fuzz-testing skill | fuzzing asserts no-crash implicitly; this skill asserts an explicit property |
+| Measuring whether the test suite catches deliberately-introduced defects | `mutation-testing` | mutation measures test-suite quality; PBT is one technique for producing high-mutation-killing tests |
+| Constructing a state-machine model of the system under test | `state-machine-modeling` (when it exists) | state-machine modeling is its own discipline; stateful PBT is a related but narrower technique |
+| Choosing test levels (unit/integration/e2e) | `testing-strategy` | testing-strategy owns level choices; this skill is a tactical technique within them |
+
+## Key Sources
+
+- Claessen, K., & Hughes, J. (2000). ["QuickCheck: A Lightweight Tool for Random Testing of Haskell Programs"](https://www.cs.tufts.edu/~nr/cs257/archive/john-hughes/quick.pdf). *ICFP 2000*. The foundational paper introducing property-based testing as a discipline; the QuickCheck library it describes is the ancestor of every modern PBT library.
+- Hughes, J. (2007). ["QuickCheck Testing for Fun and Profit"](https://link.springer.com/chapter/10.1007/978-3-540-69611-7_1). *PADL 2007*. The canonical practitioner-oriented introduction to property-based testing patterns.
+- Hughes, J., et al. (2016). ["Mysteries of Dropbox: Property-Based Testing of a Distributed Synchronization Service"](https://ieeexplore.ieee.org/document/7515466). *ICST 2016*. Industrial case study showing PBT's effectiveness on a real distributed system.
+- MacIver, D. R. ["Hypothesis — How does this work?"](https://hypothesis.works/articles/how-hypothesis-works/) and ["The shrinker is the Hypothesis"](https://hypothesis.works/articles/shrinking/). Modern PBT shrinker design; the strongest current open-source implementation.
+- fast-check team. ["fast-check Documentation — Properties"](https://fast-check.dev/docs/core-blocks/properties/). Reference for the most-adopted PBT library in the JavaScript ecosystem.
+- Arts, T., Hughes, J., Johansson, J., & Wiger, U. (2006). ["Testing telecoms software with Quviq QuickCheck"](https://dl.acm.org/doi/10.1145/1159789.1159792). *Erlang Workshop 2006*. Industrial PBT case study; a foundational reference for stateful property testing.
+- Lampropoulos, L., Gallois-Wong, D., Hritcu, C., Hughes, J., Pierce, B. C., & Xia, L. (2017). ["Beginner's Luck: A Language for Property-Based Generators"](https://dl.acm.org/doi/10.1145/3009837.3009868). *POPL 2017*. Recent research on the generator/shrinker design problem.
+- Fink, G., & Bishop, M. (1997). ["Property-based testing: a new approach to testing for assurance"](https://dl.acm.org/doi/10.1145/263244.263267). *ACM SIGSOFT Software Engineering Notes*, 22(4), 74-80. Earlier related thread on properties as a testing discipline.

package/marketplace/skills/prototyping/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: prototyping
+description: "Use when building an artifact whose purpose is to answer a specific question — paper sketch, wireframe, clickable mockup, wizard-of-oz, role-play, service prototype, or code spike — at the lowest fidelity sufficient to produce that learning. Do NOT use for production-grade component construction, design-system contribution, or building the actual ship-ready feature — those are design-module-composition and engineering implementation."
+license: CC-BY-4.0
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"design\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-12\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-12\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"paper prototype\\\\\\\",\\\\\\\"low fidelity prototype\\\\\\\",\\\\\\\"clickable prototype\\\\\\\",\\\\\\\"wizard of oz\\\\\\\",\\\\\\\"role play prototype\\\\\\\",\\\\\\\"service prototype\\\\\\\",\\\\\\\"code spike\\\\\\\",\\\\\\\"learning goal\\\\\\\",\\\\\\\"fidelity matching\\\\\\\",\\\\\\\"throwaway prototype\\\\\\\",\\\\\\\"sacrificial concept\\\\\\\",\\\\\\\"prototype to learn\\\\\\\",\\\\\\\"rough and right\\\\\\\"]\",\"triggers\":\"[\\\\\\\"prototype this\\\\\\\",\\\\\\\"wizard of oz\\\\\\\",\\\\\\\"paper prototype\\\\\\\",\\\\\\\"clickable mockup\\\\\\\",\\\\\\\"what fidelity\\\\\\\"]\",\"examples\":\"[\\\\\\\"Pick the right fidelity for a prototype that tests whether users will trust an AI-suggested category.\\\\\\\",\\\\\\\"Plan a wizard-of-oz study where a human acts as the recommendation engine.\\\\\\\",\\\\\\\"Sketch a role-play prototype for a service-desk interaction before any UI is built.\\\\\\\",\\\\\\\"Decide between a paper prototype and a Figma clickable for this onboarding test.\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"Build the production React component for the new dashboard widget.\\\\\\\",\\\\\\\"Add this component to the design system library.\\\\\\\",\\\\\\\"Write the migration script for the production database.\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"ideation\\\\\\\",\\\\\\\"usability-testing\\\\\\\",\\\\\\\"design-thinking\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"design-module-composition\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"design-module-composition produces durable design-system components meant to ship and be reused. prototyping produces disposable artifacts whose only purpose is learning — different lifecycle, different quality bar, different audience.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"interaction-patterns\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"interaction-patterns is a reference catalog of established UI behaviors. prototyping is the activity of building a thing to test a question — it may use interaction patterns but is not itself a pattern library.\\\\\\\"}]}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/prototyping/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/prototyping/SKILL.md
+---
+
+# Prototyping
+
+## Coverage
+Prototyping covers the practice of constructing artifacts whose primary purpose is to **answer a question** the team has written down. The fidelity ladder runs from **paper sketches** (fastest, cheapest, best for early flow and concept testing) through **wireframes**, **clickable prototypes** (Figma, Framer, similar), **wizard-of-oz** prototypes (a human secretly performs the function the system will eventually automate — Kelley 1984), **role-play / bodystorming** (the team physically acts out a service interaction), **service prototypes** (props and staged environments for service-design questions), and up to **code spikes** (throwaway working code that answers a feasibility question).
+
+The central skill is **fidelity matching**: choosing the lowest fidelity that can credibly answer the learning question. Paper prototypes can answer "is this flow understandable?" but not "is the typography readable?"; a clickable prototype can answer "do users find the primary action?" but not "does this feel fast under load?"; only a code spike can answer "will this API rate-limit us at scale?". Building higher fidelity than the question requires wastes time and prematurely anchors stakeholders on visual decisions.
+
+A complementary skill is **the learning goal contract**: every prototype begins with one or two written questions it is built to answer, and a definition of what evidence would count as an answer in either direction. Without this, prototypes drift into "let's just make it look nice" and the testing session that follows produces ambiguous results because nobody agreed in advance what they were looking for.
+
+The practice also covers **sacrificial concepts** — deliberately rough or extreme prototypes whose purpose is to provoke a reaction, not to be defended. IDEO and the Stanford d.school both teach using disposable artifacts to draw out user preferences that would not surface in abstract conversation.
+
+## Philosophy
+Prototyping rejects the instinct to polish before showing. Polish signals finality; polish makes stakeholders evaluate fit-and-finish instead of concept; polish makes users reluctant to criticize. A rougher prototype invites honest reaction. The famous IDEO maxim "if a picture is worth a thousand words, a prototype is worth a thousand meetings" captures the substitution effect — but only if the prototype is cheap enough that a team can build three and throw two away.
+
+The discipline insists prototypes are means, not ends. A successful prototype is one that produced a clear answer, even if the answer is "this concept doesn't work" — perhaps especially then, because that finding came at the price of a prototype rather than a launched feature. Teams that judge prototypes by their visual quality have inverted the value system; teams that judge them by what was learned have it right.
+
+## Verification
+- The prototype has a written learning question, agreed before construction began, and a definition of what evidence would answer it.
+- The fidelity matches the learning goal — the team can defend why this fidelity was chosen and what a higher- or lower-fidelity version would have cost or gained.
+- The prototype is **disposable** in the team's mind — there is no implicit commitment that this code/file/sketch will become the production artifact.
+- The construction time is small relative to the cost of being wrong about the underlying concept — if a prototype took two weeks to test a one-week assumption, the fidelity was probably too high.
+- The prototype is testable: a real participant can interact with it (or watch it being acted out) and produce a meaningful reaction, not just nod politely.
+- The team has a plan for what happens after testing — either iterate, escalate fidelity, or kill the concept — written down before testing begins.
+
+## Do NOT Use When
+- The artifact will ship to real users in production — that is engineering implementation, not prototyping; even a "high-fi prototype" that ships is a product.
+- The component is meant for reuse across many features and contexts — use **design-module-composition** to contribute to the design system.
+- No learning question has been articulated — return to **problem-framing** or **ideation** to clarify what the prototype would even test.
+- The team needs to evaluate an existing artifact with users — use **usability-testing** directly; no new prototype is required.
+- The question is purely technical performance, scaling, or infrastructure — use an engineering spike with appropriate measurement instrumentation, not a design prototype.
+- The output is a reference catalogue of established UI behaviors — use **interaction-patterns**.

package/marketplace/skills/query-optimization/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: query-optimization
+description: "Use when diagnosing and tuning a specific slow query in a relational database: the query planner mental model (parse → rewrite → plan → execute), the canonical inputs the planner reasons over (statistics, cost model, available indexes), reading EXPLAIN and EXPLAIN ANALYZE output, the catalog of plan-node types (sequential scan, index scan, index-only scan, bitmap heap scan, nested loop, hash join, merge join, sort, hash aggregate, materialize) and what each tells you about the query's actual cost, the difference between query rewriting (reformulating the SQL) and operational fixes (adding indexes, ANALYZE, statistics targets), and the diagnostic procedure that takes a slow query to a fast one. Do NOT use for the design of which indexes to maintain (use indexing-strategy), schema design (use data-modeling), distributed-data partitioning (use sharding-strategy), or isolation-level decisions (use transaction-isolation)."
+license: MIT
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"engineering/data\",\"scope\":\"reference\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-16\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-16\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"comprehension_state\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"query optimization\\\\\\\",\\\\\\\"query planner\\\\\\\",\\\\\\\"EXPLAIN\\\\\\\",\\\\\\\"EXPLAIN ANALYZE\\\\\\\",\\\\\\\"sequential scan\\\\\\\",\\\\\\\"index scan\\\\\\\",\\\\\\\"nested loop\\\\\\\",\\\\\\\"hash join\\\\\\\",\\\\\\\"merge join\\\\\\\",\\\\\\\"query rewriting\\\\\\\",\\\\\\\"statistics\\\\\\\",\\\\\\\"planner cost model\\\\\\\",\\\\\\\"cardinality estimation\\\\\\\"]\",\"triggers\":\"[\\\\\\\"this query is slow\\\\\\\",\\\\\\\"EXPLAIN ANALYZE output\\\\\\\",\\\\\\\"why isn't the planner using the index\\\\\\\",\\\\\\\"join order optimization\\\\\\\",\\\\\\\"subquery vs join\\\\\\\"]\",\"examples\":\"[\\\\\\\"diagnose a query that takes 8 seconds and identify the plan node responsible\\\\\\\",\\\\\\\"rewrite a slow correlated subquery as a join to enable a faster plan\\\\\\\",\\\\\\\"explain why ANALYZE on a recently-changed table can change the planner's decisions\\\\\\\",\\\\\\\"decide whether to add an index, rewrite the query, or accept the cost\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"design which indexes to maintain on a new schema (use indexing-strategy)\\\\\\\",\\\\\\\"choose a database schema (use data-modeling)\\\\\\\",\\\\\\\"decide isolation level for a workload (use transaction-isolation)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"indexing-strategy\\\\\\\",\\\\\\\"data-modeling\\\\\\\",\\\\\\\"transaction-isolation\\\\\\\",\\\\\\\"schema-evolution\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"indexing-strategy\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"indexing-strategy owns the design of which indexes the database has; this skill owns the diagnosis and tuning of specific slow queries. The two compose: query-optimization diagnoses; indexing-strategy is one of the response tools.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"data-modeling\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"data-modeling owns schema and access-pattern design; this skill owns the tuning of queries against the existing schema. Sometimes the diagnosis is 'the schema is wrong for this query'; the response is then in data-modeling's scope.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"transaction-isolation\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"transaction-isolation owns concurrency correctness; this skill owns single-query performance. Sometimes a slow query is slow because of lock contention from isolation; the disciplines intersect on those cases.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"indexing-strategy\\\\\\\",\\\\\\\"data-modeling\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"Query optimization is to a slow SQL query what a medical specialist's chart-reading is to a slow-recovering patient — you do not prescribe before reading the lab values; the plan reads like a chart, every plan node is a vital sign, every cardinality misestimate is a misdiagnosis the planner already made, and your job is to translate the chart into the right intervention rather than the most familiar one.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"Query optimization is the discipline of diagnosing and tuning a specific slow query. The unit of work is one query that the application or a user reported as slow; the goal is identifying the root cause and applying a response (rewrite the SQL, add an index, refresh statistics, denormalize the schema, change the access pattern). The mental model is the query planner — the database component that takes the SQL string, parses it, applies rewrites, considers possible plans, estimates each plan's cost using statistics and a cost model, picks the cheapest, and executes it. EXPLAIN and EXPLAIN ANALYZE expose the planner's choices and their actual cost; reading these is the central diagnostic skill. The work is largely interpretation: knowing what each plan-node type means, what its cost implies, what cardinality misestimation looks like, and which response (rewrite, index, statistics, schema) addresses the diagnosis.\\\\\\\",\\\\\\\"mental_model\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"purpose\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"boundary\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"taxonomy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"analogy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"misconception\\\\\\\":\\\\\\\"|\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/query-optimization/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/query-optimization/SKILL.md
+---
+
+# Query Optimization
+
+## Coverage
+
+The discipline of diagnosing and tuning specific slow queries by reading the database planner's chosen plan, identifying the root cause, and applying the right response. Covers the query planner's phases (parse → rewrite → plan → execute), the cost model and statistics that drive plan choice, the plan-node catalog (Seq Scan, Index Scan, Index Only Scan, Bitmap Heap Scan, Nested Loop, Hash Join, Merge Join, Sort, Hash Aggregate, Materialize, CTE Scan), the EXPLAIN and EXPLAIN ANALYZE diagnostic vocabulary, the response catalog (rewrite, add index, refresh statistics, denormalize, materialized view, isolation change, settings, application cache, accept cost), and the root-cause taxonomy that links diagnosis to response.
+
+## Philosophy
+
+Query optimization is largely a reading discipline. The planner exposes its decisions and the database reports the actual cost; the work is reading EXPLAIN ANALYZE output, knowing what each node means, and choosing the right response. A team that reaches for "add an index" before reading the plan is guessing; a team that reads the plan finds the actual issue and applies the right response — often *not* adding an index.
+
+The most common root cause is cardinality misestimation: the planner thinks 100 rows will match, actually 10 million do. The chosen plan optimized for 100 is wrong for 10 million. ANALYZE, raised statistics targets, and (occasionally) extended statistics objects are where most diagnoses live. Adding indexes without addressing the statistics problem produces no improvement.
+
+The discipline distinguishes diagnosis from response. The diagnosis is "what is the root cause of this query's slowness." The response is "what to do about it." The response catalog has many entries; matching diagnosis to the right one is the work.
+
+## The Diagnostic Procedure
+
+```
+   ┌───────────────────────────┐
+   │ 1. Run EXPLAIN ANALYZE    │
+   └───────────────────────────┘
+              │
+              ▼
+   ┌───────────────────────────┐
+   │ 2. Find the most-expensive│
+   │    plan node (highest     │
+   │    actual time)           │
+   └───────────────────────────┘
+              │
+              ▼
+   ┌───────────────────────────┐
+   │ 3. Compare estimated rows │
+   │    vs actual rows         │
+   └───────────────────────────┘
+              │
+              ▼
+   ┌───────────────────────────────────────────────────────┐
+   │ 4. Choose response based on diagnosis:                │
+   │    estimate ≫ actual  → predicate is more selective   │
+   │                          than planner thinks; may need│
+   │                          extended statistics or       │
+   │                          query rewrite                │
+   │    estimate ≪ actual  → ANALYZE; raise statistics     │
+   │                          target; consider extended    │
+   │                          statistics                   │
+   │    estimate ≈ actual but slow → access path is wrong; │
+   │                          maybe add index, change      │
+   │                          join order, rewrite          │
+   └───────────────────────────────────────────────────────┘
+              │
+              ▼
+   ┌───────────────────────────┐
+   │ 5. Apply response and     │
+   │    re-EXPLAIN ANALYZE     │
+   └───────────────────────────┘
+              │
+              ▼
+   ┌───────────────────────────┐
+   │ 6. Iterate until target   │
+   │    is met                 │
+   └───────────────────────────┘
+```
+
+## The Plan-Node Catalog
+
+| Plan node | What it does | Read as |
+|---|---|---|
+| Seq Scan | Read every row of a table | Slow for large tables; the planner chose this for a reason — check selectivity |
+| Index Scan | Use index to find rows; fetch row | Standard fast access for selective predicates |
+| Index Only Scan | Use covering index; no row fetch | The cheapest read access; index includes all needed columns |
+| Bitmap Heap Scan | Build bitmap from indexes; fetch matching rows | Good for AND of multiple conditions; less random I/O than nested index scans |
+| Nested Loop | For each outer row, scan inner | Fast for small outer or when inner has an index; bad for large outer |
+| Hash Join | Build hash from one side; probe with other | Standard fast equi-join for medium-large inputs |
+| Merge Join | Merge two sorted inputs | Fast when both are pre-sorted on join key (often after Sort or matching indexes) |
+| Sort | Sort rows | Expensive at scale; consider an index or ORDER BY-less query |
+| Hash Aggregate | Group-by via hash table | Fast for moderate cardinality groups |
+| Group Aggregate | Group-by on sorted input | Used after Sort or matching index |
+| Materialize | Materialize intermediate for repeated access | Inserted by planner when sub-result is reused |
+| CTE Scan | Scan CTE result | CTE may be optimization fence in older Postgres |
+
+## Response Catalog
+
+| Diagnosis | Right response |
+|---|---|
+| Sequential scan on large table; predicate is selective | Add index |
+| Sequential scan; predicate is poorly selective | Accept (scan is right) or denormalize |
+| Index Scan with high `Rows Removed by Filter` | Index doesn't match — partial index or composite |
+| Estimated rows ≫ actual | Check if predicate is more selective than planner knows; extended statistics or rewrite |
+| Estimated rows ≪ actual | ANALYZE; raise STATISTICS target |
+| Nested Loop with large outer | Hint hash join or rewrite to enable hash plan |
+| Hash Join with small outer | Should be nested loop with index — check why |
+| Many Sort nodes | Add index matching ORDER BY |
+| N+1 query pattern (application-side) | Replace with single join query |
+| Correlated subquery slow | Rewrite as join or EXISTS |
+| Query slow under concurrency, fast solo | Lock contention — check isolation, locking strategy |
+| Stale statistics suspected | ANALYZE; consider auto-vacuum tuning |
+| Query is fundamentally too much work | Materialized view, precomputed aggregate, schema change |
+
+## Verification
+
+After applying this skill, verify:
+- [ ] EXPLAIN ANALYZE is the starting point for every slow-query investigation. Guessing without reading the plan is replaced by reading the plan.
+- [ ] The most-expensive plan node is identified and the diagnosis is targeted at that node, not the query as a whole.
+- [ ] Estimated rows vs actual rows is checked at every node. Cardinality misestimates are the most common root cause.
+- [ ] The response matches the diagnosis. Adding an index is one response of many; the team is not reflexively adding indexes.
+- [ ] Slow queries are prioritized by aggregate impact (frequency × duration), not by individual duration alone. pg_stat_statements or equivalent is consulted.
+- [ ] Query rewrites are tested for semantic equivalence and plan-shape change. Two queries that "should be equivalent" can produce different plans.
+- [ ] Statistics are refreshed (ANALYZE) before deeper investigation when the planner's estimates seem off. Stale statistics are routine after bulk inserts and schema changes.
+- [ ] Periodic review of top queries detects regressions caused by data growth. A query that was fast last year may not be this year.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Designing which indexes the database maintains | `indexing-strategy` | indexing-strategy owns design; this skill diagnoses |
+| Designing the schema or entity relationships | `data-modeling` | data-modeling owns design; sometimes the answer is a schema change in its scope |
+| Reasoning about how schema changes over time | `schema-evolution` | schema-evolution owns versioning; this owns query-level tuning |
+| Choosing isolation level | `transaction-isolation` | transaction-isolation owns concurrency; this owns retrieval performance |
+| Horizontal partitioning across nodes | `sharding-strategy` | sharding owns partition; this owns within-shard performance |
+| Designing performance tests for the system | `performance-testing` | performance-testing owns measurement under load; this owns single-query tuning |
+
+## Key Sources
+
+- PostgreSQL Global Development Group. ["PostgreSQL Documentation — Performance Tips"](https://www.postgresql.org/docs/current/performance-tips.html) and ["Using EXPLAIN"](https://www.postgresql.org/docs/current/using-explain.html). The canonical reference for Postgres query planning and EXPLAIN interpretation.
+- Kleppmann, M. (2017). *Designing Data-Intensive Applications*. O'Reilly. Chapter 3 (Storage and Retrieval) covers the storage structures underlying query execution; useful framing for why plans take the shape they do.
+- Petrov, A. (2019). *Database Internals*. O'Reilly. Deep treatment of query execution, the cost model, and plan generation.
+- Tow, D. (2003). *SQL Tuning*. O'Reilly. The classic practitioner reference on diagnosing slow queries; database-agnostic methodology that applies across systems.
+- Winand, M. (2012, ongoing). [*Use The Index, Luke!*](https://use-the-index-luke.com/). The canonical practitioner guide to SQL indexing, with substantial treatment of how indexes interact with the planner.
+- Microsoft. ["Query Tuning Assistant and Query Store"](https://learn.microsoft.com/en-us/sql/relational-databases/performance/query-store). Reference for SQL Server's query-performance tooling.
+- Oracle. ["Query Optimizer Concepts"](https://docs.oracle.com/database/121/TGSQL/tgsql_optcncpt.htm). Reference for Oracle's cost-based optimizer.
+- MySQL Reference Manual. ["EXPLAIN Output Format"](https://dev.mysql.com/doc/refman/8.0/en/explain-output.html). MySQL EXPLAIN reference.
+- Selinger, P. G., Astrahan, M. M., Chamberlin, D. D., Lorie, R. A., & Price, T. G. (1979). ["Access Path Selection in a Relational Database Management System"](https://dl.acm.org/doi/10.1145/582095.582099). *SIGMOD 1979*. The foundational paper on cost-based query optimization (System R); historical reference for the discipline's origin.