diff --git a/docs/README.skills.md b/docs/README.skills.md index 7d39a9ab0..e0b1222be 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -412,6 +412,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [salesforce-flow-design](../skills/salesforce-flow-design/SKILL.md)
`gh skills install github/awesome-copilot salesforce-flow-design` | Salesforce Flow architecture decisions, flow type selection, bulk safety validation, and fault handling standards. Use this skill when designing or reviewing Record-Triggered, Screen, Autolaunched, Scheduled, or Platform Event flows to ensure correct type selection, no DML/Get Records in loops, proper fault connectors on all data-changing elements, and appropriate automation density checks before deployment. | None | | [sandbox-npm-install](../skills/sandbox-npm-install/SKILL.md)
`gh skills install github/awesome-copilot sandbox-npm-install` | Install npm packages in a Docker sandbox environment. Use this skill whenever you need to install, reinstall, or update node_modules inside a container where the workspace is mounted via virtiofs. Native binaries (esbuild, lightningcss, rollup) crash on virtiofs, so packages must be installed on the local ext4 filesystem and symlinked back. | `scripts/install.sh` | | [scaffolding-oracle-to-postgres-migration-test-project](../skills/scaffolding-oracle-to-postgres-migration-test-project/SKILL.md)
`gh skills install github/awesome-copilot scaffolding-oracle-to-postgres-migration-test-project` | Scaffolds an xUnit integration test project targeting Oracle in .NET solutions. Creates the test project, transaction-rollback base class, and seed data manager. Use only during Phase 3, before writing Oracle baseline integration tests. Do not invoke during Phase 6 — the PostgreSQL test project is produced by migrating this project, not by running this skill again. | None | +| [schemagate-sql](../skills/schemagate-sql/SKILL.md)
`gh skills install github/awesome-copilot schemagate-sql` | Answer questions about data in a large SQL database through the schemagate MCP server, which sends the model only the tables a question needs (about 91% fewer schema tokens on 50+ table databases) and only the ones the caller may read. #1 on the BIRD Mini-Dev text-to-SQL leaderboard. Use when the user asks a question that needs a query against PostgreSQL, MySQL, SQLite, SQL Server, Oracle, Snowflake, BigQuery or DuckDB. | None | | [scoutqa-test](../skills/scoutqa-test/SKILL.md)
`gh skills install github/awesome-copilot scoutqa-test` | This skill should be used when the user asks to "test this website", "run exploratory testing", "check for accessibility issues", "verify the login flow works", "find bugs on this page", or requests automated QA testing. Triggers on web application testing scenarios including smoke tests, accessibility audits, e-commerce flows, and user flow validation using ScoutQA CLI. Use this skill proactively after implementing web application features to verify they work correctly. | None | | [screen-recording](../skills/screen-recording/SKILL.md)
`gh skills install github/awesome-copilot screen-recording` | Create annotated animated GIF demos and screen recordings for pull requests and documentation. Covers frame capture, timing, imageio-based GIF creation, and per-frame annotation workflows. | None | | [secret-scanning](../skills/secret-scanning/SKILL.md)
`gh skills install github/awesome-copilot secret-scanning` | Guide for configuring and managing GitHub secret scanning, push protection, custom patterns, and secret alert remediation. For pre-commit secret scanning in AI coding agents via the GitHub MCP Server, this skill references the Advanced Security plugin (`advanced-security@copilot-plugins`). Use this skill when enabling secret scanning, setting up push protection, defining custom patterns, triaging alerts, resolving blocked pushes, or when an agent needs to scan code for secrets before committing. | `references/alerts-and-remediation.md`
`references/custom-patterns.md`
`references/push-protection.md` | diff --git a/skills/schemagate-sql/SKILL.md b/skills/schemagate-sql/SKILL.md new file mode 100644 index 000000000..aab357998 --- /dev/null +++ b/skills/schemagate-sql/SKILL.md @@ -0,0 +1,88 @@ +--- +name: schemagate-sql +description: 'Answer questions about data in a large SQL database through the schemagate MCP server, which sends the model only the tables a question needs (about 91% fewer schema tokens on 50+ table databases) and only the ones the caller may read. #1 on the BIRD Mini-Dev text-to-SQL leaderboard. Use when the user asks a question that needs a query against PostgreSQL, MySQL, SQLite, SQL Server, Oracle, Snowflake, BigQuery or DuckDB.' +license: Apache-2.0 +--- + +# Querying a database through schemagate + +[schemagate](https://github.com/ashishsinha1602/schemagate) is not another +database connector. Database MCP servers hand the model the whole schema, or +let it browse table by table, and leave the hard part to the model: picking +the few tables that matter out of hundreds, and never touching the ones this +user must not see. schemagate is the selection layer that does that part. + +- **Smaller prompts.** For each question it ranks every table (keyword + + embedding retrieval, foreign-key expansion, join-table recovery) and returns + DDL for just those. Median schema-token saving on Spider 2.0-lite databases + with 50+ tables: 91.1%. +- **Measured accuracy.** #1 on the official BIRD Mini-Dev leaderboard in + SQLite, PostgreSQL and MySQL (81.0 / 72.6 / 72.4 execution accuracy). +- **Per-user scope.** The model only sees tables and columns the caller may + read, from a policy file or the database's own GRANTs; PostgreSQL + row-level-security policies are checked per role. +- **A checked query path.** `run_query` refuses writes, multiple statements + and any object outside the caller's scope. +- **Used in agent frameworks.** Listed in LangChain's retriever integrations + (`langchain-schemagate`); also a LlamaIndex retriever and an entry in the + official MCP Registry. Apache-2.0. + +## Setup + +Add the server to your MCP configuration. With no database URL it opens +`demo`, a bundled sample schema, so you can try it without credentials: + +```json +{ + "mcpServers": { + "schemagate": { + "command": "uvx", + "args": ["--from", "schemagate[mcp]==1.15.5", "schemagate-mcp"], + "env": { "SCHEMAGATE_DATABASE_URL": "demo" } + } + } +} +``` + +For a real database, set `SCHEMAGATE_DATABASE_URL` to its SQLAlchemy URL in +`env` (for example `postgresql+psycopg://user@host/db`) and add the driver +extra: `schemagate[mcp,postgres]`, or `mysql`, `mssql`, `oracle` (SQLite needs +none). Use a read-only database user. Never paste the URL or password into +the chat. + +## Workflow + +1. **Select the schema first.** Call `select_schema` with the user's question. + Pass `principal` and `roles` when you know who is asking. A principal is + namespaced, for example `okta:jdoe` or `db:APP_USER`. Without them the + caller is anonymous and sees only unrestricted objects. +2. **Write one SELECT against that DDL only.** Use the tables and columns in + the `ddl` field and nothing else. If the DDL starts with a note that the + caller may read only part of the database and the question needs data that + is not shown, tell the user the answer is not available to them instead of + approximating it from other columns. +3. **Run it with `run_query`**, passing the same `principal` and `roles`. It + accepts a single read-only SELECT and returns rows, capped by `max_rows`. +4. **Report refusals as refusals.** An error that says `not available to this + caller` means the query named something outside the caller's scope. Say so; + do not report it as "no results" and do not retry with other roles. + +## Other tools + +- `describe_object`: full DDL for one table or view when the compact DDL is + not enough. A restricted object and a missing one give the same error. +- `list_objects`: everything this caller may read. Long on a large database; + use `select_schema` to answer a question. +- `refresh_catalog`: re-read the structure after a migration or a grant change. +- `health`: server status, object count, and whether the catalog is stale. +- `answer`, `semantic_query`, `deep_answer`: need a model provider configured + on the server. Without one, `answer` returns the scoped schema for you to + write the SQL yourself, and the other two report that they are off. + +## Limits + +- Over stdio, the server trusts the `principal` and `roles` the client sends. + It scopes what the model sees; it does not authenticate anyone. +- A table the selection left out cannot be queried from the prompt. If the + DDL looks incomplete for the question, call `select_schema` again with a + more specific question or use `describe_object`.