Plug-ins for SuiteSkills

.github/workflows/ai-plugins-ci.yml

@@ -27,7 +27,7 @@ permissions:
 
 jobs:
   validate-build:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
         with:
@@ -47,8 +47,16 @@ jobs:
       - name: Run tests
         run: npm run test --workspace @oracle/ai-plugins
 
+      - name: Run Python visualizer regressions
+        run: |
+          python3 -I -S -c 'import sys; assert sys.version_info[:2] == (3, 12), sys.version'
+          python3 -I -S packages/ai-plugins/test/test_suiteskills_visualizer.py
+
       - name: Build plugin directories
         run: npm run build --workspace @oracle/ai-plugins
 
+      - name: Install pinned Claude validator
+        run: bash packages/ai-plugins/scripts/install-claude-validator.sh
+
       - name: Verify release output matches source build
         run: npm run verify-release --workspace @oracle/ai-plugins

.github/workflows/ai-plugins-dist.yml

@@ -13,7 +13,7 @@ permissions:
 jobs:
   prepare:
     if: github.ref == 'refs/heads/master'
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     outputs:
       publish_required: ${{ steps.release-metadata.outputs.publish_required }}
     steps:
@@ -32,8 +32,13 @@ jobs:
       - name: Scan source for secrets
         run: node packages/ai-plugins/scripts/release-security-gates.mjs secrets .
 
-      - name: Audit locked dependencies
-        run: npm audit --package-lock-only --audit-level=high
+      - name: Audit Agent Skills and AI plug-in dependencies
+        # Audit the workspaces installed and built by this publishing job.
+        run: |
+          npm audit --package-lock-only --audit-level=high \
+            --workspace @oracle/agent-skills \
+            --workspace @oracle/ai-plugins \
+            --include-workspace-root=false
 
       - name: Install dependencies
         run: npm ci --workspace @oracle/agent-skills --workspace @oracle/ai-plugins
@@ -49,12 +54,20 @@ jobs:
           npm run test --workspace @oracle/agent-skills
           npm run test --workspace @oracle/ai-plugins
 
+      - name: Run Python visualizer regressions
+        run: |
+          python3 -I -S -c 'import sys; assert sys.version_info[:2] == (3, 12), sys.version'
+          python3 -I -S packages/ai-plugins/test/test_suiteskills_visualizer.py
+
       - name: Build plugin directories
         run: npm run build --workspace @oracle/ai-plugins
 
       - name: Scan generated distribution for secrets
         run: node packages/ai-plugins/scripts/release-security-gates.mjs secrets dist/ai-plugins
 
+      - name: Install pinned Claude validator
+        run: bash packages/ai-plugins/scripts/install-claude-validator.sh
+
       - name: Verify release output matches source build
         run: npm run verify-release --workspace @oracle/ai-plugins
 
@@ -142,7 +155,7 @@ jobs:
   publish:
     needs: prepare
     if: github.ref == 'refs/heads/master' && needs.prepare.result == 'success' && needs.prepare.outputs.publish_required == 'true'
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     permissions:
       contents: write
     steps:

README.md

@@ -1,10 +1,12 @@
-<p align="left"><a href="#"><img width="250" src="resources/Netsuite-logo-ocean-150-bg.png"></a></p>
+<p align="left"><a href="#"><img width="250" src="resources/Netsuite-logo-ocean-150-bg.png" alt="NetSuite"></a></p>
 
 # SuiteCloud SDK
-SuiteCloud Software Development Kit (SuiteCloud SDK) are the set of tools that let you customize accounts and create SuiteApps through SuiteCloud Development Framework (SDF).
+SuiteCloud Software Development Kit (SuiteCloud SDK) is a set of tools that let you customize accounts and create SuiteApps through SuiteCloud Development Framework (SDF).
 
 This GitHub repository contains the following SuiteCloud SDK tools, packages, and API references:
 
+- [AI Agent Plug-ins](./packages/ai-plugins/)
+
 - [SuiteCloud Agent Skills](./packages/agent-skills/)
 
 - [SuiteCloud CLI for Node.js](./packages/node-cli)<a href="https://www.npmjs.com/package/@oracle/suitecloud-cli">
@@ -44,7 +46,7 @@ If you think you've found a security vulnerability, do not open a GitHub issue.
 
 
 ## License
