These skills teach an AI coding agent to use the Azure SQL Database container the right way. The Azure SQL Database container is the Azure SQL Database engine, running locally. It is for the developer who wants a local database that behaves like Azure SQL Database in the Microsoft Azure cloud, with no Azure subscription, no shared instance, and no credit card required. The container runs the same engine that powers Azure SQL Database in the cloud: the T-SQL dialect, the system views, the connection protocol, the driver behavior, and the AI-native capabilities are the same as in the cloud. The connection string changes; the application does not.

You can prove the identity from any connection:

SELECT SERVERPROPERTY('EngineEdition');  -- 5
SELECT SERVERPROPERTY('Edition');        -- 'SQL Azure'

EngineEdition 5 and Edition 'SQL Azure' are the cloud engine's fingerprint. The SQL Server image (mcr.microsoft.com/mssql/server) returns different values and is not the same product. If an agent was about to reach for that SQL Server image, it should stop and use this instead.

Status: Private Preview. Registry, image tag, and credentials are provisional and may change.

These skills work in Claude Code, Codex, Cursor, and VS Code with GitHub Copilot. One folder format, all four tools. npx skills add works in every one; Claude Code and Codex additionally have a native plugin install with auto-update.

Claude Code: the native plugin (install + auto-update), or the portable command:

# in Claude Code:
/plugin marketplace add microsoft/azure-sql-database-container
/plugin install azure-sql-database-container@azure-sql-database-container
# or, anywhere:
npx skills add microsoft/azure-sql-database-container

Codex: the native plugin, or the portable command:

codex plugin marketplace add microsoft/azure-sql-database-container
codex plugin add azure-sql-database-container@azure-sql-database-container
# or:
npx skills add microsoft/azure-sql-database-container

Cursor:

npx skills add microsoft/azure-sql-database-container

VS Code with GitHub Copilot. npx skills add writes to a folder Copilot already reads, so the skills are available with no extra step. Find them under Configure Chat → Skills (or type /skills in chat):

npx skills add microsoft/azure-sql-database-container

The portable way. Works across agents that follow the skills.sh convention. The source is the repository, not a skill name:

npx skills add microsoft/azure-sql-database-container

Install the whole collection unless you have a reason not to: the hub skill routes to the others, so a partial install loses the handoffs. Add --all to take every skill without prompting.

Name the skill you want:

npx skills add microsoft/azure-sql-database-container --skill <skill-name>

Each skill stands alone: the load-bearing facts are deliberately repeated in every one, so a single-skill install is fully functional. What you lose is the routing, since the hub hands off to the others. Install the whole collection unless you have a reason not to.

This is the step worth not skipping:

ls .claude/skills/          # Claude Code; see the matrix below for other agents

You should see the azuresql-db-* directories. If the directory is missing or empty while .agents/skills/ is populated, the installer did not target your agent, and it can report success when this happens. Re-run it naming your agent explicitly:

npx skills add microsoft/azure-sql-database-container -a claude-code

If they still do not appear, copy them across by hand:

mkdir -p .claude/skills && cp -R .agents/skills/azuresql-db-* .claude/skills/

