Add skill for AI Agent

README.md

@@ -24,6 +24,10 @@
 
 This repository contains Aspose.BarCode Cloud SDK for Java source code. This SDK allows you to work with Aspose.BarCode for Cloud REST APIs in your Java applications quickly and easily.
 
+## AI Agent Skills
+
+This repository includes an AI-agent skill in [`skills/generate-and-scan-barcode-java/SKILL.md`](skills/generate-and-scan-barcode-java/SKILL.md). Point your coding agent to it when working with this SDK so it follows the repo workflow and SDK-specific API patterns.
+
 ## Requirements
 
 Building the API client library requires:
@@ -217,4 +221,3 @@ Authentication schemes defined for the API:
 ## Recommendation
 
 It's recommended to create an instance of `ApiClient` per thread in a multithreaded environment to avoid any potential issues.
-

skills/generate-and-scan-barcode-java/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: generate-and-scan-barcode-java
+description: "Write or update Java code that uses the Aspose.BarCode Cloud SDK (`com.aspose.barcode.cloud.*`; Maven artifact `com.aspose:aspose-barcode-cloud`) to generate, recognize, or scan barcodes through Aspose's cloud REST API. Use this skill whenever the user wants barcode work in Java, touches files under `submodules/java`, or mentions `ApiClient`, `Configuration`, `GenerateApi`, `RecognizeApi`, `ScanApi`, `GenerateParams`, `RecognizeBase64Request`, `ScanBase64Request`, or the `*RequestWrapper` classes. The Java SDK has several easy-to-miss idioms: generate methods return `File`, every API call goes through wrapper objects, GET recognize/scan methods require a public `URI`, base64 methods expect caller-encoded data, tests prefer `src/test/configuration.json` or `TEST_CONFIGURATION_ACCESS_TOKEN`, and repo scripts should run through WSL on Windows, so consult this skill instead of guessing."
+---
+
+# Generate and scan barcode in Java
+
+The Java SDK is a thin generated client over the Aspose BarCode Cloud REST API. Most tasks boil down to choosing the right API class (`GenerateApi`, `RecognizeApi`, `ScanApi`), picking the right auth path with `ApiClient` or `Configuration`, and building the matching `*RequestWrapper`.
+
+The Maven artifact and package names differ. Install `com.aspose:aspose-barcode-cloud`, then import classes from `com.aspose.barcode.cloud.*`.
+
+## Quick start
+
+Use these imports in most Java examples:
+
+```java
+import com.aspose.barcode.cloud.ApiClient;
+import com.aspose.barcode.cloud.Configuration;
+import com.aspose.barcode.cloud.api.GenerateApi;
+import com.aspose.barcode.cloud.api.RecognizeApi;
+import com.aspose.barcode.cloud.api.ScanApi;
+import com.aspose.barcode.cloud.model.*;
+import com.aspose.barcode.cloud.requests.*;
+```
+
+Prefer one of these setup patterns:
+
+```java
+ApiClient client = new ApiClient(clientId, clientSecret);
+GenerateApi generateApi = new GenerateApi(client);
+RecognizeApi recognizeApi = new RecognizeApi(client);
+ScanApi scanApi = new ScanApi(client);
+```
+
+```java
+Configuration config = new Configuration();
+config.ClientId = clientId;
+config.ClientSecret = clientSecret;
+ApiClient client = config.buildApiClient();
+```
+
+```java
+Configuration config = new Configuration();
+config.AccessToken = accessToken;
+ApiClient client = config.buildApiClient();
+```
+
+If the task is repo maintenance inside `submodules/java`, read `references/repo-workflow.md`. If the task needs a closest existing example or snippet, read `references/snippet-map.md`.
+
+## Authentication
+
+Use one of these two auth modes:
+
+1. Let the SDK fetch the token for you.
+
+```java
+ApiClient client = new ApiClient(clientId, clientSecret);
+```
+
+2. Inject a pre-fetched bearer token.
+
+```java
+ApiClient client = new ApiClient(accessToken);
+```
+
+`Configuration.buildApiClient()` follows the same rule: if `Configuration.AccessToken` is non-null, it builds token mode and ignores `ClientId`/`ClientSecret`.
+
+The README still mentions Java 8, but `submodules/java/pom.xml` currently compiles with source and target level `11`. Follow the build file, not the older README note.
+
+The upstream README recommends one `ApiClient` instance per thread in multithreaded code. Keep that guidance when writing examples or concurrent integrations.
+
+## Choose the right API shape
+
+Pick the operation first:
+
+- `GenerateApi`: create a barcode image.
+- `RecognizeApi`: decode one or more expected barcode types and optionally tune recognition.
+- `ScanApi`: auto-detect barcode types with the smallest API surface.
+
+Then pick the transport variant based on what the caller has:
+
+- Public internet URL: use `recognize(...)` or `scan(...)` with `RecognizeRequestWrapper` or `ScanRequestWrapper`.
+- Local file on disk: use `recognizeMultipart(...)` or `scanMultipart(...)`.
+- Raw bytes already in memory: base64-encode them yourself and use `recognizeBase64(...)` or `scanBase64(...)`.
+- Simple generation with query-like parameters: use `generate(...)`.
+- Structured generation payload: use `generateBody(...)` with `GenerateParams`.
+- Multipart generation: use `generateMultipart(...)` only when the caller explicitly needs the multipart form variant.
+
+Key method names:
+
+- `generate`
+- `generateBody`
+- `generateMultipart`
+- `recognize`
+- `recognizeBase64`
+- `recognizeMultipart`
+- `scan`
+- `scanBase64`
+- `scanMultipart`
+
+## Non-obvious SDK rules
+
+1. `generate`, `generateBody`, and `generateMultipart` return `java.io.File`, not bytes or an input stream. Move or copy the returned file if you need a stable destination.
+2. Every public operation takes a `*RequestWrapper`. Required arguments go into the wrapper constructor; optional parameters are set on public fields or nested models after construction.
+3. `RecognizeRequestWrapper` and `ScanRequestWrapper` take a public `URI`. Do not pass local filesystem paths there; use multipart or base64 for local files.
+4. `RecognizeBase64Request` and `ScanBase64Request` expect an already-encoded base64 string. The SDK does not call `Base64.getEncoder().encodeToString(...)` for you.
+5. `RecognizeBase64Request` takes `List<DecodeBarcodeType>`, but `RecognizeRequestWrapper` and `RecognizeMultipartRequestWrapper` take a single `DecodeBarcodeType`.
+6. `ScanApi` never takes barcode types. Use it when the caller wants auto-detection.
+7. `BarcodeResponseList` may contain multiple barcodes. Iterate `response.getBarcodes()` instead of assuming a single result.
+8. API failures throw `ApiException`. Turn on logging with `client.setDebugging(true)` when request or response details would help.
+9. Repo tests first load `src/test/configuration.json`; if that file is absent, `TestConfiguration` only falls back to `TEST_CONFIGURATION_ACCESS_TOKEN`. Client-id and client-secret environment variables are not part of the Java test harness fallback.
+
+## Common patterns
+
+Generate and save a QR code:
+
+```java
+ApiClient client = new ApiClient(clientId, clientSecret);
+GenerateApi api = new GenerateApi(client);
+
+GenerateRequestWrapper request = new GenerateRequestWrapper(EncodeBarcodeType.QR, "hello from Java");
+request.imageFormat = BarcodeImageFormat.PNG;
+request.textLocation = CodeLocation.NONE;
+
+File generated = api.generate(request);
+Files.move(generated.toPath(), Paths.get("qr.png"), StandardCopyOption.REPLACE_EXISTING);
+```
+
+Recognize specific barcode types from bytes already in memory:
+
+```java
+byte[] bytes = Files.readAllBytes(Paths.get("many-types.png"));
+String fileBase64 = Base64.getEncoder().encodeToString(bytes);
+
+RecognizeBase64Request body =
+        new RecognizeBase64Request(Arrays.asList(DecodeBarcodeType.QR, DecodeBarcodeType.CODE128), fileBase64);
+BarcodeResponseList result =
+        new RecognizeApi(client).recognizeBase64(new RecognizeBase64RequestWrapper(body));
+```
+
+Auto-scan a local file without specifying the barcode type:
+
+```java
+File image = Paths.get("unknown.png").toFile();
+BarcodeResponseList result =
+        new ScanApi(client).scanMultipart(new ScanMultipartRequestWrapper(image));
+```
+
+## Working in this repo
+
+Read `references/repo-workflow.md` when the task changes SDK source, tests, snippets, Maven metadata, README examples, or generated code in `submodules/java`.
+
+Read `references/snippet-map.md` when the task needs the closest existing pattern for generate, recognize, scan, auth, or repo-test scenarios.
+
+## Final checklist
+
+1. Use the correct artifact and package pair: Maven `com.aspose:aspose-barcode-cloud`, imports under `com.aspose.barcode.cloud.*`.
+2. Choose `ApiClient(clientId, clientSecret)`, `ApiClient(accessToken)`, or `Configuration.buildApiClient()` deliberately.
+3. Pick GET only for public `URI`s, multipart for local files, and base64 for in-memory bytes.
+4. Build the right `*RequestWrapper` and set optional public fields after construction.
+5. Base64-encode request bodies yourself before calling `recognizeBase64` or `scanBase64`.
+6. Handle returned `File` objects from generate calls and multiple entries in `response.getBarcodes()`.
+7. When changing the repo, validate with the submodule workflow in `references/repo-workflow.md`.