-Copyright (c) 2019, 2023 Oracle and/or its affiliates The Universal Permissive License (UPL), Version 1.0.
+Copyright (c) 2019, 2023 Oracle and/or its affiliates. The Universal Permissive License (UPL), Version 1.0.
 
 By installing SuiteCloud CLI for Node.js, you are accepting the installation of the SuiteCloud SDK dependency under the [Oracle Free Use Terms and Conditions](https://www.oracle.com/downloads/licenses/oracle-free-license.html) license.
 

packages/ai-plugins/DEVELOPMENT.md

@@ -18,11 +18,37 @@ npm run build:one --workspace @oracle/ai-plugins -- <provider>/<plugin-id>
 npm run verify-release --workspace @oracle/ai-plugins
 ```
 
-`<provider>/<plugin-id>` is one of `anthropic/netsuite-ai-companion`, `anthropic/netsuite-finance-analyst`, `anthropic/netsuite-suitecloud`, `openai/netsuite-ai-companion`, `openai/netsuite-finance-analyst`, or `openai/netsuite-suitecloud`.
-You can also target a plug-in by bare ID only when that ID is unique; these provider plug-ins have duplicate IDs and require the qualified key.
+`<provider>/<plugin-id>` is one of `anthropic/netsuite-ai-companion`, `anthropic/netsuite-finance-analyst`, `anthropic/netsuite-suitecloud`, `openai/netsuite-ai-companion`, `openai/netsuite-finance-analyst`, `openai/netsuite-suitecloud`, `anthropic/netsuite-suiteskills`, or `openai/netsuite-suiteskills`.
+Build commands also accept a bare ID when it is unique; these provider plug-ins have duplicate IDs and require the qualified key.
 
-Generated output is written only to `dist/ai-plugins/` and should never be edited by hand.
+Builds write directories only to `dist/ai-plugins/`. Never edit generated output by hand.
 
 ## Distribution and Releases
 
 Release operators should follow the [AI Agent Plug-ins Distribution and Release Guide](DISTRIBUTION.md). The manually dispatched **Publish AI Agent Plug-ins Dist** workflow is the standard release path.
+
+## SuiteSkills sources
+
+Edit skills in `common/skills/suiteskills/`, shared guidance in `common/layers/suiteskills/`, and provider inputs in `<provider>/netsuite-suiteskills/`. Update isolated shared copies together with the canonical shared layer. Installed README links resolve in the assembled distribution.
+
+`skillSources.suiteskills` selects the SuiteSkills source tree. Plug-ins without `skillSource` use `skillsRoot`. A selected source resolves all skills exclusively within that source. Source roots must remain inside this package and pass containment and symlink checks.
+
+Packaging layers live under `commonLayersRoot`. `commonLayers` accepts a layer name or an object with `name`, nonempty `include` patterns and `exclude` patterns. Global exclusions and destination collision checks apply to both forms. SuiteSkills selects literal shared resource paths; unlisted layer files are not packaged.
+
+SuiteSkills uses unsuffixed `skills/netsuite-suiteskills-*/` paths, with isolated shared resources in each skill. The build generates `.claude-plugin/plugin.json` for Anthropic and `.codex-plugin/plugin.json` for OpenAI from the provider recipes. OpenAI packages include five provider-local `agents/openai.yaml` files and shared NetSuite PNG branding; these assets are excluded from Anthropic packages. For ZIP packaging and Anthropic upload layout, follow the [distribution guide](DISTRIBUTION.md#zip-packaging).
+
+After changing packaged resources, refresh resource maps, foundation snapshots, the onboarding foundation lock and provider inventories. Preserve component versions and source provenance hashes. Inventories exclude themselves, the generated provider manifest and builder-supplied `LICENSE.txt`.
+
+## Additional checks
+
+Run both workspaces' validators and JavaScript suites before building:
+
+```sh
+npm run validate --workspace @oracle/agent-skills
+npm test --workspace @oracle/agent-skills
+python3 -I -S packages/ai-plugins/test/test_suiteskills_visualizer.py
+```
+
+The visualizer regression suite requires the Python version configured in the [CI](../../.github/workflows/ai-plugins-ci.yml) and [publishing](../../.github/workflows/ai-plugins-dist.yml) workflows and runs separately from `npm test`, without pip packages. File generation still requires the runbook's declared runtime dependencies. Qualify installed-host loading, model behavior, live-account workflows and export/delivery support separately on the target host. Package and local regression checks do not establish that support.
+
+Local release verification requires a compatible Claude Code on PATH when Anthropic packages are present, meeting the minimum version enforced by [the release verifier](scripts/verify-release.mjs), including support for [directory listing fields](https://code.claude.com/docs/en/plugins-reference#directory-listing-fields). It rejects missing, unusable or incompatible validators and runs `claude plugin validate --strict` for each Anthropic package. OpenAI-only workspaces do not require Claude.

packages/ai-plugins/DISTRIBUTION.md

@@ -35,22 +35,24 @@ The publisher:
 
 ### Exceptional Same-Version Reissue
 
-Use this only to correct an already published artifact without changing its version. Before dispatching, delete the existing remote release tag. For example, to reissue the corrected OpenAI AI Companion artifact at version `1.0.0`:
+Use this only to correct an already published artifact without changing its version. Before dispatching, delete the existing remote release tag. For example, to reissue the corrected OpenAI AI Companion artifact, substitute its published version for `<version>`:
 
 ```sh
-git push origin --delete ai-plugin/openai/netsuite-ai-companion/v1.0.0
+git push origin --delete ai-plugin/openai/netsuite-ai-companion/v<version>
 ```
 
-Then dispatch **Publish AI Agent Plug-ins Dist** from the intended `master` commit. The publisher still runs its full build and verification flow, publishes all otherwise valid changed plug-ins in that commit, and creates tags normally. It does not delete, overwrite, force-update, or rewrite tags: it fails before writing the distribution branch if any pending release tag still exists. After a successful run, verify that `ai-plugin/openai/netsuite-ai-companion/v1.0.0` was recreated at the corrected distribution commit.
+Then dispatch **Publish AI Agent Plug-ins Dist** from the intended `master` commit. The publisher still runs its full build and verification flow, publishes all otherwise valid changed plug-ins in that commit, and creates tags normally. It does not delete, overwrite, force-update, or rewrite tags: it fails before writing the distribution branch if any pending release tag still exists. After a successful run, verify that `ai-plugin/openai/netsuite-ai-companion/v<version>` was recreated at the corrected distribution commit.
 
 Each distribution update includes the reviewed, source-managed branch-root `README.md`, which identifies the source branch used for that release. The branch root is otherwise limited to generated plug-in directories:
 
 - `anthropic/netsuite-ai-companion/`
 - `anthropic/netsuite-finance-analyst/`
 - `anthropic/netsuite-suitecloud/`
+- `anthropic/netsuite-suiteskills/`
 - `openai/netsuite-ai-companion/`
 - `openai/netsuite-finance-analyst/`
 - `openai/netsuite-suitecloud/`
+- `openai/netsuite-suiteskills/`
 
 ## Local Fallback Procedure
 
@@ -77,7 +79,7 @@ node packages/ai-plugins/scripts/release-security-gates.mjs secrets dist/ai-plug
 npm run verify-release --workspace @oracle/ai-plugins
 ```
 
-For every plug-in whose generated content changes, increase its version in `plugin.build.json` before publishing. Published versions and release tags must use canonical stable `MAJOR.MINOR.PATCH` values (for example, `1.2.3`); prerelease versions and build metadata are unsupported. Tag each changed plug-in as `ai-plugin/<provider>/<plugin-id>/v<version>` after the distribution commit is pushed.
+For every plug-in whose generated content changes, increase its version in `plugin.build.json` before publishing. Published versions and release tags must use canonical stable `MAJOR.MINOR.PATCH` values; prerelease versions and build metadata are unsupported. Tag each changed plug-in as `ai-plugin/<provider>/<plugin-id>/v<version>` after the distribution commit is pushed.
 
 ### Create the Distribution Worktree Once
 
@@ -134,3 +136,30 @@ It should contain the generated plug-in directories for the source revision and
 The release workflow runs `packages/ai-plugins/scripts/release-security-gates.mjs` before dependency installation and again after build output is generated. It intentionally has no external scanner Action or container-image dependency. The source scan excludes `.git`, `node_modules`, and source `dist`; generated output is scanned directly.
 
 The gate is fail-closed for a focused policy baseline: GitHub token formats, AWS access keys, private-key material, and credential-shaped bearer values; plus workflow Action SHA pinning, non-persistent checkout credentials, and explicit top-level permissions. It is intentionally narrower than dedicated third-party secret and workflow scanners, and must not be treated as equivalent coverage.
+
+## ZIP packaging
+
+Run these manual commands from the repository root.
+
+**From the published distribution:**
+
+```sh
+git fetch origin ai-plugins-dist
+git archive --format=zip \
+  --output=/tmp/netsuite-suiteskills-published.zip \
+  FETCH_HEAD:anthropic/netsuite-suiteskills
+```
+
+**From a local build:**
+
+```sh
+npm run build --workspace @oracle/ai-plugins
+(cd dist/ai-plugins/anthropic/netsuite-suiteskills &&
+  zip -r -X /tmp/netsuite-suiteskills-local.zip .)
+```
+
+Choose a fresh output filename and substitute the desired provider/plug-in. Keep the hidden native manifest at the ZIP root: `.claude-plugin/plugin.json` for Anthropic or `.codex-plugin/plugin.json` for OpenAI, with `skills/` alongside it. Published archives reflect released content; local archives reflect the local build.
+
+Both plug-in workflows install the official Linux x64 Claude Code validator pinned in [the installer](scripts/install-claude-validator.sh), verify the download against its checked-in SHA-256 from the release manifest referenced there, and disable automatic updates. Every Anthropic package must pass strict validation using a validator that meets the minimum version enforced by [the release verifier](scripts/verify-release.mjs). The workflows also run the visualizer regression suite before building, using the Python version configured in the [CI](../../.github/workflows/ai-plugins-ci.yml) and [publishing](../../.github/workflows/ai-plugins-dist.yml) workflows.
+
+Packaging checks establish package layout. Verify installed skill contents and runbook loading in the target host separately.

packages/ai-plugins/README.md

@@ -6,14 +6,15 @@ AI Agent Plug-ins package skills for installation on supported AI platforms. The
 ## Included Plug-ins
 
 ### Business User Plug-ins
-- **NetSuite AI Companion Plug-in (netsuite-ai-companion):** Includes the NetSuite AI Connector Instructions skill. This plug-in guides AI assistants that use NetSuite AI Connector with the correct tool-selection order, output formatting, NetSuite domain knowledge, multi-subsidiary and currency handling, and SuiteQL safety guardrails. 
+- **NetSuite AI Companion Plug-in (netsuite-ai-companion):** Includes the NetSuite AI Connector Instructions skill. This plug-in guides AI assistants that use NetSuite AI Connector with the correct tool-selection order, output formatting, NetSuite domain knowledge, multisubsidiary and currency handling, and SuiteQL safety guardrails.
 - **NetSuite Finance Analyst Plug-in (netsuite-finance-analyst):** Includes the NetSuite Finance Analyst skill. This plug-in provides Director-level finance analysis on live NetSuite data, including financial reporting, period-close activities, variance, aging, and reconciliation reviews, cash reporting, and board-ready financial narratives with clear next actions.
+- **SuiteSkills Plug-in (netsuite-suiteskills):** Includes five skills and 48 business runbooks across Finance, Operations, Customers & Sales, and Workforce, with guided onboarding. It supports analysis, drafts, and authorized workflows through the NetSuite AI Connector, subject to account features, role permissions, and host capabilities.
 
 ### SuiteCloud Development Plug-ins
 - **NetSuite SuiteCloud Plug-in (netsuite-suitecloud):** It includes skills that support key areas of SuiteCloud development, such as SuiteScript, SDF, UIF SPAs, security, permissions, documentation, modernization, and SAFE Guide best practices. It helps SuiteCloud developers and SuiteApp teams create accurate, secure, and maintainable code and project artifacts.
 
 ## Contributing
-This project welcomes contributions from the community. Before submitting a pull request, review our [contribution guide](/CONTRIBUTING.md).
+This project welcomes contributions from the community. Before submitting a pull request, review our [contribution guide](https://github.com/oracle/netsuite-suitecloud-sdk/blob/master/CONTRIBUTING.md).
 
-## [License](../../LICENSE.txt)
-Copyright (c) 2019, 2023 Oracle and/or its affiliates The Universal Permissive License (UPL), Version 1.0.
+## [License](https://github.com/oracle/netsuite-suitecloud-sdk/blob/master/LICENSE.txt)
+Copyright (c) 2019, 2023 Oracle and/or its affiliates. The Universal Permissive License (UPL), Version 1.0.