@skill-graph/cli 0.5.6

package/marketplace/skills/compression/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: compression
+description: "This skill provides expertise in data and context compression: SaaS payload optimization (Zstd, Brotli, Gzip), database storage compression, and AI context window compression (Semantic Summarization, Token Pruning). Use when optimizing API latency, reducing storage costs, or managing long-running agent sessions near context limits. Do NOT use for image/video lossy compression (use product-photo) or file archiving."
+license: MIT
+compatibility: "Markdown, Git, agent-skill runtimes"
+allowed-tools: Read Grep Bash
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"engineering/data\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-03-28\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-03-28\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"compression\\\\\\\",\\\\\\\"Zstd\\\\\\\",\\\\\\\"Brotli\\\\\\\",\\\\\\\"Gzip\\\\\\\",\\\\\\\"context window\\\\\\\",\\\\\\\"token efficiency\\\\\\\",\\\\\\\"semantic summarization\\\\\\\",\\\\\\\"payload reduction\\\\\\\",\\\\\\\"DB TOAST\\\\\\\"]\",\"triggers\":\"[\\\\\\\"compression-skill\\\\\\\",\\\\\\\"context-compression\\\\\\\",\\\\\\\"payload-optimization\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"context-window\\\\\\\"],\\\\\\\"boundary\\\\\\\":[\\\\\\\"context-management\\\\\\\",\\\\\\\"summarization\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":90,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"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/compression/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/compression/SKILL.md
+---
+# Compression
+
+## Domain Context
+
+**What is this skill?** This skill provides expertise in data and context compression: SaaS payload optimization (Zstd, Brotli, Gzip), database storage compression, and AI context window compression (Semantic Summarization, Token Pruning). Use when optimizing API latency, reducing storage costs, or managing long-running agent sessions near context limits. Do NOT use for image/video lossy compression (use product-photo) or file archiving.
+
+## Key Files
+
+| File                                                 | Purpose                                                                                  |
+| ---------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `skills/token-efficiency/SKILL.md`                   | Adjacent authority for prompt and token-budget compression strategy.                     |
+| `skills/context-window/SKILL.md`                     | Adjacent authority for compaction timing and context-budget math.                        |
+| `scripts/hooks/pre-compact-hook.py`                  | Pre-compaction persistence hook that preserves state before context compression.         |
+| `scripts/session/session-ctl.js`                     | Session-control CLI that exposes wrap, clear, and continue operations around compaction. |
+| `docs/reference/session-control-wrapper-contract.md` | Canonical session-control contract covering wrap, clear, compact, and resume semantics.  |
+| `agent-orchestration/ONBOARDING.md`                  | Workflow context for how session-control and continuation fit the orchestration flow.    |
+
+## Coverage
+
+SaaS payload compression (Zstd, Brotli, Gzip algorithm selection, level tuning, content negotiation), PostgreSQL storage compression (TOAST with Zstd, application-layer blob compression), and AI context window compression (semantic summarization, token pruning, dead context identification, state re-injection). Covers the decision tree for matching algorithms to data types, the `Accept-Encoding` negotiation order, and the three-phase token pruning workflow.
+
+## Philosophy
+
+Compression is the science of increasing information density. In a modern SaaS, it applies at two layers: the **Infrastructure Layer** (reducing bytes on the wire/disk) and the **Intelligence Layer** (reducing tokens in the context window). Without this skill, agents default to generic compression advice that ignores the specific algorithm-to-data-type mapping (e.g., using Gzip everywhere instead of Zstd for dynamic API payloads) and fail to recognize that sub-1KB payloads should skip compression entirely. On the intelligence side, agents routinely let context windows bloat with dead research turns instead of applying structured summarization that preserves evidence paths.
+
+## 1. SaaS Data Compression Decision Tree
+
+Match the compression algorithm to the data type and lifecycle.
+
+| Data Type                  | Recommended              | Why?                                                       |
+| -------------------------- | ------------------------ | ---------------------------------------------------------- |
+| **Static Assets** (JS/CSS) | Brotli (Level 11)        | Highest ratio for web strings; slow build-time OK.         |
+| **Dynamic API** (JSON)     | Zstd (Level 3)           | Fastest decompression; lower TTFB than Gzip.               |
+| **Small Payloads** (<1KB)  | None / Custom Dictionary | Compression overhead often increases size for small items. |
+| **Large DB Columns**       | Zstd (TOAST)             | Postgres 14+ native support; high speed/low I/O.           |
+
+### Implementation Rules
+
+- **Negotiation**: Always check `Accept-Encoding` header. Order: `zstd` > `br` > `gzip`.
+- **Level Selection**: Use Level 3 for dynamic runtime; Level 11 for static build-time.
+- **Header Safety**: Ensure `Vary: Accept-Encoding` is set to prevent cache pollution.
+
+## 2. AI Context Compression
+
+Protect the context window by maximizing token density.
+
+### Semantic Summarization
+
+- **Pattern**: Replace raw logs/code with high-density Markdown summaries.
+- **Rule**: A summary must preserve **Intent**, **Outcome**, and **Evidence Paths** while removing boilerplate.
+
+### Token Pruning (The "Surgical Cut")
+
+- **Phase 1**: Identify "Dead Context" (e.g., redundant file reads, failed research turns).
+- **Phase 2**: Use `/clear` or `/compact` to drop the bottom 50% of the session history.
+- **Phase 3**: Re-inject the "State of the Union" summary via Memory MCP.
+
+> **Source**: `skills/token-efficiency/SKILL.md` (Adjacent)
+
+## 3. Storage Compression (Postgres)
+
+Optimize for cost and performance at the database layer.
+
+- **TOAST Compression**: Set `default_toast_compression = 'zstd'` for large JSONB fields.
+- **Blob Compression**: For extremely large blobs (>10MB), compress in the application layer (Node.js `zstd` bindings) before storing as `BYTEA`.
+
+## 4. Verification Checklist
+
+```text
+COMPRESSION CHECK
+=================
+[ ] Static assets pre-compressed with Brotli (Level 11)
+[ ] API middleware supports Zstd with Gzip fallback
+[ ] Vary: Accept-Encoding header present
+[ ] AI context summary preserves Evidence Paths
+[ ] redundant research/file reads pruned from session
+[ ] DB compression matches Postgres version (Zstd if 14+)
+[ ] Payloads < 1KB skip compression to avoid overhead
+```
+
+## Verification
+
+After applying this skill, verify:
+
+- [ ] Algorithm matches data type per the decision tree (static=Brotli, dynamic API=Zstd, DB=TOAST Zstd)
+- [ ] `Accept-Encoding` negotiation respects the `zstd > br > gzip` priority order
+- [ ] `Vary: Accept-Encoding` header is set to prevent cache pollution
+- [ ] Small payloads (<1KB) are not compressed (overhead exceeds savings)
+- [ ] Context summaries preserve Intent, Outcome, and Evidence Paths
+- [ ] Token pruning removes dead context (failed research turns, redundant reads) before injecting fresh state
+
+## Do NOT Use When
+
+| Instead of this skill                                                           | Use                     | Why                                                                                 |
+| ------------------------------------------------------------------------------- | ----------------------- | ----------------------------------------------------------------------------------- |
+| Image/video lossy compression (JPEG quality, WebP, AVIF format selection)       | `product-photo`         | product-photo owns the image pipeline and format selection logic                    |
+| Agent session lifecycle (when to compact, context budgets, compaction triggers) | `context-management`    | context-management owns session-level compaction strategy and budget allocation     |
+| Token budget allocation and prompt compression techniques                       | `token-efficiency`      | token-efficiency owns the token budget framework; compression handles the mechanics |
+| Credential encryption at rest                                                   | `credential-encryption` | credential-encryption covers AES-256-GCM patterns, not data compression             |

