liferay/liferay-portal / workspaces/clarity-solution-workspace/.agents/skills/build-site
build-site
VerifiedOrchestrate a complete Liferay site experience from a single prompt. Composes objects, business logic, fragments, pages, roles, and theme into a working site. Use when the user asks to "build a site", "create a site experience", or describes a multiobject, multipage scenario. Calls all other skills in sequence.
Build Site
One command orchestrator. The user describes the site; this skill calls the right subskills in the right order.
When to Invoke
- "Build a Bookstore site with an Author object, a Book object, and a home page"
- "Create a site experience for customer onboarding"
- "Scaffold the full job board site"
- Any multiobject, multipage request that spans data and presentation
Standing Requirements
These hold on every site build whether or not the user asks for them. Do not wait to be told.
-
Everything ships in the workspace, reproducible from a clean environment. Do not satisfy a request for data, pages, fragments, or styling by mutating only the running instance — write it into the tree first, then apply it. A site that cannot be rebuilt from what is checked into the workspace is not finished, however correct it looks in the browser.
Keep it to as few projects as the classification rules permit, but a whole site cannot be one project.
siteInitializerisbatch;themeCSSisfrontend; handlers aremicroservice; those three can never share aclient-extension.yaml. The initializer project carries thesiteInitializerplus exactly oneoAuthApplicationHeadlessServerand nothing else — a theme or anobjectActionadded to it fails atcreateClientExtensionConfig, after the assemble tasks have already printed success. Seerules/client-extension-types.md→ "Which Types May Share a Project".So the reproducible unit is the workspace, not a single directory. Express the site's look through what the initializer tree can carry — style book, master page, fragment CSS,
layout-setsettings, and athemeCSSCET bound in the master'spage-definition.jsonsettings.themeCSSClientExtension(ERC"LXC:" + <config-erc>), which cascades to every page and survives reprovision (rules/site-initializer-format.md→ "Binding Design to the Master viasettings"). The theme is still a sibling project (type classification rule), but its application is tree expressible — no manual Design → Theme step. -
Objects are the data layer. Model entities as Liferay Object definitions. Do not reach for web content structures or a Service Builder module for structured application data, even when the
modulesdirectory exists in the workspace. -
Verify by rendering, not by status code. A page returning 200 with an empty content area is the pack's most common silent failure. Fetch each page and confirm its fragments produced markup before reporting success.
-
Verify as the audience. When a flow is meant for unauthenticated visitors, exercise it without a session cookie. An admin authenticated check hides missing Guest permissions.
-
Report what does not work. Name every placeholder, skipped step, and unverified claim. An overstated success is worse than a reported failure.
Workflow
The sequence below is the canonical order. Skip phases the user has not requested; do not add phases they have not asked for.
Phase 0: Scope Confirmation
Before calling any subskill, confirm the scope with the user:
-
Site name — what to call the site
-
Objects — list of entity names with their key fields and relationships
-
Pages — list of pages and their purpose
-
Roles — named roles and their intended access (viewer, editor, admin)
-
Theme — any color, font, or visual requirement (optional)
-
Audience — who the site is actually for: anonymous visitors, or a signed in user. This decides every verification step later, and getting it wrong wastes a full cycle in either direction. An admin only demo needs no Guest grants and must be checked signed in; a public site needs
resource-permissions.jsonand must be checked signed out. Ask; do not infer it from the fact that a page is public.
Proceed only after the user confirms or corrects the scope list.
Settle the Reprovision Surface Before Provisioning Once
This is the single largest time sink in a site build. A whole class of change costs another run of the initializer each time it is discovered. "Reprovision" below means firing the initializer again with a clean redeploy — that run upserts pages, composition, and fragments onto the existing site (see rules/site-initializer-format.md → "Firing the initializer again UPSERTS"); delete + redeploy is only needed to remove things or recover from a doubtful upsert. Each cycle still costs a full wait to build, deploy, and import, and the number of cycles is decided here, before Phase 4, not later.
| Change | Cost after the first provision |
|---|---|
| Object definition, field, relationship, entry data | Live — object-admin API, no reprovision |
| Theme CSS content (CET already bound to the master) | Live — blade gw deploy |
Binding a themeCSS CET or style book onto the master | Reprovision |
| Fragment HTML / CSS / JS, or a new fragment | Reprovision |
| New page, or recomposing an existing one | Reprovision |
| Adding or changing a master page | Reprovision, and it rewrites every page definition |
| Style book, navigation menu, layout set settings | Reprovision |
So before writing the first fragment, answer these — each wrong guess is one cycle:
- Is there a master page? Retrofitting one later touches every
page-definition.json(each needssettings.masterPage.keyandversion: 1.1). If the site has a branded header or footer — and almost every real site does — build it in Phase 5, not after the theme prompt. - What is the complete page list, including the ones that are not navigation items: thank you, confirmation, error, "no results" pages. A form almost always implies a landing page.
- Which fragments carry JavaScript, and have they been reasoned through once for timezone, permissions, and number parsing? See the trap table below.
- Does the theme need a
themeCSSCET? Decide now: it is a sibling project whose binding lives in the master'spage-definition.jsonsettingsblock, so adding or changing it later is a master composition change — one more reprovision (skills/theme-and-design/SKILL.md).
Batch everything that costs a reprovision into as few passes as possible. A planned build provisions once or twice; a reactive one provisions five times.
Trap Preflight
Five silent failures account for most of the rework in this pack. Each one builds, deploys, and renders — the defect only shows on close reading. Check them while authoring, not after.
| Trap | Rule | Where |
|---|---|---|
fragment.json "type" | Always "component". "section" breaks the whole headless-admin-fragment listing with 400 Invalid enum value | scaffold-fragment |
| Literal text override | Replaces the editable's inner <h1>/<h2>, so tag only CSS selectors miss it | manage-pages |
DateTime in fragment JS | Use the UTC getters, or times shift into the visitor's timezone | manage-pages |
| Heading font across the site | Content fragments must not declare font-weight on headings the master rule owns | theme-and-design |
| Reserved object field names | status is taken — use <entity>Status. Inside an initializer this rolls back the entire site | manage-objects |
The canonical model is site initializer first: the siteInitializer CET tree is the single source of truth, and the site is created by triggering the initializer rather than by calling the live page API. After the initial build, iterate by editing the source tree and applying each change by the cheapest reliable path — see "Iterating on the Site" below and the spine in rules/site-initializer-format.md.
Phase 1: Prerequisites
Call feature-flags for the full set of flags the workflow needs:
| Scenario | Required Flags |
|---|---|
| Fragment composition via API | LPD-39244 |
| Object entry shares (collaborators) | LPD-17564 on 2026.Q1 and 2026.Q2; none on 2026.Q3 |
| MCP transport | LPD-63311, plus the MCPServerConfiguration switch on 2026.Q3 (see skills/mcp-server/SKILL.md) |
Report the gap table. Enable flags only after explicit user confirmation. Bounce Tomcat if any flags are written, following liferay-rules.md → "Server Restarts".
Phase 2: Transport Selection
Run the probe in skills/mcp-server/SKILL.md → "Audit the Current State First". It posts an initialize request with credentials; a bare HEAD does not, and on 2026.Q3 every unauthenticated request gets 401.
- 200: MCP is available. Use it for all subsequent API calls: the
call-http-endpointtool on 2026.Q1 and 2026.Q2, the tool set meta tools on 2026.Q3 (seeskills/mcp-server/SKILL.md→ "Tool Sets Replacecall-http-endpoint"). - 404 on 2026.Q3: The
MCPServerConfigurationswitch is probably off. Enable it perskills/mcp-server/SKILL.mdbefore falling back. - Otherwise: Fall back to direct
curlcalls with Basic auth.
Phase 3: Data Model
For each object in the confirmed scope, call manage-objects:
-
Create and publish the object definition.
-
Add all fields.
-
Add picklists (if any field references a picklist).
-
Add relationships between objects (parent → child).
-
Add validations.
-
For a count of child entries or the capacity they leave, such as places left, add an Aggregation field (
manage-objects→ "Aggregation Fields"). Filter it when only some children count.
For each business logic requirement, call manage-object-logic:
-
Choose the trigger and action type.
-
Create notification templates if needed.
-
Create the object action.
-
When a reviewer approves or rejects each entry, follow "Approval Workflow" rather than linking the stock Single Approver, which cannot set a rejected status.
Phase 4: Site Initializer Scaffold
Call scaffold-client-extension with type siteInitializer to create the CET that will provision the site. This tree is the source of truth for the site's fragments, pages, theme metadata, and roles. Populate it in Phases 5–8 per rules/site-initializer-format.md, then trigger it in Phase 9.
Phase 5: Fragments
For each unique layout section needed by the page list, call scaffold-fragment:
-
Create the fragment source files inside the initializer tree at
site-initializer/fragments/group/<collection-key>/fragments/<fragment-name>(note the requiredfragmentsnesting level under the collection). For the initial build, the content may be hardcoded (static text and images); later iterations bind it to objects. -
Record each fragment's
key(its<fragment-name>directory name) for Phase 6 — page definitions reference it asfragment.keywithsiteKey: "[$GROUP_KEY$]".
Phase 6: Pages
For each page in the confirmed scope, call manage-pages to author it in the initializer:
-
Write
site-initializer/layouts/<NN-page-name>/page.jsonwith the correct type (Content Page default). -
Write
page-definition.jsoncomposing the page with fragment elements (using keys from Phase 5). -
Add the navigation menu and SEO metadata via the initializer's
layout-setdirectory and page metadata.
The pages come into being when the initializer is triggered in Phase 9.
Phase 7: Theme and Design (Optional)
When the user provided visual requirements, call theme-and-design:
-
Generate and deploy the
themeCSSCET. -
Create and assign the style book.
-
Create the master page with header and footer fragments.
Phase 8: Roles and Permissions
For each role in the confirmed scope, call manage-roles-permissions:
-
Create the role.
-
Assign permissions on each object definition.
-
Assign permissions on each page (restrict visibility if needed).
Phase 9: Provision the Site
Deploy the CET and trigger the initializer. This creates the site with its fragments, pages, and roles in one pass:
# Deploy the site initializer CET
cd client-extensions/<site-init-name> && blade gw deploy
# Trigger it to create the site
curl \
--data '{
"membershipType": "open",
"name": "<Site Name>",
"templateType": "site-initializer",
"templateKey": "<workspace-id>-site-init"
}' \
--header "Content-Type: application/json" \
--request POST \
--silent \
--url "http://localhost:${PORT}/o/headless-admin-site/v1.0/sites" \
--user "test@liferay.com:test"
Caution: resolving a site initializer template through
POST /sitesis unreliable (the currentSiteDTO usestemplateKey, nottemplateExternalReferenceCode). The portable path is to let thesiteInitializerCET autoprovision on deploy, and to reprovision by delete then redeploy — seerules/site-initializer-format.md.
Save the site's externalReferenceCode as <site-erc> from the response.
Phase 10: Verification
Confirm the site is functional:
# Site exists
curl \
--silent \
--url "http://localhost:${PORT}/o/headless-admin-site/v1.0/sites/<site-erc>" \
--user "test@liferay.com:test" \
| jq '{externalReferenceCode, name}'
# Pages exist
curl \
--silent \
--url "http://localhost:${PORT}/o/headless-admin-site/v1.0/sites/<site-erc>/site-pages" \
--user "test@liferay.com:test" \
| jq '[.items[] | {name, friendlyUrlPath, type}]'
# Object definitions published
curl \
--silent \
--url "http://localhost:${PORT}/o/object-admin/v1.0/object-definitions?filter=status%20eq%20%27approved%27" \
--user "test@liferay.com:test" \
| jq '[.items[] | {name, status}]'
# Probe site home page — a 200 alone does not mean it rendered
curl \
--silent \
--url "http://localhost:${PORT}/web/<site-friendly-url>" \
| grep --count "<fragment-marker-or-known-content>"
Per Standing Requirement 3, fetch each page's body and confirm the expected fragment content is present. An empty content area returns 200.
Where the site serves unauthenticated visitors, repeat the critical path with no credentials and no cookie jar — see Standing Requirement 4.
Report the final state: objects created, pages created, roles created, site URL, and anything left placeholder or unverified.
Iterating on the Site
After the initial build, the user improves the site through natural language prompts. The initializer tree stays the source of truth: edit the source files first, then apply the change by the cheapest reliable path. The initializer runs only at site creation, so only page changes force a reprovision.
| Prompt Intent | Source Edit | How to Apply | Reprovision? |
|---|---|---|---|
| "Give me a unified theme" | themeCSS CET (+ style book, master page) | theme-and-design → blade gw deploy | No |
| "Replace the hardcoded list with an object" | object definition + data in the batch directory | manage-objects → object-admin API / batch import | No |
| "Edit / restyle a fragment" | fragments/group/<key>/... | scaffold-fragment → reprovision (there is no portable live fragment import endpoint) | Yes |
| "Add a new fragment" | new fragments/group/<key>/... | scaffold-fragment → reprovision | Yes |
| "Add a page" / recompose a page | layouts/<NN>/page*.json | reprovision (delete + recreate from initializer) | Yes |
Object definitions and entries are scoped at the company level, so a reprovision for a page change preserves runtime data. See rules/site-initializer-format.md for the reprovision commands.
Example Prompt Interpretation
User: "Build a Bookstore site with an Author object (name, bio), a Book object (title, isbn, linked to Author), a home page listing Books, and a Reader role that can only view Books."
Scope confirmation:
- Objects: Author (name: Text, bio: LongText), Book (title: Text, isbn: Text, authorId: Relationship to Author)
- Pages: Home (Content Page, lists Books via a fragment)
- Roles: Reader (VIEW on Book object, VIEW on Home page)
Execution order: Phase 1 (flags) → Phase 2 (MCP probe) → Phase 3 (Author, Book, relationship) → Phase 4 (scaffold initializer) → Phase 5 (book list fragment in tree) → Phase 6 (home page in layouts) → Phase 8 (Reader role + page permissions) → Phase 9 (deploy + trigger initializer) → Phase 10 (verify)
Handling Partial Failures
When a phase fails:
-
Surface the error and the raw API response to the user.
-
Diagnose the cause (missing flag, validation error, unreachable endpoint).
-
Ask the user whether to retry the failed phase, skip it, or abort.
-
Do not proceed to dependent phases when a prerequisite phase has failed.
Success Signal
TODO / inferred — verify against a running bundle. Phase 10 above holds the observable checks (site, pages, published objects, home page probe); confirm on a live bundle.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |