Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

docs(mcp): improve skill descriptions and guidelines (#18494)

p0nycf4e6b65f4f0
diff --git a/backend/api/mcp/CLAUDE.md b/backend/api/mcp/CLAUDE.md
index 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 Skill
1. 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.md
index 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 plan
diff --git a/backend/api/mcp/skills/grant-permission.md b/backend/api/mcp/skills/grant-permission.md
index 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 Permission
diff --git a/backend/api/mcp/skills/query.md b/backend/api/mcp/skills/query.md
index 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