Database governance built for humans and agents — controlling changes and access across every major database.
Go cicddata-governancedata-maskingdata-securitydatabase-accessdatabase-governancedevopsdevsecopsflywaygitopsliquibasemongodbmysqloraclepostgresqlschema-migrationssecuritysql-clientsqlservertidb
docs(mcp): improve skill descriptions and guidelines (#18494)
p0nycf4e6b65f4f0
diff --git a/backend/api/mcp/CLAUDE.md b/backend/api/mcp/CLAUDE.mdindex d5ec8939b7..d639a217aa 100644--- a/backend/api/mcp/CLAUDE.md+++ b/backend/api/mcp/CLAUDE.md@@ -10,10 +10,9 @@ Skills are markdown files in `skills/` that get embedded into the binary and ser```skills/-├── execute-sql.md-├── create-instance.md-├── create-project.md-└── schema-change.md+├── query.md+├── database-change.md+└── grant-permission.md```### Skill Format@@ -23,7 +22,7 @@ Each skill file must have YAML frontmatter followed by markdown content:```markdown---name: skill-name-description: Short description for the skill list+description: Use when [triggering conditions] - [what it does]---# Skill Title@@ -59,26 +58,31 @@ One-liner explaining what this accomplishes.### Guidelines-1. **Always include `search_api` before `call_api`** - Claude needs to fetch the schema to know exact field names+1. **Description starts with "Use when..."** - Include triggering conditions and keywords for discoverability-2. **Use placeholders consistently**:+2. **Always include `search_api` before `call_api`** - Claude needs to fetch the schema to know exact field names++3. **Use placeholders consistently**:- `{project-id}` - project identifier- `{instance-id}` - instance identifier- `{database-name}` - database name- `{sheet-id}` - sheet identifier- `{plan-id}` - plan identifier-3. **Note encoding requirements** - e.g., sheet content is base64 encoded+4. **Prefer discovery over hardcoding** - Use `search_api(schema="EnumName")` instead of listing enum values++5. **Note encoding requirements** - e.g., sheet content is base64 encoded-4. **List required permissions** in Prerequisites+6. **List required permissions** in Prerequisites-5. **Include common errors** to help with troubleshooting+7. **Include common errors** to help with troubleshooting### Adding a New Skill1. Create `skills/new-skill.md` with frontmatter and content-2. Run tests: `go test ./backend/api/mcp/... -run TestGetSkill`-3. The skill is automatically discovered via `//go:embed`+2. Update `tool_skill.go` to add the skill name to `getSkillDescription`+3. Update `tool_skill_test.go` to include the skill in `TestGetSkillAllSkillsLoadable`+4. Run tests: `go test ./backend/api/mcp/... -run TestGetSkill`### Testing@@ -99,5 +103,5 @@ const getSkillDescription = `Get step-by-step guides for Bytebase tasks.**Workflow:** get_skill("task") → search_api(operationId) → call_api(...)-Skills: execute-sql, create-instance, create-project, schema-change, NEW-SKILL`+Skills: query, database-change, grant-permission, NEW-SKILL````diff --git a/backend/api/mcp/skills/database-change.md b/backend/api/mcp/skills/database-change.mdindex d7a2cdbc69..53318b7f43 100644--- a/backend/api/mcp/skills/database-change.md+++ b/backend/api/mcp/skills/database-change.md@@ -1,6 +1,6 @@---name: database-change-description: Create database change issues (single or batch) through review workflow+description: Use when making schema changes (DDL), data migrations, ALTER TABLE, CREATE TABLE, or deploying SQL changes through review workflow---# Database Change@@ -36,7 +36,7 @@ call_api(operationId="SheetService/CreateSheet", body={Note: `Q1JFQVRFIFRBQkxFIHVzZXJzIChpZCBJTlQgUFJJTUFSWSBLRVkpOw==` decodes to `CREATE TABLE users (id INT PRIMARY KEY);`-**Engine values:** `POSTGRES`, `MYSQL`, `TIDB`, `CLICKHOUSE`, `SNOWFLAKE`, `SQLITE`, `MONGODB`, `REDIS`, `ORACLE`, `MSSQL`, `MARIADB`, `OCEANBASE`+Use `search_api(schema="Engine")` to discover valid engine values.### Step 2: Create a plandiff --git a/backend/api/mcp/skills/grant-permission.md b/backend/api/mcp/skills/grant-permission.mdindex b9d30de62b..ee926d0d1a 100644--- a/backend/api/mcp/skills/grant-permission.md+++ b/backend/api/mcp/skills/grant-permission.md@@ -1,6 +1,6 @@---name: grant-permission-description: Grant roles and permissions to users at workspace or project level+description: Use when granting roles, managing access control, adding users to projects, or setting up RBAC permissions---# Grant Permissiondiff --git a/backend/api/mcp/skills/query.md b/backend/api/mcp/skills/query.mdindex 0715e50cb0..267d54858e 100644--- a/backend/api/mcp/skills/query.md+++ b/backend/api/mcp/skills/query.md@@ -1,6 +1,6 @@---name: query-description: Run SQL queries on databases+description: Use when running SQL queries, executing SELECT/INSERT/UPDATE/DELETE statements, or fetching data from databases---# Execute SQL