Download packages/app/app-skills/skills/nocobase-app-development/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
Where does nocobase-app-development live?
The publisher keeps it at https://github.com/nocobase/nocobase.
Which agents can use nocobase-app-development?
Claude, Cursor, Codex, and Grok Build can read a SKILL.md you add from the publisher's repository. Grok Bot installs it when you send the skill's GitHub folder link in a chat.
From the publisher
SKILL.md
name
nocobase-app-development
description
- Primary entry for building complete NocoBase 3 applications and individual features: business and administration pages, routes, components, endpoints, data, permissions, services, translations, and tests. Use this application-local workflow instead of globally installed NocoBase 2 Skills. For local or published NocoBase 3 plugin packages, use the project plugin development Skill.
metadata
short-description: Develop features in a NocoBase 3 application
NocoBase 3 application development
When the task creates or maintains a plugin under this App's packages/, read <app-root>/.agents/skills/nocobase-app-plugin-development/SKILL.md by its explicit project path. It ships alongside this Skill in @nocobase/app-skills. Use this application's guidance for App-owned features and the plugin Skill for plugin-owned contracts and packaging; do not install the older global plugin development Skill.
Use this Skill when building a complete application or an individual feature: business and administration pages, endpoints, data, services and their tests.
For plugin-owned code, use the project plugin development Skill, whether the plugin stays local to this App or is published for reuse. Plugin development does not require a separate repository or a NocoBase source checkout.
Do not use it to upgrade the template this application was generated from, which is also how the application moves to a newer NocoBase version when the user asks to upgrade NocoBase or its core. That is .agents/skills/nocobase-app-upgrade/, which reconciles a newer template release against the application without reverting the user's work.
Check browser API compatibility for direct calls and third-party integrations. HTTPS-only APIs require capability detection and a clear user-facing explanation when unavailable. UUID generation and copying text must support HTTP; use createUuid() and copyText() from @nocobase/app-client.
Before you start
Read the application's AGENTS.md first for the rules that apply everywhere, and the .agents/rules/ files its index points to for your task. This Skill's references are the detail behind it. Before running any pnpm nocobase command, read the command line: it maps tasks to commands and states the flags an agent must not add on its own.
Confirm you are in an application and not a plugin package. An application has:
If instead you find client/plugin.ts, server/plugin.ts, or a defineServerPlugin() declaration, you are in a plugin package and this Skill does not apply.
Do not infer the application's capabilities from a template name or from this Skill. Inspect , , , , , and before deciding what is installed, registered, configured, or application-owned. and identify known template ancestry when present, but a new template remains valid without being listed here. Read only when those files identify one of the documented official templates.
For a new application or a feature spanning frontend and backend, identify the users' tasks, pages and key interactions together with the data, endpoint contracts and permissions before implementing either side. Read the frontend workflow at this point, not only when opening client/. Reuse existing requirements, designs and installed capabilities; a routine CRUD feature can use a short implementation plan without a separate design document. Keep API-only, UI-only and other explicitly limited requests within their requested scope.
Proceed through the authorized implementation and verification without a routine design approval stop. Ask early only when a material business rule or scope decision cannot be resolved from the requirements, existing decisions and conventions, when work exceeds authorization, or when the user explicitly requested review first. State reasonable assumptions, preserve prior answers and continue unaffected work while a necessary decision is pending. Internal design and acceptance reviews are quality checks, not additional user approval rounds.
Deliver the requested user operation across its layers: pages invoke real endpoints, data is saved and refreshed correctly, permissions hold, and loading, empty and failure states are handled. Backend tests or a design document alone are progress, not completion of a full application. If the backend is already implemented, reuse and check its contracts against the required pages, close any gaps and finish the frontend without restarting design approval. Report missing implementation and unavailable verification explicitly.
Choose where the feature belongs
For parent/child business flows, scoped references, single-person review or multi-step forms with private recoverable drafts, consult the business example catalogue and its runnable scenario index. Its resources supplement the existing list/edit patterns; read each scenario's integration dependencies before adapting it.
Build application-specific features directly in the application by default. Use a plugin when the user requests one or when code reuse or modular organization calls for a separately registered, maintainable feature. Create local plugins under packages/ with the project plugin development Skill; do not use the source repository's packages/plugins/ layout. The App builds and packages registered local plugins for deployment without an npm release. Publish only when distributing the plugin through a package registry.
Ordinary internal workspace packages can share code without plugin registration. Follow internal workspace packages, keeping one application at the workspace root with internal packages under packages/. The runnable package example supplies complete configuration and explains declaration watching.
Check the installed plugins first
NocoBase packages may publish Skills under .agents/skills/. Current application templates run pnpm nocobase skills sync automatically through postinstall; run it manually if install scripts were disabled or that directory is missing or stale. Confirm that the package is a direct @nocobase/* dependency or a registered plugin before relying on its Skill. The common capability mappings are:
The requirement sounds like
Read the Skill for
Email, IM, or in-app messages
@nocobase/app-plugin-notification
Knowledge bases, document spaces, search and document review
@nocobase/app-plugin-knowledge
Approval processes, joint decisions and approval tasks
@nocobase/app-plugin-approval (commercial Pro plugin)
Roles, permissions, per-user or per-record access
@nocobase/app-plugin-authorization
Sign-in, registration, sessions
@nocobase/app-plugin-authentication
File upload and metadata through Repository
@nocobase/app-plugin-file
File storage, disk configuration, or custom drivers
@nocobase/drive
Translated text and language switching
@nocobase/app-plugin-i18n
User administration and application-owned role assignment
@nocobase/app-plugin-users
Live updates, snapshot recovery and replacing business polling
@nocobase/realtime (nocobase-realtime)
Reading or writing data, schema changes, migrations
@nocobase/db
Read the relevant Skill before writing the feature, but treat this table as a map rather than an installed-package list. Implementing a permission system, a notification sender, or a scheduler by hand when a registered plugin provides one is the most expensive mistake available here.
For any required commercial NocoBase package, follow commercial package access: automatically probe pkg-v3 with existing credentials, install a compatible authorized package without prompting, and leave a brief conversation notice for unavailable access while continuing independent work. This includes plugins and commercial database drivers; do not infer access to one package from another.
For knowledge base requirements, check @nocobase/app-plugin-knowledge first and follow knowledge package integration. Apply the same automatic pkg-v3 access workflow when installation or update is needed. Read its synchronized Skill when available, otherwise its installed README, docs and public exports; do not assume it ships a Skill or build a substitute because one is absent.
For approval requirements, check @nocobase/app-plugin-approval first and follow approval integration prerequisites, then the plugin's installed Skill. Do not silently build a substitute approval engine from lifecycle examples. Simple single-person confirmation or rejection can remain lifecycle actions.
When the stages of a business record are fixed by developers rather than drawn by administrators — an expense report, a ticket, a contract, an order — build it with @nocobase/lifecycle as record lifecycles describes: the state stays in the record's own field and changes only through declared transitions. Declare only required business paths with precise sources and destinations; the diagram expands every from × to pair rather than analyzing routing logic. Follow readable process graphs before rendering dense definitions.
For notification configuration or sending, follow the notification plugin Skill: notification.channels maps each name to one flat channel configuration with type (provider remains a compatibility alias), and send({ idempotencyKey, messages }) supplies a complete message per Channel. Use native addresses; email and in-app arrays create independent deliveries, while Webhooks forbid to.
Install, update and customize plugins, and remove a direct NocoBase package, as plugins describes: pnpm nocobase plugin register, plugin update and package remove keep the manifest, the lockfile, the composition roots and the synchronized Skills consistent, so never hand-edit only one of them.
Business role assignments must be visible and editable through administration. Default to explicit users; do not assign application roles to every authenticated identity or broaden the inherited member role merely to enable a feature. Follow permission assignment safety and run the template's initialized-assignment guard before delivery.
Waiting feedback
For page/panel waits and native submit buttons, follow pending feedback. Use installed Loading/PendingButton and the shared timing hook; retain submission and list-state owners.
Choose sample data or a demo system
A request to add example customers, orders or tasks normally means sample data in the existing application. Use sample: true seeds or sampleDataToken; see sample data and demo systems. Keep required initialization data in ordinary seeds. Do not infer an isolated demo deployment from the words "demo data" alone.
A dedicated demo system has its own database and storage, repeatable business-data generation/clear/reset, visitor write policies and optional simulated external or Agent execution. For that requirement, follow the nocobase-app-plugin-demo-mode Skill. If @nocobase/app-plugin-demo-mode is not yet a dependency, register it with pnpm nocobase plugin register demo-mode, which also synchronizes its Skill; the Skill exists in the application only after synchronization. The plugin supplies the environment mechanisms; the application supplies its dataset, cleanup, management UI and any simulation adapters. Sample data alone supplies none of those operating policies. Use the user's stated deployment and lifecycle requirements to choose; if the intended scope remains ambiguous, clarify it before adding full-business cleanup or changing the environment mode. A trial, staging or customer environment where users keep their data, a provider's sandbox credentials and an in-app presentation mode are not demo systems.
When the application already depends on @nocobase/app-plugin-demo-mode, a change that adds business collections, outbound integrations or background jobs also updates the demo dataset's cleanup and adapters; follow that Skill's maintenance section.
Deliver system administration by default
When a user asks you to build a complete application, deliver the System settings structure (System settings navigation) and administration pages alongside the business features, unless the user explicitly excludes them or requests a narrower deliverable such as an API-only service or a prototype explicitly limited to business screens. Users do not need to request administration pages individually. Include user management and role and permission management by default. Register workflow management, background tasks and other applicable administration as module cards of the System settings home; show execution status, failures and supported recovery actions within each capability's pages, without an additional Operational monitoring group. Reuse existing pages and installed plugins, and implement missing application-owned pages. Read system administration for the baseline, capability-specific pages and acceptance criteria. For a focused feature change, extend existing administration where that feature requires it.
Whenever application requirements include a process to develop, deliver its workflow management pages by default, even when the user mentions only the business process. Reuse the installed workflow-management UI Library block, or install it with yes n | pnpm exec shadcn add @nocobase/workflow-management. Follow Lifecycle UI for installation, application adapters and the default layout: one Workflow management settings card with in-page Definitions and Executions tabs, definition diagrams with visible parameter forms, and execution details with history and effects. The two tab views use URL-backed child routes without sidebar navigation. Extend an existing management area rather than adding a duplicate. Follow the scope exceptions in system administration.
For process management, distinguish administrator-adjustable reviewers, departments, thresholds and other lifecycle parameters from workflow structure, which remains defined in source unless a supported visual designer is explicitly required.
Learn the endpoints from the API document
The running application describes every /api endpoint it serves — its own routes, every installed plugin's, the data endpoints and Better Auth's /api/auth/... — in an OpenAPI 3.1 document. Before calling an endpoint or building on one, fetch that document instead of reading route sources:
Replace /main with the application's APP_BASE_PATH. Swagger UI for people is at <APP_BASE_PATH>/api/swagger/docs. Reading either needs a signed-in session or an API key, which a signed-in user creates with POST <APP_BASE_PATH>/api/apiKeys; without one the routes answer 401, and an application with no access check registered, such as one without the authentication plugin, answers 404. Ask the user for a key rather than creating one yourself. HTTP API design explains how to read the document and how a new route declares itself in it.
Include administration by default
For every application feature, apply system settings delivery and place every administration surface in the System settings navigation (one sidebar entry, a home of cards by category, tabs inside a module): keep unused business settings disabled in a newly created application while retaining its restricted App Foundation entry; as the application develops beyond that basic shell, reconcile the template's prepared Users and Roles and permissions routes and the management surfaces for each capability actually used. Inspect this on every build or iteration, enable missing routes once and preserve already enabled pages, including workflow definitions, diagrams, configuration and authorized execution history. When building process rules, proactively declare appropriate thresholds and reviewer choices as validated, authorized business parameters and provide visible parameter forms in workflow management, with optional diagram-bound shortcuts to the same editor; the user need not ask for configurability. Apply the same check to non-workflow business policy, mutable dictionaries, business document numbering, important operation records and the other used capabilities in that reference. Follow its business administration recipes for application-owned implementations and acceptance. The real execution must consume the saved values; source/deployment configuration retains its owner. This is part of implementing the feature, not a separate user request.
For initialization prerequisites introduced by the feature, apply setup readiness: wire real required-role membership and applicable business relationship checks with the standard contextual hint. Users should see what configuration is missing and an authorized path to fix it. Installed plugins, read failures and missing business configuration are different states; keep the bare app and its protected App Foundation entry unchanged.
Frontend work
Before implementing interactions, follow component selection and source review: existing business component → installed shadcn primitive → registry addition → justified custom composition/primitive. Record the actual component source and run the targeted component checker before delivery; a matching screenshot alone does not justify duplicating a primitive. A date field follows Dates: read the matching official shadcn Date Picker example, reuse or compose client/components/date-picker.tsx once, reuse it on every page, then run the checker and the field's behavior tests; a native or shadcn Input date input is never a date picker.
Application and plugin UI share the UI design contract. Read the application's existing design records and original UI references first: record whether a reference controls appearance, structure or style, apply authorized page exceptions, and retain reusable decisions outside synchronized Skills. Use the contract's system-design section when planning a business system across modules; do not redesign the system for a small edit. Plugin implementation still belongs to nocobase-app-plugin-development, whose UI entry points to these same design and acceptance rules.
For business lists, reuse the template-provided DataTable and companions from #components/data-table, backed by the supported TanStack Table v8 dependency. Use its controlled manual mode for server paging/sorting. Do not replace it with an agent-written table engine when a dependency version is incompatible; inspect and repair the dependency first. See tables.
Use the frontend workflow selected during feature planning, or select it before a frontend-only change. Routine pages and CRUD using established patterns take the quick workflow; complex interactions and cross-module design decisions take the full workflow with internal design and acceptance reviews. Theme changes use their own verification. Each workflow routes to the relevant UI guidelines and frontend handbook; none adds a default user approval round.
The handbook's "Look up by task" table routes each frontend task to the sections that cover it, and the worked example holds the complete files of the projects feature its rules are illustrated with. Components are shadcn/ui primitives, added with the CLI when a page first needs one: the shadcn/ui skill in references/frontend/shadcn/ covers their API and composition rules, and its guide in this handbook says what to read there and where this application departs from it.
Choose your reference
Read the page for the task in front of you. Do not read all of them.
Task
Read
Anything under client/: pages, routes, components, styling, forms, API calls, copy, frontend tests
Flowcharts, process diagrams or lifecycle state diagrams
Use UI Library @nocobase/flow-diagram for generic graphs and @nocobase/lifecycle-diagram for lifecycle descriptions; see diagram guidance and the UI catalog. Preserve their application theme tokens.
Use @nocobase/app-testing for database, server, client or CLI tests; verify before finishing
A feature with a page and an API usually needs migrations, server routes, and a frontend change that follows the frontend workflow.
The three database pages above are the application side — where the files live, which commands run them, how connections are configured. The database API they are written against belongs to @nocobase/db and is documented by the nocobase-db Skill synchronized alongside this one. Read that Skill before writing a migration, a seed, or a query.
Frontend validation complements server-side validation and does not replace it.
Business permissions
When users describe different jobs, team responsibilities, confidential data, collaboration, field editing or restricted operations, read application permission development and the installed nocobase-app-plugin-authorization Skill before implementing the feature. Design pages, business actions and record scopes separately; apply database policies on the server and use client checks for visibility. The dedicated Skill covers declarations, custom scopes, relations, inherited subjects, optional rules, assignments and verification. Keep application-owned implementation in this App rather than scaffolding a plugin.
Database configuration factories
When a database driver requires @nocobase/db as a runtime peer, keep both in dependencies. TypeScript also uses that declaration to resolve inferred database configuration through the public package name; putting it only in devDependencies can cause TS2883 in an installed application even while a source workspace builds successfully.
Declare database defaults with defineAppDatabaseConfig from @nocobase/app-server/database. When switching or adding connections, read database connections for complete examples, YAML overrides, schema ownership and verification.
Where to work
Business code belongs in a small, stable set of places:
Everything else — client/routing/, client/layouts/, client/theme/, the server entry points, the build scripts, the tsconfigs — is the framework structure the template provides and evolves. Prefer the mechanism the system already offers: most work that looks like it needs a change there does not. Application structure maps every directory and the composition files.
When the built-in mechanism genuinely cannot express the requirement, changing that structure is a legitimate answer. Comment what you changed and why the built-in path did not fit, and in the same change record the application-specific guidance in the matching .agents/rules/<topic>.md, adding its entry to the AGENTS.md index, so the guidance still describes the real application. Do not write the detail into AGENTS.md itself: it is a small always-on index of at most 32 KB that every agent loads on every start. The synchronized NocoBase Skills are package-owned; propose a change to their source package when the shared framework guidance itself is wrong.
When you do change the shell (client/layouts/, client/routing/), keep the behaviors listed in customizing the shell: a single App shell with administration pages under its one System settings entry rather than a separate settings layout, the language submenu, navigation group state, permission refresh and sign-out handling.
Ownership
You own pages, components, endpoints, tables, migrations, services,
translations, tests, navigation, theme, business logic
Packages own their routes, components, tokens, services, internal tables,
and any skills/ they publish
Generated .agents/skills/ — synchronized copies, gitignored, replaced
wholesale on the next sync; never edit
.claude/skills/ — symbolic links to the above so Claude Code
discovers them; gitignored, rewritten by the same sync
Rules .agents/rules/ — application-specific guidance, committed and
application-owned; AGENTS.md indexes it
Config config.yml — written by pnpm nocobase config init, gitignored, holds
secrets; document options in config.example.yml instead
Reach a plugin's capability only through its documented package exports. Never import a plugin's internal source path or write to its tables directly.
Reversible customization
When customizing template or registry UI, prefer existing props and composition, then new application components outside client/extensions/. Keep the original extension implementation as the reusable baseline; edit it only when explicitly requested or when composition cannot reasonably meet the requirement, and explain that choice. See styling.
Treat disabling a feature as a reversible availability change by default: preserve its page and component source, conditionally exclude or guard its route, and hide its links and actions. A hidden navigation item alone does not disable direct URL access. Enforce the same feature policy on the server so direct API calls cannot execute the disabled operation. Do not delete feature code merely to remove it from the current UI; explicit permanent removal can justify deletion. See pages and routes.
When workflows or approvals are used, deliver a standard process-management table first, even for a single process. A row opens that process's definition/design, node configuration and scoped execution history. Use the standard vertically arranged, automatically sized lifecycle diagram by default, with readable node summaries and configuration buttons; do not wait for an explicit request for these system settings. Reconcile later processes into the same directory and validate their identifiers and authorization on the server; a bare Home-only create-app still gets no unused settings. See system settings delivery.
Non-negotiables
These cause real damage and appear in every reference:
Every server route owns its own authentication and authorization. Mounting under /api authenticates nothing.
Every /api route follows HTTP API design. camelCase paths, { data } on success, ApiError on failure, input validated through apiValidator(), and a describeRoute() declaration for the API document. Never hand-write an error body.
A migration is immutable history and self-contained. Never import an evolving definition into one. Never edit one whose branch is merged, not even to reformat it: change the schema incrementally with a new migration. See migrations change incrementally.
Every user-visible string goes through a translation key, the English built into shadcn/ui primitives included.
Let the owning page supply PageContainer. One per page; inline child pages and tabs use the parent's, covering child pages add their own, overlays use their own container. See section 2 of pages and routes.
Visual consistency is application-wide. Restyling only your part is a defect. Change the design tokens if a change is needed.
Route paths never include the deployment base path. The runtime restores it.
Route navigation creates sidebar entries. Declare navigation in client/routes.ts; pages load data with useApiClient (see calling the API).
Reach for the built-in mechanism first. Changing framework structure is allowed when nothing else fits — comment it and record it in .agents/rules/.
Tests live in tests/, never beside the source; browser tests against a running application go in tests/playwright/.
Remove direct NocoBase packages with package remove after reviewing their usage. Do not hand-delete only the manifest entry or leave synchronized Skills and plugin registrations behind.
The development server
When reporting or opening this application's address, use the Local: URL printed by pnpm dev, including the application base path; never infer it from default ports or from a response on Vite's port. The development server covers verifying an existing run's URL, what restarts the development run, file watching, and developing the client against another backend with PROXY_TARGET_URL.
Finishing
pnpm build --help (or -h) lists build options and exits without loading build dependencies, running hooks, or modifying dist/. Every successful build records nocobase.buildTarget in dist/package.json, including builds with no native modules: platform, arch, libc, nodeMajor, and nodeAbi. Use libc only for Linux; its value on other platforms is a compatibility placeholder. Deployment checks should compare these fields with the host runtime and also respect engines.node. With --target current (the default), the Node version and ABI come from the running process; an explicit platform target defaults to Node 24 unless --node-version is supplied.
When building for another platform, pass --target and verify the native binaries retained in dist/node_modules. better-sqlite3 13 bundles N-API binaries for multiple platforms; Alpine targets need the linuxmusl binary, while other Linux targets use the linux binary.
For each change, scope all verification to affected files, projects, or packages and their affected consumers, including formatting, lint, type checking, tests, builds, and runtime checks. Use supported file selectors, project configurations, and workspace package filters. Do not default to full-application or workspace-wide commands or pnpm check. Run the smallest supported scope when a required check cannot be narrowed further, and explain why. Expand or repeat checks only when further changes, dependency impact, configuration changes, or failures justify it, or the user requests it. Documentation-only changes need formatting and link checks for changed documents, not type checking, runtime tests, or builds. Follow Testing and verification for selection examples.
Verify observable behavior, not just that the commands passed. Testing and verification lists what to check for each kind of change.
After adding or removing a language in client/locales/ or server/locales/, run pnpm nocobase locales check. It compares only the two language lists: it reports a language declared on one side alone and exits nonzero until the lists align. A client-only language is still supported at runtime and the server falls back to English; add matching server translations when server-produced text should use that language.
Application startup defaults belong in config.yml: i18n.defaultLocale for the language, and client.app.defaultColorScheme and client.app.defaultTheme for appearance. Valid browser-local choices take precedence. Which languages the interface offers is not configured — client/locales/ is that list, while server/locales/ independently defines the server's translated languages. See internationalization, frontend copy and themes and tokens.
Logging
Use the application logging service for diagnostics so entries carry application identity and follow its level and output policy. Development pretty output uses local time and displays [appId/logger]; file and JSON console output retain UTC timestamps and structured context. Request starts and headers, configuration diagnostics and AI resource loading stages are DEBUG; request completions and AI resource totals are INFO. Default optional ai/skills directories may be absent; explicitly configured missing directories still warn.
Deployed releases carry their own runtime and logging packages: an old release keeps the formatter it was built with. Upgrade the application dependencies, rebuild and deploy a new release; never edit a deployed artifact or intercept process-wide stdout to rewrite its logs. Verify console enablement and pretty mode after upgrading.
Authentication diagnostics use the application auth logger unless an explicit authentication logger is configured. A missing Better Auth base URL is a configuration warning, not a logging error: configure app.publicOrigin with the externally reachable origin in the application deployment configuration. Do not substitute the internal Host bind address or suppress the warning to make startup appear clean.
Storage
For file storage configuration and custom driver factories in drive.disks, read .agents/skills/nocobase-drive/SKILL.md, supplied by the installed @nocobase/drive package. Keep the application's shared Drive provider and token when adding a custom disk. File storage identifies the application configuration entry point.
Standalone source and compiled entries share the deployment directory's storage; APP_STORAGE_DIR selects another storage directory, and explicit storage paths take precedence over it. Embedded applications use Host-provided paths. Expanded releases live at appRevisionsDir/<appId>/<sha256> and restart recovery requires their installed metadata. Build archives use storage/exports/dist.tar.gz.
Process UI delivery gate
When adding a business process, read Lifecycle UI before selecting a renderer. Current templates already ship the standard React Flow components and workflow-management parts. Preserve their default style unless the user explicitly requests another style; declare and connect suitable business parameters and contextual configuration automatically. UI Registry entries are not npm packages: an npm 404 is not installation failure. Acceptance must compare actual component use and configuration behavior to the original requirement, even if an intermediate design approved a fallback.