skills/generate-and-scan-barcode-java/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Generate and scan barcode in Java"
+  short_description: "Use Aspose.BarCode Cloud from Java"
+  default_prompt: "Use $generate-and-scan-barcode-java to write or update Java code that generates, recognizes, or scans barcodes with Aspose.BarCode Cloud."

skills/generate-and-scan-barcode-java/references/repo-workflow.md

@@ -0,0 +1,72 @@
+# Java submodule workflow
+
+Use this reference when the task edits SDK source, tests, snippets, docs, Maven metadata, or generated files inside `submodules/java`.
+
+## Layout
+
+- `src/main/java/com/aspose/barcode/cloud`: `ApiClient`, `Configuration`, `ApiException`, JSON helpers, auth, and HTTP plumbing.
+- `src/main/java/com/aspose/barcode/cloud/api`: generated API clients such as `GenerateApi`, `RecognizeApi`, and `ScanApi`.
+- `src/main/java/com/aspose/barcode/cloud/model`: request and response models plus enums.
+- `src/main/java/com/aspose/barcode/cloud/requests`: wrapper classes that split required constructor arguments from optional public fields.
+- `src/test/java/com/aspose/barcode/cloud/test`: integration-style tests for configuration, auth, generate, recognize, scan, and end-to-end flows.
+- `src/test/java/com/aspose/barcode/cloud/api`: unit tests for request validation, path construction, and async/execute wiring.
+- `src/test/java/com/aspose/barcode/cloud/examples/Example.java`: small standalone sample that generates then scans a barcode.
+- `snippets`: documentation snippets executed by the snippet runner.
+- `scripts`: post-processing, formatting, snippet execution, and README example insertion helpers.
+- `pom.xml`: package metadata, Java version, dependencies, JaCoCo thresholds, and Maven plugins.
+
+## Validation
+
+On Windows, run repo scripts and Make targets through WSL.
+
+From `submodules/java`:
+
+- `make build`
+- `make test`
+- `make lint`
+- `make format`
+- `make fix`
+
+`make build` does:
+
+- `mvn compile -Dmaven.test.skip=true`
+- `mvn dependency:copy-dependencies -DoutputDirectory=target/lib/`
+
+`make test` does more than `mvn test`:
+
+- runs `mvn test`
+- copies dependencies into `target/lib/`
+- runs `./scripts/run_snippets.sh`
+
+`run_snippets.sh` creates a temporary `snippets_test` directory, links `target`, and executes every snippet through `scripts/run_snippet.sh`. Treat snippet failures as package-consumer regressions, not just sample breakage.
+
+`make after-gen` runs `fix`, `format`, and `insert-example`. The root-level `make java` path already invokes `make after-gen` at the end of generation.
+
+## Test configuration
+
+- Minimal JSON shape lives in `src/test/configuration.example.json`.
+- Tests load `src/test/configuration.json` first.
+- If the config file is absent, `TestConfiguration.load()` falls back to `TEST_CONFIGURATION_ACCESS_TOKEN` only.
+- The Java test harness does not fall back to `TEST_CONFIGURATION_CLIENT_ID` or `TEST_CONFIGURATION_CLIENT_SECRET`.
+- Snippets commonly mirror the same choice: use `TEST_CONFIGURATION_ACCESS_TOKEN` when present, otherwise rely on placeholder credentials in sample code.
+
+## Regenerated code workflow
+
+If you change generated SDK code in this mono-repo:
+
+1. Make the desired SDK edit in `submodules/java` so the target behavior is clear.
+2. Mirror the change in the matching template under `codegen/Templates/java` when the file is generated. If the relevant template does not exist locally, copy it in from the upstream OpenAPI Generator templates first and edit the local copy.
+3. Stage the Java submodule changes.
+4. From the repo root, run `make java` through WSL on Windows.
+5. `codegen/generate-java.bash` regenerates into `.generated/java`, splits wrapper classes into `src/main/java/com/aspose/barcode/cloud/requests`, refreshes `api`, `model`, `docs`, `pom.xml`, and `README.template`, then runs `make after-gen` in `submodules/java`.
+6. Ensure `submodules/java` has no new unstaged diffs after regeneration.
+7. If regeneration reintroduces old code, keep fixing the templates until generated output matches the intended SDK change.
+
+## Useful anchors
+
+- `pom.xml`: artifact id `com.aspose:aspose-barcode-cloud`, Java compiler level `11`, and JaCoCo coverage rules.
+- `src/main/java/com/aspose/barcode/cloud/Configuration.java`: access-token versus client-id/client-secret behavior.
+- `src/test/java/com/aspose/barcode/cloud/test/TestConfiguration.java`: repo auth fallback rules.
+- `scripts/run_snippets.sh`: snippet execution pipeline.
+- `scripts/insert-example.bash`: README generation entry point.
+- `codegen/generate-java.bash`: main regen script for this submodule.

