Add a sample-app-generator skill: scaffold runnable starter apps against an Azure DocumentDB cluster

[khelanmodi]

Summary

Add a new skill — sample-app-generator — that scaffolds a runnable starter application against an Azure DocumentDB cluster. The skill should let an agent generate a minimal but production-shaped sample app for a target language/framework, wire it up to a user-provided cluster, and verify the connection works end-to-end.

Motivation

Every developer onboarding to Azure DocumentDB writes essentially the same first hundred lines: connection-string handling, TLS, retry, a minimal CRUD path, and a way to confirm "yes, I'm actually connected." Today there is no canonical scaffold and the existing skills (security, storage, HA, full-text-search) all assume the developer has already got a working client.

A sample-app-generator skill closes that gap and gives the rest of the agent-kit a concrete launch surface: "generate the starter, then ask me about indexing / FTS / RBAC."

Proposed scope

In scope (v1)

1. Language / framework matrix — minimum viable set:
   • Node.js + native mongodb driver
   • Python + pymongo
   • C# + MongoDB.Driver
   • Java + mongodb-driver-sync
2. Generated app shape (same across languages):
   • README.md with run instructions
   • Config via environment variables (DOCUMENTDB_CONNECTION_STRING, DOCUMENTDB_DATABASE)
   • TLS-enabled client construction (matches security-tls-required rule)
   • One database + one collection
   • CRUD endpoints / functions: insert, find-by-id, update, delete, list-paged
   • A /healthz-style probe that does a ping against the cluster
   • Basic retry with backoff on transient errors
   • Dockerfile (where it makes sense) + .env.example
3. Auth modes — the generator should support choosing one at scaffold time:
   • Connection-string + native admin user (default, easiest)
   • Microsoft Entra ID via managed identity (matches security-entra-rbac rule) — generated samples show the MONGODB-OIDC mechanism wired in
4. Optional add-on flags:
   • --with-fts → add a vector / full-text search example collection and a search endpoint (links into the existing full-text-search skill)
   • --with-private-endpoint → emit a Bicep snippet alongside the app for cluster + PE provisioning (links into security-private-endpoint)
5. Validation step — the skill should be able to run the generated app's /healthz probe to confirm the connection string works before handing off to the user.

Out of scope (v1)

• Migrating from MongoDB Atlas / CosmosDB-Mongo-vCore — that's a separate "migration" skill.
• Multi-region or read-replica wiring — covered by HA skill; the generator may reference it but not duplicate it.
• ORM-style abstractions (Mongoose, EF Core mappings) — keep v1 driver-native to stay close to the wire.
• Web UI / front-end — the sample is API/CLI only.

Proposed skill layout

Following the existing agent-kit pattern (skills/<name>/SKILL.md + rule files):

skills/sample-app-generator/
├── SKILL.md
├── rules/
│   ├── generator-language-matrix.md       # which langs/frameworks are supported and why
│   ├── generator-connection-config.md     # env-var contract, TLS, retry defaults
│   ├── generator-auth-mode-selection.md   # native-user vs Entra OIDC; when to choose which
│   ├── generator-crud-shape.md            # canonical CRUD endpoint/function signatures
│   ├── generator-healthz-probe.md         # what a working probe looks like; failure modes
│   ├── generator-fts-addon.md             # how the --with-fts flag composes with full-text-search skill
│   └── generator-private-endpoint-addon.md# how --with-private-endpoint composes with security skill
└── templates/
    ├── node/
    ├── python/
    ├── csharp/
    └── java/

Templates live under templates/ and are rendered by the agent (or a small helper script in scripts/) given the user's choices.

Cross-references with existing skills

The generator deliberately doesn't re-state guidance that other skills own — it links to them:

Generator concern	Owning skill
TLS on the client	security/security-tls-required
Auth mode (Entra OIDC)	security/security-entra-rbac, security/security-database-roles
Connection-string handling, admin password rotation	security/security-admin-password-and-identity-separation
Retry / replica behavior	high-availability/
Search / vector endpoints (--with-fts)	full-text-search/
Private endpoint Bicep (--with-private-endpoint)	security/security-private-endpoint

Open questions

1. Generation mechanism — pure-text templating with the agent doing the substitution, or a cookiecutter-style helper script invoked by the skill? My instinct: start with text templates that the agent renders, ship a script later if it pays off.
2. Which Java framework — bare main + driver, Spring Boot, or both? Start with bare main and add Spring Boot in v1.1 unless feedback says otherwise.
3. Versioning of generated apps — do we pin driver versions or use latest? Pin, with a quarterly bump cadence.
4. Telemetry — should the generated app emit OpenTelemetry traces by default? Probably yes for production-shaped, but it bulks up the sample. Maybe behind a --with-otel flag.
5. Test scaffolding — include a smoke-test file (one assertion per CRUD path) or leave it to the developer? Recommend yes, one per language, using each ecosystem's default runner.

Acceptance criteria

• skills/sample-app-generator/SKILL.md exists with frontmatter and is registered in docs/SKILLS.md.
• All rule files listed in "Proposed skill layout" are present and pass scripts/validate-skills.ps1.
• Templates for at least Node.js and Python compile / run end-to-end against a live cluster (manual verification by a maintainer).
• A generated app's /healthz probe returns success against a real cluster using the default connection-string flow and the Entra-OIDC flow.
• Cross-links to security/, high-availability/, full-text-search/ resolve.

Suggested follow-ups (not blockers)

• C# and Java templates if v1 lands with Node + Python first.
• IaC bundle: Bicep + azd up integration so --with-private-endpoint can provision a fully working cluster + PE in one shot.
• Aspire-style local dev story (containerized DocumentDB emulator if/when available).