package/marketplace/skills/conceptual-modeling/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: conceptual-modeling
+description: "Use when translating business requirements into a structured domain model before database schemas, API endpoints, or DDD aggregates are named. Covers entities, attributes, relationships, cardinality, specialization/generalization, aggregation/composition, roles, abstraction levels, stakeholder validation, and modeling anti-patterns such as implementation leakage, god entities, phantom relationships, premature normalization, attribute-as-entity, and unnamed relationships. Do NOT use for database ER diagrams with keys and normalization, formal ontology axioms with OWL/RDFS, or DDD tactical design; use those dedicated skills instead."
+license: MIT
+compatibility: "Domain- and language-agnostic. The conceptual / logical / physical ladder applies across relational, document, graph, and event-sourced systems."
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"engineering/modeling\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-06\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-06\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"conceptual model\\\\\\\",\\\\\\\"conceptual modeling methodology\\\\\\\",\\\\\\\"domain abstraction\\\\\\\",\\\\\\\"entity relationship cardinality\\\\\\\",\\\\\\\"conceptual schema before implementation\\\\\\\",\\\\\\\"business model to system model\\\\\\\",\\\\\\\"generalization specialization\\\\\\\",\\\\\\\"aggregation composition relationship\\\\\\\",\\\\\\\"reify relationship to entity\\\\\\\",\\\\\\\"conceptual logical physical layers\\\\\\\",\\\\\\\"implementation leakage anti-pattern\\\\\\\",\\\\\\\"unnamed relationship anti-pattern\\\\\\\",\\\\\\\"god entity anti-pattern\\\\\\\",\\\\\\\"missing entity anti-pattern\\\\\\\",\\\\\\\"validate model with stakeholders\\\\\\\",\\\\\\\"UML class diagram conceptual\\\\\\\",\\\\\\\"role modeling pattern\\\\\\\",\\\\\\\"is-a vs has-a vs owns\\\\\\\"]\",\"examples\":\"[\\\\\\\"a stakeholder says 'users place orders that ship in multiple boxes' — how do I capture this as a model before naming tables?\\\\\\\",\\\\\\\"is a refund its own entity or just a payment status — what conceptual test decides that?\\\\\\\",\\\\\\\"two business stakeholders disagree on whether a cart and an order are the same thing — how should the conceptual model resolve that?\\\\\\\",\\\\\\\"our domain diagram already mentions UUIDs and cascade-delete — what anti-pattern is that and how do I pull it back?\\\\\\\",\\\\\\\"this relationship has a date, an amount, and a status — should it stay as a line between entities or become its own entity?\\\\\\\",\\\\\\\"should this attribute live on the Customer entity or on Order — what's the rule?\\\\\\\",\\\\\\\"we have Physical, Digital, and Subscription products — how do I model that as generalization without lying about totality?\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"give me the physical table design with PKs, FKs, and normalization forms\\\\\\\",\\\\\\\"I need OWL class axioms and reasoning constraints for these concepts\\\\\\\",\\\\\\\"build the DDD aggregate boundaries and anti-corruption layer\\\\\\\",\\\\\\\"what hypernymy / meronymy labels apply between these terms\\\\\\\",\\\\\\\"review this ORM model class for code correctness\\\\\\\",\\\\\\\"name the entities and fields once we agree on the conceptual model\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"code-review\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"code-review evaluates implementation output; conceptual-modeling is the pre-implementation domain analysis above it\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"naming-conventions\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"naming-conventions decides what to call entities and fields; conceptual-modeling decides what entities and fields exist in the first place\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"refactor\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"refactor preserves behavior while restructuring code; conceptual-modeling restructures the domain abstraction itself, which usually requires non-behavior-preserving change\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"naming-conventions\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":365,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"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/conceptual-modeling/SKILL.md\",\"skill_graph_export_description\":\"shortened for Agent Skills 1024-character description limit; canonical source keeps the full routing contract\",\"skill_graph_canonical_description_length\":\"1044\"}"
+  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/conceptual-modeling/SKILL.md
+---
+
+# Conceptual Modeling
+
+## Coverage
+
+Methodology for abstracting a real-world domain into a structured representation _before_ any database table, API endpoint, or aggregate boundary is named. Identifies entities (distinguishable things the business tracks), attributes (properties that describe an entity), and relationships (meaningful connections between entities). Specifies cardinality (1:1, 1:N, M:N, 0..1, 1..\*); distinguishes association from aggregation from composition; uses generalization / specialization with disjoint / overlapping and total / partial constraints; recognizes when an associative relationship needs to be reified into its own entity (e.g. an enrollment between Student and Course that carries grade and date). Walks the conceptual → logical → physical abstraction ladder. Validates models against business stakeholders' mental models via walk-through, scenario testing, negative testing, and terminology audit. Names the seven anti-patterns: implementation leakage, missing entity, god entity, phantom relationship, premature normalization, attribute-as-entity, unnamed relationship.
+
+## Philosophy
+
+Every software system is a model of some real-world domain. The quality of that model determines whether the system helps or hinders its users. Without explicit conceptual modeling, the team jumps directly from requirements to code — encoding implicit assumptions that surface later as architectural debt. A requirement like "users can place orders" hides dozens of decisions: is a cart an order? can an order have multiple shipments? is a refund a new entity or a state of a payment? Conceptual modeling forces those decisions to the surface _before_ code exists, so rework happens on a whiteboard rather than across a migration.
+
+The discipline is anti-rigid in a specific way. Conceptual modeling stays one layer _above_ logical modeling (tables, foreign keys, normalization) and one layer _above_ DDD tactical design (aggregates, bounded contexts, anti-corruption layers). The moment the model speaks of UUIDs, indexes, or cascade behavior, it has fallen into logical modeling. The moment it prescribes aggregates or anti-corruption layers, it has crossed into DDD. Conceptual modeling's job is earlier and narrower: capture the domain structure clearly enough that those later design layers can proceed without guessing about the business.
+
+## 1. The Three-Level Architecture
+
+| Level          | Purpose                                          | Audience                                | Notation                                                       |
+| -------------- | ------------------------------------------------ | --------------------------------------- | -------------------------------------------------------------- |
+| **Conceptual** | What exists in the business domain               | Business stakeholders, product managers | Simplified UML class diagrams, entity lists, relationship maps |
+| **Logical**    | How the data is structured, platform-independent | Architects, senior developers           | Normalized schemas, interface contracts, type hierarchies      |
+| **Physical**   | How the data is stored and accessed              | Database engineers, backend developers  | SQL DDL, index strategies, partition schemes                   |
+
+Rules:
+
+- Always build conceptual _before_ logical. Jumping straight to physical (tables, columns) from raw requirements produces brittle, business-disconnected schemas that fail their first feature change.
+- Conceptual models must be readable by non-technical stakeholders. If a business user cannot validate the model, the model is too detailed.
+- Each level _adds_ implementation detail. None should _remove_ business meaning. If something disappears as you move down, the lower layer has dropped a constraint that the business actually has.
+
+## 2. Core Modeling Constructs
+
+### 2.1 Entities and attributes
+
+| Element                    | Definition                                  | Modeling rule                                                                     |
+| -------------------------- | ------------------------------------------- | --------------------------------------------------------------------------------- |
+| **Entity**                 | A distinguishable thing the business tracks | Must have identity criteria — what makes two X's "the same"?                      |
+| **Attribute**              | A property that describes an entity         | Belongs to exactly one entity; if it's shared, you've discovered a missing entity |
+| **Derived attribute**      | A value computed from other attributes      | Mark explicitly; never store without documenting the derivation                   |
+| **Multi-valued attribute** | An attribute with multiple values           | Usually signals a missing child entity or collection                              |
+
+### 2.2 Relationships
+
+| Type                      | Notation (UML)                  | When to use                                                 |
+| ------------------------- | ------------------------------- | ----------------------------------------------------------- |
+| **Association**           | Plain line between entities     | Two entities are meaningfully connected                     |
+| **Aggregation** (has-a)   | Open diamond                    | Whole-part where parts can exist independently of the whole |
+| **Composition** (owns)    | Filled diamond                  | Whole-part where parts cannot exist without the whole       |
+| **Generalization** (is-a) | Triangle arrow toward supertype | Subtype inherits supertype properties                       |
+| **Dependency**            | Dashed arrow                    | One entity uses another without owning it                   |
+
+### 2.3 Cardinality
+
+| Pattern | Reading                    | Example                                                              |
+| ------- | -------------------------- | -------------------------------------------------------------------- |
+| 1:1     | Exactly one to exactly one | User has one Profile                                                 |
+| 1:N     | One to many                | Customer places many Orders                                          |
+| M:N     | Many to many               | Products belong to many Categories; Categories contain many Products |
+| 0..1    | Optional one               | Order may have zero or one Refund                                    |
+| 1..\*   | One or more (mandatory)    | Order has at least one LineItem                                      |
+
+Rules:
+
+- Every relationship must have explicit cardinality. Unmarked relationships are ambiguous and will be implemented incorrectly half the time.
+- M:N relationships in the conceptual model often become junction entities in the logical model — especially once they acquire their own attributes.
+- Optional vs mandatory is a _business_ decision, not a technical one. Validate with stakeholders who actually know which orders can ship without addresses.
+
+## 3. Generalization and Specialization
+
+### When to generalize (bottom-up)
+
+- Multiple entities share roughly 70%+ of their attributes
+- Business users refer to them with a common name ("all our products, whether physical or digital")
+- Operations apply uniformly ("ship any order, regardless of type")
+
+### When to specialize (top-down)
+
+- A single entity has attributes or behaviors that apply only to some of its instances
+- Business rules differ by subtype ("digital products don't need shipping addresses")
+- The type distinction drives different processing paths
+
+### Specialization constraints
+
+| Constraint      | Meaning                                                    | Example                                                           |
+| --------------- | ---------------------------------------------------------- | ----------------------------------------------------------------- |
+| **Disjoint**    | An instance belongs to _exactly one_ subtype               | A payment is either a CardPayment or a BankTransfer, never both   |
+| **Overlapping** | An instance can belong to _multiple_ subtypes              | A user can be both a Seller and a Buyer                           |
+| **Total**       | Every supertype instance belongs to _at least one_ subtype | Every Product is either Physical or Digital — no untyped Products |
+| **Partial**     | Some supertype instances may not be specialized            | A User may not yet be a Seller or a Buyer                         |
+
+Each pair (disjoint vs overlapping) and (total vs partial) is independent — pick one from each pair for every generalization.
+
+## 4. Abstraction Strategies
+
+| Strategy           | When to use                           | Risk if skipped                                                                                                         |
+| ------------------ | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| **Classification** | Grouping instances into types         | Too many ad-hoc types; inconsistent behavior                                                                            |
+| **Aggregation**    | Composing wholes from parts           | Flat structures that lose structural meaning                                                                            |
+| **Generalization** | Finding common supertypes             | Duplicated attributes and logic across subtypes                                                                         |
+| **Association**    | Connecting related entities           | Implicit relationships buried in code                                                                                   |
+| **Reification**    | Promoting a relationship to an entity | Important relationship attributes get lost (e.g., an Enrollment between Student and Course that carries grade and date) |
+
+Rules:
+
+- Reify a relationship when it has its _own_ attributes, lifecycle, or identity.
+- If an association carries a date, status, or amount, it is probably an entity in disguise.
+
+## 5. Validating the Model with Stakeholders
+
+| Method                | What it catches                                                                                                    |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| **Walk-through**      | Read each relationship aloud: "A Customer places one or more Orders." If it sounds wrong, the model is wrong.      |
+| **Scenario testing**  | Trace a real business scenario through the model. Every step should map to a model element.                        |
+| **Negative testing**  | Try to represent something the business says is impossible. If the model permits it, a constraint is missing.      |
+| **Terminology audit** | Every entity name should match what business users actually call it. Rename to match — never the other way around. |
+
+If a business user can't read the model and recognise their own domain, the model is documentation theatre. Re-do it.
+
+## 6. Anti-Patterns
+
+| Anti-pattern                | Symptom                                                                    | Fix                                                                        |
+| --------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| **Implementation leakage**  | Conceptual model talks about tables, columns, indexes, foreign keys        | Strip all physical terminology; use entity / attribute / relationship      |
+| **Missing entity**          | An attribute stores a comma-separated list, encoded compound, or JSON blob | Extract into a proper entity with its own identity                         |
+| **God entity**              | One entity with 30+ attributes spanning multiple business concerns         | Decompose by business responsibility                                       |
+| **Phantom relationship**    | Two entities are connected and no one can explain why                      | Remove it — relationships must serve a stated business purpose             |
+| **Premature normalization** | The conceptual model is already in 3NF                                     | Normalization belongs in the logical model, not here                       |
+| **Attribute-as-entity**     | "Color" has its own entity with just a name attribute                      | Keep as an attribute or enum unless it has its own properties or lifecycle |
+| **Unnamed relationship**    | Lines between entities with no verb / role label                           | Every relationship needs a name a business user can validate               |
+
+## 7. From Conceptual to Implementation
+
+The conceptual model is consumed by downstream layers. Track the typical translations so the conceptual model stays implementation-neutral:
+
+| Conceptual element           | Logical / physical translation                                              |
+| ---------------------------- | --------------------------------------------------------------------------- |
+| Entity                       | Type / class / interface, database table, API resource                      |
+| Attribute                    | Property / field, database column                                           |
+| 1:N relationship             | Foreign key on the N side                                                   |
+| M:N relationship             | Junction table with two foreign keys (often itself an entity at this layer) |
+| Generalization (disjoint)    | Discriminated union, single-table inheritance, or class-table inheritance   |
+| Generalization (overlapping) | Multiple junction tables or role-based flags                                |
+| Composition                  | Cascade-delete on parent, nested API resource                               |
+| Aggregation                  | Set-null on parent, independent API resource                                |
+| Derived attribute            | Computed column, getter, or materialized view                               |
+
+These translations are _informational_ — the conceptual model itself stays neutral. Naming the translations explicitly avoids the trap of authoring a "conceptual" model that has already pre-decided the physical layer.
+
+## Verification
+
+- [ ] Every relationship has a name (verb or role label) — not just lines between boxes
+- [ ] Cardinality is specified on every relationship (1:1, 1:N, M:N, 0..1, 1..\*)
+- [ ] Aggregation, composition, and plain association are explicitly distinguished where relevant
+- [ ] The model is free of physical terminology (no tables, columns, indexes, foreign keys, cascade, normalization)
+- [ ] Generalization / specialization uses the correct disjoint / overlapping and total / partial pair
+- [ ] Business stakeholders have read the model and validated it against their domain
+- [ ] No M:N relationship hides an entity-worthy junction concept (i.e., one with its own attributes)
+- [ ] No attribute stores compound, multi-valued, or encoded data
+- [ ] Every entity has explicit identity criteria — "what makes two X's the same"
+- [ ] Every entity name matches the term the business actually uses
+
+## Do NOT Use When
+
+| Use instead                                                | When                                                                                                                     |
+| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| A logical / physical modeling skill (database-specific ER) | You need PKs, FKs, normalization forms, index strategies — the layer below conceptual                                    |
+| An ontology skill                                          | You need OWL axioms, RDFS class hierarchies, formal reasoning constraints — the layer above human-readable conceptual    |
+| A DDD / domain-modeling skill                              | You need bounded-context boundaries, aggregates, anti-corruption layers — DDD tactical design                            |
+| `naming-conventions`                                       | The conceptual model is settled; you now need to decide what to _call_ the entities and fields in code                   |
+| `code-review`                                              | You are reviewing code that already implements the model — conceptual modeling is the upstream activity                  |
+| `documentation`                                            | You need to _describe_ an existing system in prose for a human reader, not abstract a new domain into a structured model |

