OpenMetadata Development Workflow
This skill is loaded automatically at session start. It ensures you follow the right workflow for every task.
Before Starting Any Task
Check which skills apply to your task and use them. This is not optional — if a skill applies, you must follow it.
Skill Selection Guide
| Task type |
Required skill(s) |
| New feature (multi-file) |
/planning then /tdd then /test-enforcement then /verification |
| Bug fix |
/systematic-debugging then /tdd (write regression test) then /verification |
| New API endpoint |
/planning then /tdd then /test-enforcement (must include integration test) |
| New connector |
/connector-standards then /connector-building then /test-enforcement |
| UI component |
Read openmetadata-ui/src/main/resources/ui/DEVELOPER_HANDBOOK.md first (folder structure + file naming for any new file), then /ui-core-components + /react-best-practices + /composition-patterns before writing, then /tdd, then /web-design-guidelines after, then /test-enforcement (must include Jest + Playwright if user-facing) |
| UI a11y / UX / design audit |
/web-design-guidelines |
| React perf work (re-renders, waterfalls, bundle) |
/react-best-practices |
| Code review / PR review |
/code-review then /test-enforcement |
| Opening / finalizing a PR |
/test-enforcement then /verification then /pr-checklist |
| Connector review |
/connector-review |
| E2E test creation |
/playwright |
| Finishing implementation |
/test-enforcement then /verification |
Note: Connector skills (/connector-standards, /connector-building, /connector-review) and /playwright are part of the OpenMetadata Skills plugin and ship together with this workflow skill. They are defined in the skills/ directory alongside this file.
Why the UI row names skills explicitly: a skill only loads when it is invoked, and the model
decides that from the skill's own description. /composition-patterns describes itself as being
for refactoring prop proliferation and building component libraries, and
/web-design-guidelines describes itself as being for "review my UI" / "check accessibility" —
so neither reliably fires on "build me a component". Naming them here is what makes them part of
the workflow instead of a coin flip. Invoke /web-design-guidelines after the component
exists: it is an audit, and running it first works against its own trigger.
/react-best-practices, /composition-patterns and /web-design-guidelines are vendored from
vercel-labs/agent-skills (MIT) under
skills/vendor/. They are authoring aids, not gates — enforcement is ui-checkstyle, see
docs/ui-code-quality-gate.md.
Workflow Rules
Plan before coding. For any non-trivial task, use /planning to design the approach before writing code.
Test-first when possible. Use /tdd to write failing tests before implementation. This applies to Java, Python, and TypeScript equally.
Always enforce test coverage. Before any PR, use /test-enforcement to verify:
- 90% line coverage on changed Java classes
- Integration tests for all changed/new API endpoints
- Playwright E2E tests for new user-facing features
- Jest unit tests for new React components
Verify with evidence. Use /verification before claiming completion. Show actual test output, not claims.
Review before merging. Use /code-review for two-stage review (spec compliance + code quality).
Fill the PR template completely. Use /pr-checklist before gh pr create to gather every required section: linked issue, high-level design (large PRs), tests + coverage, UI screen recording, and manual test steps.
OpenMetadata Cross-Layer Checklist
When your task touches multiple layers, ensure all are synchronized:
CLAUDE.md Takes Precedence
If CLAUDE.md instructions conflict with any skill, CLAUDE.md wins. Skills are supplementary workflows, not overrides.
1---
2name: openmetadata-workflow
3description: Meta-skill loaded at session start. Directs Claude to check for applicable OpenMetadata skills before starting any task. Ensures structured workflows are followed.
4metadata:
5 source: https://skillmd.com/skills/open-metadata/openmetadata-workflow
6---
7
8# OpenMetadata Development Workflow
9
10This skill is loaded automatically at session start. It ensures you follow the right workflow for every task.
11
12## Before Starting Any Task
13
14**Check which skills apply to your task and use them.** This is not optional — if a skill applies, you must follow it.
15
16### Skill Selection Guide
17
18| Task type | Required skill(s) |
19|---|---|
20| New feature (multi-file) | `/planning` then `/tdd` then `/test-enforcement` then `/verification` |
21| Bug fix | `/systematic-debugging` then `/tdd` (write regression test) then `/verification` |
22| New API endpoint | `/planning` then `/tdd` then `/test-enforcement` (must include integration test) |
23| New connector | `/connector-standards` then `/connector-building` then `/test-enforcement` |
24| UI component | **Read `openmetadata-ui/src/main/resources/ui/DEVELOPER_HANDBOOK.md` first** (folder structure + file naming for any new file), then `/ui-core-components` + `/react-best-practices` + `/composition-patterns` **before writing**, then `/tdd`, then `/web-design-guidelines` **after**, then `/test-enforcement` (must include Jest + Playwright if user-facing) |
25| UI a11y / UX / design audit | `/web-design-guidelines` |
26| React perf work (re-renders, waterfalls, bundle) | `/react-best-practices` |
27| Code review / PR review | `/code-review` then `/test-enforcement` |
28| Opening / finalizing a PR | `/test-enforcement` then `/verification` then `/pr-checklist` |
29| Connector review | `/connector-review` |
30| E2E test creation | `/playwright` |
31| Finishing implementation | `/test-enforcement` then `/verification` |
32
33> **Note:** Connector skills (`/connector-standards`, `/connector-building`, `/connector-review`) and `/playwright` are part of the OpenMetadata Skills plugin and ship together with this workflow skill. They are defined in the `skills/` directory alongside this file.
34
35> **Why the UI row names skills explicitly:** a skill only loads when it is invoked, and the model
36> decides that from the skill's own `description`. `/composition-patterns` describes itself as being
37> for *refactoring* prop proliferation and *building component libraries*, and
38> `/web-design-guidelines` describes itself as being for *"review my UI" / "check accessibility"* —
39> so neither reliably fires on "build me a component". Naming them here is what makes them part of
40> the workflow instead of a coin flip. Invoke `/web-design-guidelines` **after** the component
41> exists: it is an audit, and running it first works against its own trigger.
42>
43> `/react-best-practices`, `/composition-patterns` and `/web-design-guidelines` are vendored from
44> [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) (MIT) under
45> `skills/vendor/`. They are authoring aids, not gates — enforcement is `ui-checkstyle`, see
46> [`docs/ui-code-quality-gate.md`](../../docs/ui-code-quality-gate.md).
47
48### Workflow Rules
49
501. **Plan before coding.** For any non-trivial task, use `/planning` to design the approach before writing code.
51
522. **Test-first when possible.** Use `/tdd` to write failing tests before implementation. This applies to Java, Python, and TypeScript equally.
53
543. **Always enforce test coverage.** Before any PR, use `/test-enforcement` to verify:
55 - 90% line coverage on changed Java classes
56 - Integration tests for all changed/new API endpoints
57 - Playwright E2E tests for new user-facing features
58 - Jest unit tests for new React components
59
604. **Verify with evidence.** Use `/verification` before claiming completion. Show actual test output, not claims.
61
625. **Review before merging.** Use `/code-review` for two-stage review (spec compliance + code quality).
63
646. **Fill the PR template completely.** Use `/pr-checklist` before `gh pr create` to gather every required section: linked issue, high-level design (large PRs), tests + coverage, UI screen recording, and manual test steps.
65
66### OpenMetadata Cross-Layer Checklist
67
68When your task touches multiple layers, ensure all are synchronized:
69
70- [ ] JSON Schema in `openmetadata-spec/` → run `make generate`
71- [ ] Connection schema → run `yarn parse-schema`
72- [ ] Java entity changes → Flyway migration in `bootstrap/sql/migrations/`
73- [ ] Backend API changes → update frontend API client
74- [ ] New UI strings → add to `locale/languages/en-us.json` then run `yarn i18n`
75- [ ] Java files → run `mvn spotless:apply`
76- [ ] Python files → run `make py_format && make py_format_check`
77- [ ] TypeScript/React files → run `yarn organize-imports:cli && yarn lint:fix && yarn pretty:base --write`
78- [ ] New source files → ensure Apache 2.0 license header (run `yarn license-header-fix`)
79- [ ] Application changes → run `yarn generate:app-docs`
80
81### CLAUDE.md Takes Precedence
82
83If CLAUDE.md instructions conflict with any skill, **CLAUDE.md wins**. Skills are supplementary workflows, not overrides.