Add skill for AI Agents

.gitignore

@@ -8,3 +8,5 @@ obj
 *.binlog
 snippets_test/
 *.nupkg
+
+/NetFrameworkTests/Configuration.json

README.md

@@ -38,6 +38,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 [NuGet distribution](https://www.nuget.org/packages/Aspose.BarCode-Cloud/) (recommended).
 
+## AI Agent Skills
+
+This repository includes an AI-agent skill in [`skills/generate-and-scan-barcode-dotnet/SKILL.md`](skills/generate-and-scan-barcode-dotnet/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 .NET 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/).
@@ -252,4 +256,3 @@ Class | Method | HTTP request | Description
 - [Model.RecognizeBase64Request](docs/RecognizeBase64Request.md)
 - [Model.RegionPoint](docs/RegionPoint.md)
 - [Model.ScanBase64Request](docs/ScanBase64Request.md)
-

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

@@ -0,0 +1,163 @@
+---
+name: generate-and-scan-barcode-dotnet
+description: Write or update C#/.NET code that uses the Aspose.BarCode Cloud SDK (`Aspose.BarCode.Cloud.Sdk.*` namespaces; NuGet 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 C#/.NET, touches files under `submodules/dotnet`, or mentions `GenerateApi`, `RecognizeApi`, `ScanApi`, `Configuration`, `GenerateParams`, `RecognizeBase64Request`, or `ScanBase64Request`. The SDK has several easy-to-miss idioms - `Stream` return values, `JwtToken` switching auth mode, GET methods requiring a public `fileUrl`, `RecognizeBase64Async`/`ScanBase64Async` naming, and the `(clientSecret, clientId)` convenience-constructor order - so consult this skill instead of guessing.
+---
+
+# Generate and scan barcode in .NET
+
+The .NET 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`), choosing the right transport variant (GET, body/base64, or multipart), and setting up `Configuration` correctly.
+
+The NuGet package name and code namespaces differ. Install `Aspose.BarCode-Cloud`, then import namespaces under `Aspose.BarCode.Cloud.Sdk.*`.
+
+## Quick start
+
+Use these namespaces in most C# examples:
+
+```csharp
+using Aspose.BarCode.Cloud.Sdk.Api;
+using Aspose.BarCode.Cloud.Sdk.Interfaces;
+using Aspose.BarCode.Cloud.Sdk.Model;
+```
+
+Prefer constructing APIs from a `Configuration` instance:
+
+```csharp
+var config = new Configuration
+{
+    ClientId = clientId,
+    ClientSecret = clientSecret
+};
+
+var generateApi = new GenerateApi(config);
+var recognizeApi = new RecognizeApi(config);
+var scanApi = new ScanApi(config);
+```
+
+If the task is repo maintenance inside `submodules/dotnet`, read `references/repo-workflow.md`. If the task needs style-matching examples or snippet locations, read `references/snippet-map.md`.
+
+## Authentication
+
+Use one of these two patterns:
+
+1. Let the SDK fetch JWT tokens for you.
+
+```csharp
+var config = new Configuration
+{
+    ClientId = clientId,
+    ClientSecret = clientSecret
+};
+```
+
+2. Inject a pre-fetched bearer token.
+
+```csharp
+var config = new Configuration
+{
+    JwtToken = token
+};
+```
+
+Setting `Configuration.JwtToken` changes `AuthType` from JWT to external bearer-token mode. Do not also expect `ClientId` and `ClientSecret` to be used after that.
+
+Prefer `new GenerateApi(config)` and the equivalent `RecognizeApi`/`ScanApi` constructors. Convenience constructors exist, but their parameter order is `new GenerateApi(clientSecret, clientId)` and the same pattern applies to the other API classes. That order is easy to reverse, so avoid it unless there is a strong reason.
+
+Inside this repo, `TestsBase` populates `Configuration` from `Tests/Configuration.json` or `TEST_CONFIGURATION_*` environment variables. Examples use `TEST_CONFIGURATION_JWT_TOKEN`; many snippets still use `TEST_CONFIGURATION_ACCESS_TOKEN`. Treat `Configuration.JwtToken` as the stable API surface and mirror the surrounding file when editing existing examples.
+
+## Choose the right API shape
+
+Pick the operation first:
+
+- `GenerateApi`: create a barcode image.
+- `RecognizeApi`: decode a known or limited set of barcode types and optionally tune recognition.
+- `ScanApi`: auto-detect any barcode types with the smallest API surface.
+
+Then pick the transport variant based on what the user has:
+
+- Public internet URL to an image: use `RecognizeAsync` or `ScanAsync`. The `fileUrl` must be a public URL, not a local path.
+- Local file or stream: use `RecognizeMultipartAsync` or `ScanMultipartAsync`.
+- Raw bytes already in memory: base64-encode them yourself and use `RecognizeBase64Async` or `ScanBase64Async`.
+- Small text plus simple query parameters for barcode generation: use `GenerateAsync`.
+- Structured generate payload or larger data: use `GenerateBodyAsync`.
+- Multipart form generation: use `GenerateMultipartAsync` when the caller explicitly needs multipart.
+
+Key method names:
+
+- `GenerateAsync`
+- `GenerateBodyAsync`
+- `GenerateMultipartAsync`
+- `RecognizeAsync`
+- `RecognizeBase64Async`
+- `RecognizeMultipartAsync`
+- `ScanAsync`
+- `ScanBase64Async`
+- `ScanMultipartAsync`
+
+## Non-obvious SDK rules
+
+1. `GenerateAsync`, `GenerateBodyAsync`, and `GenerateMultipartAsync` return `Stream`, not `byte[]` or a file path. Save the stream or pass it onward, and dispose it with `using` or `await using`.
+2. `RecognizeBase64Async` and `ScanBase64Async` expect a base64 string in the request model. The SDK does not call `Convert.ToBase64String` for you.
+3. `RecognizeBase64Request.BarcodeTypes` accepts multiple `DecodeBarcodeType` values. `RecognizeAsync` and `RecognizeMultipartAsync` take a single `DecodeBarcodeType`.
+4. `ScanApi` does not take a barcode type or recognition-quality knobs. Use it when the caller wants auto-detection.
+5. GET-based recognize and scan methods only work with remote files reachable by URL. For local files on disk, do not pass a local path to `fileUrl`; use multipart or base64.
+6. `BarcodeResponseList` may contain multiple results. Iterate `response.Barcodes` and read `BarcodeValue`, `Type`, `Region`, and `Checksum`.
+7. API failures throw `Aspose.BarCode.Cloud.Sdk.Api.ApiException` with an `ErrorCode` HTTP status. Turn on `Configuration.DebugMode = true` when request or response logging would help.
+8. The repo has a tested end-to-end pattern where a generated `Stream` is passed directly into `ScanMultipartAsync` without saving to disk first. Reuse that pattern when it fits.
+
+## Common patterns
+
+Generate and save a QR code:
+
+```csharp
+var config = new Configuration { ClientId = clientId, ClientSecret = clientSecret };
+var api = new GenerateApi(config);
+
+await using Stream generated = await api.GenerateAsync(
+    EncodeBarcodeType.QR,
+    "hello from .NET",
+    imageFormat: BarcodeImageFormat.Png,
+    textLocation: CodeLocation.None);
+
+await using FileStream file = File.Create("qr.png");
+await generated.CopyToAsync(file);
+```
+
+Recognize specific barcode types from bytes already in memory:
+
+```csharp
+var bytes = await File.ReadAllBytesAsync("many-types.png");
+var request = new RecognizeBase64Request
+{
+    BarcodeTypes = new List<DecodeBarcodeType>
+    {
+        DecodeBarcodeType.QR,
+        DecodeBarcodeType.Code128
+    },
+    FileBase64 = Convert.ToBase64String(bytes)
+};
+
+BarcodeResponseList result = await new RecognizeApi(config).RecognizeBase64Async(request);
+```
+
+Auto-scan a local stream without specifying the barcode type:
+
+```csharp
+await using Stream image = File.OpenRead("unknown.png");
+BarcodeResponseList result = await new ScanApi(config).ScanMultipartAsync(image);
+```
+
+## Working in this repo
+
+Read `references/repo-workflow.md` when the task changes SDK source, tests, snippets, package metadata, or generated code in `submodules/dotnet`.
+
+Read `references/snippet-map.md` when the task needs example code, README-aligned snippets, or the closest existing pattern for a generate, recognize, or scan scenario.
+
+## Final checklist
+
+1. Use the right package and namespace pair: NuGet `Aspose.BarCode-Cloud`, namespaces `Aspose.BarCode.Cloud.Sdk.*`.
+2. Prefer `Configuration`-based construction and avoid swapping `clientSecret` and `clientId`.
+3. Choose GET only for public URLs, multipart for local streams, and base64 or body variants for bytes or structured payloads.
+4. Base64-encode body payloads yourself before calling `RecognizeBase64Async` or `ScanBase64Async`.
+5. Dispose generated or opened streams.
+6. Iterate `response.Barcodes` instead of assuming a single result.
+7. When changing the repo, validate with the submodule workflow in `references/repo-workflow.md`.

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

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

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

@@ -0,0 +1,57 @@
+# Dotnet submodule workflow
+
+Use this reference when the task edits SDK source, tests, snippets, package metadata, or generated files inside `submodules/dotnet`.
+
+## Layout
+
+- `src/Api`: public API clients, `Configuration`, and `ApiException`.
+- `src/Interfaces`: public interfaces used by tests and examples.
+- `src/Model`: request and response models plus enums.
+- `src/Internal`: auth handlers, request pipeline, serialization, and debug logging.
+- `Tests`: NUnit coverage for configuration, auth, generate, recognize, scan, and error cases.
+- `snippets`: documentation snippets that are compiled and executed against the packed NuGet package.
+- `examples`: small standalone sample apps such as `GenerateQR` and `ReadQR`.
+- `scripts`: packaging, formatting, and snippet-runner helpers.
+- `Aspose.BarCode.Cloud.Sdk.sln`: main solution entry point.
+
+## Validation
+
+On Windows, run repo scripts and Make targets through WSL.
+
+From `submodules/dotnet`:
+
+- `make build`
+- `make test`
+- `make lint`
+- `make format`
+
+`make test` does more than unit tests:
+
+- runs `nuget`, which calls `./scripts/pack-nuget.bash` and `./scripts/test-nuget.bash`
+- runs `dotnet test -v normal --framework=net$(LATEST_SDK_VERSION)`
+- runs `./scripts/run_snippets.sh`
+
+`run_snippets.sh` creates a temporary project, consumes the locally packed `.nupkg`, and executes every snippet. Treat snippet failures as package-consumer regressions, not just sample breakage.
+
+## Test configuration
+
+- Minimal JSON shape lives in `Tests/Configuration.template.json`.
+- Tests load `Tests/Configuration.json` first, then fall back to `TEST_CONFIGURATION_*` environment variables.
+- `TestsBase` only maps string-valued `Configuration` properties from the environment. Useful names include `TEST_CONFIGURATION_CLIENT_ID`, `TEST_CONFIGURATION_CLIENT_SECRET`, `TEST_CONFIGURATION_JWT_TOKEN`, `TEST_CONFIGURATION_API_BASE_URL`, `TEST_CONFIGURATION_TOKEN_URL`, and `TEST_CONFIGURATION_API_VERSION`.
+
+## Regenerated code workflow
+
+If you change generated SDK code in this mono-repo:
+
+1. Make the desired SDK edit in `submodules/dotnet` so the target behavior is clear.
+2. Mirror the change in the matching template under `codegen/Templates` when the file is generated.
+3. Stage the dotnet submodule changes.
+4. From the repo root, run `make dotnet`.
+5. Ensure `submodules/dotnet` has no new unstaged diffs after regeneration.
+6. If regeneration reintroduces old code, keep fixing templates until the generated output matches the intended SDK change.
+
+## Useful anchors
+
+- `src/Aspose.BarCode.Cloud.Sdk.csproj`: package metadata, package id, and target framework (`netstandard2.0`).
+- `Tests/TestsBase.cs`: how repo tests construct `Configuration`.
+- `snippets/Snippets.csproj`: snippet target framework and package reference.

skills/generate-and-scan-barcode-dotnet/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 `.NET` SDK code or when updating docs, snippets, and examples.
+
+## Small end-user examples
+
+- `examples/GenerateQR/Program.cs`: minimal QR generation to a local file.
+- `examples/ReadQR/Program.cs`: minimal QR recognition from local file bytes.
+- `snippets/ManualFetchToken.cs`: manual OAuth client-credentials token fetch without the SDK.
+
+## Generate patterns
+
+- `snippets/generate/save/GenerateGet.cs`: simple `GenerateAsync` and save-to-file flow.
+- `snippets/generate/save/GenerateBody.cs`: `GenerateBodyAsync` with `GenerateParams`.
+- `snippets/generate/save/GenerateMultipart.cs`: 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.
+- `snippets/generate/svg/Combine.cs`: generate SVG output and combine results.
+
+## Recognize and scan patterns
+
+- `snippets/read/set-source/RecognizeGet.cs`: recognize from a public URL.
+- `snippets/read/set-source/RecognizeMultipart.cs`: recognize from a local stream.
+- `snippets/read/set-source/RecognizeBody.cs`: recognize from base64 bytes.
+- `snippets/read/set-source/ScanGet.cs`: auto-scan from a public URL.
+- `snippets/read/set-source/ScanMultipart.cs`: auto-scan from a local stream.
+- `snippets/read/set-source/ScanBody.cs`: 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
+
+- `Tests/GenerateAndThenRecognize.cs`: generate a barcode stream, then scan that same stream end to end.
+- `Tests/GenerateTests.cs`: generate via GET and body variants.
+- `Tests/RecognizeTests.cs`: recognize via base64 body, multipart, and URL.
+- `Tests/ScanTests.cs`: scan via base64 body, multipart, and URL.
+- `Tests/JwtAuthTests.cs`: pre-fetched JWT token auth path.
+- `Tests/ApiExceptionTests.cs`: expected failures and exception behavior.
+- `Tests/ConfigurationTests.cs`: configuration defaults and property behavior.