Add skill for AI Agent

README.md

@@ -34,6 +34,10 @@ To use these SDKs, you will need Client Id and Client Secret which can be looked
 
 The complete source code is available in this repository folder. You can either directly use it in your project via source code or get [from PyPi](https://pypi.org/project/aspose-barcode-cloud/) (recommended).
 
+## AI Agent Skills
+
+This repository includes an AI-agent skill in [`skills/generate-and-scan-barcode-python/SKILL.md`](skills/generate-and-scan-barcode-python/SKILL.md). Point your coding agent to it when working with this SDK so it follows the repo workflow and SDK-specific API patterns.
+
 ## Prerequisites
 
 To use Aspose.BarCode Cloud SDK for Python you need to register an account with [Aspose Cloud](https://www.aspose.cloud) and lookup/create Client Secret and Client Id at [Cloud Dashboard](https://dashboard.aspose.cloud/applications). There is free quota available. For more details, see [Aspose Cloud Pricing](https://purchase.aspose.cloud/).
@@ -146,4 +150,3 @@ Class | Method | HTTP request | Description
 - [RegionPoint](docs/RegionPoint.md)
 - [ScanBase64Request](docs/ScanBase64Request.md)
 
-

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

@@ -0,0 +1,182 @@
+---
+name: generate-and-scan-barcode-python
+description: Write or update Python code that uses the Aspose.BarCode Cloud SDK (`aspose_barcode_cloud`; pip package `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 Python, touches files under `submodules/python`, or mentions `GenerateApi`, `RecognizeApi`, `ScanApi`, `ApiClient`, `Configuration`, `GenerateParams`, `RecognizeBase64Request`, or `ScanBase64Request`. The SDK has several easy-to-miss idioms, including constructing APIs from `ApiClient(Configuration(...))`, reading generate results from `.data`, using public `file_url` values for GET recognize and scan methods, base64-encoding body payloads yourself, and remembering that the install and import names differ.
+---
+
+# Generate and scan barcode in Python
+
+The Python SDK is a thin generated client over the Aspose BarCode Cloud REST API. Most tasks come down to choosing the right API class (`GenerateApi`, `RecognizeApi`, or `ScanApi`), choosing the right transport variant (GET, base64 body, or multipart), and wiring `Configuration` into `ApiClient` correctly.
+
+The package name and import name differ. Install `aspose-barcode-cloud`, then import from `aspose_barcode_cloud`.
+
+## Quick start
+
+Use these imports in most Python examples:
+
+```python
+from aspose_barcode_cloud import (
+    ApiClient,
+    Configuration,
+    GenerateApi,
+    RecognizeApi,
+    ScanApi,
+)
+```
+
+Prefer constructing API classes from one shared `ApiClient`:
+
+```python
+config = Configuration(
+    client_id=client_id,
+    client_secret=client_secret,
+)
+api_client = ApiClient(configuration=config)
+
+generate_api = GenerateApi(api_client=api_client)
+recognize_api = RecognizeApi(api_client=api_client)
+scan_api = ScanApi(api_client=api_client)
+```
+
+If the task is repo maintenance inside `submodules/python`, read `references/repo-workflow.md`. If the task needs the closest existing example or snippet, read `references/snippet-map.md`.
+
+## Authentication
+
+Use one of these two patterns:
+
+1. Let the SDK fetch an access token lazily from client credentials.
+
+```python
+config = Configuration(
+    client_id=client_id,
+    client_secret=client_secret,
+)
+```
+
+2. Inject a pre-fetched bearer token.
+
+```python
+config = Configuration(
+    access_token=token,
+    host="https://api.aspose.cloud/v4.0",
+)
+```
+
+`Configuration.access_token` fetches a token automatically when `_access_token` is empty but `client_id`, `client_secret`, and `token_url` are present.
+
+Inside this repo, tests load `tests/configuration.json` first and then fall back to `TEST_CONFIGURATION_*` environment variables. Snippets usually check `TEST_CONFIGURATION_ACCESS_TOKEN` first, then fall back to client credentials. Mirror the surrounding file when editing existing repo code.
+
+`Configuration` defaults to `host="https://api.aspose.cloud/v4.0"` and `token_url="https://id.aspose.cloud/connect/token"`. Some older repo artifacts still mention the v3.0 host; prefer the runtime default unless you are intentionally matching older behavior in that file.
+
+## Choose the right API shape
+
+Pick the operation first:
+
+- `GenerateApi`: create a barcode image.
+- `RecognizeApi`: decode one or more known 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 to an image: use `recognize()` or `scan()`. `file_url` must be a public URL, not a local path.
+- Local file object or stream: use `recognize_multipart()` or `scan_multipart()`.
+- Raw bytes already in memory: base64-encode them yourself and use `recognize_base64()` or `scan_base64()`.
+- Simple text plus query parameters for generation: use `generate()`.
+- Structured generate payload: use `generate_body()`.
+- Multipart-form generation: use `generate_multipart()` when the caller explicitly needs that shape.
+
+Key method names:
+
+- `generate`
+- `generate_body`
+- `generate_multipart`
+- `recognize`
+- `recognize_base64`
+- `recognize_multipart`
+- `scan`
+- `scan_base64`
+- `scan_multipart`
+
+## Non-obvious SDK rules
+
+1. Install `aspose-barcode-cloud`, but import from `aspose_barcode_cloud`.
+2. Construct APIs as `GenerateApi(ApiClient(Configuration(...)))` or by reusing a shared `ApiClient`. Passing `Configuration` directly to an API class is the wrong shape for this SDK.
+3. `generate()`, `generate_body()`, and `generate_multipart()` return an `ApiResponse`. The image bytes are in `response.data`, not in a model object or file path.
+4. Recognize and scan methods return `BarcodeResponseList`. Iterate `result.barcodes` and read `barcode_value`, `type`, `region`, and `checksum`.
+5. `recognize_base64()` and `scan_base64()` expect a base64 string in the request model. The SDK does not call `base64.b64encode()` for you.
+6. `recognize()` and `recognize_multipart()` take one `DecodeBarcodeType`, but `RecognizeBase64Request.barcode_types` accepts a list.
+7. `ScanApi` auto-detects barcode types and does not take a barcode-type filter or the recognition tuning parameters exposed by `RecognizeApi`.
+8. GET-based recognize and scan methods only work with remote files reachable by URL. For local files, use multipart or base64.
+9. `ApiClient` supports header override through `header_name` and `header_value`; tests use this to customize `x-aspose-client`.
+10. Set `config.debug = True` when you need SDK and `urllib3` request logging.
+
+## Common patterns
+
+Generate and save a QR code:
+
+```python
+from aspose_barcode_cloud import (
+    ApiClient,
+    CodeLocation,
+    Configuration,
+    EncodeBarcodeType,
+    GenerateApi,
+)
+
+config = Configuration(client_id=client_id, client_secret=client_secret)
+api = GenerateApi(ApiClient(config))
+
+response = api.generate(
+    EncodeBarcodeType.QR,
+    "hello from Python",
+    text_location=CodeLocation.NONE,
+)
+
+with open("qr.png", "wb") as fh:
+    fh.write(response.data)
+```
+
+Recognize a local file stream:
+
+```python
+from aspose_barcode_cloud import ApiClient, Configuration, DecodeBarcodeType, RecognizeApi
+
+config = Configuration(client_id=client_id, client_secret=client_secret)
+api = RecognizeApi(ApiClient(config))
+
+with open("qr.png", "rb") as fh:
+    result = api.recognize_multipart(DecodeBarcodeType.QR, fh)
+
+for barcode in result.barcodes:
+    print(barcode.barcode_value)
+```
+
+Auto-scan bytes already in memory:
+
+```python
+import base64
+
+from aspose_barcode_cloud import ApiClient, Configuration, ScanApi, ScanBase64Request
+
+config = Configuration(client_id=client_id, client_secret=client_secret)
+api = ScanApi(ApiClient(config))
+
+with open("unknown.png", "rb") as fh:
+    payload = base64.b64encode(fh.read()).decode("utf-8")
+
+result = api.scan_base64(ScanBase64Request(file_base64=payload))
+```
+
+## Working in this repo
+
+Read `references/repo-workflow.md` when the task changes SDK source, tests, snippets, package metadata, or generated code in `submodules/python`.
+
+Read `references/snippet-map.md` when the task needs example code, README-aligned snippets, or the closest existing pattern for generate, recognize, or scan scenarios.
+
+## Final checklist
+
+1. Use the correct package and import pair: `aspose-barcode-cloud` for install, `aspose_barcode_cloud` for imports.
+2. Build API classes from `ApiClient(Configuration(...))`.
+3. Choose GET only for public URLs, multipart for local files, and base64 request models for bytes already in memory.
+4. Base64-encode request payloads yourself before calling `recognize_base64()` or `scan_base64()`.
+5. Treat generate responses as `response.data` bytes and recognize/scan responses as `result.barcodes`.
+6. When changing the repo, validate with the submodule workflow in `references/repo-workflow.md`.

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

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

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

@@ -0,0 +1,67 @@
+# Python submodule workflow
+
+Use this reference when the task edits SDK source, tests, snippets, package metadata, or generated files inside `submodules/python`.
+
+## Layout
+
+- `aspose_barcode_cloud/api`: generated API clients such as `generate_api.py`, `recognize_api.py`, and `scan_api.py`.
+- `aspose_barcode_cloud/models`: generated request and response models plus enums.
+- `aspose_barcode_cloud/configuration.py`, `api_client.py`, `rest.py`, and `exceptions.py`: auth, HTTP transport, and runtime behavior.
+- `docs`: generated endpoint and model docs.
+- `tests`: unittest coverage for configuration, auth, headers, generate, recognize, scan, exceptions, and end-to-end flows.
+- `snippets`: runnable documentation snippets grouped by generate/read scenario.
+- `scripts`: snippet runners and post-generation helpers such as example insertion and deprecation-warning injection.
+- `README.md` and `example.py`: user-facing usage examples.
+
+## Validation
+
+On Windows, run repo scripts and Make targets through WSL.
+
+From `submodules/python`:
+
+- `make init` or `make venv` to install dependencies.
+- `make format`
+- `make lint`
+- `make test`
+- `make test-example`
+- `make test-tox`
+
+`make test` does more than unit tests:
+
+- runs `pytest --cov=aspose_barcode_cloud tests/`
+- runs `./scripts/run_snippets.sh`
+
+`run_snippets.sh` creates `snippets_test`, symlinks the local `aspose_barcode_cloud` package into it, injects credentials into each snippet, and executes every snippet. Treat snippet failures as consumer-facing regressions, not just sample breakage.
+
+`make after-gen` is the post-processing pipeline used by code generation. It runs:
+
+- `make format`
+- `make insert-examples`
+- `make add-warnings`
+- `make format_doc`
+
+## Test configuration
+
+- Tests load `tests/configuration.json` first and then fall back to `TEST_CONFIGURATION_*` environment variables.
+- `tests/load_configuration.py` maps constructor parameter names from `Configuration.__init__` directly to env vars.
+- Useful names include `TEST_CONFIGURATION_CLIENT_ID`, `TEST_CONFIGURATION_CLIENT_SECRET`, `TEST_CONFIGURATION_ACCESS_TOKEN`, `TEST_CONFIGURATION_HOST`, and `TEST_CONFIGURATION_TOKEN_URL`.
+- `tests/configuration.example.json` still shows an older v3.0 host, but `Configuration` defaults to `https://api.aspose.cloud/v4.0`. Match the surrounding file when editing repo code and prefer the runtime default for new examples.
+
+## Regenerated code workflow
+
+If you change generated SDK code in this mono-repo:
+
+1. Make the intended SDK edit in `submodules/python` so the target behavior is clear.
+2. Mirror the change in the matching template under `codegen/Templates/python` when the file is generated.
+3. Stage the Python submodule changes.
+4. From the repo root, run `make python` through WSL.
+5. Ensure `submodules/python` has no new unstaged diffs after regeneration.
+6. If regeneration reintroduces old code, keep fixing templates or post-generation helpers until the generated output matches the intended SDK change.
+
+## Useful anchors
+
+- `aspose_barcode_cloud/__init__.py`: public exports from the package.
+- `tests/load_configuration.py`: how test config is discovered.
+- `tests/test_generate_and_recognize.py`: end-to-end generate then recognize flow.
+- `scripts/run_snippets.sh` and `scripts/run_snippet.sh`: snippet harness.
+- `Makefile`: local validation and post-generation entry points.

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

@@ -0,0 +1,41 @@
+# Snippet and example map
+
+Use this reference when you want the closest existing Python pattern before writing new SDK code or when updating docs, snippets, and examples.
+
+## Small end-user examples
+
+- `example.py`: compact generate-then-recognize flow using `ApiClient(Configuration(...))`.
+- `snippets/manual_fetch_token.py`: manual OAuth client-credentials token fetch without using the SDK.
+
+## Generate patterns
+
+- `snippets/generate/save/generate_get.py`: simple `generate()` and save-to-file flow.
+- `snippets/generate/save/generate_body.py`: `generate_body()` with `GenerateParams`.
+- `snippets/generate/save/generate_multipart.py`: 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/recognize_get.py`: recognize from a public URL.
+- `snippets/read/set_source/recognize_multipart.py`: recognize from a local file stream.
+- `snippets/read/set_source/recognize_body.py`: recognize from base64 bytes.
+- `snippets/read/set_source/scan_get.py`: auto-scan from a public URL.
+- `snippets/read/set_source/scan_multipart.py`: auto-scan from a local file stream.
+- `snippets/read/set_source/scan_body.py`: auto-scan from base64 bytes.
+- `snippets/read/set_target_types/*`: choosing a single `DecodeBarcodeType` or a list for `RecognizeBase64Request.barcode_types`.
+- `snippets/read/set_quality/*`: `RecognitionMode` examples.
+- `snippets/read/set_image_kind/*`: `RecognitionImageKind` examples.
+
+## Tests worth copying
+
+- `tests/test_generate_and_recognize.py`: generate a barcode, save it locally, and recognize it end to end.
+- `tests/test_generate_api.py`: generate via GET, body, and multipart variants.
+- `tests/test_recognize_api.py`: recognize via base64 body, multipart, and public URL.
+- `tests/test_scan_api.py`: scan via base64 body, multipart, and public URL.
+- `tests/test_auth.py`: client credential flow, external token flow, and unauthorized failures.
+- `tests/test_headers.py`: custom `ApiClient` header override behavior.
+- `tests/test_exception.py`: error and exception behavior.
+- `tests/test_load_configuration.py`: config-file and environment loading behavior.