Add Nutrient document processing skill#132
Open
jdrhyne wants to merge 1 commit intomicrosoft:mainfrom
Open
Conversation
Adds a language-agnostic REST API skill for Nutrient Document Web Services (DWS) — comprehensive document processing covering the full PDF lifecycle: format conversion, text/table extraction, OCR, pattern and AI-powered redaction, digital signatures, and watermarks. Complements azure-ai-document-intelligence (document understanding) with document manipulation and transformation capabilities.
Contributor
|
@jdrhyne please read the following Contributor License Agreement(CLA). If you agree with the CLA, please reply with the following information.
Contributor License AgreementContribution License AgreementThis Contribution License Agreement (“Agreement”) is agreed to by the party signing below (“You”),
|
thegovind
requested changes
Feb 15, 2026
Collaborator
thegovind
left a comment
thegovind
left a comment
There was a problem hiding this comment.
Could you add acceptance criteria, scenarios and tests? Also I'm not sure if this is aligned with Microsoft ecosystem
There was a problem hiding this comment.
Pull request overview
This PR adds a new skill for the Nutrient Document Web Services (DWS) API, a third-party commercial REST API for PDF and document processing operations. The skill provides curl-based examples for document format conversion, text/table extraction, OCR, redaction (pattern-based and AI-powered), digital signatures, and watermarks. This is the first third-party (non-Microsoft, non-Azure) service skill to be proposed for this repository.
Changes:
- Adds a language-agnostic skill with REST API curl examples for document processing operations
- Includes MCP server configuration for the Anthropic-published Nutrient MCP server
- Provides reference tables for action types, input formats, and best practices
Comments suppressed due to low confidence (6)
.github/skills/nutrient-document-processing/SKILL.md:97
- The skill uses curl examples throughout, which is appropriate for a REST API. However, this departs from the repository's pattern where skills typically show SDK code in specific languages (Python, .NET, TypeScript, Java). The skill-creator guide shows examples with actual SDK imports and code. While REST APIs are inherently language-agnostic, consider whether the repository would benefit from showing implementation examples in at least one primary language (e.g., Python with requests/httpx) to maintain consistency with other skills. The github-issue-creator skill is language-agnostic but focuses on output formatting rather than API calls.
### 1. Convert DOCX/XLSX/PPTX to PDF
```bash
curl -X POST https://api.nutrient.io/build \
-H "Authorization: Bearer $NUTRIENT_API_KEY" \
-F instructions='{ "parts": [{ "file": "document" }] }' \
-F document=@report.docx \
-o report.pdf
2. Convert PDF to Images (PNG/JPEG/WebP)
curl -X POST https://api.nutrient.io/build \
-H "Authorization: Bearer $NUTRIENT_API_KEY" \
-F instructions='{
"parts": [{ "file": "document" }],
"actions": [{
"type": "renderPages",
"outputFormat": { "type": "png", "dpi": 150 },
"pages": { "start": 0, "end": 0 }
}]
}' \
-F document=@input.pdf \
-o page.png3. Convert PDF to Office (DOCX/XLSX/PPTX)
curl -X POST https://api.nutrient.io/build \
-H "Authorization: Bearer $NUTRIENT_API_KEY" \
-F instructions='{
"parts": [{ "file": "document" }],
"actions": [{ "type": "office", "format": "docx" }]
}' \
-F document=@input.pdf \
-o output.docx**.github/skills/nutrient-document-processing/SKILL.md:10**
* The skill description states it complements existing azure-ai-document-intelligence skills by covering "document manipulation and transformation" vs "document understanding and extraction". However, this positioning may be misleading. Azure AI Document Intelligence actually does support some manipulation features like redaction, and Azure has native services for format conversion (like Azure Form Recognizer's output formats). The skill should more clearly explain why a developer would choose Nutrient over native Azure services, especially given that this repository is focused on Azure SDK development. What specific capabilities does Nutrient provide that aren't available through Azure services?
Nutrient Document Web Services (DWS) API
Full PDF lifecycle processing: convert, extract, OCR, redact, sign, and watermark documents via REST API.
**.github/skills/nutrient-document-processing/SKILL.md:5**
* This skill doesn't follow the repository's established naming convention for skills. According to the repository structure, all skills are either:
1. Core/cross-language skills with no suffix (azd-deployment, mcp-builder, github-issue-creator)
2. Language-specific skills with language suffixes (-py, -dotnet, -ts, -java, -rust)
Since this is a REST API skill (language-agnostic), it should either:
- Not have any suffix (current naming is correct), OR
- The repository should clarify its conventions for third-party API integrations
However, this appears to be the first third-party (non-Azure, non-Microsoft) service skill in the repository. All existing skills focus on Azure SDKs, Microsoft services, or general tooling (GitHub, podcasts). This raises a broader question about whether third-party commercial API services align with the repository's stated purpose: "Skills, custom agents, AGENTS.md templates, and MCP configurations for AI coding agents working with Azure SDKs and Microsoft AI Foundry."
name: nutrient-document-processing
description: |
Nutrient Document Web Services (DWS) REST API for document processing. Convert between formats (DOCX/XLSX/PPTX ↔ PDF ↔ images), extract text/tables/key-value pairs, apply OCR to scanned documents, redact sensitive information with pattern matching or AI, add digital signatures and watermarks, and fill PDF forms. Language-agnostic REST API. Triggers: "convert to PDF", "PDF to Word", "extract text from PDF", "OCR", "redact PII", "redact SSN", "watermark PDF", "sign PDF", "document processing", "Nutrient".
**.github/skills/nutrient-document-processing/SKILL.md:278**
* The MCP server configuration references "@anthropic-ai/nutrient-mcp-server" which appears to be an Anthropic-published package, not a Microsoft package. This is inconsistent with the repository's focus on Microsoft/Azure infrastructure. The repository's mcp-builder skill and other MCP references focus on Microsoft MCP infrastructure (Azure MCP Server, Foundry MCP, etc.). While the MCP protocol is vendor-neutral, the repository documentation emphasizes Microsoft's MCP ecosystem. Consider clarifying whether non-Microsoft MCP servers are within scope for this repository, and if so, whether they should be documented differently.
MCP Server Integration
Nutrient provides an MCP server for direct agent integration:
{
"mcpServers": {
"nutrient": {
"command": "npx",
"args": ["-y", "@anthropic-ai/nutrient-mcp-server"],
"env": {
"NUTRIENT_API_KEY": "<your-api-key>"
}
}
}
}**.github/skills/nutrient-document-processing/SKILL.md:287**
* According to the skill-creator guide and coding guidelines (Guideline 1000000), skills should follow the principle "Simplicity First" and "Don't assume. Don't hide confusion. Surface tradeoffs." This skill presents Nutrient as a solution without discussing tradeoffs such as: vendor lock-in to a third-party service, cost implications vs Azure native services, data sovereignty concerns (documents being sent to api.nutrient.io), network latency compared to Azure services in the same region, and operational dependencies on external service availability. These are important considerations for developers making architectural decisions.
Best Practices
- Chain actions — Multiple actions execute sequentially in one request (e.g., OCR then redact)
- Use preset redaction patterns for standard PII types — more reliable than regex for known formats
- Use AI redaction for complex or context-dependent PII that presets can't cover
- Set DPI appropriately — 150 DPI for screen, 300 DPI for print when rendering pages
- Check credit usage — Each API call consumes credits based on document size and action type
**.github/skills/nutrient-document-processing/SKILL.md:97**
* The README.md needs to be updated to include this new skill. Looking at the catalog structure, if this skill is approved, it would need to be added to either:
1. The "Core" section (currently showing 6 skills for "tooling, infrastructure, language-agnostic"), which would require updating the count to 7
2. A new section for third-party API integrations
The README also states "131 skills in .github/skills/" which would need to be incremented to 132. Additionally, the PR description mentions "132 skills" which suggests this count update was intended but the README.md file is not included in the diff.
name: nutrient-document-processing
description: |
Nutrient Document Web Services (DWS) REST API for document processing. Convert between formats (DOCX/XLSX/PPTX ↔ PDF ↔ images), extract text/tables/key-value pairs, apply OCR to scanned documents, redact sensitive information with pattern matching or AI, add digital signatures and watermarks, and fill PDF forms. Language-agnostic REST API. Triggers: "convert to PDF", "PDF to Word", "extract text from PDF", "OCR", "redact PII", "redact SSN", "watermark PDF", "sign PDF", "document processing", "Nutrient".
Nutrient Document Web Services (DWS) API
Full PDF lifecycle processing: convert, extract, OCR, redact, sign, and watermark documents via REST API.
API Endpoint
https://api.nutrient.io
Environment Variables
NUTRIENT_API_KEY=<your-api-key>Get an API key at nutrient.io/api
Authentication
All requests use Bearer token authentication:
curl -X POST https://api.nutrient.io/build \
-H "Authorization: Bearer $NUTRIENT_API_KEY" \
-F instructions='{ ... }' \
-F document=@input.pdf \
-o output.pdfAPI Structure
The API uses a single /build endpoint with an instructions JSON payload. The parts array defines the processing pipeline.
{
"parts": [
{
"file": "document"
}
],
"actions": [
{
"type": "<action-type>",
...action-specific-options
}
]
}Core Workflows
1. Convert DOCX/XLSX/PPTX to PDF
curl -X POST https://api.nutrient.io/build \
-H "Authorization: Bearer $NUTRIENT_API_KEY" \
-F instructions='{ "parts": [{ "file": "document" }] }' \
-F document=@report.docx \
-o report.pdf2. Convert PDF to Images (PNG/JPEG/WebP)
curl -X POST https://api.nutrient.io/build \
-H "Authorization: Bearer $NUTRIENT_API_KEY" \
-F instructions='{
"parts": [{ "file": "document" }],
"actions": [{
"type": "renderPages",
"outputFormat": { "type": "png", "dpi": 150 },
"pages": { "start": 0, "end": 0 }
}]
}' \
-F document=@input.pdf \
-o page.png3. Convert PDF to Office (DOCX/XLSX/PPTX)
curl -X POST https://api.nutrient.io/build \
-H "Authorization: Bearer $NUTRIENT_API_KEY" \
-F instructions='{
"parts": [{ "file": "document" }],
"actions": [{ "type": "office", "format": "docx" }]
}' \
-F document=@input.pdf \
-o output.docx</details>
Comment on lines
+3
to
+5
| description: | | ||
| Nutrient Document Web Services (DWS) REST API for document processing. Convert between formats (DOCX/XLSX/PPTX ↔ PDF ↔ images), extract text/tables/key-value pairs, apply OCR to scanned documents, redact sensitive information with pattern matching or AI, add digital signatures and watermarks, and fill PDF forms. Language-agnostic REST API. Triggers: "convert to PDF", "PDF to Word", "extract text from PDF", "OCR", "redact PII", "redact SSN", "watermark PDF", "sign PDF", "document processing", "Nutrient". | ||
| --- |
There was a problem hiding this comment.
The description includes a reference to the "Nutrient" brand name as a trigger keyword. According to the coding guidelines (Guideline 1000000), Azure SDKs and Foundry APIs should search official docs first using the microsoft-docs MCP. This skill doesn't include any such instruction because it's for a third-party service. However, the skill should still follow the principle of "Fresh Information First" by instructing agents to check the official Nutrient API documentation before implementing, similar to how Azure skills instruct checking microsoft-docs. Consider adding a section like "Before Implementation" that tells agents to verify current API patterns from the official documentation links provided at the bottom.
This issue also appears in the following locations of the same file:
- line 59
- line 7
- line 1
- line 262
- line 280
Comment on lines
+25
to
+35
| ## Authentication | ||
|
|
||
| All requests use Bearer token authentication: | ||
|
|
||
| ```bash | ||
| curl -X POST https://api.nutrient.io/build \ | ||
| -H "Authorization: Bearer $NUTRIENT_API_KEY" \ | ||
| -F instructions='{ ... }' \ | ||
| -F document=@input.pdf \ | ||
| -o output.pdf | ||
| ``` |
There was a problem hiding this comment.
The authentication pattern shown uses an external API key (NUTRIENT_API_KEY), which differs from the repository's strong convention of using DefaultAzureCredential for authentication. While this is understandable since Nutrient is not an Azure service, the skill should acknowledge this departure from the repository's standard authentication pattern and clarify why DefaultAzureCredential cannot be used. All Azure SDK skills in this repository consistently emphasize "Use DefaultAzureCredential" or "Never hardcode credentials" in their best practices sections. Consider adding a note explaining that this is a third-party API requiring its own authentication mechanism.
This issue also appears on line 270 of the same file.
| | Getting Started | https://www.nutrient.io/getting-started/web-services/ | | ||
| | npm MCP Server | https://www.npmjs.com/package/@anthropic-ai/nutrient-mcp-server | | ||
| | OpenClaw Plugin | https://www.npmjs.com/package/@nutrient-sdk/nutrient-openclaw | | ||
| | GitHub | https://github.com/nicegoodthings/nutrient-dws-examples | |
There was a problem hiding this comment.
The PR description states "Under 300 lines" as a feature, and the file is exactly 296 lines. However, according to the skill-creator guide, skills should be "under 500 lines" with the recommendation to "Keep SKILL.md under 500 lines. Split into reference files when approaching this limit." While being concise is good, artificially constraining to 300 lines when 500 is allowed may have resulted in less detailed documentation than would be helpful. Consider whether important details were omitted to hit this arbitrary target.
This issue also appears on line 1 of the same file.
Suggested change
| | GitHub | https://github.com/nicegoodthings/nutrient-dws-examples | | |
| | GitHub | https://github.com/nicegoodthings/nutrient-dws-examples | | |
| ## Troubleshooting & Error Handling | |
| When calls to the Nutrient DWS API fail, agents should surface concise, actionable errors and suggest next steps. | |
| Common HTTP status codes: | |
| - **400 Bad Request** — Invalid parameters (e.g., unsupported file type, invalid action configuration). | |
| - **Agent response:** Re-check requested actions and formats; confirm the source file type and requested target format are compatible. | |
| - **401 Unauthorized / 403 Forbidden** — Missing or invalid `NUTRIENT_API_KEY`. | |
| - **Agent response:** Ask the user (or operator) to verify that the API key is configured in the environment and has access to the DWS API. | |
| - **413 Payload Too Large** — File exceeds size or page limits for the configured plan. | |
| - **Agent response:** Propose splitting the document, downsampling images, or processing only selected pages. | |
| - **429 Too Many Requests** — Rate limiting or credit exhaustion. | |
| - **Agent response:** Back off, wait, and retry; consider batching requests or reducing concurrency. | |
| - **5xx Server Errors** — Temporary service issues. | |
| - **Agent response:** Retry with exponential backoff; if persistent, suggest manual retry later. | |
| For OCR and redaction: | |
| - If **OCR output is low quality**, suggest: | |
| - Increasing DPI when rendering pages to images. | |
| - Requesting grayscale instead of color to improve contrast. | |
| - Ensuring the input is not overly compressed or blurred. | |
| - If **PII remains visible after redaction**, suggest: | |
| - Combining preset redaction patterns with AI redaction. | |
| - Expanding the redaction scope (e.g., include names, addresses, or custom patterns). | |
| - Re-running redaction on specific pages or regions of interest. | |
| When chaining multiple actions (e.g., convert → OCR → redact), validate each step’s output before proceeding and log the step where failure occurs. | |
| ## Performance & Limits | |
| While exact limits depend on the user’s Nutrient plan, agents should be conservative about: | |
| - **Document size and page count** — Prefer processing only the required pages (e.g., first N pages, or a specified range) when the user’s intent is narrow. | |
| - **Number of simultaneous requests** — Batch related operations rather than firing many single-page requests in parallel. | |
| - **Credit consumption** — Some actions (especially AI-based redaction or heavy OCR) can be more expensive than simple conversions. | |
| Recommended patterns: | |
| 1. **Scope-first** — Ask the user which pages or sections matter before processing entire documents. | |
| 2. **Combine actions** — Use multi-step workflows in a single API call where available (e.g., OCR + redact) to reduce round-trips. | |
| 3. **Cache intermediate results** — If allowed by the use case, reuse extracted text or OCR results for subsequent analysis rather than reprocessing the same file. | |
| ## Security & Privacy Considerations | |
| This skill is often used with sensitive documents (contracts, IDs, financial records, medical records). | |
| - **Never log raw secrets or full documents** in agent logs or chat transcripts when not strictly necessary. | |
| - Prefer **redacting PII before sharing** any document (or page images) back into other tools or with collaborators. | |
| - Make it clear to the user when: | |
| - A document has been successfully redacted (no underlying text remains). | |
| - Only visual redaction has been applied (e.g., overlays), and underlying text may still be present. | |
| - When filling forms or adding signatures, confirm: | |
| - The user’s intent (e.g., “Sign as John Doe on page 3, bottom right”). | |
| - That the document is the correct and final version before applying a digital signature. | |
| If the user expresses compliance or regulatory constraints (HIPAA, GDPR, etc.), bias towards more aggressive redaction scopes and minimize data retention. | |
| ## Example End-to-End Flow | |
| A typical agent-driven flow for handling a scanned contract with PII: | |
| 1. **User request:** “Take this scanned contract, extract all text, redact SSNs and email addresses, and give me a clean searchable PDF plus a text summary.” | |
| 2. **Agent plan:** | |
| - Upload the scanned PDF to Nutrient. | |
| - Run OCR with sufficient DPI for legibility. | |
| - Apply preset redaction patterns for SSNs and emails, plus AI redaction for any remaining PII. | |
| - Export a searchable redacted PDF. | |
| - Extract text and generate a summary for the user. | |
| 3. **Nutrient actions (conceptual):** | |
| - Action 1: `ocr` on the uploaded file. | |
| - Action 2: `redact` with presets (`ssn`, `email`) and AI redaction enabled. | |
| - Action 3: `export` as searchable PDF and plain text. | |
| 4. **Agent response:** | |
| - Provide a link or attachment for the redacted PDF (if the environment supports file return). | |
| - Return a textual summary of the contract. | |
| - Optionally include a brief log of actions performed (OCR → redact → export) for transparency. | |
| Use this pattern as a template for other workflows (e.g., “PDF to editable Word,” “extract tables only,” “sign and watermark before distribution”). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds a document processing skill for Nutrient DWS API — a language-agnostic REST API for the full PDF lifecycle: format conversion, text/table extraction, OCR, redaction, digital signatures, and watermarks.
Why
The existing
azure-ai-document-intelligence-dotnetandazure-ai-document-intelligence-tsskills cover document understanding and extraction. This skill complements them by covering document manipulation and transformation — operations like:Format
name/description, markdown body)github-issue-creatorIntegration
Notes