package/marketplace/skills/connection-pooling/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: connection-pooling
+description: "Use when reasoning about how an application manages its database connections: why every connection has a server-side cost, the difference between application-level pools (HikariCP, pgx pool, node-postgres Pool) and proxy-level pools (PgBouncer, Pgpool, ProxySQL), the three PgBouncer modes (session, transaction, statement) and their feature compatibility, the canonical pool-sizing math (Little's Law applied to database concurrency; Wooldridge's analyses), the failure modes (connection exhaustion, hot-loop reconnects, prepared-statement breakage under transaction pooling, idle-in-transaction leaks), and the diagnostic procedure when a workload is contending on connections instead of query work. Do NOT use for query-level performance (use query-optimization), for index design (use indexing-strategy), for read/write replica routing (use replication-patterns), or for cross-shard query coordination (use sharding-strategy)."
+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\":\"[\\\\\\\"connection pooling\\\\\\\",\\\\\\\"PgBouncer\\\\\\\",\\\\\\\"HikariCP\\\\\\\",\\\\\\\"pool sizing\\\\\\\",\\\\\\\"session pooling\\\\\\\",\\\\\\\"transaction pooling\\\\\\\",\\\\\\\"statement pooling\\\\\\\",\\\\\\\"prepared statements\\\\\\\",\\\\\\\"idle in transaction\\\\\\\",\\\\\\\"Little's Law\\\\\\\",\\\\\\\"max_connections\\\\\\\",\\\\\\\"serverless databases\\\\\\\"]\",\"triggers\":\"[\\\\\\\"what should max pool size be\\\\\\\",\\\\\\\"PgBouncer transaction mode\\\\\\\",\\\\\\\"too many connections error\\\\\\\",\\\\\\\"connection exhaustion\\\\\\\",\\\\\\\"prepared statements not working with PgBouncer\\\\\\\"]\",\"examples\":\"[\\\\\\\"size a connection pool for a workload with N application servers and M cores per database\\\\\\\",\\\\\\\"diagnose why a workload is bottlenecked on connections rather than query performance\\\\\\\",\\\\\\\"decide between PgBouncer session mode and transaction mode for an application\\\\\\\",\\\\\\\"explain why HikariCP recommends small pools instead of large ones\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"tune a slow query (use query-optimization)\\\\\\\",\\\\\\\"design indexes (use indexing-strategy)\\\\\\\",\\\\\\\"route reads to a replica (use replication-patterns)\\\\\\\",\\\\\\\"design partitioning across shards (use sharding-strategy)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"query-optimization\\\\\\\",\\\\\\\"replication-patterns\\\\\\\",\\\\\\\"sharding-strategy\\\\\\\",\\\\\\\"transaction-isolation\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"query-optimization\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"query-optimization owns the cost of individual query work; this skill owns the cost of having a connection at all. A workload contending on connections has different symptoms than a workload contending on query work, and the diagnostic discipline differs.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"replication-patterns\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"replication-patterns owns the routing of reads and writes across replicas; this skill owns the connection layer beneath that routing. They compose: a pooled architecture often pools to each replica separately.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"sharding-strategy\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"sharding-strategy owns how data is partitioned across nodes; this skill owns how application connections to those nodes are pooled. A sharded architecture multiplies the pool-sizing surface — one pool per shard.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"transaction-isolation\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"transaction-isolation owns the per-transaction concurrency-correctness contract; this skill owns the connection-level mechanics that determine whether a transaction's connection is held, released, or shared. PgBouncer's transaction mode in particular interacts with isolation level and session state.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"query-optimization\\\\\\\",\\\\\\\"replication-patterns\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"A connection pool is to a database what a taxi rank is to an airport — every taxi has a standing cost (driver salary, fuel, parking space); a rank with too few taxis leaves passengers queuing on the curb; a rank with too many burns money on idle taxis and clogs the access road. The right number is the smallest that doesn't queue under peak arrival rate, sized by how long each taxi trip actually takes — and adding more taxis doesn't make the trips faster, it just lets more start at once.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"Connection pooling is the discipline of managing a finite set of database connections shared across many application threads, requests, or processes, because opening a database connection is expensive (network round-trips, authentication, session setup) and every open connection consumes server resources (a process or thread, memory for buffers and catalog state, locks on shared structures). The pool's job is to keep a small, sized-for-workload number of connections open, hand them out to application units of work for the brief time they need them, and return them to the pool. Pooling can happen at the application layer (in-process pool like HikariCP, pgx pool, node-postgres Pool) or at the proxy layer (an external service like PgBouncer or ProxySQL that multiplexes many client connections onto a smaller set of upstream database connections). The pooling mode (session, transaction, statement) determines what feature compatibility the pool preserves and what failure modes the application must handle. The pool size is a *throughput cap*, not a resource budget; sizing it correctly per Little's Law (concurrency = throughput × latency) is the central operational decision.\\\\\\\",\\\\\\\"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/connection-pooling/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/connection-pooling/SKILL.md
+---
+
+# Connection Pooling
+
+## Coverage
+
+The discipline of managing a finite set of database connections shared across many application threads, requests, or processes. Covers the connection cost (server-side process/thread, memory, locks), why pooling is required (open-cost amortization, throughput cap, load-shedding), application-level vs proxy-level pools, the three PgBouncer modes (session, transaction, statement) and their feature compatibility, the canonical pool-sizing math via Little's Law and HikariCP's analyses, the failure modes catalog (connection exhaustion, idle-in-transaction, hot-loop reconnect, prepared-statement breakage, cross-connection state leaks, long-tail accumulation), the operational concerns (wait-time monitoring, connection rotation, reconnect backoff, health checks), and the database-specific connection models (Postgres process-per-connection, MySQL thread-per-connection, serverless variants).
+
+## Philosophy
+
+The pool is a throughput throttle, not a resource budget. Sizing too large doesn't make slow queries faster — it makes the database thrash and shifts the symptom from "queue waiting for connection" to "queue waiting for CPU, buffer cache, or locks." Sizing too small produces queue waits. The right size is the smallest pool that doesn't queue under peak load — typically much smaller than teams initially set.
+
+Pooling mode determines feature surface. The choice between session, transaction, and statement pooling is not just operational — it determines what features the application is allowed to use at the database. Transaction pooling buys multiplexing in exchange for session-feature loss; statement pooling buys further multiplexing in exchange for transaction loss. Knowing which features the application uses, and the cross-product against the pooling mode, is preconditional to choosing a mode.
+
+The pool is the place where database-level health becomes application-level latency. A workload contending on the pool surfaces as request queueing in the application, not as slow queries in the database log. Pool instrumentation (`pool.active`, `pool.idle`, `pool.waiting`, `pool.acquire_time`) is the operational hygiene that makes contention legible.
+
+## Sizing — Little's Law in Practice
+
+**Little's Law:** concurrency = arrival rate × average service time.
+
+| Workload | Arrival rate | Avg query time | Concurrency | Pool size |
+|---|---|---|---|---|
+| OLTP point query | 10,000 req/sec | 1 ms | 10 | 12–15 |
+| OLTP transaction | 1,000 req/sec | 10 ms | 10 | 12–15 |
+| Mixed read/write | 2,000 req/sec | 25 ms | 50 | 60–80 |
+| Analytical | 100 req/sec | 500 ms | 50 | Pool partitioning recommended |
+
+The pool size is *peak concurrency + small headroom*. Teams that size by request rate (treating pool size as a per-app-server quota) over-size by 10x or more, then discover the database is thrashing.
+
+**HikariCP's documented advice:** start with `cores * 2 + effective_spindle_count` (e.g., 8 cores → pool size 18); raise only when measured queue waits prove a larger pool helps. Most OLTP pools are <20 per app instance.
+
+## PgBouncer Mode Matrix
+
+| Feature | Session | Transaction | Statement |
+|---|---|---|---|
+| Prepared statements (server-side) | ✅ | ✅ (1.21+) / ❌ (pre-1.21) | ❌ |
+| `SET` session variables | ✅ | ❌ (use `SET LOCAL`) | ❌ |
+| `SET LOCAL` (transaction-scoped) | ✅ | ✅ | ❌ |
+| Advisory locks | ✅ | ❌ | ❌ |
+| `LISTEN` / `NOTIFY` | ✅ | ❌ | ❌ |
+| `WITH HOLD` cursors | ✅ | ❌ | ❌ |
+| Temporary tables across transactions | ✅ | ❌ | ❌ |
+| Transactions | ✅ | ✅ | ❌ |
+| Multiplexing benefit | 1x | High (10–100x) | Highest |
+
+**Default rule:** Transaction mode for production scale; verify the application uses no session-spanning features (or, if it does, audit each one). Session mode when full Postgres feature surface is required.
+
+## The Failure Modes Catalog
+
+| Symptom | Likely cause | First diagnostic |
+|---|---|---|
+| `too many connections` error | Pool size × instances > `max_connections`; reconnect storm | Sum app pools + replica pools; check reconnect rate |
+| Request latency spike, query latency normal | Pool exhaustion (queries holding connections too long) | `pool.acquire_time_p99` vs query latency |
+| Intermittent "prepared statement does not exist" | PgBouncer transaction mode, pre-1.21 | Upgrade PgBouncer or disable server-side prepares |
+| Random session-variable values | `SET` (not `SET LOCAL`) under transaction pooling | Audit `SET` use; switch to `SET LOCAL` |
+| Connections held for hours; transaction-id age growing | Idle-in-transaction | `pg_stat_activity` for long `idle in transaction` |
+| Brief outage during deploy | Reconnect storm | Stagger app startup; add reconnect backoff |
+| Slow degradation over weeks | Long-tail connection age (memory bloat, stale prepared statements) | Enable `maxLifetime` rotation |
+
+## Verification
+
+After applying this skill, verify:
+- [ ] Pool size has been calculated against Little's Law for the workload — not copied from advice columns. Peak concurrency × small headroom, not request rate.
+- [ ] Sum of (app pool size × app instances) + replica pools + admin connections fits inside the database's `max_connections` with headroom. The database-side total is bounded, not just the per-instance pool.
+- [ ] If PgBouncer transaction mode is enabled, the application's use of prepared statements, `SET`, advisory locks, `LISTEN/NOTIFY`, and WITH HOLD cursors has been audited. Compatible patterns confirmed; incompatible patterns refactored.
+- [ ] Pool instrumentation is in place: `pool.acquire_time`, `pool.active`, `pool.waiting`. Connection contention shows up as a first-class signal, not as opaque application latency.
+- [ ] `idle_in_transaction_session_timeout` is set (Postgres) so leaked transactions don't hold pool slots indefinitely. Application code does not perform external service calls inside database transactions.
+- [ ] Connection rotation (`maxLifetime` / `server_lifetime`) is configured so connections refresh and don't accumulate long-tail bloat.
+- [ ] Reconnect backoff and circuit-breaking are configured so deploy churn or brief network partitions don't produce reconnect storms.
+- [ ] If serverless or auto-scaled application instances are used, a proxy pool (PgBouncer, Supavisor, RDS Proxy) caps the database-side connection total. Client count and server connection count are decoupled.
+- [ ] Long-running queries (>1s) and short-running queries are not in the same pool. Pool partitioning prevents one class from starving the other.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Tuning a slow query | `query-optimization` | query-optimization owns query-level cost; this owns connection-level cost |
+| Designing indexes | `indexing-strategy` | indexing-strategy owns access-path design |
+| Routing reads vs writes across replicas | `replication-patterns` | replication-patterns owns the routing layer above pooling |
+| Partitioning data across shards | `sharding-strategy` | sharding-strategy owns the data-partition layer; pooling sits beneath it per shard |
+| Choosing transaction isolation level | `transaction-isolation` | isolation owns the per-transaction concurrency contract |
+| Designing the schema | `data-modeling` | data-modeling owns design; pooling is operational |
+
+## Key Sources
+
+- Brett Wooldridge. ["About Pool Sizing"](https://github.com/brettwooldridge/HikariCP/wiki/About-Pool-Sizing). HikariCP maintainer's canonical analysis; the source of the "small pools" doctrine. Cites Oracle Real-World Performance Group's empirical findings.
+- Brett Wooldridge. ["HikariCP — Down the Rabbit Hole"](https://github.com/brettwooldridge/HikariCP/wiki/Down-the-Rabbit-Hole). Deep dive on connection pool implementation choices and overhead.
+- PgBouncer Project. ["PgBouncer Documentation"](https://www.pgbouncer.org/usage.html). Reference for the three pooling modes and their feature compatibility. The 1.21 release notes document the prepared-statement support in transaction mode.
+- PostgreSQL Global Development Group. ["PostgreSQL Documentation — Connection Pooling"](https://www.postgresql.org/docs/current/runtime-config-connection.html). Reference for `max_connections`, `idle_in_transaction_session_timeout`, and related configuration.
+- Little, J. D. C. (1961). ["A Proof for the Queuing Formula: L = λW"](https://www.jstor.org/stable/167570). *Operations Research*, 9(3). The original Little's Law paper; basis for concurrency-based pool sizing.
+- Kleppmann, M. (2017). *Designing Data-Intensive Applications*. O'Reilly. Discussion of database concurrency limits and their interaction with application architecture.
+- Amazon Web Services. ["Amazon RDS Proxy"](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/rds-proxy.html). Managed proxy pool documentation; surfaces the serverless-vs-pool tension and the proxy's role.
+- Supabase. ["Supavisor — Scalable Postgres Connection Pooler"](https://github.com/supabase/supavisor). Open-source proxy pool documentation; the recommended pooler for Neon and Supabase serverless workloads.
+- Markus Winand. ["Performance — Open Source Database Pool Sizing"](https://use-the-index-luke.com/). Practitioner reference cross-cited from `indexing-strategy`; the chapter on operational concerns.