skills/generate-and-scan-barcode-java/references/snippet-map.md

@@ -0,0 +1,42 @@
+# Snippet and example map
+
+Use this reference when you want the closest existing pattern before writing new Java SDK code or when updating docs, snippets, and examples.
+
+## Small end-user examples
+
+- `src/test/java/com/aspose/barcode/cloud/examples/Example.java`: minimal generate-then-scan flow using `GenerateApi` and `ScanApi`.
+- `snippets/ManualFetchToken.java`: manual OAuth client-credentials token fetch without the SDK.
+
+## Generate patterns
+
+- `snippets/generate/save/GenerateGet.java`: simple `generate(...)` and save-to-file flow.
+- `snippets/generate/save/GenerateBody.java`: `generateBody(...)` with `GenerateParams`.
+- `snippets/generate/save/GenerateMultipart.java`: multipart generation flow.
+- `snippets/generate/set-text/*`: `EncodeData` and `EncodeDataType` examples.
+- `snippets/generate/set-size/*`: width, height, resolution, and units examples.
+- `snippets/generate/set-colorscheme/*`: foreground and background color examples.
+- `snippets/generate/appearance/*`: richer `BarcodeImageParams` examples.
+
+## Recognize and scan patterns
+
+- `snippets/read/set-source/RecognizeGet.java`: recognize from a public URL.
+- `snippets/read/set-source/RecognizeMultipart.java`: recognize from a local file.
+- `snippets/read/set-source/RecognizeBody.java`: recognize from base64 bytes.
+- `snippets/read/set-source/ScanGet.java`: auto-scan from a public URL.
+- `snippets/read/set-source/ScanMultipart.java`: auto-scan from a local file.
+- `snippets/read/set-source/ScanBody.java`: auto-scan from base64 bytes.
+- `snippets/read/set-target-types/*`: choosing `DecodeBarcodeType` or `List<DecodeBarcodeType>`.
+- `snippets/read/set-quality/*`: `RecognitionMode` examples.
+- `snippets/read/set-image-kind/*`: `RecognitionImageKind` examples.
+
+## Tests worth copying
+
+- `src/test/java/com/aspose/barcode/cloud/test/EndToEndTest.java`: generate a barcode `File`, then scan that same file end to end.
+- `src/test/java/com/aspose/barcode/cloud/test/GenerateApiTest.java`: generate via GET, body, and multipart variants.
+- `src/test/java/com/aspose/barcode/cloud/test/RecognizeApiTest.java`: recognize via base64 body, multipart, and URL.
+- `src/test/java/com/aspose/barcode/cloud/test/ScanApiTest.java`: scan via base64 body, multipart, and URL.
+- `src/test/java/com/aspose/barcode/cloud/test/ConfigurationTest.java`: configuration defaults and `buildApiClient()` behavior.
+- `src/test/java/com/aspose/barcode/cloud/test/ExceptionTest.java`: expected failures and exception behavior.
+- `src/test/java/com/aspose/barcode/cloud/api/GenerateApiUnitTest.java`: request validation and generated request-path behavior.
+- `src/test/java/com/aspose/barcode/cloud/api/RecognizeApiUnitTest.java`: recognize request validation, request-path behavior, and async wiring.
+- `src/test/java/com/aspose/barcode/cloud/api/ScanApiUnitTest.java`: scan request validation, request-path behavior, and async wiring.