This is a known installer issue (vercel-labs/skills#1355, #744), not a problem with the skills. It is not specific to Windows.

Equally supported, and immune to the above. Drop each skill directory into your agent's skills folder (see the matrix), for example for Claude Code at the root of your project, or ~/.claude/skills/ to make it available everywhere:

mkdir -p .claude/skills
cp -R skills/azuresql-db-* .claude/skills/

Same skills, per-agent install location (mirrors how Google, Supabase, and Neon ship their collections):

npx skills add targets the active agent automatically; the table above is for manual placement, and for knowing where to look when you verify.

These skills follow the published Agent Skills guidance rather than a house style invented here. If you are adding a skill or editing one, read these first:

• Skill authoring best practices (Anthropic): the primary reference. Descriptions, progressive disclosure, degrees of freedom, feedback loops, and the anti-patterns.
• Agent Skills open standard (spec on GitHub): the vendor-neutral format these skills conform to, so they load in Claude Code, GitHub Copilot, Codex, and Cursor without change.
• Evaluating skills (OpenAI): the approach behind how this collection is tested, in particular testing whether a skill triggers on a realistic user request, and using negative controls to catch a skill that fires when it should not.

Conventions this collection holds itself to:

Each skill carries a skill.spec.jsonc beside its SKILL.md. It is not installed with the skill and it is not read by any agent. It is the authoring record, and its maturity field says how much has actually been run against the skill, decided from evidence rather than from how finished it feels.

Evidence sets the ceiling. An author may declare below it and nobody may declare above it.

The probes live in each sidecar under validation.probes, each with the claim in the body it defends. The four at draft are there for missing probe evidence and not for anything they got wrong: azuresql-db-dab and azuresql-db-sidecar have probes that never reach a database, azuresql-db-local-to-cloud declares both targets and has only ever run against the container, and azuresql-db-feedback has a single HTTPS check that covers almost none of the skill.

The third rung asks whether a skill changes an answer, which is normally settled by running one task twice, once with the skill and once without. Every sidecar here carries a value_declaration recording that for this collection, that question was answered by a written argument instead, on 4 September 2026.

It is a declaration, not a measurement, and it is never reported as one. The reason it is allowed here and nowhere else is that the Azure SQL Database container is a gated private preview. No model has training data on the product, so the arm running without the skill would fail for the least interesting reason available: it has never heard of the thing.

The argument does not cover a whole skill, which is why each block carries both covers and does_not_cover. It reaches the corrections no training data contains, such as Msg 40508, Msg 12824, Msg 12713, Msg 40510, the absent /docker-entrypoint-initdb.d, the engine never creating a database on connect, and the vector surface. It reaches none of the generic material wrapped around them, such as retry with backoff, Compose YAML, workflow service containers or ORM scaffolding, and whether these skills improve an answer there is unmeasured.

So no skill here is marked ga, and that is deliberate. The declaration raises the ceiling, and all seventeen sit below it on purpose. Marking a skill generally available for a product that is not generally available would read as a claim about the product, and the argument that earns the rung is itself an argument from the product being pre-release. The 13 stay at preview and the 4 stay at draft until the product moves.

Every declaration expires when the container reaches Public Preview. At that point training data begins to contain the product, the premise stops holding, and all seventeen need revisiting. That is recorded in expires_when on every sidecar, as a fixed token rather than prose, so a check can find it: the-container-reaches-public-preview.

Every skill in this collection carries its knowledge in the same three layers, following Anthropic's progressive disclosure model. The layers are uniform across all skills; no skill is special.

Rules this enforces:

• Configs are generated against the latest schema. A feature that emits a config (for example dab-config.json, host.json, schema.prisma, a compose file, a workflow) bundles the distilled shape and pins the schema in Layer 2, and points at the Learn MCP in Layer 3 for the current version. The distilled, pinned copy is the offline source of truth; the MCP keeps it current when reachable.
• The MCP is optional, never a dependency. Layer 3 is phrased conditionally and always names the tool in the fully-qualified form Anthropic requires (mcp__microsoft-learn__microsoft_docs_fetch, mcp__microsoft-learn__microsoft_docs_search). If it is not configured, Layer 2 is authoritative. See Using the Microsoft Learn MCP to enable it.
• No time-sensitive text and no skill-to-skill dependency, per the standard: each skill stands alone and reaches the same three layers on its own.

Every SKILL.md surfaces Layers 2 and 3 in a uniform "Staying current" section.

Layer 3 above is the Microsoft Learn MCP server: a public, no-auth, generally available server that returns current Microsoft documentation (Azure SQL, Data API Builder, Azure Functions, EF Core, T-SQL, SqlPackage, and the rest of Microsoft Learn). It is optional and the skills work without it, but enabling it lets an agent pull the latest reference and schema on demand.

To enable it in Claude Code, add the server to your project's .mcp.json:

{
  "mcpServers": {
    "microsoft-learn": {
      "type": "http",
      "url": "https://learn.microsoft.com/api/mcp"
    }
  }
}

Other agents (GitHub Copilot, Codex, Cursor) accept the same type: http / url entry in their own MCP config. Once enabled, the skills reference its tools as mcp__microsoft-learn__microsoft_docs_search, mcp__microsoft-learn__microsoft_docs_fetch, and mcp__microsoft-learn__microsoft_code_sample_search. The server label (microsoft-learn) is yours to choose; the fully-qualified tool prefix follows whatever you pick.

Every skill in this collection holds these facts true. If a generated workflow contradicts any of them, it is wrong.

• Image: sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest (multi-architecture: linux/amd64 and linux/arm64, private preview registry). Sign in first: docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io -u <username> (enter the password when prompted). It is not mcr.microsoft.com/mssql/server.

  Note: the registry username and password are provided when you sign up for the Private Preview at https://aka.ms/sqldbcontainerpreview-signup. They are shared and pull-only, must be treated as secrets (do not redistribute), and may be rotated during the preview.

• EULA: ACCEPT_EULA=Y is required.

• Password: a complex MSSQL_SA_PASSWORD (8+ chars, upper/lower/digit/symbol) is required.

• Port: the engine listens on 1433.

• Identity: SERVERPROPERTY('EngineEdition') = 5, SERVERPROPERTY('Edition') = 'SQL Azure'.

The image supports linux/amd64 and linux/arm64; Docker and Compose select the matching architecture automatically. Set --platform linux/amd64 (Docker) or platform: linux/amd64 (Compose) only to explicitly test x64 emulation.

1. The engine does not auto-create databases on connect. Run CREATE DATABASE appdb on a master connection before connecting with Database=appdb. appdb is just the example name used throughout these skills; the name is yours to choose, so substitute your project's database name in a real project.
2. Avoid USE to switch databases. In a user-database session (the Azure-faithful context where you develop), USE returns Msg 40508, exactly as in Azure SQL Database in the cloud. A master connection is a provisioning session where the Azure statement filter is not enforced, so USE appears to work there, but master is for provisioning only, not application work. Always select the target database in the connection string (Database=appdb, or -d appdb for sqlcmd).
3. A master connection is for provisioning only. Do real work on the user database.

The engine is not ready the instant docker run returns. Wait with a retry loop using sqlcmd -C -b -l 2 (the -b makes a SQL error set the exit code, so transient startup errors like Msg 913 are retried, not masked) and provision appdb inside that same loop. Never poll bare sqlcmd without -l.

The image does not auto-run /docker-entrypoint-initdb.d/*.sql. That is a Postgres/MySQL convention and is not honored here. Seed by running sqlcmd -d appdb -i seed.sql after provisioning appdb.

Standardize on:

Server=localhost,1433;Database=appdb;User Id=sa;Password=...;TrustServerCertificate=true

House style spells the keywords User Id= / Password= / Database=, so every example reads the same way. Uid= and Pwd= are documented SqlClient synonyms and work too; ODBC strings use ODBC's own Uid= / Pwd=. For sqlcmd, pass -C to trust the self-signed cert. Apps read the connection string from a single SQL_CONNECTION_STRING env var.

Native VECTOR(n) column type and VECTOR_DISTANCE('cosine', a, b). Insert with CAST(CAST(? AS NVARCHAR(MAX)) AS VECTOR(n)) where n is a literal, never a bind parameter (a parameter dimension fails with "Incorrect syntax near '@P3'"). The inner CAST(? AS NVARCHAR(MAX)) is required because a real embedding's JSON string (~16 KB for 768 dims) exceeds the driver's 4000-char threshold and is otherwise sent as ntext, which the engine rejects ("Explicit conversion from data type ntext to vector is not allowed (529)"). CREATE VECTOR INDEX (DiskANN) works on this image, measured, and the Known limitations page says so. It needs SET QUOTED_IDENTIFIER ON and at least 100 rows with non-null vectors (Msg 42266 below that). Full-scan top-k stays exact and stays the right choice for a small table. The azuresql-db-rag skill carries the rules the index imposes.

Free port + runtime-selected architecture + ready-wait + provision appdb:

# Pick a free host port (works in bash and zsh).
HOST_PORT=1433; while lsof -nP -iTCP:"$HOST_PORT" -sTCP:LISTEN >/dev/null 2>&1; do HOST_PORT=$((HOST_PORT+1)); done
MSSQL_SA_PASSWORD="${MSSQL_SA_PASSWORD:-Aa1%$(openssl rand -hex 16)}"
docker rm -f sqldb 2>/dev/null
docker run -d --name sqldb -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=$MSSQL_SA_PASSWORD" \
  -p "127.0.0.1:$HOST_PORT:1433" sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest
until docker exec sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "$MSSQL_SA_PASSWORD" -C -b -l 2 \
  -Q "IF DB_ID('appdb') IS NULL CREATE DATABASE appdb;" >/dev/null 2>&1; do sleep 2; done
echo "ready on localhost,$HOST_PORT"