Skip to content

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

chore: migrate agent instructions to AGENTS.md,workdir:/Users/p0ny/.codex/worktrees/7300/bytebase-mux,yield_time_ms:1000, (#19837)

p0nyc81e1176bd20
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000000..2af509d2a6
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,214 @@
+This file provides guidance to AI coding assistants when working with code in this repository.
+
+## Project Architecture
+
+- Database schema is defined in `./backend/migrator/migration/LATEST.sql`
+- Database migration files are in `./backend/migrator/<<version>>/`
+ - `TestLatestVersion` in `./backend/migrator/migrator_test.go` needs update after new migration files are added
+ - `./backend/migrator/migration/LATEST.sql` should be updated for DDL migrations
+- Files in `./backend/store` are mappings to the database tables
+
+## Development Workflow
+
+**ALWAYS follow these steps after making code changes:**
+
+### Go Code Changes
+
+1. **Format** — Run `gofmt -w` on modified files
+2. **Lint** — Run `golangci-lint run --allow-parallel-runners` to catch issues
+ - **Important**: Run golangci-lint repeatedly until there are no issues (the linter has a max-issues limit and may not show all issues in a single run)
+3. **Auto-fix** — Use `golangci-lint run --fix --allow-parallel-runners` to fix issues automatically
+4. **Test** — Run relevant tests before committing
+5. **Build** — `go build -ldflags "-w -s" -p=16 -o ./bytebase-build/bytebase ./backend/bin/server/main.go`
+6. **Tidy** — After upgrading Go dependencies, run `go mod tidy` to clean up `go.mod` and `go.sum`
+
+### Frontend Code Changes
+
+1. **Fix** — Run `pnpm --dir frontend fix` to auto-fix ESLint + Biome issues (format, lint, organize imports)
+2. **Check** — Run `pnpm --dir frontend check` to validate without modifying files (for CI)
+3. **Type check** — Run `pnpm --dir frontend type-check`
+4. **Test** — Run `pnpm --dir frontend test`
+
+### Proto Changes
+
+1. **Format** — Run `buf format -w proto`
+2. **Lint** — Run `buf lint proto`
+3. **Generate** — Run `cd proto && buf generate`
+
+## Build/Test Commands
+
+### Backend
+
+```bash
+# Build
+go build -ldflags "-w -s" -p=16 -o ./bytebase-build/bytebase ./backend/bin/server/main.go
+
+# Start backend
+PG_URL=postgresql://bbdev@localhost/bbdev go run ./backend/bin/server/main.go --port 8080 --data . --debug
+
+# Run single test
+go test -v -count=1 github.com/bytebase/bytebase/backend/path/to/tests -run ^TestFunctionName$
+
+# Run multiple tests
+go test -v -count=1 github.com/bytebase/bytebase/backend/path/to/tests -run ^(TestFunctionName|TestFunctionNameTwo)$
+
+# Lint
+golangci-lint run --allow-parallel-runners
+```
+
+### Frontend
+
+```bash
+# Install dependencies
+pnpm --dir frontend i
+
+# Dev server
+pnpm --dir frontend dev
+
+# Fix (ESLint + Biome: format, lint, organize imports)
+pnpm --dir frontend fix
+
+# Check (validate without modifying, for CI)
+pnpm --dir frontend check
+
+# Type check
+pnpm --dir frontend type-check
+
+# Test
+pnpm --dir frontend test
+```
+
+### Proto
+
+```bash
+# Format
+buf format -w proto
+
+# Lint
+buf lint proto
+
+# Generate
+cd proto && buf generate
+```
+
+### Database
+
+```bash
+# Connect to Postgres
+psql -U bbdev bbdev
+```
+
+## Code Style
+
+### General
+
+- Follow Google style guides for all languages
+ - [Go](https://google.github.io/styleguide/go/)
+ - [TypeScript](https://google.github.io/styleguide/tsguide.html) and [JavaScript](https://google.github.io/styleguide/jsguide.html)
+- Write clean, minimal code; fewer lines is better
+- Prioritize simplicity for effective and maintainable software
+- Only include comments that are essential to understanding functionality or convey non-obvious information
+
+### Go
+
+- Use standard Go error handling with detailed error messages
+- Always use `defer` for resource cleanup like `rows.Close()` (sqlclosecheck)
+- Avoid using `defer` inside loops (revive) — use IIFE or scope properly
+
+### API and Proto
+
+- Follow [AIPs](https://google.aip.dev/general)
+- When AIP and the proto guide conflict, AIP takes precedence
+- Use `HELLO` for enum names, not `TYPE_HELLO`
+
+### Frontend
+
+- Follow TypeScript style with strict type checking
+- **i18n**: All user-facing display text in the UI must be defined and maintained in locale files under `./frontend/src/locales/` using the i18n internationalization system. Do not hardcode any display strings directly in the source code
+ - **No Empty Objects**: Do not add empty JSON objects (e.g., `"key": {}`) to locale files. Remove any empty objects you encounter
+- **Button Spacing**: Use `gap-x-2` for ALL button groups (modals, drawers, toolbars, inline actions). Never use `space-x` for buttons. See `./frontend/.claude/BUTTON_SPACING_STANDARDIZATION.md` for full guidelines
+
+### React (New Code)
+
+The frontend is migrating from Vue to React. **All new UI code should be written in React.**
+
+**Stack**: React + [Base UI](https://base-ui.com/) (`@base-ui/react`) + Tailwind CSS v4 + shadcn-style component patterns
+
+**Component patterns**:
+- Build UI components in the shadcn style — `class-variance-authority` (cva) for variant props, `clsx`/`tailwind-merge` for class merging
+- Wrap Base UI primitives (Button, Tabs, Input, etc.) with styled variants in `./frontend/src/react/components/ui/`
+- Use `useTranslation()` from `react-i18next` for i18n
+- Use CSS custom properties (`--color-accent`, `--color-error`, `--color-control-border`, etc.) for theme tokens shared with the Vue layer
+
+**Tailwind CSS v4**:
+- CSS-first config in `./frontend/src/assets/css/tailwind.css` — no JS config file
+- Custom utilities use `@utility`, design tokens use `@theme`
+- Default border color is `currentcolor` (compat shim in `tailwind.css` preserves v3 behavior)
+
+**Accessing Vue state from React**:
+- `useVueState(getter)` — React hook that subscribes to Vue reactive state (Pinia stores, refs, computed) via `useSyncExternalStore`. React components access stores directly — no bridge layer needed
+- React pages are self-contained: import Pinia stores, `router`, utility functions directly
+- React `.tsx` is compiled by esbuild (`react-tsx-transform` Vite plugin) and type-checked separately via `tsconfig.react.json` (excluded from vue-tsc)
+
+## Naming
+
+- Use American English
+- Avoid plurals like "xxxList" for simplicity and to prevent singular/plural ambiguity stemming from poor design
+
+### Imports
+
+- Use organized imports (sorted by the import path)
+
+### Formatting
+
+- Use linting/formatting tools before committing
+
+### Error Handling
+
+- Be explicit but concise about error cases
+
+## Pull Request Guidelines
+
+- **Code Review** — Follow [Google's Code Review Guideline](https://google.github.io/eng-practices/)
+- **Author Responsibility** — Authors are responsible for driving discussions, resolving comments, and promptly merging pull requests
+- **Description** — Clearly describe what the PR changes and why
+- **Testing** — Include information about how the changes were tested
+- **SonarCloud** — When creating or updating a PR, update `.sonarcloud.properties` to reflect the latest file structure. Use `sonar.exclusions` for generated code, build artifacts, and dependencies (directory paths only). Use `sonar.test.inclusions` for test file patterns (wildcards like `**/*_test.go`). Use `sonar.cpd.exclusions` to skip copy-paste detection on test files
+
+### Breaking Change Check (MANDATORY before `gh pr create`)
+
+**This is a required step in the PR creation workflow. Run `git diff main...HEAD` and check every item below BEFORE writing the `gh pr create` command. This step comes after pushing the branch and before creating the PR.**
+
+1. **API breaking changes** — removed/renamed endpoints, changed request/response formats, removed/renamed query parameters
+2. **Database schema breaking changes** — dropped columns/tables, non-backward-compatible migrations
+3. **Proto breaking changes** — removed/renamed fields, changed field numbers/types, removed RPCs
+4. **Configuration breaking changes** — removed flags, changed default behavior, renamed environment variables
+5. **Behavior changes** — changed default values, altered existing workflows, modified permission/access control logic
+6. **Webhook/event changes** — renamed/removed events, changed payload formats
+7. **UI workflow changes** — redesigned user-facing flows that change how users perform existing tasks (e.g., merging steps, splitting pages, changing navigation)
+
+**If ANY of the above apply:**
+1. Add `--label breaking` to the `gh pr create` command
+2. Include a `## Breaking Changes` section in the PR description summarizing what changed and what users need to be aware of
+
+Do NOT skip this check. Do NOT assume changes are non-breaking without reviewing the diff.
+
+## Common Go Lint Rules
+
+Always follow these guidelines to avoid common linting errors:
+
+- **Unused Parameters** — Prefix unused parameters with underscore (e.g., `func foo(_ *Bar)`)
+- **Modern Go Conventions** — Use `any` instead of `interface{}` (since Go 1.18)
+- **Confusing Naming** — Avoid similar names that differ only by capitalization
+- **Identical Branches** — Don't use if-else branches that contain identical code
+- **Unused Functions** — Mark unused functions with `// nolint:unused` comment if needed for future use
+- **Function Receivers** — Don't create unnecessary function receivers; use regular functions if receiver is unused
+- **Proper Import Ordering** — Maintain correct grouping and ordering of imports
+- **Consistency** — Keep function signatures, naming, and patterns consistent with existing code
+- **Export Rules** — Only export (capitalize) functions and types that need to be used outside the package
+- **Linting Command** — Always run `golangci-lint run --allow-parallel-runners` without appending filenames to avoid "function not defined" errors (functions are defined in other files within the package)
+
+## Miscellaneous
+
+- The database JSONB columns store JSON marshalled by `protojson.Marshal` in Go code. `protojson.Marshal` produces camelCased keys rather than the snake_case keys defined in the proto files. e.g. `task_run` becomes `taskRun`
+- When modifying multiple files, run file modification tasks in parallel whenever possible, instead of processing them sequentially
diff --git a/CLAUDE.md b/CLAUDE.md
index 37bbf27495..43c994c2d3 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,221 +1 @@
-This file provides guidance to AI coding assistants when working with code in this repository.
-
-## Project Architecture
-
-- Database schema is defined in `./backend/migrator/migration/LATEST.sql`
-- Database migration files are in `./backend/migrator/<<version>>/`
- - `TestLatestVersion` in `./backend/migrator/migrator_test.go` needs update after new migration files are added
- - `./backend/migrator/migration/LATEST.sql` should be updated for DDL migrations
-- Files in `./backend/store` are mappings to the database tables
-
-## Development Workflow
-
-**ALWAYS follow these steps after making code changes:**
-
-### Go Code Changes
-
-1. **Format** — Run `gofmt -w` on modified files
-2. **Lint** — Run `golangci-lint run --allow-parallel-runners` to catch issues
- - **Important**: Run golangci-lint repeatedly until there are no issues (the linter has a max-issues limit and may not show all issues in a single run)
-3. **Auto-fix** — Use `golangci-lint run --fix --allow-parallel-runners` to fix issues automatically
-4. **Test** — Run relevant tests before committing
-5. **Build** — `go build -ldflags "-w -s" -p=16 -o ./bytebase-build/bytebase ./backend/bin/server/main.go`
-6. **Tidy** — After upgrading Go dependencies, run `go mod tidy` to clean up `go.mod` and `go.sum`
-
-### Frontend Code Changes
-
-1. **Fix** — Run `pnpm --dir frontend fix` to auto-fix ESLint + Biome issues (format, lint, organize imports)
-2. **Check** — Run `pnpm --dir frontend check` to validate without modifying files (for CI)
-3. **Type check** — Run `pnpm --dir frontend type-check`
-4. **Test** — Run `pnpm --dir frontend test`
-
-### Proto Changes
-
-1. **Format** — Run `buf format -w proto`
-2. **Lint** — Run `buf lint proto`
-3. **Generate** — Run `cd proto && buf generate`
-
-## Build/Test Commands
-
-### Backend
-
-```bash
-# Build
-go build -ldflags "-w -s" -p=16 -o ./bytebase-build/bytebase ./backend/bin/server/main.go
-
-# Start backend
-PG_URL=postgresql://bbdev@localhost/bbdev go run ./backend/bin/server/main.go --port 8080 --data . --debug
-
-# Run single test
-go test -v -count=1 github.com/bytebase/bytebase/backend/path/to/tests -run ^TestFunctionName$
-
-# Run multiple tests
-go test -v -count=1 github.com/bytebase/bytebase/backend/path/to/tests -run ^(TestFunctionName|TestFunctionNameTwo)$
-
-# Lint
-golangci-lint run --allow-parallel-runners
-```
-
-### Frontend
-
-```bash
-# Install dependencies
-pnpm --dir frontend i
-
-# Dev server
-pnpm --dir frontend dev
-
-# Fix (ESLint + Biome: format, lint, organize imports)
-pnpm --dir frontend fix
-
-# Check (validate without modifying, for CI)
-pnpm --dir frontend check
-
-# Type check
-pnpm --dir frontend type-check
-
-# Test
-pnpm --dir frontend test
-```
-
-### Proto
-
-```bash
-# Format
-buf format -w proto
-
-# Lint
-buf lint proto
-
-# Generate
-cd proto && buf generate
-```
-
-### Database
-
-```bash
-# Connect to Postgres
-psql -U bbdev bbdev
-```
-
-## Code Style
-
-### General
-
-- Follow Google style guides for all languages
- - [Go](https://google.github.io/styleguide/go/)
- - [TypeScript](https://google.github.io/styleguide/tsguide.html) and [JavaScript](https://google.github.io/styleguide/jsguide.html)
-- Write clean, minimal code; fewer lines is better
-- Prioritize simplicity for effective and maintainable software
-- Only include comments that are essential to understanding functionality or convey non-obvious information
-
-### Go
-
-- Use standard Go error handling with detailed error messages
-- Always use `defer` for resource cleanup like `rows.Close()` (sqlclosecheck)
-- Avoid using `defer` inside loops (revive) — use IIFE or scope properly
-
-### API and Proto
-
-- Follow [AIPs](https://google.aip.dev/general)
-- When AIP and the proto guide conflict, AIP takes precedence
-- Use `HELLO` for enum names, not `TYPE_HELLO`
-
-### Frontend
-
-- Follow TypeScript style with strict type checking
-- **i18n**: All user-facing display text in the UI must be defined and maintained in locale files under `./frontend/src/locales/` using the i18n internationalization system. Do not hardcode any display strings directly in the source code
- - **No Empty Objects**: Do not add empty JSON objects (e.g., `"key": {}`) to locale files. Remove any empty objects you encounter
-- **Button Spacing**: Use `gap-x-2` for ALL button groups (modals, drawers, toolbars, inline actions). Never use `space-x` for buttons. See `./frontend/.claude/BUTTON_SPACING_STANDARDIZATION.md` for full guidelines
-
-### React (New Code)
-
-The frontend is migrating from Vue to React. **All new UI code should be written in React.**
-
-**Stack**: React + [Base UI](https://base-ui.com/) (`@base-ui/react`) + Tailwind CSS v4 + shadcn-style component patterns
-
-**Component patterns**:
-- Build UI components in the shadcn style — `class-variance-authority` (cva) for variant props, `clsx`/`tailwind-merge` for class merging
-- Wrap Base UI primitives (Button, Tabs, Input, etc.) with styled variants in `./frontend/src/react/components/ui/`
-- Use `useTranslation()` from `react-i18next` for i18n
-- Use CSS custom properties (`--color-accent`, `--color-error`, `--color-control-border`, etc.) for theme tokens shared with the Vue layer
-
-**Tailwind CSS v4**:
-- CSS-first config in `./frontend/src/assets/css/tailwind.css` — no JS config file
-- Custom utilities use `@utility`, design tokens use `@theme`
-- Default border color is `currentcolor` (compat shim in `tailwind.css` preserves v3 behavior)
-
-**Accessing Vue state from React**:
-- `useVueState(getter)` — React hook that subscribes to Vue reactive state (Pinia stores, refs, computed) via `useSyncExternalStore`. React components access stores directly — no bridge layer needed
-- React pages are self-contained: import Pinia stores, `router`, utility functions directly
-- React `.tsx` is compiled by esbuild (`react-tsx-transform` Vite plugin) and type-checked separately via `tsconfig.react.json` (excluded from vue-tsc)
-
-**Mount system** (temporary — removed after full migration):
-- React source lives in `./frontend/src/react/`
-- `ReactPageMount.vue` — generic Vue wrapper that mounts/unmounts the React root and syncs locale. Used by most pages
-- Pages that still depend on Vue components (modals, drawers not yet migrated) get a thin page-specific mount (e.g., `SubscriptionPageMount.vue`) — these are removed once those Vue deps are rebuilt in React
-- `mount.ts` lazy-loads pages via `import.meta.glob` — exported function name must match the file name
-- To add a new React page: (1) create `.tsx` in `pages/`, (2) point route to `ReactPageMount.vue` with `props: () => ({ page: "PageName" })`
-
-### Naming
-
-- Use American English
-- Avoid plurals like "xxxList" for simplicity and to prevent singular/plural ambiguity stemming from poor design
-
-### Imports
-
-- Use organized imports (sorted by the import path)
-
-### Formatting
-
-- Use linting/formatting tools before committing
-
-### Error Handling
-
-- Be explicit but concise about error cases
-
-## Pull Request Guidelines
-
-- **Code Review** — Follow [Google's Code Review Guideline](https://google.github.io/eng-practices/)
-- **Author Responsibility** — Authors are responsible for driving discussions, resolving comments, and promptly merging pull requests
-- **Description** — Clearly describe what the PR changes and why
-- **Testing** — Include information about how the changes were tested
-- **SonarCloud** — When creating or updating a PR, update `.sonarcloud.properties` to reflect the latest file structure. Use `sonar.exclusions` for generated code, build artifacts, and dependencies (directory paths only). Use `sonar.test.inclusions` for test file patterns (wildcards like `**/*_test.go`). Use `sonar.cpd.exclusions` to skip copy-paste detection on test files
-
-### Breaking Change Check (MANDATORY before `gh pr create`)
-
-**This is a required step in the PR creation workflow. Run `git diff main...HEAD` and check every item below BEFORE writing the `gh pr create` command. This step comes after pushing the branch and before creating the PR.**
-
-1. **API breaking changes** — removed/renamed endpoints, changed request/response formats, removed/renamed query parameters
-2. **Database schema breaking changes** — dropped columns/tables, non-backward-compatible migrations
-3. **Proto breaking changes** — removed/renamed fields, changed field numbers/types, removed RPCs
-4. **Configuration breaking changes** — removed flags, changed default behavior, renamed environment variables
-5. **Behavior changes** — changed default values, altered existing workflows, modified permission/access control logic
-6. **Webhook/event changes** — renamed/removed events, changed payload formats
-7. **UI workflow changes** — redesigned user-facing flows that change how users perform existing tasks (e.g., merging steps, splitting pages, changing navigation)
-
-**If ANY of the above apply:**
-1. Add `--label breaking` to the `gh pr create` command
-2. Include a `## Breaking Changes` section in the PR description summarizing what changed and what users need to be aware of
-
-Do NOT skip this check. Do NOT assume changes are non-breaking without reviewing the diff.
-
-## Common Go Lint Rules
-
-Always follow these guidelines to avoid common linting errors:
-
-- **Unused Parameters** — Prefix unused parameters with underscore (e.g., `func foo(_ *Bar)`)
-- **Modern Go Conventions** — Use `any` instead of `interface{}` (since Go 1.18)
-- **Confusing Naming** — Avoid similar names that differ only by capitalization
-- **Identical Branches** — Don't use if-else branches that contain identical code
-- **Unused Functions** — Mark unused functions with `// nolint:unused` comment if needed for future use
-- **Function Receivers** — Don't create unnecessary function receivers; use regular functions if receiver is unused
-- **Proper Import Ordering** — Maintain correct grouping and ordering of imports
-- **Consistency** — Keep function signatures, naming, and patterns consistent with existing code
-- **Export Rules** — Only export (capitalize) functions and types that need to be used outside the package
-- **Linting Command** — Always run `golangci-lint run --allow-parallel-runners` without appending filenames to avoid "function not defined" errors (functions are defined in other files within the package)
-
-## Miscellaneous
-
-- The database JSONB columns store JSON marshalled by `protojson.Marshal` in Go code. `protojson.Marshal` produces camelCased keys rather than the snake_case keys defined in the proto files. e.g. `task_run` becomes `taskRun`
-- When modifying multiple files, run file modification tasks in parallel whenever possible, instead of processing them sequentially
diff --git a/GEMINI.md b/GEMINI.md
index a6fce0a1c7..43c994c2d3 100644
--- a/GEMINI.md
+++ b/GEMINI.md
@@ -1 +1 @@
\ No newline at end of file
diff --git a/backend/api/mcp/AGENTS.md b/backend/api/mcp/AGENTS.md
new file mode 100644
index 0000000000..d639a217aa
--- /dev/null
+++ b/backend/api/mcp/AGENTS.md
@@ -0,0 +1,107 @@
+# MCP Server Skills
+
+This directory contains the Bytebase MCP server implementation with embedded skills that provide step-by-step guides for common tasks.
+
+## Writing Skills
+
+Skills are markdown files in `skills/` that get embedded into the binary and served via the `get_skill` tool.
+
+### File Structure
+
+```
+skills/
+├── query.md
+├── database-change.md
+└── grant-permission.md
+```
+
+### Skill Format
+
+Each skill file must have YAML frontmatter followed by markdown content:
+
+```markdown
+---
+name: skill-name
+description: Use when [triggering conditions] - [what it does]
+---
+
+# Skill Title
+
+## Overview
+
+One-liner explaining what this accomplishes.
+
+## Prerequisites
+
+- Required permissions
+- What you need to know beforehand
+
+## Workflow
+
+1. **Step name**:
+ ```
+ search_api(operationId="Service/Method")
+ ```
+ ```
+ call_api(operationId="Service/Method", body={...})
+ ```
+
+2. **Next step**:
+ ...
+
+## Common Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| error message | why it happens | how to fix |
+```
+
+### Guidelines
+
+1. **Description starts with "Use when..."** - Include triggering conditions and keywords for discoverability
+
+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
+
+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
+
+6. **List required permissions** in Prerequisites
+
+7. **Include common errors** to help with troubleshooting
+
+### Adding a New Skill
+
+1. Create `skills/new-skill.md` with frontmatter and content
+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
+
+```bash
+# Run all skill tests
+go test -v github.com/bytebase/bytebase/backend/api/mcp -run ^TestGetSkill
+
+# Verify skill loads correctly
+go test -v github.com/bytebase/bytebase/backend/api/mcp -run ^TestGetSkillAllSkillsLoadable
+```
+
+## Tool Description
+
+When adding new skills, update the tool description in `tool_skill.go`:
+
+```go
+const getSkillDescription = `Get step-by-step guides for Bytebase tasks.
+
+**Workflow:** get_skill("task") → search_api(operationId) → call_api(...)
+
+Skills: query, database-change, grant-permission, NEW-SKILL`
+```
diff --git a/backend/api/mcp/CLAUDE.md b/backend/api/mcp/CLAUDE.md
index d639a217aa..43c994c2d3 100644
--- a/backend/api/mcp/CLAUDE.md
+++ b/backend/api/mcp/CLAUDE.md
@@ -1,107 +1 @@
-# MCP Server Skills
-
-This directory contains the Bytebase MCP server implementation with embedded skills that provide step-by-step guides for common tasks.
-
-## Writing Skills
-
-Skills are markdown files in `skills/` that get embedded into the binary and served via the `get_skill` tool.
-
-### File Structure
-
-```
-skills/
-├── query.md
-├── database-change.md
-└── grant-permission.md
-```
-
-### Skill Format
-
-Each skill file must have YAML frontmatter followed by markdown content:
-
-```markdown
----
-name: skill-name
-description: Use when [triggering conditions] - [what it does]
----
-
-# Skill Title
-
-## Overview
-
-One-liner explaining what this accomplishes.
-
-## Prerequisites
-
-- Required permissions
-- What you need to know beforehand
-
-## Workflow
-
-1. **Step name**:
- ```
- search_api(operationId="Service/Method")
- ```
- ```
- call_api(operationId="Service/Method", body={...})
- ```
-
-2. **Next step**:
- ...
-
-## Common Errors
-
-| Error | Cause | Fix |
-|-------|-------|-----|
-| error message | why it happens | how to fix |
-```
-
-### Guidelines
-
-1. **Description starts with "Use when..."** - Include triggering conditions and keywords for discoverability
-
-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
-
-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
-
-6. **List required permissions** in Prerequisites
-
-7. **Include common errors** to help with troubleshooting
-
-### Adding a New Skill
-
-1. Create `skills/new-skill.md` with frontmatter and content
-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
-
-```bash
-# Run all skill tests
-go test -v github.com/bytebase/bytebase/backend/api/mcp -run ^TestGetSkill
-
-# Verify skill loads correctly
-go test -v github.com/bytebase/bytebase/backend/api/mcp -run ^TestGetSkillAllSkillsLoadable
-```
-
-## Tool Description
-
-When adding new skills, update the tool description in `tool_skill.go`:
-
-```go
-const getSkillDescription = `Get step-by-step guides for Bytebase tasks.
-
-**Workflow:** get_skill("task") → search_api(operationId) → call_api(...)
-
-Skills: query, database-change, grant-permission, NEW-SKILL`
-```
diff --git a/backend/demo/AGENTS.md b/backend/demo/AGENTS.md
new file mode 100644
index 0000000000..a7c885434d
--- /dev/null
+++ b/backend/demo/AGENTS.md
@@ -0,0 +1,107 @@
+# Demo Data Automation Guide
+
+This directory contains demo data for https://demo.bytebase.com.
+
+`dump.sql` is dumped from the meta database and holds schema and data for the demo.
+
+## Updating Demo Data
+
+### Automated Steps
+
+**Step 1: Start Postgres 16 in Docker**
+
+```bash
+docker run -d --name bytebase-demo-pg -e POSTGRES_USER=bbdev -e POSTGRES_DB=bbdev -e POSTGRES_HOST_AUTH_METHOD=trust -p 5433:5432 postgres:16-alpine
+```
+
+**Step 2: Build and start Bytebase backend in demo mode**
+
+```bash
+go build -p=16 -ldflags "-w -s" -o ./bytebase-build/bytebase ./backend/bin/server/main.go && PG_URL=postgresql://bbdev@localhost:5433/bbdev ./bytebase-build/bytebase --port 8080 --data . --debug --demo
+```
+
+In a separate terminal:
+```bash
+pnpm --dir frontend dev
+```
+
+---
+
+### Manual Step Required
+
+**Step 3: Make changes through the UI**
+
+1. Navigate to http://localhost:3000
+2. Make the desired changes to the demo data through the UI
+
+---
+
+### Automated Steps (continued)
+
+**Step 4: Dump the database using Docker**
+
+```bash
+docker exec bytebase-demo-pg pg_dump -U bbdev bbdev --disable-triggers --no-owner --column-inserts --on-conflict-do-nothing > backend/demo/data/dump.sql
+```
+
+Remove the restrict/unrestrict lines from the dump:
+
+```bash
+sed -i '' '/^\\restrict /d; /^\\unrestrict /d' backend/demo/data/dump.sql
+```
+
+Verify the dump versions match at the top of `backend/demo/data/dump.sql`:
+```sql
+-- Dumped from database version 16.0
+-- Dumped by pg_dump version 16.0
+```
+
+**Step 5: Test the updated dump**
+
+Stop the running Bytebase instance from Step 2, clean the Docker database, and restart:
+
+```bash
+# Clean the Docker Postgres database
+docker exec bytebase-demo-pg psql -U bbdev -d postgres -c "DROP DATABASE IF EXISTS bbdev;" -c "CREATE DATABASE bbdev;"
+
+# Restart Bytebase with the updated dump
+PG_URL=postgresql://bbdev@localhost:5433/bbdev ./bytebase-build/bytebase --port 8080 --data . --debug --demo
+```
+
+Verify the demo data loads correctly by checking the frontend at http://localhost:3000.
+
+**Step 6: Cleanup**
+
+Stop the Bytebase backend and frontend servers, then remove the Docker container:
+
+```bash
+# Stop backend server on port 8080
+lsof -ti:8080 | xargs kill -9 2>/dev/null || true
+
+# Stop frontend server on port 3000
+lsof -ti:3000 | xargs kill -9 2>/dev/null || true
+
+# Remove Docker container
+docker stop bytebase-demo-pg && docker rm bytebase-demo-pg
+```
+
+## Service Account
+
+Demo data service account credentials:
+- Email: `[email protected]`
+- Password: `bbs_EDyd8zleJVBEZyw81kLL`
+
+## AGENTS.md Usage
+
+To automate the demo data update using an AI coding agent:
+
+**Initial prompt (Steps 1-2):**
+```
+Update the demo data following backend/demo/AGENTS.md
+```
+
+**After completing manual UI changes in Step 3:**
+```
+I've finished making changes through the UI. Continue with Steps 4-6.
+```
+
diff --git a/backend/demo/CLAUDE.md b/backend/demo/CLAUDE.md
index 4849fff697..43c994c2d3 100644
--- a/backend/demo/CLAUDE.md
+++ b/backend/demo/CLAUDE.md
@@ -1,106 +1 @@
-# Demo Data Automation Guide
-
-This directory contains demo data for https://demo.bytebase.com.
-
-`dump.sql` is dumped from the meta database and holds schema and data for the demo.
-
-## Updating Demo Data
-
-### Automated Steps
-
-**Step 1: Start Postgres 16 in Docker**
-
-```bash
-docker run -d --name bytebase-demo-pg -e POSTGRES_USER=bbdev -e POSTGRES_DB=bbdev -e POSTGRES_HOST_AUTH_METHOD=trust -p 5433:5432 postgres:16-alpine
-```
-
-**Step 2: Build and start Bytebase backend in demo mode**
-
-```bash
-go build -p=16 -ldflags "-w -s" -o ./bytebase-build/bytebase ./backend/bin/server/main.go && PG_URL=postgresql://bbdev@localhost:5433/bbdev ./bytebase-build/bytebase --port 8080 --data . --debug --demo
-```
-
-In a separate terminal:
-```bash
-pnpm --dir frontend dev
-```
-
----
-
-### Manual Step Required
-
-**Step 3: Make changes through the UI**
-
-1. Navigate to http://localhost:3000
-2. Make the desired changes to the demo data through the UI
-
----
-
-### Automated Steps (continued)
-
-**Step 4: Dump the database using Docker**
-
-```bash
-docker exec bytebase-demo-pg pg_dump -U bbdev bbdev --disable-triggers --no-owner --column-inserts --on-conflict-do-nothing > backend/demo/data/dump.sql
-```
-
-Remove the restrict/unrestrict lines from the dump:
-
-```bash
-sed -i '' '/^\\restrict /d; /^\\unrestrict /d' backend/demo/data/dump.sql
-```
-
-Verify the dump versions match at the top of `backend/demo/data/dump.sql`:
-```sql
--- Dumped from database version 16.0
--- Dumped by pg_dump version 16.0
-```
-
-**Step 5: Test the updated dump**
-
-Stop the running Bytebase instance from Step 2, clean the Docker database, and restart:
-
-```bash
-# Clean the Docker Postgres database
-docker exec bytebase-demo-pg psql -U bbdev -d postgres -c "DROP DATABASE IF EXISTS bbdev;" -c "CREATE DATABASE bbdev;"
-
-# Restart Bytebase with the updated dump
-PG_URL=postgresql://bbdev@localhost:5433/bbdev ./bytebase-build/bytebase --port 8080 --data . --debug --demo
-```
-
-Verify the demo data loads correctly by checking the frontend at http://localhost:3000.
-
-**Step 6: Cleanup**
-
-Stop the Bytebase backend and frontend servers, then remove the Docker container:
-
-```bash
-# Stop backend server on port 8080
-lsof -ti:8080 | xargs kill -9 2>/dev/null || true
-
-# Stop frontend server on port 3000
-lsof -ti:3000 | xargs kill -9 2>/dev/null || true
-
-# Remove Docker container
-docker stop bytebase-demo-pg && docker rm bytebase-demo-pg
-```
-
-## Service Account
-
-Demo data service account credentials:
-- Email: `[email protected]`
-- Password: `bbs_EDyd8zleJVBEZyw81kLL`
-
-## Claude Code Usage
-
-To automate the demo data update using Claude Code:
-
-**Initial prompt (Steps 1-2):**
-```
-Update the demo data following backend/demo/CLAUDE.md
-```
-
-**After completing manual UI changes in Step 3:**
-```
-I've finished making changes through the UI. Continue with Steps 4-6.
-```