AI Tools in Workspace

You can use AI-based tools to build your projects in Liferay Workspace. The workspace includes rules and skills you can give any AI agent. These rules point your agent at your project’s structure, the Blade commands that build it, and the Liferay features it can use. The skills guide it through tasks such as creating objects, building pages and fragments, and styling a site.

Prerequisites

Ensure you’re running Blade 8.0.2 or higher before you create your workspace. To check your version, run:
```
blade version
```
If your version is below 8.0.2, update Blade:
```
blade update
```
If you don’t have Blade yet, see Blade CLI.
Create a Liferay Workspace:
```
blade init ai-workspace
```
Note

blade init runs the workspace’s updateWorkspace task, which downloads the latest published rules and skills into the new workspace. To skip the task, pass --skip-update-workspace (-s).
Blade prompts for your Liferay version. Provide it, and your workspace is created!
Change into the new workspace folder:
```
cd ai-workspace
```
This folder is the workspace root. Your agent reads the rules from here. To confirm the rules arrived, run ls .agents and check that liferay-rules.md is present.
Follow the instructions for your chosen AI agent to install it on your system. For example, Claude, Copilot, and Gemini have CLI tools that you must install and configure with your API key. Cursor and Windsurf embed their agents in their editors.

AI Rules

Liferay Workspace includes rules written in Markdown to guide AI agents in creating Liferay projects. You can find these rules in hidden folders inside the workspace.

The workspace root holds the hidden AI rules folders alongside the project's build and source folders.

The .agents folder at the workspace root is the canonical rules tree. Its entry point is liferay-rules.md, which routes an agent to the reference cards in rules/ and the skills in skills/ (see Skills and Reference Cards).

Expand this tree by saving each custom skill as a SKILL.md file within its own new folder in .agents/skills. Save custom reference cards as new files in .agents/rules. Map each new skill by adding a row to the Skill Router table in .agents/liferay-rules.md so agents can route requests to it.

Don’t modify the bundled skills or reference cards. Updating the rules overwrites every bundled file, including liferay-rules.md. Re-add your custom Skill Router rows after every update. If you use Claude Code, copy your custom skills and reference cards to the corresponding paths in the .claude folder and add your Skill Router rows to .claude/CLAUDE.md.

If your agent doesn’t find the rules on its own, point it to the .agents folder with a prompt like this:

Using the rules in the current working directory's `.agents` folder, create an object client extension project that....

The rules instruct agents to follow Liferay best practices:

Agents learn the structure of a Liferay Workspace.
Agents learn how to connect to and query the Liferay Model Context Protocol (MCP) server. See Using Liferay as an MCP Server.
Agents use Liferay Learn for documentation rather than their generic, potentially outdated training data.
Agents suggest modern Liferay best practices, such as building with objects, fragments, and client extensions.
Agents show you how to set up a workspace, download a bundle, and start the bundle using Blade.
Agents can create a functional “Hello World” project in the client-extensions folder with no boilerplate code.
Agents provide the exact blade command for building and deploying the project.
Agents guide you in viewing and interacting with frontend client extensions in a running Liferay instance.

Skills and Reference Cards

Beta

The developer skills are in beta. An agent’s performance depends on several variables, including but not limited to harness setup, model selection, and effort level.

Liferay’s rules are organized as skills and reference cards. A skill covers one task, such as scaffolding a client extension, building out a site, or deploying a Liferay Cloud project, and lives in its own folder as a SKILL.md file. A reference card holds data that skills look up, such as the client extension types or the page types Liferay provides.

Skills load on demand rather than all at once, so an agent reads only the skills that match your task.

The set of skills changes as Liferay adds and revises them, so ask your agent what it can do rather than working from a fixed list:

List the Liferay skills available in this workspace, and describe what each one does.

Writing Your Own Skills

Use the author-skill skill to write your own skill from source code, a spec document, or an interview with you. It matches your skill to the conventions of the skills already in the workspace and writes it to .agents/skills/[name]/SKILL.md. author-skill arrives with the other skills when blade init runs updateWorkspace or when you run that task yourself.

Describe the skill you want (or name author-skill in your prompt):
```
Write a skill for [task].
```
When the agent asks for a source, provide the absolute path to a repository or module, or the path or URL of a spec document. If you have neither, the agent interviews you and marks the result as unverified.
Answer the agent’s questions about the skill’s trigger phrases, scope, prerequisites, success signal, known failure modes, and neighboring skills. If the agent finds conflicts, such as a spec that disagrees with the code, resolve each discrepancy.
Review the draft. The agent shows the full skill, its path, the Skill Router row it proposes, and anything it couldn’t verify. It only publishes the skill after you approve it.

Publishing adds the skill’s row to the Skill Router table in .agents/liferay-rules.md. Running updateWorkspace replaces that file with Liferay’s published version and removes the row. An agent can miss a skill that has no Skill Router row unless you name the skill exactly in your prompt. Your skill’s own files stay unless Liferay publishes a skill with the same name.

Using Claude Code

Liferay provides a copy of the workspace rules and a plugin for Claude Code.

