apache · arunpati · Mar 12, 2026 · Mar 10, 2026
diff --git a/ai-agent-skills/README.md b/ai-agent-skills/README.md
@@ -0,0 +1,100 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# OFBiz Agent Skills Plugin
+
+## Overall Goal
+The `ai-agent-skills` plugin is a repository of standardized knowledge, best practices, and implementation patterns for Apache OFBiz. Its primary purpose is to empower AI agents (like Antigravity) to perform complex OFBiz development tasks—such as creating entities, defining services, building screens, and managing business logic—with high accuracy and adherence to framework-specific guardrails.
+
+By providing these "skills" in a structured format, we ensure that agents follow the correct design patterns (e.g., favoring View Entities over manual iteration, using Worker classes correctly, adhering to security standards) without manual intervention for every step.
+
+## Agent Setup & Activation
+
+For an AI agent (like Antigravity, Cursor, or GitHub Copilot) to effectively use these skills, they need to be linked or aggregated into the specific directories those agents expect at the root of your workspace.
+
+### 1. Framework Location (Plugin)
+Keep the source of these skills in your OFBiz plugins directory so they remain version-controlled alongside your project:
+`~/ofbiz-framework/plugins/ai-agent-skills/`
+
+### 2. Synchronization via Gradle
+To make these skills available and properly formatted for your specific AI agents, run the automated Gradle synchronization tasks from your OFBiz root directory.
+
+```bash
+# Navigate to your OFBiz framework root
+cd ~/ofbiz-framework
+
+# Option 1: Sync to the default generic agents directory (.agents/skills)
+./gradlew syncAgentSkills
+```
+
+### Updating Skills
+If you modify or add any content inside `plugins/ai-agent-skills`, you must re-run the sync command for the changes to take effect in your AI agents:
+
+```bash
+./gradlew syncAgentSkills
+```
+This command recopies the structured files into the `.agents/` folder by default.
+
+```bash
+# Option 2: Sync targets individually using the -Pagent parameter
+./gradlew syncAgentSkills -Pagent=agents    # Copies folder to .agents/skills/
+./gradlew syncAgentSkills -Pagent=gemini    # Copies folder to .gemini/skills/
+./gradlew syncAgentSkills -Pagent=claude    # Copies folder to .claude/skills/
+./gradlew syncAgentSkills -Pagent=github    # Copies folder to .github/skills/
+./gradlew syncAgentSkills -Pagent=cursor    # Copies folder to .cursor/skills/
+
+# You can also use "all" to copy to all supported agents at once:
+./gradlew syncAgentSkills -Pagent=all
+
+# Or pass separated agents to target a subset explicitly:
+./gradlew syncAgentSkills -Pagent=claude,github
+```
+
+Using these tasks ensures that as the skills in the plugin are updated, your agents automatically inherit the updates locally without manual intervention.
+
+## How to Use with an Agent
+Once synced, the agents will automatically discover these skills when working in your OFBiz project directory.
+
+### Integration Patterns
+- **Generic Agents**: Point them to the `.agents/skills` directory.
+- **Gemini (Antigravity)**: Automatically reads from `.gemini/skills/`.
+- **Claude**: Automatically reads contexts from `.claude/skills/`.
+- **Cursor**: Automatically reads contexts from `.cursor/skills/`.
+- **GitHub Copilot**: Automatically incorporates capabilities from `.github/skills/`.
+
+## Directory Structure
+The master source of these skills should be placed within the `plugins` directory of your OFBiz framework:
+`/path/to/ofbiz/plugins/ai-agent-skills/`
+
+Each directory contains:
+- `SKILL.md`: The core knowledge file containing the goal, procedures, and guardrails for that specific skill.
+
+## Available Skills
+For a detailed list of all skills with short descriptions, see [SKILLS_SUMMARY.md](~/ai-agent-skills/SKILLS_SUMMARY.md).
+
+The toolkit currently covers:
+- **Core Abstractions**: `manage-entities`, `manage-services`, `manage-data`.
+- **UI & Interaction**: `manage-screens`, `manage-forms`, `manage-menus`, `manage-templates`, `manage-ajax`.
+- **Logic & Flows**: `manage-groovy`, `manage-java`, `manage-java-patterns`, `manage-eca`, `manage-service-groups`.
+- **Integrations**: `manage-api-integration`, `manage-email-services`.
+- **Advanced Management**: `manage-security-advanced`, `manage-localization-advanced`, `manage-webapps`, `manage-cache-and-performance`.
+- **Strategies**: `manage-strategies` (Xml vs Java/Groovy, Dos and Donts).
+
+## Deployment and Updates
+This plugin is linked to the GitHub repository. To update the skills available to your agent, pull the latest changes from the repository.
diff --git a/ai-agent-skills/SKILLS_SUMMARY.md b/ai-agent-skills/SKILLS_SUMMARY.md
@@ -0,0 +1,85 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# OFBiz Agent Skills: Summary of Coverage
+
+This document provides a high-level summary of the specialized skills developed for the OFBiz Agent Toolkit. These skills provide the necessary guardrails, patterns, and procedures for an AI agent to interact with the Apache OFBiz framework effectively.
+
+## 🏗️ Core Abstractions
+| Skill | Description |
+| :--- | :--- |
+| **manage-entities** | Handle Data Model changes, including entity definitions, relations, and primary keys. |
+| **manage-services** | Define and implement OFBiz services (Java, Groovy, Script) with proper attributes and parameters. |
+| **manage-data** | Manage Seed, Demo, and Setup data using Entity Engine XML artifacts. |
+| **manage-dynamic-view-entities**| Create advanced View Entities dynamically for optimized data retrieval without raw SQL. |
+
+## 🎨 UI & Interaction
+| Skill | Description |
+| :--- | :--- |
+| **manage-screens** | Build complex, reusable UI layouts using XML Screen Definitions and decorators. |
+| **manage-forms** | Implement declarative data entry and display forms using the OFBiz Form Widget. |
+| **manage-menus** | Manage application navigation and menu hierarchies. |
+| **manage-templates** | Develop dynamic UI components using Apache FreeMarker (FTL) and macros. |
+| **manage-ajax** | Implement seamless UI updates using OFBiz-standard AJAX patterns and event handling. |
+| **manage-themes** | Handle visual styling, CSS integration, and theme-specific properties. |
+| **manage-labels** | Manage internationalization (i18n) and UI text labels across multiple languages. |
+| **manage-content** | Work with the OFBiz Content Management System (DataResource, Content, ElectronicText). |
+| **manage-pdf-export** | Design and implement professional documents (Invoices, Labels) using Apache FOP (PDF). |
+
+## ⚙️ Logic & Flows
+| Skill | Description |
+| :--- | :--- |
+| **manage-groovy** | Write business logic using Groovy scripts, leveraging the `run-groovy` engine and DSL. |
+| **manage-java** | Implement typed business logic and worker classes in the Java source layer. |
+| **manage-java-patterns** | Adhere to OFBiz-specific Java design patterns (e.g., Worker classes, internal service calls). |
+| **manage-java-events** | Implement OFBiz Events (web boundaries) and route HTTP requests in Java. |
+| **manage-minilang** | Maintain and legacy MiniLang (XML) logic for standard service workflows. |
+| **manage-eca** | Orchestrate Event Condition Actions (Service ECA and Entity ECA) for automated flows. |
+| **manage-service-groups** | Define and manage aggregate service executions and engine-level groupings. |
+| **manage-controller** | Configure web request mappings, security constraints, and view handlers in `controller.xml`. |
+| **manage-async** | Manage asynchronous execution, scheduled jobs, and the JobSandbox in OFBiz. |
+| **manage-quartz-jobs** | Schedule and manage background tasks, job polling, and temporal expressions. |
+
+## 🔌 Integrations & Communication
+| Skill | Description |
+| :--- | :--- |
+| **manage-api-integration** | Expose services via REST or SOAP and handle JSON/XML data mapping. |
+| **manage-email-services** | Configure SMTP, manage email templates, and automate outgoing communications. |
+
+## 🔐 Advanced Management
+| Skill | Description |
+| :--- | :--- |
+| **manage-security-advanced** | Implement complex security permissions, ACLs, and service-level data filtering. |
+| **manage-security-deployment** | Harden and secure an OFBiz deployment at the infrastructure limit. |
+| **manage-localization-advanced** | Handle advanced i18n, time zones, and locale-specific formatting. |
+| **manage-webapps** | Configure web application boundaries, session management, and filter chains. |
+| **manage-cache-and-performance** | Optimize performance through Entity Cache, Service Cache, and SQL query tuning. |
+| **manage-properties** | Centralize configuration settings in `.properties` files for environment management. |
+
+## 🚀 Project Lifecycle
+| Skill | Description |
+| :--- | :--- |
+| **create-component** | Scaffold new OFBiz plugins using standardized directory structures. |
+| **manage-component** | Manage component-level dependencies and `ofbiz-component.xml` registrations. |
+| **coding-standards** | General guidelines for clean code, commenting, and OFBiz contribution standards. |
+
+## 🧠 Strategic Thinking
+| Skill | Description |
+| :--- | :--- |
+| **manage-strategies** | High-level decision-making guide: XML vs Java, Service vs Event, and Performance tradeoffs. |
diff --git a/ai-agent-skills/build.gradle b/ai-agent-skills/build.gradle
@@ -0,0 +1,61 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import java.nio.file.Files
+import java.nio.file.Path
+import java.nio.file.Paths
+
+def ofbizRoot = project.file('../../').toPath()
+def skillsDir = project.file('.').toPath()
+
+task syncAgentSkills {
+    group = 'AI Agents'
+    description = 'Syncs skills to agent directories. Usage: ./gradlew syncAgentSkills -Pagent=claude,gemini,github,cursor,agents,all (default is agents)'
+    doLast {
+        def agentsArg = project.hasProperty('agent') ? project.getProperty('agent') : 'agents'
+        def selectedAgents = agentsArg.split(',').collect { it.trim().toLowerCase() }
+        def supportedAgents = ['agents', 'gemini', 'claude', 'github', 'cursor']
+
+        def targetsToSync = selectedAgents.contains('all') ? supportedAgents : selectedAgents
+
+        targetsToSync.each { agent ->
+            if (!supportedAgents.contains(agent)) {
+                println "⚠️ Unknown agent: ${agent}. Supported options are: ${supportedAgents.join(', ')}, all"
+                return
+            }
+
+            def targetDirPath = ".${agent}/skills"
+            def targetDir = ofbizRoot.resolve(targetDirPath)
+            targetDir.toFile().mkdirs()
+
+            copy {
+                from skillsDir.toFile()
+                into targetDir.toFile()
+                exclude "build"
+                exclude ".gradle"
+                exclude "build.gradle"
+                exclude "ofbiz-component.xml"
+                exclude "README.md"
+                exclude "SKILLS_SUMMARY.md"
+            }
+            println "✅ Copied skills to ${targetDirPath}"
+        }
+    }
+}
+
diff --git a/ai-agent-skills/coding-standards/SKILL.md b/ai-agent-skills/coding-standards/SKILL.md
@@ -0,0 +1,73 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+---
+name: coding-standards
+description: Guidelines for writing production-quality code, focusing on commenting style, cleanliness, and professionalism.
+---
+
+# Skill: coding-standards
+## Goal
+Ensure all OFBiz contributions meet production-grade standards for clarity, maintainability, and architectural alignment.
+
+## Triggers
+**ALWAYS** read this skill when:
+- Writing any code (Java, Groovy, XML, CSS).
+- Reviewing PRs or auditing existing code for OFBiz alignment.
+- Using OFBiz utility libraries for validation and map creation.
+- Preparing a pull request or implementing new features.
+
+## General Rules
+1. **Explain the WHY**: Code shows *what* happens. Comments must explain *why* (e.g., explaining a workaround for a legacy constraint).
+2. **No Internal Monologue**: Delete "thinking out loud" or "maybe this works" comments.
+3. **Guard against Technical Debt**: Avoid `// TODO` without a tracking reference.
+4. **Remove Debug Code**: Clean up `System.out.println`, `println`, or excessive `Debug.logInfo` before completion.
+
+## OFBiz Specific Standards
+1. **XML Actions**: Keep logic flat. If it requires complex loops or nesting, move to Groovy.
+2. **Naming Conventions**:
+    - **Components**: `kebab-case` (e.g., `order-management`).
+    - **Entities/Services**: `UpperCamelCase` for entities, `lowerCamelCase` for services.
+    - **Java/Groovy**: `lowerCamelCase` for methods/variables, `UpperCamelCase` for classes.
+3. **Documentation**:
+    - **Services**: Every service MUST have a `<description>` in `services.xml`.
+    - **Java/Groovy**: Use Javadoc/Groovydoc for public methods and complex logic.
+4. **Utility Libraries**:
+    - **Validation**: ALWAYS use `UtilValidate.isEmpty()` or `isNotEmpty()`.
+    - **Maps/Lists**: Use `UtilMisc.toMap(...)` and `UtilMisc.toList(...)` for concise creation.
+    - **Logging**: Use `Debug.logInfo(...)`, `Debug.logError(...)` with a `MODULE` tag.
+    - Use `.filterByDate()` for all date-effective entities (e.g., `ProductPrice`, `StatusItem`).
+    - Prefer `EntityQuery` over `delegator.findOne(...)`.
+5. **Internationalization (i18n)**:
+    - Never hardcode user-facing strings. Use `uiLabelMap.LabelKey`.
+
+## Guardrails
+- **Consistency**: Follow the existing indentation and naming conventions of the component you are editing.
+- **Transactional Integrity**: Respect OFBiz service boundaries; don't commit transactions manually.
+
+## Examples
+**Example: Clean documentation**
+```java
+// Check if the product is active based on current system time.
+// We use filterByDate to ensure we only get valid price records.
+GenericValue price = EntityQuery.use(delegator).from("ProductPrice")
+        .where("productId", productId)
+        .filterByDate()
+        .queryFirst();
+```
diff --git a/ai-agent-skills/create-component/SKILL.md b/ai-agent-skills/create-component/SKILL.md
@@ -0,0 +1,73 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+---
+name: create-component
+description: Scaffold a new OFBiz component (plugin) using Gradle. Use when starting a new feature set or isolating custom code.
+---
+
+# Skill: create-component
+## Goal
+Create a new, isolated OFBiz component with the correct directory structure and configuration.
+
+## Triggers
+**ALWAYS** read this skill when:
+- Creating a new plugin or component.
+- Isolating a large feature set into a separate module.
+- Understanding plugin discovery vs. manual registration.
+
+## Use when
+- Starting a brand new feature (e.g., `my-custom-module`).
+- Developing an integration that should not impact core components.
+
+## Procedure
+1. **Gradle Command**:
+    - Run `./gradlew createPlugin -PpluginId=my-plugin-name`.
+    - Optional flags: `-PwebappName=my-app`, `-PbasePermission=MY_PERM`.
+2. **Base Structure**:
+    - Ensure the following folders are present: `src`, `webapp`, `entitydef`, `servicedef`, `data`, `widget`.
+3. **Initial Configuration**:
+    - Update `ofbiz-component.xml` with proper titles and descriptions.
+    - Add basic security permissions in `data/[Component]SecurityData.xml`.
+4. **Registration (Automatic)**:
+    - OFBiz automatically discovers any directory in `plugins/` that contains an `ofbiz-component.xml` file.
+    - NO command like `./gradlew loadAll` is required for registration.
+    - OFBiz must be restarted (or a container reload triggered) to detect new components.
+
+## Post-Scaffold Customization
+1. **Directory Structure**: Verify the existence of `entitydef/`, `servicedef/`, `data/`, and `webapp/`.
+2. **Component XML**: Update `ofbiz-component.xml` with actual resource locations.
+3. **Web Application**: If your component has a UI, ensure the `<webapp>` entry has a unique `mount-point`.
+4. **Permissions**: Define base permissions in `data/MyComponentSecurityData.xml`.
+
+## Guardrails
+- **Naming**: Use lowercase, kebab-case (e.g., `order-management`).
+- **Location**: All custom components MUST reside in the `plugins/` directory.
+- **Discovery**: Plugins in `plugins/` are auto-discovered. Do not try to manually register them in framework load files.
+- **Independence**: Ensure the new component doesn't break existing ones.
+- **Best Practice**: Immediately create a dedicated `SecurityData.xml` to avoid permission conflicts.
+- **Cleanliness**: Delete unused scaffolded files (e.g., placeholder entities) after creation.
+
+## Examples
+**Example: Creating a new inventory plugin**
+```bash
+./gradlew createPlugin -PpluginId=inventory-custom -PwebappName=inventoryApp
+./gradlew loadAll
+```
+Then, verify the folder `plugins/inventory-custom` exists.