AGENT SKILL

mongodb-expert

MongoDB document modeling, schema design, aggregation pipelines, transactions, change streams, and driver usage for Go and Python. Use when building document databases with flexible schemas, analytics pipelines, CDC, or migrating to AWS DocumentDB. Trigger: MongoDB, aggregation, indexing, transactions. Do NOT trigger for: relational DB design, SQL queries, PostgreSQL/MySQL aggregation queries, window functions, caching patterns.

License 许可
MIT
最近更新
2026-08-27
Stars
★ 1
Forks
0

01 前言 Front Matter

name
mongodb-expert
license
MIT
metadata
{ "author": "Community", "status": "stable", "version": "1.0", "category": "data" }
description
MongoDB document modeling, schema design, aggregation pipelines, transactions, change streams, and driver usage for Go and Python. Use when building document databases with flexible schemas, analytics pipelines, CDC, or migrating to AWS DocumentDB. Trigger: MongoDB, aggregation, indexing, transactions. Do NOT trigger for: relational DB design, SQL queries, PostgreSQL/MySQL aggregation queries, window functions, caching patterns.

02 资源文件 3

03 SKILL.md 正文

MongoDB Expert

MongoDB Atlas + DocumentDB: schemas, aggregations and CDC.

Core Stack

  • Database: MongoDB Atlas (analytics database), AWS DocumentDB compatible
  • Drivers: Go mongo-driver, Python motor (async)
  • Patterns: Embed vs Reference, aggregation pipelines, change streams
  • Operations: Multi-doc transactions, indexes, Atlas Search

Schema Design

Pattern Use When Example
Embed Data read together, rarely changes independently Record + line items
Reference Entities accessed independently, many-to-many User -> Events
Bucket Time-series, IoT, event streams Metrics per hour/day
type Record struct {
    ID         primitive.ObjectID `bson:"_id,omitempty"`
    UserID     string             `bson:"user_id"`
    Amount     int64              `bson:"amount"`     // units
    Category   string             `bson:"category"`
    Items      []RecordItem       `bson:"items"`       // embedded
    CreatedAt  time.Time          `bson:"created_at"`
}

Aggregation Pipeline

pipeline := mongo.Pipeline{
    {{Key: "$match", Value: bson.D{{Key: "user_id", Value: "usr_123"}}}},
    {{Key: "$group", Value: bson.D{
        {Key: "_id", Value: "$category"},
        {Key: "total", Value: bson.D{{Key: "$sum", Value: "$amount"}}},
        {Key: "count", Value: bson.D{{Key: "$sum", Value: 1}}},
    }}},
    {{Key: "$sort", Value: bson.D{{Key: "total", Value: -1}}}},
}
cursor, err := collection.Aggregate(ctx, pipeline)

Indexes

// Compound index for query patterns
indexModel := mongo.IndexModel{
    Keys: bson.D{
        {Key: "customer_id", Value: 1},
        {Key: "created_at", Value: -1},
    },
}
collection.Indexes().CreateOne(ctx, indexModel)
  • Index on query fields in ESR order (Equality -> Sort -> Range)
  • Use explain() to verify index usage

Change Streams (CDC)

stream, err := collection.Watch(ctx, mongo.Pipeline{})
for stream.Next(ctx) {
    var changeEvent bson.M
    stream.Decode(&changeEvent)
    // process insert/update/delete event
}

Constraints

  • NEVER use unbounded arrays in documents (can exceed 16MB limit)
  • NEVER skip indexes on query fields (full collection scan)
  • NEVER use $lookup without indexes on foreign field
  • ALWAYS use context.Context with timeouts on all operations
  • ALWAYS use transactions for multi-doc atomic updates
  • ALWAYS monitor slow queries via Atlas profiler
  • NEVER store unencrypted PII/CHD in MongoDB documents

Security

  • NEVER concatenate user input into $where, $expr, or $regex — NoSQL operator injection
  • ALWAYS enable authentication and TLS for every MongoDB/DocumentDB connection
  • ALWAYS use parameterized driver APIs (filter documents) — never raw JSON strings
  • ALWAYS encrypt at rest (Atlas encryption or KMS) and rotate credentials

Overview

MongoDB Atlas is team document database for semi-structured data, flexible schemas, and high-write workloads (analytics database). This skill covers document schema design (embed vs reference), aggregation pipelines for analytics, compound and multikey index strategies, multi-document ACID transactions via sessions, change streams for CDC, and AWS DocumentDB compatibility for migration scenarios.

Quick Reference

Pattern Decision Rule Max Size
Embed Data read together, sub-doc < 16MB total 16MB/doc hard limit
Reference Entity accessed independently, M:N relations No limit (separate collection)
Bucket Time-series, event streams, 1 doc per hour/day 16MB/doc hard limit
Index ESR rule: Equality → Sort → Range fields 64 indices/collection max
Change Streams Sequenced per shard, exactly-once with idempotency 16MB event batch
Transactions Multi-doc ACID, max 60s duration 1K doc limit per txn

Workflow

  1. Design documents — Identify entity relationships. Embed sub-documents that are always read together and rarely change independently. Reference entities that are queried separately or have many-to-many relationships.
  2. Build indexes — Apply ESR order: Equality filters first, Sort keys second, Range scans last. Use explain("executionStats") to verify IXSCAN (not COLLSCAN). Add compound indexes for multi-field queries.
  3. Write aggregation pipelines — Chain stages: $match (early filter) → $group/$sort → $project (shape output). Use $lookup sparingly — prefer embedded docs. Add indexes on $lookup foreign fields.
  4. Implement change streams — Open collection.Watch() for CDC. Process in order per document key. Use resumeAfter with checkpoint token for at-least-once delivery.
  5. Use transactions — For multi-document atomicity: start session → start transaction → execute operations → commit. Keep transactions under 1000 documents and 60 seconds.
  6. Monitor performance — Atlas profiler for slow queries (>100ms). Index usage stats. Connection pool utilization. Replica set lag.

Anti-patterns

FAIL: Unbounded array growth in a single document (will exceed 16MB).

// BAD: Embedded array grows forever
type AuditLog struct {
    Entries []AuditEntry `bson:"entries"` // thousands over time → 16MB+
}
// GOOD: Separate collection for high-cardinality sub-items
type AuditLog struct {
    LogID   string `bson:"_id"`
}
// Audit entries in separate collection with log_id reference

FAIL: Using $lookup without indexes on the foreign field.

// BAD: $lookup with no index on user_id in events collection
pipeline := bson.A{
    bson.D{{Key: "$lookup", Value: bson.D{
        {Key: "from", Value: "events"},
        {Key: "foreignField", Value: "user_id"},
    }}}
}
// GOOD: Create index first, then $lookup
eventsCollection.Indexes().CreateOne(ctx, mongo.IndexModel{
    Keys: bson.D{{Key: "user_id", Value: 1}},
})

FAIL: No timeout on database operations (goroutine leak under load).

// BAD: Default context — no timeout
cursor, _ := collection.Find(context.Background(), bson.D{})
// GOOD: Explicit timeout
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
cursor, _ := collection.Find(ctx, bson.D{})

References

Resource URL Last verified
MongoDB — Schema Design Best Practices https://www.mongodb.com/docs/manual/core/data-modeling-introduction/ 2026-05-25
MongoDB — Aggregation Pipeline Reference https://www.mongodb.com/docs/manual/aggregation/ 2026-05-25
MongoDB — Change Streams Production Best Practices https://www.mongodb.com/docs/manual/changeStreams/ 2026-05-25

Verification Checklist

  • [ ] Document schema designed with correct embed vs reference decision for access patterns
  • [ ] Indexes created following ESR order (Equality → Sort → Range) with explain() verification
  • [ ] context.Context with timeout used on all database operations
  • [ ] Aggregation pipeline stages ordered with early $match filter
  • [ ] No unbounded arrays in documents (16MB doc size limit)
  • [ ] $lookup foreign fields indexed to prevent full collection scans
  • [ ] Change streams idempotent with resumeAfter token for at-least-once delivery
  • [ ] No user input in $where/$expr/$regex; auth + TLS enabled on all connections

Troubleshooting

Symptom Likely cause Fix
Query returns COLLSCAN instead of IXSCAN Missing index on filter fields or wrong index order Run explain("executionStats"); create compound index matching query ESR order
Document too large error (16MB+ limit) Embedded array grew unbounded over time Split high-cardinality data into separate collection with reference
Change stream disconnects on replica set election resumeAfter token lost after primary change Use startAfter instead of resumeAfter for global resumption across elections
Known issue: $lookup with let variables silently returns empty arrays Variable reference syntax error in let block or pipeline stage mismatch Verify let variable names match exactly in $expr; test the pipeline stage in isolation before composing
Gotcha: $text search requires a text index Missing text index causes full COLLSCAN even on small collections Create text index on the search field: db.collection.createIndex({field: "text"}); verify with explain()
[WARN] Known limitation: change stream $lookup results may be stale Change events captured before $lookup target documents are fully committed Use post-image or transactional consistency guarantees; avoid $lookup in change stream pipeline when cross-document consistency is required

04 同仓库更多 Skills

ronsilver
ronsilver/agent-covenant

web-browsing-agent-expert

Web browsing for AI agents: driving a headless browser (Playwright, Puppeteer) from agent tooling, navigation and page-state grounding, DOM extraction and structured data capture, form interaction, session and cookie management, anti-bot mitigation awareness, and safe browsing rules (no PII exfiltration, respect robots and terms). Use when building a browsing tool or MCP server for an agent, teaching an agent to navigate and read web pages, extracting structured content from dynamic sites, or handling login walls and pagination in agent workflows. Trigger: web browsing agent, headless browser, Playwright MCP, Puppeteer, browser automation for agents, DOM extraction, page navigation, session management. Do NOT trigger for: end-to-end UI testing of an application (use playwright-expert); writing standalone scraping scripts for data pipelines (use python-expert); fetching a single public URL (use the fetch tool).

★ 1
ronsilver
ronsilver/agent-covenant

vector-databases

Design and operate vector databases for cloud-native AI features. Use when selecting between pgvector, Pinecone, or Weaviate for AI context layer or integration-hub; designing embedding schemas and index parameters; implementing ANN search with metadata filtering; managing embedding model versions; optimizing query latency; or debugging low retrieval quality. Pairs with rag-architecture for pipeline design and postgres-database-expert for pgvector specifics. Trigger: vector database, pgvector, Pinecone, Weaviate, embedding, ANN search, HNSW, cosine similarity. Do NOT trigger for: relational SQL optimization, standard PostgreSQL schema design, Redis caching.

★ 1
ronsilver
ronsilver/agent-covenant

typescript-expert

Full-stack TypeScript stack for modern projects: frontend SSR/CSR with Next.js 14 App Router and React, backend APIs with Node.js (Express/Fastify), state management with Zustand/Redux Toolkit, unit and integration testing with Vitest/Jest + React Testing Library + MSW, and static analysis with ESLint/Prettier/tsc. Use when building React components or hooks, implementing Next.js App Router or Server Components, writing Node.js REST API handlers, implementing middleware (auth, rate-limit, logging), managing client state (Zustand/RTK), writing frontend/backend tests, or running TypeScript linting/type checks. Trigger: TypeScript, Next.js, React, Zustand, Node.js, Express, Fastify, MSW, Vitest. Do NOT trigger for: Python backend development, Go microservices, iOS/mobile development.

★ 1
ronsilver
ronsilver/agent-covenant

tool-usage

Guide correct tool selection, design, and orchestration for AI agents. Use when choosing between dedicated vs Bash tools, designing MCP tool interfaces, naming tool parameters, handling tool response limits, orchestrating parallel vs sequential calls, evaluating tool accuracy, applying ACI design principles, selecting workflow patterns, or reading/filtering/transforming/generating structured data (JSON, YAML, CSV, TOML, XML). Trigger: tool selection, MCP tool design, orchestration, ACI, parallel execution, composite tool, structured data, jq, yq, dasel, mlr, csvkit. Do NOT trigger for: writing application business logic, domain-specific development (route to domain skill), database migrations.

★ 1
ronsilver
ronsilver/agent-covenant

token-efficiency

Enforce token-efficient output, compression, caching, and model routing. Use when calibrating response verbosity, applying compression strategies to logs or RAG chunks, routing tasks to the right model tier, setting thinking budgets, enforcing word limits, compressing context before reinitiation, applying KV-cache ordering, masking tool output observations, or applying clarification-first protocol before irreversible actions. Trigger: token efficiency, compression, model routing, thinking budget, KV-cache, clarification protocol. Do NOT trigger for: non-agent tooling, CI/CD pipeline scripting, infrastructure provisioning.

★ 1
ronsilver
ronsilver/agent-covenant

time-series-db

Time-series database patterns for cloud-native metrics and analytics: TimescaleDB, InfluxDB, and Amazon Timestream selection; continuous aggregates, retention policies, downsampling, and integration with Prometheus/Grafana. Use when storing business metrics over time, building custom business dashboards, designing high-frequency event storage, or querying time-bucketed aggregations. Trigger: time-series, TimescaleDB, InfluxDB, Prometheus, Grafana, hypertable, continuous aggregate, retention policy. Do NOT trigger for: relational PostgreSQL schema design, NoSQL document stores, Kafka event streaming.

★ 1