The `.claude` Folder

The .claude folder at the workspace root contains a copy of the .agents tree for Claude Code. Its entry point is CLAUDE.md, which mirrors liferay-rules.md.

When author-skill publishes a skill, it also copies that skill to the .claude folder and adds its row to .claude/CLAUDE.md. Back up your existing .claude/CLAUDE.md file before updating the rules, as each update overwrites CLAUDE.md. Re-add your custom Skill Router rows to this file after every update.

If Claude Code doesn’t report finding the rules, point it to the .claude folder in your prompt.

The Liferay Workspace Plugin

The Liferay Workspace plugin for Claude Code provides commands that set up, check, configure, and clean a workspace’s local environment. Liferay publishes it in the liferay/liferay-workspace-skills GitHub repository. You install the plugin in Claude Code, not in a workspace, and its commands act on the workspace where you run them.

In Claude Code, add the repository’s plugin marketplace:

/plugin marketplace add liferay/liferay-workspace-skills

Install the plugin:
```
/plugin install liferay-workspace@liferay-workspace-plugins
```
To use the plugin in all of your workspaces, choose user scope when Claude Code asks for an install scope.

The plugin’s commands are now available in Claude Code under the /liferay-workspace: prefix. For information about install scopes and managing plugins, see the Claude Code article Install and manage plugins.

The plugin provides commands such as these:

/liferay-workspace:clean: Cleans containers, build artifacts, and bundle data.
/liferay-workspace:doctor: Checks prerequisites and service health.
/liferay-workspace:feature-flags: Enables feature flags.
/liferay-workspace:mcp-server: Enables the Liferay MCP server.

The workspace’s own feature-flags and mcp-server skills handle the last two tasks without the plugin.

You can also run /liferay-workspace:setup to set up a local Docker environment. For information about the setup procedure, command list, prerequisites, and configuration, see the Liferay Workspace plugin README.

Adding or Updating AI Rules in an Existing Workspace

If your workspace already holds rules, clean up the legacy ones before you update. Older workspaces store rules in these locations:

Older files in .claude/rules, such as cx.md and setup.md
The .cursor, .gemini, .github, and .windsurf folders
The .workspace-rules folder

Migrate any custom rules you added to legacy locations into the .agents folder, then delete Liferay’s earlier rules to prevent outdated files from interfering. In .github, delete only Liferay’s rule files (such as copilot-instructions.md, instructions/cx.instructions.md, and instructions/setup.instructions.md), as that folder may also contain your own GitHub configurations.

The workspace’s updateWorkspace task copies the latest published .agents and .claude folders into the workspace root.

Warning

Back up your edits to the bundled rules and skills, including your custom Skill Router rows, before running this task. The task overwrites every file that shares a path with a published one, including .agents/liferay-rules.md and .claude/CLAUDE.md. Re-add your edits to the updated files rather than restoring the old files.

Confirm your workspace uses version 17.1.4 or higher of the workspace Gradle plugin. Check the com.liferay.gradle.plugins.workspace dependency in your settings.gradle file. To change it, see Updating Liferay Workspace and Bundled Plugins.
Run the task from the workspace root:
```
blade gw updateWorkspace
```
You can alternatively run ./gradlew updateWorkspace. When the task finishes, Gradle reports BUILD SUCCESSFUL and the workspace root contains .agents/liferay-rules.md and .claude/CLAUDE.md.

If you can’t run the task, copy the .agents and .claude folders from a newly generated workspace into your workspace root instead.

Run updateWorkspace periodically to retrieve future rule updates, as Liferay doesn’t send notifications when publishing new rules.

Using AI to Generate Projects and Code

When your environment is set up, run your AI agent from the workspace you generated. After you submit your prompt, the agent reads the rules and applies them to your Liferay project.

To confirm your agent found the rules, check the analysis it reports. If it doesn’t mention the rules, point it to the .agents folder in your prompt.

Claude reports it has found and applied the rules.

The agent runs the workspace-init skill when you request a workspace setup or when the Liferay server is unreachable. If the workspace’s bundles folder contains a Tomcat bundle that has never started, the skill prepares the bundle before its first start:

Deletes bundles/data and bundles/osgi/state.
Writes development-only properties to configs/local/portal-ext.properties. These properties add basic authentication to /o/*, where Liferay’s headless APIs are served, and turn off the setup wizard, the Terms of Use screen, and the forced password change for test@liferay.com (password test).
Copies configs/local/portal-ext.properties to bundles/portal-ext.properties to replace that file.

This preparation enables the agent to call headless APIs and MCP tools without requiring a manual sign-in. If the bundle has already started, the agent prompts you to manually sign in, accept the Terms of Use, and change the password. Provide a new password to the agent when it asks for updated credentials, as Liferay rejects reusing the current password. Only use these settings for local development.

For a complete example building a site with these skills, see AI Tools in Workspace Examples.

AI agents can bootstrap a new project, but they’re no substitute for developers. Review and refine the code they generate before you use it in production.

Happy prompting!

Capability: